高风险索引人工抽查
逐文件索引保证 2,973 个纳入范围的源文件都有入口，但“有入口”不等于“每个文件都已经人工精读”。这篇记录一次针对工具、提示词、启动装配和 Hook 协议的人工抽查，给读者一个复核自动卡片的方法。
抽查范围和证据等级
- 固定上游提交：
aa6c361a972c8369148dea7380bb5c21c24e07ec。 - 抽查对象：
packages/core/tools/src/index.ts、packages/core/tools/src/schema.ts、packages/core/system-prompt/src/index.ts、apps/cli/src/profile-boot.ts、packages/hooks/hook-protocol/src/codec.ts。 - 读取顺序：先看
study/文件索引/中的卡片，再打开固定提交源码，最后看同目录 README 和测试入口。 - 本篇记录的是静态源码和测试线索。没有把本地文档构建、网页部署或一次成功编译写成 DSH 运行时证明。
本轮的追加检查在学习仓库工作树上进行（工作树包含本地新增代码，不完全等于固定上游提交）：包括 packages/core/tools/src/types.ts、packages/interaction/user-approval/src/index.ts，并回看了 packages/core/tools/src/index.ts 中的 schemas()、resolveExecution() 和 packages/core/system-prompt/src/index.ts 中的 assemble()；其中顺带回看的 debugSnapshot() 是本学习仓库在 ToolRuntime 上新增的只读调试接口，不在固定提交 aa6c361a 里——这一证据边界由第 23 课登记，本篇初稿曾把它误写成"在同一固定提交上确认到的事实"，已更正。追加检查仍然是静态源码复核，不是启动 Profile、连接 provider 或执行外部工具。
抽查结果
| 文件 | 源码中确认到的事实 | 索引解释是否需要修正 | 仍然需要什么证据 |
|---|---|---|---|
packages/core/tools/src/index.ts | 统一暴露工具注册、模型呈现模式、schema 提供和执行流水线；声明了 tools/pre-execute、tools/execute、tools/post-execute、tools/code-dispatch-log、tools/result、tools/change 等事件 | 当前“模块入口”判断方向正确，但不能只把它写成普通 barrel；它还承载注册、呈现和完整执行边界 | 真实运行时的注册集合、可见集合和执行事件快照；没有证明所有注册工具都自动进请求 |
packages/core/tools/src/schema.ts | 提供统一 JSON 值 schema、编译、类型推断和工具参数校验；defineTool把 schema、执行、输出和可选呈现能力组合起来 | 当前卡片可以作为入口，但读者要补问“参数校验”和“执行权限”是不是同一件事；答案是否定的 | 目标 Profile 中实际加载了哪些工具，以及真实调用时的策略、审批和沙箱结果 |
packages/core/system-prompt/src/index.ts | 工具 provider 返回模型可见 schemas 和限制前 knownNames；toolOrder 负责确定顺序；assemble() 按调用上下文组装提示词和工具 | “提示词组装”判断正确；工具 schema 是组装的一部分，但不应把静态代码写成 provider token 或 KV cache 实测 | 固定模型和 provider 的 input token、缓存 token、首 token 延迟与质量数据 |
apps/cli/src/profile-boot.ts | 按 Bundle、Profile patch、home patch、--patch overlay 组合树；存在 agent-presets 时还会条件性注入 shipped preset 的 system overlay，随后追加 telemetry patch；启动后监视用户 patch，并通过 shutdown/dispose 清理 | 当前卡片的 patch／Profile 边界基本正确，但不能把用户可配置层级当成完整的实际 overlay 清单；它是判断“组合层扩展”和“源码 patch”区别的高风险入口 | 在隔离 Profile 中实际启动、修改 patch、重载和退出的日志；不能仅凭函数存在声称 HMR 在每个平台都可用 |
packages/hooks/hook-protocol/src/codec.ts | exit 0 可解析结构化 JSON 或保留普通 stdout；exit 2 表示阻断并取 stderr；其他非零退出是非阻断错误；只有调用者传入 expectedEventName 时，事件名缺失或不匹配才会丢弃事件专属字段 | 当前卡片具体且准确；但协议 codec 只负责解码，哪些字段适用于 Claude 或 Codex 由 bridge 决定；省略 expectedEventName 会关闭这项校验 | 具体 bridge 的命令、超时、权限、安装和卸载证据；codec 通过测试不等于外部 Hook 已安装 |
packages/core/tools/src/types.ts | 定义 native、code、both 三种呈现方式；事件数据记录 Code Mode 子调用的开始与结束。调试快照类型（保存作用域、名称、隐藏原因、可见 schema 名称和 UTF-8 字节数）是学习仓库工作树的本地新增，不在固定提交内 | "类型契约"方向正确，但不能把快照字段当成权限清单；字节数也不是 provider 的真实 token 数 | 真实宿主导出的快照、provider 请求字段和执行策略结果；类型定义本身不证明字段已经被生产入口使用 |
packages/interaction/user-approval/src/index.ts | 审批服务支持 ask 和 never 两种会话策略；审批提问与决定会写入 Session 日志；没有可用回答者时走 unavailable，而不是默认放行 | “模块入口”太笼统；它还规定了审批的失败方向和可回放状态，不能写成“有一个权限按钮” | 具体宿主是否装配回答者、用户界面怎样显示、真实工具调用是否走到审批，以及不同 Profile 的默认策略 |
本次抽查没有发现必须改写上述自动卡片的源码事实。需要改进的是阅读提醒：index.ts不能只理解成导出文件，system-prompt不能只理解成字符串拼接，profile-boot.ts不能只理解成“读取配置”，Hook codec 也不能替 bridge 背书。
追加抽查还把两个容易被模板掩盖的边界确认清楚了：packages/core/tools/src/types.ts 是"可观察事实的形状"，不是授权实现；packages/interaction/user-approval/src/index.ts 是"审批和审计的状态边界"，不是任何插件都自动获得的权限。学习仓库本地新增的 debugSnapshot() 只读出名称和序列化大小，packages/core/system-prompt/src/index.ts 的 assemble() 才把可见 schema、作用域、顺序和上下文组合成一次本地输入；两者都不能单独证明模型已经收到请求或任务质量已经改善。
上面的浏览器把抽查结果表变成可点选的：选一个文件，右侧给出三栏原文——源码中确认到的事实、索引解释是否需要修正、仍然需要什么证据；这正是复核一张自动卡片时应当填写的三栏。
六篇入口课文的人工抽查
为了检查“渐进式路线”有没有把概念说过头，再对首页直接引导的六篇课文做了一轮人工复读，并回看它们引用的固定源码或本地实验入口。这里检查的是课文中的高风险结论，不是声称已经逐行审阅 2,973 个索引文件。
| 课文 | 本轮确认 | 仍然保留的边界 |
|---|---|---|
00-开始这里 | 六个基础词和“注册不等于模型可见”的提醒与后续课程接得上 | 这是心智模型，不是每个 Profile 的运行清单 |
10-社区生态与扩展边界 | 普通插件、Bundle、Hook bridge、patched fork、运行时注入器分层明确；社区项目都以自述或静态观察命名 | GitHub topic、README 和固定源码都不等于官方背书、安全或兼容性证明 |
22-工具可见性与非侵入扩展 | 把已注册、agent 可解析、模型呈现和执行允许拆开，并把 restrict() 限定在作用域/API 语义内 | 可见集合变化不自动等于文件、网络、子进程或凭据权限收紧 |
23-工具可见集合观测与性能实验 | A/B 固定条件、schema 字节数、本地宿主记录和 provider 性能边界已分开 | 当前实测没有 provider、模型、token、首 token 或任务质量证据 |
25-从首页到第一次产出的动手任务单 | 网页阅读、固定源码链接和四行学习记录的完成条件清楚；Codespaces 是可选路线 | 完成任务单不等于启动 DSH、安装插件或读完全部源码 |
27-工具预算与插件责任决策卡 | “先减 Bundle，再限作用域，再看呈现，最后考虑源码修改”的责任顺序与 22、23、10 互相一致 | 这是一张决策卡，不是官方 Profile 名单或安全策略承诺 |
本轮没有发现需要改写上述六篇核心结论的事实错误。后续若修改上游固定提交、真实 Profile 或社区项目版本，必须重新做同样的抽查；当前的 44 条设计理由模板复用提示仍然只是人工抽查线索。
逐个文件怎样继续读
1. 工具入口：先看三条不同的线
打开 packages/core/tools/src/index.ts 时，用三种颜色做标记：
- 模型线：
schemas()、presentAs()、restrict()以及送往 system prompt 的 provider。 - 执行线：注册、查找、参数校验、
pre-execute、guard、execute、post-execute和结果物化。 - 观察线：
tools/change、tools/result和 code dispatch 日志。
三条线在一个包里，并不意味着“模型看到的工具”与“能被宿主执行的工具”是同一集合。把它们拆开后，前一篇的四个观测时点就能落到源码位置。
2. schema 文件：先问输入，再问权限
packages/core/tools/src/schema.ts值得先看 defineTool 的输入和输出，再看参数如何编译与验证。一个 schema 可以告诉模型应该怎样生成参数，也可以让运行时拒绝不符合形状的参数；它不会单独决定文件、网络、进程或凭据权限。
读到 execute时，继续追 ToolRunContext、取消信号、输出 schema 和 tools/pre-execute。如果只看 schema 就声称“这个工具安全”，证据链是不完整的。
3. system prompt：分清顺序、可见性和缓存推论
packages/core/system-prompt/src/index.ts至少要分三次读：
- 第一次看 provider 如何贡献
schemas和knownNames。 - 第二次看
toolOrder如何规范工具顺序，以及错误何时暴露。 - 第三次看
assemble()如何把作用域、sections、tools 和 variables 组合成一次请求的输入。
源码和 README 可以支持“可见 schema 会进入组装”“顺序变化可能改变前缀形状”这类设计解释；它们不能替你得到某个 provider 的实际 tokenizer 结果或缓存命中率。
4. profile boot：把配置组合和源码修改分开
apps/cli/src/profile-boot.ts是理解“我没有 patch 源码，为什么也能加入功能”的关键文件。它把 Bundle 和多层 patch 组合到空 root 上，再交给 Loader 启动；当 agent-presets 已经存在时，启动器还会把随 CLI 分发的 preset 根目录作为 system overlay 加入组合，并在后面追加 telemetry patch。只要你的功能停留在公开 Bundle、Profile、服务和事件边界，身份更接近组合层扩展；如果你改了这个启动器或私有 Loader 状态，就需要按 patched fork 或发行版维护来声明。
启动器还负责监听用户 patch 和处理退出。研究 HMR 时，必须记录“修改了哪个文件、触发了什么重载、旧服务是否 dispose、进程如何退出”，不能只截一张“页面仍然打开”的图。
5. Hook codec：协议成功不等于集成成功
packages/hooks/hook-protocol/src/codec.ts只把子进程退出码、stdout、stderr 和结构化字段解码成中立结果。调用者传入 expectedEventName 时，codec 才会把缺失或不匹配的事件名当作不适用并丢弃事件专属字段；省略该参数则不启用这项事件名校验。它不替 Claude 或 Codex 决定安装位置、匹配哪些事件、是否允许写文件，也不负责为所有 bridge 证明兼容性。
下一跳应该是具体 bridge 的 README、配置、实现和测试。审计社区项目时，必须把“它复用了官方协议类型”和“它真的能被目标宿主加载”写成两条不同证据。
这次抽查证明了什么
本次抽查可以支持四个结论：
- 逐文件索引中的“模块入口”“提示词组装”“Profile 启动”“协议 codec”这些角色标签有源码依据。
- 工具可见性需要同时阅读
tools和system-prompt，不能只看某一个注册调用。 - Plugin、Bundle、Profile patch、Hook bridge、源码 fork 和注入器必须按修改边界分别命名。
- 自动索引适合定位和建立下一跳，人工精读负责发现角色模板不适用、权限边界不清和测试证据不足。
它不能证明：全量源码已经被人逐行读完、所有社区插件都安全、所有 Profile 都能在 Windows 上启动，或“限制工具数量一定提升模型质量”。
以后抽查哪些文件最值得
下一批优先选择会改变“模型看见什么、宿主执行什么、用户如何扩展”的文件：
- system prompt 的具体 section provider 和动态 context provider；
packages/core/tools/tests中覆盖 restrict、呈现、取消和错误的测试；apps/cli的 Profile 解析、Loader 启动和退出路径；- hooks bridge 的配置与进程启动器；
- MCP、shell、filesystem、sandbox 工具的权限与失败路径；
- 社区项目的安装脚本、manifest、模块替换和卸载流程。
抽查顺序不要按文件大小排序，而要按“一个错误解释会影响多少下游判断”排序。尤其是会影响工具可见集合、权限和扩展边界的入口，应该先于普通 UI 组件。
读者自己的抽查记录模板
文件：
固定 commit：aa6c361a972c8369148dea7380bb5c21c24e07ec
索引卡片说了什么：
源码实际确认了什么：
同目录 README 或测试：
这个文件影响模型可见性、执行权限还是装配生命周期：
哪些是源码事实：
哪些是静态设计推论：
哪些仍需运行时验证：
下一跳文件：如果你不能填出“仍需运行时验证”，通常说明这次阅读把静态代码和运行结果混在一起了；如果你不能填出“下一跳文件”，说明只看到了文件名，还没有形成调用或协作关系。