动手学 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先观察一次完整的 Agent 运行先读懂一条从用户目标到工具结果再到最终回答的完整轨迹，为全书建立地图。
I

模型与协议

建立可执行语言

把时间、消息和外部模型翻译成稳定的内部协议。
0/5 完成
  1. 01TypeScript、测试与 ESM 生存集只学习构造 Agent 所需的 TypeScript 子集，并建立类型检查与行为测试两条证据链。
  2. 02EventStream：让过程和结果走同一条流实现一个既能逐项读取事件、又能等待最终结果的异步流，并把终态写成唯一结束信号。
  3. 03给 Agent 一套自己的消息格式用稳定的消息和内容块保存语义，不让界面格式或某家模型接口渗进核心。
  4. 04ScriptedModel：把模型行为写成可执行规格用按轮消费的确定性脚本生成模型事件，稳定验证请求快照、事件顺序、终态和失败。
  5. 05模型调用：在课程协议和 Provider API 之间转换跟随一次模型调用，读懂消息如何写成 HTTP 请求，流式响应又如何变回统一事件。
II

工具与循环

闭合 Agent 核心

让模型的意图经过验证，成为可观察的环境动作。
0/3 完成
  1. 06Tool 是类型化的环境动作依次实现 validator、Registry 和 executor，把模型提出的动作变成完整、配对的环境结果。
  2. 07把 Agent Loop 写成可验证的状态迁移让模型调用、工具执行和结果回填形成一条有明确终点的反馈回路。
  3. 08Read、Write、Edit 与 Bash把文件和进程能力接入 Agent Loop，并用明确的路径、提交和资源边界约束副作用。
III

状态与历史

让 Harness 可靠

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

扩展与验证

从核心到产品

在不污染核心的前提下组合产品，并用故障证明架构。
0/3 完成
  1. 12知识按需进入上下文，代码先过信任门把项目说明、Skill 和模板接入同一个上下文入口，再用信任检查、原子注册与故障隔离控制可执行扩展。
  2. 13把已有能力接成一个可落盘的 Runtime显式选择活动分支，恢复 Agent，在每次模型请求前统一构造上下文，并让 prompt 只有在新消息落盘后才完成。
  3. 14给完整的 Pi 建一套独立评测用新鲜 fixture、独立判定器、严格协议和脱敏报告，判断一次 Agent 运行究竟是任务失败、协议失败，还是评测设施坏了。