现代 Agent 架构与实现细节对比：十个 Coding Agent / Harness

Freshness metadata

• last_verified: 2026-08-24
• version_scope: pinned source snapshots + same-day HEAD audits listed below
• source_type: official repositories / official documentation / local source audit
• stability: fast-moving

1. 对比对象与版本口径

本章只比较 Coding Agent 产品或 Agent Harness，不再把基础模型推理后端混入同一表格。

对应报告：

• Codex
• Claude Code
• Hermes Agent
• OpenClaw
• Aider
• Goose
• OpenCode
• DeepSeek Harness Web
• pi-agent
• Grok Build

2. 先统一术语

3. 产品边界对比

4. Agent Loop 对比

4.1 三种典型 Loop 形态

1. 最小函数型：pi。最适合学习循环不变量和嵌入 SDK。
2. State machine/actor 型：Goose、Grok Build、OpenCode。适合大量异步政策与多客户端。
3. 事件/插件树型：Codex、DeepSeek Harness、OpenClaw。适合可替换 runtime 与复杂产品面。

Aider 是第四种：它把动作空间限制为 Edit Format，以 reflection 驱动修复循环。

5. Context Assembly 对比

5.1 最有代表性的设计

• 代码结构压缩：Aider Repo Map。
• 事件事实投影：DeepSeek Harness。
• Message/Part 投影：OpenCode。
• 可替换 Context Engine：OpenClaw。
• Core 自定义 transform：pi。
• 多类型任务摘要：Grok Build。

没有一种方式在所有任务都最佳。代码导航、长会话、跨会话记忆和多模态附件是四种不同检索问题。

6. Tool Protocol 与 Executor

6.1 共同不变量

Text复制
ToolCall(id, name, arguments)
  -> resolve exact implementation
  -> validate complete arguments
  -> evaluate permission and workspace boundary
  -> execute with cancel/deadline
  -> normalize success/error/progress
  -> persist ToolResult with the same id
  -> only then continue the model loop

值得特别迁移的保护：pi 对 stopReason=length 的 tool calls 全部禁执行；OpenCode 预先 snapshot 并把 patch 绑定到 turn；Grok Build 对同文件 edits 串行；Aider 对 SEARCH block 唯一匹配；Goose 把 MCP extension lifecycle 纳入管理。

7. Permission、Approval、Sandbox

**Permission、approval、sandbox 是三层：**策略决定可否，交互决定如何得到用户选择，sandbox 决定即使执行时能触及什么。三个词不可互换。

8. Session 与 Persistence

8.1 三种优秀事实模型

• Append-only event log：DeepSeek Harness，适合多种 projection/replay。
• Tree entries：pi，天然表达对话分支。
• Message parts + workspace snapshot：OpenCode，把对话和磁盘 patch 关联。

Grok Build 进一步将 session events 与 worktree/checkpoint 结合；Aider 则让 Git 自身承担大量 artifact history。

9. Compaction 与 Memory

关键不变量：tool call/result 配对、用户约束、当前计划/任务状态、未提交 workspace 事实、summary 范围和版本都要保留。压缩只是对模型输入的投影，不应销毁审计真相。

10. Skills、MCP、Plugins、Subagents

Grok Build 的 worktree subagent、OpenCode 的 child session、Claude/Codex 的官方 subagent contract、OpenClaw 的多 runtime 是四种不同层级。不要只比较“是否有 subagent”布尔值。

11. UI 与协议

共同方向是把 loop truth 从 UI 中移出。浏览器刷新、TUI 重绘或 ACP 客户端断线都不应重新执行已经提交的工具副作用。

12. Observability

生产 trace 的最小关联层次：

Text复制
request/user
  -> session/thread
  -> turn
  -> model request/attempt
  -> step
  -> tool call
  -> approval wait
  -> executor/process
  -> tool result
  -> patch/checkpoint
  -> compaction/verification/final

不同项目的代表做法：Codex/DeepSeek 的 typed events；OpenCode 的 Effect spans + EventV2 + snapshots；Grok Build 的 events.jsonl 与 checkpoint；pi 的 EventStream + JSONL tree；Aider 的 Git diff/commit/lint/test；Goose 的 tracing + state effects。

13. 如何选择研究样本

14. 推荐组合架构

不是把十个项目代码拼在一起，而是组合经过验证的边界：

建议的工程契约：

1. Session 是 durable truth，Context 是可重建 projection。
2. ToolCall、ToolResult、Patch、Approval 都有稳定 ID。
3. Scheduler 对同 session 串行，安全的只读工具可批量并发。
4. Permission 在 executor 之前强制，sandbox 是第二道边界。
5. Compaction 生成带范围的 checkpoint，不删除原事实。
6. Subagent 有预算、深度、workspace isolation 和结果合并契约。
7. UI 只消费 events/projections，不拥有执行真相。
8. 结束前运行 verifier/acceptance tests，而不是只相信 final text。

15. 反模式

1. 把模型 finish_reason 当任务完成证明。
2. 把 KV cache、聊天记录、长期 memory 混为一谈。
3. 只在 system prompt 写权限，没有 executor policy。
4. 并行所有 tool calls，不分析同文件/进程冲突。
5. Compaction 直接删除旧消息，导致 tool pair 和用户约束丢失。
6. UI 断线后重发请求，重复执行有副作用工具。
7. Subagent 共享工作树却没有写冲突和 merge 规则。
8. Plugin、Skill、MCP 共用一个信任开关。
9. 只记录最终答案，不记录 tool errors、approval、patch 与 retries。
10. 用 fast-moving HEAD 的目录名支持精确行为结论，却不固定 commit。

16. 验证清单

• 正常 final-only turn；
• 单工具与多工具；
• 截断/畸形 tool arguments；
• 同文件并发 edits；
• permission allow/ask/deny 与客户端断线；
• shell timeout、cancel 和 child process 清理；
• provider retry 不重复副作用；
• context overflow、compaction、resume；
• branch/fork/rewind 后 workspace 与 session 一致；
• subagent 深度、预算、取消和 worktree cleanup；
• event replay 不重复执行；
• headless/TUI/ACP 对同一终态解释一致。

17. 最终结论

十个项目的共同趋势已经很清晰：现代 Agent 架构从“Prompt + Tools”进化为带持久 Session、显式控制流、确定性权限、可恢复执行器、结构化事件与多客户端协议的运行时系统。

最小可用闭环是：

Text复制
Input
  -> Context Projection
  -> Model Stream
  -> Structured Actions
  -> Permission/Executor
  -> ToolResults + Workspace Evidence
  -> Durable Session
  -> Continue/Compact/Verify/Stop

评价一个 Agent 的关键不在工具数量，而在这条闭环遇到失败、取消、压缩、并发、断线和恢复时是否仍保持同一组不变量。