@furongjun1999/dsh-memory 0.4.7 → 0.4.8

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。 |