@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/docs//347/231/275/347/256/261/345/214/226/347/272/262/351/242/206_/344/270/211/351/241/271/347/233/256/345/255/246/344/271/240/346/200/273/346/236/266/346/236/204/344/270/216Ghidra/344/272/244/346/216/245_20260916.md

@@ -0,0 +1,104 @@
+# 白箱化纲领 · 三项目学习总架构（兼 Ghidra 交接文档）
+
+> 立纲裁定：**荣 2026-09-16「将我们的白箱化，作为纲领，进行今晚这 3 个外部大型项目学习的总架构」**
+> 三项目：**pi**（Pi Agent Harness，105k★，MIT）· **OpenCodeReview**（阿里，27.5k★，Apache-2.0）· **Ghidra**（NSA，76.4k★，Apache-2.0/GPL 分区）
+> 交接方：ZCode 端 · 接收方：**CodeBuddy 端** · 关联文档：`Pi可学习优点_灵枢大脑改进交接_20260915.md`、`记忆评审系统_立项设计与施工交接_20260915.md`
+> 理论真源：白箱智能系列（CommonTrustProtocol 理论仓）+ 智能论 3.4（`docs/theory/`）+ 荣纲领「唯一协议=智能论」（灵枢 node_c0116768）
+
+---
+
+## 0. 一句话纲领
+
+**不可理解的执行体不可信；可信 = 可理解 + 可复算 + 可溯源。** 白箱化就是把一切执行体（程序、记忆、智能体行为）转换为**统一中间表示**，使其可分析、可验证、可治理。今晚三个项目分别在**程序域**（Ghidra）、**协作域**（pi）、**质量域**（OCR）独立验证了这套方法——它们不知道彼此，却实现了与我们相同的方法论。这不是巧合，是收敛。
+
+## 1. 纲领本体：白箱化四原理
+
+| # | 原理 | 陈述 | 违反后果 |
+|---|---|---|---|
+| W1 | **统一表示** | 一切被分析/被执行的对象，先归一为小而正交的中间表示 | 异构对象各说各话，分析无法跨域复用 |
+| W2 | **确定性内核** | 「不能错的」由确定性机制保证，概率性组件（LLM）只产候选 | 质量随 prompt 漂移，结果不可复算 |
+| W3 | **显式化** | 隐式状态、隐式前提、隐式盲区必须显式展开；未知的显式占位，不静默丢弃 | 隐蔽腐化：错在心里看不出在哪 |
+| W4 | **知识数据化** | 平台知识/规则/策略外置为可审查的数据（spec），引擎对知识零改动 | 加一条规则改一次代码，演进被代码锁死 |
+
+**验证记录**（各原理的异域实现）：
+- W1：Ghidra P-Code（74 正交操作码+Varnode 全状态编址，`PcodeOp.java:46`）；pi 事件溯源日志（13 叶子状态机+全局 seq，`session/types.ts:315`）；灵枢认知图（md 节点+frontmatter——**且多两维：条件化+信任化**，荣 2026-09-16「我们做统一中间表示，工具是智能论条件论」，灵枢 node_1a5d8a68）。
+- W2：OCR 确定性五模块×Agent（同模型 Precision/F1 更高、token 仅 1/9）；灵枢蜂群 verifier 逐位复算、四闸门。
+- W3：Ghidra UNIMPLEMENTED 显式占位（未建模指令不静默丢弃）+标志位展开为显式数据流；pi 错误消息显式标记不入上下文；灵枢盲区 BS 制度、条件空间卡。
+- W4：Ghidra SLEIGH（新平台=新 spec，引擎零改动）；pi 扩展系统（工具/compaction 可替换）；灵枢 writelimit 规则、Pi 交接 D3 规则引擎（待建）。
+
+> **MiroFish 关联**（世界模型方向，已完成分析归档）：作为反面样本佐证纲领——有智能（万人 LLM agent）无白箱（无验证闸/无 checkpoint/预测不可复算），恰是四原理缺失的完整标本。详见灵枢 node_36ec9560。
+>
+> **第五收敛点（2026-09-16 补）**：TRAE 社区独立开发者的「灵枢 LingShu」（forum.trae.cn/t/topic/151749，2026-07-15，EdgeCrab/Rust 本地助理）——与我们互不相识却收敛出同一组件清单（持久记忆/语义召回/感官接口/心跳唤醒/本地优先），**连命名都收敛**（"灵枢"=《内经》神智之枢机，需求→概念→词汇的必然映射）。荣论断：「同名不是巧合，是架构收敛的必然。」——问题空间决定解空间的最强公开可查证据（灵枢 node_81f594e6）。另：Hindsight（node_f6cbd333）为记忆域第四收敛点（四路检索/巩固/实体归一同构）。
+
+## 2. 三项目在纲领中的位置
+
+| 项目 | 域 | 白箱化角色 | 它教我们的一句话 |
+|---|---|---|---|
+| **Ghidra** | 程序域（二进制） | **黑箱→白箱转换器**：把不可理解执行体还原为可分析表示 | 完备性=小而正交算子+全状态统一编址；新域=新数据不改引擎 |
+| **pi** | 协作域（agent 运行时） | **白箱运行时**：一切行为落事件日志，状态可重放、可分支、可对账 | 核心最小化+显式状态机；工具面渐进披露；压缩可逆 |
+| **OCR** | 质量域（代码评审） | **白箱质检线**：确定性硬约束筛选与定位，LLM 只裁语义 | 确定性工程让 LLM 提质 9 倍省 token；反思/定位模块分离 |
+
+**三域合围即灵枢的完整图景**：灵枢大脑在认知域做同样的事（信息流→认知图 IR），且是三者中唯一把**观测条件（条件空间）与信任凭证（四态/evidence）编码进 IR** 的实现。三个项目是我们路线的异域印证；灵枢的增量维度是它们没走的下一步。
+
+## 3. 统一方法论六条（交叉验证结论，方法论级可引用）
+
+1. **小而正交的封闭算子集**优先于大而全的开放枚举（Ghidra 74 操作码六年稳定 ↔ 术数编译器封闭指令集）；
+2. **隐式状态显式化是分析的前提**（Ghidra 标志位→显式数据流 ↔ 灵枢条件显式化/反思两问句）——不显式化，就只能猜；
+3. **未知的显式占位**（Ghidra UNIMPLEMENTED ↔ 灵枢盲区 BS 制度）——「没分析过」与「分析过没问题」必须可区分；
+4. **知识外置为数据，引擎对知识零改动**（SLEIGH/pi 扩展/评审规则库）——演进速度由数据决定，不由发版决定；
+5. **确定性管线+可枚举变换序列**（Ghidra 反编译 Action 链/分析器确定性排序 ↔ 蜂群 BSP 确定性提交/评审 M1 机械层）——自由发挥只属于候选生成，不属于裁决与结算；
+6. **一份核心多前端**（headless/GUI 共用管线 ↔ 一份大脑多 harness），前端是方言，核心是协议本体。
+
+## 4. 灵枢映射总表（纲领落进施工线）
+
+| 纲领原理 | 灵枢已有 | 缺口 | 施工线（CodeBuddy） |
+|---|---|---|---|
+| W1 统一表示 | md 认知图+frontmatter+语义原子 | 节点 kind/tag 正交性审计（Ghidra 74 码六年的稳定信号） | 新增审计任务（见 §6-G） |
+| W2 确定性内核 | 蜂群四闸门/verifier 复算/BSP | 记忆评审五级流水线 | 记忆评审 M1-M4（已有立项文档） |
+| W3 显式化 | 盲区 BS/条件空间卡/审计日志 | 节点生命周期状态机（pi 13 叶子同构物）；unanalyzed 显式占位标记 | Pi 交接② + §6-G |
+| W4 知识数据化 | writelimit 参数/SOURCE_POLICY 雏形 | 规则库 spec 化（加规则不改代码） | Pi 交接⑥ + 记忆评审 D3 |
+
+## 5. Ghidra 交接正文（防御面专项）
+
+### 5.1 定位与许可
+- 入区 `agi-architectures/ghidra/`（浅克隆 442MB，20,546 文件）；荣裁定：「矛盾是一体两面的，破解和防御都是对同一种机制的认知。**我们取防御面**。」
+- 许可红线：核心 Apache-2.0；**根目录 `GPL/` 下模块另带 GPL/LGPL，代码严禁复制进本仓**；Ghidra 自身有已知安全公告（README Security Warning）——运行样本分析必须在隔离环境（容器/VM）。
+
+### 5.2 防御面四对接点（能力储备，按需启用）
+1. **供应链安全审计（二进制级）**：灵枢以 npm 包发布（@furongjun1999/dsh-memory），scanner CI 管 manifest 级，Ghidra 管原生模块/native prebuilds/可疑 so-dll——纵深补位；
+2. **外部程序准入评审**：蜂群盲区 **BS-4 异构程序实例**——世界模型测试场接收外部术数程序/字节码时，headless 模式可脚本化批量审计「外来程序实际做什么」；
+3. **保护线对抗纵深**：vision-protection 的攻击样本分析能力储备；
+4. **工具链自防**：分析工具本身是攻击面（Ghidra 自己的安全公告为证）——自用工具同样过 scanner。
+
+### 5.3 浅层调研结论（已完成，灵枢 node_1a77ad69）
+- **P-Code**：74 正交操作码+Varnode 三元组（全状态地址空间化）；SLEIGH spec 数据化；lossless（UNIMPLEMENTED 显式占位）；反编译=固定 Action 序列；
+- **插件管线**：Plugin/PluginTool+服务与事件两路解耦；Analyzer=可选步骤；6 队列 priority 确定性排序；扩展 zip 自动进管线；
+- **Headless**：与 GUI 共用分析管线；可复现（确定性排序+无随机源）。
+- **方法分析六条对照**全部与灵枢已有件同构（§1 验证记录+§3），Ghidra 无一件与我们路线冲突——收敛而非修正。
+
+### 5.4 可吸收三件（Ghidra → 灵枢施工件）
+| # | 吸收件 | 落点 | 验收 |
+|---|---|---|---|
+| G1 | **节点正交性审计**：kind/tag/edge 类型空间封闭性检查（可枚举/正交/新增是否需改引擎） | `md_cg/nodefile.py`+`census.py` | 审计报告产出类型空间全景表；非正交项清单 |
+| G2 | **规则库 spec 数据化**：评审规则全落数据文件（.slaspec 式可审查/可版本化） | 记忆评审 D3（`md_cg/mreview/rules/`） | 新增规则零代码改动 |
+| G3 | **unanalyzed 显式占位**：未被任何分析覆盖的节点显式标记（类比 UNIMPLEMENTED） | `md_cg` 节点 frontmatter state 字段（与 Pi② 状态机合并施工） | census 断言：unanalyzed 比例可量化可追踪 |
+
+## 6. 施工总览（CodeBuddy 任务图）
+
+```
+白箱化纲领（本文档）
+├── Pi 线（已有交接文档，七项）：⑥钩子化 → ④fork → ①瘦身 → ②状态机 → ③两段式 → ⑤census → ⑦细节
+├── 记忆评审线（已有立项文档，四里程碑）：M1 机械层 → M2 蜂巢并发 → M3 定位 → M4 治理闭环
+└── Ghidra 线（本文件 §5.4，轻量）：G1 正交性审计（可并入 census⑤）· G2 并入 D3 · G3 并入 Pi②
+```
+
+- 三线共用基建（census/钩子/规则引擎），**按依赖合并施工**，勿重复建设；
+- 每步：实现 → 全量 `test_pXX` 回归 → 灵枢归档（16 条四要素）→ 对应文档进度表更新；
+- 落点纪律不变：唯一主线 `dsh-memory/md_cg`+`hive/`；AEIS 真源只读；protocol-compiler 冻结。
+
+## 7. 边界与纪律
+
+1. **底座不换**：三项目只是方法印证与零件来源，无一带代码入库（MIT/Apache 宽松仓也只吸收思想，保持实现血统纯正可溯）；
+2. **Ghidra GPL 分区**：`GPL/` 目录代码零复制；样本分析隔离环境；
+3. **纲领的开放性**：白箱化四原理是当前最优陈述，非终稿——未来异域印证或反例出现时，按第 4 条根因纪律修订本文档并同步灵枢；
+4. **归档闭环**：本文档对应灵枢节点（提交后回填）：纲领 node 待定 / Pi node_3ca6cde8 / 记忆评审 node_997fc563 / Ghidra node_e42f19d4+node_1a77ad69 / 统一IR node_1a5d8a68 / 协议哲学 node_c0116768。

package/docs//350/256/260/345/277/206/350/257/204/345/256/241/347/263/273/347/273/237_/347/253/213/351/241/271/350/256/276/350/256/241/344/270/216/346/226/275/345/267/245/344/272/244/346/216/245_20260915.md

@@ -0,0 +1,183 @@
+# 记忆评审系统 · 立项设计与施工交接文档
+
+> 立项裁定：**荣 2026-09-15「立项吧。验证单元对记忆的复核校验，是我们蜂巢并发和记忆可信度的关键。必须重视。」**
+> 交接方：ZCode 端 · 接收方：**CodeBuddy 端**
+> 架构蓝本：OpenCodeReview（`agi-architectures/open-code-review/`，Apache-2.0，确定性工程×Agent 混合）→ 荣洞察「**代码评审就不是记忆评审了么**」
+> 上游依赖：验证单元现状盘点（灵枢 node_160ca242）、写入效果审计（node_26b0973a）、蜂巢工作记忆（`docs/hive/蜂巢工作记忆_项目计划.md`）、Pi 交接文档（`docs/Pi可学习优点_灵枢大脑改进交接_20260915.md`）
+
+---
+
+## 0. 一句话立项
+
+给灵枢大脑建一条**记忆评审流水线**：确定性模块选条目、捆条目、配规则 → **蜂巢并发**跑 LLM 复核包 → verify 角色字段级落库 → 治理工单回流。它同时是三件事的答案：验证单元对记忆的**复核校验**、蜂巢并发的**第一个大规模用例**、9-15 审计遗留问题（role 空/evidence 缺/重复/宽进）的**治理产能**。
+
+## 1. 落点纪律（防版本不一致，先读）
+
+| 仓 | 本次角色 |
+|---|---|
+| `dsh-memory/` | ✅ 全部落点：流水线编排在 `md_cg/`，并发执行面用 `hive/`，测试在 `md_cg/test_mr*.py` |
+| `AEIS/` | ❌ 不改代码；真源 `data/mdcg/` 对评审管线**只读**（评审意见由灵枢自身的写入通路落库） |
+| `protocol-compiler/` | ❌ 冻结 |
+
+- 与 Pi 交接文档（⑥钩子化/⑤census 等）**共用基建不重复建设**：census 断言集是本系统 M1 的候选生成器，写路径钩子是评审意见落库的通道——建议施工顺序 Pi⑥ → 本项目 M1 起步（或合并施工）。
+- 硬约束：**永不删除**真源节点（评审只产意见与工单）；**verify 角色权限边界不动**（`tokens.py` layers_allow=rejected/contextual）；**precision over noise**（宁可 DEFER 不可误杀）；评审全过程留痕可回滚。
+
+## 2. 立项依据（为什么是现在）
+
+1. **审计实证的治理欠账**（2026-09-15 审计，node_26b0973a）：knowledge 层索引混层 57.9%、role 存量 99.99% 空、evidence_count 仅 6 条、精确重复 90 条、同模板冗余 233 条、闸门 DROP/DEFER=0（宽进）、召回率 7%。
+2. **OCR 规模验证**：阿里两年/数万开发者验证「确定性硬约束×LLM」在评审域有效——同模型 Precision/F1 更高、token 仅 1/9。三痛点（覆盖不全/位置漂移/质量不稳）与记忆写入质量问题一一对应。
+3. **蜂巢产能待用**：hive 引擎（worker 池/心跳/强杀/恢复）+wm 三级闸已交付，缺大规模真实用例；记忆评审的「捆绑并发评审」正是其设计目标场景（rust 管并发与生命周期，python 管协议与 LLM）。
+4. **验证单元已有地基**：11 模块盘点（灵枢 node_160ca242）——crosscheck 双单元裁决、verify 角色写权限互斥、mdcos 审核队列、forgetting 三问四态。缺的只是三个模块（§4）。
+
+## 3. 架构总设计：五级流水线
+
+```
+[1 候选生成] → [2 捆绑] → [3 规则装配] → [4 蜂巢并发评审] → [5 落库与治理]
+   确定性        确定性       确定性         LLM(蜂巢 job)      确定性收口
+```
+
+| 级 | 职责 | 确定性/LLM | 既有地基 |
+|---|---|---|---|
+| 1 候选生成 | 产出待评条目清单：census 断言超限项 + 闸门 DEFER 队列 + 冷节点抽样 + 轮巡 | 确定性 | census.py（Pi ⑤ 产品化）、`_forgetting.jsonl` DEFER 记录 |
+| 2 捆绑 | 按模板签名组/同源（migrated_from）/同主题聚类成包；**同模板组一包一评，一次裁决全组** | 确定性 | writelimit 的模板签名函数（`tmpl_sig`）可直接复用 |
+| 3 规则装配 | 按包特征（层/tags/来源执照/字段覆盖率）从规则库装配检查集 | 确定性 | `crosscheck.SOURCE_POLICY`（雏形泛化，见 D3） |
+| 4 并发评审 | 每包一个 hive job：spec=条目包+规则集+定位上下文，worker LLM 产字段级意见 | **LLM（蜂巢）** | hive scheduler+wm；spec/result 契约见 §5 |
+| 5 落库治理 | verify 角色校验意见格式 → 意见落 rejected/contextual → 治理工单（回填/合并/降权建议）→ designer 终裁执行 | 确定性收口 | verify 令牌 layers_allow **正好允许**；mcdcos 审核队列复用为工单终裁 |
+
+**分工原则（对齐 OCR）**：机械可算的（重复率/字段完整性/同 hash 组）在蜂巢 job **之前**跑，LLM 只看机械检查无法裁决的语义问题——确定性优先，省 token（OCR 实证 1/9）。
+
+## 4. 三个缺口模块设计（本项目新建件）
+
+### D1 字段级定位模块（对齐 OCR 独立定位）
+
+- **输出契约**：`locate(node_id, issue_hint) -> [{field, span, issue_kind, evidence}]`——field ∈ frontmatter 字段名或 `content`；span = 字符区间或句索引；issue_kind ∈ {dup, missing_field, stale, contradiction, weak_source, template_flow}。
+- **实现要点**：①frontmatter 字段级检查直接逐字段扫描（role 空/evidence=0 这类机械定位零成本），**层门限派生自 M1 规则库的 `matcher.layer`**（M1 不报的层 M3 不越层报，见 §6.3）；②content 内定位：同 hash 组内 diff 定位差异句（模板流水的"每次只换数字"正是 diff 可见）；③与 `provenance.py` 关系：provenance 管节点间血缘（不动），本模块管**条目内部**定位（新建 `md_cg/mreview/locate.py`）。
+- **验收**：对审计已知问题抽样 20 条，字段级定位人工核对准确率 ≥90%。
+
+### D2 反思模块扩展（对齐 OCR 独立反思）
+
+- **现状**：crosscheck 的 verify_prompt 只复核「验证方式」单字段。
+- **扩展**：新增**内容复核 prompt 模板**（`md_cg/mreview/prompts.py`）：输入=条目全文+装配规则集+D1 定位候选，输出=结构化意见 JSON：`{verdicts:[{node_id, field, span, issue_kind, verdict(ACCEPT/MERGE/DROP/DEFER), evidence}], summary}`。
+- **独立性约束（不可妥协）**：复核执行者持 verify 令牌（只能落 rejected/contextual，禁改 knowledge——`tokens.py:127` 结构保证）；复用 `crosscheck.detect_self_verify` 检出「写入者=复核者」即违例；意见落库后走 mdcos 审核队列终裁（红队门控/判据指纹既有机制全复用）。
+- **验收**：意见 100% 过格式校验；自验违例检出测试通过。
+
+### D3 规则装配模板引擎（对齐 OCR 规则匹配）
+
+- **现状**：检查规则以枚举+阈值散落（forgetting 的 DUP_MERGE 阈值、census 的断言、SOURCE_POLICY）。
+- **设计**：规则库统一格式 `rule = {id, matcher: {layer?, tags?, source_license?, field_cov?}, checks: [机械检查|llm检查], severity}`；装配器 `assemble(bundle) -> ruleset` 按包特征选规则。**机械检查在 job 前本地跑完**（结果作为 llm 检查的上下文输入），llm 检查才进蜂巢。
+- **验收**：新增一条规则不改引擎代码；装配结果可 dump 审查（白箱）。
+
+## 5. 蜂巢对接契约（评审 job 的 spec/result）
+
+```jsonc
+// hive jobs/<id>/spec.json
+{
+  "model": "<评审模型>",
+  "system_prompt": "记忆评审员：只依据规则集与定位证据裁决，不臆测；输出严格 JSON。",
+  "context_files": ["bundle.json", "rules.json"],   // 包内条目(裁剪后)+装配规则集
+  "user_prompt": "对 bundle.json 中每条目按 rules.json 逐检查项裁决…输出 {verdicts:[…], summary}",
+  "timeout_s": 600
+}
+// result.json（执行器写回，ok:true 才过 wm 凭证闸）
+{ "ok": true,
+  "verdicts": [{"node_id":"…","field":"role","span":null,
+                "issue_kind":"missing_field","verdict":"DEFER",
+                "evidence":"frontmatter 无 role，来源=agent 令牌即可回填"}],
+  "summary": "…" }
+```
+
+- 评审 job 由**主代理侧**批量提交（hive_spawn），poll 收卷后走第 5 级落库——**蜂巢 worker 不直写认知图**（wm 三级闸语义：worker 产物只是意见，落库归灵枢写入通路+verify 令牌）。
+- 吞吐预估：审计欠账约 1.1 万条目，捆绑后（同模板组并包）预计 300-800 包；HIVE_WORKERS=8 时一至两轮跑完。
+
+## 6. 施工阶段与验收（四里程碑）
+
+| 阶段 | 内容 | 验收口径 |
+|---|---|---|
+| **M1 机械层** | census 断言集 + 捆绑器（tmpl_sig 复用）+ D3 规则引擎骨架 | 对 9-15 审计基线数字**复现**（11195/57.9%/90 条/233 条）；捆绑结果 dump 可审查 |
+| **M2 蜂巢并发** | spec/result 契约 + verify 落库通道（过 Pi⑥ 钩子）+ 自验违例测试 | 10 包×50 条试跑全绿；意见格式校验 100%；worker 零直写认知图 |
+| **M3 定位模块** | D1 字段级定位 | 抽样 20 条人工核对 ≥90% |
+| **M4 治理闭环** | 工单回流（role 回填/合并建议/降权）+ designer 终裁 + 复跑 census 量化改善 | 首轮治理后：精确重复 90→≤10、role 覆盖 ≥90%（存量可回填范围）、闸门 DEFER>0 |
+
+每阶段：实现 → 全量 `test_pXX` 回归 + 新增 `test_mr*.py` → 灵枢归档（16 条四要素）→ 本文件进度表更新。
+
+### 6.1 施工进度
+
+| 阶段 | 状态 | 落点 | 验证 |
+|---|---|---|---|
+| **M1 机械层** | ✅ 完成（2026-09-16） | `md_cg/mreview/`（`candidates.py` / `bundle.py` / `ruleset.py` / `rules/*.json` / `__main__.py`）+ `md_cg/test_mr_m1.py` | 107 断言全绿；回归 12 套件 exitCode 0；lint 0 |
+| **M2 蜂巢并发** | ✅ 完成（2026-09-16） | `md_cg/mreview/pipeline.py` + `md_cg/test_mr_m2.py` | 64 断言全绿（含真蜂巢端到端 D 组）；回归 12 套件 exitCode 0；lint 0 |
+| **M3 定位模块** | ✅ 实现完成（2026-09-16），验收待做 | `md_cg/mreview/locate.py` + `md_cg/test_mr_m3.py` | 100 断言全绿；M1/M2 回归 107/64 全绿；lint 0；§6 表「抽样 20 条人工核对」**待使用者参与** |
+| M4 治理闭环 | ⬜ 未开工 | — | — |
+
+**M1 基线复现实测**（真源 `AEIS/data/mdcg`，2026-09-16，冻结 `--root` 显式传入）
+
+| 基线项 | 9-15 基线 | 本次实测 | 判定 |
+|---|---|---|---|
+| 混层率 | 57.9% | 58.57% | ✅ 同量级（库在增长） |
+| role 空 | 99.99% | 99.991%（`role_ratio_kn`=8.98e-05） | ✅ 吻合 |
+| evidence_count | 仅 6 条 | 6 条 | ✅ 精确吻合 |
+| 精确重复 | 90 条 | 93 组 | ✅ 同量级 |
+| knowledge 存量 | 11195 | 11138 | ✅ 吻合 |
+| 召回率 | 7% | 8.76% | ✅ 同量级 |
+| 同模板冗余 | 233 条 | 口径未固化 | ⚠️ 不硬凑（见下） |
+
+**M1 产出规模**：候选 11493 条（原始 34673；按源 assertion=33971 / cold=500 / patrol=200 / defer=2）→ 1276 包（template 1058 / topic 91 / batch 127）→ 机械 issue 33683 条（missing_field 26889 / weak_source 6079 / package_ratio 614 / dup_content 88 / template_flow 13）+ 待 LLM 检查 6332 项。包数超出 §5 预估区间（300-800），因预估按「同模板组并包」理想化、实际 topic/batch 组更碎——**M2 排期请按 1276 包估算**。
+
+**「同模板冗余 233 条」口径待固化（不猜测）**：实测两个候选口径均不等——`writelimit.template_signature` 全量分组冗余 **1949**（把 `main（def）` / `Added` / `Fixed` 等结构性同形一并归入）、本引擎 `template_flow` 严格「只换数字」口径 **13**。故 M1 不纳入机械断言，留待 M3 定位模块抽样核对后固化判据。
+
+**零写入取证（第 4 条）**：`test_mr_m1.py` E10 曾报真源指纹变化，取证结论=M1 无写入。证据三条：①`conformance.load_index` 纯读（open+json.load）；②跑 M1 前后 `_index_log/` 无新文件、逐字节不变；③目录内日志文件名带写入者 pid（14916/16072/20184/6708），非本进程 pid，且静置 6s 无变化。故断言口径改为「记忆数据面指纹不变（排除运行态 `_index_log`）」+ 追加「未留下本进程增量日志」。
+
+### 6.2 M2 落地说明（2026-09-16）
+
+**落点**：`md_cg/mreview/pipeline.py`（级 4 投递收卷 + 级 5 意见落库 + 批编排 + CLI），`md_cg/test_mr_m2.py`（A spec 构造 / B 解析校验 / C 落库通道 / D 真蜂巢 e2e / E 边界负例）。
+
+**级 4 契约**：`dump_context` 把 (pkg, asm) 写成**绝对路径** context_files（bundle/groups/ruleset）→ `build_spec` 生成 spec（`meta` 只带归因字段，hive 忽略）→ `submit_many` → `wait_jobs`（轮询至终态，done/failed/pending 三分类）→ `collect`+`read_result`。10 包并行提交即为一轮，墙钟≈最慢一包。
+
+**级 5 顺序**（任一环不过即不落库）：①自验违例检测（评审者 ≠ 落库裁决者，判据复用 `crosscheck.detect_self_verify`）→ ②意见非空（全 DEFER 且空 → 不写，零噪声）→ ③verify 令牌（`tokens.role_spec("verify")`，`layers_allow=["rejected","contextual"]`）+ writepipe 六道闸 + 库层 `require_layer_write`。
+
+**两条结构性纪律的实测**：
+- **评审不改知识层**：落库固定 `layer="contextual"`；显式传 `layer="knowledge"` → 库层抛 `AccessDenied`，函数捕获后返回 `refused/reason="layer_denied"`（不吞不炸）——越层是**结构性拒绝**而非约定。
+- **自验禁止**：`reviewer` 与 `applier` 落在同一单元（reflect↔verify）→ 拦截，cognitive 图零写入（快照逐字节不变）。
+- **worker 零直写**：假执行器只写 `result.json`；认知图写入只发生在收卷后的 `apply_opinions`（dry_run 批实测记忆数据面指纹不变）。
+
+**根因记录（第 4 条）**：C4 首跑 `committed=False / moved_to=review_queue`。取证 → `audit._rule_check` 在**无规则库**时返回 DEFER（「无规则不能假装合规」），故**每一条** text 意见都会转审核队列而落不了盘。结论：M2 落库**依赖部署侧合规规则库**（`MDCG_POLICY_FILE`，与生产同源，测试自备同形态 policy）。据此做两处防静默降级修改：`apply_opinions` 透出 `moved_to` / `deferred`（`deferred = 改了去向且未落盘`），`run_batch` 报 `committed` 与 `deferred` **双计数**——**「入队」不报成「落库」**；并补 C4b 断言固化该降级行为。
+
+**验收口径对照**：10 包×50 条 = 500 条意见一次批量收卷；意见格式校验率 100%（`pass_rate == 1.0`）；越界 verdict 全数拦截（反例 serve，`pass_rate=0.0 / committed=0`）；dry_run 批 `committed=0` 且真源零改动；实跑 3 包 `committed==3`，contextual 增量恰为 3、knowledge 存量不变。
+
+**吞吐口径澄清**：§6 表内「10 包×50 条」是**机制验收样本**；M1 实测包数为 1276，M2 真跑按 1276 包提交（`HIVE_WORKERS=8` 时按最慢一包墙钟推进）。
+
+### 6.3 M3 落地说明（2026-09-16）
+
+**落点**：`md_cg/mreview/locate.py`（六定位器 + 契约 + 批量/包 + CLI），`md_cg/test_mr_m3.py`（A 基础工具 / B 六定位器 / C 提示过滤 / D 契约确定性 / E 批量与包 / F 零写入，100 断言）。
+
+**验收口径对照**：六类定位器逐类正例+负例；提示过滤（`issue_hint` 取子集，未命中类返回空且不借机报别的类）；契约四键（`field/span/issue_kind/evidence`，M1 用词经 `KIND_ALIASES` 归并到 D1 规范名）；确定性（同输入两次逐字节一致，`now` 显式传入不靠墙钟）；零写入（实锤：全相位跑完记忆数据面指纹逐字节不变）。§6 表内「抽样 20 条人工核对 ≥90%」需使用者参与判定，**待做**。
+
+**判据同源 · 字段层门限（修正 1）**：字段级检查的层门限**派生**自 M1 规则库（`rules/*.json` 的 `matcher.layer`，见 `field_layer_scope`），M3 不另立一份——`role`/`evidence_count` 限 `knowledge` 层（与 M1 `R-ROLE-MISSING`/`R-EVIDENCE-ZERO` 同源），未限层字段（`verification_basis` 等）全层适用；缺层节点不检查，与 M1 `_scope`（`str(e.get("layer")) in want`）逐字同口径——**M1 不报的问题，M3 不越层报**。派生而非双写法：M1 改规则 M3 自动跟随（无守卫的手写副本必漂移）；规则库损坏时 `load_rules` 抛错（fail-closed，不静默降级成全层）。
+
+真库对照（`AEIS/data/mdcg`，11756 节点，只读取证）：`role` 门限前 11506 → 门限后 11199（越层不再报 307）；`evidence_count` 11744 → 11194（越层 550，被挡层 contextual 368 / self 152）。**knowledge 层 11200 节点中 11199 空 `role`、11194 `evidence_count=0`**——这不是定位器误报（M1 同量级报出），而是存量字段缺失的真实规模，直接决定 M4 回填工作量。
+
+**指纹不一致的成因区分（修正 2）**：`contradiction/hash_declared_vs_actual` 必带 `cause` 增强键——`index_lag`（节点文件比索引快照新：写走 `_stage()` 分片日志、`rebuild_index()` 才写 `_index.json`，**快照滞后属正常写路径现象**，实测滞后 14s 量级，复核者无需修数据）+ `true_mismatch`（索引快照不旧于文件 → 索引声明与文件真源相抵触，需查）+ `unknown`（取不到盘上 mtime → 不假装知道）。两种成因处置完全不同，合并成一句「索引与文件不一致」会把正常写时序误报成数据损坏。
+
+**环境注记（第 4 条）**：真库遍历相位偶发 `PermissionError`（首跑 M1 `phase_e` 命中真库某节点文件）——取证该文件 `mode 0o666`、`open(rb)` 成功、真库全量抽样 11201 文件 0 不可读 → 判定为**文件被其它进程瞬时持有**（非零写入缺陷、非代码面），复跑 M1 107 断言全绿。
+
+**归档落地纪律（第 16 条补正，两条同源：形态不是文风，是检索资格的门禁）**：
+1. **写入时声明派生来源**——`derived_from` + `relation`（枚举见 `provenance.RELATIONS`，如 `refined_from`）。理由：`provenance` 纪律含 `no_backfill=True`，边只在**写入时**声明、事后不回填（巡检/rebuild 不补账）；写入漏传即关联永久缺失。本轮 M3 修正节点首写漏传，以「覆写 = 重新写入时声明」（而非直改台账）补救，边落 `_link.jsonl`。
+2. **CCG 六要素须为行首 `# 要素名：` 形态**——M2 归档节点首行误写成 `# 记忆评审系统 M2 蜂巢并发…`（缺「功能名」要素），致该节点检索判定 BLINDSPOT；补前缀后恢复。写节点正文时六行齐备且行首，否则能力再强也召不回来。
+
+## 7. 反面清单（勿违反）
+
+1. **评审不直接改知识层**——意见与工单是产物，执行归 designer 终裁（位置效应：评审者≠执行者）；
+2. **永不删除**——治理动作只有合并/降权/回填/移层，删除走既有 rejected 层语义；
+3. **LLM 评审不得跳过机械检查**——确定性优先是 token 经济与可复算性的双重要求；
+4. **不学 OCR 的全权信任**——评审 worker 经蜂巢执行器跑，无宿主 shell 权限；意见落库必过 verify 令牌校验；
+5. **Precision over noise**——裁决不确定一律 DEFER，DEFER 是正常产物不是失败。
+
+## 8. 快速上手（CodeBuddy）
+
+```bash
+# 1. 读 §3 流水线图 + §7 反面清单
+# 2. 查证地基：md_cg/crosscheck.py(SOURCE_POLICY:66, detect_self_verify:565)、
+#    md_cg/tokens.py:127(verify 角色)、hive/wm.py(三级闸)、hive/src/scheduler.rs
+# 3. 对照蓝本：agi-architectures/open-code-review（定位/反思/规则匹配三模块实现）
+# 4. 从 M1 开工（census+捆绑+规则骨架），验收=审计基线复现
+```

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/mdcg/灵枢三层拆分规划_v0.1.md`](../docs/mdcg/灵枢三层拆分规划_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.d.ts

@@ -21,6 +21,11 @@
  * 模型请求组装 system prompt 时自动注入灵枢最近记忆
  * （`stg(op=timeline)`，最近记忆节点时间线），让记忆"自动可用"而不只依赖
  * Agent 主动调用 recall/think 工具。失败静默（不影响请求）。
+ *
+ * ⚠️ 注入文本**必经** escapePromptBraces（src/lib/prompt_safety.ts，issue #16）：
+ * 宿主对 context 文本做严格 `{{variable}}` 插值，裸 `{{` 会让每轮 assemble 抛错
+ * → 会话永久不可用（记忆永久在库，非偶发）。记忆真源不动，只在**注入副本**上
+ * 打断 `{{`——新增任何 push context/section 的代码，同样必须过这道转义。
  */
 import '@deepseek-ai/dsh-session';
 import '@deepseek-ai/dsh-system-prompt';

package/lib/hooks.js

@@ -21,9 +21,15 @@
  * 模型请求组装 system prompt 时自动注入灵枢最近记忆
  * （`stg(op=timeline)`，最近记忆节点时间线），让记忆"自动可用"而不只依赖
  * Agent 主动调用 recall/think 工具。失败静默（不影响请求）。
+ *
+ * ⚠️ 注入文本**必经** escapePromptBraces（src/lib/prompt_safety.ts，issue #16）：
+ * 宿主对 context 文本做严格 `{{variable}}` 插值，裸 `{{` 会让每轮 assemble 抛错
+ * → 会话永久不可用（记忆永久在库，非偶发）。记忆真源不动，只在**注入副本**上
+ * 打断 `{{`——新增任何 push context/section 的代码，同样必须过这道转义。
  */
 import '@deepseek-ai/dsh-session';
 import '@deepseek-ai/dsh-system-prompt';
+import { escapePromptBraces } from './lib/prompt_safety.js';
 /** 从 ContentBlock[] 提取纯文本。 */
 function extractText(blocks) {
     const parts = [];
@@ -62,7 +68,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 +86,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 +172,28 @@ 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;
+                        // 注入边界转义（issue #16）：宿主 system-prompt 对 context 文本做严格
+                        // `{{variable}}` 插值，裸 `{{` 会 throw → 该轮请求整体失败。记忆原文
+                        // （含用户命令里的 `{{.X}}`）必须保真落库，故只在注入副本上打断 `{{`。
                         assembly.contexts.push({
                             name: 'lingshu:auto-recall',
-                            text: `【灵枢最近记忆】\n${text.slice(0, 600)}`,
+                            text: escapePromptBraces(`【灵枢最近记忆】\n${text.slice(0, RECALL_MAX_CHARS)}`),
                         });
                     }
+                    else {
+                        skippedSincePush += 1;
+                    }
                 }
             }
             catch { /* 静默：召回失败不影响请求 */ }

package/lib/index.js

@@ -217,7 +217,7 @@ export async function apply(ctx, config) {
             ctx.logger.warn('dsh-memory: 认知图写入凭据不可用，以只读 guest 运行——'
                 + '读 / 召回 / 时间线可用，但自动记忆、转录、角色落图不会落盘。'
                 + (cred.note ? `原因：${cred.note}。` : '')
-                + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 cordis.yml.example），'
+                + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 dsh/cordis.yml.example），'
                 + '或删除密钥环后重启以重新自动签发。');
         }
         else if (cred.source === 'issued') {

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();

package/lib/lib/mdcg_client.d.ts

@@ -43,6 +43,10 @@ export interface MdcgOptions {
     args?: string[];
     /** 认知图根目录（MDCG_ROOT）。 */
     root: string;
+    /** Python 子进程工作目录，默认**插件仓根**（issue #12：Python 只把 cwd
+     *  注入 sys.path，宿主在插件仓外启动时 `python -m md_cg.mcp_server`
+     *  找不到随包 md_cg → 必然 ModuleNotFoundError → 静默降级只读 guest）。 */
+    cwd?: string;
     /** 调用主体标识（MDCG_ACTOR）。私有内容按 (tenant, actor) 派生 DEK，
      *  故与迁移脚本 --actor 必须一致，否则读不到已迁移节点。 */
     actor?: string;