现代主流 Coding Agent 研究阅读顺序

如果是第一次读 Coding Agent 源码，先挑一个项目，追踪一次工具调用就够了。熟悉后，再比较上下文、权限和恢复机制。下面按阅读目的整理入口，各报告的结论都受所列源码快照与证据范围限制。

last_verified: 2026-08-24

所有报告采用固定 commit，区分 CONFIRMED 源码事实、官方行为、INFERRED 架构推断与 UNKNOWN 未验证项。

1. 最短学习路径

1. 十个 Agent 总对比：先建立 Loop、Context、Tool、Executor、Session、Compaction、Permission 的统一坐标。
2. pi-agent：从最小双层 Loop、typed events 和 tool dispatch 开始。
3. Aider：理解 Repo Map、Edit Format、Git/lint/test reflection。
4. OpenAI Codex：进入完整 Rust coding runtime、工具生命周期和 App Server。
5. DeepSeek Harness Web：研究 Cordis Host/Browser 双插件树与 event-sourced session。
6. OpenCode：研究 Effect SessionProcessor、MessageV2、permission 与 workspace snapshot。
7. Goose：研究 StateMachine Operations、MCP Extensions 和安全检查链。
8. Grok Build：研究 Rust session actor、冲突感知工具批次和 worktree subagents。
9. Hermes Agent：研究自托管、长期 session、skills、memory 与 verification continuation。
10. OpenClaw：研究 Gateway、多 channel、多 runtime、context engine 和 memory 插件边界。
11. Claude Code：以公开仓库、官方文档与 Agent SDK 学习产品契约，同时牢记核心 runtime 的公开源码边界。

2. 按问题选读

3. 每篇都要回答的横向问题

• 主 Loop 的 owner 是谁？Turn、Step、Task 如何区分？
• 下一轮继续、等待和停止的原因是否结构化？
• Context 从哪些持久事实投影，优先级和 token budget 如何决定？
• ToolSpec、Registry、Policy、Router、Executor、ToolResult 如何分层？
• 参数截断、超时、取消、重试会不会重复副作用？
• Permission、Approval、Sandbox 是否在不同层强制？
• Session、Context、Memory、Cache 是否被正确区分？
• Compaction 如何保持 tool pair、约束、任务和 workspace 不变量？
• Subagent 是否有深度、预算、取消、隔离与结果合并契约？
• TUI/Web/ACP/SDK 是否消费同一个 event/session truth？
• Trace 是否能关联 session、turn、model request、tool call、patch 和 final？

4. 统一检查链

Text复制
InputEnvelope
  -> TurnState
  -> ContextProjection
  -> ModelStream
  -> ParsedAction / ToolCall
  -> PermissionDecision
  -> ExecutionResult
  -> ToolResult / Evidence / Patch
  -> SessionEvent
  -> ValidationResult
  -> Continue | Compact | Wait | Stop

先将项目特有名词映射到这条链，再比较实现。这样不会因某项目把“Step”叫“Turn”、把“Plugin”叫“Extension”，就误判成完全不同的架构。

5. 版本核验规则

1. 精确结论固定到 commit，不用 floating main 链接证明默认值。
2. HEAD audit 只确认主模块和行为边界仍存在，不自动覆盖旧快照细节。
3. README/官方文档、源码、测试冲突时，记录漂移并优先可执行测试与实现。
4. 闭源产品只写公开契约，不虚构内部 class 或算法。
5. 基础模型 runtime 不放进 Agent Harness 横向表；模型 KV cache 也不写成 Agent Memory。

先选一条短链路读完

第一次读源码，可以从 Pi 的 Agent Loop 或 Aider 的单轮处理开始，先弄清输入、工具结果和结束条件。再进入 Codex、OpenCode 等层次更多的实现，比较持久化、取消与权限如何接进来。

这里的先后是教学建议，不是复杂度排名。每次只选一个问题，例如“工具失败后，错误怎样回到模型”，记录当前提交与实际文件。2026-10-25 的核对已经确认 OpenCode 原 processor 路径不再适用于当前树，使用本章各项目顶部的新入口。

本节的核验依据

2026-10-25 查阅。下面的链接支持本节的机制说明；练习场景和选型建议是本教程的教学设计。

• Pi：当前循环入口
• OpenCode：当前 SessionRunner