@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/bench6_arms.py

@@ -54,6 +54,7 @@ QUERY_CONTEXT = {
 }
 
 
+# 生效条件：形参 c 若提供映射接口，则取 c["zh_fields"]（缺失或假值回落 {}）再取其 "condition"（缺失或假值回落 {}），返回三槽 observation_position/observation_tool/existence_constraint，各自以 cond.get(中文键, "") 取值——中文键缺失时回落空串，键存在而值为 None 时结果即为 None（不回落）。
 def cond_of(c):
     """zh_fields.condition（中文三槽）→ mdcos 期望的英文槽名。
 
@@ -65,6 +66,7 @@ def cond_of(c):
             "existence_constraint": cond.get("存在约束", "")}
 
 
+# 生效条件：形参 c 若提供映射接口，则 f = c["zh_fields"] 为假值（缺失/None/{}）时当作 {}，返回 [str(f["identity"] 或 "")] + [str(t) for t in (f["terms"] 或 [])]：identity 缺失或假值时首元素为空串（列表恒有 1 项），terms 缺失或假值时只有首元素。
 def tags_of(c):
     """喂 entity 路的裸词 tags = identity + terms。
 
@@ -77,24 +79,30 @@ def tags_of(c):
     return [str(f.get("identity") or "")] + [str(t) for t in (f.get("terms") or [])]
 
 
+# 生效条件：类无 __init__，实例化无需任何形参；其 describe_ingest(nids) 对任意 nids（含空）恒返回 []，而 reset()、add(nid, text)、search(query, k=5) 对任意实参一律抛 NotImplementedError。
 class Adapter:
     """统一适配接口。六家一律只回吐 id 列表，指标计算交回 bench6_common。"""
     name = "adapter"
 
+# 生效条件：无可选/必需形参，任何调用一律抛 NotImplementedError（基类接口桩）。
     def reset(self):
         raise NotImplementedError
 
+# 生效条件：对任意 nid 与 text 一律抛 NotImplementedError（形参不参与任何判断）。
     def add(self, nid, text):
         raise NotImplementedError
 
+# 生效条件：对任意 query 与任意 k（默认 5）一律抛 NotImplementedError，不返回结果。
     def search(self, query, k=5):
         raise NotImplementedError
 
+# 生效条件：对任意 nids（包括空列表或 None）都直接返回空列表 []，不读取任何存储。
     def describe_ingest(self, nids):
         """回读真实存储内容样本，用于取证「入库语言与入库形态」。"""
         return []
 
 
+# 生效条件：必须以 rows、variant、paths 三个必需形参构造（context 默认 None、with_meta 默认 False、rebuild 默认 False 可选），构造后 search(query, k=5) 是否向 search_rrf 传 context 由 context 是否为 None 决定，describe_ingest(nids)/bucket_health() 的取证内容取决于 variant 对应 root 库的索引状态。
 class LingshuAdapter(Adapter):
     """灵枢臂：进程内 MdCGOS。
 
@@ -103,6 +111,7 @@ class LingshuAdapter(Adapter):
 
     name = "lingshu"
 
+# 生效条件：root 固定为 os.path.join(ROOT_BASE, variant)；rebuild 为真且 os.path.isdir(root) 为真时先 rmtree，索引中已有节点数 ≥ len(rows) 时直接 return（幂等复用、不写库），否则按 rows 逐条 add（with_meta 为真时同时补 tags=tags_of(c)、condition_space=cond_of(c)）后 flush。
     def __init__(self, rows, variant, paths, context=None, with_meta=False,
                  rebuild=False):
         from md_cg.bench_locomo_zh_public import body_of
@@ -132,12 +141,14 @@ class LingshuAdapter(Adapter):
         print("  [lingshu/%s] 建库 %d 节点 %.1fs"
               % (variant, len(self.cg.index["nodes"]), time.time() - t0))
 
+# 生效条件：给定 query 与 k（默认 5）即调用 self.cg.search_rrf(k=k、paths=self.paths、judge=False、record=False)，仅当 self.context 不为 None 时附加 context 参数，返回每个结果 r 的 r[0]["id"] 组成的列表。
     def search(self, query, k=5):
         kw = {"context": self.context} if self.context is not None else {}
         res, _meta = self.cg.search_rrf(query, k=k, paths=self.paths,
                                         judge=False, record=False, **kw)
         return [r[0]["id"] for r in res]
 
+# 生效条件：只遍历 nids[:2]，节点索引中 .get(nid) 为假值（缺失）的 nid 被跳过，其余按 os.path.join(self.cg.root, e["path"]) 读文件头 300 字符，抛 OSError 时 file_head 保持空串，输出各字段用 e.get（缺键为 None）。
     def describe_ingest(self, nids):
         """回读真实落盘内容（索引元数据 + 文件头），取证入库语言与形态。
 
@@ -161,6 +172,7 @@ class LingshuAdapter(Adapter):
                         "file_head": head})
         return out
 
+# 生效条件：无参数，遍历 self.cg.index["nodes"] 各节点的 e.get("bucket")，其缺失或为假值（None/空串等）时归入 "<none>" 计数，再把计数字典交 routing.bucket_health 并返回其结果。
     def bucket_health(self):
         """桶健康度自检（routing.bucket_health）：取证条件路由是否有区分力。"""
         from md_cg import routing
@@ -171,6 +183,7 @@ class LingshuAdapter(Adapter):
         return routing.bucket_health(counts)
 
 
+# 生效条件：无必需构造形参，base 为假值（None/空串）时先回落 os.environ["BENCH6_EMBED_BASE"]、再回落 "http://127.0.0.1:1234/v1" 并 rstrip("/")，model 为假值时回落 os.environ["BENCH6_EMBED_MODEL"]、再回落空串 ""，timeout 缺省为 30。
 class VectorRagAdapter(Adapter):
     """纯向量 RAG 基线（零 LLM）：英文原文直嵌入 + 余弦 Top-k。
 
@@ -180,6 +193,7 @@ class VectorRagAdapter(Adapter):
 
     name = "vector_rag"
 
+# 生效条件：base 依次按 base 形参 → os.environ.get("BENCH6_EMBED_BASE") → "http://127.0.0.1:1234/v1" 取值（每级为空串/None 均继续回落）再去掉尾部 "/"，model 依次按 model 形参 → os.environ.get("BENCH6_EMBED_MODEL") → "" 取值（空串也回落），timeout 直接取形参（含 0），ids/vecs 置 []、_dim 置 0。
     def __init__(self, base=None, model=None, timeout=30):
         self.base = (base or os.environ.get("BENCH6_EMBED_BASE")
                      or "http://127.0.0.1:1234/v1").rstrip("/")
@@ -189,6 +203,7 @@ class VectorRagAdapter(Adapter):
         self.vecs = []
         self._dim = 0
 
+# 生效条件：以 self.base + path 为 URL、method="POST"、JSON 编码的 payload 为 body、Content-Type: application/json、超时 self.timeout 发出请求，返回响应体按 UTF-8 解码后 json.loads 的对象。
     def _post(self, path, payload):
         req = urllib.request.Request(
             self.base + path, method="POST",
@@ -197,6 +212,7 @@ class VectorRagAdapter(Adapter):
         with urllib.request.urlopen(req, timeout=self.timeout) as r:
             return json.loads(r.read().decode("utf-8"))
 
+# 生效条件：self.model 为真值时直接返回；否则请求 self.base + "/models"，从 data.get("data") 筛出 id 非空的模型名列表，该列表为空时抛 RuntimeError，否则优先取名字含 embed/bge/gte/m3 的第一个，无匹配则取 ids[0]，写入 self.model 后返回。
     def resolve_model(self):
         """未显式指定时，从 /models 取第一个 embedding 模型。"""
         if self.model:
@@ -216,12 +232,14 @@ class VectorRagAdapter(Adapter):
             self.model = ids[0]
         return self.model
 
+# 生效条件：对任意 text 以 self.model 调 _post("/embeddings", {"model":…, "input": text})，取 d["data"][0]["embedding"]，令 self._dim 等于该向量长度并返回该向量。
     def embed(self, text):
         d = self._post("/embeddings", {"model": self.model, "input": text})
         v = d["data"][0]["embedding"]
         self._dim = len(v)
         return v
 
+# 生效条件：按 batch（默认 32）把 texts 切片，每片整批 POST /embeddings 成功时按 x.get("index", 0) 排序后依次收集 r["embedding"]，该片抛任何异常时改为对片内每条调 self.embed 回退，self._dim 为 0 且有结果时置为最后一条向量长度，最后返回 out。
     def embed_many(self, texts, batch=32):
         """批量嵌入（服务不支持 batch 时逐条回退）。"""
         out = []
@@ -237,13 +255,16 @@ class VectorRagAdapter(Adapter):
                 self._dim = len(out[-1])
         return out
 
+# 生效条件：无前置；把 self.ids 与 self.vecs 同时清空（二者下标耦合，必须成对重置），self._dim 保留原值不动；
     def reset(self):
         self.ids, self.vecs = [], []
 
+# 生效条件：对任意 nid 与 text，把 nid 追加到 self.ids、把 self.embed(text) 的向量追加到 self.vecs，二者按下标一一对应，不查重、不返回。
     def add(self, nid, text):
         self.ids.append(nid)
         self.vecs.append(self.embed(text))
 
+# 生效条件：self.vecs 为空时直接返回 []；否则嵌入 query 并对每条候选计算余弦相似度（qn 或 vn 为 0 时用 1.0 兜底），按相似度降序、同分按 id 升序排序后返回前 k 个 nid。
     def search(self, query, k=5):
         if not self.vecs:
             return []
@@ -257,6 +278,7 @@ class VectorRagAdapter(Adapter):
         scored.sort(key=lambda x: (-x[0], x[1]))
         return [nid for _s, nid in scored[:k]]
 
+# 生效条件：对任意 nids 都只取前 2 项（nids[:2]），各返回 {"id": nid, "form": "原样英文文本 → embedding", "lang": "en", "dim": self._dim}，不读磁盘内容。
     def describe_ingest(self, nids):
         return [{"id": nid, "form": "原样英文文本 → embedding",
                  "lang": "en", "dim": self._dim} for nid in nids[:2]]
@@ -264,6 +286,7 @@ class VectorRagAdapter(Adapter):
 
 # ------------------------------------------------------------------ 套件与评分
 
+# 生效条件：lang 等于 "zh" 时逐题取 q["question_zh"]，lang 为其它任何值（含 "en"）时取 q["question_en"]，对 questions 每项调 adapter.search(query, k=k)，verbose 为真且序数能被 50 整除时打印进度，返回 {qid: 检索结果列表}。
 def run_suite(adapter, questions, lang, k=5, verbose=True):
     """一套查询语言跑一遍 → {qid: [id...]}（顺序即相关性降序）。"""
     key = "question_zh" if lang == "zh" else "question_en"
@@ -276,6 +299,7 @@ def run_suite(adapter, questions, lang, k=5, verbose=True):
     return hits
 
 
+# 生效条件：对 langs 中每个 lang 依次跑 run_suite(adapter, questions, lang, k=k)、bc.rows_from_hits 与 ec.summarize，结果写入 out["langs"][lang]；最后取 questions 前 2 条的 qid 调 adapter.describe_ingest 存入 out["ingest_probe"] 并返回 out。
 def evaluate(arm, adapter, questions, k=5, langs=("zh", "en")):
     """一套库 × 两种查询语言 → 指标 + per-question 明细 + 回读取证。"""
     out = {"arm": arm, "k": k, "langs": {}}
@@ -290,6 +314,7 @@ def evaluate(arm, adapter, questions, k=5, langs=("zh", "en")):
     return out
 
 
+# 生效条件：model 依次按 model 形参 → os.environ.get("BENCH6_EMBED_MODEL") → "text-embedding-bge-m3" 取值（形参为空串/None、环境变量缺失或为空串都会继续回落），随后 resolve_model()，再把 pool 中每条的 t["id"]、t["ingest"] 分别装进 vec.ids 与批量嵌入结果 vec.vecs 后返回 vec。
 def build_vector_rag(pool, model=None):
     """向量基线：池内英文原文批量嵌入（零 LLM、无结构化）。"""
     vec = VectorRagAdapter(model=model or os.environ.get("BENCH6_EMBED_MODEL")
@@ -303,6 +328,7 @@ def build_vector_rag(pool, model=None):
     return vec
 
 
+# 生效条件：argv 为 None 时取 sys.argv[1:]，其中出现 "--rebuild" 则各臂以 rebuild=True 建库，非 "-" 开头的项构成 only 白名单，仅当 only 为空或臂名在 only 中时执行对应臂（only 为空时额外执行 2×2 消融块），跑完返回含 manifest/results/elapsed_s 的 payload。
 def main(argv=None):
     argv = sys.argv[1:] if argv is None else argv
     rebuild = "--rebuild" in argv
@@ -322,6 +348,7 @@ def main(argv=None):
     rows = [corpus_by_id[t["id"]] for t in pool]
     results, table = {}, {}
 
+# 生效条件：形参 name 出现在外层 main 的 only 白名单中时返回 True；only 为空（假值）时对任何 name 都返回 True；only 非空且不含 name 时返回 False。
     def _want(name):
         return not only or name in only
 
@@ -381,4 +408,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench6_common.py

@@ -53,6 +53,7 @@ BOUNDARIES = [
 ]
 
 
+# 生效条件：rows 为含 qtype 的行列表、n 取默认 N_QUESTIONS、seed 取默认 SEED 时（rows 为空则分组与配额皆空、out 为空列表；n=0 时各型配额与 out 皆为空/0），按 int(n*组大小/总行数) 定配额并把余数按小数部分降序补足，逐型用 random.Random("%d:%s"%(seed,qt)) 抽 min(配额,组大小) 条，返回按 qid 排序的 (out, quota)
 def stratified_sample(rows, n=N_QUESTIONS, seed=SEED):
     """按 qtype 比例分层抽样（最大余额法）。
 
@@ -78,6 +79,7 @@ def stratified_sample(rows, n=N_QUESTIONS, seed=SEED):
     return out, quota
 
 
+# 生效条件：sample 为含 qid 与 evidence_turns 的题列表、corpus_by_id 为 id→池行的映射时，把不在 corpus_by_id 中的 evidence_turns 逐题记为 {"qid":…,"missing":[…]} 收入 dangling，其余去重后返回 (按 id 排序的 corpus_by_id 行列表, dangling)
 def build_pool(sample, corpus_by_id):
     """池 = 抽中题的 gold 引用 turn 去重。返回 (pool, dangling)。
 
@@ -94,6 +96,7 @@ def build_pool(sample, corpus_by_id):
     return [corpus_by_id[i] for i in sorted(pool_ids)], dangling
 
 
+# 生效条件：c 为含 text 键的映射时取其去空白文本，date 非空则返回 "文本 [date]"，date 为空则只返回 text。
 def ingest_text_en(c):
     """六家共用的英文写入文本：原始陈述 + 会话时间。
 
@@ -107,6 +110,7 @@ def ingest_text_en(c):
     return "%s [%s]" % (text, date) if date else text
 
 
+# 生效条件：c 含 "id" 键时返回 {'id': c["id"], 'speaker'/'date'/'text' 为 c.get(键) or ""（键缺失或值为 None/""/0/[] 等假值均落空串）, 'ingest': ingest_text_en(c)}；缺 "id" 键时 c["id"] 抛 KeyError
 def turn_rec(c):
     """池行 → 落盘行（六家共用的英文侧视图）。"""
     return {"id": c["id"], "speaker": c.get("speaker") or "",
@@ -114,6 +118,7 @@ def turn_rec(c):
             "ingest": ingest_text_en(c)}
 
 
+# 生效条件：sample 每题的 qid 在 en_by_qid 中且中英 evidence_turns 逐字相等时返回按 sample 顺序的 {qid, qtype, question_zh, question_en, evidence_turns} 列表；en_by_qid.get(qid) 为 None 抛 KeyError，两列表不等抛 AssertionError
 def align_queries(sample, en_by_qid):
     """中英双查询词面按 qid join，断言 evidence_turns 逐字一致。
 
@@ -133,6 +138,7 @@ def align_queries(sample, en_by_qid):
     return out
 
 
+# 生效条件：ids 为 id 序列、evidence 为证据 id 集合时，把 ids 包装成 [({"id": x}, 0.0)] 后原样返回 ec.first_evidence_rank 的结果
 def rank_of(ids, evidence):
     """首个证据 id 的排名（1-based；未命中 0）。
 
@@ -143,6 +149,7 @@ def rank_of(ids, evidence):
     return ec.first_evidence_rank(res, set(evidence))
 
 
+# 生效条件：questions 每题含 qid，hits_by_qid 缺该 qid 或其值为假值（含空列表）时按空 id 列表处理，取前 k=K 条后返回每题 {qid, qtype, rank, top1_score(ids 非空为 1.0 否则 0.0), n_res} 的行列表
 def rows_from_hits(questions, hits_by_qid, k=K):
     """把任一家的 id 列表统一转成 ec.summarize 的明细行。
 
@@ -159,6 +166,7 @@ def rows_from_hits(questions, hits_by_qid, k=K):
     return rows
 
 
+# 生效条件：force 为假且 os.path.exists(MANIFEST) 与 os.path.exists(QUESTIONS_JSONL) 均为真时读回 MANIFEST 直接返回（verbose 为真时打印复用信息）；否则重建口径、写 POOL_JSONL/QUESTIONS_JSONL/MANIFEST 后返回该 man
 def prepare(force=False, verbose=True):
     """固化口径层产物（幂等）。返回 manifest。"""
     if not force and os.path.exists(MANIFEST) and os.path.exists(QUESTIONS_JSONL):
@@ -211,6 +219,7 @@ def prepare(force=False, verbose=True):
     return man
 
 
+# 生效条件：无参调用时读 MANIFEST 常量并返回 {'questions': QUESTIONS_JSONL 行列表, 'pool': POOL_JSONL 行列表, 'manifest': 该 JSON 对象}
 def load():
     """读回已固化的口径层产物。六家适配器只经此取题与池。"""
     man = json.load(open(MANIFEST, encoding="utf-8"))
@@ -219,4 +228,4 @@ def load():
 
 
 if __name__ == "__main__":
-    prepare(force="--force" in sys.argv)
+    prepare(force="--force" in sys.argv)

package/md_cg/bench6_competitors.py

@@ -54,11 +54,13 @@ MAIN_ARMS = [
 LANGS = ("zh", "en")
 
 
+# 生效条件：questions、hits、k 三者给定即成立，以 hits 结合 k 经 bc.rows_from_hits 生成 rows，再返回 (ec.summarize(rows, k=k), rows)。
 def _score_hits(questions, hits, k):
     rows = bc.rows_from_hits(questions, hits, k=k)
     return ec.summarize(rows, k=k), rows
 
 
+# 生效条件：manifest_note 传入但源码未使用该形参，结果只取决于模块常量 ec.RESULTS 下 bench6_arms_result.json——该路径不存在时打印警告并返回 {}，路径可读时返回 json.load 结果 .get('results') or {}（results 键缺失或该值为假值时同样得到 {}）。
 def load_main(manifest_note):
     """读主进程臂结果（含灵枢 5 口径 + 向量基线）。"""
     path = os.path.join(ec.RESULTS, "bench6_arms_result.json")
@@ -69,6 +71,7 @@ def load_main(manifest_note):
         return json.load(f).get("results") or {}
 
 
+# 生效条件：由 arm 拼出模块常量 ARM_OUT 下 <arm>.json，该路径不存在时返回 (None, '缺文件 …（该臂未跑或跑失败）')；路径可读时用 questions 与 k 对遍历模块常量 LANGS 各语言的 hits 评分（raw['langs']、某语言块、其 hits 缺失或为假值时按 {} 处理，errors 缺失或为假值时按 [] 处理），返回 (out, None)。
 def load_competitor(arm, questions, k):
     path = os.path.join(ARM_OUT, "%s.json" % arm)
     if not os.path.exists(path):
@@ -94,6 +97,7 @@ def load_competitor(arm, questions, k):
     return out, None
 
 
+# 生效条件：遍历 rows 的每个 (label, r)，仅当 r['langs'] 对模块常量 LANGS 每个语言都存在真值时，才用 k 读 s['hit@k'] 并打印 hit@1/hit@k/MRR 及未回收率（unmapped_rate 为 None 时显示 n/a）；否则只打印 label 加「—」占位行，不打印数值。
 def print_matrix(rows, k):
     """六家 × 两语言主表（hit@1 / hit@k / MRR）。"""
     head = ("系统", "zh hit@1", "zh hit@%d" % k, "zh MRR",
@@ -119,6 +123,7 @@ def print_matrix(rows, k):
         print("  ".join(c.ljust(wi) for c, wi in zip(cells, w)))
 
 
+# 生效条件：argv 为 None 时改读 sys.argv[1:] 解析 --k，随后按 MAIN_ARMS 与 COMPETITOR_ARMS 各自装载结果，返回含 k、arms、missing 的 payload。
 def main(argv=None):
     argv = sys.argv[1:] if argv is None else argv
     k = 5
@@ -205,4 +210,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_axis_domain.py

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

package/md_cg/bench_blind_comp.py

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

package/md_cg/bench_en_atoms_public.py

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