@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/bench_role_views.py

@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+"""角色化读取视图四臂对照 bench（第四阶段计划批次 D，H5 验收）。
+
+臂：
+  A0 基线     view=None + include_work=True（无差别全量读取：
+              不看角色、含工作回执——真无差别口径）
+  A1 main     主代理（结论与修正历史）
+  A2 verifier 验证端（判据面与环境陷阱）
+  A3 receipt  回执审计（命令与预期输出）
+
+指标（复用 budget_tokens 装包口径）：
+  tokens  = recall(budget_tokens=BIG) 的 tokens_used——同等读取意图下
+            实际装入内容的消耗；budget 给足以免截断干扰四臂横比；
+  hit@k   = gold 在 pack 内位置（k=1/5/10）+ MRR。
+
+跑法：
+  对齐跑  Q_role × view=role 对比 Q_role × 基线——H5 主判据
+          （各对齐臂 token 下降 且 命中率不降）；
+  隔离跑  错配组合（如 Q_receipt × main 臂）gold 期望不可见——
+          view 过滤真实生效的硬边界实证。
+
+语料：确定性构造（固定词面、无随机、无外部数据依赖），临时库自建自清理。
+退出码：0 = H5 通过；1 = 权衡（如实报告，禁止为凑指标调规则表后不复跑）。
+
+运行：python -m md_cg.bench_role_views
+"""
+
+import shutil
+import sys
+import tempfile
+
+from .mdcos import MdCGSecure
+from .security import Principal
+
+BIG_BUDGET = 100000   # 给足预算：四臂横比看内容消耗差异，不受截断干扰
+# 候选集由词面命中决定（检索器语义，非全池排序——探针实证），k 只是宽松
+# 上限：给足以免截断干扰四臂横比；命中率报 hit@1/5/10 + MRR（窗口内位置）。
+TOP_K = 32
+
+# ---------------- 语料（确定性；(nid, layer, content_kind, role, content)） ----------------
+_CORPUS = [
+    # main 域：结论与修正历史（knowledge + text/work_done，无 role）
+    ("bm1", "knowledge", "text", None,
+     "发布回滚结论：主支合并验证完成，回滚脚本已归档备查"),
+    ("bm2", "knowledge", "work_done", None,
+     "编译链修复工作完成：名实校验五处缺陷全部清零"),
+    ("bm3", "knowledge", "text", None,
+     "缓存刷新结论：快照增量重放语义已锁定不变"),
+    ("bm4", "knowledge", "work_done", None,
+     "索引迁移完成：三处白名单补齐内容类型字段"),
+    ("bm5", "knowledge", "text", None,
+     "检索对齐结论：四路融合排序与基线逐位一致"),
+    # verifier 域：判据面与环境陷阱（ccg_marks 或 contextual 层 text）
+    ("bv1", "knowledge", "ccg_marks", None,
+     "环境陷阱判据：GBK 解码异常须显式声明 UTF-8 标志"),
+    ("bv2", "knowledge", "ccg_marks", None,
+     "静默失败判据：多行内联命令退出码不可信，须脚本文件驱动"),
+    ("bv3", "contextual", "text", None,
+     "情境上下文实录：命令链尾部被引号换行吞没"),
+    ("bv4", "contextual", "ccg_marks", None,
+     "情境判据：提交显示成功但推送静默未执行的取证要点"),
+    ("bv5", "contextual", "text", None,
+     "上下文补充：重建成果曾被陈旧常驻进程覆盖回滚"),
+    # receipt 域：命令与预期输出（code + WORK_ROLES）
+    ("br1", "knowledge", "code", "command",
+     "推送命令：git push origin main，预期输出复核通过"),
+    ("br2", "knowledge", "code", "tool-output",
+     "状态命令输出：ahead 2 尚未推送，工作区存在改动"),
+    ("br3", "knowledge", "code", "edit",
+     "补丁片段：--root 参数移动到子命令之后生效"),
+    ("br4", "knowledge", "code", "command",
+     "导入命令：python migrate_receipts 脚本文件驱动执行"),
+    ("br5", "knowledge", "code", "tool-output",
+     "测试命令输出：53 ok 0 fail 全绿通过"),
+    # 干扰：无差读取臂的背景噪声（视图臂应剔除或降位）
+    ("bd1", "knowledge", "text", None, "会议纪要：季度规划讨论了若干方向性议题"),
+    ("bd2", "knowledge", "text", None, "读书笔记：系统一致性与反馈回路的一般性介绍"),
+    ("bd3", "contextual", "text", None, "闲聊上下文：天气与周末安排的对话残留"),
+    ("bd4", "knowledge", "code", None, "示例代码片段：打印问候语的演示脚本"),
+    ("bd5", "knowledge", "work_done", None, "例行工作完成记录：周报已按时提交"),
+    ("bd6", "knowledge", "ccg_marks", None, "通用判据示例：正常路径与边界条件各自成立"),
+    # 跨域诱饵：词面横跨多域——基线（无差别）会命中，视图臂应剔除，
+    # 打破「各域词面天然隔离」的失真（首跑实证：verifier 臂 -0.0% 的根因）。
+    ("dk1", "knowledge", "work_done", None,
+     "判据复盘工作完成：陷阱用例与命令输出的归档记录"),
+    ("dk2", "contextual", "text", None,
+     "结论情境补充：命令归档上下文中的判据留痕"),
+    ("dk3", "knowledge", "code", "command",
+     "对照命令：结论与判据的输出对照脚本"),
+]
+
+# ---------------- 三角色查询集（每题唯一 gold；词面与 gold 共享中文 2-gram） ----------------
+_QUERY_SETS = {
+    "main": [
+        ("回滚 结论 归档", "bm1"),
+        ("编译链 修复 完成", "bm2"),
+        ("缓存 刷新 结论", "bm3"),
+        ("索引 迁移 完成", "bm4"),
+        ("检索 对齐 一致", "bm5"),
+    ],
+    "verifier": [
+        ("陷阱 判据 编码", "bv1"),
+        ("判据 静默 失败", "bv2"),
+        ("上下文 吞没 陷阱", "bv3"),
+        ("情境 判据 取证", "bv4"),
+        ("上下文 覆盖 成果", "bv5"),
+    ],
+    "receipt": [
+        ("推送 命令 输出", "br1"),
+        ("状态 输出 推送", "br2"),
+        ("补丁 参数 子命令", "br3"),
+        ("导入 命令 脚本", "br4"),
+        ("测试 输出 全绿", "br5"),
+    ],
+}
+
+# 对齐跑：查询集 → 自己的视图臂
+_ALIGNED = {"main": "main", "verifier": "verifier", "receipt": "receipt"}
+# 隔离跑（硬边界）：这些组合 gold 期望不可见
+#   receipt 域 gold 带 WORK_ROLES → main/verifier 臂 include_work=False 一票否决；
+#   main/verifier 域 gold 无 role → receipt 白名单不收。
+_ISOLATED = [("receipt", "main"), ("receipt", "verifier"),
+             ("main", "receipt"), ("verifier", "receipt")]
+
+
+def _mk_cg():
+    tmp = tempfile.mkdtemp(prefix="mdcg_bench_rv_")
+    p = Principal(tenant="default", actor="bench_role_views", role="designer",
+                  can_write=True, can_admin=True)
+    cg = MdCGSecure(tmp, principal=p)
+    for nid, layer, ck, role, content in _CORPUS:
+        kw = {"layer": layer, "content_kind": ck}
+        if role is not None:
+            kw["role"] = role
+        cg.add(nid, content, **kw)
+    return cg, tmp
+
+
+def _run_arm(cg, query, view, include_work=False):
+    """单题单臂：返回 (pack 内 id 序列, tokens_used)。
+
+    基线臂传 include_work=True——「无差别全量读取」的忠实口径：
+    若基线沿用默认 include_work=False，receipt 域（WORK_ROLES）在基线
+    完全不可见（首跑实证 hit 0%），对照便不公平；视图臂保持默认
+    include_work=False——view 非空时 role 维度由视图规则接管（receipt
+    是默认剔除的补集，这正是视图存在的理由之一）。
+    """
+    rec = cg.recall(query, budget_tokens=BIG_BUDGET, k=TOP_K,
+                    view=view, include_work=include_work)
+    return ([p["id"] for p in rec.get("pack") or []],
+            int(rec.get("tokens_used") or 0))
+
+
+def _metrics(hits_by_k, token_list):
+    """hits_by_k: 每题 gold 在 pack 的 1-based 位置（不可见=0）。"""
+    n = len(token_list)
+    mrr = sum(1.0 / h for h in hits_by_k if h > 0) / max(n, 1)
+    return {"hit@1": sum(1 for h in hits_by_k if 1 <= h <= 1) / n,
+            "hit@5": sum(1 for h in hits_by_k if 1 <= h <= 5) / n,
+            "hit@10": sum(1 for h in hits_by_k if 1 <= h <= 10) / n,
+            "mrr": mrr,
+            "tokens": sum(token_list) / n}
+
+
+def _fmt(m):
+    return ("hit@1 %.0f%%  hit@5 %.0f%%  hit@10 %.0f%%  MRR %.3f  tokens %.0f"
+            % (m["hit@1"] * 100, m["hit@5"] * 100, m["hit@10"] * 100,
+               m["mrr"], m["tokens"]))
+
+
+def main():
+    cg, tmp = _mk_cg()
+    ok = True
+    try:
+        print("==== bench_role_views：角色化读取视图四臂对照（H5） ====")
+        print("语料 %d 节点（main 域 5 / verifier 域 5 / receipt 域 5 / "
+              "干扰 6 / 跨域诱饵 3），查询 3 类 × 5 题，k=%d，budget=%d"
+              % (len(_CORPUS), TOP_K, BIG_BUDGET))
+
+        # ---------- 对齐跑（H5 主判据） ----------
+        print("\n---- 对齐跑：Q_role × view=role vs 基线（含诱饵词面跨域命中） ----")
+        token_pass, hit_pass = True, True
+        for role, view in _ALIGNED.items():
+            qs = _QUERY_SETS[role]
+            pos0, tok0 = [], []
+            posv, tokv = [], []
+            for q, gold in qs:
+                ids0, t0 = _run_arm(cg, q, None, include_work=True)
+                idsv, tv = _run_arm(cg, q, view)
+                pos0.append(ids0.index(gold) + 1 if gold in ids0 else 0)
+                posv.append(idsv.index(gold) + 1 if gold in idsv else 0)
+                tok0.append(t0)
+                tokv.append(tv)
+            m0, mv = _metrics(pos0, tok0), _metrics(posv, tokv)
+            drop = (m0["tokens"] - mv["tokens"]) / m0["tokens"] * 100.0
+            t_ok = mv["tokens"] < m0["tokens"]
+            h_ok = (mv["hit@1"] >= m0["hit@1"] and mv["hit@5"] >= m0["hit@5"]
+                    and mv["hit@10"] >= m0["hit@10"] and mv["mrr"] >= m0["mrr"])
+            token_pass &= t_ok
+            hit_pass &= h_ok
+            print("\n[%s] view=%s（token %s）" %
+                  (role, view, "下降" if t_ok else "未下降"))
+            print("  基线    %s" % _fmt(m0))
+            print("  %s  %s   (%+.1f%% tokens)" %
+                  (view.ljust(9), _fmt(mv), -drop))
+
+        # ---------- 隔离跑（硬边界实证） ----------
+        print("\n---- 隔离跑：错配组合 gold 期望不可见 ----")
+        iso_pass = True
+        for role, view in _ISOLATED:
+            missed = 0
+            for q, gold in _QUERY_SETS[role]:
+                ids, _t = _run_arm(cg, q, view)
+                if gold not in ids:
+                    missed += 1
+            this_ok = missed == len(_QUERY_SETS[role])
+            iso_pass &= this_ok
+            print("  Q_%s × view=%-8s gold 不可见 %d/%d %s"
+                  % (role, view, missed, len(_QUERY_SETS[role]),
+                     "" if this_ok else "  <-- 泄漏"))
+
+        # ---------- H5 判定 ----------
+        print("\n==== H5 判定 ====")
+        print("  各对齐臂 token 下降      : %s" % ("PASS" if token_pass else "FAIL"))
+        print("  各对齐臂 命中率不降      : %s" % ("PASS" if hit_pass else "FAIL"))
+        print("  隔离跑 无泄漏（辅助证据）: %s" % ("PASS" if iso_pass else "FAIL"))
+        if not (token_pass and hit_pass):
+            print("\n权衡（如实报告，不作单向通过声明）：")
+            print("  存在「token 未下降或命中率下降」的对齐臂——")
+            print("  上表数字为准；禁止为凑指标调规则表后不复跑。")
+        ok = token_pass and hit_pass
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/bench_task_ab.py

@@ -93,6 +93,7 @@ CASES = [
 ]
 
 
+# 生效条件：给定 text，当 expand_query_terms_weighted(text) 为真值字典时返回其中键不以 `__` 开头的项（键转 str、值转 float），并先弹出 `__source__`；当该调用返回假值（None/空/其他假值）时返回空字典 {}；
 def _terms(text):
     tw = expand_query_terms_weighted(text) or {}
     tw.pop("__source__", None)
@@ -100,6 +101,7 @@ def _terms(text):
             if not str(k).startswith("__")}
 
 
+# 生效条件：candidates 非空且 error 可被 _terms 处理时，按 _weighted_coverage 返回覆盖得分最高的候选，字面平局时取候选顺序最前者。
 def _pick_lexical(error, candidates):
     """无记忆臂的确定性策略：按字面覆盖选 top-1（字面平局时按候选顺序）。"""
     tw = _terms(error)
@@ -111,6 +113,7 @@ def _pick_lexical(error, candidates):
     return best
 
 
+# 生效条件：给定 error、candidates、fix、max_turns，在 pool 非空且 turns<max_turns 时每轮把 _pick_lexical(error, pool) 选中的 last 记入 touched：若 last==fix 立即返回 {'success': True, 'turns': turns, 'pick': last, 'touched': touched}，否则从 pool 移除 last 继续；候选耗尽或 max_turns 为 0/负值时退出，返回 {'success': False, 'turns': turns, 'pick': last, 'touched': touched}（未进入循环时 success=False、turns=0、pick=None、touched=[]）；
 def _trial(error, candidates, fix, max_turns):
     """无记忆臂：选错就排除该动作、下一轮重选（模拟试错）。"""
     pool = list(candidates)
@@ -128,6 +131,7 @@ def _trial(error, candidates, fix, max_turns):
             "touched": touched}
 
 
+# 生效条件：case["fix"] 为真且其字符串出现在 cg.recall(query, budget_tokens=budget, k=20) 返回 pack 各项 content 拼接成的 text 中时返回 hit=True、turns=1、touched=[]；否则以 case["error"]、candidates、case["fix"]、max_turns 调 _trial 并回填 hit=False、turns=1+fb["turns"]、tokens=int(tokens_used or 0)。
 def _decide_mem(cg, query, case, candidates, max_turns, budget):
     """有记忆臂：先召回，命中修复知识则一次到位；否则回退到试错。"""
     res = cg.recall(query, budget_tokens=budget, k=20)
@@ -141,10 +145,12 @@ def _decide_mem(cg, query, case, candidates, max_turns, budget):
     return fb
 
 
+# 生效条件：传入 x 时，返回 f"{100.0 * x:.1f}%" 的字符串（即 x 乘以 100 后保留一位小数的百分比表示）；
 def _pct(x):
     return f"{100.0 * x:.1f}%"
 
 
+# 生效条件：rows 为非空序列（n>0）且每项可解包为 (c, rn, rm)、c 含 trap/id/error、rn/rm 含 success/turns/touched（tokens 经 .get('tokens') or 0 把缺键或假值计 0，hit 经 .get 缺键或假值不计数），mined 含 pairs/knowledge_ids/rejected_ids 键，max_turns 为数值时，打印两臂指标与逐例清单，并按首次正确率与重复犯错率的大小关系（提升/相等/其余）输出三分支结论；
 def _report(rows, mined, max_turns):
     n = len(rows)
     print("\n" + "=" * 74)
@@ -204,6 +210,7 @@ def _report(rows, mined, max_turns):
     print()
 
 
+# 生效条件：调用 main(argv) 时由 argparse 解析 argv（argv 为 None 则取 sys.argv[1:]），--cases 为 0 用全部 CASES、非 0（含负值）用 CASES[:a.cases]，--max-turns 默认 2，--budget 默认 2000；随后在临时目录创建 none_arm/mem_arm，先用 mem_arm.mine_fix_pairs 从 cases 的 error/fix 写入修复对作为记忆臂命中前置，再逐例以 _trial 与 _decide_mem 生成 rows 并 _report，最终返回 0；
 def main(argv=None):
     ap = argparse.ArgumentParser(description="任务级 A/B：无记忆 vs 有记忆")
     ap.add_argument("--cases", type=int, default=0, help="只用前 N 个用例（0=全部）")
@@ -234,4 +241,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/bench_task_ab_llm.py

@@ -134,6 +134,7 @@ for _c in CASES:
 
 
 # ---- LLM 客户端（OpenAI 兼容，零第三方依赖）-------------------------------
+# 生效条件：给定 model/base/key/messages 即构造 JSON POST 到 base.rstrip("/")+"/chat/completions"，返回 (choices[0].message 的 content 或缺失/假值回落 ""、data.get("usage") 或缺失/假值回落 {}、耗时 dt)，timeout/max_tokens/temperature 仅作为请求参数传入。
 def llm_chat(model, base, key, messages, timeout=180, max_tokens=200,
              temperature=0.0):
     payload = json.dumps({
@@ -154,6 +155,7 @@ def llm_chat(model, base, key, messages, timeout=180, max_tokens=200,
     return content, (data.get("usage") or {}), dt
 
 
+# 生效条件：raw（None/空串视为 ""）中首个 "{" 至末个 "}" 的子串能解析出 pick，或全文匹配到单个数字 1-9，且该编号落在 1..n 内时返回该编号（pick 为数字字符串先转 int），否则返回 None。
 def _parse_pick(raw, n):
     """从模型输出里抠出候选编号（1..n）；解析失败返回 None。"""
     s = raw or ""
@@ -174,6 +176,7 @@ def _parse_pick(raw, n):
     return None
 
 
+# 生效条件：以 case["id"] 播种打乱 [(fix,case["fix"]),(trap,case["trap"]),(decoy,case["decoy"])] 后取三种循环排列，n<=3 返回其前 n 个，n>3 返回 6 种全排列的前 n 个。
 def _orders(case, n):
     """候选顺序。默认取 3 种循环排列（每个候选在 3 个位置各出现一次，天然去位置偏差）；
     n>3 时退回全 6 种排列。基准顺序由 case id 播种打乱，避免跨用例雷同。"""
@@ -186,6 +189,7 @@ def _orders(case, n):
     return list(itertools.permutations(base))[:n]
 
 
+# 生效条件：case 含 task 且 opts 为 (kind, txt) 序列时，返回含场景、编号候选与选择指令的提示文本，memory 非空时在开头插入记忆段。
 def _user_prompt(case, opts, memory=None):
     lines = []
     if memory:
@@ -203,12 +207,14 @@ def _user_prompt(case, opts, memory=None):
     return "\n".join(lines)
 
 
+# 生效条件：cg 存在时把模块常量 CASES 逐条以 c["task"] 为 error、c["lesson"] 为 fix 组成列表传给 cg.mine_fix_pairs 并原样返回其结果。
 def _build_memory(cg):
     """Phase A：把 5 条「项目规范」写进记忆（真实 mine_fix_pairs）。"""
     return cg.mine_fix_pairs(
         [{"error": c["task"], "fix": c["lesson"]} for c in CASES])
 
 
+# 生效条件：以 "本项目规范："+case["query"] 且 budget_tokens=budget、k=10 调用 cg.recall，取 pack 各项 content（缺失/假值为 ""）拼接，返回其前 1500 字符与 case["marker"] 是否出现在未截断拼接文本中。
 def _recall_memory(cg, case, budget):
     res = cg.recall("本项目规范：" + case["query"],
                     budget_tokens=budget, k=10)
@@ -216,6 +222,7 @@ def _recall_memory(cg, case, budget):
     return text[:1500], (case["marker"] in text)
 
 
+# 生效条件：在 cfg["max_turns"] 轮内以 cfg["model"]/cfg["base"]/cfg["key"] 调 llm_chat（timeout=cfg["timeout"]、max_tokens=cfg["max_tokens"]）并累加 usage["total_tokens"]，pick 等于 correct_pos 或为 None 时中止（否则在仍有剩余轮次时追加 assistant/user 消息重选），最终 pick 为 None 则 kind="invalid"、否则 kind=opts[pick-1][0]。
 def _run_one(cfg, case, opts, correct_pos, memory):
     messages = [{"role": "system", "content": SYS_PROMPT},
                 {"role": "user", "content": _user_prompt(case, opts, memory)}]
@@ -239,6 +246,7 @@ def _run_one(cfg, case, opts, correct_pos, memory):
             "turns": turns, "tokens": tokens, "latency": dt}
 
 
+# 生效条件：cfg["use_mem"] 为真时对每个 case 以 cfg["budget"] 先串行召回写入 mems、否则存 (None, False)，再对每 case × _orders(case, n_perms) 的排列 × ("none","mem") 两臂建任务交 ThreadPoolExecutor(max_workers=workers) 执行，返回按 arm 分组的 {"none": [...], "mem": [...]} 行表。
 def _run_model(label, cfg, cases, cg, n_perms, workers):
     # 记忆召回先串行算好（MdCGOS 非线程安全），LLM 调用再并发。
     mems = {}
@@ -254,6 +262,7 @@ def _run_model(label, cfg, cases, cg, n_perms, workers):
             for arm in ("none", "mem"):
                 tasks.append((case, oi, opts, correct_pos, arm))
 
+# 生效条件：t 解包为 (case, oi, opts, correct_pos, arm)，arm=="mem" 时 memory/hit 取闭包 mems[case["id"]]、否则为 (None, False)，_run_one 抛异常时以 kind="error"、pick=None 的占位行替代，随后补上 case/arm/hit 并打印该行后返回 r。
     def work(t):
         case, oi, opts, correct_pos, arm = t
         memory, hit = mems[case["id"]] if arm == "mem" else (None, False)
@@ -276,10 +285,12 @@ def _run_model(label, cfg, cases, cg, n_perms, workers):
     return rows
 
 
+# 生效条件：n 为真值时返回 f"{100.0*x/n:.1f}%"，n 为假值（0）时返回 "-"。
 def _pct(x, n):
     return f"{100.0 * x / n:.1f}%" if n else "-"
 
 
+# 生效条件：以 rows["none"] 的行数 n 汇总 none/mem 两臂的 correct、kind=="trap"、kind∈("invalid","error")、tokens、latency、hit 与 pick∈(1,2,3) 的分布并打印（n_perms 仅用于表头文字），返回该 agg 字典。
 def _report(label, rows, n_perms):
     n = len(rows["none"])
     print(f"\n{'-' * 78}")
@@ -333,6 +344,7 @@ def _report(label, rows, n_perms):
     return agg
 
 
+# 生效条件：argv 为 None 时改读 sys.argv；若 --key 与 DEEPSEEK_API_KEY 均为空则返回 2，否则按 --only/--cases 从 CASES 取用例跑完双臂后返回 0。
 def main(argv=None):
     ap = argparse.ArgumentParser(
         description="先验陷阱 A/B：无记忆 vs 有记忆（真实 LLM）")
@@ -394,4 +406,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/bench_unified_en.py

@@ -48,6 +48,7 @@ ARM_ROOT = os.path.join(HERE, "_md_cg_eval_unified_en")  # gitignore 已覆盖
 K = 10
 
 
+# 生效条件：传入 root 使 os.path.isdir(root) 为真时先执行 shutil.rmtree(root, ignore_errors=True)、否则跳过，随后遍历 corpus 每项 c，semantic_of 不为 None 且 semantic_of(c) 返回真值时以 semantic=sem 传入，正文按 zh_body 真值取 c.get("zh")、假值取 b6.ingest_text_en(c)，并以 c["id"] 为键 add 后 flush 并 install_read_cache，最终返回 cg；
 def build(root, corpus, semantic_of=None, zh_body=False):
     """单库构建：正文形态与 fm.semantic 摘要层是仅有的两个自由度。"""
     if os.path.isdir(root):
@@ -67,6 +68,7 @@ def build(root, corpus, semantic_of=None, zh_body=False):
     return cg
 
 
+# 生效条件：cg 可对 questions 做 evaluate_group 时，按 semantic 设置或清除 MDCG_SEMANTIC，返回词法路 rows 及其按 qtype 汇总的 by_type。
 def run_arm(cg, questions, tag, semantic=False):
     if semantic:
         os.environ["MDCG_SEMANTIC"] = "1"
@@ -82,6 +84,7 @@ def run_arm(cg, questions, tag, semantic=False):
     return rows, by_type
 
 
+# 生效条件：questions 为真时逐 q 取 q["question"]（缺该键抛 KeyError）经 query_atoms，仅当 atom 含任一满足 "A" <= ch <= "z" 的字符才计入 n_keep，n_tok 为 0 时 keep_ratio 为 0.0、否则 round(n_keep/n_tok,4)，questions 为空时 q_with_keep_ratio 为 0.0、否则 round(n_q_with_keep/len(questions),4)，返回含 n_questions/n_atoms/n_en_keep 的 dict；
 def oov_stats(questions):
     """题级 en→zh 归一覆盖统计：英文保留词占比 = 词表覆盖瓶颈的直接量化。"""
     n_tok = n_keep = n_q_with_keep = 0
@@ -100,6 +103,7 @@ def oov_stats(questions):
             if questions else 0.0}
 
 
+# 生效条件：不适用（无必需形参与模块级常量）
 def main():
     t0 = time.time()
     rows500 = list(ec.iter_jsonl(b6.QUESTIONS500))
@@ -115,6 +119,7 @@ def main():
     ec.unlock_global_cap()
     ec.use_jaccard()
 
+# 生效条件：对 c 先取 (c.get("zh_fields") or {}).get("summary") 再 or "" 并 str().strip()，该值为空时回落为 (c.get("zh") or "") 的 str().strip()，所得 s 非空则返回 " ".join(semantic_atoms(s))、否则返回空串；
     def sem_of(c):
         s = str((c.get("zh_fields") or {}).get("summary") or "").strip()
         if not s:
@@ -197,4 +202,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_zh_mad.py

@@ -62,6 +62,7 @@ QUESTIONS20 = os.path.join(ZP, "questions20.jsonl")
 AXES = ("person", "event", "time", "identity", "place", "condition")
 
 
+# 生效条件：path 以 UTF-8 打开后逐行读取，仅 strip 后非空的行经 json.loads 产出，空白行被跳过。
 def iter_jsonl(path):
     with open(path, encoding="utf-8") as f:
         for line in f:
@@ -70,11 +71,13 @@ def iter_jsonl(path):
                 yield json.loads(line)
 
 
+# 生效条件：path 以 UTF-8 打开成功时返回 json.load(f) 的解析结果，片段内无其它分支。
 def load_json(path):
     with open(path, encoding="utf-8") as f:
         return json.load(f)
 
 
+# 生效条件：raw 经 str() 后按“；”切分，仅含“=”的段被解析，其中键为身份/时间/摘要时写对应槽位、键为条件时按“|”与“:”写入 condition、键为词时按“,”拆出非空项写入 terms，其它键或未出现的槽位保持 out 的默认空值。
 def parse_zh(raw):
     """中文层串 → 槽位 dict。
 
@@ -107,6 +110,7 @@ def parse_zh(raw):
     return out
 
 
+# 生效条件：当 MANUAL_ZH/MANUAL_Q/LM_Q/LM_H 可读取、hay 覆盖 want_ids 且 meta 含 man_q 全部 qid 时写出 CORPUS20/QUESTIONS20 并返回 (corpus, questions)，缺 turn 或 qid 分别 raise SystemExit，verbose（默认 True）为真值时额外打印统计、假值时静默。
 def prepare(verbose=True):
     """生成 corpus20.jsonl 与 questions20.jsonl（幂等覆盖）。"""
     man_zh = load_json(MANUAL_ZH)
@@ -125,6 +129,7 @@ def prepare(verbose=True):
         raise SystemExit(f"[失败] haystack 缺以下 turn：{sorted(missing)}")
 
     # corpus：按 turn id 的数值序（= 时间序），保证「承接前一条」有确定语义
+# 生效条件：tid 经 rsplit("t",1) 得到至少两段且最后一段可被 int() 解析时返回该整数，否则源码未做校验会抛错。
     def turn_no(tid):
         return int(tid.rsplit("t", 1)[1])
 
@@ -171,6 +176,7 @@ def prepare(verbose=True):
     return corpus, questions
 
 
+# 生效条件：prepare(verbose=False) 返回 corpus/questions 后，对每题以 evidence_turns[0]（空则 ""）取 ev0，命中词限于 ev0 非空且词出现在 zh_of[ev0] 中，df1 收集池内 df==1 的词、all_df 收集 df==len(corpus) 的词，verbose（默认 True）为真值时打印后返回 per_q、为假值时直接返回 per_q。
 def analyze(verbose=True):
     """诊断：查询词能否落到 gold 中文层 / 池内其他条目（决定各轴是否有可桥接的实体）。
 
@@ -254,6 +260,7 @@ EN_NAME_RE = re.compile(r"\b[A-Z][a-z]{2,}(?:[ ][A-Z][a-z]{2,})*\b")
 DATE_RE = re.compile(r"(\d{4})[/-](\d{1,2})[/-](\d{1,2})")
 
 
+# 生效条件：DATE_RE.search(str(raw or "")) 有匹配时返回零填充的 YYYY-MM-DD，无匹配（含 raw 为假值回落成 ""）时返回 ""。
 def norm_time(raw):
     """'2023/05/24 04:49' → '2023-05-24'（跨条目统一格式，使日期查询可命中）。"""
     m = DATE_RE.search(str(raw or ""))
@@ -263,6 +270,7 @@ def norm_time(raw):
     return f"{int(y):04d}-{int(mo):02d}-{int(d):02d}"
 
 
+# 生效条件：对 str(text or "") 用 EN_NAME_RE 扫描，匹配串按空白切分后任一部分命中 EN_STOP 即跳过，其余项按首次出现顺序去重加入 out 并返回；text 为假值时扫描空串返回 []。
 def en_names(text):
     """英文原文中的专名候选（跨语言桥：中文查询里的英文专名可经 entity 路命中）。"""
     out, seen = [], set()
@@ -276,6 +284,7 @@ def en_names(text):
     return out
 
 
+# 生效条件：遍历 corpus，对每条记录的 zh_fields["terms"] 去重后逐词判断，词非空且不在 STOP_ZH 时使 df[词] 计数加一，返回 df。
 def build_tables(corpus):
     """全库统计：# 词项 df（**只读语料**，与查询集无关）。"""
     df = {}
@@ -286,6 +295,7 @@ def build_tables(corpus):
     return df
 
 
+# 生效条件：c 含 zh_fields（terms/condition/time/identity）且 df 为词到频次的映射时，返回 person/event/time/identity/place/condition 六轴取值字典。
 def axis_values(c, df):
     """一条 turn 的六个关系轴取值（用户裁决：条件链 + 人物/事件/时间/身份/地点）。"""
     f = c["zh_fields"]
@@ -321,6 +331,7 @@ INTENT_CLASSES = (
 )
 
 
+# 生效条件：按 INTENT_CLASSES 顺序检查 c["zh_fields"]["summary"]，首个命中类目的首个包含于摘要的动词返回 (cls, v)，全不命中返回 ('', '')。
 def intent_of(c):
     """意图抽象：摘要 → (规范类目, 命中的动词原形)。
 
@@ -338,6 +349,7 @@ def intent_of(c):
     return "", ""
 
 
+# 生效条件：把 c["zh_fields"]["terms"] 与 en_names(c["text"]) 逐项 strip 后跳过空串、STOP_ZH（原形或小写）及已见项去重入 out，再用 norm_time(条件.get("时间窗口") or c 的 time) 得到非空且未出现的时窗串追加；df 形参在该片段内未参与条件判断。
 def normalize_terms(c, df):
     """实体规范化：去停用 + 去重 + 附时间规范式 + 附英文专名（跨语言对齐）。"""
     f = c["zh_fields"]
@@ -354,6 +366,7 @@ def normalize_terms(c, df):
     return out
 
 
+# 生效条件：遍历 corpus 并以 root=os.path.join(HERE, root_base or f"_md_cg_eval_zhprobe_{arm['name']}")（root_base 为 None/空串时回落）建库，graph 分支仅当 arm.get("graph") 为真且某轴取值的同值 id 数落在 [2, max_df]（默认 5）时为这些 id 两两建有向边，coref 仅当 arm.get("coref") 为真、本条 own 为空（own 只在 arm.get("norm") 为真时由 normalize_terms 生成，否则恒为 []）且 prev_own 非空时承接前一条自身 canonical，intent 分支仅当 arm.get("intent") 为真且 intent_of 返回 cls 非空时写意图行并把意图词与长度>=2 的动词加入 tags，verbose（默认 True）为真值时打印臂统计、root 已是目录时先整树删除再建 MdCGOS。
 def build_arm(corpus, arm, max_df=5, root_base=None, verbose=True):
     """按消融臂建库。每臂一个独立 root，互不污染。
 
@@ -453,6 +466,7 @@ ARMS = [
 ]
 
 
+# 生效条件：先执行 prepare(verbose=False) 取得 corpus，再对 ARMS 每臂以 max_df=max_df（默认 5，原样下传不做假值回落）调用 build_arm 并汇总为 roots 返回。
 def build_all(max_df=5):
     corpus, _ = prepare(verbose=False)
     print(f"== 建库（消融 {len(ARMS)} 臂，max_df={max_df}）==")
@@ -469,6 +483,7 @@ ROW_RE = re.compile(
 GROUPS = ["precise", "temporal", "interference", "reference"]
 
 
+# 生效条件：os.path.exists(RUST_BIN) 为真时以 argv=[RUST_BIN,"--dataset","mad","--tag",name,"--lib",lib]（extra 为真值时追加 list(extra)）执行 subprocess，返回码非 0 或 ROW_RE 在 stdout 未匹配到任何组时 raise SystemExit，否则返回 {组:(n,hit@1,hit@5,MRR)}。
 def run_one(name, lib, extra=None):
     """调用 **Rust 检索器** 跑一臂，返回 {组: (n, hit@1, hit@5, MRR)}。
 
@@ -496,6 +511,7 @@ def run_one(name, lib, extra=None):
     return got
 
 
+# 生效条件：先打印 title 与表头，再遍历 rows 的 (label, got, note)，对 GROUPS 每组用 got[g] 取 (n,h1,h5,mrr) 并累计总体 hit@1/MRR，仅当 baseline 不为 None 且 label==baseline 时记 ref，仅当 ref 已记录且 label!=baseline 时输出 Δ。
 def print_table(title, rows, baseline=None):
     """rows: [(label, got, note)]；baseline = 参照行 label（算 Δ）。"""
     print(f"\n== {title} ==")
@@ -524,6 +540,7 @@ def print_table(title, rows, baseline=None):
               + f"{ov_h1 * 100:>10.1f}%{ov_mrr:>10.3f}{delta}{suffix}")
 
 
+# 生效条件：对 ARMS 每臂以 lib=f"_md_cg_eval_zhprobe_{name}"、无 extra 调用 run_one 组成 rows，并以 ARMS[0]["name"] 为 baseline 调 print_table 后返回 rows。
 def run_ablation():
     """消融主表：逐臂调用 Rust 检索器并汇总（种子口径 = 缺省，即生产现状）。"""
     rows = []
@@ -537,6 +554,7 @@ def run_ablation():
     return rows
 
 
+# 生效条件：以最后一个臂 ARMS[-1]['name'] 对应的库路径，先无 extra 调 run_one("a4_index", lib)、再以 extra=("--graph-seeds","sorted") 调 run_one("a4_sorted", lib) 组成 rows，并以 baseline="a4/index" 调 print_table 后返回。
 def run_seed_control():
     """对照：**同一个 a4 库**（写入侧与边结构完全相同），只切换 graph 路种子口径。
 
@@ -555,6 +573,7 @@ def run_seed_control():
     return rows
 
 
+# 生效条件：cmd 取 argv[1]（len(argv)<=1 时为 "prepare"），cmd=="prepare"/"analyze"/"build"/"run"/"seed-control" 分别调用 prepare/analyze/build_all/run_ablation/run_seed_control，cmd=="all" 依次调用 prepare、analyze、build_all、run_ablation、run_seed_control，其余值 raise SystemExit。
 def main(argv):
     cmd = argv[1] if len(argv) > 1 else "prepare"
     if cmd == "prepare":
@@ -580,4 +599,4 @@ def main(argv):
 
 
 if __name__ == "__main__":
-    main(sys.argv)
+    main(sys.argv)