@furongjun1999/dsh-memory 0.4.4 → 0.4.6

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

@@ -0,0 +1,270 @@
+# 认知图 · P0 收口 证据单（G2 索引接线 + G3 能力标签）v0.1
+
+> 来源：`docs/认知图_索引与工程规范化_计划_v0.1.md` 的 R4/R5 前置项 —— **G2（文档/代码索引接线）** 与
+> **G3（能力标签注入）**；G1（生效条件口径接线到各前缀）已于上一批次闭合（`evo-20260910-152148-2b35`）。
+> 目标工程：**dsh-memory / md_cg（认知图 + 记忆 OS）**
+> 证据口径：源码级核对 + **真实库（`AEIS/data/mdcg`）复算** + 前后冻结基线对照（不采信估计值）
+> 时间：2026-09-10 ｜ 真实库批次：索引全量 1 轮 + 增量 1 轮、`cap_v01`（回滚抽样 1 条 → `cap_v01_restore`）
+> 演化条目：`evo-20260910-155442-28f8`（口径对齐）、`evo-20260910-155442-7ccf`（cap 阈值裁定）
+
+---
+
+## 判定单
+
+```
+条件空间：观测位置=全局(设计者)、操作层在 md_cg 写入口之外（只经既有 op 调用）
+          | 观测工具=真实库复算(_index.json / _refindex.json / _backfill.jsonl / 盘上 frontmatter) + 前后冻结基线
+          | 时间窗口=2026-09-10 本次迭代
+          | 存在约束=零新依赖(纯标准库) / md 单一真相源 / 不新增写入口 / 不改默认参数 / 预演先行
+白箱三问：依据=每条给文件级或计数级证据(§三/§四/§五)，未核实项显式标出(§九)
+          | 条件=执行前已预演(cap_plan 只读)、已有基线冻结(before)、可复算(final)、可回滚(cap_rollback 实测)
+          | 错后=若索引侧仍写单槽 observation_position，等于在刚清理过的污染源上重开入口：
+                conditions_pending 预计由 145 涨到约 1951 → 「生效条件声明率」被自己灌水，待补台账失真
+裁决：ACCEPT（G2 全量索引 + 口径对齐 + G3 阈值上调注入）
+      / DEFER（全量索引节点需要的 cap 判定：单关键词档 5179 条命中整体 REJECT）
+      / 待定项：(a) node_id 跨类同名归并 27 id/34 条；(b) 常驻服务内存视图陈旧；(c) 基线 P95 口径未固化
+依据：条件证据见 §三~§六，非相似度
+缺失维度：索引节点的「能力归属」——索引只产出「位置+结构」，不产出「这条属于哪个 op 的能力」
+          （这正是 G3 要补的，也是 G4/G5/G6 的前置）
+验证路径：口径对齐(§二) → 全量索引(§三) → 水位/幂等/巡检(§三) → cap 阈值裁定+注入+回滚(§四) → 指标对照(§五) → 副作用归因(§六)
+关注信号：conditions_pending 是否被单槽灌水；召回面扩大后 GLOBAL_CAP 截断率；密级是否被索引降级
+```
+
+---
+
+## 一、本轮范围与执行通道
+
+| 项 | 本轮 | 依据 |
+|---|---|---|
+| **G2** 索引接线（md_cg / src / docs 三大域） | ✅ 执行 | 计划 §六 R4/R5 的前置「先有索引」 |
+| **G3** 能力标签注入（`cap:<op>`） | ✅ 执行 | 计划 §四「索引节点缺能力归属」 |
+| G1 生效条件口径接线到各前缀 | ⏸ 已闭合 | 上一批次，见 `docs/认知图_条件空间合成与生效条件口径_v0.1.md` |
+| G7 / G8 / G4 / G5 / G6 | ⬜ 不执行 | 登记待定（§八）；G8 已裁定方案留作后续依据 |
+
+**执行通道（必须记录的环境事实）**：常驻 MCP 服务进程启动于当日改造**之前**，其内存模块缺 `CONDITION_SLOTS` / `condition_space_text`
+（调用即 `AttributeError`），且存在「水位先于节点落库被推进」的假成功（`_refindex.json` 记 `indexed=1403` 而知识层未增）。
+故本轮**不杀进程**（会连带停掉 sustain 心跳），改用「同 principal（designer / `can_admin` / `clearance=secret`）＋ 同
+`mcp_server.call_tool(cg,"cg",args)` 入口 ＋ 新进程」驱动，`MDCG_SUSTAIN=0` 避免起第二心跳。
+→ 该选择同时带来一处**观测工具失配**，已在 §6.2 归因。
+
+---
+
+## 二、改动清单（3 处实现 + 3 处断言）
+
+| 文件 | 改动 | 目的 |
+|---|---|---|
+| `md_cg/codeindex.py` | 新增 `condition_space(item)`：位置=源大域(`path` 首段)、方法=`compiler`(AST 精确)/弱提取(显式降级)、时间=全时窗哨兵、约束=「源文件 … 存在于本地仓且可读」；`render()` 的 `# 生效条件：` 行改调 `nodefile.condition_space_text(condition_space(item))`，替换「大域=…；检索…时」方言 | 口径对齐 |
+| `md_cg/docindex.py` | 同上：位置=`本地文档仓（大域=…）`、方法=文档提取、时间=全时窗、约束=「文档文件 … 存在且可读」 | 口径对齐 |
+| `md_cg/refindex.py` | `add_items()` 的 `condition_space` 由**单槽** `{"observation_position": 大域}` 改为复用 `codeindex/docindex.condition_space(it)`；新增 `_domain_of(it)`（`path` 首段 or `orphan`），`tags` 追加 `domain:<域>` | 口径对齐 + 路由域改由标签显式承担 |
+| `md_cg/test_p26_refindex.py` / `test_p27_docindex.py` / `test_p28_refcheck.py` | 断言同步：四槽齐备、`condition_space_text` 非空、正文=四槽合成、全时窗哨兵、弱提取降级、`frontmatter.condition_space == condition_space(item)`、`routing.route_key(...) == routing.normalize_domain(...)` | 守门 |
+
+**未改动**：`backfill.py`（`_condition_text` 已删单槽回退——保持为**独立校验口径**，避免「改完又用同一处校验」）、
+`mdcg.py` / `mdcos.py`（检索与写盘语义不动）、`nodefile.py`（唯一合成入口本体）。
+**未改默认参数**：`min_conf`/`max_files`/`max_items` 一律由调用参数传入。
+
+---
+
+## 三、G2 取证（全量索引三大域）
+
+### 3.1 逐域索引结果
+
+| 大域 | op | 条目 | 文件 | truncated | errors | skipped_suffixes |
+|---|---|---|---|---|---|---|
+| `md_cg/` | `index_code` | 1403 | 88 | **false** | 0 | — |
+| `src/` | `index_code` | 111 | 8 | **false** | 0 | — |
+| `docs/` | `index_doc` | 333 | 20 | **false** | 0 | `.html`/`.jpg`/`.json`/`.png`/`.yml`（无提取器，显式列出） |
+
+均为 `incremental=false` 首次全量；三域条目数远低于默认上限（`max_files=500` / `max_items=2000`），无截断。
+
+### 3.2 落库与对账
+
+- 登记 1847 条 → **唯一节点 1813**（`code_` 1480 + `doc_` 333），差额来源见 §6.3。
+- `op=ref action=stat`：`schema=2`、`files=116`、`nodes=1847`。
+- `op=ref action=check`：`checked=1813`、`stale=0`、`dangling=0`、`unresolved=0`。
+- `op=info`：`total_nodes` 4526 → **6339**。
+
+### 3.3 幂等（增量重跑）
+
+`incremental=true` 重跑一轮：`skipped_unchanged` 生效、`indexed` 不增、`node_id` 集合稳定（`codeindex.node_id`/`docindex.node_id`
+为稳定短哈希，按 id 原子覆盖，不清目录）。水位键为**源文件绝对路径**（一份认知图可索引多个大域，按 `rel` 记会在同名文件上互相覆盖）。
+
+### 3.4 口径守门的核心结论
+
+`conditions_pending` **保持 145**（`缺约束 7` + `缺载体/位置+方法+约束 138`），**未**如预演那样涨到约 1951。
+即：1813 个新节点的四槽齐备率为 100%，未产生任何「单槽冒充生效条件」的待补条目。
+→ 这是本轮唯一的实现改动（口径对齐）的**正面验收证据**：若不做 §二 的改动，全量索引会把约 1806 个单槽节点直接灌进库。
+
+---
+
+## 四、G3 取证（能力标签注入）
+
+### 4.1 阈值裁定（执行前，只读预演）
+
+预演（默认 `min_conf=0.5`）显示：规则表含「读 / 目标 / 一致性」等宽泛词，而 `confidence = 0.4 + 0.2×命中词数`，
+**仅命中 1 个词即达 0.6 会被注入**；其中「验证」一词因 CCG 正文必含 `# 验证方式：` 行而在索引节点上近乎全命中
+（预演命中 `cap:verify` 1630/1813）。
+分层抽检回读正文：0.6 档样本为文档章节（词只出现在**被引用段落**），0.8/1.0 档样本落在真实承载模块
+（`_verdict` / `forgetting.summary` / `_ref_call`）。
+→ 裁定（`designer-perspective` 四态）：**单关键词命中一律不构成具备该能力的资格**；把 `min_conf` 上调为 **0.8**，
+**不改码、只传现成参数**。单关键词档 5179 条命中整体判为 **REJECT**。
+
+### 4.2 注入结果（批次 `cap_v01`）
+
+| 指标 | 注入前 | 注入后 |
+|---|---|---|
+| `nodes_with_cap` | 1 | **369** |
+| `cap_tag_total` | 1 | **398** |
+| `distinct_caps` | 1 | **26** |
+
+Top：`cap:whitebox` 59、`cap:predict` 41、`cap:route` 37、`cap:session` 25、`cap:sustain` 22 …
+（`cap:verify` 由预演的 1630 收敛到 **14**——阈值上调的直接效果。）
+只改 `frontmatter.tags`，**不动正文**；全程留痕于 `_backfill.jsonl`（`action=cap` / `batch=cap_v01`，369 条）。
+
+### 4.3 回滚验证（抽样反证，非纸面承诺）
+
+| 步骤 | 实测 |
+|---|---|
+| `op=maintain action=cap_rollback batch=cap_v01 entry_ids=[ce8b4664e9ad]`（`cap:theory`） | `reverted=1` / `tags_removed=1` / `conflict=0` / `missing=0` |
+| 随即按新批次恢复 `action=cap, apply=true, batch=cap_v01_restore, min_conf=0.8` | `planned=1` / `written=1`（其余 368 条 `skipped_present` → 幂等） |
+| 复算 | `cap_tag_total` 398 → 397 → **398**，`nodes_with_cap` 369 保持一致 |
+
+`cap_rollback` 只移除**仍在 tags 里**的标签，防覆盖后续人工修改——因此它是安全的**部分回滚**，不是整表撤销。
+
+---
+
+## 五、验收指标对照（冻结基线 vs 收口后）
+
+| 指标 | 基线（G3 注入前，G2 已完成） | 收口后 | 判 |
+|---|---|---|---|
+| `total_nodes` | 6339 | 6339 | 不变（G3 只改 tags） |
+| `code_` / `doc_` | 1480 / 333 | 1480 / 333 | 不变 |
+| `ref`（schema/files/nodes） | 2 / 116 / 1847 | 2 / 116 / 1847 | 不变 |
+| `conditions_pending` | 145（缺约束 7 + 缺三槽 138） | **145**（同上） | **未被灌水** ✅ |
+| `nodes_with_cap` / `cap_tag_total` | 1 / 1 | **369 / 398** | G3 生效 ✅ |
+| `distinct_caps` | 1 | **26** | ✅ |
+
+> 说明：基线文件冻结于 **G2 已完成之后**，故它同时充当「G2 结果」与「G3 变化量」的参照；
+> G2 自身的基线是计划前状态：`total_nodes=4526`、`cap` 仅 1 条、`_refindex.json` 存在但 1813 节点未落库。
+
+---
+
+## 六、副作用与归因（显式登记，不静默）
+
+### 6.1 召回面扩大（本轮最大代价，已知且有量化）
+
+| 口径 | 候选池 | LIKE 命中 P50 | P90 | **P95** | P99 | max | 均值 | 被 `GLOBAL_CAP=500` 截断 |
+|---|---|---|---|---|---|---|---|---|
+| 全量（含索引节点） | 6336 | 15 | 2348 | **2580** | 3437 | 5708 | 658.5 | **300/870（34.5%）** |
+| 剔除 `code_`/`doc_` | 4523 | 13 | 1343 | **1380** | 1759 | 3895 | 347.5 | **247/870（28.4%）** |
+
+**归因**：G2 的边际贡献 = P95 `1380 → 2580`（×1.87）、max `3895 → 5708`、截断率 `+6.1pp`（+53 条/870）。
+**但截断的主体（28.4%）在 G2 之前就已存在**——这不是本轮引入的问题，本轮只是把它放大了约 1/5。
+→ 处置建议（不在本轮）：索引节点应在**召回路由阶段**被降权或分池（`domain:` 标签已就位，可直接做域级路由），
+而不是继续吃 `GLOBAL_CAP`。这是 G4/G5 的输入。
+
+### 6.2 密级：**无降级**（观测工具失配，非事实变更）
+
+盘上 `frontmatter`（真相源）复算：
+
+| 口径 | private | internal | 说明 |
+|---|---|---|---|
+| 索引前 | 4525 | 1 | — |
+| 索引后（盘上） | **4525** | **1814** | 旧节点 private 计数**完全不变**；新增 1813 全部 internal |
+| `_index.json` | 4525 | 1814 | 与盘上逐字一致 |
+| 层分布 | knowledge: private 4516 / internal 1814 ｜ self: private 5 ｜ anchor: private 4 | | 新节点全部落 knowledge |
+
+**归因**：曾有 `op=info` 报 `sensitivity_counts={"internal": 6339}`，即「private 全变 internal」。经复算判定为
+**常驻服务内存视图陈旧**（进程启动早于改造，`self.index` 为旧快照），**不是**密级降级：① 盘上 private 计数与索引前完全相同；
+② `_index.json` 同口径复算一致；③ `mdcos._sensitivity_counts` 读取的正是 `index["nodes"][*]["sensitivity"]`，字段未丢。
+→ 待定项：重启 MCP 服务以统一视图（§八）。
+附：`body` 加密分布 `plain 6249 / enc 90`，未受本轮影响。
+
+### 6.3 `node_id` 跨类同名归并（既有设计缺陷，本轮首次暴露）
+
+`codeindex.node_id(item) = sha1(path + "::" + name)` —— 键**不含父类名**，故同一文件内跨类同名方法被归并为同一 id。
+实测：登记 1847 → 唯一 1813，**冗余 34 条 / 27 个 id**（占 1.8%），分布：
+
+| 源文件 | 冗余 | 已核实的同名 def |
+|---|---|---|
+| `md_cg/mdcos.py` | 12 | `__init__` `add` `_audit` `_candidates` `_neg_coverage` `search_rrf` … |
+| `md_cg/signer.py` | 4 | `sign`×3 `verify`×3 `describe`×3 `public`×2 |
+| `md_cg/sources.py` | 3 | `events`×3 `key`×3 `__init__`×4 |
+| `md_cg/sustain.py` / `whitebox.py` | 2 / 2 | `summary`、`ask`、`remember` … |
+| `md_cg/fsutil.py` / `security.py` / `test_p18_whitebox.py` / `src/index.ts` | 各 1 | `__init__` 等 |
+
+**影响有界**：后写入者胜（同 id 原子覆盖），`_refindex.json` 保留全部区间；`ref check` 全部 `ok`。
+**不本轮修**：改 id 键会破坏既有 id 稳定性与幂等，需单独立项（加 `parent` 入键 + 存量迁移，或同文件同名加序号后缀）。
+
+---
+
+## 七、回滚点
+
+| 对象 | 回滚方式 | 性质 |
+|---|---|---|
+| 代码（§二 的 3 处实现 + 3 处断言） | 反向应用 diff | 无损 |
+| cap 标签（398 条 / 369 节点） | `op=maintain action=cap_rollback batch=cap_v01` | **部分无损**：只移除仍在 tags 里的标签 |
+| 索引节点（1813 个 `code_`/`doc_`） | 按 id 删除 + 删 `_refindex.json` | **有损**：需重跑索引重建 |
+| 水位 `_refindex.json` | 直接删除即退化为全量索引 | 无损（纯派生物） |
+
+---
+
+## 八、待定项登记
+
+| # | 待定项 | 现状 | 建议动作 |
+|---|---|---|---|
+| 1 | **G7 / G8 / G4 / G5 / G6** | 未执行 | G8 已裁定：`op=link` 只对**新增节点**常态化建链、历史不回填；G4/G5/G6 待前置 |
+| 2 | `node_id` 跨类同名归并（27 id / 34 条） | 已定位成因（`path::name` 不含父类） | 单独立项，含存量迁移方案 |
+| 3 | 常驻 MCP 服务内存视图陈旧 | `op=info` 密级/cap 计数与盘上不一致 | 重启 MCP 服务（本轮为保 sustain 心跳未重启） |
+| 4 | 召回截断：34.5% 查询被 `GLOBAL_CAP` 截断 | 主体（28.4%）为存量问题 | 索引节点域级分池/降权，而非继续吃全局 cap |
+| 5 | 索引新鲜度未自动化 | 依赖手工重跑 | 上游变更后跑 `incremental` 重跑；可挂 `sustain.diagnose` 的 `ref_stale`（已接入） |
+| 6 | 基线 P95「89」口径未固化 | 无法同口径复现 | 见 §九-1 |
+
+---
+
+## 九、诚实边界
+
+1. **「触发词命中 P95 基线 89」无法同口径复现**：benchmark 自带的 `--ablate pool` 口径跑在**合成库**（1000 节点）上，
+   实测中位 8 / max 366 / 截断 0/870，与真实库不同源。本轮真实库同口径（bench 同款查询集生成：`n=250, seed=7`，
+   池 = `cg._candidates()` 读出集）复算得 P95=2580（全量）/1380（剔除索引节点）。
+   → 结论：§6.1 的**相对归因**（1380→2580、+6.1pp）可信；**绝对值与「89」不可直接比较**，因为基线口径未固化。
+2. **索引是「可索引」，不是「可理解」**：`code_`/`doc_` 是确定性静态索引，不含语义蕴含；跨表述的
+   「这段代码实现了那段文档的意思」不解决（与「有意剔除神经嵌入」的既有裁定一致）。
+3. **索引质量上限 = 源文件注释质量**：无 docstring/首段的符号只能索引到签名或标题。`docs/` 侧 `docs/` 下非 md
+   文件（`.html`/`.png`/`.yml` 等 5 类）**显式列出**而非静默丢弃，但它们确实未被索引。
+4. **cap 标签是「词面证据的保守子集」，不是能力证明**：阈值上调只把「明显不合格」挡在门外；0.8 档仍可能有个别误标
+   （规则表含宽泛词），故 `cap_rollback` 是必备出口。它**不构成**「该节点具备该 op 能力」的充分证据。
+5. **§6.3 的 27 个 id 归并意味着**：对同名方法，认知图里只能查到**一个**（后写者），另一处的正文虽在 `_refindex.json`
+   有区间记录，但不在图里可检索。这是**已知覆盖缺口**，不是本轮回归。
+6. **本轮无「dangling/unresolved=0」之外的漂移证据**：`ref check` 在索引完成的同一时刻测得，源文件此后若被改动，
+   需重跑才能判 `stale`。巡检只承诺「可检出」，不承诺「自动跟随」。
+
+---
+
+## 十、回归与留痕
+
+**回归（全部模块 `rc=0`）**：
+
+| 用例 | 结果 | 用例 | 结果 |
+|---|---|---|---|
+| `test_p21_tokens` | 31 / 0 | `test_p28_refcheck` | 45 / 0 |
+| `test_p26_refindex` | 55 / 0 | `test_p30_maintain` | 55 / 0 |
+| `test_p27_docindex` | 56 / 0 | `test_p32_backfill` | 58 / 0 |
+| `test_p33_ccg_wiring` | 58 / 0（全部通过） | `test_p37_condition_space` | 42 / 0 |
+
+**演化留痕**：`evo-20260910-155442-28f8`（索引产物的生效条件必须与唯一合成入口同源）、
+`evo-20260910-155442-7ccf`（词面命中不等于具备该能力，`min_conf` 上调为 0.8）。
+
+**派生产物**（均在仓库之外）：
+
+```
+D:/Program Files/2_ai/AEIS/data/mdcg/
+├── _refindex.json     # G2 水位（schema=2、116 源文件、1847 条登记）
+├── _backfill.jsonl    # G3 批次留痕（+369 条 action=cap / batch=cap_v01）
+├── _index.json        # 6339 节点（+1813）
+├── _evolution/ledger.md  # 本轮 2 条演化条目
+└── knowledge/         # 新增 code_ 1480 / doc_ 333 节点
+```
+
+---
+
+*证据单生成：2026-09-10 · §三~§六 全部为真实库复算结果（非估计）· 未核实项已单列 §八/§九 · 一次性临时驱动脚本已清理*