docs: 删掉 README「nothing to install」假声明,改正 peer 叙述

d144284 补了「Prerequisite: link the harness packages first」章节,但留下两处
与新章节自相矛盾的话,这一提交收掉:

1. README §Install 的安装注释 `npm install  # nothing to install; dsh packages
   are peers` —— 直接删。实测它不成立:干净副本里 npm install 只拉到 cordis
   (四个 peer 里唯一非 optional 的)加它的传递依赖,dsh-llm /
   dsh-system-prompt / dsh-tools 三个仍然缺;不 install 更彻底,四个全缺。
   改成说明 peer 归属 + 指向前置章节的链接。
2. 新章节开头 `This repository has **no runtime dependencies**` —— 同样不成立
   (lib/index.js 运行时 import 三个 @deepseek-ai 包)。改成「不以本插件自身
   依赖的形式拉取任何东西」,把 peer 归属说清,并写明 npm install 只解决
   cordis 一个。
3. 症状段补一句 npm run check 同样红(实测 exit=1,checkpoints.js 在 import
   阶段就 ERR_MODULE_NOT_FOUND),原文只提了 npm test。
4. scripts/link-dsh.sh 头部注释里的 `zero runtime dependencies` 一并改成同义
   但不撒谎的说法。

验证(自己跑,不转述)
- 干净副本 git archive HEAD + 本补丁,不 link:
    not ok loader / phase-b-g / phase-b-h / plugin
    # tests 34  # pass 30  # fail 4
    npm run check exit=1(Cannot find package '@deepseek-ai/cordis')
- 同一副本 bash scripts/link-dsh.sh 之后:
    # tests 120  # pass 120  # fail 0
    npm run check exit=0,10 条 ✔
- npm install 单独一步(不 link)也复现:四文件 ERR_MODULE_NOT_FOUND,
  缺的是 dsh-system-prompt / dsh-llm(cordis 已装)
- README 全文再无「nothing to install / no runtime dependencies / zero
  runtime dependencies」类断言(grep 零命中)
- README 计数禁令仍绿,无 .orig/.rej/.bak 入库

更正一处旧结论:交接说「不 link 时 4 个文件 ERR_MODULE_NOT_FOUND」= 少 4 个
用例,不对。那四个文件在 import 阶段就死,用例根本没注册,所以 npm test 汇总
是 34 tests,不是 116/120。已在 README 里写成「a handful of tests rather than
the full suite」,避免再误导。
This commit is contained in:
2026-10-30 15:07:45 +08:00
parent d1442848c4
commit e2c2bb41b7
2 changed files with 26 additions and 14 deletions

View File

@ -177,9 +177,16 @@ something", and no waterfall that can rewrite a loop-built request
## Install
The plugin brings no dependency of its own: everything it imports at runtime is a
`@deepseek-ai/*` **peer** that ships with the dsh install on the machine.
`npm install` does **not** deliver those peers (three of the four are declared
optional), so on its own it leaves a tree that cannot even load the plugin — link
them first, per
[Prerequisite: link the harness packages first](#prerequisite-link-the-harness-packages-first).
```bash
# from this repo
npm install # nothing to install; dsh packages are peers
npm install
```
The plugin needs `node:sqlite` (built into Node ≥ 22.5). On Node 22.23 it works
@ -646,22 +653,26 @@ because they will bite anyone writing a second dsh service plugin.
### 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).
Nothing here is fetched as this plugin's own dependency. The `@deepseek-ai/*`
packages that `lib/` imports at runtime are **peers**: they belong to the dsh
install already on the machine, and they are not vendored here on purpose
(a copy would drift from the harness this plugin is supposed to run inside).
`npm install` does not resolve them either — `cordis` is the only one of the four
that is non-optional, so npm fetches that one (plus its own transitive deps) and
leaves the other three missing.
So a fresh clone needs one setup step before the suite can run:
A fresh clone therefore 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.
**Skip it and `npm test` and `npm run check` both fail with four files
reporting `ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/…'`** —
`loader`, `plugin`, `phase-b-g` and `phase-b-h` (the suites that mount a real
dsh app). Those four die at import, so the run reports a handful of tests rather
than the full suite. That is the expected symptom of a missing setup step, not a
broken tree; run the script and both commands go green.
The script takes an optional argument for a non-default install root:

View File

@ -1,9 +1,10 @@
#!/usr/bin/env bash
# Link the globally-installed dsh packages into node_modules.
#
# The plugin itself has zero runtime dependencies (it uses only `node:` built-ins),
# so nothing is installed from a registry. The dsh packages are *peers*: they must
# come from the running harness. During development they live in
# The plugin declares no dependency of its own, so nothing here is fetched from a
# registry. The dsh packages it *imports* at runtime are **peers**: they must come
# from the running harness, and npm will not install them for us. During
# development they live in
# /usr/lib/node_modules/@deepseek-ai (a global install), so this script wires them
# up by symlink instead of vendoring a copy that could drift from the harness.
#