@furongjun1999/dsh-memory 0.4.11 → 0.5.1

package/md_cg/test_datapath_device_name.py

@@ -0,0 +1,203 @@
+# -*- coding: utf-8 -*-
+"""test_datapath_device_name.py · Windows 保留设备名末段吞路径的守卫（issue #39 相邻缺陷）
+
+现场（Windows 实测）：``ntpath.abspath`` 经 ``GetFullPathNameW`` 归一路径时，若
+路径**末段是 Windows 保留设备名**（aux/con/nul/prn/com1-9/lpt1-9 等），整个路径
+被吞成设备命名空间形态——env 设 ``MDCG_AUX_ROOT=<临时目录>\\aux`` 时
+``datapath.aux_root()`` 返回 ``\\\\.\\aux``，原目录语义**静默丢失**：密钥/令牌/
+信任面被指到不存在的设备路径，覆盖键静默失联（不报错、最难察觉的失败形态）。
+``abspath`` 是纯字符串归一**不触盘**，故守卫只需把 env 指向含保留名末段的
+**不存在路径**即可实弹复现——绝不能真的创建 aux 末段目录（Win32
+CreateDirectory 同样被设备名劫持）。
+
+修复（本守卫的红绿两态锚点）：``md_cg/datapath.py`` 新增模块级
+``_abs_host_path(p, env_key)``——Windows（os.name=="nt"）上归一结果以
+``\\\\.\\`` 前缀开头即抛 ValueError（消息含键名与「保留设备名」字样及改法）；
+``state_root``/``data_root``/``mdcg_root``/``aux_root`` 四处 env 覆盖面（含
+paths.json 直值面）改走该辅助。非 Windows 平台 ``\\\\.\\aux`` 是合法目录名
+字面量，**不判定**（§4 在 POSIX 上反断言「不抛」，守住平台闸本身）。
+承接面：``mcp_server.main()`` 启动早期对 root/aux 各探一次，ValueError →
+stderr 告警 + return 2（对照 `_md_cg_` 前缀守卫先例「启动即拒绝，不带病运行」）。
+
+隔离纪律：四个覆盖键（MDCG_STATE_ROOT/MDCG_DATA_ROOT/MDCG_ROOT/MDCG_AUX_ROOT）
+与 DSH_HOME 以 os.environ 副本注入、finally 逐键还原；探针路径全部是
+tempfile.mkdtemp 下**不存在**的纯字符串（或正常临时子目录），不创建任何含
+保留名的真实目录，不触真实令牌库与真实状态根。env 直设即命中各函数第一分支，
+paths.json 回落面零参与。
+
+自检 floor：断言总数低于 FLOOR 视为失败——防「探针面失效 → 假绿」。
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except AttributeError:
+    pass
+
+from .datapath import (ENV_AUX_ROOT, ENV_DATA_ROOT, ENV_MDCG_ROOT,
+                       ENV_STATE_ROOT, aux_root, data_root, mdcg_root,
+                       state_root)
+
+FLOOR = 8            # 断言总数下限（防假绿）
+PASS, FAIL = 0, 0
+
+#: 守卫注入/还原面（含 DSH_HOME——state_root 的第二档，一并与真实环境隔离）
+_GUARD_KEYS = (ENV_STATE_ROOT, ENV_DATA_ROOT, ENV_MDCG_ROOT, ENV_AUX_ROOT,
+               "DSH_HOME")
+
+
+def check(name, cond, detail=""):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  [ok] {name}")
+    else:
+        FAIL += 1
+        print(f"  [FAIL] {name}  {detail}")
+
+
+def _probe_reject(fn, key, tail, tmp):
+    """设 env=<tmp>/<tail>（不存在的纯字符串路径）→ 返回 (抛出异常, 异常消息)。
+
+    红态（修复前）fn() 不抛而返回 \\\\.\\<tail> 形态——由调用方断言兜住。
+    """
+    os.environ[key] = os.path.join(tmp, tail)
+    try:
+        fn()
+    except ValueError as ve:
+        return True, str(ve)
+    return False, ""
+
+
+def _func_window(src: str, func_name: str) -> str:
+    """取 src 中 ``def <func_name>`` 起到下一个顶层 ``def ``/``class`` 的源窗口。"""
+    start = src.find(f"def {func_name}(")
+    if start < 0:
+        return ""
+    nxt = src.find("\ndef ", start + 1)
+    nxt_cls = src.find("\nclass ", start + 1)
+    ends = [e for e in (nxt, nxt_cls) if e > 0]
+    return src[start:min(ends)] if ends else src[start:]
+
+
+def main():
+    saved = {k: os.environ.get(k) for k in _GUARD_KEYS}
+    tmp = tempfile.mkdtemp(prefix="mdcg_devname_")
+    try:
+        for k in _GUARD_KEYS:
+            os.environ.pop(k, None)
+
+        # ---- 1. 实弹红转绿核心：MDCG_AUX_ROOT 末段 aux → aux_root() 必须拒绝 ----
+        print("[1] 实弹核心：MDCG_AUX_ROOT=<临时目录>\\aux（不存在，纯字符串）")
+        raised, msg = _probe_reject(aux_root, ENV_AUX_ROOT, "aux", tmp)
+        if os.name == "nt":
+            check("1a aux_root() 抛 ValueError（红态：静默返回 \\\\.\\aux 不抛）",
+                  raised, f"msg={msg[:160]!r}")
+            check("1b 消息含覆盖键名 MDCG_AUX_ROOT（定位误配来源）",
+                  ENV_AUX_ROOT in msg, f"msg={msg[:160]!r}")
+            check("1c 消息含「保留设备名」字样（说清劫持机理）",
+                  "保留设备名" in msg, f"msg={msg[:160]!r}")
+        else:
+            # 与 [4] 同口径：平台门在 `_abs_host_path`（`os.name == "nt"`），POSIX 上
+            # `\\.\aux` 是合法目录名字面量，不判定 → 必须不抛且原样返回。
+            check("1a 非 Windows 不判定（\\\\.\\aux 是合法目录名字面量，原样返回不抛）",
+                  not raised, f"msg={msg[:160]!r}")
+            check("1b 非 Windows 不判定：不产生保留设备名拒因（消息为空）",
+                  msg == "", f"msg={msg[:160]!r}")
+            check("1c 非 Windows 不判定：aux_root() 原样返回该路径（未被吞成设备路径）",
+                  aux_root() == os.path.abspath(os.path.join(tmp, "aux")),
+                  f"aux_root()={aux_root()!r}")
+
+        # ---- 2. 同族四面：state/data/mdcg 各 env 面同样拒绝 ----
+        print("[2] 同族 env 面（MDCG_STATE_ROOT/MDCG_DATA_ROOT/MDCG_ROOT）")
+        for key, fn, tail in ((ENV_STATE_ROOT, state_root, "con"),
+                              (ENV_DATA_ROOT, data_root, "nul"),
+                              (ENV_MDCG_ROOT, mdcg_root, "aux")):
+            raised, msg = _probe_reject(fn, key, tail, tmp)
+            if os.name == "nt":
+                check(f"2·{key}: {fn.__name__}() 抛 ValueError 且消息含键名"
+                      "（env 直设命中第一分支，paths.json 零参与）",
+                      raised and key in msg,
+                      f"raised={raised} msg={msg[:160]!r}")
+            else:
+                # 与 [4] 同口径：平台门在 `_abs_host_path`，POSIX 不判定保留设备名。
+                check(f"2·{key}: 非 Windows 不判定（末段 {tail} 是合法目录名，"
+                      f"{fn.__name__}() 原样返回不抛）",
+                      not raised
+                      and fn() == os.path.abspath(os.path.join(tmp, tail)),
+                      f"raised={raised} msg={msg[:160]!r} got={fn()!r}")
+
+        # ---- 3. 正常路径不误伤：无保留名末段 → abspath 原样返回 ----
+        print("[3] 正常路径不误伤（临时子目录，末段无保留名）")
+        normals = {}
+        for name in ("state", "data", "cgroot", "auxroot"):
+            p = os.path.join(tmp, name)
+            os.makedirs(p, exist_ok=True)
+            normals[name] = p
+        os.environ[ENV_STATE_ROOT] = normals["state"]
+        os.environ[ENV_DATA_ROOT] = normals["data"]
+        os.environ[ENV_MDCG_ROOT] = normals["cgroot"]
+        os.environ[ENV_AUX_ROOT] = normals["auxroot"]
+        check("3a 四面正常值全部原样返回（不抛、不变形）",
+              state_root() == os.path.abspath(normals["state"])
+              and data_root() == os.path.abspath(normals["data"])
+              and mdcg_root() == os.path.abspath(normals["cgroot"])
+              and aux_root() == os.path.abspath(normals["auxroot"]),
+              f"state={state_root()!r} data={data_root()!r} "
+              f"mdcg={mdcg_root()!r} aux={aux_root()!r}")
+
+        # ---- 4. 保留名清单抽查（aux_root 面）：Windows 全抛；POSIX 反断言不抛 ----
+        print("[4] 保留名清单抽查（aux/con/nul/com1/lpt1）")
+        for tail in ("aux", "con", "nul", "com1", "lpt1"):
+            raised, msg = _probe_reject(aux_root, ENV_AUX_ROOT, tail, tmp)
+            if os.name == "nt":
+                check(f"4·{tail}: aux_root() 抛 ValueError（GetFullPathNameW "
+                      "劫持被拦）", raised, f"msg={msg[:160]!r}")
+            else:
+                check(f"4·{tail}: 非 Windows 不判定（\\\\.\\{tail} 是合法目录名"
+                      "字面量，原样返回不抛）",
+                      not raised, f"msg={msg[:160]!r}")
+
+        # ---- 5. 源断言：辅助函数在、四处 env 面改走它、未改面逐字保留 ----
+        print("[5] 源断言（datapath.py 四处 env 面 + mcp_server 承接）")
+        here = os.path.dirname(os.path.abspath(__file__))
+        with open(os.path.join(here, "datapath.py"), encoding="utf-8") as fh:
+            src = fh.read()
+        check("5a datapath.py 定义 _abs_host_path",
+              "def _abs_host_path(" in src)
+        for fname in ("state_root", "data_root", "mdcg_root", "aux_root"):
+            check(f"5·{fname}: 函数体改走 _abs_host_path（env 覆盖面全覆盖）",
+                  "_abs_host_path(" in _func_window(src, fname))
+        check("5e plugin_root 基于 __file__ 的 abspath 未改（非攻击/误配面，逐字保留）",
+              "os.path.abspath(__file__)" in _func_window(src, "plugin_root"))
+        with open(os.path.join(here, "mcp_server.py"), encoding="utf-8") as fh:
+            msrc = fh.read()
+        mwin = msrc[msrc.find("def main"):msrc.find("def main") + 2000]
+        check("5f mcp_server.main() 启动早期探 root/aux 且 ValueError → return 2",
+              "_probe_root" in mwin and "_probe_aux" in mwin
+              and "except ValueError" in mwin and "return 2" in mwin,
+              "main() 首段缺承接受理")
+
+        # ---- 6. 守卫自检 floor ----
+        print("[6] 守卫自检")
+        check(f"6a 断言总数 ≥ {FLOOR}（防探针面失效假绿）",
+              PASS + FAIL >= FLOOR, f"total={PASS + FAIL}")
+    finally:
+        for k, v in saved.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print(f"\n=== datapath device-name tests: {PASS} passed, {FAIL} failed ===")
+    sys.exit(1 if FAIL else 0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/test_datapath_root.py

@@ -1,199 +1,199 @@
-# -*- coding: utf-8 -*-
-"""test_datapath_root.py · 数据根解析与「迁出插件包」回归（issue #18 相邻问题）
-
-被测不变量（任一被破坏即红）：
-  ① state_root() 三档：MDCG_STATE_ROOT > $DSH_HOME/.dsh-memory > ~/.dsh/.dsh-memory
-  ② paths_file()：用户级优先；用户级不存在时**兼容读**旧包内位置；都不存在返回新位置
-  ③ default_data_root() 必在**插件包目录之外**——这是「pnpm 更新不丢数据」的充要条件
-  ④ migrate_legacy_data()：默认根生效时把旧包内数据复制到用户级根（只复制不删除、
-     不覆盖已有、不搬 paths.json、幂等）；数据根为**显式配置**时不动作
-  ⑤ set_user_root() 永远写用户级新位置，且把旧件既有取值带入（不丢用户设置）
-
-隔离纪律：插件根以 monkeypatch 换成临时假包（**不动本机 <仓>/data 与真实状态根**），
-状态根/数据根一律经 MDCG_STATE_ROOT / MDCG_DATA_ROOT 指向临时目录。
-"""
-from __future__ import annotations
-
-import json
-import os
-import shutil
-import tempfile
-import unittest
-
-from . import datapath as dp
-
-_ENV_KEYS = ("MDCG_STATE_ROOT", "MDCG_DATA_ROOT", "MDCG_ROOT", "DSH_HOME")
-
-
-def _read(path: str) -> str:
-    with open(path, encoding="utf-8") as fh:
-        return fh.read()
-
-
-def _inside(parent: str, child: str) -> bool:
-    p = os.path.normcase(os.path.abspath(parent))
-    c = os.path.normcase(os.path.abspath(child))
-    return c == p or c.startswith(p + os.sep)
-
-
-class DatapathRootTest(unittest.TestCase):
-    # 生效条件：每个用例前建临时假包与临时状态根、清空四个相关环境变量并把 plugin_root monkeypatch 到假包；异常即用例失败，不污染真实仓与真实状态根。
-    def setUp(self):
-        self.tmp = tempfile.mkdtemp(prefix="datapath-root-")
-        self.pkg = os.path.join(self.tmp, "pkg")        # 假插件包
-        self.state = os.path.join(self.tmp, "state")    # 假用户级状态根
-        os.makedirs(os.path.join(self.pkg, "md_cg"), exist_ok=True)
-        self._orig_plugin_root = dp.plugin_root
-        dp.plugin_root = lambda: self.pkg               # 隔离：不碰真实仓
-        self._env = {k: os.environ.get(k) for k in _ENV_KEYS}
-        for key in _ENV_KEYS:
-            os.environ.pop(key, None)
-        os.environ["MDCG_STATE_ROOT"] = self.state
-
-    # 生效条件：每个用例后恢复 plugin_root 与四个环境变量原值并删临时目录（ignore_errors，不掩盖用例结果）。
-    def tearDown(self):
-        dp.plugin_root = self._orig_plugin_root
-        for key, val in self._env.items():
-            if val is None:
-                os.environ.pop(key, None)
-            else:
-                os.environ[key] = val
-        shutil.rmtree(self.tmp, ignore_errors=True)
-
-    # 生效条件：给定相对 package 内路径拼绝对路径（写入旧位置假数据用）。
-    def _pkg_path(self, *parts: str) -> str:
-        return os.path.join(self.pkg, *parts)
-
-    # 生效条件：给定相对数据根路径拼用户级默认数据根下的绝对路径（断言新落点用）。
-    def _new_root_path(self, *parts: str) -> str:
-        return os.path.join(dp.default_data_root(), *parts)
-
-    # 生效条件：在旧包内位置造假数据（mdcg/mem.md、ledger.jsonl、paths.json），返回该目录。
-    def _seed_legacy(self, mem: str = "MEM-1") -> str:
-        legacy = dp.legacy_data_root()
-        os.makedirs(os.path.join(legacy, "mdcg"), exist_ok=True)
-        with open(os.path.join(legacy, "mdcg", "mem.md"), "w",
-                  encoding="utf-8") as fh:
-            fh.write(mem)
-        with open(os.path.join(legacy, "ledger.jsonl"), "w",
-                  encoding="utf-8") as fh:
-            fh.write('{"op":"write"}\n')
-        with open(dp.legacy_paths_file(), "w", encoding="utf-8") as fh:
-            json.dump({}, fh)
-        return legacy
-
-    # ① state_root 优先级三档
-    def test_state_root_priority(self):
-        self.assertEqual(dp.state_root(), os.path.abspath(self.state))
-        os.environ.pop("MDCG_STATE_ROOT")
-        dsh = os.path.join(self.tmp, "dsh-home")
-        os.environ["DSH_HOME"] = dsh
-        self.assertEqual(dp.state_root(), os.path.join(os.path.abspath(dsh), ".dsh-memory"))
-        os.environ.pop("DSH_HOME")
-        self.assertEqual(dp.state_root(),
-                         os.path.join(os.path.expanduser("~"), ".dsh", ".dsh-memory"))
-
-    # ③ 默认数据根必须在插件包目录之外（本 issue 的核心不变量）
-    def test_default_data_root_outside_package(self):
-        root = dp.default_data_root()
-        self.assertEqual(root, os.path.join(os.path.abspath(self.state), "data"))
-        self.assertFalse(_inside(self.pkg, root),
-                         f"默认数据根不得落在插件包内（包={self.pkg} 根本={root}）")
-
-    # ② paths_file 用户级优先 + 旧件兼容读
-    def test_paths_file_priority(self):
-        self.assertEqual(dp.paths_file(), os.path.join(os.path.abspath(self.state), "paths.json"))
-        self.assertEqual(dp.paths_file_source(), "user")
-        self._seed_legacy()
-        self.assertEqual(dp.paths_file(), dp.legacy_paths_file())    # 新件不存在 → 兼容读旧件
-        self.assertEqual(dp.paths_file_source(), "legacy")
-        os.makedirs(self.state, exist_ok=True)
-        with open(os.path.join(self.state, "paths.json"), "w", encoding="utf-8") as fh:
-            json.dump({}, fh)
-        self.assertEqual(dp.paths_file(), os.path.join(os.path.abspath(self.state), "paths.json"))
-        self.assertEqual(dp.paths_file_source(), "user")
-
-    # ④ 默认根生效：复制（不删除/不搬配置/不覆盖/幂等）
-    def test_migrate_copies_legacy_data(self):
-        legacy = self._seed_legacy()
-        first = dp.migrate_legacy_data()
-        self.assertTrue(first["ran"], first)
-        self.assertGreaterEqual(first["copied"], 1)
-        self.assertEqual(_read(self._new_root_path("mdcg", "mem.md")), "MEM-1")
-        self.assertTrue(os.path.isfile(self._new_root_path("ledger.jsonl")))
-        self.assertFalse(os.path.exists(self._new_root_path("paths.json")),
-                         "paths.json 属配置，不随数据面迁移")
-        self.assertTrue(os.path.isfile(os.path.join(legacy, "mdcg", "mem.md")),
-                        "迁移只复制不删除（旧目录由更新自行移除）")
-        second = dp.migrate_legacy_data()
-        self.assertFalse(second["ran"], second)
-        self.assertIn("已有数据", second["reason"])
-        # 不覆盖：旧件改了内容，新件保持不变
-        with open(os.path.join(legacy, "mdcg", "mem.md"), "w", encoding="utf-8") as fh:
-            fh.write("MEM-2")
-        dp.migrate_legacy_data()
-        self.assertEqual(_read(self._new_root_path("mdcg", "mem.md")), "MEM-1")
-
-    # ④ 数据根为显式配置 → 不动作（不越权搬运用户的真源）
-    def test_migrate_skips_when_root_explicit(self):
-        self._seed_legacy()
-        explicit = os.path.join(self.tmp, "explicit")
-        os.environ["MDCG_DATA_ROOT"] = explicit
-        got = dp.migrate_legacy_data()
-        self.assertFalse(got["ran"], got)
-        self.assertIn("显式配置", got["reason"])
-        self.assertFalse(os.path.exists(os.path.join(explicit, "mdcg")))
-        self.assertFalse(os.path.exists(self._new_root_path("mdcg")),
-                         "显式配置时用户级根不得被写入")
-
-    # ④ 旧位置不存在（多为更新时已随包目录被替换）→ 如实说明，不报成功
-    def test_migrate_reports_missing_legacy(self):
-        got = dp.migrate_legacy_data()
-        self.assertFalse(got["ran"], got)
-        self.assertIn("不存在", got["reason"])
-
-    # ⑤ set_user_root 永远写新位置，并带入旧件既有取值
-    def test_set_user_root_writes_user_level(self):
-        legacy = self._seed_legacy()
-        with open(dp.legacy_paths_file(), "w", encoding="utf-8") as fh:
-            json.dump({"data_root": "D:/old", "extra": "keep"}, fh)
-        written = dp.set_user_root("E:/new", "data_root")
-        self.assertEqual(written, os.path.join(os.path.abspath(self.state), "paths.json"))
-        with open(written, encoding="utf-8") as fh:
-            got = json.load(fh)
-        self.assertEqual(got["data_root"], "E:/new")
-        self.assertEqual(got["extra"], "keep", "旧件既有键须带入，不丢用户设置")
-        self.assertIn("_comment", got)
-        with open(dp.legacy_paths_file(), encoding="utf-8") as fh:
-            self.assertEqual(json.load(fh)["data_root"], "D:/old", "旧件只读，不被改写")
-        self.assertEqual(dp.paths_file_source(), "user")
-        # 可移植断言（2026-09-20 v15-2 修复）：`E:/new` 在 Windows 上是**绝对**路径，
-        # 在 POSIX 上是**相对**路径（`os.path.isabs("E:/new")` 为 False）——datapath
-        # 据此走不同分支（绝对：直接 abspath；相对：拼 `plugin_root()`）。旧断言一律按
-        # 「绝对路径 + 进程 cwd」求值，于是**只在 Windows 成立**，POSIX 上必红
-        # （测试自身不可移植，非实现错）。此处用**与实现同一判据**复算期望值，两分支皆覆盖。
-        base = (os.path.abspath("E:/new") if os.path.isabs("E:/new")
-                else os.path.abspath(os.path.join(dp.plugin_root(), "E:/new")))
-        self.assertEqual(dp.mdcg_root(), os.path.join(base, "mdcg"))
-        # 与平台无关的同一判据（POSIX 与 Windows 皆成立，不依赖 isabs 分支走向）：
-        # 本次只写了 data_root 键（未写 root 键），故认知图根必落在 data_root/mdcg 下。
-        self.assertEqual(dp.mdcg_root(), os.path.join(dp.data_root(), "mdcg"),
-                         "mdcg_root 必须落在 data_root()/mdcg（跨平台同一断言）")
-        self.assertTrue(os.path.isdir(legacy))          # 迁移职责不在 set_user_root
-
-    # describe(): 留痕字段齐备（启动日志与心跳消费）
-    def test_describe_exposes_sources(self):
-        self._seed_legacy()
-        got = dp.describe()
-        for key in ("plugin_root", "state_root", "data_root", "mdcg_root",
-                    "default_data_root", "is_default", "source", "paths_file",
-                    "paths_file_source", "legacy_data_root", "legacy_data_exists",
-                    "data_root_exists", "mdcg_root_exists"):
-            self.assertIn(key, got, f"describe() 缺字段 {key}")
-        self.assertEqual(got["paths_file_source"], "legacy")
-        self.assertTrue(got["legacy_data_exists"])
-        self.assertTrue(got["is_default"])
-
-
-if __name__ == "__main__":
-    unittest.main(verbosity=2)
+# -*- coding: utf-8 -*-
+"""test_datapath_root.py · 数据根解析与「迁出插件包」回归（issue #18 相邻问题）
+
+被测不变量（任一被破坏即红）：
+  ① state_root() 三档：MDCG_STATE_ROOT > $DSH_HOME/.dsh-memory > ~/.dsh/.dsh-memory
+  ② paths_file()：用户级优先；用户级不存在时**兼容读**旧包内位置；都不存在返回新位置
+  ③ default_data_root() 必在**插件包目录之外**——这是「pnpm 更新不丢数据」的充要条件
+  ④ migrate_legacy_data()：默认根生效时把旧包内数据复制到用户级根（只复制不删除、
+     不覆盖已有、不搬 paths.json、幂等）；数据根为**显式配置**时不动作
+  ⑤ set_user_root() 永远写用户级新位置，且把旧件既有取值带入（不丢用户设置）
+
+隔离纪律：插件根以 monkeypatch 换成临时假包（**不动本机 <仓>/data 与真实状态根**），
+状态根/数据根一律经 MDCG_STATE_ROOT / MDCG_DATA_ROOT 指向临时目录。
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import unittest
+
+from . import datapath as dp
+
+_ENV_KEYS = ("MDCG_STATE_ROOT", "MDCG_DATA_ROOT", "MDCG_ROOT", "DSH_HOME")
+
+
+def _read(path: str) -> str:
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _inside(parent: str, child: str) -> bool:
+    p = os.path.normcase(os.path.abspath(parent))
+    c = os.path.normcase(os.path.abspath(child))
+    return c == p or c.startswith(p + os.sep)
+
+
+class DatapathRootTest(unittest.TestCase):
+    # 生效条件：每个用例前建临时假包与临时状态根、清空四个相关环境变量并把 plugin_root monkeypatch 到假包；异常即用例失败，不污染真实仓与真实状态根。
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="datapath-root-")
+        self.pkg = os.path.join(self.tmp, "pkg")        # 假插件包
+        self.state = os.path.join(self.tmp, "state")    # 假用户级状态根
+        os.makedirs(os.path.join(self.pkg, "md_cg"), exist_ok=True)
+        self._orig_plugin_root = dp.plugin_root
+        dp.plugin_root = lambda: self.pkg               # 隔离：不碰真实仓
+        self._env = {k: os.environ.get(k) for k in _ENV_KEYS}
+        for key in _ENV_KEYS:
+            os.environ.pop(key, None)
+        os.environ["MDCG_STATE_ROOT"] = self.state
+
+    # 生效条件：每个用例后恢复 plugin_root 与四个环境变量原值并删临时目录（ignore_errors，不掩盖用例结果）。
+    def tearDown(self):
+        dp.plugin_root = self._orig_plugin_root
+        for key, val in self._env.items():
+            if val is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = val
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    # 生效条件：给定相对 package 内路径拼绝对路径（写入旧位置假数据用）。
+    def _pkg_path(self, *parts: str) -> str:
+        return os.path.join(self.pkg, *parts)
+
+    # 生效条件：给定相对数据根路径拼用户级默认数据根下的绝对路径（断言新落点用）。
+    def _new_root_path(self, *parts: str) -> str:
+        return os.path.join(dp.default_data_root(), *parts)
+
+    # 生效条件：在旧包内位置造假数据（mdcg/mem.md、ledger.jsonl、paths.json），返回该目录。
+    def _seed_legacy(self, mem: str = "MEM-1") -> str:
+        legacy = dp.legacy_data_root()
+        os.makedirs(os.path.join(legacy, "mdcg"), exist_ok=True)
+        with open(os.path.join(legacy, "mdcg", "mem.md"), "w",
+                  encoding="utf-8") as fh:
+            fh.write(mem)
+        with open(os.path.join(legacy, "ledger.jsonl"), "w",
+                  encoding="utf-8") as fh:
+            fh.write('{"op":"write"}\n')
+        with open(dp.legacy_paths_file(), "w", encoding="utf-8") as fh:
+            json.dump({}, fh)
+        return legacy
+
+    # ① state_root 优先级三档
+    def test_state_root_priority(self):
+        self.assertEqual(dp.state_root(), os.path.abspath(self.state))
+        os.environ.pop("MDCG_STATE_ROOT")
+        dsh = os.path.join(self.tmp, "dsh-home")
+        os.environ["DSH_HOME"] = dsh
+        self.assertEqual(dp.state_root(), os.path.join(os.path.abspath(dsh), ".dsh-memory"))
+        os.environ.pop("DSH_HOME")
+        self.assertEqual(dp.state_root(),
+                         os.path.join(os.path.expanduser("~"), ".dsh", ".dsh-memory"))
+
+    # ③ 默认数据根必须在插件包目录之外（本 issue 的核心不变量）
+    def test_default_data_root_outside_package(self):
+        root = dp.default_data_root()
+        self.assertEqual(root, os.path.join(os.path.abspath(self.state), "data"))
+        self.assertFalse(_inside(self.pkg, root),
+                         f"默认数据根不得落在插件包内（包={self.pkg} 根本={root}）")
+
+    # ② paths_file 用户级优先 + 旧件兼容读
+    def test_paths_file_priority(self):
+        self.assertEqual(dp.paths_file(), os.path.join(os.path.abspath(self.state), "paths.json"))
+        self.assertEqual(dp.paths_file_source(), "user")
+        self._seed_legacy()
+        self.assertEqual(dp.paths_file(), dp.legacy_paths_file())    # 新件不存在 → 兼容读旧件
+        self.assertEqual(dp.paths_file_source(), "legacy")
+        os.makedirs(self.state, exist_ok=True)
+        with open(os.path.join(self.state, "paths.json"), "w", encoding="utf-8") as fh:
+            json.dump({}, fh)
+        self.assertEqual(dp.paths_file(), os.path.join(os.path.abspath(self.state), "paths.json"))
+        self.assertEqual(dp.paths_file_source(), "user")
+
+    # ④ 默认根生效：复制（不删除/不搬配置/不覆盖/幂等）
+    def test_migrate_copies_legacy_data(self):
+        legacy = self._seed_legacy()
+        first = dp.migrate_legacy_data()
+        self.assertTrue(first["ran"], first)
+        self.assertGreaterEqual(first["copied"], 1)
+        self.assertEqual(_read(self._new_root_path("mdcg", "mem.md")), "MEM-1")
+        self.assertTrue(os.path.isfile(self._new_root_path("ledger.jsonl")))
+        self.assertFalse(os.path.exists(self._new_root_path("paths.json")),
+                         "paths.json 属配置，不随数据面迁移")
+        self.assertTrue(os.path.isfile(os.path.join(legacy, "mdcg", "mem.md")),
+                        "迁移只复制不删除（旧目录由更新自行移除）")
+        second = dp.migrate_legacy_data()
+        self.assertFalse(second["ran"], second)
+        self.assertIn("已有数据", second["reason"])
+        # 不覆盖：旧件改了内容，新件保持不变
+        with open(os.path.join(legacy, "mdcg", "mem.md"), "w", encoding="utf-8") as fh:
+            fh.write("MEM-2")
+        dp.migrate_legacy_data()
+        self.assertEqual(_read(self._new_root_path("mdcg", "mem.md")), "MEM-1")
+
+    # ④ 数据根为显式配置 → 不动作（不越权搬运用户的真源）
+    def test_migrate_skips_when_root_explicit(self):
+        self._seed_legacy()
+        explicit = os.path.join(self.tmp, "explicit")
+        os.environ["MDCG_DATA_ROOT"] = explicit
+        got = dp.migrate_legacy_data()
+        self.assertFalse(got["ran"], got)
+        self.assertIn("显式配置", got["reason"])
+        self.assertFalse(os.path.exists(os.path.join(explicit, "mdcg")))
+        self.assertFalse(os.path.exists(self._new_root_path("mdcg")),
+                         "显式配置时用户级根不得被写入")
+
+    # ④ 旧位置不存在（多为更新时已随包目录被替换）→ 如实说明，不报成功
+    def test_migrate_reports_missing_legacy(self):
+        got = dp.migrate_legacy_data()
+        self.assertFalse(got["ran"], got)
+        self.assertIn("不存在", got["reason"])
+
+    # ⑤ set_user_root 永远写新位置，并带入旧件既有取值
+    def test_set_user_root_writes_user_level(self):
+        legacy = self._seed_legacy()
+        with open(dp.legacy_paths_file(), "w", encoding="utf-8") as fh:
+            json.dump({"data_root": "D:/old", "extra": "keep"}, fh)
+        written = dp.set_user_root("E:/new", "data_root")
+        self.assertEqual(written, os.path.join(os.path.abspath(self.state), "paths.json"))
+        with open(written, encoding="utf-8") as fh:
+            got = json.load(fh)
+        self.assertEqual(got["data_root"], "E:/new")
+        self.assertEqual(got["extra"], "keep", "旧件既有键须带入，不丢用户设置")
+        self.assertIn("_comment", got)
+        with open(dp.legacy_paths_file(), encoding="utf-8") as fh:
+            self.assertEqual(json.load(fh)["data_root"], "D:/old", "旧件只读，不被改写")
+        self.assertEqual(dp.paths_file_source(), "user")
+        # 可移植断言（2026-09-20 v15-2 修复）：`E:/new` 在 Windows 上是**绝对**路径，
+        # 在 POSIX 上是**相对**路径（`os.path.isabs("E:/new")` 为 False）——datapath
+        # 据此走不同分支（绝对：直接 abspath；相对：拼 `plugin_root()`）。旧断言一律按
+        # 「绝对路径 + 进程 cwd」求值，于是**只在 Windows 成立**，POSIX 上必红
+        # （测试自身不可移植，非实现错）。此处用**与实现同一判据**复算期望值，两分支皆覆盖。
+        base = (os.path.abspath("E:/new") if os.path.isabs("E:/new")
+                else os.path.abspath(os.path.join(dp.plugin_root(), "E:/new")))
+        self.assertEqual(dp.mdcg_root(), os.path.join(base, "mdcg"))
+        # 与平台无关的同一判据（POSIX 与 Windows 皆成立，不依赖 isabs 分支走向）：
+        # 本次只写了 data_root 键（未写 root 键），故认知图根必落在 data_root/mdcg 下。
+        self.assertEqual(dp.mdcg_root(), os.path.join(dp.data_root(), "mdcg"),
+                         "mdcg_root 必须落在 data_root()/mdcg（跨平台同一断言）")
+        self.assertTrue(os.path.isdir(legacy))          # 迁移职责不在 set_user_root
+
+    # describe(): 留痕字段齐备（启动日志与心跳消费）
+    def test_describe_exposes_sources(self):
+        self._seed_legacy()
+        got = dp.describe()
+        for key in ("plugin_root", "state_root", "data_root", "mdcg_root",
+                    "default_data_root", "is_default", "source", "paths_file",
+                    "paths_file_source", "legacy_data_root", "legacy_data_exists",
+                    "data_root_exists", "mdcg_root_exists"):
+            self.assertIn(key, got, f"describe() 缺字段 {key}")
+        self.assertEqual(got["paths_file_source"], "legacy")
+        self.assertTrue(got["legacy_data_exists"])
+        self.assertTrue(got["is_default"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)