dsh-wiki-notes 1.4.3 → 1.6.0
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 +47 -0
- package/README.md +23 -7
- package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.657.md +657 -0
- package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.661.md +661 -0
- package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.final.md +661 -0
- package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.md +661 -0
- package/lib/bridge.js +23 -1
- package/lib/calls.js +32 -99
- package/lib/client.js +114 -1
- package/lib/corpus.js +21 -2
- package/lib/engine.js +300 -19
- package/lib/governance.js +849 -0
- package/lib/index.js +241 -38
- package/lib/jsonl-store.js +191 -0
- package/package.json +5 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# 变更记录
|
|
2
|
+
|
|
3
|
+
本文件的体例:只记「对使用者有影响的行为变化」,不记内部重构。版本号遵循 semver,`0.x` 阶段不承诺兼容。
|
|
4
|
+
|
|
5
|
+
## 1.6.0
|
|
6
|
+
|
|
7
|
+
### 检索
|
|
8
|
+
|
|
9
|
+
- **字面覆盖率兜底**:整句中文(无空格)在 AND 与 OR 双双落空时,降级为「中文二字组 / 拉丁整词」的覆盖率匹配(阈值 45%,`degraded: true`),并在结果里说明这是降级而非「库里没有」。长句查询的 Recall@5 从 23.1% 提到 61.5%。
|
|
10
|
+
- **NFKC 归一化**:全角输入(`AI`、`()`)先归一化再切词;全角查询的命中率从 0% 到 100%。
|
|
11
|
+
- **疑问词只剥两端**:`X 是什么`、`X 怎么安排` 里的问法不再当检索词;**只剥首尾**,不从前中段切(从中间切会造伪词,把一句完整查询切成两个不存在的词)。
|
|
12
|
+
- **查询长度上限 200 字符下沉到引擎**:以前只在工具层拦,`bin/cli.mjs`、设置页 `/search`、Python 桥都绕得过去。
|
|
13
|
+
- **标签 / 别名的逗号串**(`标签: a, b, c` 这种 YAML 裸标量)现在会被拆成多项,打分与 `list {tags}` 筛选口径一致(以前打分沾得上、筛选筛不到)。
|
|
14
|
+
- **`brokenLinks` 改为页级**,并复用语料层的双链解析(不再自己扫正文,避免把行内代码里的 `[[示例]]` 当断链)。
|
|
15
|
+
|
|
16
|
+
### 给模型看的解释
|
|
17
|
+
|
|
18
|
+
- **`note` 不再被吞**:`run()` 会给结果加 `status`,渲染层原来的条件导致所有 `note` 都印不出来;现在非 ok 时由 warnings 承载、ok 时由 note 承载。
|
|
19
|
+
- **`no_match` / 过滤空结果 / 覆盖率兜底** 都会说明原因(「库里没有这个主题」与「过滤条件把它排除了」是两回事)。
|
|
20
|
+
- **取页更诚实**:别名被多页共用时判 `partial` 并点名两页;命中只有 frontmatter 的空页会说明「这页没有正文」。
|
|
21
|
+
- **网关错误能印出 code**:以前只印 `知识网关调用失败:? — `,现在印 `E_PYTHON_UNAVAILABLE — …`。
|
|
22
|
+
|
|
23
|
+
### 账本与审计
|
|
24
|
+
|
|
25
|
+
- **测试不再往真实账本写**:11 个会 `apply()` 的测试文件改走临时目录,跑一遍 `npm test` 不再往「调用记录」里塞 33 条假调用。
|
|
26
|
+
- **`calls.read()` 合并顺序修正**:同一秒的多条不再倒序,轮转裁掉的旧行不再被内存补回来(窗口不再越读越长)。
|
|
27
|
+
- **JSONL 存储**:轮转阈值差一(5000 行会先长到 5001)、轮转改为 `.tmp` + `rename` 原子替换、末尾半行自动补换行(不再把新记录粘在坏行后面)、轮转按物理行计数(满盘坏行也能轮转)、`onRotate` 钩子让内存缓冲跟着裁。
|
|
28
|
+
|
|
29
|
+
### Python 桥
|
|
30
|
+
|
|
31
|
+
- **`stdin` 写入失败不再变成未捕获异常**:python 提前退出、而这边还在写大 payload 时会抛 `EPIPE`,以前会让宿主进程收到一个没人接的 error 事件;现在只记录并在错误消息里说明。
|
|
32
|
+
|
|
33
|
+
### 测试与工具
|
|
34
|
+
|
|
35
|
+
- 新增 `tests/tier.mjs`(类型层)、`tests/render.mjs`(渲染文本)、`tests/bridge.mjs`(桥的 11 条失败路径,用 `node` 冒充 python)、`tests/store.mjs`(JSONL 存储边界)、`tests/calls-read.mjs`(账本合并)。`npm test` 从 21 个文件到 **25 个**。
|
|
36
|
+
- 新增 `tests/local/recall.mjs`(质量评测:Recall@5 / Top-1 / MRR,按标签分组,低于 floor 退 2)与 `tests/local/queries.example.json`。
|
|
37
|
+
- `tools/probe.mjs` 同时接受 `--root=<path>` 与 `--root <path>`(以前只认后者,`--k=v` 会被当成参数名丢掉)。
|
|
38
|
+
|
|
39
|
+
## 1.5.0
|
|
40
|
+
|
|
41
|
+
- 本地知识网关的**双模式治理**:系统提示注入 + 四个工具的 description + 渲染层追加 + 治理账本,四层叠加约束「先查一次库、别自动升级成完整核验、结尾披露可信度」。
|
|
42
|
+
- `lib/index.js` 的 `inject` 补上 `sessions`(strict inject 下缺它会让插件整片不激活),新增 `tests/inject.mjs`。
|
|
43
|
+
- `wiki_observe` 只认 `kind: 'observe_stats'`(此前把日志事件的 kind 当成返回值的 kind,治理指标静默不合并)。
|
|
44
|
+
|
|
45
|
+
## 1.4.3
|
|
46
|
+
|
|
47
|
+
- 公开仓库的样例、契约文档与测试查询词全部换成虚构语料;发版前解包 `npm pack` 产物逐文件扫一遍。
|
package/README.md
CHANGED
|
@@ -221,9 +221,15 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
221
221
|
|
|
222
222
|
## 检索质量
|
|
223
223
|
|
|
224
|
-
|
|
224
|
+
三条线分开看,别混成一个数字:
|
|
225
225
|
|
|
226
|
-
|
|
226
|
+
- **对齐(parity)**:`tests/local/ab.mjs` 比的是「JS 引擎的前 5 是否覆盖 Python `search.py` 的前 5」,当前 **166/166,漏 0**;`tests/local/metrics.mjs` 比同一批槽位的集合与排序,Recall@5 100%、Jaccard 0.63,当硬门禁。两侧刻意保留少量已知分歧(疑问词剥离是有意改进、index 摘要 +8、类型层平局裁决),名单在本地 `tests/local/parity-exceptions.json`,**不入仓库**。
|
|
227
|
+
- **质量(recall)**:`tests/local/recall.mjs` 跑人工标注的评测集,报 Recall@5 / Top-1 / MRR@5 并按标签分组。当前基线 **Recall@5 85.2% · Top-1 76.3% · MRR 0.819**(59 条查询 / 194 个槽位),低于基线即 exit 2。评测集 `tests/local/queries.json` 含真实笔记主题,**不入仓库**;仓库里只有中性 6 条的 `queries.example.json`。
|
|
228
|
+
- **性能**:123 页扫一遍约 51ms,单条查询 4ms 上下;`tools/probe.mjs` 另攒一条 hit@1 / hit@3 / Recall@5 的趋势 CSV。
|
|
229
|
+
|
|
230
|
+
评分刻意朴素:标题全等 120 / 标题含 60 / 别名含 50 / 标签含 25 / 正文词频 ×3(封顶 36)/ index 摘要只在其它通道全 0 时补 8;同分再比类型层(综合 3 · 总览 3 / 概念·实体·对比 2 / 资料 1)→ 更新时间 → 码点序。四处经验细节:摘要分只补漏不抢位、同分用码点序(拼音序不可复现)、选节排除清单类与元讨论类小节、总览与综合同层(总览是全库唯一入口页,跨模块的词在它里面出现分量不同)。
|
|
231
|
+
|
|
232
|
+
中文连写整句在 AND / OR 双双落空时会降级到**字面覆盖率兜底**(中文二字组 / 拉丁整词,覆盖率 ≥45% 才入选,`degraded: true` 并在结果里说明),这是缓解不是语义检索;查询先做 NFKC 归一化并剥掉两端疑问词。
|
|
227
233
|
|
|
228
234
|
---
|
|
229
235
|
|
|
@@ -262,9 +268,10 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
262
268
|
|
|
263
269
|
## 已知局限
|
|
264
270
|
|
|
265
|
-
- 中文不分词,靠空格切分;连写词靠 `别名`
|
|
271
|
+
- 中文不分词,靠空格切分;连写词靠 `别名` 补。整句中文拿不到命中时会降级成字面覆盖率排序,那是**字面**匹配,语义相近但用词不同照样认不出。
|
|
266
272
|
- 页名本身是查询词时,正文很少重复该词,选节可能偏。
|
|
267
|
-
- 每次调用全量扫描;
|
|
273
|
+
- 每次调用全量扫描;123 页约 51ms,再大一个数量级要上增量索引。
|
|
274
|
+
- 每命中一页要塞约 900 字符正文(`sectionChars` 可调),一次返回 5 页就是 4–5k 字符 —— 瓶颈常在上下文预算而不在检索速度。
|
|
268
275
|
- **重启后第一次扫描是冷盘读**:95 页实测 5,217ms(此后 29ms)。插件启动就预热一次,所以这段延迟通常落在你还没提问的时候;但第一条查询正好赶上也确实要等。
|
|
269
276
|
- **面板没打开时 `/`、`Ctrl/⌘ + K` 不会有反应**:快捷键绑在面板上,而宿主的 `sidebarRightTabs` 只提供 `register()`,没有「打开 / 激活页签」的接口,插件没法从外面把面板叫出来。
|
|
270
277
|
- **知识网关那套仍是两套实现**:JS 侧 `wiki_recall` 和 Python 侧 `wiki_context` 各自解析页面,差在结构解读层。统一方向未定。
|
|
@@ -287,28 +294,37 @@ tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
|
|
|
287
294
|
tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
|
|
288
295
|
docs/库结构.md 库结构约定(这份才是一手文档)
|
|
289
296
|
docs/README.md 文档导航页
|
|
297
|
+
CHANGELOG.md 版本变更记录
|
|
290
298
|
docs/superpowers/specs/ 检索面板的设计稿
|
|
291
299
|
docs/契约-stage0/ 知识网关的设计与验收记录
|
|
292
300
|
examples/ 可跑的最小样例库
|
|
293
|
-
tests/ smoke / status / lint / explain / api / help / contract / watch / client
|
|
301
|
+
tests/ smoke / status / lint / explain / api / help / contract / watch / client
|
|
302
|
+
/ tier / render / bridge / store / calls / calls-read / gateway
|
|
303
|
+
tests/local/ 作者本机的评测集与回归基线(query 与基线文件不入仓库,只留 *.example)
|
|
304
|
+
tests/support/ 测试用小工具(quiet-ledger:把账本重定向到临时目录,别写进你的调用记录)
|
|
294
305
|
```
|
|
295
306
|
|
|
296
307
|
```bash
|
|
297
|
-
npm test #
|
|
308
|
+
npm test # 跑样例库,不需要本地知识库(25 个文件)
|
|
298
309
|
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
299
310
|
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
311
|
+
WIKI_ROOT="/path/your/wiki" node tests/local/recall.mjs # 质量评测:Recall@5 / Top-1 / MRR(低于 floor 退 2)
|
|
300
312
|
npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
|
|
301
313
|
node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
|
|
302
314
|
node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
|
|
303
315
|
```
|
|
304
316
|
|
|
317
|
+
`tests/local/` 那套要先把 `queries.example.json` 复制成 `queries.json` 再按自己的库改(`expect` 写「必须进前 5 的页名」,由人标,不依赖任何旧引擎的输出)。基线文件 `ab_baseline.json` 也是本地产物,重导用 `python ab_export.py > ab_baseline.json`。
|
|
318
|
+
|
|
305
319
|
跑知识网关那两段真实通路,要给两个环境变量(不给就整段跳过,不会假装通过):
|
|
306
320
|
|
|
307
321
|
```bash
|
|
308
322
|
WIKI_ROOT="/path/your/知识层-wiki" WIKI_TOOLS="/path/your/工具-tools" node tests/gateway.mjs
|
|
309
323
|
```
|
|
310
324
|
|
|
311
|
-
发版:改 `version` → `npm test` 全绿(`scripts.test`
|
|
325
|
+
发版:改 `version` → `npm test` 全绿(`scripts.test` 只串跑 `node tests/*.mjs`,25 个文件;`node --run test` 要 Node 22+,别在低版本上用它,也别拿它当门槛的证明)→ `npm pack --dry-run` 看一眼打包内容(`files` 只含 `lib`/`bin`/`docs`/`examples`/`README.md`/`CHANGELOG.md`/`LICENSE`/`cordis.patch.yml`,`preview/` 与 `tools/` 与 `tests/` 都不进包)→ **显式** `npm publish --registry=https://registry.npmjs.org/`。发布前先 `npm whoami --registry=https://registry.npmjs.org/` 确认已登录(本机 token 在 `.npmrc` 的 `//registry.npmjs.org/:_authToken=`;注意 `npm config get registry` 指向 npmmirror,而 npmmirror 那边不认这个 token,登录状态要显式指定 registry 去查)。发完要当场核三件事:`npm view <pkg>@<ver> dist.tarball` 取回的地址(带 fresh cache 与 REST cachebust)、下载 tarball 对 SHA256、`gh release view` 的 `isLatest`(注意它不能直接 `--json isLatest`)。
|
|
326
|
+
|
|
327
|
+
打包进了你的笔记标题怎么办:`tests/local/` 的 query 集、分歧白名单、回归基线与 `calls.jsonl` / `governance.jsonl` / `probe-history.csv` 都在 `.gitignore` 里,只在本机跑。发版前用 `git diff --cached | Select-String '<你的用户名>|<你的库路径>|<真实页名>'` 过一遍暂存区,命中就改口径再提交。
|
|
312
328
|
|
|
313
329
|
改样式的两条经验:
|
|
314
330
|
|