Pi 课程 Astra 初审（2026-10-04）¶
结论：需要教学结构重修。旧稿已经覆盖较多真实 1.0 边界，不能因为用户评价一般就删除这些有用内容；但“说对一个机制”和“读者能独立造出应用”之间有明显断层。本报告是本轮作者的初审，不是独立最终验收。
范围：通读 README、导航、01–20 原章节与 index、全部 examples/src 和四个测试文件；完整单文件是这些原稿的生成副本，不另算独立教材。研究基线固定 a13d35a742c6ef8462812a28fbe1d8c8b7431c32。重新读 Agent 与 loop 主链、transcript、SDK 工厂与 AgentSession 投影/持久化路径，外围按各章命题回查具体实现。未宣称整个 monorepo 逐行审计。旧版备份由主代理保存，旧复审报告保持原样。
影响学习的具体问题¶
- 贯穿任务中途换题。 13.1 是“SDK 如何恢复”的内存笔记助手，14.1 直接换成读整个源码仓库的 SDK CLI，15.3 又换成生成设计说明的目标记录。读者看不到同一个需求从两工具到持久化、再到验收的演化，容易把三个 SDK 配方当作三个独立玩具。
- 三轮实验对证据的断言不足。
examples/src/offline.ts第二/三轮仅检查最后 toolResult 存在且非 error，随后仍硬编码 read id 和最终结论。即使搜索返回空、读取另一个笔记，也可能打印同样答案。agent-loop.ts的createToolResultMessage正确回传内容不等于应用确实使用了内容。应让 fixture 消费实际返回值，加入错误来源负例。 - “带出处”尚无可验收产品对象。 13.9 将 source/日期/定位放在未来练习，15.4 只说“宿主验收 artifact”，当前示例没有 artifact 或验收函数。读者无法区别 Agent idle、模型说完成、引用确实来自本次读取三件事。应实现独立的证据收据和可检查答案，明确文本引用匹配仍不证明推理蕴含。
- 源码章按函数目录展开而少数据轨迹。 05.7 列十个步骤、05.11 正确讲并行，但没有把同一个
toolCallId从 assistant 到 execute、结果、下一请求贯穿；04.5 的箭头图也没有展示各阶段对象实际变了什么。应给七条 transcript、三次 provider 输入、消息/entry/call 三种 ID 对照，读者能预测后再运行。 - 设计解释经常只有优点，没有选择成本。 02.3 “分层组合”、07.5 “投影”、09.1 “减少中间数据”没有让读者决定何时值得承担复杂度。应比较直接函数、固定流水线、Agent 循环；比较全量日志、slice 与树投影；给 Code Mode 引入前后的可观测性代价。
- SDK 离线恢复藏在测试文件中。 14.5 的“换成 SessionManager.open(file)”未给可执行命令；
sdk-agent.ts每次 create，新手无法照章观察重开。应提供真实磁盘→dispose→open→新 SDK 实例→provider 检查的完整离线 checkpoint。 - 练习缺少反馈机制。 03.6、07.10、16.4 多是“试一下、观察、解释”，没有输入、预期差异、错误输出与回溯入口。应分成先预测、运行、只改一个变量、定位失败、迁移五步，保留开放设计题。
- 完成感被交付报告挤占。 18.7/20.5 的旧版 PASS 证明当时验收范围，不证明本轮教学质量。新修订必须注明历史验收时间，不能复用旧 21 项/网站部署结果作为新内容验收。
每章初审与处置决定¶
| 原章 | 读者实际卡点（原节） | 本轮处置 |
|---|---|---|
| index | 路线表多，缺统一产品输入输出 | 改成证据助手成品与阶段路线，链接每个 checkpoint |
| 01 | 1.3 按主题/工时排进度，缺阶段交付 | 保留版本表，增加能力前提与具体可运行交付 |
| 02 | 2.1–2.9 正确但类似架构说明 | 增加反事实、成本和选择理由，用同一问题解释分层 |
| 03 | 3.6 真实模型练习门槛高 | 增离线起步、命令预期、首次出错定位；保留 CLI 覆盖 |
| 04 | 4.3–4.5 字段分类未落实到 payload | 给具体消息实例与三次请求差量；拆清工具实现/声明/结果 |
| 05 | 5.7 函数步骤列表认知负荷大 | 增主线导读、按 call ID 跟踪、错误修复与停止反事实 |
| 06 | 6.7 提到测试但不能独立复现 | 增 SDK 请求生命周期的对象/持久化时点表与恢复实验 |
| 07 | 7.7 很细但没先说明应用的丢失问题 | 增单一知识问题下的树/摘要选择、可运行投影实验 |
| 08 | 8.1 工具契约没有完成对象 | 新证据工具设计，区分 schema、对象存在、读过、版本、引用和含义 |
| 09 | 9.7 用占位 MCP，易以为所有东西可直接跑 | 保留真实边界，新增现有 QuickJS 离线实验入口及组合成本判断 |
| 10 | 10.3 只有 UI 状态建议 | 给 started/handled/settled 与宿主验收不同状态的具体时序 |
| 11 | 11.2 邮件场景与课程项目断开 | 用发布研究报告的两个崩溃窗口推导幂等选择，保留实验成熟度 |
| 12 | 12.8 是检查单，不告诉检查是否真运行 | 给 package 单独运行、模板/skill/代码分工与负例 |
| 13 | 两工具完成后缺可验收答案 | 实质重写为逐阶段证据助手：追踪→引用验收→错误修复→预算 |
| 14 | 仅付费真实入口、恢复只一行建议 | 实质改写为同一工具迁移 SDK 的离线磁盘恢复，再接真实仓库 |
| 15 | 目标模型与评测只有建议 | 增真实 artifact 验收矩阵、故障分类、模型质量评测记录模板 |
| 16 | 八题无运行反馈 | 改成带命令/预期/定位的故障诊室与不附答案的迁移任务 |
| 17 | 文件数量与逐行原文容易被读为学习深度 | 增“命题→调用者→实现→消费者→反例”的阅读任务；原覆盖边界保留 |
| 18 | 旧 PASS 易误读为当前版 | 保留历史记录，加本轮验收范围与独立审查待完成标记 |
| 19 | 维护说明与 Agent 部署混淆风险 | 保留部署事实，补生成源/产物与实验 artifact 区分，不执行部署 |
| 20 | 原独立复审只针对旧稿 | 明确历史审查有效范围，为新初审/修稿/后续独立审查留证据链 |
本轮验收标准¶
读者应能不用真实模型：打印实际三轮请求；故意提交未读或错误引用看到拒绝；在错误结果后修正并拿到 artifact；用新 SDK 实例读取磁盘恢复；解释分支投影为何排除旧路线。测试必须调用实际课程代码与 Pi，不复制一份循环再测试复制品。真实模型的选择、语言质量、摘要质量、远程 MCP OAuth 和 Durable 断电恢复另列未测，不用 fixture 替代。