dsh-wiki-notes 1.6.2 → 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,194 @@
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
+
18
+ ## 1.10.0
19
+
20
+ 把「探索」这一窗补成能顺着走的:从标签走到相邻主题,从一页走到它指向的和指向它的。
21
+
22
+ ### 新 · 标签共现
23
+ - 探索 · 标签下多一块「标签共现」:每个高频标签旁边列三个跟它一起出现最多的标签,数字是共同出现的页数。
24
+ - 点邻居就是「两个词一起查」—— 检索只认字面命中,答不了「我还写过什么和它同时出现过」。
25
+ - 同一块里报「有标签 N 页 / 没标签 M 页」:只报标签分布时,一个九成页面没打标签的库看起来和整理得很好的库一样整齐。
26
+
27
+ ### 新 · 页面关联(探索 · 关系)
28
+ - 新增 `GET /links?name=<页名>`:返回这一页的出链 / 入链 / 双向 / 红链,每项带页名与文件路径。
29
+ - 界面上写页名回车即可;点任一页名顺着看那一页的链接,点「打开」交给系统默认程序。
30
+ - 入链没有反向索引,只能逐页比 —— 所以这一个数字是现算的,不像概览那些跟着扫描一起出。
31
+ - 找不到那一页回 404 带一句话:回一个空四列会被读成「这页没有链接」,而真相是「这页不在库里」。
32
+
33
+ ### 改 · 链接解析只留一份
34
+ - 概览的入链、关系窗的页面关联、红链归因,共用同一组解析函数(整名 → 别名小写 → 跳过 `index`/`log` 与自链)。
35
+ - 分开写过一次,症状是「入链 0,红链也 0」,两边各自都像是对的。现在口径只有一处。
36
+
37
+ ### 新 · 检索窗的「最近查过」
38
+ - 查成功之后留一排词(最多 8 个,同一句不重复堆),点一下重查。
39
+ - 只活在这次会话里,不落盘 —— 这是「刚查过的还热着」,不是第三本账。
40
+
41
+ ### 新 · 概览的「查看异常」
42
+ - 快捷操作多了「查看异常」:跳到探索窗并落在关系子页(`anomalyTick` 用序号,连点两次也生效)。
43
+
44
+ ### 改 · 文档预览图重出
45
+ - `docs/preview-overview.png` 用改后的真组件重渲染。
46
+
47
+ ## 1.9.0
48
+
49
+ 一级导航从五个页签收成四个动词:概览 / 检索 / 探索 / 调用记录。功能一个没删,只是「标签」和「关系」合成一个窗。
50
+
51
+ ### 新 · 知识探索窗
52
+ - 「标签」和「关系」不再是两个一级页签,进「探索」后一排子页签切换 —— 它们同属「看库的结构」,分成两个入口只会把导航撑长。
53
+ - 标签从「摆着看」变成入口:点一个标签,检索页签打开、查询框里就是那个词、结果已经查好。
54
+ - 同一个词连点两次也会重跑 —— 递下去的是序号(`seedSeq`),不是词本身;只比文本比不出「又点了一次」。
55
+
56
+ ### 新 · 概览的「使用情况」
57
+ - 概览多了第六块:模型调了几次、你自己在面板里查了几次、零命中率、今天几条、四类工具各几次。
58
+ - 读的是 `calls.jsonl` 那一本账,和「调用记录」页签同源 —— 不新建统计系统,两个数的口径就不可能分叉。
59
+ - 模型调用与你手动在面板里的检索分栏显示(`source:"model"` / `"panel"`):混在一起,「模型用了多少次知识库」就成了没法核对的数。
60
+ - 零命中率的分母只算「有命中几页这回事」的调用;一次都没查过时显示「—」而不是 0%,因为「没查过」和「查了没命中」是两句话。
61
+
62
+ ### 新 · 零命中时摆出最接近的 3 页
63
+ - 检索窗零命中时,列表位置显示宿主算好的 `nearMiss`:字面沾边百分比、有没有被这次的 `type`/`tags`/`status` 筛掉,点一条就按它的措辞再搜一遍。
64
+ - 0 命中在界面上和「库里没这块」长得一模一样,这一栏是两者唯一的区别;它只在零命中时出现,永不混进命中列表。
65
+
66
+ ### 改 · 文档预览图重出
67
+ - `docs/preview-overview.png` 用改后的真组件重渲染(六块 + 四项页签),不再是对不上界面的旧图。
68
+
69
+ ## 1.8.3
70
+
71
+ ### 撤掉「最近访问」和「页面」页签
72
+
73
+ 读笔记、改笔记、看反链,你自己的 markdown 编辑器本来就做得更好。面板里再放一份
74
+ 清单、再展开一次只读正文,只是把同一件事做第二遍 —— 而且点一行看着像导航、
75
+ 点完只是换了一段文字。所以这两块连同两条后端路由一起撤了:
76
+
77
+ - 概览少一块「最近访问」,五个窗剩三个:概览 / 标签 / 关系。
78
+ - 删掉 `GET /pages`(页面清单)与 `GET /page`(在面板里读一页),`lib/visits.js`
79
+ 与 `visits.jsonl` 一并删掉 —— 没人读的账本留着只是白写。
80
+ - 关系窗里点「枢纽页 / 孤岛」仍然能打开文件(走 `POST /open`),宿主顺手给
81
+ `hubPages` / `orphanSample` 补了 `file` 字段:只给页名的话客户端只能猜路径,
82
+ 猜错了又是一个「点了没反应」。
83
+ - 旧账本不会被回填、也不再有人读;想看历史就在 git 里翻 1.8.2。
84
+
85
+ ## 1.8.2
86
+
87
+ ### 修:点「最近访问」什么都打不开
88
+
89
+ 之前点一行只做一件事:在面板里展开那一页的正文。于是「最近访问」看着像导航,点下去却只是换了一段只读文字 —— 读得到字、改不了字,也接不上笔记软件的补全和反链。
90
+
91
+ - 现在点一行 = 用系统默认程序打开那个 `.md`(Windows `cmd /c start`、macOS `open`、Linux `xdg-open`,一律 detached,不挂住请求)。
92
+ - 想在这里看正文,点行右侧的「读」——同一个动作,两个目的分开摆。
93
+ - 「页面」清单里的行同理:点页名开文件,点「读」展开。
94
+ - 宿主新增 `POST /open`:路径一律按库根解析并校验落在库内,文件不在回 404 带一句话;打开成功也记一条访问(`source` 仍是 `panel`)。
95
+ - 测试用 `DSH_WIKI_OPEN_DRYRUN=1` 走旁路,不真弹窗;`tests/overview.mjs` 补了 13 条(库内/库外/绝对路径/文件不存在/缺参数/算不算访问)。
96
+
97
+ ## 1.8.1
98
+
99
+ ### 改:概览只做首页,页面 / 标签 / 关系各自成窗
100
+
101
+ 上一版把八块全塞在一个页签里:六块计数还没看完,榜单已经滑出视野。现在六个页签,概览排第一(进来就是它):
102
+
103
+ `概览 · 检索 · 页面 · 标签 · 关系 · 调用记录`
104
+
105
+ - 概览只留:知识库状态、页面数量、索引状态、内容问题、最近访问、快捷操作。
106
+ - 页面:全部页面清单 + 按页名筛 + 点一行读正文,一进这个窗就开始读清单,不必再点一次。
107
+ - 标签:出现最多的 12 个标签,点一下当查询词。
108
+ - 关系:枢纽页、孤岛页、最该先补的页 —— 「知识关系」在这扇窗里。
109
+ - 四个窗是**同一个组件的四种 view**,不是四个组件各读一遍 `/state`:四份 state 迟早不同步。
110
+
111
+ ### 改:配色提高对比度
112
+
113
+ 设计稿的次级文字 `#a89279`、60% 白卡片,放在 DSH 的暖白画布上糊成一片,数字看着像禁用态。现在:
114
+
115
+ - 正文 `#2b2724`(原 `#3d3d3d`),数字与标题同色;
116
+ - 次级文字 `#6f6558`,榜单里的值 `#4a423a`;
117
+ - 卡片实底 `#fffdf9` + 1px `rgba(168,152,133,0.55)` 描边,hover 边框转 moss `rgba(90,122,107,0.55)`;
118
+ - 链接 `#4f7d99`(原 `#7ba0b8`),正文块 `#f7f2ec` 加细边。
119
+
120
+ 2px 直角、无阴影、700ms 过渡、字重只用 200/300/400 这几条设计稿纪律没变,`tests/client.mjs` 把它们和上面几个色值一起钉住了。
121
+
122
+ ## 1.8.0
123
+
124
+ ### 新:左侧栏的「概览」变成一页真账
125
+
126
+ 以前这个页签只是把设置页那张状态卡搬过来。现在它回答的是「这个库现在什么状况、我下一步该看什么」:
127
+
128
+ - **知识库状态**:已连接 / 未配置 / 不可用,扫的是哪个目录,发现多少个文件、读到多少页。
129
+ - **页面数量**:可检索页面、资料页面、小节数、体积。「可检索」= 读进正文的页,超大未读的不算。
130
+ - **索引状态**:最近一次扫描的时刻(换算成本地时间)、耗时、发现与跳过的文件数。
131
+ - **内容问题**:红链几处、涉及几页,以及不可读取、超大页面、重名的计数。
132
+ - **最近访问**:最近打开过的 5 篇,标出是「· 你」还是「· 模型」点开的,点一行直接读。
133
+ - **快捷操作**:搜索、查看全部页面、刷新、重新扫描。
134
+ - **主题与标签**、**知识关系**:出现最多的 12 个标签(点一下就当查询词);枢纽页(被引最多)、孤岛页(没人链过来)、最该先补的页(断链落点)。
135
+
136
+ 数字全部由宿主算好再送来(`GET /state` 的 `overview`,与 `stats` 同源同一次扫描),前端不做二次计算 —— 两处各算一遍,迟早算出两个答案。
137
+
138
+ ### 新:访问记录 `visits.jsonl`
139
+
140
+ 模型读一页(`wiki_recall` 的 `page` 模式)和你在面板里点开一页(`GET /page`)都记一条,`source` 分开写,所以面板能分清「· 你」和「· 模型」。和调用记录同一套纪律:追加写、失败只 warn、有上限、同一页只留最新一条。
141
+
142
+ ### 改:概览页签换了一套排版
143
+
144
+ 照 `design (1).md` 的北欧极简:Inter、字重只用 200/300/400、卡片 2px 直角 + 无阴影 + hover 只改边框、过渡 700ms。样式限定在 `.wn-page` 作用域内的 `.hx-*` 前缀,不往 DSH 自己的界面里漏。
145
+
146
+ ### 修:「最近扫描」的时间少了八小时
147
+
148
+ `scannedAt` 是 UTC(`toISOString()`),之前一律切字符串显示,于是永远比真实时间早 8 小时。现在带时区的值换算成本地,账本里那种本地墙钟原样切 —— 两套格式分开处理,`tests/client.mjs` 各钉了一条。
149
+
150
+ ### 新:面板里能浏览全部页面
151
+
152
+ 「查看全部页面」列出每页的类型、小节数、是否超大未读,可按页名筛;点一行读正文(含 citation)。读不到时说明是超大未读还是文件读不了,不会假装页是空的。
153
+
154
+ ## 1.7.1
155
+
156
+ ### 修:介绍页那张预览图,之前是画的,现在是渲染出来的
157
+
158
+ - 换成 `docs/preview.png`。上一版是手绘 SVG,和真界面对不上 —— 页签名、卡片刻度、右栏内容都是我当时想象的,市场上点开一比就露馅。
159
+ - 现在由 `node tools/preview.mjs --only page` 取 `lib/client.js` 里**真的组件和真的样式表**渲染成 HTML,再用无头 Chromium 截一张图。`--data` 喂的是中性样例(`示例页面一` 这类),不会把库里的真实页面名跟着截图出海。
160
+ - 顺手修了预览器两处「说了没做」:SVG 属性不在白名单里(`stroke` / `d` / `viewBox` 被丢掉,图标画出来是空壳)、文件头注释写着 `--data` 参数但其实没实现。
161
+
162
+ ### 修:调用记录里「其中 partial / insufficient 分组」那一行没对齐
163
+
164
+ - 它原来靠 `margin-left` 缩进,右边那条边跟着一起缩,于是数字和上面三项的右对齐断了。改成缩内边距(`padding-left:26px`),外框宽度不动,虚线边框表示从属关系。
165
+ - `tests/client.mjs` 加了一条守卫:分组行再出现 `margin-left` 就报错。
166
+
167
+ ## 1.7.0
168
+
169
+ ### 新:左侧栏的「知识库」页
170
+
171
+ - **左侧栏多了一本书**:点进去是一整页工作台,三个页签 —— 检索 / 概览 / 调用记录。它和「插件」「自动化任务」平级,占满主列,切走即卸载(不在后台留轮询)。用的是 DSH 的面板机制(`sidebar.panellist` 给图标,同一个 id 作 `main` 的 key 给整页),服务不在就静默跳过,设置页照常可用。
172
+ - **概览页签只显示不改**:库路径、页面 / 小节 / 没读到的文件、扫描耗时、实时同步、提示词状态,加「刷新」「重新扫描」。改路径和提示词仍然回设置页 —— 两个地方都能存配置,人就会在错的地方改。
173
+ - **设置页标题右边加一颗「打开知识库页」**,配置和看库不用来回切。
174
+
175
+ ### 新:插件在市场里终于像个插件了
176
+
177
+ - `icon.svg`(一本书)、`locale/zh.json`、`locale/en.json`:市场卡片不再退化成包名加一句中英混排的长描述,标题是「知识库」、描述是白话。
178
+ - 详情页首屏加了预览图 `docs/preview.svg`(手绘 SVG,不依赖截图工具)和三处入口的表格:左侧栏那本书 / 设置 → 知识库 / 右侧栏「知识库」页签。
179
+
180
+ ### 检索(`wiki_recall`)
181
+
182
+ - **零命中不再是「没有」两个字**:返回体多一个 `nearMiss`,最多 3 页,每页带字面覆盖率、页名,以及 `filtered` —— `true` 表示这次是被自己的 `type`/`tags`/`status` 筛掉的,不是库里没有。渲染成一行「最接近的 3 页:xxx(字面沾边 42%,被这次的过滤条件筛掉)」,后面接一句「这些只是字面最沾边,不等于它们回答了问题」。
183
+ - 有命中时 `nearMiss` 恒为空数组,永不混进 `hits`:命中数不会从 0 变成 3。这条在 `tests/nearmiss.mjs` 里看着。
184
+
185
+ ### 调用记录(账本)
186
+
187
+ - **账本从 8 个字段扩到 13 个**:新增 `status`(这次结果的状态)、`fallback`(`coverage` 字面兜底 / `or` 放宽 OR / 空=正常)、`considered`(参与比对的页数)、`warnings`(警告条数)、`topScore`(最高分)。原来的账本只记「0 命中」,复盘的人分不清「该换词」「该放开过滤」「该修库路径」—— 三种下一步长得一模一样。
188
+ - **一页 10 条**:200 行堆成一堵墙没人看。翻页在客户端切片,不发新请求。
189
+ - **时间列带日期**:原来只显示 `HH:MM`,跨天翻页分不清昨天和刚才;现在两行显示(`MM-DD` + 时刻),跨天那一行日期加深加粗。
190
+ - **新增「诊断」列**:`字面兜底` / `放宽 OR` / 非 `ok` 的 `status` 直接标出来;「命中」格悬停显示「参与 N 页 · 最高 X 分」。
191
+ - **新增「反复打空的查询」卡**:同一句问话查了 3 次还是 0 命中,说明不是运气差 —— 要么库里真没有,要么说法对不上。按问法归并、按次数降序,最多列 5 条。
192
+
5
193
  ## 1.6.2
6
194
 
7
195
  ### 检索与取页(`wiki_recall` 的 7 个 mode)
package/README.md CHANGED
@@ -2,9 +2,21 @@
2
2
 
3
3
  [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4B6EF5)](https://github.com/deepseek-ai)
4
4
 
5
- **给你那堆 Markdown 笔记,接上四个能用的工具:查得到、读得出、核得住、看得见。**
5
+ **把一整个 Markdown 笔记库,变成模型能直接查的四个只读工具。**
6
6
 
7
- 为 [DeepSeek Harness](https://github.com/deepseek-ai) 做的只读检索插件。旧的流程是五步:读总览 → 读索引 → 敲命令搜 → 打开那页 → 追它的来源。现在一次调用就把**命中小节的完整正文 + 出处**返回,模型自己接着答。
7
+ ![知识库面板:左侧栏那本书点进去,是「检索 / 概览 / 调用记录」三页签;结果直接给出命中小节的正文和出处](docs/preview.png)
8
+
9
+ 它是干这个的:你有一堆笔记(Obsidian 库、导出的文档目录都行),模型要回答的问题,答案就写在里面。没这个插件,它得自己走五步 —— 读总览 → 读索引 → 敲命令搜 → 打开那页 → 追来源,还未必读对。装上之后它调一次 `wiki_recall`,拿回来的就是**命中小节的完整正文 + 出处**,接着就能答。
10
+
11
+ **三个入口,同一份数据:**
12
+
13
+ | 在哪 | 干什么 |
14
+ | --- | --- |
15
+ | 左侧栏最上面那本书 | 整页工作台:检索 / 概览 / 调用记录 |
16
+ | 设置 → 知识库 | 配库路径、看扫描状态 |
17
+ | 右侧栏「知识库」页签 | 边聊边查,不离开对话 |
18
+
19
+ 只读、不联网、不外发笔记;零第三方依赖,装完就能用。为 [DeepSeek Harness](https://github.com/deepseek-ai) 而做。
8
20
 
9
21
  > 中文文档从下面开始。实测:73 页的库,旧流程单次 ≈ 18.7k 字符,新流程 ≈ 2.5k。
10
22
 
@@ -15,6 +27,7 @@
15
27
  | 你想知道 | 直接跳 |
16
28
  | --- | --- |
17
29
  | 这插件到底能干什么 | [四个工具](#四个工具) |
30
+ | 左侧栏那本书点开是什么 | [知识库页(左侧栏)](#知识库页左侧栏) |
18
31
  | 我要先装上试试 | [装](#装) · [配](#配) |
19
32
  | 我自己的笔记该怎么写 | [库该长什么样](#库该长什么样) |
20
33
  | 检索为什么这么打分 | [检索质量](#检索质量) |
@@ -60,6 +73,10 @@
60
73
 
61
74
  每条命中带 `kind`(note / raw-summary / source)、`sources`(来源数,**证据强度的唯一可靠代理**)、`status`、`gist`、`section`(命中小节正文,不是 90 字片段)、`citation`(`← [[页名]] §小节 → 路径`)、`brokenLinks`(指向不存在页的双链 = 「库里没依据」的硬信号),以及 `updated` 后面的**距今天数**(超过 180 天标「可能已过时」——三年前的结论和上周的长得一样,模型需要这个信号)。`overview` 额外给三项健康信号:index 有磁盘无、磁盘有 index 无、跨目录重名。
62
75
 
76
+ 零命中时不是一句「没有」就完了:返回里多一个 `nearMiss`(最多 3 页),每页带字面覆盖率、页名,以及 `filtered` —— `true` 表示**这次是你自己筛掉的**(类型/标签/状态),不是库里没有。渲染出来是一行「最接近的 3 页:xxx(字面沾边 42%,被这次的过滤条件筛掉)」,后面跟一句「这些只是字面最沾边,不等于它们回答了问题」。
77
+
78
+ 有命中时 `nearMiss` 恒为空数组:它只做诊断,永不混进 `hits`,也不会让「命中 0 页」变成「命中 3 页」。
79
+
63
80
  ### `wiki_context` —— 带证据的上下文
64
81
 
65
82
  要引用笔记原文回答、或需要知道「有没有依据 / 依据够不够 / 哪里是缺口」时用它,而不是自己连续调 `wiki_recall`。
@@ -73,6 +90,10 @@
73
90
 
74
91
  同时返回 `evidence`(证据页,含分级、支撑了哪个槽位)、`missing`(缺什么、为什么缺)、`conflicts`(冲突候选,**未裁决,别当成已确认的结论**)、`answer.contract_text`(给回答的约束:必须披露缺口、不得超出证据、引文须原文),以及一个 `context_id`。模型看到的渲染文本里,每张证据页最多再附 2 条原文引文(每条按槽位标注、裁到 220 字);JSON 结构不变,引文仍是页面原文子串,不是插件替你概括的。
75
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
+
76
97
  ### `wiki_verify` —— 核验回答
77
98
 
78
99
  写完答案后自查(尤其含数字、范围、年份、题量分值这类主张时)用它。参数:`context_id` + `answer`(可选 `observe_id`,一般不用传,插件会自动带上)。
@@ -97,14 +118,23 @@
97
118
 
98
119
  在设置页的「知识库」里切到第二个页签。模型和面板**每一次**查库都会记一行,回答的是「我这句问话,它到底查了没有、查到没有」。
99
120
 
100
- 三格数字(今日调用 / 命中率 / 零命中)+ 一张表(时间 · 来源 · 工具 · 模式 · 问题 · 命中 · 耗时 · 成败)+ 筛选(全部 / 模型 / 面板、只看零命中;选中项有高亮与 `aria-pressed`)。页面每 2 秒自己刷新;错误按 400 / 403 / 500 给出下一步并可重试。
121
+ 三格数字(今日调用 / 命中率 / 零命中)+ 一张表,列是:**时间(日期 + 时刻,跨天那行日期加深)· 来源 · 工具 · 模式 · 问题 · 命中 · 耗时 · 诊断 · 成败**。筛选有「全部 / 模型 / 面板」与「只看零命中」,选中项有高亮与 `aria-pressed`。表按 10 条一页翻,不把 200 行堆成一堵墙。
122
+
123
+ 表格下面还有一张「**反复打空的查询**」:同一句问话被查了 3 次还是 0 命中,说明不是运气差,要么库里真没有,要么说法对不上。这张卡按问法归并、按次数降序,最多列 5 条。
101
124
 
102
- 账本落在插件目录旁的 `calls.jsonl`(已在 `.gitignore` 里),只记 8 个字段:
125
+ 页面每 2 秒自己刷新;错误按 400 / 403 / 500 给出下一步并可重试。
126
+
127
+ 账本落在插件目录旁的 `calls.jsonl`(已在 `.gitignore` 里),记 13 个字段:
103
128
 
104
129
  ```
105
130
  ts · source · tool · mode · query · hits · ms · ok
131
+ status · fallback · considered · warnings · topScore
106
132
  ```
107
133
 
134
+ 前 8 个是「发生了什么」,后 5 个是「为什么是这样」:`status` 是这次结果的状态(`ok` / `partial` / `no_match` / `unconfigured` / `error`),`fallback` 说明靠哪层兜底(`coverage` 字面兜底 / `or` 放宽 OR / 空 = 正常),`considered` 是参与比对的页数,`warnings` 是警告条数,`topScore` 是最高分。
135
+
136
+ **没有这 5 个字段的时候,「0 命中」是一句没法追责的话**:换词重搜、放开过滤、修库路径,三种下一步长得一模一样。现在「命中」格悬停会显示「参与 N 页 · 最高 X 分」,诊断列直接标出「字面兜底 / 放宽 OR」。
137
+
108
138
  **页面路径、正文、答案一律不进账本。** `query` 截到 120 字。
109
139
 
110
140
  几条口径值得写清楚:
@@ -191,11 +221,68 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
191
221
 
192
222
  浏览器半侧走同源 HTTP `/api/wiki-notes/*`(`state` / `search` / `check` / `save` / `rescan`),不碰 RPC。
193
223
 
224
+ 标题右边那颗「**打开知识库页**」就是跳到下面这一页 —— 配置和看库分在两处,跳一次比来回切设置省事。
225
+
226
+ ---
227
+
228
+ ## 知识库页(左侧栏)
229
+
230
+ 左侧栏最上面那本书,点进去是一整页工作台(不是弹层、不是设置里的一个 tab)。它是 DSH 的**主面板**之一,和「插件」「自动化任务」平级 —— 占满主列,切走会卸载,所以来回切不攒后台轮询。**概览是首页**,落地先看「这个库现在什么状况」,再决定去查什么:
231
+
232
+ | 页签 | 里面有什么 |
233
+ | --- | --- |
234
+ | 概览 | 状态 / 页面数量 / 索引 / 内容问题 / 使用情况 / 快捷操作,见下 |
235
+ | 检索 | 和右侧栏那个面板同一份组件(`compact:false`,宽屏下正文不再截高),能自己搜、看命中理由、复制出处 |
236
+ | 探索 · 标签 | 最常出现的 12 个标签(点一下带着词跳检索)+ 标签共现 + 有/没标签的页数 |
237
+ | 探索 · 关系 | 枢纽页、孤岛页、最该先补的页,加上任意一页的出链 / 入链 / 双向链 |
238
+ | 调用记录 | 就是上面那份账本,含「反复打空的查询」 |
239
+
240
+ 一级页签只留四个动词:看状态(概览)、查内容(检索)、看结构(探索)、看模型怎么用(调用记录)。标签和关系都是「看结构」,合成一个窗、用一排子页签切换 —— 一级导航撑长了,多出来的不是信息。
241
+
242
+ ![概览页签:左边一串数字全是宿主算好的,这一页只负责摆出来](docs/preview-overview.png)
243
+
244
+ 概览按「先看库有没有毛病,再决定查什么」排,只摆这六块:
245
+
246
+ | 块 | 内容 | 为什么在这一块 |
247
+ | --- | --- | --- |
248
+ | 知识库状态 | 已连接 / 未配置 / 不可用,扫的是哪个目录,发现 N 个文件读到 M 页 | 先分清「搜不到」和「压根没配上」 |
249
+ | 页面数量 | 可检索页面、资料页面、小节数、体积 | 「可检索」是读进正文的页,超大未读的不算在内 |
250
+ | 索引状态 | 最近一次扫描的时刻、耗时、发现与跳过的文件数 | 见过改了笔记却查不到的,多半是没重扫 |
251
+ | 内容问题 | 红链几处、涉及几页,不可读取、超大页面、重名 | 断链是库里的洞,不修就永远查不到 |
252
+ | 使用情况 | 模型调了几次、你自己在面板里查了几次、零命中率、今天几条 | 与「调用记录」页签同一本账,两个数不可能对不上 |
253
+ | 快捷操作 | 搜索、调用记录、查看异常、刷新、重新扫描 | 这一页的动词就够,其余回设置页 |
254
+
255
+ 标签、关系同住「探索」窗(里面一排子页签切换),不挤在首页 —— 五块计数还没看完,榜单已经滑出视野了。**一个组件出三个窗**(`view` 区分,探索窗里再分子页),不是三个组件各读一遍 `/state`;同一个数在两处出现,迟早会算出两个答案。
256
+
257
+ 标签是入口不是装饰:点一个标签,检索页签打开、查询框里就是那个词、结果已经查好。同一个词连点两次也会重跑(递下去的是序号,不是词本身)—— 只比文本比不出「又点了一次」。
258
+
259
+ **标签共现**(探索 · 标签的第二块):每个高频标签旁边列三个「跟它一起出现最多」的标签,数字是共同出现的页数,点一下就是「两个词一起查」。检索只认字面命中,答不了「我还写过什么和它同时出现过」—— 这一栏补的就是这个问题。同一页里重复写同一个标签只算一次;页面数分母不带超大未读页,所以「没标签 N 页」是真的没打标签,不是没读。
260
+
261
+ **页面关联**(探索 · 关系的第二块):写一个页名回车,得到这一页的**出链 / 入链 / 双向 / 红链**。点任一页名 = 看那一页的链接(顺着走),点「打开」= 交给系统默认程序。入链没有反向索引,只能逐页比一遍 —— 所以这一个数字是**现算**的,不像概览那些跟着扫描一起出。三条路由(概览入链、页面关联、红链归因)共用同一组解析函数(整名命中 → 别名小写 → 跳过 `index`/`log`、跳过自链),口径只留一份:分开写过一次,症状是「入链 0,红链也 0」,两边各自都像是对的。
262
+
263
+ **找不到这一页就 404。** 回一个空的四列会被人读成「这页没有链接」,而真相是「这页不在库里」—— 这两种情况的下一步动作完全不同。
264
+
265
+ **「使用情况」读的是调用账本那一本,不是另建一套统计。** 模型自己调的(`source:"model"`)和你手在面板里查的(`source:"panel"`)分开记两栏 —— 混在一起,「模型用了多少次知识库」就成了没法核对的数。零命中率的分母只算「有命中几页这回事」的调用,一次都没查过时显示「—」而不是 0%:没查过和查了没命中是两句话。四类工具没调过就摆 0 —— `wiki_observe` 是 0 意味着「没观察」,不是「观察了没问题」。
266
+
267
+ **这些数字全部由宿主算好再送过来,前端一个 `reduce` 都没有。** `GET /state` 里的 `overview` 与 `stats` 同源同一次扫描(`overviewOf(corpus)`),所以概览和状态卡不可能对不上;「可检索页面 = 全部 − 超大未读」这类减法也写在宿主,而不是在渲染时现算 —— 两个地方各算一遍,迟早会算出两个答案。
268
+
269
+ **这一页不替你读笔记。** 1.8.2 之前概览里有「最近访问」、页签里有「页面清单」,点一行把正文拉进面板里那段只读 `<pre>`;现在都撤了 —— 读笔记、改笔记、看反链,你自己的 markdown 编辑器(Obsidian 之类)本来就做得更好,面板再抄一份只是把同一件事做第二遍。关系窗里点一行(枢纽页 / 孤岛),仍然走 `POST /open` 交给系统默认程序(Windows 是 `cmd /c start`,macOS `open`,Linux `xdg-open`)—— 那里点的是「去那一页看看」,不是「在这里读一遍」。
270
+
271
+ `/open` 只认落在库根之内的路径(相对路径按库根解析),文件不在了回 404 带一句话 —— 这条路由要是能开任意路径,它就成了「本机任意文件 + 系统关联程序」的执行口,而它只是个看笔记的按钮。
272
+
273
+ 概览只显示、不改:改路径和提示词仍然回设置页 —— 这里出现两颗「保存」按钮的话,人就会在错的地方改配置。
274
+
275
+ 排版照 `design (1).md` 那套北欧极简:Inter、字重只用 200/300/400、卡片 2px 直角 + 无阴影 + hover 只改边框、过渡 700ms。样式全部限定在 `.wn-page` 作用域内的 `.hx-*` 前缀 —— 插件的 CSS 是往 `document.head` 里塞一个 `<style>`,不带作用域会漏进 DSH 自己的界面。
276
+
277
+ **对比度是照着设计稿又改了一遍的地方。** 设计稿的次级文字是 `#a89279`、卡片是 60% 白 —— 那套配色放在落地页上很轻,放进 DSH 的暖白画布就糊成一片,数字看着像禁用态。现在正文压到 `#2b2724`、次级文字 `#6f6558`、卡片实底 `#fffdf9` + 更实的描边,2px 直角与 700ms 过渡照旧(`tests/client.mjs` 把这几个值钉住了,免得哪天又被「调淡一点」改回去)。
278
+
279
+ 图标是一本书(`icon.svg` 同一份线稿,颜色吃 `currentColor`,选中时线粗一点),不额外装图标库。
280
+
194
281
  ---
195
282
 
196
283
  ## 检索面板
197
284
 
198
- 设置页里有一张「试一试检索」的卡,右侧栏另有一个「知识库」页签 —— 同一份组件,`compact` 控制密度。用途只有一个:**让人自己看见检索依据**,不必等模型说它查到了什么。
285
+ 同一个检索面板出现在三处:设置页的「试一试检索」卡、右侧栏的「知识库」页签、左侧栏知识库页的「检索」页签 —— 同一份组件,`compact` 控制密度。用途只有一个:**让人自己看见检索依据**,不必等模型说它查到了什么。
199
286
 
200
287
  输入关键词回车,上面一行是「命中 7 页(显示前 5)· 参与打分 95 页 · 36 ms · 库 95 页」;紧跟一行是**查询诊断**:`实际用的词` 后面逐个列出这次真正参与打分的词,一页都没沾到的词会标成「没沾到」,末尾写清这次是「全词都要(AND)」还是「命中任一(OR)」。中文不分词,写整句时这一行通常只剩一个词 —— 这是最直观的提示:换词,而不是加词。
201
288
 
@@ -206,6 +293,10 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
206
293
  - 该条命中的小节标题与正文(正文里出现过的查询词带淡黄底纹),末尾附 citation,右侧一个复制按钮 —— 把「哪句话支撑了这条」直接抄进对话里;
207
294
  - 查询降级成「命中任一」或「字面覆盖率兜底」时,计数行旁边会按实际路径分别黄字提示。
208
295
 
296
+ 零命中时,列表位置会摆出**最接近的 3 页**:字面沾边多少百分比、有没有被这次的 `type`/`tags`/`status` 过滤筛掉,点一条就按它的措辞再搜一遍。这一栏只在零命中时出现,永不混进命中列表 —— 它回答的是「是库里没这块,还是我筛掉了它」,而不是假装自己命中了。
297
+
298
+ **最近查过**:查成功之后,输入框下面留一排词(最多 8 个,同一句不重复堆),点一下重查。它只活在这次会话里、不落盘 —— 这是「刚查过的还热着」,不是第三本账;写盘就得连带处理清理、隐私和跨设备不一致。
299
+
209
300
  **键盘**:输入框防抖 350ms(够 2 个字符才查),`Enter` 立刻查,`Esc` 清空,`↑`/`↓` 在结果里移动高亮并展开对应条目;任意位置按 `/` 或 `Ctrl/⌘ + K` 直接跳到输入框。查询进行中列表上方显示「检索中…」。输入框右边有「复制词」—— 查出来的说法常常要拿去别处再查一遍,省得重敲;citation 那行的复制按钮同理(键盘走过去会看到焦点框)。
210
301
 
211
302
  **覆盖统计**在设置页的状态卡下面:`发现 102 个文件 → 读到 95 页 / 677 个小节`,后面是总体积、跳过 / 读不了 / 超大未读 / 目录与 stat 失败的计数(非 0 时标黄)、最新修改时间、本次扫描耗时,以及这次实际扫的目录(自动下钻过时它和配置里的路径不是同一个)。
@@ -220,7 +311,7 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
220
311
 
221
312
  > 这条踩过一次:字段先加进了 `run()` 的返回值,但模型拿到的是 `renderValue()` 渲染出的文本 —— 不写进渲染,模型就等于没拿到。`tests/status.mjs` 现在有两条断言看着它(有漏词要出现、没漏词不许出现)。
222
313
 
223
- 侧栏是可选能力:`ctx.inject(['sidebarRightTabs'], …)` 运行时按需取,服务不在就静默跳过,设置页照常可用;`dsh.client.inject` 刻意不钉侧栏模块(钉了会把「侧栏在不在」变成整个客户端包的加载前提)。`tests/contract.mjs` 守着这两条。
314
+ 侧栏是可选能力:`ctx.inject(['sidebarRightTabs'], …)` 运行时按需取,服务不在就静默跳过,设置页照常可用;`dsh.client.inject` 刻意不钉侧栏模块(钉了会把「侧栏在不在」变成整个客户端包的加载前提)。`tests/contract.mjs` 守着这两条。左侧栏那本书同理:`sidebar.panellist` + `main` 两个注入都是运行时按需取,`layout` 服务缺了只是「打开知识库页」这颗按钮不出现。
224
315
 
225
316
  接口:`GET /api/wiki-notes/search?q=上下文 预算&limit=5`,`q` 截到 200 字,`limit` 夹在 1–12,缺 `q` 返回 400。
226
317
 
@@ -306,6 +397,8 @@ lib/client.js 设置页 + 检索面板 + 右侧栏页签(手写 bundle,无
306
397
  bin/cli.mjs 命令行,不装插件也能跑
307
398
  tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
308
399
  tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
400
+ tools/verify-host.mjs 宿主实机验收:--self 自己起个真 HTTP 服务打 10 项探针,--port 探已在跑的 DSH
401
+ tools/verify-bridge.mjs 真管线体检:起一次 Python 桥,断言两个引擎都活着、没被标降级
309
402
  docs/库结构.md 库结构约定(这份才是一手文档)
310
403
  docs/README.md 文档导航页
311
404
  CHANGELOG.md 版本变更记录
@@ -326,6 +419,9 @@ WIKI_ROOT="/path/your/wiki" node tests/local/recall.mjs # 质量评测:Recal
326
419
  npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
327
420
  node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
328
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
329
425
  ```
330
426
 
331
427
  `tests/local/` 那套要先把 `queries.example.json` 复制成 `queries.json` 再按自己的库改(`expect` 写「必须进前 5 的页名」,由人标,不依赖任何旧引擎的输出)。基线文件 `ab_baseline.json` 也是本地产物,重导用 `python ab_export.py > ab_baseline.json`。
Binary file
Binary file
package/icon.svg ADDED
@@ -0,0 +1,4 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none" stroke="#4B6EF5" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
2
+ <path d="M18 11.2c-2.3-1.7-5.2-2.4-8.6-2.4v17.4c3.4 0 6.3.7 8.6 2.4 2.3-1.7 5.2-2.4 8.6-2.4V8.8c-3.4 0-6.3.7-8.6 2.4Z"/>
3
+ <path d="M18 11.2v17.2"/>
4
+ </svg>
package/lib/calls.js CHANGED
@@ -6,7 +6,7 @@
6
6
  * 坏行跳过、写失败不抛)跟检索逻辑一点关系都没有。
7
7
  *
8
8
  * 三条铁律:
9
- * 1. 只记白名单里的 8 个字段 —— 页面路径、正文、答案一律不进账本。
9
+ * 1. 只记白名单里的 13 个字段 —— 页面路径、正文、答案一律不进账本。
10
10
  * 2. 记账是旁路 —— 写文件失败只 warn,绝不改变工具返回值。
11
11
  * 3. 读的时候只认尾部 —— 账本会长到几千行,没人需要为了看一眼今天的调用
12
12
  * 把整个文件解析一遍。
@@ -17,9 +17,17 @@ export { MAX_LINES, KEEP_LINES, TAIL_BYTES, lineCountOf } from './jsonl-store.js
17
17
  import { MAX_LINES, KEEP_LINES } from './jsonl-store.js'
18
18
  import { clipChars } from './text.js'
19
19
 
20
- /** 账本只认这 8 个字段。顺序就是表头顺序。 */
21
- export const CALL_FIELDS = ['ts', 'source', 'tool', 'mode', 'query', 'hits', 'ms', 'ok']
22
-
20
+ /** 账本只认这 13 个字段。顺序就是表头顺序。 */
21
+ export const CALL_FIELDS = [
22
+ 'ts', 'source', 'tool', 'mode', 'query', 'hits', 'ms', 'ok',
23
+ // 后加的五项只为回答一个问题:这次为什么没命中(或命中得勉强)。
24
+ // 前 8 项能数出「命中率 27%」,但说不出那 27% 该怪词、怪库,还是怪过滤。
25
+ 'status', 'fallback', 'considered', 'warnings', 'topScore',
26
+ ]
27
+
28
+ /** status / fallback 截断长度。它们是短枚举,不该出现长文本。 */
29
+ const STATUS_MAX = 24
30
+ const FALLBACK_MAX = 12
23
31
  /** query 截断长度。一条记录撑到几十 KB 只会有害。 */
24
32
  export const QUERY_MAX = 120
25
33
  /** 内存里留最近多少条 —— 文件读不出来时的兜底。 */
@@ -59,6 +67,11 @@ export function normalizeEntry(raw) {
59
67
  // 混进命中率的分母里,命中率被系统性地压低。
60
68
  const hits = raw.hits === null || raw.hits === undefined ? Number.NaN : Number(raw.hits)
61
69
  const ms = raw.ms === null || raw.ms === undefined ? Number.NaN : Number(raw.ms)
70
+ // 诊断字段与 hits 同一口径:拿不到就是 null,不拿 0 冒充。
71
+ // 「0 页参与检索」和「不知道几页参与」在复盘时是完全不同的两句话。
72
+ const considered = raw.considered === null || raw.considered === undefined ? Number.NaN : Number(raw.considered)
73
+ const warnings = raw.warnings === null || raw.warnings === undefined ? Number.NaN : Number(raw.warnings)
74
+ const topScore = raw.topScore === null || raw.topScore === undefined ? Number.NaN : Number(raw.topScore)
62
75
  return {
63
76
  ts: typeof raw.ts === 'string' && raw.ts !== '' ? raw.ts : stampNow(),
64
77
  source: raw.source === 'panel' ? 'panel' : 'model',
@@ -68,6 +81,13 @@ export function normalizeEntry(raw) {
68
81
  hits: Number.isFinite(hits) ? Math.max(0, Math.trunc(hits)) : null,
69
82
  ms: Number.isFinite(ms) ? Math.max(0, Math.trunc(ms)) : null,
70
83
  ok: raw.ok !== false,
84
+ // status 是引擎给出的「这次能不能用」,fallback 是「用到哪一层兜底」。
85
+ // 两者合起来才回答「为什么零命中」——只有 hits=0 时,没人知道该改什么。
86
+ status: typeof raw.status === 'string' ? clipChars(raw.status, STATUS_MAX) : '',
87
+ fallback: typeof raw.fallback === 'string' ? clipChars(raw.fallback, FALLBACK_MAX) : '',
88
+ considered: Number.isFinite(considered) ? Math.max(0, Math.trunc(considered)) : null,
89
+ warnings: Number.isFinite(warnings) ? Math.max(0, Math.trunc(warnings)) : null,
90
+ topScore: Number.isFinite(topScore) ? Math.round(topScore) : null,
71
91
  }
72
92
  }
73
93