@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/skills/skills/designer-perspective/scripts/designer.py

@@ -50,6 +50,7 @@ DIM_KEYWORDS = (
 )
 
 
+# 生效条件：对 sys.stdout 与 sys.stderr 依次尝试 reconfigure(encoding="utf-8")，任何异常都被 try/except 吞掉后继续；
 def _stdout_utf8():
     for stream in (sys.stdout, sys.stderr):
         try:
@@ -58,6 +59,7 @@ def _stdout_utf8():
             pass
 
 
+# 生效条件：text 为 None 或空串时返回 default，text 已是 dict/list 时原样返回，否则返回 json.loads(text) 的结果；
 def _load_json_arg(text, default):
     if text is None or text == "":
         return default
@@ -66,12 +68,14 @@ def _load_json_arg(text, default):
     return json.loads(text)
 
 
+# 生效条件：value 为假值（None/""/[]/{}/0）时返回 []，value 是 str 时返回 [value]，其余返回 list(value)；
 def _as_list(value):
     if not value:
         return []
     return [value] if isinstance(value, str) else list(value)
 
 
+# 生效条件：text 为假值时先置为 ""，按 DIM_KEYWORDS 顺序返回首个含命中关键词的维度，全部未命中返回 "条件边界"；
 def classify_dimension(text):
     """把失配描述归入五失配维度之一；未命中归入「条件边界」。"""
     text = text or ""
@@ -81,10 +85,12 @@ def classify_dimension(text):
     return "条件边界"
 
 
+# 生效条件：key 在 FOUR_DIMS 中时原样返回 key，否则返回 classify_dimension(key) 的归类结果；
 def _dim_of_key(key):
     return key if key in FOUR_DIMS else classify_dimension(key)
 
 
+# 生效条件：conditions 为假值（None/""/{}）时返回 {}，conditions 是 str 时先 json.loads 再 dict(...)，其余直接 dict(conditions)；
 def normalize_conditions(conditions):
     if not conditions:
         return {}
@@ -95,6 +101,7 @@ def normalize_conditions(conditions):
 
 # ---------------------------------------------------------------- 步骤 1：声明
 
+# 生效条件：position 为假值时回落 "designer"，不在 POSITION_MAP 中时 raise SystemExit，space 假值时用空 OrderedDict 并 setdefault 观测位置，返回含 space_id、layer、missing_dims 的 OrderedDict；
 def declare_core(position="designer", space=None):
     """条件空间声明：四维 + 有效范围 + 切换规则（3.1/3.2）。"""
     position = position or "designer"
@@ -115,6 +122,7 @@ def declare_core(position="designer", space=None):
 
 # ---------------------------------------------------------------- 步骤 2-3：白箱三问 + 四态
 
+# 生效条件：evidence 取 candidate["evidence"] or conditions["anchors"] 再 _as_list，vpath 取 verification_path or candidate["verification_path"] 再 _as_list；evidence 为空返回 (False,"观测工具",detail)，否则 conditions 缺任一 FOUR_DIMS 时返回 (False, 首个缺失维度, detail)，否则 vpath 为空返回 (False,"条件边界",detail)，全齐返回 (True,None,detail)；
 def whitebox_check(candidate, conditions, verification_path=None):
     """白箱三问（第〇章）。返回 (ok, missing_dim, detail)。"""
     evidence = _as_list(candidate.get("evidence") or conditions.get("anchors"))
@@ -134,6 +142,7 @@ def whitebox_check(candidate, conditions, verification_path=None):
     return True, None, detail
 
 
+# 生效条件：candidates 为假值（None/[]）判 BLINDSPOT，否则逐候选按 not_applicable 与 query 的冲突记 REJECT、when 与 conditions 不符记 DEFER，全为 REJECT 判 REJECT、无合格候选取首个 DEFER、多个合格候选仅唯一 distinguishing 时选之否则 DEFER，verdict 仍空时由 whitebox_check(cand, conditions, verification_path) 定 ACCEPT 或 DEFER；
 def judge_core(query, conditions=None, candidates=None, verification_path=None):
     """四态资格裁决（6章.2）：先拒绝，后接受。"""
     conditions = normalize_conditions(conditions)
@@ -248,6 +257,7 @@ def emit_mcp_calls(result):
     return calls
 
 
+# 生效条件：从 result["conditions"] 取四维（.get 缺键显示 <未声明>）、从 result["traces"] 中首个含 "whitebox" 的项渲染白箱行，emit_mcp 为真值时追加 emit_mcp_calls(result) 的 JSON，返回 '\n'.join(lines)；
 def render_verdict(result, emit_mcp=False):
     c = result["conditions"]
     lines = ["[判定单]",
@@ -275,6 +285,7 @@ def render_verdict(result, emit_mcp=False):
 
 # ---------------------------------------------------------------- 步骤 5：归因 / 蒸馏
 
+# 生效条件：error 为假值时先 dict({})，missing 取 error.get("missing","")，dim 取 error.get("dimension") or classify_dimension(missing) 且不在 FIVE_MISMATCH 时回落 "条件边界"，返回含 triple/mismatch_dim/discipline 的 OrderedDict；
 def attribute_core(error):
     """条件层归因：三方条件空间失配 + 五失配维度定位（附录22.3）。"""
     error = dict(error or {})
@@ -297,6 +308,7 @@ def attribute_core(error):
     ])
 
 
+# 生效条件：对 rows 每行按 dimension 或 classify_dimension(row.get("missing","")) 分组（不在 FIVE_MISMATCH 归入 "条件边界"），每组以首行 symptom/missing 生成一条带 when/rule/change 的纪律项，rows 为空返回空 items 列表；
 def distill_core(rows):
     """失败集合 → 带适用条件的可复用纪律（1.1.1）。"""
     groups = defaultdict(list)
@@ -318,6 +330,7 @@ def distill_core(rows):
     return items
 
 
+# 生效条件：对 items 逐项（依赖 it["missing"]/["rule"]/["when"]/["change"]/["evidence"]）编号渲染 markdown 段落，items 为空时返回仅含标题与说明的文本；
 def render_distill(items):
     lines = ["# 蒸馏纪律（失败资产化）", "",
              "> 失败 → 根因（条件层）→ 可复用纪律（带适用条件）→ 注入 → 不再犯（1.1.1）", ""]
@@ -334,6 +347,7 @@ def render_distill(items):
 
 # ---------------------------------------------------------------- probe / selftest
 
+# 生效条件：按 os.environ.get("DMCG_HOME") 再 DEFAULT_DMCG_HOME 顺序，跳过假值或不含 md_cg 子目录的 base，命中的 base 插入 sys.path 后 import md_cg.mdcos，成功返回 available=True/mode=read-only，import 抛异常返回 available=False/degraded 附 error，全部未命中返回 available=False、base=None；
 def probe_mdcg():
     """探测 md_cg 认知图可用性（只读 import，不实例化、不写库）。"""
     bases = [os.environ.get("DMCG_HOME"), DEFAULT_DMCG_HOME]
@@ -358,6 +372,7 @@ def probe_mdcg():
                         ("error", "未找到 md_cg（可设 DMCG_HOME 指向 dsh-memory 根目录）")])
 
 
+# 生效条件：按 case.get("kind") 分派 —— declare 比对 declare_core 的 missing_dims 与 expect 的 dims_complete/observation_position_contains，judge 与 verify 比对 judge_core 的 verdict/missing_dim 与 expect 的 state/missing_dim/require_verification_path/require_missing_dim，missing 比对 attribute_core 的 mismatch_dim，其余 kind 记 ok=False；
 def run_cases(cases):
     results = []
     for case in cases:
@@ -397,6 +412,7 @@ def run_cases(cases):
 
 # ---------------------------------------------------------------- CLI
 
+# 生效条件：items 为假值（None/空列表）时返回空 OrderedDict，否则每项不含 "=" 时 raise SystemExit，含 "=" 的按首个 "=" 拆分并 strip 后写入 space；
 def _parse_space(items):
     space = OrderedDict()
     for it in items or []:
@@ -527,4 +543,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/skills/skills/designer-perspective/tests/selftest.py

@@ -21,6 +21,7 @@ sys.path.insert(0, os.path.join(ROOT, "scripts"))
 import designer  # noqa: E402  （路径注入后导入）
 
 
+# 生效条件：读取 cases_path 的 JSONL（strip 后为空的行跳过）交给 designer.run_cases，返回 (results, passed, total) 三元组；
 def run(cases_path):
     with open(cases_path, encoding="utf-8") as fh:
         cases = [json.loads(line) for line in fh if line.strip()]
@@ -30,6 +31,7 @@ def run(cases_path):
     return results, passed, total
 
 
+# 生效条件：argv（None 时取 sys.argv）解析后 --cases 缺省为 HERE/cases.jsonl，调用 run 后 passed==total 返回 0 否则返回 1，--json 为真值时打印 JSON 汇总、否则打印逐项明细；
 def main(argv=None):
     ap = argparse.ArgumentParser(prog="selftest.py",
                                  description="设计者视角 · 认知能力验收")
@@ -57,4 +59,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/src/hooks.ts

@@ -21,6 +21,14 @@
  * 模型请求组装 system prompt 时自动注入灵枢最近记忆
  * （`stg(op=timeline)`，最近记忆节点时间线），让记忆"自动可用"而不只依赖
  * Agent 主动调用 recall/think 工具。失败静默（不影响请求）。
+ * ⚠️ 该注入块的**稳定性**决定宿主是否新追加快照：内容没变时也必须照旧 push
+ * （宿主按渲染后的整段文本去重）；跳过 push 反而会各追加一份「有块/无块」的快照
+ * —— 详见 installMemoryHooks 里的长注释。
+ *
+ * ⚠️ 注入文本**必经** escapePromptBraces（src/lib/prompt_safety.ts，issue #16）：
+ * 宿主对 context 文本做严格 `{{variable}}` 插值，裸 `{{` 会让每轮 assemble 抛错
+ * → 会话永久不可用（记忆永久在库，非偶发）。记忆真源不动，只在**注入副本**上
+ * 打断 `{{`——新增任何 push context/section 的代码，同样必须过这道转义。
  */
 
 import '@deepseek-ai/dsh-session'
@@ -29,6 +37,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { MdcgClient } from './lib/mdcg_client.js'
+import { escapePromptBraces } from './lib/prompt_safety.js'
 
 /** 自动记忆开关。 */
 export interface MemoryHooksOptions {
@@ -120,8 +129,6 @@ const RECALL_MIN_CHARS = 24
 const RECALL_MAX_CHARS = 1400
 /** 永久层不自动注入（按需用 mdcg_recall / lingshu_stg 取）。 */
 const RECALL_SKIP_LAYERS = new Set(['anchor', 'self'])
-/** 连续跳过多少步后强制补一次（内容未变也刷新，防止压缩归档后块消失）。 */
-const RECALL_REPUSH_EVERY = 8
 
 /** 分级递减渲染：按距当前的次序逐档收窄，早期条目信息量更大。
  *
@@ -153,17 +160,6 @@ function formatTimelineDecayed(payload: unknown): string {
   return out.join('\n').slice(0, RECALL_MAX_CHARS)
 }
 
-/** 去重：内容与上次相同就不再 push 新副本。
- *
- *  背景：本钩子挂在 `system-prompt/assemble` 上，每个 step 都会 push 一份，而每份
- *  都会留成独立的 surface 节点 → 同一块累积 N 份（实测 11 份 ≈2700 tok/请求），
- *  随步数线性增长。去重后同一块只占 1 份，外加每 RECALL_REPUSH_EVERY 步一次自愈刷新。 */
-function shouldPushRecall(text: string, lastText: string, skippedSincePush: number): boolean {
-  if (!text) return false
-  if (text !== lastText) return true
-  return skippedSincePush >= RECALL_REPUSH_EVERY
-}
-
 /** 安装自动记忆钩子（effect 作用域内，随插件卸载自动移除）。
  *
  *  mdcg 为 null（config.mdcg.enabled=false）时自动记忆整体停用：记忆真源是
@@ -194,25 +190,34 @@ export function installMemoryHooks(ctx: Context, mdcg: MdcgClient | null, opts:
 
   // P1 完善（自动 recall 注入）：每次模型请求组装 system prompt 时，注入灵枢最近记忆。
   // 用 system-prompt/assemble 事件（waterfall）而非 llm/stream——后者请求 deep-frozen 不可改写。
+  //
+  // ⚠️ 必须**每步都 push**，哪怕内容与上一步逐字节相同。原因在宿主侧（dsh-agent-loop 的
+  // RuntimeContextProjection）：assembly.contexts 会被渲染成一段「运行时上下文快照」，
+  // 每个 step 拿渲染后的**整段文本**与上一份已提交的快照比对，**只有不同才**在会话里
+  // append 一条新的 user/message（append 语义，旧的不会被替换或移除）。于是：
+  //   · 内容不变 + 照旧 push → 渲染文本不变 → 宿主不追加任何东西（零开销、零增长）；
+  //   · 内容不变 + 跳过 push → 渲染文本**变了**（少了本块）→ 宿主追加一份「没有本块」的
+  //     快照；下一步再 push 又把本块加回来 → **再**追加一份。跳过一次反而多花两份快照
+  //     （实测每份 ~250 tok），这正是 v0.4.8「每 8 步强制补一次」的自愈刷新会把长会话的
+  //     inject 推到 30k+ tok 的原因。
+  // 因此本实现把「要不要补」交还给宿主：压缩归档后宿主会把 retained 置空并重新投影快照
+  // （RuntimeContextProjection 的 retained === null 分支），本块自然跟着回来——
+  // 不需要插件自己数步数做自愈。
   if (opts.autoRecall) {
     const recallLimit = Math.max(1, Math.min(10, opts.autoRecallLimit || 4))
-    // 去重状态：同一块内容只保留一份 surface 节点，避免随步数线性增长。
-    let lastRecallText = ''
-    let skippedSincePush = 0
     ctx.on('system-prompt/assemble', async (assembly, _ctx, next) => {
       try {
         // 异步取最近记忆节点（失败静默——不阻塞模型请求）
         if (graph.isReady()) {
           const text = formatTimelineDecayed(await graph.timeline(recallLimit))
-          if (shouldPushRecall(text, lastRecallText, skippedSincePush)) {
-            lastRecallText = text
-            skippedSincePush = 0
+          if (text) {
+            // 注入边界转义（issue #16）：宿主 system-prompt 对 context 文本做严格
+            // `{{variable}}` 插值，裸 `{{` 会 throw → 该轮请求整体失败。记忆原文
+            // （含用户命令里的 `{{.X}}`）必须保真落库，故只在注入副本上打断 `{{`。
             assembly.contexts.push({
               name: 'lingshu:auto-recall',
-              text: `【灵枢最近记忆】\n${text.slice(0, RECALL_MAX_CHARS)}`,
+              text: escapePromptBraces(`【灵枢最近记忆】\n${text.slice(0, RECALL_MAX_CHARS)}`),
             })
-          } else {
-            skippedSincePush += 1
           }
         }
       }

package/src/index.ts

@@ -17,8 +17,10 @@
  *   name: '@furongjun1999/dsh-memory'
  *   config:
  *     mdcg:                              # 记忆真源：认知图（md 文档）
- *       # root = 记忆写入路径（用户可改）。缺省 = 插件仓自身 data/mdcg。
- *       # 覆盖优先级：env MDCG_ROOT > <插件仓>/data/paths.json > 本项 > 默认
+ *       # root = 记忆写入路径（用户可改）。缺省 = 用户级状态根 data/mdcg
+ *       #   （~/.dsh/.dsh-memory/data/mdcg；**不在插件包内**——包内数据会被
+ *       #    pnpm 更新连目录一起删掉，见 src/lib/datapath.ts 头注）
+ *       # 覆盖优先级：env MDCG_ROOT > <用户级状态根>/paths.json > 本项 > 默认
  *       # root: 'D:/somewhere/mdcg'        # 例：把记忆库放到别处
  *       actor: 'dsh-memory'
  *     env:                               # 写入凭据：默认【关闭】，由你决定是否打开
@@ -52,7 +54,7 @@ import { installMemoryHooks, type MemoryHooksOptions } from './hooks.js'
 // LIB 本地库：角色扮演网页 / 互维维护 / 白箱 LLM 适配器统一收在 src/lib/。
 import { installRoleplayWeb } from './lib/roleplay_web.js'
 import { MdcgClient } from './lib/mdcg_client.js'
-import { describeDataPaths, mdcgRoot } from './lib/datapath.js'
+import { describeDataPaths, migrateLegacyData, mdcgRoot, repoRoot } from './lib/datapath.js'
 // 写入凭据密钥环（首启引导）：显式配置 → ~/.mdcg/token → 首启自动签发。
 import { resolveToken, type TokenResolution } from './lib/token_store.js'
 
@@ -178,8 +180,9 @@ export const Config: z<Config> = z.object({
     .default({ enabled: false, heartbeatMs: 10 * 60 * 1000 }),
   /** 认知图（md_cg）：记忆唯一真源。
    *  root 为**记忆写入路径**（用户可改）。缺省空串 = 未指定，按优先级解析：
-   *    ① env MDCG_ROOT ② `<插件仓>/data/paths.json` 的 root
-   *    ③ 本项 ④ 默认 `<插件仓>/data/mdcg`
+   *    ① env MDCG_ROOT ② `<用户级状态根>/paths.json` 的 root
+   *    （旧 `<插件仓>/data/paths.json` 兼容读）
+   *    ③ 本项 ④ 默认 `<用户级状态根>/data/mdcg`
    *  相对路径一律相对**插件仓根**解析——历史教训：相对 cwd 的相对路径随
    *  宿主 cwd 漂移，cwd 落在别仓时记忆真源分裂成互不可见的两处。
    *  tenant/actor 决定私有内容加解密的身份：与 migrate_roleplay 的
@@ -255,15 +258,39 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
       timeoutMs: config.toolCallTimeoutMs,
       maxRetryDelayMs: config.maxRetryDelayMs,
     })
+    // 数据面迁出插件包（issue #18 相邻问题）：旧版把运行时数据与路径配置写在包内
+    // `<pkg>/data`，pnpm 更新会连目录一起替换（实机实证：data/ 54 文件 → 0，
+    // 46 条记忆节点靠人工备份回填）。首启把「旧位置仍有货」的数据**复制**到用户级
+    // 数据根；必须在 mdcg.start() 之前——store 要在 Python 子进程接管前就位。
+    const migrated = migrateLegacyData()
+    if (migrated.ran) {
+      ctx.logger.info(
+        `dsh-memory: 数据面已迁出插件包（旧位置只复制未删除）：`
+        + `${migrated.from} → ${migrated.to}（${migrated.copied} 项`
+        + `${migrated.failed.length ? `，失败 ${migrated.failed.join(',')}` : ''}）`,
+      )
+    }
     mdcg.start()
     // 启动留痕：把「记忆真源在哪、由谁决定、路径是否存在」写进可审计日志，
     // 避免再次出现「以为在记忆、其实写到了别仓」的静默分裂（历史事故）。
     const dp = describeDataPaths(config.mdcg.root)
     ctx.logger.info(
       `dsh-memory: 记忆真源路径 = ${dp.mdcgRoot}（来源 ${dp.source}，`
-      + `dataRoot=${dp.dataRoot}，存在=${dp.mdcgRootExists ? '是' : '否（首次写入将创建）'}，`
+      + `状态根=${dp.stateRoot}，dataRoot=${dp.dataRoot}，`
+      + `存在=${dp.mdcgRootExists ? '是' : '否（首次写入将创建）'}，`
       + `用户可改：${dp.pathsFile}）`,
     )
+    // 包管理器装的插件 + 路径配置还在旧包内位置：pnpm 下次更新会把该文件连目录一起
+    // 删除，用户配置随之丢失（回落默认根 → 表现为「记忆不见了」）。只在真的会被删的
+    // 布局下提醒（开发用的 git clone 不含 node_modules 段 → 不打扰）。
+    const pnpmManaged = repoRoot().split(/[\\/]/).includes('node_modules')
+    if (pnpmManaged && String(dp.pathsFileSource) === 'legacy') {
+      ctx.logger.warn(
+        `dsh-memory: 路径配置仍在插件包内（${dp.pathsFile}）——pnpm 更新该包会连目录`
+        + `一起删除。请复制到 ${String(dp.stateRoot)}/paths.json 后重启`
+        + `（数据面已自动复制到 ${String(dp.dataRoot)}）。`,
+      )
+    }
     brainReady = await mdcg.waitReady()
     if (brainReady) {
       ctx.logger.info(`dsh-memory: 认知图已就绪（MDCG_ROOT=${resolvedRoot}）`)

package/src/lib/datapath.ts

@@ -2,21 +2,33 @@
  * datapath.ts · 灵枢数据根解析（记忆写入路径可配置）
  *
  * 与 Python 侧 `md_cg/datapath.py` **同口径**——两侧读同一份
- * `<插件仓>/data/paths.json`，避免大脑与脚本对「记忆真源在哪」各持一说。
+ * `<用户级状态根>/paths.json`（新位置；旧版 `<插件仓>/data/paths.json`
+ * 仍兼容读），避免大脑与脚本对「记忆真源在哪」各持一说。
+ *
+ * 为什么默认不再取「插件仓自身 data/」（issue #18 相邻问题，数据丢失级）：
+ *   DSH 插件按 hoisted 布局装在 `<profile>/node_modules/<pkg>`，`pnpm` 更新该包
+ *   会**整个替换包目录**——运行时数据落在包内（`<pkg>/data`）时，每次更新成功
+ *   即连目录一起删掉（贡献者实机实证：`data/` 54 文件 → 0，46 条记忆节点只能
+ *   靠人工备份回填）；`paths.json` 同址，用户配置一并丢失。故默认数据根与配置
+ *   文件一律落**用户级状态根**（见 `stateRoot()`），与包目录彻底解耦。
  *
  * 优先级（高 → 低）：
  *   1. 环境变量 `MDCG_DATA_ROOT`（数据根）／ `MDCG_ROOT`（认知图根）
- *   2. 用户可编辑配置 `<插件仓>/data/paths.json` 的 `data_root` / `root`
+ *   2. 用户可编辑配置 `paths.json` 的 `data_root` / `root`
+ *      （位置：`<用户级状态根>/paths.json`；旧 `<插件仓>/data/paths.json` 兼容读）
  *   3. 插件配置项 `mdcg.root`（可为空=未指定）
- *   4. 默认 `<插件仓>/data/mdcg`（**自身仓库**，与进程 cwd 解耦）
+ *   4. 默认 `<用户级状态根>/data/mdcg`
  *
- * 为什么默认不再取「相对 cwd 的 data/mdcg」：
+ * 为什么默认不取「相对 cwd 的 data/mdcg」：
  *   node 侧插件与 python 侧脚本的 cwd 不同，相对路径会漂移成
  *   `<cwd>/data/mdcg`。历史事故：宿主 cwd 落在 AEIS 时，记忆真源
  *   分裂到 `AEIS/data/mdcg`，与插件仓 `data/` 变成互不可见的两处。
- *   锚定 `package.json` 所在目录后，默认值稳定且可预期。
+ *
+ * 旧数据接手：`migrateLegacyData()` 在默认数据根生效且旧包内位置仍有内容时
+ * 一次性**复制**（不删除、不覆盖）到用户级位置——见该函数注释。
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
 import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -43,9 +55,56 @@ export function repoRoot(): string {
   return cachedRepoRoot
 }
 
-/** 用户可编辑的路径配置文件（固定在插件仓 data/，不受 dataRoot 取值影响）。 */
+export const ENV_STATE_ROOT = 'MDCG_STATE_ROOT'
+
+let cachedStateRoot: string | null = null
+
+/**
+ * 用户级状态根（**插件包目录之外**）：路径配置与默认数据根的落点。
+ * 优先级：`MDCG_STATE_ROOT` → `$DSH_HOME/.dsh-memory` → `~/.dsh/.dsh-memory`。
+ * `DSH_HOME` **未必**由宿主注入（本仓 `dsh/dsh-web-start.bat` 自行 set），
+ * 故家目录兜底；`~/.dsh` 是本插件既有约定（`bridge.ts` 调试日志同址）。
+ */
+export function stateRoot(): string {
+  if (cachedStateRoot) return cachedStateRoot
+  const env = process.env[ENV_STATE_ROOT]
+  if (env) {
+    cachedStateRoot = resolve(env)
+    return cachedStateRoot
+  }
+  const dshHome = process.env['DSH_HOME']
+  cachedStateRoot = dshHome
+    ? join(resolve(dshHome), '.dsh-memory')
+    : join(homedir(), '.dsh', '.dsh-memory')
+  return cachedStateRoot
+}
+
+/** 旧版落点（插件包内 `data/`）——更新时会被整个替换，只作兼容读与迁移源。 */
+export function legacyDataRoot(): string {
+  return join(repoRoot(), 'data')
+}
+
+function samePath(a: string, b: string): boolean {
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
+/**
+ * 用户可编辑的路径配置文件：
+ *   `<用户级状态根>/paths.json` → 不存在则回落**旧** `<插件仓>/data/paths.json`
+ *   （兼容读）→ 都不存在返回新位置（首次写入时创建）。
+ * 不做自动复制：配置文件是「谁说了算」的唯一真源，悄悄复制会让旧件的后续编辑
+ * 静默失效——迁移只搬数据面，配置显式交给用户搬（或用 `set_user_root`）。
+ */
 export function pathsFile(): string {
-  return join(repoRoot(), 'data', 'paths.json')
+  const current = join(stateRoot(), 'paths.json')
+  if (existsSync(current)) return current
+  const legacy = join(legacyDataRoot(), 'paths.json')
+  return existsSync(legacy) ? legacy : current
+}
+
+/** 生效中的 paths.json 位置来源：`user`=用户级 / `legacy`=旧包内（兼容读）。 */
+export function pathsFileSource(): 'user' | 'legacy' {
+  return samePath(dirname(pathsFile()), stateRoot()) ? 'user' : 'legacy'
 }
 
 function readUserPaths(): Record<string, unknown> {
@@ -63,8 +122,141 @@ function anchor(p: string): string {
   return isAbsolute(p) ? p : resolve(repoRoot(), p)
 }
 
+/** 默认数据根 = 用户级状态根下 `data/`（**插件包目录之外**，更新不触碰）。 */
 export function defaultDataRoot(): string {
-  return join(repoRoot(), 'data')
+  return join(stateRoot(), 'data')
+}
+
+export interface LegacyMigration {
+  /** 是否真的搬了（false 时 `reason` 说明为何没搬）。 */
+  ran: boolean
+  reason: string
+  from: string
+  to: string
+  /** 复制成功的顶层条目数。 */
+  copied: number
+  /** 复制失败的顶层条目（权限/占用等，逐项吞掉不抛）。 */
+  failed: string[]
+}
+
+/** dst 为「空目录」时 true（不存在/非目录/有内容均为 false）。 */
+function isEmptyDir(p: string): boolean {
+  try {
+    return readdirSync(p).length === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 一次性迁移：把旧版留在**插件包内** `data/` 的数据面复制到用户级默认数据根。
+ *
+ * 触发条件（三条同时满足，缺一不动）：
+ *   ① 数据根未被显式配置（env `MDCG_DATA_ROOT` / paths.json 的 `data_root` 都未设，
+ *      即 `dataRoot()` 恰为默认值）——显式配置是用户的决定，越权搬运等于改他的真源；
+ *   ② 旧位置存在；
+ *   ③ 目标顶层条目不存在或为空目录（**不覆盖、不合并**已有数据）。
+ *
+ * 只复制不删除（旧目录随后由 pnpm 更新自然移除）；`paths.json` 不复制
+ * （配置走 `pathsFile()` 兼容读，复制会制造「哪个文件说了算」的两说）。
+ * 任何异常逐项吞掉并记入 `failed`——迁移是增益，不该成为启动失败源。
+ *
+ * 边界（如实）：pnpm 更新是**先替换包目录再启动新代码**，故旧数据在升级瞬间
+ * 即已消失，本函数只能接手「旧位置那时仍在」的情形（手工安装、就地覆盖、
+ * 或包目录未被清理）；已在升级中丢掉的数据无法由此恢复——发布说明须提示
+ * 0.4.8 及更早用户升级前备份 `<profile>/node_modules/<pkg>/data/`。
+ */
+export function migrateLegacyData(): LegacyMigration {
+  const from = legacyDataRoot()
+  const to = defaultDataRoot()
+  const out: LegacyMigration = { ran: false, reason: '', from, to, copied: 0, failed: [] }
+  if (!samePath(dataRoot(), to)) {
+    out.reason = '数据根为显式配置（env/paths.json），不迁移'
+    return out
+  }
+  if (!existsSync(from)) {
+    out.reason = '旧位置不存在（多为更新时已随包目录被替换）'
+    return out
+  }
+  let entries: string[]
+  try {
+    entries = readdirSync(from)
+  } catch {
+    out.reason = '旧位置不可读'
+    return out
+  }
+  const names = entries.filter((n) => n !== 'paths.json')
+  if (!names.length) {
+    out.reason = '旧位置无数据'
+    return out
+  }
+  for (const name of names) {
+    const src = join(from, name)
+    const dst = join(to, name)
+    // 新位置已有实质内容 → 跳过（宁可少搬，不可覆盖）
+    if (existsSync(dst) && !isEmptyDir(dst)) continue
+    try {
+      mkdirSync(to, { recursive: true })
+      cpSync(src, dst, { recursive: true, force: false, errorOnExist: false })
+      out.copied += 1
+    } catch {
+      out.failed.push(name)
+    }
+  }
+  out.ran = out.copied > 0
+  if (!out.ran) out.reason = out.failed.length ? '目标不可写' : '新位置已有数据，未覆盖'
+  return out
+}
+
+export const ENV_CHILD_CWD = 'MDCG_CHILD_CWD'
+
+let cachedRunRoot: string | null = null
+
+/**
+ * 子进程的工作目录（**必须落在插件包目录之外**）。
+ *
+ * 为什么不能沿用 `repoRoot()`：Windows 不允许删除／改名「正被某进程当作 CWD」
+ * 的目录。DSH 的插件按 hoisted 布局安装在 `<profile>/node_modules/<pkg>`，
+ * 而 `pnpm` 每次更新该包都要先 `rmdir` 包目录 → 子进程一旦把包目录当 CWD，
+ * 更新必然 `ERR_PNPM_EBUSY: resource busy or locked`（含升级回滚一起失败，
+ * 应用内永远升不动这个插件）。注意落点也**不能**是 `<包>/data`——它仍在包内，
+ * 实测同样 `err=32`。
+ *
+ * 落点要求「稳定存在」：进程 cwd 指向已消失的目录会引出新的怪问题，故按稳定度
+ * 排候选目录，取**第一个能建成**的：
+ *   1. `MDCG_CHILD_CWD`（显式覆盖）
+ *   2. `$DSH_HOME/.dsh-memory/run`
+ *   3. `~/.dsh/.dsh-memory/run` —— 家目录兜底：`DSH_HOME` **未必**由宿主注入
+ *      （本仓 `dsh/dsh-web-start.bat` 是自行 `set DSH_HOME=%USERPROFILE%\.dsh`），
+ *      而 `~/.dsh` 是本插件既有约定（`bridge.ts` 调试日志、`token_store` 密钥环同址）
+ *   4. 系统临时目录（可能被清理，故排最后）
+ * 全部建不成时不抛错，交给 spawn 报错——cwd 落点只是防呆，不该成为启动失败源。
+ *
+ * 安全性：`python -m` 的模块解析由 `pythonPathValue()` 的 PYTHONPATH 独立保证，
+ * 不依赖 cwd；已实测 cwd=包目录 与 cwd=包外 时，MCP initialize 握手与
+ * tools/list 工具面（33 个工具）完全一致。
+ */
+export function runRoot(): string {
+  if (cachedRunRoot) return cachedRunRoot
+  const candidates: string[] = []
+  const override = process.env[ENV_CHILD_CWD]
+  if (override) candidates.push(resolve(override))
+  const dshHome = process.env['DSH_HOME']
+  if (dshHome) candidates.push(join(resolve(dshHome), '.dsh-memory', 'run'))
+  candidates.push(join(homedir(), '.dsh', '.dsh-memory', 'run'))
+  candidates.push(join(tmpdir(), 'dsh-memory-run'))
+  for (const dir of candidates) {
+    try {
+      mkdirSync(dir, { recursive: true })
+      cachedRunRoot = dir
+      return dir
+    } catch {
+      /* 该候选不可用（父目录只读等）→ 试下一个 */
+    }
+  }
+  const last = candidates[candidates.length - 1] ?? tmpdir()
+  cachedRunRoot = last
+  return last
 }
 
 /** 数据根（记忆/账本/运行态的父目录）。 */
@@ -110,18 +302,24 @@ export function describeDataPaths(configured?: string): Record<string, string |
   const dr = dataRoot()
   const mr = mdcgRoot(configured)
   const paths = readUserPaths()
-  let source = 'default(插件仓自身 data/)'
+  const pfSource = pathsFileSource()
+  let source = 'default(用户级状态根 data/)'
   if (process.env[ENV_DATA_ROOT]) source = `env:${ENV_DATA_ROOT}`
   else if (process.env[ENV_MDCG_ROOT]) source = `env:${ENV_MDCG_ROOT}`
-  else if (typeof paths['data_root'] === 'string' || typeof paths['root'] === 'string') source = 'paths.json'
-  else if (configured && configured.trim()) source = 'config.mdcg.root'
+  else if (typeof paths['data_root'] === 'string' || typeof paths['root'] === 'string') {
+    source = pfSource === 'user' ? 'paths.json(用户级)' : 'paths.json(兼容读旧包内位置)'
+  } else if (configured && configured.trim()) source = 'config.mdcg.root'
   return {
     repoRoot: repoRoot(),
+    stateRoot: stateRoot(),
     dataRoot: dr,
     mdcgRoot: mr,
     source,
     pathsFile: pathsFile(),
-    isDefault: dr === defaultDataRoot(),
+    pathsFileSource: pfSource,
+    isDefault: samePath(dr, defaultDataRoot()),
+    legacyDataRoot: legacyDataRoot(),
+    legacyDataExists: existsSync(legacyDataRoot()),
     dataRootExists: existsSync(dr),
     mdcgRootExists: existsSync(mr),
   }

package/src/lib/mdcg_client.ts

@@ -37,7 +37,7 @@
 
 import { delimiter } from 'node:path'
 import { LingshuBridge, type McpCallResult } from '../bridge.js'
-import { pythonPathValue, repoRoot } from './datapath.js'
+import { pythonPathValue, runRoot } from './datapath.js'
 
 /** md_cg 子进程与根目录配置。 */
 export interface MdcgOptions {
@@ -47,9 +47,12 @@ export interface MdcgOptions {
   args?: string[]
   /** 认知图根目录（MDCG_ROOT）。 */
   root: string
-  /** Python 子进程工作目录，默认**插件仓根**（issue #12：Python 只把 cwd
-   *  注入 sys.path，宿主在插件仓外启动时 `python -m md_cg.mcp_server`
-   *  找不到随包 md_cg → 必然 ModuleNotFoundError → 静默降级只读 guest）。 */
+  /** Python 子进程工作目录，默认 `runRoot()`——**插件包目录之外**的稳定目录
+   *  （issue #18：Windows 不允许删除/改名「正被某进程当作 cwd」的目录，
+   *  cwd 落在包内会让 pnpm 更新本包必然 `ERR_PNPM_EBUSY` 且永不自愈）。
+   *  模块解析**不依赖 cwd**：`python -m` 靠 `PYTHONPATH`
+   *  （见 `pythonPathValue()`）解析随包 md_cg，issue #12 口径不变。
+   *  显式传入本项时完全尊重原值。 */
   cwd?: string
   /** 调用主体标识（MDCG_ACTOR）。私有内容按 (tenant, actor) 派生 DEK，
    *  故与迁移脚本 --actor 必须一致，否则读不到已迁移节点。 */
@@ -122,10 +125,11 @@ export class MdcgClient {
   readonly bridge: LingshuBridge
 
   constructor(opts: MdcgOptions) {
-    // issue #12：cwd 与 PYTHONPATH 双保险锚定插件仓根——cwd 是 `python -m`
-    // 解析随包包的主通道，PYTHONPATH 覆盖显式自定义 args 的场景。opts.env
-    // 显式提供 PYTHONPATH 时完全接管（其展开在最后：显式配置原样尊重）。
-    const cwd = opts.cwd ?? repoRoot()
+    // 子进程 cwd 必须落在插件包目录之外，否则 pnpm 更新本插件时
+    // rmdir 包目录会撞上 Windows 的「目录被当作 CWD」共享冲突 → ERR_PNPM_EBUSY。
+    // 模块解析不依赖 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 在落盘 /