@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/src/lib/prompt_safety.ts

@@ -0,0 +1,62 @@
+/**
+ * prompt_safety.ts · 注入边界文本安全（宿主严格模板的转义）
+ *
+ * ── 根因（issue #16，2026-09-16）────────────────────────────────────────
+ * dsh 宿主 `@deepseek-ai/dsh-system-prompt` 的 `interpolate()` 会对**每个
+ * section / context** 文本做严格 `{{variable}}` 插值，且**四类一律 throw**：
+ *   ① `{{` 之后能找到 `}}` 但不成简单组（GROUP_AT = /^\{\{([^{}]*)\}\}/ 不匹配）
+ *   ② 组成立但名不匹配 /^[a-z][a-z0-9_]*$/（如 `{{.Architecture}}`）
+ *   ③ 名合法但未注册（如 `{{name}}`）
+ *   ④ 已注册但值为 undefined
+ * `renderContextSections()` 逐 context 调用它，throw 直接冒泡到
+ * `system-prompt/assemble` → **该轮请求整体失败**。
+ *
+ * ── 伤害路径 ───────────────────────────────────────────────────────────
+ * 自动记忆把用户命令原样沉淀（如 `docker inspect --format '{{.Architecture}}'`）
+ * → auto-recall 把含裸 `{{` 的预览推入 `assembly.contexts`
+ * → 宿主每轮 assemble 必抛 → **会话永久不可用**（记忆永久在库，非偶发故障）。
+ *
+ * ── 处置：为何只在注入边界转义，不在写入侧 ────────────────────────────
+ *   ① 记忆真源必须保真：`{{.Architecture}}` 是用户命令原文，写入侧转义会
+ *      不可逆失真，且 cg(op=read) / 工具面 / 检索都依赖原文（= 污染真源）；
+ *   ② 伤害面就是「注入到 prompt 的文本」，在注入边界处理即**最小充分**；
+ *   ③ 与写入侧 desensitize 不冲突：脱敏是**隐私**要求（不许落盘），
+ *      转义是**渲染安全**要求（落盘保真、渲染时规避）——层次不同。
+ *
+ * ── 转义策略：确保文本中不出现连续两个 `{` ────────────────────────────
+ * 依据（宿主源码 `lib/index.js:109-116`）：`interpolate` 以
+ * `text.indexOf("{{")` 为**唯一扫描锚点**；破坏 `{{` 序列后循环不进入，
+ * 文本走 `text.slice(last)` 原样返回。
+ *   · `}}` 无需处理——它只在 `{{` 成组时参与解析，锚点已破即无意义；
+ *   · 逐对打断（而非 `split('{{').join(...)`）：后者对 `{{{a}}}` 会产出
+ *     `{ {{a}}}`——新锚点仍在（相邻 `{` 重新合成），不幂等也不安全；
+ *   · 跨 context 拼接安全：`joinContextSections` 以 `"\n\n"` 分隔并带固定
+ *     前缀（`lib/index.js:85-87`，前缀以 `.` 结尾），边界不会合成新 `{{`；
+ *   · 为何不用零宽字符：显示上「看起来一样」但复制会带入不可见字符
+ *     （终端粘贴即出错）——诚实性优先，宁可让改写可见。
+ *
+ * 幂等：结果中不存在 `{{`，重复调用结果不变。
+ * 边界：本函数只服务**注入到宿主 prompt 的文本**；记忆真源与工具返回原文
+ *       一律不动（工具结果不进 assembly 插值面）。
+ */
+
+/** 宿主严格模板的扫描锚点。 */
+const TEMPLATE_OPEN = '{{'
+
+/**
+ * 把文本中每一对相邻的 `{` 打断（插入半角空格），使其不再包含 `{{`。
+ *
+ * 不含 `{{` 的文本**原样返回**（零改写，保真）。
+ * 例：`{{.Architecture}}` → `{ {.Architecture}}`；`{{{a}}}` → `{ { {a}}}`。
+ */
+export function escapePromptBraces(text: string): string {
+  if (!text.includes(TEMPLATE_OPEN)) return text
+  let out = ''
+  for (let i = 0; i < text.length; i++) {
+    const ch = text.charAt(i)
+    out += ch
+    // 该 `{` 与下一个字符构成锚点 → 立即插入空格打断
+    if (ch === '{' && text.charAt(i + 1) === '{') out += ' '
+  }
+  return out
+}

package/src/lib/token_store.ts

@@ -30,7 +30,7 @@ import { spawnSync } from 'node:child_process'
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { pythonPathValue, repoRoot } from './datapath.js'
+import { pythonPathValue, runRoot } from './datapath.js'
 
 /** 凭据来源（用于启动日志与故障定位）。 */
 export type TokenSource =
@@ -113,10 +113,9 @@ function issueToken(python: string, role: string, actor: string, clearance: stri
         windowsHide: true,
         timeout: 15_000,
         // 与工作纪律第 15 条同源：显式 UTF-8 + PYTHONUTF8，规避 Windows GBK 解码异常。
-        // issue #12：cwd+PYTHONPATH 锚定插件仓根——否则 npm 包形态下宿主在仓外
-        // 启动时 `python -m md_cg.tokens` 找不到随包 md_cg，首启签发静默失败，
-        // md_cg 侧降级只读 guest（写入全不落盘且无报错）。
-        cwd: repoRoot(),
+        // 模块解析靠 PYTHONPATH 锚定随包 md_cg（不依赖 cwd）；cwd 取包外目录，
+        // 否则 pnpm 更新本插件时 rmdir 包目录必报 ERR_PNPM_EBUSY。见 datapath.runRoot()。
+        cwd: runRoot(),
         env: {
           ...process.env,
           PYTHONPATH: pythonPathValue(),

package/zcode/AGENTS.md

@@ -1,12 +1,12 @@
-# 工作纪律（工作纪律_认知图条目_v1.1）· 16 条
+# 工作纪律（工作纪律_认知图条目_v1.1）· 17 条
 
 > 本文件由 `scripts/render_discipline.py` 从真源
 > `docs/工作纪律_认知图条目_v1.1.json` 渲染生成，**请勿手改**；改真源后重跑渲染。
-> 真源指纹（SHA256 前16位）：cd3e263159036432
+> 真源指纹（SHA256 前16位）：37aed1b5423c00af
 
 ## 概述
 
-工作纪律集: 4条方法论(理论先行/全面处理/白箱方法/根因) + 3条执行(验证/双副本/兜底) + 1条思考(中文思考/协作模式分级) + 1条保密(敏感信息隔离) + 3条图像线(选源护栏/历史查询优先/算法权威唯一) + 1条协作(访谈澄清:先问清再动手) + 1条合规(内容政策合规:公开产物过内容政策+隐私双清单) + 1条执行环境(命令执行统一走python/UTF-8: 显式encoding+PYTHONUTF8=1, 规避GBK) + 1条记忆闭环(任务收尾归档:每次任务执行完只将核心修改(内容/原因/位置/验证结论)存入灵枢记忆, 不写中间过程)
+工作纪律集: 4条方法论(理论先行/全面处理/白箱方法/根因) + 3条执行(验证/双副本/兜底) + 1条思考(中文思考/协作模式分级) + 1条保密(敏感信息隔离) + 3条图像线(选源护栏/历史查询优先/算法权威唯一) + 1条协作(访谈澄清:先问清再动手) + 1条合规(内容政策合规:公开产物过内容政策+隐私双清单) + 2条执行调度与运行环境(命令执行统一走python/UTF-8: 显式encoding+PYTHONUTF8=1, 规避GBK; 任务派发统一走蜂巢: 任何执行性任务经蜂巢spawn/submit执行并留痕, agent本体只做编排, L1出口=产物落点为只读判定(不改仓库/外部状态)可直跑须留痕) + 1条记忆闭环(任务收尾归档:每次任务执行完只将核心修改(内容/原因/位置/验证结论)按CCG六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 不写中间过程)
 
 ## 执行公约
 
@@ -23,7 +23,7 @@
 ### 1. 理论先行
 
 - **触发**：重要项目｜长期任务
-- **动作**：识别项目级别→检索相关理论文档→输出理论要点→再进入设计
+- **动作**：识别项目级别→检索理论文档与既有实践→输出理论要点→再进入设计
 - **不适用**：情感交互｜闲聊
 - **声明**：按工作纪律第1条: 理论先行——先查相关理论与既有实践再动手。
 
@@ -128,9 +128,16 @@
 ### 16. 任务收尾归档(记忆闭环)
 
 - **触发**：任务执行完成｜修改落地后｜交付后
-- **动作**：任务收尾→提炼核心修改(内容/原因/位置/验证结论四要素, 不写中间过程/试错/调试/重复确认)→写入灵枢记忆(认知图/MCP memory)→标注关联条目+更新 subgraph/depends_on
+- **动作**：任务收尾→提炼核心修改(内容/原因/位置/验证结论四要素, 不写中间过程/试错/调试/重复确认)→按 CCG 六要素成文(# 功能名/# 生效条件/# 子功能/# 执行/# 验证方式/# 不适用条件 六行缺一不可, 与正文四要素并置)→写入灵枢记忆(认知图/MCP memory)→读回确认(写入后发起一次读取查询确认写入成功且可检索)→标注关联条目+更新 subgraph/depends_on
 - **不适用**：情感交互｜闲聊｜纯查询无改动
-- **声明**：按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)存入灵枢记忆, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆」闭环。
+- **声明**：按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。
+
+### 17. 任务派发统一走蜂巢
+
+- **触发**：执行性任务｜多智能体协作｜批量/并行工作｜探索盘点｜运行测试/脚本
+- **动作**：任务→按产物落点判据定层级(不改仓库/外部状态的只读判定=L1直跑并按任务留痕一条(复核者=使用者+GitHub使用者); 改状态=必派发, 不得自我豁免)→拆spec(LLM委托型=默认exec.py: model+user_prompt+context_files; 确定性执行=自定义worker, 契约「读spec.json写result.json」)→hive_spawn/CLI submit→poll→汇总; 兜底情形须声明「蜂巢不可用, 兜底降级」
+- **不适用**：纯会话内对话/问答(无执行动作)｜蜂巢不可用且任务必须立即执行(兜底须声明)｜L1只读判定(产物落点=不改仓库/不改外部状态的本地只读命令, 秒级·可逆·高频, 如跑门禁/测试/回归/lint看结论; 判据是产物落点而非「任务简单」的主观感受, 直跑须输出一行「L1 直跑：<命令> — 风险/频次/可逆性」留痕, 留痕粒度按任务(同一任务的多条只读命令合并为一条留痕, 不逐命令逐行); 层级归属的复核者=使用者+GitHub使用者)｜情感交互｜闲聊
+- **声明**：按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。L1只读判定(产物落点=不改仓库/外部状态)可直跑, 须输出「L1 直跑：<命令> — 风险/频次/可逆性」留痕。
 
 ## 声明出口（`response.direct` 原文 · 未输出即未执行）
 
@@ -151,7 +158,8 @@
 | 13 | 按工作纪律第13条: 访谈澄清——先提问确认要做什么,逐轮问到完全清楚才动手;事实自查,决策归使用者,不完全清楚不固化。 |
 | 14 | 按工作纪律第14条: 内容政策合规——对外公开产物必须过「内容政策+隐私」双清单，过滤在生成阶段做；已发布发现违规要删条+重写git历史+通知平台清缓存。 |
 | 15 | 按工作纪律第15条: 命令执行统一走python——argv列表+显式UTF-8+PYTHONUTF8=1, 不经Windows shell, 规避GBK解码异常。 |
-| 16 | 按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)存入灵枢记忆, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆」闭环。 |
+| 16 | 按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。 |
+| 17 | 按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。L1只读判定(产物落点=不改仓库/外部状态)可直跑, 须输出「L1 直跑：<命令> — 风险/频次/可逆性」留痕。 |
 
 ## 记忆接口速查（`cg` / `stg`）
 
@@ -160,16 +168,19 @@
 | op | 用途 | 常用参数 |
 |---|---|---|
 | `route` | 任务开始路由记忆（返回知识 + 建议能力，不执行） | `intent`（任务意图） |
-| `read` | 召回/检索/按 id 取（`session`=只取该会话归属的记忆，缺省不过滤） | `query` / `node_id` / `k` / `layer` / `budget_tokens` / `context` / `session` |
+| `read` | 召回/检索/按 id 取（`session`=只取该会话归属的记忆，缺省不过滤；`validity=true`=时效过滤（显式启用，缺省不过滤），**仅排除「已过期」，「未生效」一律保留**——两者语义相反） | `query` / `node_id` / `k` / `layer` / `budget_tokens` / `context` / `session` / `validity` |
+| `edges` | 三元组反查（**只读**）：按派生边任意端/谓词/时间反查「这条记忆从哪来 / 谁由它派生」（subject/predicate/object 即 child/relation/parent）；`expand_nodes=true` 附命中端点节点卡 | `child` / `parent` / `relation` / `batch` / `start_time` / `end_time` / `time_axis` / `ordering` / `offset` / `limit` / `aggregation` / `expand_nodes` |
 | `write` | 写入（先按 content_kind 审核 + 冲突检测，ACCEPT 落盘 / DEFER 入审核队列 / REJECT 入负记忆）。**自动归属**：frontmatter 带 `writer`/`session`/`harness`（服务端身份，不可伪造） | `content` / `content_kind`（text/code/…）/ `node_id`（同 id 即改写）/ `layer` / `tags` / `importance` / `verification_basis` / `condition_space` / `gated` / `consistency` / `on_conflict`（reject\|defer\|record） |
 | `verify` | 对节点做证据验证（confirmed/weakened/falsified）——**非队列裁决** | `node_id` / `verdict` / `evidence` |
-| `review` | 审核队列：`action=list/rounds/records` 查看；传 `pid`+`decision`+`reason` 即裁决落盘（accept/reject/edit/merge，**需 can_admin**；本机未配置外部验证器时写入恒 DEFER 入队，靠此裁决落盘） | `action` / `pid` / `decision` / `reason` / `edits` / `merge_into` |
+| `review` | 审核队列：`action=list/rounds/records/stats` 查看；传 `pid`+`decision`+`reason` 即裁决落盘（accept/reject/edit/merge/noop，**需 can_admin**；`noop`=已评估且判定不改动任何现有记忆，只留痕不入库、不进负记忆；本机未配置外部验证器时写入恒 DEFER 入队，靠此裁决落盘） | `action` / `pid` / `decision` / `reason` / `edits` / `merge_into` |
+| `task` | 结构层任务实体（工程台账，跨会话/上下文压缩后不遗忘）：`name` 即身份（同名即同任务，slug 归一），`action` = open/status/plan_add/get/list/find/session（缺省 list）；**迁 `done` 必须同时给 `result`**（缺一不收，拒收不落盘）；未提供的字段沿用旧值（结果不会被静默清空） | `name` / `action` / `plan`（分步计划，每轮覆盖） / `change`（计划变更，逐轮追加） / `result` / `task_status`（active\|blocked\|done\|dropped） / `goal` / `acceptance` / `boundary` / `condition` / `node_id` |
 | `recent` | 近期事件窗口 | `action`（add/list/clear）/ `limit` |
 | `forget` / `protect` | 软删除/恢复 / 写保护 | `node_id` |
+| `help` | 取回工具面上**被投影外置**的完整 op / 参数文档（工具面渐进披露：常驻提示只留一行职责，参数语义按需取；不带 `query` 则列出全部工具） | `query`（工具名或 op 名，如 `cg` / `write`）/ `limit` |
 
 三条调用铁律：
 1. **`op` 必填**——漏传会触发参数签名推导兜底（返回标记 `op_derived: true`），复杂任务中也必须显式传，防静默执行错误意图。
-2. **返回 `moved_to: "review_queue"` / `verdict: DEFER/REJECT` 时不要重试**——这是校验闸门的正常行为（返回自带 `hint` 说明），重试同样结果；落盘须由设计者权限（can_admin）经 `op=review` 裁决（decision=accept/reject/edit/merge，本机工具：`python scripts/review_cli.py list`），agent 端无裁决权是设计（写入者不得自裁自决），转告使用者即可。
+2. **返回 `moved_to: "review_queue"` / `verdict: DEFER/REJECT` 时不要重试**——这是校验闸门的正常行为（返回自带 `hint` 说明），重试同样结果；落盘须由设计者权限（can_admin）经 `op=review` 裁决（decision=accept/reject/edit/merge/noop，本机工具：`python scripts/review_cli.py list`），agent 端无裁决权是设计（写入者不得自裁自决），转告使用者即可。
 3. `stg` 同理经 `op` 分发（`timeline` / `relation` / `anchors` 等）。
 
 ## 收尾强制流程（任务完成时不可跳过）

package/zcode/README.md

@@ -18,6 +18,10 @@ ZCode 侧的记忆访问复用同一套 MCP 大脑，配置方式与 CodeBuddy
 （见 [`../codebuddy/mcp.json`](../codebuddy/mcp.json) 与 [`../codebuddy/README.md`](../codebuddy/README.md)），
 只需把 `MDCG_ACTOR` 改为 `zcode`。
 
+该模板同源含第二条 MCP server `hive`（蜂巢：多智能体并发 + 任务上下文管理），一并合并即可；
+ZCode 与 CodeBuddy 指向同一仓库时**共享同一并发池**。语义与边界见
+[`../hive/README.md`](../hive/README.md) 的「各 harness 注册」。
+
 ## 与 CodeBuddy 并存
 
 两者互不干扰——CodeBuddy 读根目录 `CODEBUDDY.md`，ZCode 读根目录 `AGENTS.md`；

package/docs//345/212/237/350/203/275/350/260/203/347/224/250/346/230/240/345/260/204/350/241/250_v0.1.md

@@ -1,221 +0,0 @@
-# 功能调用映射表 v0.1（功能 → 显式代码）
-
-> 目标：**任何一个功能，都能从这份文档查到它调用的是哪段代码**。
-> 所有调用都是显式的——没有隐式 provider、没有隐式记忆后端。
->
-> 版本：v0.1 · 2026-09-10 · 对应改造：md_cg 唯一真源 / AEIS 降能力库 / 白箱下线 / roleplay+mutual 归 LIB。
-
----
-
-## 0. 三条总原则
-
-| 原则 | 含义 | 落点 |
-| --- | --- | --- |
-| **唯一真源** | 记忆的写 / 读 / 裁决 / 留痕只有一处：md_cg 认知图 | `md_cg/` |
-| **能力库** | AEIS 不再存记忆，只提供能力（白箱引擎、角色生成） | 由 md_cg 显式调用 |
-| **显式调用** | 每个功能 = 一条写明参数的调用，可 grep 可追踪 | 本表 |
-
-```
-DSH 插件 (src/)
-   │  src/lib/mdcg_client.ts  ← 插件侧唯一显式入口
-   ▼
-MCP stdio：md_cg/mcp_server.py
-   │  cg(op=...) / stg(op=...)        ← 两个认知基元（kernel 面）
-   │  mdcg_remember                  ← 写入工具（跳过 audit 的写入口，见 §1 注）
-   ├──────────────► md_cg/*.py        （认知图内部实现）
-   └─ cg(op=whitebox) ─► md_cg/whitebox.py ─► AEIS 能力库（python -m aeis.mcp.server）
-```
-
----
-
-## 1. 认知基元 `cg`（`md_cg/mcp_server.py:_cg_call`，入口 L1058）
-
-| 功能 | 显式调用 | 代码位置 |
-| --- | --- | --- |
-| 服务信息 / 健康 | `cg(op=info)` | `mcp_server.py:1062` → `audit.kinds` |
-| 路由：意图→知识+建议能力 | `cg(op=route)` | `mcp_server.py:1070` → `MdCG.search` |
-| 读取（按 id / 召回 / 预算） | `cg(op=read)` | `mcp_server.py:1090` → `MdCG.get` / `MdCG.recall` / `MdCG.search` |
-| 写入（含冲突检测/闸门/**审核**） | `cg(op=write)` | `mcp_server.py:1344` → `audit.audit` + `MdCG.add` / `remember_gated` / `propose` |
-| **插件写入入口（跳过审核）** | `mdcg_remember` | `mcp_server.py:1691` → `MdCG.remember_gated`（gated=true）/ `MdCG.add`（gated=false） |
-| 目标 | `cg(op=goal)` | `mcp_server.py:1190` → `MdCG.add_goal` / `set_goal_status` / `list_goals` |
-| 最近记忆 | `cg(op=recent)` | `mcp_server.py:1209` → `MdCG.remember_event` / `recent_events` |
-| 外部裁决回填 | `cg(op=verify)` | `mcp_server.py:1221` → `MdCG.verify` |
-| 审核队列 | `cg(op=review)` | `mcp_server.py:1225` → `MdCG.review_*` |
-| 主动遗忘 / 恢复 | `cg(op=forget)` | `mcp_server.py:1241` → `MdCG.forget` / `restore` |
-| 保护（不可遗忘） | `cg(op=protect)` | `mcp_server.py:1247` → `_protect_call` → `md_cg/protect.py` |
-| 身份维度 | `cg(op=identity)` | `mcp_server.py:1250` → `_identity_call` → `md_cg/identity.py` |
-| 一致性检测 | `cg(op=consistency)` | `mcp_server.py:1253` → `_consistency_call` → `md_cg/consistency.py` |
-| 元认知 | `cg(op=metacognition)` | `mcp_server.py:1256` → `_metacognition_call` → `md_cg/metacognition.py` |
-| 自我状态 | `cg(op=self_state)` | `mcp_server.py:1259` → `_self_state_call` → `md_cg/self_state.py` |
-| 飞轮 / 自愈 | `cg(op=sustain)` | `mcp_server.py:1262` → `_sustain_call` → `md_cg/sustain.py` |
-| 洗脑 / 去污染 | `cg(op=scrub)` | `mcp_server.py:1265` → `_scrub_call` → `md_cg/scrub.py` |
-| 预测 / 因果门 | `cg(op=predict)` | `mcp_server.py:1268` → `_predict_call` → `md_cg/predict.py` |
-| 因果链 | `cg(op=causal)` | `mcp_server.py:1271` → `_causal_call` → `md_cg/chain.py` |
-| **白箱能力库** | `cg(op=whitebox)` | `mcp_server.py:1274` → `_whitebox_call` → `md_cg/whitebox.py`（见 §3） |
-| 代码索引 | `cg(op=index_code)` | `mcp_server.py:1277` → `md_cg/codeindex.py` |
-
-> ⚠️ **插件写入必须走 `mdcg_remember`，不能走 `cg(op=write)`**：
-> `cg(op=write)` 先过 `audit.audit(content_kind)`，未声明 `content_kind` 且未配置
-> `MDCG_POLICY_FILE` 时恒判 BLINDSPOT/DEFER —— 只进审核队列、**永不落盘**。
-> 实测：自动记忆走 `cg(op=write)` 时 0 篇 md 文档；改用 `mdcg_remember(gated=true)`
-> 后 verdict=ACCEPT、md 文档数=1、timeline/read 均命中。
-> `cg(op=write)` 仍保留给「需要审核留痕的显式写入」场景。
-
-## 2. 语义时空基元 `stg`（`mcp_server.py:_stg_call`，入口 L1316）
-
-| 功能 | 显式调用 | 代码位置 |
-| --- | --- | --- |
-| 两节点关系 | `stg(op=relation)` | `mcp_server.py:1320` → `stg.relation` |
-| 时间线 | `stg(op=timeline)` | `mcp_server.py:1322` → `stg.timeline` |
-| 锚点检索 | `stg(op=anchors)` | `mcp_server.py:1326` → `stg.anchors` |
-| 时空一致性 | `stg(op=consistency)` | `mcp_server.py:1329` → `stg.consistency` |
-
-## 3. 白箱能力库（`md_cg/whitebox.py`，AEIS 降为能力库后的唯一入口）
-
-白箱 LLM provider **已下线**（不再注册 `lingshu-whitebox`）；能力改由 md_cg 显式调用并留痕。
-
-| 功能 | 显式调用 | 代码位置 |
-| --- | --- | --- |
-| 统一分发 | `cg(op=whitebox, action=...)` | `mcp_server.py:1274` → `_whitebox_call`（L1306）→ `whitebox.dispatch`（`whitebox.py:387`） |
-| 白箱问答 | `action=ask` | `whitebox.py:322 ask` → `WhiteboxClient.ask`（`whitebox.py:185`）→ 能力库 `wisdom_chat` |
-| 白箱编码 | `action=remember` | `whitebox.py:334 remember` → `WhiteboxClient.remember`（`whitebox.py:194`）→ 能力库 `remember` |
-| **验证编码能力** | `action=verify_encoding` | `whitebox.py:234 verify_encoding`：写入口令→追问命中 |
-| **验证已有知识回答能力** | `action=verify_existing` | `whitebox.py:266 verify_existing`：探针问题 route=self 且非空 |
-| 连通性探测 | `action=ping` | `whitebox.py:300 ping` |
-| 验证报告 | `action=report` | `whitebox.py:366 report`（self 层留痕汇总） |
-| 留痕 | — | `whitebox.py:350 _record` → `cg.add(layer=self, tags=['whitebox:verify'], verification_basis='test')` |
-
-> 细粒度工具别名：`mdcg_whitebox`（`mcp_server.py:1345`）与 `cg(op=whitebox)` 等价。
-> 启动命令可由 `MDCG_WHITEBOX_CMD` / `MDCG_WHITEBOX_ARGS` / `MDCG_WHITEBOX_TIMEOUT` 覆盖（`whitebox.py:61`）。
-
-## 4. 插件侧 LIB 本地库（`src/lib/`）
-
-### 4.1 `mdcg_client.ts` —— 插件调用认知图的唯一显式入口
-
-| 插件方法 | 映射到 | 说明 |
-| --- | --- | --- |
-| `cg(args)` / `stg(args)` | MCP `cg` / `stg` | 逃生口，显式传参 |
-| `route(intent)` | `cg(op=route)` | 意图 → 知识 + 建议能力 |
-| `read(query)` / `get(nodeId)` | `cg(op=read)` | 语义召回 / 按 id 取 |
-| `write(content, extra)` | MCP `mdcg_remember`（gated=false） | 直写 `MdCG.add`；角色 / 转录 / 导入复用 |
-| `remember(content, extra)` | MCP `mdcg_remember`（gated=true, layer=contextual） | 记忆沉淀 + 主动遗忘闸门 |
-| `recall(query, k)` | `cg(op=read, query, k)` | 语义召回；读取记 access log（复用观测） |
-| `verify(nodeId, evidence, verdict)` | `cg(op=verify)` | 外部裁决回填 |
-| `recent(limit)` | `cg(op=recent)` | 近期事件窗口 |
-| `timeline(limit)` | `stg(op=timeline)` | 最近记忆时间线（自动召回注入用） |
-| `identity(subjectId)` | `cg(op=identity)` | 身份维度读取 |
-| `whitebox(action, extra)` | `cg(op=whitebox)` | 白箱能力验证 |
-| `serviceInfo()` | `cg(op=info)` | 服务信息 |
-| `verifyClaim(claim)` | `cg(op=read)` + 依据强度判定 | 互维 memory 通道 |
-| `writeRole(roleId, content)` | `mdcg_remember(layer=knowledge)` | 角色定义落图 |
-| `writeTranscript(roleId, sid, who, text)` | `mdcg_remember(layer=contextual)` | 对话转录落图 |
-
-身份注入：`MDCG_ROOT / MDCG_TENANT / MDCG_CLEARANCE / MDCG_ACTOR / MDCG_IDENTITY`
-（`mdcg_client.ts` 构造器）。**写入还需凭据**：`MDCG_TOKEN`（推荐）或
-`MDCG_LEGACY_ENV_AUTH=1`（兼容旧部署）——**两者都不设即默认状态**：只读 guest
-（读 / 召回 / 时间线可用，写入全失败、不落盘）。
-
-### 4.2 `roleplay_web.ts` —— 角色扮演网页（LIB 本地库）
-
-| 功能 | 显式调用 | 代码位置 |
-| --- | --- | --- |
-| 对话生成 | 能力库 `roleplay_chat` | `roleplay_web.ts:765` |
-| 用户发言落图 | `MdcgClient.writeTranscript(role, cid, 'user', msg)` | `roleplay_web.ts:765` → `mdcg_remember` |
-| 角色回复落图 | `MdcgClient.writeTranscript(role, cid, 'assistant', reply)` | `roleplay_web.ts:784` → `mdcg_remember` |
-| 新建角色 | 能力库 `role_create` + `MdcgClient.writeRole` | `roleplay_web.ts:848` / `851` |
-| 导入记忆/锚点/价值观 | 能力库 `role_import` + `MdcgClient.write`（三导入→knowledge/self/structural） | `roleplay_web.ts:681` / `692` |
-| 落图开关 | `toGraph(label, fn)`（未就绪静默跳过，失败仅告警） | `roleplay_web.ts:451` |
-
-### 4.3 `mutual.ts` —— 互维维护（LIB 本地库）
-
-| 功能 | 显式调用 | 代码位置 |
-| --- | --- | --- |
-| memory 通道核验 | `MdcgClient.verifyClaim`（注入），未就绪回退能力库 `wisdom_verify` | `index.ts:274` |
-| 复核通道 | 能力库 `think`（DeepSeek 独立复核） | `index.ts:296` |
-| 双通道合并裁决 | `combineVerdict` | `mutual.ts:236` |
-| 任务处理 | `processTask` → `whiteboxVerify` + `llmReview` | `mutual.ts:267` |
-| 心跳 / 任务扫描 | `writeHeartbeat` / `scanTasks` | `mutual.ts`（默认导出 L406） |
-
-### 4.4 `whitebox_llm.ts` —— 白箱 LLM 适配器（**已下线，保留为本地库**）
-
-- 不再被 `src/index.ts` 安装 → DSH 设置页无 `lingshu-whitebox` provider。
-- 保留原因：未来成熟后恢复；或作为库复用 `isCardFormat()` 等纯函数。
-- 白箱能力验证改走 §3 的 `cg(op=whitebox)`。
-
-## 5. 数据迁移
-
-| 功能 | 显式命令 | 代码位置 |
-| --- | --- | --- |
-| AEIS（sqlite）→ 认知图 | `python -m md_cg.migrate_aeis --db <sqlite> --root <md_root>` | `md_cg/migrate_aeis.py:migrate` |
-| 角色扮演 + 互维 → 认知图 | `python -m md_cg.migrate_roleplay --data-dir <roleplay_data> --root <md_root> [--mutual-dir <~/.lingxu_net>]` | `md_cg/migrate_roleplay.py:migrate` |
-
-`migrate_roleplay` 的映射：
-
-| 源 | 目标层 | node_id |
-| --- | --- | --- |
-| `roleplay/_roles.json` 角色 | knowledge | `roleplay_role_<id>` |
-| `*_items`（memory / anchors / values） | knowledge / self / structural | `roleplay_<role>_<kind>_<i>` |
-| `transcripts/<role>__<cid>.jsonl` 每轮 | contextual | `roleplay_turn_<role>_<cid>_<idx>` |
-| 互维 `result-<id>.json` / `task-<id>.json` | contextual | `mutual_task_<id>` |
-
-验证：P18 `python -m md_cg.test_p18_whitebox`；P19 `python -m md_cg.test_p19_migrate_roleplay`。
-
-## 6. 配置项 → 生效位置
-
-| 配置 | 默认 | 生效位置 |
-| --- | --- | --- |
-| `mdcg.enabled` | true | `index.ts:189` 是否启动认知图子进程 |
-| `mdcg.root` | `data/mdcg` | `MDCG_ROOT` → `mdcg_client.ts:81` |
-| `mdcg.actor` | `dsh-memory` | `MDCG_ACTOR`；**须与迁移 `--actor` 一致** |
-| `mdcg.tenant` | `default` | `MDCG_TENANT`；**须与迁移 `--tenant` 一致** |
-| `mdcg.clearance` | `private` | `MDCG_CLEARANCE`；决定能读写的密级上限 |
-| `env.MDCG_TOKEN` | **无（写权限默认关闭）** | 认知图写入凭据。签发：`python -m md_cg.tokens issue --role designer --actor dsh-memory --clearance internal --ops-allow … --layers-allow …`（`--ops-allow` / `--layers-allow` 只能收窄，`--role recorder` 为最小权限版） |
-| `env.MDCG_LEGACY_ENV_AUTH` | 无 | 兼容旧部署的 env 直连身份（`recorder`）；与 `MDCG_TOKEN` 都不设 → 只读 `guest` |
-| `env.MDCG_CAN_ADMIN` | 无 | 配合 legacy auth：`'1'` → `designer`（可写 `self` 层，角色 anchors 导入需要） |
-
-**写权限默认关闭**：不配凭据时插件以只读 `guest` 运行——读 / 召回 / 时间线
-照常，写入不落盘（`index.ts` 启动告警）。是否打开由用户决定。三种身份的
-实际覆盖（用 `_probe_token.py` 对真实 MCP 进程实测）：
-
-| 调用点 | `guest`（默认） | `record`（最小权限） | `designer`（收窄版） |
-| --- | --- | --- | --- |
-| `route` / `read` / `recall` / `recent` / `stg(op=timeline)` | ✓ | ✓ | ✓ |
-| `cg(op=whitebox)` | ✓ | ✗ | ✓ |
-| `cg(op=goal)` | ✗ | ✓ | ✓ |
-| `cg(op=identity)` / `cg(op=verify)` | ✗ | ✗ | ✓ |
-| `mdcg_remember` → contextual / knowledge / structural | ✗ | ✓ | ✓ |
-| `mdcg_remember` → self（角色 anchors 导入） | ✗ | ✗ | ✓ |
-| 管理类（`forget` / `restore` / `review_decide`） | ✗ | ✗ | ✗（收窄后不留） |
-| `mutual.enabled` | false | `index.ts:256` 是否启动互维维护 |
-| `MDCG_MCP_SURFACE` | `kernel` | `mcp_server.py`：kernel 仅 `cg`/`stg`，full 另含 29 个细粒度工具 |
-
-## 7. 关键约定
-
-1. **身份绑定加密**：私有内容按 `(tenant, actor)` 派生 DEK；换身份读同一节点 = 「不可读即不存在」。
-   故迁移脚本 `--tenant/--actor` 必须与插件 `config.mdcg.tenant/actor` 一致。
-2. **依据强度**：`verification_basis` 取值限 `compiler | test | measurement | formal_proof | data | other`；
-   互维判定视前五者为「强依据」（`mdcg_client.ts:56`）。
-3. **失败降级**：认知图未就绪时，互维回退能力库 `wisdom_verify`（`index.ts:274`）；
-   角色扮演落图失败仅告警，不阻断对话（`roleplay_web.ts:446`）。
-4. **写权限 fail-closed 且默认关闭**：md_cg 无 `MDCG_TOKEN` / `MDCG_LEGACY_ENV_AUTH=1`
-   时降级为只读 `guest`——`route`/`read`/`recall`/`timeline` 正常（自动召回不受影响），
-   但 `mdcg_remember` 全部 `AccessDenied`、不落盘。**默认即此状态**，打开写权限由用户
-   自行决定；插件不代为注入凭据，只在启动时告警（`index.ts`），避免「看起来在记忆、
-   其实没落盘」。写 `self` 层（角色 anchors 导入）须 `designer`
-   （`MDCG_CAN_ADMIN=1` 或收窄版 designer 令牌）。
-5. **写入通道唯一**：所有插件写入经 `mdcg_remember`；`cg(op=write)` 会走 audit
-   （未声明 `content_kind` 时永不落盘），仅供需要审核留痕的显式调用。
-6. **stdio 一律 UTF-8**：`MdcgClient` 构造子进程时强制 `PYTHONIOENCODING=utf-8`。
-   Windows 下 piped Python 默认 `gbk` + `surrogateescape`，Node 写的 UTF-8 中文会被
-   解成孤立代理字符（`\udcXX`）→ md_cg 落盘/回写 `UnicodeEncodeError`，**中文记忆
-   全部失败**。md_cg 自带测试（`test_p2_mcp.py`）与 `test/bridge.test.ts` 均以该
-   环境变量启动，客户端此前漏设。
-
-## 8. 变更记录
-
-| 日期 | 变更 |
-| --- | --- |
-| 2026-09-10 | md_cg 定为唯一真源；AEIS 降能力库；白箱 provider 下线（保留本地库）+ 新增 `cg(op=whitebox)` 验证通道；roleplay/mutual 迁入 `src/lib` 并改用认知图；新增 `migrate_roleplay.py` 与 P18/P19 测试。 |
-| 2026-09-10 | **写入通道修正**：插件写入由 `cg(op=write)` 改为 MCP `mdcg_remember`（`cg(op=write)` 过 audit，未声明 content_kind 时永不落盘）；自动记忆改用 `mdcg_remember(gated=true)`，实测 ACCEPT + md 落盘 + timeline/read 命中。补写入凭据（`MDCG_TOKEN` / `MDCG_LEGACY_ENV_AUTH`）与启动期告警。 |
-| 2026-09-10 | **stdio 编码修正**：`MdcgClient` 子进程强制 `PYTHONIOENCODING=utf-8`。此前 Windows 下 gbk/surrogateescape 解码导致中文内容 `UnicodeEncodeError`，中文记忆无法落盘（实测真实桥 E2E 复现并修复）。 |
-| 2026-09-10 | **写权限改为「默认关闭 + 令牌化」**：`MDCG_TOKEN` 取代 `MDCG_LEGACY_ENV_AUTH` 成为推荐路径，示例配置一律注释掉（由用户决定是否打开）；`md_cg/tokens.py` 的 `issue` 子命令补齐 `--ops-allow` / `--layers-allow`（对齐 Python API 已有的收窄能力）。三种身份的实际覆盖矩阵见 §6。 |