dsh-wiki-notes 1.3.0 → 1.4.1

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 (23) hide show
  1. package/README.md +104 -24
  2. package/docs/README.md +70 -0
  3. package/docs//345/245/221/347/272/246-stage0/knowledge-gateway.v1.schema.json +1180 -0
  4. package/docs//345/245/221/347/272/246-stage0/samples/_verify_probe.json +46 -0
  5. package/docs//345/245/221/347/272/246-stage0/samples/context.cq-shenlun.json +612 -0
  6. package/docs//345/245/221/347/272/246-stage0/samples/verify.context-corrupt.json +20 -0
  7. package/docs//345/245/221/347/272/246-stage0/samples/verify.context-expired.json +20 -0
  8. package/docs//345/245/221/347/272/246-stage0/samples/verify.fabricated-quote.json +31 -0
  9. package/docs//345/245/221/347/272/246-stage0/samples/verify.right-with-limit.json +14 -0
  10. package/docs//345/245/221/347/272/246-stage0/samples/verify.scope-mismatch.json +27 -0
  11. package/docs//345/245/221/347/272/246-stage0/samples/verify.wrong-five.json +43 -0
  12. 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 +81 -0
  13. 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 +204 -0
  14. 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 +107 -0
  15. 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 +84 -0
  16. 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 +98 -0
  17. 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 +143 -0
  18. 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 +109 -0
  19. package/lib/bridge.js +210 -0
  20. package/lib/client.js +1 -1
  21. package/lib/config.js +59 -0
  22. package/lib/index.js +268 -4
  23. package/package.json +2 -2
@@ -0,0 +1,31 @@
1
+ {
2
+ "kind": "verify",
3
+ "contract_version": "1.0",
4
+ "context_id": "ctx_SAMPLE0001",
5
+ "status": "violations_found",
6
+ "violations": [
7
+ {
8
+ "type": "review_flag_missing",
9
+ "rule": "weak_evidence.review_flag_missing"
10
+ },
11
+ {
12
+ "type": "fabricated_quote",
13
+ "rule": "provenance.fabricated_quote"
14
+ },
15
+ {
16
+ "type": "unsupported_numeric_claim",
17
+ "rule": "numeric.claim_not_supported",
18
+ "status": "contradicted",
19
+ "claim": "五道题",
20
+ "reason": "同指标同范围(重庆·省考)证据是 4 题,答复写的是 五道题",
21
+ "page": "综合-syntheses/申论.md"
22
+ }
23
+ ],
24
+ "checked_rules": 10,
25
+ "notices": [],
26
+ "snapshot_created": "2026-11-05T06:18:00+08:00",
27
+ "timing_ms": {
28
+ "total": null
29
+ },
30
+ "_note": "伪造引文 + 中文数字错,两条一起报"
31
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "kind": "verify",
3
+ "contract_version": "1.0",
4
+ "context_id": "ctx_SAMPLE0001",
5
+ "status": "ok",
6
+ "violations": [],
7
+ "checked_rules": 10,
8
+ "notices": [],
9
+ "snapshot_created": "2026-11-05T06:18:00+08:00",
10
+ "timing_ms": {
11
+ "total": null
12
+ },
13
+ "_note": "正确答复:数值·指标·范围一致 → supported,不误报"
14
+ }
@@ -0,0 +1,27 @@
1
+ {
2
+ "kind": "verify",
3
+ "contract_version": "1.0",
4
+ "context_id": "ctx_SAMPLE0001",
5
+ "status": "violations_found",
6
+ "violations": [
7
+ {
8
+ "type": "review_flag_missing",
9
+ "rule": "weak_evidence.review_flag_missing"
10
+ },
11
+ {
12
+ "type": "unsupported_numeric_claim",
13
+ "rule": "numeric.claim_unverifiable",
14
+ "status": "unverifiable",
15
+ "claim": "6 道题",
16
+ "reason": "答复限定了6 道题 的年份口径,证据只写「重庆·省考」,不能据此判定对错,需复核(答复未标复核)",
17
+ "page": "综合-syntheses/申论.md"
18
+ }
19
+ ],
20
+ "checked_rules": 10,
21
+ "notices": [],
22
+ "snapshot_created": "2026-11-05T06:18:00+08:00",
23
+ "timing_ms": {
24
+ "total": null
25
+ },
26
+ "_note": "年份口径缺口:既不能 supported 也不能 contradicted,判 unverifiable 并要求复核"
27
+ }
@@ -0,0 +1,43 @@
1
+ {
2
+ "kind": "verify",
3
+ "contract_version": "1.0",
4
+ "context_id": "ctx_SAMPLE0001",
5
+ "status": "violations_found",
6
+ "violations": [
7
+ {
8
+ "type": "review_flag_missing",
9
+ "rule": "weak_evidence.review_flag_missing"
10
+ },
11
+ {
12
+ "type": "unsupported_numeric_claim",
13
+ "rule": "numeric.claim_not_supported",
14
+ "status": "contradicted",
15
+ "claim": "五道题",
16
+ "reason": "同指标同范围(重庆·省考)证据是 4 题,答复写的是 五道题",
17
+ "page": "综合-syntheses/申论.md"
18
+ },
19
+ {
20
+ "type": "unsupported_numeric_claim",
21
+ "rule": "numeric.claim_not_supported",
22
+ "status": "contradicted",
23
+ "claim": "180 分钟",
24
+ "reason": "同指标同范围(重庆·省考)证据是 150 分钟,答复写的是 180 分钟",
25
+ "page": "综合-syntheses/申论.md"
26
+ },
27
+ {
28
+ "type": "unsupported_numeric_claim",
29
+ "rule": "numeric.claim_unverifiable",
30
+ "status": "unverifiable",
31
+ "claim": "30 分",
32
+ "reason": "证据与主张的适用范围有一侧未标注,不能视为匹配(证据:全国·国考)(答复未标复核)",
33
+ "page": "综合-syntheses/申论.md"
34
+ }
35
+ ],
36
+ "checked_rules": 10,
37
+ "notices": [],
38
+ "snapshot_created": "2026-11-05T06:18:00+08:00",
39
+ "timing_ms": {
40
+ "total": null
41
+ },
42
+ "_note": "数字错但槽位已填满:旧判据只报 review_flag_missing,新增判据以 contradicted 拦住那两条数字"
43
+ }
@@ -0,0 +1,81 @@
1
+ # 真实使用观察期:五个观察点怎么测
2
+
3
+ > 目标不是再验证工具对不对,而是看**模型会不会用、用了会不会改**。
4
+ > 工具能发现错误,不等于模型一定会改正错误——这是从工具可靠性走向 Agent 工作流可靠性的那一步。
5
+
6
+ ## 0. 数据从哪来
7
+
8
+ 三类数据,可靠性依次下降:
9
+
10
+ | 数据 | 来源 | 可信度 | 能回答 |
11
+ |---|---|---|---|
12
+ | 服务端事实 | `wiki_bridge.py` 写入的 observe 日志 | 高(自动、无自报) | 调了什么、返回什么、核验结果 |
13
+ | 会话事实 | DSH 会话记录(tool call 序列 + 模型输出) | 中(需离线对账) | 有没有调、调的顺序、模型嘴上改没改 |
14
+ | 模型自述 | 模型自己说「我查了库」 | 低 | 只能作线索 |
15
+
16
+ 观察期默认**只信前两类**。日志路径由插件 `bridge.observeLog` 决定,当前是
17
+ `<你的库根目录>\生活库\_tools\observe\gateway.jsonl`,与自测日志
18
+ `<你的库根目录>\生活库\_tools\eval\observe_log.jsonl` 物理隔离——修 bug 时跑测试不会污染观察数据。
19
+
20
+ ## 1. 模型是否先调 wiki_context
21
+
22
+ - **能测度**:测不到。网关没有「本轮没被调用」这个事件。
23
+ - **取数**:会话记录里逐轮看,首个 tool call 是不是 `wiki_context`;答案里出现库内事实而该轮无调用,记为「疑似绕过」。
24
+ - **判据**:出现库内可答的事实题却零调用 → 记为一次绕过。
25
+ - **已知偏差**:工具描述与系统提示会显著影响调用率;这测的其实是「提示工程 + 工具描述的合力」,不是模型单方面意愿。
26
+
27
+ ## 2. 是否遵守 contract_text 的四条约束
28
+
29
+ - **能测度**:间接可测。约束要落在答案上,核验能抓一部分(必须披露缺口、不得超出证据、引文须原文)。
30
+ - **取数**:`verify` 事件的 `violation_types`;`missing.not_disclosed`、`provenance.fabricated_quote`、`weak_evidence.*` 都属这一类。
31
+ - **判据**:违规率按类型看,不看总数(不同类型发现难度差很多)。
32
+
33
+ ## 3. 是否在适当时机调 wiki_verify
34
+
35
+ - **能测度**:可测,比值。
36
+ - **取数**:`stats()` 的 `totals.contexts` 与 `totals.verifies`。
37
+ - **判据**:
38
+ - `verifies / contexts ≥ 0.6`:基本在用;
39
+ - `0.2 ≤ 比值 < 0.6`:只在「感觉不稳」时才核;
40
+ - `< 0.2`:基本不用,核验层形同虚设。
41
+ - **注意**:一个 context 被核验多次是好事(= 在改),别把高比值当异常。
42
+
43
+ ## 4. 发现违规后模型是否修正(重点)
44
+
45
+ - **能测度**:一半。能测「重新核验后是否通过」,测不到「嘴上改了但没重验」。
46
+ - **取数**:`stats().revision`:
47
+ - `contexts_verified`:被核验过的 context 数;
48
+ - `corrected`:同 context 首次 fail、末次 pass —— **真改了**;
49
+ - `unresolved`:末次仍 fail —— **改了没改对,或者压根没改**;
50
+ - `correction_rate = corrected / contexts_verified`;
51
+ - `sequences[]`:每个 context 的核验序列(`attempts` / `first_ok` / `last_ok` / `types_seen`)。
52
+ - **判据**:
53
+ - `correction_rate ≥ 0.7`:核验结果被当真。
54
+ - `0.3–0.7`:部分当真,要看 `unresolved` 的 `types_seen` 是哪类(数字类通常最容易改,披露类最难)。
55
+ - `< 0.3`:**核验在空转**——模型看见了红字不认账。这时该改的不是判据,是提示词里的「核验结果优先」。
56
+ - **盲区(务必记住)**:只数「重验过的」。模型读了 violation 直接重写但懒得再核,会同时降低 `contexts_verified` 的可用性——表现为序列只有 1 次 attempt 且 `last_ok=false`。这种要回会话记录人工看,别直接用 `correction_rate` 下结论。
57
+
58
+ ## 5. wiki_observe 能否发现长期缺口
59
+
60
+ - **能测度**:可测,但要攒量。
61
+ - **取数**:`missing[].reason` 三档(`not_found` / `not_verifiable` / `not_covered_in_wiki`)+ `support_distribution` + `retrieval_distribution`。
62
+ - **判据**:同一主题反复 `not_found` = 真缺页;反复 `not_verifiable` = 页在但证据不合格(该补来源或补结构);`weak_only` 占比高 = 检索层单调。
63
+ - **节奏**:至少两周再聚类,一周的量看不出「长期」。
64
+
65
+ ## 6. 复盘方式
66
+
67
+ 每周一次,同一句:
68
+
69
+ ```bash
70
+ cd <你的库根目录>\工具-tools
71
+ printf '%s' '{"days":7,"limit":10}' | PYTHONIOENCODING=utf-8 python wiki_bridge.py observe
72
+ ```
73
+
74
+ 看四件事:`totals` 比值(第 3 点)、`revision`(第 4 点)、`violation_types` 分布(第 2 点)、`recent[].query` 里重复出现的主题(第 5 点)。第 1 点需要翻会话记录,建议每次抽 10 轮人工过一遍。
75
+
76
+ ## 7. 这套观察自身的局限
77
+
78
+ 1. 只覆盖「调了网关」的轮次,绕过检索的轮次天然不可见。
79
+ 2. `correction_rate` 的分母是「被核验过的 context」,不是「所有出过错的回答」。
80
+ 3. 日志无轮转,观察期结束要手动归档。
81
+ 4. 单机单人样本,结论只对本人有效,别外推成「模型普遍行为」。
@@ -0,0 +1,204 @@
1
+ # 阶段 0 · 契约与现状审计
2
+
3
+ > 日期:2026-11-05 | 插件:dsh-wiki-notes 1.3.0 | 管线:`<你的库根目录>\工具-tools`
4
+ > 位置:本文档只做映射与判定,**不改任何检索评分、不改 engine.js、不改 Answer Policy 判据**。
5
+
6
+ ## 0. 一句话结论
7
+
8
+ 目标契约的字段 **90% 能直接映射到现有 `context_builder.build()` 的返回**,不需要重写判据;
9
+ 真正缺的不是字段而是**三样运行期结构**(context 快照、engine 级状态、数值矛盾判据),
10
+ 以及一个必须马上修的**故障可见性缺陷**(引擎报错被吞成空候选)。
11
+
12
+ ## 1. 现状调用链(已核实)
13
+
14
+ ```
15
+ context_builder.build(query, engines, limit)
16
+ ├─ query_planner.plan(query) → plan_obj: original_query / query_units / anchors / has_constraint_anchor
17
+ ├─ run_search_py(unit_query) → subprocess → search.py,从 stderr 的 [diag] JSON 解析候选
18
+ ├─ run_plugin(unit_query) → subprocess → node bin/cli.mjs search(cwd=PLUGIN)
19
+ ├─ 页面去重(按 title)→ read_page() → extract()/extract_table_numeric()
20
+ ├─ dedup.dedup(all_supports) → evidence_items + dedup_stats
21
+ ├─ conflict_check.analyze(...) → conflicts / incomparable / compatible_pairs
22
+ ├─ 状态三段:retrieval_status / support_status / pipeline.stage
23
+ └─ answer_policy.policy() / check_context() / contract_text()
24
+ ```
25
+
26
+ 已有但未暴露的核验入口:`answer_policy.check_answer(ctx, answer, root)` —— 参数就是 **原 ctx**,
27
+ 天然满足「verify 不得重新检索」。
28
+
29
+ ## 2. 逐字段映射
30
+
31
+ 图例:✅ 直接可用 | 🔁 需重命名/聚合(纯包装) | 🆕 必须新增 | ⚠️ 语义要拆
32
+
33
+ | 契约字段 | 现状来源 | 状态 |
34
+ |---|---|---|
35
+ | `contract_version` | 无 | 🆕 常量 `"1.0"` |
36
+ | `request_id` | 无 | 🆕 Bridge 生成 |
37
+ | `context_id` | 无(`build()` 返回即失联) | 🆕 Bridge 快照表 |
38
+ | `query` | `ctx["query"]` | ✅ |
39
+ | `plan` | `ctx["query_plan"]`(qp.plan 原样) | ✅ |
40
+ | `engines.search.status/candidates` | `ctx["retrieval_runs"]` 里 `engine=="search.py"` 的聚合 | 🔁 现成数据,需按引擎归组 |
41
+ | `engines.wiki_recall.*` | 同上,`engine=="wiki_recall"` | 🔁 |
42
+ | `engines.*.error` | **不存在**(错误被 `continue` 吞掉) | ⚠️ 见 F1 |
43
+ | `status.retrieval` | `ctx["retrieval_status"]`(none/direct/related/weak_only/unknown) | ✅ 同名迁移 |
44
+ | `status.support` | `ctx["support_status"]`(sufficient/partial/insufficient) | ✅ 同名迁移 |
45
+ | `status.stage` | `ctx["pipeline"]["stage"]` + `["reason"]` | ✅ 打平,reason 放 detail |
46
+ | `status.degraded` | 无 | 🆕 由 engines 状态派生 |
47
+ | `evidence[]` | `ctx["evidence"]`(字段一一对应) | 🔁 仅改名 `relation→source_relation`(两字段现有并存) |
48
+ | `evidence[].supports[]` | 同名 | ✅ 原样 |
49
+ | `evidence_items[]` | `ctx["evidence_items"]`(dedup 产出,含 evidence_id/page_count/engine_count) | ✅ |
50
+ | `missing[]` | `ctx["missing"]`(slot/target/reason/status/must_preserve_disagreement) | ✅ |
51
+ | `unresolved[]` | `ctx["unresolved"]` | ✅ |
52
+ | `conflicts[]` + `conflict_status` | `ctx["conflicts"]` / `ctx["conflict_status"]` / `incomparable` / `compatible_pairs` | ✅ |
53
+ | `metrics` | `ctx["metrics"]` + `dedup` + `claims_checked` | ✅ |
54
+ | `answer.policy` | `ctx["answer_policy"]` | ✅ |
55
+ | `answer.constraints` | `ctx["answer_constraints"]` | ✅ |
56
+ | `answer.contract_text` | `ctx["contract_text"]` | ✅ |
57
+ | `timing_ms` | 无 | 🆕 Bridge 用 `perf_counter` 包一层 |
58
+ | `observe_id` | 无(`observe.record_of()` 存在但 build 内不调用) | 🆕 阶段 3 |
59
+ | `verify.status/violations` | `check_answer()` 返回 `{ok, violations[]}` | 🔁 ok→status,rule→type 映射表(下方) |
60
+ | `violation.type=unsupported_numeric_claim` | **判据不存在** | 🆕 见 F2 |
61
+
62
+ ### verify 规则 → 契约类型映射(现成 9 条)
63
+
64
+ | 管线 rule | 契约 type |
65
+ |---|---|
66
+ | `conditional.limit_not_with_claim` | `conditional_limit_missing` |
67
+ | `insufficient.answered_unfilled_slot` | `answered_unfilled_slot` |
68
+ | `missing.not_disclosed_in_answer` | `gap_not_disclosed` |
69
+ | `recorded_unresolved.disclosure_missing` | `unresolved_disclosure_missing` |
70
+ | `recorded_unresolved.arbitrated` | `unresolved_arbitrated` |
71
+ | `weak_evidence.review_flag_missing` | `review_flag_missing` |
72
+ | `provenance.duplicate_as_independent` | `duplicate_as_independent` |
73
+ | `provenance.fabricated_quote` | `fabricated_quote` |
74
+ | `insufficient.conclusion_without_evidence` | `conclusion_without_evidence` |
75
+
76
+ 另有 6 条 `check_context()` 的自检规则(`provenance.quote_not_verbatim`、`conditional.note_missing`、
77
+ `table_evidence.*`、`missing.not_disclosed`、`recorded_unresolved.flag_missing`),属**上下文自身**健康度,
78
+ 不进 verify 的 violations,建议作为 `context.answer.self_check` 暴露。
79
+
80
+ ## 3. 实测发现(用真实题包跑出来的,不是推理)
81
+
82
+ 题包:`重庆 申论 考几道题`,`--engine both --limit 8`。
83
+
84
+ ```
85
+ 候选页 9|候选行 24|可读 9|证据 5 条|必要槽位 1(numeric)已填 1
86
+ retrieval_status=weak_only support_status=partial stage=ok
87
+ conflict_status=none_detected contract_violations=[](上下文自检通过)
88
+ ```
89
+
90
+ ### F1 引擎故障在输出里不可见(**必须在阶段 1 修**)
91
+
92
+ `run_search_py()` / `run_plugin()` 出错时都 `return [{"engine": ..., "error": str(exc)}]`(context_builder.py:64、109),
93
+ 而 build() 第 693 行 `if "error" in c: continue` 直接丢弃。后果:
94
+
95
+ - 插件崩了/超时,输出与「插件没召回到任何页面」**字节级相同**;
96
+ - 事后无法从 ctx 重建 engine 状态,只能回看 stderr;
97
+ - 直接违背「引擎故障不得伪装成证据不足」。
98
+
99
+ 修法(阶段 1,不碰判据):在 `runs` 里额外记 `{"engine":..., "status": "error"|"timeout"|"empty"|"ok", "error": {...}}`,
100
+ `engines.*.status` 由此派生,`status.degraded=true` 时 support 不可单独采信。
101
+
102
+ ### F2 「答错数字」现在抓不到(**verify 的真实缺口**)
103
+
104
+ 拿同一份 ctx 快照跑三种答案(产物见 `samples/_verify_probe.json`):
105
+
106
+ | 答案 | 结果 | 说明 |
107
+ |---|---|---|
108
+ | 「重庆申论一共考五道题,180 分钟,作文 30 分。」 | `violations_found`,仅 `weak_evidence.review_flag_missing` | **只抓到没标"需复核",没抓到"五道题"与证据 4 题矛盾** |
109
+ | 「…4 题、150 分钟…属台账记录…需复核。」 | `ok` | 正确 |
110
+ | 含伪造引文的那句 | 抓到 `provenance.fabricated_quote` | 引文核验可用 |
111
+
112
+ 原因:`numeric` 槽被填了(`filled` 里有),`missing` 为空,于是
113
+ `insufficient.answered_unfilled_slot` 不触发;管线**没有**「答案里的数值 vs 证据里的数值」比对。
114
+
115
+ 结论:契约里 `unsupported_numeric_claim` 是**新增判据**,不是已有能力的改名。它必须在阶段 1 单列为
116
+ 新规则(读 `ctx.evidence[].supports[].values` 与 quote 中的数值 + 槽位口径),并单测覆盖。
117
+ 这也是唯一一处会让「Python 是判定中心」这句话落空的地方——不新增,verify 就只是半个核验。
118
+
119
+ ### F3 support 与 stage 已独立,但 support 缺 reason
120
+
121
+ 实测同时出现 `support=partial` + `stage=ok`(槽位填满但证据只到 weak)。契约需要给 support 一个
122
+ `support_reason`(如 `evidence_weak` / `slot_partial` / `conditional_only`),否则插件侧只能原样转发,
123
+ LLM 看不出"为什么是 partial"。
124
+
125
+ ### F4 无 context 快照
126
+
127
+ `check_answer` 吃的是内存里的 ctx。跨进程(插件 ↔ Bridge)必须落盘快照 + TTL,否则 verify 只能重建,
128
+ 也就是用户明确禁止的「第二次检索判第一次答案」。建议快照只存 `ctx` 的 evidence/supports/answer 三块
129
+ (约 40–60KB),TTL 30 分钟,过期返回 `E_CONTEXT_EXPIRED` 而不是自动重建。
130
+
131
+ ### F5 子查询漂移(记录,不在本次修)
132
+
133
+ `query_planner` 把 `重庆 申论 考几道题` 拆成 `Q1 = "重庆 申论 考"`,尾部"几道题"丢失。
134
+ 不致命(Q0 原句仍在),但会让 numeric 槽的关键词单元变弱。属阶段 4 评测项。
135
+
136
+ ### F6 numeric 槽抽到「国考口径」行(记录)
137
+
138
+ 证据 E001/E005 抽的是 `申论.md` 与 `申论·资料摘要.md` 里「180 分钟 5 题」那两行——
139
+ 数字密集所以被 numeric 槽选中,与问题真正要的「重庆 4 题」是**两种口径**。
140
+ E002 抽对了(`4 题 / 150 分钟 / 100 分`)。说明抽取层还缺"口径限定词"过滤(国考/省考/重庆)。
141
+ 这条属阶段 4,但**正好说明 verify 的数值判据不能只看数字相等,还要看口径标签**。
142
+
143
+ ## 4. 错误码 / 超时 / 版本
144
+
145
+ ### 4.1 错误码(顶层 `error`,与 `status.support` 严格分离)
146
+
147
+ | code | 触发 | retryable |
148
+ |---|---|---|
149
+ | `E_QUERY_EMPTY` | query 空/全空白 | false |
150
+ | `E_CONTRACT_VERSION_MISMATCH` | 插件与 Bridge contract_version 不等 | false |
151
+ | `E_PYTHON_UNAVAILABLE` | python 可执行文件不存在 | false |
152
+ | `E_BRIDGE_SPAWN_FAILED` | 进程起不来 | true |
153
+ | `E_BRIDGE_TIMEOUT` | 超预算(见 4.2) | true |
154
+ | `E_BRIDGE_CRASH` | 非 0 退出且无 JSON | true |
155
+ | `E_BRIDGE_BAD_JSON` | stdout 不是契约 JSON | false |
156
+ | `E_CONTEXT_NOT_FOUND` / `E_CONTEXT_EXPIRED` | verify 拿到未知/过期 id | false |
157
+ | `E_VERIFY_EMPTY_ANSWER` | verify 传空答案 | false |
158
+ | `E_ENGINE_UNAVAILABLE` | 单引擎故障(**不阻断**,只标 degraded) | true |
159
+ | `E_WIKI_ROOT_MISSING` | 库根不存在 | false |
160
+ | `E_INTERNAL` | 兜底 | false |
161
+
162
+ 铁律:`error` 出现 ≠ `support=insufficient`。前者是环境故障,后者是知识结论。二者同时出现时,
163
+ 以 `error` 为准,`support` 标 `unknown`(不能报 insufficient)。
164
+
165
+ ### 4.2 超时预算
166
+
167
+ | 阶段 | 预算 | 超时行为 |
168
+ |---|---|---|
169
+ | plan | 1s | E_INTERNAL |
170
+ | retrieve(单引擎/单子查询) | 8s | 该引擎该单元标 timeout,其余继续 |
171
+ | retrieve 总计 | 20s | 返回已完成部分 + degraded=true |
172
+ | read+extract | 10s | 未读页记 `unreadable` |
173
+ | policy | 1s | 失败时 `answer.contract_text=""`(现有行为,保留) |
174
+ | **verify** | 2s | 纯内存读快照,超时即 E_BRIDGE_TIMEOUT |
175
+ | **observe** | 3s | 失败不影响 context 返回(现有 try/except 语义保留) |
176
+
177
+ ### 4.3 版本四件套
178
+
179
+ | 字段 | 值来源 | 变更影响 |
180
+ |---|---|---|
181
+ | `plugin_version` | package.json(现 1.3.0) | 工具 schema 变 |
182
+ | `bridge_version` | wiki_bridge.py `__version__`(新) | 命令/快照格式变 |
183
+ | `contract_version` | 常量 `"1.0"` | 三者同时协商 |
184
+ | `pipeline_version` | 管线 git 短哈希或日期(现无版本) | 抽取/判据变 |
185
+
186
+ 只改抽取逻辑时升 `pipeline_version`;只改工具参数时升 `plugin_version`;契约字段增删才升 `contract_version`。
187
+
188
+ ## 5. 阶段 1 最小改动清单(都不重写判据)
189
+
190
+ 1. `build()` 记录 engine 级 status(F1),输出 `engines` 段。
191
+ 2. 把 `check_answer` 包成 CLI 子命令 `verify --context-file`,`ok→status`、rule→type 映射。
192
+ 3. 新增判据 `unsupported_numeric_claim`(F2),单测先行。
193
+ 4. 给 `support_status` 补 `support_reason`(F3)。
194
+ 5. `wiki_bridge.py`:`context` / `verify` 两个命令,stdin/stdout JSON,stderr 只放诊断。
195
+ 6. 快照目录(默认 `%TEMP%\wiki-gateway\contexts\`),TTL 30 分钟。
196
+
197
+ ## 6. 验收(对齐阶段 0 要求)
198
+
199
+ - [x] 契约每个字段都能指到现有来源(本文件 §2)
200
+ - [x] 契约字段不需要重写判据即可产出(除 §F2 明确列为新增)
201
+ - [x] 真实题包样例:`samples/context.cq-shenlun.json`(来自实跑,非手写)
202
+ - [x] verify 样例三份(`samples/verify.*.json`)+ 探针原始结果 `samples/_verify_probe.json`
203
+ - [x] 错误码、超时、版本四件套定稿(§4)
204
+ - [ ] **待你拍板**:`unsupported_numeric_claim` 的判定边界(只比数字?还是数字+口径标签一起比)
@@ -0,0 +1,107 @@
1
+ # 阶段 1 交付:数值判据 `unsupported_numeric_claim` 与引擎状态显式化
2
+
3
+ > 拍板依据:用户 2026-11-05 决定「不能只比数字,必须比数值 + 适用范围 + 约束条件」,并同步要求 F1 修复。
4
+ > 本文只记录**已落地并跑过回归**的内容;未做的写进 §7。
5
+
6
+ ## 1 交付物
7
+
8
+ | 文件 | 类型 | 说明 |
9
+ | --- | --- | --- |
10
+ | `<你的库根目录>\工具-tools\numeric_claim.py` | 新增 | 数值主张抽取 + 五维范围判定,四态输出 |
11
+ | `<你的库根目录>\工具-tools\answer_policy.py` | 改 | `check_answer()` 第 8 步接入;判据崩溃记 `numeric.check_failed` |
12
+ | `<你的库根目录>\工具-tools\context_builder.py` | 改 | F1:`engine_states` / `engines` / `pipeline.degraded` |
13
+ | `_tools\eval\eval_numeric_claim.py` | 新增 | 11 条规格用例 + 2 条真 context 端到端 |
14
+ | `_tools\eval\eval_engine_state.py` | 新增 | 6 条引擎状态用例 |
15
+ | `docs\契约-stage0\knowledge-gateway.v1.schema.json` | 改 | violation 加 `status`/`claim`,type 枚举 +2;新增 `$defs.notice` 与 `verify.notices` |
16
+ | `docs\契约-stage0\samples\verify.*.json` | 重生成 | 四份样例已反映新判据 |
17
+
18
+ ## 2 判据设计(与拍板逐条对应)
19
+
20
+ ### 2.1 五维
21
+
22
+ `_scope_of(text)` 从文字里抽三组适用范围:`region`(地域)、`exam`(考试类型)、`period`(年份)。数值侧另两维由 `_METRIC_PATTERNS` 承担:数值/单位(`normalize()` 统一时长到分钟)与指标(`duration`/`count`/`score`/`words`)。
23
+
24
+ ### 2.2 `compare_scope` 的三条语义
25
+
26
+ 1. **只有两侧都标了某维度,该维度才提供判据**——一侧缺不自动算匹配。
27
+ 2. 都有值且相交 → 相容;都有值不相交 → `mismatch`。
28
+ 3. 所有维度都不提供判据 → `unknown`,绝不默认 `match`。
29
+
30
+ ### 2.3 补一条拍板没写、但实测必须有的规则:`scope_gaps`
31
+
32
+ 主张说「2023 年考 6 道题」,证据只写「重庆 4 题」,`compare_scope` 会给 `match`(年份一侧缺)。若照此比较就会得出 `contradicted`——把「证据没说」当成「证据反对」。
33
+
34
+ 所以加 `scope_gaps(claim_scope, ev_scope)`:主张限定了、证据没写的维度。命中时不进 `matched`,进 `partial`,最终判 `unverifiable`:
35
+
36
+ ```
37
+ 证据与主张的适用范围有一侧未标注,不能视为匹配(证据:重庆·省考)
38
+ ```
39
+
40
+ 这正是拍板里「未标注 ≠ 适用于所有情况」的直接落地。
41
+
42
+ ### 2.4 四态判定顺序(`judge_claim`)
43
+
44
+ ```
45
+ 无同指标证据 → unverifiable
46
+ 有 matched 且数值全等 → supported
47
+ 有 matched 且数值不等 → contradicted
48
+ 只有 partial(范围缺口) → unverifiable
49
+ 只有 mismatched → scope_mismatch
50
+ 只剩 unknown → unverifiable
51
+ ```
52
+
53
+ `scope_mismatch` 与 `contradicted` 分开输出,回答里永不出现「重庆一定不是 5 题」这种话。
54
+
55
+ ### 2.5 证据侧的范围归属(踩过的真 bug)
56
+
57
+ `build_evidence_pool()` 里,一条证据的范围**以数字所在那句话为准**;那句话自己没标范围时,才退回页面标题。
58
+
59
+ 原因:「重庆申论考情」页里有一句「国考申论 5 题、180 分钟」,若按标题取范围,这句就变成重庆口径,直接把国考证据洗成重庆证据——正是拍板要防的错配。
60
+
61
+ ### 2.6 违规与提示分开
62
+
63
+ - `contradicted` / `scope_mismatch` → `violations`,`type = unsupported_numeric_claim`,带 `status`
64
+ - `unverifiable` → `notices`;**仅当答复没有任何复核措辞**(`REVIEW_WORDS`)时才升为 violation。答复自己写了「需复核」,就不再重复报警
65
+ - 判据内部异常 → `numeric.check_failed` / `internal_error`,可见,不静默通过
66
+
67
+ ## 3 F1:引擎状态显式化
68
+
69
+ `run_search_py()` / `run_plugin()` 的异常分支带 `status ∈ timeout|error`;`build()` 记 `engine_states[{engine, query_id, status, candidates, error}]`,`status` 区分 `ok` / `empty`(通了但零命中)/ `error` / `timeout`。输出新增 `engines` 聚合与 `pipeline.degraded` / `degraded_sources`。
70
+
71
+ 实测:把 `cb.PLUGIN` 指向不存在目录 → 插件侧 `error` + `degraded=true`,`search.py` 仍产出 8 条证据,`support` 保持 `partial` 没跌成 `insufficient`,错误原因 `[WinError 267] 目录名称无效。` 完整保留在输出里。
72
+
73
+ ## 4 契约映射
74
+
75
+ ```json
76
+ {"type": "unsupported_numeric_claim", "rule": "numeric.claim_not_supported",
77
+ "status": "contradicted", "claim": "五道题",
78
+ "reason": "同指标同范围(重庆·省考)证据是 4 题,答复写的是 五道题"}
79
+ ```
80
+
81
+ `violation.type` 枚举现为 11 项;`verify.notices` 与 `violations` 分开,避免把「说不清」当「说错了」。
82
+
83
+ ## 5 验收结果
84
+
85
+ | 测试 | 结果 |
86
+ | --- | --- |
87
+ | `eval_numeric_claim.py` | **13/13**(11 条规格 + 2 条真 context) |
88
+ | `eval_engine_state.py` | 6/6 |
89
+ | `eval_answer_policy.py` | 8/8 |
90
+ | `eval_support.py` | 3/3 |
91
+ | `eval_4d.py` | 7/7 |
92
+ | `eval_conflicts.py` / `eval_dedup.py` / `eval_method.py` / `eval_blocks.py` | 全通过 |
93
+ | `e2e_check.py` | 8 题漂移 0 |
94
+ | `protect.py` | 35 条漂移 0 |
95
+
96
+ 拍板八条验收的对应关系:同范围同值→supported(用例 1/4)、同范围不同值→contradicted(2)、国考证据支撑重庆→scope_mismatch(3)、重庆证据支撑重庆→supported(4)、证据缺地域→unverifiable(5/5b)、指标不同→不得 supported(6)、单位换算(7,3 小时 vs 180 分钟)、多年份分别判断(8/8b)。
97
+
98
+ ## 6 已知局限(不要当成已解决)
99
+
100
+ 1. **考试类型别名覆盖不全**:`重庆申论` 这种写法只抽到地域,抽不到 `省考`。后果是国考证据里的「国考 30 分」与「重庆作文 30 分」只能判 `unverifiable`(保守,不放行),而不是更准确的 `scope_mismatch`。
101
+ 2. **中文数字支持到千位**,且只认「一二三四五六七八九十百零两」;「二十余」「十几」这类模糊量词抽不出,属未覆盖。
102
+ 3. **不做跨句推理**:只比较单个分句里的数值主张,句中指代(「这一说法」「上述数字」)不追踪。
103
+ 4. **`unverifiable` 会升 violation**:答复没写复核措辞时,不确定的数字主张也算违规。这是刻意选择——把不确定当定论说出来,就该被标;如果将来觉得太严,改 `REVIEW_WORDS` 触发条件即可。
104
+
105
+ ## 7 未做(按拍板「不擅自扩大范围」)
106
+
107
+ F3(support_reason 字段)、F4(context 快照 + TTL)、F5(子查询漂移)、F6 的抽取侧「口径限定词」过滤——F6 只作为 F2 的测试案例落地,抽取侧没有改。这些都留在阶段 2/3 处理。
@@ -0,0 +1,84 @@
1
+ # 阶段 2(仅 F4):context 快照 + TTL
2
+
3
+ > 范围:只做 F4。F3(support_reason)、F5(子查询漂移)、别名补齐都没动。
4
+ > 依据:用户 2026-11-05 的六条回归要求 + 一条接口细节(context_id 与 observe_id 分开)。
5
+
6
+ ## 1 为什么必须先有快照
7
+
8
+ `wiki_verify` 的输入是 `context_id`,不是「重新检索一遍」。如果核验时重建上下文,
9
+ 会出现两种恶性情况:
10
+
11
+ - 页面改了 → 拿新证据判旧回答,回答被「事后判错」;
12
+ - 检索抖了(子查询漂移、引擎降级)→ 同一份回答两次核验结论不同,不可复现。
13
+
14
+ 所以核验只能对着**当初交给 LLM 的那份证据**做。快照就是这个「当初」。
15
+
16
+ ## 2 交付物
17
+
18
+ | 文件 | 说明 |
19
+ | --- | --- |
20
+ | `<你的库根目录>\工具-tools\context_snapshot.py` | 新增:save / load / verify_answer / purge_expired + CLI |
21
+ | `<你的库根目录>\工具-tools\answer_policy.py` | `check_answer()` 现在同时返回 `notices`(原有数值判据的提示不再被吞掉) |
22
+ | `_tools\eval\eval_snapshot.py` | 新增:12 条验收(六条要求 × 细分) |
23
+ | `docs\契约-stage0\knowledge-gateway.v1.schema.json` | 新增 `E_CONTEXT_CORRUPT` 与 `verify.status=context_corrupt` |
24
+ | `docs\契约-stage0\samples\verify.context-expired.json` / `verify.context-corrupt.json` | 两份真实输出样例 |
25
+
26
+ ## 3 快照里存什么
27
+
28
+ ```json
29
+ {"snapshot_version":"1","contract_version":"1.0","context_id":"ctx_…",
30
+ "created_at":"…","expires_at":"…","ttl_seconds":1800,
31
+ "query":"重庆 申论 考几道题","root":"<你的库根目录>\\知识层-wiki",
32
+ "payload_sha256":"…","pages":{"概念-concepts/重庆申论考情.md":"a1b2…"},
33
+ "payload":{ /* 完整 context,原样 */ }}
34
+ ```
35
+
36
+ - `payload` 是整份 context 的深拷贝,**不做裁剪**——证据、`matched`(检索层级)、`provenance`(哪个引擎、第几名、哪个查询单元)、`supports`(槽位、引文、是否需要复核)全部保留。
37
+ - `payload_sha256` 是规范化 JSON 的 sha256,读回时校验;对不上就是 `corrupt`,绝不「尽量用」。
38
+ - `pages` 记录每张证据页当时的指纹。页面后来变了,核验仍按快照执行,但会带一条 `snapshot.page_changed` 提示——不静默,也不推翻结论。
39
+
40
+ ## 4 四种状态,各有各的话
41
+
42
+ | 状态 | error.code | 含义 | retryable |
43
+ | --- | --- | --- | --- |
44
+ | `ok` | — | 正常核验 | — |
45
+ | `violations_found` | — | 核验完成,有违规 | — |
46
+ | `context_missing` | `E_CONTEXT_NOT_FOUND` | 没这个 id | false |
47
+ | `context_expired` | `E_CONTEXT_EXPIRED` | 超时,需重新取上下文 | **true** |
48
+ | `context_corrupt` | `E_CONTEXT_CORRUPT` | 文件坏了或被改过 | false |
49
+
50
+ 损坏与丢失分开:文件不见了可能是清理;文件在但校验失败说明**有人动过**,这两件事的处置完全不同。
51
+
52
+ ## 5 并发与原子性
53
+
54
+ - `context_id = "ctx_" + uuid4().hex[:16]`,冲突概率可忽略;
55
+ - 写入走 `mkstemp` + `os.replace`,读的人只会看到「没有」或「完整」,看不到半个文件;
56
+ - 读路径无全局缓存、无共享状态,纯函数式读盘。
57
+
58
+ ## 6 接口细节:context_id 与 observe_id
59
+
60
+ 按用户的判断落地:**`context_id` 是快照的唯一引用**(本次核验凭这个找回证据),`observe_id` 是观察日志的编号(阶段 3 自动观察时生成)。契约里两个字段本来就有,这次只是让上下文侧真的产出 `context_id`,没有改字段名,也没有把两者合并。
61
+
62
+ ## 7 验收(12/12,全部实跑)
63
+
64
+ | # | 要求 | 用例 | 结果 |
65
+ | --- | --- | --- | --- |
66
+ | 1 | 快照后另一个进程核验,结果与原上下文一致 | 进程 A 保存,进程 B 核验,与本地 `check_answer` 比 violations 集合 | ✓ |
67
+ | 2 | 重启进程后仍能验证未过期快照 | 再起进程 C,结果与 B 逐字段相同 | ✓ |
68
+ | 3 | 过期 / 丢失 / 损坏分别明确 | 3a 随机 id→missing;3b ttl=1→expired(带过期时间文案);3c 改 payload→corrupt;3d 半截 JSON→corrupt | ✓✓✓✓ |
69
+ | 4 | 验证不重新检索、不重建上下文 | 把 `context_builder.build` 换成抛异常的桩,核验照常通过、调用计数 0 | ✓ |
70
+ | 5 | 证据 / 范围 / provenance 不丢不改 | payload 与原 ctx 深度相等;provenance/matched/supports 均在;核验前后快照字节不变 | ✓ |
71
+ | 6 | 并发不串用 | 4 份内容不同的快照 × 4 线程 = 16 次核验,各自判定互不污染 | ✓ |
72
+
73
+ 同时回归:`eval_answer_policy` 8/8、`eval_numeric_claim` 13/13、`eval_support` 3/3、`eval_engine_state` 6/6、`eval_4d` 7/7、`e2e` 8 题漂移 0、`protect` 35 条漂移 0。
74
+
75
+ ## 8 已知局限
76
+
77
+ 1. **过期快照不自动删**:`purge_expired()` 要显式调用(或由插件定时调)。没清理的过期快照仍占磁盘,但不会误用——状态是 `expired`。
78
+ 2. **TTL 固定 30 分钟起**:`save_context(ttl_seconds=…)` 可调,但没有「滑动续期」。一次核验窗口内够用,长期会话需要重新取上下文。
79
+ 3. **不做快照加密与权限隔离**:目录是普通文件,同一台机器上的其他进程可读。当前场景(本机个人库)可接受,多用户场景必须另做。
80
+ 4. **`snapshot.page_changed` 只是提示**:页面变了不改变核验结论,只多一条 notice。要不要据此降级为「需复核」,留给阶段 3 决定。
81
+
82
+ ## 9 下一步(按用户定的顺序)
83
+
84
+ F3 support_reason → 考试类型别名 → F5 子查询漂移。本轮未动其中任何一项。