@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/md_cg/mcp_server.py

@@ -117,12 +117,17 @@ TOOLS = [
                           },
     {
         "name": "mdcg_recall",
-        "description": "按 token 预算召回记忆包（RRF 多路融合，超大条目跳过而非停下）。"
+        "description": "按 token 预算召回记忆包（RRF 多路融合）。装包策略：条目超预算时"
+                       "**按 max_item_tokens 截取前 N token 摘录纳入**（返回体标 truncated=true），"
+                       "仅当剩余预算放不下最小摘录时才跳过——避免旧行为"
+                       "「跳过超大、继续试更小的」在预算紧张时淘汰最有价值的详实条目。"
                        "会话开始或重要工作前调用。可选启用第 5 路模糊召回（分级隶属度）"
                        "与第 6 路条件语义路（条件结构驱动），并注入调用方 LLM 的查询"
                        "扩展词（索引侧始终白箱）。",
         "inputSchema": _s("", query=_p("string", "描述当前任务的查询", True),
                           budget_tokens=_p("integer", "token 预算（默认 1200）"),
+                          max_item_tokens=_p("integer", "单条上限（默认 250）；超限条目截断纳入。"
+                                                        "传 0 关闭截断、回到「超大一律跳过」的旧行为"),
                           k=_p("integer", "候选上限"), context=_p("object", "当前情境条件空间"),
                           include_work=_p("boolean", "是否含工具输出/命令/编辑（默认否）"),
                           fuzzy=_p("boolean", "启用第 5 路模糊召回（分级隶属度，默认否）"),
@@ -131,6 +136,8 @@ TOOLS = [
                                                "四槽，不适用条件命中即剔除；默认否）"),
                           expand=_p("array", "LLM 查询侧扩展词：[{term,weight}] 或 [\"词\"]；"
                                              "仅在查询时刻生效，索引侧仍白箱"),
+                          session=_p("string", "会话归属过滤（frontmatter.session；"
+                                     "多会话共用 root 时只取本会话记忆；缺省不过滤）"),
                           goal=_p("string", "当前目标（第 5 篇第 3 章）：启用 goal 路给召回定向；"
                                             "省略则自动取活跃目标"),
                           goal_path=_p("boolean", "启用目标定向路（默认否；给 goal 即自动启用）"),
@@ -146,7 +153,9 @@ TOOLS = [
         "description": "精确检索（T0–T3 阶梯 + 四态资格判定）。返回 score/state/tier。",
         "inputSchema": _s("", query=_p("string", "查询", True), k=_p("integer", "条数"),
                           layer=_p("string", "限定层"), context=_p("object", "情境"),
-                          roles=_p("array", "限定角色"), include_work=_p("boolean", "含工作角色")),
+                          roles=_p("array", "限定角色"), include_work=_p("boolean", "含工作角色"),
+                          session=_p("string", "会话归属过滤（frontmatter.session；"
+                                     "缺省不过滤）")),
     },
     {
         "name": "mdcg_get",
@@ -314,7 +323,7 @@ TOOLS = [
     {
         "name": "mdcg_self_state",
         "description": "自我状态层（薄自我 + 富索引）：self 层只放一张自我状态卡"
-                       "（单例）+ 有向关系节点，登记八项自我信息的当前值与指针"
+                       "（单例）+ 有向关系节点，登记九项自我信息的当前值与指针"
                        "（信息差 D/d1/d2、信任 P_gap/P_trust、情绪=d²D/dt²、"
                        "情感=d²T/dt²、短期记忆窗口摘要、重要性、身份锚点、关系度）；"
                        "具体任务/人物/会话/时间/信任的细节仍留在原层，按五维索引"
@@ -508,7 +517,7 @@ KERNEL_TOOLS = [
                        "action=report|trace|calibration|blindspots|trust|self_check|"
                        "history|catalog）；"
                        "op=self_state：自我状态层（薄自我+富索引：状态卡单例 + 关系节点，"
-                       "八项自我信息只存当前值与指针，具体任务/人物/会话/时间/信任由认知图"
+                       "九项自我信息只存当前值与指针，具体任务/人物/会话/时间/信任由认知图"
                        "按五维索引连接；action=snapshot|refresh|bootstrap|relate|relations|"
                        "index|dimensions|audit|history|summary|catalog）；"
                        "op=info：身份+健康+审核体系自描述；"
@@ -627,7 +636,7 @@ KERNEL_TOOLS = [
                                 "isolate|withdraw|decay|policy|card|publish|peers|"
                                 "evidence|export|import|derive|derive_dangling|"
                                 "derive_catalog|derive_rebuild|catalog；"
-                                "ref: read|check|stat；"
+                                "ref: read|check|stat|prune；"
                                 "session: note|recall|compact；"
                                 "ingest: file|dir|jsonl|stat；"
                                 "export: graph|nodes|slice|stat；"
@@ -655,6 +664,16 @@ KERNEL_TOOLS = [
             path=_p("string", "index_code/index_doc 的目录（大域）；link import 的证据包文件"),
             patterns=_p("array", "index_code/index_doc 的文件后缀，默认取各自注册表"
                                  "（代码 .py/.ts/.tsx/.js/.mjs/.cjs；文档 .md/.markdown）"),
+            skip_dirs=_p("array", "index_code/index_doc 的**追加**排除目录（只增不减："
+                                  "内置 .git/.venv/node_modules 等不可被关闭）。含 / 按"
+                                  "相对 root 的路径匹配（docs/experiments 只排这一处）；"
+                                  "不含 / 按目录名匹配（experiments 排任意层级同名目录）。"
+                                  "被排掉的目录见返回 skipped_dirs（排除与截断一样不静默）"),
+            prune=_p("boolean", "index_code/index_doc：索引后清退「同 root + 同 path "
+                                "但已不在本次产出中」的过期代节点（文档改标题致 node_id "
+                                "重算时产生），默认开；截断时不执行"),
+            prune_dry_run=_p("boolean", "prune 预演：只列待清退节点，不落删除"),
+            roots=_p("array", "ref action=prune：只清这些 root 下的悬空节点（默认全部）"),
             max_files=_p("integer", "index_code/index_doc 最多扫描文件数（被截断时"
                                     "返回里会显式给 truncated，不再静默不完整）"),
             max_items=_p("integer", "index_code/index_doc 最多产出条目数（越限即截断并上报）"),
@@ -668,7 +687,9 @@ KERNEL_TOOLS = [
             ref=_p("object", "ref op：直接给 code_ref/doc_ref 对象（与 node_id 二选一）"),
             root=_p("string", "ref op：覆盖 ref 里记录的 root（索引结果的跨机器搬迁）"),
             name=_p("string", "sustain：心跳名（默认 md_cg）"),
-            session=_p("string", "sustain：会话 id（resume/note 用）"),
+            session=_p("string", "read（search/recall 分支）：会话归属过滤"
+                                 "（frontmatter.session；缺省不过滤）；"
+                                 "sustain：会话 id（resume/note 用）"),
             ts=_p("number", "sustain note：事件时间戳"),
             seq=_p("integer", "sustain note：事件序号"),
             task_running=_p("boolean", "sustain：任务执行中（心跳阈值放宽）"),
@@ -996,7 +1017,7 @@ def _metacognition_call(cg, a):
 def _self_state_call(cg, a):
     """自我状态层统一入口（cg op=self_state 与 mdcg_self_state 共用）。
 
-    薄自我：self 层只放状态卡（单例）+ 关系节点，登记八项自我信息的当前值
+    薄自我：self 层只放状态卡（单例）+ 关系节点，登记九项自我信息的当前值
     与指针；具体任务/人物/会话/时间/信任的细节留在原层，由认知图按五维
     索引连接。一致性由 audit 重算校验（不依赖人的判断）。
     """
@@ -1078,7 +1099,8 @@ def _predict_call(cg, a):
             a.get("predicted_node_id") or a.get("node_id") or "",
             actual_node_id=a.get("actual_node_id"),
             hit=a.get("hit"), note=a.get("note") or "",
-            actor=a.get("actor") or getattr(cg, "actor", "predict"))
+            actor=a.get("actor") or getattr(cg, "actor", "predict"),
+            sync_self=bool(a.get("sync_self", True)))
     if act == "stats":
         return cg.predict_stats(limit=int(a.get("limit") or 20))
     if act == "catalog":
@@ -1285,7 +1307,10 @@ def _sustain_call(cg, a):
             auto_scrub=bool(a.get("auto_scrub", False)),
             evolve_interval=float(a.get("evolve_interval")
                                   or sustain.DEFAULT_EVOLVE_INTERVAL),
-            auto_evolve=bool(a.get("auto_evolve", False)))
+            auto_evolve=bool(a.get("auto_evolve", False)),
+            tidy_interval=float(a.get("tidy_interval")
+                                or sustain.DEFAULT_TIDY_INTERVAL),
+            auto_tidy=bool(a.get("auto_tidy", False)))
         return {"loop": lp.start().status()}
     if act in ("stop", "down"):
         lp = sustain.get_loop(cg, name)
@@ -1307,6 +1332,7 @@ def _sustain_call(cg, a):
                 "heal_interval": sustain.DEFAULT_HEAL_INTERVAL,
                 "scrub_interval": sustain.DEFAULT_SCRUB_INTERVAL,
                 "evolve_interval": sustain.DEFAULT_EVOLVE_INTERVAL,
+                "tidy_interval": sustain.DEFAULT_TIDY_INTERVAL,
                 "evolve_fixes": dict(sustain.EVOLVE_FIXES),
                 "provenance_fixes": {},     # 悬空派生边只检出、无自动修复
 
@@ -1375,7 +1401,33 @@ def _scrub_call(cg, a):
 
 
 def _cg_call(cg, a):
-    """认知图唯一入口。"""
+    """认知图唯一入口（外层：op 缺省推导兜底 + 推导透出；分发主体见 _cg_dispatch）。"""
+    op0 = (a.get("op") or "").strip().lower()
+    op = op0
+    if not op:
+        # op 缺省推导兜底：复杂任务后 agent 精力分散漏传 op 时，
+        # 旧行为静默降级 read（写入意图被吞，排查成本高）——按参数签名猜意图。
+        if a.get("content"):
+            op = "write"
+        elif a.get("query") or a.get("node_id"):
+            op = "read"
+        elif a.get("intent"):
+            op = "route"
+        else:
+            op = "read"        # 无任何签名可依：维持旧缺省 read
+    args = dict(a)
+    args["op"] = op
+    out = _cg_dispatch(cg, args)
+    if isinstance(out, dict) and not op0:
+        out["op"] = op
+        out["op_derived"] = True
+        out["hint"] = ("op 未显式传入，已按参数签名推导（本次按 %s 执行）；op 为必填参数，"
+                       "复杂任务中也请始终显式传 op，避免静默执行错误意图" % op)
+    return out
+
+
+def _cg_dispatch(cg, a):
+    """认知图唯一入口的 op 分发主体。"""
     op = (a.get("op") or "read").strip().lower()
     _p = getattr(cg, "principal", None)
     if _p is not None and hasattr(_p, "require_op"):
@@ -1550,10 +1602,12 @@ def _cg_call(cg, a):
                              k=int(a.get("k") or 20), context=a.get("context"),
                              goal_text=a.get("goal"),
                              include_recent=bool(a.get("include_recent")),
-                             recent_limit=int(a.get("limit") or 10))
+                             recent_limit=int(a.get("limit") or 10),
+                             session=a.get("session"))
         from . import refindex
         res, meta = cg.search(q, layer=a.get("layer"), k=int(a.get("k") or 20),
-                              context=a.get("context"))
+                              context=a.get("context"),
+                              session=a.get("session"))
         return {"meta": meta, "results": [
             {"node": _node_view(n), "score": s, "state": q2.get("state"),
              "reason": q2.get("reason"), **refindex.ref_fields(n)}
@@ -1598,7 +1652,14 @@ def _cg_call(cg, a):
                                      **_proposal_extras(a, verdict))
                     return {"ok": False, "id": nid, "pid": pid, "committed": False,
                             "moved_to": "review_queue", "consistency": cvd,
-                            "verdict": verdict}
+                            "verdict": verdict,
+                            "hint": "这是冲突闸门的正常行为：本次写入与既有条件/纪律冲突"
+                                    "（on_conflict=defer），已转入审核队列待裁决——"
+                                    "不是工具故障，重试同样结果；"
+                                    "落盘须由设计者权限（can_admin）裁决，转告使用者："
+                                    "python scripts/review_cli.py list 后 accept/reject，"
+                                    "或 cg(op=review, pid=<pid>, decision=accept|reject|"
+                                    "edit|merge, reason=<理由>)"}
             if a.get("gated"):
                 hint = a.get("importance_hint")
                 if hint is None and a.get("importance") is not None:
@@ -1642,12 +1703,21 @@ def _cg_call(cg, a):
                                   verification_basis=verdict.get("basis") or "test",
                                   tags=a.get("tags"))
             return {"ok": False, "id": rid, "committed": False,
-                    "moved_to": "rejected", "verdict": verdict}
+                    "moved_to": "rejected", "verdict": verdict,
+                    "hint": "这是审核闸门的正常行为：内容未过内容政策审核（REJECT），"
+                            "已记入负记忆——不是工具故障，重试同样结果；"
+                            "拒绝依据见 verdict.evidence"}
         pid = cg.propose(nid, a.get("content", ""), layer=a.get("layer") or "knowledge",
                          tags=a.get("tags"), condition_space=a.get("condition_space"),
                          **_proposal_extras(a, verdict))
         return {"ok": True, "id": nid, "pid": pid, "committed": False,
-                "moved_to": "review_queue", "verdict": verdict}
+                "moved_to": "review_queue", "verdict": verdict,
+                "hint": "这是校验闸门的正常行为（verdict=%s）：内容未达 ACCEPT，"
+                        "已入审核队列——不需要重试；落盘须由设计者权限（can_admin）"
+                        "对提案 pid 裁决（agent 端无裁决权是设计），转告使用者："
+                        "python scripts/review_cli.py list 后 accept/reject，"
+                        "或 cg(op=review, pid=<pid>, decision=accept|reject|"
+                        "edit|merge, reason=<理由>)" % verdict.get("state")}
 
     if op == "goal":
         act = (a.get("action") or "list").strip().lower()
@@ -1749,6 +1819,7 @@ def _cg_call(cg, a):
             max_files=int(a.get("max_files") or 500),
             max_items=int(a.get("max_items") or 2000),
             incremental=bool(a.get("incremental")),
+            skip_dirs=a.get("skip_dirs"),
             ledger=refindex.Ledger(cg.root))
         ids, _sens = refindex.add_items(cg, items, kind="code_ref", root=root,
                                         layer=a.get("layer"))
@@ -1760,11 +1831,14 @@ def _cg_call(cg, a):
                "files": stats["files"], "truncated": stats["truncated"],
                "skipped_unchanged": stats.get("skipped_unchanged", 0),
                "skipped_suffixes": stats["skipped_suffixes"], "note": note}
+        out.update(_skip_dirs_report(stats))
         if stats["truncated"]:
             # 截断必须显式说出来：以前静默 return，调用方以为索引是完整的。
             out["truncated_reason"] = stats["truncated_reason"]
             out["note"] = (f"⚠ 索引被截断，结果不完整（{stats['truncated_reason']}），"
                            f"调大 max_files/max_items 后重跑。" + note)
+        out["pruned"] = _prune_after_index(cg, a, kind="code_ref", root=root,
+                                           items=items, stats=stats)
         return out
 
     if op == "index_doc":
@@ -1779,7 +1853,8 @@ def _cg_call(cg, a):
             root, kind="doc_ref", patterns=a.get("patterns"),
             max_files=int(a.get("max_files") or 500),
             max_items=int(a.get("max_items") or 2000),
-            incremental=incremental, ledger=refindex.Ledger(cg.root))
+            incremental=incremental, skip_dirs=a.get("skip_dirs"),
+            ledger=refindex.Ledger(cg.root))
         ids, sens_counts = refindex.add_items(
             cg, items, kind="doc_ref", root=root, layer=layer,
             sensitivity=a.get("sensitivity"))
@@ -1793,10 +1868,13 @@ def _cg_call(cg, a):
                "skipped_unchanged": stats.get("skipped_unchanged", 0),
                "skipped_suffixes": stats["skipped_suffixes"],
                "layer": layer, "sensitivity": sens_counts, "note": note}
+        out.update(_skip_dirs_report(stats))
         if stats["truncated"]:
             out["truncated_reason"] = stats["truncated_reason"]
             out["note"] = (f"⚠ 索引被截断，结果不完整（{stats['truncated_reason']}），"
                            f"调大 max_files/max_items 后重跑。" + note)
+        out["pruned"] = _prune_after_index(cg, a, kind="doc_ref", root=root,
+                                           items=items, stats=stats)
         return out
 
     if op == "ref":
@@ -1861,6 +1939,42 @@ def _session_call(cg, a):
     raise ValueError(f"session 未知 action：{act}（允许 note/recall/compact）")
 
 
+def _prune_after_index(cg, a, *, kind, root, items, stats):
+    """索引后的**节点级对账**：清退「同 root + 同 path 的过期代」。
+
+    存在理由：`node_id` 含 heading_path，文档一改标题整篇 id 重算，而
+    `add_items` 只做**同 id 幂等 upsert**——不补这步，旧代节点与新代并存，
+    同一文档被召回两份（旧代引用的区间往往已失效）。水位层 `reconcile`
+    只剪水位条目、不剪节点，所以必须在索引后显式清。
+
+    开关：`prune=false` 关闭；`prune_dry_run=true` 只列清单不落删除；
+    截断时一律跳过（没扫完 ≠ 剩下的都过期）。
+    """
+    from . import refindex
+    flag = a.get("prune", True)
+    if isinstance(flag, str):
+        flag = flag.strip().lower() not in ("false", "0", "no", "off", "")
+    if not flag or stats.get("truncated"):
+        return None
+    return refindex.prune_orphans(
+        cg, kind=kind, root=root, items=items,
+        dry_run=bool(a.get("prune_dry_run")))
+
+
+def _skip_dirs_report(stats, limit=20):
+    """把「本次被 skip_dirs 排掉的目录」压成可审计字段。
+
+    与截断同一纪律——**不许静默**：调用方据此能把「源文件真的少了」与「被规则
+    排掉了」区分开。目录多时只回前 `limit` 个并给出总数，避免回报体被噪声撑爆。
+    """
+    sd = list(stats.get("skipped_dirs") or [])
+    out = {"skipped_dirs": sd[:limit], "skipped_dirs_count": len(sd),
+           "skip_dirs": list(stats.get("skip_dirs") or [])}
+    if len(sd) > limit:
+        out["skipped_dirs_note"] = f"另有 {len(sd) - limit} 个被排除目录未列出"
+    return out
+
+
 def _ingest_call(cg, a):
     """文件摄取分派（P0）：file / dir / jsonl / stat。
 
@@ -2059,8 +2173,19 @@ def _ref_call(cg, a):
                        "巡检只读、不改源文件；修复：op=index_code / op=index_doc 重建，"
                        "或 op=sustain action=heal。")
         return res
+    if action in ("prune", "prune_dangling"):
+        res = refindex.prune_dangling(
+            cg, only_roots=a.get("roots"), dry_run=bool(a.get("dry_run")),
+            max_nodes=int(a.get("max_nodes") or refindex.MAX_CHECK))
+        res["action"] = "prune"
+        res["note"] = ("清退悬空节点（ref 指向的源文件已删除，回读必然失败）。"
+                       "check 只报告、prune 才处置；dry_run=true 先列清单。"
+                       "受保护节点（self/anchor 层、protected 标记、"
+                       "importance≥0.7）会被拦下并列入 skipped_protected，"
+                       "不越权强删；删除可经 op=restore 回滚。")
+        return res
     if action not in ("read", "get"):
-        raise ValueError(f"ref 未知 action：{action}（支持 read|check|stat）")
+        raise ValueError(f"ref 未知 action：{action}（支持 read|check|stat|prune）")
     nid = (a.get("node_id") or "").strip()
     node = None
     if nid:
@@ -2215,15 +2340,22 @@ def _dispatch(cg, name, args):
         # self@1 拉低 10.1%，因为求和奖励「多路共识」、低估「模糊路独有」的目标。
         # semantic 路同理：条件结构命中常是「独有召回」，故一并缺省 max。
         fusion = a.get("fusion") or ("max" if (use_fuzzy or use_semantic or use_goal) else None)
+        # 默认单条上限从 mdcos 取（该模块只在 main() 里惰性导入，模块级没有名字，
+        # 直接引用 mdcos.DEFAULT_MAX_ITEM_TOKENS 会 NameError —— 故此处按需导入）。
+        from .mdcos import DEFAULT_MAX_ITEM_TOKENS as _DEFAULT_MAX_ITEM
         return cg.recall(a.get("query", ""),
                          budget_tokens=int(a.get("budget_tokens") or 1200),
+                         max_item_tokens=int(a["max_item_tokens"])
+                         if a.get("max_item_tokens") is not None
+                         else _DEFAULT_MAX_ITEM,
                          k=int(a.get("k") or 20), context=a.get("context"),
                          include_work=bool(a.get("include_work")),
                          paths=paths, fusion=fusion,
                          goal_text=a.get("goal"),
                          include_recent=bool(a.get("include_recent")),
                          recent_limit=int(a.get("recent_limit") or 10),
-                         query_expand=_make_query_expand(a.get("expand")))
+                         query_expand=_make_query_expand(a.get("expand")),
+                         session=a.get("session"))
 
     if name == "mdcg_search":
         from . import refindex
@@ -2231,7 +2363,8 @@ def _dispatch(cg, name, args):
                               k=int(a.get("k") or 20), context=a.get("context"),
                               roles=tuple(a["roles"]) if a.get("roles") else None,
                               include_work=bool(a.get("include_work")),
-                              pools=a.get("pools"))
+                              pools=a.get("pools"),
+                              session=a.get("session"))
         return {"meta": meta,
                 "results": [{"node": _node_view(n), "score": s, "state": q.get("state"),
                              "reason": q.get("reason"), **refindex.ref_fields(n)}
@@ -2381,6 +2514,12 @@ def _start_sustain(cg):
         evolve_interval=float(os.environ.get("MDCG_EVOLVE_INTERVAL")
                               or sustain.DEFAULT_EVOLVE_INTERVAL),
         auto_evolve=os.environ.get("MDCG_AUTO_EVOLVE", "0")
+        not in ("0", "false", "False"),
+        tidy_interval=float(os.environ.get("MDCG_TIDY_INTERVAL")
+                            or sustain.DEFAULT_TIDY_INTERVAL),
+        # 整理巡检（contextual 同构组聚合+成员降权）默认开：确定性动作、
+        # 永不删除节点（可逆可审计）；MDCG_AUTO_TIDY=0 关闭
+        auto_tidy=os.environ.get("MDCG_AUTO_TIDY", "1")
         not in ("0", "false", "False"))
     lp.start()
     return lp
@@ -2511,6 +2650,19 @@ def main():
     if not root:
         sys.stderr.write("[mdcg-mcp] 缺少 MDCG_ROOT 环境变量\n")
         return 2
+    # root 守卫（fail-closed）：`_md_cg_` 前缀目录是 md_cg 工具链的导出/评测
+    # 产物（白箱语料 _md_cg_wisdom_graph、评测灌库 _md_cg_eval_* 等——只读
+    # 或可再生语义），不是认知图 root；配成 root 写入会污染双表示
+    # （2026-09-13 workdone_readme_en500 错写白箱语料事故根因）。
+    # 启动即拒绝，不带病运行。
+    _base = os.path.basename(os.path.normpath(os.path.abspath(root)))
+    if _base.lower().startswith("_md_cg_"):
+        sys.stderr.write(
+            "[mdcg-mcp] MDCG_ROOT 指向 md_cg 工具链产物目录（`_md_cg_` 前缀，"
+            "白箱语料/评测快照，只读或可再生语义），禁止作为认知图 root：\n"
+            f"    {root}\n"
+            "[mdcg-mcp] 请指向主认知图目录（如仓库内 md_cg/）。\n")
+        return 2
     from .mdcos import MdCGSecure
     principal, err = _build_principal()
     if err:
@@ -2520,6 +2672,12 @@ def main():
             "    python -m md_cg.tokens issue --role designer --actor <你>\n"
             "然后设置 MDCG_TOKEN=<返回的明文令牌>。\n")
         return 3
+    # 会话归属（归因维度，不参与授权）：部署侧可为每个 agent 连接注入固定
+    # 会话 id（MDCG_SESSION），多会话共用一个 root 时按 frontmatter.session
+    # 区分「本会话记忆 / 其他会话记忆」；缺省=进程自动生成（sess_<uuid>）。
+    _p_session = os.environ.get("MDCG_SESSION", "").strip()
+    if _p_session:
+        principal.session = _p_session
     cg = MdCGSecure(root, principal=principal)
     # 外部验证器注入（**能力外置**）：识图/实测/验收等能力不在认知图内，
     # 由 MDCG_VERIFIER_MODULES（逗号分隔 import 路径）声明的外部模块注入，

package/md_cg/md_whitebox.py

@@ -12,18 +12,26 @@ nodes 4355 / edges 2948）无损导出为 md 认知图（`_md_cg_wisdom_graph/`
 ------------------------
 白箱检索层（`whitebox_kb/wisdom/semantic_translate.py`、`chat_engine.py`、
 `card_validator.py`、`neural_retrieve.py` 等）并非只调用 `dex` 的高层接口，
-而是**深度直查 SQL**——KCCS 注释索引、学科路由、四要素卡递归、知识点对齐
-等 7+ 处 `dex.store.conn.execute("SELECT ... FROM nodes ...")`。
-逐处改写成「读 md」既侵入又易错，还会让两条路径的行为悄悄分叉。
+历史上**深度直查 SQL**——KCCS 注释索引、学科路由、四要素卡递归、知识点
+对齐等 8 处 `dex.store.conn.execute("SELECT ... FROM nodes ...")`。
+逐处语法翻译成「读 md」既侵入又易错，还会让两条路径的行为悄悄分叉。
 
-故本模块把 md 语料还原成**同 schema 的检索库**，让白箱全部确定性检索
-逻辑零改动运行：
+**读路径现已收口到 md 直读访问层**（`whitebox_kb/wisdom/md_access.py`）：
+8 处直查统一经 `read_conn(dex)`，`WB_MD_DIRECT=1` 时走 md 语料
+（SELECT 子集解释器 + 行同构/行序复刻，对拍守卫
+`test_md_access_parity` 逐位一致），否则回落派生库。逐处语法翻译的
+教训由「同接口 + 机械对拍」替代：SQL 语义不翻写，数据源切换，
+行为分叉由测试红挡住。
+
+故本模块仍把 md 语料还原成**同 schema 的检索库**，作为派生库回落
+路径与引擎初始化底座，白箱全部确定性检索逻辑零改动运行：
 
     md 语料（唯一知识来源）
         │  build_db_from_md()      ← 本模块
         ▼
     检索库（同 schema · 可随时重建的派生物）
         │  WhiteboxEngine          ← 白箱引擎（seed=False，不污染语料）
+        │        ↑ read_conn(dex)  ← WB_MD_DIRECT=1 时检索读走 md 直读
         ▼
     回答（route / reply / hits）
 
@@ -125,8 +133,23 @@ def _edge_row(src, tgt, rel, conf, ver):
 
 
 def _restore(cg, con, verbose=False):
-    """md 语料 → 检索库（nodes / edges 两表）。返回 (n_nodes, n_edges)。"""
-    ids = list(cg.index["nodes"])
+    """md 语料 → 检索库（nodes / edges 两表）。返回 (n_nodes, n_edges)。
+
+    插入序规范 = **(LAYERS 序, 相对路径字典序)**（与白箱访问层
+    `whitebox_kb/wisdom/md_access.py::_load_rows` 同规范）：索引运行时序
+    （json 基础序 + 增量日志回放）含历史迁移序噪声且不可复现，
+    派生库行序必须由 md 实时状态确定性决定。
+    """
+    from .mdcg import LAYERS as _md_layers
+    _ord = {name: i for i, name in enumerate(_md_layers)}
+
+    def _order_key(nid):
+        e = cg.index["nodes"].get(nid) or {}
+        p = str(e.get("path")
+                or f"{e.get('layer') or 'zz'}/{nid}.md").replace("\\", "/")
+        return (_ord.get(p.split("/", 1)[0], 99), p)
+
+    ids = sorted(cg.index["nodes"], key=_order_key)
     n_rows, e_rows = [], []
     for i, nid in enumerate(ids, 1):
         d = cg.get(nid)