// Part 目标 v0.3 · 章节展开持续修订

从一次 API 调用，到一个几千行的编码 agent

Part 按真实任务需求划分：新能力带来新的工程压力，runtime 再承担新的责任。每个 Part 先固定出口，再从真实代码 checkpoint 反推章节。

每章结构

1为什么需要它
2原理拆解
3动手实现
4跑起来看效果
5练习与延伸

全书写作中：目前推进序章与第一部分。旧 00–16 条目只按最接近的 Part 临时归类；旧 ch10、ch12 横跨新边界，进入对应 Part 时再重切。

写作中暂定可读

序章

看见模型边界

从一次调用开始

打通终端输入到一次 HTTP 响应的最短路径，并亲手看见“模型调用还不是 agent”。

Part 出口: 一个使用裸 fetch 的无状态聊天 CLI；连续追问时会失忆，读者能解释原因。
阶段验收: 连续问“我叫什么”，第二轮稳定暴露客户端没有保存历史。
明确延后: 跨轮 messages、tool use、agent loop、流式与 SDK。

// 当前章节素材 · 开发本 Part 前重切并冻结

00 导言：把黑盒拆开写作中里程碑 → 环境就绪，看完最终成品演示为什么 agent 没有魔法；最终成品演示；环境准备（Node 22+、API key、~$5 预算）。 01 从 API 调用到聊天 CLI 写作中里程碑 → 一个会失忆的聊天 CLI——连问"我叫什么"都答不出 messages 与角色；打通一次干净的调用，再套一个无状态对话循环。

第一部分

核心闭环

从 fetch 到 SDK

完成模型调用工具、改变环境、读回结果并继续行动的最小 coding agent，再结束 fetch 的教学使命。

Part 出口: SDK 版 agent 能 Read / Write / Edit / Bash，把失败测试修到通过；fetch 与 SDK 行为等价，runAgent 可复用。
阶段验收: 对带失败测试的 fixture 完成“读、改、跑、再改、通过”，并用同一 transcript 验证 fetch / SDK 等价。
明确延后: 环境注入、权限、长上下文、持久化和子 agent；不预留空回调。

// 当前章节素材 · 开发本 Part 前重切并冻结

02 Tool Use：给模型一双手写作中里程碑 → 能查询指定时区时间的助手工具即 JSON Schema 声明；tool call 的请求-响应协议；为什么说"模型只是输出了一段 JSON"。 03 Agent Loop：循环直到完成写作中里程碑 → 记得住你上一句的代码问答 agent loop 的终止条件；messages 数组的增长方式；实现 read_file 工具。 04 写与改：Write、Edit 与 diff 写作中里程碑 → 能修真实 bug 的最小编码 agent 全量写 vs 精确替换；old_string/new_string 的设计权衡；终端里渲染 diff。 05 Bash：让 agent 跑命令写作中里程碑 → 丢给它一个失败的测试，它自己修到通过子进程、stdout/stderr 捕获、超时与输出截断；跑测试→看报错→改代码→再跑的自我迭代闭环。

第二部分

可控运行

让最小 agent 在真实项目中安全、可观察地执行，并在拒绝、故障或取消后保持可用。

Part 出口: 理解项目环境、过程可见、危险操作受控、工具错误可恢复、网络瞬时错误可重试、Ctrl+C 无孤儿进程。
阶段验收: 综合 fixture 覆盖项目指令、权限拒绝、工具失败、429 与 Ctrl+C，失败后当前对话仍可继续。
明确延后: token 预算、compaction、跨 prompt 保存，以及 Todo、子 agent、Skills 和 MCP。

// 当前章节素材 · 开发本 Part 前重切并冻结

06 系统提示词与环境感知暂定里程碑 → 注入环境后答对"当前分支有什么未提交改动" system prompt 的分层设计；注入 cwd、git 状态、目录结构；CLAUDE.md 式的项目记忆文件。 07 权限系统：信任但确认暂定里程碑 → agent 不再能悄悄 rm -rf 危险操作分级；写操作/命令执行的用户确认交互；白名单与会话内记忆。

第三部分

长任务与 Session

管理持续膨胀的上下文和成本，让工作跨 prompt、跨进程延续。

Part 出口: 能观测 token、截断大输出、验证 caching、安全 compaction，并用 JSONL 保存和恢复线性 Session。
阶段验收: 压缩后保留原始任务和关键证据，cache usage 可见，关闭重开可恢复且损坏尾行不拖垮 Session。
明确延后: Todo、Skills、子 agent、MCP，以及 Session tree、事务恢复和 run 中途崩溃续跑。

// 当前章节素材 · 开发本 Part 前重切并冻结

08 token 感知：计数、截断与缓存暂定里程碑 → API 账单下降；大输出不再把窗口撑爆 token 计数与预算（count_tokens / usage 锚定）；大输出截断策略；prompt caching 与账单观测。 09 上下文压缩：compaction 暂定里程碑 → 长对话不再爆窗口，压缩前后 usage 眼见为实手写客户端压缩：何时压（锚定真实 usage、双参数防 thrash）；怎么压；切点结构性排除 toolResult；硬事实结构化留存。 10 健壮性与会话生命周期暂定里程碑 → 429 退避、Ctrl+C 优雅取消、关终端重开对话还在三层健壮性：网络重试与退避；工具错误三段式编码进 tool_result；session JSONL 持久化。

第四部分

计划与分工

让 agent 显式规划多步任务，并把调查工作交给隔离的只读子 agent。

Part 出口: Todo 跨 prompt 保存进度；Task Tool 复用 runAgent，以新 messages 和只读工具集返回可复查证据。
阶段验收: Todo 对比不漏步骤；explorer 返回文件与行号证据，主上下文保持清晰，usage 与取消完整上卷。
明确延后: Skills、MCP、写操作子 agent、worktree 合并、并行调度和后台任务。

// 当前章节素材 · 开发本 Part 前重切并冻结

11 子 agent：分而治之暂定里程碑 → 主 agent 派只读子 agent 全库搜索，自己保持清爽为什么需要隔离上下文；Task 工具的实现；只读工具集作结构性权限；结果附可复查证据。 12 计划、命令与 Skills 暂定里程碑 → 开 todo 不漏步骤；/commit skill 按需加载眼见为实扩展 agent 行为不碰核心 loop：TodoWrite 式工具、斜杠命令、skill 文件的按需加载。

第五部分

开放扩展

沿行为文本和外部工具两条轴增加能力，同时保持核心 loop 不变。

Part 出口: Skills 按需进入 system prompt；MCP 工具经过命名、权限和错误适配后进入同一个 Tool Map。
阶段验收: 未加载 Skill 不占 token；真实 MCP server 可握手、分页、调用、失败降级并在退出时干净关闭。
明确延后: 通用插件框架、多 Provider、MCP 自动重连、热更新和动态下架。

// 当前章节素材 · 开发本 Part 前重切并冻结

13 MCP：接入外部世界暂定里程碑 → 你的 agent 能用上整个 MCP 生态 MCP 协议拆解（不是黑魔法，就是 JSON-RPC）；实现 MCP client，接入一个现成 server。

第六部分

验证与交付

把开发者自用的 CLI 变成体验可展示、能力可量化、边界诚实、别人能复现的开源作品。

Part 出口: 终端体验完整，eval 产出确定性报告，能力证据分级，干净环境可在三分钟内安装跑通。
阶段验收: 产出体验对比 GIF、通过率与成本报告，并由发布 CI 完成干净环境安装和 demo。
明确延后: 生产级 harness、IDE / Web、多用户和企业治理。

// 当前章节素材 · 开发本 Part 前重切并冻结

14 终端体验打磨暂定里程碑 → 流式 markdown、spinner、工具调用折叠不依赖重型 TUI 框架的渲染：spinner、工具调用折叠、流式 markdown 渲染；裸 SSE 手解析作练习。 15 评测：怎么知道它变好了暂定里程碑 → 三配置的通过率与 token 成本对比表为 agent 写 mini eval：固定任务集 + 自动判分；用 eval 验证前面每个特性确实有效。 16 发布暂定里程碑 → 干净容器里 npm i -g 后三分钟跑通 demo 打包成 npm 全局命令；README 写法；如何让别人三分钟跑起来。

附录

Appendix

A API 提供商选择暂定里程碑 → Anthropic 直连 / OpenRouter / 兼容端点 Anthropic 直连 / OpenRouter / 任意 OpenAI 兼容端点（解决国内读者访问问题）。 B 多模型适配层暂定在不同模型供应商之间切换的适配层设计。 C 术语表（中英对照）暂定全书技术名词的中英文对照表。