Appearance
工程问题地图：一个最小 Agent 怎样逐步变完整
很多 Agent 架构图一上来就列出模型、上下文、工具、记忆、规划、沙箱、评估和多 Agent。每个词都对，但第一次接触的人仍然不知道：先做什么，为什么要做，晚一点做会发生什么。
本册换一种画法。先从一个能运行的最小版本开始，每遇到一种真实失败，再增加一个部件：
text
一次 LLM API 调用
↓ 模型只能回答，不能读取真实项目
加入工具调用
↓ 一次工具结果还不足以完成多步任务
加入 while 循环
↓ 每轮给模型看什么、改文件、跑命令都有各自的坑
搭出骨架：循环 + 工具 + 上下文 + 写入 + 安全
↓ 能跑不等于好用：上下文会爆、任务会断、规模会大
补高级能力：压缩、渐进加载、会话恢复、长任务、记忆、协作
↓ 能运行不等于稳定完成
补可靠性、评估和上线这条路线把全书分成四层。
| 层次 | 先解决什么 | 对应章节 |
|---|---|---|
| 理解模型 | 一次请求怎样变成输出,上下文成本怎样产生,缓存怎样提速降本 | 第 1～2 章;模型原理与架构见选读章 |
| 骨架 | 用循环、工具调用、上下文、文件写入、Shell 和安全底线，搭出一个简单但完整的 Coding Agent | 第 3～9 章 |
| 高级 | 把骨架变成可用系统：工具调度、检索、渐进加载、压缩、会话恢复、长任务、记忆、多 Agent、扩展、可靠性与界面 | 第 10～20 章 |
| 评估与上线 | 判断 Agent 真的完成而不是只说"完成了"，再谈发布 | 第 21～22 章 |
用工程问题组织内容，用四个实现核对答案
本册不按产品功能清单组织内容，而是从 Code Agent 会遇到的工程问题出发。每个问题先解释失败怎样发生，再比较四个实现如何处理：
| 问题领域 | 写 Code Agent 时会遇到的问题 | 对应章节 |
|---|---|---|
| Agent 基础 | 模型、上下文和工具怎样组成循环？模型之外的程序负责什么？ | 第 3～5 章 |
| 上下文工程 | 每轮给模型看什么？历史太长怎么办？为什么稳定前缀重要？ | 第 2、6、11～13 章 |
| 记忆和知识 | 当前对话、项目知识和跨会话记忆怎样分开？ | 第 11、15 章 |
| 工具 | 工具怎样声明、校验、执行、限权并返回结果？ | 第 4、5、7、8、10、17 章 |
| Coding Agent | 文件怎样安全修改？命令怎样运行？完成后怎样验证？ | 第 7～9、19 章 |
| 交互扩展 | 用户插话、后台任务、图片和取消怎样进入同一运行流程？ | 第 10、18、20 章 |
| 评估 | 怎样判断 Agent 真的完成，而不是只说"完成了"？ | 第 21 章 |
| 模型后训练 | 问题应该修在提示、工具、程序还是模型里？ | 选读章、第 19、21 章 |
| 持续进化 | 经验怎样沉淀、验证、发布和回滚？ | 第 15～17、19 章 |
| 多 Agent | 什么时候拆任务有收益？怎样控制上下文、并发和停止？ | 第 16 章 |
四个实现给出的答案并不相同：
| 项目 | 它优先解决什么 | 适合观察什么 |
|---|---|---|
| codex | 受控地执行真实开发任务 | 权限、沙箱、会话恢复和多端协议 |
| grok-build | 在一个产品中集成大量能力 | 多种编辑方式、后台任务和复杂工具调度 |
| dsh | 让模型、工具、文件系统和循环都可替换 | 插件化、事件记录和运行时组装 |
| pi | 保持核心尽可能小 | 最小循环、默认工具和扩展边界 |
它们不是"完整版到简化版"的排名。能力内置得多，行为更统一，但核心更复杂；能力留给扩展，核心更清楚，但安全、恢复和一致性需要扩展作者自己保证。
读每个高级章节时只问四个问题
- 为什么需要它？ 没有它会出现什么具体故障？
- 最小做法是什么？ 先做到哪一步就能解决主要问题？
- 边界在哪里？ 并发、失败、权限和恢复时会发生什么？
- 四家怎样取舍？ 哪种实现适合自己的产品边界？
读完后，你不需要背一套"标准 Agent 架构"。更重要的是能够从一个最小循环出发，知道每增加一种能力，会同时增加哪些失败方式，以及应该用什么工程手段把风险补回来。