Astra 全书初审：从源码资料集改成可学习的课程¶
审查对象：2026-10-04 修订前的 01–26 章、首页、README、实验 src/test/Python 与 mkdocs 导航。旧稿备份由主作者保留。本报告是本轮作者的初审与修改任务单，不是独立终审。源码基准：主分支 da00f7f5358f2949383b35c14f548bc20187d80c；实验 639ed015397290b3745d163aafe02ffee4aa3f84 / npm 0.2.0-rc.2。版本不迁移。
总判断：教学结构需要实质重写¶
旧稿已有较扎实的引用和大量难得的失败路径细节，不能以删短换取流畅。但它要求读者先消化 Cordis Proxy/Fiber、Session surface generation、Agent admission 等十多章机制，18 章才出现第一个具体业务能力。读者往往知道一个函数做什么，却不知道自己的哪项需求迫使它存在。18–20 章主要解释已写完的例子，缺少“我先运行什么、修改哪一项、现在观察到什么不同”的连续练习。
真正的主线应当是：用自己的笔记回答一个问题 → 看见三次实际 HTTP 请求如何积累证据 → 数据源从内存换成文件而工具不动 → 注册的工具仍能被政策拒绝 → 请求次数到限停止 → 保存运行证据并理解能冷读什么、哪个控制面能继续旧会话。每引入一个层次，都说明更简单方案以及什么时候值得支付这层成本。
逐章问题、源码核对与处置¶
| 原章 | 具体读者困境/原文依据 | 本轮处置与理由 |
|---|---|---|
| 01 | 01.3 首个命令是启动完整 Web；01.4 是章节与抽象问题表，不能立即观察一个 Agent 的输入输出 | 重写学习入口：先跑离线个人知识 Agent，再沿同一问题读机制；版本表保留 |
| 02 | 2.1 起手列六个内部服务，2.2 先定义 seam；“为什么不直接函数调用”到18.2才出现 | 用需求变化推导三角色、事件与效果；增加简单闭包/构造注入/插件树的成本比较 |
| 03 | 3.1 从 Context Proxy/root Fiber 初始化开始；3.10 直接要求做 provider 卸载/scope/isolate 多个实验 | 先做现有真实 Cordis provider 卸载测试，解释哪个工具为何消失，再进入逐函数参考；不将组件夹具当 launcher |
| 04 | 4.1–4.5 先展示 profile/preset/realm/HMR；4.6 仍是占位 research.patch.yml | 用实际生成的 notes.patch.json 与 dump 命令定位两个工具；保留全层级和 rc.2/main 差异 |
| 05 | 5.1 先讲 branded seq/offset，5.2 是13类事件表；读者没有可对照事件流 | 前置实际请求对应的逻辑事件表，区分读取笔记事实与最终回答；保留恢复/repair细节 |
| 06 | 6.1 抽象 seq 2/4/7 示例虽正确，但未接自己的知识证据；request/header 与 surface 的关系需跨章拼接 | 用第二次请求为何含搜索结果解释投影；给出日志/模型消息/wire三份数据的字段对应 |
| 07 | 连续讲 create/inbox/admission/scheduler，末尾才谈插入点 | 以 search→read→answer 三 step 推演；预算2时逐阶段解释为什么无第三 HTTP |
| 08 | 8.2 用不存在于实验的 summarize_record；8.13 大半是未实施清单 | 改用 read_note canonical结果，加入真正 composition 中可配置 deny gate，给 body未发生的独立证据 |
| 09 | 9.1 从四种类型开始，adapter和retry术语密集；没有可打开的实际 wire请求 | 保存三份实际 Messages请求，解释tool_use/tool_result关联与路由；保留compaction公式和协议细节 |
| 10 | 10.11 给能力清单，未从个人笔记读取需求推出是否需要shell | 比较快照笔记工具、任意文件工具、远端工作区三个产品变化，列出需要新增/替换的实际服务 |
| 11 | 11.1 示例调用 lookup_note，实验实际是 read_note；canonical string意味着程序需要JSON.parse | 统一实际工具名与输出契约；用多条笔记聚合解释PTC收益与进程/权限成本，标明扩展设计不是已跑PTC实验 |
| 12 | 12.1 MCP配置为占位server，12.11 建议接入却无需求驱动的选择过程 | 用笔记数据迁往团队服务推导native provider/MCP两方案，讨论部署/生命周期与失败结果；不伪造外部实验 |
| 13 | 开头列五种持续机制；读者未先遇到足以需要子Agent的工作 | 用“十份笔记核对/每日摘要/长期调研”区分机制，解释何时保持单Agent更简单 |
| 14 | 开头称“本课程的离线验证使用替身进程”，而20章/src/mock-server.ts已使用真实dsh加HTTPfixture | 修正事实；以前面跑过的SDK为入口，解释同runtime续问和冷恢复产品需求，不把私有fake-runtime当公共用法 |
| 15 | 全面说明载体/BFF，但“自己的产品”只有11节建议 | 从个人笔记问答页的读历史/继续/取消三个按钮推导控制面与状态；保留认证/附件/Desktop/ACP |
| 16 | 16.12 要求完整崩溃演练，而目前home在close后删除；读者无留存证据路径 | 提供保留home的真实SDK检查点，关闭后通过官方storage reader冷读，核对逻辑事件；不伪称SDK冷resume |
| 17 | 自动化/人机审批覆盖广，但计划模式、approval与业务完成缺少同一个具体动作 | 用“读笔记→拟定发布摘要→人工批准发布”分解三种授权/状态；明确本例仍只读，写工具是设计练习 |
| 18 | 只有局部abstract class，全文讲完整实现而未教如何从最小步长搭出 | 改为可执行递进实验讲义：从两工具到provider替换再到gate，逐文件说明输入输出与错误分支 |
| 19 | composition始终mkdtemp并删除，policy仅出现在组件测试；无法观察实际政策和长期存储 | 增加公开工厂选项与checkpoints命令；保留唯一dsh profile入口，扩展持久home和deny gate |
| 20 | 三请求时序正确但没有每次真实messages截面；测试总数被多处当作教学产出 | 新增逐请求trace产物、反例对照和可复做步骤；测试按行为证据说明，不靠数量证明质量 |
| 21 | 原比较全面但多为框架内部名词对照 | 增加同一个笔记Agent的三项变更决策与维护成本，避免靠大/小或性能猜测选型 |
| 22 | 22.1 把本次用户服务器授权写进长期教材 | 改为可复用发布/回滚与产物归属说明；不操作部署 |
| 23 | 700余行地图，读者可能误把清单完整当理解完整 | 在生成标记之外加入按需求追源码的工作示范；保留全清单但定位为查阅材料 |
| 24 | 排错图问assistant settlement但无法区分body前deny与body后block；练习多为未来工作 | 以新增checkpoint具体失败输出为索引，保留未测范围，避免泛化实验结果 |
| 25 | 25.3 “均通过”仅对应旧稿指纹，不能覆盖本轮重写 | 改成旧稿历史证据与本轮作者自查/独立复审分开记录，待主作者整合新终审 |
| 26 | 版本边界有价值，但main标签易被理解成实际分支，更新流程尚无具体变更示范 | 统一主分支快照称谓，拿tool-schedule迁移解释包/API/组合三级检查，保留冻结版本 |
已核对的关键源码与后续验证依据¶
- vendor/cordis/src/events.ts:176–238：parallel 等待allSettled、emit不等待、waterfall链决定必须返回next；不能用EventEmitter直觉解释政策。
- vendor/cordis/src/reflect.ts:273–333：provide拥有effect，撤provider先notify依赖再删除自身store；支持consumer随provider停用的教学实验。
- packages/core/agent-loop/src/agent.ts:597–703：header按变化/series记录，deriveMessages后冻结；三次请求不应硬说一定有三条request/header。
- packages/core/agent-loop/src/tool-calls.ts:51–177：tool/call先于prepare，post/commit按模型顺序；deny仍可有tool/call，不能以此认定body执行。
- packages/core/session/src/index.ts:716–775、856–887、1189–1206：内存append/derive/flush三阶段不同，读磁盘必须有自己的耐久屏障。
- examples/src/composition.ts、notes-tools.ts、mock-server.ts与全部三份test：真实SDK/CLI和SSE边界已具备，适合扩展为递进教材；原例未有组合级业务gate、可保留home或可检查请求产物。
本轮不变更 upstream/release、不运行付费模型、不改部署。作者验证与独立审查会另留记录，任何未实际跑过的扩展设计都不得写成实验通过。