@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/bench_membench.py

@@ -52,11 +52,13 @@ SEG_SPLIT = re.compile(r"([，。；：、,;.!?！？\s]+)")
 
 # --------------------------------------------------------------------------- 数据
 
+# 生效条件：按 path（默认模块常量 DATA）以 utf-8 打开文件逐行 json.loads，仅保留 l.strip() 为真的行，返回解析出的记录列表。
 def load_rows(path=DATA):
     with open(path, encoding="utf-8") as f:
         return [json.loads(l) for l in f if l.strip()]
 
 
+# 生效条件：以 root（默认模块常量 ROOT）建 MdCGOS，rows 为假值（None/空容器）时回落 load_rows() 取数据，逐行用 r["id"] 与 r["text"] 调 add，仅当 r["id"] 已在构建开始时取的 cg.index["nodes"] 快照 have 中才 continue（该快照不随新增 id 更新），verbose 假值则不打印，最后 cg.flush() 并返回 cg。
 def build(root=ROOT, rows=None, verbose=True):
     """把数据集写进 md 认知图（幂等：同 id 覆盖）。"""
     rows = rows or load_rows()
@@ -81,6 +83,7 @@ def build(root=ROOT, rows=None, verbose=True):
 
 # --------------------------------------------------------------------- 查询构造
 
+# 生效条件：遍历 SYNONYM_GROUPS_WEIGHTED 每组，按权重降序找第一个出现在当前 out（初值 text，可能已被前组改写）里的词 w，若组内除 w 外还有词则用其中权重最大者 alt 执行一次 out.replace(w, alt, 1) 且 hits+1，随后 break 该组；返回 (out, hits)。
 def paraphrase(text):
     """按加权同义词组做一次同义/泛化改写，返回 (改写后, 替换次数)。
 
@@ -99,6 +102,7 @@ def paraphrase(text):
     return out, hits
 
 
+# 生效条件：text 经 SEG_SPLIT.split 后剔除空白项与分隔符本身得 parts，len(parts)<=1 时原样返回 text，否则按 rng.random() < keep_p（默认 0.5；keep_p 为 0 时全被丢弃）保留片段，若一条未留则回退 [parts[0]]，返回拼接串。
 def drop_segments(text, rng, keep_p=0.5):
     """随机丢弃约一半语义片段（模拟「记得不全」）。"""
     parts = [p for p in SEG_SPLIT.split(text)
@@ -111,6 +115,7 @@ def drop_segments(text, rng, keep_p=0.5):
     return "".join(kept)
 
 
+# 生效条件：rows 中 r.get("label")=="signal" 且 r.get("text") 为真的行入选，n 为真值且 n < len(sig) 时才用 random.Random(seed) 抽 n 条（n=0 等假值不抽样），每条产生 orig/head/drop 三条查询，仅在 paraphrase(t[:60]) 的 hits 非零时追加 para 查询，返回 qs。
 def make_queries(rows, n=250, seed=7):
     """从 signal 条目构造查询集（多模式）。"""
     sig = [r for r in rows if r.get("label") == "signal" and r.get("text")]
@@ -131,11 +136,13 @@ def make_queries(rows, n=250, seed=7):
 
 # ----------------------------------------------------------------------- 评测
 
+# 生效条件：传入 cg 后把 cg._read 换成按 entry["path"] 缓存的闭包（该 path 未命中才调用原 _read），返回该 cache 字典。
 def install_read_cache(cg):
     """评测是只读的：把节点文件读进内存，避免每次检索重复 1000 次磁盘 I/O。"""
     cache = {}
     orig = cg._read
 
+# 生效条件：entry["path"] 不在闭包 cache 中时调用 orig(entry) 存入该键，随后返回 cache[p]（同一 path 后续命中直接取缓存）。
     def _cached(entry):
         p = entry["path"]
         if p not in cache:
@@ -146,6 +153,7 @@ def install_read_cache(cg):
     return cache
 
 
+# 生效条件：对 queries 每条 item 以 cg.search_rrf(item["q"], k=k, paths=arm, judge=False, record=False, path_weights=path_weights, recall_only=recall_only, fusion=fusion) 取结果，rank 记 item["target"] 在返回 ids 中的 1 基位次（不在 ids 中记 0），逐条追加明细后返回 out。
 def run_arm(cg, queries, arm, k=10, path_weights=None, recall_only=None,
             fusion="sum"):
     """跑一臂，返回 per-query 明细。"""
@@ -167,6 +175,7 @@ def run_arm(cg, queries, arm, k=10, path_weights=None, recall_only=None,
     return out
 
 
+# 生效条件：对 queries 每条以 cg.search_rrf(item["q"], k=k, paths=(path,)) 单路取结果，rank 记 item["target"] 的 1 基位次（未命中记 0），fuzzy_hit 恒为 False、expand_source 恒为 None，返回 out。
 def run_single(cg, queries, path, k=10):
     """单路独立排序（用于诊断每路的自身质量）。"""
     out = []
@@ -181,6 +190,7 @@ def run_single(cg, queries, path, k=10):
     return out
 
 
+# 生效条件：rows 为空时返回 None；否则按 n=len(rows) 算 self@1、self@k（0<rank<=k，k 由形参给定）、mrr（仅 rank 非 0 行取 1/rank 再除 n）与标签占比（分母 sum(lab.values()) or 1，无标签时用 1），fuzzy_prov 在 hit_rows 为空时记 0.0。
 def summarize(rows, k=10):
     """汇总一个查询模式的指标。"""
     n = len(rows)
@@ -203,10 +213,12 @@ def summarize(rows, k=10):
     }
 
 
+# 生效条件：把 x 乘 100 后按 5 位宽保留一位小数加百分号返回，源码未对 x 做类型或范围校验。
 def _pct(x):
     return f"{x * 100:5.1f}%"
 
 
+# 生效条件：r4 长度为 0 时返回 {}；否则以 seed 建 rng，对 (1,"self@1") 与 (k,f"self@{k}") 由 r4/r5 的 0<rank<=kk 命中向量算 b01/b10，m=b01+b10 为 0 时 p=1.0 否则取 McNemar 精确单侧和除以 2**m，并用 n_boot 次有放回重采样取 deltas[int(0.025*n_boot)] 与 deltas[int(0.975*n_boot)-1] 为 ci，另加 MRR 键（b01/b10/p 与 ci 均为 None）后返回。
 def paired_test(r4, r5, k=10, seed=0, n_boot=5000):
     """配对显著性：bootstrap 95% CI + McNemar 精确单侧 p（H1: 五路更好）。"""
     from math import comb
@@ -237,6 +249,7 @@ def paired_test(r4, r5, k=10, seed=0, n_boot=5000):
     return out
 
 
+# 生效条件：scopes 以 ("全合并", r4, r5) 起头，仅当某模式在 r4 中有条目时才追加该模式（orig/head/para/drop）的 (模式名, 筛选后 a, 筛选后 b)；对每个 scope 用 k、seed 调 paired_test 并逐项打印 self@1、self@k、MRR 的 delta/ci/b01-b10/p，函数本身不返回值。
 def print_sig(r4, r5, qs, k=10, seed=0):
     """按查询模式 + 全模式合并，打印配对显著性。"""
     print(f"\n配对显著性（五路 − 四路，配对 bootstrap 5000 次 + McNemar 精确单侧）")
@@ -260,6 +273,7 @@ def print_sig(r4, r5, qs, k=10, seed=0):
         print("-" * 66)
 
 
+# 生效条件：把 cg._path_fuzzy 换成闭包，原结果按分数降序取前 50 后用 random.Random(seed) 打乱并改写为递减伪分；本函数自身无 return。
 def patch_shuffled_fuzzy(cg, seed=0):
     """把 fuzzy 路**候选集保留、内部顺序打乱**（对照：区分「候选集贡献」与「排序质量贡献」）。
 
@@ -269,6 +283,7 @@ def patch_shuffled_fuzzy(cg, seed=0):
     rng = random.Random(seed)
     orig = cg._path_fuzzy
 
+# 生效条件：以 (query, entries, context, expand=expand) 调用原 _path_fuzzy，结果按分数降序取前 50 条，用闭包 rng 打乱后改写为递减伪分 (node, float(n-i))，返回 (out, str(src)+"+shuffled")。
     def _shuf(query, entries, context=None, expand=None):
         out, src = orig(query, entries, context, expand=expand)
         out = sorted(out, key=lambda x: -x[1])[:50]      # fuzzy 真实候选集
@@ -280,10 +295,12 @@ def patch_shuffled_fuzzy(cg, seed=0):
     cg._path_fuzzy = _shuf
 
 
+# 生效条件：把 cg._path_fuzzy 换成忽略 context/expand、对 cg._read_many 全量条目按 random.Random(seed) 随机分降序排序的闭包；本函数自身无 return。
 def patch_random_path(cg, seed=0):
     """把第 5 路替换为**全库随机排序**（对照：max 融合机制本身能带来多少增益）。"""
     rng = random.Random(seed)
 
+# 生效条件：忽略 context 与 expand，对 cg._read_many(entries, stat) 的每条记录用 rng.random() 打分并降序排序，节点 id 取 fm.get("id") or e["path"]，返回 (out, "random")。
     def _rand(query, entries, context=None, expand=None):
         stat = {"scanned": 0}
         out = []
@@ -296,6 +313,7 @@ def patch_random_path(cg, seed=0):
     cg._path_fuzzy = _rand
 
 
+# 生效条件：不使用 cg，直接把 md_cg.mdcos.GLOBAL_CAP 置为 10**9 并返回该值。
 def patch_symmetric_pool(cg):
     """【2026-09-16 起已冗余】抬高 GLOBAL_CAP，让 lexical 与 fuzzy 候选池对称。
 
@@ -311,6 +329,7 @@ def patch_symmetric_pool(cg):
     return _m.GLOBAL_CAP
 
 
+# 生效条件：把 cg._lexical 换成先 cg._read_many(entries, stat) 全量读入、再 cg._score(docs, query, bigrams(query)) 打分的闭包；本函数自身无 return。
 def patch_lexical_full(cg):
     """让 lexical 也对**全量候选池**打分（消除「扫描范围」差异，只留排序算法差异）。
 
@@ -320,6 +339,7 @@ def patch_lexical_full(cg):
     """
     from md_cg.mdcg import bigrams
 
+# 生效条件：entries 经 cg._read_many(entries, stat) 全量读入后交给 cg._score(docs, query, bigrams(query)) 打分并返回其结果。
     def _lex(query, entries, stat):
         docs = cg._read_many(entries, stat)
         return cg._score(docs, query, bigrams(query))
@@ -327,12 +347,14 @@ def patch_lexical_full(cg):
     cg._lexical = _lex
 
 
+# 生效条件：把 cg._read 包装为仅当原 _read 返回的 fm 是 dict 时覆写 fm["importance"]=0.5（非 dict 不修改），返回 (fm, c)；本函数自身无 return。
 def patch_zero_importance(cg):
     """抹掉 importance：数据集里 signal 的 importance 系统性偏高（≈0.6），
     而 search_rrf 用 (-score, -importance) 做同分 tie-break → 会泄漏 label。
     """
     orig = cg._read
 
+# 生效条件：orig(entry) 返回的 fm 是 dict 时把 fm["importance"] 设为 0.5（非 dict 不修改），返回 (fm, c)。
     def _z(entry):
         fm, c = orig(entry)
         if isinstance(fm, dict):
@@ -342,6 +364,7 @@ def patch_zero_importance(cg):
     cg._read = _z
 
 
+# 生效条件：cg 与 qs 均须可用；内部先经 cg._candidates() 取候选池、cg._read_many 读正文，再按每题 query terms 统计 _like 命中数；只打印诊断（含 GLOBAL_CAP 与截断计数）并返回 None，不改库；
 def pool_diag(cg, qs):
     """候选池对称性诊断：lexical 的 LIKE 命中数是否真的被 GLOBAL_CAP 截断。"""
     from md_cg import mdcos as _m
@@ -364,6 +387,7 @@ def pool_diag(cg, qs):
     return 0
 
 
+# 生效条件：cg.search_rrf 可用、queries 每项含 q/target/mode 时，对目标未列首的题打印顶替者与目标在 ARM5 各单路的排名，最多打印 limit 例。
 def diag_failures(cg, queries, k=10, arm=ARM5, limit=6, path_weights=None):
     """打印失败案例：谁把目标挤掉了、目标在单路里排第几。"""
     print(f"\n失败案例诊断（{'+'.join(arm)}，Top-{k} 未把目标排第一）")
@@ -395,6 +419,7 @@ def diag_failures(cg, queries, k=10, arm=ARM5, limit=6, path_weights=None):
         print("  （无失败案例）")
 
 
+# 生效条件：args.ablate=="pool" 时直接返回 pool_diag(cg, qs)；=="idcheck" 时对四路 sum 与四路 max 逐条比较 rank/labels 并打印差异数后返回 0；其余取值时先算四路基线与五路 fuzzy max 基线，再按 =="shuffle" 调 patch_shuffled_fuzzy、否则调 patch_random_path 做扰动臂，打印三臂指标后返回 0（k 取 args.k）。
 def ablate(cg, qs, args):
     """对照实验：分离「候选集贡献」「排序质量贡献」「融合机制红利」。"""
     k = args.k
@@ -438,6 +463,7 @@ def ablate(cg, qs, args):
     return 0
 
 
+# 生效条件：argv 经 argparse 解析（--n/--k/--seed/--rebuild/--per-path/--sweep/--diag/--ablate/--sympool/--fusion/--lexfull/--zero-importance 等）；外部数据集缺失即抛异常、不静默降级；返回进程退出码；
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--n", type=int, default=250, help="抽样 signal 条数（0=全量）")
@@ -604,4 +630,4 @@ def main():
 
 if __name__ == "__main__":
     sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/bench_p0.py

@@ -40,6 +40,7 @@ QUERIES = [("能量守恒", "物理学"), ("二分查找", "计算机科学"), (
            ("事务隔离", "计算机科学")]
 
 
+# 生效条件：fn 为可不带参调用的可调用对象时，重复执行 repeat 次并返回耗时（毫秒）的中位数、最小值、最大值三元组。
 def timeit(fn, repeat=5):
     ts = []
     for _ in range(repeat):
@@ -49,6 +50,7 @@ def timeit(fn, repeat=5):
     return statistics.median(ts), min(ts), max(ts)
 
 
+# 生效条件：模块级常量 ROOT 不是目录（not os.path.isdir(ROOT)）时打印未找到提示并返回 1；否则在 ROOT 上建 MdCG 依次跑检索延迟、情境对比与写入/维护基准，打印各项统计与耗时，并返回 0。
 def main():
     if not os.path.isdir(ROOT):
         print(f"未找到 md 库 {ROOT}，请先跑 python -m md_cg.test_p0")
@@ -81,6 +83,7 @@ def main():
 
     # ---- 2. 条件路由（情境正确）vs 全量 vs 朴素全库读盘扫描 ----
     # 朴素参照：每个查询都把全部节点文件读出来做一次子串匹配（无索引的代价上限）
+# 生效条件：给定 q 时遍历 cg.index["nodes"] 逐个读取 ROOT/e["path"]，内容含 q 子串（q 为空串时任何可读内容都命中）即收集其 path，读取抛 OSError 的条目被跳过，返回 hits 列表。
     def brute_force(q):
         hits = []
         for e in cg.index["nodes"].values():
@@ -144,4 +147,4 @@ if __name__ == "__main__":
     # 会在解释器退出阶段丢缓冲（实测只落盘 444 字节），CI 里会看不到结果。
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/bench_progressive.py

@@ -48,11 +48,13 @@ from md_cg.test_sem_noise import (                           # noqa: E402
     GOLD, GOLD_COND, NEG_TEXTS, NEIGHBORS, QUERY, UNREL_DOCS, _doc)
 
 
+# 生效条件：ev、ids 给定时按 ids 顺序找首个满足 nid in ev 的 1-based 位次返回，找不到（或 ids 为空、ev 为空）时返回 0。
 def rank_of(ev, ids):
     """gold 在 id 排名中的位次（不在则 0）。"""
     return next((r for r, nid in enumerate(ids, 1) if nid in ev), 0)
 
 
+# 生效条件：rank 为 1 时 st["h1"] 加 1，rank 落在 0<rank<=5 时 st["h5"] 加 1，落在 0<rank<=10 时 st["h10"] 加 1，rank 为真值时 st["rr"] 加 1.0/rank（负 rank 亦进入该分支得负增量），无返回值。
 def _agg(rank, st):
     if rank == 1:
         st["h1"] += 1
@@ -64,6 +66,7 @@ def _agg(rank, st):
         st["rr"] += 1.0 / rank
 
 
+# 生效条件：label、st、n 与可选 extra 给定时打印 label、st["h1"/"h5"/"h10"]*100.0/n、st["rr"]/n 及 extra 组成的行，n 为 0 时因源码直接相除抛 ZeroDivisionError（源码未校验 n）。
 def _show(label, st, n, extra=""):
     print("  %-22s hit@1=%5.1f%%  hit@5=%5.1f%%  hit@10=%5.1f%%  "
           "MRR=%.4f%s" % (label, st["h1"] * 100.0 / n,
@@ -71,6 +74,7 @@ def _show(label, st, n, extra=""):
                           st["rr"] / n, extra))
 
 
+# 生效条件：qa、docs 给定时对 docs 每项按 jaccard(qa, na) 降序、id 升序排序并返回其 id 序列，docs 为空返回空列表，qa 为空时全部分数相同故只按 id 升序。
 def full_rank(qa, docs):
     """全池 Jaccard 排序 → id 序列（与 run_arm 同判据）。"""
     scored = sorted(((jaccard(qa, na), nid) for nid, na in docs),
@@ -78,6 +82,7 @@ def full_rank(qa, docs):
     return [nid for _s, nid in scored]
 
 
+# 生效条件：无 required 形参；以模块级常量 CORPUS、QUESTIONS 逐行 json.loads 建语料与题目，每题取 evidence_turns 与 question 分词结果，qa 为空则跳过且不计入 n，最终返回含 g0/g2/g1i/g1f/n/fa10_conservative/avg_pool 的统计字典（分母均以 max(·,1) 兜零）。
 def exp_locomo():
     """实验一：原子面渐进三形态。"""
     t0 = time.time()
@@ -93,6 +98,7 @@ def exp_locomo():
 
     pool_sizes = []                        # G1 各阶段候选池大小（统计面）
 
+# 生效条件：used 给定时对其 frozenset 调 full_rank 取前 20 条，把该池大小追加进 pool_sizes，返回由这些 id 与 0.0 组成的二元组列表。
     def rank_fn(used):
         ranked = full_rank(frozenset(used), docs)[:20]
         pool_sizes.append(len(ranked))
@@ -148,6 +154,7 @@ def exp_locomo():
             "avg_pool": sum(pool_sizes) / max(len(pool_sizes), 1)}
 
 
+# 生效条件：无必需形参；自建临时库（tempfile.mkdtemp + MdCGOS）注入 GOLD/NEIGHBORS 语料后跑渐进消歧，finally 清理临时目录；返回指标 dict，不依赖外部数据；
 def exp_controlled():
     """实验二：受控干扰池——条件冒充形态下渐进消歧（引擎侧真检索）。"""
     print("\n[progressive] 实验二 受控干扰池（42+2 节点真实 MdCGOS）")
@@ -177,12 +184,14 @@ def exp_controlled():
         KW = dict(paths=("lexical", "bucket", "entity", "graph", "fuzzy"),
                   fusion="sum", judge_ranking=True)
 
+# 生效条件：used 给定时，used 为假值（空列表等）则查询串仅为 QUERY，否则为 QUERY 加空格再加空格连接的 used，再经 cg.search_rrf(k=10, judge=True, **KW) 返回 (id, 分值) 列表。
         def engine_rank(used):
             res, _m = cg.search_rrf(QUERY + (" " + " ".join(used)
                                              if used else ""),
                                     k=10, judge=True, **KW)
             return [(r[0]["id"], r[1]) for r in res]
 
+# 生效条件：res 给定时遍历其前 10 项，跳过 r[0]["id"] 属于外层 gold_ids 的项，对余项取 r[2]（len(r)<=2 时取空 dict）并仅在 (ji or {}).get("state")=="ACCEPT" 时把该 id 收入，返回收集到的 out 列表。
         def false_accepts(res):
             out = []
             for r in res[:10]:
@@ -194,6 +203,7 @@ def exp_controlled():
                     out.append(nid)
             return out
 
+# 生效条件：res 给定时遍历其前 10 项，len(r)>2 时取 (r[2] or {}).get("state")、否则取 None，该值属于 ACCEPT/DEFER/REJECT/BLINDSPOT 四键之一则对应计数、否则计入「无judge」，返回只保留计数非零项的字典（全零则返回空 dict）。
         def state_dist(res):
             """渐进循环四态分布（top10 内 judge state 计数，只列非零项）。
 
@@ -207,6 +217,7 @@ def exp_controlled():
                 d[st if st in d else "无judge"] += 1
             return {k: v for k, v in d.items() if v}
 
+# 生效条件：res、fa 给定时返回 100.0*len(fa)/max(1, min(10, len(res)))，即 len(res)>=10 时除以 10、不足时除以 len(res)，len(res) 为 0 时被 max(1,·) 兜为除数 1。
         def fa_rate(res, fa):
             return 100.0 * len(fa) / max(1, min(10, len(res)))
 
@@ -264,6 +275,7 @@ def exp_controlled():
         shutil.rmtree(tmp, ignore_errors=True)
 
 
+# 生效条件：无 required 形参；先执行 exp_locomo()，再按 exp_controlled() 返回值 ok 的真假返回 0（真）或 1（假）。
 def main():
     exp_locomo()
     ok = exp_controlled()
@@ -273,4 +285,4 @@ def main():
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

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