dsh-wiki-notes 1.10.0 → 1.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  本文件的体例:只记「对使用者有影响的行为变化」,不记内部重构。版本号遵循 semver,`0.x` 阶段不承诺兼容。
4
4
 
5
+ ## 1.10.1
6
+
7
+ ### 修 · `wiki_context` 长期「降级」其实是一个环境变量没传
8
+ - 症状:每次 `wiki_context` 都返回 `degraded: true` / `degraded_sources: ["wiki_recall"]`,而 `status.support` 仍有值 —— 单看 `support` 会以为「库里的证据就这样」,实际是半个引擎在跑。
9
+ - 根因在插件这侧:Python 管线的 `wiki_recall` 引擎是回头调本插件的 `node bin/cli.mjs search`(`context_builder.py` 的 `run_plugin`),它用环境变量 `WIKI_PLUGIN_DIR` 定位插件目录。插件调桥时只传了 `WIKI_OBSERVE_LOG`,于是 cwd 落在工具目录、`bin/cli.mjs` 不存在,stdout 空,那边 `json.loads('')` 抛 `Expecting value: line 1 column 1 (char 0)`,引擎判死。
10
+ - 现在 `lib/index.js` 每次都传 `WIKI_PLUGIN_DIR`。修后实测:`engines` 两个都 `ok`,`degraded: false`,`degraded_sources: []`。
11
+ - 加了一条源码守卫(`tests/bridge.mjs`):假 python 的单元测试看不见这类故障 —— 它压根不调真管线,只有「必须传这个变量」的断言拦得住。
12
+
13
+ ### 新 · 两个体检脚本
14
+ - `node tools/verify-bridge.mjs`:真起一次 Python 桥,逐项断言「两个引擎都活着 / 没被标降级 / 带回了证据 / observe 认得回来」。默认不传观察日志,所以不会往治理账本里写东西。
15
+ - `node tools/verify-host.mjs --self`:在自己进程里用真入口起一个真 HTTP 服务,打 10 项探针(`/state` 版本指纹、`/links` 与它的 404、`/search`、`/open` 越界闸、`/calls` 字段数)。`--port <端口>` 探已在跑的 DSH。
16
+ - 两个脚本都在仓库里而不进包(`files` 不变),`npm run verify:bridge` / `npm run verify:host` 也能跑。
17
+
5
18
  ## 1.10.0
6
19
 
7
20
  把「探索」这一窗补成能顺着走的:从标签走到相邻主题,从一页走到它指向的和指向它的。
package/README.md CHANGED
@@ -90,6 +90,10 @@
90
90
 
91
91
  同时返回 `evidence`(证据页,含分级、支撑了哪个槽位)、`missing`(缺什么、为什么缺)、`conflicts`(冲突候选,**未裁决,别当成已确认的结论**)、`answer.contract_text`(给回答的约束:必须披露缺口、不得超出证据、引文须原文),以及一个 `context_id`。模型看到的渲染文本里,每张证据页最多再附 2 条原文引文(每条按槽位标注、裁到 220 字);JSON 结构不变,引文仍是页面原文子串,不是插件替你概括的。
92
92
 
93
+ `degraded` 为真时要先修通道,再谈结论。返回里的 `engines` 会写清每个通道的状态(`{"search":{"status":"ok"},"wiki_recall":{"status":"ok"}}`),`degraded_sources` 则点名是哪个死了。想直接体检这条通路,跑 `node tools/verify-bridge.mjs`:它真起一次 Python 管线,逐项断言「两个引擎都活着 / 没被标降级 / 带回了证据 / observe 认得回来」。
94
+
95
+ > 2026-11-17 踩过的一个真实故障:`wiki_recall` 通道长期是死的,于是每次 `wiki_context` 都挂 `degraded:true`,而 `support` 看上去还有值 —— 单看 `support` 会以为「库里的证据就这样」。根因不在 Python 也不在检索,而是插件调桥时**少传了一个环境变量** `WIKI_PLUGIN_DIR`:管线的 `wiki_recall` 引擎是回头调本插件的 `node bin/cli.mjs search`(见 `context_builder.py` 的 `run_plugin`),拿不到插件目录就把 cwd 落在工具目录,`bin/cli.mjs` 不存在,stdout 空,那边 `json.loads('')` 抛错,引擎判死。现在 `lib/index.js` 每次都传它,`tests/bridge.mjs` 里有一条源码守卫盯着这行 —— 假 python 的单元测试看不见这种故障,因为它压根不调真管线。
96
+
93
97
  ### `wiki_verify` —— 核验回答
94
98
 
95
99
  写完答案后自查(尤其含数字、范围、年份、题量分值这类主张时)用它。参数:`context_id` + `answer`(可选 `observe_id`,一般不用传,插件会自动带上)。
@@ -393,6 +397,8 @@ lib/client.js 设置页 + 检索面板 + 右侧栏页签(手写 bundle,无
393
397
  bin/cli.mjs 命令行,不装插件也能跑
394
398
  tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
395
399
  tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
400
+ tools/verify-host.mjs 宿主实机验收:--self 自己起个真 HTTP 服务打 10 项探针,--port 探已在跑的 DSH
401
+ tools/verify-bridge.mjs 真管线体检:起一次 Python 桥,断言两个引擎都活着、没被标降级
396
402
  docs/库结构.md 库结构约定(这份才是一手文档)
397
403
  docs/README.md 文档导航页
398
404
  CHANGELOG.md 版本变更记录
@@ -413,6 +419,9 @@ WIKI_ROOT="/path/your/wiki" node tests/local/recall.mjs # 质量评测:Recal
413
419
  npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
414
420
  node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
415
421
  node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
422
+ node tools/verify-host.mjs --self # 宿主验收:本进程起真 HTTP 服务,打 10 项探针
423
+ node tools/verify-host.mjs --port 63123 # 探已在跑的 DSH(改完宿主没重启时,会在这几项上红)
424
+ node tools/verify-bridge.mjs # 真管线体检:两个引擎都得是 ok,degraded 得是 false
416
425
  ```
417
426
 
418
427
  `tests/local/` 那套要先把 `queries.example.json` 复制成 `queries.json` 再按自己的库改(`expect` 写「必须进前 5 的页名」,由人标,不依赖任何旧引擎的输出)。基线文件 `ab_baseline.json` 也是本地产物,重导用 `python ab_export.py > ab_baseline.json`。
package/lib/index.js CHANGED
@@ -1496,8 +1496,16 @@ async function callBridge(command, payload) {
1496
1496
  python: cfg.python || 'python',
1497
1497
  toolsRoot: cfg.toolsRoot,
1498
1498
  timeoutMs: cfg.timeoutMs,
1499
- // 观察日志单独落盘:正式使用与测试数据物理隔离,免得修正率被自测记录带歪
1500
- env: cfg.observeLog ? { WIKI_OBSERVE_LOG: cfg.observeLog } : {},
1499
+ // 观察日志单独落盘:正式使用与测试数据物理隔离,免得修正率被自测记录带歪。
1500
+ // WIKI_PLUGIN_DIR 必须一起给:Python 管线里有一个 `wiki_recall` 引擎是回头调
1501
+ // 本插件的 `node bin/cli.mjs search`(context_builder.py 的 run_plugin),它按
1502
+ // 这个变量定位插件目录;不给就 cwd 落到工具目录、`bin/cli.mjs` 不存在,
1503
+ // node 的错误只进 stderr,stdout 空 → 那边 json.loads('') 抛
1504
+ // 「Expecting value: line 1 column 1 (char 0)」→ 每次 context 都被标成
1505
+ // degraded / degraded_sources:["wiki_recall"],两个引擎等于只跑了一个。
1506
+ env: cfg.observeLog
1507
+ ? { WIKI_OBSERVE_LOG: cfg.observeLog, WIKI_PLUGIN_DIR: pluginRoot }
1508
+ : { WIKI_PLUGIN_DIR: pluginRoot },
1501
1509
  pluginVersion: PLUGIN_VERSION,
1502
1510
  })
1503
1511
  if (!result.ok) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-wiki-notes",
3
- "version": "1.10.0",
3
+ "version": "1.10.1",
4
4
  "type": "module",
5
5
  "description": "Read-only knowledge gateway over a local Markdown vault for DeepSeek Harness — recall, evidence pack, answer verification, call audit | 本地 Markdown 笔记库的只读知识网关:检索、证据包、核验、调用审计",
6
6
  "keywords": [
@@ -46,7 +46,9 @@
46
46
  "scripts": {
47
47
  "test": "node tests/smoke.mjs && node tests/status.mjs && node tests/overview.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/calls.mjs && node tests/governance.mjs && node tests/inject.mjs && node tests/watch.mjs && node tests/client.mjs && node tests/tier.mjs && node tests/render.mjs && node tests/nearmiss.mjs && node tests/calls-read.mjs && node tests/store.mjs && node tests/bridge.mjs && node tests/text.mjs && node tests/parse.mjs && node tests/fingerprint.mjs && node tests/bom.mjs",
48
48
  "cli": "node bin/cli.mjs",
49
- "probe": "node tools/probe.mjs"
49
+ "probe": "node tools/probe.mjs",
50
+ "verify:host": "node tools/verify-host.mjs --self",
51
+ "verify:bridge": "node tools/verify-bridge.mjs"
50
52
  },
51
53
  "peerDependencies": {
52
54
  "@deepseek-ai/cordis": "^4.0.1",