动手学 Pi从零实现 Pi

COURSE MAP

不是 15 个主题，
是一个系统的 15 次状态转移。

你会反复穿过同一条 user → model → tool → result → next turn 主链路； 每一部只增加一种新的所有权或资源约束。

贯穿全书的不变量

  1. 01Provider 专属格式止于 adapter，不能进入 Agent Loop。
  2. 02每个 tool call 都有且只有一个配对 tool result。
  3. 03length 截断中的工具参数绝不执行。
  4. 04完成事件顺序与 transcript 顺序是两种不同事实。
  5. 05Session 只追加；Context 可以重建，但不覆盖历史。
  6. 06Skill 是资源，Extension 是可执行代码与信任边界。
00

序章

先看见完整系统

先观察一条完整轨迹，再亲手重建每个因果环节。
0/1 完成
  1. 00一次 README 读取请求怎样走完 Agent 闭环跟随七个可见里程碑，观察用户消息、模型请求、工具结果和最终回答怎样连成一次完整运行。
I

模型与协议

建立可执行语言

把时间、消息和外部模型翻译成稳定的内部协议。
0/5 完成
  1. 01TypeScript 生存集：四个 DemoEvent 怎样进入测试跟随一组事件对象，读懂联合类型、分支收窄、unknown 验证，以及 ESM 测试怎样加载源码。
  2. 02EventStream：同一个对象怎样交付下一项和最终结果跟随一个 EventStream 实例，观察 push、next 与 result 怎样在两种到达顺序下汇合。
  3. 03保存一次完整的工具往返用一段 README transcript 看清文本、工具调用和工具结果怎样成为可保存的消息。
  4. 04ScriptedModel：同一个实例怎样依次播放两个回合跟踪同一个 ScriptedModel 的两次调用，看清请求快照、cursor、microtask 和消息到事件的投影。
  5. 05模型调用：在课程协议和 Provider API 之间转换跟随一次模型调用，读懂消息如何写成 HTTP 请求，流式响应又如何变回统一事件。
II

工具与循环

闭合 Agent 核心

让模型的意图经过验证，成为可观察的环境动作。
0/3 完成
  1. 06工具调用：一条 echo 请求怎样变成配对结果跟随一次 echo 调用，观察参数怎样经过 schema、Registry 和 executor，最后形成同 id 的工具结果。
  2. 07Agent Loop：一次 README 往返怎样调用模型两次跟随同一条 read 调用，看模型消息、工具结果和最终回答怎样依次进入 transcript。
  3. 08四个工具怎样在同一个 workspace 里完成文件任务跟随 task.txt 的读取、覆盖、精确编辑和命令检查，理解文件与进程工具怎样返回可验证结果。
III

状态与历史

让 Harness 可靠

区分运行状态、持久历史和每次决策所见的上下文。
0/3 完成
  1. 09从单次循环到有状态 Agent让一个对象持有跨运行状态，并把重入、订阅、取消、steering 与 follow-up 的时序写成可执行契约。
  2. 10从一棵会话树恢复当前对话给完成消息加上稳定 id 与 parentId，追加到 JSONL；从选中的叶子恢复 active path，并明确副本、顺序和断尾边界。
  3. 11历史不动，上下文按预算重建把工具往返组成不可拆分的交互，在预算内选择完整后缀，并用追加的结构化摘要恢复更早事实。
IV

扩展与验证

从核心到产品

在不污染核心的前提下组合产品，并用故障证明架构。
0/3 完成
  1. 12知识按需进入上下文，代码先过信任门把项目说明、Skill 和模板接入同一个上下文入口，再用信任检查、原子注册与故障隔离控制可执行扩展。
  2. 13把已有能力接成一个能提交历史的 Runtime显式选择活动分支，恢复 Agent，在每次模型请求前统一构造上下文，并让 prompt 只有在新消息被 Session Store 接受后才完成。
  3. 14给完整的 Pi 建一套独立评测让 runner 每次重新调用 EvalCase.prepare，验证执行轨迹和任务结果，并输出只含固定分类与计数的报告。