dsh-wiki-notes 1.6.1 → 1.10.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 +195 -0
- package/README.md +112 -20
- package/bin/cli.mjs +2 -2
- package/docs/preview-overview.png +0 -0
- package/docs/preview.png +0 -0
- package/docs//345/272/223/347/273/223/346/236/204.md +1 -1
- package/examples/sample-wiki//350/265/204/346/226/231-sources//346/237/220/350/257/276/347/250/213/347/254/254/344/270/211/350/256/262/302/267/350/265/204/346/226/231/346/221/230/350/246/201.md +1 -1
- package/icon.svg +4 -0
- package/lib/calls.js +24 -4
- package/lib/client.js +1409 -17
- package/lib/corpus.js +3 -1
- package/lib/engine.js +116 -15
- package/lib/index.js +425 -7
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +10 -5
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,201 @@
|
|
|
2
2
|
|
|
3
3
|
本文件的体例:只记「对使用者有影响的行为变化」,不记内部重构。版本号遵循 semver,`0.x` 阶段不承诺兼容。
|
|
4
4
|
|
|
5
|
+
## 1.10.0
|
|
6
|
+
|
|
7
|
+
把「探索」这一窗补成能顺着走的:从标签走到相邻主题,从一页走到它指向的和指向它的。
|
|
8
|
+
|
|
9
|
+
### 新 · 标签共现
|
|
10
|
+
- 探索 · 标签下多一块「标签共现」:每个高频标签旁边列三个跟它一起出现最多的标签,数字是共同出现的页数。
|
|
11
|
+
- 点邻居就是「两个词一起查」—— 检索只认字面命中,答不了「我还写过什么和它同时出现过」。
|
|
12
|
+
- 同一块里报「有标签 N 页 / 没标签 M 页」:只报标签分布时,一个九成页面没打标签的库看起来和整理得很好的库一样整齐。
|
|
13
|
+
|
|
14
|
+
### 新 · 页面关联(探索 · 关系)
|
|
15
|
+
- 新增 `GET /links?name=<页名>`:返回这一页的出链 / 入链 / 双向 / 红链,每项带页名与文件路径。
|
|
16
|
+
- 界面上写页名回车即可;点任一页名顺着看那一页的链接,点「打开」交给系统默认程序。
|
|
17
|
+
- 入链没有反向索引,只能逐页比 —— 所以这一个数字是现算的,不像概览那些跟着扫描一起出。
|
|
18
|
+
- 找不到那一页回 404 带一句话:回一个空四列会被读成「这页没有链接」,而真相是「这页不在库里」。
|
|
19
|
+
|
|
20
|
+
### 改 · 链接解析只留一份
|
|
21
|
+
- 概览的入链、关系窗的页面关联、红链归因,共用同一组解析函数(整名 → 别名小写 → 跳过 `index`/`log` 与自链)。
|
|
22
|
+
- 分开写过一次,症状是「入链 0,红链也 0」,两边各自都像是对的。现在口径只有一处。
|
|
23
|
+
|
|
24
|
+
### 新 · 检索窗的「最近查过」
|
|
25
|
+
- 查成功之后留一排词(最多 8 个,同一句不重复堆),点一下重查。
|
|
26
|
+
- 只活在这次会话里,不落盘 —— 这是「刚查过的还热着」,不是第三本账。
|
|
27
|
+
|
|
28
|
+
### 新 · 概览的「查看异常」
|
|
29
|
+
- 快捷操作多了「查看异常」:跳到探索窗并落在关系子页(`anomalyTick` 用序号,连点两次也生效)。
|
|
30
|
+
|
|
31
|
+
### 改 · 文档预览图重出
|
|
32
|
+
- `docs/preview-overview.png` 用改后的真组件重渲染。
|
|
33
|
+
|
|
34
|
+
## 1.9.0
|
|
35
|
+
|
|
36
|
+
一级导航从五个页签收成四个动词:概览 / 检索 / 探索 / 调用记录。功能一个没删,只是「标签」和「关系」合成一个窗。
|
|
37
|
+
|
|
38
|
+
### 新 · 知识探索窗
|
|
39
|
+
- 「标签」和「关系」不再是两个一级页签,进「探索」后一排子页签切换 —— 它们同属「看库的结构」,分成两个入口只会把导航撑长。
|
|
40
|
+
- 标签从「摆着看」变成入口:点一个标签,检索页签打开、查询框里就是那个词、结果已经查好。
|
|
41
|
+
- 同一个词连点两次也会重跑 —— 递下去的是序号(`seedSeq`),不是词本身;只比文本比不出「又点了一次」。
|
|
42
|
+
|
|
43
|
+
### 新 · 概览的「使用情况」
|
|
44
|
+
- 概览多了第六块:模型调了几次、你自己在面板里查了几次、零命中率、今天几条、四类工具各几次。
|
|
45
|
+
- 读的是 `calls.jsonl` 那一本账,和「调用记录」页签同源 —— 不新建统计系统,两个数的口径就不可能分叉。
|
|
46
|
+
- 模型调用与你手动在面板里的检索分栏显示(`source:"model"` / `"panel"`):混在一起,「模型用了多少次知识库」就成了没法核对的数。
|
|
47
|
+
- 零命中率的分母只算「有命中几页这回事」的调用;一次都没查过时显示「—」而不是 0%,因为「没查过」和「查了没命中」是两句话。
|
|
48
|
+
|
|
49
|
+
### 新 · 零命中时摆出最接近的 3 页
|
|
50
|
+
- 检索窗零命中时,列表位置显示宿主算好的 `nearMiss`:字面沾边百分比、有没有被这次的 `type`/`tags`/`status` 筛掉,点一条就按它的措辞再搜一遍。
|
|
51
|
+
- 0 命中在界面上和「库里没这块」长得一模一样,这一栏是两者唯一的区别;它只在零命中时出现,永不混进命中列表。
|
|
52
|
+
|
|
53
|
+
### 改 · 文档预览图重出
|
|
54
|
+
- `docs/preview-overview.png` 用改后的真组件重渲染(六块 + 四项页签),不再是对不上界面的旧图。
|
|
55
|
+
|
|
56
|
+
## 1.8.3
|
|
57
|
+
|
|
58
|
+
### 撤掉「最近访问」和「页面」页签
|
|
59
|
+
|
|
60
|
+
读笔记、改笔记、看反链,你自己的 markdown 编辑器本来就做得更好。面板里再放一份
|
|
61
|
+
清单、再展开一次只读正文,只是把同一件事做第二遍 —— 而且点一行看着像导航、
|
|
62
|
+
点完只是换了一段文字。所以这两块连同两条后端路由一起撤了:
|
|
63
|
+
|
|
64
|
+
- 概览少一块「最近访问」,五个窗剩三个:概览 / 标签 / 关系。
|
|
65
|
+
- 删掉 `GET /pages`(页面清单)与 `GET /page`(在面板里读一页),`lib/visits.js`
|
|
66
|
+
与 `visits.jsonl` 一并删掉 —— 没人读的账本留着只是白写。
|
|
67
|
+
- 关系窗里点「枢纽页 / 孤岛」仍然能打开文件(走 `POST /open`),宿主顺手给
|
|
68
|
+
`hubPages` / `orphanSample` 补了 `file` 字段:只给页名的话客户端只能猜路径,
|
|
69
|
+
猜错了又是一个「点了没反应」。
|
|
70
|
+
- 旧账本不会被回填、也不再有人读;想看历史就在 git 里翻 1.8.2。
|
|
71
|
+
|
|
72
|
+
## 1.8.2
|
|
73
|
+
|
|
74
|
+
### 修:点「最近访问」什么都打不开
|
|
75
|
+
|
|
76
|
+
之前点一行只做一件事:在面板里展开那一页的正文。于是「最近访问」看着像导航,点下去却只是换了一段只读文字 —— 读得到字、改不了字,也接不上笔记软件的补全和反链。
|
|
77
|
+
|
|
78
|
+
- 现在点一行 = 用系统默认程序打开那个 `.md`(Windows `cmd /c start`、macOS `open`、Linux `xdg-open`,一律 detached,不挂住请求)。
|
|
79
|
+
- 想在这里看正文,点行右侧的「读」——同一个动作,两个目的分开摆。
|
|
80
|
+
- 「页面」清单里的行同理:点页名开文件,点「读」展开。
|
|
81
|
+
- 宿主新增 `POST /open`:路径一律按库根解析并校验落在库内,文件不在回 404 带一句话;打开成功也记一条访问(`source` 仍是 `panel`)。
|
|
82
|
+
- 测试用 `DSH_WIKI_OPEN_DRYRUN=1` 走旁路,不真弹窗;`tests/overview.mjs` 补了 13 条(库内/库外/绝对路径/文件不存在/缺参数/算不算访问)。
|
|
83
|
+
|
|
84
|
+
## 1.8.1
|
|
85
|
+
|
|
86
|
+
### 改:概览只做首页,页面 / 标签 / 关系各自成窗
|
|
87
|
+
|
|
88
|
+
上一版把八块全塞在一个页签里:六块计数还没看完,榜单已经滑出视野。现在六个页签,概览排第一(进来就是它):
|
|
89
|
+
|
|
90
|
+
`概览 · 检索 · 页面 · 标签 · 关系 · 调用记录`
|
|
91
|
+
|
|
92
|
+
- 概览只留:知识库状态、页面数量、索引状态、内容问题、最近访问、快捷操作。
|
|
93
|
+
- 页面:全部页面清单 + 按页名筛 + 点一行读正文,一进这个窗就开始读清单,不必再点一次。
|
|
94
|
+
- 标签:出现最多的 12 个标签,点一下当查询词。
|
|
95
|
+
- 关系:枢纽页、孤岛页、最该先补的页 —— 「知识关系」在这扇窗里。
|
|
96
|
+
- 四个窗是**同一个组件的四种 view**,不是四个组件各读一遍 `/state`:四份 state 迟早不同步。
|
|
97
|
+
|
|
98
|
+
### 改:配色提高对比度
|
|
99
|
+
|
|
100
|
+
设计稿的次级文字 `#a89279`、60% 白卡片,放在 DSH 的暖白画布上糊成一片,数字看着像禁用态。现在:
|
|
101
|
+
|
|
102
|
+
- 正文 `#2b2724`(原 `#3d3d3d`),数字与标题同色;
|
|
103
|
+
- 次级文字 `#6f6558`,榜单里的值 `#4a423a`;
|
|
104
|
+
- 卡片实底 `#fffdf9` + 1px `rgba(168,152,133,0.55)` 描边,hover 边框转 moss `rgba(90,122,107,0.55)`;
|
|
105
|
+
- 链接 `#4f7d99`(原 `#7ba0b8`),正文块 `#f7f2ec` 加细边。
|
|
106
|
+
|
|
107
|
+
2px 直角、无阴影、700ms 过渡、字重只用 200/300/400 这几条设计稿纪律没变,`tests/client.mjs` 把它们和上面几个色值一起钉住了。
|
|
108
|
+
|
|
109
|
+
## 1.8.0
|
|
110
|
+
|
|
111
|
+
### 新:左侧栏的「概览」变成一页真账
|
|
112
|
+
|
|
113
|
+
以前这个页签只是把设置页那张状态卡搬过来。现在它回答的是「这个库现在什么状况、我下一步该看什么」:
|
|
114
|
+
|
|
115
|
+
- **知识库状态**:已连接 / 未配置 / 不可用,扫的是哪个目录,发现多少个文件、读到多少页。
|
|
116
|
+
- **页面数量**:可检索页面、资料页面、小节数、体积。「可检索」= 读进正文的页,超大未读的不算。
|
|
117
|
+
- **索引状态**:最近一次扫描的时刻(换算成本地时间)、耗时、发现与跳过的文件数。
|
|
118
|
+
- **内容问题**:红链几处、涉及几页,以及不可读取、超大页面、重名的计数。
|
|
119
|
+
- **最近访问**:最近打开过的 5 篇,标出是「· 你」还是「· 模型」点开的,点一行直接读。
|
|
120
|
+
- **快捷操作**:搜索、查看全部页面、刷新、重新扫描。
|
|
121
|
+
- **主题与标签**、**知识关系**:出现最多的 12 个标签(点一下就当查询词);枢纽页(被引最多)、孤岛页(没人链过来)、最该先补的页(断链落点)。
|
|
122
|
+
|
|
123
|
+
数字全部由宿主算好再送来(`GET /state` 的 `overview`,与 `stats` 同源同一次扫描),前端不做二次计算 —— 两处各算一遍,迟早算出两个答案。
|
|
124
|
+
|
|
125
|
+
### 新:访问记录 `visits.jsonl`
|
|
126
|
+
|
|
127
|
+
模型读一页(`wiki_recall` 的 `page` 模式)和你在面板里点开一页(`GET /page`)都记一条,`source` 分开写,所以面板能分清「· 你」和「· 模型」。和调用记录同一套纪律:追加写、失败只 warn、有上限、同一页只留最新一条。
|
|
128
|
+
|
|
129
|
+
### 改:概览页签换了一套排版
|
|
130
|
+
|
|
131
|
+
照 `design (1).md` 的北欧极简:Inter、字重只用 200/300/400、卡片 2px 直角 + 无阴影 + hover 只改边框、过渡 700ms。样式限定在 `.wn-page` 作用域内的 `.hx-*` 前缀,不往 DSH 自己的界面里漏。
|
|
132
|
+
|
|
133
|
+
### 修:「最近扫描」的时间少了八小时
|
|
134
|
+
|
|
135
|
+
`scannedAt` 是 UTC(`toISOString()`),之前一律切字符串显示,于是永远比真实时间早 8 小时。现在带时区的值换算成本地,账本里那种本地墙钟原样切 —— 两套格式分开处理,`tests/client.mjs` 各钉了一条。
|
|
136
|
+
|
|
137
|
+
### 新:面板里能浏览全部页面
|
|
138
|
+
|
|
139
|
+
「查看全部页面」列出每页的类型、小节数、是否超大未读,可按页名筛;点一行读正文(含 citation)。读不到时说明是超大未读还是文件读不了,不会假装页是空的。
|
|
140
|
+
|
|
141
|
+
## 1.7.1
|
|
142
|
+
|
|
143
|
+
### 修:介绍页那张预览图,之前是画的,现在是渲染出来的
|
|
144
|
+
|
|
145
|
+
- 换成 `docs/preview.png`。上一版是手绘 SVG,和真界面对不上 —— 页签名、卡片刻度、右栏内容都是我当时想象的,市场上点开一比就露馅。
|
|
146
|
+
- 现在由 `node tools/preview.mjs --only page` 取 `lib/client.js` 里**真的组件和真的样式表**渲染成 HTML,再用无头 Chromium 截一张图。`--data` 喂的是中性样例(`示例页面一` 这类),不会把库里的真实页面名跟着截图出海。
|
|
147
|
+
- 顺手修了预览器两处「说了没做」:SVG 属性不在白名单里(`stroke` / `d` / `viewBox` 被丢掉,图标画出来是空壳)、文件头注释写着 `--data` 参数但其实没实现。
|
|
148
|
+
|
|
149
|
+
### 修:调用记录里「其中 partial / insufficient 分组」那一行没对齐
|
|
150
|
+
|
|
151
|
+
- 它原来靠 `margin-left` 缩进,右边那条边跟着一起缩,于是数字和上面三项的右对齐断了。改成缩内边距(`padding-left:26px`),外框宽度不动,虚线边框表示从属关系。
|
|
152
|
+
- `tests/client.mjs` 加了一条守卫:分组行再出现 `margin-left` 就报错。
|
|
153
|
+
|
|
154
|
+
## 1.7.0
|
|
155
|
+
|
|
156
|
+
### 新:左侧栏的「知识库」页
|
|
157
|
+
|
|
158
|
+
- **左侧栏多了一本书**:点进去是一整页工作台,三个页签 —— 检索 / 概览 / 调用记录。它和「插件」「自动化任务」平级,占满主列,切走即卸载(不在后台留轮询)。用的是 DSH 的面板机制(`sidebar.panellist` 给图标,同一个 id 作 `main` 的 key 给整页),服务不在就静默跳过,设置页照常可用。
|
|
159
|
+
- **概览页签只显示不改**:库路径、页面 / 小节 / 没读到的文件、扫描耗时、实时同步、提示词状态,加「刷新」「重新扫描」。改路径和提示词仍然回设置页 —— 两个地方都能存配置,人就会在错的地方改。
|
|
160
|
+
- **设置页标题右边加一颗「打开知识库页」**,配置和看库不用来回切。
|
|
161
|
+
|
|
162
|
+
### 新:插件在市场里终于像个插件了
|
|
163
|
+
|
|
164
|
+
- `icon.svg`(一本书)、`locale/zh.json`、`locale/en.json`:市场卡片不再退化成包名加一句中英混排的长描述,标题是「知识库」、描述是白话。
|
|
165
|
+
- 详情页首屏加了预览图 `docs/preview.svg`(手绘 SVG,不依赖截图工具)和三处入口的表格:左侧栏那本书 / 设置 → 知识库 / 右侧栏「知识库」页签。
|
|
166
|
+
|
|
167
|
+
### 检索(`wiki_recall`)
|
|
168
|
+
|
|
169
|
+
- **零命中不再是「没有」两个字**:返回体多一个 `nearMiss`,最多 3 页,每页带字面覆盖率、页名,以及 `filtered` —— `true` 表示这次是被自己的 `type`/`tags`/`status` 筛掉的,不是库里没有。渲染成一行「最接近的 3 页:xxx(字面沾边 42%,被这次的过滤条件筛掉)」,后面接一句「这些只是字面最沾边,不等于它们回答了问题」。
|
|
170
|
+
- 有命中时 `nearMiss` 恒为空数组,永不混进 `hits`:命中数不会从 0 变成 3。这条在 `tests/nearmiss.mjs` 里看着。
|
|
171
|
+
|
|
172
|
+
### 调用记录(账本)
|
|
173
|
+
|
|
174
|
+
- **账本从 8 个字段扩到 13 个**:新增 `status`(这次结果的状态)、`fallback`(`coverage` 字面兜底 / `or` 放宽 OR / 空=正常)、`considered`(参与比对的页数)、`warnings`(警告条数)、`topScore`(最高分)。原来的账本只记「0 命中」,复盘的人分不清「该换词」「该放开过滤」「该修库路径」—— 三种下一步长得一模一样。
|
|
175
|
+
- **一页 10 条**:200 行堆成一堵墙没人看。翻页在客户端切片,不发新请求。
|
|
176
|
+
- **时间列带日期**:原来只显示 `HH:MM`,跨天翻页分不清昨天和刚才;现在两行显示(`MM-DD` + 时刻),跨天那一行日期加深加粗。
|
|
177
|
+
- **新增「诊断」列**:`字面兜底` / `放宽 OR` / 非 `ok` 的 `status` 直接标出来;「命中」格悬停显示「参与 N 页 · 最高 X 分」。
|
|
178
|
+
- **新增「反复打空的查询」卡**:同一句问话查了 3 次还是 0 命中,说明不是运气差 —— 要么库里真没有,要么说法对不上。按问法归并、按次数降序,最多列 5 条。
|
|
179
|
+
|
|
180
|
+
## 1.6.2
|
|
181
|
+
|
|
182
|
+
### 检索与取页(`wiki_recall` 的 7 个 mode)
|
|
183
|
+
|
|
184
|
+
- **`search` 的 `status` 不再是摆设**:工具参数表里一直写着 `status`,但 `search` 主循环和覆盖率兜底都只认 `type`/`tags` —— 传 `status:'存疑'` 会被静默忽略,结果里混着别的成熟度,模型还以为筛过了。现在两处都按 frontmatter 的「状态」过滤,空结果也会说清是「被 type/tags/status 过滤掉了」并列出库里现有的状态。
|
|
185
|
+
- **状态口径对齐五档**:把 `草稿 / 演进中 / 已提纯` 这版旧三档从参数说明、help、库结构文档、示例页里统一改成 `草稿 / 演进中 / 稳定 / 存疑 / 已归档`(`已归档` 表生命周期,与成熟度不同维度)。旧写法会让「稳定」「存疑」的页在筛选时被漏掉。
|
|
186
|
+
- **深度上下文把原文引文露出来**:`wiki_context` 返回的 JSON 里逐条带 `quote`(原文子串),渲染却只列槽位名;模型拿到「支撑 definition/numeric」却看不到原文,只能再查一轮。现在每张证据页最多渲染 2 条、每条裁到 220 字并标出槽位。不改 JSON 结构、不碰冻结契约。
|
|
187
|
+
- **`page` 能取整节了**:原来截断提示写「要整节用 page 取「页名」」,但 `page` 只有整页、照样截断 —— 照提示再调一次白花一轮。现在新增 `section` 参数(小节标题或 1-based 序号),只回那一节、引用指到该节,截断提示也带上节名。序号跳过无标题的 H1 前言;指定了却找不到时回 `no_match`、列出现有小节,不退回整页、不谎报「整页没正文」。截断的是无标题前言时,提示改说「按标题或序号都取不到,可调大 `sectionChars`」,不再拼出 `section:「」` 这种照做也取不到的死链。
|
|
188
|
+
|
|
189
|
+
### 设置页 / 右侧栏
|
|
190
|
+
|
|
191
|
+
- **覆盖诊断的「目录/stat 失败」不再是死数**:`/state` 原来不回 `failuresTotal`,界面读它永远得 0 —— 库里有读不了的目录/文件时静默不显示,跟检索时的降级警告对不上。现在补上透传,并修掉失败总数把 stat 失败重复计一次的问题。
|
|
192
|
+
- **两处死样式修好**:调用页错误条用的 `wn-notice-bad` 没有对应 CSS(错误显示成中性灰),筛选按钮的 `wn-btn-on` 也没有规则(点哪个都长一样)。前者接到 `wn-notice-err`,后者补样式并加 `aria-pressed`。
|
|
193
|
+
- **「保存并生效」不再谎报**:profile 里配了 `config.root`(或 `DSH_WIKI_ROOT`)时,设置页换路径只会写进配置文件、实际库没换,界面却说「已保存并生效」。现在明确提示「当前生效路径仍被覆盖,请改 profile 配置」,并把 inline 来源标成警示色;优先级本身不动(既有部署依赖它)。
|
|
194
|
+
- **调用账本补齐两个字段、错误能分流**:账本记 8 个字段,表格原来只有 6 列(少了 mode / ok),失败调用和成功调用长得一样。现在补上「模式」「成败」两列;错误按 HTTP 状态给下一步(400 去设置页看配置、403 只在本机页面操作、500 是宿主问题可重试),检索与调用页失败加重试按钮。
|
|
195
|
+
|
|
196
|
+
### 命令行
|
|
197
|
+
|
|
198
|
+
- 扫描行的 `N 资料` 改成 `其中资料页 N 个`(那个数字是资料页数,不是原文份数);`--status` / `--section` 透传到引擎。
|
|
199
|
+
|
|
5
200
|
## 1.6.1
|
|
6
201
|
|
|
7
202
|
### 检索面板(设置页 / 右侧栏)
|
package/README.md
CHANGED
|
@@ -2,9 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/deepseek-ai)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**把一整个 Markdown 笔记库,变成模型能直接查的四个只读工具。**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+

|
|
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
|
| 检索为什么这么打分 | [检索质量](#检索质量) |
|
|
@@ -44,8 +57,8 @@
|
|
|
44
57
|
|
|
45
58
|
| mode | 干什么 | 参数 |
|
|
46
59
|
| --- | --- | --- |
|
|
47
|
-
| `search`(默认) | 关键词 AND
|
|
48
|
-
| `page` |
|
|
60
|
+
| `search`(默认) | 关键词 AND 检索;`type` / `tags` / `status` 过滤在主路径和覆盖率兜底里都生效 | `query`、`type`、`tags`、`status`、`limit`(5,≤12)、`sectionChars`(900,≤3000) |
|
|
61
|
+
| `page` | 按页名/别名取整页,或只取一节 | `name`、`section`(小节标题或 1-based 序号)、`pageChars`(6000) |
|
|
49
62
|
| `list` | 按类型/标签/状态列目录 | `type`、`tags`、`status`、`limit`(40,≤200) |
|
|
50
63
|
| `overview` | 总览 + 规模行 + 最近日志 + 健康计数 | `pageChars`(4000)、`logLimit`(5,≤20) |
|
|
51
64
|
| `lint` | 库健康检查:孤儿页、断链名字、缺字段、别名冲突、久未更新、无出链、草稿、index 与磁盘不一致;**并和上次体检对比,报出新增与已修** | `limit`(8,≤40)、`staleDays`(120) |
|
|
@@ -56,8 +69,14 @@
|
|
|
56
69
|
{ "mode": "search", "query": "上下文 预算", "limit": 5 }
|
|
57
70
|
```
|
|
58
71
|
|
|
72
|
+
`status` 按 frontmatter「状态」筛,取值是五档:`草稿` / `演进中` / `稳定` / `存疑` / `已归档`(`已归档` 记生命周期,与成熟度不同维度)。`page` 的 `section` 只认有标题的小节;页首无标题前言不按序号计入,找不到时返回 `no_match` 并列出现有小节,不会把整页正文混进来。
|
|
73
|
+
|
|
59
74
|
每条命中带 `kind`(note / raw-summary / source)、`sources`(来源数,**证据强度的唯一可靠代理**)、`status`、`gist`、`section`(命中小节正文,不是 90 字片段)、`citation`(`← [[页名]] §小节 → 路径`)、`brokenLinks`(指向不存在页的双链 = 「库里没依据」的硬信号),以及 `updated` 后面的**距今天数**(超过 180 天标「可能已过时」——三年前的结论和上周的长得一样,模型需要这个信号)。`overview` 额外给三项健康信号:index 有磁盘无、磁盘有 index 无、跨目录重名。
|
|
60
75
|
|
|
76
|
+
零命中时不是一句「没有」就完了:返回里多一个 `nearMiss`(最多 3 页),每页带字面覆盖率、页名,以及 `filtered` —— `true` 表示**这次是你自己筛掉的**(类型/标签/状态),不是库里没有。渲染出来是一行「最接近的 3 页:xxx(字面沾边 42%,被这次的过滤条件筛掉)」,后面跟一句「这些只是字面最沾边,不等于它们回答了问题」。
|
|
77
|
+
|
|
78
|
+
有命中时 `nearMiss` 恒为空数组:它只做诊断,永不混进 `hits`,也不会让「命中 0 页」变成「命中 3 页」。
|
|
79
|
+
|
|
61
80
|
### `wiki_context` —— 带证据的上下文
|
|
62
81
|
|
|
63
82
|
要引用笔记原文回答、或需要知道「有没有依据 / 依据够不够 / 哪里是缺口」时用它,而不是自己连续调 `wiki_recall`。
|
|
@@ -69,7 +88,7 @@
|
|
|
69
88
|
- `support` 说的是**知识够不够**(`sufficient` / `partial` / `insufficient`)。
|
|
70
89
|
- `degraded` 说的是**引擎有没有坏**。它是布尔值,为真时说明某个检索通道挂了 —— 这时候不能把 `support` 当结论,那是拿不完整的检索结果下的判断。
|
|
71
90
|
|
|
72
|
-
同时返回 `evidence`(证据页,含分级、支撑了哪个槽位)、`missing`(缺什么、为什么缺)、`conflicts`(冲突候选,**未裁决,别当成已确认的结论**)、`answer.contract_text`(给回答的约束:必须披露缺口、不得超出证据、引文须原文),以及一个 `context_id
|
|
91
|
+
同时返回 `evidence`(证据页,含分级、支撑了哪个槽位)、`missing`(缺什么、为什么缺)、`conflicts`(冲突候选,**未裁决,别当成已确认的结论**)、`answer.contract_text`(给回答的约束:必须披露缺口、不得超出证据、引文须原文),以及一个 `context_id`。模型看到的渲染文本里,每张证据页最多再附 2 条原文引文(每条按槽位标注、裁到 220 字);JSON 结构不变,引文仍是页面原文子串,不是插件替你概括的。
|
|
73
92
|
|
|
74
93
|
### `wiki_verify` —— 核验回答
|
|
75
94
|
|
|
@@ -95,14 +114,23 @@
|
|
|
95
114
|
|
|
96
115
|
在设置页的「知识库」里切到第二个页签。模型和面板**每一次**查库都会记一行,回答的是「我这句问话,它到底查了没有、查到没有」。
|
|
97
116
|
|
|
98
|
-
三格数字(今日调用 / 命中率 / 零命中)+
|
|
117
|
+
三格数字(今日调用 / 命中率 / 零命中)+ 一张表,列是:**时间(日期 + 时刻,跨天那行日期加深)· 来源 · 工具 · 模式 · 问题 · 命中 · 耗时 · 诊断 · 成败**。筛选有「全部 / 模型 / 面板」与「只看零命中」,选中项有高亮与 `aria-pressed`。表按 10 条一页翻,不把 200 行堆成一堵墙。
|
|
118
|
+
|
|
119
|
+
表格下面还有一张「**反复打空的查询**」:同一句问话被查了 3 次还是 0 命中,说明不是运气差,要么库里真没有,要么说法对不上。这张卡按问法归并、按次数降序,最多列 5 条。
|
|
120
|
+
|
|
121
|
+
页面每 2 秒自己刷新;错误按 400 / 403 / 500 给出下一步并可重试。
|
|
99
122
|
|
|
100
|
-
账本落在插件目录旁的 `calls.jsonl`(已在 `.gitignore`
|
|
123
|
+
账本落在插件目录旁的 `calls.jsonl`(已在 `.gitignore` 里),记 13 个字段:
|
|
101
124
|
|
|
102
125
|
```
|
|
103
126
|
ts · source · tool · mode · query · hits · ms · ok
|
|
127
|
+
status · fallback · considered · warnings · topScore
|
|
104
128
|
```
|
|
105
129
|
|
|
130
|
+
前 8 个是「发生了什么」,后 5 个是「为什么是这样」:`status` 是这次结果的状态(`ok` / `partial` / `no_match` / `unconfigured` / `error`),`fallback` 说明靠哪层兜底(`coverage` 字面兜底 / `or` 放宽 OR / 空 = 正常),`considered` 是参与比对的页数,`warnings` 是警告条数,`topScore` 是最高分。
|
|
131
|
+
|
|
132
|
+
**没有这 5 个字段的时候,「0 命中」是一句没法追责的话**:换词重搜、放开过滤、修库路径,三种下一步长得一模一样。现在「命中」格悬停会显示「参与 N 页 · 最高 X 分」,诊断列直接标出「字面兜底 / 放宽 OR」。
|
|
133
|
+
|
|
106
134
|
**页面路径、正文、答案一律不进账本。** `query` 截到 120 字。
|
|
107
135
|
|
|
108
136
|
几条口径值得写清楚:
|
|
@@ -158,6 +186,8 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
158
186
|
| 3 | `wiki-notes.config.json`(设置页写这里) |
|
|
159
187
|
| 4 | `lib/config.js` 的 `DEFAULT_WIKI_ROOT`(默认空) |
|
|
160
188
|
|
|
189
|
+
设置页改的路径写入第 3 层;若第 1 层 `config.root` 或第 2 层 `DSH_WIKI_ROOT` 正在覆盖,界面会明确提示「保存也盖不过它」,保存后也不会谎称「已保存并生效」。优先级本身保持不变。
|
|
190
|
+
|
|
161
191
|
没配时工具会直接告诉你「还没配置知识库路径」,不会静默扫空目录。
|
|
162
192
|
|
|
163
193
|
`wiki_context` / `wiki_verify` / `wiki_observe` 还需要一条 Python 通路(`bridge.python` + `bridge.toolsRoot`,后者是含 `wiki_bridge.py` 的目录)。没配或配错时这三个工具会明确报错,且**不会假装成「知识库里没有」**:
|
|
@@ -183,15 +213,72 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
183
213
|
|
|
184
214
|
## 设置页
|
|
185
215
|
|
|
186
|
-
设置 →「知识库」。状态栏圆点表示实时同步是否生效,三个数字是页面 /
|
|
216
|
+
设置 →「知识库」。状态栏圆点表示实时同步是否生效,三个数字是页面 / 资料页 / 红链页,下面是路径卡片和 `测试 · 保存并生效 · 重新扫描`。一次没配过时,卡片会变成三步引导。被 profile 的 `config.root` 或环境变量覆盖时,路径卡片会直接说明「保存改不动生效路径」;保存成功提示也会区分「已生效」与「已保存但仍被覆盖」。
|
|
187
217
|
|
|
188
218
|
浏览器半侧走同源 HTTP `/api/wiki-notes/*`(`state` / `search` / `check` / `save` / `rescan`),不碰 RPC。
|
|
189
219
|
|
|
220
|
+
标题右边那颗「**打开知识库页**」就是跳到下面这一页 —— 配置和看库分在两处,跳一次比来回切设置省事。
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## 知识库页(左侧栏)
|
|
225
|
+
|
|
226
|
+
左侧栏最上面那本书,点进去是一整页工作台(不是弹层、不是设置里的一个 tab)。它是 DSH 的**主面板**之一,和「插件」「自动化任务」平级 —— 占满主列,切走会卸载,所以来回切不攒后台轮询。**概览是首页**,落地先看「这个库现在什么状况」,再决定去查什么:
|
|
227
|
+
|
|
228
|
+
| 页签 | 里面有什么 |
|
|
229
|
+
| --- | --- |
|
|
230
|
+
| 概览 | 状态 / 页面数量 / 索引 / 内容问题 / 使用情况 / 快捷操作,见下 |
|
|
231
|
+
| 检索 | 和右侧栏那个面板同一份组件(`compact:false`,宽屏下正文不再截高),能自己搜、看命中理由、复制出处 |
|
|
232
|
+
| 探索 · 标签 | 最常出现的 12 个标签(点一下带着词跳检索)+ 标签共现 + 有/没标签的页数 |
|
|
233
|
+
| 探索 · 关系 | 枢纽页、孤岛页、最该先补的页,加上任意一页的出链 / 入链 / 双向链 |
|
|
234
|
+
| 调用记录 | 就是上面那份账本,含「反复打空的查询」 |
|
|
235
|
+
|
|
236
|
+
一级页签只留四个动词:看状态(概览)、查内容(检索)、看结构(探索)、看模型怎么用(调用记录)。标签和关系都是「看结构」,合成一个窗、用一排子页签切换 —— 一级导航撑长了,多出来的不是信息。
|
|
237
|
+
|
|
238
|
+

|
|
239
|
+
|
|
240
|
+
概览按「先看库有没有毛病,再决定查什么」排,只摆这六块:
|
|
241
|
+
|
|
242
|
+
| 块 | 内容 | 为什么在这一块 |
|
|
243
|
+
| --- | --- | --- |
|
|
244
|
+
| 知识库状态 | 已连接 / 未配置 / 不可用,扫的是哪个目录,发现 N 个文件读到 M 页 | 先分清「搜不到」和「压根没配上」 |
|
|
245
|
+
| 页面数量 | 可检索页面、资料页面、小节数、体积 | 「可检索」是读进正文的页,超大未读的不算在内 |
|
|
246
|
+
| 索引状态 | 最近一次扫描的时刻、耗时、发现与跳过的文件数 | 见过改了笔记却查不到的,多半是没重扫 |
|
|
247
|
+
| 内容问题 | 红链几处、涉及几页,不可读取、超大页面、重名 | 断链是库里的洞,不修就永远查不到 |
|
|
248
|
+
| 使用情况 | 模型调了几次、你自己在面板里查了几次、零命中率、今天几条 | 与「调用记录」页签同一本账,两个数不可能对不上 |
|
|
249
|
+
| 快捷操作 | 搜索、调用记录、查看异常、刷新、重新扫描 | 这一页的动词就够,其余回设置页 |
|
|
250
|
+
|
|
251
|
+
标签、关系同住「探索」窗(里面一排子页签切换),不挤在首页 —— 五块计数还没看完,榜单已经滑出视野了。**一个组件出三个窗**(`view` 区分,探索窗里再分子页),不是三个组件各读一遍 `/state`;同一个数在两处出现,迟早会算出两个答案。
|
|
252
|
+
|
|
253
|
+
标签是入口不是装饰:点一个标签,检索页签打开、查询框里就是那个词、结果已经查好。同一个词连点两次也会重跑(递下去的是序号,不是词本身)—— 只比文本比不出「又点了一次」。
|
|
254
|
+
|
|
255
|
+
**标签共现**(探索 · 标签的第二块):每个高频标签旁边列三个「跟它一起出现最多」的标签,数字是共同出现的页数,点一下就是「两个词一起查」。检索只认字面命中,答不了「我还写过什么和它同时出现过」—— 这一栏补的就是这个问题。同一页里重复写同一个标签只算一次;页面数分母不带超大未读页,所以「没标签 N 页」是真的没打标签,不是没读。
|
|
256
|
+
|
|
257
|
+
**页面关联**(探索 · 关系的第二块):写一个页名回车,得到这一页的**出链 / 入链 / 双向 / 红链**。点任一页名 = 看那一页的链接(顺着走),点「打开」= 交给系统默认程序。入链没有反向索引,只能逐页比一遍 —— 所以这一个数字是**现算**的,不像概览那些跟着扫描一起出。三条路由(概览入链、页面关联、红链归因)共用同一组解析函数(整名命中 → 别名小写 → 跳过 `index`/`log`、跳过自链),口径只留一份:分开写过一次,症状是「入链 0,红链也 0」,两边各自都像是对的。
|
|
258
|
+
|
|
259
|
+
**找不到这一页就 404。** 回一个空的四列会被人读成「这页没有链接」,而真相是「这页不在库里」—— 这两种情况的下一步动作完全不同。
|
|
260
|
+
|
|
261
|
+
**「使用情况」读的是调用账本那一本,不是另建一套统计。** 模型自己调的(`source:"model"`)和你手在面板里查的(`source:"panel"`)分开记两栏 —— 混在一起,「模型用了多少次知识库」就成了没法核对的数。零命中率的分母只算「有命中几页这回事」的调用,一次都没查过时显示「—」而不是 0%:没查过和查了没命中是两句话。四类工具没调过就摆 0 —— `wiki_observe` 是 0 意味着「没观察」,不是「观察了没问题」。
|
|
262
|
+
|
|
263
|
+
**这些数字全部由宿主算好再送过来,前端一个 `reduce` 都没有。** `GET /state` 里的 `overview` 与 `stats` 同源同一次扫描(`overviewOf(corpus)`),所以概览和状态卡不可能对不上;「可检索页面 = 全部 − 超大未读」这类减法也写在宿主,而不是在渲染时现算 —— 两个地方各算一遍,迟早会算出两个答案。
|
|
264
|
+
|
|
265
|
+
**这一页不替你读笔记。** 1.8.2 之前概览里有「最近访问」、页签里有「页面清单」,点一行把正文拉进面板里那段只读 `<pre>`;现在都撤了 —— 读笔记、改笔记、看反链,你自己的 markdown 编辑器(Obsidian 之类)本来就做得更好,面板再抄一份只是把同一件事做第二遍。关系窗里点一行(枢纽页 / 孤岛),仍然走 `POST /open` 交给系统默认程序(Windows 是 `cmd /c start`,macOS `open`,Linux `xdg-open`)—— 那里点的是「去那一页看看」,不是「在这里读一遍」。
|
|
266
|
+
|
|
267
|
+
`/open` 只认落在库根之内的路径(相对路径按库根解析),文件不在了回 404 带一句话 —— 这条路由要是能开任意路径,它就成了「本机任意文件 + 系统关联程序」的执行口,而它只是个看笔记的按钮。
|
|
268
|
+
|
|
269
|
+
概览只显示、不改:改路径和提示词仍然回设置页 —— 这里出现两颗「保存」按钮的话,人就会在错的地方改配置。
|
|
270
|
+
|
|
271
|
+
排版照 `design (1).md` 那套北欧极简:Inter、字重只用 200/300/400、卡片 2px 直角 + 无阴影 + hover 只改边框、过渡 700ms。样式全部限定在 `.wn-page` 作用域内的 `.hx-*` 前缀 —— 插件的 CSS 是往 `document.head` 里塞一个 `<style>`,不带作用域会漏进 DSH 自己的界面。
|
|
272
|
+
|
|
273
|
+
**对比度是照着设计稿又改了一遍的地方。** 设计稿的次级文字是 `#a89279`、卡片是 60% 白 —— 那套配色放在落地页上很轻,放进 DSH 的暖白画布就糊成一片,数字看着像禁用态。现在正文压到 `#2b2724`、次级文字 `#6f6558`、卡片实底 `#fffdf9` + 更实的描边,2px 直角与 700ms 过渡照旧(`tests/client.mjs` 把这几个值钉住了,免得哪天又被「调淡一点」改回去)。
|
|
274
|
+
|
|
275
|
+
图标是一本书(`icon.svg` 同一份线稿,颜色吃 `currentColor`,选中时线粗一点),不额外装图标库。
|
|
276
|
+
|
|
190
277
|
---
|
|
191
278
|
|
|
192
279
|
## 检索面板
|
|
193
280
|
|
|
194
|
-
|
|
281
|
+
同一个检索面板出现在三处:设置页的「试一试检索」卡、右侧栏的「知识库」页签、左侧栏知识库页的「检索」页签 —— 同一份组件,`compact` 控制密度。用途只有一个:**让人自己看见检索依据**,不必等模型说它查到了什么。
|
|
195
282
|
|
|
196
283
|
输入关键词回车,上面一行是「命中 7 页(显示前 5)· 参与打分 95 页 · 36 ms · 库 95 页」;紧跟一行是**查询诊断**:`实际用的词` 后面逐个列出这次真正参与打分的词,一页都没沾到的词会标成「没沾到」,末尾写清这次是「全词都要(AND)」还是「命中任一(OR)」。中文不分词,写整句时这一行通常只剩一个词 —— 这是最直观的提示:换词,而不是加词。
|
|
197
284
|
|
|
@@ -200,11 +287,15 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
200
287
|
- 页名、类型、总分,以及「只命中部分词」的标记(该条没命中全部查询词);
|
|
201
288
|
- **命中理由**:每个查询词一条徽章,主词加粗、明细灰字,例如 `上下文 · 页名 120 · 别名 50 · 正文 ×7 21`,未得分的词显示为「未命中」。悬停徽章有各通道的权重说明;
|
|
202
289
|
- 该条命中的小节标题与正文(正文里出现过的查询词带淡黄底纹),末尾附 citation,右侧一个复制按钮 —— 把「哪句话支撑了这条」直接抄进对话里;
|
|
203
|
-
-
|
|
290
|
+
- 查询降级成「命中任一」或「字面覆盖率兜底」时,计数行旁边会按实际路径分别黄字提示。
|
|
291
|
+
|
|
292
|
+
零命中时,列表位置会摆出**最接近的 3 页**:字面沾边多少百分比、有没有被这次的 `type`/`tags`/`status` 过滤筛掉,点一条就按它的措辞再搜一遍。这一栏只在零命中时出现,永不混进命中列表 —— 它回答的是「是库里没这块,还是我筛掉了它」,而不是假装自己命中了。
|
|
293
|
+
|
|
294
|
+
**最近查过**:查成功之后,输入框下面留一排词(最多 8 个,同一句不重复堆),点一下重查。它只活在这次会话里、不落盘 —— 这是「刚查过的还热着」,不是第三本账;写盘就得连带处理清理、隐私和跨设备不一致。
|
|
204
295
|
|
|
205
296
|
**键盘**:输入框防抖 350ms(够 2 个字符才查),`Enter` 立刻查,`Esc` 清空,`↑`/`↓` 在结果里移动高亮并展开对应条目;任意位置按 `/` 或 `Ctrl/⌘ + K` 直接跳到输入框。查询进行中列表上方显示「检索中…」。输入框右边有「复制词」—— 查出来的说法常常要拿去别处再查一遍,省得重敲;citation 那行的复制按钮同理(键盘走过去会看到焦点框)。
|
|
206
297
|
|
|
207
|
-
**覆盖统计**在设置页的状态卡下面:`发现 102 个文件 → 读到 95 页 / 677 个小节`,后面是总体积、跳过 / 读不了 / 超大未读 /
|
|
298
|
+
**覆盖统计**在设置页的状态卡下面:`发现 102 个文件 → 读到 95 页 / 677 个小节`,后面是总体积、跳过 / 读不了 / 超大未读 / 目录与 stat 失败的计数(非 0 时标黄)、最新修改时间、本次扫描耗时,以及这次实际扫的目录(自动下钻过时它和配置里的路径不是同一个)。
|
|
208
299
|
|
|
209
300
|
没查之前不是一片空白:显示库的规模、同步开关,以及库里出现最多的几个标签 —— 点一下直接拿它当查询词,省得先想「该查什么」。查不到时也顺带报覆盖:`参与检索 95 页 / 677 个小节 · 跳过 7` ——「没命中」和「那几页根本没读」是两回事,面板得能分清。`discovered = pages + unreadable + skipped` 在 `tests/api.mjs` 里当恒等式断言,这几个数不是凑出来的。
|
|
210
301
|
|
|
@@ -216,7 +307,7 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
216
307
|
|
|
217
308
|
> 这条踩过一次:字段先加进了 `run()` 的返回值,但模型拿到的是 `renderValue()` 渲染出的文本 —— 不写进渲染,模型就等于没拿到。`tests/status.mjs` 现在有两条断言看着它(有漏词要出现、没漏词不许出现)。
|
|
218
309
|
|
|
219
|
-
侧栏是可选能力:`ctx.inject(['sidebarRightTabs'], …)` 运行时按需取,服务不在就静默跳过,设置页照常可用;`dsh.client.inject` 刻意不钉侧栏模块(钉了会把「侧栏在不在」变成整个客户端包的加载前提)。`tests/contract.mjs`
|
|
310
|
+
侧栏是可选能力:`ctx.inject(['sidebarRightTabs'], …)` 运行时按需取,服务不在就静默跳过,设置页照常可用;`dsh.client.inject` 刻意不钉侧栏模块(钉了会把「侧栏在不在」变成整个客户端包的加载前提)。`tests/contract.mjs` 守着这两条。左侧栏那本书同理:`sidebar.panellist` + `main` 两个注入都是运行时按需取,`layout` 服务缺了只是「打开知识库页」这颗按钮不出现。
|
|
220
311
|
|
|
221
312
|
接口:`GET /api/wiki-notes/search?q=上下文 预算&limit=5`,`q` 截到 200 字,`limit` 夹在 1–12,缺 `q` 返回 400。
|
|
222
313
|
|
|
@@ -232,9 +323,9 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
232
323
|
|
|
233
324
|
三条线分开看,别混成一个数字:
|
|
234
325
|
|
|
235
|
-
- **对齐(parity)**:`tests/local/ab.mjs` 比的是「JS 引擎的前 5 是否覆盖 Python `search.py` 的前 5
|
|
236
|
-
- **质量(recall)**:`tests/local/recall.mjs` 跑人工标注的评测集,报 Recall@5 / Top-1 / MRR@5
|
|
237
|
-
-
|
|
326
|
+
- **对齐(parity)**:`tests/local/ab.mjs` 比的是「JS 引擎的前 5 是否覆盖 Python `search.py` 的前 5」;`tests/local/metrics.mjs` 比同一批槽位的集合与排序(Recall@5 / Top-1 一致率 / Jaccard),当硬门禁。两侧刻意保留少量已知分歧(疑问词剥离是有意改进、index 摘要 +8、类型层平局裁决),名单在本地 `tests/local/parity-exceptions.json`,**不入仓库**。
|
|
327
|
+
- **质量(recall)**:`tests/local/recall.mjs` 跑人工标注的评测集,报 Recall@5 / Top-1 / MRR@5 并按标签分组。`queries.json` 里的 `floor` 与 `libraryFingerprint` 绑定:库内容变了要按规矩重导基线、把证据写进 `floorNote`,低于 floor 即 exit 2。评测集 `tests/local/queries.json` 含本机笔记主题,**不入仓库**;仓库里只有中性 6 条的 `queries.example.json`。
|
|
328
|
+
- **性能**:基准数字随库规模与机器变化,用 `tools/probe.mjs` 在本机攒 hit@1 / hit@3 / Recall@5 的趋势 CSV;别把某一次读数写进文档当承诺。
|
|
238
329
|
|
|
239
330
|
评分刻意朴素:标题全等 120 / 标题含 60 / 别名含 50 / 标签含 25 / 正文词频 ×3(封顶 36)/ index 摘要只在其它通道全 0 时补 8;同分再比类型层(综合 3 · 总览 3 / 概念·实体·对比 2 / 资料 1)→ 更新时间 → 码点序。四处经验细节:摘要分只补漏不抢位、同分用码点序(拼音序不可复现)、选节排除清单类与元讨论类小节、总览与综合同层(总览是全库唯一入口页,跨模块的词在它里面出现分量不同)。
|
|
240
331
|
|
|
@@ -279,9 +370,10 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
279
370
|
|
|
280
371
|
- 中文不分词,靠空格切分;连写词靠 `别名` 补。整句中文拿不到命中时会降级成字面覆盖率排序,那是**字面**匹配,语义相近但用词不同照样认不出。
|
|
281
372
|
- 页名本身是查询词时,正文很少重复该词,选节可能偏。
|
|
282
|
-
-
|
|
373
|
+
- 每次调用全量扫描;具体耗时随库规模与机器变化,再大一个数量级要上增量索引。
|
|
283
374
|
- 每命中一页要塞约 900 字符正文(`sectionChars` 可调),一次返回 5 页就是 4–5k 字符 —— 瓶颈常在上下文预算而不在检索速度。
|
|
284
|
-
-
|
|
375
|
+
- `page` 的 `section` 只认有标题的小节:页首无标题前言按标题或序号都取不到,遇到它只能调大 `sectionChars`;`list` / `search` 也还没有 `dir` / `offset` 分页,超过 `limit` 上限的后半段要先按 `type` / `tags` / `status` 收窄。
|
|
376
|
+
- **重启后第一次扫描是冷盘读**:具体耗时随库规模与磁盘变化,插件启动就预热一次,所以这段延迟通常落在你还没提问的时候;但第一条查询正好赶上也确实要等。
|
|
285
377
|
- **面板没打开时 `/`、`Ctrl/⌘ + K` 不会有反应**:快捷键绑在面板上,而宿主的 `sidebarRightTabs` 只提供 `register()`,没有「打开 / 激活页签」的接口,插件没法从外面把面板叫出来。
|
|
286
378
|
- **知识网关那套仍是两套实现**:JS 侧 `wiki_recall` 和 Python 侧 `wiki_context` 各自解析页面,差在结构解读层。统一方向未定。
|
|
287
379
|
- **`unverifiable` 只在 `notices` 里**:模型若只看 `violations`,会漏掉「这个数字我核实不了」。
|
|
@@ -314,7 +406,7 @@ tests/support/ 测试用小工具(quiet-ledger:把账本重定向到临时
|
|
|
314
406
|
```
|
|
315
407
|
|
|
316
408
|
```bash
|
|
317
|
-
npm test # 跑样例库,不需要本地知识库(
|
|
409
|
+
npm test # 跑样例库,不需要本地知识库(29 个文件)
|
|
318
410
|
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
319
411
|
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
320
412
|
WIKI_ROOT="/path/your/wiki" node tests/local/recall.mjs # 质量评测:Recall@5 / Top-1 / MRR(低于 floor 退 2)
|
|
@@ -331,9 +423,9 @@ node tools/preview.mjs --diag # 同上,并量一遍宽度
|
|
|
331
423
|
WIKI_ROOT="/path/your/知识层-wiki" WIKI_TOOLS="/path/your/工具-tools" node tests/gateway.mjs
|
|
332
424
|
```
|
|
333
425
|
|
|
334
|
-
发版:改 `version` → `npm test` 全绿(`scripts.test` 只串跑 `node tests/*.mjs`,
|
|
426
|
+
发版:改 `version` → `npm test` 全绿(`scripts.test` 只串跑 `node tests/*.mjs`,29 个文件;`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 list` 里该版本是不是 Latest(`gh release view --json isLatest` 不是可用字段)。
|
|
335
427
|
|
|
336
|
-
打包进了你的笔记标题怎么办:`tests/local/` 的 query 集、分歧白名单、回归基线与 `calls.jsonl` / `governance.jsonl` / `probe-history.csv` 都在 `.gitignore`
|
|
428
|
+
打包进了你的笔记标题怎么办:`tests/local/` 的 query 集、分歧白名单、回归基线与 `calls.jsonl` / `governance.jsonl` / `probe-history.csv` 都在 `.gitignore` 里,只在本机跑;`tests/local/_*.mjs` 这类写死本机路径的只读体检脚本也一样。发版前用 `git diff --cached | grep -E '<用户名>|<库路径>|<真实页名>'` 过一遍暂存区,再解包 `npm pack` 产物逐文件扫一遍;命中就改口径再提交。
|
|
337
429
|
|
|
338
430
|
改样式的两条经验:
|
|
339
431
|
|
package/bin/cli.mjs
CHANGED
|
@@ -56,7 +56,7 @@ async function main() {
|
|
|
56
56
|
const t0 = Date.now()
|
|
57
57
|
const corpus = await loadCorpus(root)
|
|
58
58
|
const loadMs = Date.now() - t0
|
|
59
|
-
process.stderr.write(`[扫描] ${corpus.stats.pages} 页 / ${corpus.stats.resources}
|
|
59
|
+
process.stderr.write(`[扫描] ${corpus.stats.pages} 页 / 其中资料页 ${corpus.stats.resources} 个 / ${corpus.stats.brokenPages} 页有断链 / ${loadMs}ms / root=${root}\n`)
|
|
60
60
|
|
|
61
61
|
if (command === 'bench') {
|
|
62
62
|
const queries = ['上下文 工程', '记忆 系统', '检索 增强', '微调', '证据 分级', '窗口']
|
|
@@ -70,7 +70,7 @@ async function main() {
|
|
|
70
70
|
}
|
|
71
71
|
|
|
72
72
|
const started = Date.now()
|
|
73
|
-
const result = run(corpus, { mode: command, query: positional[0], name: positional[0], type: flags.type, tags: flags.tags, limit: flags.limit, pageChars: flags.chars })
|
|
73
|
+
const result = run(corpus, { mode: command, query: positional[0], name: positional[0], type: flags.type, tags: flags.tags, status: flags.status, section: flags.section, limit: flags.limit, pageChars: flags.chars })
|
|
74
74
|
const queryMs = Date.now() - started
|
|
75
75
|
process.stderr.write(`[查询] ${queryMs}ms\n`)
|
|
76
76
|
console.log(JSON.stringify(result, null, 2))
|
|
Binary file
|
package/docs/preview.png
ADDED
|
Binary file
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
| 字段 | 取值 | 用途 | 缺失后果 |
|
|
41
41
|
| --- | --- | --- | --- |
|
|
42
42
|
| `类型` | 概念 / 实体 / 对比 / 综合 / 资料 | 类型筛选;同分时排序(综合 > 概念/实体/对比 > 资料) | 类型筛选失效,排序退化为默认档 |
|
|
43
|
-
| `状态` | 草稿 / 演进中 /
|
|
43
|
+
| `状态` | 草稿 / 演进中 / 稳定 / 存疑 / 已归档 | 状态筛选;「这页成熟到什么程度」与生命周期(已归档另算一档) | 状态筛选失效 |
|
|
44
44
|
| `标签` | `[a, b]` 或 `[a,b]`(中英文逗号都认) | 标签筛选;命中 +25 分 | 标签通道失效 |
|
|
45
45
|
| `别名` | `[a, b]` | **别名命中 +50 分**——中英文/缩写/旧称都能搜到 | 只能靠页名和正文,缩写查不到 |
|
|
46
46
|
| `来源数量` | 数字 | **证据强度的唯一可靠代理**(库里没有「可信档」字段,按它推) | 不显示证据强度 |
|
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. 只记白名单里的
|
|
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
|
-
/** 账本只认这
|
|
21
|
-
export const CALL_FIELDS = [
|
|
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
|
|