@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/docs/{ → mdcg/}/347/201/265/346/236/242/344/270/211/345/261/202/346/213/206/345/210/206/350/247/204/345/210/222_v0.1.md

@@ -1,181 +1,181 @@
-# 灵枢三层拆分规划 v0.1
-
-> 状态：规划稿（未执行任何文件搬迁）
-> 日期：2026-09-10
-> 范围：理论（灵）/ 大脑（brain）/ 身体（body）三仓职责分离与主仓库瘦身
-> 性质：**本文只定义职责与顺序，不构成搬迁授权**；所有搬迁动作须先通过 Phase 0 裁决。
-
----
-
-## 0. 背景与结论
-
-### 0.1 现状问题
-
-| 问题 | 表现 |
-|---|---|
-| 主仓库职责混杂 | `dsh-memory` 同时承载「记忆大脑」与「工程/身体运行时」（`docker/`、`scripts/` 看门狗、宿主启动脚本），二者依赖量级完全不同 |
-| 同名不同物 | 历史命名中「AEIS」既指理论方（CTP）自带的工程副本，又指 `dsh-memory` 的 Python 大脑包，导致「aeis = 大脑」的旧语义债 |
-| 跨库同步困难 | 同一份工程内容在多库各存一份，改动需人工同步，真源不清 |
-| 断链 | `AEIS/tools/*` 指向 `dsh-memory\llm-adapter-poc`，该路径当前不存在（待 Phase 0 核实） |
-| 交付面过宽 | 完整灵枢 = 理论 + 大脑 + 身体，体量巨大；理论难懂、身体重依赖，二者都阻碍了「大多数人只需大脑」这一主路径 |
-
-### 0.2 结论（本次收敛）
-
-**主仓库不再放工程内容的完整实现，只放「大脑」。**
-
-- 完整灵枢 = **灵** + **脑** + **身**；但对外**默认只交付大脑**。
-- 理论（灵）与身体（身）作为大脑的**可选下层 / 上层**，通过 README 分层入口引导，而非塞进主仓库。
-- 分离的直接收益：消除跨库重复实现，真源唯一，降低同步成本。
-- 面向人群：理论 → 研究者；身体 → 少数需具身者；**大脑 → 大多数人（默认入口）**。
-
----
-
-## 1. 三层定位
-
-| 仓 | 角色 | 内容边界 | 默认读者 | 依赖量级 |
-|---|---|---|---|---|
-| CTP / CommonTrustProtocol | **理论（灵）** | 协议、认识论、信任账本；**不含工程实现**（待剥离自带 `aeis/` 工程副本） | 研究者 | 无（纯文档/协议） |
-| **dsh-memory（主仓库）** | **大脑** | `md_cg` 认知图内核 + MCP/npm 接口 + 记忆数据；**纯逻辑、零重依赖** | **大多数人（默认入口）** | 轻（标准库 + 轻量 npm） |
-| AEIS / body | **身体** | 传感器、语音、执行器、docker 运行环境、模型权重、宿主看门狗 | 少数需具身者 | 重（设备/模型/容器） |
-
-**一句话各自定位**
-
-- 灵：定义「什么样的智能值得被信任」——协议与公理，不落代码。
-- 脑：定义「记住什么、如何召回、如何自演化」——可在任意宿主上单独运行。
-- 身：定义「如何感知与作用于世界」——可选，且可替换。
-
----
-
-## 2. 主仓库（大脑）取舍清单
-
-### 2.1 保留（= 大脑本体）
-
-| 路径 | 内容 | 理由 |
-|---|---|---|
-| `md_cg/` | 认知图内核（98 py：consolidate / refine / pooling / provenance / whitebox / MCP server…） | 大脑核心，纯 Python |
-| `src/` | MCP / npm 插件接口（8 ts） | 大脑对外唯一入口 |
-| `test/` | 集成测试 | 大脑正确性保障 |
-| `data/` | 记忆数据（**归位须待 Phase 3**） | 大脑资产，非工程副产物 |
-| `package.json` / `tsconfig.json` | 构建定义 | 轻依赖 |
-| `README.md` / `docs/` | 分层入口文档 | 需重写为三层入口（Phase 4） |
-
-### 2.2 移出或降级（= 身体 / 工程）
-
-| 路径 | 处置 | 去向 |
-|---|---|---|
-| `docker/` | 移出 | 身体仓（运行环境） |
-| `dsh-web-start.bat` | 移出 | 身体仓（宿主启动） |
-| `scripts/`（看门狗 ps1 / vbs） | 移出 | 身体仓（宿主守护） |
-| 语音 / 模型权重 / 设备相关资源 | 移出 | 身体仓 |
-
-### 2.3 断链修复（Phase 2 处理）
-
-- `AEIS/tools/*` → `dsh-memory\llm-adapter-poc`（当前缺失）。
-- 二选一：**补齐**该路径，或**声明废弃**并从文档/代码中移除引用。
-- 原则：不允许存在「文档指向不存在路径」的悬空引用。
-
----
-
-## 3. 分期任务规划
-
-> 顺序不可交换：**先裁决 → 再冻接口 → 再搬代码 → 最后动数据**。
-> 每一期均有独立验收，未通过不得进入下一期。
-
-### Phase 0 — 裁决（不搬任何文件）
-
-| # | 任务 | 产出 |
-|---|---|---|
-| 0.1 | `diff -rq` 定 `aeis` 唯一真源（CTP 侧 vs 独立仓侧） | 真源结论 + diff 快照存档 |
-| 0.2 | 一句话写死「身体」操作定义：设备端口 / 世界载体 / 宿主客户端（三择一） | 定义条目（可导出为边界表） |
-| 0.3 | 将 `data/mdcg` 声明为大脑资产，并**冻结写入** | 冻结记录 + 恢复步骤 |
-
-**验收**：真源唯一；身体定义可一句话导出；`data/mdcg` 冻结生效且可恢复。
-
-### Phase 1 — 接口先行（仍不搬文件）
-
-| # | 任务 | 产出 |
-|---|---|---|
-| 1.1 | 冻结 brain↔body 契约：只暴露**能力名**，不暴露执行细节 | 契约表（能力名 + 入参/出参语义） |
-| 1.2 | 跑通两条链路各一次：身体取知识（`cg(op=whitebox)`）、大脑写记忆（`mdcg_remember`） | 双向链路验证记录 |
-
-**验收**：契约冻结且带版本号；两条链路各绿一次。
-
-### Phase 2 — 代码剥离
-
-| # | 任务 | 产出 |
-|---|---|---|
-| 2.1 | 主仓库移除重依赖目录（见 §2.2） | 瘦身后的主仓库 |
-| 2.2 | CTP 侧剥离自带 `aeis/` 工程副本（或反向声明 CTP 为发布源） | 剥离/声明记录 |
-| 2.3 | 修复 `AEIS/tools/*` 断链 | 补齐或废弃说明 |
-
-**验收**：主仓库在干净环境 `pip install` / `npm install` 后**无重依赖**即可运行大脑。
-
-> **详规**：理论仓具体拆分清单、主仓切 `md_cg` 的逐行改动点、白箱知识库内迁的依赖阻断与搬迁映射，见 [docs/理论仓拆分与白箱知识库内迁_v0.1.md](理论仓拆分与白箱知识库内迁_v0.1.md)。
-
-### Phase 3 — 数据迁移（最后做 · 不可逆）
-
-| # | 任务 | 产出 |
-|---|---|---|
-| 3.1 | **先演练回退**：`mdcg.enabled: false` + 数据不迁移，确认旧通道可用 | 回退演练记录 |
-| 3.2 | 再迁 `data/mdcg` | 迁移报告（幂等 + 备份） |
-
-**验收**：迁移后节点数与原库一致（当前基准 **6340** 节点）；数量不符即说明密级 / root / actor 未对齐，须回退重来。
-
-### Phase 4 — 命名与文档统一
-
-| # | 任务 | 产出 |
-|---|---|---|
-| 4.1 | 全库统一「灵 / 大脑 / 身体」表述 | 术语表 |
-| 4.2 | 同步 README 与 `docs/`，清掉「aeis = 大脑」旧语义债 | 修订后的分层入口文档 |
-
-**验收**：README 三层入口清晰，无「aeis = 大脑」歧义表述；命名与职责一致。
-
----
-
-## 4. 贯穿全程的三条铁律
-
-1. **先定职责、再定归属**——库名是历史沉积，不是功能声明。不得因为「名字里有 aeis」就归给理论方。
-2. **接口冻结早于代码搬迁**——否则拆的是目录，不是耦合；耦合仍在，只是换了个地方报错。
-3. **数据最后动且可回退**——`data/mdcg` 挪错是**静默失效**（写入只打 warn），6340 节点无法从代码重建。
-
----
-
-## 5. 风险与回退
-
-| 风险 | 触发条件 | 回退动作 |
-|---|---|---|
-| 记忆真源错位 | `mdcg.root` 落到错误目录，写入静默告警 | 恢复 `data/mdcg` 原位 + `mdcg.enabled: false` |
-| 写入冻结期间数据丢失 | Phase 0 冻结但未建备份 | 冻结前先做全量备份（必须前置） |
-| 契约冻结不彻底 | 身体侧仍直接读大脑文件 | 强制走契约能力名，禁止跨层直连 |
-| 真源判断错误 | Phase 0 diff 结论有误 | 保留 diff 快照，可重判并回滚剥离 |
-
-**迁移不可逆点**：Phase 3.2。进入前必须完成 Phase 3.1 回退演练。
-
----
-
-## 6. 明确不做（边界声明）
-
-- 本文**不授权**任何文件实际搬迁 / 删除。
-- 本文**不改变**任何运行时配置、不修改 `cordis.patch.yml`、不动 `data/mdcg` 内容。
-- 本文**不替代** Phase 0 的裁决结论——若裁决结果与本规划假设冲突，以裁决为准并回改本文。
-
----
-
-## 7. 下一步（三个裁决性动作）
-
-1. `diff -rq` 定 `aeis` 真源；
-2. 一句话写死「身体」定义；
-3. 冻结 `data/mdcg` 写入（含前置备份）。
-
-> 这三件做完，搬迁清单会自动收敛；在此之前动手，等于在大脑里留一个没有海马体的身体。
-
----
-
-## 附：术语对照
-
-| 本文用语 | 对应现状命名 | 说明 |
-|---|---|---|
-| 灵 / 理论 | 智能论 v3.4、CTP、CommonTrustProtocol | 协议与认识论 |
-| 大脑 / brain | `md_cg`、`dsh-memory`、`@furongjun1999/dsh-memory` | 认知图 + MCP 接口 + 记忆数据 |
-| 身体 / body | AEIS（独立仓）、`docker/`、`scripts/`、`src` 之外的宿主层 | 传感器 / 执行器 / 宿主运行时 |
-| 真源 | single source of truth | 同一内容只允许一处为准 |
+# 灵枢三层拆分规划 v0.1
+
+> 状态：规划稿（未执行任何文件搬迁）
+> 日期：2026-09-10
+> 范围：理论（灵）/ 大脑（brain）/ 身体（body）三仓职责分离与主仓库瘦身
+> 性质：**本文只定义职责与顺序，不构成搬迁授权**；所有搬迁动作须先通过 Phase 0 裁决。
+
+---
+
+## 0. 背景与结论
+
+### 0.1 现状问题
+
+| 问题 | 表现 |
+|---|---|
+| 主仓库职责混杂 | `dsh-memory` 同时承载「记忆大脑」与「工程/身体运行时」（`docker/`、`scripts/` 看门狗、宿主启动脚本），二者依赖量级完全不同 |
+| 同名不同物 | 历史命名中「AEIS」既指理论方（CTP）自带的工程副本，又指 `dsh-memory` 的 Python 大脑包，导致「aeis = 大脑」的旧语义债 |
+| 跨库同步困难 | 同一份工程内容在多库各存一份，改动需人工同步，真源不清 |
+| 断链 | `AEIS/tools/*` 指向 `dsh-memory\llm-adapter-poc`，该路径当前不存在（待 Phase 0 核实） |
+| 交付面过宽 | 完整灵枢 = 理论 + 大脑 + 身体，体量巨大；理论难懂、身体重依赖，二者都阻碍了「大多数人只需大脑」这一主路径 |
+
+### 0.2 结论（本次收敛）
+
+**主仓库不再放工程内容的完整实现，只放「大脑」。**
+
+- 完整灵枢 = **灵** + **脑** + **身**；但对外**默认只交付大脑**。
+- 理论（灵）与身体（身）作为大脑的**可选下层 / 上层**，通过 README 分层入口引导，而非塞进主仓库。
+- 分离的直接收益：消除跨库重复实现，真源唯一，降低同步成本。
+- 面向人群：理论 → 研究者；身体 → 少数需具身者；**大脑 → 大多数人（默认入口）**。
+
+---
+
+## 1. 三层定位
+
+| 仓 | 角色 | 内容边界 | 默认读者 | 依赖量级 |
+|---|---|---|---|---|
+| CTP / CommonTrustProtocol | **理论（灵）** | 协议、认识论、信任账本；**不含工程实现**（待剥离自带 `aeis/` 工程副本） | 研究者 | 无（纯文档/协议） |
+| **dsh-memory（主仓库）** | **大脑** | `md_cg` 认知图内核 + MCP/npm 接口 + 记忆数据；**纯逻辑、零重依赖** | **大多数人（默认入口）** | 轻（标准库 + 轻量 npm） |
+| AEIS / body | **身体** | 传感器、语音、执行器、docker 运行环境、模型权重、宿主看门狗 | 少数需具身者 | 重（设备/模型/容器） |
+
+**一句话各自定位**
+
+- 灵：定义「什么样的智能值得被信任」——协议与公理，不落代码。
+- 脑：定义「记住什么、如何召回、如何自演化」——可在任意宿主上单独运行。
+- 身：定义「如何感知与作用于世界」——可选，且可替换。
+
+---
+
+## 2. 主仓库（大脑）取舍清单
+
+### 2.1 保留（= 大脑本体）
+
+| 路径 | 内容 | 理由 |
+|---|---|---|
+| `md_cg/` | 认知图内核（98 py：consolidate / refine / pooling / provenance / whitebox / MCP server…） | 大脑核心，纯 Python |
+| `src/` | MCP / npm 插件接口（8 ts） | 大脑对外唯一入口 |
+| `test/` | 集成测试 | 大脑正确性保障 |
+| `data/` | 记忆数据（**归位须待 Phase 3**） | 大脑资产，非工程副产物 |
+| `package.json` / `tsconfig.json` | 构建定义 | 轻依赖 |
+| `README.md` / `docs/` | 分层入口文档 | 需重写为三层入口（Phase 4） |
+
+### 2.2 移出或降级（= 身体 / 工程）
+
+| 路径 | 处置 | 去向 |
+|---|---|---|
+| `docker/` | 移出 | 身体仓（运行环境） |
+| `dsh-web-start.bat` | 移出 | 身体仓（宿主启动） |
+| `scripts/`（看门狗 ps1 / vbs） | 移出 | 身体仓（宿主守护） |
+| 语音 / 模型权重 / 设备相关资源 | 移出 | 身体仓 |
+
+### 2.3 断链修复（Phase 2 处理）
+
+- `AEIS/tools/*` → `dsh-memory\llm-adapter-poc`（当前缺失）。
+- 二选一：**补齐**该路径，或**声明废弃**并从文档/代码中移除引用。
+- 原则：不允许存在「文档指向不存在路径」的悬空引用。
+
+---
+
+## 3. 分期任务规划
+
+> 顺序不可交换：**先裁决 → 再冻接口 → 再搬代码 → 最后动数据**。
+> 每一期均有独立验收，未通过不得进入下一期。
+
+### Phase 0 — 裁决（不搬任何文件）
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 0.1 | `diff -rq` 定 `aeis` 唯一真源（CTP 侧 vs 独立仓侧） | 真源结论 + diff 快照存档 |
+| 0.2 | 一句话写死「身体」操作定义：设备端口 / 世界载体 / 宿主客户端（三择一） | 定义条目（可导出为边界表） |
+| 0.3 | 将 `data/mdcg` 声明为大脑资产，并**冻结写入** | 冻结记录 + 恢复步骤 |
+
+**验收**：真源唯一；身体定义可一句话导出；`data/mdcg` 冻结生效且可恢复。
+
+### Phase 1 — 接口先行（仍不搬文件）
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 1.1 | 冻结 brain↔body 契约：只暴露**能力名**，不暴露执行细节 | 契约表（能力名 + 入参/出参语义） |
+| 1.2 | 跑通两条链路各一次：身体取知识（`cg(op=whitebox)`）、大脑写记忆（`mdcg_remember`） | 双向链路验证记录 |
+
+**验收**：契约冻结且带版本号；两条链路各绿一次。
+
+### Phase 2 — 代码剥离
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 2.1 | 主仓库移除重依赖目录（见 §2.2） | 瘦身后的主仓库 |
+| 2.2 | CTP 侧剥离自带 `aeis/` 工程副本（或反向声明 CTP 为发布源） | 剥离/声明记录 |
+| 2.3 | 修复 `AEIS/tools/*` 断链 | 补齐或废弃说明 |
+
+**验收**：主仓库在干净环境 `pip install` / `npm install` 后**无重依赖**即可运行大脑。
+
+> **详规**：理论仓具体拆分清单、主仓切 `md_cg` 的逐行改动点、白箱知识库内迁的依赖阻断与搬迁映射，见 [docs/theory/理论仓拆分与白箱知识库内迁_v0.1.md](../theory/理论仓拆分与白箱知识库内迁_v0.1.md)。
+
+### Phase 3 — 数据迁移（最后做 · 不可逆）
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 3.1 | **先演练回退**：`mdcg.enabled: false` + 数据不迁移，确认旧通道可用 | 回退演练记录 |
+| 3.2 | 再迁 `data/mdcg` | 迁移报告（幂等 + 备份） |
+
+**验收**：迁移后节点数与原库一致（当前基准 **6340** 节点）；数量不符即说明密级 / root / actor 未对齐，须回退重来。
+
+### Phase 4 — 命名与文档统一
+
+| # | 任务 | 产出 |
+|---|---|---|
+| 4.1 | 全库统一「灵 / 大脑 / 身体」表述 | 术语表 |
+| 4.2 | 同步 README 与 `docs/`，清掉「aeis = 大脑」旧语义债 | 修订后的分层入口文档 |
+
+**验收**：README 三层入口清晰，无「aeis = 大脑」歧义表述；命名与职责一致。
+
+---
+
+## 4. 贯穿全程的三条铁律
+
+1. **先定职责、再定归属**——库名是历史沉积，不是功能声明。不得因为「名字里有 aeis」就归给理论方。
+2. **接口冻结早于代码搬迁**——否则拆的是目录，不是耦合；耦合仍在，只是换了个地方报错。
+3. **数据最后动且可回退**——`data/mdcg` 挪错是**静默失效**（写入只打 warn），6340 节点无法从代码重建。
+
+---
+
+## 5. 风险与回退
+
+| 风险 | 触发条件 | 回退动作 |
+|---|---|---|
+| 记忆真源错位 | `mdcg.root` 落到错误目录，写入静默告警 | 恢复 `data/mdcg` 原位 + `mdcg.enabled: false` |
+| 写入冻结期间数据丢失 | Phase 0 冻结但未建备份 | 冻结前先做全量备份（必须前置） |
+| 契约冻结不彻底 | 身体侧仍直接读大脑文件 | 强制走契约能力名，禁止跨层直连 |
+| 真源判断错误 | Phase 0 diff 结论有误 | 保留 diff 快照，可重判并回滚剥离 |
+
+**迁移不可逆点**：Phase 3.2。进入前必须完成 Phase 3.1 回退演练。
+
+---
+
+## 6. 明确不做（边界声明）
+
+- 本文**不授权**任何文件实际搬迁 / 删除。
+- 本文**不改变**任何运行时配置、不修改 `cordis.patch.yml`、不动 `data/mdcg` 内容。
+- 本文**不替代** Phase 0 的裁决结论——若裁决结果与本规划假设冲突，以裁决为准并回改本文。
+
+---
+
+## 7. 下一步（三个裁决性动作）
+
+1. `diff -rq` 定 `aeis` 真源；
+2. 一句话写死「身体」定义；
+3. 冻结 `data/mdcg` 写入（含前置备份）。
+
+> 这三件做完，搬迁清单会自动收敛；在此之前动手，等于在大脑里留一个没有海马体的身体。
+
+---
+
+## 附：术语对照
+
+| 本文用语 | 对应现状命名 | 说明 |
+|---|---|---|
+| 灵 / 理论 | 智能论 v3.4、CTP、CommonTrustProtocol | 协议与认识论 |
+| 大脑 / brain | `md_cg`、`dsh-memory`、`@furongjun1999/dsh-memory` | 认知图 + MCP 接口 + 记忆数据 |
+| 身体 / body | AEIS（独立仓）、`docker/`、`scripts/`、`src` 之外的宿主层 | 传感器 / 执行器 / 宿主运行时 |
+| 真源 | single source of truth | 同一内容只允许一处为准 |

package/docs/mdcg//347/201/265/346/236/242/350/256/260/345/277/206/345/212/250/350/257/215/345/215/217/350/256/256_v1.0-draft.md

@@ -0,0 +1,172 @@
+# 灵枢记忆动词协议 v1.0（draft）
+
+> **本文档是投影，不是真源。** 真源 = `md_cg/protocol.py`（`VERBS` / `VERB_SPECS` /
+> `WRITE_TRIO` / `OP_DERIVE` / `DERIVE_EXTRA_KEYS` / `VERDICT_FIELDS`）。
+> 文档与 `md_cg/conformance.py` 的断言**均从真源取值**；改形状只改真源，本文档随之同步。
+> 手写行号会腐化（本仓已有实证），故本文档只写**符号名**不写行号。
+
+**版本**：v1 · **状态**：draft（`protocol.FROZEN = False`）
+
+## 1 目的与范围
+
+把 MCP 记忆工具面的**动词与 I/O 形状**冻结成可裁决的声明，使三端（本仓 MCP 客户端 /
+DSH 内建基元 / 第三方客户端）**各自实现客户端而不必读源码**。
+
+- **动词范围（先行收窄）**：`route` / `read` / `write` / `supersede` / `forget`。
+- **协议面 ≠ MCP 面全量**：`_cg_dispatch` 现有 35 个 op 分支，其中 30 个
+  （`ccg` / `review` / `protect` / `verify` / `whitebox` …）属**扩展能力面**——
+  它们是能力，不是协议违例。把协议覆盖范围当成 MCP 面全量，会让协议每加一个 op
+  就永久红灯；故反向对账降级为 `extension_ops` 报告项（清单可见、**不 FAIL**）。
+  扩展面的文档一致性由 README 认知图 + `docs/mdcg/功能调用映射表` 的 cogmap 门禁承担。
+- **非目标**：本文档不定义 HTTP / 传输层；不定义扩展 op 的形状（只登记其存在）。
+
+## 2 三条铁律
+
+| # | 铁律 | 判据 |
+|---|---|---|
+| 1 | **不冒充** | 未实现的动词登记 `status="reserved"` 并给出 `map_to` 现状映射证据；live 的形状取**代码实测**，不取设想 |
+| 2 | **write 三键铁律** | `write` **任一形态**必含 `ok` / `id` / `committed` 三键——客户端据此判定「是否落盘」，不靠猜 |
+| 3 | **fail-closed 取形状** | 未声明动词 / 未声明形态直接抛 `KeyError`，不返回空壳（`protocol.shape_of`） |
+
+`ok` 与 `committed` **分离**是本协议对客户端最有价值的一条：它表达
+「**闸门行为 ≠ 工具故障**」——`ok=True, committed=False` 是校验闸门正常短路
+（REJECT / DEFER / 冲突），**重试同样结果**，客户端不应重试而应读 `hint`。
+
+## 3 动词总览
+
+| 动词 | status | 变更性 | 必需入参（任一满足） | 形态数 | 语义 |
+|---|---|---|---|---|---|
+| `route` | live | 否 | `intent` \| `query` | 1 | 只给知识与建议能力名，不执行 |
+| `read` | live | 否 | `node_id` \| (`query` \| `intent`) \| `budget_tokens` | 4（含 null） | 读三分态：单节点 / 结果列表 / token 预算包 |
+| `write` | live | 是 | `content` | 4 | 落盘或闸门短路；未 committed 必给去向 |
+| `supersede` | **reserved** | 是 | `node_id` \| `superseded_by` | 1（planned） | 以新节点取代旧节点（**未实现**，见 §5） |
+| `forget` | live | 是 | `node_id` | 3 | 软删（移 trash + 删除清单 + 摘索引）与恢复 |
+
+## 4 形状声明（required 必在，optional 可缺）
+
+### 4.1 `route`
+
+| 形态 | when | required | optional |
+|---|---|---|---|
+| `default` | 恒 | `knowledge`, `meta` | `suggested_capabilities`, `note` |
+
+### 4.2 `read`（三分态 + null）
+
+| 形态 | when | required | optional |
+|---|---|---|---|
+| `node` | `node_id` 非空且目标存在且可见 | `id`, `path`, `frontmatter`, `content`, `verification_state` | `truncated`, `content_lines`, `content_bytes`, `offset`, `next_offset`, `note` |
+| `node_missing` | `node_id` 非空但目标不存在 / 不可见 / 已软删 | **（返回 `null`）** | — |
+| `list` | `budget_tokens` 为空 | `meta`, `results` | — |
+| `pack` | `budget_tokens` 非空 | `pack`, `tokens_used`, `budget`, `skipped`, `recent`, `meta` | — |
+
+> **`read` 目标缺失返回 `null`（实测），不是错误对象。** 客户端必须先判空再解析：
+> 把 `null` 当异常会误报，把 `null` 当空内容会静默吞未知。这是本协议里唯一
+> 以 `returns_null` 登记的形态。
+
+### 4.3 `write`（四形态）
+
+| 形态 | when | required | optional |
+|---|---|---|---|
+| `committed` | 链尾执行器落盘 | `ok`, `id`, `committed` | `verdict`, `consistency`, `propagation` |
+| `gate_short_circuit` | 任一 before 闸门短路（审核 REJECT / DEFER / 冲突） | 三键 + `moved_to`, `verdict`, `hint` | `pid`, `dedup`, `dup_of`, `dup_status`, `consistency` |
+| `gate_hard_reject` | 契约缺失硬拒（依赖声明闸 E050/E051） | 三键 + `gate`, `error`, `hint` | `missing`, `verdict` |
+| `gate_gated` | 主动遗忘闸（`gated=true`） | 三键 + `gate`, `verdict` | `consistency`, `moved_to`, `propagation` |
+
+`hint` 的语义固定为：**闸门正常行为、不是工具故障、重试同样结果**（并给出下一步 op）。
+
+### 4.4 `forget`
+
+| 形态 | when | required | optional |
+|---|---|---|---|
+| `forgotten` | `action` 缺省或非 `restore` | `ok`, `id`, `tombstone` | — |
+| `restored` | `action == 'restore'` | `ok`, `id`, `forced` | — |
+| `failed` | 目标不存在 / 已 tombstone（未 force）/ trash 无文件 / OSError | `ok`, `error` | `reason`, `t`, `action`, `action_derived`, `hint_action` |
+
+### 4.5 `supersede`（reserved，未实现）
+
+| 形态 | when | required | optional |
+|---|---|---|---|
+| `planned` | （预留位，尚未实现） | `ok`, `id`, `superseded_by` | `supersedes`, `propagation`, `verdict` |
+
+## 5 `supersede` 为何 reserved 而非 live
+
+**现状映射证据（`map_to`，即「现在实际怎么做」）**：
+
+| 现有锚 | 说明 |
+|---|---|
+| `write` | 新节点写入本身走 `write`（五动词不重复造写入通道） |
+| `review` / `verify` | 现有撤回体系由校验（`verify` 验伪）与审核（`review` 的 delete/merge）承担，无独立取代动词 |
+| `nodefile.believed_at` | 取代语义的锚字段已就位（写侧注释），缺的是动词入口与检索面过滤 |
+
+**不实现的原因**：取代会改变**默认检索面**（被取代节点是否可见），属行为变更，
+须先冻结协议再落实现——否则三端各自发明可见性口径，协议形同虚设。
+
+## 6 op 推导兜底（客户端须知）
+
+`op` 漏传时 wrapper 按入参签名推导（2026-09-13 防呆落地）：
+
+| 入参签名 | 推导 op |
+|---|---|
+| `content` | `write` |
+| `query` | `read` |
+| `node_id` | `read` |
+| `intent` | `route` |
+| （无签名） | `read` |
+
+推导发生时返回体**追加透出** `op` / `op_derived` / `hint`（`DERIVE_EXTRA_KEYS`）——
+语义是「本次 op 是猜的」，客户端据此可要求调用方补显式 op。这是 **additive** 行为，
+不破坏各形态的 required 子集判定。
+
+> 协议侧只作**文档化声明**，不对推导做强静态对账：推导实现散落在 wrapper 分支里，
+> 强做正则对账会误报——**宁可少断言，不可假绿灯**。
+
+## 7 `verdict` 字段集
+
+写路径闸门短路时随返回透出（`VERDICT_FIELDS`）：
+
+`state` · `kind` · `basis` · `evidence` · `detail`
+
+其中 `state ∈ {ACCEPT, REJECT, DEFER, BLINDSPOT}`（四态资格裁决）。
+客户端应据 `state` 决定「可用 / 待补 / 不可用」，而不是据 HTTP 式成败。
+
+## 8 静态对账与门禁
+
+`conformance.check()` **恒追加**四条断言（`protocol.*`）：
+
+| check id | 级别 | 判据 |
+|---|---|---|
+| `protocol.op.extension_surface` | WARN | 报告协议冻结面与扩展面规模（能力不是违例） |
+| `protocol.verb.implemented` | FAIL | 声明为 live 的动词在 MCP 面均有实现分支（**说了没做**） |
+| `protocol.verb.reserved_clean` | FAIL | reserved 动词未出现实现分支（**预留位被静默实现**） |
+| `protocol.shape.declared` | FAIL | 每动词至少一形态、每形态有 `when`、reserved 有 `map_to`、live 有 `impl` |
+
+op 分支提取用 **AST** 而非正则（`protocol._ops_from_source`）：正则对单引号 /
+换行 / `op.strip().lower()` 形态会**静默漏提**，而漏提在本协议里等于假绿灯
+（cogmap 已有同类教训：单引号写法静默漏报窗口）。AST 结构性识别不依赖写法。
+
+**命令**：
+
+```bash
+python -m md_cg.protocol            # 打印静态对账结论（只读，零写入）
+python -m md_cg.test_protocol       # 形状钉死测试（41 断言：静态 17 + 真调 16 + 集成 8）
+```
+
+## 9 边界与不适用条件
+
+**生效条件**：三端需要按同一形状实现记忆客户端时；改动五动词任一的返回形状时；
+新增/变更 MCP 面 op 分支时（须复核是否触碰协议面）。
+
+**不适用条件**：
+
+- 扩展能力面（30 个 op）的形状——本协议不定义，由各自模块文档与 cogmap 门禁承担。
+- 传输 / 序列化 / 鉴权——属宿主层，不在协议面。
+- 未冻结前（draft 期）**形状可破坏性调整**；冻结是单向门，须三端实测收敛后
+  由使用者拍板（工作计划 §9 风险 3）。冻结后改形状须递增版本号（v1 → v2），
+  不得原地改 v1。
+
+**已知边界（如实声明，不假装覆盖）**：
+
+- `write.committed` 形态在**无 `MDCG_POLICY_FILE` 的环境不可达**（校验闸门恒 DEFER
+  入 `review_queue`），故 `test_protocol` 的 B 段按实际走的那一态校验形状；
+  `committed` 字段依据是 `writepipe` 链尾执行器的**源码事实**而非实测返回。
+- 本协议只冻结**形状**（键集），不冻结**取值语义**（如 `pack` 内条目排序口径）。

package/docs/mdcg//347/216/257/344/272/214_/347/231/275/347/256/261/345/241/253/345/205/205/346/265/201/346/260/264/347/272/277_v0.1.md

@@ -0,0 +1,31 @@
+# 环二·白箱填充流水线 v0.1（测试阶段记录）
+
+> 分工（使用者裁定 2026-09-17）：**LLM 提供模板并做校验；白箱负责确定性填充**；先测试（自有文件）→ 再试点（10 符号）→ 后规模化。
+
+## 一、流水线四段
+
+| 段 | 产物 | 性质 | 位置 |
+|---|---|---|---|
+| ① 事实提取 | 逐符号 required/optional/externals/guards/returns/doc | **确定性**（ast） | `md_cg/cond_facts.py` |
+| ② 模板 | 7 槽位 + 10 规则 + 12 条校验清单 | **LLM 单次产出**（job `h1789643186033_ba80bc`） | `md_cg/cond_template.json`（含 `_provenance`） |
+| ③ 填充 | 中文功能级生效条件 | **确定性**（零 LLM） | `md_cg/cond_compose.py` |
+| ④ 校验 | 逐条 PASS/REVISE/BLINDSPOT + 依据 | **LLM 单次复核**（job `h1789643407918_380037`） | 见本文件 §三 |
+
+门禁：任一条生成文本须过 `md_cg/condition_anchor.judge`（`ANCHORED` 或 `BLINDSPOT`；`WEAK`/`REJECT_META` 不放行）。**锚点通过 ≠ 语义正确**，故必须有 ④。
+
+## 二、测试结果（自有文件：`condition_anchor.py` + `cond_facts.py`）
+
+- 事实提取 13 符号；白箱填充 13 条；确定性门禁 **13/13 ANCHORED**；0 BLINDSPOT。
+- 样例：`调用 judge 时，必须提供实参 cond、src；可选 prefix=""、suffix="" 可省略；体内引用 META_MARKS、IDENT 需已定义；返回 out；功能：判定单条候选条件。…`
+
+## 三、LLM 校验结果与两处归因
+
+- 结论：**8 PASS / 5 REVISE / 0 BLINDSPOT**；5 条 REVISE 全部集中在同一处，另有 1 处真实缺陷。
+- **受控偏离（非缺陷）**：校验清单 C6/C9 要求「guards 非空时必须把每个 guard 原文写入」，但 `guards` 含**函数内部分支**（如 `if hits:`、`if i == 0 and …`）——那是实现细节不是前置条件。填充器按 `early` 标记只保留「首条语句且含 return/raise」的早退式前置。修正口径：**模板/清单需增加 `early` 条件**（此处登记为模板 v0.2 待改项，改由 LLM 复核）。
+- **真实缺陷（已修）**：`doc_head` 截断 60 字导致词被切半（`option` ≠ `referenced`），校验器 C9 以原文比对抓出。修正：超长按句读收口，不再截半个词。
+
+## 四、下一步（原始计划）
+
+1. 把 13 条写入自有源码（`# 生效条件：…` 置于定义前），过 `condition_anchor` + 全组回归，落候选分支交编外裁定。
+2. 模板 v0.2：把 `early` 条件写入 C6/C9（LLM 复核）；补 `md_cg/test_cond_facts.py`、`test_cond_compose.py` 断言。
+3. 试点：把 `hive/interop/iter-008-ring2-pilot/proposals.json` 的 10 条（LLM 路线）与白箱路线对比，择优或互补。

package/docs/{ → mdcg/}/347/274/272/345/217/243/345/215/225_P0/346/224/266/345/217/243_v0.1.md

@@ -1,6 +1,6 @@
 # 认知图 · P0 收口 证据单（G2 索引接线 + G3 能力标签）v0.1
 
-> 来源：`docs/认知图_索引与工程规范化_计划_v0.1.md` 的 R4/R5 前置项 —— **G2（文档/代码索引接线）** 与
+> 来源：`docs/mdcg/认知图_索引与工程规范化_计划_v0.1.md` 的 R4/R5 前置项 —— **G2（文档/代码索引接线）** 与
 > **G3（能力标签注入）**；G1（生效条件口径接线到各前缀）已于上一批次闭合（`evo-20260910-152148-2b35`）。
 > 目标工程：**dsh-memory / md_cg（认知图 + 记忆 OS）**
 > 证据口径：源码级核对 + **真实库（`AEIS/data/mdcg`）复算** + 前后冻结基线对照（不采信估计值）
@@ -38,7 +38,7 @@
 |---|---|---|
 | **G2** 索引接线（md_cg / src / docs 三大域） | ✅ 执行 | 计划 §六 R4/R5 的前置「先有索引」 |
 | **G3** 能力标签注入（`cap:<op>`） | ✅ 执行 | 计划 §四「索引节点缺能力归属」 |
-| G1 生效条件口径接线到各前缀 | ⏸ 已闭合 | 上一批次，见 `docs/认知图_条件空间合成与生效条件口径_v0.1.md` |
+| G1 生效条件口径接线到各前缀 | ⏸ 已闭合 | 上一批次，见 `docs/mdcg/认知图_条件空间合成与生效条件口径_v0.1.md` |
 | G7 / G8 / G4 / G5 / G6 | ⬜ 不执行 | 登记待定（§八）；G8 已裁定方案留作后续依据 |
 
 **执行通道（必须记录的环境事实）**：常驻 MCP 服务进程启动于当日改造**之前**，其内存模块缺 `CONDITION_SLOTS` / `condition_space_text`

package/docs/{ → mdcg/}/350/256/244/347/237/245/345/233/276_G4-G8/347/274/272/345/217/243/350/243/201/345/256/232/345/215/225_v0.1.md

@@ -1,6 +1,6 @@
 # 认知图 · G4–G8 缺口裁定单（条件空间声明 + 四态裁决）v0.1
 
-> 来源：`docs/缺口单_P0收口_v0.1.md` §八「DEFER 登记项」——**G4 层归属错位 / G5 视觉证据未落 / G6 node_ 结构提炼 /
+> 来源：`docs/mdcg/缺口单_P0收口_v0.1.md` §八「DEFER 登记项」——**G4 层归属错位 / G5 视觉证据未落 / G6 node_ 结构提炼 /
 > G7 自主演化无驱动 / G8 溯源链缺失**，外加缺口单 §6.1 的「索引节点应域级分池降权，而非吃 GLOBAL_CAP」。
 > 目标工程：**dsh-memory / md_cg（认知图 + 记忆 OS）**
 > 证据口径：源码级核对（行号可回溯）+ **真实库（`AEIS/data/mdcg`）只读复算** + 前后冻结基线对照（不采信估计值、不转述文档结论）

package/docs/{ → mdcg/}/350/256/244/347/237/245/345/233/276_/347/264/242/345/274/225/344/270/216/345/267/245/347/250/213/350/247/204/350/214/203/345/214/226_/350/256/241/345/210/222_v0.1.md

@@ -101,7 +101,7 @@ judge_qualification(mdcg.py:709-714)
              "lineno":383,"end":462,"lang":"py","hash":"9f2c1ab3de44"}
 
 // 文档节点
-"doc_ref":  {"path":"docs/认知图_MD目录方案_v0.1.md","heading":"9. 分阶段实施（稳健）",
+"doc_ref":  {"path":"docs/mdcg/认知图_MD目录方案_v0.1.md","heading":"9. 分阶段实施（稳健）",
              "heading_path":["9. 分阶段实施（稳健）"],"level":2,
              "lineno":491,"end":513,"anchor":"9-分阶段实施稳健","hash":"41ab77c0e1d9"}
 ```
@@ -161,7 +161,7 @@ judge_qualification(mdcg.py:709-714)
 |---|---|---|---|
 | **R0** | ✅ **已完成**（§十一 取证纪录）：全量 28 用例基线取证 + 修 4 条缺陷（`corpus.reset_root` 全量 rmtree / 3 处编码） | 28/28 全绿；P0 25/25、P1 38/38、P11 27/27、P12 32/32 | ✅ |
 | **R1** | ✅ **已完成**（§十二 取证纪录）：`codeindex.render` 改产 CCG 6 行、`EXTRACTORS` 后缀注册化（AST 精确 / TS-JS 弱提取）、`op=ref` 回读 + 漂移检测、`truncated`/`skipped_suffixes` 显式上报；实测 §1.3-1（role 档位） | ✅ 代码节点判定 **ACCEPT**（不再 BLINDSPOT）；`op=ref` 回读文本与源区间**逐字一致**、`hash_match` 检出漂移 | ✅ |
-| **R2** | ✅ **已完成**（§十三 取证纪录）：`docindex.py`（章节切块 + CCG 渲染 + `doc_ref`）+ `op=index_doc`；裁 §1.3-3（层/密级） | ✅ `docs/` 全部 md（实测 **19/19**，非静默跳过）切块可定位；`docs/认知图_MD目录方案_v0.1.md` 的 §9 表被判 **ACCEPT** 且给出行号 `L491-L516` | ✅ |
+| **R2** | ✅ **已完成**（§十三 取证纪录）：`docindex.py`（章节切块 + CCG 渲染 + `doc_ref`）+ `op=index_doc`；裁 §1.3-3（层/密级） | ✅ `docs/` 全部 md（实测 **19/19**，非静默跳过）切块可定位；`docs/mdcg/认知图_MD目录方案_v0.1.md` 的 §9 表被判 **ACCEPT** 且给出行号 `L491-L516` | ✅ |
 | **R3** | ✅ **已完成**（§十四 取证纪录）：`_refindex.json` 增量（抄 `sources.Ingestor` 范式）+ `check_refs` 漂移巡检 + `truncated` 显式上报 + 接入 `sustain.diagnose` | ✅ 改源文件一行 → `ref check` 报 stale（重建后消除）；删源 → dangling；`max_files` 触发时 `truncated=true` 且写进水位；`diagnose` 报 `ref_stale`、`heal` 的 `rebuild_refs` 修复 | ✅ |
 | **R3.1** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：节点级对账——`prune_orphans`（改标题产生的过期代）+ `prune_dangling`（源已删的悬空节点），接入 `index_code`/`index_doc` 与 `op=ref action=prune` | ✅ P27 §10/§10b 全绿；真实现场悬空 **20 → 0**（`LIVE_HITS=0`/`TRASH_HITS=20`）；受影响面 7 模块 6 绿 1 环境红 | ✅ |
 | **R3.2** | ✅ **已完成**（§十五 取证纪录，2026-09-12）：索引器**追加排除** `skip_dirs`（`index_code`/`index_doc`）——把 `.gitignore` 已忽略却物理留存的实验产物挡在门外，替代「调大 `max_files`」这一掩盖手段 | ✅ P27 **75/0** 全绿（§9 由 `500/2388` 红转 `30/30`）；新增 §9b 验证匹配口径 / 只增不减 / 可审计；受影响面 10 模块全绿 | ✅ |
@@ -223,7 +223,7 @@ md_cg 侧再补 `timeout_ms` 与 `needs_clearance` 两个扩展字段。裁剪
 3. **`hash` 不是内容寻址**：只做变更探测，不保证「内容相同即同节点」。
 4. ~~R0 有一个待闭环疑点~~ → **已在 §十一 闭环**。「`test_p1` EXIT 1 且输出仅 165 字节」的根因与 `test_p0` 同一类：受管环境下 `os.remove` 被环境 shim 接管，
    删除量越阈即中断进程；且失败形态是**静默截断 + 非零退出**，不是一条 FAIL。现已改为不清空目录（原子覆盖 + 等号守门），并全量复跑验证。
-5. **当前工作区未提交**：`docs/认知图_MD目录方案_v0.1.md`、`bench_p0.py`、`census.py`、`test_p0.py`、`test_p1.py` 已改，`md_cg/corpus.py` 未跟踪——R0 应先收口提交，再动索引层。
+5. **当前工作区未提交**：`docs/mdcg/认知图_MD目录方案_v0.1.md`、`bench_p0.py`、`census.py`、`test_p0.py`、`test_p1.py` 已改，`md_cg/corpus.py` 未跟踪——R0 应先收口提交，再动索引层。
 
 ---
 
@@ -253,7 +253,7 @@ md_cg 侧再补 `timeout_ms` 与 `needs_clearance` 两个扩展字段。裁剪
 `_md_cg_p0` 实测 **0 文件**——说明第一个 `reset_root(ROOT)` 已清空+重建成功，死在第二个；
 `_md_cg_p1` 实测 **350 文件**（< 500）故通过——**只差 150 就到阈值**，这正是历史上「P1 EXIT 1 / 165 字节」的同源形态。
 
-**关键点：文档早已裁决过**。`docs/认知图_MD目录方案_v0.1.md:365-367` 原文：
+**关键点：文档早已裁决过**。`docs/mdcg/认知图_MD目录方案_v0.1.md:365-367` 原文：
 > 幂等性：迁移按 node id 原子覆盖写，可反复执行，**不需要先清空目录**。（这不只是便利：清空目录依赖 `rmtree`，
 > 在有安全策略的环境下会被拦截，而"必须先删除才能重跑"的迁移脚本本身就是个脆弱设计。）