25. Agent Loop 全景知识图谱与端到端复习

本章不新增一套与前文平行的概念，而是以一次完整 Agent Loop 为主轴，把第 1—20 章重新组织成多张互相对照的架构图。阅读时始终追踪同一个业务事实：用户目标如何成为模型输入，模型提议如何成为受控副作用，结果如何回到 Context，系统又如何停止、压缩、恢复或分发给子 Agent。

本章是第二遍学习使用的“完整地图”：第一次阅读先看 0.6 节，建立主链和章节位置；学完各专题后再回到本章，把正常执行、异常恢复、Context、Memory、安全、Multi-Agent 和可观测体系串在一起。这样既避免一开始被细节淹没，也能在复习时检查知识之间是否真正连通。

25.1 图谱阅读方法：一条主链，八个观察视角

八个视角共享同一组稳定标识：thread/session_id → turn_id → step_id → call_id/task_id → artifact/event_id。其中 artifact_id 表示执行产物 ID。图中如果两个模块不能用这些 ID 或明确的父子关系关联，就意味着它们之间仍存在恢复、审计或一致性缺口。

25.1.1 核心信息图导航

先用六张核心信息图建立对象关系，再回到本章的全景架构、时序与异常流程。导航按一次任务的理解顺序排列，但排障时也可以根据问题直接跳转。

25.2 Harness 全景功能架构图

这张图体现 Harness 的核心原理：模型不直接接触操作系统，也不拥有最终完成权。模型只在一个固定 Step Context 上产生文本或动作提议；Runtime 把提议交给 Tool、安全和状态平面；Verifier 再依据外部证据判断是否完成。Context、权限、Rollout 和 Trace 必须引用同一 Step/Call 快照，否则模型看到的动作、用户批准的动作与实际执行动作可能不是同一个事实。

Claude Code 的 query → StreamingToolExecutor → executeToolCall → Session Storage 与 Codex 的 RegularTask → run_turn → ToolRouter/Handler → Rollout 都能映射到这张图：query.ts:280、toolExecution.ts:614、regular.rs:38、turn.rs:1288。

25.3 一次 Turn 的端到端时序图

时序中的两个“先持久化”非常关键：模型响应中的 ToolCall 要先写入持久化事件记录，ToolResult 也要先保存最终状态，然后才能推送 UI 或进入下一次采样。这样断线只会丢失临时展示，不会让 Runtime 忘记已执行的副作用。Codex 的 History/Rollout 写入与 Claude Code 的 JSONL/有序写队列分别体现了这一原则：session/mod.rs:1389、sessionStorage.ts:549。

25.3.1 同一次 Turn 中的控制流、数据流与状态流

三条流不能混为一谈：控制流可以重新运行，数据流可以裁剪或压缩，但已经确认的副作用状态不能被重算覆盖。恢复时先用状态流重建“已经发生什么”，再恢复控制流决定“下一步做什么”，最后重新构建数据流需要的 Context；顺序反过来就可能重复执行工具或使用过期权限。

25.4 Agent Loop 控制流与停止条件图

Loop 的“继续”必须带结构化原因：工具结果需要观察、验证失败、用户追加输入、Stop Hook 阻塞、上下文需要压缩、计划需要修订或预算允许重试。while true 只表达重复，无法决定下一轮应改变 Context、权限、输出预算还是任务图。Claude Code query.ts 中不同 transition reason 与 Codex 外层 RegularTask、内层 Turn Loop 的分层，都是把继续原因显式化：query.ts:1095、regular.rs:49。

必须停止的条件包括用户取消、墙钟/Token/费用/Step 预算耗尽、不可恢复安全错误、连续无进展和外部系统明确终止。模型输出自然语言“完成”只是一项完成提议；只有验收通过且系统中没有未完成 ToolCall、Task 或审批时，Runtime 才能写入 Turn 终态。

25.5 什么场景会触发上下文压缩

触发判断不能只写成“当前 Token 超过 80%”。生产系统至少有四类触发：

1. Pre-sampling 预测触发：当前尚未超限，但加上下一批 World State、用户输入或工具 Schema 后将接近阈值。
2. Turn 执行中触发（mid-turn）：工具结果加入 Context 后仍需继续循环，而下一次请求的有效输入已经达到自动压缩阈值。
3. Reactive 触发：Provider 明确返回 Prompt Too Long，Runtime 先清理异常大项，再重建请求。
4. 显式触发：用户手动压缩，或 Session Memory 已有可靠摘要边界，可主动替换旧历史。

压缩通常不应只由 Session 累计消耗的 Token 触发；累计成本预算可以要求停止或提醒，但窗口压缩真正依据的是下一次请求会发送给模型的有效输入。相反，单个 50K Token 工具输出即使总窗口尚有空间，也应先受“单项内容硬上限”约束，避免一项内容挤掉全部计划和约束。

Codex 将 Turn 开始前（pre-turn）与 Turn 执行中（mid-turn）的初始上下文插入策略分开，并在替换后重算 Token；Claude Code 会调整切分位置以保持 ToolUse/ToolResult 配对，再恢复 Plan、Skill、Hook 和后台 Agent 状态：compact.rs:57、compact.rs:368、sessionMemoryCompact.ts:317、compact.ts:1471。

25.6 在线状态机与崩溃恢复流程

25.6.1 Turn 在线状态机

状态机中的 Interrupted 不等于 Failed。采样中断通常可以从已持久化边界重建；工具运行中断则必须区分“确认未执行”“已有终态”和“可能产生副作用但结果未知”。只有前两类能自动继续或复用，第三类需要下游幂等查询或人工确认。

25.6.2 进程重启后的恢复流程

恢复必须重放事实再修复边界，不能反序列化一个旧内存对象后继续运行。权限、cwd、MCP 连接和文件系统可能已经变化，因此旧 StepContext 只能用于审计，恢复后的下一 Step 必须重新捕获世界状态。Claude Code 沿 parentUuid 选择主链并恢复 Plan/Skill，Codex 的 Resume/Fork 分支则恢复历史、有效配置和持久化前缀：conversationRecovery.ts:409、session/mod.rs:1317。

25.6.3 出现异常时如何判断：先确认副作用，再决定恢复动作

判断异常时使用下面的固定顺序：

1. 先查持久化事件，不先猜错误文本：确认 ToolCall、审批、执行开始和 ToolResult 分别记录到了哪一步。
2. 再查外部事实：文件是否已修改、远端任务是否已创建、支付或发布是否已经发生。
3. 再判断幂等性：重复执行是否安全，是否存在业务幂等键，是否只能查询而不能重放。
4. 再判断 Context 是否过期：权限、工作目录、工具 Schema、文件版本或计划假设变化后，必须创建新 Step 快照。
5. 最后选择恢复动作：复用、重试、重新规划、等待审批、人工确认或停止。

25.7 Context–Memory–Prompt 数据流图

这张图要记住三个边界：

• Memory 不等于 Context：Memory 是可持久化候选，Context 是一次 Step 实际选中的有界视图。
• Rollout 不等于 Prompt History：Rollout 是用于恢复的原始事件记录，Prompt History 是根据模型能力、预算和协议约束生成的模型可见视图。
• 压缩不等于删除事实：压缩只替换模型可见历史，原始事件、执行产物和来源记录仍用于审计、恢复，以及按原始记录重新构建状态。

Codex History::for_prompt 在发送前补齐调用结果、移除孤立输出、适配多模态并截断 FunctionCall 输出；World State 又只渲染相对基线的变化，说明 Context 是一个有类型的编译过程，而非字符串拼接：history.rs:141、history.rs:325、environment.rs:115。

25.8 安全工具执行与信任边界图

安全链中每层解决的问题不同：Schema 防止结构错误，Semantic Validator 理解工具语义，Hook 是扩展治理点，Authorization 判断主体是否可请求，Approval 是本次动作的交互授权，Sandbox 则由 OS 强制“即使进程恶意也不能越界”。审批通过不能自动关闭沙箱，Feature Flag 为真也不能跳过权限链。

参数规范化必须只做一次并形成 hash，审批、Policy、Sandbox 和 Audit 都引用同一动作对象。Claude Code 的执行顺序与 Codex requested/granted permission 交集、SandboxManager 后端编译共同体现了这一不变量：toolExecution.ts:682、policy_transforms.rs:126、manager.rs:272。

25.9 Multi-Agent 协作、隔离与汇总图

Multi-Agent 的四个一致性域必须分别管理：Spawn 决定执行实体是否存在，Mailbox 决定信息是否送达，Task Store 决定责任和依赖状态，Worktree/Patch 决定文件修改如何隔离。消息发送成功不代表任务 owner 已转移，Worktree 创建成功也不代表 Agent 获得额外权限。最终 Join 必须同时检查 Task 终态、证据、Diff 与 Agent 生命周期。

根 Agent 不应复制所有子 Agent 的历史，只保留任务摘要、状态、证据和执行产物引用；否则子任务越多，协调者的 Context 越容易膨胀。Claude Code 的 AgentTool、Task Store、Worktree 与 Codex 的 AgentControl、父子 Thread 和通信事件都体现了这些独立边界：runAgent.ts:412、TaskUpdateTool.ts:276、spawn.rs:452、agent_communication.rs:6。

25.10 Rollout、Trace、Metric 与 Eval 的质量闭环

四种数据必须从同一领域事件派生，但不能保存相同内容：Rollout 可以在受控权限下保留回放所需原文；Trace 保存因果、时间和脱敏属性；Metric 只保存取值种类较少的聚合指标；Eval 读取 Rollout 与执行产物并产出质量标签。它们共享 turn_id/step_id/call_id，才能从线上告警定位到单次执行轨迹，再把失败转成可复现的 Eval 用例。

成功指标不能只有 HTTP 200。一次 Turn 可能请求成功却修改错文件，因此需要同时观察任务验收率、验证通过率、用户纠正率、重复工具调用、压缩后事实丢失、权限拒绝与沙箱违规。Codex TurnTimingState 对采样、压缩、工具等待分别计时，Claude Code Session Trace 对 model/tool/approval/hook 建立 Span，正是为了把“慢”和“错”分解到可行动环节：turn_timing.rs:43、sessionTracing.ts:49。

25.11 二十个知识维度在主链中的位置

25.12 一次完整复习的推荐顺序

第一遍只沿第 25.3 节时序图口述正常路径，确保能在 5 分钟内讲清 UserInput → Step Context → Model → Tool → Result → Next Step → Verify。第二遍在每个节点加入异常：模型超长、工具拒绝、审批等待、沙箱违规、进程崩溃、MCP 断线、子 Agent 冲突。第三遍用第 25.11 节表格逐项检查 20 个维度是否都能落到主链位置和一个明确不变量。

方案表达时推荐采用固定结构：先画第 25.2 节六平面全景，再用第 25.3 节走一次时序；评审方追问长任务就展开压缩、Memory 与恢复，追问生产安全就展开权限—沙箱链，追问复杂任务就展开 Plan—Task DAG—Multi-Agent，追问线上质量就展开 Rollout—Trace—Eval 闭环。这样所有知识点都围绕一条 Agent Loop 主线展开，不会变成互不相干的术语清单。

25.13 判断架构是否正确的关键不变量

组件名称会变化，但下面这些规则不能被破坏。复习源码或设计新系统时，应优先检查不变量，而不是检查是否存在某个同名类。

25.14 一页复习卡：从用户目标到可验证结果

25.14.1 六十秒口述模板

一个生产级 Agent 不是“模型加几个工具”，而是由 Harness 管理的可恢复状态机。用户输入先进入 Session 并创建 Turn；Runtime 在每个 Step 固定世界状态、权限和工具目录，再由 Context Builder 按预算组合规则、历史、计划、Skill、Memory 与证据。模型只能生成文本或 ToolCall，动作必须经过参数校验、权限、必要审批和沙箱。ToolResult 先以稳定 call_id 持久化，再进入下一 Step。系统根据验证结果、未完成任务、预算和安全状态决定继续或停止。长任务通过压缩、事件恢复和 Multi-Agent 扩展；Rollout、Trace、Metric 与 Eval 使用同一组 ID 形成质量闭环。

25.14.2 十个自测问题

1. 能否解释 Session、Turn、Step、ToolCall、Task 和 Agent 的区别？
2. 为什么模型看到的 Tool Schema 必须与执行时的 Registry 属于同一 Step 快照？
3. ToolCall 和 ToolResult 为什么必须先持久化再进入下一 Step？
4. 哪四类情况会触发上下文压缩，压缩后必须重新注入什么？
5. Memory、Context、Prompt History 和 Rollout 分别是什么？
6. Approval 与 Sandbox 分别解决什么问题，为什么不能互相替代？
7. 工具超时且结果未知时，为什么不能直接按失败重试？
8. Multi-Agent 中 Spawn、Message、Task 和 Worktree 为什么是四条独立协议？
9. Runtime 在什么条件下才能把 Turn 标记为完成？
10. 如何用相同的 turn_id/step_id/call_id 从告警定位到轨迹，再生成 Eval 用例？

如果这十个问题都能结合一条源码入口、一个异常分支和一个设计取舍回答，说明已经形成完整知识体系，而不是只记住了术语。