@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/docindex.py

@@ -58,6 +58,7 @@ DEFAULT_SENSITIVITY = "internal"
 PRIVATE_HINTS = ("private", "secret", "internal", "未公开", "私有", "内部")
 
 
+# 生效条件：override 为真值即返回 (override, "调用方显式指定")；否则 path（假值按 ""）按 "\" 与 "/" 分段，任一段小写含 PRIVATE_HINTS 中任一提示即返回 ("private", 路径段命中理由)，全部不命中返回 (DEFAULT_SENSITIVITY, 默认密级理由)；
 def sensitivity_for(path, override=None):
     """返回 (密级, 依据)。override 优先；否则按路径段保守降级。
 
@@ -81,6 +82,7 @@ _FENCE = re.compile(r"^\s*(```+|~~~+)")
 _ATX = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
 
 
+# 生效条件：lines 非空且 lines[0].strip() == "---" 时，从下标 1 起找到首个 strip() == "---" 的行并返回其后一行下标 i+1；lines 为空、首行不是 "---" 或找不到闭合 "---" 时返回 0；
 def _body_start(lines):
     """跳过开头 YAML frontmatter，返回正文起始行下标（0 基）。"""
     if lines and lines[0].strip() == "---":
@@ -90,6 +92,7 @@ def _body_start(lines):
     return 0
 
 
+# 生效条件：从 start（默认 0）遍历 lines，未处于围栏时遇 _FENCE 匹配行打开同标记围栏、围栏内遇同标记行关闭并继续；围栏外 _ATX 匹配行追加 {level: 一级 # 个数, title: 去空白后的标题, lineno: i+1}；返回 out 列表；start 不小于 len(lines) 时返回空列表；
 def _headings(lines, start=0):
     """产出 ATX 标题 `{level,title,lineno}`；**围栏代码块内的 `#` 不算标题**。"""
     out, fence = [], None
@@ -112,6 +115,7 @@ def _headings(lines, start=0):
     return out
 
 
+# 生效条件：title 真值时取其 strip 后小写，删去 `*[]() 与除 \w\s- 外字符，再把空白/下划线连成 "-" 并 strip("-")；title 为假值（含 None、空串）时按空串处理并返回 ""；
 def _anchor(title):
     a = (title or "").strip().lower()
     a = re.sub(r"`|\*|\[|\]|\(|\)", "", a)
@@ -119,6 +123,7 @@ def _anchor(title):
     return re.sub(r"[\s_]+", "-", a).strip("-")
 
 
+# 生效条件：region_lines 逐行 strip 后跳过空行与 "---"，去掉行首 #+ 和 >|*- 标记，以空格连接成 text；返回 text[:limit]（limit 默认 MAX_SUMMARY；limit=0 返回 ""，limit=None 返回全文，limit='' 时切片抛 TypeError，负 limit 按负索引切片）；
 def _summary(region_lines, limit=MAX_SUMMARY):
     """把一段正文压成一行摘要（去 markdown 噪声，不逐字保留）。"""
     parts = []
@@ -133,6 +138,7 @@ def _summary(region_lines, limit=MAX_SUMMARY):
     return text[:limit]
 
 
+# 生效条件：以 heads[i]["level"]-1 为需匹配层级向前回溯，返回按层级递减补齐的祖先标题列表（不含 heads[i] 自身）。
 def _path_titles(heads, i):
     """第 i 个标题的祖先链（不含自身），按层级补齐。"""
     out, need = [], heads[i]["level"] - 1
@@ -145,11 +151,13 @@ def _path_titles(heads, i):
     return out
 
 
+# 生效条件：直接以 lines、lineno、end 调用 codeindex.region_hash 并返回其结果；
 def _region_hash(lines, lineno, end):
     # 唯一实现复用 codeindex.region_hash：两侧各写一份，漂移检测会悄悄失效。
     return codeindex.region_hash(lines, lineno, end)
 
 
+# 生效条件：ext = suffix 真值时原样使用的 suffix，否则取 os.path.splitext(path)[1].lower()；ext 不在 SUFFIX 时抛 ValueError；在 SUFFIX 时把 source 按 "\n" 拆分，经 _body_start 与 _headings 得到标题，仅 level<=MAX_LEVEL 且非 small 的标题生成条目，小/过深子节摘要并入父摘要，返回 items；
 def extract(source, path="", suffix=None):
     """抽取一份 md 的章节条目；按后缀分派。返回条目列表（可能为空）。
 
@@ -213,6 +221,7 @@ def extract(source, path="", suffix=None):
 # --------------------------------------------------------------------------
 # 渲染 / id
 # --------------------------------------------------------------------------
+# 生效条件：item.get("path") 缺键或为假值时 path 取 ""，top 取 path.split("/")[0] or "."（故空 path 时 top="."）；path 为真值时 top 取其 "/" 前首段，首段为空则 top="."；返回含 observation_position（大域=top）、time_window（[nodefile.FULL_TIME_WINDOW_MIN, nodefile.FULL_TIME_WINDOW_MAX]）、observation_tool、existence_constraint（以 path 拼入）的四槽字典；
 def condition_space(item):
     """章节条目 → 条件空间四槽（纯函数，**唯一来源**）。
 
@@ -237,6 +246,7 @@ def condition_space(item):
     }
 
 
+# 生效条件：item 含 heading、path、lineno、end、anchor 键时渲染 7 行 CCG 文本（第2行取 condition_space(item) 文本），item.get("parent") 或 "" 假值回落 "（顶层章节）"，item.get("summary_parts") 假值回落 "（该节无直接正文，见子节）"，item.get("children") 假值回落空列表且不追加子节行，children 非空时追加 "# 子节：" + 前 12 个；返回以 "\n" 连接的行串；
 def render(item):
     """章节条目 → CCG 6 行正文（可被 search 命中，不含全文）。
 
@@ -265,6 +275,7 @@ def render(item):
     return "\n".join(lines)
 
 
+# 生效条件：以 item["path"] + "#" + "/".join(item["heading_path"]) 为 key，item.get("dup", 1)（缺键取 1）大于 1 时追加 "#" + item["dup"]，返回 "doc_" + sha1(key utf-8) hexdigest 前 12 位；
 def node_id(item):
     """稳定 id：path#heading_path 的短哈希（重复索引幂等；同名用 dup 区分）。"""
     key = item["path"] + "#" + "/".join(item["heading_path"])
@@ -273,6 +284,116 @@ def node_id(item):
     return "doc_" + hashlib.sha1(key.encode("utf-8")).hexdigest()[:12]
 
 
+# ==========================================================================
+# fence 真源绑定（§3.5）：条件卡 ↔ Markdown 真源的「往返列」
+#
+# 往返列 = 真源（root + path）+ 定位（anchor / heading_path）+ 行位（lineno/end）
+# + 校验（hash）。**行位是易腐化量，键不含行位**：在章节上方插一段话会让整篇行号
+# 位移，但键 `path#heading_path` 不变——故「同一章节」的匹配一律走键，行位只用于
+# 回读原文与漂移判定。写侧唯一入口是 `refindex._doc_ref`（与索引同源，避免第二份
+# 列口径）；本节只补读侧：取列 / 校验 / 造键 / 反查行位。
+#   · 正向：卡片 → 真源（`doc_ref.lineno/end` + `refindex.read_ref` 回读原文区间）
+#   · 反向：真源行 → 卡片（`locate`；对账器 `--at path:line` 即此接口）
+# ==========================================================================
+
+#: 必需列：真源（root/path）+ 定位（anchor）+ 行位（lineno/end）+ 校验（hash）
+BINDING_FIELDS = ("root", "path", "anchor", "lineno", "end", "hash")
+#: 附加列：有则参与更精确匹配与人读，缺省不算绑定失败
+BINDING_OPTIONAL = ("heading_path", "heading", "level", "lang", "precise")
+
+
+# 生效条件：node 为 cg.get 产物（含 frontmatter 子字典）或 frontmatter dict 本身，且其 doc_ref 为 dict 时，返回按 BINDING_FIELDS + BINDING_OPTIONAL 投影的列值 dict（缺列以 None 占位）；非 dict / 无 doc_ref 返回 None。
+def binding_of(node):
+    """取一条条件卡的往返列；**非索引节点返回 None**（不猜、不补默认值）。"""
+    fm = node
+    if isinstance(node, dict) and isinstance(node.get("frontmatter"), dict):
+        fm = node["frontmatter"]
+    if not isinstance(fm, dict):
+        return None
+    ref = fm.get("doc_ref")
+    if not isinstance(ref, dict) or not ref:
+        return None
+    return {k: ref.get(k) for k in BINDING_FIELDS + BINDING_OPTIONAL}
+
+
+# 生效条件：b 为 dict 且 heading_path 为非空 list/tuple 时返回 path#join(heading_path, '/')，否则回落 path#anchor；b 非 dict 返回空串。
+def binding_key(b):
+    """稳定键 `path#heading_path`：**不含行位**（真源重排只动行位、不动键）。"""
+    if not isinstance(b, dict):
+        return ""
+    path = str(b.get("path") or "")
+    hp = b.get("heading_path")
+    if isinstance(hp, (list, tuple)) and hp:
+        return path + "#" + "/".join(str(x) for x in hp)
+    return path + "#" + str(b.get("anchor") or "")
+
+
+# 生效条件：b 为 dict 时返回 'path#anchor'（与 render 正文里的「本条目属于」逐字同源）；非 dict 返回空串。
+def binding_slug(b):
+    """人读定位串 `path#anchor`——与 `render` 正文里的「本条目属于」同源。"""
+    b = b if isinstance(b, dict) else {}
+    return f"{b.get('path') or ''}#{b.get('anchor') or ''}"
+
+
+# 生效条件：b 为 dict 时逐列校验（缺列 / 类型错 / 行位越界），返回 {"ok": bool, "issues": [str, ...]}；**不抛异常**——对账要逐条报告，不能因一条坏数据中断全库；行位仅在列齐且类型对时才判，避免级联噪声。
+def validate_binding(b):
+    """校验往返列形状。**不抛异常**：对账逐条报告，不能一条坏数据中断全库。"""
+    if not isinstance(b, dict):
+        return {"ok": False, "issues": ["绑定不是字典（该节点无 doc_ref）"]}
+    issues = []
+    for k in BINDING_FIELDS:
+        if b.get(k) in (None, ""):
+            issues.append(f"缺列 {k}")
+    for k in ("root", "path", "anchor", "hash"):
+        v = b.get(k)
+        if v not in (None, "") and not isinstance(v, str):
+            issues.append(f"{k} 应为字符串，实为 {type(v).__name__}")
+    if not issues:
+        try:
+            lo, hi = int(b["lineno"]), int(b["end"])
+        except (TypeError, ValueError):
+            issues.append("行位不是整数")
+        else:
+            if lo < 1:
+                issues.append(f"lineno 越界（{lo} < 1）")
+            if hi < lo:
+                issues.append(f"end 早于 lineno（{lo}-{hi}）")
+    return {"ok": not issues, "issues": issues}
+
+
+# 生效条件：old/new 任意为 dict 或假值；按 (path, anchor, heading_path, lineno, end, hash) 固定顺序返回取值不同的列名列表（空列表=同一章节同一行位），任一侧假值按空 dict 处理。
+def binding_drift(old, new):
+    """旧往返列 vs 新往返列 → 变化列名（顺序固定，供报告与测试断言）。"""
+    old, new = old if isinstance(old, dict) else {}, new if isinstance(new, dict) else {}
+    return [k for k in ("path", "anchor", "heading_path", "lineno", "end", "hash")
+            if old.get(k) != new.get(k)]
+
+
+# 生效条件：items 为 extract 产出的条目序列、lineno 可转 int；返回覆盖该行的条目中 **lineno 最大者**（嵌套即最内层，h3 优于其父 h2）；不可转值或无可覆盖条目返回 None。
+def locate(items, lineno):
+    """反向定位：真源第 `lineno` 行 → 覆盖它的条目（嵌套取**最内层**）。
+
+    区间闭合：标题行算本节；多层嵌套时取 `lineno` 最大者即最内层。
+    """
+    try:
+        ln = int(lineno)
+    except (TypeError, ValueError):
+        return None
+    hit = None
+    for it in items or []:
+        lo, hi = it.get("lineno"), it.get("end")
+        if lo is None or hi is None:
+            continue
+        try:
+            lo, hi = int(lo), int(hi)
+        except (TypeError, ValueError):
+            continue
+        if lo <= ln <= hi and (hit is None or lo > int(hit["lineno"])):
+            hit = it
+    return hit
+
+
+# 生效条件：以 root 为根 os.walk，patterns 假值回落 SUFFIX；files 达到 max_files 或 items 达到 max_items 时提前返回并置 stats["truncated"]/truncated_reason；fresh 非 None 且 fresh(rel, fp) 为真时跳过该文件读盘并计 skipped_unchanged；on_file 非 None 且 open/extract 成功后以 (rel, fp, got) 回调；名字在 SKIP_DIRS 的目录仅剪枝不记录，skip_dirs 经 codeindex.skip_matcher 命中的目录剪枝并记入 stats["skipped_dirs"]；返回 (items, errors, stats)。
 def index_dir(root, patterns=None, max_files=500, max_items=2000,
               fresh=None, on_file=None, skip_dirs=None):
     """按大域（目录）遍历 md，产出 `(items, errors, stats)`。零 LLM。
@@ -350,4 +471,4 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
                 return items, errors, stats
     stats["files"] = files
     stats["skipped_suffixes"] = sorted(s for s in seen_suffix if s and s not in pats)[:12]
-    return items, errors, stats
+    return items, errors, stats

package/md_cg/eval_common.py

@@ -58,14 +58,16 @@ PATHS = ("lexical", "bucket", "entity", "graph")   # 引擎默认四路 RRF
 PATHS_CAL = PATHS + ("semantic",)   # 口径 B：显式启用条件结构路（负路由所在）
 
 
+# 生效条件：仅评测口径调用（主库不调用）；必须双改 md_cg.mdcg 与 md_cg.mdcos 两份 from-import 的同名值（漏改其一即静默失效），置为 10**9；无返回值、不落盘；
 def unlock_global_cap():
     """评测口径：解除 GLOBAL_CAP 截断（bench_membench patch_lexical_full 同法）。
 
-    默认 GLOBAL_CAP=500 会把 LIKE 预筛命中按「插入序」截到前 500 条再打分；
-    大型英文语料（turn 高度互相似）预筛命中数千条 → 证据 turn 被插入序随机
-    截掉，检索质量混入插入序 lottery（sanity：证据原文自检索仅 10% hit@1）。
-    评测主口径解除之，只测排序质量。mdcg 与 mdcos 各持一份 from-import 值，
-    必须双改（test_p43_pooling 先例）。
+    【2026-09-16 后语义更新】截断依据已由「插入序」改为「相关度」（`mdcg
+    .cut_by_relevance` 与 `mdcos._lexical` 均先全量打分再排序截断，cap 值仍
+    500）——插入序 lottery 已消除。评测仍解除 cap 的理由只剩一条：避免
+    「按相关度截掉尾部」在长语料上压低召回天花板（相近似 turn 数千条时，
+    排 501 名之后仍可能是证据）——评测要测**排序质量**而非截断策略。
+    mdcg 与 mdcos 各持一份 from-import 值，必须双改（test_p43_pooling 先例）。
     """
     import md_cg.mdcg as m
     import md_cg.mdcos as mo
@@ -73,6 +75,7 @@ def unlock_global_cap():
     mo.GLOBAL_CAP = 10 ** 9
 
 
+# 生效条件：仅评测口径调用（短条目语料下 jaccard 会退化）；把 md_cg.mdcg.SCORE_MODE 置为 "jaccard"（mdcos 读同一份、无需双改）；无返回值、不落盘；
 def use_jaccard():
     """评测口径：词法打分切 jaccard（对称归一化，长度自惩罚）。
 
@@ -93,6 +96,7 @@ def use_jaccard():
     m.SCORE_MODE = "jaccard"
 
 
+# 生效条件：对 path 调用 open(path, encoding="utf-8") 后逐行读取，仅对 strip 后非空的 line yield json.loads(line)；
 def iter_jsonl(path):
     with open(path, encoding="utf-8") as f:
         for line in f:
@@ -101,6 +105,7 @@ def iter_jsonl(path):
                 yield json.loads(line)
 
 
+# 生效条件：ds 等于 "lm" 时 path=LM_Q，否则 path=LC_Q；先由 iter_jsonl(path) 取全部 rows，再仅当 qtypes 为真值时保留 r["qtype"] 在 qtypes 中的行（qtypes 为 None/空串/空容器等假值则不过滤）；
 def load_questions(ds, qtypes=None):
     """ds: 'lm' | 'lc'。qtypes 过滤题型（None=全部）。"""
     path = LM_Q if ds == "lm" else LC_Q
@@ -110,6 +115,7 @@ def load_questions(ds, qtypes=None):
     return rows
 
 
+# 生效条件：对 rows/n（seed 默认 7），若 not n 或 n >= len(rows) 则原样返回 rows，否则返回 random.Random(seed).sample(rows, n)；
 def sample_questions(rows, n, seed=7):
     if not n or n >= len(rows):
         return rows
@@ -118,12 +124,14 @@ def sample_questions(rows, n, seed=7):
 
 # ------------------------------------------------------------------ 建库
 
+# 生效条件：对 t，若 t.get("speaker") 为真值则返回 f"{t['speaker']}: {t['text']} [{t['date']}]"，否则返回 f"{t['text']} [{t['date']}]"；
 def lm_turn_text(t):
     """LongMemEval turn → 入库文本（日期内联，词法路可召回时间词）。"""
     return f"{t['speaker']}: {t['text']} [{t['date']}]" if t.get("speaker") \
         else f"{t['text']} [{t['date']}]"
 
 
+# 生效条件：对 r，若 r.get("title") 为真值则返回 f"{r['text']} [{r['title']}]"，否则返回 r["text"]；
 def lc_turn_text(r):
     """LoCoMo turn → 入库文本（title 含 Data time 时间戳，内联保序）。"""
     return f"{r['text']} [{r['title']}]" if r.get("title") else r["text"]
@@ -146,6 +154,7 @@ _STOP_HEADS = frozenset(
 _NEG_MARKS = ("n't", " not ", " never ", "nobody", "nothing", "no one", "none of")
 
 
+# 生效条件：对 text（limit 默认 4），按正则收集非 _STOP_HEADS 开头的大写词与 4 位年/时刻/日期数字并去重后，返回前 limit 项；
 def _extract_entities(text, limit=4):
     """确定性实体近似：连续大写词（人名/地名）+ 日期/时间数字。只读 turn 正文。
     纯数字编号（"1."）不是实体——只保留年份/时刻/日期形态，否则列表编号会
@@ -161,6 +170,7 @@ def _extract_entities(text, limit=4):
     return ents[:limit]
 
 
+# 生效条件：对 title，若 title 为假值则返回空串，否则按 YYYY-MM-DD、英文星期日期、d/d/d 三个正则顺序取首个匹配串，无匹配返回空串；
 def _date_tag(title):
     """从 title 抽规范化日期串做 tag。整段 title 入 tags 会污染实体路
     （_path_entity 的 `query in t` 方向：长 tag 是误报源）。"""
@@ -173,6 +183,7 @@ def _date_tag(title):
     return m.group(0) if m else ""
 
 
+# 生效条件：r 为语料 turn 行（缺 text/role 等键时按空串处理）；date_key/title_key 为 None 时对应日期取空串；返回 (CCG 五要素正文, tags, condition_space) 三元组，仅当原文出现强否定标记才生成不适用条件、否则显式写「（无）」；
 def calibrate_turn(r, date_key=None, title_key=None):
     """turn 行 → (CCG 五要素正文, tags, condition_space)。
 
@@ -225,10 +236,12 @@ def calibrate_turn(r, date_key=None, title_key=None):
     return body, tags, cond_space
 
 
+# 生效条件：任意 t 与可选 ctx（默认 None）传入即原样转调 calibrate_turn(t, date_key="date", ctx=ctx)，返回其结果；
 def calibrate_lm_turn(t, ctx=None):
     return calibrate_turn(t, date_key="date", ctx=ctx)
 
 
+# 生效条件：任意 r 与可选 ctx（默认 None）传入即原样转调 calibrate_turn(r, title_key="title", ctx=ctx)，返回其结果；
 def calibrate_lc_turn(r, ctx=None):
     return calibrate_turn(r, title_key="title", ctx=ctx)
 
@@ -238,6 +251,7 @@ def calibrate_lc_turn(r, ctx=None):
 # 指代消解，把语料加工成可沿链行走的形态。以下三步全部是**确定性规则近似**
 # （纯标准库、盲于查询集、随报告公开词表），不引入任何模型依赖。
 
+# 生效条件：对 corpus_path（min_df 默认 3），逐行取 text=str(r.get("text") or "")、spk=str(r.get("speaker") or "").strip()，以 {spk}（spk 真值）或空集合并入正文大写词首词（排除 _STOP_HEADS）更新 df 计数，最后返回计数 >= min_df 的词集合；
 def build_canon(corpus_path, min_df=3):
     """离线实体规范化：全语料扫一遍，聚合大写词/人名的文档频次（df）。
     df≥min_df 的是 canonical 实体（会话成员 + 高频专名）——单 turn 局部抽取
@@ -267,11 +281,13 @@ _INTENT_HEADS = ("plan", "going to", "thinking of", "thinking about", "want to",
                  "prefer", "favorite", "love", "hate", "enjoy")
 
 
+# 生效条件：对 text 小写并前后加空格得到 low，返回 _INTENT_HEADS 中满足 f" {h}" 出现在 low 的项；
 def _intent_of(text):
     low = f" {text.lower()} "
     return [h for h in _INTENT_HEADS if f" {h}" in low]
 
 
+# 生效条件：r 为语料 turn 行；ctx 为写入时全库视图（canon/intents/last_canon），ctx 为 None 时按空视图处理并退化为 v2 行为；返回 (CCG 五要素正文, tags, condition_space) 三元组；
 def calibrate_turn(r, date_key=None, title_key=None, ctx=None):
     """turn 行 → (CCG 五要素正文, tags, condition_space)。
 
@@ -335,6 +351,7 @@ def calibrate_turn(r, date_key=None, title_key=None, ctx=None):
     return body, tags, cond_space
 
 
+# 生效条件：rebuild=True 且 os.path.isdir(root) 时先 rmtree(root)；cg_cls 为假值（如 None）时回落 MdCGOS(root, autoflush=500)；语料行数 n_rows ≤ cg.index["nodes"] 现有节点数（n_rows=0 的空语料也满足）时直接复用返回 cg；否则逐行写入——calib_of 为真走标定口径 B（先 build_canon，calib_of(r, {"canon": canon, "last_canon": last_canon}) 取 body/tags/condition_space），calib_of 为假（含 None）走 legacy 口径 A（用 text_of(r)），id 已在 cg.index["nodes"] 的行跳过，verbose 为真时每 20000 行打印进度，循环后 cg.flush() 再返回 cg；
 def build_eval_cg(cg_cls, root, corpus_path, text_of, src_tag, verbose=True,
                   calib_of=None, rebuild=False):
     """幂等建库：节点数已达语料行数则直接复用。返回 cg（不 flush 句柄）。
@@ -388,11 +405,13 @@ def build_eval_cg(cg_cls, root, corpus_path, text_of, src_tag, verbose=True,
     return cg
 
 
+# 生效条件：对传入 cg，用闭包 cache（键为 entry["path"]）包装其原 cg._read 并赋回 cg._read，返回该 cache；仅当 p = entry["path"] 不在 cache 时调用 orig(entry) 并缓存其（含假值）结果，p 已在 cache 中时直接返回缓存值；
 def install_read_cache(cg):
     """评测只读：节点文件读进内存，避免逐次检索重复磁盘 I/O。"""
     cache = {}
     orig = cg._read
 
+# 生效条件：entry["path"] 未在闭包 cache 中时调用 orig(entry) 存入并返回，已在 cache 中则直接返回缓存值（cache 与原 _read 由外层 install_read_cache 提供）；
     def _cached(entry):
         p = entry["path"]
         if p not in cache:
@@ -405,6 +424,7 @@ def install_read_cache(cg):
 
 # ------------------------------------------------------------------ 检索与指标
 
+# 生效条件：对 cg/query（k 默认 5、paths 默认 PATHS、judge 默认 False），若 fusion 为真值则加入 kw["fusion"]，若 path_weights 为真值则加入 kw["path_weights"]，若 context is not None（含空 dict/空串）则加入 kw["context"]，再调用 cg.search_rrf(...)；
 def run_query(cg, query, k=5, paths=PATHS, judge=False, fusion=None,
               path_weights=None, context=None):
     """单查询，返回 (结果四元组列表, meta)。
@@ -425,6 +445,7 @@ def run_query(cg, query, k=5, paths=PATHS, judge=False, fusion=None,
     return cg.search_rrf(query, k=k, paths=paths, judge=judge, record=False, **kw)
 
 
+# 生效条件：当 evidence 为真值且 res 中某 r 的 r[0]["id"] 属于 evidence 时返回首个 1-based 排名，否则（evidence 为假值或未命中）返回 0；
 def first_evidence_rank(res, evidence):
     """首个证据 turn 的排名（1-based；未命中 0）。"""
     if not evidence:
@@ -435,6 +456,7 @@ def first_evidence_rank(res, evidence):
     return 0
 
 
+# 生效条件：对 questions 中每个 it，若 context_of 为真值则 ctx=context_of(it) 否则 ctx=None；以 k/paths/judge/fusion/path_weights 调用 run_query，按 evidence_turns 算 first_evidence_rank，收集 qid/qtype/rank/top1_score/n_res 行，返回 rows；
 def evaluate_group(cg, questions, k=5, paths=PATHS, judge=False, verbose=True,
                    fusion=None, path_weights=None, context_of=None):
     """一组题 → per-question 明细行。负例组传 judge=False（拒答看分数线）。
@@ -461,6 +483,7 @@ def evaluate_group(cg, questions, k=5, paths=PATHS, judge=False, verbose=True,
     return rows
 
 
+# 生效条件：当 rows 为真值时按 k（默认 5）计算 hit@1、hit@k、MRR、score_p10/p50 及 by_qtype 指标，否则返回 {"n": 0}；
 def summarize(rows, k=5):
     """hit@1 / hit@K / MRR + 分题型。score_p10 供拒答线校准。"""
     if not rows:
@@ -491,6 +514,7 @@ def summarize(rows, k=5):
     return out
 
 
+# 生效条件：当 rows 非空时按 r["top1_score"] < line 统计拒答数并返回拒绝率，否则返回 {"n": 0}；
 def refusal_metrics(rows, line):
     """负例组：Top-1 分 < line 记为拒答。返回拒答率与明细统计。"""
     n = len(rows)
@@ -501,6 +525,7 @@ def refusal_metrics(rows, line):
             "refused": ref, "line": line}
 
 
+# 生效条件：当 rows 非空时返回 r["top1_score"] < line 的行占比，否则返回 0.0；
 def false_refusal_rate(rows, line):
     """正例误杀（被错误拒答的正例比例）：正例 Top-1 分 < line。"""
     n = len(rows)
@@ -509,6 +534,7 @@ def false_refusal_rate(rows, line):
     return sum(1 for r in rows if r["top1_score"] < line) / n
 
 
+# 生效条件：当 pos_rows 中存在 rank==1 的行时，返回这些行 top1_score 升序后 max(0, len//10) 索引处的值，否则返回 0.0；
 def calibrate_line(pos_rows):
     """拒答线 = 正例 hit@1 题 Top-1 分的 10 分位。"""
     scores = sorted(r["top1_score"] for r in pos_rows if r["rank"] == 1)
@@ -517,6 +543,7 @@ def calibrate_line(pos_rows):
     return scores[max(0, len(scores) // 10)]
 
 
+# 生效条件：当 name/payload 给出时，确保 RESULTS 目录（os.makedirs(RESULTS, exist_ok=True)），将 payload 以 ensure_ascii=False、indent=2 写入 RESULTS/name 并返回 path；
 def save_result(name, payload):
     """评测结果 JSON 落盘（报告数据源）。"""
     os.makedirs(RESULTS, exist_ok=True)
@@ -527,6 +554,7 @@ def save_result(name, payload):
     return path
 
 
+# 生效条件：对 groups（k 默认 5），若某组 s 的 s.get("n") 为假（缺 n 或 n=0）则打印 0 行并跳过，否则按 s["hit@1"]、s[f"hit@{k}"]、s["mrr"] 打印并遍历 s.get("by_qtype", {}) 输出子行；
 def print_table(title, groups, k=5):
     """groups: {组名: summarize 输出}。"""
     print(f"\n== {title}（证据命中口径，k={k}）==")
@@ -543,5 +571,6 @@ def print_table(title, groups, k=5):
                   f"{st[f'hit@{k}']:>9.1%}{st['mrr']:>8.3f}")
 
 
+# 生效条件：对任意 x，返回 f"{x * 100:.1f}%" 的百分比字符串；
 def pct(x):
-    return f"{x * 100:.1f}%"
+    return f"{x * 100:.1f}%"

package/md_cg/evidence.py

@@ -62,22 +62,27 @@ class EvidenceError(Exception):
 # 路径与身份
 # --------------------------------------------------------------------------
 
+# 生效条件：当传入 path 为真值时返回 path；否则若环境变量 SWARM_DIR_ENV 为真值则返回其值；否则返回模块级常量 DEFAULT_SWARM_DIR。
 def swarm_dir(path: str = None) -> str:
     return path or os.environ.get(SWARM_DIR_ENV) or DEFAULT_SWARM_DIR
 
 
+# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "peers")。
 def peers_dir(swarm: str = None) -> str:
     return os.path.join(swarm_dir(swarm), "peers")
 
 
+# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "inbox")。
 def inbox_dir(swarm: str = None) -> str:
     return os.path.join(swarm_dir(swarm), "inbox")
 
 
+# 生效条件：当传入 root 为真值时返回 root；否则返回环境变量 ROOT_ENV 的值（可能为 None）。
 def _root_of(root: str = None) -> str:
     return root or os.environ.get(ROOT_ENV)
 
 
+# 生效条件：当 explicit 或环境变量 NODE_ID_ENV strip 后非空时返回该值；否则若 _root_of(root) 返回真值，返回基于规范绝对路径的 'node-<12hex>'；否则抛出 EvidenceError。
 def node_id(root: str = None, explicit: str = None) -> str:
     """本节点身份。
 
@@ -95,6 +100,7 @@ def node_id(root: str = None, explicit: str = None) -> str:
     return "node-" + hashlib.sha256(key.encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：包内 md_cg.theory 可导入且 _th.check() 成功时返回 {version, accepted, theory_ok}；任何异常（版本层缺失或校验失败）一律吞掉返回 {}，不阻断证据层主流程；
 def _theory_state() -> dict:
     try:
         from . import theory as _th
@@ -106,11 +112,13 @@ def _theory_state() -> dict:
         return {}
 
 
+# 生效条件：当传入 obj 时，返回其 json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(',',':')).encode("utf-8") 字节。
 def _canon(obj) -> bytes:
     return json.dumps(obj, ensure_ascii=False, sort_keys=True,
                       separators=(",", ":")).encode("utf-8")
 
 
+# 生效条件：当传入 s 时，返回 str(s) 中每个字符若为字母数字或 '_' '-' 则保留，否则替换为 '_' 的字符串。
 def _slug(s) -> str:
     return "".join(ch if (ch.isalnum() or ch in "_-") else "_" for ch in str(s))
 
@@ -119,6 +127,7 @@ def _slug(s) -> str:
 # 节点名片（发现）
 # --------------------------------------------------------------------------
 
+# 生效条件：当传入 root、subsystem（默认常量 SUBSYSTEM）、signers_file 时，基于 _signer.policy_for 和 _signer.get_signer 返回名片字典，其中 root 为 os.path.abspath(_root_of(root)) 若 _root_of(root) 真值否则 None。
 def card(root: str = None, *, subsystem: str = SUBSYSTEM,
          signers_file: str = None) -> dict:
     """本节点名片：身份 + 版本 + 签名器公开信息（**不含密钥**）。"""
@@ -139,6 +148,7 @@ def card(root: str = None, *, subsystem: str = SUBSYSTEM,
     }
 
 
+# 生效条件：当传入 root、swarm、subsystem（默认常量 SUBSYSTEM）、signers_file 时，调用 card 得到 c，将 c 以 JSON 写入 peers_dir(swarm)/<c["node_id"]>.json，返回 {"ok": True, "file": p, "card": c}。
 def publish_card(root: str = None, *, swarm: str = None,
                  subsystem: str = SUBSYSTEM, signers_file: str = None) -> dict:
     """把本节点名片写入共享目录 `peers/<node_id>.json`（0600）。"""
@@ -148,6 +158,7 @@ def publish_card(root: str = None, *, swarm: str = None,
     return {"ok": True, "file": p, "card": c}
 
 
+# 生效条件：当 peers_dir(swarm) 是目录时，遍历其中 .json 文件，加载为 dict 且 kind 等于常量 CARD_KIND 的名片，若 exclude_self 为真则排除 node_id 等于 node_id(root) 的名片（node_id(root) 抛 EvidenceError 时 self_id 为 None 不排除），返回按文件名排序的列表及计数；目录不存在则返回空列表。
 def peers(swarm: str = None, *, exclude_self: bool = True,
           root: str = None) -> dict:
     """发现共享目录里的对端名片（按 node_id 排序）。"""
@@ -183,6 +194,7 @@ _PACK_FIELDS = ("schema", "kind", "pack_id", "from_node", "from_root",
                 "theory", "created_at", "subjects", "items")
 
 
+# 生效条件：当传入 pack 字典时，返回仅含模块级常量 _PACK_FIELDS 中字段（缺失字段取 pack.get(k) 得到 None）的规范化 JSON 字节。
 def _pack_payload(pack: dict) -> bytes:
     """签名载荷：固定字段 + 排序序列化，同参数必同字节。"""
     body = {}
@@ -191,6 +203,7 @@ def _pack_payload(pack: dict) -> bytes:
     return _canon(body)
 
 
+# 生效条件：当传入 cg、subjects、since 时，遍历 cg.index["nodes"] 中按 node_id 排序的节点，仅收集标签含常量 TAG_OBS、不含 TAG_ANCHOR/TAG_TRAIT、不含 TAG_XNODE、能提取 subject: 标签且该 subject 在 subjects（subjects 为真时）或不限制（subjects 假值时）、且若 since 为真且 ts 为真则要求 float(ts) >= float(since) 的节点，返回含 node_id、subject、text（截断 MAX_TEXT）、kind、role、layer、过滤后的 tags、importance、verification_basis、ts 的列表。
 def _collect(cg, subjects=None, since=None) -> list:
     """收集本根**本地原始**观测证据（排除档案节点与已导入的跨节点证据）。"""
     want = set(subjects or [])
@@ -237,6 +250,7 @@ def _collect(cg, subjects=None, since=None) -> list:
     return items
 
 
+# 生效条件：当传入 cg、subjects、since、swarm、subsystem（默认 SUBSYSTEM）、signers_file、require_signature（默认 True）时，收集证据并截断至常量 MAX_ITEMS，用 _signer.sign_for 以常量 SIGN_ACTION 签名，若 require_signature 为真且签名未成功则抛出 EvidenceError，否则返回含 pack、count、truncated、signed 的字典。
 def export_pack(cg, *, subjects=None, since=None, swarm: str = None,
                 subsystem: str = SUBSYSTEM, signers_file: str = None,
                 require_signature: bool = True) -> dict:
@@ -275,6 +289,7 @@ def export_pack(cg, *, subjects=None, since=None, swarm: str = None,
             "truncated": truncated, "signed": pack["sig"]["signed"]}
 
 
+# 生效条件：当传入 pack、path、swarm 时，若 path 为假值则用 os.path.join(inbox_dir(swarm), f"{_slug(pack.get('from_node'))}__{pack.get('pack_id')}.json") 生成路径，将 pack 以 JSON 写入该路径并返回 {"ok": True, "file": path}。
 def write_pack(pack: dict, path: str = None, swarm: str = None) -> dict:
     """把证据包落盘到收件箱（或指定路径）。"""
     if not path:
@@ -288,6 +303,7 @@ def write_pack(pack: dict, path: str = None, swarm: str = None) -> dict:
 # 证据包：导入
 # --------------------------------------------------------------------------
 
+# 生效条件：当 src 是 dict 时直接返回 src；否则以 src 为路径打开 JSON 文件并返回 json.load(f)。
 def _read_pack(src) -> dict:
     if isinstance(src, dict):
         return src
@@ -295,6 +311,7 @@ def _read_pack(src) -> dict:
         return json.load(f)
 
 
+# 生效条件：当 pack 为 dict 且 kind 等于常量 KIND、int(pack.get("schema") or 0) 不大于常量 SCHEMA、from_node strip 后非空、items 为 list 时返回空字符串；否则按序返回对应错误字符串（非 dict、kind 不符、schema 过新、缺 from_node、缺 items）。
 def _validate(pack: dict) -> str:
     if not isinstance(pack, dict):
         return "证据包不是 JSON 对象"
@@ -309,10 +326,12 @@ def _validate(pack: dict) -> str:
     return ""
 
 
+# 生效条件：当传入 from_node 和 orig 时，返回 f"xnode_{_slug(from_node)}_{_slug(orig)}"。
 def _xnode_id(from_node: str, orig: str) -> str:
     return f"xnode_{_slug(from_node)}_{_slug(orig)}"
 
 
+# 生效条件：当传入 pack、reason、swarm、**kw 时，构建含 at、reason、from_node、pack_id 及 kw 中非 None 项的拒绝记录，尝试追加到 inbox_dir(swarm)/_rejected.jsonl（OSError 忽略），返回 {"ok": False, "rejected": True, "reason": reason, "from_node": ...} 并合并 kw 中非 None 项。
 def _note_reject(pack: dict, reason: str, swarm: str = None, **kw) -> dict:
     rec = {"at": time.time(), "reason": reason,
            "from_node": (pack or {}).get("from_node"),
@@ -330,6 +349,7 @@ def _note_reject(pack: dict, reason: str, swarm: str = None, **kw) -> dict:
     return out
 
 
+# 生效条件：当传入 cg、src、subsystem（默认 SUBSYSTEM）、swarm、signers_file、archive（默认 True）时，依次读取 src 为 pack、_validate 校验、来源 node_id 不等于本节点、_signer.verify_for 验签成功、且有签名或 signer 等于 "null" 方可通过；通过则对 pack["items"] 前常量 MAX_ITEMS 项中 subject/text 非空者以 _identity.observe 写入（带常量 TAG_XNODE 和 SOURCE_PREFIX 标签，importance 默认 0.5，verification_basis 默认 "data"），统计 written/skipped，若 archive 为真则写包到收件箱，返回含 ok、from_node、pack_id、imported、skipped、truncated、node_ids、archived 的字典；任一拒绝分支调用 _note_reject 返回拒绝结果。
 def import_pack(cg, src, *, subsystem: str = SUBSYSTEM, swarm: str = None,
                 signers_file: str = None, archive: bool = True) -> dict:
     """导入对端证据包：验签 → 落本根（带 `source:<node>` 标签）。
@@ -404,6 +424,7 @@ def import_pack(cg, src, *, subsystem: str = SUBSYSTEM, swarm: str = None,
 # 查询
 # --------------------------------------------------------------------------
 
+# 生效条件：当传入 cg、subject、source、limit（默认 100）时，收集标签含常量 TAG_XNODE 的节点，若 subject 为真则仅保留 subject 标签等于 subject 的节点，若 source 为真则仅保留 source 标签等于 source 的节点，返回最后 int(limit or 100) 条记录（limit 为假值如 0 时取 100）的 count 与列表。
 def evidence(cg, *, subject: str = None, source: str = None,
              limit: int = 100) -> dict:
     """列本根已导入的跨节点证据（按来源/主体过滤）。"""
@@ -432,6 +453,7 @@ def evidence(cg, *, subject: str = None, source: str = None,
     return {"count": len(out), "evidence": out}
 
 
+# 生效条件：无参数调用时返回包含模块级常量 SUBSYSTEM、SIGN_ACTION、SWARM_DIR_ENV、NODE_ID_ENV、ROOT_ENV、MAX_ITEMS、MAX_TEXT 及 swarm_dir() 等字段的自描述字典。
 def catalog() -> dict:
     return {
         "layer": "跨节点证据存储（蜂群互联 v0.3）",
@@ -453,6 +475,7 @@ def catalog() -> dict:
 # 工具
 # --------------------------------------------------------------------------
 
+# 生效条件：当传入 path 和 obj 时，在 path 所在目录（若 dirname 为空则 "."）创建目录，将 obj 以 JSON 写入 path+".tmp"（ensure_ascii=False, indent=1, sort_keys=True），尝试 chmod 0600，替换到 path，返回 path。
 def _write_json(path: str, obj) -> str:
     os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
     tmp = path + ".tmp"
@@ -466,6 +489,7 @@ def _write_json(path: str, obj) -> str:
     return path
 
 
+# 生效条件：当传入 root 且 _root_of(root) 返回真值时，以 designer 角色 Principal（tenant 取 os.environ.get("MDCG_TENANT", "default") 的实际值，actor 取 os.environ.get("MDCG_ACTOR", "swarm-cli") 的实际值）打开 MdCGSecure；否则抛出 EvidenceError。
 def _open_cg(root: str = None):
     """CLI 用：以 designer 身份打开根（令牌路径仍推荐走 MCP）。"""
     from .mdcos import MdCGSecure
@@ -483,10 +507,12 @@ def _open_cg(root: str = None):
     return MdCGSecure(r, principal=p)
 
 
+# 生效条件：当传入 obj 时，打印 json.dumps(obj, ensure_ascii=False, indent=1, default=str)。
 def _print(obj):
     print(json.dumps(obj, ensure_ascii=False, indent=1, default=str))
 
 
+# 生效条件：argv 为 None 时取 sys.argv[1:]；经 argparse 解析后必填子命令（catalog/card/export/import 等）之一，参数缺失或非法由 argparse 直接退出；返回进程退出码；
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.evidence",
@@ -552,4 +578,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())