dsh-wiki-notes 1.1.3 → 1.3.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/README.md CHANGED
@@ -39,7 +39,7 @@ Built for [DeepSeek Harness](https://github.com/deepseek-ai). Instead of a 5-ste
39
39
  plugin_manager { action: "install_bundle", target: "<绝对路径>" }
40
40
  ```
41
41
 
42
- 返回 `application: applied` 就生效,不用重启。改 `lib/*.js` 后关开插件热重载;改 `lib/client.js`(设置页)要重启 DSH。
42
+ 返回 `application: applied` 就生效,不用重启。但**改插件自己的代码要重启 DSH**:`lib/*.js`(宿主半)和 `lib/client.js`(设置页)都一样,已载入的模块不会因为关开插件而重新求值。
43
43
 
44
44
  ---
45
45
 
@@ -88,7 +88,40 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
88
88
 
89
89
  设置 →「知识库」。状态栏圆点表示实时同步是否生效,三个数字是页面 / 资料 / 红链页,下面是路径卡片和 `测试 · 保存并生效 · 重新扫描`。一次没配过时,卡片会变成三步引导。
90
90
 
91
- 浏览器半侧走同源 HTTP `/api/wiki-notes/*`(`state` / `check` / `save` / `rescan`),不碰 RPC。
91
+ 浏览器半侧走同源 HTTP `/api/wiki-notes/*`(`state` / `search` / `check` / `save` / `rescan`),不碰 RPC。
92
+
93
+ ---
94
+
95
+ ## 检索面板
96
+
97
+ 设置页里有一张「试一试检索」的卡,右侧栏另有一个「知识库」页签 —— 同一份组件,`compact` 控制密度。用途只有一个:**让人自己看见检索依据**,不必等模型说它查到了什么。
98
+
99
+ 输入关键词回车,上面一行是「命中 7 页(显示前 5)· 参与打分 95 页 · 36 ms · 库 95 页」;紧跟一行是**查询诊断**:`实际用的词` 后面逐个列出这次真正参与打分的词,一页都没沾到的词会标成「没沾到」,末尾写清这次是「全词都要(AND)」还是「命中任一(OR)」。中文不分词,写整句时这一行通常只剩一个词 —— 这是最直观的提示:换词,而不是加词。
100
+
101
+ 每条命中占一行,左边是名次、页名、类型,右边是一条按「相对第一名」缩放的分数条和总分。多类型命中会按类型分组(`概念(3)`、`资料(2)`…)。展开后有:
102
+
103
+ - 页名、类型、总分,以及「只命中部分词」的标记(该条没命中全部查询词);
104
+ - **命中理由**:每个查询词一条徽章,主词加粗、明细灰字,例如 `上下文 · 页名 120 · 别名 50 · 正文 ×7 21`,未得分的词显示为「未命中」。悬停徽章有各通道的权重说明;
105
+ - 该条命中的小节标题与正文(正文里出现过的查询词带淡黄底纹),末尾附 citation,右侧一个复制按钮 —— 把「哪句话支撑了这条」直接抄进对话里;
106
+ - 查询降级成「命中任一」时,计数行旁边会黄字提示。
107
+
108
+ **键盘**:输入框防抖 350ms(够 2 个字符才查),`Enter` 立刻查,`Esc` 清空,`↑`/`↓` 在结果里移动高亮并展开对应条目;任意位置按 `/` 或 `Ctrl/⌘ + K` 直接跳到输入框。查询进行中列表上方显示「检索中…」。输入框右边有「复制词」—— 查出来的说法常常要拿去别处再查一遍,省得重敲;citation 那行的复制按钮同理(键盘走过去会看到焦点框)。
109
+
110
+ **覆盖统计**在设置页的状态卡下面:`发现 102 个文件 → 读到 95 页 / 677 个小节`,后面是总体积、跳过 / 读不了 / 超大未读 / 读取失败的计数(非 0 时标黄)、最新修改时间、本次扫描耗时,以及这次实际扫的目录(自动下钻过时它和配置里的路径不是同一个)。
111
+
112
+ 没查之前不是一片空白:显示库的规模、同步开关,以及库里出现最多的几个标签 —— 点一下直接拿它当查询词,省得先想「该查什么」。查不到时也顺带报覆盖:`参与检索 95 页 / 677 个小节 · 跳过 7` ——「没命中」和「那几页根本没读」是两回事,面板得能分清。`discovered = pages + unreadable + skipped` 在 `tests/api.mjs` 里当恒等式断言,这几个数不是凑出来的。
113
+
114
+ 面板是只读的:不写库、不改配置、不进模型上下文。
115
+
116
+ **`explain` 是对既有检索的解释,不是第二套检索。** 引擎里分数只有一个实现 —— `termScore(page, token)` 就是 `termBreakdown(page, token).score`,理由和排序分数出自同一份明细,所以面板不可能显示「一套理由、另一套排序」;`tests/explain.mjs` 对同一批查询比对开关前后的 `name|score|allTerms` 逐条相同,还核对了「每个词的明细加起来 === 该条总分」。`explain` 也不在工具 schema 里:模型触发不到它,`wiki_recall` 的输出体积一个 token 都不变。
117
+
118
+ 工具输出里新增两个短字段,是给**模型**看的而不是给面板看的:`matchMode`(`and`/`or`)和 `missedTerms`(一个词都没沾到的那些)—— 模型看到「这个词没用上」才可能换词重查。它们会被渲染成一行:`没沾到:量子纠缠(这些词在库里一页都没命中,换同义词或干脆去掉)`;没有漏词时这行不出现,正常路径不多花一个 token。而「每个词命中多少页」(`termPages`) 只在 `explain` 时出现:那是面板的事,模型用不上。
119
+
120
+ > 这条踩过一次:字段先加进了 `run()` 的返回值,但模型拿到的是 `renderValue()` 渲染出的文本 —— 不写进渲染,模型就等于没拿到。`tests/status.mjs` 现在有两条断言看着它(有漏词要出现、没漏词不许出现)。
121
+
122
+ 侧栏是可选能力:`ctx.inject(['sidebarRightTabs'], …)` 运行时按需取,服务不在就静默跳过,设置页照常可用;`dsh.client.inject` 刻意不钉侧栏模块(钉了会把「侧栏在不在」变成整个客户端包的加载前提)。`tests/contract.mjs` 守着这两条。
123
+
124
+ 接口:`GET /api/wiki-notes/search?q=上下文 预算&limit=5`,`q` 截到 200 字,`limit` 夹在 1–12,缺 `q` 返回 400。
92
125
 
93
126
  ---
94
127
 
@@ -100,7 +133,7 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
100
133
 
101
134
  ## 检索质量
102
135
 
103
- 与一个零依赖的 python 检索脚本做 A/B:14 条 query、比 top5 集合,**召回 65 / 65,无遗漏**。单条查询 0–2ms,扫 73 页约 50ms。
136
+ 基线是 v3:14 条 query / 68 个槽位,比 top5 集合,**Recall@5 = 100%,当回归硬门禁**(口径、判据与历史快照见 [docs/metrics.md](docs/metrics.md))。单条查询 0–2ms,扫 95 页约 76ms。
104
137
 
105
138
  评分刻意朴素:标题全等 120 / 标题含 60 / 别名含 50 / 标签含 25 / 正文词频 ×3(封顶 36)/ index 摘要只在其它通道全 0 时补 8。三处经验细节:摘要分只补漏不抢位、同分用码点序(拼音序不可复现)、选节排除清单类与元讨论类小节。
106
139
 
@@ -118,6 +151,8 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
118
151
  - 中文不分词,靠空格切分;连写词靠 `别名` 补。
119
152
  - 页名本身是查询词时,正文很少重复该词,选节可能偏。
120
153
  - 每次调用全量扫描;70–100 页无所谓,再大一个数量级要上增量索引。
154
+ - **重启后第一次扫描是冷盘读**:95 页实测 5,217ms(此后 29ms)。插件启动就预热一次,所以这段延迟通常落在你还没提问的时候;但第一条查询正好赶上也确实要等。
155
+ - **面板没打开时 `/`、`Ctrl/⌘ + K` 不会有反应**:快捷键绑在面板上,而宿主的 `sidebarRightTabs` 只提供 `register()`,没有「打开 / 激活页签」的接口,插件没法从外面把面板叫出来。
121
156
  - 只读。不写库、不改页、不修红链。
122
157
 
123
158
  ---
@@ -129,12 +164,14 @@ lib/corpus.js 扫描 + frontmatter / 小节 / 双链解析
129
164
  lib/engine.js 评分、选节、七种模式(纯函数)
130
165
  lib/config.js 库路径解析与配置读写
131
166
  lib/index.js 插件入口:工具、渲染、设置页 API、目录监听
132
- lib/client.js 设置页(手写 bundle,无构建)
167
+ lib/client.js 设置页 + 检索面板 + 右侧栏页签(手写 bundle,无构建)
133
168
  bin/cli.mjs 命令行,不装插件也能跑
134
169
  tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
170
+ tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
135
171
  docs/库结构.md 库结构约定(这份才是一手文档)
172
+ docs/superpowers/specs/ 检索面板的设计稿
136
173
  examples/ 可跑的最小样例库
137
- tests/ smoke / status / lint / api / help / contract / watch / client bundle
174
+ tests/ smoke / status / lint / explain / api / help / contract / watch / client bundle
138
175
  ```
139
176
 
140
177
  ```bash
@@ -142,8 +179,18 @@ node --run test # 跑样例库,不需要本
142
179
  node bin/cli.mjs search 上下文 --root=examples/sample-wiki
143
180
  WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
144
181
  node --run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
182
+ node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
183
+ node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
145
184
  ```
146
185
 
186
+ 发版:改 `version` → `node --run test` 全绿 → `npm pack --dry-run` 看一眼打包内容(`files` 只含 `lib`/`bin`/`docs`/`examples`/`README.md`/`LICENSE`/`cordis.patch.yml`,`preview/` 与 `tools/` 不进包)→ `npm publish`。本机 npm 常是未登录状态(`npm whoami` 报 `need auth`),发布前先在浏览器里确认 token。
187
+
188
+ 改样式的两条经验:
189
+
190
+ - `.wn-hit-row` 那道 span 不能省。`<summary>` 自带 display 规则,某些浏览器会把 `display:flex` 顶掉,行就塌成内容宽度、分数贴在标题右边 —— 所以行布局放在 summary 里那层 span 上,`tests/client.mjs` 守着它。
191
+ - 小字别用 `--wn-faint`(这组 token 在浅色底上约 3.4:1,低于 WCAG AA 的 4.5),小字一律 `--wn-muted`(约 5:1),层级靠字号和字重拉开,不靠把字调淡。
192
+ - `--diag` 遍历样式表时,别用「有 `cssRules` 就往下钻」的写法:现代 Chrome 的 `CSSStyleRule` 自己也带一个空的 `cssRules`(CSS 嵌套),会把你正要找的那条规则跳过,于是明明 `display=flex` 却报「NOT FOUND」。先判 `rule.cssRules.length`。
193
+
147
194
  ## License
148
195
 
149
196
  MIT
@@ -0,0 +1,113 @@
1
+ # 可视化检索面板设计(设置页 + 右侧栏)
2
+
3
+ 日期:2026-11-04 · 状态:待确认 · 规模:小(约 350 行)
4
+
5
+ ## 为什么
6
+
7
+ 现在检查一个检索插件的唯一办法是问模型「你查到了什么」,再自己判断它是不是在编。
8
+ 人看不见检索过程,也就无法判断**是库没写、还是没查到、还是查到了没用好**——
9
+ 这三种失败在对话里长得一模一样。
10
+
11
+ 面板把同一套 `run()` 的结果直接摊在人眼前:搜的词切成了什么、
12
+ 每个命中凭什么得分、选中的是哪一小节。人和模型看同一份证据,
13
+ 分歧才能落到具体一条上。
14
+
15
+ ## 目标
16
+
17
+ - 设置页「知识库」里多一个搜索框:输入 → 立刻看到命中列表与命中理由。
18
+ - 右侧栏多一个常驻 tab,装的是**同一个组件**,不必每次开设置。
19
+ - 每条命中可展开该小节正文与出处(页名 · §小节 · 文件路径)。
20
+ - 空查询时显示库的状态摘要(页数 / 资料数 / 扫描耗时 / 红链 / 最后更新)。
21
+
22
+ ## 非目标(本轮不做)
23
+
24
+ - 一键把结果注入对话上下文。
25
+ - 打开笔记文件到编辑器(那是 better-sidebar 的能力,本轮不引入该依赖)。
26
+ - 任何检索算法改动:分数口径、分词、排序一律不动。
27
+ - 任何写知识库的能力。
28
+
29
+ ## 约束
30
+
31
+ - `lib/client.js` 是手写 `__ModuleLoader__` bundle,无构建步骤,只能用 `React.createElement`(`h`)。
32
+ - 组件必须能在测试的 React stub 下加载(`tests/client.mjs` 现有做法)。
33
+ - 客户端改动要**重启 DSH** 才生效,改完得自己验一遍。
34
+ - 侧栏接入不依赖 `dsh-better-sidebar`:用原生 `sidebarRightTabs` + `sidebar.right.pane.tab` 插槽。
35
+
36
+ ## 方案(已选 B)
37
+
38
+ | 方案 | 代价 | 结论 |
39
+ |---|---|---|
40
+ | A 只在设置页加搜索框 | 约 150 行 | 能做,但每次要开设置 |
41
+ | **B 设置页 + 右侧栏 tab,共用一个组件** | 约 350 行 | **选中**:常驻,且与模型同源 |
42
+ | C 接 better-sidebar `registerTab` | 多一个硬依赖 | 不做:它的 tab 最后也落在原生右侧栏 |
43
+
44
+ ## 怎么实现
45
+
46
+ ### 1. 命中理由要能看见 → 引擎加一个只给面板用的开关
47
+
48
+ `search()` 增加 `args.explain === true` 时,每条命中多返回:
49
+
50
+ ```js
51
+ termHits: [{ term: '上下文', score: 15, via: 'body', count: 5 },
52
+ { term: '预算', score: 3, via: 'body', count: 1 }]
53
+ ```
54
+
55
+ `via` 取值 `name | alias | tag | body | index`,`count` 是正文出现次数。
56
+ **这只是把 `termScore` 已经在算的数摊开**,权重与排序零改动;
57
+ 开关不进工具 schema,模型永远触发不到,工具输出的 token 也不变。
58
+
59
+ ### 2. 一个只读接口
60
+
61
+ `GET /api/wiki-notes/search?q=…&limit=5&explain=1`
62
+
63
+ - 复用 `loadCorpus` 的 30s 缓存与 `fs.watch` 失效,不引入第二条读取路径。
64
+ - 直接返回 `run({ mode:'search', query, limit, explain:true })` 的结果 + `elapsedMs`。
65
+ - `q` 上限 200 字、`limit` 上限 20;超了截断而不是报错。
66
+ - 只读 GET,和 `/state` 同级,不过跨源写闸。
67
+
68
+ ### 3. 组件 `WikiSearchPanel`
69
+
70
+ - 输入框(Enter 提交)+ 结果计数行:`命中 1 / 考虑 95 · 全词命中 · 12ms`。
71
+ - 降级(OR)时那行变黄并写明「没有一条命中全部词,下面是任一词命中」。
72
+ - 每条:`页名 · 类型 · 分数` + 命中词徽章(词 + 通过哪条通道 + 次数)+「未命中全词」标记。
73
+ - 点击展开:该小节 `## 标题` + 正文 + `← [[页名]] §小节 → 相对路径`。
74
+ - 空查询:显示 `/state` 已有的规模摘要,顺带一眼看出库配没配好。
75
+
76
+ ### 4. 两处挂载
77
+
78
+ - 设置页:现有 `settings.section` 组件底部加一节「查一下」。
79
+ - 右侧栏:`ctx.inject(['sidebarRightTabs'], owner => …)`,注册
80
+ `{ id:'dsh-wiki-notes/search', kind:'wiki-notes-search', priority:'extension', title:()=>'知识库' }`
81
+ 与 `sidebar.right.pane.tab` 插槽;`package.json` 的 `dsh.client.inject` 补
82
+ `@deepseek-ai/dsh-client-ui-sidebar-right`。
83
+ - 服务不存在时静默跳过侧栏那一半,设置页照常可用。
84
+
85
+ ## 测试
86
+
87
+ - `tests/api.mjs`:`/search` 正常返回、`limit` 截断、空 `q` 400、`explain` 打开时每条命中带 `termHits`。
88
+ - 新增 `tests/explain.mjs`:`explain` 不改分数、不改排序、不加字段到默认输出(同一 query 两次对比)。
89
+ - `tests/client.mjs`:模块结构、面板组件是函数、侧栏注册代码在。
90
+ - `tests/contract.mjs`:`package.json` 的 `dsh.client.inject` **不含**侧栏模块(见下方实现记录,原方案写反了)。
91
+ - 重启 DSH 后手验:设置页搜「上下文 预算」;右侧栏 tab 同步出结果。
92
+
93
+ ## 留给实现者
94
+
95
+ - 面板的视觉细节(间距、徽章配色)按现有设置页 CSS 变量走,不新增主题。
96
+ - 命中很多时的折叠策略:默认只展示前 5 条(侧栏 8 条),计数行标出「显示前 N」,不做二次展开。
97
+
98
+ ## 实现记录(2026-11-04,1.2.0)
99
+
100
+ 三处与设计稿不同,都是实现时才发现设计稿写错/写不全:
101
+
102
+ 1. **`dsh.client.inject` 不加侧栏模块**(设计稿写反)。加了会把「侧栏模块在不在」变成整个客户端包的加载前提 —— 侧栏一缺,连设置页都进不去,正好违反本轮的故障隔离要求。改为运行时 `ctx.inject(['sidebarRightTabs'], …)` 按需取,取不到就静默跳过;`tests/contract.mjs` 钉住「不许钉进 inject」。
103
+ 2. **不引 better-sidebar**,原生 `sidebarRightTabs` + `sidebar.right.pane.tab` 就够(照 dsh-image-gen 的写法)。
104
+ 3. **不做「还有 N 条」展开**,改在计数行标「显示前 N」——面板的用途是对照模型看到什么,条数与工具默认值一致更重要。
105
+
106
+ 已验证:
107
+
108
+ - explain 不改检索:`termScore` 现在就是 `termBreakdown().score`,同一份明细既排序又当理由;拿 `git show HEAD:lib/engine.js` 的旧引擎与新引擎同跑活库(95 页),27 次查询(15 个 query × limit 3/12)+ 6 个 mode,输出 JSON 完全一致。
109
+ - `tests/explain.mjs` 34 项:6 个查询开关前后 `name|score|allTerms` 逐条相同、每条 `termHits` 各词分数之和 === 该条总分、工具 schema 与工具输出里都没有 `termHits`。
110
+ - 侧栏故障隔离:`tests/client.mjs` 用假 owner 跑「服务缺失 → 0 个面板、不抛」,设置页那份面板照常渲染。
111
+ - 全量 `node --run test` 17 个脚本全绿(新增 explain 34 项、api 增到 35 项、contract 11 项、client 增侧栏断言)。
112
+ - 活库经 `/search` 路由实测:`上下文 预算` → 命中 7 / 参与 95 / 36ms,Top1「上下文 [概念] 194 分」理由 `上下文(name:120+alias:50+body×7:21)` + `预算(body×1:3)`;`逻辑填空` → 1ms,Top1 123 分 `name:120+body×1:3`。
113
+ - 未完成:GUI 内的实际点击验收要重启 DSH 才有效(新路由 `/api/wiki-notes/search` 在运行中的宿主里还是 404)。