dsh-wiki-notes 1.4.1 → 1.4.3

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.
Files changed (20) hide show
  1. package/README.md +49 -4
  2. package/docs/README.md +1 -1
  3. package/docs/superpowers/plans/2026-11-05-wiki-call-audit.md +553 -0
  4. package/docs/superpowers/specs/2026-11-05-wiki-call-audit-design.md +164 -0
  5. package/docs//345/245/221/347/272/246-stage0/samples/_verify_probe.json +1 -1
  6. package/docs//345/245/221/347/272/246-stage0/samples/{context.cq-shenlun.json → context.sample-cache.json} +80 -80
  7. package/docs//345/245/221/347/272/246-stage0/samples/verify.fabricated-quote.json +3 -3
  8. package/docs//345/245/221/347/272/246-stage0/samples/verify.scope-mismatch.json +3 -3
  9. package/docs//345/245/221/347/272/246-stage0/samples/verify.wrong-five.json +9 -9
  10. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2650-/345/256/241/350/256/241/344/270/216/345/245/221/347/272/246.md +10 -10
  11. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2651-/346/225/260/345/200/274/345/210/244/346/215/256/344/270/216/345/274/225/346/223/216/347/212/266/346/200/201.md +9 -9
  12. 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 +3 -3
  13. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2653-/346/224/257/346/214/201/345/216/237/345/233/240.md +3 -3
  14. 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 +5 -2
  15. 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 +30 -10
  16. package/lib/calls.js +250 -0
  17. package/lib/client.js +350 -11
  18. package/lib/config.js +33 -0
  19. package/lib/index.js +156 -7
  20. package/package.json +6 -4
package/lib/index.js CHANGED
@@ -19,7 +19,8 @@ import { mkdirSync, readFileSync, statSync, watch, writeFileSync } from 'node:fs
19
19
  import { fileURLToPath } from 'node:url'
20
20
 
21
21
  import { asList, loadCorpus } from './corpus.js'
22
- import { mergePromptConfig, mergeTopicConfig, normalizeTopicConfig, readBridgeConfig, readTopicConfig, writeTopicConfig } from './config.js'
22
+ import { createCallLog } from './calls.js'
23
+ import { mergePromptConfig, mergeTopicConfig, normalizeTopicConfig, readBridgeConfig, readCallsConfig, readTopicConfig, writeCallsConfig, writeTopicConfig } from './config.js'
23
24
  import { MODES, freshnessOf, lint, run } from './engine.js'
24
25
  import { configPath, DEFAULT_WIKI_ROOT, NOT_CONFIGURED_HINT, readConfigFile, normalizePromptConfig, readPromptConfig, resolveWikiRootInfo, writeConfigFile, writePromptConfig } from './config.js'
25
26
  import { errorEnvelope, runBridge } from './bridge.js'
@@ -262,6 +263,30 @@ export function apply(ctx, config = {}) {
262
263
  let promptCfg = normalizePromptConfig(config?.prompt) ?? readPromptConfig(pluginRoot)
263
264
  let topicCfg = normalizeTopicConfig(config?.topics) ?? readTopicConfig(pluginRoot)
264
265
 
266
+ /**
267
+ * 调用账本。
268
+ *
269
+ * 位置优先级:DSH_WIKI_CALLS_LOG(测试与临时排查)> 配置里的 calls.log > 插件目录旁的
270
+ * calls.jsonl。绝不写进知识库本体 —— 库是用户的,插件只能在库外面留账。
271
+ */
272
+ let callsCfg = readCallsConfig(pluginRoot)
273
+ const calls = createCallLog({
274
+ file: process.env.DSH_WIKI_CALLS_LOG || callsCfg.log || path.join(pluginRoot, 'calls.jsonl'),
275
+ enabled: callsCfg.enabled,
276
+ })
277
+
278
+ /**
279
+ * 记一条调用。旁路:记账失败绝不能变成工具失败 ——
280
+ * 审计的价值远小于「查库还能用」,坏了就让它坏在暗处。
281
+ */
282
+ function recordCall(entry) {
283
+ try {
284
+ calls.record(entry)
285
+ } catch {
286
+ // 吞掉:账本写不进去不该影响检索
287
+ }
288
+ }
289
+
265
290
  let cache = null
266
291
  let cachedAt = 0
267
292
  let inflight = null
@@ -276,6 +301,33 @@ export function apply(ctx, config = {}) {
276
301
  generation += 1
277
302
  }
278
303
 
304
+ /**
305
+ * context_id → observe_id 的短期对照表。
306
+ *
307
+ * 为什么插件要自己记:观察闭环要求 verify 记录能指回它的 context(parent_observe_id),
308
+ * 但契约里 verify 的返回体不带 observe_id,Python 侧也不从快照回查 ——
309
+ * 只认请求里带过去的那一个(`req.get("observe_id")`)。所以这一对得由插件存着,转发时补上。
310
+ *
311
+ * 换库时清掉:旧库的编号留着只会指错地方。
312
+ * 内存里只留最近几条:context_id 每次都是新 uuid,用不到几轮。
313
+ */
314
+ const observeIds = new Map()
315
+ const OBSERVE_ID_MAP_MAX = 64
316
+
317
+ function rememberObserve(contextId, observeId) {
318
+ observeIds.set(contextId, observeId)
319
+ while (observeIds.size > OBSERVE_ID_MAP_MAX) {
320
+ const oldest = observeIds.keys().next()
321
+ if (oldest.done) break
322
+ observeIds.delete(oldest.value)
323
+ }
324
+ }
325
+
326
+ /** 查一对对应关系;查不到就返回空串,不猜。 */
327
+ function lookupObserve(contextId) {
328
+ return observeIds.get(contextId) ?? ''
329
+ }
330
+
279
331
  /* ---------------------- 目录监听:库是活的 ---------------------- */
280
332
  // 有 30 秒缓存兜底就够了,但「刚改完笔记,模型还在念旧版本」很容易让人以为插件坏了。
281
333
  // 监听只做一件事:发现 .md 变了就作废缓存,下次查询重扫(70 页约 40ms,重扫不心疼)。
@@ -309,7 +361,11 @@ export function apply(ctx, config = {}) {
309
361
  const watchRoot = drillTarget(root) || root
310
362
  let handle
311
363
  try {
312
- handle = watch(watchRoot, { recursive: true }, (_event, filename) => {
364
+ // persistent: false —— 声明的就是「这个句柄不该把进程钉住」。
365
+ // 光靠下面的 handle.unref() 不够:Linux 上 recursive watch 是「每个子目录一个 inotify 句柄」,
366
+ // unref() 只作用于主 handle,子句柄仍然是 ref 状态,Node 20/22 上进程跑完测试不退(CI 里挂死 15 分钟)。
367
+ // Node 24 重写了实现、Windows 用单句柄,所以只有 ubuntu + node20/22 这一格暴露。
368
+ handle = watch(watchRoot, { recursive: true, persistent: false }, (_event, filename) => {
313
369
  const name = String(filename ?? '')
314
370
  // 只认笔记:编辑器保存时会带出 .swp/.tmp/xxx.md~ 之类的临时文件,别为它们重扫整库
315
371
  if (name !== '' && !/\.md$/i.test(name)) return
@@ -579,6 +635,15 @@ export function apply(ctx, config = {}) {
579
635
  limit: clampLimit(parsed.searchParams.get('limit')),
580
636
  explain: true,
581
637
  })
638
+ recordCall({
639
+ source: 'panel',
640
+ tool: 'wiki_recall',
641
+ mode: 'search',
642
+ query,
643
+ hits: Array.isArray(result?.hits) ? result.hits.length : 0,
644
+ ms: Date.now() - started,
645
+ ok: true,
646
+ })
582
647
  return sendJson(res, 200, {
583
648
  ...result,
584
649
  // 面板要的分母:扫了多少页、扫描本身花了多久、这次查询花了多久
@@ -587,6 +652,27 @@ export function apply(ctx, config = {}) {
587
652
  elapsedMs: Date.now() - started,
588
653
  })
589
654
  }
655
+ // 调用审计:账本只读得回最近的调用,够回答「模型到底查没查、查了什么、查到没有」。
656
+ if (route === '/calls' && req.method === 'GET') {
657
+ const parsed = new URL(req.url ?? '/', 'http://127.0.0.1')
658
+ const limit = Number(parsed.searchParams.get('limit'))
659
+ return sendJson(res, 200, calls.read({
660
+ limit: Number.isFinite(limit) ? limit : undefined,
661
+ source: parsed.searchParams.get('source') ?? 'all',
662
+ only: parsed.searchParams.get('only') ?? 'all',
663
+ }))
664
+ }
665
+ if (route === '/calls/config' && req.method === 'POST') {
666
+ const body = await readBody(req)
667
+ if (body === undefined) return sendJson(res, 400, { error: '请求体不是合法 JSON' })
668
+ callsCfg = writeCallsConfig(pluginRoot, { ...callsCfg, ...body }).config
669
+ calls.setEnabled(callsCfg.enabled)
670
+ return sendJson(res, 200, { enabled: callsCfg.enabled })
671
+ }
672
+ if (route === '/calls/clear' && req.method === 'POST') {
673
+ calls.clear()
674
+ return sendJson(res, 200, { ok: true })
675
+ }
590
676
  if (route === '/check' && req.method === 'POST') {
591
677
  const body = await readBody(req)
592
678
  return sendJson(res, 200, await probeRoot(body?.root))
@@ -616,6 +702,8 @@ export function apply(ctx, config = {}) {
616
702
  rootInfo = resolveWikiRootInfo(pluginRoot, inlineRoot)
617
703
  root = rootInfo.root
618
704
  invalidate()
705
+ // 换了库,旧库的 context_id ↔ observe_id 对就指错地方了,清掉。
706
+ observeIds.clear()
619
707
  startWatch()
620
708
  return sendJson(res, 200, await buildState())
621
709
  }
@@ -729,6 +817,9 @@ function renderContext(args, value) {
729
817
 
730
818
  if (value.answer?.contract_text) lines.push('', value.answer.contract_text.trim())
731
819
  if (value.context_id) lines.push('', `context_id:${value.context_id}(可交给 wiki_verify 核验回答)`)
820
+ // observe_id 也露出来:观察日志靠它把 verify 记录挂回这条 context。
821
+ // 插件会自动转发它,所以模型不用管;但写出来,模型想显式传参时手里有。
822
+ if (value.observe_id) lines.push(`observe_id:${value.observe_id}`)
732
823
  return lines.join('\n')
733
824
  }
734
825
 
@@ -796,9 +887,22 @@ function renderObserve(args, value) {
796
887
 
797
888
  /** 统一的 Bridge 调用包装:配置从插件配置读,错就错在明处。 */
798
889
  async function callBridge(command, payload) {
890
+ const started = Date.now()
799
891
  const cfg = readBridgeConfig(pluginRoot)
800
892
  const rootInfo = resolveWikiRootInfo(pluginRoot, root)
893
+ /** 网关这条路上「一次调用」的记账:三个工具都从这里过,记在一处不散。 */
894
+ const note = (hits, ok) => recordCall({
895
+ tool: `wiki_${command}`,
896
+ mode: typeof payload?.engine === 'string' ? payload.engine : '',
897
+ query: typeof payload?.query === 'string' ? payload.query : '',
898
+ // 只有 context 会产生「命中了几页证据」;verify 是核对、observe 是读统计,
899
+ // 记成 0 会把命中率的分母悄悄稀释,所以记 null。
900
+ hits: command === 'context' ? hits : null,
901
+ ms: Date.now() - started,
902
+ ok,
903
+ })
801
904
  if (rootInfo.root === '') {
905
+ note(null, false)
802
906
  return errorEnvelope('E_WIKI_ROOT_MISSING', NOT_CONFIGURED_HINT, 'validate')
803
907
  }
804
908
  const result = await runBridge({
@@ -811,8 +915,13 @@ async function callBridge(command, payload) {
811
915
  env: cfg.observeLog ? { WIKI_OBSERVE_LOG: cfg.observeLog } : {},
812
916
  pluginVersion: PLUGIN_VERSION,
813
917
  })
814
- if (!result.ok) return result.error
815
- return result.data ?? errorEnvelope('E_BRIDGE_CRASH', 'Bridge 返回了空结果', 'bridge')
918
+ if (!result.ok) {
919
+ note(null, false)
920
+ return result.error
921
+ }
922
+ const data = result.data ?? errorEnvelope('E_BRIDGE_CRASH', 'Bridge 返回了空结果', 'bridge')
923
+ note(Array.isArray(data?.evidence) ? data.evidence.length : 0, true)
924
+ return data
816
925
  }
817
926
 
818
927
  const registerGateway = () => {
@@ -850,12 +959,18 @@ const registerGateway = () => {
850
959
  if (query === '') {
851
960
  return errorEnvelope('E_QUERY_EMPTY', 'query 不能为空', 'validate')
852
961
  }
853
- return callBridge('context', {
962
+ const value = await callBridge('context', {
854
963
  query: query.slice(0, MAX_QUERY_CHARS * 4),
855
964
  limit: args?.limit,
856
965
  engine: args?.engine,
857
966
  ttl_seconds: args?.ttl_seconds,
858
967
  })
968
+ // 记下 context_id ↔ observe_id 这一对,verify 时自动带上(见 lookupObserve)。
969
+ // 观察记录写不进去时 Python 返回 observe_id=null,这里也就没得记 —— 不硬造。
970
+ if (value && value.kind === 'context' && value.context_id && value.observe_id) {
971
+ rememberObserve(value.context_id, value.observe_id)
972
+ }
973
+ return value
859
974
  },
860
975
  }))
861
976
 
@@ -871,6 +986,12 @@ const registerGateway = () => {
871
986
  properties: {
872
987
  context_id: { type: 'string', description: 'wiki_context 返回的 context_id' },
873
988
  answer: { type: 'string', description: '要核验的回答原文' },
989
+ observe_id: {
990
+ type: 'string',
991
+ description:
992
+ '可选:wiki_context 返回的 observe_id。插件会自动带上与之对应的那个,'
993
+ + '一般不用自己传;显式传了则以你传的这个为准。',
994
+ },
874
995
  },
875
996
  required: ['context_id', 'answer'],
876
997
  additionalProperties: false,
@@ -888,7 +1009,16 @@ const registerGateway = () => {
888
1009
  if (answer.trim() === '') {
889
1010
  return errorEnvelope('E_VERIFY_EMPTY_ANSWER', 'answer 不能为空', 'validate')
890
1011
  }
891
- return callBridge('verify', { context_id: contextId, answer })
1012
+ // observe_id 转发:显式传的优先,否则用插件记下的那一对。
1013
+ // Python 侧只认请求里带的 observe_id(不从快照回查),不传就等于把 verify
1014
+ // 记录和它的 context 拆成两条互不相认的日志。
1015
+ const explicit = typeof args?.observe_id === 'string' ? args.observe_id.trim() : ''
1016
+ const observeId = explicit || lookupObserve(contextId)
1017
+ return callBridge('verify', {
1018
+ context_id: contextId,
1019
+ answer,
1020
+ ...(observeId ? { observe_id: observeId } : {}),
1021
+ })
892
1022
  },
893
1023
  }))
894
1024
 
@@ -942,8 +1072,27 @@ const registerGateway = () => {
942
1072
  if (typeof corpus.drilledFrom === 'string') result.drilledFrom = corpus.drilledFrom
943
1073
  result.ms = Date.now() - started
944
1074
  }
945
- return result ?? { mode: 'error', error: '查询没有返回结果(mode 可能传错了)' }
1075
+ const value = result ?? { mode: 'error', error: '查询没有返回结果(mode 可能传错了)' }
1076
+ recordCall({
1077
+ tool: 'wiki_recall',
1078
+ mode: typeof value?.mode === 'string' ? value.mode : '',
1079
+ query: typeof args?.query === 'string' ? args.query : '',
1080
+ // 只有 search 有「命中几页」这回事。page/list 是「读到了就是读到了」,
1081
+ // 记成 0 会把命中率的分子分母一起带歪,所以记 null 让它不进统计。
1082
+ hits: value?.mode === 'search' && Array.isArray(value.hits) ? value.hits.length : null,
1083
+ ms: Date.now() - started,
1084
+ ok: value?.mode !== 'error',
1085
+ })
1086
+ return value
946
1087
  } catch (error) {
1088
+ recordCall({
1089
+ tool: 'wiki_recall',
1090
+ mode: typeof args?.mode === 'string' ? args.mode : '',
1091
+ query: typeof args?.query === 'string' ? args.query : '',
1092
+ hits: null,
1093
+ ms: Date.now() - started,
1094
+ ok: false,
1095
+ })
947
1096
  // 工具层不往上抛:把「库读不出来」变成一条模型看得懂、能转告用户的错误,
948
1097
  // 而不是一次工具调用失败。库里 0 页和库里没有这个词,是两回事。
949
1098
  // 这里只剩两类:没配路径(用户该去设置页),以及真正的程序异常(该转告)。
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "dsh-wiki-notes",
3
- "version": "1.4.1",
3
+ "version": "1.4.3",
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 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 管线,插件只负责调用与错误隔离。",
5
+ "description": "Read-only knowledge gateway over a local Markdown vault for DeepSeek Harness — recall, evidence pack, answer verification, call audit | 本地 Markdown 笔记库的只读知识网关:检索、证据包、核验、调用审计",
6
6
  "keywords": [
7
7
  "deepseek",
8
8
  "deepseek-harness",
@@ -12,7 +12,9 @@
12
12
  "notes",
13
13
  "markdown",
14
14
  "retrieval",
15
- "obsidian"
15
+ "obsidian",
16
+ "knowledge-base",
17
+ "llm"
16
18
  ],
17
19
  "main": "lib/index.js",
18
20
  "exports": {
@@ -37,7 +39,7 @@
37
39
  "node": ">=20.13.0"
38
40
  },
39
41
  "scripts": {
40
- "test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/watch.mjs && node tests/client.mjs",
42
+ "test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/calls.mjs && node tests/watch.mjs && node tests/client.mjs",
41
43
  "cli": "node bin/cli.mjs",
42
44
  "probe": "node tools/probe.mjs"
43
45
  },