阅读指南：从问题进入

这不是要求从第一页读到最后一页的项目百科。正文以机制为主线，项目是有边界的案例；同一个问题可能在几个系统中得到不同答案。你可以选择一条路线开始，再沿章节中的链接交叉阅读。

四条阅读路线

先理解机制。 如果还分不清模型、运行器和工具，先看一项任务中的五层职责；再从 Agent、工作流与多 Agent 和 Agent loop 进入上下文、记忆、审批和扩展。每章先抓住“谁决定、谁保存、谁执行、谁验证”，再看项目映射。

沿项目追源码。 从 Pi 的分层进入一条实际运行路径，然后打开章内的代码导读。读系统篇时，先确认上游仓库、固定 commit 和研究范围，再沿“入口 → 状态 → 分支 → 副作用 → 结束或恢复”追踪；不要把一条局部路径误读成项目全貌。

带着设计问题查阅。 如果你正在决定如何保存会话、拦截动作或判断完成，先读相应机制，再看横向对照。比较只针对同一个问题和已有证据，不给项目排总名次。

拿自己的任务做概念对照。 已经在用 Codex 或 Claude Code 的读者，可以先用五层职责分析一项自己的任务：项目约定从哪来、Skill 何时读、MCP 提供什么、动作在哪里受限。此处先提供判断框架；各产品的逐步操作教程和同环境实验仍在编写，不把概念例子当成实测。

概念图是帮助思考的抽象，不声称某个项目恰好按图实现；项目实现图则须能回到固定版本的源码或官方文档。每张正式图都附有文字说明和可编辑图源。箭头表示什么，应由图注与正文解释，不能只靠颜色猜。

书中区分源码事实、文档声明、运行观察、工程推断和未知。例如，读到一个函数的分支，是源码事实；官方文档描述的行为是文档声明；只有记录环境、输入、版本和结果，才称得上运行观察。由证据推导的设计解释应保留“推断”身份，资料不够的地方就标为未知。来源规则说明了这套标记。

图示、测试结果与模型的“完成”回复都不能单独替代任务验收。遇到关键结论，建议点击章内固定源码链接核对版本与条件；遇到图文不一致、链接失效或遗漏的边界，请按贡献指南提交可复核的修正。

在线预览稿：书稿仍在校稿，系统篇以文内固定源码版本为准；静态阅读不等于运行验收。