docs: README 补前置准备(干净 clone 直接跑 npm test 会红 4 个文件)

缺口(评审复现,我独立复现确认)
git archive HEAD 到空目录、原样 npm test:
  # tests 34  # pass 30  # fail 4
  not ok test/loader.test.js / phase-b-g.test.js / phase-b-h.test.js / plugin.test.js
根因:Cannot find package '@deepseek-ai/cordis'。
而 README 全文对 link-dsh.sh / node_modules / 前置准备零命中 ——
正文只写「npm test 是 how many 的权威」,默认读者已经跑过 link-dsh.sh,
而这个前提谁都没写。

这与本轮刚修的那个缺口同族:判据/文档声称的能力,在没有守卫的地方悄悄不成立。
(刚删掉 README 计数,理由是「没守卫就会漂」;「npm test 是权威」这句话
  同样没有守卫 —— 它默认了一个没人写下来的前置。)

修法(按裁定选 ①,不用 pretest 钩子)
README §Verify 开头新增「Prerequisite: link the harness packages first」:
- 说清本仓零运行时依赖,@deepseek-ai/* 全部是 peer,
  必须来自机器上已装的 dsh(vendoring 会与它要运行的 harness 漂开)
- 给命令 bash scripts/link-dsh.sh
- 明确写出跳过它的症状:四个文件 ERR_MODULE_NOT_FOUND
  (loader / plugin / guard / http 四套,与实测逐一对齐),
  并说明这是缺前置的正常形态,不是树坏了
- 补非默认安装根的可选参数

按裁定的第二条不加判据去测「干净 clone 能跑测试」(成本高于收益),写清楚就够。

顺带一处:README 的计数禁令只匹配数字形态(119 tests / 10 checkpoints /
10/10 passed),新段落用了英文「four files」,不被误报 ——
在守卫里加注释说明这个 scope,以及为什么不去匹配文字形态
(「四个文件报 ERR_MODULE_NOT_FOUND」是合法的散文,再往下写就变成小解析器)。

验证
- 干净 clone 复现:无链接 4 红;bash scripts/link-dsh.sh 之后 120/120、check 10/10
- README 描述的失败文件清单与实测逐一一致
- npm test 连跑 5 次 120/120
- npm run check 3 次,exit=0、10 条全绿
- README 计数禁令仍绿(未误报新段落)
- 无 .orig / .rej 残留,未 amend / 未 force push
This commit is contained in:
2026-10-30 15:02:38 +08:00
parent 0e65dfee64
commit d1442848c4
2 changed files with 34 additions and 0 deletions

View File

@ -644,6 +644,33 @@ because they will bite anyone writing a second dsh service plugin.
## Verify
### Prerequisite: link the harness packages first
This repository has **no runtime dependencies** — `lib/` uses only `node:`
built-ins. Everything it imports from `@deepseek-ai/*` is a **peer** that must
come from the dsh install already on the machine, which is why none of it is
bundled here (vendoring a copy would let it drift from the harness it is supposed
to run inside).
So a fresh clone needs one setup step before the suite can run:
```bash
bash scripts/link-dsh.sh # symlinks the installed dsh packages into node_modules
```
**If you skip it, `npm test` fails with four files reporting
`ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/cordis'`** (loader,
plugin, guard and http suites). That is the expected symptom of a missing setup
step, not a broken tree — run the script and it goes green.
The script takes an optional argument for a non-default install root:
```bash
bash scripts/link-dsh.sh /path/to/global/node_modules
```
### Run
```bash
npm test # the full suite
npm run check # human-readable evidence, one line per checkpoint

View File

@ -232,6 +232,13 @@ test('scripts/checkpoints.js registers checkpoints AND refuses to pass with zero
//
// So the invariant is now the opposite: the README must NOT state a count. If
// someone re-adds one, this fails and the reason is right here.
//
// Scope: this matches DIGIT forms ("119 tests", "10 checkpoints", "10/10 …").
// It does not try to catch a count spelled out in words ("four files"), because
// the README legitimately needs prose like "four files report ERR_MODULE_NOT_FOUND
// — that is the missing-setup symptom" and a prose-matching rule would either
// fire on that or grow into a mini parser. The rule targets the shape a
// maintainer actually writes when pasting a run result, which is digits.
test('README states no test or checkpoint counts', () => {
const readme = readFileSync(join(new URL('..', import.meta.url).pathname, 'README.md'), 'utf8')