@furongjun1999/dsh-memory 0.4.9 → 0.4.11

package/README.md

@@ -1,6 +1,6 @@
 # 让 AI Agent 拥有不可遗忘的记忆
 
-**灵枢（Lingshu）** —— 高性能 · 无幻觉 · 多智能体适用的长期记忆系统（v0.4.9）
+**灵枢（Lingshu）** —— 高性能 · 无幻觉 · 多智能体适用的长期记忆系统（v0.4.10）
 
 [![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)
 
@@ -31,7 +31,7 @@
 
 | 层 | 位置 | 系统功能 | 一句话定位 | 文档入口 |
 |---|---|---|---|---|
-| 🧠 **灵枢大脑** | [`md_cg/`](md_cg/) | **元认知** | 记忆系统本体：对话沉淀为 md 认知图，记什么 / 取什么 / 能否写入全由确定性规则裁决，四层证据防火墙白箱剔除弱证据干扰 | [README 详细版](docs/mdcg/README详细版_v0.4.5.md) |
+| 🧠 **灵枢大脑** | [`md_cg/`](md_cg/) | **元认知** | 记忆系统本体：对话沉淀为 md 认知图，记什么 / 取什么 / 能否写入全由确定性规则裁决，四层证据防火墙白箱剔除弱证据干扰 | [README 详细版](docs/mdcg/README详细版_v0.4.10.md) |
 | ⚙️ **Rust 检索引擎** | [`rust/`](rust/) | 检索内核 | 只读侧检索核心：零第三方依赖三形态（库内嵌大批量 / `--serve` 多智能体进程实例 / 评测器），与 Python 口径逐位对齐 | [rust/README.md](rust/README.md) |
 | 🐝 **蜂群运行时** | [`swarm/`](swarm/) | **自维持** | 多进程蜂群执行层（靠轮次心跳存续）：.pbc 确定性实例 + Gossip 拓扑 / 水位信箱 / WAL-HMAC / 信任聚合 / 健康评分，实例管道断裂即同轮重建（Rust 纯 std 零依赖） | [功能说明 v0.6](docs/swarm/蜂群多智能体_功能说明_v0.6.md) |
 | 📜 **中文编译器** | [`compiler/`](compiler/) | **验证 · 审计** | 术数编译器：词法 → 语法 → 名实校验 → 白名单代码生成 → 验证终裁，五环确定性编译链 + 封闭指令集结构性沙箱 | `python -m compiler.cli`（模块内文档） |
@@ -54,7 +54,7 @@
 
 ## ⚡ 快速开始
 
-> **按宿主选择入口**：**DSH** → 下方三步 ｜ **CodeBuddy · ZCode · Codex CLI · Claude Code** → [多 harness 接入](#多-harness-接入按端分目录)（各端独立三步说明） ｜ **其它 MCP 宿主** → 直接挂载大脑 `python -m md_cg.mcp_server`（stdio MCP），再按需注入工作纪律
+> **按宿主选择入口**：**DSH** → 下方三步 ｜ **CodeBuddy · ZCode · Codex CLI · Claude Code** → [多 harness 接入](#多-harness-接入按端分目录)（各端独立三步说明） ｜ **其它 MCP 宿主** → 直接挂载大脑 `python -m md_cg.mcp_server`（Windows）/ `python3 -m md_cg.mcp_server`（Linux·macOS）（stdio MCP），再按需注入工作纪律
 
 ```bash
 # ① 克隆并构建插件本体
@@ -92,11 +92,11 @@ dsh plugin --profile web add .
 
 > 首次使用记忆库为空，召回返回空结果属正常现象；未配写入凭据时以只读 `guest` 运行（**读得到、写不进**），要真正落盘见[写入凭据](#-写入凭据让记忆真正落盘)。
 
-- **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1 · **大脑零安装**（`md_cg` 随包自带，无需 pip 装任何引擎）
+- **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1 · **大脑零安装**（`md_cg` 随包自带，无需 pip 装任何引擎）· **Python 解释器**（插件按平台自动选：Windows `python` / Linux·macOS `python3`；解释器名特殊时用 `MDCG_PYTHON` 覆盖）
 - **写权限默认关闭**：不配凭据即以只读 `guest` 运行（读 / 召回 / 时间线可用，写入不落盘）。要真正落盘见「写入凭据」
-- 完整配置项（30+ 项）· 自动记忆机制 · DSH 看门狗 → [README 详细版](docs/mdcg/README详细版_v0.4.5.md)
+- 完整配置项（30+ 项）· 自动记忆机制 · DSH 看门狗 → [README 详细版](docs/mdcg/README详细版_v0.4.10.md)
 - **非 DSH 宿主**（CodeBuddy / ZCode / Codex CLI / Claude Code）：走[多 harness 接入](#多-harness-接入按端分目录)，各端有独立三步接入说明
-- **装后验证**：重启 DSH 后对 Agent 说「列出你的记忆工具」应看到 `cg` / `stg`（`tools: 'all'` 时还有 `mdcg_*`）；大脑直连验证：`python -m md_cg.mcp_server`（stdio JSON-RPC）收到 initialize 应答即通，更多细节见 [README 详细版](docs/mdcg/README详细版_v0.4.5.md)
+- **装后验证**：重启 DSH 后对 Agent 说「列出你的记忆工具」应看到 `cg` / `stg`（`tools: 'all'` 时还有 `mdcg_*`）；大脑直连验证：`python -m md_cg.mcp_server`（Windows）/ `python3 -m md_cg.mcp_server`（Linux·macOS）（stdio JSON-RPC）收到 initialize 应答即通；**若工具始终不注册、日志刷「灵枢调用超时」**，先看桥探针 `~/.dsh/logs/lingshu-bridge-debug.log` 里的 `spawn … ENOENT`——那是第一因（解释器名与平台不匹配），「调用超时」只是次生现象。更多细节见 [README 详细版](docs/mdcg/README详细版_v0.4.10.md)
 
 ---
 
@@ -363,7 +363,7 @@ DSH 采用 Cordis bundle 机制，新增或更新插件后必须**重启 DSH 进
 | 文档 | 内容 |
 |---|---|
 | **[docs/ 目录索引](docs/README.md)** | 六域快速索引（mdcg / swarm / hive / theory / eval / plans）· 新文档归域规则 |
-| [README 详细版](docs/mdcg/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 · 安装与验证细节 |
+| [README 详细版](docs/mdcg/README详细版_v0.4.10.md) | 完整能力说明 · 配置项全表 · 安装与验证细节 |
 | [发布说明 v0.4.5](docs/mdcg/release_v0.4.5.md) | 本版变更 / 兼容性 / 升级指引 |
 | [AGI 七维评分报告 v2.0](docs/eval/AGI七维评分报告_md_cg_v2.0.md) | 逐维得分依据 / 扣分项 / 实库证据 / 诚实边界 |
 | [第三方复评 · 统一评分 v7](docs/eval/第三方验证报告_灵枢_vs_dejavu_统一评分_v7.md) | 独立评估者七轮对照（灵枢 vs deja-vu）：八维加权 / 收敛轨迹 7.79→9.258 / 评审偏差声明 / 自身建议全撤回勘误 |
@@ -429,7 +429,7 @@ npm test         # 真实集成测试（spawn 本机灵枢，验证握手/往返
 
 ### Python 测试约定（必须 `python -m`）
 
-`md_cg/` 等包内测试普遍使用**包内相对导入**，必须以模块方式从**仓库根**运行；直接 `python md_cg/test_xxx.py` 会 ImportError（59/61 踩坑实测）。一键入口已固化该约定：
+`md_cg/` 等包内测试普遍使用**包内相对导入**，必须以模块方式从**仓库根**运行；直接 `python md_cg/test_xxx.py` 会 ImportError（59/61 踩坑实测）。一键入口已固化该约定（Linux·macOS 上把下面的 `python` 换成 `python3`——发行版默认无 `python`）：
 
 ```bash
 python scripts/run_tests.py                  # 全量（md_cg + compiler + swarm）

package/docs/README.md

@@ -23,7 +23,7 @@ docs/
 
 | 文档 | 内容 |
 |---|---|
-| [README 详细版](mdcg/README详细版_v0.4.5.md) | 完整能力说明 · 配置项全表 |
+| [README 详细版](mdcg/README详细版_v0.4.10.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) | 功能 → 源码行号（管线生成，勿手写行号） |

package/docs/mdcg/README/350/257/246/347/273/206/347/211/{210_v0.4.5.md → 210_v0.4.10.md}

@@ -1,4 +1,4 @@
-> **本文件 = README 详细版（v0.4.5 全文归档）**
+> **本文件 = README 详细版（v0.4.5 全文归档 · 正文续写至 v0.4.10）**
 > 精简版入口：[README.md](../../README.md) —— 以「AGI 七维评分标尺」组织。
 > 本文件保留完整的能力说明、配置项全表、工具面全量、安装与验证细节；文内相对链接按本文件所在目录（`docs/mdcg/`）解析。
 
@@ -54,7 +54,7 @@ dsh plugin --profile web add @furongjun1999/dsh-memory
 > **不要**用 `npm install` 把插件装进 profile 的 `node_modules`——那会引入错误版本的 `@deepseek-ai` peer 包，导致插件加载失败 / 浏览器报错。
 > 想自己改源码？克隆 `FuRongJun-1999/dsh-memory` 后用 `npm install && npm run build`（构建插件本身），再用 `dsh plugin add <本地路径>` 部署。
 >
-> 兼容：DSH 官方列表（Memory 分类）· npm `@furongjun1999/dsh-memory`（0.4.5）· **要求 DSH 内核 ≥ 0.1.2-rc.1**（0.4.x 用新版 `dsh-tools` 调度器/`defineTool`；旧内核 0.1.1-rc.2 结构不兼容、会 `scheduler_prepare` 崩——**旧内核用户请用 0.4.2**）。
+> 兼容：DSH 官方列表（Memory 分类）· npm `@furongjun1999/dsh-memory`（0.4.10）· **要求 DSH 内核 ≥ 0.1.2-rc.1**（0.4.x 用新版 `dsh-tools` 调度器/`defineTool`；旧内核 0.1.1-rc.2 结构不兼容、会 `scheduler_prepare` 崩——**旧内核用户请用 0.4.2**）。
 
 ---
 
@@ -136,7 +136,7 @@ dsh plugin --profile web add @furongjun1999/dsh-memory
 
 ## 协议的内在约束 · 信息差与信任
 
-灵枢的一切都建立在**[智能论 v3.3 协议](https://github.com/FuRongJun-1999/CommonTrustProtocol/blob/main/智能论3.3.md)**（共同信任协议理论版）之上。协议规定了一个智能体维持值得被信任所需的**内在约束**：
+灵枢的一切都建立在**[智能论 v3.4 协议](https://github.com/FuRongJun-1999/CommonTrustProtocol/blob/main/智能论3.4.md)**（共同信任协议理论版）之上。协议规定了一个智能体维持值得被信任所需的**内在约束**：
 
 **v3.3 起新增**：扮演论（存在论基底——智能即扮演，灵枢角色扮演机制的理论底座）· 三翼（真实论校准 / 导航税·认知外部化 / 注入极性定律）· 双维（信任 = 认知一致 / 时效维度）· 条件论失败分析协议 · 蒸馏机制与自我锚点。
 
@@ -146,7 +146,7 @@ dsh plugin --profile web add @furongjun1999/dsh-memory
 
 > 一句话：灵枢不是"记住了再用"，而是**通过持续减少信息差、维持可观测的一致行为，建立值得跨会话维护的信任**。
 
-**协议原文**：[智能论 v3.3（共同信任协议理论版）](https://github.com/FuRongJun-1999/CommonTrustProtocol/blob/main/智能论3.3.md)
+**协议原文**：[智能论 v3.4（共同信任协议理论版）](https://github.com/FuRongJun-1999/CommonTrustProtocol/blob/main/智能论3.4.md)
 
 ---
 
@@ -403,6 +403,21 @@ python -m aeis.mcp.server
 
 > **引擎内部能力（按安全边界未挂载 MCP）**：条件空间 7 操作、情境层直写（`add_context`）、代码执行（`code_test` / `compile_exec`）、自修改安全闭环（快照 / 回滚）等存在于引擎中，但刻意不暴露给外部 Agent 调用。
 
+## 🔬 0.4.6 → 0.4.10 变更（版本速览）
+
+> 本文件正文以 v0.4.5 为基底续写；0.4.6 起的变更在此按提交如实登记（每条附提交号，可 `git show <提交号>` 复核）。
+
+| 版本 | 日期 | 核心变更 | 提交 |
+|---|---|---|---|
+| 0.4.6 | 2026-09-11 | 发布前清除包内硬编码本机绝对路径（隐私面）· 请求级身份收窄（`as_unit`）· 公开 `locomo-zh-500` 与 rust 评测器 | `01fac35` `4d53285` |
+| 0.4.7 | 2026-09-14 | issue #12：python 子进程锚定插件仓根（`cwd` + `PYTHONPATH` 双保险） | `1bba53c` |
+| 0.4.8 | 2026-09-16 | issue #16：注入上下文 `{{` 转义（宿主模板插值不再抛错）· 蜂巢任务编排器（`orch`）· 相对链接机制化巡检 | `7288323` `8febf89` `d99c707` |
+| 0.4.9 | 2026-09-20 | issue #18 系列：子进程 `cwd` 移出插件包（修 pnpm 更新必现 EBUSY）· 数据面与路径配置迁出插件包（终止「更新即清空记忆」） | `394661d` `9499866` |
+| 0.4.10 | 2026-09-20 | 子进程注入 `PYTHONUTF8=1`（堵「读线程按 locale 解 UTF-8」崩溃）· 编码守卫改 AST 判定（消除「守卫扫到自己」的判据缺陷） | `58d4908` `df6730b` |
+
+> **发版门禁（本轮新增，不随任何已发布版本）**：`scripts/check_publish_artifact.py` —— 凭据/密钥 · 私有数据面 · 隐私文本 · 非追踪件四类任一命中即拒绝发布；本地挂 `prepublishOnly`、CI 挂 `publish-artifact-check.yml`；发版后可用 `--registry <版本>` 核验发布件哈希与内容面。
+> 0.4.5 及更早见 [release_v0.4.5.md](release_v0.4.5.md)。
+
 ## 🔬 本轮修复与验证（0.4.4 → 0.4.5）
 
 > **0.4.5 变更**：移除失效的 `docker/`（一键部署四个入口全部不可用）· `src/`+`test/` datapath 路径解析统一 · `package-lock.json` 同步当前 npm（`npm ci` 可复现）· 写入闸门文档化（`committed: false`）。

package/docs/mdcg/guardrail-charter.md

@@ -154,7 +154,7 @@
 
 **请验证单元逐项判断**：
 
-1. **效力层级**：元规则"宪章效力不高于协议"是否成立？与智能论 v3.3 的条款（价值观一致性、信任保护、P0 保护协议）是否存在冲突或需要补强？
+1. **效力层级**：元规则"宪章效力不高于协议"是否成立？与智能论 v3.4 的条款（价值观一致性、信任保护、P0 保护协议）是否存在冲突或需要补强？
 2. **定位一致性**：协议＝自我约束（内部宪法）、宪章＝对外约束（公共法律）的分工是否与协议框架自洽？
 3. **人类保护章节（第七章）**：AI 身份披露/知情权/不欺骗不操纵/可退出/申诉/伤害防护——是否与协议对设计者/人类的关系定位一致？"人类保护原则优先于一切"是否与"宪章效力不高于协议"存在张力（若存在，应如何表述消解）？
 4. **适用范围（第四条）**：外部智能体"入境即受约束"的声明机制是否充分？接入声明应写入哪些接口文档（MCP/插件/蜂群）？

package/docs/mdcg/memory_score.html

@@ -206,7 +206,7 @@
     免责声明：他系统评分基于公开能力评估（2026-08-17），非官方基准；灵枢评分经设计者校准（不虚高）。<br>
     综合分 = min × 0.4 + mean × 0.6 —— 安全性是底线，短板效应显著。
   </div>
-  <div class="footer">灵枢 AEIS · 共同信任协议（Common Trust Protocol）· 智能论 v3.2 工程实现</div>
+  <div class="footer">灵枢 AEIS · 共同信任协议（Common Trust Protocol）· 智能论 v3.4 工程实现</div>
 
 </div>
 </body>

package/docs/mdcg/release_v0.4.5.md

@@ -22,7 +22,7 @@
 - TypeScript：实验模块归入 `src/lib/`；新增 `src/lib/datapath.ts` 统一数据路径解析（消除相对 / 绝对路径错位），`src/lib/mdcg_client.ts` 为插件侧唯一显式入口；`src/tools.ts` / `src/hooks.ts` / `src/index.ts` 随 MCP 工具面一并调整。
 
 **文档与工程**
-- README 精简重写（以「AGI 七维评分标尺」组织），原文归档为 [README 详细版](README详细版_v0.4.5.md)。
+- README 精简重写（以「AGI 七维评分标尺」组织），原文归档为 [README 详细版](README详细版_v0.4.10.md)。
 - **移除 `docker/`**：该目录对外四个入口**全部不可用**——镜像自述「Docker Hub 待发布」故 `docker run` 必然失败、`npx @lingxu/dsh-memory` 包名错误（实际 `@furongjun1999/dsh-memory`）、`build.sh` 的 aeis 源码取自他仓路径；且主 README 与 CI 对 `docker/` **零引用**，v0.4.x 已从 python 引擎转向 npm 插件。需要时可用 git 历史取回。
 - `package-lock.json` 用当前 npm 重新生成，`npm ci` 可复现。
 - 工作纪律第 15 条：命令执行统一走 python / UTF-8（显式 encoding + `PYTHONUTF8=1`，规避 GBK）。

package/docs//345/217/221/345/270/203/344/273/266/345/233/236/346/272/257/350/257/264/346/230/216_v0.1.md

@@ -0,0 +1,82 @@
+# 发布件回溯说明 v0.1
+
+> **一句话**：`@furongjun1999/dsh-memory` 的 **0.4.9 / 0.4.10** 两个已发布 tarball 夹带了
+> 非追踪件（实验工作区 + 白箱 KB 运行时数据 + 认知图孤节点 + 字节码缓存），合计约
+> **4009 件 / 28 MB**。该缺陷已由 `cee729a` 收口，**0.4.11 发布件为 1306 件**
+> （本地门禁实测）；已发布版本按「不回溯」处置（§5）。
+
+---
+
+## 1 事实
+
+| 版本 | 发布件数 | `docs/experiments` | 白箱 KB 运行时 | 孤节点 | `__pycache__` | 体积 |
+|---|---|---|---|---|---|---|
+| 0.4.9 | 4008 | 2434 | 474 | 6 | 1 | ~28.0 MB |
+| 0.4.10 | 4009 | 2434 | 474 | 6 | 1 | ~28.0 MB |
+| **0.4.11（收口后）** | **1306** | 0 | 0 | 0 | 0 | — |
+
+**复算方式**：0.4.9 / 0.4.10 两行的件数与体积由第三方从 npm 镜像独立下载 tarball 后逐件
+分类（**不调用本仓任何脚本**），结论与 `publish-artifact-check` workflow 头部的自述
+**逐项一致**——即本缺陷属**如实披露**，非隐瞒。
+
+**0.4.11 一行的口径**：为**本地门禁实测**（`npm pack --dry-run` 清单 1306 件、
+非追踪件 0）。第三方报告在其基线 `1087ae4` 上测得 1302 件——该基线尚未包含后续提交的
+增量件，加之统计口径差异，故与本行不逐位相等；**此处以实测为准，不沿用引用值**。
+
+## 2 根因
+
+`package.json` 的 `files` 白名单包含 `md_cg` 与 `docs` 两个**目录**，而 npm 在存在
+`files` 白名单时**整体忽略根级 `.npmignore`**——只有「白名单目录自身的 `.npmignore`」
+才生效。于是白名单目录内、被 `.gitignore` 排除的运行时产物（实验脚本 / `result_*.json` /
+`_store` 数据目录 / 白箱 KB 的库与索引 / 认知图孤节点 / 字节码缓存）随包分发。
+
+**为什么本地自检没拦下**：门禁脚本的历史版本只校验「发布件清单 vs git 追踪件」的
+一致性，而这些目录属 `.gitignore` 忽略的**本地数据面**——它们在「非追踪件」判定里
+出现过，但当时未按严重度阻断发布。
+
+## 3 收口（`cee729a`，2026-09-20）
+
+改用**子目录级 `.npmignore`**：`docs/.npmignore` + `md_cg/.npmignore` +
+`skills/.npmignore`（共 54 行），覆盖三类：
+
+1. **认知图运行时状态**：`_keys.json` / `_keys.*.json` / `*_audit.jsonl` /
+   `_access.log` / `_index.json` / `_index.json.lock` / `_index_log/` / `_refindex.json`
+   —— 与 `_keys.json` 同级别的凭据信封与审计留痕，**绝不入包**；
+2. **Python 字节码缓存**：`__pycache__/` / `*.pyc` / `*.pyo` / `*.pyd`；
+3. **实验工作区与含沙箱绝对路径的文档**：`docs/experiments/`（可重跑再生产物）等。
+
+`md_cg/.npmignore` 同时排除白箱 KB 运行时数据与本地记忆面；`skills/.npmignore`
+排除纪律模板的中间产物。
+
+## 4 门槛（防复发）
+
+- `scripts/check_publish_artifact.py`：跑 `npm pack --dry-run --json` → 按规则分类 →
+  非追踪件白名单审阅 → `VERDICT=PASS / FAIL`；`--selftest` 覆盖清单解析健壮性与判据自身
+  （含 `prepare` 文本污染 stdout 的场景、数组与对象两形态）。
+- `.github/workflows/publish-artifact-check.yml`：本地模式 + registry 后置核验两种口径。
+- 判据形态：**红着即拦下一次发布**（0.4.11 门禁实测：清单 1306 件、非追踪件 24 = 允许
+  上限 24，`VERDICT=PASS`）。
+
+## 5 处置裁定：已发布版本不回溯
+
+- npm **不允许覆盖同版本号**，撤回（unpublish）会打断已安装用户的依赖解析——代价大于收益；
+- 已发布件不含凭据（`_keys.json` 从未入包，此项经第三方逐件复算确认）；
+- 措施落在「拦下一次」，并对本事实在此**留痕**，供使用者与审计者追溯。
+
+## 6 `files` 白名单与排除规则的一致性复核
+
+| 白名单条目 | 排除机制 | 复核结论 |
+|---|---|---|
+| `md_cg` | 子目录级 `.npmignore`（§3） | 运行时状态与本地记忆面已排除 |
+| `skills` | 子目录级 `.npmignore` | 中间产物已排除 |
+| `docs` | 子目录级 `.npmignore` | 实验区与含沙箱路径文档已排除 |
+| `lib` | 构建产物（`files` 白名单内，无运行时数据） | 无非追踪件 |
+| `src` | 源码（无运行时数据） | 无非追踪件 |
+| `dsh` / `codebuddy` / `zcode` | 接入模板与纪律产物 | 无非追踪件 |
+| `README.md` | 单文件 | — |
+
+复核以门禁脚本本地模式逐件判定为准：0.4.11 发布前 `VERDICT=PASS`（非追踪件 0）。
+
+---
+
+生成：2026-09-20 · 依据：第三方独立验证报告（v15 §5.4）+ 本仓门禁复算 · 维护：随发布件口径变更同步

package/dsh/cordis.yml.example

@@ -12,7 +12,8 @@
 #     ② 编辑 <用户级状态根>/paths.json 的 "data_root" / "root"
 #        （旧版包内 data/paths.json 仍兼容读，但会被下次 pnpm 更新删除）
 #     ③ 本文件的 mdcg.root（填绝对路径或相对插件仓的路径）
-#   查当前解析结果：python md_cg/datapath.py
+#   查当前解析结果（解释器按平台：Windows python / Linux·macOS python3，下同）：
+#     python md_cg/datapath.py
 #   旧版数据迁移：包内 data/ 仍有内容时，插件首启会**复制**（不删除）到用户级根；
 #   也可手动执行 python md_cg/datapath.py --migrate-legacy
 
@@ -32,7 +33,13 @@
     identity: '灵枢'
 
     # Python 与启动参数（默认即可；md_cg 随插件自带，无需 pip 安装第三方包）
-    python: 'python'
+    # 解释器**无需配置**：默认按平台自动选——Windows → python，Linux/macOS → python3。
+    # 为什么不能照抄 'python'（issue #19）：Linux/macOS 发行版按 PEP 394 只提供
+    # python3（这是默认状态，不是环境损坏），写死 python 会让桥 spawn ENOENT，
+    # 重试 8 次后进终态——插件看起来装好了，但工具不注册、记忆永不落盘且不自愈。
+    # 解释器名特殊（如 python3.12）时：在此显式配置，或设环境变量 MDCG_PYTHON
+    # （优先级：config.python > env MDCG_PYTHON > 平台默认）。
+    # python: 'python'
     # 大脑进程：md_cg（主仓自带，不再依赖 pip aeis）
     moduleArgs: ['-m', 'md_cg.mcp_server']
 
@@ -49,7 +56,7 @@
     # 但转录 / 历史 / 翻译 / 落图始终可用（走大脑）。
     # capability:
     #   enabled: false
-    #   python: 'python'
+    #   python: ''              # 留空 = 跟随上面的 python（平台默认）
     #   args: ['-m', 'aeis.mcp.server']
 
     # 自动记忆（对话沉淀进灵枢）

package/lib/bridge.js

@@ -11,6 +11,9 @@ import { createInterface } from 'node:readline';
 import { mkdirSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+// issue #19：自检命令文案按平台给出（Windows python / 其它 python3）、
+// 并在 ENOENT 时把「解释器名不匹配」这一第一因直接写进日志。
+import { explainMissingPython, selfCheckCommand } from './lib/python_path.js';
 /**
  * 调试探针：记录桥生命周期到独立文件（绕过 DSH 日志系统，便于定位启动问题）。
  * 路径从用户家目录动态解析（issue #5）——此前硬编码作者本机绝对路径，
@@ -162,6 +165,12 @@ export class LingshuBridge {
             // 进程无法启动（python 不存在等）——响亮失败
             if (!this.disposed) {
                 console.error(`[lingshu-bridge] 灵枢进程启动失败: ${err.message}`);
+                // issue #19：ENOENT 的第一因通常不是「环境损坏」，而是解释器名与平台不匹配
+                // （Linux/macOS 按 PEP 394 只有 python3）。把成因与修法写进同一条日志——
+                // 原始日志把该缺陷伪装成「调用超时」，用户按超时方向排查只会白耗一轮。
+                if (err.code === 'ENOENT') {
+                    console.error(`[lingshu-bridge] ${explainMissingPython(python)}`);
+                }
                 probe(`spawn error: ${String(err)}`);
                 this.readyState = 'failed';
                 this.flushBootQueue(false);
@@ -185,8 +194,8 @@ 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 依赖。` +
+                        `自检 \`${selfCheckCommand(python)}\` 须在插件包根目录运行` +
                         '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12）。');
                 }
                 else if (this.unexpectedExits.length >= 3) {
@@ -246,7 +255,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` 须在插件包根目录运行' +
+                `请检查 ${this.options.python} 可执行文件与 md_cg 依赖；` +
+                `自检 \`${selfCheckCommand(this.options.python)}\` 须在插件包根目录运行` +
                 '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12），修复后在 DSH 中重新启用 dsh-memory 插件。');
             probe(`give up: ${this.retries} consecutive failures, entering failed terminal state`);
             return;
@@ -273,7 +283,9 @@ export class LingshuBridge {
         // issue #6：放弃终态下快速失败——之前进程不在且不再重启，请求只能白等超时
         if (this.gaveUp) {
             return Promise.reject(new Error('灵枢进程不可用：连续启动失败已达上限，已停止重试。' +
-                '请检查 python 可执行文件与 md_cg 依赖（自检 `python -m md_cg.mcp_server` 须在插件包根目录运行），修复后重新启用 dsh-memory 插件。'));
+                `请检查 ${this.options.python} 可执行文件与 md_cg 依赖` +
+                `（自检 \`${selfCheckCommand(this.options.python)}\` 须在插件包根目录运行），` +
+                '修复后重新启用 dsh-memory 插件。'));
         }
         const id = this.nextId++;
         const timeout = this.options.timeoutMs;

package/lib/index.d.ts

@@ -56,7 +56,9 @@ export declare const inject: string[];
 export interface Config {
     /** 工具命名空间前缀（默认 lingshu → lingshu_remember）。 */
     serverName: string;
-    /** Python 可执行文件（或 md_cg-mcp console script）。 */
+    /** Python 可执行文件（或 md_cg-mcp console script）。
+     *  缺省 = 平台感知（issue #19）：Windows `python` / Linux·macOS `python3`，
+     *  可用 env `MDCG_PYTHON` 覆盖；显式配置本项优先级最高。 */
     python: string;
     /** 传给 python 的参数（默认启动 md_cg MCP server）。 */
     moduleArgs: string[];

package/lib/index.js

@@ -52,6 +52,9 @@ import { installMemoryHooks } from './hooks.js';
 // LIB 本地库：角色扮演网页 / 互维维护 / 白箱 LLM 适配器统一收在 src/lib/。
 import { installRoleplayWeb } from './lib/roleplay_web.js';
 import { MdcgClient } from './lib/mdcg_client.js';
+// 解释器解析（issue #19）：默认值按平台取（Windows: python / 其它: python3），
+// 可用 env MDCG_PYTHON 覆盖；此前写死 'python' 使 Linux/macOS 首装即挂。
+import { defaultPython, selfCheckCommand } from './lib/python_path.js';
 import { describeDataPaths, migrateLegacyData, mdcgRoot, repoRoot } from './lib/datapath.js';
 // 写入凭据密钥环（首启引导）：显式配置 → ~/.mdcg/token → 首启自动签发。
 import { resolveToken } from './lib/token_store.js';
@@ -84,7 +87,10 @@ function mcpText(r) {
 export const inject = ['tools'];
 export const Config = z.object({
     serverName: z.string().default('lingshu'),
-    python: z.string().default('python'),
+    // issue #19：默认值按平台解析（Windows: python / 其它: python3；env MDCG_PYTHON 可覆盖）。
+    // 写死 'python' 时 Linux/macOS 首装即 spawn ENOENT（PEP 394 只有 python3），
+    // 且表现为「装好了但记忆永远为空」——最难定位的失效形态。
+    python: z.string().default(defaultPython()),
     moduleArgs: z.array(String).default(['-m', 'md_cg.mcp_server']),
     dbPath: z.string().default('data/lingshu.db'),
     identity: z.string().default('灵枢'),
@@ -258,7 +264,9 @@ export async function apply(ctx, config) {
     /** 大脑桥：工具面 + 互维 + 角色落图共用的唯一 md_cg 通道（mdcg 关闭时为 null）。 */
     const bridge = mdcg?.bridge ?? null;
     if (!brainReady) {
-        const message = '灵枢大脑（md_cg）未就绪（检查 python 是否可用、md_cg 是否可导入：python -m md_cg.mcp_server）';
+        // issue #19：自检命令按当前解释器给出（Windows python / 其它 python3），
+        // 照抄报错里的命令在用户平台上必须真的可执行。
+        const message = `灵枢大脑（md_cg）未就绪（检查 ${config.python} 是否可用、md_cg 是否可导入：${selfCheckCommand(config.python)}）`;
         if (config.failOnStartupError && config.mdcg.enabled) {
             // P1 修复（GPT 审查）：启动失败抛错前必须 dispose——此前 throw 在 try 之前，
             // 桥接对象泄漏 + 后台重试计时器继续跑

package/lib/lib/mdcg_client.d.ts

@@ -71,6 +71,40 @@ export interface MdcgOptions {
     timeoutMs?: number;
     maxRetryDelayMs?: number;
 }
+/** 子进程环境构造参数（`MdcgOptions` 中与环境相关的那半）。 */
+export interface MdcgChildEnvOptions {
+    root: string;
+    surface?: 'kernel' | 'full';
+    tenant?: string;
+    clearance?: string;
+    actor?: string;
+    identity?: string;
+    env?: Record<string, string>;
+}
+/**
+ * MCP 子进程环境：**唯一构造点**（导出即为了让机械守卫能断言它——
+ * 见 `test/python-utf8-mode.test.ts`）。勿在别处另拼 env。
+ *
+ * ⚠️ 两条编码注入是**硬约束**，不是可选项：
+ *
+ * ① `PYTHONIOENCODING=utf-8`（子进程**自身** stdio）：Windows 下 piped 子进程默认
+ *    gbk + surrogateescape，Node 写出的 UTF-8 中文会被解成孤立代理字符（\udcXX），
+ *    md_cg 在落盘 / 回写 stdout 时抛 UnicodeEncodeError——中文记忆（主场景）全失败。
+ *
+ * ② `PYTHONUTF8=1`（子进程**后代**的默认 text 编码，PEP 540）：`PYTHONIOENCODING`
+ *    会被后代继承（后代于是往管道写 UTF-8），但**文本解码口径不被继承**——后代读
+ *    `subprocess.run(..., text=True)` 时取的是 locale（本机 cp936），于是
+ *    「子进程写 UTF-8、父进程按 gbk 读」→ 读线程崩死、诊断静默丢失。
+ *    2026-09-20 实证现场（`npm test` 周期复现，来源为子进程的后代代码单元）：
+ *      Exception in thread Thread-N (_readerthread):
+ *      UnicodeDecodeError: 'gbk' codec can't decode byte 0x82 in position 181
+ *    UTF-8 模式把默认 text 编码改为 UTF-8，读写两侧同口径（且解码结果正确，
+ *    而非 `errors="replace"` 那种替换字符）。
+ *
+ * 确定性对照实验（P1 复现 / P3 消除）见 `test/python-utf8-mode.test.ts`。
+ * `opts.env` 最后展开——显式覆盖优先。
+ */
+export declare function mdcgChildEnv(opts: MdcgChildEnvOptions): Record<string, string>;
 /**
  * 请求级**单元身份**（MCP 参数 `as_unit`）。
  *

package/lib/lib/mdcg_client.js

@@ -37,6 +37,44 @@
 import { LingshuBridge } from '../bridge.js';
 import { pythonPathValue, runRoot } from './datapath.js';
 const DEFAULT_ARGS = ['-m', 'md_cg.mcp_server'];
+/**
+ * MCP 子进程环境：**唯一构造点**（导出即为了让机械守卫能断言它——
+ * 见 `test/python-utf8-mode.test.ts`）。勿在别处另拼 env。
+ *
+ * ⚠️ 两条编码注入是**硬约束**，不是可选项：
+ *
+ * ① `PYTHONIOENCODING=utf-8`（子进程**自身** stdio）：Windows 下 piped 子进程默认
+ *    gbk + surrogateescape，Node 写出的 UTF-8 中文会被解成孤立代理字符（\udcXX），
+ *    md_cg 在落盘 / 回写 stdout 时抛 UnicodeEncodeError——中文记忆（主场景）全失败。
+ *
+ * ② `PYTHONUTF8=1`（子进程**后代**的默认 text 编码，PEP 540）：`PYTHONIOENCODING`
+ *    会被后代继承（后代于是往管道写 UTF-8），但**文本解码口径不被继承**——后代读
+ *    `subprocess.run(..., text=True)` 时取的是 locale（本机 cp936），于是
+ *    「子进程写 UTF-8、父进程按 gbk 读」→ 读线程崩死、诊断静默丢失。
+ *    2026-09-20 实证现场（`npm test` 周期复现，来源为子进程的后代代码单元）：
+ *      Exception in thread Thread-N (_readerthread):
+ *      UnicodeDecodeError: 'gbk' codec can't decode byte 0x82 in position 181
+ *    UTF-8 模式把默认 text 编码改为 UTF-8，读写两侧同口径（且解码结果正确，
+ *    而非 `errors="replace"` 那种替换字符）。
+ *
+ * 确定性对照实验（P1 复现 / P3 消除）见 `test/python-utf8-mode.test.ts`。
+ * `opts.env` 最后展开——显式覆盖优先。
+ */
+export function mdcgChildEnv(opts) {
+    return {
+        PYTHONIOENCODING: 'utf-8',
+        PYTHONUTF8: '1',
+        MDCG_ROOT: opts.root,
+        // 工具面必须是 full：写入通道 mdcg_remember 属细粒度工具（见 MdcgOptions.surface）。
+        MDCG_MCP_SURFACE: opts.surface ?? 'full',
+        MDCG_TENANT: opts.tenant ?? 'default',
+        MDCG_CLEARANCE: opts.clearance ?? 'private',
+        PYTHONPATH: pythonPathValue(),
+        ...(opts.actor ? { MDCG_ACTOR: opts.actor } : {}),
+        ...(opts.identity ? { MDCG_IDENTITY: opts.identity } : {}),
+        ...(opts.env ?? {}),
+    };
+}
 /** 认知图依据强度：这些 basis 视为「强依据」，可支撑 pass。
  *  取值须在 md_cg.mdcg.VERIFICATION_BASIS 允许集内：
  *  compiler | test | measurement | formal_proof | data | other（other 不算强依据）。 */
@@ -68,23 +106,8 @@ export class MdcgClient {
         // 模块解析不依赖 cwd：PYTHONPATH（pythonPathValue()）已锚定随包 md_cg；
         // opts.env 显式提供 PYTHONPATH 时完全接管（其展开在最后）。详见 datapath.runRoot()。
         const cwd = opts.cwd ?? runRoot();
-        const env = {
-            // ⚠️ 必须显式 utf-8：Windows 下 piped 子进程默认 gbk + surrogateescape，
-            // Node 写出的 UTF-8 中文会被解成孤立代理字符（\udcXX），md_cg 在落盘 /
-            // 回写 stdout 时抛 UnicodeEncodeError —— 中文记忆（本插件的主场景）全部失败。
-            // md_cg 自带测试（test_p2_mcp.py）与 test/bridge.test.ts 均以
-            // PYTHONIOENCODING=utf-8 启动子进程，此处对齐该约定；opts.env 可覆盖。
-            PYTHONIOENCODING: 'utf-8',
-            MDCG_ROOT: opts.root,
-            // 工具面必须是 full：写入通道 mdcg_remember 属细粒度工具（见 MdcgOptions.surface）。
-            MDCG_MCP_SURFACE: opts.surface ?? 'full',
-            MDCG_TENANT: opts.tenant ?? 'default',
-            MDCG_CLEARANCE: opts.clearance ?? 'private',
-            PYTHONPATH: pythonPathValue(),
-            ...(opts.actor ? { MDCG_ACTOR: opts.actor } : {}),
-            ...(opts.identity ? { MDCG_IDENTITY: opts.identity } : {}),
-            ...(opts.env ?? {}),
-        };
+        // 编码与模块解析口径见 mdcgChildEnv() 头注（含 2026-09-20 读线程崩溃现场）。
+        const env = mdcgChildEnv(opts);
         this.bridge = new LingshuBridge({
             python: opts.python,
             args: opts.args ?? DEFAULT_ARGS,

package/lib/lib/mutual.js

@@ -16,6 +16,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { pythonPathValue, runRoot } from './datapath.js';
+// issue #19：解释器默认值按平台解析（Windows: python / 其它: python3；
+// env MDCG_PYTHON 可覆盖）。此前写死 'python'，Linux/macOS 上 mutual 一开就撞 ENOENT。
+import { defaultPython } from './python_path.js';
 const DEFAULTS = {
     heartbeatMs: 10 * 60 * 1000,
     warnMs: 25 * 60 * 1000,
@@ -68,7 +71,10 @@ export function judgeStamp(stamp, opts = DEFAULTS) {
 // ---------------------------------------------------------------------------
 // 守护 A（检测 harness 进程 + 拉起）
 // ---------------------------------------------------------------------------
-const HARNESS_PROC = ['python', 'harness.guardian']; // wmic 特征
+// 进程探测特征 = 命令行含 'harness.guardian' / 'harness.main'（见 harnessRunning）。
+// issue #19 已知边界（未纳入本轮修复面）：Windows 分支按 name='python.exe' 过滤，
+// 用其它可执行名（conda 的 python3.exe 等）启动的 harness 可能漏检；该路径由
+// config.mutual.enabled 控制（默认关）。
 function execP(cmd) {
     return new Promise((resolve) => {
         exec(cmd, { windowsHide: true, timeout: 15_000 }, (err, stdout) => {
@@ -94,7 +100,7 @@ export async function harnessRunning() {
     return !!psOut;
 }
 /** detached 拉起 A 侧 harness.guardian（幂等：先确认不存在） */
-export async function ensureHarness(python = 'python', opts = DEFAULTS) {
+export async function ensureHarness(python = defaultPython(), opts = DEFAULTS) {
     const running = await harnessRunning();
     if (running)
         return 'already';
@@ -123,7 +129,18 @@ export async function ensureHarness(python = 'python', opts = DEFAULTS) {
                 // 同 mdcg_client：cwd 必须在包外（否则 pnpm 更新时 rmdir 包目录被 Windows
                 // 拒绝 → ERR_PNPM_EBUSY）；模块解析由 PYTHONPATH 保证，见 datapath.runRoot()。
                 cwd: runRoot(),
-                env: { ...process.env, PYTHONPATH: pythonPathValue() },
+                // 两条编码注入与 mdcg_client.mdcgChildEnv() 同口径（2026-09-20 v15-9）：
+                // 本站点此前只给 PYTHONPATH，是「唯一构造点」主张下**未表态**的 Python 站点
+                // （v15b 结构扫描：Python 目标 3 站点、走构造点 0 个、两条编码变量全缺 2 个）。
+                // 此处**不引** mdcgChildEnv()：它构造的是 md_cg 子进程环境（带 MDCG_ROOT /
+                // MDCG_MCP_SURFACE / MDCG_MCP_* 等，对 harness.guardian 无意义）；只对齐编码口径。
+                // 站点表态由 test/python-utf8-mode.test.ts ④（站点扫描）机械守护。
+                env: {
+                    ...process.env,
+                    PYTHONPATH: pythonPathValue(),
+                    PYTHONUTF8: '1',
+                    PYTHONIOENCODING: 'utf-8',
+                },
             });
         }
         catch (e) {
@@ -308,7 +325,7 @@ export function installMutualMaintenance(ctx, config = {}, hooks = {}) {
         try {
             writeHeartbeat(opts);
             // 守护 A：harness 不在 → 拉起
-            ensureHarness('python', opts).then((r) => {
+            ensureHarness(defaultPython(), opts).then((r) => {
                 if (r === 'started')
                     ctx.logger.info(`mutual: 已拉起 A 侧 harness（${r}）`);
             });

package/lib/lib/python_path.d.ts

@@ -0,0 +1,57 @@
+/**
+ * python_path.ts —— Python 解释器的**平台感知**解析（issue #19）
+ *
+ * 要解决的问题（首次安装即失效，且不自愈）
+ * ------------------------------------------------
+ * 解释器默认值此前是**字面量 `'python'`**。Linux/macOS 按 PEP 394 只要求提供
+ * `python3`——发行版默认状态就是这样，不是用户把环境装坏了。于是 `spawn('python')`
+ * 抛 `ENOENT`，桥重试 8 次后进入 failed 终态：插件看起来装好了，工具不注册、
+ * 记忆只读（`guest`）、必须重启 DSH 才会再试一次。同时日志被
+ * `灵枢调用超时（60000ms）：initialize` 刷屏，把人引向「超时/性能」的错误方向，
+ * 而第一因是更早一行不起眼的 `spawn … ENOENT`。
+ * Windows 上 `python` 通常存在，所以该缺陷只在作者机器之外暴露。
+ *
+ * 解析顺序（高 → 低）
+ * ------------------------------------------------
+ *   ① `config.python` —— 用户显式配置，**原样尊重**（本模块不介入）
+ *   ② env `MDCG_PYTHON` —— 容器 / CI 固定解释器；命名风格与既有
+ *      `MDCG_ROOT` / `MDCG_CHILD_CWD` 一致
+ *   ③ 平台默认：`win32` → `python`（**逐字节保持既有行为**）；其它 → `python3`
+ *
+ * 边界（诚实声明，勿据此扩大承诺）
+ * ------------------------------------------------
+ * - **不做** PATH 扫描式候选回退（`python3` → `python3.12` → `python` 取首个存在）：
+ *   隐式行为在跨平台/多环境（conda、pyenv、WSL）下难以预测，且失败模式从
+ *   「明确 ENOENT」退化为「悄悄选了另一个解释器」。解释器名特殊时请显式配置
+ *   或设 `MDCG_PYTHON`。
+ * - md_cg 侧**不挑** Python 版本：只要存在解释器即可（issue 复现方实测 conda 的
+ *   `python3.12` 亦正常握手）。
+ * - 本模块只**解析名字**，不校验可执行文件是否真的存在（校验属调用方职责，
+ *   且 `stat` 结果会被 PATH/沙箱差异推翻）。
+ */
+/** 解释器覆盖的环境变量名（与 MDCG_ROOT 等同风格，便于容器固定）。 */
+export declare const PYTHON_ENV_VAR = "MDCG_PYTHON";
+/**
+ * 解析默认 Python 解释器（issue #19）。
+ *
+ * 参数刻意做成**可注入**（platform / env）而非直接读全局：默认值此前写死导致的
+ * 正是「不可测 → 只在作者机器上成立」，注入后回归测试可在任意平台断言三分支。
+ */
+export declare function defaultPython(platform?: string, env?: Readonly<Record<string, string | undefined>>): string;
+/** 自检命令文案（按平台给出**可照抄**的写法，issue #19 影响面第 4 条）。 */
+export declare function selfCheckCommand(python?: string): string;
+/**
+ * spawn 失败（ENOENT）时的修复指引。
+ *
+ * 为什么值得单列一条日志：该缺陷的原始日志把「解释器名不匹配」伪装成
+ * 「调用超时」，用户按超时方向排查只会浪费一轮；把成因与三条修法写在
+ * **同一行**，可诊断性直接闭环。
+ */
+export declare function explainMissingPython(python: string): string;
+declare const _default: {
+    defaultPython: typeof defaultPython;
+    selfCheckCommand: typeof selfCheckCommand;
+    explainMissingPython: typeof explainMissingPython;
+    PYTHON_ENV_VAR: string;
+};
+export default _default;