dsh-wiki-notes 1.4.0 → 1.4.2
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 +109 -27
- package/docs/README.md +70 -0
- package/docs//345/245/221/347/272/246-stage0//350/247/202/345/257/237/346/234/237/346/226/271/346/241/210.md +2 -2
- package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2652-/345/277/253/347/205/247/344/270/216TTL.md +1 -1
- package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2654-/346/217/222/344/273/266/346/216/245/345/205/245.md +6 -3
- package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2655-/350/247/202/345/257/237/351/227/255/347/216/257/344/270/216/345/256/236/346/210/230/351/252/214/346/224/266.md +22 -2
- package/lib/client.js +1 -1
- package/lib/index.js +60 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,14 +2,92 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/deepseek-ai)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**给你那堆 Markdown 笔记,接上四个能用的工具:查得到、读得出、核得住、看得见。**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
为 [DeepSeek Harness](https://github.com/deepseek-ai) 做的只读检索插件。旧的流程是五步:读总览 → 读索引 → 敲命令搜 → 打开那页 → 追它的来源。现在一次调用就把**命中小节的完整正文 + 出处**返回,模型自己接着答。
|
|
8
8
|
|
|
9
9
|
> 中文文档从下面开始。实测:73 页的库,旧流程单次 ≈ 18.7k 字符,新流程 ≈ 2.5k。
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
|
+
## 目录
|
|
14
|
+
|
|
15
|
+
| 你想知道 | 直接跳 |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| 这插件到底能干什么 | [四个工具](#四个工具) |
|
|
18
|
+
| 我要先装上试试 | [装](#装) · [配](#配) |
|
|
19
|
+
| 我自己的笔记该怎么写 | [库该长什么样](#库该长什么样) |
|
|
20
|
+
| 检索为什么这么打分 | [检索质量](#检索质量) |
|
|
21
|
+
| 它有没有偷看我的东西 | [只读,且不往外发](#只读且不往外发) |
|
|
22
|
+
| 已知毛病 | [已知局限](#已知局限) |
|
|
23
|
+
| 要改代码 | [目录 / 开发](#目录--开发) |
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 四个工具
|
|
28
|
+
|
|
29
|
+
插件注册四个工具,用途不重叠,按顺序读就明白了:
|
|
30
|
+
|
|
31
|
+
| 工具 | 一句话 | 什么时候用 |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| **`wiki_recall`** | 检索库,拿到命中小节的正文与出处 | 「我的笔记里怎么写的?」 |
|
|
34
|
+
| **`wiki_context`** | 检索 + 抽证据 + 标缺口 + 给回答约束,**一次做完** | 要引用笔记原文回答,或想知道「依据够不够」 |
|
|
35
|
+
| **`wiki_verify`** | 拿已有的 context 核验一段回答,**不重新检索** | 答案写完了自查,特别是有数字的时候 |
|
|
36
|
+
| **`wiki_observe`** | 查观察日志统计(调用次数、支持状态分布、违规类型) | 诊断,不参与回答 |
|
|
37
|
+
|
|
38
|
+
### `wiki_recall` —— 检索
|
|
39
|
+
|
|
40
|
+
一个工具,七种 mode:
|
|
41
|
+
|
|
42
|
+
| mode | 干什么 | 参数 |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| `search`(默认) | 关键词 AND 检索 | `query`、`limit`(5,≤12)、`sectionChars`(900,≤3000) |
|
|
45
|
+
| `page` | 按页名/别名取整页 | `name`、`pageChars`(6000) |
|
|
46
|
+
| `list` | 按类型/标签/状态列目录 | `type`、`tags`、`status`、`limit`(40,≤200) |
|
|
47
|
+
| `overview` | 总览 + 规模行 + 最近日志 + 健康计数 | `pageChars`(4000)、`logLimit`(5,≤20) |
|
|
48
|
+
| `lint` | 库健康检查:孤儿页、断链名字、缺字段、别名冲突、久未更新、无出链、草稿、index 与磁盘不一致;**并和上次体检对比,报出新增与已修** | `limit`(8,≤40)、`staleDays`(120) |
|
|
49
|
+
| `draft` | 把好答案回写成新页的落盘骨架(目录、frontmatter、index 行、log 条),不写文件 | `title`、`type`、`tags`、`summary`、`sources` |
|
|
50
|
+
| `help` | 用法与状态说明:七个 mode 各返回什么、`status` 各取值怎么读、参数默认值 | 无 |
|
|
51
|
+
|
|
52
|
+
```jsonc
|
|
53
|
+
{ "mode": "search", "query": "上下文 预算", "limit": 5 }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
每条命中带 `kind`(note / raw-summary / source)、`sources`(来源数,**证据强度的唯一可靠代理**)、`status`、`gist`、`section`(命中小节正文,不是 90 字片段)、`citation`(`← [[页名]] §小节 → 路径`)、`brokenLinks`(指向不存在页的双链 = 「库里没依据」的硬信号),以及 `updated` 后面的**距今天数**(超过 180 天标「可能已过时」——三年前的结论和上周的长得一样,模型需要这个信号)。`overview` 额外给三项健康信号:index 有磁盘无、磁盘有 index 无、跨目录重名。
|
|
57
|
+
|
|
58
|
+
### `wiki_context` —— 带证据的上下文
|
|
59
|
+
|
|
60
|
+
要引用笔记原文回答、或需要知道「有没有依据 / 依据够不够 / 哪里是缺口」时用它,而不是自己连续调 `wiki_recall`。
|
|
61
|
+
|
|
62
|
+
参数:`query`(必填)、`limit`(1–12,默认 5)、`engine`(`both` / `search` / `wiki_recall`,默认 `both`)、`ttl_seconds`(默认 1800)。
|
|
63
|
+
|
|
64
|
+
返回里最重要的一条:**`status.support` 和 `status.degraded` 是两件事,必须分开看。**
|
|
65
|
+
|
|
66
|
+
- `support` 说的是**知识够不够**(`sufficient` / `partial` / `insufficient`)。
|
|
67
|
+
- `degraded` 说的是**引擎有没有坏**。它是布尔值,为真时说明某个检索通道挂了 —— 这时候不能把 `support` 当结论,那是拿不完整的检索结果下的判断。
|
|
68
|
+
|
|
69
|
+
同时返回 `evidence`(证据页,含分级、支撑了哪个槽位)、`missing`(缺什么、为什么缺)、`conflicts`(冲突候选,**未裁决,别当成已确认的结论**)、`answer.contract_text`(给回答的约束:必须披露缺口、不得超出证据、引文须原文),以及一个 `context_id`。
|
|
70
|
+
|
|
71
|
+
### `wiki_verify` —— 核验回答
|
|
72
|
+
|
|
73
|
+
写完答案后自查(尤其含数字、范围、年份、题量分值这类主张时)用它。参数:`context_id` + `answer`(可选 `observe_id`,一般不用传,插件会自动带上)。
|
|
74
|
+
|
|
75
|
+
它不重新检索 —— 拿当初那份快照来比,所以快,也不受库里后来改动的影响。
|
|
76
|
+
|
|
77
|
+
返回 `status` 与 `violations`:violations 非空说明回答越过了证据允许的边界,每条都带类型、主张和原因。另有 `notices` 单独放「说不清」的提示 —— **「说不清」不等于「说错了」**,模型若只读 violations 会漏掉这一块。
|
|
78
|
+
|
|
79
|
+
`context_expired` / `context_missing` 是**快照问题**,不等于回答错了:重新取一份 context 再核验就行。
|
|
80
|
+
|
|
81
|
+
每次核验都会往观察日志追加一条记录,并用 `parent_observe_id` 指回当初那份 context —— 这样「哪次核验修好了哪次回答」在日志里追得回。
|
|
82
|
+
|
|
83
|
+
### `wiki_observe` —— 诊断
|
|
84
|
+
|
|
85
|
+
参数:`days`(1–365,默认 7)、`limit`(1–50,默认 10)。
|
|
86
|
+
|
|
87
|
+
报观察窗口内的调用次数、支持状态分布、检索状态分布、违规类型分布,还有**修正情况**(核验过的 context 里已改正 / 仍未改正的比例)—— 这一项比违规总数更能反映核验到底有没有用。只读诊断,不参与回答,也不改检索行为。
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
13
91
|
## 设计从哪来
|
|
14
92
|
|
|
15
93
|
库结构来自 [Karpathy 的 `llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):与其每次提问都从原始文档重新检索(知识不累积),不如让 LLM 增量维护一个持久的 wiki。本插件只加速其中的 **Query** 一段。
|
|
@@ -56,32 +134,16 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
56
134
|
|
|
57
135
|
没配时工具会直接告诉你「还没配置知识库路径」,不会静默扫空目录。
|
|
58
136
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
## 用
|
|
137
|
+
`wiki_context` / `wiki_verify` / `wiki_observe` 还需要一条 Python 通路(`bridge.python` + `bridge.toolsRoot`,后者是含 `wiki_bridge.py` 的目录)。没配的话这三个工具会明确报 `E_PYTHON_UNAVAILABLE` —— **不会假装成「知识库里没有」**。配置形状见 [docs/契约-stage0/阶段4-插件接入.md](docs/契约-stage0/阶段4-插件接入.md)。
|
|
62
138
|
|
|
63
|
-
|
|
64
|
-
| --- | --- | --- |
|
|
65
|
-
| `search`(默认) | 关键词 AND 检索 | `query`、`limit`(5,≤12)、`sectionChars`(900,≤3000) |
|
|
66
|
-
| `page` | 按页名/别名取整页 | `name`、`pageChars`(6000) |
|
|
67
|
-
| `list` | 按类型/标签/状态列目录 | `type`、`tags`、`status`、`limit`(40,≤200) |
|
|
68
|
-
| `overview` | 总览 + 规模行 + 最近日志 + 健康计数 | `pageChars`(4000)、`logLimit`(5,≤20) |
|
|
69
|
-
| `lint` | 库健康检查:孤儿页、断链名字、缺字段、别名冲突、久未更新、无出链、草稿、index 与磁盘不一致;**并和上次体检对比,报出新增与已修** | `limit`(8,≤40)、`staleDays`(120) |
|
|
70
|
-
| `draft` | 把好答案回写成新页的落盘骨架(目录、frontmatter、index 行、log 条),不写文件 | `title`、`type`、`tags`、`summary`、`sources` |
|
|
71
|
-
| `help` | 用法与状态说明:七个 mode 各返回什么、`status` 各取值怎么读、参数默认值 | 无 |
|
|
72
|
-
|
|
73
|
-
```jsonc
|
|
74
|
-
{ "mode": "search", "query": "上下文 预算", "limit": 5 }
|
|
75
|
-
```
|
|
139
|
+
---
|
|
76
140
|
|
|
77
|
-
|
|
141
|
+
## 模型怎么知道该查库
|
|
78
142
|
|
|
79
|
-
|
|
143
|
+
插件会从你库里现有的 `标签` 算出主题词,注入一行(约 50 token,例如「本地知识库主题:上下文工程、ai、agent…」)。不带页数 —— 页数一变就会打掉提示词的前缀缓存,而它对「该不该查」没有帮助。换库自动变,所以问题沾这些主题时它自己会去查,不用你提醒。设置页里可以关掉(不占上下文)、换成自己的整段、或在末尾追加一句,改完下一回合生效。
|
|
80
144
|
|
|
81
145
|
主题词怎么挑:跳过 `总览`/`index` 这类结构页,跳过 `数据`/`工具`/`meta` 这类空泛标签,默认只留出现 ≥2 次的标签(设置页可改回 ≥1)。全被滤掉时退回不过滤的前五 —— 小库不至于一条提示都没有。
|
|
82
146
|
|
|
83
|
-
> `limit` 默认 5,一次约 2.5–3k token。嫌多可以传 3 省四成,但默认留 5 —— 少一次往返比省四成更值钱。
|
|
84
|
-
|
|
85
147
|
---
|
|
86
148
|
|
|
87
149
|
## 设置页
|
|
@@ -139,6 +201,15 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
139
201
|
|
|
140
202
|
---
|
|
141
203
|
|
|
204
|
+
## 只读,且不往外发
|
|
205
|
+
|
|
206
|
+
- 插件只读你的笔记:不写库、不改页、不修红链。
|
|
207
|
+
- 检索在本地进程内跑,没有任何出站请求。
|
|
208
|
+
- `wiki_context` / `wiki_verify` 调的是**你自己机器上的** Python 管线(`bridge.toolsRoot`),同样不出网。
|
|
209
|
+
- 仓库里不含任何本机绝对路径或用户名;测试用环境变量拿真实路径(`WIKI_ROOT` / `WIKI_TOOLS`),不给就跑样例库。
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
142
213
|
## 上下游(可选)
|
|
143
214
|
|
|
144
215
|
- **进料**:[Obsidian Web Clipper](https://github.com/obsidianmd/obsidian-clipper) —— 网页剪藏成 Markdown 落进 raw 层。模板里写好 `类型` / `来源数量` / `标签`,本插件的 `kind`、`sources`、证据强度才有东西可用。
|
|
@@ -153,7 +224,10 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
153
224
|
- 每次调用全量扫描;70–100 页无所谓,再大一个数量级要上增量索引。
|
|
154
225
|
- **重启后第一次扫描是冷盘读**:95 页实测 5,217ms(此后 29ms)。插件启动就预热一次,所以这段延迟通常落在你还没提问的时候;但第一条查询正好赶上也确实要等。
|
|
155
226
|
- **面板没打开时 `/`、`Ctrl/⌘ + K` 不会有反应**:快捷键绑在面板上,而宿主的 `sidebarRightTabs` 只提供 `register()`,没有「打开 / 激活页签」的接口,插件没法从外面把面板叫出来。
|
|
156
|
-
-
|
|
227
|
+
- **知识网关那套仍是两套实现**:JS 侧 `wiki_recall` 和 Python 侧 `wiki_context` 各自解析页面,差在结构解读层。统一方向未定。
|
|
228
|
+
- **`unverifiable` 只在 `notices` 里**:模型若只看 `violations`,会漏掉「这个数字我核实不了」。
|
|
229
|
+
- **观察日志无轮转**:只追加不清理,`legacy` 计数会随时间变大。
|
|
230
|
+
- **快照不自动清理**,也没有滑动续期。
|
|
157
231
|
|
|
158
232
|
---
|
|
159
233
|
|
|
@@ -169,21 +243,29 @@ bin/cli.mjs 命令行,不装插件也能跑
|
|
|
169
243
|
tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
|
|
170
244
|
tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
|
|
171
245
|
docs/库结构.md 库结构约定(这份才是一手文档)
|
|
246
|
+
docs/README.md 文档导航页
|
|
172
247
|
docs/superpowers/specs/ 检索面板的设计稿
|
|
248
|
+
docs/契约-stage0/ 知识网关的设计与验收记录
|
|
173
249
|
examples/ 可跑的最小样例库
|
|
174
|
-
tests/ smoke / status / lint / explain / api / help / contract / watch / client bundle
|
|
250
|
+
tests/ smoke / status / lint / explain / api / help / contract / watch / client bundle / gateway
|
|
175
251
|
```
|
|
176
252
|
|
|
177
253
|
```bash
|
|
178
|
-
|
|
254
|
+
npm test # 跑样例库,不需要本地知识库
|
|
179
255
|
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
180
256
|
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
181
|
-
|
|
257
|
+
npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
|
|
182
258
|
node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
|
|
183
259
|
node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
|
|
184
260
|
```
|
|
185
261
|
|
|
186
|
-
|
|
262
|
+
跑知识网关那两段真实通路,要给两个环境变量(不给就整段跳过,不会假装通过):
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
WIKI_ROOT="/path/your/知识层-wiki" WIKI_TOOLS="/path/your/工具-tools" node tests/gateway.mjs
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
发版:改 `version` → `npm test` 全绿(`scripts.test` 只调 `node tests/*.mjs`,所以 20.x 也能跑;`node --run test` 要 Node 22+,别在低版本上用它,也别拿它当门槛的证明)→ `npm pack --dry-run` 看一眼打包内容(`files` 只含 `lib`/`bin`/`docs`/`examples`/`README.md`/`LICENSE`/`cordis.patch.yml`,`preview/` 与 `tools/` 不进包)→ `npm publish`。发布前先 `npm whoami --registry=https://registry.npmjs.org/` 确认已登录(本机 token 在 `.npmrc` 的 `//registry.npmjs.org/:_authToken=`;注意 `npm config get registry` 指向 npmmirror,而 npmmirror 那边不认这个 token,登录状态要显式指定 registry 去查)。
|
|
187
269
|
|
|
188
270
|
改样式的两条经验:
|
|
189
271
|
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# 文档导航
|
|
2
|
+
|
|
3
|
+
这个目录里有两类文档,混在一起容易迷路:
|
|
4
|
+
|
|
5
|
+
| 类别 | 目录 | 读者 | 什么时候看 |
|
|
6
|
+
| --- | --- | --- | --- |
|
|
7
|
+
| **使用类** | [库结构.md](库结构.md)、[metrics.md](metrics.md) | 库的作者、插件的使用者 | 想知道「我的笔记该怎么写」「插件到底怎么打分」 |
|
|
8
|
+
| **设计类** | [契约-stage0/](契约-stage0/) | 改插件的人、审方案的人 | 想知道「知识网关为什么长这样」「某个字段为什么这么定」 |
|
|
9
|
+
|
|
10
|
+
**只想用插件** → 读仓库根目录的 [README.md](../README.md) 就够了,这页是给要动手改的人看的。
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 使用类
|
|
15
|
+
|
|
16
|
+
### [库结构.md](库结构.md) · 163 行
|
|
17
|
+
|
|
18
|
+
**一份目录 + 一堆 `.md` 就能用**,其余全是加分项。文档按四层写:第 0 层最小可用 → 第 1 层 frontmatter 七字段 → 第 2 层 `index.md` 摘要目录 → 第 3 层 `总览-overview.md`。
|
|
19
|
+
|
|
20
|
+
想知道「`别名` 到底有什么用」「`来源数量` 为什么是证据强度的唯一代理」,看这份。
|
|
21
|
+
|
|
22
|
+
### [metrics.md](metrics.md) · 107 行
|
|
23
|
+
|
|
24
|
+
检索**一致性**指标的定义:Recall@5(micro)、Top-1 一致率、Top-5 集合一致率(Jaccard)。
|
|
25
|
+
|
|
26
|
+
文档开头有一句话值得抄下来贴在墙上:*「这些指标不回答『检索得准不准』。名字选错,后面所有人都会拿它当正确答案。」*
|
|
27
|
+
|
|
28
|
+
### [superpowers/specs/](superpowers/specs/)
|
|
29
|
+
|
|
30
|
+
`2026-11-04-wiki-search-panel-design.md` —— 检索面板的设计稿(113 行)。改面板样式前先看它。
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 设计类:契约-stage0
|
|
35
|
+
|
|
36
|
+
这一组是**知识网关**(`wiki_context` / `wiki_verify` / `wiki_observe` 三个工具)的设计与验收记录,按阶段推进,每份都以「已实现 + 已验收」的状态定稿。
|
|
37
|
+
|
|
38
|
+
| 阶段 | 文档 | 行数 | 回答什么问题 |
|
|
39
|
+
| --- | --- | --- | --- |
|
|
40
|
+
| 0 | [阶段0-审计与契约.md](契约-stage0/阶段0-审计与契约.md) | 204 | 现有能力怎么映射成契约?实测发现哪 6 个缺口(F1–F6)?错误码与超时预算怎么定? |
|
|
41
|
+
| 1 | [阶段1-数值判据与引擎状态.md](契约-stage0/阶段1-数值判据与引擎状态.md) | 107 | 「答案里的数字和库里对不上」怎么判定?引擎坏了怎么在输出里看得见? |
|
|
42
|
+
| 2 | [阶段2-快照与TTL.md](契约-stage0/阶段2-快照与TTL.md) | 84 | `wiki_verify` 不重新检索,怎么拿到当初那份证据?快照存什么、多久过期? |
|
|
43
|
+
| 3 | [阶段3-支持原因.md](契约-stage0/阶段3-支持原因.md) | 98 | `support_status` 为什么是这个值?11 个原因码分别什么意思? |
|
|
44
|
+
| 4 | [阶段4-插件接入.md](契约-stage0/阶段4-插件接入.md) | 143 | 插件怎么调 Python 桥?进程协议、文件清单、配置、降级矩阵、踩过的坑 |
|
|
45
|
+
| 5 | [阶段5-观察闭环与实战验收.md](契约-stage0/阶段5-观察闭环与实战验收.md) | 109 | 五类问题(直接事实/证据不足/范围混淆/证据冲突/错误答案)实战验收结果,三层能力对照 |
|
|
46
|
+
| — | [观察期方案.md](契约-stage0/观察期方案.md) | 81 | 真实使用中怎么观察「模型会不会用、用得对不对」?五个观察点怎么测? |
|
|
47
|
+
|
|
48
|
+
### 配套产物
|
|
49
|
+
|
|
50
|
+
- **[knowledge-gateway.v1.schema.json](契约-stage0/knowledge-gateway.v1.schema.json)** —— 契约的机器可读定义(28 KB),`context` / `verify` / `observe_stats` 三种输出的完整字段。
|
|
51
|
+
- **[samples/](契约-stage0/samples/)** —— 8 份真实样例:`context.cq-shenlun.json`(一份完整的 context)、6 份 verify 场景(答对但有缺口 / 编引文 / 范围错 / 数字错 / 快照过期 / 快照损坏)、`_verify_probe.json`。
|
|
52
|
+
改判据前,先拿样例跑一遍 `wiki_verify` 看行为有没有变。
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 阅读顺序建议
|
|
57
|
+
|
|
58
|
+
| 你的目的 | 顺序 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| 第一次用这个插件 | README → [库结构.md](库结构.md) |
|
|
61
|
+
| 想知道插件为什么这么打分 | README「检索质量」节 → [metrics.md](metrics.md) → 阶段 1 |
|
|
62
|
+
| 要加一个新工具 | 阶段 0 → 阶段 4 → `knowledge-gateway.v1.schema.json` |
|
|
63
|
+
| 要改判定逻辑(会拦答案的那种) | 阶段 1(数值判据)→ 阶段 3(支持原因)→ `samples/` |
|
|
64
|
+
| 要看这套东西到底行不行 | 阶段 5 → [观察期方案.md](契约-stage0/观察期方案.md) |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 一条规矩
|
|
69
|
+
|
|
70
|
+
**这些文档记的是「当时的结论」,不是「永久有效的规则」。** 每份文档末尾都有「已知局限」一节 —— 那是设计者自己写下的边界,比正文更值得读。真要改设计,先看局限那一节,多数坑已经写在纸上了。
|
|
@@ -14,8 +14,8 @@
|
|
|
14
14
|
| 模型自述 | 模型自己说「我查了库」 | 低 | 只能作线索 |
|
|
15
15
|
|
|
16
16
|
观察期默认**只信前两类**。日志路径由插件 `bridge.observeLog` 决定,当前是
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
`<你的库根目录>\生活库\_tools\observe\gateway.jsonl`,与自测日志
|
|
18
|
+
`<你的库根目录>\生活库\_tools\eval\observe_log.jsonl` 物理隔离——修 bug 时跑测试不会污染观察数据。
|
|
19
19
|
|
|
20
20
|
## 1. 模型是否先调 wiki_context
|
|
21
21
|
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
```json
|
|
29
29
|
{"snapshot_version":"1","contract_version":"1.0","context_id":"ctx_…",
|
|
30
30
|
"created_at":"…","expires_at":"…","ttl_seconds":1800,
|
|
31
|
-
"query":"重庆 申论 考几道题","root":"
|
|
31
|
+
"query":"重庆 申论 考几道题","root":"<你的库根目录>\\知识层-wiki",
|
|
32
32
|
"payload_sha256":"…","pages":{"概念-concepts/重庆申论考情.md":"a1b2…"},
|
|
33
33
|
"payload":{ /* 完整 context,原样 */ }}
|
|
34
34
|
```
|
|
@@ -111,10 +111,10 @@ stdout 解析取**最后一行能 parse 的 JSON**,容忍 Python 偶尔往 std
|
|
|
111
111
|
| `eval_snapshot` | 12/12 |
|
|
112
112
|
| `eval_conflicts` / `eval_dedup` | 8 / 8 |
|
|
113
113
|
| `eval_method` / `eval_blocks` | 7/7、9/9 |
|
|
114
|
-
| `e2e_check --check` | 8 题漂移 0
|
|
114
|
+
| `e2e_check --check` | 8 题漂移 0(重庆申论页入库后重录 1 条基线,非回归) |
|
|
115
115
|
| `protect.py` | 35 条漂移 0 |
|
|
116
116
|
|
|
117
|
-
**插件侧**:`tests/gateway.mjs` 22/22;原有 17 个测试全绿(smoke/help/topics/lintdiff/lint/params/fields/robust/api/explain/cli/contract/draft/watch/client/status),旧测试只把 mock 改成按名取 `wiki_recall
|
|
117
|
+
**插件侧**:`tests/gateway.mjs` 22/22;原有 17 个测试全绿(smoke/help/topics/lintdiff/lint/params/fields/robust/api/explain/cli/contract/draft/watch/client/status),旧测试只把 mock 改成按名取 `wiki_recall`(注册方式改成按名取后,旧 mock 的「取第一个工具」假设过期了)。
|
|
118
118
|
|
|
119
119
|
**实测开销**(本机,冷启动):`ping` 117ms(纯 spawn + import),完整 `context` 993ms(内部 855ms)。一次问答可接受;高频短问答建议后续做常驻或连接复用。
|
|
120
120
|
|
|
@@ -138,6 +138,9 @@ stdout 解析取**最后一行能 parse 的 JSON**,容忍 Python 偶尔往 std
|
|
|
138
138
|
|
|
139
139
|
## 下一步(阶段 3 原计划)
|
|
140
140
|
|
|
141
|
-
-
|
|
141
|
+
- ~~`wiki_observe` 自动记录(现在 `observe_id` 恒为 null,观察链路还没接上)。~~
|
|
142
|
+
**已接通(1.4.2)**:插件侧记下 `context_id ↔ observe_id` 这一对,wiki_verify 转发时带上,
|
|
143
|
+
观察日志里 verify 记录的 `parent_observe_id` 能指回它的 context。
|
|
144
|
+
插件侧补了显式 `observe_id` 参数兜底;Python 侧契约与实现未动。
|
|
142
145
|
- 降级策略细化:单引擎 error 时是否给模型一条「本次只有一路召回」的显式提示。
|
|
143
146
|
- 第 1 条局限的收口:页面读取单一权威实现。
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# 阶段 5:读取一致性、观察闭环与实战验收
|
|
2
2
|
|
|
3
3
|
> 本轮只做三件事:量一次「两套读取到底差在哪」、把观察闭环接上、拿五类真实问题压一遍。
|
|
4
|
-
>
|
|
4
|
+
> 判据与检索打分一行没动(除抽取补齐的两处:字数对象词、表格行借用页面标题)。
|
|
5
5
|
|
|
6
6
|
## 一、页面读取一致性(`eval_read_parity.py`)
|
|
7
7
|
|
|
@@ -72,6 +72,23 @@ wiki_context ──► context_id(快照)+ observe_id(观察记录)
|
|
|
72
72
|
|
|
73
73
|
验收 `eval_observe_loop.py`:**21/21**(含跨进程查得到、追得回、计数准、不含引文、写不进也不影响主链路、两次调用不串用)。
|
|
74
74
|
|
|
75
|
+
### 插件侧接线(1.4.2 补)
|
|
76
|
+
|
|
77
|
+
上面这条闭环图在 **Python 侧**是通的,但插件侧原本断了一截:`wiki_context` 把 `observe_id` 放在返回体里,
|
|
78
|
+
插件既不在渲染里露出来,也不在 `wiki_verify` 请求里转发——契约里 verify 的返回体不带 `observe_id`,
|
|
79
|
+
Python 也不从快照回查(只认请求里带过去的那一个)。结果就是:走插件时,每条 verify 记录的
|
|
80
|
+
`parent_observe_id` 恒为 null,闭环在最后一跳断开。
|
|
81
|
+
|
|
82
|
+
1.4.2 的补法(Python 侧契约与实现未动):
|
|
83
|
+
|
|
84
|
+
- 插件在 apply() 内记 `context_id ↔ observe_id` 的短期对照表(最多 64 条,换库时清空)。
|
|
85
|
+
- `wiki_verify` 转发时带上这一对的 `observe_id`;另开一个可选 `observe_id` 参数,显式传入时以传入的为准。
|
|
86
|
+
- `renderContext` 把 `observe_id` 一并输出,模型想显式传参时手里有。
|
|
87
|
+
- 回归门禁在 `tests/gateway.mjs`:断言 verify 记录的 `parent_observe_id` 指回 context 的 `observe_id`。
|
|
88
|
+
|
|
89
|
+
**注意**:这条修的是日志溯源,不是统计口径——`observe.stats()` 的「修正序列」本来��按 `context_id` 归组算的,
|
|
90
|
+
`parent_observe_id` 从头到尾没有任何统计代码消费它。
|
|
91
|
+
|
|
75
92
|
## 三、五类问题实战验收(`eval_acceptance.py`)
|
|
76
93
|
|
|
77
94
|
链路与 MCP 工具同一条(`wiki_bridge.py`)。完整报告:`_tools/eval/ACCEPTANCE-2026-11-05.md`。
|
|
@@ -84,7 +101,7 @@ wiki_context ──► context_id(快照)+ observe_id(观察记录)
|
|
|
84
101
|
| D | 多证据冲突 | 重庆申论作文多少字(答 800 字) | partial | `unsupported_numeric_claim`(contradicted) | ✅ 与库内 1000–1200 字冲突被指出 |
|
|
85
102
|
| E | 错误答案 | 重庆申论考五道题 | partial | `unsupported_numeric_claim`(contradicted) | ✅ 数字错、单位对、范围对,仍被抓 |
|
|
86
103
|
|
|
87
|
-
**5/5 符合预期。** 首轮暴露的两个真问题(A 误拦、D
|
|
104
|
+
**5/5 符合预期。** 首轮暴露的两个真问题(A 误拦、D 漏报)已修,修法记在这份文档末尾(判据放宽、主张范围继承、区间比较、表格证据补齐),细节见各阶段的验收记录。
|
|
88
105
|
|
|
89
106
|
1. `unverifiable` 不再升 violation,只进 `notices`——「说不清」不等于「说错了」。
|
|
90
107
|
2. 主张范围继承整段回答——中文答句句首声明「重庆……」,后面分句省略主语。
|
|
@@ -107,3 +124,6 @@ wiki_context ──► context_id(快照)+ observe_id(观察记录)
|
|
|
107
124
|
4. **`numeric_claim` 不做跨句推理**:主张散落在两句里(「作文 40 分。」「字数 1000–1200。」)时,靠整段口径继承兜底,不做句间绑定。
|
|
108
125
|
5. **观察日志无轮转**:只追加,不清理;`legacy` 计数会随时间变大,需要时手工归档。
|
|
109
126
|
6. **快照不自动清理**,也没有滑动续期。
|
|
127
|
+
7. **插件侧的 `observe_id` 对照表只在内存里**:插件重启后,之前的 `context_id` 查不到对应的 `observe_id`,
|
|
128
|
+
这时 verify 仍能跑(核验靠快照,不靠这张表),但那条 verify 记录的 `parent_observe_id` 会是空的。
|
|
129
|
+
跨进程、跨重启追不回——这是设计取舍:把编号写进快照要多动 Python 侧契约。
|
package/lib/client.js
CHANGED
|
@@ -582,7 +582,7 @@ window.__ModuleLoader__.load({
|
|
|
582
582
|
value: draft,
|
|
583
583
|
spellCheck: false,
|
|
584
584
|
'aria-label': '知识库目录路径',
|
|
585
|
-
placeholder: '例如
|
|
585
|
+
placeholder: '例如 /home/me/notes 或 <你的库根目录>\\知识层-wiki',
|
|
586
586
|
onChange: function (event) {
|
|
587
587
|
setDraft(event.target.value)
|
|
588
588
|
// 换了路径,上一次「扫不出页面」的结论就不再指同一个东西了。
|
package/lib/index.js
CHANGED
|
@@ -276,6 +276,33 @@ export function apply(ctx, config = {}) {
|
|
|
276
276
|
generation += 1
|
|
277
277
|
}
|
|
278
278
|
|
|
279
|
+
/**
|
|
280
|
+
* context_id → observe_id 的短期对照表。
|
|
281
|
+
*
|
|
282
|
+
* 为什么插件要自己记:观察闭环要求 verify 记录能指回它的 context(parent_observe_id),
|
|
283
|
+
* 但契约里 verify 的返回体不带 observe_id,Python 侧也不从快照回查 ——
|
|
284
|
+
* 只认请求里带过去的那一个(`req.get("observe_id")`)。所以这一对得由插件存着,转发时补上。
|
|
285
|
+
*
|
|
286
|
+
* 换库时清掉:旧库的编号留着只会指错地方。
|
|
287
|
+
* 内存里只留最近几条:context_id 每次都是新 uuid,用不到几轮。
|
|
288
|
+
*/
|
|
289
|
+
const observeIds = new Map()
|
|
290
|
+
const OBSERVE_ID_MAP_MAX = 64
|
|
291
|
+
|
|
292
|
+
function rememberObserve(contextId, observeId) {
|
|
293
|
+
observeIds.set(contextId, observeId)
|
|
294
|
+
while (observeIds.size > OBSERVE_ID_MAP_MAX) {
|
|
295
|
+
const oldest = observeIds.keys().next()
|
|
296
|
+
if (oldest.done) break
|
|
297
|
+
observeIds.delete(oldest.value)
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/** 查一对对应关系;查不到就返回空串,不猜。 */
|
|
302
|
+
function lookupObserve(contextId) {
|
|
303
|
+
return observeIds.get(contextId) ?? ''
|
|
304
|
+
}
|
|
305
|
+
|
|
279
306
|
/* ---------------------- 目录监听:库是活的 ---------------------- */
|
|
280
307
|
// 有 30 秒缓存兜底就够了,但「刚改完笔记,模型还在念旧版本」很容易让人以为插件坏了。
|
|
281
308
|
// 监听只做一件事:发现 .md 变了就作废缓存,下次查询重扫(70 页约 40ms,重扫不心疼)。
|
|
@@ -309,7 +336,11 @@ export function apply(ctx, config = {}) {
|
|
|
309
336
|
const watchRoot = drillTarget(root) || root
|
|
310
337
|
let handle
|
|
311
338
|
try {
|
|
312
|
-
|
|
339
|
+
// persistent: false —— 声明的就是「这个句柄不该把进程钉住」。
|
|
340
|
+
// 光靠下面的 handle.unref() 不够:Linux 上 recursive watch 是「每个子目录一个 inotify 句柄」,
|
|
341
|
+
// unref() 只作用于主 handle,子句柄仍然是 ref 状态,Node 20/22 上进程跑完测试不退(CI 里挂死 15 分钟)。
|
|
342
|
+
// Node 24 重写了实现、Windows 用单句柄,所以只有 ubuntu + node20/22 这一格暴露。
|
|
343
|
+
handle = watch(watchRoot, { recursive: true, persistent: false }, (_event, filename) => {
|
|
313
344
|
const name = String(filename ?? '')
|
|
314
345
|
// 只认笔记:编辑器保存时会带出 .swp/.tmp/xxx.md~ 之类的临时文件,别为它们重扫整库
|
|
315
346
|
if (name !== '' && !/\.md$/i.test(name)) return
|
|
@@ -616,6 +647,8 @@ export function apply(ctx, config = {}) {
|
|
|
616
647
|
rootInfo = resolveWikiRootInfo(pluginRoot, inlineRoot)
|
|
617
648
|
root = rootInfo.root
|
|
618
649
|
invalidate()
|
|
650
|
+
// 换了库,旧库的 context_id ↔ observe_id 对就指错地方了,清掉。
|
|
651
|
+
observeIds.clear()
|
|
619
652
|
startWatch()
|
|
620
653
|
return sendJson(res, 200, await buildState())
|
|
621
654
|
}
|
|
@@ -729,6 +762,9 @@ function renderContext(args, value) {
|
|
|
729
762
|
|
|
730
763
|
if (value.answer?.contract_text) lines.push('', value.answer.contract_text.trim())
|
|
731
764
|
if (value.context_id) lines.push('', `context_id:${value.context_id}(可交给 wiki_verify 核验回答)`)
|
|
765
|
+
// observe_id 也露出来:观察日志靠它把 verify 记录挂回这条 context。
|
|
766
|
+
// 插件会自动转发它,所以模型不用管;但写出来,模型想显式传参时手里有。
|
|
767
|
+
if (value.observe_id) lines.push(`observe_id:${value.observe_id}`)
|
|
732
768
|
return lines.join('\n')
|
|
733
769
|
}
|
|
734
770
|
|
|
@@ -850,12 +886,18 @@ const registerGateway = () => {
|
|
|
850
886
|
if (query === '') {
|
|
851
887
|
return errorEnvelope('E_QUERY_EMPTY', 'query 不能为空', 'validate')
|
|
852
888
|
}
|
|
853
|
-
|
|
889
|
+
const value = await callBridge('context', {
|
|
854
890
|
query: query.slice(0, MAX_QUERY_CHARS * 4),
|
|
855
891
|
limit: args?.limit,
|
|
856
892
|
engine: args?.engine,
|
|
857
893
|
ttl_seconds: args?.ttl_seconds,
|
|
858
894
|
})
|
|
895
|
+
// 记下 context_id ↔ observe_id 这一对,verify 时自动带上(见 lookupObserve)。
|
|
896
|
+
// 观察记录写不进去时 Python 返回 observe_id=null,这里也就没得记 —— 不硬造。
|
|
897
|
+
if (value && value.kind === 'context' && value.context_id && value.observe_id) {
|
|
898
|
+
rememberObserve(value.context_id, value.observe_id)
|
|
899
|
+
}
|
|
900
|
+
return value
|
|
859
901
|
},
|
|
860
902
|
}))
|
|
861
903
|
|
|
@@ -871,6 +913,12 @@ const registerGateway = () => {
|
|
|
871
913
|
properties: {
|
|
872
914
|
context_id: { type: 'string', description: 'wiki_context 返回的 context_id' },
|
|
873
915
|
answer: { type: 'string', description: '要核验的回答原文' },
|
|
916
|
+
observe_id: {
|
|
917
|
+
type: 'string',
|
|
918
|
+
description:
|
|
919
|
+
'可选:wiki_context 返回的 observe_id。插件会自动带上与之对应的那个,'
|
|
920
|
+
+ '一般不用自己传;显式传了则以你传的这个为准。',
|
|
921
|
+
},
|
|
874
922
|
},
|
|
875
923
|
required: ['context_id', 'answer'],
|
|
876
924
|
additionalProperties: false,
|
|
@@ -888,7 +936,16 @@ const registerGateway = () => {
|
|
|
888
936
|
if (answer.trim() === '') {
|
|
889
937
|
return errorEnvelope('E_VERIFY_EMPTY_ANSWER', 'answer 不能为空', 'validate')
|
|
890
938
|
}
|
|
891
|
-
|
|
939
|
+
// observe_id 转发:显式传的优先,否则用插件记下的那一对。
|
|
940
|
+
// Python 侧只认请求里带的 observe_id(不从快照回查),不传就等于把 verify
|
|
941
|
+
// 记录和它的 context 拆成两条互不相认的日志。
|
|
942
|
+
const explicit = typeof args?.observe_id === 'string' ? args.observe_id.trim() : ''
|
|
943
|
+
const observeId = explicit || lookupObserve(contextId)
|
|
944
|
+
return callBridge('verify', {
|
|
945
|
+
context_id: contextId,
|
|
946
|
+
answer,
|
|
947
|
+
...(observeId ? { observe_id: observeId } : {}),
|
|
948
|
+
})
|
|
892
949
|
},
|
|
893
950
|
}))
|
|
894
951
|
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-wiki-notes",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.2",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "Read-only Markdown knowledge-base retrieval for DeepSeek Harness: one wiki_recall tool (search/page/list/overview/lint/draft) returning the matching section's full text with page-level citations, plus
|
|
5
|
+
"description": "Read-only Markdown knowledge-base retrieval for DeepSeek Harness: one wiki_recall tool (search/page/list/overview/lint/draft) returning the matching section's full text with page-level citations, plus three knowledge-gateway tools (wiki_context / wiki_verify / wiki_observe) that delegate evidence judgement to the local LLM-Wiki Python pipeline. 中文:本地 Markdown 笔记库检索插件,一次调用返回命中小节正文与出处,另带健康检查与回写骨架;新增知识网关三工具(wiki_context / wiki_verify / wiki_observe),证据判定交给本地 Python 管线,插件只负责调用与错误隔离。",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"deepseek",
|
|
8
8
|
"deepseek-harness",
|