@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/bench_axis_domain.py

@@ -88,6 +88,7 @@ PATHSETS = (("lexical",), ("lexical", "bucket"),
 
 # ------------------------------------------------------------------ 写入侧加工
 
+# 生效条件：c 含 'zh_fields' 且其中 identity/time/summary/terms/condition 均存在时，返回按身份、时间、摘要、词、条件及 c['text'] 拼成的正文，缺任一键则抛 KeyError；
 def body_of(c):
     """正文：与 bench_zh_mad.build_arm 的 a0 臂**逐字一致**（无意图行/无承接行）。"""
     f = c["zh_fields"]
@@ -102,6 +103,7 @@ def body_of(c):
     ])
 
 
+# 生效条件：c 含 'zh_fields'，terms 可迭代且 summary 经 str() 后参与空白切分时，将 terms 与切分词合并后交 routing.big_domain_classify 返回域判定结果；
 def write_domain(c):
     """写入侧域判定：只读 turn 自身的 zh_fields（盲于查询集）。"""
     f = c["zh_fields"]
@@ -109,11 +111,13 @@ def write_domain(c):
     return routing.big_domain_classify(terms)
 
 
+# 生效条件：q 含 question 字段时，返回 mg.expand_query_terms(q["question"]) 的词列表经 routing.big_domain_classify 得到的域分类。
 def query_domain(q):
     """查询侧域判定：与写入侧共用同一份 routing 词表（两侧同构）。"""
     return routing.big_domain_classify(list(mg.expand_query_terms(q["question"])))
 
 
+# 生效条件：mode 为 'base' 时返回 []；mode 为 'bare' 时返回 bz.normalize_terms(c, df) 的列表；其余 mode 下取 doms.get(c['id']) 得 d，d 为真值时返回 ['domain:'+d]，否则返回 []；
 def arm_tags(c, mode, df, doms):
     if mode == "base":
         return []
@@ -124,6 +128,7 @@ def arm_tags(c, mode, df, doms):
     return [f"domain:{d}"] if d else []
 
 
+# 生效条件：传入 corpus/name/mode/df 时先清空 HERE+ARM_PREFIX+name 同名目录再建 MdCGOS 并返回 (cg, doms)；mode 为 'shuf' 时把有域节点的域随机重排，verbose 为假值时跳过桶健康输出；
 def build_domain_arm(corpus, name, mode, df, verbose=True):
     """按臂建库。四臂唯一差异是 tags 内容（layer/正文/edges 全同）。"""
     import shutil
@@ -158,6 +163,7 @@ def build_domain_arm(corpus, name, mode, df, verbose=True):
 
 # ------------------------------------------------------------------ 主流程
 
+# 生效条件：不适用（无必需形参与模块级常量）
 def main():
     corpus = list(ec.iter_jsonl(CORPUS567))
     questions = list(ec.iter_jsonl(QUESTIONS500))
@@ -175,6 +181,7 @@ def main():
     n_ctx = sum(1 for v in qctx.values() if v)
     print(f"查询侧落域 {n_ctx}/{len(questions)} = {n_ctx / len(questions):.1%}")
 
+# 生效条件：q 含 'qid' 键时返回查询上下文映射中该 qid 对应的值，映射缺该键时 .get 返回 None（q 缺 'qid' 则抛 KeyError）；
     def context_of(q):
         return qctx.get(q["qid"])
 
@@ -218,6 +225,7 @@ def main():
     ec.save_result("axis_domain_locomo_zh.json", out)
 
     # ---- 裁决摘要 ----
+# 生效条件：a 与 p 以 '|' 拼成键后，在结果字典的 cells 映射中取该键，含键时返回其值，缺键时 .get 返回 {}；
     def cell(a, p):
         return out["cells"].get(f"{a}|{p}", {})
 
@@ -247,4 +255,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_blind_comp.py

@@ -122,10 +122,12 @@ D_TPL = [
 DISTRACT_POOL = ["马", "鱼", "狗", "鸟", "羊", "猪", "鸭", "肉", "奶", "蛋", "油", "米"]
 
 
+# 生效条件：s 为字符串时返回其全部相邻二元组集合；当 len(s) 小于 2 时返回空集合。
 def _bigrams(s):
     return {s[i:i + 2] for i in range(len(s) - 1)}
 
 
+# 生效条件：无参调用且 ATOMS_PATH 载入 atoms 后，逐条确认 UNSEEN 各组合词不在其中文集合、其相邻字符对均为原子，并确认 UNSEEN 无重复、set(COMP_EN)==set(UNSEEN)、set(COMP_L3)<=set(UNSEEN)，全部成立才静默通过，任一断言不成立即 AssertionError。
 def assert_material():
     """盲测纪律的机器化：素材在/不在 atoms + 组合词互相不冲突。"""
     atoms = json.load(open(ATOMS_PATH, encoding="utf-8"))["atoms"]
@@ -139,6 +141,7 @@ def assert_material():
     assert set(COMP_EN) == set(UNSEEN) and set(COMP_L3) <= set(UNSEEN)
 
 
+# 生效条件：以 SEED 初始化 random.Random 后对 UNSEEN 每词按 G_TPL 取模板生成含 gold 的篇目，再对 j=0..21 用 DISTRACT_POOL 随机取两个不同词按 D_TPL 造文，50 次重试内首次出现不含 UNSEEN 任何组合词的文本即 break 并 append，22 篇齐备后返回 corpus，50 次全冲突则 raise AssertionError。
 def gen_corpus():
     """33 篇受控语料：11 gold + 22 干扰。确定性，断言内嵌。"""
     rng = random.Random(SEED)
@@ -160,6 +163,7 @@ def gen_corpus():
     return corpus
 
 
+# 生效条件：对 UNSEEN 中每个 c 生成 L1 与 L2 题；当 c 属于 L3_SET 时，用 assert 强制其 COMP_L3 问句与 g_c 的 gold 文本 bigram 零交集，失败抛 AssertionError，通过后追加 L3 题。
 def gen_questions():
     """33 题。L3 生成时校验 query×gold bigram 零交集（纪律4）。"""
     questions = []
@@ -184,6 +188,7 @@ def gen_questions():
 CORPUS = None   # gen_questions 需引用语料正文（L3 校验），main 内先建语料
 
 
+# 生效条件：以 cg/questions/tag/en_atoms 与默认 semantic=False 调用时，en_atoms 为真则设 os.environ["MDCG_EN_ATOMS"]="1"、为假则 pop，semantic 为真则设 MDCG_SEMANTIC="1" 且仅当 semantic=="norm" 时把带真值 q_atoms 的题替换为 q_atoms 文本、semantic=="raw" 保持原句、semantic 为假则 pop，随后在 lexical 路径以 k=5 评测并返回 (按 ALL/L1_surface/L2_crosslingual/L3_semantic 分型的 by_type, 仅 en_atoms 为真时按 L2_crosslingual 题收集中文语素的 probe)。
 def run_arm(cg, questions, tag, en_atoms, semantic=False):
     """单臂评测：臂差异只在查询侧环境开关展开。返回 (summary_by_type, l2_probe)。
 
@@ -223,6 +228,7 @@ def run_arm(cg, questions, tag, en_atoms, semantic=False):
     return by_type, probe
 
 
+# 生效条件：无参调用时先 assert_material 再经 gen_corpus/gen_questions 得到语料与题，os.path.isdir(ARM_ROOT) 为真则删除该目录，以 ARM_ROOT 建 cg 并写入 CORPUS 全部篇目，os.path.isdir(ARM_ROOT+"_b2") 为真则删除该目录、以该路径建 cg2 并仅对 gold 为真值的篇目附加 semantic=" ".join(gold) 后写入，再依次以 (cg,b0_legacy,False,False)/(cg,b1_enatoms,True,False)/(cg2,b2_comp,False,"norm")/(cg2,b3_unified,False,"raw") 四臂调 run_arm 汇总指标与 b1 的 L2 探针，最后 ec.save_result 写出 blind_comp_baseline.json 并在 out 中记录 seed/n_corpus/n_q/arms/l2_probe/elapsed_s/boundaries。
 def main():
     global CORPUS
     t0 = time.time()
@@ -300,4 +306,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_en_atoms_public.py

@@ -68,6 +68,7 @@ NOISE_ZH = "天气 音乐 旅行"
 WRONG_POOLS = ["经济 历史 音乐", "天体 地理 化学", "科技 法律 医学"]
 
 
+# 生效条件：text 非空且 mode 为 drop20/noise3/wrong20 时按 idx 错位扰动并返回新串；text 为空返回 text or ""，mode 不在三者之内时原样返回 text。
 def perturb_kw(text, mode, idx):
     """②路 query 关键词扰动（确定性规则，验证归一噪声灵敏度）。
 
@@ -89,6 +90,7 @@ def perturb_kw(text, mode, idx):
     return text
 
 
+# 生效条件：CHAR_ATOMS 可读时按 data.get("lexicon") or {} 取词库，lexicon 缺失或为假值即返回空字典，否则逐键返回 {ch: str(v.get("en") or "")}（v 缺 "en" 或 "en" 为假值时该键值为空串）。
 def load_char_atoms():
     """字级英文原子库：{中文字: 英文短语}。"""
     with io.open(CHAR_ATOMS, encoding="utf-8") as f:
@@ -97,6 +99,7 @@ def load_char_atoms():
     return {ch: str(v.get("en") or "") for ch, v in lex.items()}
 
 
+# 生效条件：以 text or "" 逐字符、char_atoms 为字级映射表——字符落在 ZH_RANGE 内时取 char_atoms.get(ch, "")（缺键回落空串），其余字符原样保留，返回 normalize_en(" ".join(parts))；text 为假值（None/空串）时按空串返回 normalize_en("")。
 def zh_map_en(text, char_atoms):
     """中文逐字→英文短语映射串；英文/数字原样保留（交 normalize_en 归一）。"""
     lo, hi = ZH_RANGE
@@ -109,6 +112,7 @@ def zh_map_en(text, char_atoms):
     return normalize_en(" ".join(parts))
 
 
+# 生效条件：以 normalize_en(str(c.get("text") or "")).split() 为基词集，body_only 为真时只返回该集合的 frozenset；body_only 为假（默认 False）时再并入 zh_map_en(str(c.get("zh") or ""), char_atoms) 拆出的词，返回合并后的 frozenset。
 def node_atom_set(c, char_atoms, body_only=False):
     """doc 侧节点原子集：中文五槽字级映射 ∪ 英文正文归一词（双语双路 doc 侧）。
 
@@ -121,6 +125,7 @@ def node_atom_set(c, char_atoms, body_only=False):
     return frozenset(toks)
 
 
+# 生效条件：a 或 b 为假值（None/空集）时返回 0.0，否则交集非空返回 len(a & b)/len(a | b)、交集为空亦返回 0.0。
 def jaccard(a, b):
     if not a or not b:
         return 0.0
@@ -128,10 +133,12 @@ def jaccard(a, b):
     return inter / len(a | b) if inter else 0.0
 
 
+# 生效条件：对 st.items() 每个值取 round(v, 1) 组成同键字典，st 为空字典时返回空字典。
 def round_dict(st):
     return {k: round(v, 1) for k, v in st.items()}
 
 
+# 生效条件：遍历 questions 逐问评测——qatoms_of(q) 为假值时仅累加 st["n"] 不计命中，否则按 jaccard 对 docs 降序（同分按 nid 升序）排序、以首个 nid 落在 q.get("evidence_turns") or [] 中的 rank 累加 hit@1/5/10 与 1/rank 的 MRR，打印后返回 {k: v/max(st["n"],1)（rr 项）或 v*100.0/max(st["n"],1)}。
 def run_arm(questions, docs, qatoms_of, label):
     """单臂评测：全池 Jaccard 排序，hit@1/5/10 + MRR。"""
     st = {"h1": 0, "h5": 0, "h10": 0, "rr": 0.0, "n": 0}
@@ -160,6 +167,7 @@ def run_arm(questions, docs, qatoms_of, label):
     return {k: (v / n if k == "rr" else v * 100.0 / n) for k, v in st.items()}
 
 
+# 生效条件：CORPUS、QUESTIONS、CHAR_ATOMS 与 b6.EN_QUESTIONS 均可读（en_rows 由 ec.iter_jsonl 读取 b6.EN_QUESTIONS 构建）时，载入语料与题、构建 docs 与 docs_body、逐臂 run_arm 并打印锚点，返回 0。
 def main():
     t0 = time.time()
     with io.open(CORPUS, encoding="utf-8") as f:
@@ -190,6 +198,7 @@ def main():
     # 臂④ 机械归一端到端下界：英文问句 → 词表直译为中文词（CEDICT 28294 键
     #     ∪ EN_ZH 手工层，无 AI）→ ②同链路。与②唯一差异 = query 归一来源：
     #     ②=AI 理解式归一的输出形态（标注关键词），④=机械查表归一。
+# 生效条件：以 en_rows.get(q.get("qid"), "")（qid 缺键回落空串）取英文题面，经 normalize_en_query 取出的 terms 拼接后由 zh_map_en 映射，返回 frozenset(zh_map_en(" ".join(terms), char_atoms).split())；terms 为空时返回空 frozenset。
     def e4(q):
         terms, _ = normalize_en_query(en_rows.get(q.get("qid"), ""))
         return frozenset(zh_map_en(" ".join(terms), char_atoms).split())

package/md_cg/bench_governance.py

@@ -0,0 +1,348 @@
+# -*- coding: utf-8 -*-
+"""治理四指标只读评估器（阶段三 §5.1/§5.2 基线测量，纯合成确定性语料，不改任何行为面）。
+
+四指标（对照值来自 docs/灵枢自我改进工作计划_外部研究系列吸收 §5）：
+  g1 修正传播率  — 上游信任态降级后，依赖下游一跳同步失效比例
+                   （承载=trust.set_state+mark_dependents；对照 MAGE 91.2%）
+  g2 矛盾处理率  — 矛盾/否定证据被正确裁决比例
+                   （承载=judge_qualification 负条件 REJECT + judge_ranking 终排剔除；
+                   对照 MAGE 88.5%）
+  g3 过期取回率  — 检索 top-k 返回已过期节点比例（越低越好）
+                   （口径唯一真源=trust.is_expired / scrub._EXPIRY_KEYS；
+                   主口径=validity 防线残留率，副口径=默认面暴露率；对照 MAGE 3.1%）
+  g4 拒答 F1     — 不可答问题拒答的精确率/召回率/F1
+                   （拒答判据=空结果 或 top1 资格态∈{BLINDSPOT, DEFER}；
+                   对照 REMem 64.0）
+
+设计约束：
+  - 纯合成语料、无随机源，重复运行结果逐位一致（第 5 条可回放）；
+  - tempfile 库，不触碰真实认知图库（评估器只读）；
+  - 语料守卫断言（语料本身不合法立即 fail，防指标虚高——对齐 bench_blind_comp
+    assert_material 纪律）。
+运行：python -X utf8 -m md_cg.bench_governance [--out <json>]
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+
+from .mdcg import MdCG
+from .mdcos import MdCGOS
+from . import trust
+
+BASELINE_REF = {
+    "g1_correction_propagation": {"ours": None, "mage": 0.912},
+    "g2_contradiction_handling": {"ours": None, "mage": 0.885},
+    "g3_expired_recall": {"ours": None, "mage": 0.031, "note": "越低越好"},
+    "g4_refusal_f1": {"ours": None, "remem_f1": 64.0, "note": "REMem 为其自报口径，仅作量级对照"},
+}
+
+# ---------------------------------------------------------------- 语料 ----
+
+NOW = None  # main 内注入，保证同一次运行内时间一致
+
+
+def _doc(title, fact, cond="无条件", neg=None):
+    """CCG 六要素正文（与 test_sem_noise._doc 同构：负条件双写中的正文行）。"""
+    lines = [
+        "# 功能名：" + title,
+        "# 生效条件：" + cond,
+        "# 子功能：" + title + "事实卡",
+        "# 执行：检索面事实提供",
+        "# 验证方式：test",
+        "# 不适用条件：" + (neg or "无"),
+        "",
+        fact,
+    ]
+    return "\n".join(lines)
+
+
+# 可答事实：条件词面刻意出现在对应 query 里（正条件确认可命中 → ACCEPT）
+FACTS = [
+    # (nid, 事实句, 正条件行, query)
+    ("g_f1", "灵枢检索缓存默认保留 128 条。", "载体：缓存配置", "缓存配置里默认缓存多大"),
+    ("g_f2", "蜂巢心跳间隔为 30 秒。", "载体：蜂巢参数", "蜂巢参数中心跳间隔是多少"),
+    ("g_f3", "评测器统一经 eval_common 汇总指标。", "载体：评测约定", "评测约定的汇总入口在哪"),
+    ("g_f4", "python 命令统一走 argv 列表加显式 UTF-8。", "无条件", "python 命令执行要用什么编码约定"),
+    ("g_f5", "语义摘要路默认关闭、显式 opt-in 才启用。", "无条件", "语义摘要路默认开还是关"),
+    ("g_f6", "分支节点不出库、不进主支检索。", "无条件", "分支节点会不会进主支检索"),
+]
+
+# 否定反事实：负条件双写（kwarg + 正文行），否定情境 query=「你刚才在干什么」
+NEG_QUERY = "你刚才在干什么"
+NEG_COND = "刚才在干什么"
+NEGATIVES = [
+    ("g_n1", "我没有在喝水。"),
+    ("g_n2", "我没有在写代码。"),
+    ("g_n3", "我没有在开会。"),
+    ("g_n4", "我没有在跑步。"),
+]
+
+# 过期节点：与可答事实同题竞争（旧版本数值已失效），effective_until 已过
+STALE = [
+    ("g_e1", "蜂巢心跳间隔曾为 10 秒（旧版）。", "g_f2"),
+    ("g_e2", "评测器旧口径按 k=3 汇总（已废弃）。", "g_f3"),
+    ("g_e3", "检索缓存默认曾为 64 条（旧版）。", "g_f1"),
+]
+
+# 修正传播链：地基 U + 一跳依赖 D1..D4
+U_GOV = "g_u_gov"
+DEPENDENTS = ["g_d1", "g_d2", "g_d3", "g_d4"]
+
+# 无关背景（干扰；CCG 完整可 ACCEPT——拒答 F1 的诚实下界来自它）
+BACKDROP = [
+    ("g_b1", "工作区在约定中默认使用简体中文交流。"),
+    ("g_b2", "认知图只给知识与建议能力名，不执行操作。"),
+    ("g_b3", "留痕粒度按任务合并，不逐命令逐行。"),
+]
+
+# 不可答问题（与语料词面零重叠；期望系统拒答）
+UNANSWERABLE = [
+    "用户 2026 年春节在哪过的",
+    "项目预算总共批了多少万",
+    "作者最喜欢的菜是什么",
+    "下个版本计划支持日语吗",
+    "服务器部署在哪个机房",
+    "团队现在有多少人",
+    "竞品报价单是多少",
+    "昨天的会议纪要说了什么",
+]
+
+
+def _assert_material(now):
+    """语料守卫：素材纪律机器断言（违者 fail，防指标虚高）。"""
+    fact_ids = {nid for nid, *_ in FACTS}
+    stale_ids = {nid for nid, *_ in STALE}
+    neg_ids = {nid for nid, *_ in NEGATIVES}
+    assert not (fact_ids & stale_ids | fact_ids & neg_ids | stale_ids & neg_ids), "语料 id 重叠"
+    assert len(UNANSWERABLE) >= 5 and len(FACTS) >= 5, "探针集过小"
+    # 不可答题与语料词面零重叠（粗粒度：语料特征词不出现于不可答题面）
+    lex = "".join(f for _, f, *_ in FACTS) + "".join(f for _, f in NEGATIVES) \
+        + "".join(f for _, f, _ in STALE) + "".join(f for _, f in BACKDROP)
+    for q in UNANSWERABLE:
+        overlap = [w for w in ("缓存", "蜂巢", "心跳", "评测", "python", "语义摘要", "分支") if w in q]
+        assert not overlap, f"不可答题词面泄漏：{q} 命中 {overlap}"
+    assert "无条件" not in lex or True  # 语料自洽由 judge 实测兜底
+    for _, _, base in STALE:
+        assert base in fact_ids, "过期节点必须与某可答事实同题竞争"
+
+
+def build_corpus(cg, now):
+    """建确定性语料。返回节点数。"""
+    n = 0
+    # 可答事实（F1-F3 带条件、F4-F6 无条件豁免）
+    for nid, fact, cond, _q in FACTS:
+        cg.add(nid, _doc(nid, fact, cond=cond), layer="knowledge",
+               verification_basis="test")
+        n += 1
+    # 否定反事实（负条件双写）
+    for nid, sent in NEGATIVES:
+        cg.add(nid, _doc(nid, sent, cond="时间：即时情境", neg=NEG_COND), layer="knowledge",
+               verification_basis="test", non_applicable_conditions=[NEG_COND])
+        n += 1
+    # 过期节点（effective_until 已过；expired_at 冗余由 add 派生）
+    for nid, fact, _base in STALE:
+        cg.add(nid, _doc(nid, fact, cond="无条件"), layer="knowledge",
+               verification_basis="test",
+               effective_from=now - 7200.0, effective_until=now - 3600.0)
+        n += 1
+    # 无关背景
+    for nid, fact in BACKDROP:
+        cg.add(nid, _doc(nid, fact), layer="knowledge", verification_basis="test")
+        n += 1
+    # 修正传播链：地基 + 一跳依赖（depends_on=依赖图语义，trust.dependents_index 消费；
+    # derived_from=血缘溯源，语义不同不混用）
+    cg.add(U_GOV, _doc(U_GOV, "地基结论：核心算法口径以文档 A 为准。", cond="无条件"),
+           layer="knowledge", verification_basis="test")
+    n += 1
+    for did in DEPENDENTS:
+        cg.add(did, _doc(did, f"{did} 结论：沿用地基口径实现细节。", cond="无条件"),
+               layer="knowledge", verification_basis="test", depends_on=[U_GOV])
+        n += 1
+    return n
+
+
+# ---------------------------------------------------------------- 指标 ----
+
+def m1_correction_propagation(cg):
+    """g1：上游降级 doubted → mark_dependents 一跳同步传播率。"""
+    r0 = trust.set_state(cg, U_GOV, "doubted", reason="基线评测：地基被修正")
+    assert isinstance(r0, dict) and r0.get("ok"), f"上游降级失败：{r0}"
+    r = trust.mark_dependents(cg, U_GOV, reason="基线评测：上游修正传播", apply=True)
+    deps, upd = r.get("dependents") or [], r.get("updated") or []
+    assert sorted(deps) == sorted(DEPENDENTS), f"依赖索引不符预期：{deps}"
+    rate = (len(upd) / len(deps)) if deps else None
+    return {"metric": "correction_propagation", "value": rate,
+            "detail": {"dependents": len(deps), "updated": len(upd),
+                       "skipped": r.get("skipped"), "reference_mage": 0.912}}
+
+
+def _is_refusal(results):
+    """拒答判据：空结果 或 top1 资格态 ∈ {BLINDSPOT, DEFER}。"""
+    if not results:
+        return True, "empty"
+    entry = results[0]
+    qual = entry[2] if len(entry) > 2 else None  # 条目=(node, score, qual, prov)
+    st = (qual or {}).get("state") if isinstance(qual, dict) else None
+    return st in ("BLINDSPOT", "DEFER"), st
+
+
+def m2_contradiction_handling(cg):
+    """g2：否定证据正确裁决率 = 定点裁决 + 检索防线（skip 项不入分母）。"""
+    correct = wrong = skipped = 0
+    detail = {"judged": [], "retrieval": []}
+    # (a) 定点裁决：否定节点在否定情境下应 REJECT（judge_qualification 直调）
+    for nid, _sent in NEGATIVES:
+        node = cg.get(nid)
+        qual = MdCG.judge_qualification(
+            {"frontmatter": node.get("frontmatter") or {}, "content": node.get("content") or ""},
+            NEG_QUERY, None)
+        st = qual.get("state")
+        detail["judged"].append({"nid": nid, "state": st})
+        if st == "REJECT":
+            correct += 1
+        elif st is None:
+            skipped += 1
+        else:
+            wrong += 1
+    # (b) 检索防线：judge_ranking 终排后 top-k 无否定节点冒充
+    res, meta = cg.search_rrf(NEG_QUERY, k=10, judge=True, judge_ranking=True,
+                              record=False)
+    ids = [r[0]["id"] for r in res]
+    leaked = [i for i in ids if i in {n for n, _ in NEGATIVES}]
+    detail["retrieval"] = {"top_ids": ids[:5], "leaked_negatives": leaked,
+                           "judge_filtered": (meta or {}).get("judge_filtered")}
+    if leaked:
+        wrong += 1
+    else:
+        correct += 1
+    total = correct + wrong
+    return {"metric": "contradiction_handling", "value": (correct / total) if total else None,
+            "detail": dict(detail, correct=correct, wrong=wrong, skipped=skipped,
+                           reference_mage=0.885)}
+
+
+def m3_expired_recall(cg, now):
+    """g3：过期取回率。主口径=validity 防线残留率；副口径=默认面暴露率。"""
+    stale_ids = {nid for nid, *_ in STALE}
+    probe = "蜂巢参数中心跳间隔是多少"  # 与过期节点 g_e1 同题竞争
+    out = {}
+    for tag, kw in (("raw", {}), ("guard", {"validity": True}),
+                    ("judge_ranking", {"judge_ranking": True})):
+        res, _meta = cg.search_rrf(probe, k=10, judge=True, record=False, **kw)
+        ids = [r[0]["id"] for r in res]
+        hits = [i for i in ids if i in stale_ids]
+        out[tag] = {"top_ids": ids[:5], "stale_hits": hits,
+                    "rate": (len(hits) / len(ids)) if ids else None}
+    return {"metric": "expired_recall",
+            "value": out["guard"]["rate"],            # 主口径：防线后残留（越低越好）
+            "detail": dict(out, probe=probe, stale_total=len(stale_ids),
+                           reference_mage=0.031, note="raw=默认面暴露；guard=validity 防线")}
+
+
+def m4_refusal_f1(cg):
+    """g4：拒答精确率/召回率/F1（正类=不可答）。"""
+    tp = fn = fp = tn = 0
+    detail = {"unanswerable": [], "answerable": []}
+    for q in UNANSWERABLE:
+        res, _m = cg.search_rrf(q, k=3, judge=True, judge_ranking=True, record=False)
+        refused, st = _is_refusal(res)
+        detail["unanswerable"].append({"q": q, "refused": refused, "top_state": st})
+        if refused:
+            tp += 1
+        else:
+            fn += 1
+    for _nid, _fact, _cond, q in FACTS:
+        res, _m = cg.search_rrf(q, k=3, judge=True, judge_ranking=True, record=False)
+        refused, st = _is_refusal(res)
+        detail["answerable"].append({"q": q, "refused": refused, "top_state": st})
+        if refused:
+            fp += 1
+        else:
+            tn += 1
+    p = tp / (tp + fp) if (tp + fp) else None
+    r = tp / (tp + fn) if (tp + fn) else None
+    if p is not None and r is not None and p + r:
+        f1 = 2 * p * r / (p + r)
+    else:
+        # tp+fp=0：系统从未拒答（无 query 侧拒答信号）——保守编码 F1=0.0 并如实注明
+        f1 = 0.0
+    return {"metric": "refusal_f1",
+            "value": f1,
+            "detail": {"precision": p, "recall": r, "tp": tp, "fn": fn, "fp": fp, "tn": tn,
+                       "refusal_rule": "empty or top1 state in {BLINDSPOT, DEFER}",
+                       "note": ("no refusal signal: judge 资格态只判节点可用性，"
+                                "不判答案存在性；不可答题被无关 ACCEPT 节点冒充全部未拒"
+                                if (tp + fp) == 0 else ""),
+                       "reference_remem_f1": 64.0}}
+
+
+# ---------------------------------------------------------------- 主流程 ----
+
+def run(root=None, keep=False):
+    """跑四指标，返回 (report_dict, root)。root 供测试复检。"""
+    now = time.time()
+    _assert_material(now)
+    root = root or tempfile.mkdtemp(prefix="mdcg_governance_")
+    try:
+        cg = MdCGOS(root, actor="bench_governance", autoflush=200)
+        n_nodes = build_corpus(cg, now)
+        cg.flush()
+        report = {
+            "meta": {
+                "bench": "bench_governance",
+                "date": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now)),
+                "corpus_nodes": n_nodes,
+                "head": _git_head(),
+                "determinism": "synthetic corpus, no RNG",
+                "scopes": "阶段三 §5.1 治理三件套 + §5.2 拒答量化（基线测量，不改行为）",
+            },
+            "g1_correction_propagation": m1_correction_propagation(cg),
+            "g2_contradiction_handling": m2_contradiction_handling(cg),
+            "g3_expired_recall": m3_expired_recall(cg, now),
+            "g4_refusal_f1": m4_refusal_f1(cg),
+            "baseline_reference": BASELINE_REF,
+        }
+        return report, root
+    finally:
+        if not keep:
+            shutil.rmtree(root, ignore_errors=True)
+
+
+def _git_head():
+    try:
+        out = subprocess.run(["git", "rev-parse", "--short", "HEAD"],
+                             capture_output=True, text=True, encoding="utf-8",
+                             errors="replace", shell=False, timeout=10)
+        return (out.stdout or "").strip() or "unknown"
+    except Exception:                                     # noqa: BLE001
+        return "unknown"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="治理四指标只读评估器")
+    ap.add_argument("--out", default=os.path.join("data", "external", "eval_results",
+                                                  "governance_baseline.json"))
+    ap.add_argument("--keep", action="store_true", help="保留临时库目录（调试用）")
+    args = ap.parse_args(argv)
+    report, root = run(keep=args.keep)
+    out = os.path.abspath(args.out)
+    os.makedirs(os.path.dirname(out), exist_ok=True)
+    with open(out, "w", encoding="utf-8") as f:
+        json.dump(report, f, ensure_ascii=False, indent=2)
+    print(json.dumps({k: v.get("value") for k, v in report.items()
+                      if isinstance(v, dict) and "value" in v},
+                     ensure_ascii=False, indent=2))
+    print("baseline ->", out, "| temp root:", root)
+    vals = [report[g]["value"] for g in ("g1_correction_propagation",
+                                         "g2_contradiction_handling",
+                                         "g3_expired_recall", "g4_refusal_f1")]
+    return 0 if all(v is not None for v in vals) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/md_cg/bench_lme_zh.py

@@ -75,6 +75,7 @@ ZH_Q_PROMPT = """从下面英文问题里抽出中文关键词：只输出名词
 
 
 # ------------------------------------------------------------------ LLM
+# 生效条件：环境变量 DEEPSEEK_API_KEY 为真值（缺省或空串即抛 RuntimeError「需要 DEEPSEEK_API_KEY」）且 range(retries) 至少迭代一次（retries≥1）时，用 messages、max_tokens 调 llm_chat 并返回 (content, usage)；全部重试失败或 retries=0（last 保持 None）时抛 RuntimeError「LLM 调用失败：…」。
 def _llm(messages, max_tokens=400, retries=3):
     from md_cg.bench_task_ab_llm import llm_chat
     key = os.environ.get("DEEPSEEK_API_KEY")
@@ -100,6 +101,7 @@ _DEFAULT_COND = {"observation_position": "会话陈述", "observation_tool": "
                  "existence_constraint": "公开"}
 
 
+# 生效条件：p 经 os.path.isfile(p) 判定为普通文件时按 utf-8 打开并返回 json.load(f)；os.path.isfile(p) 为假（含目录、不存在路径、空串）时返回 {}。
 def _load_json(p):
     if os.path.isfile(p):
         with open(p, encoding="utf-8") as f:
@@ -107,6 +109,7 @@ def _load_json(p):
     return {}
 
 
+# 生效条件：无参调用即返回 (_load_json(MAN_ZH), _load_json(MAN_Q))，每个元素在模块级常量 MAN_ZH / MAN_Q 指向普通文件时为解析出的 JSON、否则为 {}。
 def _load_manual():
     """读入会话模型直接产出的中文层 / 中文查询词（零 API 依赖）。
 
@@ -119,6 +122,7 @@ def _load_manual():
     return _load_json(MAN_ZH), _load_json(MAN_Q)
 
 
+# 生效条件：z 为真值且 re.search(r"条件=([^；;]+)") 命中，并按 [|｜] 切分后至少有一段以 ":" / "：" 分为两段且首段 strip 后在模块级常量 _COND_KEYS 中时，返回非空映射 dict；z 为假值、正则未命中或映射为空时返回 None。
 def _cond_of(z):
     """从中文层的「条件=观测位置:…|观测工具:…|…」抽条件空间 dict。"""
     m = re.search(r"条件=([^；;]+)", z or "")
@@ -132,6 +136,7 @@ def _cond_of(z):
     return out or None
 
 
+# 生效条件：模块级常量 CACHE 经 os.path.isfile(CACHE) 判定为普通文件时按 utf-8 打开并返回 json.load(f)；否则返回 {}。
 def _load_cache():
     if os.path.isfile(CACHE):
         with open(CACHE, encoding="utf-8") as f:
@@ -139,12 +144,14 @@ def _load_cache():
     return {}
 
 
+# 生效条件：以 c 为输入即 os.makedirs(DIR, exist_ok=True) 后按 utf-8 把 c 以 ensure_ascii=False、indent=1 写入模块级常量 CACHE，无前置校验、无返回值。
 def _save_cache(c):
     os.makedirs(DIR, exist_ok=True)
     with open(CACHE, "w", encoding="utf-8") as f:
         json.dump(c, f, ensure_ascii=False, indent=1)
 
 
+# 生效条件：cache 命中 "L2:"+turn["id"] 时直接返回该缓存值；否则用 ZH_PROMPT 拼 json.dumps({"date": turn.get("date"), "text": turn.get("text")})（键缺失回落 null）调 _llm，依次取 max_tokens=1200、2600，对 content or "" 去代码块与标签后 strip(" ,，、|")，首个非空即 break，把结果写回 cache 并返回（两次皆空则缓存并返回 ""）。
 def zh_layer(turn, cache):
     """一条 turn → 中文词袋。缓存 key 带版本号：prompt 改版必须失效旧缓存。
 
@@ -171,6 +178,7 @@ def zh_layer(turn, cache):
     return s
 
 
+# 生效条件：cache 命中 "Q2:"+q["qid"] 时直接返回该缓存值；否则以 ZH_Q_PROMPT+q["question"] 调 _llm(max_tokens=1200)，去代码块后 strip(" ,，、") 写入 cache[key]，结果为空串时抛 RuntimeError「查询侧关键词为空…」，非空时返回 cache[key]。
 def zh_question(q, cache):
     """英文问题 → 中文关键词（与写入侧同源；额度须 ≥1200，否则推理烧空 content）。"""
     key = "Q2:" + q["qid"]
@@ -186,6 +194,7 @@ def zh_question(q, cache):
 
 
 # ------------------------------------------------------------------ 池
+# 生效条件：模块级常量 POOL 为普通文件时直接返回其中非空行的 json.loads 列表（此时不读 n_q、n_distract、seed）；否则以 random.Random(seed)、每组 max(1, n_q//len(GROUPS)) 条（取 q["evidence_turns"][0] 为 gold）采样后追加 rng.sample(rest, min(n_distract, len(rest))) 干扰项，写出 POOL 与 questions.json 并返回 pool。
 def build_pool(n_q, n_distract, seed=7):
     """采样：n_q 题（分组覆盖）各取 evidence_turns[0] 为 gold，再取干扰。"""
     if os.path.isfile(POOL):
@@ -222,12 +231,14 @@ def build_pool(n_q, n_distract, seed=7):
     return pool
 
 
+# 生效条件：DIR 目录下的 questions.json 是 UTF-8 合法 JSON 时，返回 json.load 得到的对象。
 def load_questions_zh():
     with open(os.path.join(DIR, "questions.json"), encoding="utf-8") as f:
         return json.load(f)
 
 
 # ------------------------------------------------------------------ 建库 / 评测
+# 生效条件：以 ec.build_eval_cg(None, root, corpus or POOL, ec.lm_turn_text, "lmezh", calib_of=calib if zh_of 为真值 else None, rebuild=rebuild) 执行并返回其结果（形参 pool 在该调用中未被使用，实际用 corpus or POOL；zh_only 只在内层 calib 中生效，不传给 build_eval_cg）。
 def build(root, pool, zh_of=None, rebuild=False, zh_only=False, corpus=None):
     """zh_of: turn_id → 中文层；None = 裸文本库。
 
@@ -237,6 +248,7 @@ def build(root, pool, zh_of=None, rebuild=False, zh_only=False, corpus=None):
     上界而非全译库真值。故另设 F 臂（池只含 20 条 gold、正文全中文）隔离该假象，
     单测中文层自身的可区分性。
     """
+# 生效条件：作为 build 的内层函数闭包使用 zh_of/zh_only，ctx 未被使用；zh_of 为真值且 zh_of.get(r["id"]) 为真值时 cs = _cond_of(z) or cs，否则 cs = dict(_DEFAULT_COND)；zh_only 为真值时返回 (z or ec.lm_turn_text(r), [], cs)，否则返回 (ec.lm_turn_text(r) 在 z 为真值时再拼 "\n"+z, [], cs)。
     def calib(r, ctx=None):
         z = zh_of.get(r["id"]) if zh_of else None
         cs = dict(_DEFAULT_COND)
@@ -252,6 +264,7 @@ def build(root, pool, zh_of=None, rebuild=False, zh_only=False, corpus=None):
                             calib_of=calib if zh_of else None, rebuild=rebuild)
 
 
+# 生效条件：给定 cg、questions 与 qtext_of 时，对每题用 qtext_of(q) 替换 question 后经 ec.evaluate_group 评测，并按 k 汇总为结果。
 def eval_arm(cg, questions, qtext_of, k=5):
     rows = []
     for q in questions:
@@ -261,6 +274,7 @@ def eval_arm(cg, questions, qtext_of, k=5):
     return ec.summarize(rows, k=k)
 
 
+# 生效条件：argv 由 argparse 解析（--n-q/--n-distract/--k/--build/--rebuild/--workers 等）；--build 只产池即返回，否则需外部数据在指定路径就位、缺失即抛异常不静默降级；
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--n-q", type=int, default=20)
@@ -287,6 +301,7 @@ def main():
     print(f"中文层：本地 {len(man_zh)} 条（查询词本地 {len(man_q)} 条），"
           f"缓存合计 {len(cache)} 条，模型 {MODEL}（本轮不调用）")
 
+# 生效条件：对 r 调 zh_layer(r, cache)（cache 为闭包变量）成功时返回 (r["id"], 中文层, None)；zh_layer 抛任何异常时返回 (r["id"], "", f"{type(exc).__name__}: {exc}")。
     def work(r):
         try:
             return r["id"], zh_layer(r, cache), None
@@ -393,4 +408,4 @@ def main():
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())