前言

我看过不少 Code Agent 的教程、产品文档和源码解析。它们经常把“Codex 是怎么做的”“Claude Code 是怎么做的”讲得很细：有哪些工具、提示词放了什么、一次调用经过哪些模块。可读完以后，最重要的因果关系仍然不清楚：它为什么要这样做，解决的是哪种失败，又会怎样影响 Agent 最终完成任务的质量。

缺少这层解释，资料越多反而越难吸收。我们能记住一个产品有某项能力，却很难判断自己的 Agent 是否需要它，也不知道遇到质量问题时该改模型、提示词、工具接口还是运行程序。真正需要回答的是：

• 这个设计在防什么具体问题？不做会怎样失败？
• 它影响的是模型判断、执行正确性、稳定性、成本，还是只影响产品形态？
• 哪些环节真正决定任务能否完成，哪些只是某个产品的实现选择？
• 几种实现看起来不同，是否其实在解决同一个问题？各自付出了什么代价？
• 出现质量问题时，应该改提示词、工具、上下文、验证方式，还是模型本身？

这使普通研发工程师很难从现有资料中建立一套可迁移的判断方法：看懂了别人的代码，却仍然不知道自己的系统该怎样设计。

这就是我写这本小册的原因。

这本小册怎样讲

我们不从一张塞满术语的架构图开始，而从研发最熟悉的东西开始：一次 API 调用和一个 while 循环。

一次模型调用
  → 加一个读文件工具
  → 加 while 循环，让模型根据工具结果继续决定
  → 加文件编辑和 Shell，让它能完成真实代码任务
  → 加上下文、安全、状态、恢复和评估，让它从 demo 变成可用系统

每增加一个部分，都按同一条因果链说明：

1. 先把问题说具体：没有它时，哪一步会失败；
2. 再说明为什么需要这项机制，它影响哪一类质量；
3. 然后给出最小做法，以及真实任务里的边界和代价；
4. 最后比较 codex、grok-build、deepseek-harness 和 pi 怎样解决同一个问题，只单独说明真实差异。

表达上遵循一个简单原则：流程图优于代码，代码优于直接描述，直接描述优于概念描述。 先让读者看见数据和控制怎样流动；流程还说不清时，才放少量代码或伪代码；概念只在确实能帮助理解时出现。

这本小册写给谁

本册面向普通研发工程师。你只需要有常规软件开发经验，知道 API、JSON、文件、进程和 Git 是什么；不需要 Rust、机器学习或模型训练背景。

LLM 主线只讲开发 Agent 必须理解的内容:模型 API 怎样工作、上下文成本从哪里来、缓存怎样提速降本。对 token、Transformer、MoE、后训练和推理模型感兴趣的读者,可以阅读第一部分末尾的选读章;不读也不影响后面的实现。

本册也不是源码逐行解析。正文重点是问题、策略、取舍和适用场景；源码入口统一放在附录，供需要继续深挖的读者查阅。

为什么比较四个实现

本册不会沿着某个产品的目录逐项介绍功能。四个开源 Code Agent 用来核对真实实现，也用来观察同一个问题有哪些不同取舍：

• codex（OpenAI，Rust）
• grok-build（SpaceXAI，Rust）
• deepseek-harness / dsh（DeepSeek，TypeScript）
• pi（earendil-works，TypeScript）

比较的目的不是记住“谁有哪个功能”，而是找出三件事：它们共同在防什么问题，真正影响质量的边界在哪里，差异背后的代价是什么。相同做法会合并说明，只有源码中确实不同的选择才分开讨论。

建议接下来先读工程问题地图，再从第 1 章顺序阅读。选读章按兴趣决定是否停留;源码精读入口见附录 B。