dsh-wiki-notes 1.4.2 → 1.5.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.
Files changed (27) hide show
  1. package/README.md +43 -0
  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/superpowers/specs/2026-11-07-wiki-verification-governance-design.657.md +657 -0
  6. package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.661.md +661 -0
  7. package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.final.md +661 -0
  8. package/docs/superpowers/specs/2026-11-07-wiki-verification-governance-design.md +661 -0
  9. package/docs//345/245/221/347/272/246-stage0/samples/_verify_probe.json +1 -1
  10. package/docs//345/245/221/347/272/246-stage0/samples/{context.cq-shenlun.json → context.sample-cache.json} +80 -80
  11. package/docs//345/245/221/347/272/246-stage0/samples/verify.fabricated-quote.json +3 -3
  12. package/docs//345/245/221/347/272/246-stage0/samples/verify.scope-mismatch.json +3 -3
  13. package/docs//345/245/221/347/272/246-stage0/samples/verify.wrong-five.json +9 -9
  14. 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
  15. 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
  16. 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
  17. 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
  18. 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 +1 -1
  19. 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 +10 -10
  20. package/lib/bridge.js +10 -0
  21. package/lib/calls.js +167 -0
  22. package/lib/client.js +463 -11
  23. package/lib/config.js +33 -0
  24. package/lib/governance.js +849 -0
  25. package/lib/index.js +298 -14
  26. package/lib/jsonl-store.js +137 -0
  27. package/package.json +7 -5
@@ -0,0 +1,164 @@
1
+ # 调用审计页设计(设置页新标签页)
2
+
3
+ 日期:2026-11-05 · 状态:已实现(1.4.3)· 规模:小(约 400 行)
4
+
5
+ ## 为什么
6
+
7
+ 知识库有没有被用起来,现在没人知道。
8
+
9
+ `wiki_observe` 的统计只覆盖走 Python 网关的 `wiki_context` / `wiki_verify`。
10
+ 实测本机:`wiki_recall` 被调用 158 次,观察日志里 **0 条**——因为 recall 是纯 JS
11
+ 路径,从头到尾没有写日志的代码。结果是「库到底有没有帮上忙」这个问题,
12
+ 插件自己答不上来。
13
+
14
+ 这个页面回答的是使用审计问题:**模型到底有没有查库、查了什么、查到没有。**
15
+
16
+ ## 目标
17
+
18
+ - 设置页「知识库」入口里新增一个**页内页签**「调用记录」,展示调用流水。
19
+ (2026-11-05 修正:不新开第二个 `settings.section` —— 那会变成左侧多一个一级入口,
20
+ 而「路径/体检/提示词」和「谁问过它」回答的是同一个问题,拆两处只会让人多点一次。)
21
+ - 每次工具调用(四个 wiki 工具)与每次面板手查,都留一条最小记录。
22
+ - 顶部三个数:今日调用次数、命中率、零命中次数。
23
+ - 流水表:时间 / 来源 / 工具 / 问题 / 命中数 / 耗时。
24
+ - 能筛:全部 / 只看模型 / 只看面板 / 只看零命中。
25
+ - 能一键清空记录。
26
+
27
+ ## 非目标(本轮不做)
28
+
29
+ - 「哪类问题压根没查库」——这需要读 DSH 会话转录,要 Node 22.15+ 的
30
+ `zstdDecompressSync`,而 `engines` 是 `>=20.13.0`。留待下一轮。
31
+ - 任何检索算法改动:分词、评分、排序一律不动。
32
+ - 记录正文、页面路径、答案原文。
33
+ - 跨机器同步、上传、任何网络出口。
34
+
35
+ ## 约束
36
+
37
+ - `lib/client.js` 是手写 bundle,无构建步骤,只能用 `React.createElement`(`h`)。
38
+ - 客户端改动要**重启 DSH** 才生效。
39
+ - 客户端组件必须能在 `tests/client.mjs` 的 React stub 下加载。
40
+ - 插件当前**零运行时依赖**,本设计不新增依赖。
41
+ - 写盘一律走插件根目录(已在 `.gitignore`),不写进知识库。
42
+
43
+ ## 方案(已选 B)
44
+
45
+ | 方案 | 代价 | 结论 |
46
+ |---|---|---|
47
+ | A 只放内存环形缓冲 | 约 250 行 | 能看,但重启即空,审计要的跨天趋势拿不到 |
48
+ | **B 内存 + 追加写 jsonl** | 约 400 行 | **选中**:有历史,字段最小化后不增加隐私面 |
49
+ | C 复用 Python 观察日志 | 约 200 行 | 不做:recall 走 Python 会把 0–2ms 拖成进程启动级,违背原设计 |
50
+
51
+ ## 怎么实现
52
+
53
+ ### 1. 采集点:包一层 `execute`,不碰各工具内部
54
+
55
+ 四个工具都经 `ctx.tools.register` 注册。新增一个小包装器:
56
+
57
+ ```js
58
+ function traced(name, execute) {
59
+ return async function (args) {
60
+ const started = Date.now()
61
+ let ok = true, hits = null
62
+ try {
63
+ const value = await execute(args)
64
+ if (value && value.mode === 'error') ok = false
65
+ hits = countHits(value)
66
+ return value
67
+ } catch (error) {
68
+ ok = false
69
+ throw error
70
+ } finally {
71
+ if (callsOn) record({ source: 'model', tool: name, mode: modeOf(args),
72
+ query: queryOf(args), hits, ms: Date.now() - started, ok })
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ `countHits`:
79
+ - recall → `Array.isArray(value.hits) ? value.hits.length : 0`(非 search 模式记 null)
80
+ - context → `value.evidence?.length ?? 0`
81
+ - verify / observe → `null`(它们不产生「命中页」,硬塞一个数会让命中率失真)
82
+
83
+ `queryOf`:recall/context 取 `args.query`;verify 取 `args.context_id`;
84
+ observe 取空。**截到 120 字**,超了加省略号。
85
+
86
+ 面板手查(`GET /search`)在 handler 里单独调一次 `record({source:'panel', tool:'search', …})`,
87
+ 与模型调用同表不同色。
88
+
89
+ **不包 `execute` 之外的任何东西**:不改工具返回值、不改 schema、不改描述。
90
+
91
+ ### 2. 记录格式(字段白名单,写死)
92
+
93
+ ```json
94
+ {"ts":"2026-11-05T21:37:12","source":"model","tool":"wiki_recall",
95
+ "mode":"search","query":"别了 旧索引","hits":0,"ms":1,"ok":true}
96
+ ```
97
+
98
+ **只有这 8 个字段。** 明确不写:页面路径、文件名、正文片段、答案、错误堆栈。
99
+
100
+ `record()` 做两件事:推入内存环形缓冲(上限 500 条),并 append 一行到文件。
101
+ 写文件失败只 `console.warn`,绝不影响工具返回——观察是旁路。
102
+
103
+ ### 3. 存储与轮转
104
+
105
+ - 路径:`pluginRoot/calls.jsonl`,可通过配置 `calls.log` 覆盖。
106
+ - 轮转:append 前若文件行数超 5000,读回最后 2500 行重写。检查用计数缓存,
107
+ 不每次 `readFile`。
108
+ - 文件不存在时自动创建;目录不存在时跳过写文件但仍保留内存缓冲。
109
+
110
+ ### 4. 读取接口
111
+
112
+ `GET /api/wiki-notes/calls?limit=200&source=all|model|panel&only=miss`
113
+
114
+ - 只读 GET,和 `/state` 同级,**不过跨源写闸**。
115
+ - 从文件**尾部**读,不做全量解析:读最后 256KB,按行 `JSON.parse`,坏行跳过。
116
+ - `limit` 上限 500;`only=miss` 过滤 `hits === 0`。
117
+ - 返回 `{ rows: [...], totals: {today, hitRate, misses} }`,`totals` 按当天统计。
118
+
119
+ ### 5. 页面
120
+
121
+ 新增第二个 `settings.section`:
122
+
123
+ ```js
124
+ ctx.slots.register({
125
+ name: 'settings.section',
126
+ id: 'wiki-notes-calls',
127
+ order: 48,
128
+ label: () => '知识库 · 调用',
129
+ }, WikiCallsSection)
130
+ ```
131
+
132
+ 组件 `WikiCallsSection`:
133
+ - 顶部三格数字:今日调用 / 命中率 / 零命中(分子固定为「返回 ≥1 页证据」的调用,
134
+ `verify` 与 `observe` 不计入分母,页面上注一句)。
135
+ - 筛选行:三个来源按钮 + 「只看零命中」开关 + 「清空」按钮(`POST /calls/clear`,过写闸)。
136
+ - 流水表:时间(只到分)· 来源徽章 · 工具 · 问题(单行截断,`title` 给全文)·
137
+ 命中 · 耗时(>1000ms 标黄)。
138
+ - 轮询:页面可见时每 2 秒拉一次(`document.visibilityState`),不可见就停。
139
+ - 空态:写明「还没有调用记录。让模型查一次库,或在这儿手查一次」。
140
+
141
+ 样式复用现有 `wn-` 前缀变量,不新增主题变量。
142
+
143
+ ### 6. 开关
144
+
145
+ 配置项 `calls.enabled`,默认 `true`。关掉后 `record()` 直接返回,内存与文件都不动。
146
+ 设置页那一块给一个勾选框 + 一句「关掉后不再记录任何调用」。
147
+
148
+ ## 测试
149
+
150
+ - 新增 `tests/calls.mjs`:
151
+ - 调用一次 recall,`calls.jsonl` 多一行,字段恰好是那 8 个(断言不含 `file`/`path`/`text`)。
152
+ - 超长 query 被截到 120 字。
153
+ - 第 5001 次写入触发轮转,行数落到 2500。
154
+ - `calls.enabled=false` 时不写任何行。
155
+ - 写文件失败(目录只读)时工具仍正常返回。
156
+ - `tests/api.mjs` 补:`GET /calls` 默认返回、`limit` 截断、`only=miss` 过滤、
157
+ `POST /calls/clear` 清空且过跨源闸。
158
+ - `tests/client.mjs` 补:新 section 注册代码在、组件是函数。
159
+
160
+ ## 已定结论(2026-11-05)
161
+
162
+ 1. 页面标题:「知识库 · 调用」。
163
+ 2. 命中率分母**排除 `verify` / `observe`**,只算 recall 与 context;页面上注一句说明。
164
+ 3. 「清空」要一行内二次确认(不弹系统对话框)。