@furongjun1999/dsh-memory 0.4.11 → 0.5.0

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

@@ -1,172 +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` 内条目排序口径）。
+# 灵枢记忆动词协议 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` 内条目排序口径）。