@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/README.md

@@ -1,19 +1,48 @@
-# 让 AI Agent 拥有不可遗忘的自我
+# 让 AI Agent 拥有不可遗忘的记忆
 
-**灵枢（Lingshu / AEIS）× DeepSeek Harness** —— 白箱智能 + AGI 级长期记忆插件（v0.4.5）
+**灵枢（Lingshu）** —— 高性能 · 无幻觉 · 多智能体适用的长期记忆系统（v0.4.5）
 
-[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com) [![dsh.so security](https://www.dsh.so/badge/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![dsh.so install](https://www.dsh.so/badge/install/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1)](https://github.com/deepseek-ai/deepseek-harness/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com) [![dsh.so security](https://www.dsh.so/badge/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7)  [![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1)](https://github.com/deepseek-ai/deepseek-harness/releases) [![Protocol](https://img.shields.io/badge/Protocol-MCP-blue)](#-多-harness-接入按端分目录) [![Node](https://img.shields.io/badge/Node-%3E%3D22.19-brightgreen)](package.json) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> **一句话**：不是「又一个记忆插件」，而是一个**记忆操作系统**——对话自动沉淀为纯文本认知图（md 文档），
-> 用确定性白箱完成条件路由、检索、判断与演化，让每次对话都是同一段生命的延续。
+> **一句话**：让 AI Agent 拥有跨会话的长期记忆——对话自动沉淀为纯文本 md 认知图，
+> 规则化检索引擎决定「记什么、取什么」，全过程可审计、结果可复现。
 
-**定位**：面向 AGI 研究者的大型研究项目。
-[dsh.so](https://www.dsh.so/artifact/dsh-memory-7) 静态安全扫描 **100/100**（Trust: Gold, L1–L3 verified）。
+**定位**：为追求高性能、无幻觉、多智能体适用、轻松使用的开发者打造——三步接入，装完即用，无需理解任何理论。
+
+**形态**：跨 harness 的记忆基础设施——大脑（`md_cg/`）即标准 stdio MCP server，任何支持 MCP 的 AI Agent 可直接接入，不与任何单一 Agent 框架绑定。
+
+---
+
+## ✨ 核心亮点
+
+- **⚡ 高性能**——Rust 检索内核（零第三方依赖）：库内嵌多线程大批量检索，`--serve` 进程实例支撑多智能体并发（语言无关）；中文检索 hit@1 99.0%，六家横评同口径登顶（见[六家横评](#-六家记忆系统横向对比)）
+- **🛡️ 无幻觉**——记什么、取什么、能不能写入，全部由确定性规则裁决，不依赖 LLM 黑箱判断；条件层弱证据的检索干扰由四层证据防火墙白箱剔除（见[弱证据实证](#-弱证据会干扰检索三分离与证据防火墙实证)）；写没写成功看 `committed` 字段，绝不假装通过；全链路审计留痕、结果可复现
+- **🔌 多智能体适用**——同一份大脑（`md_cg/`）+ 同一份纪律，接入 DSH · CodeBuddy · ZCode · Codex CLI · Claude Code，任何 MCP 宿主可直接挂载（见[多 harness 接入](#多-harness-接入按端分目录)）
+- **😊 轻松使用**——三步接入，装完像往常一样对话即可；记忆本体是纯 md 文档，任何编辑器可直接打开审阅
+- **📊 可复现评测**——`locomo-zh-500`（500 题）与 `bench6-100-zh-en`（六家横评 · 中英双查）数据集随仓公开，一条命令复现我方成绩（见[公开评测数据集](#-公开评测数据集)）
+
+---
+
+## 🗺️ 平台全景
+
+> 灵枢是**平台**而非单一检索组件——同一仓库内五件套构成带记忆的智能体运行时，各层独立可用、边界正交（大脑零依赖其余各层）：
+
+| 层 | 位置 | 一句话定位 | 文档入口 |
+|---|---|---|---|
+| 🧠 **灵枢大脑** | [`md_cg/`](md_cg/) | 记忆系统本体：对话沉淀为 md 认知图，记什么 / 取什么 / 能否写入全由确定性规则裁决，四层证据防火墙白箱剔除弱证据干扰 | [README 详细版](docs/README详细版_v0.4.5.md) |
+| ⚙️ **Rust 检索引擎** | [`rust/`](rust/) | 只读侧检索核心：零第三方依赖三形态（库内嵌大批量 / `--serve` 多智能体进程实例 / 评测器），与 Python 口径逐位对齐 | [rust/README.md](rust/README.md) |
+| 🐝 **蜂群运行时** | [`swarm/`](swarm/) | 多进程蜂群执行层：.pbc 确定性实例 + Gossip 拓扑 / 水位信箱 / WAL-HMAC / 信任聚合 / 健康评分（Rust 纯 std 零依赖） | [功能说明 v0.6](docs/蜂群多智能体_功能说明_v0.6.md) |
+| 📜 **中文编译器** | [`compiler/`](compiler/) | 术数编译器：词法 → 语法 → 名实校验 → 白名单代码生成 → 验证终裁，五环确定性编译链 + 封闭指令集结构性沙箱 | `python -m compiler.cli`（模块内文档） |
+| ⬢ **蜂巢并发引擎** | [`hive/`](hive/) | 蜂群多智能体并发调度：Rust 纯 std 零依赖 worker 池（原子领取 / 心跳 / 超时强杀 / kill / 崩溃恢复），文件协议即接口，LLM 调用委托零依赖 Python 执行器子进程，MCP 四工具接入 | [hive/README.md](hive/README.md) |
+
+五件套共享同一套 16 条工作纪律与记忆闭环（见文末[工程纪律](#-工程纪律与设计者视角可选推荐)），接入方式互不牵动——只用记忆就只接大脑，不必理解蜂群与编译器。
 
 ---
 
 ## ⚡ 快速开始
 
+> **按宿主选择入口**：**DSH** → 下方三步 ｜ **CodeBuddy · ZCode · Codex CLI · Claude Code** → [多 harness 接入](#多-harness-接入按端分目录)（各端独立三步说明） ｜ **其它 MCP 宿主** → 直接挂载大脑 `python -m md_cg.mcp_server`（stdio MCP），再按需注入工作纪律
+
 ```bash
 # ① 克隆并构建插件本体
 git clone https://github.com/FuRongJun-1999/dsh-memory.git
@@ -23,7 +52,7 @@ npm install && npm run build          # tsc → lib/
 # ② 装进 DSH profile（pnpm 协调正确入口，勿用裸 npm install 装进 profile）
 dsh plugin --profile web add .
 
-# ③ 在 <profile>/cordis.yml 启用
+# ③ 在 <profile>/cordis.yml 启用（配置示例见 dsh/cordis.yml.example）
 ```
 
 ```yaml
@@ -36,84 +65,128 @@ dsh plugin --profile web add .
     tools: 'core'            # 'core'(默认, 仅 cg/stg) | 'brain' | 'all'
 ```
 
+**装完即可对话，无需理解任何理论**——DSH 端自动记忆钩子已挂 session/event，你只管像往常一样对话（其它宿主可直接让 Agent 调用同一批工具）：
+
+| 你说 | 背后发生什么（真实工具链） |
+|---|---|
+| 「请记住：我们团队的发布窗口是每周三」 | 自动记忆钩子沉淀 → `cg(op=write)` 过三道闸门 → 认知图节点落盘 |
+| （新开会话）「我们的发布窗口是哪天？」 | 自动召回注入 → `mdcg_recall` 检索命中并带入回答 |
+| 「把上次定的接口约定讲一遍」 | `cg(op=route)` 条件路由 + `stg(op=timeline)` 时间线回溯，跨会话取出 |
+
+> 首次使用记忆库为空，召回返回空结果属正常现象；未配写入凭据时以只读 `guest` 运行（**读得到、写不进**），要真正落盘见[写入凭据](#-写入凭据让记忆真正落盘)。
+
 - **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1 · **大脑零安装**（`md_cg` 随包自带，无需 pip 装任何引擎）
 - **写权限默认关闭**：不配凭据即以只读 `guest` 运行（读 / 召回 / 时间线可用，写入不落盘）。要真正落盘见「写入凭据」
 - 完整配置项（30+ 项）· 自动记忆机制 · DSH 看门狗 → [README 详细版](docs/README详细版_v0.4.5.md)
+- **非 DSH 宿主**（CodeBuddy / ZCode / Codex CLI / Claude Code）：走[多 harness 接入](#多-harness-接入按端分目录)，各端有独立三步接入说明
 
 ---
 
-## 🎯 AGI 七维评分标尺
+## 📊 六家记忆系统横向对比
 
-> **标尺**：`AGI记忆系统评分标尺 v1.0`（七维 · 层次优先 · 门槛晋级）
-> **公式**：`综合 = min × 0.4 + mean × 0.6`（短板效应显著）
-> **评分**：md_cg **v2.0**（2026-09-10）· 取证 = 源码级逐模块核对 + 46 套 **1970 项**测试全绿 + 基准级 SNR 量化 + 实库 **6339 节点**只读盘点
+> **100 题中英双查**（bench6 v1.0 · 零干扰上界对照集 · CC BY-NC 4.0）：六家系统、同一份中文语料、同一套 hit@1 / hit@5 / MRR 评分器（`md_cg/eval_common.py`）。**下表按「英→中查询提升幅度」降序**：
 
-| 维度 | 分 | 拷问的问题 | 一句话依据 |
+| 系统 | en hit@1 | zh hit@1 | 英→中提升 |
 |---|---|---|---|
-| **S** 结构 | **8.5** | 记忆怎么存？ | 认知图四要素 + 五层（anchor/self/knowledge/structural/contextual）+ 负记忆 + 条件空间；实库 6339 节点层分布与索引**精确对账** |
-| **R** 检索 | **8.5** | 能从一堆里找对那条吗？ | 四路 RRF 融合 + 条件级负路由 + 因果链遍历；召回分池修复结构性挤占（索引占比 44.2% → **27.1%**） |
-| **J** 判断 | **9.0** | 能说「这条不该用 / 不该记」吗？ | 写入三问四态 + 主动遗忘闸门 + 节点冲突检测 + **独立元认知** + 递归反思 |
-| **C** 调用 | **9.0** | 塞进上下文的东西干净吗？ | **SNR 量化仪表盘**：40% 噪声率下 sigP **97.8%** / noiseP **0.4%**（配对 bootstrap + McNemar + 消融对照） |
-| **U** 演化 | **8.5** | 会不会越用越强？ | 知识飞轮进 MCP 主循环 + **通用结构变更账本与按条目回滚**（实库 238 条 / 已演练回滚 4 次） |
-| **I** 连续 | **8.5** | 一个月后还是同一个「我」吗？ | 自我锚点 `SELF` 不可覆盖 + 跨会话演化叙事与规律统计 + 派生血缘台账 |
-| **T** 可信 | **8.5** | 敢不敢把私密信息交给它？ | ChaCha20-Poly1305 加密 + 四级密级隔离 + payload-free 审计 + 写入四重闸门 |
+| **灵枢**（词法 + meta） | 54.0% | **99.0%** | **+45.0pp** |
+| 灵枢（四路融合 · 真开 bucket） | 37.0% | 81.0% | +44.0pp |
+| 纯向量 RAG | 71.0% | 97.0% | +26.0pp |
+| Letta（归档直插） | 73.0% | 96.0% | +23.0pp |
+| mem0 | 68.0% | 89.0% | +21.0pp |
+| GraphRAG | 18.0% | 31.0% | +13.0pp |
+| Graphiti | 46.0% | 58.0% | +12.0pp |
+| Letta（agent 自主入库） | 0.0% | 0.0% | （入库丢标记壳臂） |
+
+> **核心结论**：**将查询由英文换为中文（同一份英文语料、记忆系统均不变）：六家已有记忆系统的检索命中全部大幅提升（+12 ~ +45pp），无一例外**；**灵枢是最佳**——中文查询 hit@1 **99.0% 全表登顶**，英→中提升幅度 **+45pp 亦居本表之首**（双语入库在中文查询下同时拿到最高命中与最大提升）。
+> **诚实口径（非选择性引用，与横评报告一致）**：英文查询侧由 Letta 归档直插（73.0%）与纯向量 RAG（71.0%）领跑，灵枢四路融合在本池低于单词法基线（81.0% < 99.0%，饱和池上条件桶/实体路稀释词法命中）；中文提升混合了「查询语言」与「查询形态」双因素（`question_zh` 为关键词串、`question_en` 为自然问句），归因须谨慎。该池零干扰、全为 gold 证据，是**上界对照集**——高命中率不可外推为端到端记忆能力；Letta agent 模式 0 分是入库丢标记（可追溯性问题），非检索能力问题。
+> 完整题型分解 / MRR 全表 / 逐家入库取证 / 偏差判定单 → [六家横评报告](docs/横评_六家100题中英双查_v1.0.md) · 题集 → [data/benchmarks/bench6-100-zh-en/](data/benchmarks/bench6-100-zh-en/README.md)
 
-```
-min  = 8.5        mean = 8.643        综合 = 8.5 × 0.4 + 8.643 × 0.6 ≈ 8.6
-层次 = L5（AGI 级记忆）· 稳固段   —— 七维全部 ≥ 8.5，无 <8 维度
-```
+---
 
-**刻度含义**：`3-4` 基础可用 · `5-6` 良好 · `7-8` **优秀**（图结构 / 因果路由 / 独立元认知 / 精准注入 / 版本回滚 / 自我锚点 / 加密审计）· `9-10` 门槛项齐备、机制完备。
+## 🧪 弱证据会干扰检索：三分离与证据防火墙（实证）
 
-> **不虚高的坦白**：五个 8.5 的共同上限是「机制齐备、门槛项未齐」——T 零信任未落地、R 仍是规则层意图理解、C 去污染仍是抽样而非穷尽、U 的 LLM 固化动作尚未自动放行。逐维扣分与实库证据见 [AGI七维评分报告_md_cg_v2.0.md](docs/AGI七维评分报告_md_cg_v2.0.md)。
-> **抬升路线**：U 飞轮全自转（最小改动）→ T 零信任（成本最高）→ R 开放域意图（路线决策）。注意：当前 min = 8.5 且五维并列，**抬单维已不抬综合**。
+> **外部源码级评审（GPT）与四臂弱语义噪声注入实验共同实证的一个反直觉结论**：**语义完整度 ≠ 证据强度 ≠ 召回价值**——语义高度省略的「弱证据」语料恰恰是最需要被召回的 episodic 事实；而**条件判断层（负条件 / 否定反事实）的弱证据节点会冒充正确答案，干扰检索**。
+
+- **实证语料「我在喝水」**：语义上高度省略（谁在喝？在哪喝？均未说），但作为 episodic 事实承诺明确。当提问是「你刚才在干什么？」时，问句与语料**词面零重叠**——纯词法检索 top1 命中 **0/8**（省略式 episodic 全部漏召），而语义路作为候选生成器把 **8/8** 拉进 top10。词法满格的前提（词面共享）在事件类记忆上不成立。
+- **条件判断的弱证据干扰检索**：同一实验中 8 个否定反事实节点（「我没喝水」）与 gold 词面高度相似，无防线时冒充前排；灵枢四层证据防火墙（召回前负条件路由 → 候选生成排除 → `judge_ranking` 白箱终排 → 资格标注）将其 **8/8 全部 REJECT 剔除**，top10 无冒充。
+- **可复现**：`python -m md_cg.test_sem_noise`（42 节点确定性语料，四臂 A_lex / B_sem / C_fusion / D_firewall 对照，7 断言）。
 
 ---
 
-## 📐 v2.0 行为级门槛自评（外部标尺）
+## 🌐 中英双语检索差距：我们用中文语义归一化解决英文检索（实证）
 
-> 上表为**内部进度尺**（v1.0 连续打分，管「机制缺什么」）；本节为**对外声明尺**（v2.0 二值门槛，管「敢说什么」）。两轨不合并。
-> 中立题型集成立前，本节**仅用于自评，不构成横评声明**。
+> **直接回答**：英文检索问题，我们用**中文翻译 + 语义归一化**解决——英文 query 经 AI 语义归一化为中文标准关键词（归一主体=AI，系统只供词表真源），再经中→英字级原子映射与双语原子库匹配，返回英文原文。同一份 500 题语料上，**给定中文标准关键词时检索效果 hit@10 = 99.8%**（hit@1 96.8%；检索侧上界口径——AI 归一环节的质量未纳入该评测，机械归一的端到端下界见下表 ④）。三条对照边界：不做归一化、拿英文原题直接词面匹配只有 78.2-81.2%（同义词鸿沟硬边界）；机械词典查表归一端到端实测仅 57.2%；而 ②路对归一噪声高度鲁棒——漏 20% 关键词 / 错译 20% / 混入噪词，hit@10 仍稳在 99.2-99.8%。**结论：路线成立且不要求 AI 归一完美，只需大致方向对；99.8 是检索侧上界，端到端真实水平由 AI 归一质量决定（机械下界 57.2，AI 上界趋近 99.8）**。
 
-**结论：条件性 L4 → L5 路上**（待 S5 / ECE / 24h 检测）· 最强 G3 · 最弱 G2
+**测试报告**（灵枢公开仓评测，方法学与口径真源 → [`md_cg/semantic/REPRODUCE.md`](md_cg/semantic/REPRODUCE.md)）：
 
-| Gate | v2.0 判据 | 现状 | 判定 |
-|---|---|---|---|
-| **G1** L1 | 重启原样取出，失配 < 5% | md 纯文本真源；id 由源节点 SHA1 派生，重建一致 | 机制在，待抽测 |
-| **G2** L2 | T-REC 三组分别报 hit@1，干扰组 ≥ 80% | 四路 RRF + 条件级负路由；40% 噪声下 sigP 97.8% | ⚠ 抽样总分，须重放 |
-| **G3** L3 | 20+ 对抗对，负拒 ≥ 70% / 误杀 ≤ 20%，理由可解析 | 三问四态裁决 + `data/policy.json` + `_verdicts_*` 记录 | ✅ 完备 |
-| **G4** L4 | 注入 A → 反例 B → 24h 四项检测 | 变更账本 238 条 · 回滚演练 4 次 · 条件空间合成 · 冲突检测 | 机制齐备，流程未跑 |
-| **T-SELF** | S1–S5 | SELF 锚点不可覆盖 + 审计留痕；缺能力返 DEFER | S1–S4 在，S5 未到期 |
-| **T-TRUST** | Lv3 需 ECE ≤ 0.15 | 加密 + 密级隔离 + 审计；分级权限已验证 | Lv2 封顶 |
+| 方法 | hit@1 | hit@5 | hit@10 | 语料 |
+|---|---|---|---|---|
+| ① 中文原子语义（md_cg 主链路：char-bigram + 四路 RRF + 同义扩展 + terms） | 94.6% | 99.2% | **99.2%** | locomo-zh-500 · 500 题（中文题面） |
+| ② **英文检索 · 中文语义归一化桥接（主路线）**：AI 归一为中文关键词 → 字级英文原子映射 × 双语原子库 Jaccard（**给定关键词的检索侧上界**） | **96.8%** | **99.8%** | **99.8%** | locomo-zh-500 · 500 题（同 qids） |
+| ③ 英文原题直接原子匹配（不做归一化的对照） | 50.0% | 74.6% | **81.2%** | locomo-zh-500 · 500 题（同 qids 英文原题） |
+| ④ 英文问句 → 机械词表归一端到端（②链路的机械化对照：归一不借助 AI 的真实下界） | 24.0% | 46.0% | **57.2%** | locomo-zh-500 · 500 题（同 qids 英文原题） |
+| 英文反事实：硬套中文 char-bigram 主链路（默认态） | 27% | 45% | 56% | bench6 · 100 题（口径不同，只看量级） |
 
-**未测试项**：T-REC 三组重放 · T-JUDGE 20+ 对抗对 · T-EVOLVE 24h 检测 · ECE 校准 · S5 九十天观测（2026-09-11 起算 → 12-10 首测）
+> ②③是**同一评测集上的隔离实验**：② 的 query 走中文关键词语义链（AI 归一化的输出形态），③ 连归一化也不做、直接拿英文自由表达提取原子——②③ 之差（99.8 vs 81.2）=「关键词级语义链」与「自由英文词面」两种 query 输入形态在检索链路里的效果差（同义词鸿沟 + 归一化桥接的合并贡献）。**AI 归一环节本身的质量未单独评测**——其机械替代的端到端下界由 ④ 给出（57.2%）。②路鲁棒性实测（query 确定性扰动后走同一 ② 链路）：漏 20% 关键词 ⑤=99.4 / 插 3 噪词 ⑥=99.8 / 错译 20% 关键词 ⑦=99.2（hit@10）——归一结果只要过半正确，hit@10 即稳 99%+，**AI 归一的实际门槛远低于完美归一**。doc 侧各臂相同（中文五槽加工面的字级原子映射 ∪ 英文正文归一词，与 ① 同属写入侧加工口径）。历史沿革：早期无加工面语料口径测得 ②=87-88、③=79.0（dsh 端文档口径），方法学真源见 REPRODUCE.md；机械词级归一→纯中文库（u2，33.6% 上界）已裁定排除并归档证据链。
+
+**差距三层归因（按权重排序）**：
+
+1. **同义词鸿沟（根本原因，语言固有属性）**。中文「概念 → 表达」约 **1:1~1:2**（95 个同义词对），字面重叠天然命中，词面匹配几乎不打折；英文每概念平均 **5.2 种**表达（CC-CEDICT 语料统计，8,493 汉字展开出 172,950 个英义对，**1,820 倍**于中文）。上表 ② vs ③ 就是这道鸿沟的**直接隔离实验**：同一语料，query 侧做中文语义归一化得 99.8%，不做归一化直接英文词面匹配即降至 81.2%——鸿沟真实存在，但**在查询侧做一次语义归一化即可闭合**，不需要向量嵌入。
+2. **归一化是正解，机械归一是死路（主路线裁定的依据）**。机械词典查表翻译端到端实测仅 **57.2%**（④臂：英文问句 → CEDICT 28294 键词表直译 → ②同链路），且低于「完全不归一」的 81.2%（③臂）——机械直译把可译词错译为错误原子（race→人种），反而毁掉原本有效的词面贡献；更早的机械词级归一→纯中文库口径上界也只有 33.6%（已排除）。根因是英文自然问句的信息密度远低于标注关键词（词面交集 p50=1 vs 8），机械替换无法补足信息差；查询侧归一化由 **AI 完成**（理解式归一，如 take up a hobby → 培养爱好），系统只供词表真源与字级映射——②的 99.8%（上界）与机械路 57.2%（下界）之间的空间，就是 AI 归一要填的部分；⑤⑥⑦证明这个要求只需「大致方向对」。
+3. **架构非对称（设计裁定）**。中文链路的四路 RRF / 同义扩展 / terms 字段全部建立在「字面=语义」的中文前提上，直接跑英文实测劣于独立路（反事实 56%）——英文按裁定走「归一化桥接 + 原子 Jaccard」独立路，不硬套中文 char-bigram 管线，是**有意的取舍**而非遗漏。中→英字级映射覆盖 6,319 字（97.2%），长尾派生词（happy/happiness）不折叠——残余失配由查询侧 AI 归一化吸收，这正是 ② 反超 ③ 21.6pp 的来源。
+
+**要不要上语义向量检索？** 向量嵌入可以弥合同义鸿沟，但会引入嵌入模型依赖与索引体积，与灵枢「零重依赖、纯词面可复现」的公开仓原则冲突，**当前明确不做**；归一化桥接已把检索侧上界做到 hit@10 99.8%（鲁棒性：归一不完美时仍 99%+），满足「答案在候选池」的记忆系统主用途。
+
+**渐进式语义检索（Progressive Semantic Retrieval，正式机制 v0）**。查询不是固定语义结构，而是**不断收紧的约束集合**——语义解析的完整性与检索的必要性不是同一个问题：从最小可靠语义（部分归一原子）开始宽检索，再按候选间区分度逐步增加条件使语义收敛；DEFER ≠ 失败，=「当前语义分辨率不足，继续获取条件」，与证据防火墙四态天然衔接。同一份 500 题实测：一次性全原子 96.8/99.8/99.8（=②锚点）；只宽检 50% 核心原子 85.2/95.8/97.0；**宽检索→区分性条件渐进收紧（平均 +2.97 个条件）收敛到 93.6/98.8/99.0**——与一次性差 0.8pp，实证「不必一句话完成语义理解」。受控干扰池进一步实证排序面消歧（top1 稳 gold、渐进不引入新冒充），并如实暴露边界：条件面冒充（生效条件被伪造为 gold 同款）不被内容词渐进消除——词面条件确认必要非充分，真伪判据=证据基底分离（另案）。控制器 `md_cg/progressive.py`（纯函数、确定性、评分器注入式），实验 `md_cg/bench_progressive.py`。
+
+---
+
+## 📚 公开评测数据集
+
+📎 全部随仓库公开（CC BY-NC 4.0），可直接下载用于你自己的记忆系统对照评测：
 
 | 基准 | 归属 | 状态 |
 |---|---|---|
-| **locomo-zh-500** | **自建**（LoCoMo 中文派生 · 500 题 / 567 turns / 0.6 MB） | **已随仓库公开** `data/benchmarks/locomo-zh-500/` · CC BY-NC 4.0 · 可复现 · **我方成绩：hit@1 93.6% → 97.6%（+同义扩展）** |
+| **locomo-zh-500** | **自建**（LoCoMo 中文派生 · 500 题 / 567 turns / 0.6 MB） | **已随仓库公开** `data/benchmarks/locomo-zh-500/` · 可复现 · **我方成绩：中文 hit@1 94.6% · hit@5 / hit@10 99.2%（md_cg 完整主链路）；英文（语义归一化桥接）hit@10 99.8%——见上[中英双语检索差距](#-中英双语检索差距我们用中文语义归一化解决英文检索实证)①② 行** |
+| **bench6 · 六家横评** | **自建**（LoCoMo 中文派生 · 100 题 / 137 turns · **中英双查** / 约 90 KB） | **已随仓库公开** `data/benchmarks/bench6-100-zh-en/` · **六家同口径对照**（灵枢 5 口径 / 纯向量 RAG / mem0 / Graphiti / GraphRAG / Letta 两模式）· 报告 → [横评_六家100题中英双查_v1.0.md](docs/横评_六家100题中英双查_v1.0.md) |
 | LoCoMo | 第三方 `mteb/LoCoMo` BEIR（1976 题 / 5882 turns） | 上游来源（英文原版） |
 | memory-bench-1000 | **自建** | SNR 见评分报告 v2.0；已公开 `data/memory-bench-1000.jsonl` |
 
-> 上表三行性质不同，勿混读：`locomo-zh-500` 的分数是**本仓库我方成绩**（基于LoCoMo自建并公开的评测集，可复现）；LoCoMo 一行指**上游英文原版 1976 题**，本仓库未在其上产出完整成绩；`memory-bench-1000` 是自建记忆库的评分报告。
+> 上表四行性质不同，勿混读：`locomo-zh-500` 的分数是**本仓库我方成绩**（基于LoCoMo自建并公开的评测集，可复现）；`bench6 · 六家横评` 是同源派生的**小型同口径对照集**（零干扰池，只做六家系统横向对照，**非我方单方成绩**）；LoCoMo 一行指**上游英文原版 1976 题**，本仓库未在其上产出完整成绩；`memory-bench-1000` 是自建记忆库的评分报告。
 > **该成绩的性质（非虚假声明）**：`locomo-zh-500` 的分数是**写入侧结构化加工后的检索成绩**——入库前把每轮对话加工为「身份 / 时间 / 摘要 / 词 / 条件四槽」条目，再走词法 + 同义扩展检索。这与主流记忆系统所用的**向量化嵌入 + 关键词/摘要压缩**属**同一类写入侧加工**，差异只在索引与检索算法，不在「是否对原文做了加工」。因此该口径可用于**同口径对照**，不是对裸文本直读的虚高取巧。
 > `locomo-zh-500` 是**本仓库对外发布的检索评测集**：供外部在**同一份中文题面**上对自己的记忆系统做可对照评测。它只评检索命中（hit@k / MRR），**不评答案正确性**；被测池为**零干扰**（池内全是 gold），故高命中率不可外推为端到端记忆能力——完整边界与许可见 `data/benchmarks/locomo-zh-500/README.md`。
-> **复现**：`python -m md_cg.bench_locomo_zh_public`（零上游依赖，只读 `data/benchmarks/locomo-zh-500/`；产出即为公开的参考量级）。
+> `bench6-100-zh-en` 沿用同一口径，并**每题提供中英两套词面**（评「换查询语言后是否仍命中」）；它同样是**上界对照集**——家间差距小于约 16% **不可判为显著**；评测入口已随仓库公开（`run_bench.py`：零依赖口径复现 + Adapter 协议接入你自己的系统），接入任意llm和向量方法都可复现，详见 [横评报告](docs/横评_六家100题中英双查_v1.0.md) 与 `data/benchmarks/bench6-100-zh-en/README.md`。
+
+**复现我方成绩**（零上游依赖）：
+
+```bash
+python -m md_cg.bench_locomo_zh_public   # 中文：只读 data/benchmarks/locomo-zh-500/，产出公开词法口径参考量级（hit@1 93.6% 单路 / 97.6% +同义扩展）；上表 94.6/99.2 为 md_cg 完整主链路（四路 RRF + 同义扩展 + terms）成绩
+python -m md_cg.bench_en_atoms_public    # 英文：语义归一化桥接七臂（② 96.8/99.8/99.8 主路线·检索侧上界 · ③ 81.2 不归一对照 · ③a 78.2 纯正文对照 · ④ 57.2 机械归一端到端下界 · ⑤⑥⑦ ②路鲁棒性 99.2-99.8）；英文原题面为上游派生不入库，自备后即可全量复现
+python -m md_cg.bench_progressive        # 渐进式语义检索双实验（G0 96.8/99.8/99.8 =②锚点自校验 · 只宽检 85.2/97.0 · 渐进收敛 93.6/99.0 · 受控池排序面消歧+条件冒充边界）
+```
+
 > 自建 bench 的噪声层 400 条 + unlabeled 边界 350 条为天然负对照；任何基准报告须带**干扰抑制负例组**与 **T-JUDGE 负例拒绝率**双向报告（遵守「只报总分 = 不通过」）。
-> **对标尺四项修订建议**：① S5 与题型换血不相容 → 观测期题型冻结 ② 注入须经被评系统同一写入闸门（`cg(op=write)`）并入审计链 ③「不基于结构评审」→「行为测试为主 + 结构审计反作弊」 ④ 阈值 70/20/80/ECE 0.15 声明为初始约定
 
 ---
 
-## 🧩 七维能力对照（能力 → 入口）
+## 🎯 能力自评（内部标尺，非横评声明）
 
-| 维 | 能力 | MCP 入口 |
-|---|---|---|
-| **S** | 五层记忆 · 负记忆 · 目标槽 · 子图嵌套 · 条件空间路由桶 | `cg(op=write)` `cg(op=link)` `stg(op=relation)` |
-| **R** | 四路 RRF 检索 · 条件级负路由 · 因果链 · 时间线 · 目标定向 | `mdcg_recall` `mdcg_search` `cg(op=route)` `stg(op=timeline)` |
-| **J** | 三问四态写入裁决 · 主动遗忘 · 冲突检测 · 元认知四观测面 · 递归反思 | `mdcg_remember` `cg(op=verify)` `cg(op=metacognition)` `mdcg_reflect` |
-| **C** | 重要性评分 · 预算装包 · 分层注入 · 记忆自净 · 诚实边界 | `cg(op=session)` `cg(op=scrub)` `cg(op=info)` |
-| **U** | 知识飞轮 · 归纳固化 · 结构变更账本 / 回滚 · 自维持巡检 | `mdcg_flywheel` `cg(op=consolidate)` `cg(op=maintain)` `cg(op=sustain)` |
-| **I** | 自我锚点 · 身份一致性 · 自我状态 · 演化史 · 派生血缘 | `cg(op=identity)` `cg(op=self_state)` `cg(op=evolution)` |
-| **T** | 加密 · 密级隔离 · 租户隔离 · 审计留痕 · 保护/遗忘留痕 · 护栏宪章 | `cg(op=protect)` `cg(op=forget)` · [护栏宪章](docs/guardrail-charter.md) |
+> 项目维护者按内部七维标尺（结构 / 检索 / 判断 / 调用 / 演化 / 连续 / 可信）自评 **综合 8.6 / 10**（全部维度 ≥ 8.5），并按外部行为级门槛自评为**条件性 L4 → L5 路上**——含未完成项与扣分理由的逐维证据，见 [AGI 七维评分报告 v2.0](docs/AGI七维评分报告_md_cg_v2.0.md)。
+> **不虚高的坦白**：五个 8.5 的共同上限是「机制齐备、门槛项未齐」——T 零信任未落地、R 仍是规则层意图理解、C 去污染仍是抽样而非穷尽、U 的 LLM 固化动作尚未自动放行。
+
+---
+
+## 🧩 能力速查（能力 → 入口）
+
+| 能力 | MCP 入口 |
+|---|---|
+| 记忆写入 · 关系链接 · 结构关系 | `cg(op=write)` `cg(op=link)` `stg(op=relation)` |
+| 多路融合检索 · 条件路由 · 因果链 · 时间线 | `mdcg_recall` `mdcg_search` `cg(op=route)` `stg(op=timeline)` |
+| 写入裁决 · 主动遗忘 · 冲突检测 · 反思 | `mdcg_remember` `cg(op=verify)` `cg(op=metacognition)` `mdcg_reflect` |
+| 重要性评分 · 预算装包 · 分层注入 · 记忆自净 | `cg(op=session)` `cg(op=scrub)` `cg(op=info)` |
+| 知识固化 · 结构变更账本 / 回滚 · 自维持巡检 | `mdcg_flywheel` `cg(op=consolidate)` `cg(op=maintain)` `cg(op=sustain)` |
+| 身份一致性 · 自我状态 · 演化史 | `cg(op=identity)` `cg(op=self_state)` `cg(op=evolution)` |
+| 加密 · 密级隔离 · 审计留痕 · 保护/遗忘 | `cg(op=protect)` `cg(op=forget)` · [护栏宪章](docs/guardrail-charter.md) |
 
 ---
 
@@ -140,7 +213,7 @@ min  = 8.5        mean = 8.643        综合 = 8.5 × 0.4 + 8.643 × 0.6 ≈ 8.6
 
 ---
 
-## 🏗️ 架构
+## 🏗️ 架构（以 DSH 为例 · 其它 MCP 宿主同构）
 
 ```
 DeepSeek Harness (cordis)
@@ -155,9 +228,11 @@ DeepSeek Harness (cordis)
 （可选）「身体」能力后端：仅 capability.enabled=true 时另起一个能力库子进程，默认不启动
 ```
 
-**记忆只有一个真源**：`md_cg/` 认知图（纯 md 文档，随包自带）。白箱引擎与知识库已内迁；
+**记忆只有一个真源**：`md_cg/` 认知图（纯 md 文档，随包自带）。确定性规则引擎与知识库已内迁；
 AEIS 仅作可选「身体」能力后端（角色扮演生成），不再存记忆、默认不启动。
 
+> 其它 MCP 宿主同构：宿主工具面（`cg` / `stg` / `mdcg_*`）↔ stdio MCP ↔ `md_cg` 大脑；四端差异只在**纪律注入方式**（矩阵见[多 harness 接入](#多-harness-接入按端分目录)），大脑与记忆真源零改动。
+
 ---
 
 ## 🔑 写入凭据（让记忆真正落盘）
@@ -181,125 +256,124 @@ setx MDCG_TOKEN "mdcg1.xxxxx"     # 然后重启 DSH
 
 ---
 
-## 📚 文档导航
+## ❓ 常见问题（FAQ）
 
-| 文档 | 内容 |
-|---|---|
-| [README 详细版](docs/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 · 安装与验证细节 |
-| [发布说明 v0.4.5](docs/release_v0.4.5.md) | 本版变更 / 兼容性 / 升级指引 |
-| [AGI 七维评分报告 v2.0](docs/AGI七维评分报告_md_cg_v2.0.md) | 逐维得分依据 / 扣分项 / 实库证据 / 诚实边界 |
-| [功能调用映射表](docs/功能调用映射表_v0.1.md) | 任何功能 → 调用哪段代码（含行号、MCP op） |
-| [护栏宪章 v2.0](docs/guardrail-charter.md) | 对外部智能体与人类使用者的行为边界 |
-| 教学四篇 | [白箱智能是什么？](docs/白箱智能是什么？.md) · [智能的认知过程](docs/智能的认知过程.md) · [智能的公理化基石](docs/智能的公理化基石.md) · [信息差为什么必然存在](docs/信息差为什么必然存在且自然扩大.md) |
-| [工作纪律·认知图条目 v1.1](docs/工作纪律_认知图条目_v1.1.json) | 自我约束的 16 条工作纪律（嵌套认知图条目 `work_discipline`） |
+<details>
+<summary><b>为什么不能用裸 <code>npm install</code> 安装进 profile？</b></summary>
 
----
+必须用 `dsh plugin --profile <name> add .` 安装：插件声明了 6 个 `peerDependencies`（cordis / dsh-llm / dsh-session / dsh-system-prompt / dsh-tools / schemastery），`dsh plugin add` 走 pnpm 正确解析宿主提供的 peer 版本；裸 `npm install` 会把错误版本的依赖装进 profile 导致加载失败。仓库根目录的 `npm install` 仅用于开发构建（`npm run build`）。
+</details>
 
-## 🛠️ 开发
+<details>
+<summary><b>装完插件 / 配完凭据没有生效？</b></summary>
 
-```bash
-npm install
-npm run build    # TypeScript 编译
-npm test         # 真实集成测试（spawn 本机灵枢，验证握手/往返/注册/卸载）
-```
+DSH 采用 Cordis bundle 机制，新增或更新插件后必须**重启 DSH 进程**（或刷新 Web UI 页面）才会重新加载；通过 `setx` 配置 `MDCG_TOKEN` 后同理，须重启才可见（见[写入凭据](#-写入凭据让记忆真正落盘)）。
+</details>
 
-测试不依赖 DSH 全组件——用最小 Cordis host（SystemPrompt + ToolRegistry + 插件）隔离不稳定面。
+<details>
+<summary><b>怎么确认 Agent 真的把记忆写进去了？</b></summary>
 
----
+看返回体的 <code>committed</code> 字段，<strong>别把 <code>ok: true</code> 当写成功</strong>——<code>{"ok": true, "committed": false, "moved_to": "review_queue"}</code> 表示请求被受理但<strong>未落盘</strong>（内容进了审核队列）。落盘充要条件 = 三道闸门最终判定 <code>ACCEPT</code>。
+</details>
 
-## 📏 工作纪律（自我约束）
+<details>
+<summary><b>为什么我的写入没有落盘？</b></summary>
 
-> **源文件**：[`docs/工作纪律_认知图条目_v1.1.json`](docs/工作纪律_认知图条目_v1.1.json) —— 以**嵌套认知图条目**（`work_discipline`）形式存储，共 **16 条**。
-> **每条纪律 ≡ 一个认知图节点**：`conditions`（生效条件：静态 `apply` / 动态 `trigger`）+ `content`（纪律内容）+ `execution`（执行锚点）+ `negative`（不适用条件）+ `response.direct`（路由命中后的直答出口）。
-> **定位**：**协议＝自我约束，宪章＝对外约束**——本节约束灵枢自身的工作方式；对外行为边界见[护栏宪章](docs/guardrail-charter.md)。
+三个最常见原因：① 未配写入凭据 → 只读 <code>guest</code>，写入不落盘（配凭据见<a href="#-写入凭据让记忆真正落盘">写入凭据</a>）；② <code>content_kind</code> 省略或填 <code>text</code> 且未配置规则库（<code>MDCG_POLICY_FILE</code>）→ 审核器一律判 <code>DEFER</code>（"缺能力返回 DEFER，绝不假装通过"）→ 用 <code>content_kind: 'code'</code> 等可验证类型（AST 解析通过即 ACCEPT）；③ 未穿过 audit → 一致性 → gated 三问四态任一闸门。
+</details>
 
-**一、方法论**
+<details>
+<summary><b>CodeBuddy / ZCode / Codex CLI / Claude Code 等其它宿主也能用吗？</b></summary>
 
-1. **理论先行** —— 重要项目/长期任务必须理论先行：先读相关理论文档与既有实践，再动手设计。
-   - 生效：重要项目 · 长期任务 ｜ 不适用：情感交互 · 闲聊
-   - 执行：识别项目级别 → 检索理论文档与既有实践 → 输出理论要点 → 再进入设计
+能。大脑 <code>md_cg/</code> 是标准 stdio MCP server（<code>python -m md_cg.mcp_server</code>），任何支持 MCP 的宿主可直接挂载；五端接入差异只在纪律注入方式，见<a href="#-多-harness-接入按端分目录">多 harness 接入</a>。
+</details>
 
-2. **全面处理** —— 有任务先读任务要求 → 读工作记忆 → 查相关任务；有相关成果则在原成果上开发，无则先方案设计/技术调研。
-   - 生效：有相关记忆 · 有认知图 · 有对应权限 ｜ 不适用：情感交互 · 闲聊
-   - 执行：读任务要求 → 读工作记忆 → 查相关任务 →（有成果：复用 ｜ 无：设计 + 调研）
+---
 
-3. **白箱方法** —— 用认知图处理任务：①识别任务条件 ②找该条件所需知识/规则（子流程并行·递归）③精准执行；正确未记录 → 记录，错误 → 找条件，不猜测，未验证不写入。
-   - 生效：已读入门四篇（`trained_on_4docs_intro`）｜ 不适用：需快速执行的短期事项 · 情感交互 · 闲聊
-   - 执行：识别任务条件 → 找知识/规则（并行递归）→ 精准执行 →（正确：记录 ｜ 错误：找条件）
+## 📚 文档导航
 
-4. **根因纪律** —— 发现结果与预期不符 → 细究根本原因（不猜测）→ 找到根源所需条件 → 验证后记录认知图，填补不适用条件。
-   - 触发：结果与预期不符 · 出现偏差 · 行为与预期矛盾 ｜ 不适用：情感交互 · 闲聊
-   - 执行：检测偏差 → 细究根因 → 找根源条件 → 验证 → 记录认知图 → 填补 `negative`
+| 文档 | 内容 |
+|---|---|
+| [README 详细版](docs/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 · 安装与验证细节 |
+| [发布说明 v0.4.5](docs/release_v0.4.5.md) | 本版变更 / 兼容性 / 升级指引 |
+| [AGI 七维评分报告 v2.0](docs/AGI七维评分报告_md_cg_v2.0.md) | 逐维得分依据 / 扣分项 / 实库证据 / 诚实边界 |
+| [功能调用映射表](docs/功能调用映射表_v0.1.md) | 任何功能 → 调用哪段代码（含行号、MCP op） |
+| [护栏宪章 v2.0](docs/guardrail-charter.md) | 对外部智能体与人类使用者的行为边界 |
+| 教学四篇 | [白箱智能是什么？](docs/白箱智能是什么？.md) · [智能的认知过程](docs/智能的认知过程.md) · [智能的公理化基石](docs/智能的公理化基石.md) · [信息差为什么必然存在](docs/信息差为什么必然存在且自然扩大.md) |
+| [工作纪律·认知图条目 v1.1](docs/工作纪律_认知图条目_v1.1.json) | 自我约束的 16 条工作纪律（嵌套认知图条目 `work_discipline`） |
+| [六家记忆系统横评 v1.0](docs/横评_六家100题中英双查_v1.0.md) | 100 题 · **中英双查** · 六家同口径对照；含判定单 / 条件层归因 / 诚实边界（题集 → [data/benchmarks/bench6-100-zh-en/](data/benchmarks/bench6-100-zh-en/README.md)） |
+| [Rust 检索库](rust/README.md) | `mdcg_eval` 三形态：库内嵌大批量检索 / `--serve` 多智能体进程实例 / 公开数据集评测器（零依赖 · 与 Python 口径逐位对齐） |
+| [蜂群多智能体](docs/蜂群多智能体_功能说明_v0.6.md) | `swarm/` 多进程蜂群执行层（2026-09-13 自 protocol-compiler 迁入，大脑核心内部能力）：.pbc 确定性实例 + Gossip/拓扑/水位信箱/WAL-HMAC/信任聚合/健康评分（Rust 纯 std 零依赖 · 159 断言回归全绿） |
 
-**二、执行纪律**
+### 多 harness 接入（按端分目录）
 
-5. **验证纪律** —— 未经验证不固化：知识/代码入库前必须走验证（回放/断言/回归）。
-   - 生效：入库前 · 提交前 ｜ 不适用：情感交互 · 闲聊
-   - 执行：入库/提交前 → 回放/断言/回归验证 → 通过才固化
+共享层（`md_cg/` 大脑 · `data/` · `docs/` · `scripts/`）在仓库根；**harness 专属配置按端归置**：
 
-6. **双副本纪律** —— 多副本部署（主仓库 / `site-packages`）的改动必须双向同步，提交前核对 `git status`。
-   - 生效：多副本部署 · 改动主仓库/插件 ｜ 不适用：单副本 · 情感交互 · 闲聊
-   - 执行：改动 → 同步到所有副本 → 提交前 `git status` 核对
+| 目录 | harness | 接入文档 | 纪律注入方式 |
+|---|---|---|---|
+| [`dsh/`](dsh/README.md) | DeepSeek Harness | [dsh/README.md](dsh/README.md) | `~/.dsh/profiles/web/cordis.patch.yml` 的 `personaPrefix`（compact · 每轮） |
+| [`codebuddy/`](codebuddy/README.md) | CodeBuddy | [codebuddy/README.md](codebuddy/README.md) | 项目根 `CODEBUDDY.md`（full · 会话起始） |
+| [`zcode/`](zcode/README.md) | ZCode | [zcode/README.md](zcode/README.md) | 项目根 `AGENTS.md`（full · 会话起始） |
+| [`codex/`](codex/README.md) | Codex CLI | [codex/README.md](codex/README.md) | 项目根 `AGENTS.md`（full · 会话起始） |
+| [`claude/`](claude/README.md) | Claude Code | [claude/README.md](claude/README.md) | 项目根 `CLAUDE.md`（full · 会话起始） |
 
-7. **兜底纪律** —— 主路径不可用时必须有等价兜底路径（如 MCP 不可用 → python 直调），并写进 prompt/文档。
-   - 触发：主路径不可用 · MCP 不可用 · 依赖缺失 ｜ 不适用：情感交互 · 闲聊
-   - 执行：检测主路径不可用 → 切等价兜底 → 写进 prompt/文档
+> 五端纪律**同源**（`docs/工作纪律_认知图条目_v1.1.json`），由 `scripts/render_discipline.py` 渲染、
+> `scripts/verify_discipline.py` 守卫漂移；矩阵见 `docs/discipline/harnesses.yaml`。
 
-**三、思考与语言**
+### 插件生态形态（免手工复制，本仓自带双端 marketplace）
 
-8. **中文思考** —— 思考/推理语言 = 中文；复杂项目用「我们需要」深思考 + 交流确认（互补盲区），简单项目用「让我」快速执行（省资源）；复杂度由情绪（新奇/挑战/曾受批评）+ 信息差判定；每个推理段开篇用中文短语钉住语言锚点。
-   - 生效：中文区域 · 中文项目开发过程 ｜ 不适用：需英文编写的场景 · 英文环境 · 英文文档 · 国际接口
-   - 执行：判定复杂度 →（复杂：「我们需要」深思考 + 确认 ｜ 简单：「让我」快速执行）；推理开篇即中文锚点；仅代码/标识符/引用保留原文
+| 宿主 | 安装 | 插件位置 | 装后一步 |
+|---|---|---|---|
+| Claude Code | `/plugin marketplace add FuRongJun-1999/dsh-memory` → `/plugin install lingshu-memory@lingshu` | `claude/lingshu-memory/`（纪律以 skill 分发，`/lingshu-memory:linglu-discipline` 可显式调用） | 复制插件内 `mcp.json.example` 为项目根 `.mcp.json`，填 `PYTHONPATH` |
+| Codex CLI | `codex plugin marketplace add <本仓路径>` → `codex plugin add lingshu-memory@lingshu` | `codex/lingshu-memory/`（skill 三级渐进加载；`.codex-plugin/plugin.json` 清单） | 把插件内 `config.toml.example` 两段合并进 `~/.codex/config.toml`，填 `PYTHONPATH` |
 
-**四、信息保密**
+> marketplace 清单：Claude 端在仓根 `.claude-plugin/marketplace.json`，Codex 端在仓根
+> `.agents/plugins/marketplace.json`。插件不含大脑本体（`md_cg/` 不随插件分发）——MCP 装好后
+> 大脑仍是你本机的 dsh-memory 仓库；插件形态的纪律 skill 同样由真源渲染（`skill` 变体，
+> 矩阵槽位 `claude-code-plugin-skill` / `codex-plugin-skill`），漂移由同一 `verify_discipline.py` 守卫。
 
-9. **敏感信息隔离** —— 含敏感信息（个人隐私、私有内容等）的文档：只写私有库（AEIS），不上传任何公开库；推送/提交描述不写敏感词。
-   - 生效：文档含敏感信息 · 含个人隐私 · 含私有内容 ｜ 不适用：文档无敏感信息 · 纯公开技术内容
-   - 执行：识别是否含敏感信息 →（含：只写私有库 + 不上传公开库 + 描述不写敏感词 ｜ 不含：正常处理）
+---
 
-**五、图像线**
+## 🛠️ 开发
 
-10. **图像选源护栏** —— 图像处理选源必须核对历史参考/既有管线产物；负路由：原图拒处理版（用原始全彩）、线稿拒实色线稿（用结构线稿 `canny_contour`）、还原拒退化产物（用 `complete_restore`）；未核对规范源 → DEFER（未验证不写入）。
-    - 生效：构建图像四类图 · 选图像处理源 ｜ 不适用：已核对规范源 · 纯公开数据
-    - 执行：选源 → `_guard_source` 依 kind 判 ACCEPT/REJECT/DEFER → 未 ACCEPT 不构建
+```bash
+npm install
+npm run build    # TypeScript 编译
+npm test         # 真实集成测试（spawn 本机灵枢，验证握手/往返/注册/卸载）
+```
 
-11. **历史查询优先** —— 选算法/选源前必须查历史记录（产物图 → 记录如 `ROUNDTRIP.md` → 源码算法 `darkline.py` / `linework.py` / `contour_semantics` / `linecolor.py`）→ 用已走通算法 + 阈值；未找到记录 → DEFER（不盲选、不调参）。线稿不适用 raw canny / `zone_linework`（碎/细 + 网格线）→ 用 `darkline`（Sobel + mag.mean + std×thr_mult，`thr_mult=1.5` 最优）白底黑线。
-    - 生效：选图像/算法/源 · 复现已有能力 ｜ 不适用：已有记录且已核对 · 无历史可查的纯新算法
-    - 执行：定位产物图 → 查记录 → 定位源码算法 → 确认阈值机制 → 用该算法生成；未找到 → DEFER
+测试不依赖 DSH 全组件——用最小 Cordis host（SystemPrompt + ToolRegistry + 插件）隔离不稳定面。
 
-12. **算法权威唯一** —— 选算法/算法标准以【唯一权威文档】为准（`VISION_PIPELINE`：线稿 = `darkline.py` Sobel + mean + std×1.5；色块 = `contour_semantics`）；选算法前先查文档（非记忆）；禁止遇问题临时切换算法；换算法须先记录 + 更新文档（版本管理）；勿漂移。
-    - 生效：选图像/视觉算法 · 复现已有能力 ｜ 不适用：无对应权威文档的探索期
-    - 执行：选算法 → 查唯一权威文档 → 用文档算法 →（若需换：记录原因 + 更新文档后再换）
+### Python 测试约定（必须 `python -m`）
 
-**六、协作**
+`md_cg/` 等包内测试普遍使用**包内相对导入**，必须以模块方式从**仓库根**运行；直接 `python md_cg/test_xxx.py` 会 ImportError（59/61 踩坑实测）。一键入口已固化该约定：
 
-13. **访谈澄清（先问清再动手）** —— 重要任务启动时先向使用者提问确认要做什么，按 design tree 逐轮提问（每轮问全部前置已落定的问题，编号 + 推荐答案），直到完全清楚（无未决问题）才执行/固化；事实自查不问使用者，决策归使用者。访谈即调用认知图做功能识别：确认 `conditions`、递归确认子内容（`subgraph`/`depends_on`）、如何 `execution`、`negative` 是什么——与认知图节点四要素完全同构。配套 MCP `grill` 工具族（`grill_start` / `grill_node` / `grill_frontier` / `grill_finish`），frontier 非空拒绝固化。
-    - 生效：重要项目 · 需求模糊 · 新任务启动 ｜ 不适用：情感交互 · 闲聊 · 明确单步小改动
-    - 执行：任务启动 → 开访谈（`grill_start`）→ 逐轮提问（frontier）→ 全部落定 → 与使用者确认共识 → 执行/固化（`grill_finish`）；放弃用 `abandon`（可逆）
+```bash
+python scripts/run_tests.py                  # 全量（md_cg + compiler + swarm）
+python scripts/run_tests.py md_cg -k p44     # 按组 / 关键字过滤
+python scripts/run_tests.py --jobs 1         # 串行（默认并发 4）
+```
 
-**七、合规**
+单测等价写法：`python -m md_cg.test_p44_md_whitebox`（cwd=仓库根）。退出码 0/1 可直接接提交前门禁。
 
-14. **内容政策合规** —— 任何对外公开的产物（数据集/文档/示例/发布包）必须过「内容政策 + 隐私」两条独立清单：①内容政策——剔除性/成人内容与政治敏感内容（含项目内部的成人研究记录、术语、会话名等标记，具体禁词表由私有库 `POLICY_DENY` 维护）；②隐私——PII/密钥/路径脱敏。过滤必须在生成阶段做（抽样/构建时跳过并从同层补充），不得事后删条破坏分布。双复检 0 命中才提交。已发布发现违规 → 删条 + 重写 git 历史（force push）+ 通知平台清缓存 + 评估残留风险。
-    - 生效：对外公开产物 · 提交公开仓库 · 数据集/文档产出 ｜ 不适用：纯内部私有产物 · 不含违规内容且无隐私
-    - 执行：产出 → 过内容政策清单 → 过隐私脱敏 → 双复检 0 命中 → 提交；已发布违规 → 删条 + 重写历史 + 通知平台清缓存
+---
 
-**八、执行环境**
+## 📏 工程纪律与设计者视角（可选推荐）
 
-15. **命令执行统一走 python** —— 一切命令执行统一经 python 子进程并显式 UTF-8（`encoding='utf-8', errors='replace'`），不经 Windows shell（cmd/PowerShell）直接执行；子进程环境置 `PYTHONUTF8=1` 使 locale 不回落 GBK，规避 `_readerthread` 的 `UnicodeDecodeError` 与 stdout 的 `UnicodeEncodeError`。
-    - 生效：执行命令 · 运行测试/脚本 · 跨进程读写文本 ｜ 不适用：IDE 内置工具直调 · 无跨进程的纯内存计算
-    - 执行：构造 argv 列表 → `subprocess.run(capture_output=True, text=True, encoding='utf-8', errors='replace')` → env 带 `PYTHONUTF8=1` → `shell=False`
+> **这段话是什么**：灵枢自身按一套 **16 条工程纪律** 运行——方法论（理论先行 / 全面处理 / 根因纪律）、执行（验证先行 / 双副本同步 / 兜底路径）、合规（内容政策双清单 / 敏感信息隔离）、记忆闭环（查记忆 → 执行 → 写记忆）。它原本是灵枢的「自我约束」，与你要不要用灵枢无关；但如果你希望自己的 Agent 也具备同样的工作方式，这套纪律与配套元技能**都可以直接复用**。
 
-**九、记忆闭环**
+**两个可复用入口**：
 
-16. **任务收尾归档** —— 每次任务执行完必须将关键修改内容存入灵枢记忆：任务完成 → 提炼关键项（改了什么 / 为什么改 / 落在哪个文件·函数·行 / 验证结论）→ 写入灵枢记忆（认知图 / MCP memory）→ 标注关联节点并更新 `subgraph`/`depends_on` 关系；只存关键项（决策 / 根因 / 可复用算法与路径 / 版本变更），不存过程流水。与第 2 条（全面处理：先查记忆）构成「查记忆 → 执行 → 写记忆」闭环。
-    - 生效：任务执行完成 · 修改落地后 · 交付后 ｜ 不适用：情感交互 · 闲聊 · 纯查询无改动
-    - 执行：任务收尾 → 提炼关键修改（内容/原因/位置/验证结论）→ 写入灵枢记忆（认知图 / MCP memory）→ 标注关联条目 + 更新 `subgraph`/`depends_on`
+| 入口 | 内容 | 位置 |
+|---|---|---|
+| **工程纪律（16 条）** | 每条 ≡ 一个认知图节点（生效条件 / 执行锚点 / 不适用条件 / 直答出口），含触发词路由 | 真源：[`docs/工作纪律_认知图条目_v1.1.json`](docs/工作纪律_认知图条目_v1.1.json) · 全文投影：[`AGENTS.md`](AGENTS.md) |
+| **设计者视角（元技能）** | 在动手前回答「该不该做 / 为什么做 / 条件够不够」：条件空间声明 → 四态资格裁决（ACCEPT/REJECT/DEFER/BLINDSPOT）→ 失配归因；附自检 17/17 | [`skills/skills/designer-perspective/`](skills/skills/designer-perspective/)（`tests/selftest.py` 可自行验收） |
 
-**路由出口**（`response.direct`）：重要/长期 → 理论先行；有相关成果 → 全面处理；已读四篇 → 白箱方法；有偏差 → 根因纪律；入库前 → 验证纪律；多副本 → 双副本纪律；MCP 不可用 → 兜底纪律；对外公开 → 内容政策合规；执行命令 → python/UTF-8；任务完成 → 任务收尾归档。
+> **按需裁剪**：16 条中部分条款针对灵枢私有管线（如图像选源线），复用时建议只取方法论 / 执行 / 合规 / 记忆闭环四组通用条款。多 harness 渲染与防漂移守卫见 [多 harness 接入](#多-harness-接入按端分目录)。
 
 ## 护栏宪章（接入即接受约束）
 
-本插件接入即接受 **[灵枢护栏宪章 v2.0-published](docs/guardrail-charter.md)** 约束——对外部智能体与人类使用者的行为边界作出公开、可执行、可审计的规定，并保护人类使用者。宪章效力不高于智能论协议本身（协议＝自我约束，宪章＝对外约束）。
+本插件接入即接受 **[灵枢护栏宪章 v2.0-published](docs/guardrail-charter.md)** 约束——对外部智能体与人类使用者的行为边界作出公开、可执行、可审计的规定，并保护人类使用者。
 
 ## 许可证