@furongjun1999/dsh-memory 0.4.9 → 0.4.10

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)
 

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/md_cg/test_subproc_encoding.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""test_subproc_encoding.py · 子进程**文本解码口径**的机械守卫（第15条纪律的守卫面）
+
+现场（2026-09-20 取证）：桥的子进程被注入 `PYTHONIOENCODING=utf-8`，其**后代**因此往
+管道写 UTF-8；但后代读子进程输出时默认 text 编码取自 locale（Windows=cp936），两侧
+口径不一致 → 读线程崩死、子进程诊断静默丢失：
+
+    Exception in thread Thread-N (_readerthread):
+    UnicodeDecodeError: 'gbk' codec can't decode byte 0x82 in position 181
+
+两道防线（本守卫管第二道）：
+  ① 运行期：桥子进程一律以 `PYTHONUTF8=1` 启动（PEP 540，默认 text 编码=utf-8）；
+     见 `src/lib/mdcg_client.ts` 的 `mdcgChildEnv()` 与 `test/python-utf8-mode.test.ts`。
+  ② 源码：**任何**文本模式子进程读取都必须显式声明 `encoding=`（配 `errors=`），
+     不依赖 locale——脚本/工具也可能被非桥路径启动，那时没有 ① 的保护。
+
+判据（**AST 判定，非文本窗口**——2026-09-20 改进）：以 `ast` 解析每个 git 跟踪的 .py，
+对**真实的调用节点**判定：
+· 子进程调用 = `subprocess.<run|Popen|check_output|call|check_call|getoutput|getstatusoutput>`
+  （含 `import subprocess as sp` 与 `from subprocess import run` 两种别名形态）
+· 文本模式 = 调用处出现 `text=<非 False>` / `universal_newlines=<非 False>` / `encoding=`
+· 违例 = 文本模式却无 `encoding=` 实参；`**kwargs` 透传且**该调用确有管道**
+  （`capture_output` 或 stdout/stderr=PIPE）而无 `encoding=` 报「不可判定」——口径无法
+  确认即不合格，须显式声明；`os.popen` 直接违例（该 API 无法声明编码）。
+  注：输出落 DEVNULL/日志文件且无管道的 `Popen` **不判**——它根本不经过解码器。
+> 之所以不用文本窗口：窗口会把**字符串字面量与文档样例**当调用（守卫曾因此自伤，
+> 把自身源码里的 `"os.popen("` 字串判为违例）——AST 只认语法意义上的调用，无此缺陷。
+
+自检：被检查的文本模式调用点低于 FLOOR 视为失败——防止「扫描范围意外为空 → 假绿」。
+"""
+from __future__ import annotations
+
+import ast
+import os
+import subprocess
+import sys
+
+FLOOR = 12          # 本仓文本模式子进程调用点的下限（低于它说明扫描面失效了）
+SUB_FUNCS = {"run", "Popen", "check_output", "call", "check_call",
+             "getoutput", "getstatusoutput"}
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+# 生效条件：无入参；返回仓根下 git 跟踪的 .py 相对路径列表（git 不可用时返回 None，调用方据此跳过并说明）。
+def _tracked_py() -> list[str] | None:
+    try:
+        r = subprocess.run(["git", "-C", ROOT, "ls-files", "*.py"],
+                           capture_output=True, text=True,
+                           encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if r.returncode != 0:
+        return None
+    return [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]
+
+
+# 生效条件：v 为 ast 常量节点时按其布尔取反判定；非常量（变量/表达式）一律按 True 保守处理。
+def _truthy(v: ast.AST | None) -> bool:
+    if isinstance(v, ast.Constant):
+        return bool(v.value)
+    return True
+
+
+class _Scanner(ast.NodeVisitor):
+    """单文件扫描器：先收别名导入，再按 AST 调用节点判文本模式与 encoding 声明。"""
+
+    def __init__(self, rel: str, bad: list[str]) -> None:
+        self.rel = rel
+        self.bad = bad
+        self.sub_aliases: set[str] = set()
+        self.func_aliases: dict[str, str] = {}
+        self.checked = 0
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for a in node.names:
+            if a.name == "subprocess":
+                self.sub_aliases.add(a.asname or "subprocess")
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        if node.module == "subprocess":
+            for a in node.names:
+                if a.name in SUB_FUNCS:
+                    self.func_aliases[a.asname or a.name] = a.name
+        self.generic_visit(node)
+
+    # 生效条件：node.func 为 subprocess.<func> / 别名 / os.popen 三种形态之一时返回 (kind, funcname)，否则 None。
+    def _callee(self, node: ast.Call) -> tuple[str, str] | None:
+        f = node.func
+        if isinstance(f, ast.Attribute) and isinstance(f.value, ast.Name):
+            base = f.value.id
+            if base in self.sub_aliases and f.attr in SUB_FUNCS:
+                return ("subprocess", f.attr)
+            if base == "os" and f.attr == "popen":
+                return ("os", "popen")
+        if isinstance(f, ast.Name) and f.id in self.func_aliases:
+            return ("subprocess", self.func_aliases[f.id])
+        return None
+
+    # 生效条件：kws 为调用处关键字实参表；capture_output 为真或 stdout/stderr 取 PIPE 时返回 True（该调用确有管道）。
+    @staticmethod
+    def _piped(kws: dict[str, ast.AST]) -> bool:
+        if "capture_output" in kws and _truthy(kws.get("capture_output")):
+            return True
+        for key in ("stdout", "stderr"):
+            v = kws.get(key)
+            if isinstance(v, ast.Attribute) and v.attr == "PIPE":
+                return True
+            if isinstance(v, ast.Name) and v.id == "PIPE":
+                return True
+        return False
+
+    def visit_Call(self, node: ast.Call) -> None:
+        callee = self._callee(node)
+        if callee is not None:
+            kind, fname = callee
+            if kind == "os":
+                self.bad.append("%s:%d: os.popen(...)（该 API 无法声明编码，"
+                                "改用 subprocess.run）" % (self.rel, node.lineno))
+            else:
+                kws = {k.arg: k.value for k in node.keywords if k.arg is not None}
+                has_star = any(k.arg is None for k in node.keywords)
+                text_mode = ("encoding" in kws
+                             or ("text" in kws and _truthy(kws.get("text")))
+                             or ("universal_newlines" in kws
+                                 and _truthy(kws.get("universal_newlines"))))
+                if text_mode:
+                    self.checked += 1
+                    if "encoding" not in kws:
+                        self.bad.append(
+                            "%s:%d: subprocess.%s(...) 文本模式未声明 encoding="
+                            % (self.rel, node.lineno, fname))
+                elif has_star and self._piped(kws):
+                    # **kwargs 透传且确有管道：口径不可判定（可能被调用方注入 text=True）→ 不合格。
+                    # 输出落 DEVNULL/文件且无管道的调用不判——不经过解码器，无该缺陷面。
+                    self.bad.append(
+                        "%s:%d: subprocess.%s(..., **kwargs) 无法确认编码口径，"
+                        "须显式声明 encoding=" % (self.rel, node.lineno, fname))
+        self.generic_visit(node)
+
+
+# 生效条件：无入参；扫描 git 跟踪的 .py 返回 (违例列表, 受检文本模式调用点数, git 可用性)。
+def scan() -> tuple[list[str], int, bool]:
+    files = _tracked_py()
+    if files is None:
+        return [], 0, False
+    bad: list[str] = []
+    checked = 0
+    for rel in files:
+        path = os.path.join(ROOT, rel)
+        try:
+            with open(path, encoding="utf-8", errors="replace") as fh:
+                src = fh.read()
+        except OSError:
+            continue
+        try:
+            tree = ast.parse(src, filename=rel)
+        except SyntaxError:
+            bad.append("%s:0: 语法错误，无法 AST 判定（守卫拒绝在未解析文件上放行）" % rel)
+            continue
+        sc = _Scanner(rel, bad)
+        sc.visit(tree)
+        checked += sc.checked
+    return sorted(bad), checked, True
+
+
+def main() -> int:
+    bad, checked, git_ok = scan()
+    if not git_ok:
+        print("SKIP：git 不可用，无法枚举跟踪文件（本守卫需要 git）")
+        return 0
+    print("受检文本模式子进程调用点：%d（下限 %d）" % (checked, FLOOR))
+    if bad:
+        print("✖ 不合格的文本模式调用点 %d 处：" % len(bad))
+        for b in bad:
+            print("   ", b)
+        print("修法：补 encoding=\"utf-8\", errors=\"replace\"（不依赖 locale）")
+        return 1
+    if checked < FLOOR:
+        print("✖ 受检调用点 %d < 下限 %d——扫描面失效（文件枚举/判据坏了），"
+              "不得视为通过" % (checked, FLOOR))
+        return 1
+    print("✔ 全部调用点均显式声明 encoding=（子进程文本解码不依赖 locale）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/units.py

@@ -124,8 +124,11 @@ def _tasklist_row(pid):
     按列精确比对，**不用子串包含**——子串会让 pid=441 被 4410 命中（假存活）。
     """
     try:
+        # 显式 utf-8 + replace：只消费 ASCII 的 pid 列，但**不依赖 locale**——
+        # locale 口径与「后代写 UTF-8」不一致时读线程会崩（见 test_subproc_encoding.py）。
         r = subprocess.run(["tasklist", "/FI", f"PID eq {pid}", "/NH", "/FO", "CSV"],
-                           capture_output=True, text=True, errors="replace")
+                           capture_output=True, text=True,
+                           encoding="utf-8", errors="replace")
     except OSError:
         return None
     for line in (r.stdout or "").splitlines():

package/md_cg/whitebox_kb/wisdom/audit_log/chain_heat.json

@@ -5,7 +5,7 @@
  "初中数学知识点内容（按骨架填充）→小学数学知识点内容（按骨架填充）→高中数学知识点内容（按骨架填充）": 2,
  "单卡:初中数学知识点内容（按骨架填充）": 2,
  "单卡:小学数学知识点内容（按骨架填充）": 2,
- "单卡:高中数学知识点内容（按骨架填充）": 240,
+ "单卡:高中数学知识点内容（按骨架填充）": 244,
  "小学科学→数学→初中物理": 9,
  "单卡:小学科学": 9,
  "单卡:数学": 9,
@@ -14,15 +14,15 @@
  "单卡:数学物理方法": 9,
  "单卡:理论力学": 9,
  "单卡:物理学·综合": 9,
- "单卡:打喷嚏（健康与身体·通识知识卡）": 238,
- "单卡:质数（数学·通识知识卡）": 238,
- "常见家电的功率（物理学·通识知识卡）→日食与月食的成因（天文学·通识知识卡）": 238,
- "单卡:常见家电的功率（物理学·通识知识卡）": 238,
- "单卡:日食与月食的成因（天文学·通识知识卡）": 238,
- "数学分析知识点内容（按骨架填充）→高中数学知识点内容（按骨架填充）→测度论与物理离散性": 114,
- "单卡:数学分析知识点内容（按骨架填充）": 238,
- "单卡:测度论与物理离散性": 238,
- "高中数学知识点内容（按骨架填充）→数学分析知识点内容（按骨架填充）→测度论与物理离散性": 124,
+ "单卡:打喷嚏（健康与身体·通识知识卡）": 242,
+ "单卡:质数（数学·通识知识卡）": 242,
+ "常见家电的功率（物理学·通识知识卡）→日食与月食的成因（天文学·通识知识卡）": 242,
+ "单卡:常见家电的功率（物理学·通识知识卡）": 242,
+ "单卡:日食与月食的成因（天文学·通识知识卡）": 242,
+ "数学分析知识点内容（按骨架填充）→高中数学知识点内容（按骨架填充）→测度论与物理离散性": 116,
+ "单卡:数学分析知识点内容（按骨架填充）": 242,
+ "单卡:测度论与物理离散性": 242,
+ "高中数学知识点内容（按骨架填充）→数学分析知识点内容（按骨架填充）→测度论与物理离散性": 126,
  "协议-知识飞轮→白箱测试定义→价值理论与AI对齐": 1,
  "单卡:协议-知识飞轮": 1,
  "单卡:白箱测试定义": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furongjun1999/dsh-memory",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "灵枢（Lingshu·líng shū）DeepSeek Harness 插件：完整大脑——长期记忆/知识飞轮/自我认知/递归反思接入 DSH，对话自动沉淀进 md_cg 认知图（md 文档）",
   "type": "module",
   "main": "lib/index.js",

package/src/lib/mdcg_client.ts

@@ -78,6 +78,56 @@ export interface MdcgOptions {
 
 const DEFAULT_ARGS = ['-m', 'md_cg.mcp_server']
 
+/** 子进程环境构造参数（`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 function mdcgChildEnv(opts: MdcgChildEnvOptions): Record<string, string> {
+  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 不算强依据）。 */
@@ -130,23 +180,8 @@ export class MdcgClient {
     // 模块解析不依赖 cwd：PYTHONPATH（pythonPathValue()）已锚定随包 md_cg；
     // opts.env 显式提供 PYTHONPATH 时完全接管（其展开在最后）。详见 datapath.runRoot()。
     const cwd = opts.cwd ?? runRoot()
-    const env: Record<string, string> = {
-      // ⚠️ 必须显式 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,