动手学 Pi从零实现 Pi

15 CHECKPOINTS · TYPESCRIPT

从一条运行轨迹开始，
一步步实现 Pi。

课程从完全离线的运行轨迹出发，逐章建立流式模型、工具协议、 Agent Loop、会话树、Context Compaction 与可扩展产品入口。 每一步都有真实 TypeScript、故障实验和机器验收。

开始学习00 · 一次 README 读取请求怎样走完 Agent 闭环
先看完整路线为什么这样组织
OFFLINE TRACEScriptedModel · deterministic
  1. 01user读取 README，修复失败测试
  2. 02modeltoolCall · read({ path })
  3. 03tooltoolResult · 文件内容
  4. 04modeltoolCall · edit({ oldText, newText })
  5. 05tooltoolResult · exact replacement
  6. 06modeltoolCall · bash({ command: npm test })
  7. 07loopstop · 修改完成，测试通过
7 events3 model turns0 network calls
从地图开始
真实代码正文接口来自同一套可编译 Workshop
真实输出关键 trace 和边界由测试固定
逐章累积每章留下一个可恢复 checkpoint
失败优先从首次偏差定位责任层与不变量

15 CHECKPOINTS · ONE RUNNING SYSTEM

沿同一条主链路，逐层增加真实复杂性

章节不是仓库目录导览。每一章只引入一种主要复杂性，并让上一章的知识在新约束下再次被调用。
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，验证执行轨迹和任务结果，并输出只含固定分类与计数的报告。

本书的掌握标准

当堂绿灯不是终点。

延迟、无提示、换一个故障情境后，仍能守住消息配对、状态所有权和历史不变量， 才说明你真的会造 Agent。
阅读学习契约 →