@furongjun1999/dsh-memory 0.4.7 → 0.4.9

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,21 @@ 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 端子代理。
+           # P4 新增（可验证记忆单元，2026-09-19）：
+           #   status  验证态 / 依赖 / 双时间轴 / 履历查询（只读）
+           #        —— 「它还成不成立」的读面；真源 md_cg/trust.py
+           # P4 新增（三元组反查原语，阶段二 4.2，2026-09-20）：
+           #   edges  按任意端 / 谓词 / 时间 + 排序分页聚合反查派生边（只读）
+           #        —— 「这条记忆从哪来 / 谁由它派生」的读面；真源
+           #        md_cg/provenance.py（find_edges）。**只读 op**：不含任何
+           #        写入 path，故读面角色一律放行（与 status 同档）
+           "ccg", "status", "edges")
 
 
 class TokenError(Exception):
@@ -102,8 +118,13 @@ 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", "status",
+                      "edges"],
         "delegable": False,
         "forbidden": ["self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -116,7 +137,7 @@ ROLE_SPECS = OrderedDict([
         # maintain=反思后的前馈/模式分离候选（apply 类改写走 require_admin）
         # insight=发现差异/新路径：开窗 window + 情景重构 reconstruct + 盲区学习 learn
         "ops_allow": ["info", "route", "read", "write", "recent", "metacognition",
-                      "session", "maintain", "insight"],
+                      "session", "maintain", "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -125,7 +146,8 @@ ROLE_SPECS = OrderedDict([
         "duty": "判断规则、执行结果和结构是否有效；只写验证证据与负记忆",
         "can_write": True, "can_admin": False, "clearance_cap": "internal",
         "layers_allow": ["rejected", "contextual"],
-        "ops_allow": ["info", "route", "read", "write", "verify", "insight"],
+        "ops_allow": ["info", "route", "read", "write", "verify", "insight",
+                      "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/self/anchor 层（不得改被验证内容）",
                       "private/secret 密级", "裁决与删除"],
@@ -138,7 +160,7 @@ ROLE_SPECS = OrderedDict([
         # session 仅开放只读 recall；note/compact 在分发层按 can_write 拦截
         # insight 仅开放只读呈现（list/report/outlook/reconstruct）；写入被 can_write 拦截
         "ops_allow": ["info", "route", "read", "recent", "whitebox", "session",
-                      "insight"],
+                      "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["全部写入", "private/secret 密级", "管理操作"],
     }),
@@ -152,7 +174,7 @@ ROLE_SPECS = OrderedDict([
         # insight=整体结构洞察 outlook（趋势/盲区/建议）+ 条件层报告 report
         "ops_allow": ["info", "read", "write", "sustain", "scrub", "evolution",
                       "self_state", "metacognition", "link", "session",
-                      "maintain", "insight"],
+                      "maintain", "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -161,7 +183,8 @@ ROLE_SPECS = OrderedDict([
         "duty": "无令牌时的降级身份：只读、最低密级",
         "can_write": False, "can_admin": False, "clearance_cap": "internal",
         "layers_allow": [],
-        "ops_allow": ["info", "route", "read", "recent", "whitebox"],
+        "ops_allow": ["info", "route", "read", "recent", "whitebox", "status",
+                      "edges"],
         "delegable": False,
         "forbidden": ["全部写入", "private/secret 密级", "管理操作"],
     }),
@@ -177,12 +200,40 @@ 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)
+
+
+# 生效条件：role 为假值（None/空串）时按 "" 处理，经 strip().lower() 得 r，r 命中 ROLE_ALIASES 键时返回别名，否则返回 r 本身。
 def normalize_role(role: str) -> str:
     r = (role or "").strip().lower()
     return ROLE_ALIASES.get(r, r)
 
 
+# 生效条件：normalize_role(role) 得 r，r 不在 ROLE_SPECS 中即抛 TokenError，否则返回 dict(ROLE_SPECS[r]) 的浅拷贝。
 def role_spec(role: str):
     r = normalize_role(role)
     if r not in ROLE_SPECS:
@@ -190,6 +241,7 @@ def role_spec(role: str):
     return dict(ROLE_SPECS[r])
 
 
+# 生效条件：无 required 形参，调用即返回含 SCHEMA、token_file()、CORE_PRIVATE_SENSITIVITIES/CORE_LAYERS/ALL_LAYERS/POSITION_ROLES/DELEGABLE_ROLES/ROLE_ALIASES/ROLE_SPECS 各自 list/dict 拷贝的字典。
 def catalog():
     """角色职责矩阵（供 whoami / service_info / 文档自描述）。"""
     return {"schema": SCHEMA, "token_file": token_file(),
@@ -205,10 +257,12 @@ def catalog():
 # 存储（仓库外，0600）
 # --------------------------------------------------------------------------
 
+# 生效条件：path 为真值时返回 path，否则回落 os.environ.get(TOKEN_FILE_ENV)（取到空串同为假值），仍为假值时返回 DEFAULT_TOKEN_FILE。
 def token_file(path: str = None) -> str:
     return path or os.environ.get(TOKEN_FILE_ENV) or DEFAULT_TOKEN_FILE
 
 
+# 生效条件：p=token_file(path) 的 os.path.exists(p) 为真且 json.load 得到 dict 时，setdefault("tokens", {}) 后返回该 dict；路径不存在、解析结果非 dict 或抛 OSError/ValueError 时返回 {"schema": SCHEMA, "tokens": {}}。
 def _load(path: str = None) -> dict:
     p = token_file(path)
     if os.path.exists(p):
@@ -223,6 +277,7 @@ def _load(path: str = None) -> dict:
     return {"schema": SCHEMA, "tokens": {}}
 
 
+# 生效条件：以 data 为内容、p=token_file(path) 为目标，先对 os.path.dirname(p) or "." 做 makedirs(exist_ok=True)，写 p+".tmp" 后 os.replace 覆盖 p，再尝试 chmod 0600（仅吞 OSError）。
 def _save(data: dict, path: str = None):
     p = token_file(path)
     os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
@@ -236,14 +291,17 @@ def _save(data: dict, path: str = None):
         pass
 
 
+# 生效条件：secret 经 encode("utf-8") 后取 sha256 的 hexdigest；secret 非 str 时按其 encode 失败抛出。
 def _hash(secret: str) -> str:
     return hashlib.sha256(secret.encode("utf-8")).hexdigest()
 
 
+# 生效条件：_rank(want) <= _rank(cap) 时返回 want，否则返回 cap。
 def _clamp_level(want: str, cap: str) -> str:
     return want if _rank(want) <= _rank(cap) else cap
 
 
+# 生效条件：allow 为 None 时按 parent_allow 是否为 None 返回 None 或 list(parent_allow)；否则 parent_allow 为 None 或含 "*" 时返回 list(allow)；否则 allow 含 "*" 时返回 list(parent_allow)；否则返回 [x for x in allow if x in parent_allow]。
 def _narrow(allow, parent_allow):
     """求交：子权限只能收窄。父为 None（不限制）时取子；子为 None 时取父。"""
     if allow is None:
@@ -255,10 +313,12 @@ def _narrow(allow, parent_allow):
     return [x for x in allow if x in parent_allow]
 
 
+# 生效条件：role/token_id/secret 即使为假值也照拼，返回 f"{PREFIX}.{role}.{token_id}.{secret}"。
 def make_token(role: str, token_id: str, secret: str) -> str:
     return f"{PREFIX}.{role}.{token_id}.{secret}"
 
 
+# 生效条件：token 为假值时按 "" 处理，split(".") 后长度不为 4 或 parts[0] != PREFIX 即抛 TokenError；长度与前缀合规后 role/token_id/secret 任一为空再抛 TokenError；否则返回 (role.lower(), token_id, secret)。
 def parse_token(token: str):
     parts = (token or "").strip().split(".")
     if len(parts) != 4 or parts[0] != PREFIX:
@@ -273,6 +333,7 @@ def parse_token(token: str):
 # 签发 / 校验 / 派生 / 吊销
 # --------------------------------------------------------------------------
 
+# 生效条件：role 经 normalize_role+role_spec（未知角色抛 TokenError），clearance 为假值时取 spec["clearance_cap"] 再经 _clamp_level 收窄到该 cap，layers_allow/ops_allow 经 _narrow 与 spec 默认求交，actor 为假值时取 role，delegable is None 时取 spec["delegable"]、否则按所传值取 bool，ttl 为真值时 expires_at=now+float(ttl)、为假值（None/0）时 None，记录写入 token_file(path) 后返回含明文 token 的字典。
 def issue(role: str, actor: str = None, clearance: str = None,
           tenant: str = "default", ttl: float = None, label: str = "",
           issued_by: str = "root", parent: str = None, delegable: bool = None,
@@ -307,6 +368,7 @@ def issue(role: str, actor: str = None, clearance: str = None,
             "expires_at": rec["expires_at"], "token_file": token_file(path)}
 
 
+# 生效条件：token 先经 parse_token（格式非法即抛 TokenError），其后 _load(path) 的 tokens 中该 token_id 无记录、rec 的 role 与解析出的 role 不等、revoked_at 为真、hash 与 _hash(secret) 经 hmac.compare_digest 不等、expires_at 为真且小于当前时间中任一成立即抛 TokenError；否则返回 Principal，tenant=tenant or rec.get("tenant") or "default"、actor=rec.get("actor") or role、clearance=rec.get("clearance") or "internal"、can_write/can_admin 取对应 rec 值的 bool。
 def verify_token(token: str, tenant: str = None, path: str = None) -> Principal:
     """校验令牌 → Principal。任何异常都抛 TokenError（fail-closed）。"""
     role, token_id, secret = parse_token(token)
@@ -333,6 +395,7 @@ def verify_token(token: str, tenant: str = None, path: str = None) -> Principal:
         ops_allow=rec.get("ops_allow"), auth_mode="token")
 
 
+# 生效条件：parent_token 经 verify_token(parent_token, path=path) 成功且父记录 delegable 为真才继续，否则抛 TokenError；role 经 normalize_role+role_spec，clearance 为假值时取 spec["clearance_cap"] 再 _clamp_level，若仍高于 parent.clearance 则降为 parent.clearance 并向 clamped 追加 "clearance"；layers/ops 先与 spec 求交再与父记录求交；can_write/can_admin 取 spec 与父对应值的与；ttl 为真值时 expires_at=now+float(ttl)、为假值（None/0）时沿用父记录 expires_at；新记录 delegable 恒 False、parent/issued_by 为 parent.token_id，返回含明文 token 与 clamped 的字典。
 def derive(parent_token: str, role: str, actor: str = None, ttl: float = None,
            label: str = "", path: str = None, clearance: str = None,
            layers_allow=None, ops_allow=None):
@@ -376,6 +439,7 @@ def derive(parent_token: str, role: str, actor: str = None, ttl: float = None,
             "expires_at": rec["expires_at"]}
 
 
+# 生效条件：normalize_role(unit) 结果不在 POSITION_ROLES 时抛 TokenError；否则返回 Principal：unit/role=u、can_admin 恒 False、clearance=_clamp_level(spec["clearance_cap"], p.clearance)、can_write=bool(spec["can_write"]) and bool(p.can_write)、layers_allow/ops_allow=_narrow(spec 对应值, p 对应值)，tenant/actor/session/harness/token_id/parent/expires_at/auth_mode/theory 等沿用 p。
 def narrowed_principal(p: Principal, unit: str) -> Principal:
     """按「单元」收窄 principal 权限（**请求级**身份，只能变小不能变大）。
 
@@ -412,6 +476,7 @@ def narrowed_principal(p: Principal, unit: str) -> Principal:
         theory_ok=p.theory_ok, theory_version=p.theory_version)
 
 
+# 生效条件：token_id 在 _load(path) 的 tokens 中无记录时抛 TokenError；有记录则将其 revoked_at 置为 time.time() 并 _save，再对 tokens 中 parent 等于 token_id 的每个子令牌递归 revoke(c, path)，返回 {"ok": True, "token_id": token_id, "revoked_children": children}。
 def revoke(token_id: str, path: str = None):
     data = _load(path)
     rec = (data.get("tokens") or {}).get(token_id)
@@ -426,6 +491,7 @@ def revoke(token_id: str, path: str = None):
     return {"ok": True, "token_id": token_id, "revoked_children": children}
 
 
+# 生效条件：从 _load(path)（path 为 None 时取默认令牌文件）的 tokens 取值；条目的 revoked_at 为真且 include_revoked 为假时跳过；返回不含密钥材料与摘要的清单；
 def list_tokens(path: str = None, include_revoked: bool = False):
     """令牌清单（不含密钥材料与摘要）。"""
     out = []
@@ -450,10 +516,12 @@ def list_tokens(path: str = None, include_revoked: bool = False):
 # CLI：签发 / 派生 / 清单 / 吊销 / 角色矩阵
 # --------------------------------------------------------------------------
 
+# 生效条件：obj 一律经 json.dumps(obj, ensure_ascii=False, indent=1) 加换行写入 sys.stdout；obj 不可 JSON 序列化时抛出 TypeError。
 def _print(obj):
     sys.stdout.write(json.dumps(obj, ensure_ascii=False, indent=1) + "\n")
 
 
+# 生效条件：v 为假值（None/空串）时返回 None；否则按 "," 切分、strip 后丢弃空项，结果为空列表时同样返回 None。
 def _csv_list(v):
     """CLI 的逗号分隔白名单 → list；空值返回 None（= 不额外收窄）。
 
@@ -464,6 +532,24 @@ def _csv_list(v):
     return [x.strip() for x in str(v).split(",") if x.strip()] or None
 
 
+# 生效条件：path 经 os.path.abspath 得 p，其 dirname 非空时 makedirs(exist_ok=True)，text 原样写入 p+".tmp" 后 os.replace 覆盖 p，再尝试 chmod 0600（仅吞 OSError）。
+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
+
+
+# 生效条件：argv 为 None 时取 sys.argv[1:]；经 argparse 解析（--token-file 与必填子命令 issue/verify/revoke/list/roles 等）；参数非法时经 argparse 退出，写盘失败抛 OSError；
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.tokens",
@@ -491,6 +577,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 +619,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:
@@ -539,4 +661,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/tool_face.py

@@ -0,0 +1,261 @@
+# -*- 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": "灵枢认知图唯一入口（34 op：写/读/审/护/演化/元认知/预测/白箱/验证态 status/"
+          "三元组反查 edges…）。" + 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",
+})
+
+
+# 生效条件：desc 为 None/空串等假值时按 `desc or ""` 回落空串、`_OP_SEC_RE.finditer` 无匹配而返回空 dict；否则以每个匹配的组 1 为键、组 2 去首尾空白并去掉结尾「；/;」后为值填入并返回。
+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
+
+
+# 生效条件：tools 为空时可迭代但无元素、返回空 set；否则遍历每个工具，并入其 `t.get("description") or ""` 经 op_sections 得到的键，以及其 `(t.get("inputSchema") or {}).get("properties") or {}` 中名为 op/action 的属性 description（缺省 ""）里 `_ENUM_RE` 匹配串按 "|" 拆出的词，返回并集 vocab。
+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
+
+
+# 生效条件：head=(desc or "")[:prefix_len]（desc 假值即空串、prefix_len 默认 18），当 vocab 中存在长度 ≥3 且作为子串出现在 head 中的元素时返回 True，否则（含 vocab 为空）返回 False。
+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)
+
+
+# 生效条件：desc 为假值返回 None；否则空白归一化后按 _ENUM_RE 结果分派——恰 1 组返回该组、多于 1 组返回 ENUM_PLACEHOLDER、0 组时若 op_specific 为真则 d 长度 ≤OP_SPECIFIC_LIMIT 原样返回否则 None，若 op_specific 为假则 d 长度 >GENERIC_LIMIT 时返回 d[:GENERIC_LIMIT].rstrip()+"…"、否则原样返回 d。
+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
+
+
+# 生效条件：tool 的 "inputSchema" 键存在且值为真时原样返回该值；键缺失或值为 None/{} 等假值时按 `or {}` 回落返回空 dict。
+def _schema_of(tool):
+    return tool.get("inputSchema") or {}
+
+
+# 生效条件：tool 须含 "name" 键（缺失即 KeyError），desc=`tool.get("description") or ""`、isch=`_schema_of(tool)`；逐条属性去掉 "_req" 键后，若其 description 为真则按「key 在 GENERIC_PARAMS 或 `not _is_op_specific(d, vocab)`」判为 generic，再经 short_desc 投影——非空则替换 description、空则弹出该 description 键；返回 name 与 `TOOL_BRIEFS.get(name) or _first_sentence(desc,140)` 的 description，inputSchema 的 type 取 `isch.get("type") or "object"`，仅当 required 非空时才带 "required"。
+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}
+
+
+# 生效条件：d=折叠 (desc or "") 空白，按 "。"、"；"、";" 顺序取各字符在 d 中 `find` 的首次出现位置 i，遇到首个满足 0<i<=limit 者即返回 d[:i+1]；三个字符的首次位置均不满足时，len(d)>limit 返回 d[:limit].rstrip()+"…"，否则原样返回 d（limit=0 时无 i 满足，d 非空则返回 "…"）。
+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
+
+
+# 生效条件：环境变量 FULL_ENV 取值 `(os.environ.get(FULL_ENV) or "").strip().lower()=="full"`（未设或设为空串均不成立）时原样返回入参 tools；否则以 tools 算出 vocab 并返回 `[slim_tool(t, vocab) for t in tools]`（tools 为空则返回空列表）。
+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=…)
+# --------------------------------------------------------------------------
+# 生效条件：取 `_schema_of(tool)` 的 properties，仅保留 description（缺省 ""）满足 `_is_op_specific(desc, {op})` 的属性，每项记为 name/type/required(k in required)/desc，返回该列表的 `out[:limit]` 切片（limit 默认 40，limit=0 得空列表，负值从尾部削减）。
+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]
+
+
+# 生效条件：tools 用于建 `by_name={t["name"]: t}`（某工具缺 "name" 即 KeyError），q=(query or "").strip()——q 为空串返回 {"ok":True,"tool_index":[每工具 name 与 `TOOL_BRIEFS.get(name) or _first_sentence(desc,120)`],"usage":...}；q 等于某工具名时返回该工具的 description/ops（op_sections 键排序）/params/required；否则逐工具收集「q 出现在 op 段落键中」与「pname==q 或 len(q)>=4 且 pname 以 q 开头」两类命中（不互斥、可同时追加），全部工具遍历后无命中返回 {"ok":False,"error",...,"hint",...}，有命中返回 {"ok":True,"query":q,"hits":hits[:max(1, limit)]}（limit≤1 时按 1 条截取）。
+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)]}