按经验选择阅读路线¶
不同读者看同一篇源码导读，想解决的问题并不一样，所以你不用把「从头到尾读完所有文件」当成目标。先选对深度。更合适的读法是先回答当前这一层的问题，等任务主线已经清楚，再进入更深的实现。
Starter：先建立一条完整任务链¶
如果你刚接触编程智能体，而且只熟悉一种编程语言，可以从这一层开始。
第一遍阅读时，只关注这五个直接决定任务主线的问题：
- 项目从哪里接收用户任务；
- 模型请求工具时产生什么数据；
- 工具结果怎样回到下一轮；
- 哪个条件让循环结束；
- 一次失败会在哪里被看到。
Provider（模型提供商）兼容层、终端怎样渲染、遥测怎样导出、发布脚本以及大量边界类型都可以暂时跳过。学完这一层以后，你不必背出文件名。只要合上文档还能画出一次任务怎样沿主链跑完，就算达到了目标。
你可以先读五篇基础导读，再看 pi 或 DeepSeek Harness 的系统地图，然后进入对应课程，依次读 Agent Loop、工具和 Session 相关章节。
Builder：解释一个变量怎样改变行为¶
如果你正在搭建智能体、工具系统或编程智能体，这一层会更贴近手头的问题。
看清完整任务链以后，再继续追踪这些会改变系统行为的变量：
- 配置怎样进入模型请求；
- Tool Schema、调用参数和结果消息怎样转换；
- 可见、允许、批准和可执行为何是四层不同判断；
- Steering、Follow-up、Hook、Extension 或子 Agent 在循环哪个位置介入；
- Session 恢复和压缩怎样改变下一轮输入。
读到这一层时，要把实现和测试对照起来，因为只看一边很难确认某种行为究竟是怎样触发的。变量名不能代替行为。每读完一章，你可以挑一个配置项或状态字段，沿着调用链说明代码在哪里读取它，它又怎样改变后面的行为。
你可以先完整读完任意一条课程，再选一条架构明显不同的课程，等两边的主链都清楚以后，再看对应的横向比较。
Maintainer：判断结论能否持续被核对¶
如果你负责维护 Harness，或者关心安全治理、可观测性和评测系统，可以把阅读推进到这一层。
到了维护阶段，你要开始追问系统长期运行时会发生什么，以及文章里的判断还能不能持续核对：
- 错误是否被正确分类，而不是统一重试；
- 并发执行是否保留确定性的历史顺序；
- 权限拒绝、系统能力不足和工具失败能否区分；
- Session、Trace 和结果产物能否建立稳定关联；
- 上游升级后，哪些源码锚点和解释会失效；
- Eval 是否独立判定任务结果，而不是相信模型自述。
到了这一层，你需要完成确定性实践、检查上游测试，还要为自己关心的机制写出最小复现。一次演示成功证明不了系统换到其他任务、平台或部署条件以后仍然可靠，因此你给出结论时，也必须同时说清自己验证到了什么范围。
怎样在一篇文章中切换层级¶
每篇源码课主要写给 Builder，但也会留下三类入口，让不同阶段的读者都能找到自己该从哪里切入：
- 开头的「先看问题」和流程图供 Starter 建立直觉；
- 中间的源码站点、状态变化与设计解释供 Builder 深读；
- 末尾的核对方法、失败路径和开放问题供 Maintainer 验证。
如果某篇第一遍读不懂，可以先回到课程 README 的系统地图，看看当前模块是在模型调用之前、工具执行之中，还是结果返回以后。只要先确定它在整条任务链上的位置，代码里谁调用谁通常就容易理解了。