前言：把四份资料读成一套工程方法

你可能已经读过 Claude Code 的源码附录、DeepSeek Harness 的入门介绍、Pi 的中文教程，或者 Codex 的工程导读。它们让我们知道“代码在哪里”，但真正动手时，还会遇到另一组问题：模型已经会调用工具，为什么任务仍然可能失败？保存了聊天记录，为什么不能放心重试写操作？两套框架都说支持插件，它们的生命周期为什么不一样？

本书从这些具体问题出发，把四份资料与实际源码放到同一张工作台上。全书的主线是一个可以验收的小任务：读取工作区文件，修正拼写，再检查结果。先把这条任务在四套系统中的控制路径找出来，再讨论消息、工具、权限、恢复、并发、扩展和评估，最后用随书实验实现其中最重要的边界。

三种读法

如果刚入门，先读第一至第三章，再读第九、十章和第二十章。暂时不懂 Rust 或 TypeScript，不妨先画数据怎样流动：谁发请求，谁执行操作，谁记录结果，谁判断完成。源码中的名字是定位点，职责才是要建立的知识。

如果研究架构，顺读第四至第八章，然后对照第十一至第十九章。每个项目都选了固定提交，关键结论附有精确源码链接。横向比较使用同一组问题，而不把目录大小、功能数量或语言选择直接当作优劣排名。

如果准备实现自己的代理，先跑第二十章的实验，再阅读第二十一至第二十四章。实验不需要密钥，也不调用真实模型服务；它用脚本模型产生完整流协议，真实执行文件读取、受控写入、校验和日志恢复。这样可以把网络波动、模型随机性与宿主程序错误分开研究。

本书承诺什么

正文是重新组织的工程讲解，不是四本旧书的合订本。四个项目提供源码证据，随书 Python 程序提供可重复实验，练习与答案帮助你检查是否真正理解了边界。实验程序的完整代码也编入电子书附录，脱离网站仍能阅读。

源码结论只适用于列明的快照。Claude Code 材料是用户提供的 2.1.88 提取快照，本书引用保存它的镜像仓库，不声称这是官方公开源码仓库。其构建期分支、缺失模块和外部服务条件，不能根据文件存在与否推断为可用产品能力。

本书没有运行四套上游系统的全部功能，也没有把示意轨迹写成真实模型调用记录。可以实测的随书代码会给出命令与检查项；需要在完整部署环境进一步验证的结论，会注明条件。读者应当能够追问每一句重要的话：“这是源码事实、教学推导，还是实验结果？”

最重要的一句话

一个代理做了什么，应由可核查的状态与结果说明。模型的回答、界面的动画、日志里的“开始”事件，都不能单独证明目标完成。你会在本书不同层次反复遇见这个问题，因为可靠的 Harness 正是把这些证据连接起来的程序。