@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/md_cg/test_writepipe.py

@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""写入路径拦截器链（writepipe）验收：Pi 钩子化移植（交接文档 §3⑥）。
+
+验收口径：
+- 默认链行为与重构前 _cg_dispatch write 分支逐字节一致
+  （ACCEPT 直写 / REJECT 负记忆 / DEFER 入队 + 幂等去重联动 / gated 闸 /
+  冲突 cvd 透传）；
+- 新增/移除一个拦截器不改核心文件（register/unregister 即插即拔）；
+- 角色/层权限校验结构上不可被拦截器绕过（反面清单：信任必须结构强制）；
+- REWRITE（拦截器改写 ctx["a"]["content"]）/ 链序 / 短路 / after 观测者。
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+
+from . import writepipe
+from .mdcos import MdCGSecure
+from .security import AccessDenied, Principal
+
+_ok = 0
+_bad = []
+_seq = [0]
+
+
+def _check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("  ok   %s" % name)
+    else:
+        _bad.append("%s %s" % (name, detail))
+        print("  FAIL %s %s" % (name, detail))
+
+
+def _mk_cg(tmp, role="designer"):
+    _seq[0] += 1
+    root = os.path.join(tmp, "root_%02d_%s" % (_seq[0], role))
+    p = Principal(tenant="default", actor="t_" + role, role=role,
+                  can_write=(role != "guest"),
+                  can_admin=(role == "designer"))
+    return MdCGSecure(root, principal=p)
+
+
+def _policy(tmp, required=("PASSED",), forbidden=("FORBIDDEN_WORD",)):
+    path = os.path.join(tmp, "policy.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"forbidden": list(forbidden),
+                   "required": list(required)}, f)
+    os.environ["MDCG_POLICY_FILE"] = path
+    return path
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="writepipe_")
+    old_policy = os.environ.pop("MDCG_POLICY_FILE", None)
+    try:
+        _run(tmp)
+    except Exception:
+        traceback.print_exc()
+        _bad.append("未捕获异常")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+        if old_policy is not None:
+            os.environ["MDCG_POLICY_FILE"] = old_policy
+        else:
+            os.environ.pop("MDCG_POLICY_FILE", None)
+    print("\nwritepipe 验收：%d 通过%s" % (
+        _ok, ("，%d 失败：%s" % (len(_bad), "; ".join(_bad))) if _bad else ""))
+    return 1 if _bad else 0
+
+
+def _run(tmp):
+    policy = _policy(tmp)
+
+    # ---------- 1 默认链：与重构前 write 分支行为一致 ----------
+    pipe = writepipe.install_default_gates(writepipe.WritePipeline())
+    cg = _mk_cg(tmp)
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "要素齐全 PASSED",
+                            "layer": "knowledge"})
+    _check("默认链ACCEPT直写", out.get("committed") is True and out.get("ok") is True,
+           repr(out))
+    _check("冲突闸cvd透传", isinstance(out.get("consistency"), dict), repr(out))
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "含 FORBIDDEN_WORD 的违禁内容",
+                            "layer": "knowledge"})
+    _check("REJECT负记忆", out.get("moved_to") == "rejected"
+           and out.get("committed") is False, repr(out))
+
+    # DEFER（无规则文件 → 无法判定 → 入审核队列）+ 幂等去重联动
+    os.environ.pop("MDCG_POLICY_FILE", None)
+    a = {"content_kind": "text", "content": "无规则可判的内容",
+         "layer": "knowledge"}
+    out1 = pipe.execute(cg, dict(a))
+    _check("DEFER入队", out1.get("moved_to") == "review_queue"
+           and bool(out1.get("pid")), repr(out1))
+    out2 = pipe.execute(cg, dict(a))
+    _check("幂等去重联动", out2.get("dedup") is True
+           and out2.get("dup_of") == out1.get("pid"), repr(out2))
+    os.environ["MDCG_POLICY_FILE"] = policy
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "PASSED 情境记忆", "gated": True,
+                            "layer": "contextual"})
+    _check("gated闸代执行", "gate" in out, repr(out))
+
+    # ---------- 2 注册/移除拦截器不改核心文件 ----------
+    singleton = writepipe.default_pipeline()
+
+    def _block_skipme(ctx):
+        if "SKIPME" in (ctx["a"].get("content") or ""):
+            return {"ok": False, "committed": False,
+                    "moved_to": "hook_blocked", "by": "test_block"}
+        return None
+
+    singleton.register_before("test_block", _block_skipme)
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("注册即拦", out.get("moved_to") == "hook_blocked", repr(out))
+    singleton.unregister_before("test_block")
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("移除即恢复(核心文件零改动)", out.get("committed") is True, repr(out))
+    _check("单例默认链", singleton.names()["before"]
+           == ["audit", "consistency", "gated"],
+           repr(singleton.names()))
+
+    # ---------- 3 链序 / 短路 / REWRITE ----------
+    p3 = writepipe.WritePipeline()
+    order = []
+    p3.register_before("g1", lambda ctx: order.append("g1") or None)
+    p3.register_before("g2", lambda ctx: order.append("g2") or None)
+    p3.register_before("g3", lambda ctx: order.append("g3")
+                       or {"ok": False, "moved_to": "halt"})
+    cg3 = _mk_cg(tmp)
+    out = p3.execute(cg3, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("链序按注册序", order == ["g1", "g2", "g3"], repr(order))
+    _check("终态短路不落盘", out.get("moved_to") == "halt"
+           and "id" not in out and "committed" not in out, repr(out))
+
+    p4 = writepipe.WritePipeline()
+    p4.register_before("rw", lambda ctx:
+                       ctx["a"].__setitem__("content",
+                                            ctx["a"].get("content") + " REWRITTEN")
+                       or None)
+    cg4 = _mk_cg(tmp)
+    out = p4.execute(cg4, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("REWRITE改写生效", out.get("committed") is True
+           and bool(cg4.search("REWRITTEN")), repr(out))
+
+    # ---------- 4 权限结构上不可被拦截器绕过 ----------
+    cg_guest = _mk_cg(tmp, role="guest")
+    p5 = writepipe.WritePipeline()
+    p5.register_before("always_pass", lambda ctx: None)
+    try:
+        p5.execute(cg_guest, {"content_kind": "text", "content": "PASSED",
+                              "consistency": False, "layer": "knowledge"})
+        _check("权限不可绕", False, "guest 写入未被拒")
+    except AccessDenied:
+        _check("权限不可绕", True)
+    except Exception as e:  # noqa: BLE001
+        _check("权限不可绕", False,
+               "异常类型=%s:%s" % (type(e).__name__, e))
+
+    # ---------- 5 after 观测者 ----------
+    p6 = writepipe.WritePipeline()
+    seen = []
+    p6.register_after("spy", lambda ctx, out: seen.append(out.get("committed")))
+    cg6 = _mk_cg(tmp)
+    p6.execute(cg6, {"content_kind": "text", "content": "PASSED",
+                     "layer": "knowledge"})
+    _check("after观测成功", seen == [True], repr(seen))
+
+    def _boom(ctx, out):
+        raise RuntimeError("after钩子故障")
+
+    p6.register_after("boom", _boom)
+    try:
+        p6.execute(cg6, {"content_kind": "text", "content": "PASSED 二次",
+                         "layer": "knowledge"})
+        _check("after故障不吞", False, "异常被静默")
+    except RuntimeError:
+        _check("after故障不吞", True)
+
+    # ---------- 6 注册表卫生 ----------
+    p7 = writepipe.WritePipeline()
+    p7.register_before("x", lambda ctx: None)
+    p7.register_before("x", lambda ctx: None)  # 同名幂等替换
+    _check("同名幂等注册", p7.names()["before"] == ["x"], repr(p7.names()))
+    try:
+        p7.register_before("y", 123)
+        _check("类型守卫", False, "非可调用未拒")
+    except TypeError:
+        _check("类型守卫", True)
+    _check("注销返回布尔", p7.unregister_before("x") is True
+           and p7.unregister_before("x") is False)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/theory.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """md_cg · 版本层（蜂群互联 · 层0）
 
-设计依据：`docs/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
+设计依据：`docs/swarm/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
 
 版本更新权 = 蜂群**唯一核心权限**（严格唯一，仅 designer）。本模块只做
 「声明 + 校验」两件事，不做跨节点证据交换（§9.1 属存在约束，留待 v0.3）：

package/md_cg/tokens.py

@@ -53,7 +53,9 @@ ALL_LAYERS = ("anchor", "structural", "knowledge", "contextual", "self",
               "rejected", "unresolved", "goals")
 
 # 认知图 op 全集（与 mcp_server._cg_call 对齐，供 ops_allow 收窄）
-ALL_OPS = ("info", "route", "read", "write", "goal", "recent", "verify",
+#   help  按需披露入口：工具面投影（见 md_cg/tool_face.py）后，被外置的完整
+#         op/参数语义在此从真源取回；只读元信息，不经角色闸（不属于写/裁决面）
+ALL_OPS = ("help", "info", "route", "read", "write", "goal", "task", "recent", "verify",
            "review", "forget", "protect", "identity", "consistency",
            "metacognition", "self_state", "evolution", "sustain", "scrub",
            "predict", "causal", "whitebox", "index_code", "index_doc", "ref",
@@ -71,7 +73,13 @@ ALL_OPS = ("info", "route", "read", "write", "goal", "recent", "verify",
            #                情景重构（reconstruct）+ 盲区学习（learn）+
            #                结构洞察（outlook）；写入 action 按 can_write 收窄，
            #                learn/apply 与批量落库走 require_admin
-           "session", "ingest", "export", "maintain", "consolidate", "insight")
+           "session", "ingest", "export", "maintain", "consolidate", "insight",
+           # P3 新增（记忆可靠性闸，见 docs 讨论）：
+           #   ccg  CCG 六要素编译器（compile/review/attest/link/recalibrate/units）
+           #        —— 对话记录→六要素候选→**编外复核**→落库；裁定 A：编译者不得自证
+           #        （E041 机械拒绝 verifier == compiled_by）。复核通道优先蜂巢
+           #        reflect/verify 单元，不可用则提示配置或降级 harness 端子代理。
+           "ccg")
 
 
 class TokenError(Exception):
@@ -102,8 +110,12 @@ ROLE_SPECS = OrderedDict([
         # session=记会话要点；ingest=摄取外部文件流（记录单元本职）
         # maintain=写入前馈 prefeed（apply 类批量改写仍被 require_admin 拦截）
         # insight=记录洞见事件（record）；verify/learn 在分发层按单位职责收窄
-        "ops_allow": ["info", "route", "read", "write", "goal", "recent",
-                      "session", "ingest", "maintain", "insight"],
+        # ccg=CCG 六要素编译器（记录单元本职：保存观测/过程/结果与误差）；
+        #     其准入不靠 admin 闸而靠签章机械闸（E040/E041/E042）——编译者不得自证
+        # task=结构层任务台账（工程做到哪一步/结果是什么）——记录单元本职：
+        #     保存过程与结果；「不得自证」由 done 时的结果必填闸承接
+        "ops_allow": ["info", "route", "read", "write", "goal", "task", "recent",
+                      "session", "ingest", "maintain", "insight", "ccg"],
         "delegable": False,
         "forbidden": ["self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -177,6 +189,32 @@ POSITION_ROLES = ("record", "reflect", "verify", "output", "sustain")
 
 DELEGABLE_ROLES = tuple(r for r, s in ROLE_SPECS.items() if s["delegable"])
 
+# --------------------------------------------------------------------------
+# 蜂巢编排器（hive/orch.py）派生收窄面 · 单一真源
+# --------------------------------------------------------------------------
+# 设计依据（取证 2026-09-16，源码级：本文件 derive() + md_cg/mdcos.py 的
+# require_admin 闸门）：
+#   ① 编排器要「能裁决子代理冲突」→ 必须过 `MdCGSecure.review_decide` 的库层
+#      `require_admin`。而 `derive()` 的 `can_admin = spec.can_admin and
+#      parent.can_admin`（**不可收窄**）→ 唯一可行 role 是 designer。
+#      （`narrowed_principal()` 的 can_admin 恒 False，裁决会被库层拒 —— 这是被
+#      代码证据排除的路径，不是偏好取舍。）
+#   ② 因此「不给 delete / 不给 anchor / 不给 delegate」**不能依赖 admin 闸**
+#      （can_admin=True 时该闸不拦清单内的 op），而由三重结构保证：
+#        · ops_allow 白名单（ALL_OPS 的**子集**）—— 不在清单的 op 被
+#          `_cg_dispatch` 前置 `require_op` 直接拒：forget=删除、identity=动地基、
+#          protect=固化、maintain/consolidate 的 apply 类批量改写，全在清单外；
+#        · layers_allow 白名单（排除 CORE_LAYERS=anchor/self）—— 写不进地基；
+#        · `derive()` 硬编码 `delegable=False` —— 派生令牌结构上不可再派生。
+#      白名单方向 fail-closed：ALL_OPS 将来新增 op，默认不在清单内 = 不给。
+#   ③ 残余面（诚实标注，未收窄）：can_admin=True 使清单内 op 的 admin 分支仍可
+#      通过 —— `recent` 的 clear、`consistency` 的 auto_flywheel 写、`review` 的
+#      裁决（功能所求）。改本常量即改编排器权限：签发（CLI `orch`）与
+#      hive/orch.py 同引此处，防两处硬编码漂移。
+ORCH_ROLE = "designer"
+ORCH_OPS_ALLOW = ("route", "read", "write", "review", "recent", "consistency")
+ORCH_LAYERS_ALLOW = tuple(l for l in ALL_LAYERS if l not in CORE_LAYERS)
+
 
 def normalize_role(role: str) -> str:
     r = (role or "").strip().lower()
@@ -464,6 +502,22 @@ def _csv_list(v):
     return [x.strip() for x in str(v).split(",") if x.strip()] or None
 
 
+def _write_secret(path: str, text: str) -> None:
+    """把令牌明文写入文件（0600，原子替换）——供 HIVE_ORCH_TOKEN_FILE 读取。"""
+    p = os.path.abspath(path)
+    d = os.path.dirname(p)
+    if d:
+        os.makedirs(d, exist_ok=True)
+    tmp = p + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, p)
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+
+
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.tokens",
@@ -491,6 +545,23 @@ def main(argv=None):
     p_d.add_argument("--actor", default=None)
     p_d.add_argument("--ttl", type=float, default=None)
     p_d.add_argument("--label", default="")
+    p_d.add_argument("--ops-allow", dest="ops_allow", default=None,
+                     help="收窄 op 白名单（逗号分隔；越界项被忽略，只能小于角色默认）")
+    p_d.add_argument("--layers-allow", dest="layers_allow", default=None,
+                     help="收窄可写层白名单（逗号分隔；越界项被忽略）")
+    p_d.add_argument("--clearance", default=None,
+                     help="收窄密级（默认取角色上限，且不超过父令牌）")
+
+    p_o = sub.add_parser(
+        "orch",
+        help="签发蜂巢编排器令牌（收窄面取自本模块 ORCH_* 真源，一步到位）")
+    p_o.add_argument("--token", default=None, help="父令牌明文（须为 designer 且可派生）")
+    p_o.add_argument("--token-file-in", dest="token_file_in", default=None,
+                     help="从文件读父令牌")
+    p_o.add_argument("--ttl", type=float, default=None, help="有效期（秒）")
+    p_o.add_argument("--label", default="hive-orchestrator")
+    p_o.add_argument("--out", default=None,
+                     help="把令牌明文写入该文件（0600；供 HIVE_ORCH_TOKEN_FILE 读取）")
 
     p_v = sub.add_parser("verify", help="校验令牌并打印身份")
     p_v.add_argument("--token", default=None)
@@ -516,7 +587,26 @@ def main(argv=None):
                 with open(a.token_file_in, encoding="utf-8") as f:
                     tok = f.read().strip()
             _print(derive(tok, a.role, actor=a.actor, ttl=a.ttl,
-                          label=a.label, path=a.token_file))
+                          label=a.label, path=a.token_file,
+                          clearance=a.clearance,
+                          layers_allow=_csv_list(a.layers_allow),
+                          ops_allow=_csv_list(a.ops_allow)))
+        elif a.cmd == "orch":
+            tok = a.token
+            if a.token_file_in:
+                with open(a.token_file_in, encoding="utf-8") as f:
+                    tok = f.read().strip()
+            r = derive(tok, ORCH_ROLE, actor="hive-orchestrator", ttl=a.ttl,
+                       label=a.label, path=a.token_file,
+                       layers_allow=list(ORCH_LAYERS_ALLOW),
+                       ops_allow=list(ORCH_OPS_ALLOW))
+            if a.out:
+                _write_secret(a.out, r["token"])
+                r = {k: v for k, v in r.items() if k != "token"}
+                r["token_written_to"] = os.path.abspath(a.out)
+            r["usage"] = ("把令牌明文放入 hive serve 的环境变量 HIVE_ORCH_TOKEN"
+                          "（或写文件后设 HIVE_ORCH_TOKEN_FILE）再重启 serve")
+            _print(r)
         elif a.cmd == "verify":
             tok = a.token
             if a.token_file_in:

package/md_cg/tool_face.py

@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+"""工具面渐进披露（pi ① 上下文经济学 · 灵枢落地）。
+
+【为什么】
+MCP 工具的 op 参数空间全量 schema 常驻调用方上下文：kernel 暴露面（cg+stg）
+达 ~20k 字符，其中 cg 一个工具就有 169 个参数——绝大多数是「长尾 op 专属参数的
+解释文字」，只在少数场景才需要，却每次会话都要付费注入。
+
+pi 的做法（`system-prompt.ts:82-84` 工具只以一行 snippet 常驻系统提示，完整描述
+只进 API tools 字段；`skills.ts:355-383` 索引常驻、正文按需 read）证明：
+**常驻面只需「我知道它存在、且知道怎么问」**，完整语义按需取回即可。
+
+【怎么做 · 信息零丢失】
+本模块**不改 schema 真源**（`mcp_server.KERNEL_TOOLS` / `TOOLS` 仍是完整定义），
+只做运行时**投影**：
+  · 工具 description → `TOOL_BRIEFS` 一行职责（缺省回退首句）；
+  · 参数 description → 短提示：通用参数保留首段（≤30 字符）、op 专属参数压到
+    ≤16 字符，枚举型参数保留**完整值集**（值集是调用契约，不可省）；
+  · 顺带剔除 `_req`（`_p()` 写的内部标记，本不该出现在对外 schema）。
+被投影掉的原文既不复制也不搬运——`cg(op=help, query=…)` 直接从真源渲染，
+故不存在第二真源、无漂移面，信息守恒是结构性的而非靠人工维护。
+
+【守卫】`md_cg/test_tool_face.py` 机械断言：注入面 ≥50% 削减 + 工具名/参数名/
+required/类型/枚举值集逐位不变 + 每个被投影掉的参数描述都能由 op=help 无损取回。
+
+【关闭】`MDCG_TOOL_FACE=full` 返回完整真源（调试/兼容）。
+"""
+from __future__ import annotations
+
+import os
+import re
+
+FULL_ENV = "MDCG_TOOL_FACE"
+
+# --------------------------------------------------------------------------
+# 一行职责（唯一手写面：必须由人写，不能机械生成）
+# --------------------------------------------------------------------------
+CG_HELP_HINT = '完整 op/参数语义：cg(op="help", query="<op 名 | 参数名 | 工具名>")'
+
+TOOL_BRIEFS = {
+    "cg": "灵枢认知图唯一入口（32 op：写/读/审/护/演化/元认知/预测/白箱…）。" + CG_HELP_HINT,
+    "stg": "语义时空图 4 op：relation|timeline|anchors|consistency。" + CG_HELP_HINT,
+    "mdcg_remember": "写入记忆节点（gated=true 走主动遗忘闸门；正文建议含 CCG 五要素）。",
+    "mdcg_recall": "按 token 预算召回记忆包（RRF 多路融合，可开模糊/条件语义路与查询扩展）。",
+    "mdcg_search": "精确检索（T0–T3 阶梯 + 四态资格判定）。",
+    "mdcg_get": "按 id 读取单个节点（frontmatter + content）。",
+    "mdcg_reflect": "记录信息差 D(t,C) 与二阶 d²D/dt²（写 _reflection.jsonl）。",
+    "mdcg_verify": "节点外部裁决 confirmed/weakened/falsified（falsified 入负记忆）。",
+    "mdcg_flywheel": "误差（预期 vs 实际）转为 unresolved 条目，驱动补条件。",
+    "mdcg_mine_fix_pairs": "从行为日志挖掘「错误→修复」对（产修复知识 + 负记忆）。",
+    "mdcg_rejected": "写入负记忆（被证伪假设），同内容幂等。",
+    "mdcg_unresolved": "写入未解问题（驱动主动探索）。",
+    "mdcg_propose": "候选记忆入审核队列（海马体 inbox）。",
+    "mdcg_review_list": "列出待审核候选（红队打回者带 needs_reapproval）。",
+    "mdcg_review_decide": "审核裁决 accept|reject|edit|merge（redteam 打回需再审批）。",
+    "mdcg_review_records": "裁决记录审计（可复核 record_hash 一致性）。",
+    "mdcg_forget": "软删除（tombstone → trash/，受保护节点需 override）。",
+    "mdcg_protect": "写保护：stats|check|mark|snapshot|history|forgetting（mark 需 admin）。",
+    "mdcg_forgetting_history": "主动遗忘裁决留痕（四态 + 三问判据）。",
+    "mdcg_identity": "身份特征识别（self/user/role/agent 的锚点、位置效应、条件特征）。",
+    "mdcg_consistency": "节点间冲突检测（L0 情绪 → L1 反思 → L2 递归反思；可投飞轮）。",
+    "mdcg_metacognition": "独立元认知（情绪/校准/盲区/信任四面；只读留痕）。",
+    "mdcg_self_state": "自我状态层（薄自我 + 富索引：状态卡单例 + 关系节点）。",
+    "mdcg_predict": "生成式预测（候选未来；过滤门 + 四维评分 + 命中反馈校准）。",
+    "mdcg_causal": "因果推理（causal 边 = 条件依赖；path|gate|chain|explain）。",
+    "mdcg_evolution": "演化账本（每次修改 = 补一条缺失条件；可 rollback 留痕）。",
+    "mdcg_restore": "恢复被 forget 的节点（在删除清单中且未 force 则拒绝）。",
+    "mdcg_health": "健康度（分桶健康 + CCG 完整度 + 验证基底覆盖 + OS 指标）。",
+    "mdcg_whoami": "身份与权限（tenant/actor/clearance/可见节点/可读密级）。",
+    "mdcg_ingest": "设备驱动：从会话文件增量摄取事件（fix-pair 挖掘 + watermark 去重）。",
+    "mdcg_watermarks": "各事件源的摄取水位（增量摄取状态，可审计）。",
+    "mdcg_whitebox": "白箱能力库调用与能力验证（ask|remember|verify_*|ping|report）。",
+    "mdcg_service_info": "服务信息（身份/版本/根目录/节点统计/工具数/权限）。",
+}
+
+# --------------------------------------------------------------------------
+# 投影规则
+# --------------------------------------------------------------------------
+_ENUM_RE = re.compile(r"[A-Za-z_][\w\-]*(?:\|[A-Za-z_][\w\-]*)+")
+_OP_SEC_RE = re.compile(r"op=([a-z_]+)：(.+?)(?=op=[a-z_]+：|$)", re.S)
+
+GENERIC_LIMIT = 24      # 通用参数（k/limit/tags/importance…）保留首段长度
+OP_SPECIFIC_LIMIT = 12  # op 专属参数（长尾）压缩长度；超此长度整体外置
+ENUM_PLACEHOLDER = "取值随 op 变化，完整枚举见 op=help"
+
+# 高频参数：无论描述是否带 op 前缀，都按「通用」处理（保留短提示）
+# ——这些是每次调用都可能要传的旋钮，让 agent 靠 schema 就能用起来。
+GENERIC_PARAMS = frozenset({
+    "op", "action", "query", "content", "node_id", "k", "limit", "intent",
+    "tags", "importance", "layer", "pid", "reason", "force", "dry_run",
+    "session", "note", "evidence", "verdict", "decision", "content_kind",
+    "budget_tokens", "text", "path", "role", "subject",
+})
+
+
+def op_sections(desc):
+    """从工具 description 里切出 {op: 段落}（机械切分，无损）。"""
+    out = {}
+    for m in _OP_SEC_RE.finditer(desc or ""):
+        out[m.group(1)] = m.group(2).strip().rstrip("；;")
+    return out
+
+
+def op_vocab(tools):
+    """全量 op 词汇表（用于判定「这是 op 专属参数的描述」）。"""
+    vocab = set()
+    for t in tools:
+        vocab |= set(op_sections(t.get("description") or ""))
+        props = (t.get("inputSchema") or {}).get("properties") or {}
+        for key, spec in props.items():
+            if key in ("op", "action"):
+                d = spec.get("description") or ""
+                for m in _ENUM_RE.finditer(d):
+                    vocab |= set(m.group(0).split("|"))
+    return vocab
+
+
+def _is_op_specific(desc, vocab, prefix_len=18):
+    head = (desc or "")[:prefix_len]
+    return any(len(o) >= 3 and o in head for o in vocab)
+
+
+def short_desc(desc, vocab, op_specific=False):
+    """投影一条参数描述。
+
+    返回 None 表示「整体外置」——该参数（长尾 op 专属）的描述不进常驻面，
+    由 ``cg(op=help, query="<参数名>")`` 按需取回。
+    """
+    if not desc:
+        return None
+    d = " ".join(str(desc).split())
+    groups = _ENUM_RE.findall(d)
+    if len(groups) == 1:
+        return groups[0]
+    if len(groups) > 1:
+        return ENUM_PLACEHOLDER
+    if op_specific:
+        # 长尾参数：短的原样留（信息本就少），长的一句话整体外置。
+        return d if len(d) <= OP_SPECIFIC_LIMIT else None
+    if len(d) > GENERIC_LIMIT:
+        return d[:GENERIC_LIMIT].rstrip() + "…"
+    return d
+
+
+def _schema_of(tool):
+    return tool.get("inputSchema") or {}
+
+
+def slim_tool(tool, vocab):
+    """投影单个工具（不修改入参）。"""
+    name = tool["name"]
+    desc = tool.get("description") or ""
+    isch = _schema_of(tool)
+    req = list(isch.get("required") or [])
+    props = isch.get("properties") or {}
+    new_props = {}
+    for key, spec in props.items():
+        clean = {k: v for k, v in spec.items() if k != "_req"}
+        d = clean.get("description")
+        if d:
+            generic = key in GENERIC_PARAMS or not _is_op_specific(d, vocab)
+            short = short_desc(d, vocab, op_specific=not generic)
+            if short:
+                clean["description"] = short
+            else:
+                clean.pop("description", None)
+        new_props[key] = clean
+    out_schema = {"type": isch.get("type") or "object", "properties": new_props}
+    if req:
+        out_schema["required"] = req
+    return {"name": name, "description": TOOL_BRIEFS.get(name) or _first_sentence(desc, 140),
+            "inputSchema": out_schema}
+
+
+def _first_sentence(desc, limit):
+    d = " ".join((desc or "").split())
+    for ch in ("。", "；", ";"):
+        i = d.find(ch)
+        if 0 < i <= limit:
+            return d[:i + 1]
+    return (d[:limit].rstrip() + "…") if len(d) > limit else d
+
+
+def slim_tools(tools):
+    """投影整个工具面。MDCG_TOOL_FACE=full 时原样返回（调试/兼容）。"""
+    if (os.environ.get(FULL_ENV) or "").strip().lower() == "full":
+        return tools
+    vocab = op_vocab(tools)
+    return [slim_tool(t, vocab) for t in tools]
+
+
+# --------------------------------------------------------------------------
+# 按需披露：cg(op=help, query=…)
+# --------------------------------------------------------------------------
+def _params_for(tool, op, limit=40):
+    isch = _schema_of(tool)
+    props = isch.get("properties") or {}
+    req = set(isch.get("required") or [])
+    vocab = {op}
+    out = [{"name": k, "type": v.get("type"), "required": k in req,
+            "desc": v.get("description") or ""}
+           for k, v in props.items()
+           if _is_op_specific(v.get("description") or "", vocab)]
+    return out[:limit]
+
+
+def help_text(tools, query=None, limit=40):
+    """从**完整真源**按需渲染说明——被投影掉的原文在此无损取回。"""
+    q = (query or "").strip()
+    by_name = {t["name"]: t for t in tools}
+    if not q:
+        return {"ok": True,
+                "tool_index": [{"name": t["name"],
+                                "brief": TOOL_BRIEFS.get(t["name"])
+                                or _first_sentence(t.get("description") or "", 120)}
+                               for t in tools],
+                "usage": 'query 取 op 名 / 参数名 / 工具名，例如 '
+                         'cg(op="help", query="write")'}
+    if q in by_name:
+        t = by_name[q]
+        isch = _schema_of(t)
+        props = isch.get("properties") or {}
+        req = list(isch.get("required") or [])
+        return {"ok": True, "tool": t["name"],
+                "description": t.get("description") or "",
+                "ops": sorted(op_sections(t.get("description") or "")),
+                "params": [{"name": k, "type": v.get("type"),
+                            "required": k in req,
+                            "desc": v.get("description") or ""}
+                           for k, v in props.items()],
+                "required": req}
+    hits = []
+    for t in tools:
+        isch = _schema_of(t)
+        props = isch.get("properties") or {}
+        req = set(isch.get("required") or [])
+        secs = op_sections(t.get("description") or "")
+        if q in secs:
+            hits.append({"tool": t["name"], "op": q, "doc": secs[q],
+                         "params": _params_for(t, q, limit)})
+        # 不短路：op 名与参数名同名时（如 goal/ref/consistency），两者都要能取回。
+        for pname, spec in props.items():
+            if pname == q or (len(q) >= 4 and pname.startswith(q)):
+                hits.append({"tool": t["name"], "param": pname,
+                             "type": spec.get("type"), "required": pname in req,
+                             "desc": spec.get("description") or ""})
+    if not hits:
+        return {"ok": False, "error": f"未找到 op / 参数 / 工具：{q}",
+                "hint": "cg(op=help) 不带 query 可列出全部工具与一行职责"}
+    return {"ok": True, "query": q, "hits": hits[:max(1, limit)]}