@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/bench_task_ab_llm.py

@@ -134,6 +134,7 @@ for _c in CASES:
 
 
 # ---- LLM 客户端（OpenAI 兼容，零第三方依赖）-------------------------------
+# 生效条件：给定 model/base/key/messages 即构造 JSON POST 到 base.rstrip("/")+"/chat/completions"，返回 (choices[0].message 的 content 或缺失/假值回落 ""、data.get("usage") 或缺失/假值回落 {}、耗时 dt)，timeout/max_tokens/temperature 仅作为请求参数传入。
 def llm_chat(model, base, key, messages, timeout=180, max_tokens=200,
              temperature=0.0):
     payload = json.dumps({
@@ -154,6 +155,7 @@ def llm_chat(model, base, key, messages, timeout=180, max_tokens=200,
     return content, (data.get("usage") or {}), dt
 
 
+# 生效条件：raw（None/空串视为 ""）中首个 "{" 至末个 "}" 的子串能解析出 pick，或全文匹配到单个数字 1-9，且该编号落在 1..n 内时返回该编号（pick 为数字字符串先转 int），否则返回 None。
 def _parse_pick(raw, n):
     """从模型输出里抠出候选编号（1..n）；解析失败返回 None。"""
     s = raw or ""
@@ -174,6 +176,7 @@ def _parse_pick(raw, n):
     return None
 
 
+# 生效条件：以 case["id"] 播种打乱 [(fix,case["fix"]),(trap,case["trap"]),(decoy,case["decoy"])] 后取三种循环排列，n<=3 返回其前 n 个，n>3 返回 6 种全排列的前 n 个。
 def _orders(case, n):
     """候选顺序。默认取 3 种循环排列（每个候选在 3 个位置各出现一次，天然去位置偏差）；
     n>3 时退回全 6 种排列。基准顺序由 case id 播种打乱，避免跨用例雷同。"""
@@ -186,6 +189,7 @@ def _orders(case, n):
     return list(itertools.permutations(base))[:n]
 
 
+# 生效条件：case 含 task 且 opts 为 (kind, txt) 序列时，返回含场景、编号候选与选择指令的提示文本，memory 非空时在开头插入记忆段。
 def _user_prompt(case, opts, memory=None):
     lines = []
     if memory:
@@ -203,12 +207,14 @@ def _user_prompt(case, opts, memory=None):
     return "\n".join(lines)
 
 
+# 生效条件：cg 存在时把模块常量 CASES 逐条以 c["task"] 为 error、c["lesson"] 为 fix 组成列表传给 cg.mine_fix_pairs 并原样返回其结果。
 def _build_memory(cg):
     """Phase A：把 5 条「项目规范」写进记忆（真实 mine_fix_pairs）。"""
     return cg.mine_fix_pairs(
         [{"error": c["task"], "fix": c["lesson"]} for c in CASES])
 
 
+# 生效条件：以 "本项目规范："+case["query"] 且 budget_tokens=budget、k=10 调用 cg.recall，取 pack 各项 content（缺失/假值为 ""）拼接，返回其前 1500 字符与 case["marker"] 是否出现在未截断拼接文本中。
 def _recall_memory(cg, case, budget):
     res = cg.recall("本项目规范：" + case["query"],
                     budget_tokens=budget, k=10)
@@ -216,6 +222,7 @@ def _recall_memory(cg, case, budget):
     return text[:1500], (case["marker"] in text)
 
 
+# 生效条件：在 cfg["max_turns"] 轮内以 cfg["model"]/cfg["base"]/cfg["key"] 调 llm_chat（timeout=cfg["timeout"]、max_tokens=cfg["max_tokens"]）并累加 usage["total_tokens"]，pick 等于 correct_pos 或为 None 时中止（否则在仍有剩余轮次时追加 assistant/user 消息重选），最终 pick 为 None 则 kind="invalid"、否则 kind=opts[pick-1][0]。
 def _run_one(cfg, case, opts, correct_pos, memory):
     messages = [{"role": "system", "content": SYS_PROMPT},
                 {"role": "user", "content": _user_prompt(case, opts, memory)}]
@@ -239,6 +246,7 @@ def _run_one(cfg, case, opts, correct_pos, memory):
             "turns": turns, "tokens": tokens, "latency": dt}
 
 
+# 生效条件：cfg["use_mem"] 为真时对每个 case 以 cfg["budget"] 先串行召回写入 mems、否则存 (None, False)，再对每 case × _orders(case, n_perms) 的排列 × ("none","mem") 两臂建任务交 ThreadPoolExecutor(max_workers=workers) 执行，返回按 arm 分组的 {"none": [...], "mem": [...]} 行表。
 def _run_model(label, cfg, cases, cg, n_perms, workers):
     # 记忆召回先串行算好（MdCGOS 非线程安全），LLM 调用再并发。
     mems = {}
@@ -254,6 +262,7 @@ def _run_model(label, cfg, cases, cg, n_perms, workers):
             for arm in ("none", "mem"):
                 tasks.append((case, oi, opts, correct_pos, arm))
 
+# 生效条件：t 解包为 (case, oi, opts, correct_pos, arm)，arm=="mem" 时 memory/hit 取闭包 mems[case["id"]]、否则为 (None, False)，_run_one 抛异常时以 kind="error"、pick=None 的占位行替代，随后补上 case/arm/hit 并打印该行后返回 r。
     def work(t):
         case, oi, opts, correct_pos, arm = t
         memory, hit = mems[case["id"]] if arm == "mem" else (None, False)
@@ -276,10 +285,12 @@ def _run_model(label, cfg, cases, cg, n_perms, workers):
     return rows
 
 
+# 生效条件：n 为真值时返回 f"{100.0*x/n:.1f}%"，n 为假值（0）时返回 "-"。
 def _pct(x, n):
     return f"{100.0 * x / n:.1f}%" if n else "-"
 
 
+# 生效条件：以 rows["none"] 的行数 n 汇总 none/mem 两臂的 correct、kind=="trap"、kind∈("invalid","error")、tokens、latency、hit 与 pick∈(1,2,3) 的分布并打印（n_perms 仅用于表头文字），返回该 agg 字典。
 def _report(label, rows, n_perms):
     n = len(rows["none"])
     print(f"\n{'-' * 78}")
@@ -333,6 +344,7 @@ def _report(label, rows, n_perms):
     return agg
 
 
+# 生效条件：argv 为 None 时改读 sys.argv；若 --key 与 DEEPSEEK_API_KEY 均为空则返回 2，否则按 --only/--cases 从 CASES 取用例跑完双臂后返回 0。
 def main(argv=None):
     ap = argparse.ArgumentParser(
         description="先验陷阱 A/B：无记忆 vs 有记忆（真实 LLM）")
@@ -394,4 +406,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/bench_unified_en.py

@@ -48,6 +48,7 @@ ARM_ROOT = os.path.join(HERE, "_md_cg_eval_unified_en")  # gitignore 已覆盖
 K = 10
 
 
+# 生效条件：传入 root 使 os.path.isdir(root) 为真时先执行 shutil.rmtree(root, ignore_errors=True)、否则跳过，随后遍历 corpus 每项 c，semantic_of 不为 None 且 semantic_of(c) 返回真值时以 semantic=sem 传入，正文按 zh_body 真值取 c.get("zh")、假值取 b6.ingest_text_en(c)，并以 c["id"] 为键 add 后 flush 并 install_read_cache，最终返回 cg；
 def build(root, corpus, semantic_of=None, zh_body=False):
     """单库构建：正文形态与 fm.semantic 摘要层是仅有的两个自由度。"""
     if os.path.isdir(root):
@@ -67,6 +68,7 @@ def build(root, corpus, semantic_of=None, zh_body=False):
     return cg
 
 
+# 生效条件：cg 可对 questions 做 evaluate_group 时，按 semantic 设置或清除 MDCG_SEMANTIC，返回词法路 rows 及其按 qtype 汇总的 by_type。
 def run_arm(cg, questions, tag, semantic=False):
     if semantic:
         os.environ["MDCG_SEMANTIC"] = "1"
@@ -82,6 +84,7 @@ def run_arm(cg, questions, tag, semantic=False):
     return rows, by_type
 
 
+# 生效条件：questions 为真时逐 q 取 q["question"]（缺该键抛 KeyError）经 query_atoms，仅当 atom 含任一满足 "A" <= ch <= "z" 的字符才计入 n_keep，n_tok 为 0 时 keep_ratio 为 0.0、否则 round(n_keep/n_tok,4)，questions 为空时 q_with_keep_ratio 为 0.0、否则 round(n_q_with_keep/len(questions),4)，返回含 n_questions/n_atoms/n_en_keep 的 dict；
 def oov_stats(questions):
     """题级 en→zh 归一覆盖统计：英文保留词占比 = 词表覆盖瓶颈的直接量化。"""
     n_tok = n_keep = n_q_with_keep = 0
@@ -100,6 +103,7 @@ def oov_stats(questions):
             if questions else 0.0}
 
 
+# 生效条件：不适用（无必需形参与模块级常量）
 def main():
     t0 = time.time()
     rows500 = list(ec.iter_jsonl(b6.QUESTIONS500))
@@ -115,6 +119,7 @@ def main():
     ec.unlock_global_cap()
     ec.use_jaccard()
 
+# 生效条件：对 c 先取 (c.get("zh_fields") or {}).get("summary") 再 or "" 并 str().strip()，该值为空时回落为 (c.get("zh") or "") 的 str().strip()，所得 s 非空则返回 " ".join(semantic_atoms(s))、否则返回空串；
     def sem_of(c):
         s = str((c.get("zh_fields") or {}).get("summary") or "").strip()
         if not s:
@@ -197,4 +202,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/md_cg/bench_zh_mad.py

@@ -62,6 +62,7 @@ QUESTIONS20 = os.path.join(ZP, "questions20.jsonl")
 AXES = ("person", "event", "time", "identity", "place", "condition")
 
 
+# 生效条件：path 以 UTF-8 打开后逐行读取，仅 strip 后非空的行经 json.loads 产出，空白行被跳过。
 def iter_jsonl(path):
     with open(path, encoding="utf-8") as f:
         for line in f:
@@ -70,11 +71,13 @@ def iter_jsonl(path):
                 yield json.loads(line)
 
 
+# 生效条件：path 以 UTF-8 打开成功时返回 json.load(f) 的解析结果，片段内无其它分支。
 def load_json(path):
     with open(path, encoding="utf-8") as f:
         return json.load(f)
 
 
+# 生效条件：raw 经 str() 后按“；”切分，仅含“=”的段被解析，其中键为身份/时间/摘要时写对应槽位、键为条件时按“|”与“:”写入 condition、键为词时按“,”拆出非空项写入 terms，其它键或未出现的槽位保持 out 的默认空值。
 def parse_zh(raw):
     """中文层串 → 槽位 dict。
 
@@ -107,6 +110,7 @@ def parse_zh(raw):
     return out
 
 
+# 生效条件：当 MANUAL_ZH/MANUAL_Q/LM_Q/LM_H 可读取、hay 覆盖 want_ids 且 meta 含 man_q 全部 qid 时写出 CORPUS20/QUESTIONS20 并返回 (corpus, questions)，缺 turn 或 qid 分别 raise SystemExit，verbose（默认 True）为真值时额外打印统计、假值时静默。
 def prepare(verbose=True):
     """生成 corpus20.jsonl 与 questions20.jsonl（幂等覆盖）。"""
     man_zh = load_json(MANUAL_ZH)
@@ -125,6 +129,7 @@ def prepare(verbose=True):
         raise SystemExit(f"[失败] haystack 缺以下 turn：{sorted(missing)}")
 
     # corpus：按 turn id 的数值序（= 时间序），保证「承接前一条」有确定语义
+# 生效条件：tid 经 rsplit("t",1) 得到至少两段且最后一段可被 int() 解析时返回该整数，否则源码未做校验会抛错。
     def turn_no(tid):
         return int(tid.rsplit("t", 1)[1])
 
@@ -171,6 +176,7 @@ def prepare(verbose=True):
     return corpus, questions
 
 
+# 生效条件：prepare(verbose=False) 返回 corpus/questions 后，对每题以 evidence_turns[0]（空则 ""）取 ev0，命中词限于 ev0 非空且词出现在 zh_of[ev0] 中，df1 收集池内 df==1 的词、all_df 收集 df==len(corpus) 的词，verbose（默认 True）为真值时打印后返回 per_q、为假值时直接返回 per_q。
 def analyze(verbose=True):
     """诊断：查询词能否落到 gold 中文层 / 池内其他条目（决定各轴是否有可桥接的实体）。
 
@@ -254,6 +260,7 @@ EN_NAME_RE = re.compile(r"\b[A-Z][a-z]{2,}(?:[ ][A-Z][a-z]{2,})*\b")
 DATE_RE = re.compile(r"(\d{4})[/-](\d{1,2})[/-](\d{1,2})")
 
 
+# 生效条件：DATE_RE.search(str(raw or "")) 有匹配时返回零填充的 YYYY-MM-DD，无匹配（含 raw 为假值回落成 ""）时返回 ""。
 def norm_time(raw):
     """'2023/05/24 04:49' → '2023-05-24'（跨条目统一格式，使日期查询可命中）。"""
     m = DATE_RE.search(str(raw or ""))
@@ -263,6 +270,7 @@ def norm_time(raw):
     return f"{int(y):04d}-{int(mo):02d}-{int(d):02d}"
 
 
+# 生效条件：对 str(text or "") 用 EN_NAME_RE 扫描，匹配串按空白切分后任一部分命中 EN_STOP 即跳过，其余项按首次出现顺序去重加入 out 并返回；text 为假值时扫描空串返回 []。
 def en_names(text):
     """英文原文中的专名候选（跨语言桥：中文查询里的英文专名可经 entity 路命中）。"""
     out, seen = [], set()
@@ -276,6 +284,7 @@ def en_names(text):
     return out
 
 
+# 生效条件：遍历 corpus，对每条记录的 zh_fields["terms"] 去重后逐词判断，词非空且不在 STOP_ZH 时使 df[词] 计数加一，返回 df。
 def build_tables(corpus):
     """全库统计：# 词项 df（**只读语料**，与查询集无关）。"""
     df = {}
@@ -286,6 +295,7 @@ def build_tables(corpus):
     return df
 
 
+# 生效条件：c 含 zh_fields（terms/condition/time/identity）且 df 为词到频次的映射时，返回 person/event/time/identity/place/condition 六轴取值字典。
 def axis_values(c, df):
     """一条 turn 的六个关系轴取值（用户裁决：条件链 + 人物/事件/时间/身份/地点）。"""
     f = c["zh_fields"]
@@ -321,6 +331,7 @@ INTENT_CLASSES = (
 )
 
 
+# 生效条件：按 INTENT_CLASSES 顺序检查 c["zh_fields"]["summary"]，首个命中类目的首个包含于摘要的动词返回 (cls, v)，全不命中返回 ('', '')。
 def intent_of(c):
     """意图抽象：摘要 → (规范类目, 命中的动词原形)。
 
@@ -338,6 +349,7 @@ def intent_of(c):
     return "", ""
 
 
+# 生效条件：把 c["zh_fields"]["terms"] 与 en_names(c["text"]) 逐项 strip 后跳过空串、STOP_ZH（原形或小写）及已见项去重入 out，再用 norm_time(条件.get("时间窗口") or c 的 time) 得到非空且未出现的时窗串追加；df 形参在该片段内未参与条件判断。
 def normalize_terms(c, df):
     """实体规范化：去停用 + 去重 + 附时间规范式 + 附英文专名（跨语言对齐）。"""
     f = c["zh_fields"]
@@ -354,6 +366,7 @@ def normalize_terms(c, df):
     return out
 
 
+# 生效条件：遍历 corpus 并以 root=os.path.join(HERE, root_base or f"_md_cg_eval_zhprobe_{arm['name']}")（root_base 为 None/空串时回落）建库，graph 分支仅当 arm.get("graph") 为真且某轴取值的同值 id 数落在 [2, max_df]（默认 5）时为这些 id 两两建有向边，coref 仅当 arm.get("coref") 为真、本条 own 为空（own 只在 arm.get("norm") 为真时由 normalize_terms 生成，否则恒为 []）且 prev_own 非空时承接前一条自身 canonical，intent 分支仅当 arm.get("intent") 为真且 intent_of 返回 cls 非空时写意图行并把意图词与长度>=2 的动词加入 tags，verbose（默认 True）为真值时打印臂统计、root 已是目录时先整树删除再建 MdCGOS。
 def build_arm(corpus, arm, max_df=5, root_base=None, verbose=True):
     """按消融臂建库。每臂一个独立 root，互不污染。
 
@@ -453,6 +466,7 @@ ARMS = [
 ]
 
 
+# 生效条件：先执行 prepare(verbose=False) 取得 corpus，再对 ARMS 每臂以 max_df=max_df（默认 5，原样下传不做假值回落）调用 build_arm 并汇总为 roots 返回。
 def build_all(max_df=5):
     corpus, _ = prepare(verbose=False)
     print(f"== 建库（消融 {len(ARMS)} 臂，max_df={max_df}）==")
@@ -469,6 +483,7 @@ ROW_RE = re.compile(
 GROUPS = ["precise", "temporal", "interference", "reference"]
 
 
+# 生效条件：os.path.exists(RUST_BIN) 为真时以 argv=[RUST_BIN,"--dataset","mad","--tag",name,"--lib",lib]（extra 为真值时追加 list(extra)）执行 subprocess，返回码非 0 或 ROW_RE 在 stdout 未匹配到任何组时 raise SystemExit，否则返回 {组:(n,hit@1,hit@5,MRR)}。
 def run_one(name, lib, extra=None):
     """调用 **Rust 检索器** 跑一臂，返回 {组: (n, hit@1, hit@5, MRR)}。
 
@@ -496,6 +511,7 @@ def run_one(name, lib, extra=None):
     return got
 
 
+# 生效条件：先打印 title 与表头，再遍历 rows 的 (label, got, note)，对 GROUPS 每组用 got[g] 取 (n,h1,h5,mrr) 并累计总体 hit@1/MRR，仅当 baseline 不为 None 且 label==baseline 时记 ref，仅当 ref 已记录且 label!=baseline 时输出 Δ。
 def print_table(title, rows, baseline=None):
     """rows: [(label, got, note)]；baseline = 参照行 label（算 Δ）。"""
     print(f"\n== {title} ==")
@@ -524,6 +540,7 @@ def print_table(title, rows, baseline=None):
               + f"{ov_h1 * 100:>10.1f}%{ov_mrr:>10.3f}{delta}{suffix}")
 
 
+# 生效条件：对 ARMS 每臂以 lib=f"_md_cg_eval_zhprobe_{name}"、无 extra 调用 run_one 组成 rows，并以 ARMS[0]["name"] 为 baseline 调 print_table 后返回 rows。
 def run_ablation():
     """消融主表：逐臂调用 Rust 检索器并汇总（种子口径 = 缺省，即生产现状）。"""
     rows = []
@@ -537,6 +554,7 @@ def run_ablation():
     return rows
 
 
+# 生效条件：以最后一个臂 ARMS[-1]['name'] 对应的库路径，先无 extra 调 run_one("a4_index", lib)、再以 extra=("--graph-seeds","sorted") 调 run_one("a4_sorted", lib) 组成 rows，并以 baseline="a4/index" 调 print_table 后返回。
 def run_seed_control():
     """对照：**同一个 a4 库**（写入侧与边结构完全相同），只切换 graph 路种子口径。
 
@@ -555,6 +573,7 @@ def run_seed_control():
     return rows
 
 
+# 生效条件：cmd 取 argv[1]（len(argv)<=1 时为 "prepare"），cmd=="prepare"/"analyze"/"build"/"run"/"seed-control" 分别调用 prepare/analyze/build_all/run_ablation/run_seed_control，cmd=="all" 依次调用 prepare、analyze、build_all、run_ablation、run_seed_control，其余值 raise SystemExit。
 def main(argv):
     cmd = argv[1] if len(argv) > 1 else "prepare"
     if cmd == "prepare":
@@ -580,4 +599,4 @@ def main(argv):
 
 
 if __name__ == "__main__":
-    main(sys.argv)
+    main(sys.argv)

package/md_cg/blindspot_tickets.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""盲区消解票据（阶段三 §5.4）：BLINDSPOT/DEFER 盲区 → 四类消解票据（任务卡形态）挂认知图。
+
+四类分类判据（确定性、声明式、可审计，不做语义猜测）：
+  task      — 盲区 query 精确命中某 unresolved 层节点正文首行 → 直接立工程任务卡
+  grilling  — defer 主导（defer > blindspot，信息不完整须澄清）；执行通道=宿主侧
+              访谈（grill），md_cg 库内无访谈工具，本模块只建卡不越权代答（边界如实）
+  research  — blindspot >= 3（反复未知）→ 研究议题（检索/调研补证）
+  prototype — 其余 → 最小探针实验验证
+
+幂等：tasks.upsert 同 slug 即同任务，重复生成不新建卡（updated 计数）。
+依赖挂接：票据即任务节点（认知图节点天然在图上、可检索）。「升级为正式工程
+任务时的机械 depends_on 边」由使用者在该卡更新时显式填写——本模块不伪造
+工程边，消解路径以正文声明。
+预演：apply=False 只出清单不落库（与 learn/reconstruct 的 opt-in 同构，
+默认链路零变更）。
+"""
+from . import metacognition, tasks
+
+TICKET_TYPES = ("research", "prototype", "grilling", "task")
+
+_RESOLVE = {
+    "research": "检索/调研补证（外部研究系列吸收流程），产出知识节点后复核 gap_hint",
+    "prototype": "构造最小探针实验验证，结论回写认知图",
+    "grilling": "澄清缺位：执行通道=宿主侧访谈（grill）；库内无访谈工具，不越权代答",
+    "task": "直接立工程任务推进（关联 unresolved 悬挂线索）",
+}
+
+_JUDGE = {
+    "research": "blindspot>=3（反复未知 → 研究议题）",
+    "prototype": "其余（偶发未知 → 最小探针）",
+    "grilling": "defer 主导（信息不完整 → 须澄清）",
+    "task": "query 精确命中 unresolved 节点正文首行",
+}
+
+
+def classify(item, unresolved_first_lines):
+    """按确定性判据给盲区分派票据类型。unresolved_first_lines={首行: node_id}。"""
+    q = str(item.get("query") or "").strip()
+    if q and q in unresolved_first_lines:
+        return "task"
+    b = int(item.get("blindspot") or 0)
+    d = int(item.get("defer") or 0)
+    if d > b:
+        return "grilling"
+    if b >= 3:
+        return "research"
+    return "prototype"
+
+
+def _plan_text(item, ttype, unresolved_first_lines):
+    q = str(item.get("query") or "").strip()
+    lines = [
+        "来源：盲区簇 key=%s（blindspot=%s defer=%s samples=%s）" % (
+            metacognition._key(q), item.get("blindspot"), item.get("defer"),
+            item.get("samples")),
+        "分类判据：%s" % _JUDGE[ttype],
+    ]
+    if ttype == "task" and q in unresolved_first_lines:
+        lines.append("关联悬挂：unresolved 节点 %s" % unresolved_first_lines[q])
+    lines.append("消解路径：%s" % _RESOLVE[ttype])
+    lines.append("完成判据：盲区簇后续反思记录中 BLINDSPOT/DEFER 归零（gap_hint 复核）")
+    return "\n".join(lines)
+
+
+def make_tickets(cg, *, types=None, limit=10, min_blindspot=0,
+                 apply=False, actor=None) -> dict:
+    """盲区 → 消解票据。apply=False 预演（零落库）；apply=True 经 tasks.upsert 落卡。"""
+    want = tuple(t for t in (types or TICKET_TYPES) if str(t).strip())
+    bad = [t for t in want if str(t).strip().lower() not in TICKET_TYPES]
+    if bad:
+        return {"ok": False,
+                "error": "未知票据类型：%s（可选 %s）" % (bad, list(TICKET_TYPES))}
+
+    mp = metacognition.blindspots(cg, limit=max(int(limit), 20))
+    items = []
+    for it in mp.get("items") or []:
+        b = int(it.get("blindspot") or 0)
+        d = int(it.get("defer") or 0)
+        if b >= int(min_blindspot) or d >= 1:
+            items.append(it)
+
+    unresolved_first_lines = {}
+    for u in mp.get("unresolved") or []:
+        first = str(u.get("content") or "").strip().splitlines()
+        if first and first[0].strip():
+            unresolved_first_lines.setdefault(first[0].strip(), u.get("node_id"))
+
+    out, created, updated, errors = [], 0, 0, 0
+    for it in items[:int(limit)]:
+        q = str(it.get("query") or "").strip()
+        if not q:
+            continue
+        ttype = classify(it, unresolved_first_lines)
+        if ttype not in [str(t).strip().lower() for t in want]:
+            out.append({"type": ttype, "query": q, "skipped": "types 过滤"})
+            continue
+        name = "票据:%s:%s" % (ttype, q[:24])
+        if not apply:
+            out.append({"type": ttype, "query": q, "name": name, "dry_run": True})
+            continue
+        r = tasks.upsert(
+            cg, name, plan=_plan_text(it, ttype, unresolved_first_lines),
+            status="active",
+            note="盲区簇 key=%s｜blindspot=%s｜defer=%s" % (
+                metacognition._key(q), it.get("blindspot"), it.get("defer")),
+            tags=["blindspot-ticket", "ticket:%s" % ttype],
+            actor=actor or "blindspot_tickets")
+        if r.get("ok"):
+            if r.get("created"):
+                created += 1
+            else:
+                updated += 1
+            out.append({"node_id": r.get("node_id"), "type": ttype,
+                        "query": q, "created": bool(r.get("created"))})
+        else:
+            errors += 1
+            out.append({"type": ttype, "query": q, "error": r.get("error")})
+
+    return {"ok": errors == 0, "action": "tickets", "op": "insight",
+            "scanned": len(items), "created": created, "updated": updated,
+            "errors": errors, "applied": bool(apply), "tickets": out,
+            "unresolved_count": len(unresolved_first_lines)}

package/md_cg/branches.py

@@ -33,16 +33,19 @@ COLD_DIR = "_branches"
 _BRANCH_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
 
 
+# 生效条件：调用 branch_tag(branch_id) 时，返回 "branch:" 拼接 str(branch_id or "").strip().lower()（branch_id 为假值时以空串参与拼接）。
 def branch_tag(branch_id: str) -> str:
     """分支节点的标注 tag（fork 时写入；branch_summary 也带它以便反查）。"""
     return "branch:" + str(branch_id or "").strip().lower()
 
 
+# 生效条件：调用 branch_node_id(orig, branch_id) 时，返回 orig 与 str(branch_id or "").strip().lower() 以 @ 拼接的字符串（branch_id 为假值时用空串）。
 def branch_node_id(orig: str, branch_id: str) -> str:
     """分支副本 id：`<主支nid>@<branch_id>`（@ 文件名合法、撞名不可能）。"""
     return "%s@%s" % (orig, str(branch_id or "").strip().lower())
 
 
+# 生效条件：调用 _audit(cg, op, **meta) 时，仅当 getattr(cg, "_audit", None) 不为 None 才用 op 等调用之，且该调用抛出的任何 Exception 被静默吞掉；否则直接返回。
 def _audit(cg, op: str, **meta) -> None:
     """生命周期留痕；审计失败绝不阻断主流程（G8 同哲学）。"""
     a = getattr(cg, "_audit", None)
@@ -54,12 +57,14 @@ def _audit(cg, op: str, **meta) -> None:
         pass
 
 
+# 生效条件：调用 _iter_branch_nodes(cg, branch_id) 时，返回 cg.index 的 "nodes" 字典（假值则视为空字典）中所有 v.get("branch_id") 等于 str(branch_id or "").strip().lower() 的 (k, v) 列表。
 def _iter_branch_nodes(cg, branch_id: str):
     bid = str(branch_id or "").strip().lower()
     return [(k, v) for k, v in (cg.index.get("nodes") or {}).items()
             if v.get("branch_id") == bid]
 
 
+# 生效条件：调用 _fm_of(rec) 时，若 rec 为假值返回 {}；否则返回 rec.get("frontmatter")（若该值真）或 rec 本身。
 def _fm_of(rec):
     """get 返回形态兼容：{'frontmatter': fm, 'content': c} 或平铺 fm。"""
     if not rec:
@@ -67,6 +72,7 @@ def _fm_of(rec):
     return rec.get("frontmatter") or rec
 
 
+# 生效条件：调用 fork(cg, node_ids, branch_id=None, note=None) 时，先将 node_ids 去空转字符串，为空则返回 {"ok": False, "error": ...}；否则 branch_id 为 None 时生成 "br_"+uuid4().hex[:8]，再 str(branch_id).strip().lower()，若不匹配模块常量 _BRANCH_RE 则返回错误；然后对每个 nid 跳过含 "@"、cg.get(nid) 为假值或 cg.get(branch_node_id(nid, branch_id)) 已存在者，其余经 cg.add 复制并记入 forked，最终返回 ok=bool(forked) 及 branch_id/tag/forked/skipped。
 def fork(cg, node_ids, branch_id=None, note=None) -> dict:
     """把主支节点复制成分支实验副本。
 
@@ -115,11 +121,13 @@ def fork(cg, node_ids, branch_id=None, note=None) -> dict:
             "tag": branch_tag(branch_id), "forked": forked, "skipped": skipped}
 
 
+# 生效条件：调用 search(cg, query, branch_id, **kw) 时，以 branch=str(branch_id or "").strip().lower() 为参数转调 cg.search，并原样返回其结果。
 def search(cg, query: str, branch_id: str, **kw):
     """分支内检索：主支 + 本分支可见、其他分支隐身（_candidates branch 过滤）。"""
     return cg.search(query, branch=str(branch_id or "").strip().lower(), **kw)
 
 
+# 生效条件：当 node_id 经 str 转换并 strip 后含 '@'、cg.index['nodes'] 中存在该 id 且其 branch_id 非空、content 不是 dict 且不是 None 时返回 {'ok': True, 'node': nid, 'branch_id': ...}，否则返回 {'ok': False, 'error': ...}。
 def rewrite(cg, node_id, content, tags=None, importance=None,
             actor="branch_rewrite", **extra) -> dict:
     """分支实验改写的**唯一正路**（防裸 add 丢分支归属）。
@@ -167,6 +175,7 @@ def rewrite(cg, node_id, content, tags=None, importance=None,
     return {"ok": True, "node": nid, "branch_id": e.get("branch_id")}
 
 
+# 生效条件：调用 merge(cg, branch_id, reason=None) 时，先取 bid=str(branch_id or "").strip().lower() 与 _iter_branch_nodes(cg, bid)，若结果为空返回 {"ok": False, "error": ...}；否则遍历每个分支节点，若其 branched_from 取不到主支节点则记 skipped，否则把分支内容用 cg.add 回写主支（override=True、derived_from 追加分支 nid、relation="merged_from" 等），最终返回 ok=bool(merged) 等。
 def merge(cg, branch_id, reason=None) -> dict:
     """把分支上的改写按 branched_from 溯源回写主支。
 
@@ -210,6 +219,7 @@ def merge(cg, branch_id, reason=None) -> dict:
             "hint": "分支节点保留：可 branch_search 继续实验，或 discard 冷归档"}
 
 
+# 生效条件：调用 discard(cg, branch_id, summary) 时，若 cg.principal 存在则先 require_admin("branch_discard")；取 bid=str(branch_id or "").strip().lower()，若 summary 缺少模块常量 BRANCH_MARKS 中任一标记则返回错误，若 _iter_branch_nodes(cg, bid) 为空也返回错误；否则写 "branch_summary_"+bid 知识节点，把分支节点文件移入 COLD_DIR/bid 并从 cg.index["nodes"] 弹出，最后返回 ok=True 等。
 def discard(cg, branch_id, summary: str) -> dict:
     """放弃分支：校验教训必填 → 写 branch_summary 教训节点 → 分支冷归档。
 
@@ -258,6 +268,7 @@ def discard(cg, branch_id, summary: str) -> dict:
             "summary_node": sid, "cold_dir": "%s/%s" % (COLD_DIR, bid)}
 
 
+# 生效条件：调用 list_branches(cg) 时，遍历 cg.index 的 "nodes"（假值则空字典），仅对 e.get("branch_id") 为真值的节点按 bid 分组，收集节点 id 和 branched_from，返回 ok=True 与按 branch_id 排序的分组列表。
 def list_branches(cg) -> dict:
     """按 branch_id 聚合现存分支（节点清单 + 溯源主支）。"""
     groups = {}
@@ -272,4 +283,4 @@ def list_branches(cg) -> dict:
         if bf and bf not in g["branched_from"]:
             g["branched_from"].append(bf)
     return {"ok": True,
-            "branches": sorted(groups.values(), key=lambda g: g["branch_id"])}
+            "branches": sorted(groups.values(), key=lambda g: g["branch_id"])}

package/md_cg/build_postings.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""倒排发布表构建/查看（S7 候选层）。
+
+用法：
+  python -X utf8 -m md_cg.build_postings --root <库根>            # 全量重建（幂等）
+  python -X utf8 -m md_cg.build_postings --root <库根> --stats     # 只看现状
+  python -X utf8 -m md_cg.build_postings --root <库根> --limit 500 # 抽样构建（冒烟用，永不算新鲜）
+  python -X utf8 -m md_cg.build_postings --root <库根> --if-stale  # 过期才重建（守候环用）
+
+说明：发布表是**派生索引**（<root>/_postings.json + _postings_meta.json），
+不修改任何节点内容；节点新增/修改后需重建（v1 不做增量维护）。
+"""
+import argparse
+import json
+import sys
+
+from . import postings
+from .mdcg import MdCG
+
+
+# 生效条件：st 为 dict 时返回其摘要——保留 schema/built_at/nodes/terms/postings/partial/rebuilt/rebuilt_from，
+# 并把 snapshot 折成 dirs/root_files 计数（快照本体含上千个目录键，直接打印会淹没日志）；st 非 dict 时原样返回。
+def _brief(st):
+    if not isinstance(st, dict):
+        return st
+    keys = ("schema", "built_at", "nodes", "terms", "postings", "partial",
+            "rebuilt", "rebuilt_from")
+    out = {k: st.get(k) for k in keys if k in st}
+    snap = st.get("snapshot")
+    if isinstance(snap, dict):
+        out["dirs"] = len(snap.get("dir_mtimes") or {})
+        out["root_files"] = len(snap.get("file_mtimes") or {})
+    return out
+
+
+# 生效条件：无条件解析参数（root 必填；stats/limit/if-stale 可选；if-stale 与 limit 互斥则 argparse 报错并退出 2）；
+# stats 为真时打开库打印 stats 摘要（含 stale_reason）并返回 0；if-stale 为真且快照新鲜时打印 {"rebuilt": false} 返回 0、
+# 过期时重建并打印摘要（附 rebuilt_from=过期原因）；否则一律重建并打印摘要，返回 0。
+# 三条路径打印的都是 _brief 摘要——不打印快照指纹本体。
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True)
+    ap.add_argument("--stats", action="store_true")
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--if-stale", action="store_true", dest="if_stale")
+    a = ap.parse_args(argv)
+    if a.if_stale and a.limit:
+        ap.error("--if-stale 与 --limit 互斥（抽样表不可当作新鲜快照）")
+    cg = MdCG(a.root)
+    nodes = cg.index.get("nodes") or {}
+    if a.stats:
+        st = postings.stats(a.root, nodes)
+        print(json.dumps({"terms": st.get("terms"), "postings": st.get("postings"),
+                          "stale_reason": st.get("stale_reason"),
+                          "meta": _brief(st.get("meta"))}, ensure_ascii=False))
+        return 0
+    if a.if_stale:
+        sr = postings.stale_reason(a.root, nodes)
+        if not sr:
+            print(json.dumps({"rebuilt": False, "reason": "fresh"}, ensure_ascii=False))
+            return 0
+        st = postings.build(cg)
+        print(json.dumps(_brief(dict(st, rebuilt_from=sr)), ensure_ascii=False))
+        return 0
+    st = postings.build(cg, limit=a.limit)
+    print(json.dumps(_brief(st), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())