@furongjun1999/dsh-memory 0.4.7 → 0.4.9

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

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,25 +313,33 @@ def patch_random_path(cg, seed=0):
     cg._path_fuzzy = _rand
 
 
+# 生效条件：不使用 cg，直接把 md_cg.mdcos.GLOBAL_CAP 置为 10**9 并返回该值。
 def patch_symmetric_pool(cg):
-    """让 lexical 与 fuzzy 看到同样的全量候选池（消除 GLOBAL_CAP 截断偏置）。
+    """【2026-09-16 起已冗余】抬高 GLOBAL_CAP，让 lexical 与 fuzzy 候选池对称。
 
-    lexical 命中数超过 GLOBAL_CAP 时按**插入序**截断；fuzzy 则全库打分后取 Top-50。
-    两条路的候选池不对称，会系统性偏袒 fuzzy。抬高 cap 使其对等。
+    背景：lexical 命中数超 GLOBAL_CAP 时按**插入序**截断，fuzzy 则全库打分后取
+    Top-50；两条路候选池不对称，会系统性偏袒 fuzzy。当时以「抬高 cap」对冲。
+
+    现状：截断依据已改为**相关度**（`mdcg.cut_by_relevance` 与 `mdcos._lexical`
+    均先全量打分再排序截断，cap 值仍为 500）——插入序偏置的根因已消除，本 patch
+    不再必要。保留仅为兼容既有对照命令（`--symmetric-pool`）与历史口径复现。
     """
     from md_cg import mdcos as _m
     _m.GLOBAL_CAP = 10 ** 9
     return _m.GLOBAL_CAP
 
 
+# 生效条件：把 cg._lexical 换成先 cg._read_many(entries, stat) 全量读入、再 cg._score(docs, query, bigrams(query)) 打分的闭包；本函数自身无 return。
 def patch_lexical_full(cg):
     """让 lexical 也对**全量候选池**打分（消除「扫描范围」差异，只留排序算法差异）。
 
-    默认 _lexical 只在 LIKE 命中集上打分（中位约 20 条），而 _path_fuzzy 扫全库 1000 条；
-    仅抬高 GLOBAL_CAP 只修好「LIKE 全空」的兜底分支，非空命中时池仍不对等。
+    默认 _lexical 只在 LIKE 命中集上打分（中位约 20 条），而 _path_fuzzy 扫全库 1000 条。
+    注：截断依据改为相关度后（2026-09-16），「排序依据不对等」已消除，此处差异
+    仅剩**扫描范围**一项；本 patch 仍用于隔离排序算法差异的对照实验。
     """
     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))
@@ -322,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):
@@ -337,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
@@ -359,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} 未把目标排第一）")
@@ -390,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
@@ -433,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=全量）")
@@ -599,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()
@@ -91,15 +96,19 @@ def exp_locomo():
     print("[progressive] 实验一 locomo-zh-500 · 语料 %d / 题 %d"
           % (len(corpus), len(questions)))
 
+    pool_sizes = []                        # G1 各阶段候选池大小（统计面）
+
+# 生效条件：used 给定时对其 frozenset 调 full_rank 取前 20 条，把该池大小追加进 pool_sizes，返回由这些 id 与 0.0 组成的二元组列表。
     def rank_fn(used):
-        return [(nid, 0.0) for nid in
-                full_rank(frozenset(used), docs)[:20]]
+        ranked = full_rank(frozenset(used), docs)[:20]
+        pool_sizes.append(len(ranked))
+        return [(nid, 0.0) for nid in ranked]
 
     st_g0 = {"h1": 0, "h5": 0, "h10": 0, "rr": 0.0}
     st_g2 = dict(st_g0)
     st_i = dict(st_g0)
     st_f = dict(st_g0)
-    steps_sum = conv = n = 0
+    steps_sum = conv = n = fa10_sum = 0
     for q in questions:
         ev = set(q.get("evidence_turns") or [])
         qa = [w for w in zh_map_en(str(q.get("question") or ""),
@@ -117,8 +126,11 @@ def exp_locomo():
                                 ratio=0.5, k=10, max_stages=4)
         _agg(rank_of(ev, full_rank(frozenset(tr["stages"][0]["used"]),
                                    docs)), st_i)
-        _agg(rank_of(ev, full_rank(frozenset(tr["stages"][-1]["used"]),
-                                   docs)), st_f)
+        fin_all = full_rank(frozenset(tr["stages"][-1]["used"]), docs)
+        _agg(rank_of(ev, fin_all), st_f)
+        # 保守 false_accept 口径：final top10 内非 gold 条数（本语料无资格
+        # 判定面，非 gold 全计为假接受——上界，见打印行口径注明）
+        fa10_sum += sum(1 for nid in fin_all[:10] if nid not in ev)
         steps_sum += len(tr["added"])
         conv += 1 if (tr["converged"] or len(tr["added"]) < 3) else 0
 
@@ -130,9 +142,19 @@ def exp_locomo():
     print("  refinement: 平均加条件数=%.2f  一步收敛率=%.1f%%  (n=%d, %.0fs)"
           % (steps_sum / max(n, 1), conv * 100.0 / max(n, 1), n,
              time.time() - t0))
-    return {"g0": st_g0, "g2": st_g2, "g1i": st_i, "g1f": st_f, "n": n}
+    print("  false_accept(保守口径)=%.2f%%  =G1 final top10 非 gold 平均占比"
+          "（上界：本语料无 CCG 注释面，非 gold 全计为假接受）"
+          % (fa10_sum * 10.0 / max(n, 1)))
+    print("  候选池: G1 各阶段平均 top 池大小=%.1f (k=20 上限)"
+          % (sum(pool_sizes) / max(len(pool_sizes), 1)))
+    print("  四态分布: 本实验为原子面（语料无 CCG 注释，judge_qualification "
+          "将全判 BLINDSPOT）——资格判定不适用，不硬造数字；四态实证见实验二")
+    return {"g0": st_g0, "g2": st_g2, "g1i": st_i, "g1f": st_f, "n": n,
+            "fa10_conservative": fa10_sum * 10.0 / max(n, 1),
+            "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）")
@@ -162,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]:
@@ -179,13 +203,34 @@ 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 计数，只列非零项）。
+
+            judge info 直接复用 search_rrf(judge=True) 注入的
+            judge_qualification 产物（结果第三元），不重复判定。
+            """
+            d = {"ACCEPT": 0, "DEFER": 0, "REJECT": 0, "BLINDSPOT": 0,
+                 "无judge": 0}
+            for r in res[:10]:
+                st = (r[2] or {}).get("state") if len(r) > 2 else None
+                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)))
+
         # 宽检索（不加任何条件；judgeinfo 直接取 results 第三元）
         wide_res, _m = cg.search_rrf(QUERY, k=10, judge=True, **KW)
         wide = [(r[0]["id"], r[1]) for r in wide_res]
         fa_pre = false_accepts(wide_res)
         top1_pre = wide[0][0] if wide else None
-        print("  宽检索 top1=%s  top10 内 False ACCEPT=%s"
-              % (top1_pre, fa_pre or "无"))
+        print("  宽检索 top1=%s  top10 内 False ACCEPT=%s（率=%.1f%%）"
+              % (top1_pre, fa_pre or "无", fa_rate(wide_res, fa_pre)))
+        print("  四态分布(宽检索 top10)=%s  候选池=%d  judge 剔除=%s"
+              % (state_dist(wide_res), len(wide_res),
+                 (_m or {}).get("judge_filtered", 0)))
 
         # 渐进：候选间区分性条件词 → 带条件重排
         POOL = ["我", "喝水", "吃饭", "电脑", "书", "音乐", "出门",
@@ -203,7 +248,12 @@ def exp_controlled():
             fa_post = false_accepts(refined_res)
             top1_post = refined_res[0][0]["id"] if refined_res else None
             print("  区分性条件=%r → 重排 top1=%s  top10 内 "
-                  "False ACCEPT=%s" % (cond, top1_post, fa_post or "无"))
+                  "False ACCEPT=%s（率=%.1f%%）"
+                  % (cond, top1_post, fa_post or "无",
+                     fa_rate(refined_res, fa_post)))
+            print("  四态分布(重排 top10)=%s  候选池=%d  judge 剔除=%s"
+                  % (state_dist(refined_res), len(refined_res),
+                     (_m2 or {}).get("judge_filtered", 0)))
             ok1 = top1_post in gold_ids
             no_new = set(fa_post) <= set(fa_pre)
             print("  断言①渐进后 top1∈gold：%s" % ("PASS" if ok1 else "FAIL"))
@@ -225,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()
@@ -234,4 +285,4 @@ def main():
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())