@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/backfill.py

@@ -127,11 +127,13 @@ CAP_RULES = OrderedDict(
 
 # ---- 通用工具 ------------------------------------------------------------
 
+# 生效条件：x 为 str 时返回 MdCGOS(x)，否则原样返回 x。
 def _as_cg(x):
     """接受 root 路径或已构造的 cg 实例——保持密级隔离与密钥上下文。"""
     return MdCGOS(x) if isinstance(x, str) else x
 
 
+# 生效条件：v 为 list/tuple 时返回分号连接的非空元素文本；v 为 None 或空串时返回 ""；否则返回 str(v).strip()（v 为 0 或 False 走此支返回 "0"/"False"）。
 def _as_text(v) -> str:
     if isinstance(v, (list, tuple)):
         return "；".join(str(x).strip() for x in v if str(x).strip())
@@ -140,12 +142,14 @@ def _as_text(v) -> str:
     return str(v).strip()
 
 
+# 生效条件：fm 为假值时按 {} 处理，state_attributes.comment 为 dict 时返回该 dict，否则返回 {}。
 def _comment(fm: dict) -> dict:
     st = (fm or {}).get("state_attributes")
     c = st.get("comment") if isinstance(st, dict) else None
     return c if isinstance(c, dict) else {}
 
 
+# 生效条件：fm 的 state_attributes 为 dict 且其下 comment 为 dict 时原样返回该 comment；否则创建并返回空 comment dict（state_attributes 非 dict 时置 fm["state_attributes"]={}，comment 非 dict 时置 st["comment"]={}）。
 def _ensure_comment(fm: dict) -> dict:
     st = fm.get("state_attributes")
     if not isinstance(st, dict):
@@ -158,10 +162,12 @@ def _ensure_comment(fm: dict) -> dict:
     return c
 
 
+# 生效条件：e 的 id 为真值时返回 id，否则返回 e 的 path 基名去掉最后 3 个字符（path 为假值时基名为空，结果空串）。
 def _node_id(e: dict) -> str:
     return e.get("id") or os.path.basename(e.get("path") or "")[:-3]
 
 
+# 生效条件：fm 的 condition_space 四槽齐全时返回 nodefile.condition_space_text 合成文本，否则返回空串。
 def _condition_text(fm: dict) -> str:
     """→ 条件空间四槽合成的生效条件声明；四槽不齐 → ""（不冒充）。
 
@@ -172,14 +178,17 @@ def _condition_text(fm: dict) -> str:
     return nodefile.condition_space_text((fm or {}).get("condition_space"))
 
 
+# 生效条件：s 为真值时返回其 sha1 前 12 位，s 为假值（None/空串等）时对空串取 sha1 前 12 位。
 def _sha(s: str) -> str:
     return hashlib.sha1((s or "").encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：batch 与 nid 经 f-string 拼接后取 sha1 前 12 位；两者为 None 会字符串化为 "None"。
 def _entry_id(batch: str, nid: str) -> str:
     return hashlib.sha1(f"{batch}|{nid}".encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：content 中 strip 后以 # 开头且去掉 # 与空白后、全角或半角冒号前首段等于 field 的整行被删除，其余行保留并 join。
 def _remove_ccg_line(content: str, field: str) -> str:
     """删掉 `# <字段>：…` 整行（回滚用）。"""
     keep = []
@@ -192,12 +201,14 @@ def _remove_ccg_line(content: str, field: str) -> str:
     return "\n".join(keep)
 
 
+# 生效条件：cg.root 与模块级常量 BACKFILL_LOG 拼接为返回路径。
 def _log_path(cg) -> str:
     return os.path.join(cg.root, BACKFILL_LOG)
 
 
 # ---- 字段推导（唯一入口：只搬运已声明的证据） -----------------------------
 
+# 生效条件：fm 与 content 给定时，仅对 content 中尚无对应 CCG 行的字段（功能名/生效条件/子功能/执行/验证方式/不适用条件）从 fm 的已有声明（state_attributes.comment、frontmatter、verification_basis、或形参 basis_text）取值，值非空且非占位文本才写入 out，假值不写、占位文本只把字段名追加进 placeholder_out（未传该形参时用临时列表）。
 def derive_fields(fm: dict, content: str, basis_text: str = None,
                   placeholder_out: list = None) -> dict:
     """按**已有声明**推导可回填字段 → `{field: (value, basis)}`。
@@ -213,6 +224,7 @@ def derive_fields(fm: dict, content: str, basis_text: str = None,
     ph = placeholder_out if placeholder_out is not None else []
     out = {}
 
+# 生效条件：field 与 basis 在 value 为真值且 nodefile.is_placeholder_text(value) 为假时写入 out；value 为假值不写入；value 为占位文本时仅把 field 记入 ph。
     def _put(field, value, basis):
         """有值且非占位标记才写出；占位值只记名，绝不渲染成事实。"""
         if not value:
@@ -267,6 +279,7 @@ def derive_fields(fm: dict, content: str, basis_text: str = None,
 
 # ---- 节点筛选 ------------------------------------------------------------
 
+# 生效条件：cg 无 _readable 可调用时返回 True；有可调用时返回 bool(fn(e))，fn(e) 抛异常时返回 False。
 def _readable_guard(cg, e) -> bool:
     fn = getattr(cg, "_readable", None)
     if not callable(fn):
@@ -277,6 +290,7 @@ def _readable_guard(cg, e) -> bool:
         return False
 
 
+# 生效条件：仅当 cg 对 e 读出的 fm 非 None、content 未被 crypto.is_encrypted、e['layer'] 不在 SKIP_LAYERS 且 fm.get('tags') 无命中 SKIP_TAGS、ccg_completeness(content)['complete'] 为假时才继续——derive_fields（受 basis_text 影响）过滤掉 content 已有 CCG 行的可写字段为空时按 placeholder_out 是否非空返回 ('placeholder'/'unfillable', None)，非空时返回 ('', item)（item 的 id 取 nid、class 依 undeducible 是否为空取 'backfillable' 或 'partial'）；上述四个前置不满足时依次返回 ('unreadable'/'locked'/'derived'/'present', None)。
 def _classify(cg, e, nid, basis_text=None):
     """→ (skip_reason, item)；skip_reason 非空表示不参与回填。"""
     fm, content = cg._read(e)
@@ -317,6 +331,7 @@ def _classify(cg, e, nid, basis_text=None):
     }
 
 
+# 生效条件：x 经 _as_cg 后遍历 cg.index.nodes，按 ids/layer/prefix 过滤，内部层/不可读/locked/derived/present/unfillable/placeholder/partial 且 include_partial 为 False 分别计数跳过，其余标记 entry_id 并计入 targeted，items 受 limit 限制（limit 为 None 或 len(items) < limit 时追加），返回 dry_run rep。
 def plan(x, layer=None, limit=None, ids=None, include_partial=False,
          basis_text=None, prefix=None) -> dict:
     """预演：产出可回填清单，不写盘。
@@ -381,6 +396,7 @@ def plan(x, layer=None, limit=None, ids=None, include_partial=False,
 
 # ---- 回填写入 / 回滚 / 留痕 ----------------------------------------------
 
+# 生效条件：x 可被 _as_cg 解释为 CG 句柄时，按 layer/ids/prefix/entry_ids 选定条目做回填并返回含 written 等计数的 rep，其中 limit 非 None 时把写入数截断到该值。
 def apply(x, ids=None, entry_ids=None, layer=None, limit=None,
           batch=BATCH_DEFAULT, include_partial=False, basis_text=None,
           actor=None, prefix=None) -> dict:
@@ -458,6 +474,7 @@ def apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg 定位后读留痕日志，仅对 action=='backfill' 且（batch 为假值则不过滤 batch，否则 rec['batch']==batch）、（entry_ids 为假值则不过滤，否则 rec['entry_id'] 属于该集合）、write_id 未出现在已完成 rollback 集合中、节点命中 cg.index['nodes'] 且 cg._read(e) 的 fm 可读、字段当前 _ccg_field(content, f) 等于留痕 after 的记录执行撤销写回（before 为 None 则删该 comment 键，否则还原原值），无字段可撤销只计 conflict 不写盘，reverted 非空时 rebuild_index，结果汇总进返回的 rep。
 def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """按留痕反向应用：撤销本批次回填（当前值 ≠ 写入值时跳过，防覆盖）。"""
     cg = _as_cg(x)
@@ -528,6 +545,7 @@ def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，action/batch 为真值时过滤对应日志记录；limit 不为 None 且 >=0 时按 recs[-limit:] 截断（limit=0 时切片为全部记录），limit 为 None 或负数时不截断；返回 total/returned/records。
 def history(x, limit=100, action=None, batch=None) -> dict:
     cg = _as_cg(x)
     recs = []
@@ -555,6 +573,7 @@ def history(x, limit=100, action=None, batch=None) -> dict:
 _CAP_TEMPLATE_LINES = ("验证方式",)
 
 
+# 生效条件：content 中去除 # 与空白后、全角或半角冒号前首段命中 _CAP_TEMPLATE_LINES 的行被剔除，其余行保留并 join。
 def _cap_body(content: str) -> str:
     """正文（供关键词匹配）——剔除 CCG 模板行，防模板词污染候选。"""
     keep = []
@@ -567,6 +586,7 @@ def _cap_body(content: str) -> str:
     return "\n".join(keep)
 
 
+# 生效条件：当 fm 为可 get 的 frontmatter、e 为带 id 的节点条目、content 为正文文本时，返回 title+e.id+功能名/生效条件/子功能字段+正文前 300 字合并后的小写串（不含 fm.tags）。
 def _cap_text(e, fm, content) -> str:
     """候选匹配文本：节点标识 + CCG 字段 + 正文（**不含 `fm.tags`**）。"""
     parts = [_as_text(fm.get("title")), e.get("id") or ""]
@@ -578,6 +598,7 @@ def _cap_text(e, fm, content) -> str:
     return " ".join(parts).lower()
 
 
+# 生效条件：text 包含 CAP_RULES 中某 cap 的至少一个关键词时，该 cap 以匹配关键词与置信度加入返回，按置信度降序、cap 升序排序；无匹配返回空 hits。
 def cap_matches(text: str) -> list:
     hits = []
     for cap, kws in CAP_RULES.items():
@@ -589,6 +610,7 @@ def cap_matches(text: str) -> list:
     return hits
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 ids/layer 过滤，不可读计 denied，读取失败或加密计 locked，扫描后以 _cap_text 匹配并过滤 confidence >= min_conf 且标签未含 cap:，无命中计 present，有命中则 targeted 并受 limit 限制加入 items，返回 dry_run rep。
 def cap_plan(x, layer=None, limit=None, ids=None, min_conf=0.5) -> dict:
     """预演：按关键词启发式给出 `cap:<op>` 标签建议（含依据与置信度），不写盘。"""
     cg = _as_cg(x)
@@ -626,6 +648,7 @@ def cap_plan(x, layer=None, limit=None, ids=None, min_conf=0.5) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 BATCH_DEFAULT；先 cap_plan 得 items，按 entry_ids 过滤；逐个检查节点存在、读取可读、无新增标签分别计 drift/locked/drift，成功写 tags 并记日志，limit 非 None 且 written >= limit 时 break；返回 rep。
 def cap_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
               batch=BATCH_DEFAULT, min_conf=0.5, actor=None) -> dict:
     """注入 `cap:<op>` 标签：只改 frontmatter.tags，不动正文。"""
@@ -676,6 +699,7 @@ def cap_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg，读取日志中 action=cap 且未回滚的记录，按 batch/entry_ids 过滤，节点存在且原加入标签仍在 tags 中时移除，否则计 conflict/missing，返回 rep。
 def cap_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """撤销 cap 注入：仅移除**仍在 tags 里**的 `cap:` 标签（防覆盖后续修改）。"""
     cg = _as_cg(x)
@@ -730,6 +754,7 @@ def cap_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
 EXEMPT_FLAG = "ccg_exempt"
 
 
+# 生效条件：fm 的 verification_basis 合法且 content 的 ccg_completeness 标记 complete 时返回 (True, [])，否则把缺失项放入 miss 返回 ready=False。
 def _exempt_ready(fm: dict, content: str):
     """摘豁免前置条件 → `(ready, missing)`。
 
@@ -745,6 +770,7 @@ def _exempt_ready(fm: dict, content: str):
     return (not miss), miss
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 ids/prefix/layer 过滤，内部层/不可读/读取失败或加密分别计数跳过，fm 无 EXEMPT_FLAG 计 not_exempt，require_ready 为真且不 ready 时计 unready 并在 want 为 None 时跳过，否则生成 item 受 limit 限制；sample 为真值时按 id 序等距抽取 sample 个。
 def exempt_plan(x, layer=None, limit=None, ids=None, require_ready=True,
                 sample=0, prefix=None) -> dict:
     """预演：列出可摘 `ccg_exempt` 的节点（默认要求证据就绪），不写盘。
@@ -804,6 +830,7 @@ def exempt_plan(x, layer=None, limit=None, ids=None, require_ready=True,
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 BATCH_DEFAULT；先 exempt_plan 得 items，按 entry_ids 过滤；逐个检查节点存在、可读、EXEMPT_FLAG 仍真、require_ready 为真时 _exempt_ready 再次通过；不通过计 skipped_unready 并记 exempt_skip；通过则置 EXEMPT_FLAG=False 写盘记日志；limit 限制 written；返回 rep。
 def exempt_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
                  batch=BATCH_DEFAULT, require_ready=True, actor=None,
                  prefix=None) -> dict:
@@ -864,6 +891,7 @@ def exempt_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：当 x 可解析为 cg 时，日志中 action 为 exempt 的记录若其非空 write_id 已存在于既有 action 为 exempt_rollback 的记录 write_id 集合中，则跳过并计入 skipped_done，否则在通过 batch 与 entry_ids 过滤后，节点存在且可读、EXEMPT_FLAG 当前为假时，该记录才被还原并计入 reverted；。
 def exempt_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """反向还原 `ccg_exempt`：仅当当前仍为「已摘」状态时还原，否则计 conflict。"""
     cg = _as_cg(x)
@@ -920,6 +948,7 @@ def exempt_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
 #   ③ verify_conditions    只读复算：验收指标 legacy_position == 0
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 prefix/layer 过滤，内部层/不可读/读取失败或加密/derived 层或 SKIP_TAGS 分别计数跳过；扫描后，正文已有生效条件计 declared，derive_fields 可推出计 derivable，否则按 condition_space 缺失槽计 pending 并受 limit 限制收集 items；返回 rep。
 def conditions_pending(x, prefix=None, layer=None, limit=None) -> dict:
     """只读台账：列出「未声明生效条件、且四槽推不出」的节点及其缺失槽。
 
@@ -978,6 +1007,7 @@ def conditions_pending(x, prefix=None, layer=None, limit=None) -> dict:
     return rep
 
 
+# 生效条件：cg 的留痕日志中存在 basis 为 LEGACY_CONDITION_BASIS 且未被回滚的 backfill 生效条件写入时，按 node 记录最后一次的 after/original 返回；无匹配返回空。
 def _legacy_condition_records(cg) -> dict:
     """→ {node: {after, original, …}}：我们**自己写下的**单槽冒充行（真源 = 留痕）。
 
@@ -1005,6 +1035,7 @@ def _legacy_condition_records(cg) -> dict:
     return out
 
 
+# 生效条件：x 经 _as_cg，从 _legacy_condition_records 取候选，按 prefix 过滤，节点不存在/不可读/读取失败或加密分别计 missing/denied/locked；当前生效条件等于留痕 after 时，四槽合成非空则 rewrite 否则 drop，不等则 conflict；items 受 limit 限制；返回 dry_run rep。
 def fix_conditions_plan(x, prefix=None, limit=None) -> dict:
     """预演：清洗存量单槽冒充行。不写盘。
 
@@ -1054,6 +1085,7 @@ def fix_conditions_plan(x, prefix=None, limit=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 FIX_BATCH_DEFAULT；先 fix_conditions_plan 得 items，按 ids/entry_ids 过滤；逐个再验当前值仍等于 before 且 comment_before 一致，否则 skipped_drift；rewrite 时 upsert 生效条件行并写 comment，drop 时删行并还原 comment；写盘记 condition_fix，drop 另记 condition_pending；limit 限制 rewritten+dropped；返回 rep。
 def fix_conditions_apply(x, ids=None, entry_ids=None, prefix=None, limit=None,
                          batch=FIX_BATCH_DEFAULT, actor=None) -> dict:
     """执行清洗：`rewrite` 改写为四槽合成声明；`drop` 删行并登记待补。
@@ -1144,6 +1176,7 @@ def fix_conditions_apply(x, ids=None, entry_ids=None, prefix=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg，读取日志中 action=condition_fix 且未回滚的记录，按 batch/entry_ids 过滤，节点存在且当前生效条件等于 after 时，还原 before（空则删行）并还原 comment_before，否则计 conflict/missing；返回 rep。
 def fix_conditions_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """按留痕反向应用：恢复被改写的旧值 / 重建被删除的冒充行。
 
@@ -1210,6 +1243,7 @@ def fix_conditions_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 prefix 过滤、内部层跳过，读取失败或加密跳过；对每个节点当前生效条件行，缺失计 absent，否则按 is_legacy_position_condition、等于 _condition_text 合成、等于 comment、其他分别计数，legacy_ids 受 limit 限制；返回 rep。
 def verify_conditions(x, prefix=None, limit=None) -> dict:
     """复算核对（只读）：生效条件行的来源分布 + 弱等价残留计数。
 
@@ -1264,6 +1298,7 @@ ACTIONS = ("backfill", "backfill_rollback", "backfill_history",
            "exempt", "exempt_rollback", "exempt_history")
 
 
+# 生效条件：按其 action 分派——action=='backfill' 时 kw['apply'] 为真调 apply(x, 去掉 apply 的 kw)、否则调 plan 同参；action=='cap'/'exempt' 同理在 kw['apply'] 为真时调 cap_apply/exempt_apply、否则调 cap_plan/exempt_plan；action=='backfill_rollback'/'cap_rollback'/'exempt_rollback' 分别调 rollback/cap_rollback/exempt_rollback(x, **kw)；action=='backfill_history' 调 history(x, **kw)，'cap_history'/'exempt_history' 调 history(x, action='cap'/'exempt', **kw)；其余 action 值抛 ValueError。
 def run(x, action, **kw) -> dict:
     """`maintain` op 的分派入口：action ∈ ACTIONS。"""
     if action == "backfill":
@@ -1290,4 +1325,4 @@ def run(x, action, **kw) -> dict:
         return exempt_rollback(x, **kw)
     if action == "exempt_history":
         return history(x, action="exempt", **kw)
-    raise ValueError(f"未知 backfill action：{action}（允许：{ACTIONS}）")
+    raise ValueError(f"未知 backfill action：{action}（允许：{ACTIONS}）")

package/md_cg/backfill_bigdomain.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""big_domain 域标签回填（S1 大域收敛的前置元数据；幂等、支持 --dry-run）。
+
+用法：
+  python -X utf8 -m md_cg.backfill_bigdomain --root <库根> [--dry-run] [--limit N]
+
+为何需要单独的回填入口：域标签是**写入侧**新增的元数据，存量节点没有；
+S1 要按域收敛，就必须先把存量补齐（契约 §8.1）。
+"""
+import argparse
+import json
+import sys
+
+from .mdcg import MdCG
+
+
+# 生效条件：无条件解析参数（root 必填，dry_run/limit 可选）、以 MdCG(root) 打开库、调用 backfill_big_domain 并把统计 dict 以 JSON 打印，返回 0。
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True, help="库根目录")
+    ap.add_argument("--dry-run", action="store_true", dest="dry_run",
+                    help="只统计不改盘")
+    ap.add_argument("--limit", type=int, default=None, help="最多补写多少个节点")
+    a = ap.parse_args(argv)
+    cg = MdCG(a.root)
+    st = cg.backfill_big_domain(dry_run=a.dry_run, limit=a.limit)
+    print(json.dumps(st, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())

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