@furongjun1999/dsh-memory 0.4.8 → 0.4.10

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())

package/md_cg/bench_locomo.py

@@ -40,6 +40,7 @@ GROUPS = {
 POS_GROUPS = ("precise", "temporal", "interference")
 
 
+# 生效条件：命令行参数可被解析、GROUPS 中每组题型可按 --n 抽样时，按 --calibrated 选择 ROOT_LC_CAL 或 legacy 库评估并打印，无返回值。
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--n", type=int, default=0, help="每组抽样上限（0=全量）")
@@ -118,4 +119,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_locomo_zh.py

@@ -89,6 +89,7 @@ KNOWN_DANGLING = {"scene_3_session_10_turn_19"}
 MAX_DF_FIXED = 5
 
 
+# 生效条件：任意 n_pool（含 0 等假值，源码不做校验）下返回 max(MAX_DF_FIXED, int(round(0.05 * n_pool)))，结果不小于模块级常量 MAX_DF_FIXED。
 def max_df_auto(n_pool):
     """池规模 → edges 的 df 上限。
 
@@ -100,6 +101,7 @@ def max_df_auto(n_pool):
     return max(MAX_DF_FIXED, int(round(0.05 * n_pool)))
 
 
+# 生效条件：path 指向逐行 JSON 的 UTF-8 文本时，跳过空行并逐行 yield json.loads 结果。
 def iter_jsonl(path):
     with open(path, encoding="utf-8") as f:
         for line in f:
@@ -108,11 +110,13 @@ def iter_jsonl(path):
                 yield json.loads(line)
 
 
+# 生效条件：path 能被 open(path, encoding="utf-8") 打开时返回 json.load(f) 的解析结果。
 def load_json(path):
     with open(path, encoding="utf-8") as f:
         return json.load(f)
 
 
+# 生效条件：os.path.isdir(d) 为假时直接返回空 dict；为真时按 sorted(os.listdir(d)) 顺序读取后缀为 .json 的分片并 out.update(part)（后者覆盖前者），任一分片不是 dict 时抛 SystemExit，否则返回合并后的 out。
 def load_chunks(d):
     """合并目录下全部分片 JSON（后者覆盖前者，便于修订单条）。"""
     out = {}
@@ -133,6 +137,7 @@ _SPEAKER_RE = re.compile(r"^([A-Za-z][A-Za-z .'\-]{0,24}): ")
 _DATE_RE = re.compile(r"Data time: (\d{1,2}:\d{2} [AP]M on \w+ \d{1,2} \w+, \d{4})")
 
 
+# 生效条件：调用即从 locomo_corpus.jsonl 建 id→记录映射、读 locomo_questions.jsonl，逐题取 q.get("evidence_turns") or []（缺键或假值按空列表）去重排序为证据 turn，text/title 用 c.get(...) or "" 兜假值、speaker/date 由 _SPEAKER_RE.match / _DATE_RE.search 命中才非空；verbose=True 时额外打印含 KNOWN_DANGLING 未登记告警与直接取键 q["qtype"] 的题型统计，verbose=False 时只跳过打印，写 RAW_TURNS/RAW_QUESTIONS 与返回 (rows, questions) 不变。
 def cmd_dump(verbose=True):
     """确定性派生：证据 turn 全集 + 题库 → raw_turns/raw_questions（零标注）。"""
     os.makedirs(ZH_TURNS, exist_ok=True)
@@ -176,6 +181,7 @@ def cmd_dump(verbose=True):
 
 
 # ------------------------------------------------------------------ status
+# 生效条件：verbose=True 时打印写入/查询侧完成度、多余 turn/qid 键与待补项（各截取前 head 项），并对已产出中文层用 bz.parse_zh 检查 identity/time/summary/terms 四项真值（并非五槽），非全真者记入 bad；verbose=False 时不打印、不做该槽位检查，返回值中 bad 恒为 []。
 def cmd_status(verbose=True, head=12):
     """产出进度：中文层 / 中文查询的覆盖与缺口（分批产出时用）。"""
     turns, questions = cmd_dump(verbose=False)
@@ -217,6 +223,7 @@ def cmd_status(verbose=True, head=12):
 
 
 # ------------------------------------------------------------------ prepare
+# 生效条件：miss_t 或 miss_q 任一非空即 raise SystemExit，否则按 sort_key（仅接受 scene_数字_session_数字_turn_数字 形式的 id，否则 raise SystemExit）对 turns 数值序排序，写出 corpus567.jsonl/questions500.jsonl 并返回 (corpus, out_q)，其中 answer 与 evidence_turns 为假值时分别落为 "" 与 []，verbose 只控制末尾打印。
 def cmd_prepare(verbose=True):
     """合并中文层 → corpus567.jsonl + questions500.jsonl（幂等覆盖）。"""
     turns, questions = cmd_dump(verbose=False)
@@ -231,6 +238,7 @@ def cmd_prepare(verbose=True):
             f"先跑 `status` 看缺口。")
 
     # 语料：按 (scene, session, turn) 数值序 —— 「承接前一条」需要确定的时间序
+# 生效条件：tid 匹配 ^scene_(\d+)_session_(\d+)_turn_(\d+)$ 时返回三个整数的 tuple（scene, session, turn），否则 raise SystemExit（不做其他容错或回退）。
     def sort_key(tid):
         m = re.match(r"scene_(\d+)_session_(\d+)_turn_(\d+)$", tid)
         if not m:
@@ -275,6 +283,7 @@ def cmd_prepare(verbose=True):
 
 
 # ------------------------------------------------------------------ build
+# 生效条件：max_df 为 None（默认）时用 max_df_auto(len(corpus)) 自动取值，max_df 传出值（含 0 等假值）则直接使用；随后对 bz.ARMS 每臂调 bz.build_arm(corpus, arm, max_df=md, root_base=...) 并返回 {arm["name"]: 建库结果}；verbose 形参在该符号源码段内未参与如何分支。
 def cmd_build(max_df=None, verbose=True):
     corpus, _ = cmd_prepare(verbose=False)
     md = max_df if max_df is not None else max_df_auto(len(corpus))
@@ -296,6 +305,7 @@ GATE_RE = re.compile(r"拒答率：([\d.]+)%")
 LINE_RE = re.compile(r"拒答线（正例 hit@1 题 Top-1 分 p10）：([\d.]+)")
 
 
+# 生效条件：RUST_BIN 经 os.path.exists 为假时抛 SystemExit；否则以 argv 列表 [RUST_BIN, "--dataset", "lc", "--tag", name, "--lib", lib, "--qfile", qfile]（extra 为真值时追加其元素）执行 subprocess.run，返回码非 0 或 stdout 未匹配 ROW_RE 时抛 SystemExit，成功时返回 (got, neg, line)，其中 GATE_RE/LINE_RE 未命中时对应值为 None。
 def run_one(name, lib, qfile, extra=None):
     """调用 Rust 评测器跑一臂（--dataset lc 的组映射 + 显式 lib/qfile）。
 
@@ -326,6 +336,7 @@ def run_one(name, lib, qfile, extra=None):
         (float(line.group(1)) if line else None)
 
 
+# 生效条件：对 rows 中每个 (label, got, note) 按 GROUPS 顺序打印 got[g] 的 hit@1/MRR（got 缺任一 GROUPS 键会 KeyError），并对 POS_GROUPS 组按样本数 n 加权算正例 hit@1/MRR；baseline 非 None 且某行 label 等于 baseline 时该行值记为参照，其后 label 不等于 baseline 的行附加 Δpp，无返回值。
 def print_table(title, rows, baseline=None):
     """rows: [(label, got, note)]；baseline = 参照行 label（算 Δ）。"""
     print(f"\n== {title} ==")
@@ -355,6 +366,7 @@ def print_table(title, rows, baseline=None):
               + f"{ov_h1 * 100:>10.1f}%{ov_mrr:>10.3f}{delta}{suffix}")
 
 
+# 生效条件：seeds 等于 "sorted" 时给每个 run_one 追加 ["--graph-seeds", "sorted"]，seeds 为其它值（含 None）时不追加；先 cmd_build(max_df=max_df) 取各臂库，再对 bz.ARMS 逐臂 run_one，neg 非 None 时把拒答率写入 note，返回 rows 并以 bz.ARMS[0]["name"] 为 baseline 打印主表。
 def cmd_run(max_df=None, seeds=None):
     """消融主表（5 组；正例 hit@1/MRR = precise+temporal+interference）。"""
     roots = cmd_build(max_df=max_df)
@@ -373,6 +385,7 @@ def cmd_run(max_df=None, seeds=None):
     return rows
 
 
+# 生效条件：cmd_build(max_df=max_df) 后取 bz.ARMS[-1]["name"] 对应的库，对同一库分别以索引序（lczh_a4_index，无额外参数）与 --graph-seeds sorted（lczh_a4_sorted）各跑一次 run_one，返回这两行结果并以 baseline="a4/index" 打印对照表。
 def cmd_seed(max_df=None):
     """对照：同一个 a4 库，只切换 graph 路种子口径（隔离种子缺陷与边质量）。"""
     roots = cmd_build(max_df=max_df)
@@ -389,6 +402,7 @@ def cmd_seed(max_df=None):
     return rows
 
 
+# 生效条件：kind 等于 "turn" 时从 RAW_TURNS 读取并按 id/speaker/date/text 打印 rows[start:end]（序号自 start+1 起，text 截到 width）；kind 为其它任何值时改从 RAW_QUESTIONS 按 qid/qtype/question 打印同一区间，无返回值。
 def cmd_show(kind, start, end, width=240):
     """打印 [start, end) 区间的待标注项（分批产出时读原文用）。
 
@@ -403,6 +417,7 @@ def cmd_show(kind, start, end, width=240):
             print(f"{i}\t{r['qid']}\t{r['qtype']}\t{r['question'][:width]}")
 
 
+# 生效条件：len(argv) > 1 时 cmd 取 argv[1]、否则 cmd 为 "status"；遍历 argv 时遇 "--max-df" 取 argv[i+1] 转 int 为 max_df、遇 "--seeds" 取 argv[i+1] 为 seeds；cmd 为 "show" 时调 cmd_show(argv[2], int(argv[3]), int(argv[4]))，为 "dump"/"status"/"prepare" 时分别无参转调同名函数，为 "build"/"seed" 时传 max_df=max_df，为 "run" 时传 max_df=max_df 与 seeds=seeds，其余 cmd 值抛 SystemExit("未知子命令")。
 def main(argv):
     cmd = argv[1] if len(argv) > 1 else "status"
     max_df = None
@@ -433,4 +448,4 @@ def main(argv):
 
 
 if __name__ == "__main__":
-    main(sys.argv)
+    main(sys.argv)

package/md_cg/bench_locomo_zh_public.py

@@ -55,6 +55,7 @@ CONFIGS = (
 REFERENCE = {"lexical": 0.936, "lexical,fuzzy": 0.976}
 
 
+# 生效条件：c 含 zh_fields（identity、time、summary、terms、condition）与 text 时，返回按身份/时间/摘要/词/条件/原始陈述拼接的正文。
 def body_of(c):
     """正文：与 bench_axis_domain.body_of / bench_zh_mad 的 a0 臂**逐字一致**。
 
@@ -74,6 +75,7 @@ def body_of(c):
     ])
 
 
+# 生效条件：传入 corpus 时，若 rebuild 为真且 ROOT 是目录则先删除 ROOT；随后以 MdCGOS(ROOT, autoflush=500) 打开，若已有节点数 >= len(corpus)（corpus 为空列表时该式恒真）则直接返回 cg，否则逐条 cg.add(c["id"], body_of(c), layer="knowledge", eval_src="public:locomo-zh-500", verification_basis="data") 并 cg.flush() 后返回 cg；
 def build_pool(corpus, rebuild=False):
     """把 567 条灌成灵枢记忆库（layer=knowledge，无 tags）。
 
@@ -99,6 +101,7 @@ def build_pool(corpus, rebuild=False):
     return cg
 
 
+# 生效条件：无参数；仅当 CORPUS567 与 QUESTIONS500 的 os.path.exists 均为真时才继续执行，否则立即 raise SystemExit；
 def main():
     if not os.path.exists(CORPUS567) or not os.path.exists(QUESTIONS500):
         raise SystemExit(
@@ -142,4 +145,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_longmem.py

@@ -35,6 +35,7 @@ GROUPS = {
 POS_GROUPS = ("precise", "temporal", "interference")
 
 
+# 生效条件：命令行参数可被解析、GROUPS 中每组题型可按 --n 抽样时，按 --calibrated 选择 ROOT_LM_CAL 或 legacy 库评估并打印，无返回值。
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--n", type=int, default=0, help="每组抽样上限（0=全量）")
@@ -109,4 +110,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()