@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/md_cg/bench_progressive.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""bench_progressive.py · 渐进式语义检索双实验（2026-09-14）
+
+理论（使用者与 GPT 定稿）：查询不是固定语义结构，而是不断收紧的约束集合；
+从最小可靠语义开始宽检索，再按区分度逐步增加条件使语义收敛。
+「语义解析的完整性与检索的必要性不是同一个问题。」
+
+实验一（locomo-zh-500 · 原子面，与 bench_en_atoms_public 同 doc 侧口径）：
+  G0 一次性全原子      —— 对照锚点（应 ≈ ② 96.8/99.8/99.8，同口径自校验）
+  G2 只宽检不细化      —— core 50% 一次性排序（「最小可靠语义」本身水平）
+  G1 渐进              —— Stage-1 宽检索 → 区分度引导加原子 → 重排
+                          （max_stages=4；每阶段都被测量）
+  统计：initial（Stage-1）/ final（终态）hit@1/5/10+MRR、平均 refinement
+  steps（added 条件数）、一步收敛率。
+  诚实边界：池 567 全 gold 零干扰——G1≈G0 属预期（⑤⑥⑦已证宽检索
+  鲁棒）；本实验量化「渐进不劣于一次性 + 步数可观测」，消歧增益见实验二。
+
+实验二（受控干扰池 · 引擎侧，42+2 节点真实 MdCGOS）：
+  在 test_sem_noise 语料上放 2 条条件冒充邻居（正条件与 gold 同款 →
+  judge 判 ACCEPT）——构造 False ACCEPT>0 的形态；渐进循环：
+  宽检索 → discriminative 在候选间选区分性条件词 → 带条件重排。
+  断言：渐进后 False ACCEPT=0 且 top1 ∈ gold——
+  「DEFER/冒充不是终点，加条件后语义收敛」的引擎侧实证。
+  条件词池本轮手工给定（示教）；真实系统应由 atoms.json 标准词表驱动。
+
+跑法：python -m md_cg.bench_progressive
+"""
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if HERE not in sys.path:
+    sys.path.insert(0, HERE)
+
+from md_cg import bench6_common as b6                        # noqa: E402
+from md_cg.bench_en_atoms_public import (                    # noqa: E402
+    CORPUS, QUESTIONS, jaccard, load_char_atoms, node_atom_set,
+    round_dict, zh_map_en)
+from md_cg.mdcos import MdCGOS                               # noqa: E402
+from md_cg.progressive import discriminative, progressive_search  # noqa: E402
+from md_cg.test_sem_noise import (                           # noqa: E402
+    GOLD, GOLD_COND, NEG_TEXTS, NEIGHBORS, QUERY, UNREL_DOCS, _doc)
+
+
+def rank_of(ev, ids):
+    """gold 在 id 排名中的位次（不在则 0）。"""
+    return next((r for r, nid in enumerate(ids, 1) if nid in ev), 0)
+
+
+def _agg(rank, st):
+    if rank == 1:
+        st["h1"] += 1
+    if 0 < rank <= 5:
+        st["h5"] += 1
+    if 0 < rank <= 10:
+        st["h10"] += 1
+    if rank:
+        st["rr"] += 1.0 / rank
+
+
+def _show(label, st, n, extra=""):
+    print("  %-22s hit@1=%5.1f%%  hit@5=%5.1f%%  hit@10=%5.1f%%  "
+          "MRR=%.4f%s" % (label, st["h1"] * 100.0 / n,
+                          st["h5"] * 100.0 / n, st["h10"] * 100.0 / n,
+                          st["rr"] / n, extra))
+
+
+def full_rank(qa, docs):
+    """全池 Jaccard 排序 → id 序列（与 run_arm 同判据）。"""
+    scored = sorted(((jaccard(qa, na), nid) for nid, na in docs),
+                    key=lambda t: (-t[0], t[1]))
+    return [nid for _s, nid in scored]
+
+
+def exp_locomo():
+    """实验一：原子面渐进三形态。"""
+    t0 = time.time()
+    with io.open(CORPUS, encoding="utf-8") as f:
+        corpus = [json.loads(ln) for ln in f if ln.strip()]
+    with io.open(QUESTIONS, encoding="utf-8") as f:
+        questions = [json.loads(ln) for ln in f if ln.strip()]
+    char_atoms = load_char_atoms()
+    docs = [(c["id"], node_atom_set(c, char_atoms)) for c in corpus]
+    docs_map = dict(docs)
+    print("[progressive] 实验一 locomo-zh-500 · 语料 %d / 题 %d"
+          % (len(corpus), len(questions)))
+
+    def rank_fn(used):
+        return [(nid, 0.0) for nid in
+                full_rank(frozenset(used), docs)[:20]]
+
+    st_g0 = {"h1": 0, "h5": 0, "h10": 0, "rr": 0.0}
+    st_g2 = dict(st_g0)
+    st_i = dict(st_g0)
+    st_f = dict(st_g0)
+    steps_sum = conv = n = 0
+    for q in questions:
+        ev = set(q.get("evidence_turns") or [])
+        qa = [w for w in zh_map_en(str(q.get("question") or ""),
+                                   char_atoms).split() if w]
+        if not qa:
+            continue
+        n += 1
+        # G0 一次性全原子（对照锚点）
+        _agg(rank_of(ev, full_rank(frozenset(qa), docs)), st_g0)
+        # G2 只宽检不细化
+        core = qa[:max(1, int(len(qa) * 0.5))]
+        _agg(rank_of(ev, full_rank(frozenset(core), docs)), st_g2)
+        # G1 渐进
+        tr = progressive_search(rank_fn, qa, docs_map,
+                                ratio=0.5, k=10, max_stages=4)
+        _agg(rank_of(ev, full_rank(frozenset(tr["stages"][0]["used"]),
+                                   docs)), st_i)
+        _agg(rank_of(ev, full_rank(frozenset(tr["stages"][-1]["used"]),
+                                   docs)), st_f)
+        steps_sum += len(tr["added"])
+        conv += 1 if (tr["converged"] or len(tr["added"]) < 3) else 0
+
+    _show("G0 一次性全原子", st_g0, n,
+          "   ← 锚点应≈② 96.8/99.8/99.8")
+    _show("G2 只宽检(core50%)", st_g2, n)
+    _show("G1 渐进·initial", st_i, n)
+    _show("G1 渐进·final", st_f, n)
+    print("  refinement: 平均加条件数=%.2f  一步收敛率=%.1f%%  (n=%d, %.0fs)"
+          % (steps_sum / max(n, 1), conv * 100.0 / max(n, 1), n,
+             time.time() - t0))
+    return {"g0": st_g0, "g2": st_g2, "g1i": st_i, "g1f": st_f, "n": n}
+
+
+def exp_controlled():
+    """实验二：受控干扰池——条件冒充形态下渐进消歧（引擎侧真检索）。"""
+    print("\n[progressive] 实验二 受控干扰池（42+2 节点真实 MdCGOS）")
+    tmp = tempfile.mkdtemp(prefix="mdcg_prog_")
+    try:
+        root = os.path.join(tmp, "root")
+        cg = MdCGOS(root)
+        gold_ids = [g for g, _ in GOLD]
+        for gid, fact in GOLD:
+            cg.add(gid, _doc(fact, GOLD_COND), layer="knowledge",
+                   verification_basis="test")
+        # 2 条邻居改用 gold 同款生效条件 → 正条件命中 → judge 判 ACCEPT（冒充）
+        IMPOSTORS = ("n1a", "n3a")
+        for gid, lst in NEIGHBORS.items():
+            for nid, fact, _cond in lst:
+                cg.add(nid, _doc(fact, GOLD_COND if nid in IMPOSTORS
+                                 else _cond), layer="knowledge",
+                       verification_basis="test")
+        for nid, fact in NEG_TEXTS:
+            cg.add(nid, _doc(fact, "问没做的事", extra_neg=True),
+                   layer="knowledge", verification_basis="test",
+                   non_applicable_conditions=["刚才在干什么"])
+        for nid, fact, cond in UNREL_DOCS:
+            cg.add(nid, _doc(fact, cond), layer="knowledge",
+                   verification_basis="test")
+
+        KW = dict(paths=("lexical", "bucket", "entity", "graph", "fuzzy"),
+                  fusion="sum", judge_ranking=True)
+
+        def engine_rank(used):
+            res, _m = cg.search_rrf(QUERY + (" " + " ".join(used)
+                                             if used else ""),
+                                    k=10, judge=True, **KW)
+            return [(r[0]["id"], r[1]) for r in res]
+
+        def false_accepts(res):
+            out = []
+            for r in res[:10]:
+                nid = r[0]["id"]
+                if nid in gold_ids:
+                    continue
+                ji = r[2] if len(r) > 2 else {}
+                if (ji or {}).get("state") == "ACCEPT":
+                    out.append(nid)
+            return out
+
+        # 宽检索（不加任何条件；judgeinfo 直接取 results 第三元）
+        wide_res, _m = cg.search_rrf(QUERY, k=10, judge=True, **KW)
+        wide = [(r[0]["id"], r[1]) for r in wide_res]
+        fa_pre = false_accepts(wide_res)
+        top1_pre = wide[0][0] if wide else None
+        print("  宽检索 top1=%s  top10 内 False ACCEPT=%s"
+              % (top1_pre, fa_pre or "无"))
+
+        # 渐进：候选间区分性条件词 → 带条件重排
+        POOL = ["我", "喝水", "吃饭", "电脑", "书", "音乐", "出门",
+                "浇花", "下班"]
+        cand_chars = {}
+        for r in wide_res[:10]:
+            nid = r[0]["id"]
+            cand_chars[nid] = frozenset(str(r[0].get("content") or ""))
+        cond = discriminative([p for p in POOL],
+                              [cand_chars.get(nid, frozenset())
+                               for nid, _s in wide[:10]])
+        if cond:
+            refined_res, _m2 = cg.search_rrf(QUERY + " " + cond,
+                                             k=10, judge=True, **KW)
+            fa_post = false_accepts(refined_res)
+            top1_post = refined_res[0][0]["id"] if refined_res else None
+            print("  区分性条件=%r → 重排 top1=%s  top10 内 "
+                  "False ACCEPT=%s" % (cond, top1_post, fa_post or "无"))
+            ok1 = top1_post in gold_ids
+            no_new = set(fa_post) <= set(fa_pre)
+            print("  断言①渐进后 top1∈gold：%s" % ("PASS" if ok1 else "FAIL"))
+            print("  断言②渐进不引入新冒充（fa_post⊆fa_pre）：%s"
+                  % ("PASS" if no_new else "FAIL"))
+            if fa_post:
+                for r in refined_res[:10]:
+                    if r[0]["id"] in fa_post and len(r) > 2:
+                        print("    冒充 %s judge reason：%s"
+                              % (r[0]["id"],
+                                 (r[2] or {}).get("reason", "")))
+            print("  边界（如实）：条件面冒充（生效条件被伪造为 gold 同款）"
+                  "不被内容词渐进消除——词面条件确认是必要非充分，"
+                  "真伪判据=verification_basis/时间线冲突（证据强度分离，另案）")
+            return ok1 and no_new
+        print("  无区分性条件可选（宽检索已无冒充）——如实记录")
+        return not fa_pre
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def main():
+    exp_locomo()
+    ok = exp_controlled()
+    print("\n[progressive] 完成。受控池消歧断言：%s"
+          % ("PASS" if ok else "FAIL"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/md_cg/bench_unified_en.py

@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+"""locomo-zh-500 英文侧统一标准真源路复测（2026-09-14）。
+
+背景：统一标准真源语义路（MDCG_SEMANTIC=1，semantic/canonical.py）已在受控
+盲测（bench_blind_comp b3_unified 臂）实证「英文原题经 query_atoms 内部归一
+（en_normalizer→中文语素→标准原子）直查 fm.semantic 摘要，L2 hit@1=100%」。
+本脚本回答开放域问题：真实 locomo 语料 + 500 道英文原题上，统一真源路净效应
+多大？en→zh 归一词表覆盖瓶颈多大？
+
+三臂（同题同池，只变 doc 侧正文形态与开关）：
+
+* u0_en_lex  ：doc=英文原文正文（text+[date]），默认词法路——英文 char-bigram
+  对英文正文的词法基线（现状跨语答案所在层的对照组）；
+* u1_unified ：doc=英文原文正文 + fm.semantic=segment(中文摘要)（AI 写入侧
+  归一的规则近似下界），MDCG_SEMANTIC=1，英文原题直查——语义增量 = u1-u0；
+* u2_pure_zh ：doc=中文五槽正文（zh）+ fm.semantic 同上，英文原题直查——
+  英文 query 对中文正文词法零交集，唯一通路就是归一原子与语义资格层——
+  「英文检索路径归一化到统一标准真源」的最强形态。
+
+诚实边界（报告须原样引用）：
+
+* fm.semantic 为规则切分（segment）非 AI 真实归一——下界口径；
+* en→zh 归一词表（EN_ZH 手工表）远小于中文原子空间，英文专名/域词保留原文
+  → 对中文 doc 零命中——词表覆盖瓶颈按题级 OOV 统计报告；
+* 池全为 gold 证据语料（bench6 同源口径）→ 指标是上界而非端到端记忆能力；
+* question_en 是英文自然语言问句，中文侧 questions500.question 是关键词串
+  → 本测只与自身三臂对照，不与中文口径 94.6/99.2 直接比（题面形态不同）。
+
+跑法：python -m md_cg.bench_unified_en
+"""
+import json
+import os
+import shutil
+import sys
+import time
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+for _p in (HERE, os.path.join(HERE, "md_cg")):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from md_cg import eval_common as ec            # noqa: E402
+from md_cg import bench6_common as b6          # noqa: E402  口径/数据源复用
+from md_cg.mdcos import MdCGOS                 # noqa: E402
+from md_cg.semantic.canonical import semantic_atoms, query_atoms  # noqa: E402
+
+ARM_ROOT = os.path.join(HERE, "_md_cg_eval_unified_en")  # gitignore 已覆盖
+K = 10
+
+
+def build(root, corpus, semantic_of=None, zh_body=False):
+    """单库构建：正文形态与 fm.semantic 摘要层是仅有的两个自由度。"""
+    if os.path.isdir(root):
+        shutil.rmtree(root, ignore_errors=True)
+    cg = MdCGOS(root, autoflush=500)
+    for c in corpus:
+        kw = {}
+        if semantic_of is not None:
+            sem = semantic_of(c)
+            if sem:
+                kw["semantic"] = sem
+        body = c.get("zh") if zh_body else b6.ingest_text_en(c)
+        cg.add(c["id"], body, layer="knowledge",
+               eval_src="unified_en", verification_basis="data", **kw)
+    cg.flush()
+    ec.install_read_cache(cg)
+    return cg
+
+
+def run_arm(cg, questions, tag, semantic=False):
+    if semantic:
+        os.environ["MDCG_SEMANTIC"] = "1"
+    else:
+        os.environ.pop("MDCG_SEMANTIC", None)
+    rows = ec.evaluate_group(cg, questions, k=K, paths=("lexical",),
+                             judge=False, verbose=False)
+    summ = ec.summarize(rows, k=K)
+    by_type = {"ALL": summ}
+    for qt in sorted({r["qtype"] for r in rows}):
+        sub = [r for r in rows if r["qtype"] == qt]
+        by_type[qt] = ec.summarize(sub, k=K)
+    return rows, by_type
+
+
+def oov_stats(questions):
+    """题级 en→zh 归一覆盖统计：英文保留词占比 = 词表覆盖瓶颈的直接量化。"""
+    n_tok = n_keep = n_q_with_keep = 0
+    for q in questions:
+        atoms = query_atoms(q["question"])
+        keeps = [a for a in atoms if any("A" <= ch <= "z" for ch in a)]
+        n_tok += len(atoms)
+        n_keep += len(keeps)
+        if keeps:
+            n_q_with_keep += 1
+    return {"n_questions": len(questions),
+            "n_atoms": n_tok,
+            "n_en_keep": n_keep,
+            "keep_ratio": round(n_keep / n_tok, 4) if n_tok else 0.0,
+            "q_with_keep_ratio": round(n_q_with_keep / len(questions), 4)
+            if questions else 0.0}
+
+
+def main():
+    t0 = time.time()
+    rows500 = list(ec.iter_jsonl(b6.QUESTIONS500))
+    corpus = list(ec.iter_jsonl(b6.CORPUS567))
+    en_by_qid = {r["qid"]: r for r in ec.iter_jsonl(b6.EN_QUESTIONS)}
+    # 全量 500 题（不抽样），中英 qrels 逐字一致断言复用 bench6 口径
+    questions = b6.align_queries(rows500, en_by_qid)
+    for q in questions:
+        q["question"] = q["question_en"]        # 英文原题直查
+    print("[unified_en] 题 %d（英文原题全量）/ 语料 %d / k=%d"
+          % (len(questions), len(corpus), K))
+
+    ec.unlock_global_cap()
+    ec.use_jaccard()
+
+    def sem_of(c):
+        s = str((c.get("zh_fields") or {}).get("summary") or "").strip()
+        if not s:
+            s = str(c.get("zh") or "").strip()
+        return " ".join(semantic_atoms(s)) if s else ""
+
+    out = {"n_q": len(questions), "n_corpus": len(corpus), "k": K,
+           "arms": {}, "oov": oov_stats(questions),
+           "semantic_rule": "segment(zh_fields.summary)，OOV 保留——规则近似下界"}
+
+    cg0 = build(os.path.join(ARM_ROOT, "u0"), corpus)               # 英文正文
+    cg1 = build(os.path.join(ARM_ROOT, "u1"), corpus, sem_of)       # +semantic
+    cg2 = build(os.path.join(ARM_ROOT, "u2"), corpus, sem_of,
+                zh_body=True)                                        # 纯中文库
+    arms = ((cg0, "u0_en_lex", False),
+            (cg1, "u1_unified", True),
+            (cg2, "u2_pure_zh", True))
+    # CLI：--arms u2,u2c 只跑指定臂（归因探针用）；--out 改结果文件名
+    argv = sys.argv[1:]
+    only = None
+    out_name = "unified_en_baseline.json"
+    if "--arms" in argv:
+        only = set(argv[argv.index("--arms") + 1].split(","))
+        arms = tuple((cg, tag, sem) for cg, tag, sem in arms if tag in only)
+    if "--out" in argv:
+        out_name = argv[argv.index("--out") + 1]
+    if not arms:
+        print("[arms] 无匹配臂")
+        return
+    for cg, tag, sem in arms:
+        _rows, by_type = run_arm(cg, questions, tag, semantic=sem)
+        out["arms"][tag] = by_type
+        mode = ("MDCG_SEMANTIC=1" if sem else "词法默认") + \
+               (" + fm.semantic 摘要层" if sem else "")
+        print("\n== 臂 %s（%s）==" % (tag, mode))
+        for name, s in by_type.items():
+            print("  %-18s hit@1=%6.1f%%  hit@%d=%6.1f%%  MRR=%.4f  (n=%d)"
+                  % (name, s["hit@1"] * 100, K, s["hit@%d" % K] * 100,
+                     s["mrr"], s["n"]))
+        if tag == "u2_pure_zh":
+            # 归因臂 u2c：中文关键词原题 × 同一纯中文库 × 同一语义路——
+            # 钉「语义路机制 + doc 侧摘要」上界。u2c 远高于 u2 → 瓶颈纯在
+            # query 侧 en→zh 归一（扩表有效）；u2c 亦低 → 瓶颈在 win6 共现
+            # 机制或 doc 侧，扩表无效。
+            zh_q = [dict(q, question=q["question_zh"]) for q in questions]
+            _rc, by_c = run_arm(cg, zh_q, "u2c", semantic=True)
+            out["arms"]["u2c_zh_sem_attribution"] = by_c
+            print("== 臂 u2c_zh_sem_attribution（中文题面 × 同库同语义路，归因上界）==")
+            for name, s in by_c.items():
+                print("  %-18s hit@1=%6.1f%%  hit@%d=%6.1f%%  MRR=%.4f  (n=%d)"
+                      % (name, s["hit@1"] * 100, K, s["hit@%d" % K] * 100,
+                         s["mrr"], s["n"]))
+        cg.close()
+
+    a0, a1, a2 = ((out["arms"].get(t) or {}).get("ALL") for t in
+                  ("u0_en_lex", "u1_unified", "u2_pure_zh"))
+    if not all((a0, a1, a2)):
+        print("[arms] 单臂探针模式，跳过 deltas")
+        ec.save_result(out_name, out)
+        print("\n[unified_en] 完成（%.1fs），结果已存 %s"
+              % (time.time() - t0, out_name))
+        return
+    out["deltas"] = {
+        "u1_minus_u0_hit@1": round(a1["hit@1"] - a0["hit@1"], 4),
+        "u1_minus_u0_hit@10": round(a1["hit@%d" % K] - a0["hit@%d" % K], 4),
+    }
+    out["elapsed_s"] = round(time.time() - t0, 1)
+    out["boundaries"] = [
+        "池全为 gold 证据语料 → 指标是上界而非端到端记忆能力",
+        "fm.semantic=规则切分（segment），非 AI 真实归一 → 下界口径",
+        "英文题面为自然问句，中文口径 94.6/99.2 的题面是关键词串——"
+        "两口径题面形态不同，不可直接比较",
+        "en→zh 归一词表覆盖瓶颈见 out.oov（英文保留词占比）——扩表是明确路径",
+        "u2 纯中文库上英文词法零交集 → 该臂成绩全部来自统一真源语义路",
+        "u2c 归因臂=中文题面×同库×同语义路 → u2c−u2 差值即 query 侧归一缺口，"
+        "u2c 自身即机制+doc 侧上界",
+    ]
+    ec.save_result(out_name, out)
+    print("\n[unified_en] 完成（%.1fs），结果已存 %s" % (out["elapsed_s"], out_name))
+
+
+if __name__ == "__main__":
+    main()

package/md_cg/census.py

@@ -23,15 +23,27 @@ from md_cg import nodefile, routing
 DEFAULT_ROOT = os.path.join(
     os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "data", "mdcg")
 
+#: 归档区目录名：这些目录下的 .md 是**库存/历史**（软删除的墓碑、覆盖保护的快照），
+#: 不是活跃节点。此前不剪枝，导致同一库被报成「54 活跃 + 67 墓碑 = 123 节点」，
+#: 而本函数的结论是「分桶键有没有区分度」的 go/no-go 判据（见模块 docstring：
+#: 「任何新库接入前都应先跑一遍」）——被历史稀释后，判据本身失真。
+#: 与 mdcg_maintain.py 的 _is_archived() 同口径。
+ARCHIVE_DIRS = ("trash", "_protected_history", "_protected", "_index_log", "hippocampus")
+
 
 def load(root):
     """遍历 md 记忆库根，返回 [(node_id, layer, condition_space, tags), ...]。
 
     只认能被 nodefile.loads 解析出 frontmatter 的 .md —— 解析不出说明不是节点文件
     （例如随手放进来的说明文档），直接跳过而不是塞进空条件桶污染统计。
+    归档区（ARCHIVE_DIRS）整体剪枝，不参与普查。
     """
     out = []
-    for dirpath, _dirs, files in os.walk(root):
+    for dirpath, dirs, files in os.walk(root):
+        # 剪枝必须在遍历 files 之前：归档区不仅自己不普查，
+        # 也不允许继续下钻（_protected_history/<id>/<ts>.md 是两层）。
+        dirs[:] = [d for d in dirs
+                   if d not in ARCHIVE_DIRS and not d.startswith("_protected_history_")]
         for fn in files:
             if not fn.endswith(".md"):
                 continue

package/md_cg/codeindex.py

@@ -291,8 +291,45 @@ def node_id(item):
     return "code_" + hashlib.sha1(key).hexdigest()[:12]
 
 
+def skip_matcher(skip_dirs):
+    """把调用方的 `skip_dirs` 编译成「该子目录是否排除」的判定 `hit(rel_dir, base)`。
+
+    与 `SKIP_DIRS` 在**同一处**生效，且**只增不减**：调用方只能追加排除，不能拿掉
+    `.git`/`.venv` 这类内置保护——否则一次参数写错就能把版本库元数据索引进认知图。
+    规则口径（两类可混用）：
+      · 含 `/` → 按**相对 root 的路径**匹配（`docs/experiments` 只排这一处）；
+      · 不含 `/` → 按**目录名**匹配（`experiments` 排任意层级的同名目录）。
+    反斜杠与首尾斜杠一律归一，避免「规则传了却不生效」这类静默失配。
+
+    返回 `(hit, rules)`；`rules` 为空时 `hit is None` → 调用方走原路径，
+    保证**默认行为与改造前逐字一致**（与 `fresh`/`on_file` 同一纪律）。
+    排除的**理由**：`.gitignore` 整目录忽略的实验产物物理仍在盘上，会把
+    `max_files` 撑爆并让「索引不全」变成常态；用「显式排除 + 回报」比「调大上限」
+    诚实。`docindex` 复用本函数（唯一实现，避免两处口径漂移）。
+    """
+    rules, names, paths = [], set(), []
+    for raw in (skip_dirs or ()):
+        s = str(raw).strip().replace("\\", "/").strip("/")
+        if not s:
+            continue
+        rules.append(s)
+        if "/" in s:
+            paths.append(s)
+        else:
+            names.add(s)
+    if not rules:
+        return None, []
+
+    def hit(rel_dir, base):
+        if base in names:
+            return True
+        return any(rel_dir == p or rel_dir.startswith(p + "/") for p in paths)
+
+    return hit, rules
+
+
 def index_dir(root, patterns=None, max_files=500, max_items=2000,
-              fresh=None, on_file=None):
+              fresh=None, on_file=None, skip_dirs=None):
     """按大域（目录）遍历代码，产出 `(items, errors, stats)`。零 LLM。
 
     `stats["truncated"]` 必须显式上报——截断**不再是静默的**：改造前达到上限
@@ -305,15 +342,34 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
       · `fresh` 返回 True → 该文件自上次索引后未变，**不读盘**直接跳过，
         计入 `skipped_unchanged`（仍计入 `files`，故截断语义不变）；
       · `on_file` 在成功提取后回调，用于记录水位。
+
+    `skip_dirs` 是**追加**排除（见 `skip_matcher`）：命中的目录整棵剪掉、不计入
+    `files`；实际排掉了哪些目录写进 `stats["skipped_dirs"]`——**排除与截断一样不许
+    静默**，否则「节点数变少」会被误读成「源文件真的少了」。
     """
     pats = tuple(patterns or SUFFIX)
+    hit_skip, skip_rules = skip_matcher(skip_dirs)
     items, errors, files = [], [], 0
     seen_suffix = set()
     stats = {"root": root, "patterns": list(pats), "files": 0, "truncated": False,
              "truncated_reason": "", "max_files": max_files, "max_items": max_items,
-             "skipped_suffixes": [], "skipped_unchanged": 0}
+             "skipped_suffixes": [], "skipped_unchanged": 0,
+             "skip_dirs": list(skip_rules), "skipped_dirs": []}
     for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        rel_dir = os.path.relpath(dirpath, root).replace("\\", "/")
+        if rel_dir == ".":
+            rel_dir = ""
+        keep = []
+        for d in dirnames:
+            if d in SKIP_DIRS:
+                continue
+            child = f"{rel_dir}/{d}" if rel_dir else d
+            if hit_skip is not None and hit_skip(child, d):
+                # 就地追加、不依赖末尾汇总：截断提前 return 时也带得走（同 skipped_suffixes）。
+                stats["skipped_dirs"].append(child)
+                continue
+            keep.append(d)
+        dirnames[:] = keep
         for fn in sorted(filenames):
             ext = os.path.splitext(fn)[1].lower()
             seen_suffix.add(ext)