@furongjun1999/dsh-memory 0.4.5 → 0.4.7

package/docs//350/234/202/347/276/244/347/233/262/345/214/272/346/240/207/350/256/260_v1.0.md

@@ -0,0 +1,89 @@
+> **迁移注记（2026-09-13）**：本文件自 protocol-compiler 迁入灵枢大脑仓；蜂群子系统现为 `swarm/` 包（大脑核心内部能力）。
+
+# 蜂群多智能体 · 结构性盲区标记 v1.0（R4 · 2026-09-13）
+
+> 制度来源：智能论 v3.4 附录6（盲区标记先例，95 项）——协议承认结构性盲区无法被自身解决，
+> 但将持续标记和关注。本文件是蜂群多智能体架构（RUST-SWARM-REV2，v0.6-v0.7）的工程盲区登记。
+> 规则：每个设计判定单必须携带盲区声明；新盲区连续编号；状态变更须记录。
+
+## 盲区清单
+
+### BS-1：跨机网络故障域未验证
+
+**状态**：新增（2026-09-13），待跨机部署验证
+**描述**：gossip 对账（`gossip_consistent`）口径为单机投递覆盖断言——单机管道投递失败直接 Err，
+不存在静默丢消息。跨机部署引入网络分区/丢包/延迟后，水位对账才面对真实故障域，
+当前的对账逻辑与 watermarks/gossip 水位的恢复口径（在线窗口）均未经跨机检验。
+**处理方式**：跨机 federation（Peer 三 trait 抽象，A5 笔记）实施时重演全部容错验收。
+
+### BS-2：dead 分支的确定性触发缺失
+
+**状态**：已实现，端到端触发留长稳/跨机
+**描述**：实例重试仍失败的 dead 退场路径已实现（outcomes 记 None、uptime 降、蜂群继续），
+但单机下确定性触发需在重建后的极窄时序窗内二次击杀同一实例，测试不可稳定构造。
+**处理方式**：长稳测试（随机 kill 注入）或跨机网络故障场景自然覆盖。
+
+### BS-3：health/watermark 的恢复场景在线窗口口径
+
+**状态**：设计决策（诚实口径），非缺陷
+**描述**：恢复续跑后，health 四因子与 watermarks 仅统计本次会话执行的轮次（在线窗口），
+重放前轮次不重计。幂等聚合路径 health 为空对象。
+**处理方式**：如需跨会话累计口径，需将轮次终态序列持久化进快照（当前快照仅存末轮终态）。
+
+### BS-4：异构程序实例未实现
+
+**状态**：新增（2026-09-13），特性候选
+**描述**：当前 `run_swarm` 全部实例共享同一 program.pbc（单字节码路径），实例仅 id/初始符号不同。
+「不同实例执行不同术数」需要 per-instance pbc 路径——是多程序蜂群/职能异质实例的前提。
+**处理方式**：SwarmConfig.instance_programs 扩展（向后兼容：缺省共用）。
+
+### BS-5：编译器常量折叠绕过运行时除零
+
+**状态**：已确认（2026-09-13）
+**描述**：`德 1/0` 在解析层被常量折叠（编译产物为 DE 1.0），运行时 DIV 除零错误无法通过
+字面量构造。error 终态场景测试改用恒真死循环（步数超限）。
+**处理方式**：如需运行时除零语义，编译器需禁用字面量除法折叠或显式保留 DIV 指令。
+
+### BS-6：修正信号的 P0/P1 级维生介入未实现
+
+**状态**：已实现 P2（观察级），P0/P1 留真实场景
+**描述**：修正信号当前仅记录+透出（维生边界=被动安全服务端，荣 2026-09-13 裁定）。
+P1（限制敏感操作）/P0（冻结/回滚/隔离）对真实重大分歧的介入动作未实现。
+**处理方式**：出现真实重大分歧场景（跨机复算不一致/信任崩溃）时按 §3.16 实现。
+
+### BS-7：条件空间运行时切换未实现
+
+**状态**：新增（2026-09-13），声明+持久化已实现
+**描述**：条件空间卡当前为启动声明+快照持久化；运行中按 D_norm/P_trust 阈值触发切换
+（§3.1.2 流程：触发→声明→验证复核→执行→D_norm 确认→日志）未实现。
+**处理方式**：切换机制依赖 per-instance 状态与 D_norm 实时计算，随 BS-4/BS-1 一并演进。
+
+### BS-8：ruflo HNSW 性能自述未独立复测
+
+**状态**：降级（引用 A4 取证）
+**描述**：ruflo 自述 HNSW 加速倍率（N=5k 3.2-4.7×、N=20k 1.9×）与其自身默认路径
+（暴力余弦，issue #2922）矛盾，且倍率随 N 递减反常。原 C2 复测项降级为引用 A4 结论。
+**处理方式**：若未来接入向量检索（md_cg >5 万节点且语义需求明确），实施时独立复测。
+
+### BS-9：轮次屏障的通信瓶颈（智能论盲区60 的工程对应）
+
+**状态**：结构固有（BSP 模型性质）
+**描述**：轮间屏障使通信与快照落盘成为固定开销——VM 计算轻（~2ms/轮）时屏障主导延迟，
+加速比低于理论值（实测 2.38×@8 实例 vs 理论 8×）。
+**处理方式**：计算加重时自然趋近理论值；如需消除屏障等待，需引入流水线轮次（架构扩展）。
+
+### BS-10：CodeBuddy 并行工作的合并协调
+
+**状态**：新增（2026-09-13），持续观察
+**描述**：多 harness（ZCode/CodeBuddy）并行修改同一仓库时存在字段/构造的合并协调成本
+（实例：SwarmReport.condition_space 字段由 CodeBuddy 并行添加，ZCode 侧补构造共存）。
+**处理方式**：工作区提交前互相知会；字段级冲突以测试全绿为准入。
+
+## 状态图例
+
+| 状态 | 含义 |
+|---|---|
+| 新增 | 已登记，待观察/处理 |
+| 已实现，待触发 | 代码就位，端到端场景留后续 |
+| 设计决策 | 有意的诚实口径，非缺陷 |
+| 降级/已关闭 | 有替代方案或引用依据 |

package/docs//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

@@ -38,7 +38,7 @@
 
 ## 一、冻结基线（本轮实测，2026-09-10）
 
-**库根裁定**：真实库为 `D:/Program Files/2_ai/AEIS/data/mdcg`（6340 个 `.md`，6339 有 frontmatter）；
+**库根裁定**：真实库为 `AEIS/data/mdcg`（6340 个 `.md`，6339 有 frontmatter）；
 工作区 `dsh-memory/data/mdcg` 实测仅 **1** 个节点（`python -m md_cg.census` 输出 `总节点: 1`），**非本批对象**，不参与。
 → 这一条必须先声明，否则「库根写错」会让所有后续计数与判定失效。
 
@@ -113,7 +113,7 @@
 
 ## 三、G5 裁定：视觉证据未落 → 守卫式证据回填（ACCEPT，条件=脱敏 + 只读 AEIS）
 
-**证据源（AEIS 侧，全部只读；`D:/Program Files/2_ai/AEIS` 为异仓，不得写入）**
+**证据源（AEIS 侧，全部只读；`AEIS` 为异仓，不得写入）**
 
 | 资产 | 位置 | 用途 |
 |---|---|---|

package/docs//350/256/244/347/237/245/345/233/276_/346/235/241/344/273/266/347/251/272/351/227/264/345/220/210/346/210/220/344/270/216/347/224/237/346/225/210/346/235/241/344/273/266/345/217/243/345/276/204_v0.1.md

@@ -314,12 +314,12 @@ CONDITION_SLOTS = (
 ```bash
 # 只读预演：清洗计划 + 待补台账（不写盘）
 python -X utf8 -c "from md_cg.mdcos import MdCGOS; from md_cg import backfill; \
- cg=MdCGOS(r'D:/Program Files/2_ai/AEIS/data/mdcg'); \
+ cg=MdCGOS(r'AEIS/data/mdcg'); \
  print(backfill.fix_conditions_plan(cg)); print(backfill.conditions_pending(cg)['by_missing'])"
 
 # 复算：弱等价残留 / 合成来源 / 缺失清单
 python -X utf8 -c "from md_cg.mdcos import MdCGOS; from md_cg import backfill; \
- cg=MdCGOS(r'D:/Program Files/2_ai/AEIS/data/mdcg'); print(backfill.verify_conditions(cg))"
+ cg=MdCGOS(r'AEIS/data/mdcg'); print(backfill.verify_conditions(cg))"
 
 # 回滚（按批次，当前值一致才撤销）
 #   fix_conditions_rollback(batch="cond_fix_v01") / rollback(batch="cond_full_v01")

package/docs//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

@@ -144,10 +144,10 @@ judge_qualification(mdcg.py:709-714)
 
 | 文件 | 动作 | 职责 |
 |---|---|---|
-| `md_cg/refindex.py` | **新增** | ref 协议常量 + 提取器注册表 + 统一 `index_dir` 调度 + `_refindex.json` 增量 + `check_refs()` 漂移巡检 + `read_ref()` 回读 |
-| `md_cg/docindex.py` | **新增** | `.md` 章节切块：ATX 标题栈、heading_path、行号区间、首段摘要、anchor |
-| `md_cg/codeindex.py` | **改造** | ①`render()` 改产 CCG 5 要素（修 B）②后缀注册化（`.py` 走 AST、`.ts/.js` 走弱提取器）③`index_dir` 返回 `truncated` 与 `files_scanned`（修 F）④`node_id` 保持稳定（重复索引幂等） |
-| `md_cg/mcp_server.py` | **扩** | 新增 `op=ref`（`action=read\|check\|stat`，兼回读与巡检）；`op=index_code` 保留为别名并透传 `truncated`；`op=index_doc`；op 枚举与 `:542-546` 同步 |
+| `md_cg/refindex.py` | **新增** | ref 协议常量 + 提取器注册表 + 统一 `index_dir` 调度 + `_refindex.json` 增量 + `check_refs()` 漂移巡检 + `read_ref()` 回读 + **节点级对账** `prune_orphans()`（过期代）/ `prune_dangling()`（悬空）（R3.1）+ `skip_dirs` 透传（R3.2） |
+| `md_cg/docindex.py` | **新增** | `.md` 章节切块：ATX 标题栈、heading_path、行号区间、首段摘要、anchor；`skip_dirs` 追加排除（R3.2，复用 `codeindex.skip_matcher`） |
+| `md_cg/codeindex.py` | **改造** | ①`render()` 改产 CCG 5 要素（修 B）②后缀注册化（`.py` 走 AST、`.ts/.js` 走弱提取器）③`index_dir` 返回 `truncated` 与 `files_scanned`（修 F）④`node_id` 保持稳定（重复索引幂等）⑤`skip_matcher()` + `skip_dirs`（R3.2，两条链路的唯一实现） |
+| `md_cg/mcp_server.py` | **扩** | 新增 `op=ref`（`action=read\|check\|stat\|prune`，兼回读 / 巡检 / 清退）；`op=index_code` 保留为别名并透传 `truncated`；`op=index_doc`；op 枚举与 `:542-546` 同步；`index_code`/`index_doc` 索引后自动节点级对账（`prune` 默认开、`prune_dry_run` 可预演，R3.1）；`skip_dirs` 透传 + `skipped_dirs` 回报（R3.2） |
 | `md_cg/tokens.py` | **改** | `ALL_OPS`(`:56-59`) 加 `ref` / `index_doc`（漏改会被权限层直接拒），`test_p21_tokens.py` 同步 |
 | `md_cg/sustain.py` | **扩** | `diagnose` 增巡检项 `ref_stale` / `ref_dangling`，`heal` 动作为「重建索引」（派生物，符合现有自愈边界 `:12-14`） |
 | `md_cg/mdcos.py` | **扩** | 检索结果带 `ref` 与 `ref_kind`（读侧不改召回逻辑，只加字段） |
@@ -163,6 +163,8 @@ judge_qualification(mdcg.py:709-714)
 | **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` | ✅ |
 | **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 模块全绿 | ✅ |
 | **R4** | 修 H：code↔doc 互链（文档中出现的符号名/路径 → 建边指向 code 节点；反向亦然） | 「某功能」检索能同时给出代码位置与文档位置 | ⬜ |
 | **R5** | 修 I（工程规范化产出，见 §九） | 三份索引文件可由 `index_ref` **自动生成**，非手写 | ⬜ |
 | DEFER | `.ps1/.vbs/.yml` 提取器；跨副本身份下的 ref 可见性 | 先决：R4 完成且互链被实际使用 | ⬜ |
@@ -493,4 +495,94 @@ md 不是代码，切块风险集中在「把不该当标题的当标题」。
 
 ---
 
-*计划生成：2026-09-10 · 证据：§一 全部为源码行级核对结果 · 未核对项已单列 §1.3 / §十 · §十一 为 R0 实测取证 · §十二 为 R1 实测取证 · §十三 为 R2 实测取证 · §十四 为 R3 实测取证*
+## 十五、R3.1 / R3.2 取证纪录（已完成 · 2026-09-12）：节点级对账 + 索引追加排除
+
+> **为什么单开一节而不并进 R3**：R3 只做了**水位层**对账（`Ledger.reconcile`/`prune` 剪的是 `_refindex.json` 的水位条目），
+> **节点层**两类残留无人处置——`node_id = sha1(相对路径 + "#" + heading_path)`，文档标题一变整篇 id 全量重算，
+> 于是同 path 的旧代节点与新代节点并存（一份文档召回两份）；源文件一删，节点永久 `dangling`。
+> §十四 验收项 5 的原话是「删源报 `dangling`」——**悬空当时只承诺「可检出」，本节补上「可处置」**。
+
+### 15.1 交付物与改动清单
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `md_cg/refindex.py` | **扩** | 节点级对账节：`_norm_root`/`_same_root`/`_norm_rel`（大域与路径归一）+ `_forget_many`（逐条软删、受保护拦下、缺 `forget` 能力显式报错）+ `prune_orphans`（清退同 root+path 的过期代）+ `prune_dangling`（清退悬空） |
+| `md_cg/mcp_server.py` | **扩** | `op=ref` 增 `action=prune`/`prune_dangling`；`index_code`/`index_doc` 返回前接 `_prune_after_index`（读 `prune` 默认 True、`prune_dry_run` 预演）；schema 增 `prune`/`prune_dry_run`/`roots` |
+| `md_cg/test_p27_docindex.py` | **扩** | 新增【10】节点级对账、【10b】悬空清退；`cg` 由 `MdCG` 改 `MdCGOS`（对齐生产路径） |
+
+### 15.2 两个真实缺陷（首轮实测暴露，逐条留证）
+
+1. **对账静默假成功（严重）**：`cg.index['nodes']` 是 `mdcg._scan_nodes()` 产出的**元数据快照**（path/layer/tags/importance/edges…），**不含 `ref`**——`ref` 只写在节点 frontmatter 里。首版直接对索引条目调 `ref_of()`，**恒返回 `('', None)`**，于是「清退了 0 条」却报 `ok=True`。实测 `prune_orphans count=0`、`prune_dangling candidates=0`。
+   → 改为 `node = cg.get(nid)` 取回节点再 `ref_of(node)`，并加 `doc`/`code` 标签预筛（与 `check_refs` 同口径，免得为全库每条记忆都读一次盘）。
+2. **`forget` 能力分层被忽略**：`forget` 属 **`MdCGOS` 层**（保护裁决 + 回收站 + 删除清单），基础层 `MdCG` 没有任何删除原语。首版测试用 `MdCG(ROOT)`，实测 `'MdCG' object has no attribute 'forget'`。
+   → ①`_forget_many` 缺能力时**显式返回错误、不静默跳过**（文案点名「生产路径是 MdCGOS，测试请用 MdCGOS」）；②测试改 `MdCGOS` 构造。
+   → 与 P43 的教训同构：**双实现类（`MdCG`/`MdCGOS`）必须双路覆盖**，只测一条路径等于留静默盲区。
+
+### 15.3 三条保守约束（宁可不删，不可误删）
+
+- **只清「本次真正重切过」的文件**：`prune_orphans` 的判定范围限于 `items` 里的 path；增量索引跳过的未变文件不进判定——否则会把完好节点整片误删。
+- **截断轮次不清退**：没扫完 ≠ 剩下的都过期。`_prune_after_index` 见 `truncated=True` 直接返回，不算、不删。
+- **探测失败不算悬空**：`probe_ref` 抛异常即跳过，不把「读不到」当成「源已删」。
+
+### 15.4 真实现场处置（`AEIS/data/mdcg`）
+
+常驻 MCP 进程加载的仍是旧代码（`op=ref` 只认 `read|check|stat`），故按**工作纪律第7条**走等价兜底：python 直调同一模块（身份从 CodeBuddy `mcp.json` 读取，不落盘、不回显令牌）。
+
+| 步骤 | 命令 | 实测 |
+|---|---|---|
+| 巡检 | `op=ref action=check max_nodes=20000` | `checked=5456`、`dangling=20`、`stale=42`、`truncated=false` |
+| 预演 | `action=prune_dangling dry_run=true` | `scanned=10136`、`candidates=20`、`count=20` |
+| 清退 | `action=prune_dangling`（designer 身份，`can_admin=true`） | `count=20`，全部软删进 `trash/` |
+| 复核 | 同 `dry_run` 再跑 + 落盘核对 | `candidates=0`；20 个 `node_id` **`LIVE_HITS=0` / `TRASH_HITS=20`**；`trash/` 与 `_deletions.jsonl` 均 36 条 |
+
+悬空来源单一：4 个已删的临时脚本（`_tmp_v3check.py`×2、`cmp_rows.py`×4、`dump_rows.py`×2、`vision.py`×12），非业务记忆，清退无信息损失且可 `op=restore` 回滚。
+
+### 15.5 诚实边界（R3.1 新增）
+
+1. **对账是 O(带标签节点数) 次读盘**：`ref` 不在索引快照里，只能逐节点 `cg.get()`。每次 `index_code`/`index_doc` 都会带上这一遍开销（本仓 ~500 节点级、现场 10k 节点级；后者秒级但非零成本）。若成热点，正解是把 `ref` 摘要进 `_scan_nodes` 快照，而非放松判定。
+2. **只处置「孤儿」与「悬空」，不处置 `stale`**：漂移（源已改）用重建解决（重跑索引或 `sustain.heal`），不靠清退——删掉再索引等于绕远路。
+3. **`stale` 与「孤儿」判据不同**：孤儿靠 `node_id` 重算比对（结构性），不看内容哈希；内容已变但 id 未变的节点不属孤儿。
+4. **本仓 `test_p27` §9 的计数断言曾在本机为红**（`files=500/2388`，唯一失败项，非 R3.1 改动引起）：`.gitignore` 已整目录忽略的 `docs/experiments/`（实测 2358 个 md 于 `docs/experiments/md-cg-gate-probe/`）物理仍在盘上，把 `docs/` 从 30 个 md 撑到 2388，越过 `max_files=500`。**处置口径已裁定并落地 → 见 §15.7（R3.2）**：给索引器加**追加排除**，而非调大上限。裁后 §9 由 `500/2388` 转为 `30/30` 全绿。
+
+### 15.6 回归（R3.1）
+
+受影响面 7 模块：`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p28_refcheck` 45/0、`test_p2_mcp` 63/0 **全绿**；`test_p27_docindex` **68/1**（当时唯一红项为 §15.5-4 的环境事实，非代码缺陷）。
+
+### 15.7 R3.2：`skip_dirs` 追加排除（原 §15.5-4 的裁定落地）
+
+**问题**：索引的「扫描范围」只有**下限**（`SKIP_DIRS` 硬编码）没有**上限**——`.gitignore` 已整目录忽略的实验产物物理仍留在盘上，就照样被扫。本仓 `docs/` 真实内容 30 个 md，被 `docs/experiments/` 的 2358 个撑到 2388，直接压爆 `max_files=500`。此前唯一的应对是「调大 `max_files`」，那是**掩盖**：上限调到 2500，下次再多一批产物同样爆。
+
+**交付物**：
+
+| 文件 | 动作 | 职责 |
+|---|---|---|
+| `md_cg/codeindex.py` | **扩** | `skip_matcher(skip_dirs)` → `(hit, rules)`；`index_dir(..., skip_dirs=None)` 在 `os.walk` 处**追加**剪枝；`stats` 增 `skip_dirs`（规则回显）/ `skipped_dirs`（实际排掉的目录） |
+| `md_cg/docindex.py` | **扩** | 同签名同语义，复用 `codeindex.skip_matcher`（**唯一实现**，避免两条链路口径漂移） |
+| `md_cg/refindex.py` | **扩** | `index_dir(..., skip_dirs=None)` 透传给底层 |
+| `md_cg/mcp_server.py` | **扩** | `index_code`/`index_doc` 透传 `skip_dirs`；`_skip_dirs_report()` 把「排掉了什么」压成 `skipped_dirs` / `skipped_dirs_count` / `skip_dirs` 回报；schema 增 `skip_dirs` |
+| `md_cg/test_p27_docindex.py` | **扩** | §9 改用 `skip_dirs=["experiments"]`；新增 §9b 专测匹配口径 / 只增不减 / 可审计 |
+
+**三条设计裁定**：
+
+1. **只增不减**：`skip_dirs` 在 `SKIP_DIRS` **同一处**生效，调用方只能追加，**不能关掉** `.git`/`.venv`/`node_modules` 这类内置保护——否则一次参数写错就能把版本库元数据索引进认知图。
+2. **排除不许静默**（与「截断不许静默」同一纪律）：命中目录写进 `stats["skipped_dirs"]`（就地追加、不依赖末尾汇总，所以**截断提前 return 时也带得走**），MCP 层再压成可读回报。调用方据此能把「源文件真的少了」与「被规则排掉了」区分开。
+3. **两类匹配口径可混用**：含 `/` 按**相对 root 的路径**（`docs/experiments` 只排这一处）；不含 `/` 按**目录名**（`experiments` 排任意层级同名目录）。反斜杠 / 首尾斜杠先归一——否则「规则传了却不生效」又是一次静默失配。默认 `None` 时 `hit is None`、走原路径，**行为与改造前逐字一致**（同 `fresh`/`on_file` 纪律）。
+
+**实测**（`test_p27` §9 / §9b）：
+- 本仓 `docs/`：`files=30/30`、`truncated=false`，`skipped_dirs=['experiments']`（此前 `files=500/2388` 已截断）。
+- 合成树（`keep.md` + 两层 `experiments/*` + `sub/experiments/y.md` + `node_modules/pkg/n.md`）：不给规则 → `files=4`「内置排除照旧」；`skip_dirs=["experiments"]` → `files=1` 且 `skipped=['docs/experiments','sub/experiments']`（**同时证明 `node_modules` 仍被排，即只增不减**）；`skip_dirs=["docs/experiments"]` → `files=2` 只排这一处；`skip_dirs=["docs\\experiments\\"]` → `files=2`（归一后仍生效）。
+
+### 15.8 诚实边界（R3.2 新增）
+
+1. **按路径的规则不跨 root**：`docs/experiments` 是「相对本次 root」的路径，换个 root 就不再匹配；跨仓复用规则要用不含 `/` 的目录名形式。
+2. **同名目录一网打尽**：`skip_dirs=["experiments"]` 会排掉**任意层级**的同名目录。这正是它对 `2_ai` 那种多子项目树好用的原因，但也意味着「只想排一处」必须写全路径。
+3. **排除只影响扫描，不清理既有节点**：已在库、但本次被排掉的目录里的节点**不会**因此消失（`prune_orphans` 的判定范围限于本次真正重切过的 path，见 §15.3-1）。若要清掉，需先不带 `skip_dirs` 跑一次让它们成为孤儿，或直接 `prune_dangling`。
+4. **`max_files` 仍是安全上限而非目标值**：`skip_dirs` 解决「噪声挤占额度」，不解决「真实内容超过 500」——真超了应当**调大 `max_files`**（那是真实内容），而不是继续加排除。
+
+### 15.9 回归（R3.2）
+
+受影响面 10 模块**全绿**：`test_p2_mcp` 63/0、`test_p9_forget_protect` 37/0、`test_p14_sustain` 44/0、`test_p21_tokens` 31/0、`test_p26_refindex` 55/0、`test_p27_docindex` **75/0**、`test_p28_refcheck` 45/0、`test_p29_session_ingest_export` 48/0、`test_p30_maintain` 55/0、`test_p32_backfill` 58/0。改动文件 lint 0 错误。
+
+---
+
+*计划生成：2026-09-10 · 证据：§一 全部为源码行级核对结果 · 未核对项已单列 §1.3 / §十 · §十一 为 R0 实测取证 · §十二 为 R1 实测取证 · §十三 为 R2 实测取证 · §十四 为 R3 实测取证 · §十五 为 R3.1 / R3.2 实测取证*

package/dsh/README.md

@@ -0,0 +1,49 @@
+# DSH 端 · 灵枢插件配置
+
+本目录 = **DeepSeek Harness（DSH）harness 专属配置**。与 `codebuddy/`、`zcode/` 平级，
+共享层（`md_cg/` 大脑、`data/`、`docs/`、`scripts/`）在仓库根。
+
+## 目录内容
+
+| 文件 | 作用 |
+|---|---|
+| `cordis.patch.yml` | 插件 **bundle 入口**（`package.json` 的 `dsh.bundle.patch` 指向本文件；裸 insert 声明） |
+| `cordis.yml.example` | 插件配置示例（30+ 项：mdcg / memory / mutual / capability …） |
+| `cordis-patch-profile-web.example.yml` | profile `web` 的 config override **备份模板**（换 profile / 重装 / 升级后须核对仍在） |
+| `dsh-web-start.bat` | DSH web 宿主启动脚本（带 8GB heap 保护，防启动 OOM） |
+
+## 安装
+
+```bash
+git clone https://github.com/FuRongJun-1999/dsh-memory.git
+cd dsh-memory
+npm install && npm run build          # tsc → lib/
+dsh plugin --profile web add .        # 必须走 dsh plugin，勿用裸 npm install 装进 profile
+```
+
+再参照 `cordis.yml.example` 在 `<profile>/cordis.yml` 启用配置。
+
+## 纪律注入（personaPrefix 受管块）
+
+DSH 端的 16 条工作纪律**不走独立文件**，而是以 `compact` 变体写入
+`~/.dsh/profiles/web/cordis.patch.yml` 的 `personaPrefix` 键，用受管标记块 `lingshu:discipline`
+原地修订（保留注释）：
+
+```
+python scripts/render_discipline.py --target dsh --write
+python scripts/verify_discipline.py --target dsh
+```
+
+> DSH 的 `personaPrefix` 是**每轮注入**的系统提示槽位，因此用 `compact` 变体；
+> CodeBuddy / ZCode 是**会话起始注入**，用 `full` 变体。三角色同源于
+> `docs/工作纪律_认知图条目_v1.1.json`，矩阵见 `docs/discipline/harnesses.yaml`。
+
+## 与「三层拆分规划」的关系
+
+本目录是**按 harness 维度**（DSH / CodeBuddy / ZCode）归置配置；
+[`../docs/灵枢三层拆分规划_v0.1.md`](../docs/灵枢三层拆分规划_v0.1.md) 讨论的是**另一种正交维度**
+（灵 / 脑 / 身 三仓职责分离，目标是主仓瘦身）。
+
+二者在 `dsh-web-start.bat` 上存在**归属分歧**：三层规划拟将其移出主仓至「身体仓（宿主启动）」，
+而本目录按 harness 维度将其收拢。该分歧**留待三层规划 Phase 裁决收敛**——本目录为其当前的
+可追踪落点，不改变三层规划的结论。

package/dsh/dsh-web-start.bat

@@ -0,0 +1,17 @@
+@echo off
+rem ============================================================
+rem dsh-web-start.bat —— 启动 DSH web（带 8GB heap 保护，防启动 OOM）
+rem
+rem 背景：灵枢 embedding 权重加载 + dsh-bridge + 记忆注入在启动时
+rem 同时分配，默认 4GB heap 偶发 OOM。此脚本用 8GB 上限规避。
+rem
+rem 用法：双击或命令行运行；首次运行后浏览器访问 http://127.0.0.1:3080
+rem ============================================================
+setlocal
+rem 用当前用户环境变量解析，不写死机器/用户名（换台机器 clone 也能直接跑）
+set DSH_HOME=%USERPROFILE%\.dsh
+set NODE_OPTIONS=--max-old-space-size=8192
+
+echo [dsh-web] 启动 DSH web（heap 8GB）...
+node "%APPDATA%\npm\node_modules\@deepseek-ai\dsh\lib\bin.js" web
+endlocal

package/lib/bridge.js

@@ -185,7 +185,9 @@ export class LingshuBridge {
                 this.unexpectedExits = this.unexpectedExits.filter((t) => Date.now() - t < 600_000);
                 this.unexpectedExits.push(Date.now());
                 if (uptimeS >= 0 && uptimeS < 5) {
-                    console.error('[lingshu-bridge] 进程启动后 5 秒内即退出——请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检）。');
+                    console.error('[lingshu-bridge] 进程启动后 5 秒内即退出——请检查 python 可执行文件与 md_cg 依赖。' +
+                        '自检 `python -m md_cg.mcp_server` 须在插件包根目录运行' +
+                        '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12）。');
                 }
                 else if (this.unexpectedExits.length >= 3) {
                     console.error(`[lingshu-bridge] 10 分钟内已意外退出 ${this.unexpectedExits.length} 次，` +
@@ -244,7 +246,8 @@ export class LingshuBridge {
             this.readyState = 'failed';
             this.flushBootQueue(false);
             console.error(`[lingshu-bridge] 连续启动失败 ${this.retries} 次，已停止自动重启（不再后台空转）。` +
-                '请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检），修复后在 DSH 中重新启用 dsh-memory 插件。');
+                '请检查 python 可执行文件与 md_cg 依赖；自检 `python -m md_cg.mcp_server` 须在插件包根目录运行' +
+                '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12），修复后在 DSH 中重新启用 dsh-memory 插件。');
             probe(`give up: ${this.retries} consecutive failures, entering failed terminal state`);
             return;
         }
@@ -270,7 +273,7 @@ export class LingshuBridge {
         // issue #6：放弃终态下快速失败——之前进程不在且不再重启，请求只能白等超时
         if (this.gaveUp) {
             return Promise.reject(new Error('灵枢进程不可用：连续启动失败已达上限，已停止重试。' +
-                '请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检），修复后重新启用 dsh-memory 插件。'));
+                '请检查 python 可执行文件与 md_cg 依赖（自检 `python -m md_cg.mcp_server` 须在插件包根目录运行），修复后重新启用 dsh-memory 插件。'));
         }
         const id = this.nextId++;
         const timeout = this.options.timeoutMs;

package/lib/hooks.js

@@ -62,7 +62,8 @@ export function desensitize(text) {
     return out;
 }
 /** 时间线载荷 → 注入文本。
- *  `stg(op=timeline)` 返回 {count, limit, items:[{id, layer, start, end, preview}]}。 */
+ *  `stg(op=timeline)` 返回 {count, limit, items:[{id, layer, start, end, preview}]}。
+ *  （保留原始实现；自动召回改用下面的分级递减渲染） */
 function formatTimeline(payload) {
     const items = (payload && typeof payload === 'object'
         && Array.isArray(payload.items))
@@ -79,6 +80,63 @@ function formatTimeline(payload) {
         .filter(Boolean)
         .join('\n');
 }
+// ---------------------------------------------------------------- 自动召回渲染
+// 常量写死在此处（而非 config schema）——未知键会被 schema 剥离。
+/** 第 1 档（最新 1 条）每条字符上限。 */
+const RECALL_BASE_CHARS = 160;
+/** 每 N 条降一档。 */
+const RECALL_DECAY_EVERY = 1;
+/** 每档缩放比例（−10%）。 */
+const RECALL_DECAY_RATIO = 0.9;
+/** 最小保留字符。 */
+const RECALL_MIN_CHARS = 24;
+/** 整块上限（与调用点 slice 对齐）。 */
+const RECALL_MAX_CHARS = 1400;
+/** 永久层不自动注入（按需用 mdcg_recall / lingshu_stg 取）。 */
+const RECALL_SKIP_LAYERS = new Set(['anchor', 'self']);
+/** 连续跳过多少步后强制补一次（内容未变也刷新，防止压缩归档后块消失）。 */
+const RECALL_REPUSH_EVERY = 8;
+/** 分级递减渲染：按距当前的次序逐档收窄，早期条目信息量更大。
+ *
+ *  动机：注入块总长受限，而"最近 N 条"里越靠前的越可能被用到；线性等宽分配
+ *  会让整块被最旧的一条挤掉。逐档递减后整块实测约 1133 字符（≈472 tok），
+ *  9 条全部保留。（注意：整块仍远小于一条知识节点 500~800 tok，故本块定位是
+ *  「存在性索引/提醒」，不承载知识本身——要知识请显式 mdcg_recall 并给足预算。） */
+function formatTimelineDecayed(payload) {
+    const items = (payload && typeof payload === 'object'
+        && Array.isArray(payload.items))
+        ? payload.items
+        : [];
+    const out = [];
+    let rank = 0;
+    for (const it of items) {
+        const layer = String(it['layer'] ?? '');
+        if (RECALL_SKIP_LAYERS.has(layer))
+            continue;
+        const preview = String(it['preview'] ?? '').replace(/\s+/g, ' ').trim();
+        if (!preview)
+            continue;
+        const tier = Math.floor(rank / RECALL_DECAY_EVERY);
+        const budget = Math.max(RECALL_MIN_CHARS, Math.round(RECALL_BASE_CHARS * Math.pow(RECALL_DECAY_RATIO, tier)));
+        out.push(`- [${layer}] ` + (preview.length > budget ? preview.slice(0, budget) + '…' : preview));
+        rank += 1;
+        if (out.join('\n').length >= RECALL_MAX_CHARS)
+            break;
+    }
+    return out.join('\n').slice(0, RECALL_MAX_CHARS);
+}
+/** 去重：内容与上次相同就不再 push 新副本。
+ *
+ *  背景：本钩子挂在 `system-prompt/assemble` 上，每个 step 都会 push 一份，而每份
+ *  都会留成独立的 surface 节点 → 同一块累积 N 份（实测 11 份 ≈2700 tok/请求），
+ *  随步数线性增长。去重后同一块只占 1 份，外加每 RECALL_REPUSH_EVERY 步一次自愈刷新。 */
+function shouldPushRecall(text, lastText, skippedSincePush) {
+    if (!text)
+        return false;
+    if (text !== lastText)
+        return true;
+    return skippedSincePush >= RECALL_REPUSH_EVERY;
+}
 /** 安装自动记忆钩子（effect 作用域内，随插件卸载自动移除）。
  *
  *  mdcg 为 null（config.mdcg.enabled=false）时自动记忆整体停用：记忆真源是
@@ -108,17 +166,25 @@ export function installMemoryHooks(ctx, mdcg, opts) {
     // 用 system-prompt/assemble 事件（waterfall）而非 llm/stream——后者请求 deep-frozen 不可改写。
     if (opts.autoRecall) {
         const recallLimit = Math.max(1, Math.min(10, opts.autoRecallLimit || 4));
+        // 去重状态：同一块内容只保留一份 surface 节点，避免随步数线性增长。
+        let lastRecallText = '';
+        let skippedSincePush = 0;
         ctx.on('system-prompt/assemble', async (assembly, _ctx, next) => {
             try {
                 // 异步取最近记忆节点（失败静默——不阻塞模型请求）
                 if (graph.isReady()) {
-                    const text = formatTimeline(await graph.timeline(recallLimit));
-                    if (text) {
+                    const text = formatTimelineDecayed(await graph.timeline(recallLimit));
+                    if (shouldPushRecall(text, lastRecallText, skippedSincePush)) {
+                        lastRecallText = text;
+                        skippedSincePush = 0;
                         assembly.contexts.push({
                             name: 'lingshu:auto-recall',
-                            text: `【灵枢最近记忆】\n${text.slice(0, 600)}`,
+                            text: `【灵枢最近记忆】\n${text.slice(0, RECALL_MAX_CHARS)}`,
                         });
                     }
+                    else {
+                        skippedSincePush += 1;
+                    }
                 }
             }
             catch { /* 静默：召回失败不影响请求 */ }

package/lib/index.js

@@ -51,6 +51,8 @@ import { installMemoryHooks } from './hooks.js';
 import { installRoleplayWeb } from './lib/roleplay_web.js';
 import { MdcgClient } from './lib/mdcg_client.js';
 import { describeDataPaths, mdcgRoot } from './lib/datapath.js';
+// 写入凭据密钥环（首启引导）：显式配置 → ~/.mdcg/token → 首启自动签发。
+import { resolveToken } from './lib/token_store.js';
 /**
  * 调试探针：记录 apply 失败到独立文件（绕过 DSH 日志系统）。
  * 路径从用户家目录动态解析（issue #5，与 bridge.ts 同因同修）。
@@ -103,9 +105,10 @@ export const Config = z.object({
     maxRetryDelayMs: z.number().default(30_000),
     failOnStartupError: z.boolean().default(false),
     /** 角色扮演入口按钮（issue #8）：注入 dsh 首页右上角浮动入口；
-     * 关闭后不注入（/roleplay 页面仍可直接访问）。按钮本身支持拖动，
+     * **默认关闭**：该功能尚未开放，右上角浮动按钮会遮挡 GUI 侧边栏；
+     * 显式设 true 才注入；/roleplay 页面仍可直接访问。按钮支持拖动，
      * 位置记忆在浏览器 localStorage。 */
-    roleplayEntryButton: z.boolean().default(true),
+    roleplayEntryButton: z.boolean().default(false),
     /** 互维维护（v1.1）：心跳 10min / 任务验证双通道。 */
     mutual: z
         .object({
@@ -155,9 +158,29 @@ export async function apply(ctx, config) {
     // 提供完整认知面。插件侧唯一显式入口：src/lib/mdcg_client.ts（一方法 = 一条 MCP 调用）。
     let mdcg = null;
     let brainReady = false;
+    /** 写入凭据解析结果（首启引导；诊断与启动日志用）。 */
+    let cred = null;
     /** 记忆真源解析结果（「新写入去哪」）——用户可改：env > paths.json > 配置 > 默认自身仓 data/。 */
     const resolvedRoot = mdcgRoot(config.mdcg.root);
     if (config.mdcg.enabled) {
+        // ── 写入凭据解析（首启引导）：显式配置 → 密钥环 → 首启自动签发 ──
+        // 为什么需要：md_cg 无令牌即降级只读 guest，自动记忆 / 转录 / 角色落图
+        // **静默不落盘**——「装好了插件，但记忆永远是空的」是最难定位的失效形态。
+        // 解析顺序与「自动签发不降低实际安全强度」的论证见 lib/token_store.ts 文件头。
+        // legacy env 认证本就等价于「已显式授权」→ 不再签发，避免多签一枚无用令牌。
+        const legacyAuth = config.env.MDCG_LEGACY_ENV_AUTH ?? process.env.MDCG_LEGACY_ENV_AUTH;
+        const resolution = resolveToken({
+            python: config.python,
+            configured: config.env.MDCG_TOKEN,
+            actor: config.mdcg.actor,
+            clearance: config.mdcg.clearance,
+            autoIssue: !legacyAuth,
+        });
+        cred = resolution;
+        // 注入子进程 env：显式配置与密钥环都在此汇合成**唯一**的 MDCG_TOKEN。
+        const mdcgEnv = { ...config.env };
+        if (resolution.token)
+            mdcgEnv.MDCG_TOKEN = resolution.token;
         mdcg = new MdcgClient({
             python: config.python,
             args: config.moduleArgs,
@@ -166,7 +189,7 @@ export async function apply(ctx, config) {
             tenant: config.mdcg.tenant,
             clearance: config.mdcg.clearance,
             identity: config.identity,
-            env: config.env,
+            env: mdcgEnv,
             timeoutMs: config.toolCallTimeoutMs,
             maxRetryDelayMs: config.maxRetryDelayMs,
         });
@@ -185,17 +208,25 @@ export async function apply(ctx, config) {
             ctx.logger.warn(`dsh-memory: 认知图未就绪（MDCG_ROOT=${resolvedRoot}），`
                 + '核验按白箱纪律 fail-closed；桥将后台重连并在就绪后补注册工具。');
         }
-        // 写入凭据检查（fail-closed，且**默认关闭**）：md_cg 身份优先级
-        // ① MDCG_TOKEN ② MDCG_LEGACY_ENV_AUTH=1 ③ 都没有 → 只读 guest。
-        // 默认即第 ③ 种：读 / 召回 / 时间线照常，但自动记忆、转录、角色落图**不落盘**。
-        // 是否打开写权限由用户自行决定（见 cordis.yml.example 的「写入凭据」段），
-        // 插件不代为注入任何凭据，只在启动时告警——避免「看起来在记忆、其实没落盘」。
+        // 写入凭据检查（fail-closed）：凭据来源已由 token_store 解析（见上）。
+        // ① 显式配置 / 密钥环 / 首启自动签发 → 可写；② 都不行 → 只读 guest，必须告警。
+        // 告警仍是硬要求：guest 下读 / 召回 / 时间线照常，但自动记忆、转录、
+        // 角色落图**不落盘**——不吭声就是「看起来在记忆、其实没落盘」。
         const authEnv = { ...process.env, ...config.env };
-        if (!authEnv.MDCG_TOKEN && !authEnv.MDCG_LEGACY_ENV_AUTH) {
-            ctx.logger.warn('dsh-memory: 未配置认知图写入凭据（默认关闭），以只读 guest 运行——'
+        if (!cred.token && !authEnv.MDCG_LEGACY_ENV_AUTH) {
+            ctx.logger.warn('dsh-memory: 认知图写入凭据不可用，以只读 guest 运行——'
                 + '读 / 召回 / 时间线可用，但自动记忆、转录、角色落图不会落盘。'
-                + '要打开：签发令牌 MDCG_TOKEN（推荐）或设 MDCG_LEGACY_ENV_AUTH=1，'
-                + '经 config.env 注入，见 cordis.yml.example。');
+                + (cred.note ? `原因：${cred.note}。` : '')
+                + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 dsh/cordis.yml.example），'
+                + '或删除密钥环后重启以重新自动签发。');
+        }
+        else if (cred.source === 'issued') {
+            // 首启引导：自动签发是**改变用户可写权限**的动作，必须留痕（含关闭/吊销方式）。
+            ctx.logger.info(`dsh-memory: ${cred.note}`);
+        }
+        else {
+            ctx.logger.info(`dsh-memory: 认知图写入凭据来源=${cred.source}（密钥环 ${cred.keyringPath}）`
+                + '——自动记忆 / 转录 / 角色落图已开启');
         }
     }
     else {

package/lib/lib/datapath.d.ts

@@ -12,5 +12,15 @@ export declare function dataRoot(): string;
  * @param configured 插件配置项 `mdcg.root`；空串/未给=None 表示未指定，走默认。
  */
 export declare function mdcgRoot(configured?: string): string;
+/**
+ * Python 子进程的 PYTHONPATH 值（issue #12）。
+ *
+ * Python 启动 `-m` 时只把 **cwd** 注入 sys.path——DSH 宿主在插件仓外启动时
+ * `python -m md_cg.mcp_server` / `python -m md_cg.tokens` 必然
+ * ModuleNotFoundError。cwd 与 PYTHONPATH 双保险：后者不依赖 cwd，即使调用方
+ * 显式覆盖了启动参数/工作目录也兜得住。顺序：仓根在前（优先随包 md_cg，
+ * 防宿主环境同名旧包抢先），进程既有 PYTHONPATH 在后。
+ */
+export declare function pythonPathValue(): string;
 /** 当前解析快照（供启动日志留痕——把「记忆真源在哪」写进可审计痕迹）。 */
 export declare function describeDataPaths(configured?: string): Record<string, string | boolean>;

package/lib/lib/datapath.js

@@ -17,7 +17,7 @@
  *   锚定 `package.json` 所在目录后，默认值稳定且可预期。
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 export const ENV_DATA_ROOT = 'MDCG_DATA_ROOT';
 export const ENV_MDCG_ROOT = 'MDCG_ROOT';
@@ -87,6 +87,22 @@ export function mdcgRoot(configured) {
         return anchor(configured.trim());
     return join(dataRoot(), 'mdcg');
 }
+/**
+ * Python 子进程的 PYTHONPATH 值（issue #12）。
+ *
+ * Python 启动 `-m` 时只把 **cwd** 注入 sys.path——DSH 宿主在插件仓外启动时
+ * `python -m md_cg.mcp_server` / `python -m md_cg.tokens` 必然
+ * ModuleNotFoundError。cwd 与 PYTHONPATH 双保险：后者不依赖 cwd，即使调用方
+ * 显式覆盖了启动参数/工作目录也兜得住。顺序：仓根在前（优先随包 md_cg，
+ * 防宿主环境同名旧包抢先），进程既有 PYTHONPATH 在后。
+ */
+export function pythonPathValue() {
+    const prev = process.env.PYTHONPATH ?? '';
+    const parts = [repoRoot()];
+    if (prev && !prev.split(delimiter).includes(repoRoot()))
+        parts.push(prev);
+    return parts.join(delimiter);
+}
 /** 当前解析快照（供启动日志留痕——把「记忆真源在哪」写进可审计痕迹）。 */
 export function describeDataPaths(configured) {
     const dr = dataRoot();