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
@@ -21,7 +21,7 @@
21
21
  "primary": "partial_slot_coverage", // 主原因码(解释 support_status 本身)
22
22
  "primary_label": "部分槽位有证据、部分缺失",
23
23
  "reasons": [ // 全部原因,按严重度排序,不因 primary 而丢弃
24
- {"code": "partial_slot_coverage", "label": "…", "detail": "缺失 1 个槽位:题量", "slots": ["numeric"]},
24
+ {"code": "partial_slot_coverage", "label": "…", "detail": "缺失 1 个槽位:分片数", "slots": ["numeric"]},
25
25
  {"code": "engine_degraded", "label": "…", "detail": "wiki_recall error(…);search.py 仍返回了结果",
26
26
  "engines": ["wiki_recall"]}
27
27
  ]
@@ -73,7 +73,7 @@ conflicting_evidence 0 → no_candidates 1 → no_usable_evidence 2 → recorded
73
73
  - 接入点 `context_builder.py`:`ctx_out` 组装完、`answer_policy` 之前调用;**解释失败不拖垮检索**,
74
74
  异常时落 `{"primary":"unknown","reasons":[{"code":"unknown","detail":str(exc)}]}`。
75
75
  - 契约:`$defs.support_reason` / `$defs.support_reason_item`(code 用 enum 锁死),
76
- `context.properties.support_reason` 为**可选**——老调用方不传不报错。样例 `samples/context.cq-shenlun.json` 已带实现值。
76
+ `context.properties.support_reason` 为**可选**——老调用方不传不报错。样例 `samples/context.sample-cache.json` 已带实现值。
77
77
 
78
78
  ## 6. 验收(`_tools/eval/eval_support_reason.py`,34/34)
79
79
 
@@ -95,4 +95,4 @@ conflicting_evidence 0 → no_candidates 1 → no_usable_evidence 2 → recorded
95
95
 
96
96
  ## 8. 本轮没碰
97
97
 
98
- F5 子查询漂移、考试类型别名扩展、`page_changed` 是否降级、自动知识维护、SHA-256 措辞(「完整性校验失败」而非「人为修改」,仍待改)。
98
+ F5 子查询漂移、口径别名扩展、`page_changed` 是否降级、自动知识维护、SHA-256 措辞(「完整性校验失败」而非「人为修改」,仍待改)。
@@ -111,7 +111,7 @@ 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(重庆申论页入库后重录 1 条基线,非回归) |
114
+ | `e2e_check --check` | 8 题漂移 0(星港缓存策略页入库后重录 1 条基线,非回归) |
115
115
  | `protect.py` | 35 条漂移 0 |
116
116
 
117
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 的「取第一个工具」假设过期了)。
@@ -1,7 +1,7 @@
1
1
  # 阶段 5:读取一致性、观察闭环与实战验收
2
2
 
3
- > 本轮只做三件事:量一次「两套读取到底差在哪」、把观察闭环接上、拿五类真实问题压一遍。
4
- > 判据与检索打分一行没动(除抽取补齐的两处:字数对象词、表格行借用页面标题)。
3
+ > 本轮只做三件事:量一次「两套读取到底差在哪」、把观察闭环接上、拿五类问题压一遍(当年的实跑用例;仓库里的题目现已换成虚构语料)。
4
+ > 判据与检索打分一行没动(除抽取补齐的两处:TTL 对象词、表格行借用页面标题)。
5
5
 
6
6
  ## 一、页面读取一致性(`eval_read_parity.py`)
7
7
 
@@ -26,7 +26,7 @@
26
26
  ### 三条真实差异
27
27
 
28
28
  1. **frontmatter 列表未解析**:Python 只做 `k, v = line.split(":", 1)`,把
29
- `别名: [重庆省考申论, 重庆市考申论]` 读成字符串 `"[重庆省考申论, 重庆市考申论]"`;
29
+ `别名: [星港区域口径缓存策略, 星港区域口径缓存策略]` 读成字符串 `"[星港区域口径缓存策略, 星港区域口径缓存策略]"`;
30
30
  JS 的 `asList()` 正常解析成数组。今天这不影响证据(证据只从正文抽),
31
31
  但别名匹配、标签过滤这类能力在 Python 侧等于没有。
32
32
  2. **sections 语义不同**:JS 只按 `## `(level 2)切;Python 认 2–4 级,
@@ -95,16 +95,16 @@ Python 也不从快照回查(只认请求里带过去的那一个)。结果
95
95
 
96
96
  | # | 类型 | 问题 | support | verify 命中 | 结论 |
97
97
  |---|---|---|---|---|---|
98
- | A | 直接事实 | 重庆申论考几道题 | partial(条件性证据) | `review_flag_missing` | ✅ 放行,只要求标复核 |
99
- | B | 证据不足 | 重庆事业单位综合知识考几道题 | **insufficient** | `answered_unfilled_slot`、`gap_not_disclosed` | ✅ 承认缺口,编的数字被拦 |
100
- | C | 范围混淆 | 重庆申论考几道题(答国考口径) | partial | 3 × `unsupported_numeric_claim`(均 contradicted) | ✅ 三个数字全被抓 |
101
- | D | 多证据冲突 | 重庆申论作文多少字(答 800 字) | partial | `unsupported_numeric_claim`(contradicted) | ✅ 与库内 1000–1200 字冲突被指出 |
102
- | E | 错误答案 | 重庆申论考五道题 | partial | `unsupported_numeric_claim`(contradicted) | ✅ 数字错、单位对、范围对,仍被抓 |
98
+ | A | 直接事实 | 星港缓存策略分几个片 | partial(条件性证据) | `review_flag_missing` | ✅ 放行,只要求标复核 |
99
+ | B | 证据不足 | 星港事业单位综合知识分几个片 | **insufficient** | `answered_unfilled_slot`、`gap_not_disclosed` | ✅ 承认缺口,编的数字被拦 |
100
+ | C | 范围混淆 | 星港缓存策略分几个片(答统一口径) | partial | 3 × `unsupported_numeric_claim`(均 contradicted) | ✅ 三个数字全被抓 |
101
+ | D | 多证据冲突 | 星港缓存策略冷数据 TTL 多少秒(答 800 秒) | partial | `unsupported_numeric_claim`(contradicted) | ✅ 与库内 1000–1200 秒冲突被指出 |
102
+ | E | 错误答案 | 星港缓存策略分五个分片 | partial | `unsupported_numeric_claim`(contradicted) | ✅ 数字错、单位对、范围对,仍被抓 |
103
103
 
104
104
  **5/5 符合预期。** 首轮暴露的两个真问题(A 误拦、D 漏报)已修,修法记在这份文档末尾(判据放宽、主张范围继承、区间比较、表格证据补齐),细节见各阶段的验收记录。
105
105
 
106
106
  1. `unverifiable` 不再升 violation,只进 `notices`——「说不清」不等于「说错了」。
107
- 2. 主张范围继承整段回答——中文答句句首声明「重庆……」,后面分句省略主语。
107
+ 2. 主张范围继承整段回答——中文答句句首声明「星港……」,后面分句省略主语。
108
108
  3. 支持区间写法(`1000–1200 字`),单值对区间比相交。
109
109
  4. 证据抽取补两处:`字数` 对象词 + 表格行允许借用页面标题满足地域约束(行内已有别的地域则不借)。
110
110
 
@@ -121,7 +121,7 @@ Python 也不从快照回查(只认请求里带过去的那一个)。结果
121
121
  1. **读取仍是两套实现**——差在结构解读层,见第一节;统一方向待拍板。
122
122
  2. **`unverifiable` 只在 `notices` 里**:模型若只看 `violations`,会漏掉「这个数字我核实不了」。需要模型侧读 notices。
123
123
  3. **区间只支持「A–B 单位」**:`一千到一千二百字` 这类中文区间仍抽不出。
124
- 4. **`numeric_claim` 不做跨句推理**:主张散落在两句里(「作文 40 分。」「字数 1000–1200。」)时,靠整段口径继承兜底,不做句间绑定。
124
+ 4. **`numeric_claim` 不做跨句推理**:主张散落在两句里(「冷数据 40%。」「TTL 1000–1200 秒。」)时,靠整段口径继承兜底,不做句间绑定。
125
125
  5. **观察日志无轮转**:只追加,不清理;`legacy` 计数会随时间变大,需要时手工归档。
126
126
  6. **快照不自动清理**,也没有滑动续期。
127
127
  7. **插件侧的 `observe_id` 对照表只在内存里**:插件重启后,之前的 `context_id` 查不到对应的 `observe_id`,
package/lib/bridge.js CHANGED
@@ -33,6 +33,16 @@ export function errorEnvelope(code, message, stage = 'bridge', detail = null, re
33
33
  }
34
34
  }
35
35
 
36
+ /**
37
+ * 冻结契约里 observe 命令的「成功统计返回」只有一种形状:kind === 'observe_stats'。
38
+ * 'observe' 是 observe_log.jsonl 里单条日志事件的 kind,不是命令返回;
39
+ * 'error' 是通路坏了的错误信封,绝不能往上挂治理指标。
40
+ * 判定放在 bridge 层(这里只管调用形状),让插件接线和 CI 复用同一份语义。
41
+ */
42
+ export function isObserveResult(value) {
43
+ return value !== null && typeof value === 'object' && value.kind === 'observe_stats'
44
+ }
45
+
36
46
  function tail(text, n = 600) {
37
47
  const s = String(text ?? '')
38
48
  return s.length <= n ? s : `…${s.slice(-n)}`
package/lib/calls.js ADDED
@@ -0,0 +1,167 @@
1
+ /**
2
+ * calls.js —— 调用审计的账本。
3
+ *
4
+ * 为什么单独一个文件:这是插件里唯一会「每调用一次就写一行」的东西。
5
+ * 放进 index.js 会把宿主那半撑得更长,而它需要守的纪律(字段白名单、
6
+ * 坏行跳过、写失败不抛)跟检索逻辑一点关系都没有。
7
+ *
8
+ * 三条铁律:
9
+ * 1. 只记白名单里的 8 个字段 —— 页面路径、正文、答案一律不进账本。
10
+ * 2. 记账是旁路 —— 写文件失败只 warn,绝不改变工具返回值。
11
+ * 3. 读的时候只认尾部 —— 账本会长到几千行,没人需要为了看一眼今天的调用
12
+ * 把整个文件解析一遍。
13
+ */
14
+ import { createJsonlStore } from './jsonl-store.js'
15
+
16
+ export { MAX_LINES, KEEP_LINES, TAIL_BYTES, lineCountOf } from './jsonl-store.js'
17
+ import { MAX_LINES, KEEP_LINES } from './jsonl-store.js'
18
+
19
+ /** 账本只认这 8 个字段。顺序就是表头顺序。 */
20
+ export const CALL_FIELDS = ['ts', 'source', 'tool', 'mode', 'query', 'hits', 'ms', 'ok']
21
+
22
+ /** query 截断长度。一条记录撑到几十 KB 只会有害。 */
23
+ export const QUERY_MAX = 120
24
+ /** 内存里留最近多少条 —— 文件读不出来时的兜底。 */
25
+ export const BUFFER_MAX = 500
26
+ const DEFAULT_LIMIT = 200
27
+ const LIMIT_MAX = 500
28
+ /** totals 最多扫这么多行 —— 再老的不值得为「今日」统计去解析。 */
29
+ const TOTALS_MAX = 2000
30
+
31
+ function pad(value) {
32
+ return String(value).padStart(2, '0')
33
+ }
34
+
35
+ /** 本地时间戳,和「今日」用的是同一套时区。 */
36
+ function stampNow(date = new Date()) {
37
+ return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
38
+ + `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
39
+ }
40
+
41
+ function localDayOf(ts) {
42
+ return typeof ts === 'string' ? ts.slice(0, 10) : ''
43
+ }
44
+
45
+ function clipQuery(value) {
46
+ if (typeof value !== 'string') return ''
47
+ return value.length > QUERY_MAX ? value.slice(0, QUERY_MAX) + '…' : value
48
+ }
49
+
50
+ /**
51
+ * 只留白名单字段。输入不是对象就返回 null —— 调用方据此决定「这条不记」,
52
+ * 而不是记一条全是 undefined 的空壳。
53
+ */
54
+ export function normalizeEntry(raw) {
55
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
56
+ // null 与 0 是两件事:`Number(null)` 是 0,直接转会把「不产生命中的工具」
57
+ // 混进命中率的分母里,命中率被系统性地压低。
58
+ const hits = raw.hits === null || raw.hits === undefined ? Number.NaN : Number(raw.hits)
59
+ const ms = raw.ms === null || raw.ms === undefined ? Number.NaN : Number(raw.ms)
60
+ return {
61
+ ts: typeof raw.ts === 'string' && raw.ts !== '' ? raw.ts : stampNow(),
62
+ source: raw.source === 'panel' ? 'panel' : 'model',
63
+ tool: typeof raw.tool === 'string' ? raw.tool : '',
64
+ mode: typeof raw.mode === 'string' ? raw.mode : '',
65
+ query: clipQuery(raw.query),
66
+ hits: Number.isFinite(hits) ? Math.max(0, Math.trunc(hits)) : null,
67
+ ms: Number.isFinite(ms) ? Math.max(0, Math.trunc(ms)) : null,
68
+ ok: raw.ok !== false,
69
+ }
70
+ }
71
+
72
+ /**
73
+ * 建一个账本。同一个文件可以有多个实例(宿主一个、测试一个),
74
+ * 它们各记各的内存缓冲,文件是共享的。
75
+ */
76
+ export function createCallLog({ file, enabled = true, maxLines = MAX_LINES, keepLines = KEEP_LINES } = {}) {
77
+ const buffer = []
78
+ const store = createJsonlStore({ file, maxLines, keepLines })
79
+ let on = enabled !== false
80
+ let warned = false
81
+
82
+ function warnOnce(error) {
83
+ if (warned) return
84
+ warned = true
85
+ console.warn('[wiki-notes] 调用记录写不进文件,只保留在内存里:', error?.message ?? error)
86
+ }
87
+
88
+ function append(entry) {
89
+ if (file === undefined || file === null || file === '') return
90
+ try {
91
+ store.append(entry)
92
+ warned = false
93
+ } catch (error) {
94
+ // 目录被删、只读、被别的进程占住 —— 都只影响账本,不影响检索。
95
+ // 下次还会再试:用户可能只是临时删掉了文件。
96
+ warnOnce(error)
97
+ store.invalidate()
98
+ }
99
+ }
100
+
101
+ function record(raw) {
102
+ // 关闭观察就是明确放弃这段历史:先阻断新事件进入,连内存缓冲也不收。
103
+ // 否则关闭后旧周期仍会有一行「没落盘但留在内存里」的残留,重新打开时又浮出来。
104
+ if (!on) return null
105
+ const entry = normalizeEntry(raw)
106
+ if (entry === null) return null
107
+ buffer.push(entry)
108
+ while (buffer.length > BUFFER_MAX) buffer.shift()
109
+ append(entry)
110
+ return entry
111
+ }
112
+
113
+ function read({ limit = DEFAULT_LIMIT, source = 'all', only = 'all' } = {}) {
114
+ const fileRows = store.readRows()
115
+ // 文件里可能只有历史的一部分(刚被删过、或写失败过),把内存里文件没覆盖的补回来。
116
+ // 键带上 hits / ms:同一秒里两次相同的查询是不同的两件事,不该被去重吃掉。
117
+ const seen = new Set(fileRows.map((row) => `${row.ts}|${row.tool}|${row.query}|${row.hits}|${row.ms}`))
118
+ const merged = fileRows.slice()
119
+ for (const row of buffer) {
120
+ const key = `${row.ts}|${row.tool}|${row.query}|${row.hits}|${row.ms}`
121
+ if (seen.has(key)) continue
122
+ seen.add(key)
123
+ merged.push(row)
124
+ }
125
+ merged.sort((a, b) => String(a.ts ?? '').localeCompare(String(b.ts ?? '')))
126
+
127
+ const scanned = merged.slice(-TOTALS_MAX)
128
+ const today = localDayOf(stampNow())
129
+ const todayRows = scanned.filter((row) => localDayOf(row.ts) === today)
130
+ const denom = todayRows.filter((row) => typeof row.hits === 'number')
131
+ const scored = denom.filter((row) => row.hits > 0)
132
+ const totals = {
133
+ today,
134
+ calls: todayRows.length,
135
+ hits: scored.length,
136
+ misses: denom.filter((row) => row.hits === 0).length,
137
+ hitRate: denom.length === 0 ? null : scored.length / denom.length,
138
+ }
139
+
140
+ const filtered = merged.filter((row) => {
141
+ if (source !== 'all' && row.source !== source) return false
142
+ if (only === 'miss' && row.hits !== 0) return false
143
+ return true
144
+ })
145
+ const size = Math.max(1, Math.min(Math.trunc(Number(limit) || DEFAULT_LIMIT), LIMIT_MAX))
146
+ const rows = filtered.slice(-size).reverse() // 新的在前:表头下面第一行就该是刚才那次
147
+ return { rows, totals, enabled: on, window: merged.length }
148
+ }
149
+
150
+ function clear() {
151
+ buffer.length = 0
152
+ if (file === undefined || file === null || file === '') return
153
+ try {
154
+ store.clear()
155
+ warned = false
156
+ } catch (error) {
157
+ warnOnce(error)
158
+ store.invalidate()
159
+ }
160
+ }
161
+
162
+ function setEnabled(next) {
163
+ on = next !== false
164
+ }
165
+
166
+ return { record, read, clear, setEnabled, enabled: () => on, buffer: () => buffer.slice() }
167
+ }