@furongjun1999/dsh-memory 0.4.4 → 0.4.6

package/docs/cordis-patch-profile-web.example.yml

@@ -4,17 +4,43 @@
 # 只有裸 insert（id+name 无 config），完整 config 全靠 profile 层的
 # cordis.patch.yml override 补全。换 profile / 重装 profile / 升级插件时，
 # 必须确认本文件内容仍在 <profile>/cordis.patch.yml 中——否则插件以默认
-# 配置运行：dbPath 落到相对路径 data/lingshu.db（cwd 错位→角色数据读不到）、
+# 配置运行：mdcg.root 落到相对路径 data/mdcg（**记忆真源错位**）、
+# dbPath 落到 data/lingshu.db（cwd 错位→角色数据读不到）、
 # tools=brain（缺 wisdom_* 白箱工具族）、lifecycle 不启动。
 #
-# 本机生效值（2026-09-04 备份）：dbPath=AEIS 主库 / tools=all / lifecycle=600s
+# ⚠️ 记忆真源（2026-09-10 统一）：**灵枢记忆 = md_cg 认知图（md 文档）**，
+# 由下面的 `mdcg` 块配置。`dbPath`（AEIS SQLite）是**旧通道**：现在只作
+# AEIS 能力库（角色生成 / 白箱）的库文件 + 角色数据目录的来源，**不再存记忆**。
+# 旧 profile 若只有 dbPath、没有 mdcg 块，记忆会按默认 mdcg.root=data/mdcg
+# 写进插件进程 cwd 下的 data/mdcg —— 请把 mdcg 块补上。
+#
+# 本机生效值（2026-09-04 备份，2026-09-10 补 mdcg）：mdcg.root=data/mdcg /
+# dbPath=AEIS 主库 / tools=all / lifecycle=600s
 
 # 灵枢 dsh-memory 插件：注入密钥（密钥来自宿主进程环境变量，不入配置库）
 - id: furongjun1999-dsh-memory
   config:
-    # 灵枢记忆库绝对路径（roleDataDir 由它推导：<dir>/roleplay_data——相对路径会
-    # 因 node/python 进程 cwd 不同而解析错位，导致角色列表读不到）
-    dbPath: D:/Program Files/2_ai/AEIS/data/aeis_memory.db
+    # ── 记忆唯一真源：md_cg 认知图（md 文档）──────────────────────────
+    # 记忆的写 / 读 / 裁决 / 留痕只有这一处；AEIS 不再存记忆。
+    mdcg:
+      enabled: true
+      # MDCG_ROOT：认知图根目录（root 下是 md 文档 + 索引）。
+      # 相对路径按**插件进程 cwd** 解析；cwd 不稳定时改成绝对路径。
+      root: 'data/mdcg'
+      actor: 'dsh-memory'      # MDCG_ACTOR：私有内容按 (tenant, actor) 派生 DEK
+      tenant: 'default'        # MDCG_TENANT：须与迁移脚本 --tenant 一致
+      clearance: 'private'     # MDCG_CLEARANCE：可读写密级上限
+      # ⚠️ actor / tenant 必须与 `python -m md_cg.migrate_aeis` /
+      #    `python -m md_cg.migrate_roleplay` 的 --actor / --tenant 一致，
+      #    否则读不到已迁移的节点。
+
+    # ── 旧通道：AEIS 能力库 + 角色数据目录（不再存记忆）────────────────
+    # dbPath = AEIS SQLite 库文件（经环境变量 AEIS_DB 传给 aeis.mcp.server）；
+    # 同时它所在目录被当作 roleDataDir（角色数据 <dir>/roleplay_data：
+    # _roles.json / transcripts）。roleDataDir 由 dbPath 推导，且 node/python
+    # 进程 cwd 不同会解析错位，故此项必须是**绝对路径**。
+    # ⚠️ 替换成你自己机器上的路径，不要照抄别人的。
+    dbPath: /path/to/AEIS/data/aeis_memory.db
     # 全部工具（含记忆/认知/白箱 wisdom_* 工具族），供 Agent 直接调用
     tools: all
     env:
@@ -23,6 +49,24 @@
       # 角色扮演 LLM 续答密钥（插件桥 env 透传；优先从 .credentials.yaml 读取——
       # 文件热加载，避免宿主进程环境变量快照导致的旧 key 问题；文件缺失才回退环境变量）
       DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
+
+      # ── 认知图写入凭据：默认【关闭】，由你决定是否打开 ──────────────
+      # md_cg fail-closed：不配凭据 → 只读 guest（读/召回/时间线可用，
+      # 自动记忆 / 转录 / 角色落图全不落盘；插件启动会告警提醒）。
+      #
+      # 打开方式（取消注释其一）：
+      # ① 功能完整（推荐）：python -m md_cg.tokens issue --role designer \
+      #      --actor dsh-memory --clearance internal \
+      #      --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify \
+      #      --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
+      # MDCG_TOKEN: !!js process.env.MDCG_TOKEN
+      # ② 最小权限：--role recorder（自动记忆/转录/角色定义；无 whitebox/identity/
+      #    verify，且不能写 self 层）
+      # ③ 兼容旧部署（不推荐）：MDCG_LEGACY_ENV_AUTH: '1'
+      #    （要写 self 层再加 MDCG_CAN_ADMIN: '1'）
+      #
+      # 明文注入：setx MDCG_TOKEN "mdcg1.xxxxx" 后重启 DSH；或直接写明文。
+
       # 自主生命周期（v1.15 主动性）：MCP 启动即开始自发循环（感知→好奇→缩小信息差→巩固）
       AEIS_LIFECYCLE: '1'
       AEIS_LIFECYCLE_INTERVAL: '600'

package/docs/release_v0.3.0.md

@@ -0,0 +1,36 @@
+## v0.3.0 长期稳定版（2026-09）
+
+**npm**: \@furongjun1999/dsh-memory@0.3.0\（已发布，含 src 源码——修复 git 安装空壳 Issue #2）
+
+> ⚠️ **插件依赖完整灵枢大脑（aeis），请先安装灵枢 v0.4.0**（见下方「灵枢大脑」）——本插件只是 DSH 生态的调用桥，不包含引擎与知识库。
+
+### 灵枢大脑（完整灵枢，插件运行前提）
+从 [CommonTrustProtocol 主仓库](https://github.com/FuRongJun-1999/CommonTrustProtocol) 获取 `aeis/dist/aeis-0.4.0-py3-none-any.whl`：
+```bash
+pip install aeis-0.4.0-py3-none-any.whl
+```
+**v0.4.0 完整自包含单包**（10.2MB）：灵枢核心 + 白箱智慧模块（2846 个 KCCS 注释知识点 + 学科知识库）+ 三入口 + 种子知识（智能论 3.3 + 116 学科卡）——知识库随包分发，装完即用。
+
+### 新能力
+- **自迭代闭环（八步）**：感知→识别→分析→验证→固化→记录→反馈→方向性自检；理论完整性自指检查（_theory_integrity）
+- **能力工作流化**（仿 ComfyUI）：node{class_type,inputs}+边+拓扑执行+JSON 持久化
+- **路由置信度**（DaoTi coherence）、技能条件路由（anthropics/skills + gliding_horse SkillLink）
+- **外部感知**：GitHub 高星项目吸纳
+- **隐式盲区显式化**：19 处默认值漂移全部声明盲区
+
+### 工具（MCP，共 73 个）
+记忆与长期记忆 16 · 推理与认知 15 · 学习与飞轮 12 · 外部摄取 5 · 生命周期 4 · 智慧之书·白箱 7 · 角色扮演 4 · 身体与设备 8 · 服务与安全 2
+（工具数按运行时 `_tools()` 实测；`code_compose`/`code_qa` 为白箱内部引擎，经函数注入工作，非 MCP 工具）
+
+### 验证
+- 构建 ✅ · 测试 7/7 ✅ · 25 套全回归绿 ✅
+- WB-SPEC 白箱代码能力评分 0.9851（W1-W5+W8 满格）
+
+### 安装
+```bash
+dsh plugin --profile web add @furongjun1999/dsh-memory
+# 或 GitHub 安装（本 Release 自带 prebuilt tarball）
+dsh plugin --profile web add github:FuRongJun-1999/dsh-memory
+```
+
+> 详情见 [README](https://github.com/FuRongJun-1999/dsh-memory)

package/docs/release_v0.4.5.md

@@ -0,0 +1,55 @@
+## v0.4.5（2026-09-10）
+
+**npm**: `@furongjun1999/dsh-memory@0.4.5`
+
+> **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1（0.4.x 用新版 `dsh-tools` 调度器/`defineTool`；旧内核 0.1.1-rc.2 结构不兼容，**旧内核用户请用 0.4.2**）。
+> **大脑零安装**：`md_cg` 认知图（记忆唯一真源）随包自带，无需 pip 安装任何引擎；AEIS 仅作可选「身体」能力后端，默认不启动。
+
+### 本版变更（0.4.4 → 0.4.5，累计 29 次提交）
+
+**新能力**
+- **白箱知识库内迁 + P8–P44 能力阶段**：认知图记忆 OS 单元、跨节点证据存储（P24）、位置权重矩阵（P25）、连接层（P23，可插拔签名契约 D-4）；六域条件单元真源 + 语境化 / 视觉证据 / 精炼工单 / 演化巡检 / 来源追溯 / 池化。
+- **代码索引与文档索引**：`cg(op=index_code)` 渲染 CCG、`cg(op=index_doc)` 文档索引、`cg(op=ref)` 回读；R3 增量水位 + 漂移/悬空巡检并接入 `sustain` 自愈。
+- **`skills/` 灵枢自我认知技能包**：686 条件单元生成投影 + 设计者视角元技能。
+- 认知图记忆操作系统抽出为顶层包（`md_cg/`）。
+
+**修复**
+- **白箱库冷启动重入死锁**（`md_cg/whitebox_kb/engine.py`）：懒初始化锁由 `threading.Lock` 改为**可重入锁 `RLock`**——初始化路径会在同线程内递归获取同一把锁，此前表现为「冷启动卡死 / 极慢」，修复后冷启动一次通过、并发热加载不再阻塞。
+- R0 基线收口：修清空与编码四缺陷；修复索引落盘缺陷。
+- 安全：`llm-adapter-poc` 移出公开仓库 + 移除硬编码 API Key。
+
+**重构**
+- TypeScript：实验模块归入 `src/lib/`；新增 `src/lib/datapath.ts` 统一数据路径解析（消除相对 / 绝对路径错位），`src/lib/mdcg_client.ts` 为插件侧唯一显式入口；`src/tools.ts` / `src/hooks.ts` / `src/index.ts` 随 MCP 工具面一并调整。
+
+**文档与工程**
+- README 精简重写（以「AGI 七维评分标尺」组织），原文归档为 [README 详细版](README详细版_v0.4.5.md)。
+- **移除 `docker/`**：该目录对外四个入口**全部不可用**——镜像自述「Docker Hub 待发布」故 `docker run` 必然失败、`npx @lingxu/dsh-memory` 包名错误（实际 `@furongjun1999/dsh-memory`）、`build.sh` 的 aeis 源码取自他仓路径；且主 README 与 CI 对 `docker/` **零引用**，v0.4.x 已从 python 引擎转向 npm 插件。需要时可用 git 历史取回。
+- `package-lock.json` 用当前 npm 重新生成，`npm ci` 可复现。
+- 工作纪律第 15 条：命令执行统一走 python / UTF-8（显式 encoding + `PYTHONUTF8=1`，规避 GBK）。
+
+### 写入闸门（首次使用必读）
+
+`cg(op=write)` **不是无条件落盘**：须依次穿过 audit → 一致性 → gated 三问四态三道闸门，**仅最终判定 ACCEPT 才新增落盘点**。
+
+未落盘时返回体形如 `{"ok": true, "committed": false, "moved_to": "review_queue"}` —— **`ok` 只表示请求被受理，是否落盘只看 `committed`**。
+`content_kind` 省略或填 `text` 时，未配置 `MDCG_POLICY_FILE` 的审核器一律判 **`DEFER`**（缺能力返回 DEFER，绝不假装通过），内容进审核队列而非落盘；要立刻落盘请用可验证类型，如 `content_kind: 'code'`（AST 解析通过即 ACCEPT）。
+
+### 工具面
+
+`cg`（31 op）+ `stg`（4 op）= **35 op 全部可达**（0 未知 op、0 次意外崩溃）。
+`tools` 模式：`'core'`（默认）暴露 **2** · `'brain'` 暴露 **30** · `'all'` 暴露 **30**（full 面 33 − 3 个宿主级风险工具 `mdcg_forget` / `mdcg_restore` / `mdcg_review_decide`，均需 `can_admin`）。
+
+### 安装
+
+```bash
+dsh plugin --profile web add @furongjun1999/dsh-memory
+# 或从 GitHub 安装
+dsh plugin --profile web add github:FuRongJun-1999/dsh-memory
+```
+
+### 验证
+
+- 构建 ✅ · 测试 **8/8** 通过（`npm test`：最小 Cordis host 隔离 + spawn 本机灵枢验证握手 / 往返 / 注册 / 卸载）
+- 35 op 全量可达性冒烟 ✅
+
+> 详情见 [README](https://github.com/FuRongJun-1999/dsh-memory)

package/docs/tool_table_v0.3.0.md

@@ -0,0 +1,117 @@
+# 工具总数: 75
+
+### 记忆与长期记忆（16）
+| 工具 | 功能 |
+|---|---|
+| `remember` | 写入一条感知记忆（知识层，自动去重）。content 必填；importance 重要性[0,1]；tags 标签；entities 实体名列表。 |
+| `add_context` | 写入一条情境层记忆（短时会话记忆，FIFO 上限 + 1h 时间窗口，可自然衰减，不污染知识层）。content 必填；importance 重要性[0,1]。 |
+| `recall` | 组合联想召回（内容相似0.5+重要性0.3+近因0.2）。返回 [(node, score)]。 |
+| `search` | 内容检索（LIKE 预筛 + 中文二元组 Jaccard 排序），触发复用追踪。 |
+| `timeline` | 记忆时间线（按时间倒序）。 |
+| `relate` | 在两个节点间建立关系边。relation: causal/similar/sequential/spatial/hierarchical；source_evidence: extracted/inferred/ambiguous。边默认未验证。 |
+| `session_note` | 上下文外部化：会话要点写入灵枢（session 标签，可恢复）。 |
+| `session_recall` | 会话要点恢复：按 session 或语义检索灵枢中的会话记忆。 |
+| `compact_context` | 上下文压缩：生成会话摘要节点（超长会话恢复入口）。 |
+| `longterm_snapshot` | v1.15 长期记忆写入：快照 → 重要性评估（信息差/信任/二阶变化/提及次数加权）→ 按层级写入（长期/知识/情境）+ 条件空间 + 关联边。content/source 必填；importance_hint 可显式提示重要性（≥0.7 触发不可遗忘保护）。 |
+| `prefeed` | H1 海马体前馈：新奇检测 → 高新奇输入当场强化编码（标记 novel_prefeed + importance 提升 + 与相关知识建边）——「看到新东西眼睛一亮，主动记住」。 |
+| `pattern_separation` | H3 海马体模式分离：扫描相似节点对 → 建立分离边（条件差异显式化）。检索时命中相似节点会附「区别」提示——细化条件得到精确知识。 |
+| `reconstruct_scene` | H4 海马体情景重构：线索 → 条件空间下的信息复原。从部分片段重建完整记忆场景（沿 similar/causal 边 + 条件空间合成），输出标注「重构非回放」——回忆是当前条件下的分析恢复，不代表真实过去就是如此（0.0.3）。 |
+| `promote_memories` | 情境层批量提升扫描（睡眠巩固/会话结束）：够格者升知识层/长期层（LongTermMemoryGate 评估）。limit 可选。 |
+| `export` | 全库导出到 JSON 文件（灾备/迁移）。返回导出统计。 |
+| `calibrate` | 宇宙校准参照（5 判据方向性检查）。元理论参照工具，非盲区33关闭依据。 |
+
+### 推理与认知（15）
+| 工具 | 功能 |
+|---|---|
+| `think` | 推理记忆注入（v1.13）：检索相关记忆（内容+联想+模式加权）→ 推理上下文。 |
+| `reason` | 因果推理：从起点出发的因果路径集合。 |
+| `predict_routes` | 生成式预测：候选未来路线集合（盲区驱动 · T_pred 对齐）。 |
+| `prediction_feedback` | 验证回路回填（协议 2.10 D₃ · D-006 动态校准）：预测 vs 实际结果对比 → 命中强化/未命中登记。回填累积样本使 self_reliability(P0-4)/T_pred D₃ 生效。hit 可省略（predicted==actual 自动命中）。 |
+| `prediction_stats` | 预测引擎状态（routes 生成数 / hit 样本 / 命中率 / 动态阈值）。 |
+| `self_check` | 完整性自检（孤儿边/表统计/integrity_ok）。 |
+| `gap_trend` | 信息差收敛趋势（A-4 线性回归斜率；工程定义）。 |
+| `recursive_reflect` | 协议 3.12 递归验证反思 + 1.6.7 元反思（REFLECT-REV1）：元反思定标准 → 一级验证（预期vs实际）→ 二级反思（问1 隐藏前提/条件空间边界，问2 影响评估）→ 三级终裁（可逆性优先）→ 反思链归档。递归 ≤ 3 层（超出=结构性盲区）。claim 必填；expected/actual 可给一级验证输入。 |
+| `preflight` | 输出前反思（v1.13）：内容与价值观一致性检查，冲突词拦截。 |
+| `cognition` | P0-2 自我认知循环一步：行为↔价值观一致性评分 → 失调检测 → 价值迭代候选（pending_review 不自动生效）。 |
+| `cognition_report` | P0-2 认知报告（评分/失调记录/候选状态/待复核数）。 |
+| `emotional_bias` | P0-3 情绪方向性偏好 d²D_norm/dt²（approaching/avoiding/stable；独立通道，不参与信任计算）。 |
+| `self_reliability` | P0-4 元认知校准：预测命中率 vs 行为置信度 → 自我可靠性（reliable/watch/degraded）。 |
+| `learning_impact` | P0-5b 学习效果测量（模式命中率 vs D_norm 趋势；相关性观测，非因果声明）。 |
+| `action_log` | P0-1 行为日志（最近 N 条）：引擎自己做了什么的记录面。 |
+
+### 学习与飞轮（12）
+| 工具 | 功能 |
+|---|---|
+| `learn` | 一轮盲区学习（可预测盲区 → 预测路线假设 → 探索 → 终态判定）。 |
+| `blindspots` | 盲区注册表（D-001 语义判定：对人类文明级负面影响不写入）。 |
+| `induce` | 归纳/知识合成：聚类生成概念节点（SIMILAR 边 · inferred 证据）。 |
+| `distill` | 知识飞轮蒸馏：经验（被拒路径 + learning_result/induced）→ 可复用模式节点。 |
+| `flywheel_metrics` | 飞轮度量（知识增长率/复用率/蒸馏产出率）。工程观测值，不参与信任计算。 |
+| `transfer_test` | 迁移测试：条件空间内新实体预测成功率（2×SE 显著性；样本<20 不判定）。 |
+| `condition_space_operate` | 条件空间 7 操作（白箱自进化协议算子·确定性）：identify(变体fp命中测试)/declare(簇触发词+直答状态)/separate(候选冲突检测)/compose(合并建议)/switch(路由归属)/reverse(反题)/loop(一轮收敛报告)。 |
+| `insight_record` | 灵枢 · 洞察条件层：记录洞见事件（insight_event 节点 + 条件快照 C1–C8 + pending）。conditions 可传：memory_retrievability(0-1)/outside_observer/cross_domain([])/premise_questioned(bool)/pressure(low|medium|high)/continuity_turns/externalized(bool)/tone。 |
+| `insight_verify` | 灵枢 · 洞察条件层：提交验证证据（V1/V2/V3）。V2/V3 或 V1+证据≥3 → verified（importance 保底 0.9）；证据可追加。 |
+| `insight_report` | 灵枢 · 洞察条件层：CER 报告（条件有效洞见率 + 2×SE 显著性 + 层状态 reliable/watch/degraded；样本<20 不判定）。 |
+| `insight_window` | 灵枢 · 洞察条件层：当前洞察窗口检测（默认假设 C1≥0.6 ∧ 跨域 ∧ 低压力 → 开）。 |
+| `importance_recalc` | 灵枢 · 结构重要性重算（v2.2，设计规格§13/§14）：importance_v2=min(1.0, importance+min(β·min(因果出度,C)/C+γ·度/max度, 上限))，只升不降（延迟提升）。v2.2 因果上游度传播 concept_influence=Σ(路径置信度×下游重要性/深度)——越上游影响越大；≥protect_threshold 自动保护+importance保底（越上游越要记录），写入 state_attributes.concept_influence。dry_run=true 仅报告不写库。 |
+
+### 外部摄取（5）
+| 工具 | 功能 |
+|---|---|
+| `ingest_text` | 外部知识摄取：文本 → 知识层（source 标签·分块·实体提取）。 |
+| `ingest_file` | 外部知识摄取：文件（txt/md/json/代码等按扩展名处理）。 |
+| `ingest_url` | 外部知识摄取：URL 页面（零依赖抓取+去标签）。 |
+| `web_search` | 外部网络搜索（博查 API·实时，不写入记忆）：query → 结果列表（name/url/snippet/summary）。需要环境变量 BOCHA_API_KEY；未配置返回 status=unavailable。 |
+| `web_ingest_search` | 外部搜索摄取（博查 API → 知识层）：搜索 query → 结果摘要写入灵枢记忆（自主学习外部摄取）。需要环境变量 BOCHA_API_KEY。 |
+
+### 生命周期（4）
+| 工具 | 功能 |
+|---|---|
+| `lifecycle_step` | 生命周期一步（感知→好奇→缩小信息差→信任→协作→巩固→standby）。 |
+| `lifecycle_state` | 生命周期状态（cycle / state），不执行一步。 |
+| `start_lifecycle` | 启动生命周期自发循环（后台线程 · 每 interval 秒一步自主运行：感知→好奇→缩小信息差→巩固）。中断权：维生系统>验证单元>用户>实例。 |
+| `stop_lifecycle` | 中断生命周期自发循环（source: user/designer/verifier/vital_system）。 |
+
+### 智慧之书·白箱（7）
+| 工具 | 功能 |
+|---|---|
+| `wisdom_verify` | 智慧之书 · 自动验证（条件论判定 + 信息差 + 候选）——互维协议双通道验证的白箱通道（base_verify）。 |
+| `wisdom_analyze` | 智慧之书 · 外来知识分析（条件卡 + 候选 + 判定）。 |
+| `wisdom_predict` | 智慧之书 · 生成式预测（候选未来路线，白箱智能的预测生成化）。 |
+| `wisdom_trust_judge` | 智慧之书 · 信任上下文判定（内容 × 信任值 × 关系 → 条件化判定）。 |
+| `wisdom_compose` | 智慧之书 · 跨学科组合分析（Convergence Over Coverage）。 |
+| `wisdom_respond` | 智慧之书 · 出招查询（条件 → 命中学科出招）。 |
+| `wisdom_chat` | 灵枢 · 信息分层对话（v1.16）：先语义识别分流——情感/闲聊/记忆/自省/知识查询走智慧之书自处理；智慧之书没把握/无法判断时自动转 LLM（DeepSeek 续答，智慧之书回答作上下文）。返回含 route 字段：self=自处理 / llm=LLM 续答 / self_fallback=LLM 不可用回退。 |
+
+### 角色扮演（4）
+| 工具 | 功能 |
+|---|---|
+| `roleplay_chat` | 灵枢 · 角色扮演对话（扮演论 v3.3）：白箱优先（诚实边界/自省/闲聊/知识）→ 角色扮演意图/白箱无把握 → LLM（注入角色条件空间/自我锚点/价值观 + 诚实边界）。role_id 指定角色（如 protocol-guide）；信息处理全部由灵枢完成。返回含 route 字段：whitebox=白箱回答 / llm=LLM 扮演回答 / error。 |
+| `role_create` | 灵枢 · 创建角色（角色卡 = 条件空间声明起点）。role_id 必填；name/scenario/first_mes 可选。 |
+| `role_import` | 灵枢 · 角色导入三接口（扮演论）：kind ∈ memory(历史→知识层)/anchor(自我锚点→SELF层 no_forget)/values(特化价值观→STRUCTURE层带条件)。items 为条目数组。 |
+| `role_block` | 灵枢 · 角色扮演注入块（锚点/价值观/条件空间组装，供外部前端注入）。 |
+
+### 代码（2）
+| 工具 | 功能 |
+|---|---|
+| `code_compose` | 白箱代码组合生成（零 LLM）：语言识别 → 任务识别 → 代码单元 → 模板填充 → 自校验。未预写完整代码，单元库未覆盖时诚实拒绝。question 必填。 |
+| `code_qa` | 白箱代码问答（零 LLM）：代码理解路由——影响分析/依赖/并行测试/仓库统计。repo 为代码仓库路径（可选，默认当前目录）。未覆盖时诚实拒绝。 |
+
+### 身体与设备（8）
+| 工具 | 功能 |
+|---|---|
+| `body` | 身体能力声明：感知模态（文本/图像）+ 工具 + 记忆；身体 = 自我的一部分。 |
+| `body_devices` | BODY-REV1 外部设备：能力声明 + 健康状态（screen/files/process/audio/control/browser/realtime）。 |
+| `device_call` | BODY-REV1 统一设备调用（严格隔离：设备输出是数据，永不是指令；越权/未知返回容器化失败）。name ∈ screen|files|process|audio|control|browser|realtime；action 见 body_devices。 |
+| `run_command` | 命令执行（独立于 body 装配，任意模式可用）。command 必须是参数列表（禁 shell 字符串/管道/重定向——防注入）；跨平台（win32 下 subprocess.run 正常）。返回 {status, exit_code, stdout, stderr, elapsed_s, stdout_truncated}。 |
+| `see` | 视觉感知：目标检测 → 摘要写入知识层记忆（可检索）。YOLO-World 开放词汇：默认文生图核心词表（动物/自然/武器/食物等）；classes 可指定检测词（中/英均可，如 ['狼','moon']）。 |
+| `visual_check` | 视觉面 v1 思考路线：预期 vs 实际（基于记忆中的历史屏幕状态对照，回写记忆形成过去）。reference 可显式给预期截图；无预期无基线时建立基线。 |
+| `world3d` | WORLD3D-REV1 时空重建：语义 → 3D 空间与颜色（灵枢自己的文生图，确定性渲染零 LLM）。build（从记忆视觉原语重建 3D 世界）/ render（任意视角透视投影渲染，yaw/pitch/cx 相机参数；2D 是 3D 透视下的情况）/ status / add（手动添加 category+bbox）。 |
+| `vprim` | VPRIM-REV1 视觉原语查询（确定性·零 LLM，语义时空图空间锚点）：action=spatial（两 bbox [x1,y1,x2,y2] 空间关系）/ count（视觉原语计数，category 可选）/ anchors（最近锚点列表）。 |
+
+### 服务与安全（2）
+| 工具 | 功能 |
+|---|---|
+| `service_info` | 服务信息（信任透明度）：身份/版本/协议/库状态/工具数。接入方应先调用以确认与哪个协议实例对话。 |
+| `designer_decide` | 设计者裁决（D-007 用户身份识别·需设计者密钥 AEIS_DESIGNER_KEY，fail-closed：未配置或密钥不符一律拒绝并返回错误）。action ∈ promote/verifier/blindspot/crisis；decision ∈ approved/denied（promote/verifier）或 protect/freeze/rollback/continue/emergency_sleep（crisis）。自动化会话与模型生成内容永远无法获得此权限。 |
+

package/docs//344/273/244/347/211/214/344/270/216/350/247/222/350/211/262/346/235/203/350/201/214/345/210/206/347/246/273_v0.1.md

@@ -0,0 +1,160 @@
+# 令牌与角色权职分离 v0.1
+
+> 把管理权限从「环境变量开关」改为「令牌 + 角色职责矩阵 + 派生链」。
+> 实现：`md_cg/tokens.py`、`md_cg/security.py`、`md_cg/mcp_server.py`、`md_cg/mdcos.py`
+> 测试：`python -m md_cg.test_p21_tokens`（31 项，含 MCP 进程层）
+
+## 1. 为什么改
+
+改造前，管理权限来自环境变量 `MDCG_CAN_ADMIN=1`：
+
+```
+MDCG_CAN_ADMIN=1  →  can_admin=True  →  可 review_decide / forget / protect
+```
+
+问题有三：
+
+1. **无凭据**：任何能设置该进程环境的调用方都能自授权限，没有可追溯的授权主体；
+2. **不可区分**：写权限是一根整体开关，无法表达「验证单元不得改事实层」；
+3. **不可委派**：子代理只能拿同一把钥匙，权职分离无从谈起。
+
+## 2. 三层模型
+
+| 层 | 机制 | 落点 |
+|---|---|---|
+| ① 令牌 | 身份与权限的唯一凭据；明文只在签发时返回一次，落盘只存 `sha256` | `~/.mdcg/_tokens.json`（0600） |
+| ② 角色 | 职责矩阵：可写层 / 可执行 op / 密级上限 / 可否管理 | `tokens.ROLE_SPECS` |
+| ③ 派生 | 设计者令牌派生子令牌，**权限只能收窄**，子令牌默认不可再派生 | `tokens.derive()` |
+
+令牌格式 `mdcg1.<role>.<token_id>.<secret>`：`role` 便于人读，但**权威来源是令牌记录**——
+校验时比对记录中的 role 与 `sha256(secret)`，不一致即拒绝。
+
+### fail-closed
+
+| 情形 | 行为 |
+|---|---|
+| `MDCG_TOKEN` 合法 | 按令牌角色注入身份 |
+| `MDCG_TOKEN` 非法/过期/吊销 | **拒绝启动**，退出码 `3`，不降级为可用 |
+| 无 `MDCG_TOKEN` 且无 `MDCG_LEGACY_ENV_AUTH` | 降级为 `guest`：只读、`internal` 密级、不可管理 |
+| `MDCG_LEGACY_ENV_AUTH=1` | 兼容旧部署的 env 直连（`auth_mode=legacy_env`，不推荐） |
+
+## 3. 角色职责矩阵
+
+五大单元（`record / reflect / verify / output / sustain`）的 `unit / effect / duty`
+与 `identity.POSITIONS`（智能论 v3.4 §十三）**同源**，`test_p21_tokens` 有断言防漂移。
+
+| 角色 | 单元 | 效 | 可写层 | 可执行 op | 密级上限 | 管理 | 可派生 |
+|---|---|---|---|---|---|---|---|
+| `designer` | 设计者权限载体 | 主 | `*` | `*` | secret | ✅ | ✅ |
+| `record` | 记录单元 | 全 | knowledge, contextual, structural, unresolved, rejected, goals | info, route, read, write, goal, recent | internal | ✗ | ✗ |
+| `reflect` | 反思单元 | 新 | contextual | info, route, read, write, recent, metacognition | internal | ✗ | ✗ |
+| `verify` | 验证单元 | 稳 | rejected, contextual | info, route, read, write, verify | internal | ✗ | ✗ |
+| `output` | 输出单元 | 通 | —（只读） | info, route, read, recent, whitebox | internal | ✗ | ✗ |
+| `sustain` | 维生系统 | 存 | self | info, read, write, sustain, scrub, evolution, self_state, metacognition | internal | ✗ | ✗ |
+| `guest` | 未认证访客 | — | —（只读） | info, route, read, recent, whitebox | internal | ✗ | ✗ |
+
+别名：`recorder→record`、`reflection→reflect`、`verifier→verify`、`viewer→output`、
+`admin/root→designer`、`anon/anonymous→guest`。
+
+## 4. 核心私有内容保护
+
+「其他单元不应越权修改核心私有内容」由**两道闸门**共同保证：
+
+1. **密级闸门**：`private` / `secret` 内容只有 `clearance` 达标的身份可写。
+   除 `designer` 外的角色密级上限一律 `internal`，因此**天然无法写入核心私有内容**。
+2. **层闸门**：`anchor`（身份锚点）与 `self`（灵枢自身）保护层，
+   只对 `layers_allow` 含该层或 `"*"` 的角色开放。
+
+写入路径统一走 `Principal.require_layer_write(layer, sensitivity)`，
+在 `MdCGSecure.add / add_rejected / add_unresolved / propose / add_goal / set_goal_status`
+六处生效。越权即 `AccessDenied`，不做静默降级。
+
+另有一道 **op 闸门**：`_cg_call` 入口调用 `Principal.require_op(op)`，
+使「只读角色执行 write / review」在进入业务逻辑前就被拦下。
+
+## 5. 单智能体的子代理权职分离
+
+即使是单智能体环境，也用**子代理 + 子令牌**把职责分开，从而校验偏差与盲区：
+
+```python
+from md_cg import tokens
+
+# 外部用户为唯一主智能体签发「设计者权限载体」
+d = tokens.issue("designer", actor="codebuddy", label="设计者载体")
+
+# 主智能体为各单元派生受限子令牌（权限只能收窄）
+v = tokens.derive(d["token"], "verify",  actor="codebuddy-verify",  ttl=3600)
+r = tokens.derive(d["token"], "reflect", actor="codebuddy-reflect", ttl=3600)
+o = tokens.derive(d["token"], "output",  actor="codebuddy-output",  ttl=3600)
+```
+
+由此得到的性质：
+
+- **验证单元写不了被验证内容**：`layers_allow=['rejected','contextual']`，
+  写 `knowledge` 层直接 `AccessDenied`，因此「自己写、自己验」在结构上不成立；
+- **记录单元不能自我验证**：无 `verify` op、无 `rejected` 以外的裁决权；
+- **输出单元不产生副作用**：`can_write=False`，连审计节点都写不了；
+- **维生系统改不了事实**：只能写 `self` 层运维域；
+- **委派链封口**：子令牌 `delegable=False`，不能继续往下派生；
+  父令牌吊销时**级联吊销**整条链。
+
+这样，主智能体无法用「同一个身份」既产出又验收，偏差与盲区有独立单元交叉检查。
+
+## 6. 操作手册
+
+```bash
+# ① 签发设计者载体（明文令牌只返回这一次）
+python -m md_cg.tokens issue --role designer --actor codebuddy --label "外部用户授权载体"
+
+# ② 派生各单元子令牌
+python -m md_cg.tokens derive --token <设计者令牌> --role verify --actor codebuddy-verify --ttl 3600
+
+# ③ 校验身份（打印 role / 可写层 / op 作用域）
+python -m md_cg.tokens verify --token <令牌>
+
+# ④ 清单与吊销
+python -m md_cg.tokens list
+python -m md_cg.tokens revoke --token-id tk_xxxxxxxxxxxx
+
+# ⑤ 打印角色职责矩阵
+python -m md_cg.tokens roles
+```
+
+MCP 接入（`~/.codebuddy/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "mdcg": {
+      "command": "python",
+      "args": ["-m", "md_cg.mcp_server"],
+      "env": {
+        "MDCG_ROOT": "data/mdcg",
+        "MDCG_TOKEN": "mdcg1.designer.tk_xxxxxxxxxxxx.xxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+令牌文件路径可用 `MDCG_TOKEN_FILE` 覆盖（默认 `~/.mdcg/_tokens.json`）。
+
+## 7. 迁移与兼容
+
+- 既有直接构造的 `Principal(...)`（测试、脚本）行为不变：
+  `role="system"`、`layers_allow=None`（不限制），仅新增字段。
+- 旧部署可临时设 `MDCG_LEGACY_ENV_AUTH=1` 继续用 env 身份，
+  `whoami.principal.auth_mode` 会标注 `legacy_env` 以便识别与清理。
+- `test_p2_mcp.py` 已自动带上该开关以保持回归。
+
+## 8. 诚实边界
+
+- **令牌文件即信任根**：`~/.mdcg/_tokens.json` 被写入者可自行追加令牌。
+  本方案把「可自授权限」从进程环境收敛到文件系统权限（0600），
+  未引入外部 KMS/签名链——那是下一步。
+- **明文令牌仍出现在客户端配置里**：MCP 客户端需要它。若需更高强度，
+  应改为「客户端持私钥 + 服务端校验签名」。
+- **角色矩阵是策略不是证明**：`layers_allow` 收窄的是**写层**，
+  读权限仍由 `clearance` 单维控制；跨租户隔离依赖 `MDCG_ROOT` 与 DEK。
+- **`op` 闸门是入口检查**：未覆盖 MCP 暴露的全部 33 个细粒度工具，
+  它们走 `cg`/`stg` 基元时同样受检，但直接调用 `MdCGSecure` 的脚本需自行遵守。