dsh-wiki-notes 1.4.1 → 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 +6 -4
- 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 +4 -1
- 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 +20 -0
- package/lib/index.js +60 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
|
|
71
71
|
### `wiki_verify` —— 核验回答
|
|
72
72
|
|
|
73
|
-
写完答案后自查(尤其含数字、范围、年份、题量分值这类主张时)用它。参数:`context_id` + `answer
|
|
73
|
+
写完答案后自查(尤其含数字、范围、年份、题量分值这类主张时)用它。参数:`context_id` + `answer`(可选 `observe_id`,一般不用传,插件会自动带上)。
|
|
74
74
|
|
|
75
75
|
它不重新检索 —— 拿当初那份快照来比,所以快,也不受库里后来改动的影响。
|
|
76
76
|
|
|
@@ -78,6 +78,8 @@
|
|
|
78
78
|
|
|
79
79
|
`context_expired` / `context_missing` 是**快照问题**,不等于回答错了:重新取一份 context 再核验就行。
|
|
80
80
|
|
|
81
|
+
每次核验都会往观察日志追加一条记录,并用 `parent_observe_id` 指回当初那份 context —— 这样「哪次核验修好了哪次回答」在日志里追得回。
|
|
82
|
+
|
|
81
83
|
### `wiki_observe` —— 诊断
|
|
82
84
|
|
|
83
85
|
参数:`days`(1–365,默认 7)、`limit`(1–50,默认 10)。
|
|
@@ -249,10 +251,10 @@ tests/ smoke / status / lint / explain / api / help / contract / watch
|
|
|
249
251
|
```
|
|
250
252
|
|
|
251
253
|
```bash
|
|
252
|
-
|
|
254
|
+
npm test # 跑样例库,不需要本地知识库
|
|
253
255
|
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
254
256
|
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
255
|
-
|
|
257
|
+
npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
|
|
256
258
|
node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
|
|
257
259
|
node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
|
|
258
260
|
```
|
|
@@ -263,7 +265,7 @@ node tools/preview.mjs --diag # 同上,并量一遍宽度
|
|
|
263
265
|
WIKI_ROOT="/path/your/知识层-wiki" WIKI_TOOLS="/path/your/工具-tools" node tests/gateway.mjs
|
|
264
266
|
```
|
|
265
267
|
|
|
266
|
-
发版:改 `version` → `node --run test`
|
|
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 去查)。
|
|
267
269
|
|
|
268
270
|
改样式的两条经验:
|
|
269
271
|
|
|
@@ -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 条局限的收口:页面读取单一权威实现。
|
|
@@ -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`。
|
|
@@ -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/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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-wiki-notes",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.2",
|
|
4
4
|
"type": "module",
|
|
5
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": [
|