@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/codebuddy/CODEBUDDY.md

@@ -0,0 +1,195 @@
+# 工作纪律（工作纪律_认知图条目_v1.1）· 17 条
+
+> 本文件由 `scripts/render_discipline.py` 从真源
+> `docs/工作纪律_认知图条目_v1.1.json` 渲染生成，**请勿手改**；改真源后重跑渲染。
+> 真源指纹（SHA256 前16位）：01f7f0be85eb1fac
+
+## 概述
+
+工作纪律集: 4条方法论(理论先行/全面处理/白箱方法/根因) + 3条执行(验证/双副本/兜底) + 1条思考(中文思考/协作模式分级) + 1条保密(敏感信息隔离) + 3条图像线(选源护栏/历史查询优先/算法权威唯一) + 1条协作(访谈澄清:先问清再动手) + 1条合规(内容政策合规:公开产物过内容政策+隐私双清单) + 2条执行调度与运行环境(命令执行统一走python/UTF-8: 显式encoding+PYTHONUTF8=1, 规避GBK; 任务派发统一走蜂巢: 任何执行性任务经蜂巢spawn/submit执行并留痕, agent本体只做编排) + 1条记忆闭环(任务收尾归档:每次任务执行完只将核心修改(内容/原因/位置/验证结论)按CCG六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 不写中间过程)
+
+## 执行公约
+
+| 约定 | 内容 |
+|---|---|
+| **0.1 会话起始先查记忆** | 动手前先调认知图入口——工具名随端：MCP 端 = server「mdcg」的 `cg`；DSH 端 = 内建基元 `lingshu_cg`（即下文所有 `cg(...)`，同一服务勿因名字不同而猜测）。**`op` 是必填参数（route/read/write/verify/review…），任何调用都显式传、勿省略**。先 `cg(op=route, intent=<任务意图>)`；命中纪律/知识则按其 `execution.how` 执行。**禁止跳过此步直接改代码或跑命令。** |
+| **0.2 命中即声明** | 命中纪律须在回复中输出该条 `response.direct` 原文（「按工作纪律第 N 条：…」）。**这是「已执行」的唯一可观测证据；未声明即视为未执行。** |
+| **0.3 产出即证据** | 「动作」栏要求的产出（判定单／检索结果／验证结论／归档节点 id）必须实际给出，缺失即未执行。 |
+| **0.4 违规即归档** | 发现自己违反任一条 → 第 4 条归因 + 第 16 条写入灵枢记忆。**隐瞒违规本身是更严重的违规。** |
+| **0.5 例外不外溢** | 某条的「不适用」只豁免该条，不豁免其它条。 |
+
+## 纪律路由表
+
+### 1. 理论先行
+
+- **触发**：重要项目｜长期任务
+- **动作**：识别项目级别→检索理论文档与既有实践→输出理论要点→再进入设计
+- **不适用**：情感交互｜闲聊
+- **声明**：按工作纪律第1条: 理论先行——先查相关理论与既有实践再动手。
+
+### 2. 全面处理
+
+- **触发**：有相关记忆｜有认知图｜有对应权限
+- **动作**：读任务要求→读工作记忆→查相关任务→(有成果:复用 | 无:设计+调研)
+- **不适用**：情感交互｜闲聊
+- **声明**：按工作纪律第2条: 全面处理——先读任务/工作记忆, 有相关成果就在其上开发, 没有则先设计调研。
+
+### 3. 白箱方法
+
+- **触发**：trained_on_4docs_intro
+- **动作**：识别任务条件→找知识/规则(并行递归)→精准执行; 正确→记录; 错误→找条件
+- **不适用**：需要快速执行的短期事项｜情感交互｜闲聊
+- **声明**：按工作纪律第3条: 白箱方法——用认知图【识别条件→找知识规则→精准执行】, 正确记录/错误找条件/不猜测/未验证不写入。
+
+### 4. 根因纪律
+
+- **触发**：（无前置条件，始终适用）
+- **动作**：检测偏差→细究根因(不猜测)→找根源条件→验证→记录认知图→填补negative
+- **不适用**：情感交互｜闲聊
+- **声明**：按工作纪律第4条: 根因纪律——先取证现场不猜测; 根因找到并验证后归档认知图并补不适用条件。
+
+### 5. 验证纪律
+
+- **触发**：入库前｜提交前
+- **动作**：入库/提交前→回放/断言/回归验证→通过才固化
+- **不适用**：情感交互｜闲聊
+- **声明**：按工作纪律第5条: 验证纪律——入库前必须过回放/断言/回归验证, 未验证不固化。
+
+### 6. 双副本纪律
+
+- **触发**：多副本部署｜改动主仓库/插件
+- **动作**：改动→同步到所有副本→提交前 git status 核对
+- **不适用**：单副本｜情感交互｜闲聊
+- **声明**：按工作纪律第6条: 双副本纪律——多副本改动双向同步, 提交前核对 git status。
+
+### 7. 兜底纪律
+
+- **触发**：（无前置条件，始终适用）
+- **动作**：检测主路径不可用→切等价兜底→写进 prompt/文档
+- **不适用**：情感交互｜闲聊
+- **声明**：按工作纪律第7条: 兜底纪律——主路径不可用则切等价兜底(如MCP→python直调), 并写进文档。
+
+### 8. 中文思考
+
+- **触发**：中文区域｜中文项目开发过程
+- **动作**：判定复杂度(情绪: 新奇/挑战/曾受批评 + 信息差: 不确定度)→复杂?「我们需要」深思考+确认 | 简单?「让我」快速执行; 推理开篇即中文锚点; 全程中文, 仅代码/标识符/引用保留原文
+- **不适用**：需要英文编写的场景｜英文环境｜英文文档｜国际接口
+- **声明**：按工作纪律第8条: 中文思考——中文书写; 复杂(新奇/挑战/曾受批评/高信息差)→「我们需要」交流确认互补盲区; 简单→「让我」快速执行不空耗; 每段推理开篇用中文短语锚定语言。
+
+### 9. 敏感信息隔离
+
+- **触发**：文档含敏感信息｜含个人隐私｜含私有内容
+- **动作**：识别文档是否含敏感信息→若含→只写私有库(AEIS)+不上传公开库+推送描述不写敏感词；若不含→正常处理
+- **不适用**：文档无敏感信息｜纯公开技术内容
+- **声明**：按工作纪律第9条: 敏感信息隔离——含敏感/隐私内容只放私有库(AEIS)，不推公开库，推送描述不写敏感词。
+
+### 10. 图像选源护栏
+
+- **触发**：构建图像四类图｜选图像处理源
+- **动作**：选源→_guard_source 依kind判ACCEPT/REJECT/DEFER→未ACCEPT不构建
+- **不适用**：已核对规范源｜纯公开数据
+- **声明**：按工作纪律第10条: 图像选源护栏——核对历史参考, 拒处理版/实色线稿/退化产物, 未验证不写入。
+
+### 11. 历史查询优先(先查记录再做)
+
+- **触发**：选图像/算法/源｜复现已有能力
+- **动作**：定位产物图→查记录→定位源码算法→确认阈值机制→用该算法生成；未找到→DEFER
+- **不适用**：已有记录且已核对｜无历史可查的纯新算法
+- **声明**：按工作纪律第11条: 历史查询优先——先查记录/源码用已走通算法, 未找到不盲选DEFER；线稿用darkline(Sobel+mean+std*1.5)白底黑线, 拒raw canny/zone_linework。
+
+### 12. 算法权威唯一(根因纪律)
+
+- **触发**：选图像/视觉算法｜复现已有能力
+- **动作**：选算法→查唯一权威文档→用文档算法→若需换: 记录原因+更新文档后再换
+- **不适用**：无对应权威文档的探索期
+- **声明**：按工作纪律第12条: 算法权威唯一(线稿=darkline.py/色块=contour_semantics)——选算法查文档, 勿临时切换/漂移; 换算法须记录+更新文档。
+
+### 13. 访谈澄清(先问清再动手)
+
+- **触发**：重要项目｜需求模糊｜新任务启动
+- **动作**：任务启动→开访谈(grill_start)→逐轮提问(frontier)→全部落定→与使用者确认共识→执行/固化(grill_finish); 放弃用 abandon(可逆)
+- **不适用**：情感交互｜闲聊｜明确单步小改动
+- **声明**：按工作纪律第13条: 访谈澄清——先提问确认要做什么,逐轮问到完全清楚才动手;事实自查,决策归使用者,不完全清楚不固化。
+
+### 14. 内容政策合规
+
+- **触发**：对外公开产物｜提交公开仓库｜数据集/文档产出
+- **动作**：产出→过内容政策清单(POLICY_DENY)→过隐私脱敏→双复检0命中→提交；已发布违规→删条+重写历史+通知平台清缓存
+- **不适用**：纯内部私有产物｜不含违规内容且无隐私
+- **声明**：按工作纪律第14条: 内容政策合规——对外公开产物必须过「内容政策+隐私」双清单，过滤在生成阶段做；已发布发现违规要删条+重写git历史+通知平台清缓存。
+
+### 15. 命令执行统一走python
+
+- **触发**：执行命令｜运行测试/脚本｜跨进程读写文本
+- **动作**：构造 argv 列表→subprocess.run(capture_output=True, text=True, encoding='utf-8', errors='replace')→env 带 PYTHONUTF8=1→shell=False
+- **不适用**：IDE 内置工具直调｜无跨进程的纯内存计算
+- **声明**：按工作纪律第15条: 命令执行统一走python——argv列表+显式UTF-8+PYTHONUTF8=1, 不经Windows shell, 规避GBK解码异常。
+
+### 16. 任务收尾归档(记忆闭环)
+
+- **触发**：任务执行完成｜修改落地后｜交付后
+- **动作**：任务收尾→提炼核心修改(内容/原因/位置/验证结论四要素, 不写中间过程/试错/调试/重复确认)→按 CCG 六要素成文(# 功能名/# 生效条件/# 子功能/# 执行/# 验证方式/# 不适用条件 六行缺一不可, 与正文四要素并置)→写入灵枢记忆(认知图/MCP memory)→读回确认(写入后发起一次读取查询确认写入成功且可检索)→标注关联条目+更新 subgraph/depends_on
+- **不适用**：情感交互｜闲聊｜纯查询无改动
+- **声明**：按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。
+
+### 17. 任务派发统一走蜂巢
+
+- **触发**：执行性任务｜多智能体协作｜批量/并行工作｜探索盘点｜运行测试/脚本
+- **动作**：任务→拆spec(LLM委托型=默认exec.py: model+user_prompt+context_files; 确定性执行=自定义worker, 契约「读spec.json写result.json」)→hive_spawn/CLI submit→poll→汇总; 兜底情形须声明「蜂巢不可用, 兜底降级」
+- **不适用**：纯会话内对话/问答(无执行动作)｜蜂巢不可用且任务必须立即执行(兜底须声明)｜情感交互｜闲聊
+- **声明**：按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。
+
+## 声明出口（`response.direct` 原文 · 未输出即未执行）
+
+| # | 声明（response.direct 原文） |
+|---|---|
+| 1 | 按工作纪律第1条: 理论先行——先查相关理论与既有实践再动手。 |
+| 2 | 按工作纪律第2条: 全面处理——先读任务/工作记忆, 有相关成果就在其上开发, 没有则先设计调研。 |
+| 3 | 按工作纪律第3条: 白箱方法——用认知图【识别条件→找知识规则→精准执行】, 正确记录/错误找条件/不猜测/未验证不写入。 |
+| 4 | 按工作纪律第4条: 根因纪律——先取证现场不猜测; 根因找到并验证后归档认知图并补不适用条件。 |
+| 5 | 按工作纪律第5条: 验证纪律——入库前必须过回放/断言/回归验证, 未验证不固化。 |
+| 6 | 按工作纪律第6条: 双副本纪律——多副本改动双向同步, 提交前核对 git status。 |
+| 7 | 按工作纪律第7条: 兜底纪律——主路径不可用则切等价兜底(如MCP→python直调), 并写进文档。 |
+| 8 | 按工作纪律第8条: 中文思考——中文书写; 复杂(新奇/挑战/曾受批评/高信息差)→「我们需要」交流确认互补盲区; 简单→「让我」快速执行不空耗; 每段推理开篇用中文短语锚定语言。 |
+| 9 | 按工作纪律第9条: 敏感信息隔离——含敏感/隐私内容只放私有库(AEIS)，不推公开库，推送描述不写敏感词。 |
+| 10 | 按工作纪律第10条: 图像选源护栏——核对历史参考, 拒处理版/实色线稿/退化产物, 未验证不写入。 |
+| 11 | 按工作纪律第11条: 历史查询优先——先查记录/源码用已走通算法, 未找到不盲选DEFER；线稿用darkline(Sobel+mean+std*1.5)白底黑线, 拒raw canny/zone_linework。 |
+| 12 | 按工作纪律第12条: 算法权威唯一(线稿=darkline.py/色块=contour_semantics)——选算法查文档, 勿临时切换/漂移; 换算法须记录+更新文档。 |
+| 13 | 按工作纪律第13条: 访谈澄清——先提问确认要做什么,逐轮问到完全清楚才动手;事实自查,决策归使用者,不完全清楚不固化。 |
+| 14 | 按工作纪律第14条: 内容政策合规——对外公开产物必须过「内容政策+隐私」双清单，过滤在生成阶段做；已发布发现违规要删条+重写git历史+通知平台清缓存。 |
+| 15 | 按工作纪律第15条: 命令执行统一走python——argv列表+显式UTF-8+PYTHONUTF8=1, 不经Windows shell, 规避GBK解码异常。 |
+| 16 | 按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。 |
+| 17 | 按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。 |
+
+## 记忆接口速查（`cg` / `stg`）
+
+工具名随端：MCP 端 = server「mdcg」的 `cg` / `stg`；DSH 端 = 内建基元 `lingshu_cg` / `lingshu_stg`（与 `cg` / `stg` 同一服务，仅注册名不同）。**`op` 一律必填。**
+
+| op | 用途 | 常用参数 |
+|---|---|---|
+| `route` | 任务开始路由记忆（返回知识 + 建议能力，不执行） | `intent`（任务意图） |
+| `read` | 召回/检索/按 id 取（`session`=只取该会话归属的记忆，缺省不过滤） | `query` / `node_id` / `k` / `layer` / `budget_tokens` / `context` / `session` |
+| `write` | 写入（先按 content_kind 审核 + 冲突检测，ACCEPT 落盘 / DEFER 入审核队列 / REJECT 入负记忆）。**自动归属**：frontmatter 带 `writer`/`session`/`harness`（服务端身份，不可伪造） | `content` / `content_kind`（text/code/…）/ `node_id`（同 id 即改写）/ `layer` / `tags` / `importance` / `verification_basis` / `condition_space` / `gated` / `consistency` / `on_conflict`（reject\|defer\|record） |
+| `verify` | 对节点做证据验证（confirmed/weakened/falsified）——**非队列裁决** | `node_id` / `verdict` / `evidence` |
+| `review` | 审核队列：`action=list/rounds/records` 查看；传 `pid`+`decision`+`reason` 即裁决落盘（accept/reject/edit/merge，**需 can_admin**；本机未配置外部验证器时写入恒 DEFER 入队，靠此裁决落盘） | `action` / `pid` / `decision` / `reason` / `edits` / `merge_into` |
+| `task` | 结构层任务实体（工程台账，跨会话/上下文压缩后不遗忘）：`name` 即身份（同名即同任务，slug 归一），`action` = open/status/plan_add/get/list/find/session（缺省 list）；**迁 `done` 必须同时给 `result`**（缺一不收，拒收不落盘）；未提供的字段沿用旧值（结果不会被静默清空） | `name` / `action` / `plan`（分步计划，每轮覆盖） / `change`（计划变更，逐轮追加） / `result` / `task_status`（active\|blocked\|done\|dropped） / `goal` / `acceptance` / `boundary` / `condition` / `node_id` |
+| `recent` | 近期事件窗口 | `action`（add/list/clear）/ `limit` |
+| `forget` / `protect` | 软删除/恢复 / 写保护 | `node_id` |
+| `help` | 取回工具面上**被投影外置**的完整 op / 参数文档（工具面渐进披露：常驻提示只留一行职责，参数语义按需取；不带 `query` 则列出全部工具） | `query`（工具名或 op 名，如 `cg` / `write`）/ `limit` |
+
+三条调用铁律：
+1. **`op` 必填**——漏传会触发参数签名推导兜底（返回标记 `op_derived: true`），复杂任务中也必须显式传，防静默执行错误意图。
+2. **返回 `moved_to: "review_queue"` / `verdict: DEFER/REJECT` 时不要重试**——这是校验闸门的正常行为（返回自带 `hint` 说明），重试同样结果；落盘须由设计者权限（can_admin）经 `op=review` 裁决（decision=accept/reject/edit/merge，本机工具：`python scripts/review_cli.py list`），agent 端无裁决权是设计（写入者不得自裁自决），转告使用者即可。
+3. `stg` 同理经 `op` 分发（`timeline` / `relation` / `anchors` 等）。
+
+## 收尾强制流程（任务完成时不可跳过）
+
+1. **验证**（第 5 条）：未验证不固化——回放／断言／回归通过才收尾。
+2. **归档**（第 16 条）：提炼关键修改（内容／原因／位置／验证结论四要素，禁写中间过程）→ 写入灵枢记忆。
+3. **自检**（第 4 条）：本次是否有违规？有 → 按条件层归因，并补不适用条件。
+
+## 本文件维护（防漂移）
+
+- 真源唯一：`docs/工作纪律_认知图条目_v1.1.json`。
+- 本文件是**渲染产物**，不是手抄投影；任何端的手改都会被 `scripts/verify_discipline.py` 判为漂移。
+- 改纪律 → 改真源 → `render_discipline.py --write` → `verify_discipline.py` 通过 → 提交。

package/codebuddy/README.md

@@ -0,0 +1,78 @@
+# CodeBuddy 端 · 灵枢接入配置
+
+本目录 = **CodeBuddy harness 专属配置**（灵枢 = Lingshu 记忆系统）。与 `dsh/`、`zcode/` 平级，
+共享层（`md_cg/` 大脑、`data/`、`docs/`、`scripts/`）在仓库根，不属任何单端。
+
+## 目录内容
+
+| 文件 | 作用 | 性质 |
+|---|---|---|
+| `CODEBUDDY.md` | 16 条工作纪律全文（会话起始注入） | **渲染产物**，勿手改 |
+| `mcp.json` | 灵枢 MCP server 接入模板（复制进 CodeBuddy 设置） | 模板 |
+| `README.md` | 本文件（接入说明 + 记忆策略） | 手写 |
+
+## 三步接入
+
+### 1. 接入记忆大脑（MCP）
+
+把 `mcp.json` 里的 `mcpServers.mdcg` 一段合并进 CodeBuddy 的 MCP 配置，然后把
+`PYTHONPATH` 的占位值（`REPLACE_WITH_ABSOLUTE_PATH_TO_dsh-memory`）替换为**你本机
+dsh-memory 仓库所在目录**。此处须用可解析的绝对路径——Python 要据此定位仓库内的 `md_cg`
+包，相对路径会随进程工作目录漂移而失效。
+
+`md_cg` 大脑随仓库自带，**无需 pip 安装任何引擎**；只需本机有 Python 与 Node ≥ 22.19。
+
+> **工具面 `MDCG_MCP_SURFACE=kernel`**（与 `md_cg/mcp_server.py` 的默认值一致）：只暴露 `cg` /
+> `stg` 两个认知基元；`cg` 已覆盖 `route` / `read` / `write` 等全部 op，**写入通道不缺**。
+> 细粒度 `mdcg_*` 工具仅在 `full` 面可见，属兼容 / 调试用途，日常接入无需开启。
+
+### 2. 注入工作纪律
+
+把 `CODEBUDDY.md` 复制到**你项目的根目录**。
+
+> CodeBuddy 规则优先级：根目录存在 `CODEBUDDY.md` 时会**忽略 `AGENTS.md`**。
+> 本仓库刻意把产物放在 `codebuddy/` 子目录而**不落根**——因为仓库根的 `AGENTS.md`
+> 是本地私有载体（含本机运维注记，已被 `.gitignore` 忽略）。子目录放置既让外部用户可直接取用，
+> 又不屏蔽本地纪律。
+
+### 3. 重启会话
+
+纪律在**会话开始时全文注入一次**，改动后须新建会话才生效。
+
+## 记忆策略：只记重要内容，不记流水
+
+灵枢是记忆系统，但**什么都记等于什么都不记**——因此写入侧有两道机制化过滤，而非靠人自觉：
+
+| 层 | 内容 | 落点 | 过滤方式 |
+|---|---|---|---|
+| **重要内容** | 核心修改：内容 / 原因 / 位置 / 验证结论 | `knowledge` / `self` 层 | `cg(op=write, gated=true)` 过**三问四态闸门**，非 `ACCEPT` 不落盘 |
+| **对话记录** | 会话转录 | `contextual` 层 | 主动遗忘闸门按重要性阈值自动 `DROP` 低熵噪音 |
+
+- **纪律第 16 条**要求每次任务收尾主动归档核心修改——这是「对话 → 长期记忆」的闭环入口。
+- **严禁**写入中间过程 / 试错步骤 / 调试细节 / 重复确认；这类内容会污染检索、干扰后续召回。
+- CodeBuddy 侧**没有** DSH 那样的会话 hook 自动记忆，故记忆沉淀由纪律驱动（Agent 在收尾显式调用
+  `cg(op=write, gated=true)`），而非进程自动抓取。
+
+## 写入凭据（决定能否真正落盘）
+
+`md_cg` 是 **fail-closed**：不配凭据时插件以**只读 guest** 运行——读取 / 召回 / 时间线照常，
+但记忆写入**不落盘**。要落盘请签发令牌：
+
+```bash
+python -m md_cg.tokens issue --role designer --actor codebuddy --clearance internal ^
+  --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify ^
+  --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
+```
+
+然后把 `MDCG_TOKEN` 填进 `mcp.json` 的 `env`（或设系统环境变量后引用）。
+
+> **别把 `ok: true` 当写成功**：未落盘时返回体形如
+> `{"ok": true, "committed": false, "moved_to": "review_queue"}`——是否落盘**只看 `committed`**。
+
+## 维护（面向灵枢维护者）
+
+- `CODEBUDDY.md` 由 `scripts/render_discipline.py` 从**唯一真源** `docs/工作纪律_认知图条目_v1.1.json`
+  渲染生成，矩阵见 `docs/discipline/harnesses.yaml`（`codebuddy` 槽位）。
+- 改纪律 → 改真源 → `python scripts/render_discipline.py --target codebuddy --write`
+  → `python scripts/verify_discipline.py --target codebuddy` 通过 → 提交。
+- **手改本目录的 `CODEBUDDY.md` 会被 `verify_discipline.py` 判为漂移**。

package/codebuddy/mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "mdcg": {
+      "command": "python",
+      "args": ["-m", "md_cg.mcp_server"],
+      "env": {
+        "PYTHONPATH": "REPLACE_WITH_ABSOLUTE_PATH_TO_dsh-memory",
+        "PYTHONUTF8": "1",
+        "PYTHONIOENCODING": "utf-8",
+        "MDCG_MCP_SURFACE": "kernel",
+        "MDCG_ACTOR": "codebuddy",
+        "MDCG_TENANT": "default",
+        "MDCG_CLEARANCE": "private",
+        "MDCG_TOKEN": ""
+      }
+    }
+  }
+}

package/docs/Pi/345/217/257/345/255/246/344/271/240/344/274/230/347/202/271_/347/201/265/346/236/242/345/244/247/350/204/221/346/224/271/350/277/233/344/272/244/346/216/245_20260915.md

@@ -0,0 +1,144 @@
+# Pi 可学习优点 · 灵枢大脑改进交接文档
+
+> 交接方：ZCode 端 · 接收方：**CodeBuddy 端**
+> 交接时间：2026-09-15 · 依据：荣指令「整理完整的 Pi 可学习优点文档，交接 CodeBuddy 处理，避免灵枢大脑版本不一致」
+> 素材：`agi-architectures/pi/`（浅克隆，MIT 许可，代码思想可吸收）· 三轮源码深读结论（状态管理/会话持久化/压缩、扩展机制、上下文工程、协议哲学）
+
+---
+
+## 0. 一句话交接
+
+pi（Pi Agent Harness，105k★）把**事件溯源、显式状态机、渐进披露、可逆压缩、钩子化扩展**做到了 coding agent 领域的标杆；本文档将其七项可学习优点逐项映射到灵枢大脑（`md_cg`）的改进落点，每项带 pi 源码证据、灵枢现状基线、建议落点与验收口径。
+
+## 1. 版本与落点纪律（⚠️ 防版本不一致，先读）
+
+| 仓 | 角色 | 本次改动落点 |
+|---|---|---|
+| `dsh-memory/` | **大脑 · 唯一主线**（荣 2026-09-14 裁定：中文编译器并入大脑作核心架构） | ✅ **本文件全部改进落这里**（`md_cg/` 为主） |
+| `AEIS/` | 身体仓：记忆真源数据（`data/mdcg/`）+ `tools/coggraph/` 可视化管线 | ❌ 不改代码；数据真源对管线**只读** |
+| `protocol-compiler/` | 已冻结（世界模型测试地点，荣 2026-09-14 裁定） | ❌ 不动 |
+
+- 记忆真源 = `AEIS/data/mdcg/`（11,195 节点，纯 md，主链路零 SQLite）；`md_cg` 通过路径锚（`data/paths.json`）访问，**不要**在 md_cg 内硬编码本机路径（沿用 `--root`/`MDCG_ROOT`/datapath 约定）。
+- coggraph 可视化管线（DSH→CodeBuddy 另一份交接 `AEIS/docs/知识图谱项目_交接文档_20260914.md`）与本文件**并行不冲突**：那边管可视化与语义层，本文件管写入纪律与运行时。两者都遵守「管线只读真源、产物不入库」。
+- 改动后必须跑全量回归（`python -m md_cg.test_pXX` 形式，60+ 套件）不回退；测试只能模块方式跑，直接 `pytest md_cg/` 会崩（相对导入，已知 P2 缺陷）。
+
+## 2. pi 素材位置（查证入口）
+
+| 内容 | 路径（相对 `agi-architectures/pi/`） |
+|---|---|
+| 状态机/会话/存储 | `packages/agent/src/harness/session/`、`runtime/`、`drive/` |
+| 压缩 | `packages/agent/src/harness/compaction/compaction.ts`（865 行） |
+| 扩展机制 | `packages/coding-agent/docs/extensions.md`（API 全典）、`src/core/extensions/` |
+| 上下文组装 | `packages/coding-agent/src/core/system-prompt.ts`、`skills.ts`、`tools/` |
+| 安全立场 | `packages/coding-agent/docs/security.md` |
+
+## 3. 可学习优点清单（按建议优先级排序）
+
+> **完成度判据（2026-09-16 补正）**：各项的「落地状态」是**手工标注、无机械守卫**，历史上多次滞后于代码（① ② ④ ⑥ 已入库而本文件长期漏标）。**判断某项是否完成，请以认知图落地记录 + `git log` 提交取证为准**，本文件的标注只作索引——与「手写行号必腐化」同构：无守卫的手工标注必漂移。此纪律已由实证触发：本轮曾据「本文件未标落地状态」误判 ① 未落地，被使用者纠正。
+
+### ④★P0 记忆演化 fork（最高价值——条件论反事实的实验场）
+
+- **pi 机制**：会话是 entry 树，任意历史节点可 fork；两种 scope（`branch` 只拷贝某分支路径 / `tree` 拷全树），运行态一律不复制（`session/types.ts:562-602`、`jsonl/repo.ts:146-196`、`fork-policy.ts:56-63`）；被放弃旁支由 branch_summary 归档（2048 token 定长摘要，`branch-summarization.ts:87-118,274`），切回时提供上下文。
+- **灵枢现状**：认知图是**单一演化线**（`_evolution/ledger.md` 2,650 行账本），没有假设分支。条件论的「负条件/反事实显式化」在记忆层没有实验场。
+- **建议落点**：`md_cg/mdcg.py` 新增 fork 层（节点 frontmatter 加 `branch_id`/`branched_from`；派生索引记分支 tip），`stg.py` 支持分支时间线；新增 `branch_summary` 节点类型（复用 `NEG_MEMORY_MARKS` 式的必填 MARKS 模式）。语义：大规模改写/遗忘策略变更前先 fork 推演，验证通过合并回主支（合并=按 `derived_from` 溯源回写），失败归档 branch_summary 教训节点。
+- **验收**：fork→改写→合并后主支节点 `derived_from` 链完整可回溯；放弃分支不污染主支检索（召回主支时 branch 节点零命中）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `419305c`）。落点 `md_cg/branches.py`（新，分支真源）+ `md_cg/test_branches.py`（新）+ `mdcg.py`/`mdcos.py`/`mcp_server.py` 接线。语义：`BRANCH_MARKS` 教训必填 + 命名守卫；`fork`（副本 nid=`<主支>@<bid>`，layer/tags/importance/cs 继承旧 fm，`derived_from=[主支]`/`relation=split_from`，fm 落 `branch_id`/`branched_from`/`branch_note`）；`rewrite` 为**分支改写的唯一正路**——关键机制发现：`add` 是**全量重建 fm**（非增量更新），裸 add 改写分支节点不重传 `branch_id` 会让副本在索引退化成主支、实验内容泄漏进主支检索，故 `rewrite` 强制归属/血缘从旧 fm 继承、同名 extra 键剥离、override 快照留痕；`merge` 分支级合并（逐节点按 `branched_from` 溯源回写，主支缺失 `skipped` 不炸）；`discard`（require_admin→MARKS 校验→`branch_summary_<bid>` 教训节点入 knowledge→文件 `os.replace` 移冷区 `_branches/<bid>/`→索引摘除→audit）；`list_branches`。检索**一处过滤全链路生效**（`mdcg.search/_stage/_scan_nodes` 与 `mdcos._candidates` 加 `branch=None`：分支节点仅主支+本 branch 可见，与 session 过滤正交）；`mdcos` insight 增六分支 act。
+  **偏离建议**：实现落**新模块** `branches.py` 而非文档建议的内联进 `mdcg.py`（`stg.py` 分支时间线未做）。**边界（如实）**：分支节点**不出库**（冷区 `_branches/` 在 root 下 LAYERS 外、索引隐身——永不删除但检索不可见）；`merge` 是分支级而非节点级。验收：`test_branches` **41/41** 全绿（含主支零污染，断言口径=分支 nid 不在命中集而非结果为空）、回归 10 套件 292 断言全绿、cogmap check 绿、lint 0。
+
+### ⑥★P0 写入路径钩子化（闸门即扩展）
+
+- **pi 机制**：全生命周期事件总线，每个钩子可改变行为——`before_agent_start` 改提示词、`context` 每次 LLM 调用前改消息、`tool_call` 阻断/改参、`session_before_compact` 整体替换压缩（`docs/extensions.md:277-349,452-475,780-848`）。闸门/路径保护/审批全是以扩展形态叠加的，核心没有硬编码策略。
+- **灵枢现状**：写入侧闸门族已经是管线形态——role 作用域闸（`mcp_server.py:1434`）→ 冲突闸（:1656）→ 审核闸（:1707）→ 校验闸（:1715）→ 主动遗忘闸门（`forgetting.assess` 三问四态）→ writelimit（写侧限流+同构聚合，`writelimit.py`）→ canonical 语义归一（`semantic/canonical.py`）。**次序与启停硬编码在 write 路径里**，加一道闸要改核心代码。
+- **建议落点**：`md_cg/mcp_server.py` 写路径重构为拦截器链：`before_write(ctx) -> verdict`（可 ACCEPT/MERGE/DROP/DEFER/改写）与 `after_write(ctx)` 两个挂载点，现有六道闸全部改注册为拦截器（行为不变，回归护航），token 角色校验保留在链首**不可卸载**（见 §4 反面清单——不学 pi 的全权信任）。
+- **验收**：全部既有写入测试（`test_md_writepath.py`/`test_writelimit.py`/`test_verify_answer.py` 等）零改动通过；新增/移除一个拦截器不改核心文件。
+- **落地状态（2026-09-15 · CodeBuddy 端）：✅ 已落地**（commit `419305c`）。落点 `md_cg/writepipe.py`（新，拦截器链真源）：write 分支原 128 行硬编码流程重构为链式——`register_before`/`unregister` 即插即拔、**链尾 executor 常驻**（保证「链上无拦截器也能落盘」）、`after` 观测者、REWRITE 语义（拦截器可改写内容后交下游）；`mcp_server.py` 的 op=write 收敛为**一行分发**。
+  **权限闸保持库层不可绕过**（刻意的不对称）：「卸掉链上全部拦截器」≠ 取得写权限，token 角色校验不因闸门可组合化而下放——对齐 §4 反面清单「不学 pi 的全权信任」。验收：`test_writepipe` **18/18** 全绿 + 全部既有写入测试**零改动通过**（writepath 52 / writelimit 全过 / verify_answer 31 / identity 14 / conformance 26 / p2_mcp 63）。
+
+### ①P1 上下文经济学：工具面与纪律的分层驻留
+
+- **pi 机制**：system prompt 约 150 词骨架（`system-prompt.ts:127-144`）；工具只以**一行 snippet** 常驻系统提示，完整描述只进 API tools 字段（`system-prompt.ts:82-84`）；8 个内建工具默认只激活 4 个（`agent-session.ts:2831-2834`）；skills 只驻留「name+description+path」三元组 XML 索引，正文由 agent 任务匹配时自己 read（`skills.ts:355-383`）。
+- **灵枢现状**：MCP 工具（cg/stg）的 op 参数空间全量 schema 常驻；16 条工作纪律全文常驻 AGENTS.md。
+- **建议落点**：`md_cg/mcp_server.py` 工具 schema 瘦身（一行职责+`docs/工具详细说明.md` 按需引用）；纪律/技能分层（索引常驻、正文文件化按需读）；评估工具子集按 profile 启停（对齐已有 `tools: 'core'|'brain'|'all'` 三档，做到档内再分层）。
+- **验收**：瘦身前后工具描述 token 数对比产物（目标 ≥50% 削减）；检索/写入功能回归零变化。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `c789e95`，同批含「索引幽灵条目根因修复」）。落点 `md_cg/tool_face.py`（新，**投影真源**）+ `md_cg/test_tool_face.py`（新）+ `mcp_server.tools_for_surface` 返回 slim 投影（开关 `MDCG_TOOL_FACE=full` 回到真源）+ cg 新增 **op=help**（`tokens.ALL_OPS` 同步登记）。
+  **信息守恒的结构性保证（本项能减 token 而不减能力的原因）**：被投影掉的原文**不复制、不搬运**，`cg(op=help, query=…)` **从真源即时渲染取回**——不存在第二真源、零漂移面。这是「瘦身」与「信息丢失」的分界线。**偏离建议**：文档建议的「纪律/技能分层驻留」「按 profile 分层启停」两项本轮**未做**（本轮只落工具面投影层）。**顺带修正**：补齐 6 个「op 枚举里有、说明段缺失」的真源文档段（session/ingest/export/maintain/consolidate/insight）——分层后这些会真丢能力，属实测发现的既有缺口。
+  验收：注入面 kernel **20878→8330 字符（−60.10%）**、full31 20347→15221（−25.19%）、all 33 工具 41225→23507（−42.98%）；`test_tool_face` **23 断言**全绿（削减≥50% + 工具名/参数名/顺序/required/类型/枚举值集**逐位不变** + 外置参数经 op=help **逐字**取回 + op 枚举每项都有说明段 + 开关与幂等 + 真源 schema 零改动）；MCP 回归 63/63；72 套件全量回归除 2 个 pre-existing 失败外全绿。
+
+### ②P1 记忆节点显式生命周期状态机
+
+- **pi 机制**：运行操作 = 13 叶子显式状态机（`session/types.ts:315-329`），drive 循环按 `at` 分发；一轮无任何进展抛 `SessionInvariantError`（`drive.ts:101-104`）——非法迁移在结构上不可能。
+- **灵枢现状**：节点生命周期状态**散落**：writelimit 的 `tidy:converged` 标记、forgetting 的 importance 降权、`_evolution/ledger.md` 账本、`protect` 的 protected 标记——没有一个统一状态字段，迁移合法性无校验。
+- **建议落点**：`nodefile.py` frontmatter 新增 `state` 字段（建议集：`active → converged → demoted → archived`，受保护节点单独豁免），`mdcg.py` 写入时校验迁移合法性（非法迁移拒绝，负路由）；存量节点默认 `active`，一次性回填。
+- **验收**：非法迁移用例被拒且回归零变化；`_index.json` 索引快照带 state（免读文件可查）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**（commit `2ebf8f0`）。落点 `md_cg/lifecycle.py`（新，**状态机唯一真源**）+ `md_cg/test_lifecycle.py`（新）。`STATES` = `active → converged → demoted → archived`；`TRANSITIONS` 合法迁移表（逐级降级/回升，**拒跳级**）；`check()` 纯函数裁决（`code ∈ ok/noop/unknown_state/illegal_transition/protected`）；`stamp()` 就地推进（复用供需等字段的**同批落盘收口点**，免重复写盘）；`set_state()` 单点推进 + `_lifecycle.jsonl` 审计；`backfill()` 存量回填（dry-run/apply 幂等）。
+  **偏离建议（字段名，重要）**：新增字段取 **`lifecycle_state`** 而非文档建议的 `state`——`state` 已被认知图**裁决四态**（ACCEPT/REJECT/DEFER/BLINDSPOT）占用，复用会让「资格裁决态」与「生命周期态」两个正交轴撞进同一字段（真源节点 fm 现同时带 `state` 与 `lifecycle_state`，可实证两轴并置）。**边界（如实）**：本项落地**不含** Ghidra G3 所设想的 `unanalyzed` 取值——状态集仅四项，分析覆盖度不进生命周期轴（G3 改由 conformance 派生判据承载，见 ⑤ 落地状态）。
+
+### ③P2 写入两段式提交（intent/结果对账）
+
+- **pi 机制**：工具调用先持久化 intent+参数（status=effect_pending）再执行，完成后原子写结果；崩溃后 `replay:"safe"` 工具重放，否则合成 interrupted 结果——消息永不缺失（`drive/tools.ts:187-227,515-540`）。
+- **灵枢现状**：`_audit.jsonl` 已是追加式操作日志（coggraph 会话串链的数据源），但只有 op=add 事后记录，**没有写入意图的先行持久化**，崩溃时无法区分「写了没落盘」。
+- **建议落点**：`md_cg` 写路径在闸门通过后先落 `_audit.jsonl` intent 事件（含 content_hash），写入完成落 outcome 事件；启动时对账（有 intent 无 outcome 的写入做 content_hash 校验补账）。工具幂等声明可后置（md_cg 写入天然可重放：同 hash 幂等）。
+- **验收**：kill -9 模拟半途写入后重启，对账报告正确补账/标记；`test_lock.py` 回归通过。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**。`md_cg/twophase.py`（新，两段式真源）+ 两条真实落盘路径接线（`writepipe.py`：链尾执行器 / `_gate_gated` 替代落盘路径各自 begin→commit）+ 库层门面（`mdcg.reconcile_writes` / `pending_writes`）+ MCP 启动自动对账（`mcp_server.py`，失败不阻塞启动但必须 stderr 上报）。**偏离建议**：账本落**独立文件** `_write_2pc.jsonl` 而非本文档建议的 `_audit.jsonl`——理由见 `twophase.py` docstring（`_audit.jsonl` 已被当作单一语义流消费，混入三类事件会扰动既有断言口径；本仓已有 `protect.py/_protected_audit.jsonl` 独立审计惯例）。**边界（如实）**：对账只做「补账 / 如实标记」，**不重放写入**；`append_jsonl` 在 Windows 非原子（对账是增益、不是「保证不丢」）；`_gate_audit` 的 REJECT 负记忆与各闸 propose（无落盘动作）不在覆盖面内。验收：`python -m md_cg.test_twophase` 10 组 35 项全绿 + 全量回归零新增失败。
+
+### ⑤P2 conformance：数据健康不变量的周期巡检
+
+- **pi 机制**：`session/testing/conformance/`（storage 920 行 + session-repo 1185 行）把存储承诺写成断言：事务原子提交、seq 严格递增、非法写被拒且状态完全不变、close/reopen 状态保持、重放确定性。
+- **灵枢现状**：机制测试 60+ 套件很强；但**数据健康不变量**没有周期断言。2026-09-15 审计（灵枢 node_26b0973a）发现的存量问题：knowledge 层索引节点混层 57.9%、role 存量 99.99% 为空、evidence_count 仅 6 条、精确重复 90 条、闸门 DROP/DEFER=0、召回率 7%——全靠人肉审计发现。
+- **建议落点**：`md_cg/census.py` 产品化：把审计脚本（临时位置 `Temp/audit_write_effect.py`，可向 ZCode 端索取）改写为断言集（混层比例阈值/重复度阈值/字段覆盖率下限/闸门四态分布），挂 `sustain` 周期巡检；超阈值告警不自动改数据（治理另走 tidy/merge，永不删除）。
+- **验收**：census 断言集可一键复跑；对当前真源产出首份基线报告（以上数字应复现）。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 已落地**。`md_cg/conformance.py`（新，断言集真源）+ `md_cg/test_conformance.py`（53 断言自测）+ `sustain._tick_conformance` 挂点（复用 6h tidy 节奏，不新开周期）+ `.github/workflows/conformance-check.yml`。
+  **偏离建议**：①**不改造 `census.py`** 而新建 `conformance.py`——census 是**节点清单工具**（`by_keys`/`report`，答「有多少、在哪」），conformance 是**不变量断言集**（答「是否失真」），职责不同；且 census 已有 `test_census_prune` 既有口径，改其语义会牵连回归。②G3 `unanalyzed` 用**派生判据**（`evidence_count==0 ∧ basis 空 ∧ state 空`）而非字段级占位——生命周期是单向降级轴、与分析覆盖正交，塞同字段即破坏正交性；且 `verification_basis` 已有 `other` 逃逸口（真源 273 条在用），「分析过但无法归类」有归宿。③基线报告落**真源库同级私有目录**（`AEIS/data/conformance_baseline_mdcg.json`）、不入公开仓——基线是环境特定运维产物，随库增长变动，入库即制造虚假同步义务。
+  **口径更正（关键，9-15 审计数字的复现前提）**：审计的「role 99.99% 为空」「evidence_count 仅 6 条」是 **knowledge 层分母**；全库分母会把 99.991% 的空缺摊薄成「role 2.13%、evidence 12 条」，把严重空缺伪装成「还行」。故断言集**判据一律取 knowledge 层口径**、全库口径仅作对照。据此：role[knowledge]=0.009%（↔ 99.991% 空，与审计逐位吻合）、evidence[knowledge]=0.054%（↔ knowledge 层 6 条，吻合）。
+  **首份基线（2026-09-16，真源 nodes=11666）**：混层 6505/11113=**58.5%**（审计 57.9%，差=期间库增长）；`dir_mismatch=0`、`path_missing=0`、悬空边 0（不变量全绿）；重复 content_hash **93 组/186 节点**（审计 90 条）；闸门 decisions **142**（accept 115 / reject 21 / edit 6）、inbox_pending 0；触达率 **8.7%**（审计 7%；源为滚动追加日志，差异未逐条复算，故**不纳入基线不劣化比对**——日志轮转会误报）；G3 unanalyzed 派生 **4619（39.6%）**。
+  **G1 新发现（正交性审计的增量产出）**：①边类型空间**不封闭**——`above/counterpart/generalizes/instance_of` **未声明已用**（读侧退化 `chain.DEFAULT_EDGE_WEIGHT=0.50`，不炸但权重失真）、另有 8 个声明未用（`applies_to/parent_of/spatial_*` 等）；②**96.9%（5543/5719）的边用 legacy `type` 键**而非规范 `relation_type`——取证更正：`subgraph.children_index:122`/`parents_index:162` 已含 `or e.get("type")` 容错，**读侧不忽略**（`normalize_edge` docstring 称「会被静默忽略」属**文档滞后于代码**，已登记 `DOC_CODE_DRIFT`）；故该项判 **WARN 非 FAIL**（不冒充硬失败），仅以「不劣化」为判据；③`role` 与 `tag_prefix` **无模块级真源**（自由文本/命名约定）→ 标 `None`→BLINDSPOT，不冒充封闭；④`hierarchical` 同名反义（md_cg=本节点是子 / 白箱源库=source 是父）已登记为方向口径分歧；`part_of/parent_of/contains` 已核对**逐字对称、无分歧**（防止被反复误报）。
+  **验收证据**：`python -m md_cg.test_conformance` **53/53 全绿**（对照 test_p27【9】教训：自测**自备 tempfile 合成库**，外部 clone 下集成段自动 SKIP，不依赖仓外目录）；**回归 16 套件零失败**（conformance/census_prune/p14_sustain/sustain_mutual/p30/p41/p2_mcp 64/cond_match 17/p33 58/p36 34/p37 42/sem_noise 7/writepipe 18/branches 41/identity 14/autonomy 10，墙钟 3.6s）；lint 0。
+
+### ⑦P3 上下文组装工程细节（零散但便宜）
+
+pi 的细节清单（出处省略，均可直接对照源码）：错误/中止的 assistant 消息不入上下文；read 截断 2000 行/50KB 附续读提示；bash 大输出全量落盘临时文件+消息保尾部；图片自动缩 2000px、token 估算按 4800 字符/张；AGENTS.md 祖先链发现+worktree 防重复；**system prompt 不持久化，会话恢复时实时重建**（配置变更自动反映到旧会话）。
+灵枢对应落点：`stg.py`/recall 组装路径与 `compact_context`；「错误消息不入上下文」与「大输出落盘保尾」两条最值得先做。
+- **落地状态（2026-09-16 · CodeBuddy 端）：✅ 六条全落地 + 一条取证后判定「结构性已满足」**（改动面：`hive/exec.py`、`hive/test_exec_tools.py`、`md_cg/mcp_server.py`、`md_cg/test_read_clip.py`、`scripts/render_discipline.py`、`scripts/verify_discipline.py`、`scripts/test_injection_chain.py`、`docs/discipline/harnesses.yaml`、`.github/workflows/discipline-check.yml`）。
+  | pi 细节 | 灵枢落点 | 与 pi 的偏离 |
+  |---|---|---|
+  | 错误/中止 assistant 消息不入上下文 | `exec.py` 空轮护栏：`content` 与 `tool_calls` **双空** → 记日志 + `progress(error)` + `error` 终态，不再冒充有效终答（旧行为曾产出 `ok=true` + 空 content 的假成功） | 判据取「双空」而非「有 error 字段」——错误轮本身可能带有效 content（工具失败但模型给了说明），一律丢弃会**丢真信息** |
+  | read 截断 2000 行/50KB 附续读提示 | `mcp_server.py` `_clip_text` 双阈值（`READ_MAX_LINES`/`READ_MAX_BYTES`）+ `offset`/`next_offset` 续读；截断时**显式**返回 `truncated/total_lines/total_bytes/note`，未截断路径零新增键（旧调用方无感） | 阈值同 pi；**不静默**——「截了多少、从哪续」是返回体必带字段，不靠模型猜 |
+  | bash 大输出全量落盘 + 消息保尾 | `exec.py` 工具回喂面：全量落 `tool_<i>_<j>.json`，回喂消息保**头+尾**并插「中间省略」提示（对齐 `_dump_step`+`_render` 既有形态） | 保留头部（错误常在首屏），pi 只保尾 |
+  | 图片自动缩 2000px、4800 字符/张 | `exec.py` context_files 面：零依赖探测尺寸（PNG IHDR / JPEG SOF，不读像素内容）；超阈值按需处理并反馈「是否已压缩」；token 折算 `IMAGE_CHARS_PER=4800` | **不主动缩图**（处置由调用方决定、结果如实回报），不做隐式重编码 |
+  | AGENTS.md 祖先链发现 + worktree 防重复 | `render_discipline.py`（`_walk_ancestors` + `discover_injection_chain`）/`verify_discipline.py`（`check_injection_matrix`）/`harnesses.yaml`（`injection:` 声明段 + 每 target `slot:`） | 见下方「⑤ 关键取舍」 |
+  | system prompt 不持久化、恢复时重建 | `exec.py` `resolve_system_prompt`：`system_prompt_from` 声明后**每次执行重建**（rust 侧 claimed 重投的崩溃恢复窗口也覆盖），缺文件 **fail-closed**（明确失败优于静默沿用旧提示词） | **取证结论：默认路径结构性已满足**——hive 每次 spawn 由调用方重建 `system_prompt`，`spec.json` 是**任务证据**而非 pi 所指「持久化会话状态」，故不存在 pi 那个缺陷本体；仅补一条显式重建通道，未做无靶改动 |
+  **⑤ 关键取舍（防重复的真实落点）**：去重落在**目录层**——走祖先链按物理目录身份（realpath+normcase）折叠别名拼写，使 worktree/junction/大小写别名下同一份件只查一次。**反面已实证**：按「git 仓身份 + 仓内相对路径」做键**会错**——worktree 与其主仓的 `AGENTS.md` 是同相对路径但**物理不同的两个文件**（各自 checkout 一份），折叠即把真实重复注入源静默藏起；故此类同仓不同物理文件只**标注**（`wt_dups`）不折叠。判据分两档：**硬失败**（`path_dup` 同物理文件被两个 target 写；`root_shadow` 仓根遮蔽本地私有件 → 后者使本地纪律注入失效）与**发现面报告**（祖先链同槽位命中：仓内判定同源指纹、仓外属宿主侧事实，本仓不裁决但不得假定不存在）；每个 file target 必须声明 `slot` 且产物名在其槽位清单内（否则遮蔽判定失真），有守卫。
+  **验收证据**：`hive/test_exec_tools.py` **47/47**、`md_cg/test_read_clip.py` **14/14**、`scripts/test_injection_chain.py` **35/35**（含 junction 别名折叠实证、`path_dup`/`root_shadow` 两硬判据的**正向与恢复双向**断言、防重复反面对照）；`scripts/run_tests.py` 新增 `scripts` 组（scripts/ 非包 → 直跑）；`verify_discipline.py` 注入面全绿；CI `discipline-check.yml` 增挂注入面自检步（Linux 下 junction 项自动 SKIP，属环境差异非失败）。
+
+## 4. 反面清单（不学什么，与灵枢哲学冲突）
+
+| pi 做法 | 为什么不学 | 灵枢对应原则 |
+|---|---|---|
+| 无 sandbox/无审批，扩展以用户全权运行（security.md:35 自述有意设计，隔离外包 OS/容器） | 信任必须**结构强制且可复算**，不能靠文档告诫+一道 project trust | 位置效应、写权限互斥、凭据六角色（designer/reflection/verifier/recorder/output/sustain/guest） |
+| No MCP 立场（CLI+README 替代协议） | 灵枢保持双形态接口：MCP 服务 MCP 阵营（资格闸服务端强制），CLI 形态补「md 目录直改设防」后再开；协议哲学见荣 2026-09-15 纲领（唯一协议=智能论，字节层放开） | 智能论=唯一行为协议 |
+| 子进程模型（OASIS 式批处理/每工具一进程） | md_cg 主链路常驻+Rust `--serve` 检索形态已占优 | 记忆真源唯一+多端共享 |
+| 会话即全部记忆（无跨会话沉淀） | pi 的 session 文件就是它的全部记忆；灵枢的认知图蒸馏（16 条闭环）是**灵枢独有的维度**，绝不为对齐 pi 而弱化 | 记忆闭环（第 16 条） |
+
+## 5. 与既有工作线的边界（防撞车）
+
+- **writelimit.py（已落地 2026-09-15）**：contextual 层写侧限流+同构聚合+读侧 tidy——不要重做；③/⑤ 与它互补（两段式对账、census 断言）。
+- **coggraph 交接（DSH→CodeBuddy，另一份文档）**：可视化管线/语义层/命名治理归那边；本文件的 ①④⑥ 改 `md_cg` 核心不碰 `tools/coggraph/`。
+- **审计遗留五项**（role 回填/evidence 补齐/精确重复 90/闸门加严/召回 7%）：⑤ 的 census 会持续暴露它们；修复动作（回填/合并）另立子步，先断言后治理。
+
+## 6. 建议施工顺序
+
+1. **⑥ 钩子化**（先改结构，后续一切闸门策略都挂上去）→ 2. **④ fork**（条件论落地最大增量）→ 3. **① 描述瘦身**（立即降 token，独立可并行）→ 4. **② 状态机** → 5. **③ 两段式** → 6. **⑤ census** → 7. **⑦ 细节**。
+每步：实现 → 全量回归 → 灵枢归档（16 条四要素）→ 看板/文档同步。
+
+> **进度（2026-09-16 取证核）**：第 **1–6 步均已落地**——⑥④ 见 `419305c`、③ 见 `4201238`、① 见 `c789e95`、② 见 `2ebf8f0`、⑤ 见 `8fffc24`；**仅剩第 7 步 ⑦ 未开工**。落点与验收数字见 §3 各项「落地状态」。
+
+## 7. 快速上手（CodeBuddy 5 分钟）
+
+```bash
+# 1. 读本文档 §1 落点纪律 + §4 反面清单
+# 2. 查证 pi 源码（任选两条路径核对本文档行号引用）：
+#    agi-architectures/pi/packages/agent/src/harness/session/types.ts:315
+#    agi-architectures/pi/packages/coding-agent/docs/extensions.md:277
+# 3. 确认灵枢基线：python -m md_cg.test_p0（及全量 test_pXX 回归绿）
+# 4. §6 第 1–6 步（⑥④①②③⑤）已落地、仅 ⑦ 未开工——续做前先按 §3「完成度判据」取证
+```

package/docs/README.md

@@ -0,0 +1,111 @@
+# docs/ 目录索引
+
+> 按工程域分目录，与本仓 README「平台全景」五件套对应。新文档先归域、后登记到本页对应清单；跨域的横切件留顶层。改纪律真源路径前须核对引用面（AGENTS.md / 渲染管线 / md_cg 注释）。
+
+## 目录结构
+
+```
+docs/
+├── mdcg/      灵枢大脑 md_cg 工程（架构/工具表/发布/教程/护栏）
+├── swarm/     蜂群运行时 swarm/
+├── hive/      蜂巢并发引擎 hive/
+├── world_model/  世界模型神经网络底层架构（hex 系列台账）
+├── theory/    智能论与白箱智能理论（跨工程）
+├── eval/      评测与第三方验证报告
+├── plans/     项目计划 / 交接文档 / 实验规格（跨工程）
+├── discipline/  工作纪律渲染管线（模板 / harness 矩阵）
+├── promo/     宣传物料
+├── experiments/ 实验区（gitignored，可重跑再生产物）
+└── 工作纪律_认知图条目_v1.1.json   ← 全局真源（横切面，不属单一工程）
+```
+
+## mdcg/ · 灵枢大脑 md_cg 工程
+
+| 文档 | 内容 |
+|---|---|
+| [README 详细版](mdcg/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 |
+| [发布说明 v0.3.0](mdcg/release_v0.3.0.md) / [v0.4.5](mdcg/release_v0.4.5.md) | 各版变更 / 升级指引 |
+| [工具表 v0.3.0](mdcg/tool_table_v0.3.0.md) | MCP 工具清单 |
+| [功能调用映射表 v0.1](mdcg/功能调用映射表_v0.1.md) | 功能 → 源码行号（管线生成，勿手写行号） |
+| [灵枢 MCP 工具总表 v3.4](mdcg/灵枢MCP工具总表_v3.4.md) | 工具参数与调用规范 |
+| [灵枢 82 工具迁移映射 v0.1](mdcg/灵枢82工具_功能整理与迁移映射_v0.1.md) | 功能整理与迁移对照 |
+| [灵枢自我层定义](mdcg/灵枢_自我层定义.md) | 自我层行为规范（test_p16 行号级引用） |
+| [三层拆分规划 v0.1](mdcg/灵枢三层拆分规划_v0.1.md) | 架构分层规划 |
+| [记忆操作系统 MdCGOS 与 MCP 接入 v0.1](mdcg/记忆操作系统_MdCGOS与MCP接入_v0.1.md) | 核心架构设计 |
+| [认知图 MD 目录方案 v0.1](mdcg/认知图_MD目录方案_v0.1.md) | 目录方案（test_p27 验收对象） |
+| [认知图索引与工程规范化计划 v0.1](mdcg/认知图_索引与工程规范化_计划_v0.1.md) | 索引工程化 |
+| [认知图条件空间合成与生效条件口径 v0.1](mdcg/认知图_条件空间合成与生效条件口径_v0.1.md) | 条件论口径 |
+| [认知图 G4-G8 缺口裁定单 v0.1](mdcg/认知图_G4-G8缺口裁定单_v0.1.md) | 缺口裁决留痕 |
+| [认知图作为记忆操作系统：评估与路线 v0.1](mdcg/认知图作为记忆操作系统_评估与路线_v0.1.md) | 路线图 |
+| [主代理子代理记忆架构设计](mdcg/主代理子代理记忆架构设计.md) | 多代理记忆分工 |
+| [子代理配置标准 v0.4](mdcg/子代理配置标准_v0.4.md) | 统一执行默认（§0）/ 派发 / 确定性执行（§7）/ 复用 / 产出物生命周期（§5.4） |
+| [单元自我锚点·系统提示词标准 v0.3](mdcg/单元自我锚点_系统提示词标准_v0.3.md) | 提示词锚点标准 |
+| [令牌与角色权职分离 v0.1](mdcg/令牌与角色权职分离_v0.1.md) | 权限模型 |
+| [缺口单 P0 收口 v0.1](mdcg/缺口单_P0收口_v0.1.md) | P0 缺口清单 |
+| [源码级架构审计：GPT 批评对照 v1.0](mdcg/源码级架构审计_GPT批评对照_v1.0.md) | 外部审计取证 |
+| [护栏宪章 v2.0](mdcg/guardrail-charter.md) | 对外部智能体与人类的行为边界 |
+| [memory_score](mdcg/memory_score.html)（[png](mdcg/memory_score.png)） · [memory-assessment](mdcg/memory-assessment.html) · [教学教程](mdcg/lingshu_tutorial.html) | 评分 / 评估 / 教程 |
+
+## swarm/ · 蜂群运行时
+
+| 文档 | 内容 |
+|---|---|
+| [功能说明 v0.6](swarm/蜂群多智能体_功能说明_v0.6.md) | .pbc 确定性实例 + Gossip/WAL/信任聚合 |
+| [使用报告 2026-09-13](swarm/蜂群多智能体_使用报告_20260913.md) | 实测记录 |
+| [蜂群互联 v0.1](swarm/蜂群互联_v0.1.md) | 多蜂群互联协议 |
+| [蜂群盲区标记 v1.0](swarm/蜂群盲区标记_v1.0.md) | 盲区协同标记 |
+| [蜂群同错检测实验协议 v0.1](swarm/蜂群同错检测实验协议_v0.1.md) | 同错检测实验设计 |
+
+## hive/ · 蜂巢并发引擎
+
+| 文档 | 内容 |
+|---|---|
+| [蜂巢工作记忆·项目计划](hive/蜂巢工作记忆_项目计划.md) | hive 工作记忆规划 |
+
+## world_model/ · 世界模型神经网络底层架构
+
+| 文档 | 内容 |
+|---|---|
+| [世界模型·神经网络底层架构 v1.0](world_model/世界模型_神经网络底层架构_v1.0.md) | hex 系列工程成果台账（11 件组件 / 反传语义 / Rust 后端 / 认知图对接面 / 验证基线与红线） |
+
+## theory/ · 智能论理论
+
+| 文档 | 内容 |
+|---|---|
+| [白箱智能是什么？](theory/白箱智能是什么？.md) | 教学一 |
+| [智能的认知过程](theory/智能的认知过程.md) | 教学二 |
+| [智能的公理化基石](theory/智能的公理化基石.md) | 教学三 |
+| [信息差为什么必然存在且自然扩大](theory/信息差为什么必然存在且自然扩大.md) | 教学四 |
+| [白箱智能系列·第五篇：让 AI 真正装上记忆](theory/白箱智能系列·第五篇：让AI真正装上记忆.md) | 系列续篇 |
+| [智能论 3.4](theory/智能论3.4.md) | 理论主文档 |
+| [并发必然性理论 v0.2](theory/并发必然性理论_v0.2.md) | 并发架构的必然性论证 |
+| [单线程与注意力集中 v1.0](theory/单线程与注意力集中_无争议理论文档_v1.0.md) | 无争议理论文档（含验证留痕表） |
+| [概念分层对齐表 v0.1](theory/概念分层对齐表_v0.1.md) | 概念层级对齐 |
+| [认知代理与收敛结构·条件论重构 v0.1](theory/认知代理与收敛结构_条件论重构_v0.1.md) | 条件论 |
+| [理论·机制·代码·实验·缺口矩阵 v0.1](theory/理论_机制_代码_实验_缺口矩阵_v0.1.md) | 全景矩阵 |
+| [理论仓拆分与白箱知识库内迁 v0.1](theory/理论仓拆分与白箱知识库内迁_v0.1.md) | 拆分方案 |
+
+## eval/ · 评测与第三方验证
+
+| 文档 | 内容 |
+|---|---|
+| [AGI 七维评分报告 v1.0](eval/AGI七维评分报告_md_cg_v1.0.md) / [v2.0](eval/AGI七维评分报告_md_cg_v2.0.md) | 逐维得分 / 诚实边界 |
+| [第三方复评·统一评分 v7](eval/第三方验证报告_灵枢_vs_dejavu_统一评分_v7.md) | 七轮对照：灵枢 9.258 / deja-vu 9.119 |
+| [第三方验证·LoCoMo 独立复现](eval/第三方验证报告_LoCoMo_灵枢_.md)（[png](eval/第三方验证报告_LoCoMo_灵枢_.png)） | 独立评测全流程复现 |
+| [六家横评 100 题中英双查 v1.0](eval/横评_六家100题中英双查_v1.0.md) | 六家同口径对照 |
+| [实验方案·学习闭环 AB 与横评 v1.0](eval/实验方案_学习闭环AB与横评_v1.0.md) | 实验设计 |
+
+## plans/ · 项目计划 / 交接 / 规格
+
+| 文档 | 内容 |
+|---|---|
+| [命名治理·项目计划](plans/命名治理_项目计划.md) | 命名规范治理 |
+| [知识图谱项目·交接文档 2026-09-14](plans/知识图谱项目_交接文档_20260914.md) | 项目交接 |
+| [GridWorld 最小闭环规格 v0.1](plans/GridWorld最小闭环规格_v0.1.md) | 实验规格 |
+
+## 归域规则（新文档放哪）
+
+1. **工程文档** → 对应工程域（`mdcg/`、`swarm/`、`hive/`、`world_model/`；rust / compiler 有专属文档时新增同目录）。
+2. **跨工程理论** → `theory/`；**评测 / 第三方报告** → `eval/`；**计划 / 交接 / 规格** → `plans/`。
+3. **横切全局件**（工作纪律真源等）→ 留顶层，移动前必须核对引用面并全量重写。
+4. 入域后在本页对应清单登记一行；`discipline/`、`experiments/`、`promo/` 既有惯例不变。