@furongjun1999/dsh-memory 0.9.22 → 0.10.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 (179) hide show
  1. package/CHANGELOG.en.md +450 -0
  2. package/CHANGELOG.md +112 -0
  3. package/README.en.md +244 -0
  4. package/README.md +272 -260
  5. package/codebuddy/CODEBUDDY.md +1 -1
  6. package/docs/README.md +2 -0
  7. package/docs/discipline/templates/full.md.tmpl +1 -1
  8. package/docs/discipline/templates/rules.mdc.tmpl +1 -1
  9. package/docs/en/README.md +190 -0
  10. package/docs/en/TRANSLATION.md +78 -0
  11. package/docs/en/TRANSLATION_MANIFEST.json +170 -0
  12. package/docs/en/TRANSLATION_REPORT.md +11 -0
  13. package/docs/en/dev/README.md +10 -0
  14. package/docs/en/dev/coding-testing.md +72 -0
  15. package/docs/en/dev/switch-matrix.md +10 -0
  16. package/docs/en/glossary.md +97 -0
  17. package/docs/en/harnesses/claude.md +100 -0
  18. package/docs/en/harnesses/codebuddy.md +93 -0
  19. package/docs/en/harnesses/codex.md +88 -0
  20. package/docs/en/harnesses/dsh.md +84 -0
  21. package/docs/en/harnesses/zcode.md +42 -0
  22. package/docs/en/mdcg/ccg.md +32 -0
  23. package/docs/en/mdcg/generated-docs.md +20 -0
  24. package/docs/en/mdcg/guardrail-charter.md +170 -0
  25. package/docs/en/mdcg/mcp-tool-names.md +43 -0
  26. package/docs/en/mdcg/multi-harness.md +43 -0
  27. package/docs/en/mdcg/recall-metadata.md +30 -0
  28. package/docs/en/mdcg/world-model-endpoint.md +379 -0
  29. package/docs/en/mdcg/write-aliases.md +130 -0
  30. package/docs/en/ops/README.md +11 -0
  31. package/docs/en/ops/environment-known-issues.md +244 -0
  32. package/docs/en/ops/install.md +72 -0
  33. package/docs/en/ops/operations-troubleshooting.md +86 -0
  34. package/docs/en/ops/permissions-review.md +79 -0
  35. package/docs/en/ops/release-governance.md +49 -0
  36. package/docs/en/ops/tool-name-migration.md +30 -0
  37. package/docs/en/ops/ui-install-troubleshooting.md +53 -0
  38. package/docs/en/standards/ai-coding-standard-checklist.md +71 -0
  39. package/docs/en/standards/ai-coding-standard-lingshu.md +47 -0
  40. package/docs/en/standards/ai-coding-standard.md +185 -0
  41. package/docs/en/ui/minimal.md +62 -0
  42. package/docs/mdcg/cogmap_ops.md +16 -15
  43. package/lib/client.js +29 -3
  44. package/lib/hooks.d.ts +34 -0
  45. package/lib/hooks.js +167 -33
  46. package/lib/index.js +19 -3
  47. package/lib/lib/console_web.mjs +30 -3
  48. package/lib/lib/hook_audit.d.ts +3 -2
  49. package/lib/lib/hook_audit.js +14 -4
  50. package/lib/lib/mdcg_client.d.ts +5 -2
  51. package/lib/lib/mdcg_client.js +8 -4
  52. package/lib/lib/prompt_safety.d.ts +24 -0
  53. package/lib/lib/prompt_safety.js +77 -1
  54. package/lib/lib/token_store.js +5 -2
  55. package/lib/tools.js +5 -3
  56. package/md_cg/bucketindex.py +231 -0
  57. package/md_cg/bucketscope.py +339 -0
  58. package/md_cg/config_registry_bulk.py +19 -10
  59. package/md_cg/config_validate.py +14 -2
  60. package/md_cg/detrerank.py +137 -0
  61. package/md_cg/fsutil.py +215 -25
  62. package/md_cg/govern/__init__.py +23 -0
  63. package/md_cg/iface/__init__.py +46 -0
  64. package/md_cg/iface/_verify.py +609 -0
  65. package/md_cg/iface/contracts.py +337 -0
  66. package/md_cg/judgment_manifest.py +14 -0
  67. package/md_cg/kernel/__init__.py +27 -0
  68. package/md_cg/mcp_server.py +457 -23
  69. package/md_cg/mdcg.py +1034 -79
  70. package/md_cg/mdcos.py +263 -21
  71. package/md_cg/metacognition.py +66 -13
  72. package/md_cg/mutate_extract_shipped.py +126 -0
  73. package/md_cg/mutate_ledger_e2e.py +100 -0
  74. package/md_cg/nodefile.py +147 -23
  75. package/md_cg/op_table.py +22 -4
  76. package/md_cg/probe_c_ledger_integrity.py +258 -0
  77. package/md_cg/probe_d_retirement_discipline.py +263 -0
  78. package/md_cg/reconcile.py +9 -11
  79. package/md_cg/review_cli.py +6 -1
  80. package/md_cg/rollback.py +16 -1
  81. package/md_cg/run_tests.py +30 -1
  82. package/md_cg/scopeselect.py +214 -0
  83. package/md_cg/scrub.py +160 -23
  84. package/md_cg/security.py +4 -2
  85. package/md_cg/state_extract.py +149 -0
  86. package/md_cg/state_slots.py +58 -10
  87. package/md_cg/structboost.py +179 -0
  88. package/md_cg/test_alternatives_historical.py +162 -0
  89. package/md_cg/test_b2_sensitivity_landing.py +226 -223
  90. package/md_cg/test_b3_merge_keeps_content.py +608 -583
  91. package/md_cg/test_bucket_cards.py +85 -0
  92. package/md_cg/test_bucket_day_order.py +74 -0
  93. package/md_cg/test_bucket_quota.py +79 -0
  94. package/md_cg/test_bucket_recency_guards.py +75 -0
  95. package/md_cg/test_bucket_three_causes.py +83 -0
  96. package/md_cg/test_bucketindex.py +130 -0
  97. package/md_cg/test_bucketscope_early.py +71 -0
  98. package/md_cg/test_cond_term_fold.py +183 -0
  99. package/md_cg/test_cond_term_fold_gate.py +1210 -0
  100. package/md_cg/test_cond_term_neg_scope.py +147 -0
  101. package/md_cg/test_cond_terms_colon.py +348 -0
  102. package/md_cg/test_detrerank.py +157 -0
  103. package/md_cg/test_gate_four_kpi.py +136 -0
  104. package/md_cg/test_generation_guard.py +76 -43
  105. package/md_cg/test_issue192_move_layer_indices_guard.py +48 -0
  106. package/md_cg/test_issue362_neg_condition.py +44 -7
  107. package/md_cg/test_issue39_utf8_stdio.py +572 -572
  108. package/md_cg/test_issue413_preimage_failclosed.py +147 -9
  109. package/md_cg/test_issue444_scrub_evidence_plaintext.py +14 -8
  110. package/md_cg/test_issue677_flush_batch_io.py +139 -0
  111. package/md_cg/test_issue677_info_fast.py +82 -0
  112. package/md_cg/test_issue677_remember_dedupe.py +106 -0
  113. package/md_cg/test_issue712_tokens_sessions_read.py +199 -0
  114. package/md_cg/test_issue722_strict_conditions.py +96 -0
  115. package/md_cg/test_issue730_narrowing_audit.py +121 -0
  116. package/md_cg/test_issue733_verify_override.py +193 -0
  117. package/md_cg/test_issue733_verify_override_and_overwrite_inherit.py +315 -0
  118. package/md_cg/test_issue740_filelock_fd_leak.py +218 -0
  119. package/md_cg/test_issue741_content_hash_same_source.py +158 -0
  120. package/md_cg/test_issue747_slot_contradiction.py +125 -0
  121. package/md_cg/test_issue754_nested_root_guard.py +197 -0
  122. package/md_cg/test_issue757_index_hash_compare.py +85 -0
  123. package/md_cg/test_issue758_disk_hash_single.py +67 -0
  124. package/md_cg/test_issue759_twophase_hash.py +67 -0
  125. package/md_cg/test_issue768_overwrite_time_window_anchor.py +135 -0
  126. package/md_cg/test_issue789_log_plaintext_probe.py +100 -0
  127. package/md_cg/test_issue790_verb_negation.py +77 -0
  128. package/md_cg/test_issue810_root_guard.py +71 -0
  129. package/md_cg/test_issue812_info_index_stale.py +78 -0
  130. package/md_cg/test_issue827_weaken_dedup.py +361 -0
  131. package/md_cg/test_issue829_calibration_positive_gate.py +473 -0
  132. package/md_cg/test_kernel_iface_contracts.py +18 -0
  133. package/md_cg/test_md_cg_no_hive_dep.py +238 -17
  134. package/md_cg/test_n204_n205_n226_n227_n228_n229_exit_gates.py +545 -542
  135. package/md_cg/test_n209_verify_write_face_gates.py +5 -2
  136. package/md_cg/test_neg_condition_hits.py +336 -333
  137. package/md_cg/test_probe_cd_shipped.py +385 -0
  138. package/md_cg/test_recent_tail.py +93 -0
  139. package/md_cg/test_run_tests_entry_gates.py +110 -0
  140. package/md_cg/test_scopeselect.py +70 -0
  141. package/md_cg/test_scopeselect_clock.py +70 -0
  142. package/md_cg/test_scrub_source_line_false_positive.py +64 -0
  143. package/md_cg/test_session_attribution_consistency.py +835 -813
  144. package/md_cg/test_state_extract_shipped.py +162 -0
  145. package/md_cg/test_state_ledger_chain.py +207 -0
  146. package/md_cg/test_state_ledger_e2e.py +145 -0
  147. package/md_cg/test_structboost.py +102 -0
  148. package/md_cg/test_timeboost.py +83 -0
  149. package/md_cg/test_timeboost_relativedate.py +71 -0
  150. package/md_cg/test_topicagg.py +129 -0
  151. package/md_cg/test_twophase.py +286 -286
  152. package/md_cg/timeboost.py +223 -0
  153. package/md_cg/tokens.py +55 -7
  154. package/md_cg/topicagg.py +142 -0
  155. package/md_cg/twophase.py +15 -6
  156. package/md_cg/whitebox_kb/wisdom/code_compose.py +33 -5
  157. package/md_cg/whitebox_kb/wisdom/compose_engine.py +5 -1
  158. package/md_cg/whitebox_kb/wisdom/role_compose.py +271 -268
  159. package/md_cg/writepipe.py +35 -3
  160. package/package.json +4 -1
  161. package/scripts/workspace_index.py +2 -0
  162. package/src/hooks.ts +182 -34
  163. package/src/index.ts +19 -3
  164. package/src/lib/console_web.mjs +30 -3
  165. package/src/lib/hook_audit.ts +15 -5
  166. package/src/lib/mdcg_client.ts +8 -4
  167. package/src/lib/prompt_safety.ts +73 -1
  168. package/src/lib/token_store.ts +5 -2
  169. package/src/tools.ts +5 -3
  170. package/ui/minimal/integrity.json +2 -2
  171. package/ui/minimal/payload/build-ui.mjs +41 -2
  172. package/ui/minimal/payload/lib/client.js +29 -3
  173. package/ui/minimal/payload/lib/lib/console_web.mjs +30 -3
  174. package/ui/minimal/payload/src/lib/console_web.mjs +30 -3
  175. package/ui/minimal/payload/web/app.js +3 -1
  176. package/ui/minimal/payload/web/client.js +30 -3
  177. package/web/app.js +3 -1
  178. package/web/client.js +30 -3
  179. package/zcode/AGENTS.md +1 -1
@@ -26,8 +26,21 @@
26
26
  · `tier` =最后有值事件的顶层 `tier` 透传(`append(extra=…)` 会把 extra 并入行
27
27
  顶层,故「extra.tier」与「行顶层 tier」是同一处);缺失(键不在或为 None)→
28
28
  `TIER_UNSPECIFIED`——**不编造**。
29
- · `alternatives` / `blindspots`:本批**结构在场、恒为空列表**——「同期未决值」与
30
- 「声明缺口」的判定口径**后置**(P1 事件行尚无该信号),**不得臆造填充**。
29
+ · `alternatives`(**本批已落地**,判据见下);`blindspots` 仍**结构在场、恒为空列表**
30
+ ——「声明缺口」的判定口径**后置**(P1 事件行尚无该信号),**不得臆造填充**。
31
+
32
+ `alternatives` 判据(本批,2026-11-02)——**只读面,写侧一字未动**:
33
+ 定义为「该槽位**曾被断言过、且不等于当前值**的去重值集合」(保持首次出现序)。
34
+ · 明确**不用**「同一时间窗」判「同期」:台账 `t` 是 `time.time()` **记账时刻**,
35
+ 不是事件发生时刻;`seq` 是调用方给的轮/序号且**可缺省为 None**。
36
+ 拿它们做时间窗判据会把「相隔很久的两次记账」误判成同期 ⇒ 违背「不臆造」。
37
+ · 因此本字段的语义是**历史遗留候选**,比设计稿「同期未决值」弱——已在
38
+ `docs/eval/` 读数文档中标注定级,不冒充强语义。
39
+ · retired 态(值已撤回)下,被撤回的值**仍进 alternatives**(可回溯);
40
+ 复位后当前值不入 alternatives,更旧的遗留值仍在。
41
+ · `history=False` 的快速路径(`_project_current_page`)**不保留历史**,
42
+ 算不出本字段 ⇒ 恒返回空列表,并在返回值上如实标注 `alternatives_partial=True`
43
+ (**不静默给一个看起来完整的空**)。
31
44
  · `history` =该槽位全部事件原样(每条=事件行的 `t/seq/old/new/kind/evidence/
32
45
  actor` 七字段,值不改写;缺键取 None);`history=False` 时**不带该键**。
33
46
 
@@ -47,8 +60,9 @@ CLI(纯只读人工入口,**恒可用、无开关**):
47
60
  CLI 是人工排查入口(只读、不改任何状态)。
48
61
 
49
62
  不适用条件:本模块**不判语义**——「不是事实」的言语(玩笑/元层/回忆转述)之消歧
50
- 标记(`not_fact` 等)不在本批(P1 事件行无该信号);`alternatives`/`blindspots` 的
51
- 真值判定亦未落地(见上,恒空列表)。跨库/多租户合并不在此(单库=单台账)。
63
+ 标记(`not_fact` 等)不在本批(P1 事件行无该信号);`blindspots` 的真值判定亦
64
+ 未落地(见上,恒空列表)。`alternatives` **已落地**(历史遗留候选,见上判据段)。
65
+ 跨库/多租户合并不在此(单库=单台账)。
52
66
  """
53
67
  from __future__ import annotations
54
68
 
@@ -82,7 +96,30 @@ def _hist_item(rec) -> dict:
82
96
  return {k: rec.get(k) for k in _HIST_FIELDS}
83
97
 
84
98
 
85
- # 生效条件:subject/slot 为分组键、recs 为同组记录(**非空**,落盘序)、history 为真值时——按模块头回放规则返回单元 dict(含 history 键);history 为假值时同一单元但不带 history 键;recs 为空时抛 IndexError(组由记录现场建成,恒非空,不吞错)。
99
+ # 生效条件:recs 为同组台账记录(落盘序)、value 为当前值——返回该槽位**曾被断言过、且不等于当前值**的去重值列表(保持首次出现序);撤回事件(`_is_void`)不计,当前值不计;去重按相等比较线性进行(**不用 set**:`new` 可以是不可哈希的 dict/list)。
100
+ def _alternatives_of(recs, value) -> list:
101
+ """该槽位**曾被断言过、且不等于当前值**的去重值(保持首次出现序)。
102
+
103
+ 判据见模块头:只读历史 `new` 的非空值,剔除当前值;**不用时间窗/seq 判「同期」**
104
+ (台账 `t` 是记账时刻、`seq` 可缺省),故语义是「历史遗留候选」而非强「同期未决」。
105
+
106
+ 去重**不用 `set`**:台账是外部可写面,`new` 可以是任意 JSON 值(dict/list),
107
+ 不可哈希 ⇒ `set` 会抛 `TypeError`(本批实测踩到,见
108
+ `test_state_projection_streaming` 的 dict 值用例)。改用线性「已见列表 + 相等比较」:
109
+ 槽位值个数极小,O(n²) 无实际代价,且对 dict/list/None/数字一律成立。
110
+ """
111
+ out = []
112
+ for rec in recs:
113
+ if _is_void(rec):
114
+ continue
115
+ v = rec.get("new")
116
+ if v == value:
117
+ continue
118
+ if v not in out:
119
+ out.append(v)
120
+ return out
121
+
122
+
86
123
  def _replay(subject, slot, recs, *, history=True) -> dict:
87
124
  """单组回放:现值 / 档位 / 区间 / 变迁史(规则逐条见模块头)。"""
88
125
  value = None
@@ -118,17 +155,25 @@ def _replay(subject, slot, recs, *, history=True) -> dict:
118
155
  "t_from": t_from, "t_to": t_to,
119
156
  "seq_from": seq_from, "seq_to": seq_to,
120
157
  "tier": tier,
121
- # 结构在场、恒空:判定口径后置(模块头,不得臆造填充)。
122
- "alternatives": [], "blindspots": [],
158
+ # alternatives 本批已落地(判据见模块头);blindspots 仍后置、恒空。
159
+ "alternatives": _alternatives_of(recs, value),
160
+ "blindspots": [],
123
161
  "event_count": len(recs)}
124
162
  if history:
125
163
  unit["history"] = [_hist_item(r) for r in recs]
126
164
  return unit
127
165
 
128
166
 
129
- # 生效条件:recs 为落盘序记录(可迭代、可空)时——按 (subject, slot) 分组并稳定排序,经共享分页回放单点返回全量单元;history 为假时不带 history 键;不改写入参记录。
167
+ # 生效条件:recs 为落盘序记录(可迭代、可空)时——history=True 经共享分页回放单点返回全量单元;history=False 与 `project_page` 走**同一归约器**(`_project_current_page`),保证两条入口同口径(否则 alternatives 在两条路上一真一空);include_retired 为假时剔除退役单元;不改写入参记录。
130
168
  def _project(recs, *, include_retired=False, history=True) -> list:
131
- """落盘序记录 → 全量投影;流式分组后逐组释放原始记录。"""
169
+ """落盘序记录 → 全量投影;流式分组后逐组释放原始记录。
170
+
171
+ history=False 必须与 `project_page(history=False)` 同源:两处若各走一条路,
172
+ `alternatives` 会出现「一条路径有真值、另一条恒空」的口径分叉
173
+ (`test_state_projection_streaming` 的 L46/L49 就是钉这条的)。
174
+ """
175
+ if not history:
176
+ return _project_current_page(recs, include_retired=include_retired)[1]
132
177
  return _project_history_page(recs, include_retired=include_retired,
133
178
  history=history)[1]
134
179
 
@@ -205,7 +250,10 @@ def _project_current_page(recs, *, include_retired=False, limit=None) -> tuple:
205
250
  "t_from": t_from, "t_to": t_to,
206
251
  "seq_from": seq_from, "seq_to": seq_to,
207
252
  "tier": TIER_UNSPECIFIED if tier is None else tier,
208
- "alternatives": [], "blindspots": [], "event_count": count})
253
+ # 单遍路径**不保留历史** ⇒ 算不出 alternatives。
254
+ # 不静默给一个看起来完整的空:如实标注该字段不可得。
255
+ "alternatives": [], "alternatives_partial": True,
256
+ "blindspots": [], "event_count": count})
209
257
  return total, out
210
258
 
211
259
 
@@ -0,0 +1,179 @@
1
+ # -*- coding: utf-8 -*-
2
+ """结构信号重排(structboost)——**章节路由 + 元素覆盖**的确定性提升。
3
+
4
+ bench 读数(hive-memory-bench · 六元素判断题 476 · 行窗切块 · gold=evidence 行号):
5
+
6
+ | 配置 | gold@1 | gold@3 | gold@10 |
7
+ |---|---:|---:|---:|
8
+ | baseline | 49.6% | 71.9% | 92.0% |
9
+ | 章节 ×2 | 49.0% | 85.7% | 95.8% |
10
+ | **章节 ×2 + 元素 ×1.0** | **52.5%** | **85.7%** | **96.2%** |
11
+
12
+ 两条信号都是**确定性可数**的(与 detrerank 同一纪律):
13
+ · 章节:题面「第N章」→ 候选正文里的「## 第N章」标题 / tags 里的章号;
14
+ · 元素:题面按 `·`(六元素分隔符)切出的元素,在候选正文中出现的比例。
15
+
16
+ 不做硬过滤:题面可能故意写错章节(负例题),硬滤会把正确证据筛掉 ⇒ 只用**乘性提升**。
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import re
21
+
22
+ #: 章节命中提升倍数(bench 扫描 1.5/2.0/3.0 结果相同,取中位 2.0)。
23
+ CHAPTER_BOOST = 2.0
24
+ #: 元素覆盖率提升系数(bench 扫描 0.5/1.0/2.0,1.0 最优:@3 不掉、@1/@10 最高)。
25
+ ELEMENT_BOOST = 1.0
26
+
27
+ _CN = {"一": 1, "二": 2, "三": 3, "四": 4, "五": 5,
28
+ "六": 6, "七": 7, "八": 8, "九": 9, "十": 10}
29
+
30
+
31
+ def cn2int(s):
32
+ """中文数字/阿拉伯数字 → int(1..99 够用);解析不出返回 None。"""
33
+ s = (s or "").strip()
34
+ if not s:
35
+ return None
36
+ if s.isdigit():
37
+ return int(s)
38
+ if s in _CN:
39
+ return _CN[s]
40
+ if len(s) == 2 and s[1] == "十":
41
+ return _CN.get(s[0], 0) * 10
42
+ if len(s) == 2 and s[0] == "十":
43
+ return 10 + _CN.get(s[1], 0)
44
+ if len(s) == 3 and s[1] == "十":
45
+ return _CN.get(s[0], 0) * 10 + _CN.get(s[2], 0)
46
+ return None
47
+
48
+
49
+ def query_chapter(query):
50
+ """从查询里取章号(「第N章」/「第N章「标题」」);没有返回 None。"""
51
+ m = re.search(r"第\s*([一二三四五六七八九十\d]+)\s*章", str(query or ""))
52
+ return cn2int(m.group(1)) if m else None
53
+
54
+
55
+ def node_chapter(node):
56
+ """候选节点的章号:**正文标题优先**,其次 tags。
57
+
58
+ 为什么正文优先:实测(476 题)tags 里常有与正文不一致的章号(人工打标/批次标签),
59
+ 按 tags 优先会让提升打到错的章上——@1 从 0.50 掉到 0.30。
60
+ 正文的 `## 第N章` 标题是语料自带的结构,才可信。
61
+ """
62
+ text = str(node.get("content") or "")
63
+ m = re.search(r"^#{1,4}\s*第\s*([一二三四五六七八九十\d]+)\s*章", text, re.M)
64
+ if m:
65
+ return cn2int(m.group(1))
66
+ fm = node.get("frontmatter") or {}
67
+ for tag in (fm.get("tags") or []):
68
+ t = str(tag)
69
+ if t.startswith(CHAPTER_TAG_PREFIX): # 入库期盖章约定:ch:3
70
+ try:
71
+ return int(t[len(CHAPTER_TAG_PREFIX):])
72
+ except ValueError:
73
+ continue
74
+ got = query_chapter(t)
75
+ if got:
76
+ return got
77
+ return None
78
+
79
+
80
+ def elements(query):
81
+ """六元素:按 `·` 切分,去掉章节标签与过短片段。"""
82
+ parts = [p.strip() for p in str(query or "").split("·") if p.strip()]
83
+ out = []
84
+ for p in parts:
85
+ if query_chapter(p):
86
+ continue
87
+ p = re.sub(r"^[《「【((]|[》」】))]$", "", p).strip()
88
+ if len(p) >= 2:
89
+ out.append(p)
90
+ return out
91
+
92
+
93
+ def boost(node, query, chap=0, elems=None):
94
+ """单个候选的提升倍数(确定性;无信号返回 1.0)。
95
+
96
+ `chap`:**显式章号**(0 表示「本条不启用章节信号」)。
97
+ 这里刻意**不**在函数内重新解析 query——否则调用方用 `chap=None` 关闸时,
98
+ 函数又把章号解析回来,闸门形同虚设(实测:gold@1 仍然从 0.50 掉到 0.15)。
99
+ """
100
+ q_chap = chap or None
101
+ es = elements(query) if elems is None else elems
102
+ factor = 1.0
103
+ if q_chap is not None and node_chapter(node) == q_chap:
104
+ factor *= CHAPTER_BOOST
105
+ if es:
106
+ text = str(node.get("content") or "")
107
+ hits = sum(1 for e in es if e in text)
108
+ factor *= 1.0 + ELEMENT_BOOST * (hits / float(len(es)))
109
+ return factor
110
+
111
+
112
+ #: 章节提升的启用前提:候选集中**已知章号**的比例达到此值。
113
+ #: 实测(476 题):仅 23/153 块自带章节标题时启用章节提升,gold@1 从 0.50 掉到 0.16——
114
+ #: 因为提升只打在「少数知道章号的块」上,把它们错误地顶到前面。
115
+ #: 故候选集里章号信息不足时,**整条章节信号弃用**(而不是半用)。
116
+ CHAPTER_MIN_KNOWN = 0.5
117
+
118
+
119
+ def rerank(results, query, k=None):
120
+ """对 [(node, score, ...), ...] 做稳定重排:score × boost,同分按原序(确定性)。
121
+
122
+ 只在**已召回的候选集内**重排,不改候选集、不做过滤 ⇒ 无召回损失风险。
123
+ 章节信号按 `CHAPTER_MIN_KNOWN` 闸门决定是否启用(信息不足则整条弃用)。
124
+ """
125
+ q_chap = query_chapter(query)
126
+ es = elements(query)
127
+ if q_chap is not None and results:
128
+ known = sum(1 for item in results if node_chapter(item[0]) is not None)
129
+ if known / float(len(results)) < CHAPTER_MIN_KNOWN:
130
+ q_chap = 0 # 章号信息不足 ⇒ 弃用章节信号(0 = 关,只留元素信号)
131
+ order = []
132
+ for idx, item in enumerate(results or ()):
133
+ node = item[0]
134
+ try:
135
+ score = float(item[1])
136
+ except (TypeError, ValueError, IndexError):
137
+ score = 0.0
138
+ order.append((score * boost(node, query, q_chap, es), idx, item))
139
+ order.sort(key=lambda t: (-t[0], t[1]))
140
+ out = [t[2] for t in order]
141
+ return out[:k] if k else out
142
+
143
+
144
+ #: 盖章用的 tag 前缀(`ch:3`)。与内容标题同源,避免与人工 tag 混用。
145
+ CHAPTER_TAG_PREFIX = "ch:"
146
+
147
+
148
+ def stamp_chapters(nodes):
149
+ """入库期章号盖章:按给定顺序遍历节点,把「最近一次出现的章节标题」写成 tag。
150
+
151
+ 为什么需要(bench 实测):行窗切块后 **153 块里只有 23 块自带 `## 第N章` 标题**,
152
+ 其余块在查询期无法判知自己属于哪一章 ⇒ 章节提升会打到「章节首块」上,
153
+ gold@1 从 0.50 掉到 0.16。章号必须在**入库期**按文档顺序继承,查询期才有得用。
154
+
155
+ nodes: [{"id":..., "content":...}, ...](有序);返回 {id: chapter},并原地把
156
+ `ch:N` 写进 `frontmatter["tags"]`(若给定的是可变 dict)。
157
+ """
158
+ out = {}
159
+ last = None
160
+ for node in nodes or ():
161
+ text = str(node.get("content") or "")
162
+ m = re.search(r"^#{1,4}\s*第\s*([一二三四五六七八九十\d]+)\s*章", text, re.M)
163
+ if m:
164
+ got = cn2int(m.group(1))
165
+ if got:
166
+ last = got
167
+ if last is None:
168
+ continue
169
+ nid = node.get("id")
170
+ out[nid] = last
171
+ fm = node.get("frontmatter")
172
+ if isinstance(fm, dict):
173
+ tags = fm.get("tags")
174
+ if not isinstance(tags, list):
175
+ tags = fm["tags"] = []
176
+ key = "%s%d" % (CHAPTER_TAG_PREFIX, last)
177
+ if key not in tags:
178
+ tags.append(key)
179
+ return out
@@ -0,0 +1,162 @@
1
+ # -*- coding: utf-8 -*-
2
+ """守卫:`alternatives`(历史遗留候选)判定口径 —— 只读面,写侧一字未动。
3
+
4
+ 背景:`state_slots` 模块头原写「alternatives/blindspots 结构在场、恒为空列表,
5
+ 判定口径后置,不得臆造填充」。本批只落地 **alternatives**,`blindspots` 仍后置。
6
+
7
+ 本守卫钉住:
8
+ A 口径定义:曾被断言过、且**不等于当前值**的去重值(保持首次出现序)
9
+ B 不臆造:无历史遗留 ⇒ 空;当前值绝不进 alternatives
10
+ C 撤回/复位语义:retired 态被撤回值仍可回溯;复位后旧值仍在
11
+ D 单遍快速路径(history=False)算不出 ⇒ 如实标注 `alternatives_partial=True`
12
+ E 与既有行为不冲突:blindspots 仍恒空;单元键集只增不减
13
+ F t/seq 不得当「同期」判据(口径备忘,防后人误用)
14
+ G 写入侧零改动(写盘行字段集不变)
15
+ """
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import os
20
+ import sys
21
+ import tempfile
22
+
23
+ _HERE = os.path.dirname(os.path.abspath(__file__))
24
+ sys.path.insert(0, os.path.dirname(_HERE))
25
+
26
+ from md_cg import mdcg, state_events, state_slots # noqa: E402
27
+
28
+ _P, _F = [], []
29
+
30
+
31
+ def ok(cond, name, detail=""):
32
+ (_P if cond else _F).append(name)
33
+ print((" PASS " if cond else " FAIL ") + name + ((" | " + detail) if detail else ""))
34
+
35
+
36
+ SUBJ = "鲸娘"
37
+
38
+
39
+ def seed(cg):
40
+ """住所:旧家 → 新家 → 撤回;身份:学徒(单值)。
41
+ 复用一个干净台账,供 C/G 组使用。"""
42
+ state_events.append(cg, SUBJ, "住所", old=None, new="旧家",
43
+ kind="enablement", seq=1, evidence="r1")
44
+ state_events.append(cg, SUBJ, "住所", old="旧家", new="新家",
45
+ kind="migration", seq=2, evidence="r2")
46
+ state_events.append(cg, SUBJ, "身份", old=None, new="学徒",
47
+ kind="enablement", seq=3, evidence="r3")
48
+ state_events.append(cg, SUBJ, "住所", old="新家", new=None,
49
+ kind="retraction", seq=4, evidence="r4")
50
+
51
+
52
+ def main():
53
+ root = tempfile.mkdtemp(prefix="t_alt_")
54
+ try:
55
+ cg = mdcg.MdCG(root)
56
+ seed(cg)
57
+
58
+ # ---------- A 口径定义 ----------
59
+ units = {(u["subject"], u["slot"]): u
60
+ for u in state_slots.project(cg, include_retired=True)}
61
+ zs = units[(SUBJ, "住所")]
62
+ ok(zs["alternatives"] == ["旧家", "新家"],
63
+ "A1 历史两值(旧家/新家)均为备择,保持首次出现序", str(zs["alternatives"]))
64
+ ok(isinstance(zs["alternatives"], list), "A2 alternatives 是 list 类型")
65
+
66
+ # ---------- B 不臆造 ----------
67
+ sf = units[(SUBJ, "身份")]
68
+ ok(sf["alternatives"] == [], "B1 无历史遗留 ⇒ 空列表(不臆造)",
69
+ str(sf["alternatives"]))
70
+ ok(sf["value"] == "学徒" and "学徒" not in sf["alternatives"],
71
+ "B2 当前值不进 alternatives")
72
+
73
+ # ---------- C 撤回 / 复位 ----------
74
+ ok(zs["state"] == "retired" and "新家" in zs["alternatives"],
75
+ "C1 retired 态:被撤回的值仍进备择(可回溯)")
76
+ state_events.append(cg, SUBJ, "住所", old=None, new="新家",
77
+ kind="enablement", seq=5, evidence="r5")
78
+ units2 = {(u["subject"], u["slot"]): u
79
+ for u in state_slots.project(cg, include_retired=True)}
80
+ zs2 = units2[(SUBJ, "住所")]
81
+ ok(zs2["value"] == "新家", "C2 复位后当前值=新家", repr(zs2["value"]))
82
+ ok(zs2["alternatives"] == ["旧家"],
83
+ "C3 复位后:当前值新家不入备择,旧家仍在(去重无重复)",
84
+ str(zs2["alternatives"]))
85
+
86
+ # ---------- C4/C5 去重的真阳性样本 ----------
87
+ # 前面「旧家」只出现过一次,M3(去掉去重)在那种样本上抓不到。
88
+ # 这里让同一值「旧家」在历史上**再次出现**(且仍不是当前值):
89
+ # 旧家 → 新家 → 旧家 → 新家(当前)
90
+ # 期望 alternatives 仍只有一条「旧家」,不得重复。
91
+ state_events.append(cg, SUBJ, "住所", old="新家", new="旧家",
92
+ kind="migration", seq=6, evidence="r6")
93
+ state_events.append(cg, SUBJ, "住所", old="旧家", new="新家",
94
+ kind="migration", seq=7, evidence="r7")
95
+ units3 = {(u["subject"], u["slot"]): u
96
+ for u in state_slots.project(cg, include_retired=True)}
97
+ zs3 = units3[(SUBJ, "住所")]
98
+ ok(zs3["value"] == "新家", "C4 再次复位后当前值=新家", repr(zs3["value"]))
99
+ ok(zs3["alternatives"] == ["旧家"],
100
+ "C5 同一值历史重复出现 ⇒ 备择去重后仅一条", str(zs3["alternatives"]))
101
+ ok(len(zs3["alternatives"]) == len(set(zs3["alternatives"])),
102
+ "C6 alternatives 无重复项(去重不变量)", str(zs3["alternatives"]))
103
+
104
+ # ---------- D 单遍快速路径必须如实标注 ----------
105
+ fast = state_slots.project(cg, include_retired=True, history=False)
106
+ fmap = {(u["subject"], u["slot"]): u for u in fast}
107
+ fz = fmap[(SUBJ, "住所")]
108
+ ok(fz.get("alternatives") == [] and fz.get("alternatives_partial") is True,
109
+ "D1 history=False 快速路径:alternatives 空且标注 partial=True(不假绿)", repr(fz.get("alternatives_partial")))
110
+ ok("alternatives_partial" not in zs2,
111
+ "D2 完整路径不带 partial 标记(键只在不完整路径出现)")
112
+
113
+ # ---------- E 既有行为不冲突 ----------
114
+ ok(all(u["blindspots"] == [] for u in units2.values()),
115
+ "E1 blindspots 仍恒空(口径后置,未被本批顺带改动)")
116
+ expected = {"subject", "slot", "value", "state", "t_from", "t_to",
117
+ "seq_from", "seq_to", "tier", "alternatives",
118
+ "blindspots", "event_count"}
119
+ ok(expected <= set(zs2), "E2 单元键集未减少", str(sorted(set(zs2) - expected)))
120
+ ok(set(zs2) - expected <= {"history"}, "E3 无未经登记的新键",
121
+ str(sorted(set(zs2) - expected)))
122
+
123
+ # ---------- F 口径备忘:t/seq 不可当同期判据 ----------
124
+ recs = state_events.read(cg)
125
+ ok(all("t" in r for r in recs), "F1 台账 t 存在(记账时刻,非事件发生时刻)")
126
+ ok(any(r.get("seq") is None for r in state_events.read(cg)) is False,
127
+ "F2 本样本 seq 全非 None(但口径允许 None,不作判据)")
128
+
129
+ # ---------- G 写入侧零改动 ----------
130
+ keys_written = set()
131
+ for r in state_events.read(cg):
132
+ keys_written |= set(r)
133
+ ok(keys_written <= {"t", "subject", "slot", "old", "new", "kind",
134
+ "seq", "evidence", "actor"},
135
+ "G1 写盘行字段集与改前一致(本批只改读面)", str(sorted(keys_written)))
136
+
137
+ # ---------- H 两个入口同口径(_project vs project_page)----------
138
+ # 回归来源:本批曾让 _project(history=False) 走回放、project_page(history=False)
139
+ # 走归约器,于是 alternatives 一条路径有真值、另一条恒空。
140
+ # test_state_projection_streaming 抓到了;这里补一条**本守卫内**的断言。
141
+ raw = state_events.read(cg)
142
+ for retire in (False, True):
143
+ a = state_slots._project(raw, include_retired=retire, history=False)
144
+ b = state_slots.project_page(cg, include_retired=retire, history=False)[1]
145
+ ok(a == b, "H1 _project 与 project_page(history=False) 逐位一致 retire=%s" % retire,
146
+ "" if a == b else "分叉:%r vs %r" % (a[:1], b[:1]))
147
+ # 且两处都必须标注 partial(口径一致而非都退化成空)
148
+ a0 = state_slots._project(raw, history=False)[0]
149
+ ok(a0.get("alternatives_partial") is True,
150
+ "H2 _project(history=False) 同样标注 partial(两入口同口径)",
151
+ repr(a0.get("alternatives_partial")))
152
+
153
+ finally:
154
+ import shutil
155
+ shutil.rmtree(root, ignore_errors=True)
156
+
157
+ print("\nSUMMARY: 通过=%d 失败=%d" % (len(_P), len(_F)))
158
+ return 1 if _F else 0
159
+
160
+
161
+ if __name__ == "__main__":
162
+ sys.exit(main())