动手学 Pi从零实现 Pi

15 CHECKPOINTS · TYPESCRIPT

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

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

开始学习00 · 先观察一次完整的 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先观察一次完整的 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 运行究竟是任务失败、协议失败，还是评测设施坏了。

本书的掌握标准

当堂绿灯不是终点。

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