雨 雨天小六

读懂 Codex（7.14）：`close_agent` V1 的边关闭、后代 Shutdown 与资源释放

· 更新于 2026-08-02 · 专栏：读懂 Codex

#Codex#Agent Runtime#Multi-Agent#Extension#软件架构

V1 close 是拓扑和运行时的联合关闭：先把非临时父子边标为 Closed，再对目标及当前可见后代执行物化、Shutdown、等待和 Registry/Residency/Manager 清理。

本节只研究“V1 显式永久关闭”。输入是 target ThreadId，状态由 AgentControl legacy close 与 Graph Store 持有，成功输出为 previous_status 与已释放的运行时资源。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题本节答案
谁发起target ThreadId
谁拥有可变状态AgentControl legacy close 与 Graph Store
成功产物previous_status 与已释放的运行时资源
不在本节内V1 显式永久关闭之外的上游产品策略和下游业务实现

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

端到端调用链

  1. 读取 previous_status
  2. 标记入边 Closed
  3. 收集 live descendants
  4. 逐个 flush/materialize/shutdown
  5. 移除 Manager/Residency/Registry
`close_agent` V1 的边关闭、后代 Shutdown 与资源释放的端到端机制流程，展示读取 previous_status、标记入边 Closed、收集 live descendants、逐个 flush/materialize/shutdown、移除 Manager/Residency/Registry
图 7.14-1：读取 previous_status → 标记入边 Closed → 收集 live descendants → 逐个 flush/materialize/shutdown → 移除 Manager/Residency/Registry。图中每条箭头都表示下一层只接收上一层已经确认的状态。

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

源码机制拆解

先关闭边防止恢复竞态

非 ephemeral Thread 的入边在 Shutdown 前改为 Closed；即便进程在运行时清理中途崩溃，后续恢复也不会沿这条边把目标重新当作开放子树。

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

关闭覆盖当前活后代

控制层收集目标和内存中后代，避免只关父 Thread、仍留下子任务继续修改共享工作区。图查询与 live manager 快照承担不同部分。

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

Shutdown 前保留历史

调用确保 Rollout materialized 并 flush，再提交 Shutdown、等待终止；Close 不是通过丢弃 Session 来“快速删除”。

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

结果返回 previous_status

调用者看到关闭前是 Running/Completed/Interrupted 等，而不是被 Shutdown 事件覆盖后的单一状态，便于解释 Close 的对象。

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

Python 风格伪代码

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

async def close_agent_v1(control, target_id):
    previous = control.status(target_id)
    if not control.is_ephemeral(target_id):
        await control.graph.set_incoming_edge(target_id, 'closed')

    descendants = control.live_descendants_breadth_first(target_id)
    for thread_id in [target_id, *descendants]:
        if thread := control.thread_manager.get(thread_id):
            await thread.ensure_rollout_materialized()
            await thread.flush_rollout()
            await thread.shutdown_and_wait()
        control.thread_manager.remove(thread_id)
        control.residency.remove(thread_id)
        control.registry.release(thread_id)
    return previous

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

失败、取消与恢复

`close_agent` V1 的边关闭、后代 Shutdown 与资源释放的三类失败分支、可观察结果和恢复责任
图 7.14-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。
故障点已发生的状态可观察结果恢复责任
Edge 不存在Graph set status 是 no-op仍尝试关闭已知 Thread保持幂等
某后代 Shutdown 失败部分节点可能已清理传播/记录错误再次 close 可继续剩余节点
目标已不在 Manager可能只有持久边边仍设 Closed返回先前 NotFound 状态

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

并发与一致性不变量

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

设计思路与代价

本节设计保护的核心不变量是：V1 close 是拓扑和运行时的联合关闭：先把非临时父子边标为 Closed，再对目标及当前可见后代执行物化、Shutdown、等待和 Registry/Residency/Manager 清理。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

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

源码与测试证据

位置能证明什么
codex-rs/core/src/agent/control/legacy.rsclose/shutdown_live_agent 的清理顺序
codex-rs/agent-graph-store/src/store.rsEdge Closed 更新与 no-op 语义
测试/可执行检查覆盖重点预期
codex-rs/core/src/agent/control_tests.rs正常、边界与状态转换应与本节不变量一致
codex-rs/agent-graph-store/src/local.rs失败、并发或兼容行为应与本节不变量一致

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

Mini Codex 复刻建议

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

本节结论

V1 close 是拓扑和运行时的联合关闭：先把非临时父子边标为 Closed，再对目标及当前可见后代执行物化、Shutdown、等待和 Registry/Residency/Manager 清理。 掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：wait_agent V1 的多目标状态订阅与超时 · 下一节：spawn_agent V2 的 AgentPath、fork_turns 与元数据隐藏

源码依据

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

评论

← 返回文章列表