# 功能调用映射表 v0.1（功能 → 显式代码）

> 目标：**任何一个功能，都能从这份文档查到它调用的是哪段代码**。
> 所有调用都是显式的——没有隐式 provider、没有隐式记忆后端。
>
> 版本：v0.1 · 2026-09-10 · 对应改造：md_cg 唯一真源 / AEIS 降能力库 / 白箱下线 / roleplay+mutual 归 LIB。
>
> **链接纪律**：`md_cg/` 侧三张映射表由 `scripts/cogmap_sync.py` 自动生成（`FUNCMAP` 标记段，
> 行号从真源 AST 提取、`check` 门禁守卫永不过期）；**禁止手写行号锚**（手写必腐化——v0.1 首发
> 版的 60+ 处手写行号在三轮代码重构后全部过期，即为实证）。`src/` 侧为 DSH 插件仓（本仓外），
> 以「文件 + 符号名」定位，跨仓行号不受本仓门禁。

---

## 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`（认知图统一入口，分发实现见 `_cg_dispatch`）

<!-- FUNCMAP:BEGIN id=cg (scripts/cogmap_sync.py 自动生成 · 勿手改段内) -->

**认知基元 `cg` · 36 个 op**（行号由本管线从真源自动提取，`check` 门禁守卫漂移）：

| 功能 | 显式调用 | 代码位置（点击直达源码行） |
|---|---|---|
| 按需披露（投影后完整工具 / 参数文档即时取回） | `cg(op=help)` | [`help`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1914) → [`_help_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1833) |
| 验证态 / 双时间轴 / 履历（含冷路径队列；只读） | `cg(op=status)` | [`status`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1920) → [`_status_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1748) |
| 三元组反查（派生边任意端 / 谓词 / 时间反查；只读） | `cg(op=edges)` | [`edges`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1923) → [`_edges_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1804) |
| 理论检索（领域理论 / 方法论文） | `cg(op=theory)` | [`theory`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1926) → [`theory`](../../md_cg/theory.py) |
| 记忆互链（节点间链接管理） | `cg(op=link)` | [`link`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1943) → [`evidence`](../../md_cg/evidence.py) → [`links`](../../md_cg/links.py) → [`provenance`](../../md_cg/provenance.py) → [`signer`](../../md_cg/signer.py) |
| 服务信息 / 健康 | `cg(op=info)` | [`info`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2052) → [`audit`](../../md_cg/audit.py) → [`links`](../../md_cg/links.py) → [`nodefile`](../../md_cg/nodefile.py) → [`theory`](../../md_cg/theory.py) |
| 路由：意图→知识+建议能力 | `cg(op=route)` | [`route`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2069) |
| 读取（按 id / 召回 / 预算） | `cg(op=read)` | [`read`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2090) → [`refindex`](../../md_cg/refindex.py) |
| 写入（含冲突检测 / 闸门 / 审核） | `cg(op=write)` | [`write`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2124) → [`writepipe`](../../md_cg/writepipe.py) |
| 目标（写入 / 状态 / 清单） | `cg(op=goal)` | [`goal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2132) |
| 任务实体（登记 / 计划 / 状态 / 结果；done 无结果拒收） | `cg(op=task)` | [`task`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2151) → [`_task_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1846) |
| 最近记忆（事件窗口） | `cg(op=recent)` | [`recent`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2154) |
| 外部裁决回填（节点证据验证） | `cg(op=verify)` | [`verify`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2166) |
| 审核队列（DEFER / 提案裁决） | `cg(op=review)` | [`review`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2170) |
| 主动遗忘 / 恢复 | `cg(op=forget)` | [`forget`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2190) |
| 保护（不可遗忘） | `cg(op=protect)` | [`protect`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2196) → [`_protect_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1089) |
| 身份维度 | `cg(op=identity)` | [`identity`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2199) → [`_identity_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1117) |
| 一致性检测 | `cg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2202) → [`_consistency_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1168) |
| 元认知（盲区聚合） | `cg(op=metacognition)` | [`metacognition`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2205) → [`_metacognition_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1197) |
| 自我状态 | `cg(op=self_state)` | [`self_state`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2208) → [`_self_state_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1232) |
| 演化（记忆结构演化） | `cg(op=evolution)` | [`evolution`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2211) → [`_evolution_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1367) |
| 飞轮 / 自愈 | `cg(op=sustain)` | [`sustain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2214) → [`_sustain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1459) |
| 洗脑 / 去污染 | `cg(op=scrub)` | [`scrub`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2217) → [`_scrub_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1568) |
| 预测 / 因果门 | `cg(op=predict)` | [`predict`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2220) → [`_predict_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1294) |
| 因果链 | `cg(op=causal)` | [`causal`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2223) → [`_causal_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L1328) |
| 白箱能力库（AEIS 能力显式调用） | `cg(op=whitebox)` | [`whitebox`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2226) → [`_whitebox_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2835) |
| 代码索引 | `cg(op=index_code)` | [`index_code`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2229) → [`refindex`](../../md_cg/refindex.py) |
| 文档索引 | `cg(op=index_doc)` | [`index_doc`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2261) → [`refindex`](../../md_cg/refindex.py) |
| 引用 / 反向引用 | `cg(op=ref)` | [`ref`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2297) → [`_ref_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2766) |
| 会话管理（多会话归属与过滤） | `cg(op=session)` | [`session`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2300) → [`_session_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2496) |
| 导入落图 | `cg(op=ingest)` | [`ingest`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2303) → [`_ingest_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2573) |
| 导出 | `cg(op=export)` | [`export`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2306) → [`_export_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2594) |
| 维护 | `cg(op=maintain)` | [`maintain`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2309) → [`_maintain_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2613) |
| 记忆固化 / 整理 | `cg(op=consolidate)` | [`consolidate`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2312) → [`_consolidate_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2691) |
| 洞察 / 自主探索（信息差驱动） | `cg(op=insight)` | [`insight`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2315) → [`_insight_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2716) |
| CCG 六要素编译（对话→候选→编外复核→落库） | `cg(op=ccg)` | [`ccg`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2318) → [`_ccg_call`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2325) |

<!-- FUNCMAP:END -->

> ⚠️ **插件写入必须走 `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`（语义时空图入口）

<!-- FUNCMAP:BEGIN id=stg (scripts/cogmap_sync.py 自动生成 · 勿手改段内) -->

**语义时空基元 `stg` · 4 个 op**：

| 功能 | 显式调用 | 代码位置（点击直达源码行） |
|---|---|---|
| 两节点关系 | `stg(op=relation)` | [`relation`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2858) |
| 时间线 | `stg(op=timeline)` | [`timeline`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2860) |
| 锚点检索（时空窗口） | `stg(op=anchors)` | [`anchors`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2864) |
| 时空一致性 | `stg(op=consistency)` | [`consistency`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L2868) |

<!-- FUNCMAP:END -->

## 3. 白箱能力库（`md_cg/whitebox.py`，AEIS 降为能力库后的唯一入口）

白箱 LLM provider **已下线**（不再注册 `lingshu-whitebox`）；能力改由 md_cg 显式调用并留痕。

<!-- FUNCMAP:BEGIN id=wb (scripts/cogmap_sync.py 自动生成 · 勿手改段内) -->

**白箱能力库 `whitebox`（AEIS 能力库唯一显式入口）· action 分发**：

| 功能 | 显式调用 | 代码位置（点击直达源码行） |
|---|---|---|
| 白箱问答 | `cg(op=whitebox, action=ask)` | [`ask`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L505) → [`whitebox.ask`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L432) |
| 白箱编码（知识写入能力库） | `cg(op=whitebox, action=remember)` | [`remember`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L508) → [`whitebox.remember`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L445) |
| 验证编码能力（写入口令→追问命中） | `cg(op=whitebox, action=verify_encoding)` | [`verify_encoding`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L512) → [`whitebox.verify_encoding`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L341) |
| 验证已有知识回答能力（探针 route=self） | `cg(op=whitebox, action=verify_existing)` | [`verify_existing`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L516) → [`whitebox.verify_existing`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L374) |
| 验证报告（self 层留痕汇总） | `cg(op=whitebox, action=report)` | [`report`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L520) → [`whitebox.report`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L479) |
| 连通性探测 | `cg(op=whitebox, action=ping)` | [`ping`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/mcp_server.py#L522) → [`whitebox.ping`](https://github.com/FuRongJun-1999/dsh-memory/blob/main/md_cg/whitebox.py#L409) |

<!-- FUNCMAP:END -->

调用链（`mcp_server.py` 的 `_whitebox_call` → `whitebox.py` 的 `dispatch`）：统一分发
`cg(op=whitebox, action=...)`；能力调用最终经 `WhiteboxClient`（子进程 / 本地引擎）到达
能力库（`wisdom_chat` / `remember`）；验证结果经 `_record` 以
`layer=self, tags=['whitebox:verify'], verification_basis='test'` 留痕。

> 细粒度工具别名：`mdcg_whitebox` 与 `cg(op=whitebox)` 等价。
> 启动命令可由 `MDCG_WHITEBOX_CMD` / `MDCG_WHITEBOX_ARGS` / `MDCG_WHITEBOX_TIMEOUT` 覆盖
> （`whitebox.py` 的 `_launch_cmd`）。

## 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` |
| 用户发言落图 | `MdcgClient.writeTranscript(role, cid, 'user', msg)` | `roleplay_web.ts` → `mdcg_remember` |
| 角色回复落图 | `MdcgClient.writeTranscript(role, cid, 'assistant', reply)` | `roleplay_web.ts` → `mdcg_remember` |
| 新建角色 | 能力库 `role_create` + `MdcgClient.writeRole` | `roleplay_web.ts` |
| 导入记忆/锚点/价值观 | 能力库 `role_import` + `MdcgClient.write`（三导入→knowledge/self/structural） | `roleplay_web.ts` |
| 落图开关 | `toGraph(label, fn)`（未就绪静默跳过，失败仅告警） | `roleplay_web.ts` |

### 4.3 `mutual.ts` —— 互维维护（LIB 本地库）

| 功能 | 显式调用 | 代码位置 |
| --- | --- | --- |
| memory 通道核验 | `MdcgClient.verifyClaim`（注入），未就绪回退能力库 `wisdom_verify` | `index.ts` |
| 复核通道 | 能力库 `think`（DeepSeek 独立复核） | `index.ts` |
| 双通道合并裁决 | `combineVerdict` | `mutual.ts` |
| 任务处理 | `processTask` → `whiteboxVerify` + `llmReview` | `mutual.ts` |
| 心跳 / 任务扫描 | `writeHeartbeat` / `scanTasks` | `mutual.ts`（默认导出） |

### 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](../../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](../../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` 是否启动认知图子进程 |
| `mdcg.root` | `data/mdcg` | `MDCG_ROOT` → `mdcg_client.ts` 构造器 |
| `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` 是否启动互维维护 |
| `MDCG_MCP_SURFACE` | `kernel` | `mcp_server.py`：kernel 仅 `cg`/`stg`，full 另含全部 `mdcg_*` 细粒度工具（数量以 README「工具面」认知图段为准） |

## 7. 关键约定

1. **身份绑定加密**：私有内容按 `(tenant, actor)` 派生 DEK；换身份读同一节点 = 「不可读即不存在」。
   故迁移脚本 `--tenant/--actor` 必须与插件 `config.mdcg.tenant/actor` 一致。
2. **依据强度**：`verification_basis` 取值限 `compiler | test | measurement | formal_proof | data | other`；
   互维判定视前五者为「强依据」（`mdcg_client.ts` 的 `MDCG_STRONG_EVIDENCE` 常量）。
3. **失败降级**：认知图未就绪时，互维回退能力库 `wisdom_verify`（`index.ts`）；
   角色扮演落图失败仅告警，不阻断对话（`roleplay_web.ts`）。
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。 |