Codex · Agent Runtime 工程解析

<blockquote> <p>本文从 Codex 的工程实现出发，拆解它的 Agent Runtime 是如何被设计与构建的：架构如何分层、一个请求如何被接收与处理、长对话如何在上下文溢出前被压缩、多个 Agent 如何被调度与通讯、记忆如何沉淀与淘汰、以及贯穿全系统的生命周期控件做了什么。</p> <p>全文只讨论设计与机制，不走代码细节，不出现函数名、文件路径与代码片段。所有技术论断均基于对工程实现事实的归纳。</p> </blockquote> <h2>§1 全景与导读：五层叠层 × 四贯穿控件</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cad95d8.png" width="100%" /></p> <p align="center">_{<b>图 1-1</b>　Codex Agent Runtime 架构全景：左侧五层（入口面 / 会话与回合面 / 执行体平面 / 能力与工具面 / 持久化与记忆面）各自展开子组件；右侧四根贯穿控件（Guardian / TokenBudget / CancellationToken / Rollout + GhostSnapshot）垂直穿越所有层。这张图是后续每一章的坐标系。}</p> <h3>1.1 这一章要做什么</h3> <p>这是全文唯一一张<strong>全景图</strong>。读完这一章，你应该能回答三个问题：</p> <ol> <li>Codex Agent Runtime 是由<strong>哪几层</strong>构成的？每一层在回答什么问题？</li> <li>除了分层，它还有哪几根<strong>贯穿控件</strong>？每一根兜底哪一类失败？</li> <li>为什么要把"层"和"控件"沿两个正交维度分开？</li> </ol> <p>这三个问题的答案，就是阅读后续八章时反复回望的<strong>认知框架</strong>。后面每一章（回合节拍、执行体契约、上下文压缩、多 Agent 调度、通讯、记忆、贯穿控件）本质上都是这张全景图里某一块的局部放大。</p> <h3>1.2 一个断言：两个正交维度</h3> <p>Codex Agent Runtime 的骨架可以归结为一个断言：</p> <blockquote> <p><strong>水平方向五层，各管一段"正常路径"的职责；垂直方向四根控件，集中兜底"失败路径"。</strong></p> </blockquote> <p>层与控件在架构上是<strong>正交</strong>的——层不负责失败，控件不负责正常。这种沿两个维度切开的方式，是整个系统可以在长时间运行中不崩塌的结构性原因。后文所有看似琐碎的设计（Replace 语义、基线差分、SpawnReservation Drop guard、水位线单调、审批独立成 Task……）都可以用这一条断言解释。</p> <h3>1.3 水平五层：每层回答一个独立问题</h3> <p>五层从入口到持久化依次是：</p> <table> <thead> <tr> <th>层</th> <th>要回答的问题</th> <th>主要载体</th> <th>对应章节</th> </tr> </thead> <tbody> <tr> <td>① <strong>入口面</strong></td> <td>请求从哪里进来、如何归一化</td> <td>用户输入 · 会话恢复 · 事件注入 · Mailbox 唤醒 · 外部触发</td> <td>§2 §6</td> </tr> <tr> <td>② <strong>会话与回合面</strong></td> <td>谁持有态、谁承载瞬态</td> <td>Session（跨回合持久） · ActiveTurn（仅当次） · TurnContext（只读快照） · pending_input 通道 · granted_permissions</td> <td>§2</td> </tr> <tr> <td>③ <strong>执行体平面</strong></td> <td>真正跑起来的东西长什么样</td> <td>SessionTask 契约 + 六种形态的 Task</td> <td>§3</td> </tr> <tr> <td>④ <strong>能力与工具面</strong></td> <td>Agent 能做什么</td> <td>内建工具 · MCP 扩展 · Code Mode · ToolRouter · ToolOrchestrator · 多 Agent v2 七件套</td> <td>§5</td> </tr> <tr> <td>⑤ <strong>持久化与记忆面</strong></td> <td>跑完之后留下什么</td> <td>Rollout JSONL 时光机 · 两阶段记忆管线 · GhostSnapshot · ContextManager · State DB</td> <td>§4 §7 §8</td> </tr> </tbody> </table> <p>五层并不是对称的：<strong>入口面与能力面"宽而胖"，中间三层"窄而高"</strong>——呈现一个上下宽、腰身窄的漏斗。入口面要容纳各种形态的请求源，能力面要承载数十种内建工具与 MCP 扩展；但所有请求都必须穿过 Session 与 SessionTask 这两个窄口才可能真正执行。</p> <p>这种"窄腰"不是审美，是<strong>工程压缩</strong>：把失败模式的类别收敛到尽可能少的几个点。只要中间这三层守住各自的不变量，前后两端无论怎么扩，失败面都不会爆炸。</p> <h3>1.4 垂直四根控件：每根兜底一类失败</h3> <p>四根贯穿控件与"层"正交——它们不属于任何一层，但在每一层失灵时都在场：</p> <table> <thead> <tr> <th>控件</th> <th>兜底的失败类别</th> <th>核心语义</th> <th>对应章节</th> </tr> </thead> <tbody> <tr> <td><strong>Guardian</strong> · 异步审批</td> <td>"需要征求人类同意"这类阻塞</td> <td>审批独立成一种 Review Task，策略文件可编辑，审批事件写入 Rollout 可审计</td> <td>§8.1</td> </tr> <tr> <td><strong>TokenBudget</strong> · 窗口兜底</td> <td>上下文超长、prompt cache 失效</td> <td>贯穿每回合的实时窗口管理员；基线-差分让下一回合只发增量</td> <td>§4</td> </tr> <tr> <td><strong>CancellationToken</strong> · 方向性取消</td> <td>任务需要被中断</td> <td>只向下级联、绝不向上爆炸；100 ms 优雅窗口；失败半径局部化</td> <td>§2.1 §8.4</td> </tr> <tr> <td><strong>Rollout + GhostSnapshot</strong> · 可回放</td> <td>状态丢失、无法复盘、无法分叉</td> <td>JSONL 追加写；flush 严格先于 TurnAborted 事件；任一点可分叉复刻</td> <td>§8.2 §8.3</td> </tr> </tbody> </table> <p>每一根控件都有明确的<strong>方向</strong>与<strong>顺序约束</strong>，不是一张撒向全局的 aspect 网：</p> <ul> <li>Guardian 的审批事件必须独立成 Review Task，不能塞进主回合附带处理</li> <li>TokenBudget 必须在每一回合<strong>之前</strong>完成基线对比，不能回合结束后再事后补救</li> <li>CancellationToken 只向下、不向上</li> <li>Rollout 的 flush 必须发生在 TurnAborted 事件<strong>之前</strong>——下游可能一收到事件就回读 rollout 文件，若顺序反了会读到半包</li> </ul> <p>"有方向 + 有顺序约束"是这四根控件长期运行后不退化为乱麻的根因。</p> <h3>1.5 为什么要把"层"与"控件"分开？</h3> <p>如果把审批、取消、持久化、预算都揉进各层自己的职责里，就会得到一种"每层都自己管自己失败"的伪解耦：每一层都要实现一份类似的中断逻辑、一份类似的审批逻辑、一份类似的持久化逻辑。调试时任何一处漂移都可能让整个系统陷入"失败的组合爆炸"。</p> <p>Codex 的取舍是把"正常"与"失败"解耦得干干净净——<strong>层只负责正常路径，控件专职兜底失败路径</strong>。失败路径集中管理之后，"哪个环节在失败时做什么"变成一组显式的、有向的合约，而不是一堆分散在各层里、各自为战的 defensive code。</p> <h3>1.6 全文阅读导航</h3> <p>理解了五层 × 四控这张全景之后，后续章节按"从里到外"的次序展开：</p> <ul> <li><strong>§2 回合节拍</strong> — 最内核的运行节奏：Turn 状态机、Replace 语义、单 Agent 内部两层嵌套的 runtime loop</li> <li><strong>§3 执行体契约</strong> — 所有能在回合里跑的东西共享的薄契约，以及 6 种具体形态</li> <li><strong>§4 上下文压缩</strong> — TokenBudget 这根控件的完整算法：窗口度量、阈值、触发、动作、影响</li> <li><strong>§5 多 Agent 调度</strong> — 把单 Agent 的能力扩展为多 Agent 时，控制面怎么共享、执行栈怎么独立</li> <li><strong>§6 Agent 通讯</strong> — 多 Agent 之间靠 Mailbox 传话的三件原语</li> <li><strong>§7 记忆</strong> — 让 Agent 跨 session 记住东西的两阶段管线</li> <li><strong>§8 贯穿控件真实面貌</strong> — 把四根控件与五层的 4×5 交点矩阵彻底拆开</li> <li><strong>§9 设计结语</strong> — 抽出三条可被其他 Agent 框架带走的工程哲学</li> </ul> <h3>1.7 本章速查</h3> <table> <thead> <tr> <th>关键断言</th> <th>工程含义</th> </tr> </thead> <tbody> <tr> <td>五层呈漏斗形</td> <td>把失败模式收敛到中间三层的窄口</td> </tr> <tr> <td>控件与层正交</td> <td>失败路径集中、层专注正常路径</td> </tr> <tr> <td>控件有"方向"和"顺序约束"</td> <td>避免控件退化为无向的横切代码</td> </tr> <tr> <td>flush 先于 TurnAborted</td> <td>下游读取 rollout 不会撞上半包</td> </tr> <tr> <td>全景图是全文坐标系</td> <td>后续每一章都是它的局部放大</td> </tr> </tbody> </table> <blockquote> <p>图 1-1 是全文<strong>唯一</strong>的全景坐标。读不懂后面任何一章时，回来看它一眼。</p> </blockquote> <hr /> <h2>§2 回合节拍：Turn 模型与单 Agent 内部 runtime loop</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175caf09c0.png" width="100%" /></p> <p align="center">_{<b>图 2-0</b>　本章总览：左侧是 Turn 的四态状态机，右侧是单 Agent 内部两层嵌套的真实 runtime loop。}</p> <p>Codex 的运行节拍不是一个 <code>while true</code> 的事件循环，而是以"回合"为单位的进出场模型——<strong>一次用户意图对应一次 Turn，每次 Turn 都是一次独立的进场与退场</strong>。这个选择与它"与人对话而不是批量处理作业"的定位直接相关：Turn 化之后，回合就成为调度、遥测、UI 指示、审批、中断、压缩的共同落点。</p> <h3>2.1 回合状态机：四态与 Replace 语义</h3> <p>一个回合只有四个态：<code>Idle → Starting → Running → Aborting / Completing → Idle</code>。几条值得单独点名的约束：</p> <ul> <li><strong>Replace 优先于 Queue</strong>：新的回合进入时，系统不会把它排到队尾，而是<strong>先把当前的活跃回合以 Replaced 理由中止掉</strong>。对"与人对话"的场景，这条纪律把"我刚说的这句话应立刻被理解、不用等上一句跑完"这个用户预期写死到了 Runtime 层。</li> <li><strong>进场先清场</strong>：新回合的第一个动作是 <code>abort_all_tasks(Replaced)</code>，然后才新建 ActiveTurn 与 Task。顺序不能颠倒。</li> <li><strong>退场先落盘</strong>：回合被中断时，系统不会立刻把 <code>TurnAborted</code> 事件发出去，而是先把 <code>TURN_ABORTED</code> 标记写入 rollout、再 flush 到磁盘，最后才发事件——下游有可能一收到事件就回读 rollout 检查状态，若顺序反了就会读到半包。</li> <li><strong>100 ms 优雅窗口</strong>：收到中断信号后，先 notify 执行体给 100 ms 的收尾时间，超时再强制 <code>handle.abort()</code>。100 ms 不是拍脑袋，而是"绝大多数流式写盘的一个微批能收干净"的经验值。</li> </ul> <p>Replace 语义的代价是<strong>长任务会被打断</strong>。Codex 的回答是：长任务不应该塞在主回合里——那种活交给子 Agent 去跑（见 §5），主回合必须始终保持"随时可被新输入顶掉"的能力。</p> <h3>2.2 跨回合与回合内：两个容器的明确分野</h3> <p>Codex 把"要跨回合保留"的状态与"仅当次回合有效"的瞬态分别装进两个容器：</p> <table> <thead> <tr> <th>容器</th> <th>生命周期</th> <th>典型内容</th> </tr> </thead> <tbody> <tr> <td><strong>TurnContext</strong></td> <td>跨回合、当次不变</td> <td>sub_id、模型信息、turn 计时、session 遥测</td> </tr> <tr> <td><strong>ActiveTurn · TurnState</strong></td> <td>仅当次回合</td> <td>一组 <code>pending_*</code> 的单向 oneshot 通道、token_usage_at_turn_start、tool_calls 计数、<code>granted_permissions</code> 合并态</td> </tr> </tbody> </table> <p>这里有一条容易被忽略的工程纪律：<strong>权限不跨回合</strong>。回合内用户临时授予的"允许访问网络"、"允许写这个目录"这类权限会被滚动合并进当次 <code>granted_permissions</code>，但回合一结束，整份 profile 就随瞬态一起被丢弃。下一回合要做同样的事，必须重新请求。这条纪律换来的是——不会出现"上次批准过所以这次也能偷偷做"的灰色地带。</p> <h3>2.3 一次 Turn 的完整时序</h3> <pre><code class="language-mermaid">sequenceDiagram participant U as 用户/触发源 participant S as Session participant T as ActiveTurn participant Tk as 执行体 Task participant R as Rollout/遥测 U->>S: 提交输入 / Mailbox 唤醒 S->>S: abort_all_tasks(Replaced) 顶掉旧回合 S->>T: 新建 ActiveTurn · 起 tokio 任务 T->>Tk: 挂取消令牌 + AbortOnDropHandle Tk->>Tk: run() 执行本回合逻辑 Tk->>R: flush_rollout T->>S: on_task_finished(last_agent_message) S->>R: token 直方图上报 S->>U: TurnComplete 事件 alt 被中断 S->>Tk: cancellation_token.cancel() Tk-->>S: 100ms 优雅窗口内收尾 S->>Tk: handle.abort() 强制砍 S->>R: 写入 TURN_ABORTED + flush S->>U: TurnAborted 事件（严格在 flush 之后） end</code></pre> <h3>2.4 单 Agent 内部 runtime loop：两层嵌套</h3> <p>用户输入进来之后，真正推动事情发生的是<strong>两层嵌套的循环</strong>。Codex 里最容易被误读的事情之一是——外层那个"submission_loop"<strong>并不是 LLM 的思考循环</strong>，它只是一个 Op 分发器（用户输入、审批响应、shutdown、review 等控制指令的分派中心）。真正的 LLM 循环在下面两层里。</p> <h4>2.4.1 外层循环：pending input 的吸收</h4> <p>外层循环是 Task 自身的 <code>run()</code> 主体（以最常用的 RegularTask 为例），它的职责只有两件：</p> <ol> <li>调一次 <code>run_turn()</code>（进入内层循环）</li> <li>内层返回后，检查 <code>TurnState.pending_input</code> <ul> <li>有 pending → 把它作为下一次输入，再进一次 <code>run_turn()</code></li> <li>没有 → 结束当次 Turn，把 <code>last_agent_message</code> 交回</li> </ul> </li> </ol> <p>这是 Codex 处理"用户在 Agent 跑的时候追加输入"的方式：新输入<strong>不会</strong>立刻新开一个独立 LLM loop，而是被塞进 <code>TurnState.pending_input</code>，等外层循环的下一次检查时再吸收。这条设计让"追加"与"替换"成为两种明确可区分的语义——追加走 pending input，替换走 Replace。</p> <h4>2.4.2 内层循环：采样事件流的消费闭环</h4> <p>内层是真正贴近模型的地方。它在进入前先做一串预处理：</p> <ul> <li><strong>预采样压缩</strong>：检查上下文是否接近阈值，若接近则先触发 compact（详见 §4）</li> <li><strong>context updates</strong>：计算 <code>reference_context_item</code> 与当前状态的差分，生成本回合要发的增量</li> <li><strong>skill / plugin / app mention 注入</strong>：把用户提到的扩展按需塞进 history</li> <li><strong>hook 执行</strong>：submit hook / pending input hook 等</li> <li><strong>ghost snapshot 旁路</strong>：可能启动一个 <code>GhostSnapshotTask</code> 订阅 <code>tool_call_gate</code></li> <li><strong>构造本次 prompt</strong></li> <li><strong>进入采样</strong></li> </ul> <p>然后进入一个带重试的真实采样循环，它<strong>持续消费</strong>模型流式返回的事件（<code>OutputItemAdded</code> / <code>OutputTextDelta</code> / <code>OutputItemDone</code> / <code>ReasoningSummaryDelta</code> / <code>ReasoningContentDelta</code> / <code>Completed</code>），并按事件类型分流：</p> <ul> <li>模型返回的是普通文本 / reasoning / web 等非工具调用项 → 记录进 history、同步发 EventMsg 给前端</li> <li>模型返回的是工具调用 → 进入<strong>工具闭环</strong>：</li> </ul> <pre><code class="language-mermaid">flowchart LR A[OutputItemDone<br/>含 tool call] --> B[ToolRouter<br/>构建 tool call] B --> C[ToolCallRuntime<br/>运行时上下文] C --> D[ToolRegistry<br/>dispatch_any] D --> E[ToolOrchestrator<br/>审批 + 沙箱 + 重试] E --> F[工具结果 → ResponseInputItem] F --> G[drain_in_flight<br/>回写 history] G --> H[下一轮采样] H -. needs_follow_up .-> A</code></pre> <p>工具执行<strong>不阻塞主循环</strong>。模型产生 tool call 之后，这条闭环以"记录 call → 异步执行 → 回灌结果"的方式推进；工具跑的时候，内层循环可以继续消费别的事件；工具完成后，结果以 <code>ResponseInputItem</code> 的形式进入 history，下一轮采样模型就能看到。</p> <h4>2.4.3 结束判定与自动压缩</h4> <p>采样结束时要回答一个问题：<strong>要不要再来一轮？</strong></p> <ul> <li>若 <code>needs_follow_up = true</code> 且 <code>token_limit_reached = true</code> → 先触发 <strong>auto compact</strong>（mid-turn 压缩，见 §4），然后回到预处理阶段准备下一轮</li> <li>若 <code>needs_follow_up = true</code> 但未触发压缩 → 直接回到预处理阶段准备下一轮</li> <li>若 <code>needs_follow_up = false</code> → 走 stop hook / after_agent hook；hook 决定 block / stop / continue</li> </ul> <p>这里 <code>token_limit_reached</code> 是压缩章节最关键的布尔，它的取值规则见 §4.1。</p> <h3>2.5 Ghost snapshot 的 gate：为什么"修改性工具"要等</h3> <p><code>run_turn</code> 开头可能启动一个 <code>GhostSnapshotTask</code>，订阅 <code>tool_call_gate</code>。ToolRegistry 在分派工具时区分两类：</p> <ul> <li><strong>读取类工具</strong>（grep、read、list 等）——不需要等</li> <li><strong>修改类工具</strong>（apply_patch、write、exec 中会改环境的指令等）——进入 <code>wait_ready()</code> 阻塞，直到 <code>GhostSnapshot</code> 完成并 <code>mark_ready()</code></li> </ul> <p>这条 gate 的意义是——<strong>所有会改环境的动作，在"能撤回的快照"就位之前绝不启动</strong>。这让后续的 undo / ghost commit 语义具备一致的时间基线。纯读取不被拖累，成本只落在真正会动环境的那一小撮工具上。</p> <h3>2.6 本章速查</h3> <table> <thead> <tr> <th>关键约束</th> <th>工程兑现</th> </tr> </thead> <tbody> <tr> <td>Replace 优先于 Queue</td> <td>新回合进场先 abort_all_tasks(Replaced)</td> </tr> <tr> <td>退场顺序</td> <td>flush_rollout → TurnAborted 事件</td> </tr> <tr> <td>中断容错</td> <td>100 ms 优雅窗口 → handle.abort() 强砍</td> </tr> <tr> <td>权限不跨回合</td> <td>granted_permissions 随 TurnState 销毁</td> </tr> <tr> <td>外层 loop 职责</td> <td>合并 pending input，准备下一次 run_turn</td> </tr> <tr> <td>内层 loop 职责</td> <td>消费 ResponseEvent，分流普通 item 与 tool call 闭环</td> </tr> <tr> <td>自动压缩触发</td> <td>token_limit_reached && needs_follow_up</td> </tr> <tr> <td>ghost gate 规则</td> <td>mutating tool 等快照 ready，读取类直通</td> </tr> </tbody> </table> <hr /> <h2>§3 执行体契约：一个共享骨架，六种形态</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb0844c.png" width="100%" /></p> <p align="center">_{<b>图 3-0</b>　本章总览：一份 SessionTask 契约（kind / span_name / run / abort 四件事），向下辐射出六种执行体形态；对外只暴露三档 TaskKind。}</p> <p>§2 讲清了"回合怎么跑"，接下来这一章回答另一个同样基础的问题：<strong>一个"能在回合里跑起来的东西"，长什么样？</strong></p> <h3>3.1 契约只约束四件事</h3> <p>Codex 没有给执行体定一棵继承树，而是给了一份薄到极点的契约。契约只约束四件事：</p> <table> <thead> <tr> <th>契约字段</th> <th>用途</th> </tr> </thead> <tbody> <tr> <td><code>kind</code></td> <td>用于遥测分桶</td> </tr> <tr> <td><code>span_name</code></td> <td>用于 tracing span 的命名</td> </tr> <tr> <td><code>run</code></td> <td>承载所有业务逻辑——怎么跑，随你</td> </tr> <tr> <td><code>abort</code></td> <td>被中断时如何优雅收尾</td> </tr> </tbody> </table> <p>契约之外的一切——内部如何组织状态、走哪些工具、何时发事件、要不要再分内部循环——都不管。执行体只需要承诺"被中断时能收尾"，其他全部自由。</p> <p>这份克制带来的工程红利非常具体：<strong>新增一种形态时，唯一的问题是"它能不能满足这四件事"</strong>，而不是"它应该长在哪棵子树下、要重写哪些虚函数、会不会破坏基类不变量"。失败模式从"继承误用 + 业务错误"收敛到"业务错误"。</p> <h3>3.2 六种形态：共骨架，各身份</h3> <p>共享契约上落了六种具体形态。每一种身份清晰、关键能力差异明确：</p> <table> <thead> <tr> <th>形态</th> <th>身份</th> <th>关键能力差异</th> </tr> </thead> <tbody> <tr> <td><strong>RegularTask</strong></td> <td>与用户对话的主回合</td> <td>最通用——消费用户输入、调工具、写回 history</td> </tr> <tr> <td><strong>ReviewTask</strong></td> <td>审批与批准</td> <td>Guardian 主导，跑在自己的"审查回合"里，不与对话回合混用（见 §8）</td> </tr> <tr> <td><strong>CompactTask</strong></td> <td>上下文压缩</td> <td>按 provider 能力分流到 local / remote 两条路径（见 §4）</td> </tr> <tr> <td><strong>GhostSnapshotTask</strong></td> <td>时光分叉与修改性工具的门闸</td> <td>以 Task 身份被调度，结果同时作用于 <code>tool_call_gate</code></td> </tr> <tr> <td><strong>UndoTask</strong></td> <td>逆向回滚</td> <td>撤销上若干个回合的副作用，利用 Rollout 反向播放</td> </tr> <tr> <td><strong>UserShellTask</strong></td> <td>用户直通 Shell</td> <td>把用户的一次 shell 命令做成托管 Task，共享中断与遥测</td> </tr> </tbody> </table> <h3>3.3 对外只暴露三档 TaskKind</h3> <p>值得单独点名的一条工程纪律：<strong>对内六种，对外三档</strong>。TaskKind 这个对外枚举只有 Regular / Review / Compact 三档。GhostSnapshot、Undo、UserShell 都被归到 Regular 这一档对外呈现。</p> <p>理由朴素——UI、遥测、用户心智只需要知道"系统现在在对话、在审查、还是在压缩"这三种宏观状态。"系统正在做一次 ghost 快照" 或 "正在回放 undo" 是实现细节，不应泄漏到外部契约。</p> <p>这是一条标准的"对外枚举窄、对内实现宽"的分层纪律。反过来做的系统——对外字段越堆越多、对内反而乱成一锅——每次升级都在 breaking change。</p> <h3>3.4 为什么"压缩"也要做成一种 Task？</h3> <p>在很多 Agent 框架里，上下文压缩是一个躲在主循环之外的"外挂功能"——偷偷改历史、不走日志、出错了留个 error log 就完事。这种架构每次 bug 都是一场考古：谁改了上下文？什么时候改的？改完触发了哪些事件？压缩失败后当前回合到底继不继续？没人能当场说清楚。</p> <p>Codex 把压缩做成 Task，这些问题当场全部消失：</p> <ul> <li>压缩有自己的 sub_id、走自己的 rollout、享受自己的遥测分桶</li> <li>压缩走 CancellationToken 级联，可以被正常中断</li> <li>压缩可以被新的 Regular 回合以 Replace 语义顶掉——不会卡住主流程</li> <li>压缩失败会像任何 Task 一样 emit <code>TurnAborted</code> / <code>TurnComplete</code>，上层该重试就重试、该熔断就熔断</li> </ul> <p>统一成 Task 的代价是<strong>进度反馈不够细</strong>——一个压缩 Task 对外只能告诉你"开始了"和"结束了"。需要中间进度时，用事件流（Mailbox / EventMsg）补；不需要时省事。这是可接受的取舍。</p> <h3>3.5 本章速查</h3> <table> <thead> <tr> <th>关键断言</th> <th>工程含义</th> </tr> </thead> <tbody> <tr> <td>契约只约束四件事</td> <td>新形态只需满足四件事，不需要继承适配</td> </tr> <tr> <td>对内六种 / 对外三档</td> <td>实现宽、接口窄</td> </tr> <tr> <td>压缩、快照、undo 都是 Task</td> <td>共享中断、遥测、rollout；失败路径一致</td> </tr> <tr> <td>Task 缺细粒度进度</td> <td>需要时用事件流补；不强塞进 Task 自己</td> </tr> </tbody> </table> <hr /> <h2>§4 上下文压缩：双路分流 × 基线差分 × 阈值算法</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb184be.png" width="100%" /></p> <p align="center">_{<b>图 4-0</b>　本章总览：窗口度量决定”要不要压”，双路分流决定”在哪压”，注入策略决定”压完怎么回到历史里”。图中双路对比处仅标注了两条路径各自的最突出特征；完整的性价比矩阵请参见 §4.3 的表格。}</p> <p>长对话 Agent 绕不过的一个问题是：<strong>历史无限增长，但模型的上下文窗口是有限的</strong>。很多框架把压缩做成"事后补救"，但 Codex 把它做成贯穿每一回合的实时窗口管理——压缩不是一次性任务，是一台每回合都在计算"要不要压、在哪压、压完回哪儿"的引擎。</p> <p>这一章是全文最需要精确度的一章，我们按四个问题层层拆：</p> <ul> <li><strong>怎么量</strong>——窗口是如何被度量的？</li> <li><strong>什么时候压</strong>——触发条件是什么？</li> <li><strong>怎么压</strong>——压缩动作与两条分支的差异</li> <li><strong>压完之后</strong>——对上下文与 history 的确切影响</li> </ul> <h3>4.1 窗口如何被度量</h3> <p>Codex 的 <code>ContextManager</code> 维护一份按时间序追加的 items 列表，同时持续维护一套<strong>可量化的窗口指标</strong>。核心指标有四个：</p> <table> <thead> <tr> <th>指标</th> <th>含义</th> </tr> </thead> <tbody> <tr> <td><code>last_api_response_total_tokens</code></td> <td>上一次成功 API 响应里模型返回的 total tokens（服务端权威数据）</td> </tr> <tr> <td><code>all_history_items_model_visible_bytes</code></td> <td>当前历史中所有"模型可见项"的累计字节</td> </tr> <tr> <td><code>estimated_tokens_of_items_added_since_last_successful_api_response</code></td> <td>上次成功响应以来新增 items 的估算 tokens</td> </tr> <tr> <td><code>estimated_bytes_of_items_added_since_last_successful_api_response</code></td> <td>上次成功响应以来新增 items 的估算字节</td> </tr> </tbody> </table> <p>这四个指标合起来描述<strong>一条复合的窗口推进曲线</strong>：</p> <blockquote> <p><strong>真实曲线 = 上次 API 的权威 token 底板 + 自那以后自己追加的估算增量</strong></p> </blockquote> <p>为什么不直接"每回合都本地数 token 重算一次"？因为 token 数与具体 tokenizer 强相关，本地估算总是粗略的；真正准确的数字只能从模型服务端的响应里回来。Codex 的折中是——<strong>把权威数据作为基准，把本地估算仅用于"基准之后"的增量</strong>，这样误差永远锁在"一次回合的增量范围"而不是"整段历史的累计范围"。</p> <p>两个配置决定了窗口上限：</p> <table> <thead> <tr> <th>配置项</th> <th>角色</th> </tr> </thead> <tbody> <tr> <td><code>model_context_window</code></td> <td>模型的<strong>硬上限</strong>（例：某模型是 272 000）</td> </tr> <tr> <td><code>model_auto_compact_token_limit</code></td> <td>自动压缩的<strong>软阈值</strong>（可选，模型级可配）</td> </tr> </tbody> </table> <p>工程上这两个阈值的意义完全不同：<strong>硬上限是"物理不可越过"的天花板，软阈值是"到这里就该主动压一次"的预警线</strong>。</p> <h3>4.2 触发条件：一个布尔的合成</h3> <p>压缩的真正触发点发生在<strong>内层采样循环结束时</strong>的一次判定——具体就是 §2.4 提到的 <code>token_limit_reached && needs_follow_up</code>。这个布尔并不神秘，它是由上面几个指标合成的：</p> <ul> <li><strong><code>token_limit_reached = true</code></strong>：当"权威底板 + 本地增量估算"越过了 <code>model_auto_compact_token_limit</code>（若未配置则退化为 <code>model_context_window</code> 的某个保守比例）</li> <li><strong><code>needs_follow_up = true</code></strong>：本轮采样还需要继续（例如刚刚触发了 tool call、或模型要求继续生成）</li> </ul> <p>两者同时成立才触发自动压缩。逻辑上这是<strong>必要的合取</strong>——如果本轮根本不需要继续，就没必要压；如果本轮要继续但还没到阈值，也没必要压。</p> <p>除了这条 mid-turn 自动路径，还有两条触发入口：</p> <ul> <li><strong>pre-turn 预采样压缩</strong>：<code>run_turn</code> 开头预检一次，若发现即将超限则先压后采样</li> <li><strong>用户/系统显式调用</strong>：作为一个 CompactTask 被显式 spawn</li> </ul> <p>三条入口在<strong>动作层</strong>使用同一套压缩 pipeline，但在<strong>注入策略</strong>上会分叉（见 4.5）。</p> <h3>4.3 双路分流：本地还是远端</h3> <p>压缩动作到底在哪里发生？Codex 不给你一个全局开关，它有一个能力探测器。判定逻辑极简：</p> <blockquote> <p><strong><code>should_use_remote_compact_task(provider) = provider.is_openai()</code></strong></p> </blockquote> <p>只要 provider 是 OpenAI，走远端平台侧压缩；否则走客户端本地压缩。理由也朴素——OpenAI 平台有专门的历史压缩能力，吞吐大、对超长文本失真小；其他 provider 不一定具备相同能力，本地压缩更稳妥。</p> <p>两条路径的性价比差异如下表：</p> <table> <thead> <tr> <th>路径</th> <th>优势</th> <th>劣势</th> <th>适用</th> </tr> </thead> <tbody> <tr> <td><strong>local</strong>（客户端）</td> <td>时延低、成本低、provider 不分家</td> <td>吞吐受限、对超长文本失真大</td> <td>非 OpenAI provider、日常小幅收缩</td> </tr> <tr> <td><strong>remote</strong>（平台侧）</td> <td>吞吐大、对超长历史失真小</td> <td>时延高、走一次网络</td> <td>OpenAI provider、极长历史</td> </tr> </tbody> </table> <p>重要的不是"谁更好"，而是<strong>两条路径都在 rollout 与遥测里打了独立标签</strong>，可以长期观察性价比漂移——随着平台能力进化，分流规则本身就可以被数据驱动地调整。</p> <p>压缩输入里还有一条硬上限：<strong>一次被压缩的"用户消息侧输入"不超过 <code>COMPACT_USER_MESSAGE_MAX_TOKENS = 20 000</code></strong>。这不是压缩后的输出上限，而是"喂给压缩模型的原文本输入"的上限——防止一次异常大的用户消息把压缩本身给撑爆。</p> <h3>4.4 压缩动作：做了什么</h3> <p>无论走 local 还是 remote，压缩核心动作都是三步：</p> <pre><code class="language-mermaid">flowchart LR A[当前 history 快照] --> B[运行压缩采样<br/>生成 summary 文本] B --> C[替换 history] C --> D[按 InitialContextInjection<br/>决定 reference 命运] D --> E[写入 ContextCompaction<br/>一条标记 item 进 history 并落盘 rollout]</code></pre> <p>第 3 步的 "replace history" 不是粗暴地把全部历史扔掉，而是一次<strong>可控替换</strong>：保留必要的会话前缀（系统指令、instruction wrapper 等），把"可被压缩的正文"替换为 summary 文本。</p> <p>最后一步是 Codex 的一条关键工程纪律：<strong>压缩本身要在 history 里留痕</strong>。一条 <code>ContextCompaction</code> item 作为"此处发生过一次压缩"的显式标记被追加写入 history 和 rollout。事后复盘任何一次对话，都能清楚看到"在第几回合做了压缩、压缩前后 history 长什么样"。</p> <h3>4.5 注入策略：两种"回到历史"的方式</h3> <p>压缩出来的 summary 如何被放回 history？这里要先引入一个马上会高频出现的概念——<code>reference_context_item</code>：它是 ContextManager 里登记的"上次稳定态快照"的引用，下一回合要发给模型的内容只是相对它的增量，而不是整份历史。这个锚点怎么处置，决定了 summary 的注入方式。Codex 有两种策略，对应两种触发入场：</p> <table> <thead> <tr> <th>策略</th> <th>使用场景</th> <th>summary 放置位置</th> <th><code>reference_context_item</code> 的命运</th> </tr> </thead> <tbody> <tr> <td><code>BeforeLastUserMessage</code></td> <td><strong>mid-turn 自动压缩</strong></td> <td>注入到 last user message <strong>之前</strong>；因模型被训练为"把 summary 视作 history 末项"处理</td> <td>保留</td> </tr> <tr> <td><code>DoNotInject</code></td> <td><strong>pre-turn / 手动压缩</strong></td> <td>不再往 summary 里合并 initial context</td> <td><strong>主动清空</strong>为 None</td> </tr> </tbody> </table> <p>这里藏着一个模型侧的配合约定——模型被训练为"遇到压缩 summary 时，把它当成 history 的末项"来理解后续的 last user message。mid-turn 场景必须遵守这个习惯，所以采用 <code>BeforeLastUserMessage</code>；pre-turn 场景还没开始与模型交互，不必遵守，采用更简单的 <code>DoNotInject</code>，并把 reference 清掉，让下一次 regular turn 从"基线空"的状态开始，全量重注 initial context。</p> <h3>4.6 reference_context_item：基线差分的灵魂</h3> <p><code>reference_context_item</code> 是 <code>ContextManager</code> 里最重要的一个字段：<strong>它是下一回合与"上次稳定态"做差分的锚点</strong>。</p> <table> <thead> <tr> <th>状态</th> <th>含义</th> </tr> </thead> <tbody> <tr> <td><code>Some(snapshot)</code></td> <td>下一回合只发送与该基线的差异（context update）</td> </tr> <tr> <td><code>None</code></td> <td>下一回合走全量重注（会一次 cache miss，但语义一定对）</td> </tr> </tbody> </table> <p>基线差分的工程红利非常具体——<strong>维持它就能让后端 prompt cache 结构性命中</strong>：如果每回合都重发整个上下文，后端 cache 每次失效；如果只发"多出来的部分"，prefix 始终复用，cache 命中率稳定。</p> <p>这份红利的风险是——<strong>基线一旦指向已不存在的历史，下一轮 diff 就是错的</strong>。Codex 用一条硬规定堵死这个漏洞：<strong>回滚（<code>drop_last_n_user_turns</code>）若触及"混合 developer context bundle"，必须立即把 <code>reference_context_item</code> 设为 None</strong>。下一回合会退化为全量重注，代价是一次性的 cache miss，但语义一定正确。</p> <p>这是一条典型的"<strong>不要在快路径上省状态，而要在错路径上保正确</strong>"的取舍：快路径因状态充分而快，错路径因基线被显式清空而对。</p> <h3>4.7 截断纪律：压缩之外的一道防线</h3> <p>压缩是面向"历史总量"的，但还有一道面向"单次工具输出"的防线——<strong>TruncationPolicy</strong>。</p> <p>每个工具调用返回的输出都要按策略截断，防止一份异常大的 JSON 响应把整段上下文撑爆：</p> <table> <thead> <tr> <th>策略</th> <th>行为</th> </tr> </thead> <tbody> <tr> <td><code>TruncationPolicy::Tokens(n)</code></td> <td>按 token 估算逼近上限截断</td> </tr> <tr> <td><code>TruncationPolicy::Bytes(n)</code></td> <td>按字节兜底强制截断</td> </tr> </tbody> </table> <p>两条策略在不同工具里按场景使用：Code Mode 与 ToolRouter 默认走 Tokens，JS REPL 默认走 Bytes。图片和文档类工具输出更激进——<strong>压缩前就被整体替换为占位符</strong>，保留"此处曾有一张图"的结构性信息，丢弃昂贵的 token 体积。</p> <h3>4.8 reasoning 的跨回合可见性</h3> <p>最后一条与压缩联动的小纪律：<strong>reasoning 项在当前回合内完全可见，但跨过下一个 user message 边界后不可见</strong>。</p> <p>模型 reasoning 是"本次决策的过程"，不是结论。把上一个回合的 reasoning 塞给下一个回合，只会浪费 token、增加噪声、让模型陷入已经做过的推理。Codex 在 history 归一化时对跨边界的 reasoning 做了显式剥离——切片只保留当前回合内的推理过程，跨边界的推理自动失踪。</p> <p>这条纪律看起来琐碎，但它直接决定了长对话的上下文稳定性：<strong>越老的推理越不该被带进新的回合</strong>。</p> <h3>4.9 压缩的全生命周期示例</h3> <pre><code class="language-mermaid">sequenceDiagram participant L as 内层 sampling loop participant CM as ContextManager participant Comp as Compact 引擎 participant H as history/rollout L->>CM: 查询窗口度量 CM-->>L: token_limit_reached = true L->>L: needs_follow_up = true Note over L: 两条件合取 → 触发自动压缩 L->>Comp: run_inline_auto_compact_task<br/>(InitialContextInjection::BeforeLastUserMessage) Comp->>Comp: 选择 local / remote<br/>(provider.is_openai()?) Comp->>Comp: 生成 summary Comp->>H: replace_compacted_history<br/>写入 ContextCompaction item Comp->>CM: 保留 reference_context_item H-->>L: 新 history 就位 L->>L: 回到预处理 → 构造新 prompt → 下一轮采样</code></pre> <h3>4.10 本章速查</h3> <table> <thead> <tr> <th>关键参数 / 断言</th> <th>工程含义</th> </tr> </thead> <tbody> <tr> <td>窗口度量 = 权威底板 + 本地增量估算</td> <td>误差锁在本回合，不累积</td> </tr> <tr> <td>硬上限 <code>model_context_window</code></td> <td>物理天花板</td> </tr> <tr> <td>软阈值 <code>model_auto_compact_token_limit</code></td> <td>主动压缩的预警线</td> </tr> <tr> <td>触发条件</td> <td><code>token_limit_reached && needs_follow_up</code> 合取</td> </tr> <tr> <td>双路分流判据</td> <td><code>provider.is_openai()</code></td> </tr> <tr> <td>压缩输入上限</td> <td><code>COMPACT_USER_MESSAGE_MAX_TOKENS = 20 000</code></td> </tr> <tr> <td>压缩留痕</td> <td>history 写入一条 <code>ContextCompaction</code> item</td> </tr> <tr> <td>两种注入策略</td> <td><code>BeforeLastUserMessage</code>（mid-turn） vs <code>DoNotInject</code>（pre-turn/manual）</td> </tr> <tr> <td>基线清空规则</td> <td>回滚触及混合 bundle → 强制清 reference</td> </tr> <tr> <td>Truncation 两档</td> <td><code>Tokens(n)</code> / <code>Bytes(n)</code></td> </tr> <tr> <td>图片/文档</td> <td>压缩前以占位符替换</td> </tr> <tr> <td>Reasoning 边界</td> <td>跨下一个 user message 后不可见</td> </tr> </tbody> </table> <h3>4.11 压缩路径拓扑视角</h3> <p>把 §4 全章的关键机制收到同一张图里：上半段是 local / remote 双路分流的决策走向，下半段是 ContextManager 内部"基线 + 差分"数据通路。两段合起来回答一件事——<strong>一次压缩触发，系统从"在哪压"到"压完怎么回到历史里"经历了哪些关键状态</strong>。</p> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb24376.png" width="100%" /></p> <p align="center">_{<b>图 4-1</b>　压缩路径拓扑：上半段展示 local / remote 两条压缩路径由 provider 能力探测器分流；下半段展示 ContextManager 的基线-差分通路——reference_context_item 作为稳定基线，增量变更以 diff 形式注入下一回合。}</p> <hr /> <h2>§5 多 Agent 调度：共享控制面 × 独立执行栈 × 七件套工具</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb2eebc.png" width="100%" /></p> <p align="center">_{<b>图 5-0</b>　本章总览：协调者只派活不亲自动手（顶部）、per-root 的 AgentControl 带四道守门锁（中部）、每个子 Agent 持有独立 Thread/Codex/Session/Turn 执行栈（底部），Mailbox 做横向邮路衔接 §6。}</p> <p>这里先澄清一个容易被误读的事实：<strong>Codex 的"多 Agent"不是一堆 Agent 共享同一个执行循环</strong>。每一个被派出的子 Agent 都会<strong>新建自己独立的 Thread / Codex / Session / ActiveTurn</strong>——也就是说，子 Agent 自己跑着一份完整的、与父 Agent 同构的单 Agent runtime loop。</p> <p>真正被"共享"的，是<strong>控制面</strong>：派单、限额、命名、回滚、通讯，这一整套协调机制由父之上的 AgentControl 与 AgentRegistry 统一管辖。多 Agent 架构的核心思想一句话概括就是——<strong>执行栈独立、控制面共享</strong>。</p> <h3>5.1 协调者的不对称：只派活，不亲自动手</h3> <p>第一条纪律：<strong>协调者自己绝不下场执行</strong>。遇到要干的事，永远派一个子 Agent 去跑，自己只负责设预算、等回执、裁决。这条"不对称"看起来很形式主义，但它直接决定整个架构的可观测性。</p> <p>设想对立面：如果协调者"遇到事不急就自己干、很忙时再派活"，这棵任务树的深度就会在运行时飘移——谁在跑、谁在等、谁在排队，从外部看不清楚。Codex 的选择是强制每一次"动手"都必须显式派一次单，任务树因此永远是"两层浅树"——根是协调者，叶是若干子 Agent。<strong>可观测性与架构形状天然对齐</strong>。</p> <h3>5.2 per-root 的 AgentControl：为什么是一个，不是一棵</h3> <p>AgentControl 不是每个 Agent 自带一份，而是<strong>整棵 root 会话树共享一份</strong>。按"每个 Agent 自带控制面"的直觉，这似乎反了。理由有两条：</p> <ul> <li><strong>调度必须全局一致</strong>：谁还在跑、还剩多少名额、下一个新 Agent 起什么昵称——这些决策一旦分散就会失去一致性，出现"A 觉得还能派，B 觉得满了"的尴尬。</li> <li><strong>子 Agent 天然继承父的上下文世界</strong>：shell 快照、执行权限、会话来源等"能力域"绑在 root，子 Agent 不需要从零重建。</li> </ul> <p>这里还有一条工程细节值得单独点名——<strong>AgentControl 对 ThreadManagerState 的反指是单向的弱引用，而不是共享强引用</strong>。整个引用链是 <code>ThreadManagerState → CodexThread → Session → SessionServices → AgentControl</code>，若再从 AgentControl 以强引用反指回 ThreadManagerState，就形成一个完整的引用环，内存永不释放。<strong>弱引用反指针一刀斩断这个环</strong>——控制面结构虽有反向查询需要，但不延长对象生命周期。这是基于引用计数的内存管理里一条通用纪律，和语言无关；在具备自动垃圾回收的运行时里换成等价的手动解绑即可。</p> <h3>5.3 AgentRegistry 的四道守门锁</h3> <p>AgentRegistry 是控制面真正的"门卫"，同时在四个维度上设锁：</p> <table> <thead> <tr> <th>锁</th> <th>作用</th> <th>机制</th> </tr> </thead> <tbody> <tr> <td><strong>总数锁</strong></td> <td>限制同一 root 下最多多少子 Agent</td> <td>原子计数器 + <code>max_threads</code> 硬上限</td> </tr> <tr> <td><strong>深度锁</strong></td> <td>限制 spawn 嵌套深度</td> <td>从 session_source 取 depth，加 1 与 <code>max_depth</code> 比</td> </tr> <tr> <td><strong>昵称池锁</strong></td> <td>防止同名 Agent 冲突</td> <td>随机抽名，用尽后 reset + "the 2nd" / "the 3rd" 后缀</td> </tr> <tr> <td><strong>路径锁</strong></td> <td>防止 agent_path 被占用</td> <td>HashMap entry 占位，冲突则拒绝注册</td> </tr> </tbody> </table> <p>昵称池那一条还值得多说一句：<strong>用尽不是错误，而是信号</strong>。reset 会打点 <code>codex.multi_agent.nickname_pool_reset</code>，运维侧看到这条指标上升，就知道用户在一次 session 里派出了大量 Agent——这是典型的"从数据面反观行为面"。</p> <h3>5.4 SpawnReservation：悲观预留、乐观提交</h3> <p>Codex 的 spawn 流程遵循一条并发纪律：<strong>预占先于干活，提交晚于结果</strong>。</p> <pre><code class="language-mermaid">sequenceDiagram participant P as 父（协调者） participant C as AgentControl participant R as AgentRegistry participant SS as 父 Session（Rollout） participant Ch as 子 Agent P->>C: spawn_agent(config, initial_op, source) C->>R: reserve_spawn_slot(max_threads) R-->>C: SpawnReservation（带 Drop guard） alt Fork 分支 C->>SS: ensure_rollout_materialized + flush C->>SS: 读取父 rollout 历史 C->>Ch: fork_thread_with_source · 注入 FORKED 引导 else 普通 spawn C->>Ch: spawn_new_thread_with_source · 空白起跑 end C->>R: reservation.commit(agent_metadata) Ch-->>P: 子就绪 · 进入独立 Turn 节拍</code></pre> <p>流程关键在 <strong>SpawnReservation 的 Drop guard</strong>：reserve 先拿 slot，后面任何一步失败时，guard 析构会自动把计数器减回去——<strong>写代码的人不需要在每一个失败分支手动 release</strong>。这是 Rust RAII 在 Agent 调度场景里的一次标准运用；换其他语言得靠 try/finally 或 defer，代码会长、容易漏。</p> <h3>5.5 Fork vs 普通 spawn：父态下沉</h3> <p>普通 spawn 起一个空白子 Agent。Fork 则把<strong>父的 rollout 历史复制给子</strong>作为背景，并注入一条硬编码的 FORKED 引导消息：</p> <blockquote> <p>"你是新派出的 Agent，上文是父的对话历史，请把它当背景；下一条真正的用户消息才是你的任务"</p> </blockquote> <p>这条引导的必要性很朴素——没有它，模型可能把"背景"误当"指令"，开始反复回答父回合里的老问题。Codex 用这条硬编码消息把边界划清楚。</p> <p>Fork 还会<strong>下沉两件父态</strong>，这一点很多系统容易漏：</p> <table> <thead> <tr> <th>下沉项</th> <th>作用</th> </tr> </thead> <tbody> <tr> <td><code>inherited_shell_snapshot</code></td> <td>父的 shell 进程状态（cd 过的目录、设过的 env、npm install 后的依赖）</td> </tr> <tr> <td><code>inherited_exec_policy</code></td> <td>父的执行权限策略（哪些目录可写、哪些命令允许）</td> </tr> </tbody> </table> <p>只复制"数据"不复制"能力"的 fork，醒来后只是一张死历史截图。Codex 的 fork 把"手能动到哪里"一并下沉，才真正做到"副本能接着干活"。</p> <h3>5.6 v2 七件套：委派的行为语法</h3> <p>多 Agent 的对外行为接口收敛为七件工具，每件只做一件事：</p> <table> <thead> <tr> <th>工具</th> <th>语义</th> <th>一句话描述</th> </tr> </thead> <tbody> <tr> <td><code>spawn</code></td> <td>派出新子 Agent</td> <td>带初始任务的新 thread</td> </tr> <tr> <td><code>assign_task</code></td> <td>给已存在 Agent 交活</td> <td>不创建新 Agent，绑定任务</td> </tr> <tr> <td><code>send_message</code></td> <td>发一条消息</td> <td>通道化，默认仅入队，除非 <code>trigger_turn=true</code> 才立即唤醒新回合</td> </tr> <tr> <td><code>close_agent</code></td> <td>主动收掉一个 Agent</td> <td>关 thread，释放 slot</td> </tr> <tr> <td><code>list_agents</code></td> <td>枚举当前活跃 Agent</td> <td>可见性快照</td> </tr> <tr> <td><code>wait</code></td> <td>父等待子的进展</td> <td>挂起父回合，观察子状态变化</td> </tr> <tr> <td><code>message_tool</code></td> <td>消息路由总入口</td> <td><code>send_message</code> 的上层封装，统一承担优先级、<code>trigger_turn</code> 唤醒位、目的地路由三件事</td> </tr> </tbody> </table> <p>七件套的工程美学在于<strong>正交性</strong>——彼此没有重叠语义，没有一件是另一件的超集。协调者的提示词因此很好写："想派活用 spawn，想等结果用 wait，想催一下用 trigger_turn=true 的 send_message"——不会出现"X 也能做 Y 但这时候别用 Z"的坑。</p> <p>正交的另一层红利是<strong>独立演进</strong>：任何一件工具升级都不会连累其他。</p> <h3>5.7 多 Agent 拓扑全景</h3> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb38dd5.png" width="100%" /></p> <p align="center">_{<b>图 5-1</b>　多 Agent 拓扑视角：中央立着 root 会话主干，下方是 AgentControl + AgentRegistry 双节点控制面，向侧翼铺开若干子 Agent 节点，子 Agent 之间用 Mailbox 邮路横向相连。协调面只有一个，子 Agent 有多个，但它们共享同一张调度网。}</p> <h3>5.8 本章速查</h3> <table> <thead> <tr> <th>关键纪律</th> <th>工程兑现</th> </tr> </thead> <tbody> <tr> <td>协调者只派活</td> <td>任务树永远两层扁平</td> </tr> <tr> <td>AgentControl per-root</td> <td>调度一致性、上下文继承</td> </tr> <tr> <td>Weak 引用破环</td> <td>避免 ThreadManagerState 泄漏</td> </tr> <tr> <td>四道守门锁</td> <td>总数 / 深度 / 昵称池 / 路径</td> </tr> <tr> <td>SpawnReservation Drop guard</td> <td>失败分支自动回滚 slot</td> </tr> <tr> <td>Fork 父态下沉</td> <td>shell 快照 + exec policy 一并继承</td> </tr> <tr> <td>v2 七件套正交</td> <td>每件只做一件事，提示词好写</td> </tr> <tr> <td>Mailbox 背压从调度层来</td> <td>unbounded channel 靠 max_threads 兜底</td> </tr> </tbody> </table> <hr /> <h2>§6 Agent 通讯：Mailbox 的三件原语</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb44168.png" width="100%" /></p> <p align="center">_{<b>图 6-0</b>　本章总览：Mailbox 由 mpsc / AtomicU64 seq / watch 三件原语合成，发送方通过 trigger_turn 位决定”立刻唤醒”还是”只入队”，接收侧用 pending_mails 二级暂存保证可反复检查不误消费。}</p> <p>Codex 的多 Agent 默认跑在同一进程里——父与子共享一个 tokio runtime。既然共享 runtime，通讯就应该使用 runtime 原生语义，而不是搭一层文件/网络/消息总线。Mailbox 的实现朴素到令人意外：三件标准原语组合而成。这一章要回答的问题是——<strong>为什么恰好是这三件、缺任何一件都不行？</strong></p> <h3>6.1 进程内 mpsc：两条坦然接受的代价</h3> <p>Mailbox 不跨进程。<strong>它是为"同 runtime 内的多 Agent 协作"设计的</strong>，明天要把某个 Agent 挪到另一台机器时，Mailbox 派不上用场，必须另起一层桥。Codex 没有试图造"一个机制打穿本地与远程"，而是坦然让 Runtime 层与 Remote 层分化——Runtime 层用 Mailbox，跨机走 app-server / cloud-tasks。换来的是 Runtime 层的极简。</p> <p>Mailbox 用的是 <code>mpsc::unbounded</code>，<strong>没有背压</strong>。发送方永远不会被阻塞。代价是——上游如果发疯，channel 会无限涨。Codex 的回答不是"给 channel 加边界"，而是——<strong>把背压挪到调度层</strong>：AgentRegistry 的 <code>max_threads</code> 限制了"同时最多有多少 Agent"，间接限制了"最多有多少发送方"。通讯层因此可以极简，背压责任下放给调度层。</p> <p>这条"层间信任"的取舍很典型：<strong>每一层相信它下面的那一层把自己的活干好</strong>。</p> <h3>6.2 为什么是三件原语？——反证式论证</h3> <p>Mailbox 的三件原语（mpsc / AtomicU64 seq / watch）缺任何一件都不行。用反证看最清楚：</p> <table> <thead> <tr> <th>只保留</th> <th>会遇到的问题</th> </tr> </thead> <tbody> <tr> <td>只有 mpsc</td> <td>收件方必须一直在 <code>recv</code> 上阻塞，但 Agent 大部分时候在跑自己的 Turn，无法一边干活一边随时听信；或者必须到处写 <code>select!</code>，代码立刻变脏</td> </tr> <tr> <td>只有 watch</td> <td>watch 只广播"最新值"，不保序、不保量。收件方知道"有新东西"，但不知道有多少封、先后如何</td> </tr> <tr> <td>只有 seq</td> <td>seq 能比较发送先后，但光一个原子计数器无法承载消息内容，也无法唤醒</td> </tr> </tbody> </table> <p>三件合起来的分工是：</p> <ul> <li><strong>mpsc 承载真实消息</strong>——保序、保量、不丢</li> <li><strong>AtomicU64 seq 提供全局比较尺</strong>——任意两封信的先后可以被读出</li> <li><strong>watch 提供轻量唤醒</strong>——调度器只订阅 seq，seq 变化即意味着"有新东西"，再去 drain 具体消息</li> </ul> <p>三件原语各自简单，但组合起来的语义<strong>超过</strong>任何一件单独的能力。这是一条工程朴素但常被忽略的设计路径——<strong>不要追求一个万能原语，要追求原语之间的正交互补</strong>。</p> <h3>6.3 trigger_turn：精准唤醒 vs 仅入队</h3> <p>每封 <code>InterAgentCommunication</code> 都带一个布尔字段 <code>trigger_turn</code>。这个字段的语义只有一个问题——<strong>这封信需不需要立刻启动一个新的 Turn？</strong></p> <table> <thead> <tr> <th>取值</th> <th>行为</th> <th>典型场景</th> </tr> </thead> <tbody> <tr> <td><code>trigger_turn = false</code></td> <td>仅入队，收件方下次自然启动 Turn 时一并读到</td> <td>异步状态汇报、背景数据同步</td> </tr> <tr> <td><code>trigger_turn = true</code></td> <td>调度器立刻起一个新 Turn 处理</td> <td>"@-提醒"式的主动催促、紧急指令</td> </tr> </tbody> </table> <p>调度器判断"要不要唤醒"的唯一入口是 <code>has_pending_trigger_turn</code>——扫一遍 <code>pending_mails</code>，只要有一封 trigger_turn=true 就起 Turn。</p> <p>这条设计把"异步协商"与"主动催促"在同一个通讯机制里天然分离。Agent 之间可以用 <code>trigger_turn=false</code> 的信件堆积"状态汇报"，直到某一方觉得时机到了、该推进，才发一封 <code>trigger_turn=true</code> 把对方真正叫醒。这非常像人类群聊的行为——信息可以持续堆积，但真正要对方反应时得"@ 一下"。</p> <h3>6.4 二级暂存 pending_mails：为什么要再暂存一次</h3> <p>Receiver 侧不是直接从 mpsc 读就完事，而是在 mpsc 读端之上套一个 <code>pending_mails</code>（VecDeque）做二级暂存。每次 drain 时：</p> <ol> <li>先把 mpsc 里积压的所有消息 <code>try_recv</code> 到 pending_mails</li> <li>再把 pending_mails 整体返回</li> </ol> <p>为什么要这一层？因为 mpsc 的 <code>try_recv</code> 是<strong>破坏性的</strong>——你调一次就把消息消耗掉了。如果在某个非 drain 的操作里需要<strong>只检查不消费</strong>（例如 <code>has_pending_trigger_turn</code> 想判断"现在有没有 trigger"），就必须有一个<strong>可反复检查、但保序消费</strong>的中间站。<code>pending_mails</code> 就是这个中间站。</p> <h3>6.5 易混点：seq 保序 ≠ 全局消费保序</h3> <p>这是 Mailbox 最值得推敲的一条纪律。</p> <p>AtomicU64 的 seq 只保证<strong>发送顺序可观测</strong>——任何两封发出去的信，谁先谁后，seq 能告诉你。但它<strong>不保证跨接收者的消费顺序</strong>。如果父对两个子 Agent 各发了一封信，两个子 Agent 的 drain 时间完全由各自的 Turn 节拍决定。</p> <p>这是故意的。<strong>不同 Agent 应按自己的节拍读信，强行对齐会打破 Runtime 的独立性</strong>。</p> <p>如果业务真需要跨 Agent 的严格时序怎么办？Codex 的答案直接——<strong>那就让协调者来决定谁先处理</strong>。把"跨 Agent 时序"这种复杂性推到它该负责的那一层（协调语义），而不是塞进通讯层。</p> <p>这条设计是整套 Runtime 反复复用的思路：<strong>把复杂性推到该负责它的那一层</strong>。通讯层简单，是因为协调层接住了。</p> <h3>6.6 本章速查</h3> <table> <thead> <tr> <th>关键事实</th> <th>工程含义</th> </tr> </thead> <tbody> <tr> <td>三件原语缺一不可</td> <td>mpsc 保量保序、seq 保可比、watch 保轻量唤醒</td> </tr> <tr> <td>unbounded 无背压</td> <td>背压下放给调度层 max_threads</td> </tr> <tr> <td>trigger_turn 二态</td> <td>异步汇报 vs 主动唤醒</td> </tr> <tr> <td>pending_mails 二级暂存</td> <td>为支持"只检查不消费"场景</td> </tr> <tr> <td>seq 保序 ≠ 跨 Agent 消费保序</td> <td>跨 Agent 时序交由协调语义解决</td> </tr> <tr> <td>跨进程不在本层承诺</td> <td>Runtime 层专注同进程，跨机走别的协议</td> </tr> </tbody> </table> <hr /> <h2>§7 记忆：两阶段管线 × 水位线 × 使用感知</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb52558.png" width="100%" /></p> <p align="center">_{<b>图 7-0</b>　本章总览：记忆系统被拆成两条节拍完全不同的管线——左侧 Phase 1 多 worker 并行从历史里抽取原子级 raw_memory 与 rollout_summary，右侧 Phase 2 单例串行读取 State DB、按 usage_count 与水位线筛选 Top-N，交给一个受约束的 consolidation 子 Agent 整理成可读文件。}</p> <p>Agent 的"记忆"是个被讨论过度但做扎实不多的话题。业界默认答案是向量库——切块、嵌入、余弦相似度。Codex 没有走这条路，它的选择更反潮流也更朴素。</p> <h3>7.1 反潮流：不走向量</h3> <p>向量库确实快、确实可规模化，但它有一个永远绕不过去的问题——<strong>召回结果对人类不可读</strong>。一次向量召回给出的"奇怪但相关"的片段，用户只能接受、解释不了；要手动纠正一条错误记忆，你得先从向量里把它找出来。</p> <p>Codex 走另一条路：</p> <ul> <li><strong>记忆以可读文件形态落盘</strong>——<code>raw_memories.md</code> 合并主干，<code>rollout_summaries/</code> 逐份细目</li> <li><strong>召回不算余弦</strong>——走一次小模型的相关性选择，由它根据当前任务语义挑选注入</li> <li><strong>用户可以直接 cat、grep、手动编辑</strong></li> </ul> <p>这是一次有意识的交易：<strong>用召回延迟换可解释性与可审计性</strong>。对短命的 bot 这笔交易看似过分，但对长期陪伴的 Agent 是划算的——<strong>记忆漂移</strong>这件事可以被发现、被纠正，而不是在某次向量距离的抖动中被悄悄吞噬。</p> <h3>7.2 为什么拆成两个阶段？</h3> <p>记忆的生产是两件截然不同的事：</p> <table> <thead> <tr> <th>事件</th> <th>性质</th> <th>适合的并发模型</th> </tr> </thead> <tbody> <tr> <td>从单条历史里提取片段</td> <td>"读"——独立、可并行</td> <td>多 worker 高并发</td> </tr> <tr> <td>把散落的片段汇总成连贯知识</td> <td>"写"——必须串行、全局一致</td> <td>单例、串行、有锁</td> </tr> </tbody> </table> <p>塞在一起，要么读慢了，要么写乱了。Codex 拆成两个阶段，每段用自己该用的并发模型。</p> <h3>7.3 Phase 1：分布式 Rollout 抽取</h3> <p>Phase 1 的工作单位是"一份历史 rollout → 一条结构化记忆"。它只对满足一串前提的 session 触发：</p> <ul> <li>不是 ephemeral 会话</li> <li>不是 sub-agent 会话（应由根会话承担）</li> <li>启用了 memory feature</li> <li>State DB 可用</li> <li>session 已空闲足够时间（不抽热数据）</li> <li>没被另一个 worker 抢先 claim</li> <li>在本次启动的扫描/领取上限内</li> </ul> <p>满足条件后，worker 会在 State DB 里抢一把 <strong>lease</strong>：拿到即成为这份 rollout 的唯一处理者，其他 worker 看到就绕开。Lease 失败、抽取失败会走 retry backoff，不热循环。</p> <p>这是一套在 State DB 层用 <strong>claim-lease</strong> 实现的分布式协调——不依赖额外的分布式锁服务，因为 State DB 已具备事务能力。</p> <p>抽取出来的结构体有三件：</p> <table> <thead> <tr> <th>产物</th> <th>用途</th> </tr> </thead> <tbody> <tr> <td><code>raw_memory</code></td> <td>尽量完整的记忆描述，供 Phase 2 consolidator 使用</td> </tr> <tr> <td><code>rollout_summary</code></td> <td>精简摘要，供人类快速浏览与审计</td> </tr> <tr> <td><code>rollout_slug</code></td> <td>可选短 id，供文件系统落地</td> </tr> </tbody> </table> <p>落盘前还有一道<strong>秘密擦洗</strong>：按规则把抽取过程中混进来的三类敏感内容——API 令牌 / 密钥、口令与认证串、绝对路径里的私有目录与用户名——统一替换成占位符。这是看似琐碎但不可省的防线——<strong>记忆若承载秘密，Agent 就会在某次无意中把它吐出来</strong>。</p> <h4>7.3.1 三种结局的分类价值</h4> <p>Phase 1 的单份抽取有<strong>三种可能结局</strong>，每一种被独立分类：</p> <table> <thead> <tr> <th>结局</th> <th>含义</th> <th>是否重试</th> </tr> </thead> <tbody> <tr> <td><strong>succeeded</strong></td> <td>产出了非空记忆，入库等待 Phase 2</td> <td>否</td> </tr> <tr> <td><strong>succeeded_no_output</strong></td> <td>抽取跑通但判定"此历史没什么值得记的"，空记防重</td> <td><strong>否</strong></td> </tr> <tr> <td><strong>failed</strong></td> <td>抽取过程出错</td> <td><strong>是</strong>（带 backoff）</td> </tr> </tbody> </table> <p>三分法的工程价值在于——<strong>"没记东西"与"记失败"是两个完全不同的失败模式</strong>。前者是产品判断，不该被重试；后者是系统错误，应该被重试。把它们合并成一档的系统，要么反复跑一份"其实不值得记"的历史，要么对真实错误熟视无睹。</p> <h3>7.4 Phase 2：全局 Consolidation（单例）</h3> <p>Phase 2 是"一次完整的整理活动"，<strong>必须全局串行</strong>——同一时刻只能有一个 Phase 2 job 在跑。这不是性能取舍，是语义正确性的要求：两个 job 同时写 <code>raw_memories.md</code> 会互相覆盖；两个 job 同时做 Top-N 选择，结果相互矛盾。</p> <p>Phase 2 从 DB 里按规则选候选：</p> <ul> <li>按 <code>usage_count</code> 降序为主——<strong>被用过越多越重要</strong></li> <li>按 <code>last_usage</code>（或 fallback 到 <code>generated_at</code>）降序为次——<strong>新鲜优先</strong></li> <li>跨 <code>max_unused_days</code> 的冷记忆被淘汰出候选集</li> </ul> <p>选完 Top-N 后，Phase 2 做两件事：</p> <ol> <li><strong>先同步文件系统</strong>：合并 <code>raw_memories.md</code>，按需写入/裁剪 <code>rollout_summaries/</code></li> <li><strong>再起一个专用 consolidation sub-agent</strong>（整合用子 Agent）：用 LLM 把原始记忆整理成更高一层的观点</li> </ol> <p>这个专用 sub-agent 有<strong>四条硬约束</strong>：</p> <table> <thead> <tr> <th>约束</th> <th>动机</th> </tr> </thead> <tbody> <tr> <td><strong>无审批</strong></td> <td>不打断自动化流程</td> </tr> <tr> <td><strong>无网</strong></td> <td>防数据外泄与副作用</td> </tr> <tr> <td><strong>仅本地写</strong></td> <td>只能改记忆目录，不能碰其他文件</td> </tr> <tr> <td><strong>禁 collab</strong></td> <td>不允许再派子 Agent，防止递归整理</td> </tr> </tbody> </table> <p>四条里"禁 collab"最关键：没有它，consolidation agent 可能在某次"我需要更多信息"的冲动下自派一个子 Agent 去查——于是进入递归调度。硬性禁止，把问题从根上消灭。</p> <h3>7.5 水位线：让"该不该跑"有明确答案</h3> <p>Phase 2 每次启动时读一个 <code>claimed_watermark</code>——这是"上一次成功整理时，输入数据的最新时间戳"。</p> <p>新一轮整理完成后写一个：</p> <blockquote> <p><strong><code>new_watermark = max(claimed_watermark, newest input's source_updated_at)</code></strong></p> </blockquote> <p>水位线<strong>只单调前进，从不回退</strong>。它的价值是——下一次启动时 Phase 2 立刻能判断"有没有新东西值得整理"：watermark 没动 → 数据还是老的 → 跳过。</p> <p>这是一个极朴素的脏位判据。它不依赖复杂的分布式状态机，只依赖"时间戳单调前进"这一个可靠前提。<strong>幂等因此自然成立</strong>：同一份数据被重复整理的结果应当一致，就算不一致也不会倒退到更旧的水位。</p> <h3>7.6 三态差分：added / retained / removed</h3> <p>每次 Phase 2 选完 Top-N，会与"上一次成功 Phase 2 的选择"做对比，标成三态：</p> <table> <thead> <tr> <th>状态</th> <th>含义</th> </tr> </thead> <tbody> <tr> <td><strong>added</strong></td> <td>本次新进入 Top-N</td> </tr> <tr> <td><strong>retained</strong></td> <td>本次与上次都在 Top-N</td> </tr> <tr> <td><strong>removed</strong></td> <td>上次在、本次不在</td> </tr> </tbody> </table> <p>这份三态差分被拼进 Phase 2 的提示词里，让 consolidation agent 知道"什么是新增、什么是保留、什么是被遗忘"，而不是把每一次都当作从零开始的整理。</p> <p>最巧妙的一条：<strong>removed 的 evidence 不会被立刻删</strong>。被移除的记忆在本次整理过程中仍然可见，让 consolidator 可以"说明性地遗忘"——在新整理中显式提及"某某知识已过时"，而不是悄悄消失。</p> <p>这是 Codex 记忆系统最值得被复用的一条设计——<strong>它能解释"遗忘"</strong>。大多数记忆系统在这点上是哑的：你问它为什么忘了某件事，它答不上来；Codex 能答出来——"那条记忆的 usage_count 连续多久没涨、被 max_unused_days 淘汰"。可追溯、可解释。</p> <h3>7.7 usage_count 与 last_usage：让记忆会老去</h3> <p>每条记忆被召回使用时，<code>last_usage</code> 被打点、<code>usage_count</code> 累加。这两个字段是"记忆活力"的度量：</p> <ul> <li>活跃记忆的 <code>usage_count</code> 不断增长 → 在 Top-N 中稳居前列</li> <li>不活跃记忆的 <code>last_usage</code> 停滞 → 一旦跨过 <code>max_unused_days</code> 阈值进入淘汰候选</li> </ul> <p>还有一个容易被忽略的标签——<code>selected_for_phase2</code>。它记录的是<strong>上一次成功 Phase 2 的那份选择快照</strong>。Phase 1 的后续 upsert 只改 stage-1 原始数据，不会踩掉这个标签——这让"前一轮 selection 基线"永远保留，三态差分才能稳定工作。</p> <p>这条纪律再一次印证了整个系统的一条同源思想：<strong>快路径由于状态被保留而快，错路径由于标签被守住而对</strong>。与 §4 的 <code>reference_context_item</code> 是同一个范式。</p> <h3>7.8 Phase 详细管线放大</h3> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb5d9c9.png" width="100%" /></p> <p align="center">_{<b>图 7-1</b>　把 §7.3 与 §7.4 的流程细节放到同一张工程视图里：Phase 1 侧展示了多 worker 在 State DB 上抢 lease、三种结局分类（succeeded / succeeded_no_output / failed）、落盘前的秘密擦洗；Phase 2 侧展示了水位线判据、Top-N 候选池选择、三态差分（added / retained / removed）以及 consolidation sub-agent 的四条硬约束（无审批 / 无网 / 仅本地写 / 禁 collab）。}</p> <h3>7.9 本章速查</h3> <table> <thead> <tr> <th>关键设计</th> <th>工程兑现</th> </tr> </thead> <tbody> <tr> <td>目录式记忆</td> <td>raw_memories.md + rollout_summaries/，可 cat/grep/手改</td> </tr> <tr> <td>两阶段拆分</td> <td>Phase 1 读并发、Phase 2 写单例</td> </tr> <tr> <td>claim-lease</td> <td>基于 State DB 事务的分布式协调</td> </tr> <tr> <td>三种结局分类</td> <td>succeeded / succeeded_no_output / failed 不可合并</td> </tr> <tr> <td>水位线单调</td> <td>幂等自然成立</td> </tr> <tr> <td>三态差分</td> <td>added / retained / <strong>removed</strong>（可解释遗忘）</td> </tr> <tr> <td>selected_for_phase2 标签</td> <td>保留上一次 selection 基线</td> </tr> <tr> <td>四条硬约束</td> <td>consolidator 无审批 / 无网 / 仅本地写 / 禁 collab</td> </tr> </tbody> </table> <hr /> <h2>§8 贯穿控件：审批、可回放、快照、取消</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb69589.png" width="100%" /></p> <p align="center">_{<b>图 8-0</b>　本章总览：四根贯穿控件（Guardian 审批 / Rollout JSONL 时光机 / GhostSnapshot 分叉快照 / CancellationToken 方向性取消）与五层（入口面 / 会话与回合面 / 执行体平面 / 能力与工具面 / 持久化与记忆面）形成 4×5 交点矩阵，每个非空格子都对应一类具体的保护行为。}</p> <p>§1 讲到，层解决正常路径、控件解决失败路径。这一章要做的，是把四根控件各自"做了什么、做在哪一层、有什么方向与顺序约束"讲透。</p> <p>一个容易被误读的事实：<strong>控件不是"横切关注点"</strong>。大多数框架谈 aspect 时把日志、权限、审计一股脑扔进切面，骄傲宣称"解耦了"——但那是<strong>无向的切面</strong>。Codex 的四根控件每一根都有明确的传播方向与截断规则，它们是<strong>有方向的贯穿柱</strong>，不是随手撒开的网。</p> <h3>8.1 Guardian：把"问人"从主回合里抽出来</h3> <p>Guardian 解决一类很特殊的阻塞——<strong>Agent 不确定某个操作能否执行时需要问人类</strong>。问人既不能阻塞主回合（用户可能半天才来看一眼），也不能完全异步（审批决策必须影响后续流程）。</p> <p>Codex 的做法是——<strong>把 Review 做成一种 Task</strong>。TaskKind 里专门给了 Review 一档。当主回合触发审批需求时，系统起一个独立的 Review Task，它跑在自己的回合节拍里：有自己的上下文、自己的 rollout 痕迹、自己的遥测。主回合该暂停的地方暂停，审查结束后结论回灌。</p> <p>"审批独立成回合"的工程红利是——<strong>审批历史被持久化到与对话同等的粒度</strong>。事后复盘一次任务，可以清晰看到"在第几回合、系统请求了审批、决策是 Allow、于是继续"。对代码生成、生产部署这类需要审计的场景尤其重要。</p> <p>Guardian 的策略文件是<strong>可编辑</strong>的，不是硬编码。不同团队、不同项目可以带各自的 policy 文件，策略调整不需要改代码。<strong>策略与代码分离</strong>是 Guardian 的一条小但关键的工程纪律。</p> <h3>8.2 Rollout：一条 JSONL 写到底的时光机</h3> <p>Rollout 是 Codex 的时光机。每一项 ResponseItem——用户消息、模型回复、工具调用、工具输出、reasoning、ghost snapshot 标记——都以<strong>追加写一行 JSONL</strong> 的方式落盘。没有二级索引、没有复杂 schema，就是一行一行往下写的朴素 JSONL。</p> <p>这份朴素换来三件事：</p> <ul> <li><strong>可回放</strong>：从任何一个点读起，就能重建当时的上下文</li> <li><strong>可分叉</strong>：任何一条 rollout 都可以被 fork 出一个新线程，作为子 Agent 的背景（见 §5.5）</li> <li><strong>可 grep</strong>：调试时不需要专门工具，文本编辑器就能看</li> </ul> <p>Rollout 有一条<strong>顺序约束</strong>——<strong>flush 必须发生在 TurnAborted 事件发出之前</strong>。下游接收方可能一收到 <code>TurnAborted</code> 就回读 rollout 文件检查状态，若 rollout 尚未落盘就会读到半包，整个下游的状态判断都会错。</p> <p>这条顺序约束的代价是每次回合结束都有一次同步写盘。这笔开销是值得的——换来的是"跨进程读 rollout 的一致性"永远成立。</p> <h3>8.3 GhostSnapshot：把"时光快照"做成一等公民</h3> <p>GhostSnapshot 是 Codex 里一个独特的抽象——<strong>"我要看看这个历史点长什么样"这件事本身是一种 Task</strong>。</p> <p>大多数系统把快照做成"外挂功能"——点一个按钮、系统偷偷复制一份状态。GhostSnapshot 反过来：它是真正的 Task，享受全部 Task 纪律——有自己的 sub_id、走自己的 rollout、被 CancellationToken 管理、走遥测分桶。</p> <p>除了"可分叉"之外，GhostSnapshot 还承担一条在 §2.5 讲过的关键职责——<strong>mutating tool 的门闸</strong>。修改性工具在执行前必须 <code>wait_ready()</code>，等 GhostSnapshot 完成并 <code>mark_ready()</code>。这让<strong>所有会改环境的动作</strong>在"能撤回的快照"就位之前绝不启动，保证后续 undo / ghost commit 拥有一致的时间基线。</p> <p>把快照做成 Task 的工程意义是——<strong>分叉体验变便宜</strong>。想试"如果在第三步选另一个方向会怎样"，起一个 GhostSnapshotTask 就行，不需要任何特殊流程。机制的成本越低，使用频率越高；使用频率越高，早期问题越容易被暴露。</p> <h3>8.4 CancellationToken：方向性取消</h3> <p>Codex 的取消信号只有一条硬规定——<strong>只向下传，不向上爆炸</strong>。</p> <p>父 Task 的 CancellationToken 取消时，通过 <code>child_token</code> 级联到所有子 Task；子 Task 内部的取消<strong>绝不上溯到父</strong>。这条方向性看起来是细节，其实是"多 Agent 系统长时间运行后不崩溃"的根因之一。</p> <p>想象没有这条规则：一个子 Agent 跑错了被取消，父也跟着死、兄弟们也跟着死——一次局部失败变成雪崩。Codex 用方向性纪律把<strong>失败的半径严格限定在局部</strong>：父可以主动决定"我也不玩了"，但绝不被子的死拖着陪葬。</p> <p>这是把失败做成<strong>局部事件</strong>的典型设计。失败局部化后，可恢复性就是局部的、便宜的；失败全局化后，每一次失败都要动用大修。</p> <h3>8.5 四根控件的交点矩阵</h3> <p>回到本章的总览矩阵（图 8-0）。每一个交点都是一条具体的保护行为：</p> <table> <thead> <tr> <th>控件 \ 层</th> <th>入口面</th> <th>会话与回合面</th> <th>执行体平面</th> <th>能力与工具面</th> <th>持久化与记忆面</th> </tr> </thead> <tbody> <tr> <td><strong>Guardian</strong></td> <td>审批请求生成</td> <td>Review 独立成 Task</td> <td>审查回合与对话回合互斥</td> <td>敏感工具前置审批</td> <td>审批事件写 rollout</td> </tr> <tr> <td><strong>Rollout</strong></td> <td>事件入口记录</td> <td>flush 先于 TurnAborted</td> <td>每 Task 有自己痕迹</td> <td>工具调用与输出落盘</td> <td>JSONL 追加写</td> </tr> <tr> <td><strong>GhostSnapshot</strong></td> <td>—</td> <td>—</td> <td>以一等 Task 存在</td> <td>mutating tool 前 gate</td> <td>从 rollout 分叉复刻</td> </tr> <tr> <td><strong>CancellationToken</strong></td> <td>取消信号入口</td> <td>父→子级联</td> <td>100 ms 优雅窗口</td> <td>正在跑的工具可被中断</td> <td>—</td> </tr> </tbody> </table> <p>空格子（"—"）也值得看一眼：<strong>不是每根控件都要贯穿所有层</strong>。GhostSnapshot 不管入口面与会话面；CancellationToken 不直接落到持久化层（持久化由 Rollout 自己管）。<strong>控件只穿过它真正需要穿过的层</strong>——这是"有方向"的另一层意思。</p> <h3>8.6 本章速查</h3> <table> <thead> <tr> <th>控件</th> <th>关键方向 / 顺序约束</th> </tr> </thead> <tbody> <tr> <td>Guardian</td> <td>审批独立成 Review Task；策略可编辑而非硬编码</td> </tr> <tr> <td>Rollout</td> <td>flush 先于 TurnAborted；一条 JSONL 写到底</td> </tr> <tr> <td>GhostSnapshot</td> <td>mutating tool 必须等 mark_ready；分叉零特殊流程</td> </tr> <tr> <td>CancellationToken</td> <td>只向下、不向上；失败半径局部化</td> </tr> </tbody> </table> <hr /> <h2>§9 设计结语：可带走的三条工程哲学</h2> <p><img src="http://weizn.net/wp-content/uploads/2026/05/post-1097-6a0175cb74d35.png" width="100%" /></p> <p align="center">_{<b>图 9-0</b>　全文收束：三根柱子（Replace 优先 / 契约优先 / 基线差分）各自有核心判断、代价承认、一句话提炼；底部的”共同元模式”把三者收拢到同一条思想下；”适用 vs 不适用”界定清楚能把它带到哪儿。}</p> <p>一篇技术文章最后应该做的，不是再拆一个模块，而是回头看一眼——<strong>哪些设计是 Codex 的独有选择，哪些是可以被带走的通用哲学</strong>。</p> <h3>9.1 三条可复用的哲学</h3> <h4>哲学一：Replace 优先于 Queue</h4> <p>对与人类对话的 Agent，"最新意图永远最大"是一条几乎没有例外的心智默认。把这条默认提到 Runtime 层做硬承诺，整个系统的对外语义天然与用户期待对齐。代价是长任务必须被派出去——但这反而促成了多 Agent 架构的必要性（§5）。</p> <h4>哲学二：契约优先于继承</h4> <p>一个薄到只有四件事的契约，比一棵深继承树好太多。契约让新形态的加入只需要"满足四件事"，不需要"正确继承十个方法"。它把抽象能力从"类层次"下降到"约定层次"，换来的是<strong>扩展成本的大幅下降</strong>。</p> <h4>哲学三：基线-差分优先于全量重注</h4> <p>无论是上下文管理的 <code>reference_context_item</code>（§4）、记忆 Phase 2 的三态差分（§7）、还是 Agent 调度的 <code>SpawnReservation</code>（§5），它们共享同一条思想：</p> <blockquote> <p><strong>维护一个"上次的稳定态"，本次只发送与它的差异。</strong></p> </blockquote> <p>这条思想让 prompt cache 变成结构性红利而不是偶然红利、让记忆整理能解释"遗忘"、让 Agent 调度能自动回滚。是 Codex 里被反复复用的一条元设计。</p> <p>这三条哲学其实是<strong>同一个模式在不同层面的化身</strong>——让系统的正确依赖"被守住的基线"，而不是"每次重建的全量"。Replace 把"最新意图"作为基线；契约把"四件事"作为基线；基线差分把"上次的稳定态"作为基线。从这个视角回望全文每一个决策——双路压缩是为了给基线管理保留自由度、Mailbox 的 trigger_turn 是为了在基线之上精准增量、记忆的三态差分是在 Top-N 基线上解释变化、per-root 的 AgentControl 是让调度基线始终单一——它们突然都说得通了。</p> <h3>9.2 适用与不适用的边界</h3> <p>Codex Agent Runtime 不是万能的。它的设计适合一类场景、不适合另一类：</p> <table> <thead> <tr> <th>适用</th> <th>不适用</th> </tr> </thead> <tbody> <tr> <td>单用户交互式场景</td> <td>百万 QPS 多租户场景</td> </tr> <tr> <td>多回合、长对话</td> <td>一次性问答服务</td> </tr> <tr> <td>代码编辑、开发工具类</td> <td>极致低延迟检索</td> </tr> <tr> <td>需要可回放的场景</td> <td>不关心历史的场景</td> </tr> <tr> <td>进程内多 Agent 协作</td> <td>大规模跨机 Agent 编排</td> </tr> </tbody> </table> <p>右列的场景不是说 Codex 做不到，而是<strong>它的架构重心不在那里</strong>。想在右列场景里用，要做的不是"调调 Codex"，而是另起一条路。这是一种诚实的边界承认——每个系统都有它的气候带，硬把它移植到别的气候带，结果一定是"跑是跑起来了，但不对劲"。</p> <h3>9.3 一句话收束</h3> <blockquote> <p><strong>Runtime 的底气，不来自循环本身，而来自循环周围那些让它能失败的东西。</strong></p> </blockquote> <p>换句话讲——Runtime 的底气不在于"不会出错"，而在于<strong>它为每一种可能的错提前备好了承接它的结构</strong>。你可以在一台表面很简单的机器里塞进去所有边缘情况，也可以让机器表面看起来稍复杂一点，但每一块复杂都对应一种它准备好承受的失败。Codex 的选择是后者——这是工程上最朴素、也最稀缺的一种美德。</p> <hr /> <h2>附录：全文术语速查</h2> <table> <thead> <tr> <th>术语</th> <th>一句话定义</th> </tr> </thead> <tbody> <tr> <td>Session</td> <td>跨回合持有的会话级运行时宿主</td> </tr> <tr> <td>TurnContext</td> <td>当次回合的只读执行上下文快照</td> </tr> <tr> <td>ActiveTurn · TurnState</td> <td>仅当次回合有效的瞬态（含 pending 通道、计数、授予权限）</td> </tr> <tr> <td>pending_input</td> <td>TurnState 中存放用户追加输入的单向通道，外层循环据此决定是否再跑一轮 run_turn</td> </tr> <tr> <td>granted_permissions</td> <td>当次回合内的临时权限集合，回合结束即随瞬态销毁</td> </tr> <tr> <td>SessionTask</td> <td>执行体契约：kind / span_name / run / abort 四件事</td> </tr> <tr> <td>RegularTask</td> <td>主对话回合</td> </tr> <tr> <td>ReviewTask</td> <td>审查与批准</td> </tr> <tr> <td>CompactTask</td> <td>上下文压缩</td> </tr> <tr> <td>GhostSnapshotTask</td> <td>一等公民快照 + mutating tool 门闸</td> </tr> <tr> <td>UndoTask</td> <td>逆向回滚</td> </tr> <tr> <td>UserShellTask</td> <td>用户直通 Shell</td> </tr> <tr> <td>ContextManager</td> <td>上下文实时窗口管理员</td> </tr> <tr> <td>reference_context_item</td> <td>基线差分的锚点——上次稳定态的 history 快照，下一回合只发与它的 diff</td> </tr> <tr> <td>model_context_window</td> <td>模型硬上限（物理天花板）</td> </tr> <tr> <td>model_auto_compact_token_limit</td> <td>自动压缩的软阈值（预警线）</td> </tr> <tr> <td>token_limit_reached</td> <td>合成布尔：权威 token 底板 + 本地增量估算是否越线</td> </tr> <tr> <td>needs_follow_up</td> <td>合成布尔：当前采样是否需要再来一轮</td> </tr> <tr> <td>InitialContextInjection</td> <td>压缩注入策略（BeforeLastUserMessage / DoNotInject）</td> </tr> <tr> <td>ContextCompaction item</td> <td>写入 history 与 rollout 的压缩标记，事后可复盘"在第几回合压过"</td> </tr> <tr> <td>TruncationPolicy</td> <td>单次工具输出的截断策略，分 Tokens(n) 与 Bytes(n) 两档</td> </tr> <tr> <td>AgentControl</td> <td>per-root 多 Agent 控制面</td> </tr> <tr> <td>AgentRegistry</td> <td>四道守门锁（总数 / 深度 / 昵称池 / 路径）</td> </tr> <tr> <td>SpawnReservation</td> <td>带 Drop guard 的 slot 预占：拿锁先行，失败时自动回滚计数</td> </tr> <tr> <td>Fork vs spawn</td> <td>Fork 复制父的 rollout 历史 + shell 快照 + exec policy；spawn 则空白起跑</td> </tr> <tr> <td>Mailbox</td> <td>三件原语合成的通讯层（mpsc 保量 / AtomicU64 seq 保可比 / watch 轻量唤醒）</td> </tr> <tr> <td>trigger_turn</td> <td>消息位：true 立刻唤醒新 Turn；false 仅入队</td> </tr> <tr> <td>pending_mails</td> <td>Mailbox receiver 侧的二级暂存队列，支持"只检查不消费"</td> </tr> <tr> <td>Rollout</td> <td>JSONL 追加的回放/分叉时光机，flush 先于 TurnAborted</td> </tr> <tr> <td>Guardian</td> <td>审批独立成 Review Task 的异步审批面</td> </tr> <tr> <td>CancellationToken</td> <td>只向下级联、不向上爆炸的取消信号（失败半径局部化）</td> </tr> <tr> <td>Phase 1 / Phase 2</td> <td>记忆"分布式抽取"与"全局整合"两阶段</td> </tr> <tr> <td>claim-lease</td> <td>Phase 1 在 State DB 上的分布式认领机制</td> </tr> <tr> <td>claimed_watermark</td> <td>Phase 2 的单调水位线，只前进不回退，自然幂等</td> </tr> <tr> <td>selected_for_phase2</td> <td>Phase 2 选择基线标签，保留上一次 Top-N 快照以支撑三态差分</td> </tr> <tr> <td>usage_count · last_usage</td> <td>记忆老去度量</td> </tr> </tbody> </table>

sequenceDiagram
    participant U as 用户/触发源
    participant S as Session
    participant T as ActiveTurn
    participant Tk as 执行体 Task
    participant R as Rollout/遥测

    U->>S: 提交输入 / Mailbox 唤醒
    S->>S: abort_all_tasks(Replaced) 顶掉旧回合
    S->>T: 新建 ActiveTurn · 起 tokio 任务
    T->>Tk: 挂取消令牌 + AbortOnDropHandle
    Tk->>Tk: run() 执行本回合逻辑
    Tk->>R: flush_rollout
    T->>S: on_task_finished(last_agent_message)
    S->>R: token 直方图上报
    S->>U: TurnComplete 事件
    alt 被中断
        S->>Tk: cancellation_token.cancel()
        Tk-->>S: 100ms 优雅窗口内收尾
        S->>Tk: handle.abort() 强制砍
        S->>R: 写入 TURN_ABORTED + flush
        S->>U: TurnAborted 事件（严格在 flush 之后）
    end

flowchart LR
    A[OutputItemDone<br/>含 tool call] --> B[ToolRouter<br/>构建 tool call]
    B --> C[ToolCallRuntime<br/>运行时上下文]
    C --> D[ToolRegistry<br/>dispatch_any]
    D --> E[ToolOrchestrator<br/>审批 + 沙箱 + 重试]
    E --> F[工具结果 → ResponseInputItem]
    F --> G[drain_in_flight<br/>回写 history]
    G --> H[下一轮采样]
    H -. needs_follow_up .-> A

flowchart LR
    A[当前 history 快照] --> B[运行压缩采样<br/>生成 summary 文本]
    B --> C[替换 history]
    C --> D[按 InitialContextInjection<br/>决定 reference 命运]
    D --> E[写入 ContextCompaction<br/>一条标记 item 进 history 并落盘 rollout]

sequenceDiagram
    participant L as 内层 sampling loop
    participant CM as ContextManager
    participant Comp as Compact 引擎
    participant H as history/rollout

    L->>CM: 查询窗口度量
    CM-->>L: token_limit_reached = true
    L->>L: needs_follow_up = true
    Note over L: 两条件合取 → 触发自动压缩
    L->>Comp: run_inline_auto_compact_task<br/>(InitialContextInjection::BeforeLastUserMessage)
    Comp->>Comp: 选择 local / remote<br/>(provider.is_openai()?)
    Comp->>Comp: 生成 summary
    Comp->>H: replace_compacted_history<br/>写入 ContextCompaction item
    Comp->>CM: 保留 reference_context_item
    H-->>L: 新 history 就位
    L->>L: 回到预处理 → 构造新 prompt → 下一轮采样

sequenceDiagram
    participant P as 父（协调者）
    participant C as AgentControl
    participant R as AgentRegistry
    participant SS as 父 Session（Rollout）
    participant Ch as 子 Agent

    P->>C: spawn_agent(config, initial_op, source)
    C->>R: reserve_spawn_slot(max_threads)
    R-->>C: SpawnReservation（带 Drop guard）
    alt Fork 分支
        C->>SS: ensure_rollout_materialized + flush
        C->>SS: 读取父 rollout 历史
        C->>Ch: fork_thread_with_source · 注入 FORKED 引导
    else 普通 spawn
        C->>Ch: spawn_new_thread_with_source · 空白起跑
    end
    C->>R: reservation.commit(agent_metadata)
    Ch-->>P: 子就绪 · 进入独立 Turn 节拍