读懂 Codex（7.20）：`list_agents` 的路径前缀、树形投影与 loaded-only 快照

list_agents 先把可选 path_prefix 相对当前 Agent 解析，再从 Registry 地址集合投影状态；当前实现只返回此刻仍能从 ThreadManager 取到的已加载 Thread，因此它不是持久拓扑全集。

本节只研究“V2 可观察树快照”。输入是可选 path_prefix，状态由 List Handler 与 AgentControl 持有，成功输出为按路径排序的 Agent 列表与状态。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题	本节答案
谁发起	可选 path_prefix
谁拥有可变状态	List Handler 与 AgentControl
成功产物	按路径排序的 Agent 列表与状态
不在本节内	V2 可观察树快照之外的上游产品策略和下游业务实现

这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。

端到端调用链

解析 prefix
枚举 Registry metadata
按 prefix 过滤
ThreadManager 读取 loaded thread/status
按 AgentPath 排序返回

`list_agents` 的路径前缀、树形投影与 loaded-only 快照的端到端机制流程，展示解析 prefix、枚举 Registry metadata、按 prefix 过滤、ThreadManager 读取 loaded thread/status、按 AgentPath 排序返回 — 图 7.20-1：解析 prefix → 枚举 Registry metadata → 按 prefix 过滤 → ThreadManager 读取 loaded thread/status → 按 AgentPath 排序返回。图中每条箭头都表示下一层只接收上一层已经确认的状态。

这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。

源码机制拆解

prefix 支持相对路径

与消息工具相同，worker 在 /root/research 下解析为 /root/research/worker；绝对 /root/... 从根定位。空/非法段先被拒绝。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 List Handler 与 AgentControl 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

Root 可以出现在结果中

AgentControl 的树快照不是只列 subagent；当 prefix 匹配时 Root 也作为节点出现，便于调用方知道当前树基准。

冷 Agent 当前被跳过

虽然 Registry 仍有被 Residency 卸载的 metadata，但 list_agents 获取 Thread 失败后跳过该项；因此“列表没有”不能单独证明 AgentPath 不可恢复。

排序保证稳定展示，输出保持最小

结果按规范路径排序，不依赖 HashMap 遍历次序。Registry 内虽有昵称和 Role，当前 ListedAgent 只公开 agent_name 与 agent_status；寻址仍以 path 为准。

Python 风格伪代码

下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：

async def list_agents(caller, prefix_ref=None):
    prefix = caller.path.resolve(prefix_ref) if prefix_ref else None
    rows = []
    for metadata in caller.control.registry.all_metadata():
        if prefix and not metadata.path.is_under(prefix):
            continue
        thread = caller.control.thread_manager.get(metadata.thread_id)
        if thread is None:
            continue  # current implementation projects loaded threads only
        rows.append(AgentRow(agent_name=str(metadata.path), agent_status=thread.status()))
    return sorted(rows, key=lambda row: row.agent_name)

阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。

失败、取消与恢复

`list_agents` 的路径前缀、树形投影与 loaded-only 快照的三类失败分支、可观察结果和恢复责任 — 图 7.20-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。

故障点	已发生的状态	可观察结果	恢复责任
prefix 非法	未枚举	参数错误	使用合法相对/绝对路径
Thread 在枚举中途卸载	Registry 元数据存在	该节点跳过	再次调用或直接按路径通信恢复
把列表当持久图	Closed/Open 边信息未返回	诊断结论错误	查询 AgentGraphStore/后续持久化章

取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。

并发与一致性不变量

同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。

设计思路与代价

本节设计保护的核心不变量是：list_agents 先把可选 path_prefix 相对当前 Agent 解析，再从 Registry 地址集合投影状态；当前实现只返回此刻仍能从 ThreadManager 取到的已加载 Thread，因此它不是持久拓扑全集。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。

源码与测试证据

位置	能证明什么
`codex-rs/core/src/tools/handlers/multi_agents_v2/list_agents.rs`	Tool 参数与调用
`codex-rs/core/src/agent/control.rs`	Registry→ThreadManager 状态投影与排序
`codex-rs/protocol/src/agent_path.rs`	prefix resolve

测试/可执行检查	覆盖重点	预期
`codex-rs/core/src/tools/handlers/multi_agents_tests.rs`	正常、边界与状态转换	应与本节不变量一致
`codex-rs/core/src/agent/control_tests.rs`	失败、并发或兼容行为	应与本节不变量一致

当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。

Mini Codex 复刻建议

Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。

本节结论

list_agents 先把可选 path_prefix 相对当前 Agent 解析，再从 Registry 地址集合投影状态；当前实现只返回此刻仍能从 ThreadManager 取到的已加载 Thread，因此它不是持久拓扑全集。掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：interrupt_agent 的目标校验、previous status 与幂等取消 · 下一节：Result Mailbox 的终态通知、QueueOnly 与父 Agent 唤醒

源码依据

本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：

codex-rs/core/src/tools/handlers/multi_agents_v2/list_agents.rs：Tool 参数与调用
codex-rs/core/src/agent/control.rs：Registry→ThreadManager 状态投影与排序
codex-rs/protocol/src/agent_path.rs：prefix resolve