学习仓库的质量检查与审阅

这一课解释“CI 还要不要加单元测试、lint 和 Agent review”这个问题。答案是：要加，但每一项都只负责一种可重复检查；它们一起降低教材和示例退化的概率，不能替代真实 DSH、真实模型、第三方安装或人工安全审计。

如果你还没有运行过最小示例，先完成最小插件示例与学习检查。本篇从它已经存在的 test、lint 和 A/B 快照检查出发，再说明 GitHub Actions 和 PR 审阅怎样把结果保存下来。

先看这张课程卡

项目	这一轮的答案
预计时间	阅读约 10 分钟；做一次最小修改和本地检查约 20 分钟
前置条件	阅读只需网页；运行命令需要完整 clone 或 Codespaces、Node 和 pnpm
你会产出	一份能说明“哪项检查支持哪项结论”的 PR 或学习记录
这一步不证明什么	CI 绿色不是完整 DSH 运行、真实模型质量、第三方安全审计或自动合并授权；要不要合并，最终判断仍由维护者负责

先记住这一条流水线

text

提交或 Pull Request
  -> 示例单元测试：已声明的行为还成立吗？
  -> 示例 lint：JavaScript 是否违反已选的静态规则？
  -> DSH 编译：源码和网页是否仍能编译、打包？
  -> DSH 单元测试：固定源码的可重复行为是否仍然通过？
  -> DSH lint：提交的 TypeScript/JavaScript 是否通过仓库静态规则？
  -> A/B 结构预检：两份快照是否只改变了可见工具集合？
  -> 学习材料路径与源码索引检查：入口是否指向固定提交，2973 个源文件是否仍有索引？
  -> 学习入口 smoke check：首页、START-HERE、示例和 Pages manifest 是否仍然接得上？
  -> 学习体验契约：关键入口是否同时写了动作、预期结果和证据边界？
  -> 首页状态数字门禁：首页上的教材页数、导读卡数和实验数是否仍与仓库实际一致？
  -> 索引质量审计：字段、测试关系和设计证据是否触发已知提示？
  -> 文档门禁与 Pages 构建：链接、双语记录、索引路由和站点能否生成？
  -> Agent 审阅契约：审阅指南、PR 模板和 Actions 是否仍然要求证据边界和风险说明？
  -> Agent 审阅清单：证据边界和风险说明有没有被漏掉？
  -> 维护者判断：是否合并，以及还需要哪一种真实运行证据？

这些命令是确定性检查：同一份输入应得到同一类通过或失败结果。Agent 审阅和维护者判断不是确定性测试；它们帮助发现遗漏、误称和难以机械判断的语义问题。

每一种检查到底证明什么

展开每一种检查到底证明什么（16 行）

检查	运行位置	通过时能支持的结论	通过时仍不能支持的结论
最小插件 `test`	示例目录或 GitHub Actions	预览限长、非文本块被忽略、观察器不改写测试夹具	真实 DSH 已加载 Bundle，或 Fiber 已完成卸载
最小插件 `lint`	示例目录或 GitHub Actions	提交的 JavaScript 符合该示例启用的 correctness/suspicious 规则，且能通过 Node 语法检查	所有 DSH 版本、所有平台或安全策略都兼容
根仓库 `pnpm run build`	GitHub Actions 或完整本地 checkout	官方固定源码的 TypeScript 库和 Web 构建入口能完成本次编译、打包	真实 DSH 已启动、provider 已响应、模型质量或插件已安装
根仓库 `pnpm test`	GitHub Actions 或本地完整 checkout	DSH 仓库当前 Vitest 单元测试通过	真实 provider、模型质量、第三方插件安装或所有操作系统行为
根仓库 `pnpm lint`	GitHub Actions 或本地完整 checkout	DSH 仓库当前静态规则通过	运行时安全、真实模型行为或跨版本兼容
A/B 比较器单元测试	仓库根目录或 GitHub Actions	比较器能接受合法差异，并拒绝改变固定条件或共同 schema 的输入	提交中的教学快照没有漂移，或 provider 性能存在差异
提交快照 A/B 比较	仓库根目录或 GitHub Actions	版本库中的两份教学快照确实满足 A/B 结构条件	provider token、缓存、延迟、成本、任务质量的真实差异
手写学习路径检查	仓库根目录或 GitHub Actions	README、入口课文和专题课文中的官方源码路径仍存在于固定提交	这些路径对应的实现仍然正确，或读者已经真正读懂了它们
源文件索引检查	仓库根目录或 GitHub Actions	固定提交中的 2,973 个纳入范围源文件都有索引条目，提交号和必填字段一致	自动条目已经替代逐行人工阅读，或设计理由对每个文件都完全准确
学习入口检查	仓库根目录或 GitHub Actions	首屏按钮、START-HERE 第一轮、最小示例课程和 Pages manifest 的关键映射仍存在	浏览器真实点击、页面视觉效果、读者是否理解或 DSH 是否运行
学习体验契约	仓库根目录或 GitHub Actions	关键入口同时保留“现在做什么”“应该看到什么”或“没有证明什么”等新手所需说明	读者一定理解了内容、页面一定适合所有设备或真实 DSH 已运行
索引质量审计	仓库根目录或 GitHub Actions	发现结构错误、字段自洽问题和设计理由模板复用提示，便于安排人工抽查	44 条模板提示自动变成错误，或 2,973 个文件已经人工逐行读完
`doc-sync` 与 Pages 构建	完整仓库 checkout 的 GitHub Actions	文档门禁、站点投影和 VitePress 构建在该提交可通过	页面已被人读懂、DSH 已运行或社区插件安全
`study:agent-review`	GitHub Actions 或本地完整 checkout	Agent 审阅指南、PR 模板和工作流之间的确定性接线没有漂移	Agent 已经审阅某个 PR、审阅意见正确，或自动批准合并
提交范围内的 `git diff --check`	GitHub Actions	给定提交比较范围内的差异没有 Git 能识别的空白错误	Markdown 结论准确，或测试覆盖充足
Agent 审阅	PR 描述、评论或人工工具	有人按证据、侵入性和未验证项的清单审阅过	模型输出一定正确、安全、无偏差，或可以自动批准合并

上面的浏览器把这张表变成可点选的：选一项检查，右侧给出运行位置、通过时能支持的结论和通过时仍不能支持的结论；「不能支持」一栏就是「CI 绿不等于 DSH 运行」的逐项落地。

因此，CI 不是“一个绿色勾就宣布完成”。它是一串带边界的证据；最后的文案必须把证据名称和结论范围一起写出来。

你现在可以照着运行的检查命令

先在仓库根目录运行最小、不会启动 DSH 的检查：

pnpm run build
pnpm test
pnpm lint
pnpm --dir study-examples/minimal-observer-plugin run demo
pnpm --dir study-examples/minimal-observer-plugin run test
pnpm --dir study-examples/minimal-observer-plugin run lint
node --test study-tools/*.test.mjs
node study-tools/compare-tool-visibility-ab.mjs study-tools/tool-visibility-ab.a.example.json study-tools/tool-visibility-ab.b.example.json
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
node study-tools/verify-study-links.mjs
node study-tools/verify-source-index.mjs
node study-tools/verify-study-entry.mjs
node study-tools/verify-study-learning-contract.mjs
node study-tools/verify-study-home-metrics.mjs
node study-tools/audit-source-index-quality.mjs
node study-tools/verify-built-study-site.mjs
node study-tools/verify-study-publication.mjs
pnpm run doc-sync

如果已经完成 Pages 构建，还可以用一条更短的发布产物复核入口：

pnpm run study:quick-check --site

它会逐页检查构建后的中文 HTML 外壳和站内学习链接；它不是浏览器点击测试，也不会启动 DSH、provider 或模型。

这些命令分别覆盖以下范围：

编译与测试：官方源码和网页编译、DSH 单元测试、DSH lint；
学习示例：demo/行为/静态规则；
工具可见性实验：A/B 比较器逻辑、提交中的 A/B 教学快照、离线快照处理成本；
教材完整性：手写课文的固定源码路径、逐文件索引结构、索引质量提示；
学习入口：第一次阅读入口的接线关系、关键入口的动作与证据边界；
发布：构建后学习页面的发布产物和整套中文教材页面及其站内链接。

pnpm run study:agent-review 额外检查审阅流程本身是否仍然接线；它不调用外部模型。最后的仓库级文档门禁会检查 Markdown、链接、翻译配对、Agent Note 格式、Pages 投影和文档构建；它不是“只编译一下网页”。

如果你不想先记住这一组命令，可以在仓库根目录运行一条维护者入口：

pnpm run study:quick-check --example

它默认检查学习入口、学习体验契约、首页状态数字、固定源码链接、离线 A/B 和 study-tools 单元测试；加上 --example 后再检查最小示例的 test 与 lint，加上 --deep 后再扫描逐文件索引。它是一个分层 smoke，不会替代本课后面的完整 doc-sync、Pages 构建或真实运行证据。

在 GitHub 网页、github.dev 或一个只为阅读准备的局部 checkout 中，不需要为了完成第一课而运行这些命令。需要运行时，使用完整 clone 或 Codespaces，并把每条命令的输出和环境写进学习记录。不要因为某个本地 checkout 缺少完整构建输入，就把环境问题改写成 DSH 行为错误。

这套仓库的 CI 会做什么

学习材料质量工作流会在 Pull Request 和 master 的相关改动上依次运行上面的检查，按组划分是：

源码与示例：DSH 编译、DSH 单元测试、DSH lint、示例 demo/测试/lint；
学习工具：study-tools 语法检查、A/B 逻辑测试、提交快照比较、离线快照基线；
教材门禁：手写学习路径、学习入口、学习体验契约、首页状态数字、源码索引检查、索引质量审计、Agent-review 契约；
网页与仓库：整套教材网页发布检查、doc-sync、按事件比较范围执行的 git diff --check。

它的范围仍然限定为本仓库可重复的编译、教材、学习示例和网页投影：不会假装替官方上游跑完整 DSH 发布流水线。

Pages 工作流只负责构建和部署学习网站。它与质量工作流分开，是为了让“能发布页面”和“示例与教材通过所选检查”有各自清楚的失败原因。仓库没有独立 Web 后端；页面发布链是 Markdown → website/docs.ts → VitePress → website/.dist → Pages。两个验证器随后分工：verify-built-study-site.mjs 检查首屏产物，verify-study-publication.mjs 检查整套教材页面和站内路线。

质量工作流在 doc-sync 成功后还会上传一个保留 7 天的 dsh-study-site-<commit> 工件，并在 Actions 的 job summary 中写明“这次检查证明了什么、没有证明什么”。这借鉴了文档项目把可审阅构建产物和机器检查结果放在同一次变更里的做法：维护者可以下载同一提交生成的网页检查视觉层，而不必把“构建成功”误读成“真实 DSH 已运行”。工件上传只发生在构建成功时；它不是截图、provider 记录或模型质量报告。

一个具体练习

打开最小观察插件的 patch，把 maxPreviewCharacters 从 160 改为 80。
在对应测试中把直接传给 apply(ctx, config) 的值和 x.repeat(160) 的预期从 160 改为 80。
运行最小插件的 test 和 lint。
在 PR 或学习记录中写：单元测试证明 80 字符预览；尚未证明真实 Profile 安装。
不要把上述句子改成“插件已经可以发布”或“DSH 全部验证”。

这个例子把每一层的职责分开：测试守住行为，lint 守住静态规则，文档门禁守住链接和页面，维护者再判断是否需要 Loader、卸载、provider 或安全证据。

Agent review 应该怎样加

本仓库把 Agent 审阅说明和PR 模板放在版本库里，并用 study:agent-review检查这些接线是否仍在。它们要求每个教材或示例改动回答同一组问题：结论来自固定源码、源码测试、文档构建还是实际运行？有没有把“已注册”或“当前 agent 可解析”误说成模型已经收到原生 schema？有没有让普通插件偷偷接触私有 registry、Loader、模块缓存、系统设置或进程注入？还没有证明什么？这个脚本只检查契约文本和工作流，不调用外部模型；真正的 Agent 意见仍然必须由维护者按固定范围复核。

这比直接装一个带 API key 的“自动 AI 审查 Action”更适合目前的学习仓库。自动审阅 Action 会带来四个新增决定：Pull Request 源码能否发给外部模型、fork PR 的 secret 如何隔离、费用和延迟由谁承担、模型意见是否会错误阻止合并。在这些决定没有明确之前，Agent 审阅只能是 advisory（辅助意见），不能是必过的安全认证或自动合并条件。

如果以后决定接入模型审阅，先在独立 PR 中写清数据范围、secret 策略、输出保留位置、失败降级方式和人类最终责任；再用无 secret 的测试 PR 验证它不会把凭据或未审核内容泄露出去。

一个合格的 PR 记录长什么样

提交者不必写长篇报告，只要能写清下面六项：

text

我改了什么：把最小观察器的文本预览上限从 160 改为 80。
源码或文档依据：示例自己的公开 tools/result 监听契约。
我运行了什么：最小插件 test、lint；A/B 单测和提交快照比较也已运行。
已证明什么：测试夹具中的文本预览最多为 80 字符。
未证明什么：真实 DSH Profile、真实模型 token、跨版本兼容和卸载。
侵入性检查：没有读取私有 registry、修改 Loader、改模块缓存、改系统设置或注入进程。

这份记录让审阅者能够复现已完成的部分，也不会把未完成的部分隐藏在“CI 已绿”里。

以后应该补什么

当前最值得补的是第二个和第三个示例：一个纯内存工具注册示例，以及一个对 agent 作用域调用 restrict() 的解析／模型呈现集合示例。它们应各自先有单元测试、lint、明确的 Loader/卸载缺口和对应课程；不要为了追求“例子多”而把真实模型、文件、网络、子进程和注入器塞进同一个 demo。

真正在得到隔离 Profile 和维护权限后，再补 Loader 组合测试、卸载检查、脱敏观测快照和固定模型 A/B。完整优先级见后续研究路线。

完成标准

[ ] 我能说出 build、test、lint、A/B 结构预检和 Pages 构建分别检查什么。
[ ] 我知道“课文路径仍存在”和“索引条目存在”只是结构检查，不等于源码语义已经人工确认。
[ ] 我知道 Actions 绿色和真实 DSH 运行是不同证据。
[ ] 我知道 Agent 审阅是辅助意见，不是自动安全认证或合并授权。
[ ] 我能在一次小改动后同时写出“已证明”和“未证明”。
[ ] 我知道下一个示例应该先补测试和卸载证据，再加功能。

完成后回到最小插件示例与学习检查做一次小改动，或者打开社区生态与扩展边界判断一个真实社区项目需要哪一层证据。

学习仓库的质量检查与审阅 ​

先看这张课程卡 ​

先记住这一条流水线 ​

每一种检查到底证明什么 ​

你现在可以照着运行的检查命令 ​

这套仓库的 CI 会做什么 ​

一个具体练习 ​

Agent review 应该怎样加 ​

一个合格的 PR 记录长什么样 ​

以后应该补什么 ​

完成标准 ​