DSH VERTICAL KIT · CORPUS STATUS
每条规则的语料状况
这里的 22 个检查,判定规则是不是「验证过」,取决于它在多少份真实文档上跑过。自己造的 fixture 只能证明"我想到的情况它判对了",证明不了"别人写的东西它不会误报"——因为在我编的 fixture 里,「正确」和「被检查器接受」是同一件事。
分三层:跑过陌生人写的文件、跑过自家真实产物、只有自造样例。
第一层:跑过别人写的文件(5 个检查)
| 检查 | 语料 | 份数 | 第一次跑出的问题 |
|---|---|---|---|
| onboarding-check | 其他插件仓库的 README | 39 | 不认识 dsh plugin add(生态里 216 个文件用它);把所有代码块都遮蔽,连作者写在 shell 注释里的成功提示也遮蔽了 |
| license-check | 其他插件仓库的 LICENSE | 21 | 把 Apache-2.0 定义段的 "the copyright owner" 当成版权声明行,4 份正确文件被报错 |
| release-notes-check | 其他插件仓库的 CHANGELOG | 11 | 折叠的 <details> 历史附录被当成主时间线;order 报的行号系统性偏上一行 |
| dockerfile-check | 第三方 Dockerfile | 2 | 一份以 root 收尾(真缺陷),一份干净——检查不是见谁咬谁 |
| env-example-check | 第三方 .env.example | 1 | 把文档里的 https://remote.example.edu/... 判成提交了真值 |
剩下仍报错的两份是真发现,不是误报:一份 LICENSE 的正文不是任何标准许可证;另一份标题写 MIT、正文是 AGPL-3.0;英文版 changelog 把未发布的 alpha 重列在新版本之后,而它的中文版把同一条放进了折叠区。
第二层:跑过自家真实产物(6 个检查)
| 检查 | 语料 | 份数 | 第一次跑出的问题 |
|---|---|---|---|
| commit-msg-check | 三个仓库的提交历史 | 120 | 83% 报 type-missing——那是团队约定不是缺陷;56% 主题超 72 字,那是真问题 |
| pr-description-check | 已合并的目录 PR 正文 | 19 | 19/19 报缺 what/why/test,其实三个问题都用散文答了;另 2 个被误判"声明了破坏性变更" |
| adr-check | 本项目的决策记录 | 3 | 只看项目符号,把写在段落行上的「好处:」「代价:」判成未标注 |
| incident-report-check | 事故复盘 | 1 | 无 |
| ops-runbook-check | 四份 runbook | 4 | 两份用 ## 3. 编号标题的 runbook 被报"完全没有编号步骤" |
| api-doc-check | host 路由的接口参考 | 1 | 文档写对了,但探针发现六处形状写错——那是文档的错,不是检查的错 |
第三层:只有自造样例(11 个检查)
这些检查的每条规则都在测试里被观察到两个方向——坏文档会报、好文档沉默——但那个"好文档"是我写的。没有陌生人的真实文件跑过它们。
- agreement-check(合同)
- invoice-check(发票)
- listing-check(商品信息)
- meeting-notes-check(会议纪要)
- resume-check(简历)
- weekly-report-check(周报)
- bug-report-check(缺陷报告)
- test-report-check(测试报告)
- spec-doc-check(需求文档)
- handover-check(交接单)
- expense-claim-check(报销单)
为什么第一层最重要
到目前为止找出 17 个检测器缺陷,其中 14 个是"规则要求某一种写法,而真实文档用了另一种同样合法的写法"。这个缺陷在自造 fixture 上永远不会暴露。
最典型的一个是第十七个:order 报的行号系统性偏上一行——判定是对的,指针是错的,用户按报的行号找会落在空行上。这件事我写了十七轮都没发现,因为我写 fixture 时只关心"有没有报",从不关心"报的行号对不对"。第一个陌生人的 changelog 第一次就暴露了它。
如果你手上有一份
任意一条判断错了——多报了不该报的、或漏了该报的——请开一个 语料报告,附上脱敏后的原文片段和 CLI 的原样输出。
提交前请把真名、公司、金额、地址、证件号、联系方式、内网域名替换成占位符。这份内容会成为那条规则的回归测试,所以它会进仓库、会公开。
第三层那十一个检查,我一个人补不上——我没有别人的合同、别人的简历、别人的报销单。
另外两处
这套材料不是只有本 kit。同一个作者另两个仓库各有一份:五个通用检查跑过什么(里面记着第 18 个缺陷——tablelint 对故意无表头的表格误报,就是拿第三方 README 试出来的);以及 项目交接单(唯一维护者写给"如果明天他不在",接收人一栏至今是「尚未指定」)。