为什么不是源码导览
上游仓库按照维护、复用和发布优化；学习路径要按照认知依赖优化。 如果一开始同时面对 provider 协议、流式事件、工具校验、循环终止和会话持久化， 代码可能跑起来，但你很难判断错误第一次出现在哪一层。因此每章只让一种主要复杂性进入系统。
每个学习单元怎样工作
- 预测在看到 trace 前先写判断，让错误形成可比较的信号。
- 完整范例先沿一条因果链建立 schema，不让新手同时搜索目标和代码形状。
- 对照提交每章对应教学分支上的真实 commit，先看 parent，再看这一章只增加了什么。
- 隔离重建从 parent 生成无 Git 历史的目录，只注入本章聚焦测试；第 00 章例外，只观察 target。
- Agent 陪练旁边的 Agent 一次只给一个动作；卡住时按“定位文件 → 指出签名 → 伪代码 → 局部代码”逐级提示。
- 故障注入主动破坏一个边界，寻找首次偏差而不是盯最后一句输出。
- 可选迁移第一次学习不以独立写出 sibling case 为门槛；熟练后再减少提示、延迟重做。
为什么要让 Agent 同时看教材和 commit
只看讲解时，你知道“为什么”；只看最终代码时，你又会一下子看到太多变化。 教学 commit 把两者锁在同一个状态转换上：parent 是本章起点，commit 是本章终点， diff 就是这一步真实增加的复杂性。陪学 Agent 因而能基于你的当前位置提示，而不是 从最终答案倒着猜一条虚假的捷径。
npm run checkpoint -w @pi/course -- 05
npm run practice -w @pi/course -- 05 ../pi-practice-05
请阅读 target commit 与 parent 的 diff，但不要把答案展示或复制给我。
结合当前教材和练习目录里的 LEARNING.md 指导我：先问我对下一次测试
结果的预测，然后一次只给一个动作；我卡住时再逐级增加提示。`checkpoint` 负责定位状态转换；`practice` 才把它变成可动手的练习目录。 01～14 从 parent 开始，只带 target 的聚焦测试，因此学生不会意外看到实现。 `迁移练习` 保留为可选挑战：它适合在你已经完成一次引导重建后检验迁移， 不适合拿来判断第一次学习是否合格。
什么来自 D2L，什么是本书新增
D2L 明确采用 just-in-time、一个 working example 对应一个 notebook、 解释与代码交错、从零实现再切换到高层抽象的组织方式。本书迁移的是这种 “问题—概念—代码—结果”短距离，而不是复制 Notebook 或页面皮肤。
Pi 是多文件、事件驱动、涉及文件系统和进程生命周期的 Node 程序。 它的等价物不是“一节一个 notebook”，而是“一章一个可复现的系统增量”。 本书进一步加入 D2L 网站没有强制编排的预测、真实 commit、陪学提示阶梯、 延迟检索和混合故障诊断。
参考：D2L Preface、D2L build pipeline。本书正文和代码均为原创。
课程实现与上游 Pi 的关系
课程保留消息配对、流终态、事件顺序、追加式历史和扩展信任边界等关键不变量， 但会主动删掉不影响核心推理的产品复杂度。每章的 “Pi 源码对照” 会明确标记： 哪些行为相同、哪些是教学简化、哪些是课程主动强化。
- 课程的 deterministic eval、maxSteps 与 workspace guardrail 是教学增强。
- 当前上游 coding tools 没有内建 cwd jail 或权限确认。
- 当前产品主路径仍是 Agent、AgentSession 与 SessionManager；AgentHarness 是并存的演进方向。
- Compaction 生成 Context 投影，不删除 Session 历史。