学习工具箱：不启动 DSH 也能做的检查
这一页把仓库里的学习脚本集中成一条可以复制的路线。它们检查的是文档、快照、索引和静态发布产物，不会启动真实 DSH、provider、模型或第三方插件。
如果你第一次来，先完成15 分钟动手任务单；如果你已经知道要检查什么，就按下面的表格直接选一条。
懒人入口：先复制一条命令
已经在 Codespaces 或完整仓库根目录打开终端时，先运行：
pnpm run study:quick-check它会依次做七项不启动 DSH 的检查：学习工具单元测试、第一次阅读入口、学习体验契约、首页状态数字、Agent 审阅契约、固定提交源码链接和离线 A/B 快照。首页上的“学习工具测试”数字会随着 study-tools/*.test.mjs 增删自动由门禁重新计算（写作本课时是 190），不是 DSH 运行时指标。
想把已经构建好的 Pages 也逐页检查（包括中文语言、viewport、VitePress 正文容器、阅读样式、H1 和学习页之间的站内链接）：
pnpm run study:quick-check --site--site 不会启动浏览器或 DSH；它读取 website/.dist，所以必须先有一次 Pages 构建。它能证明发布产物的静态外壳完整，不能证明浏览器、屏幕阅读器或人工阅读体验已经被逐页审计。
想把最小示例的单元测试和 lint 也一起跑：
pnpm run study:quick-check --example想把 2,973 个逐文件索引也纳入同一条命令：
pnpm run study:quick-check --deep两个选项可以叠加成 pnpm run study:quick-check --example --deep：第一次不被完整索引和构建拖住，需要证据时再扩大范围。
宿主库已经构建好、想观察真实本地 ToolRuntime 时，再加 --runtime：
pnpm run study:quick-check --example --runtime它只挂载当前工作树的 ToolRuntime，比较全量视图和 agent 作用域 restrict() 后的 schema／提示词组装，不调用 provider、不启动模型。需要查看完整 JSON 报告时运行：
pnpm run build:lib:host
pnpm run study:runtime-benchmark -- --iterations 200 --warmup 25先看这张工具卡
展开先看这张工具卡（11 行）
| 你想做什么 | 从哪里开始 | 需要什么 | 完成后能说什么 |
|---|---|---|---|
| 看懂一份工具快照 | inspect-tool-visibility.mjs | Node，不需要 API key | 这份 JSON 里记录了哪些注册、可见和隐藏集合 |
| 判断 A/B 快照是否公平 | compare-tool-visibility-ab.mjs | Node，不需要 API key | 两组快照是否保持注册集合和共同 schema 的可比性 |
| 测本地 JSON 处理成本 | benchmark-tool-visibility-ab.mjs | Node，不需要 API key | 本机解析、序列化和字节计算的相对结果 |
| 测真实宿主准备阶段 | benchmark-tool-runtime-ab.mjs | 先构建 host library；不需要 API key | ToolRuntime、schemas()、SystemPrompt.assemble() 的本地 A/B 观测（接口为本仓库新增，见「工具三点五」） |
| 检查学习入口 | verify-study-entry.mjs | Node，不需要构建 | 首页、START-HERE、示例和 Pages manifest 是否接上 |
| 检查学习体验契约 | verify-study-learning-contract.mjs | Node，不需要构建 | 关键入口是否同时写了动作、预期或证据边界 |
| 检查首页状态数字 | verify-study-home-metrics.mjs | Node，不需要构建 | 首页显示的学习页、索引、测试和结构错误数量是否与当前仓库一致 |
| 检查逐文件索引 | verify-source-index.mjs | Node，不需要运行 DSH | 索引是否覆盖清单、结构是否正确、固定提交是否一致 |
| 检查手写源码链接 | verify-study-links.mjs | Node，不需要运行 DSH | 教材里的官方路径是否仍指向固定提交中的文件 |
| 检查已构建 Pages 入口 | verify-built-study-site.mjs | 先构建 Pages | 首页、学习入口和首屏阅读资产是否存在 |
| 检查最终网页 | verify-study-publication.mjs | 先构建 Pages | 每个学习源页是否有投影页面、中文 HTML 外壳、正文容器、阅读样式、H1 和可解析的站内学习链接 |
工具箱里的“通过”只支持对应一行的结论。它不支持“插件已经安装”“模型已经收到这些 schema”“工具一定让模型变快”或“社区项目安全”。
你现在只做三步
第一步：从仓库根目录打开终端
下面的命令都假设当前目录是 deepseek-harness-study 的仓库根目录；如果你使用 Codespaces，先在左侧文件树打开这个仓库，再打开终端。
deepseek-harness-study/
├── study-tools/
├── study-examples/
├── study/
└── package.json只想阅读时不要创建 Codespace；GitHub 网页和 Pages 已经足够完成课程阅读。
第二步：先运行不会启动 DSH 的最小检查
node study-tools/verify-study-entry.mjs
node study-tools/verify-study-home-metrics.mjs
node study-tools/inspect-tool-visibility.mjs study-tools/tool-visibility-snapshot.example.json
node --test study-tools/*.test.mjs你应该看到学习入口通过、快照被解析，以及学习工具测试通过；每项“通过”支持什么结论，以本页开头的声明和工具卡最后一列为准。
第三步：选择一条深入路线
- 想研究工具数量：运行 A/B 比较器和离线基准，再读工具可见集合观测与性能实验。
- 想检查教材完整性：运行索引、手写链接和发布检查，再读学习仓库的质量检查与审阅。
- 想修改一个真实学习示例：先读最小插件示例与学习检查，不要把工具箱脚本当成 DSH 插件。
工具一：读一份工具可见性快照
node study-tools/inspect-tool-visibility.mjs study-tools/tool-visibility-snapshot.example.json它会把快照中的注册集合、可见集合、限制集合和 schema 字节数整理出来，适合第一次认识“已注册”和“当前可见”不是同一层。三层怎样逐道收窄、每个工具被哪一层挡住，工具可见性实验可以亲手勾一遍。
它没有连接 ToolRuntime，也没有访问 provider；示例 JSON 是教学夹具。要把真实宿主输出接进来，仍需要宿主维护者提供脱敏的 debugSnapshot() 导出和版本信息。
工具二：比较两组 A/B 快照
node study-tools/compare-tool-visibility-ab.mjs study-tools/tool-visibility-ab.a.example.json study-tools/tool-visibility-ab.b.example.json先看输出里的变量和集合差异，再确认 A/B 只改变了可见性，而没有顺便改工具名称、共同 schema、执行实现或权限策略。A/B 支持的是结构差异结论；“B 组一定更快、更便宜或更聪明”需要真实模型条件。
工具三：运行离线基准
node study-tools/benchmark-tool-visibility-ab.mjs study-tools/tool-visibility-ab.a.example.json study-tools/tool-visibility-ab.b.example.json --iterations 1000 --warmup 100基准测的是 JSON 解析、可见集合比较、序列化、UTF-8 字节数和一个粗略的 bytes / 4 提示。bytes / 4 不是 tokenizer，也不是 provider 的 input token 字段。
拿到真实模型条件后，仍要固定模型、provider、任务、上下文、工具实现和时间窗口，并记录 provider token、缓存 token、首 token 延迟、总延迟、失败率、质量和成本。
工具三点五：运行真实宿主的离线 A/B
这项检查需要先构建 packages/core/tools 等 host package；构建产物会写入各 package 自己的输出目录：
pnpm run build:lib:host
pnpm run study:runtime-benchmark -- --iterations 200 --warmup 25报告会明确打印 providerCalls: 0、modelCalls: 0 和 dshProcessStarted: false——这三行就是本项检查的边界凭据：它测的是本地宿主在两个可见集合下如何生成快照、schema 和 prompt assembly；Profile 启动、文件／网络权限和 provider 延迟不在其内。还有一个前提要记住：debugSnapshot() 是本学习仓库在 ToolRuntime 上新增的只读观测接口，不在固定上游提交里（证据边界由第 23 课登记），所以这组数字描述的是本工作树构建出的宿主，不是固定提交的公共 API。
第一次运行时，你可以把输出和工具可见集合观测与性能实验里的实测记录对照。当前最新记录使用 Node v24.15.0、Windows win32、x64，两组都注册 24 个工具；A 组可见 24 个，B 组通过同一个 agent 作用域的 restrict({ allow }) 可见 3 个。
| 指标（200 次测量，预热 25 次） | A 组 | B 组 |
|---|---|---|
| 可见 schema UTF-8 字节 | 4,524 | 533 |
toolWireUtf8Bytes | 4,549 | 537 |
debugSnapshot() 平均 | 309,234 ns | 160,564 ns |
schemas() 平均 | 338,379.5 ns | 96,022 ns |
SystemPrompt.assemble() 平均 | 158,517.5 ns | 89,516.5 ns |
读这组数字只记住两点：它是同一台 Windows 机器上的本地相对基线，会随机器、JIT 和负载变化，不是性能承诺；可见集合与本地组装规模的变化是真的，但 token 数量、首 token 延迟、回答质量和工具执行仍属后续实验条件。
工具四：检查教材入口和最终网页
先检查源文件和 manifest：
node study-tools/verify-study-entry.mjs如果你已经运行过 Pages 构建，再检查首屏和整套发布产物：
node study-tools/verify-built-study-site.mjs
node study-tools/verify-study-publication.mjs这两项会检查页面文件、稳定文案、中文 HTML 外壳、阅读样式、H1 和站内学习链接。它们不是浏览器点击测试；本机浏览器或 GitHub Pages 真实访问仍要单独抽查。
工具五：检查索引和手写源码路径
node study-tools/verify-source-index.mjs
node study-tools/audit-source-index-quality.mjs
node study-tools/verify-study-links.mjsverify-source-index.mjs 关注覆盖和结构，audit-source-index-quality.mjs 输出设计理由复用等质量信号，verify-study-links.mjs 关注手写学习材料引用的固定官方路径。
质量审计里的统计或提示是选取人工抽查对象的线索，不是 DSH 运行时错误。当前 44 条设计理由模板复用统计不能被改写成“44 个文件有 bug”。
一份合格的学习记录
每次运行后只写四行就够了：
我运行的命令：
命令输出支持的结论：
这次没有证明的事情：
下一步要回到哪一篇源码或课程：例如：
我运行的命令：node study-tools/compare-tool-visibility-ab.mjs study-tools/tool-visibility-ab.a.example.json study-tools/tool-visibility-ab.b.example.json
命令输出支持的结论：B 组的离线快照可见集合比 A 组少，注册集合和共同 schema 保持可比较。
这次没有证明的事情：没有 provider token、首 token 延迟、模型质量或真实 ToolRuntime 运行记录。
下一步要回到哪一篇源码或课程：23-工具可见集合观测与性能实验.md。这种写法比“实验成功”更有用，因为别人知道成功的对象、证据范围和下一步复核位置。
清理和停止条件
- 这些命令只读仓库文件，通常不会创建需要保留的运行数据。
- Pages 构建产生的
website/.dist和其它临时缓存是构建产物；研究结束后可以按仓库的安全清理规则删除，不要删除源 Markdown、索引清单或用户已有改动。 - 真实 DSH、provider、API key、Profile、Loader、第三方插件和注入器不属于这页的默认练习范围。
- 如果一个实验需要读取私有 registry、模块缓存、进程或 Windows 注册表，先停下来把它标成宿主修改、patched fork 或注入器研究，不要继续用普通插件的证据表述。
完成后回到后续研究路线，把离线快照、真实宿主观测、模型 A/B、插件安装卸载和网页视觉检查分别排队。