@furongjun1999/dsh-memory 0.4.6 → 0.4.8

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²、短期记忆窗口摘要、重要性、身份锚点、关系度）；"
                        "具体任务/人物/会话/时间/信任的细节仍留在原层，按五维索引"
@@ -487,7 +496,9 @@ KERNEL_TOOLS = [
     {
         "name": "cg",
         "description": "认知图接口（唯一入口）。op=route：按情境条件路由，返回相关知识 + "
-                       "建议能力名（不执行，由调用方决定）；op=read：召回/检索/按 id 取；"
+                       "建议能力名（不执行，由调用方决定）；op=read：召回/检索/按 id 取"
+                       "（长内容自动截断 2000 行 / 50KB，返回 truncated+next_offset，"
+                       "续读传 offset=next_offset，不静默丢内容）；"
                        "op=write：写入前按 content_kind 审核（ACCEPT 落盘 / REJECT 进负记忆 / "
                        "DEFER 进审核队列）+ 节点间冲突检测（三级决策：情绪→反思→递归反思；"
                        "consistency=false 可关，on_conflict=reject|defer|record）；"
@@ -498,6 +509,12 @@ KERNEL_TOOLS = [
                        "op=forget：软删除/恢复（受保护节点需 override）；"
                        "op=goal：目标槽（第 5 篇七件套之「目标」，"
                        "action=add|list|status；目标不进召回，只给 read 定向）；"
+                       "op=task：结构层任务实体（跨会话的工程台账，与信任/自我/协议同级；"
+                       "action=open 登记或更新（同名即同卡）、status 状态迁移"
+                       "（进行中/受阻/完成/放弃，迁 完成 时结果必填）、plan_add 追加计划变更、"
+                       "get 单卡全字段、list 清单、find 同族提示（只提示不合并）、"
+                       "session 会话装配面（进行中+近期完成）；"
+                       "任务只存骨架，中间过程不入库，任务知识走 knowledge 层）；"
                        "op=recent：近期事件窗口（七件套之「近期事件」，"
                        "action=add|list|clear，滚动保留最近 N 条）；"
                        "op=identity：身份特征识别（智能论 v3.4 位置效应 + 扮演论"
@@ -508,7 +525,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：身份+健康+审核体系自描述；"
@@ -553,16 +570,44 @@ KERNEL_TOOLS = [
                        "另有节点**派生溯源**（区别于对端信任）：derive 列边、"
                        "derive_dangling 悬空巡检（只读、不删边）、derive_catalog 自描述、"
                        "derive_rebuild 按 frontmatter 重建台账（默认预演）；权威声明只在"
-                       "节点写入时产生（write/remember 的 derived_from），本层不新增写入口）。",
+                       "节点写入时产生（write/remember 的 derived_from），本层不新增写入口）；"
+                       "op=session：会话三件套（action=note 写要点 / recall 续接 / "
+                       "compact 压摘要；hook 缺失时的库侧替代——载体负责「何时做」、库保证"
+                       "「一次调用就够用」；note 与 compact(note=True) 需 can_write，recall 只读）；"
+                       "op=ingest：文件摄取（action=file|dir|jsonl|stat；写链需 can_write，"
+                       "支持 dry_run 预演与 incremental 增量去重、watermark 留痕）；"
+                       "op=export：全库导出（action=graph|nodes|slice|stat；导出整库属管理"
+                       "操作，一律 require_admin）；"
+                       "op=maintain：记忆维护（action=stat|history|importance|longterm|"
+                       "prefeed|separate|rollback|backfill|cap|exempt|vision_evidence|refine "
+                       "及其 *_history；权限按 action 分档：只读放行、prefeed 写入需 "
+                       "can_write、批量改写与 rollback 需 admin；dry-run 只出报表不改盘）；"
+                       "op=consolidate：离线固化（action=promote 提升 | induce 归纳 | "
+                       "contextualize 语境化，及其 _rollback/_history；批量提升属管理操作，"
+                       "一律 require_admin）；"
+                       "op=insight：洞察（action=window|record|verify|list|report|"
+                       "reconstruct|learn|outlook|catalog|fork|branch_rewrite|branch_search|"
+                       "branch_merge|branch_discard|branches；权限按 action 分档：只读放行、"
+                       "条件记账与分支写需 can_write、落库 apply 与分支弃置需 admin）；"
+                       "op=ccg：CCG 六要素编译器（action=compile|review|attest|link|"
+                       "recalibrate|units|catalog；入参统一在 ccg 对象里）。"
+                       "把对话记录编译为六要素候选 → **编外复核**（裁定 A：编译者不得自证，"
+                       "E041 机械拒绝）→ 落库；复核优先走蜂巢 reflect/verify 单元，"
+                       "蜂巢不可用则提示配置，或显式 allow_degrade 降级 harness 端子代理。",
         "inputSchema": _s("",
             op=_p("string", "route|read|write|verify|review|protect|identity|"
                             "consistency|metacognition|self_state|evolution|sustain|"
                             "scrub|predict|causal|"
-                            "forget|goal|recent|info|index_code|index_doc|ref|whitebox|"
+                            "forget|goal|task|recent|info|index_code|index_doc|ref|whitebox|"
                             "theory|link|session|ingest|export|maintain|consolidate|"
-                            "insight", True),
+                            "insight|ccg|help", True),
+            ccg=_p("object", "CCG 六要素编译器入参：{action, node_id, dialog, marks, "
+                             "slots, strict_spans, role, verdict, verifier, compiled_by, "
+                             "evidence, slot_corrections, model, jobs, blocking, wait_s, "
+                             "allow_degrade, channel, autostart, doctor, apply, basis}"),
             intent=_p("string", "route 的查询意图"), query=_p("string", "read 的查询"),
-            goal=_p("string", "goal op 的目标文本；read 的定向目标（缺省用活跃目标）"),
+            goal=_p("string", "goal op 的目标文本；read 的定向目标（缺省用活跃目标）；"
+                              "task op：任务目标（CCG「执行」栏）"),
             goal_status=_p("string", "goal op：active|done|dropped"),
             priority=_p("number", "goal op：优先级 0-1（兼作定向偏置依据）"),
             deadline=_p("string", "goal op：截止时间（仅排序用，不做硬约束）"),
@@ -576,8 +621,9 @@ KERNEL_TOOLS = [
             include_recent=_p("boolean", "read：是否附近期事件窗口（默认否）"),
             limit=_p("integer", "goal/recent 的返回条数；read 的近期事件条数"),
             node_id=_p("string", "节点 id"),
+            offset=_p("integer", "read 的续读起始行（1 基；传上次返回的 next_offset）"),
             content=_p("string", "write 的内容（建议含 CCG 5 要素注释）"),
-            content_kind=_p("string", "write 的内容类型：code|image_desc|text|permission|work_done|work_wip"),
+            content_kind=_p("string", "write 的内容类型：code|image_desc|text|permission|work_done|work_wip|ccg_marks"),
             layer=_p("string", "层：anchor|structural|knowledge|contextual|self"),
             tags=_p("array", "标签（cap:xxx 会作为 route 的建议能力名）"),
             importance=_p("number", "重要性 0-1"),
@@ -627,7 +673,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；"
@@ -643,7 +689,11 @@ KERNEL_TOOLS = [
                                 "promote_history|induce|contextualize|"
                                 "contextualize_rollback|contextualize_history；"
                                 "insight: window|record|verify|list|report|"
-                                "reconstruct|learn|outlook|catalog"),
+                                "reconstruct|learn|outlook|catalog|"
+                                "fork|branch_rewrite|branch_search|"
+                                "branch_merge|branch_discard|branches；"
+                                "分支六 act：node_ids/branch_id/note/content/"
+                                "reason 按 act 取用（rewrite 传 node_id+content）"),
             pid=_p("string", "review decide 的提案 id"),
             decision=_p("string", "review 裁决：accept|reject|edit|merge"),
             edits=_p("object", "review edit 的覆盖字段（不可含 verify）"),
@@ -655,6 +705,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 最多产出条目数（越限即截断并上报）"),
@@ -667,8 +727,11 @@ KERNEL_TOOLS = [
                                      "路径命中私有提示时保守降为 private）"),
             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 用）"),
+            name=_p("string", "sustain：心跳名（默认 md_cg）；"
+                              "task op：任务名（**身份判据**：同名即同任务，slug 归一后落 id）"),
+            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：任务执行中（心跳阈值放宽）"),
@@ -708,7 +771,8 @@ KERNEL_TOOLS = [
             hit=_p("boolean", "predict feedback：是否命中（缺省按 predicted==actual）"),
             rule=_p("string", "evolution record：规律（必填，一句话认知规律）"),
             missing=_p("string", "evolution record：补的是哪一维缺失条件"),
-            change=_p("string", "evolution record：这次具体改了什么"),
+            change=_p("string", "evolution record：这次具体改了什么；"
+                                "task op：本轮计划变更/新增问题（追加进「计划变更」节，可追溯）"),
             kind=_p("string", "evolution：condition_gap|layer_shift|general"),
             entry_id=_p("string", "evolution show/rollback：条目 id"),
             source=_p("string", "evolution record：来源 consolidate|verify|manual；"
@@ -789,7 +853,20 @@ KERNEL_TOOLS = [
             neighbors=_p("boolean", "insight reconstruct：是否并入一跳邻域（默认 true）"),
             recent_days=_p("integer", "insight outlook：近期窗口天数（默认 7）"),
             sample_limit=_p("integer", "insight outlook：抽样清单条数（默认 8）"),
-            max_events=_p("integer", "ingest：单次最多摄取事件数")),
+            max_events=_p("integer", "ingest：单次最多摄取事件数"),
+            task_status=_p("string", "task op：active|blocked|done|dropped；"
+                                     "迁 done 必须同时给 result（缺一不收）"),
+            plan=_p("string", "task op：分步计划（每轮覆盖更新，跨会话持久存在）"),
+            result=_p("string", "task op：任务结果（done 时必填；本次不传则**保留旧值**，"
+                                "不会被静默清空）"),
+            acceptance=_p("string", "task op：验收判据（怎么算完成）"),
+            boundary=_p("string", "task op：不适用条件/边界"),
+            note=_p("string", "task op：本轮备注（change 是计划变更，note 是附注）；"
+                              "self_state relate：备注"),
+            condition=_p("string", "task op：生效条件（CCG「生效条件」栏）；"
+                                   "self_state relate：关系成立条件"),
+            active_limit=_p("integer", "task action=session：进行中任务条数（默认 5）"),
+            done_limit=_p("integer", "task action=session：近期已完成条数（默认 5）")),
     },
     {
         "name": "stg",
@@ -812,8 +889,16 @@ SURFACE = os.environ.get("MDCG_MCP_SURFACE", "kernel").strip().lower()
 
 
 def tools_for_surface():
-    """kernel：只暴露 2 个基元；full：2 个基元 + 31 个细粒度工具（兼容/调试）。"""
-    return ALL_TOOLS if SURFACE == "full" else KERNEL_TOOLS
+    """kernel：只暴露 2 个基元；full：2 个基元 + 31 个细粒度工具（兼容/调试）。
+
+    返回**投影后**的工具面（工具一行职责 + 参数短提示）：完整语义由
+    ``cg(op=help, query=…)`` 按需取回。真源 KERNEL_TOOLS/TOOLS 保持完整定义，
+    投影只是运行时视图（信息零丢失，见 md_cg/tool_face.py）。
+    关闭投影：``MDCG_TOOL_FACE=full``。
+    """
+    tools = ALL_TOOLS if SURFACE == "full" else KERNEL_TOOLS
+    from .tool_face import slim_tools
+    return slim_tools(tools)
 
 
 # --------------------------------------------------------------------------
@@ -845,11 +930,60 @@ def _pick_source(path):
     return JsonlSource(path)
 
 
-def _node_view(node):
+READ_MAX_LINES = 2000           # 单次 read 返回行数上限（Pi⑦② 截断）
+READ_MAX_BYTES = 50 * 1024      # 单次 read 返回字节上限（Pi⑦② 截断）
+
+
+def _clip_text(text: str, *, offset: int = 0, max_lines: int = READ_MAX_LINES,
+               max_bytes: int = READ_MAX_BYTES) -> dict:
+    """行窗口 + 双阈值截断（Pi⑦② 截断必带续读提示）。
+
+    offset 为 1 基起始行（续读传上次 next_offset）。不静默丢内容——截断时
+    返回 total_lines / total_bytes / next_offset / note，调用方按 offset 续读。
+    """
+    text = text or ""
+    lines = text.split("\n")
+    total_lines = len(lines)
+    total_bytes = len(text.encode("utf-8"))
+    start = max(0, int(offset) - 1) if offset else 0
+    if start >= total_lines:
+        return {"text": "", "offset": start + 1, "next_offset": None,
+                "returned_lines": 0, "total_lines": total_lines,
+                "total_bytes": total_bytes, "truncated": False,
+                "note": f"offset={start + 1} 超出总行数 {total_lines}，返回空"}
+    got, used = [], 0
+    for ln in lines[start:start + max_lines]:
+        b = len(ln.encode("utf-8")) + 1
+        if got and used + b > max_bytes:
+            break
+        got.append(ln)
+        used += b
+    end = start + len(got)
+    truncated = end < total_lines
+    out = {"text": "\n".join(got), "offset": start + 1,
+           "next_offset": end + 1 if truncated else None,
+           "returned_lines": len(got), "total_lines": total_lines,
+           "total_bytes": total_bytes, "truncated": truncated, "note": ""}
+    if truncated:
+        out["note"] = (f"内容已截断（单次上限 {max_lines} 行 / {max_bytes} 字节）："
+                       f"共 {total_lines} 行 / {total_bytes} 字节，本次返回第 "
+                       f"{start + 1}–{end} 行；续读传 offset={end + 1}。")
+    return out
+
+
+def _node_view(node, offset: int = 0):
     if not node:
         return None
-    return {"id": node.get("id"), "path": node.get("path"),
-            "frontmatter": node.get("frontmatter"), "content": node.get("content")}
+    clip = _clip_text(node.get("content") or "", offset=offset)
+    out = {"id": node.get("id"), "path": node.get("path"),
+           "frontmatter": node.get("frontmatter"), "content": clip["text"]}
+    if clip["truncated"] or offset:
+        out.update({"truncated": clip["truncated"],
+                    "content_lines": clip["total_lines"],
+                    "content_bytes": clip["total_bytes"],
+                    "offset": clip["offset"], "next_offset": clip["next_offset"],
+                    "note": clip["note"]})
+    return out
 
 
 # --------------------------------------------------------------------------
@@ -996,7 +1130,7 @@ def _metacognition_call(cg, a):
 def _self_state_call(cg, a):
     """自我状态层统一入口（cg op=self_state 与 mdcg_self_state 共用）。
 
-    薄自我：self 层只放状态卡（单例）+ 关系节点，登记八项自我信息的当前值
+    薄自我：self 层只放状态卡（单例）+ 关系节点，登记九项自我信息的当前值
     与指针；具体任务/人物/会话/时间/信任的细节留在原层，由认知图按五维
     索引连接。一致性由 audit 重算校验（不依赖人的判断）。
     """
@@ -1078,7 +1212,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 +1420,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 +1445,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": {},     # 悬空派生边只检出、无自动修复
 
@@ -1374,9 +1513,200 @@ def _scrub_call(cg, a):
     raise ValueError(f"scrub 未知 action：{act}")
 
 
+# ---- action 缺省防呆（2026-09-16）------------------------------------------
+# 与「op 缺省静默降级」同构的第二类静默失败：op 传了、action 漏了 → 各分支按
+# 字面量默认 action 执行。若默认恰是**读类**，写意图会被静默吞掉且返回形似正常
+# 的结果——最典型是文档化契约 `cg(op=review, pid, decision, reason)`（不带
+# action）实际静默走 review_list，裁决从未落盘（契约与实现漂移）。
+# 处置：签名明确指向非默认 action → 按签名推导并透出 action_derived/hint_action；
+# 无签名可依 → 维持默认执行但同样透出标记，让「按默认走」可见而非静默。
+# 判据用「键存在且非 None」（False / 0 / "" 属显式传入），避免真值判断误吞。
+_ACTION_SIGS = {
+    "review":  (("decision", "decide"), ("node_id", "verify_record")),
+    "recent":  (("text", "add"), ("content", "add")),
+    "goal":    (("goal", "add"), ("action_hint", "add")),
+    # task：**写意图优先、读意图最后**。name→open 先命中——open（upsert）本身
+    # 兼容 plan/result/change 全字段，故「name+change」同传也不会丢信息；把
+    # change→plan_add 放其后，只在「只给 change」时才是纯追加变更。node_id→get
+    # 置于末位：否则「node_id+change」会被静默当成只读（写意图被吞，
+    # 与 review 的 `pid+decision` 静默走 list 同构）。
+    "task":    (("name", "open"), ("task_status", "status"),
+                ("result", "status"), ("change", "plan_add"),
+                ("node_id", "get")),
+    "predict": (("hit", "feedback"), ("predicted_node_id", "feedback"),
+                ("actual_node_id", "feedback")),
+    "session": (("summary", "note"), ("text", "note"), ("content", "note")),
+    "insight": (("statement", "record"),),
+    "whitebox": (("questions", "verify_existing"), ("question", "ask"),
+                 ("message", "ask"), ("query", "ask"),
+                 ("marker", "verify_encoding"),
+                 ("content", "remember"), ("text", "remember")),
+}
+
+# op → 分支内缺省 action 字面量。**仅供缺省透出提示，不参与执行**；与各
+# _xxx_call / 分支里的 `a.get("action") or "<默认>"` 保持同步（同源守卫见
+# test_action_derive.py）。
+_ACTION_DEFAULT = {
+    "theory": "check", "link": "ls", "scrub": "sweep", "forget": "forget",
+    "protect": "stats", "identity": "profile", "consistency": "check",
+    "metacognition": "report", "self_state": "snapshot", "predict": "routes",
+    "causal": "path", "evolution": "summary", "sustain": "status",
+    "goal": "list", "task": "list", "recent": "list", "review": "list", "session": "recall",
+    "ingest": "stat", "export": "stat", "maintain": "stat",
+    "consolidate": "promote", "insight": "outlook",
+    "ccg": "compile", "ref": "read", "whitebox": "ping",
+}
+
+
+def _action_sig(a, op):
+    """action 缺省时的签名推导 → (action, 依据键)；无签名可依 → (None, None)。
+
+    `ingest` 单独处理：其 op 语义是**写**（摄入），缺省 action 却是**读**（stat）
+    ——「传了 path 却静默 stat」会把摄入整件事吞掉。类型按**保守优先**推导：
+    patterns→dir、`*.jsonl`→jsonl、其余 path→file（file 最保守：若实为目录会
+    报错可见，而不会误把整棵目录树摄进来）。
+    """
+    if op == "ingest":
+        path = str(a.get("path") or "").strip()
+        if path:
+            if a.get("patterns"):
+                return "dir", "patterns"
+            if path.lower().endswith(".jsonl"):
+                return "jsonl", "path(*.jsonl)"
+            return "file", "path"
+    for key, act in _ACTION_SIGS.get(op, ()):
+        if key in a and a.get(key) is not None:
+            return act, key
+    return None, None
+
+
 def _cg_call(cg, a):
-    """认知图唯一入口。"""
+    """认知图唯一入口（外层：op/action 缺省推导兜底 + 推导透出；主体见 _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)
+    act0 = (args.get("action") or "").strip().lower()
+    act_sig = act_derived = None
+    if not act0:
+        act_derived, act_sig = _action_sig(args, op)
+        if act_derived:
+            args["action"] = act_derived     # 按签名补 action：避免写意图被默认吞掉
+    args["op"] = op
+    out = _cg_dispatch(cg, args)
+    if isinstance(out, dict):
+        if not op0:
+            out["op"] = op
+            out["op_derived"] = True
+            out["hint"] = ("op 未显式传入，已按参数签名推导（本次按 %s 执行）；op 为必填参数，"
+                           "复杂任务中也请始终显式传 op，避免静默执行错误意图" % op)
+        if not act0 and (act_derived or op in _ACTION_DEFAULT):
+            eff = act_derived or _ACTION_DEFAULT[op]
+            out.setdefault("action", eff)
+            out["action_derived"] = True
+            if act_derived:
+                out["hint_action"] = (
+                    "action 未显式传入，已按参数 %s 推导为 action=%s（旧行为会静默走默认 %s，"
+                    "意图被吞）；建议显式传 action" % (act_sig, act_derived,
+                                                     _ACTION_DEFAULT.get(op, "?")))
+            else:
+                out["hint_action"] = (
+                    "action 未显式传入，本次按 %s 的默认 action=%s 执行；"
+                    "若意图是其它 action 请显式传 action" % (op, eff))
+    return out
+
+
+def _help_call(cg, a):
+    """按需披露入口（工具面渐进披露的读取面，见 md_cg/tool_face.py）。
+
+    常驻上下文只留「一行职责 + 参数短提示」；被投影掉的完整 op/参数语义
+    在此从真源无损取回——所以瘦身不损失能力，只把「随时付费」换成「按需取」。
+    只读元信息（工具 schema 本身对客户端可见），故不过角色权限闸。
+    """
+    from .tool_face import help_text
+    return help_text(ALL_TOOLS, query=a.get("query") or a.get("intent"),
+                     limit=int(a.get("limit") or a.get("k") or 40))
+
+
+def _task_call(cg, a):
+    """结构层任务实体（op=task）——跨会话的工程台账。
+
+    action:
+      open / add   登记或更新任务卡（**同名即同卡**；未给字段沿用旧值，不静默清空）
+      status       状态迁移（active|blocked|done|dropped；迁 done 时「结果」必填）
+      plan_add     追加计划变更（执行中发现的偏差与新问题）
+      get          单卡全字段读回
+      list         任务清单（默认；可按 task_status 过滤）
+      find         同族任务提示（**只提示，不自动合并**）
+      session      会话装配面（进行中 + 近期完成）——供上下文召回
+
+    :param name: 任务名（身份判据：同名即同任务，slug 归一后落节点 id）
+    """
+    from . import tasks as _t
+    act = (a.get("action") or "").strip().lower()
+    if not act:
+        act = _action_sig(a, "task")[0] or "list"
+    name = a.get("name") or a.get("task_name") or a.get("task") or ""
+    nid = a.get("node_id") or a.get("task_id") or ""
+    tstat = a.get("task_status") or a.get("new_status") or ""
+
+    if act in ("open", "add", "upsert"):
+        imp = a.get("importance")
+        try:
+            imp = float(imp) if imp is not None else None
+        except (TypeError, ValueError):
+            imp = None
+        return _t.upsert(cg, name or nid,
+                         plan=a.get("plan"), status=tstat or None,
+                         result=a.get("result"), condition=a.get("condition"),
+                         goal=a.get("goal_text") or a.get("goal"),
+                         acceptance=a.get("acceptance"), boundary=a.get("boundary"),
+                         change=a.get("change"), note=a.get("note"),
+                         tags=a.get("tags"), importance=imp, actor=a.get("actor"))
+
+    if act in ("status", "set_status"):
+        if not tstat:
+            return {"ok": False, "error": "缺 task_status",
+                    "hint": "可选 active|blocked|done|dropped；迁 done 必须同时给 result"}
+        return _t.set_status(cg, nid or name, tstat, result=a.get("result"),
+                             note=a.get("note"), actor=a.get("actor"))
+
+    if act == "plan_add":
+        return _t.plan_add(cg, nid or name, a.get("change") or a.get("text"),
+                           actor=a.get("actor"))
+
+    if act == "get":
+        return _t.get_task(cg, nid or name)
+
+    if act == "find":
+        return _t.find_similar(cg, name, k=int(a.get("k") or a.get("limit") or 5))
+
+    if act == "session":
+        return _t.session_tasks(cg, active_limit=int(a.get("active_limit") or 5),
+                                done_limit=int(a.get("done_limit") or 5))
+
+    if act != "list":
+        return {"ok": False, "error": "未知 task action：%r" % act,
+                "hint": "可选 open|status|plan_add|get|list|find|session"}
+
+    return _t.list_tasks(cg, status=tstat or None, limit=a.get("limit"))
+
+
+def _cg_dispatch(cg, a):
+    """认知图唯一入口的 op 分发主体。"""
     op = (a.get("op") or "read").strip().lower()
+    if op == "help":
+        return _help_call(cg, a)
     _p = getattr(cg, "principal", None)
     if _p is not None and hasattr(_p, "require_op"):
         _p.require_op(op)          # 角色作用域闸门：越权即 AccessDenied
@@ -1509,12 +1839,15 @@ def _cg_call(cg, a):
 
     if op == "info":
         from . import audit
+        from . import nodefile
         from . import theory as _th
         from . import links as _lk
         h = cg.health_os()
         h.update({"surface": SURFACE,
                   "tools": [t["name"] for t in tools_for_surface()],
-                  "audit_kinds": audit.kinds(), "whoami": cg.whoami()})
+                  "audit_kinds": audit.kinds(), "whoami": cg.whoami(),
+                  # 裁定 B：CCG 六要素的契约角色（术语真源在 nodefile，此处只透出）
+                  "ccg_contract": dict(nodefile.CCG_CONTRACT_ROLES)})
         # 能力外置可观测：本进程实际注入了哪些外部验证器（含失败原因）
         h["external_verifiers"] = audit.load_external_verifiers()
         h["theory"] = _th.check()
@@ -1543,111 +1876,32 @@ def _cg_call(cg, a):
 
     if op == "read":
         if a.get("node_id"):
-            return _node_view(cg.get(a["node_id"]))
+            return _node_view(cg.get(a["node_id"]),
+                              offset=int(a.get("offset") or 0))
         q = a.get("query") or a.get("intent") or ""
         if a.get("budget_tokens"):
             return cg.recall(q, budget_tokens=int(a["budget_tokens"]),
                              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)}
             for n, s, q2 in res]}
 
     if op == "write":
-        from . import audit
-        verdict = audit.audit(
-            (a.get("content_kind") or "").strip(),
-            {"content": a.get("content", ""), "action": a.get("action"),
-             "sensitivity": a.get("sensitivity"),
-             "topic": a.get("query") or a.get("intent")},
-            {"cg": cg, "principal": getattr(cg, "principal", None)})
-        nid = a.get("node_id") or ("mem_" + str(int(__import__("time").time() * 1000)))
-        st = verdict["state"]
-        if st == audit.ACCEPT:
-            # 节点间自动冲突检测（三级决策：情绪→反思→递归反思）：
-            # 写入前与既有条件/纪律校验；不通过则不落盘（可进审核队列）。
-            # 与 mdcg_remember 同源、默认开启——「信息的修改必须先通过校验」。
-            cvd = None
-            if bool(a.get("consistency", True)):
-                oc = (a.get("on_conflict") or "defer").strip().lower()
-                cvd = cg.check_consistency(
-                    a.get("content", ""),
-                    layer=a.get("layer") or ("contextual" if a.get("gated")
-                                             else "knowledge"),
-                    condition_space=a.get("condition_space"),
-                    non_applicable_conditions=a.get("non_applicable_conditions"),
-                    tags=a.get("tags"), exclude=nid, auto_flywheel=True)
-                v = cvd.get("verdict")
-                blocked = ((v == "REJECT" and oc == "reject")
-                           or (v in ("REJECT", "BLINDSPOT") and oc == "defer"))
-                if blocked:
-                    if oc == "reject":
-                        return {"ok": False, "id": nid, "committed": False,
-                                "moved_to": "conflict_rejected",
-                                "consistency": cvd, "verdict": verdict}
-                    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": False, "id": nid, "pid": pid, "committed": False,
-                            "moved_to": "review_queue", "consistency": cvd,
-                            "verdict": verdict}
-            if a.get("gated"):
-                hint = a.get("importance_hint")
-                if hint is None and a.get("importance") is not None:
-                    hint = float(a["importance"])
-                res = cg.remember_gated(
-                    nid, a.get("content", ""), layer=a.get("layer") or "contextual",
-                    role=a.get("role"), tags=a.get("tags"),
-                    condition_space=a.get("condition_space"),
-                    verification_basis=(a.get("verification_basis")
-                                        or verdict.get("basis")),
-                    non_applicable_conditions=a.get("non_applicable_conditions"),
-                    importance_hint=hint, override=bool(a.get("override")),
-                    consistency=False,
-                    derived_from=_split_ids(a.get("derived_from")),
-                    relation=a.get("relation"))
-                v = res.get("verdict")
-                committed = v == "ACCEPT"
-                out = {"ok": committed, "id": nid, "committed": committed,
-                       "gate": res, "verdict": verdict}
-                if cvd is not None:
-                    out["consistency"] = cvd
-                if v == "MERGE":
-                    out["moved_to"] = "merged_into:" + str(res.get("merged_into"))
-                elif v in ("DROP", "DEFER"):
-                    out["moved_to"] = v.lower()
-                return out
-            cg.add(nid, a.get("content", ""), layer=a.get("layer") or "knowledge",
-                   tags=a.get("tags"), condition_space=a.get("condition_space"),
-                   importance=float(a.get("importance", 0.5)),
-                   verification_basis=a.get("verification_basis") or verdict.get("basis"),
-                   non_applicable_conditions=a.get("non_applicable_conditions"),
-                   override=bool(a.get("override")), consistency=False,
-                   derived_from=_split_ids(a.get("derived_from")),
-                   relation=a.get("relation"))
-            out = {"ok": True, "id": nid, "committed": True, "verdict": verdict}
-            if cvd is not None:
-                out["consistency"] = cvd
-            return out
-        if st == audit.REJECT:
-            rid = cg.add_rejected((a.get("content") or "")[:200], verdict["evidence"],
-                                  verification_basis=verdict.get("basis") or "test",
-                                  tags=a.get("tags"))
-            return {"ok": False, "id": rid, "committed": False,
-                    "moved_to": "rejected", "verdict": verdict}
-        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}
+        # 写入路径拦截器链（Pi 钩子化移植，writepipe.py）：六道闸以扩展
+        # 形态注册于 writepipe.default_pipeline()，次序/启停不再硬编码于
+        # 本文件；新增闸门 = register_before 一行，即插即拔。
+        # 角色/层权限校验在 MdCGSecure.add 库层，结构上不可被拦截器绕过。
+        from .writepipe import default_pipeline
+        return default_pipeline().execute(cg, a)
 
     if op == "goal":
         act = (a.get("action") or "list").strip().lower()
@@ -1668,6 +1922,9 @@ def _cg_call(cg, a):
                                        limit=int(a.get("limit") or 20)),
                 "active": cg.active_goals(limit=int(a.get("limit") or 5))}
 
+    if op == "task":
+        return _task_call(cg, a)
+
     if op == "recent":
         act = (a.get("action") or "list").strip().lower()
         if act in ("add", "append", "remember"):
@@ -1749,6 +2006,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 +2018,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 +2040,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 +2055,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":
@@ -1820,9 +2085,182 @@ def _cg_call(cg, a):
     if op == "insight":
         return _insight_call(cg, a)
 
+    if op == "ccg":
+        return _ccg_call(cg, a)
+
     raise ValueError(f"cg 未知 op：{op}")
 
 
+def _ccg_call(cg, a):
+    """CCG 六要素编译器（op=ccg）：对话记录 → 六要素候选 → **编外复核** → 落库。
+
+    定位：**记忆可靠性闸**——不是又一个写入通道，而是写入前「条件是否成立」的检查。
+    裁定 A（LLM 不得自己验证自己）由 ccgc 的 E041 **机械执行**，不依赖 prompt 自觉。
+
+    action（缺省 compile）：
+        compile      对话记录 → 六要素候选（五环编译）；候选+签章槽落
+                    `_ccgc_pending/<node_id>.json`（**不当场写库**）
+        review       派发编外复核单元：**蜂巢 reflect/verify 优先** → 不可用则提示配置
+                    → 显式 allow_degrade 才降级 harness 端子代理；拿到裁决即自动签章
+        attest       外部裁决签章（verifier 须 != compiled_by；E041/E042 机械把关）
+        link         读回候选+签章 → 准入校验 → apply=True 落库（成功后清 pending）
+        recalibrate  四槽修正（须编外验证方；E043 只放开 condition_space 四槽）
+        units        复核通道体检/计划（hive → 提示配置 → 子代理 三级链）
+        catalog      引擎自描述（错误码/契约角色/动作清单）
+
+    入参集中在 `ccg` 对象里（与 `redteam`/`verify` 同风格）——避免与既有扁平参数
+    重名（如 `verdict` 在 verify 面是 confirmed|weakened|falsified，语义不同）。
+
+    返回语义：`ok` 表示**本次请求本身**是否成立；`verdict` 是单元给出的裁决
+    （未复核为 None）；`passed` = 裁决为 ACCEPT。三者分开，避免「派发成功」
+    被误读成「复核通过」。
+
+    权限：编译器属写路径 → 记录/设计者角色可用（见 tokens.ALL_OPS 的 ccg 条目）。
+    attest/link 的准入**不靠 admin 闸**，而靠签章机械闸（E040/E041/E042）——理由：
+    默认部署（未设 MDCG_CAN_ADMIN）下再加 admin 会让编译器对使用者不可见
+    （「权限到位但通路不可见」是既有教训），而裁定 A 的保证本就在机械闸里。
+    """
+    from . import ccgc
+    from . import units as _units
+
+    o = a.get("ccg") or {}
+    if not isinstance(o, dict):
+        return {"ok": False, "op": "ccg",
+                "error": "ccg 参数须为对象：{action, node_id, dialog, ...}"}
+    act = str(o.get("action") or a.get("action") or "compile").strip().lower()
+    node_id = str(o.get("node_id") or a.get("node_id") or "").strip()
+    actor = str(getattr(getattr(cg, "principal", None), "actor", "") or o.get("actor") or "agent")
+    jobs = str(o.get("jobs") or "")
+
+    if act == "catalog":
+        return {"ok": True, "op": "ccg", "action": "catalog",
+                "actions": ["compile", "review", "attest", "link", "recalibrate",
+                            "units", "catalog"],
+                "states": list(ccgc.STATES), "contract_roles": list(ccgc.CONTRACT_ROLES),
+                "errors": dict(ccgc.E_CODES),
+                "rule": "裁定 A：验证方标识不得等于编译执行者（E041）；缺签章不写库（E040）；"
+                        "未通过不写库（E042）"}
+
+    if act == "units":
+        if o.get("doctor"):
+            return {"ok": True, "op": "ccg", "action": "units", **_units.doctor(jobs)}
+        p = _units.plan(jobs=jobs, model=o.get("model") or "",
+                        allow_degrade=bool(o.get("allow_degrade")),
+                        channel=o.get("channel") or "")
+        return {"ok": True, "op": "ccg", "action": "units", **p}
+
+    if act == "compile":
+        dialog = str(o.get("dialog") or o.get("content") or a.get("content") or "")
+        if not dialog.strip():
+            return {"ok": False, "op": "ccg", "action": "compile",
+                    "error": "缺对话记录：传 ccg.dialog（或顶层 content）"}
+        if not node_id:
+            return {"ok": False, "op": "ccg", "action": "compile",
+                    "error": "缺 node_id：六要素候选须指明目标节点"}
+        res = ccgc.compile_dialog(dialog, node_id, actor,
+                                  marks=o.get("marks"), slots=o.get("slots"),
+                                  strict_spans=bool(o.get("strict_spans", True)), cg=cg)
+        saved = ccgc.save_pending(cg, res)
+        return {"ok": bool(res.success), "op": "ccg", "action": "compile",
+                "compiled": ccgc.asdict(res), "pending": saved,
+                "actor": actor, "compiled_by": actor,
+                "hint": ("候选已落 pending；下一步 cg(op=ccg, action=review, "
+                         "ccg={node_id, blocking:true}) 交编外单元复核"
+                         "——编译者不得自证（E041）" if res.success else
+                         "编译未通过：" + (res.errors[0] if res.errors else "未知错误"))}
+
+    if act == "review":
+        got = ccgc.load_pending(cg, node_id)
+        if not got.get("ok") or not got.get("hash_ok"):
+            return {"ok": False, "op": "ccg", "action": "review",
+                    "error": got.get("error") or "pending 产物与编译时不一致（hash 不符）",
+                    "hint": "先 cg(op=ccg, action=compile, ccg={node_id, dialog}) 生成候选"}
+        compiled = got["compiled"]
+        role = str(o.get("role") or _units.REFLECT).strip().lower()
+        prompt = _units.prompt_for(role, compiled, dialog=str(o.get("dialog") or ""))
+        r = _units.review(prompt=prompt, role=role, node_id=node_id, jobs=jobs,
+                          model=o.get("model") or "",
+                          timeout_s=int(o.get("timeout_s") or _units.DEFAULT_TIMEOUT_S),
+                          allow_degrade=bool(o.get("allow_degrade")),
+                          channel=o.get("channel") or "",
+                          wait_s=float(o.get("wait_s") or _units.DEFAULT_TIMEOUT_S),
+                          blocking=bool(o.get("blocking")), cg=cg, actor=actor,
+                          autostart=bool(o.get("autostart")))
+        unit = r.get("unit")
+        out = {"ok": True, "op": "ccg", "action": "review", "state": r["state"],
+               "role": role, "node_id": node_id, "job_id": r.get("job_id"),
+               "transport": r.get("transport"), "verdict": (unit or {}).get("verdict"),
+               "passed": bool((unit or {}).get("verdict") == ccgc.ACCEPT),
+               "unit": unit, "channel": r.get("channel") or "",
+               "blocking": bool(o.get("blocking")), "hint": r.get("hint") or ""}
+        if r["state"] != _units.HIVE:
+            out["ok"] = False
+            out["prompt"] = r.get("prompt")      # 降级/配置路径：把复核请求包交回调用方
+            return out
+        if unit:                                  # 已获编外裁决 → 自动签章
+            args = r.get("attest") or {}
+            at = ccgc.attest(node_id, args.get("verdict") or ccgc.DEFER,
+                             args.get("verifier") or "", compiled.actor or actor,
+                             slot_corrections=args.get("slot_corrections"),
+                             evidence=args.get("evidence") or "", cg=cg)
+            out["attest"] = ccgc.asdict(at)
+            out["pending"] = ccgc.save_pending(cg, compiled, at)
+            out["hint"] = ("已签章（%s）；下一步 cg(op=ccg, action=link, "
+                           "ccg={node_id, apply:true}) 落库"
+                           % (args.get("verifier") or "-") if at.ok else
+                           "签章未通过：" + (at.error or "DEFER/REJECT 不构成准入"))
+        return out
+
+    if act == "attest":
+        got = ccgc.load_pending(cg, node_id)
+        if not got.get("ok") or not got.get("hash_ok"):
+            return {"ok": False, "op": "ccg", "action": "attest",
+                    "error": got.get("error") or "pending 产物与编译时不一致（hash 不符）",
+                    "hint": "先 cg(op=ccg, action=compile, ...) 生成候选"}
+        compiled = got["compiled"]
+        at = ccgc.attest(node_id, str(o.get("verdict") or ""),
+                         str(o.get("verifier") or ""),
+                         str(o.get("compiled_by") or compiled.actor or actor),
+                         slot_corrections=o.get("slot_corrections"),
+                         evidence=str(o.get("evidence") or ""), cg=cg)
+        return {"ok": bool(at.ok), "op": "ccg", "action": "attest",
+                "attest": ccgc.asdict(at),
+                "pending": ccgc.save_pending(cg, compiled, at),
+                "hint": ("签章通过；下一步 cg(op=ccg, action=link, ccg={node_id, apply:true})"
+                         if at.ok else "签章未通过：" + (at.error or "DEFER/REJECT 不构成准入"))}
+
+    if act == "link":
+        apply = bool(o.get("apply"))
+        res = ccgc.link_pending(cg, node_id, apply=apply, actor=actor,
+                                basis=str(o.get("basis") or "ccgc link"))
+        return {"ok": bool(res.ok), "op": "ccg", "action": "link", "apply": apply,
+                "link": ccgc.asdict(res),
+                "hint": ("已落库（entry_id=%s，written=%s）" % (res.entry_id, res.written)
+                         if res.ok and apply else
+                         ("准入通过（dry_run 未写库）；apply=true 才落库" if res.ok else
+                          "；".join(res.errors or []) or "准入未通过"))}
+
+    if act == "recalibrate":
+        corr = o.get("slot_corrections") or o.get("corrections") or {}
+        verifier = str(o.get("verifier") or "").strip()
+        compiled_by = str(o.get("compiled_by") or "").strip()
+        if not verifier or verifier == compiled_by:
+            return {"ok": False, "op": "ccg", "action": "recalibrate",
+                    "error": "E041 自证拒绝：recalibrate 须由编外验证方给出"
+                             "（verifier 必填且 != compiled_by）"}
+        res = ccgc.recalibrate(node_id, corr, verifier, compiled_by,
+                               evidence=str(o.get("evidence") or ""), cg=cg,
+                               apply=bool(o.get("apply")))
+        return {"ok": bool(res.ok), "op": "ccg", "action": "recalibrate",
+                "recalibrate": ccgc.asdict(res),
+                "hint": ("；".join(res.errors or []) or "修正已应用（apply=true）" if res.ok
+                         else "；".join(res.errors or []) or "修正未通过")}
+
+    return {"ok": False, "op": "ccg", "action": act,
+            "error": "ccg 未知 action：%s（可选 compile|review|attest|link|recalibrate|"
+                     "units|catalog）" % act}
+
+
 def _session_call(cg, a):
     """会话三件套（P0）：note 写要点 / recall 续接 / compact 压摘要。
 
@@ -1861,6 +2299,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。
 
@@ -1989,13 +2463,16 @@ def _consolidate_call(cg, a):
 
 def _insight_call(cg, a):
     """洞察（P2）：window / record / verify / list / report / reconstruct / learn /
-    outlook / catalog。
+    outlook / catalog / fork / branch_rewrite / branch_search / branch_merge /
+    branch_discard / branches。
 
     权限**按 action 分档**（与 maintain 同构，比整 op 收窄更贴合语义）：
-      · 只读（window / list / report / reconstruct 预演 / outlook / catalog）
-        → 不额外拦截；
-      · 条件层记账（record / verify）→ 需 can_write；
-      · 落库（reconstruct apply / learn apply）→ 批量改写，require_admin。
+      · 只读（window / list / report / reconstruct 预演 / outlook / catalog /
+        branch_search / branches / fork 预演）→ 不额外拦截；
+      · 条件层记账（record / verify）与分支写操作（fork / branch_rewrite /
+        branch_merge）→ 需 can_write；
+      · 落库（reconstruct apply / learn apply）与分支弃置（branch_discard，
+        改变库可见性）→ require_admin（discard 库层还有第二道闸）。
     这样 output 角色能读洞察但不能记；reflect 能重构与学习预演；批量落库须请示。
     """
     act = (a.get("action") or "outlook").strip().lower()
@@ -2005,18 +2482,26 @@ def _insight_call(cg, a):
     actor = getattr(principal, "actor", None) if principal is not None else None
     if principal is not None and act in ("record", "verify") and not can_write:
         principal.require_admin(f"insight_{act}")     # 无写权 → 抛 AccessDenied
+    if principal is not None and act in ("fork", "branch_rewrite",
+                                         "branch_merge") and not can_write:
+        principal.require_admin(f"insight_{act}")     # 分支写 → 需写权
     if principal is not None and act in ("reconstruct", "learn") and apply:
         principal.require_admin(f"insight_{act}")
+    if principal is not None and act == "branch_discard":
+        principal.require_admin("branch_discard")     # 弃置：分发层+库层双闸
     return cg.insight(
         action=act, layer=a.get("layer"), limit=a.get("limit"),
         conditions=a.get("conditions"), apply=apply, actor=actor,
         statement=a.get("statement"), category=a.get("category"),
         source=a.get("source"), tags=a.get("tags"),
         importance=a.get("importance"), node_id=a.get("node_id"),
+        content=a.get("content"),
         evidence=a.get("evidence"), v_types=a.get("v_types"),
         verdict=a.get("verdict"), state=a.get("state"),
         window_days=a.get("window_days"), clues=a.get("clues"),
         ids=a.get("ids"), neighbors=a.get("neighbors"),
+        branch_id=a.get("branch_id"), note=a.get("note"),
+        reason=a.get("reason"),
         blindspot_id=a.get("blindspot_id"), horizon=a.get("horizon"),
         max_branches=a.get("max_branches"), recent_days=a.get("recent_days"),
         sample_limit=a.get("sample_limit"), max_nodes=a.get("max_nodes"))
@@ -2059,8 +2544,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:
@@ -2083,7 +2579,7 @@ def _whitebox_call(cg, a):
     """显式调用白箱能力库（AEIS 降为本地库后的唯一入口）。
 
     显式调用映射：md_cg.whitebox.dispatch
-    见 docs/功能调用映射表_v0.1.md。
+    见 docs/mdcg/功能调用映射表_v0.1.md。
     """
     from . import whitebox
     return whitebox.dispatch(cg, a)
@@ -2105,7 +2601,13 @@ def _stg_call(cg, a):
     if op == "consistency":
         return stg.consistency(cg, layer=a.get("layer"),
                                limit=int(a.get("limit") or 50))
-    raise ValueError(f"stg 未知 op：{op}")
+    if not op:
+        # fail-closed 且给出可操作提示：stg 的 op 四值签名区分度低于 cg（relation 需
+        # a+b、timeline/anchors/consistency 皆以 layer+limit 为主），**不做签名推导**
+        # ——猜错会静默返回错误视图，比报错更贵。
+        raise ValueError("stg 的 op 为必填参数（缺失即报错，不静默降级）；"
+                         "允许 op：relation | timeline | anchors | consistency")
+    raise ValueError(f"stg 未知 op：{op}（允许 relation | timeline | anchors | consistency）")
 
 
 # --------------------------------------------------------------------------
@@ -2215,15 +2717,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,14 +2740,16 @@ 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)}
                             for n, s, q in res]}
 
     if name == "mdcg_get":
-        return _node_view(cg.get(a.get("node_id", "")))
+        return _node_view(cg.get(a.get("node_id", "")),
+                          offset=int(a.get("offset") or 0))
 
     if name == "mdcg_reflect":
         res, _ = cg.search(a.get("query", ""), k=int(a.get("k") or 10), record=False)
@@ -2263,10 +2774,18 @@ def _dispatch(cg, name, args):
                                         a.get("goal", ""))}
 
     if name == "mdcg_propose":
-        return {"pid": cg.propose(a.get("node_id", ""), a.get("content", ""),
-                                  layer=a.get("layer") or "knowledge",
-                                  tags=a.get("tags"), condition_space=a.get("condition_space"),
-                                  **_proposal_extras(a))}
+        pr = cg.propose(a.get("node_id", ""), a.get("content", ""), info=True,
+                        layer=a.get("layer") or "knowledge",
+                        tags=a.get("tags"), condition_space=a.get("condition_space"),
+                        **_proposal_extras(a))
+        out = {"pid": pr["pid"], "dedup": bool(pr.get("dedup"))}
+        if pr.get("dedup"):
+            out["dup_of"] = pr["pid"]
+            out["dup_status"] = pr.get("dup_status")
+            out["hint"] = ("同内容提案已存在（pid=%s，状态=%s），幂等返回既有提案、"
+                           "未重复入队，无需重试"
+                           % (pr["pid"], pr.get("dup_status") or "pending"))
+        return out
 
     if name == "mdcg_review_list":
         return {"pending": cg.review_list()}
@@ -2381,6 +2900,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 +3036,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,7 +3058,20 @@ def main():
             "    python -m md_cg.tokens issue --role designer --actor <你>\n"
             "然后设置 MDCG_TOKEN=<返回的明文令牌>。\n")
         return 3
-    cg = MdCGSecure(root, principal=principal)
+    # 会话归属（归因维度，不参与授权）：部署侧可为每个 agent 连接注入固定
+    # 会话 id（MDCG_SESSION），多会话共用一个 root 时按 frontmatter.session
+    # 区分「本会话记忆 / 其他会话记忆」；缺省=进程自动生成（sess_<uuid>）。
+    _p_session = os.environ.get("MDCG_SESSION", "").strip()
+    if _p_session:
+        principal.session = _p_session
+    # 索引可见性（2026-09-16）：autoflush=1 —— 逐条写入立即落分片日志
+    # `_index_log/`。根因（第4条取证）：默认 autoflush=64 且常驻进程不 close，
+    # 单条写入在达阈值前**对其他进程不可见**（`_load_index` = 快照 + 分片日志
+    # 重放；`_index.json` 只在 compact/rebuild 时重写），表现为「写入返回
+    # committed=true 但第16条读回确认在跨进程读面上不可检索」。本参数是
+    # server 级兜底：覆盖不经 writepipe 写链的路径（propose / remember_gated /
+    # add_rejected 等）；写链另有显式提交边界（writepipe._commit_visibility）。
+    cg = MdCGSecure(root, principal=principal, autoflush=1)
     # 外部验证器注入（**能力外置**）：识图/实测/验收等能力不在认知图内，
     # 由 MDCG_VERIFIER_MODULES（逗号分隔 import 路径）声明的外部模块注入，
     # 通常位于私有运行时仓。加载失败不阻塞启动——失败原因写进 stderr 与
@@ -2530,6 +3081,20 @@ def main():
     if _verifiers.get("loaded") or _verifiers.get("failed"):
         sys.stderr.write("[mdcg-mcp] 外部验证器: loaded=%s failed=%s\n"
                          % (_verifiers.get("loaded"), _verifiers.get("failed")))
+    # ③ 两段式对账：上个进程若被杀在「落盘前后」之间，账本里会留下「有意图
+    # 无结果」的写入——启动即清账（内容确已落盘 → 补账 committed；没落上 →
+    # 如实标记 interrupted）。失败**不阻塞启动**：对账是增益，不是服务前提，
+    # 但必须上报（stderr），不静默。
+    try:
+        _rep = cg.reconcile_writes()
+        if _rep.get("unpaired"):
+            sys.stderr.write("[mdcg-mcp] 写入两段式对账: 未结清=%s 补账=%s "
+                             "中断=%s\n" % (_rep.get("unpaired"),
+                                            _rep.get("committed"),
+                                            _rep.get("interrupted")))
+    except Exception as _exc:         # 对账故障不得影响服务可用性
+        sys.stderr.write("[mdcg-mcp] 两段式对账失败（不阻塞启动）: %r\n"
+                         % (_exc,))
     _start_sustain(cg)
 
     for line in sys.stdin: