@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/d_meta.py

@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+"""md_cg · D_meta 投影：边界压力向量（三代理，各自 [0,1]，**不合成单值**）
+
+理论约束（智能论3.4 §2.7.0 DEV-002 / DEV-002a；工程方案
+`docs/mdcg/D_meta_工程化方案_v0.2.md`）：
+
+- DEV-002：`D_task` = 图上操作性距离；`D_meta` = 未被建模的现实总量。
+  **两者对象不同、数值不互换**。本模块**不参与** `MdCG._compute_d`——
+  `D_task` 口径零变更（"双 D 落盘"= 并列新增，不是打通）。
+- DEV-002a：可新增 `D_meta` 投影链路，但不能并入 `D_task` 计算公式。
+- 增定律 `d(D_meta)/dt ≥ 0`：本模块只**观测**压力与其趋势，不做"缩小"运算。
+- **不合成单一数值**：任何把三代理加权成一个 `D_meta` 数的企图都违反
+  DEV-002a。上层若需单值，只允许**指定单一代理**（见 `pressure()`）。
+
+诚实边界（随代码同行，不可省略）：
+
+1. 三代理只计「**已进入本系统、但未被消化**」的可观测量——**不是**「世界真实
+   未发生的事件」，后者不可观测。全部数据来自**已落盘留痕与索引**，
+   不重放检索、不读全库正文（热路径约束）。
+2. 本模块是**叶子只读**模块：不 import `mdcg` / `mdcos`（防循环依赖），
+   只依赖 `fsutil` 原语与注入的 `cg` 对象（duck-typing）；`metacognition`
+   惰性导入（调用点内），理由同 `self_state._prediction_face`。
+3. 只读：本模块**没有任何写路径**。
+
+开关（三面隔离之一，方案 §2.1/§3）：
+
+- `MDCG_D_META`：D_meta 计算总闸，**默认开启**；置 `0/false/off/no`
+  显式回退（关闭计算 → 上层加分退化为 0，回到旧排序）。
+
+三个代理的口径（各自 [0,1]，可核验、可复算）：
+
+| 代理 | 口径 | 数据源（已落盘） |
+|---|---|---|
+| `events_pressure` | 窗口内新增未消化事件密度 = (近期事件条数 + 探索留痕条数) / (2×window) | `_recent.jsonl` + `_explore.jsonl` 尾部窗口 |
+| `unmodeled_growth` | 0.5×存量饱和率 + 0.5×反思窗口未消化率（BLINDSPOT+DEFER 占比） | 索引 `rejected`/`unresolved` 层计数 + `_reflection.jsonl` 窗口 |
+| `boundary_violation_rate` | 反思窗口内 (REJECT+BLINDSPOT) / 全部资格态 | `_reflection.jsonl` 窗口 `states` 分布 |
+
+**query-relative 口径不在本模块**：`_neg_coverage` 之类的命中率需要
+query+results 现场，留在 `MdCG.reflect`（彼处两者都有）。本模块口径
+**库侧 query 无关**，故可在 `autonomy.proposals` 里"每轮一次、循环内复用"。
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from .fsutil import count_jsonl
+
+# ---------------------------------------------------------------- 常量
+
+_ENV_FLAG = "MDCG_D_META"
+_FALSY = ("0", "false", "off", "no")
+DEFAULT_WINDOW = 200
+
+#: `rejected`/`unresolved` 存量的归一化饱和基准（达到即视为压力 1.0）。
+STOCK_FULL = 100
+
+EXPLORE_LOG = "_explore.jsonl"
+RECENT_LOG = "_recent.jsonl"
+REFLECTION_LOG = "_reflection.jsonl"
+
+#: 未建模层（负记忆两类：失败/否决 + 未解问题）。
+UNMODELED_LAYERS = ("rejected", "unresolved")
+
+#: 资格四态（`judge_qualification` 的 states 取值域）。
+JUDGE_STATES = ("ACCEPT", "REJECT", "DEFER", "BLINDSPOT")
+
+PROXY_KEYS = ("events_pressure", "unmodeled_growth", "boundary_violation_rate")
+
+_TAIL_BLOCK = 1 << 16          # 尾部反向扫描块（64KiB）
+_CACHE_MAX = 64                # 进程内缓存条目上限（超出即清空，无后台线程）
+_CACHE = {}
+
+
+# 生效条件：读取环境变量 MDCG_D_META（大小写不敏感、去首尾空白），其值属于 _FALSY 时返回 False，其余（含未设置）返回 True；
+def _enabled() -> bool:
+    """D_meta 计算总闸（默认开启）。"""
+    return str(os.environ.get(_ENV_FLAG, "")).strip().lower() not in _FALSY
+
+
+# 生效条件：path 不存在或不是文件、或 window<=0 时返回 []；否则从文件末尾按 _TAIL_BLOCK 分块反向读取，直到累计换行数超过 window 或到达文件头，再按行 json.loads 解析尾部 window 条非空记录（解析失败的行跳过、块首半截行跳过）；
+def tail_jsonl(path: str, window: int) -> list:
+    """只读 JSONL **尾部最多 window 条**（反向分块，避免全文件 IO）。
+
+    与 `fsutil.read_jsonl` 的区别：不流式扫全文件，读盘量 ≈ O(window)。
+    日志文件可能末尾无换行（写者被杀死），此时最后一行会被解析失败丢弃——
+    与 `read_jsonl` 同语义（不猜内容）。
+    """
+    window = int(window)
+    if window <= 0:
+        return []
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return []
+    if size <= 0:
+        return []
+    data = b""
+    pos = size
+    try:
+        with open(path, "rb") as f:
+            while pos > 0 and data.count(b"\n") <= window:
+                step = min(_TAIL_BLOCK, pos)
+                pos -= step
+                f.seek(pos)
+                data = f.read(step) + data
+    except OSError:
+        return []
+    out = []
+    for raw in data.split(b"\n")[-(window + 1):]:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            out.append(json.loads(raw.decode("utf-8", "replace")))
+        except ValueError:
+            continue
+    return out[-window:]
+
+
+# 生效条件：cg.index 缺失或不是 dict 时返回 0；否则统计其 "nodes" 中各条目 layer 属于 UNMODELED_LAYERS 的条数（entry 非 dict 或 layer 缺失的条目不计）；
+def _layer_stock(cg) -> int:
+    """未建模存量：索引中 rejected / unresolved 两层的条目计数（零正文 IO）。"""
+    idx = getattr(cg, "index", None)
+    nodes = (idx or {}).get("nodes") if isinstance(idx, dict) else None
+    if not nodes:
+        return 0
+    n = 0
+    for e in nodes.values():
+        if isinstance(e, dict) and e.get("layer") in UNMODELED_LAYERS:
+            n += 1
+    return n
+
+
+# 生效条件：cg 的 reflection_log 属性缺失或为假值时回落 os.path.join(cg.root, REFLECTION_LOG)；该文件不存在时返回计数 0；
+def _reflection_count(cg) -> int:
+    path = getattr(cg, "reflection_log", "") or os.path.join(
+        str(getattr(cg, "root", "") or ""), REFLECTION_LOG)
+    try:
+        return int(count_jsonl(path))
+    except OSError:
+        return 0
+
+
+# 生效条件：惰性导入 metacognition 并取窗口内资格态分布；metacognition.trace 返回 ok 为假（无反思留痕）或抛异常时返回 {"total": 0, "states": {}}；
+def _state_dist(cg, window: int) -> dict:
+    """反思窗口内的资格态分布（复用 metacognition.trace，不重算）。"""
+    try:
+        from . import metacognition
+        tr = metacognition.trace(cg, window=int(window))
+    except Exception:                                      # noqa: BLE001
+        return {"total": 0, "states": {}}
+    if not tr.get("ok"):
+        return {"total": 0, "states": {}}
+    states = {k: int(v) for k, v in (tr.get("states") or {}).items()}
+    return {"total": sum(states.values()), "states": states}
+
+
+# 生效条件：给定 cg 与 window，返回窗口内新增未消化事件的密度代理（[0,1]），= min(1.0, (recent 尾部条数 + explore 尾部条数) / (2*window))；
+def events_pressure(cg, window: int = DEFAULT_WINDOW) -> float:
+    """代理一：未被建模的现实总量 → 窗口内新增未消化事件密度。"""
+    window = max(1, int(window or DEFAULT_WINDOW))
+    recent_path = (getattr(cg, "recent_log", "") or
+                   os.path.join(str(getattr(cg, "root", "") or ""), RECENT_LOG))
+    explore_path = os.path.join(str(getattr(cg, "root", "") or ""), EXPLORE_LOG)
+    n = len(tail_jsonl(recent_path, window)) + len(tail_jsonl(explore_path,
+                                                              window))
+    return round(min(1.0, n / float(2 * window)), 4)
+
+
+# 生效条件：给定存量 stock 与资格态分布 dist，返回未建模信号增长的归一化代理（[0,1]），= min(1.0, 0.5*min(1.0, stock/STOCK_FULL) + 0.5*((BLINDSPOT+DEFER)/max(1,total)))；
+def unmodeled_growth(stock: int, dist: dict) -> float:
+    """代理二：未建模信号持续增长 → 存量饱和率 + 反思窗口未消化率 的均值。"""
+    stock_rate = min(1.0, max(0, int(stock)) / float(STOCK_FULL))
+    states = (dist or {}).get("states") or {}
+    total = int((dist or {}).get("total") or 0)
+    bad = 0
+    for k in ("BLINDSPOT", "DEFER"):
+        try:
+            bad += int(states.get(k) or 0)
+        except (TypeError, ValueError):
+            continue
+    return round(min(1.0, 0.5 * stock_rate + 0.5 * bad / float(max(1, total))), 4)
+
+
+# 生效条件：给定资格态分布 dist，返回边界违反速率代理（[0,1]），= (REJECT+BLINDSPOT)/max(1,total)（无分布即 0.0）；
+def boundary_violation_rate(dist: dict) -> float:
+    """代理三：边界违反速率 → 反思窗口内 REJECT/BLINDSPOT 占比。"""
+    states = (dist or {}).get("states") or {}
+    total = int((dist or {}).get("total") or 0)
+    bad = 0
+    for k in ("REJECT", "BLINDSPOT"):
+        try:
+            bad += int(states.get(k) or 0)
+        except (TypeError, ValueError):
+            continue
+    return round(bad / float(max(1, total)), 4)
+
+
+# 生效条件：cg 必需；MDCG_D_META 属于 _FALSY 时三代理恒 0.0、enabled=False 且 note 声明已回退；否则按 (root, 反思条数, 存量, recent 条数, explore 条数, window) 查进程内缓存，未命中则计算三代理并回填（缓存超 _CACHE_MAX 条即清空），返回含四键（三代理 + enabled/window/note）；query/results 仅透传留痕于 note（本轮口径为库侧 query 无关，不计入数值）；
+def compute(cg, query=None, results=None, window: int = DEFAULT_WINDOW,
+            now=None) -> dict:
+    """边界压力向量（三代理各自 [0,1]，**不合成单一 D_meta 数值**）。
+
+    返回：`{"events_pressure", "unmodeled_growth", "boundary_violation_rate",
+    "enabled", "window", "note"}`。
+
+    - `enabled=False`（`MDCG_D_META` 显式关闭）时三值为 0.0 且 `note` 声明已回退。
+    - `query` / `results` 为**接口对称性**保留：query-relative 的 `_neg_coverage`
+      命中留 `reflect`（彼处有现场）；本模块口径库侧 query 无关，
+      故可在 `proposals` 每轮一次、循环内复用。
+    - 纯读 + 进程内缓存（key 含两日志条数），无写路径、无后台线程、无网络。
+    """
+    window = max(1, int(window or DEFAULT_WINDOW))
+    if not _enabled():
+        return {"events_pressure": 0.0, "unmodeled_growth": 0.0,
+                "boundary_violation_rate": 0.0, "enabled": False,
+                "window": window,
+                "note": ("MDCG_D_META 已显式关闭：D_meta 计算回退，三代理恒 0.0"
+                         "（上层加分退化 → 旧排序）")}
+    root = str(getattr(cg, "root", "") or "")
+    refl_n = _reflection_count(cg)
+    stock = _layer_stock(cg)
+    recent_path = (getattr(cg, "recent_log", "") or
+                   os.path.join(root, RECENT_LOG))
+    explore_path = os.path.join(root, EXPLORE_LOG)
+    recent_n = count_jsonl(recent_path)
+    explore_n = count_jsonl(explore_path)
+    key = (root, refl_n, stock, recent_n, explore_n, window)
+    hit = _CACHE.get(key)
+    if hit is None:
+        dist = _state_dist(cg, window)
+        hit = {
+            "events_pressure": events_pressure(cg, window=window),
+            "unmodeled_growth": unmodeled_growth(stock, dist),
+            "boundary_violation_rate": boundary_violation_rate(dist),
+        }
+        if len(_CACHE) >= _CACHE_MAX:
+            _CACHE.clear()
+        _CACHE[key] = hit
+    note = ("边界压力向量：三代理各自 [0,1]、**不合成单值**（DEV-002a）；"
+            "只计「进入系统但未被消化」的事件，不是世界真实未发生事件；"
+            "不参与 _compute_d（D_task 口径零变更）")
+    if query is not None:
+        note += "；query 已透传（本轮口径为库侧 query 无关，不计入数值）"
+    return {
+        "events_pressure": hit["events_pressure"],
+        "unmodeled_growth": hit["unmodeled_growth"],
+        "boundary_violation_rate": hit["boundary_violation_rate"],
+        "enabled": True, "window": window,
+        "note": note,
+    }
+
+
+# 生效条件：vec 为 dict 且其 key（缺省 "unmodeled_growth"）的值为 int/float 时返回裁剪到 [0,1] 的 float，否则返回 0.0；
+def pressure(vec, key: str = "unmodeled_growth") -> float:
+    """取**单一指定代理**作单值用途（禁止三代理加权合成，DEV-002a）。"""
+    if not isinstance(vec, dict):
+        return 0.0
+    v = vec.get(key)
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return 0.0
+    return round(max(0.0, min(1.0, float(v))), 4)
+
+
+# 生效条件：prev 或 cur 为假值时返回 None；否则返回三代理的逐字段差（cur-prev，round 4）字典；
+def diff(prev, cur) -> dict:
+    """逐字段差（供 `reflect` 落 `d_meta_delta`；首条无前值时返回 None）。"""
+    if not prev or not cur:
+        return None
+    out = {}
+    for k in PROXY_KEYS:
+        try:
+            out[k] = round(float(cur.get(k) or 0.0) - float(prev.get(k) or 0.0), 4)
+        except (TypeError, ValueError):
+            out[k] = 0.0
+    return out
+
+
+# 生效条件：不适用（无必需形参与分支），恒定返回本模块的自描述 dict（module/role/theory/proxies/constraints/knobs）；
+def catalog() -> dict:
+    """自描述：三代理口径、诚实边界与开关（防文档与实现漂移）。"""
+    return {
+        "module": "d_meta",
+        "role": "D_meta 结构性投影（边界压力向量，三代理各自 [0,1]，不合成单值）",
+        "theory": {
+            "dev_002": "D_task=图上操作性距离；D_meta=未被建模的现实总量——不互换",
+            "dev_002a": "可新增投影链路，不得并入 _compute_d；不得加权合成单值",
+            "increasing": "d(D_meta)/dt ≥ 0 → 只观测趋势，不做缩小运算",
+            "boundary": "审美/创造/非任务探索不由 ΔD·σ(Gain) 定价 → 只做排序加分",
+        },
+        "proxies": {
+            "events_pressure": "窗口内新增未消化事件密度（_recent + _explore 尾窗）",
+            "unmodeled_growth": ("0.5×存量饱和率（rejected+unresolved / %d）"
+                                 " + 0.5×反思窗口未消化率（BLINDSPOT+DEFER）"
+                                 % STOCK_FULL),
+            "boundary_violation_rate": "反思窗口内 (REJECT+BLINDSPOT)/全部资格态",
+        },
+        "default_proxy_for_single_value": "unmodeled_growth",
+        "knobs": {"env_gate": _ENV_FLAG, "default_enabled": True,
+                  "default_window": DEFAULT_WINDOW,
+                  "stock_full": STOCK_FULL},
+        "constraints": [
+            "只读：无写路径；不 import mdcg / mdcos（叶子模块，防循环依赖）",
+            "不参与 _compute_d（D_task 口径零变更）",
+            "不合成单一 D_meta 数值（DEV-002a）；单值只允许指定单一代理",
+            "代理只计「进入系统但未被消化」的事件，不是世界真实未发生事件",
+        ],
+        "faces": ["compute", "pressure", "diff", "tail_jsonl", "catalog"],
+    }

package/md_cg/datapath.py

@@ -1,19 +1,31 @@
 # -*- coding: utf-8 -*-
 """datapath.py · 灵枢数据根解析（记忆写入路径可配置）
 
+与 node 侧 `src/lib/datapath.ts` **同口径**——两侧读同一份
+`<用户级状态根>/paths.json`（旧 `<插件仓>/data/paths.json` 兼容读）。
+
 解析优先级（高 → 低）：
   1. 环境变量 `MDCG_DATA_ROOT`（数据根）／ `MDCG_ROOT`（认知图根）
-  2. 用户可编辑的路径文件 `<插件仓>/data/paths.json` 的 "data_root" / "root"
-  3. 默认：`<插件仓>/data`（**自身仓库**，与进程 cwd 解耦）
-
-为什么默认锚定「插件仓自身」而不是 `data/mdcg` 相对路径：
+  2. 用户可编辑的路径文件 `paths.json` 的 "data_root" / "root"
+     （位置：`<用户级状态根>/paths.json`；旧 `<插件仓>/data/paths.json` 兼容读）
+  3. 默认：`<用户级状态根>/data`（**插件包目录之外**，与进程 cwd 解耦）
+
+为什么默认**不**锚定「插件仓自身 data/」（issue #18 相邻问题，数据丢失级）：
+  DSH 插件按 hoisted 布局装在 `<profile>/node_modules/<pkg>`，`pnpm` 更新该包会
+  **整个替换包目录**——运行时数据落在包内时，每次更新成功即连目录一起删掉
+  （实机实证：`data/` 54 文件 → 0，46 条记忆节点靠人工备份回填）；`paths.json`
+  同址，用户配置一并丢失。故默认数据根与配置文件一律落**用户级状态根**
+  （见 state_root()），与包目录彻底解耦。
+
+为什么默认不锚定 `data/mdcg` 相对路径：
   相对路径随进程 cwd 漂移——node 侧插件与 python 侧脚本 cwd 不同
-  （历史事故：DSH 进程 cwd 在 AEIS 时，记忆真源落到 `AEIS/data/mdcg`，
-  与插件仓内的 `data/` 分裂成两处）。锚定 `__file__` 后默认值稳定。
+  （历史事故：DSH 进程 cwd 在私有库目录时，记忆真源落到 `[私有库]/data/mdcg`，
+  与插件仓内的 `data/` 分裂成两处）。
 
 设计边界：
-  - 本模块只决定「**新写入去哪**」，不搬运、不改写既有数据。
-    已有库（如 `AEIS/data/mdcg`）继续由其配置显式指定即可。
+  - 本模块只决定「**新写入去哪**」。唯一的搬运是 `migrate_legacy_data()`：
+    默认数据根生效且旧包内位置仍有内容时，一次性**复制**（不删除、不覆盖）
+    到用户级位置——见该函数注释。
   - 纯标准库、无包内相对导入——可被 `sys.path` 以顶层模块方式加载，
     绕开 `md_cg/__init__.py` 的重依赖。
 
@@ -21,30 +33,82 @@
   from datapath import data_root, mdcg_root, state_dir   # scripts/ 内
   python md_cg/datapath.py                 # 打印当前解析结果
   python md_cg/datapath.py --set-root D:/x/data   # 写入 paths.json（用户可改）
+  python md_cg/datapath.py --migrate-legacy       # 把旧包内数据复制到用户级根
 """
 from __future__ import annotations
 
 import json
 import os
+import shutil
 
 ENV_DATA_ROOT = "MDCG_DATA_ROOT"
 ENV_MDCG_ROOT = "MDCG_ROOT"
+ENV_STATE_ROOT = "MDCG_STATE_ROOT"
 
 
+# 生效条件：无入参，恒返回本文件 __file__ 绝对路径上溯两级得到的插件仓根目录。
 def plugin_root() -> str:
     """插件仓根目录（本文件位于 <root>/md_cg/datapath.py）。"""
     return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
 
+# 生效条件：无入参；ENV_STATE_ROOT 环境变量为非空真值时返回其 abspath，为空串/未设时若 DSH_HOME 为非空真值则返回其 abspath 下 ".dsh-memory"，两者皆无则返回 ~/.dsh/.dsh-memory 的 abspath。
+def state_root() -> str:
+    """用户级状态根（**插件包目录之外**）：路径配置与默认数据根的落点。
+
+    `DSH_HOME` **未必**由宿主注入（本仓 `dsh/dsh-web-start.bat` 自行 set），
+    故家目录兜底；`~/.dsh` 是本插件既有约定（node 侧调试日志同址）。
+    """
+    env = os.environ.get(ENV_STATE_ROOT)
+    if env:
+        return os.path.abspath(env)
+    dsh_home = os.environ.get("DSH_HOME")
+    if dsh_home:
+        return os.path.join(os.path.abspath(dsh_home), ".dsh-memory")
+    return os.path.join(os.path.expanduser("~"), ".dsh", ".dsh-memory")
+
+
+# 生效条件：无入参，恒返回 plugin_root() 下 "data" 的拼接路径（旧版落点，更新时被整目录替换，只作兼容读与迁移源）。
+def legacy_data_root() -> str:
+    """旧版落点（插件包内 `data/`）——更新时会被整个替换。"""
+    return os.path.join(plugin_root(), "data")
+
+
+# 生效条件：无入参，恒返回 legacy_data_root() 下 "paths.json" 的拼接路径。
+def legacy_paths_file() -> str:
+    """旧版路径配置文件位置（包内，兼容读）。"""
+    return os.path.join(legacy_data_root(), "paths.json")
+
+
+# 生效条件：两个路径参数经 normpath+normcase 规范化后相等时返回 True，否则 False（Windows 大小写不敏感）。
+def _same_path(a: str, b: str) -> bool:
+    return (os.path.normcase(os.path.normpath(a)) ==
+            os.path.normcase(os.path.normpath(b)))
+
+
+# 生效条件：无入参；<state_root()>/paths.json 存在（isfile）时返回之，不存在而 legacy_paths_file() 存在时返回旧件，两者皆不存在时返回新位置路径（首次写入时创建），不受 data_root() 取值影响。
 def paths_file() -> str:
-    """用户可编辑的路径配置文件——固定在插件仓 `data/paths.json`。
+    """用户可编辑的路径配置文件——用户级优先，旧包内位置兼容读。
 
-    固定锚点（不受 data_root 自身取值影响），保证「配置读取」不会
-    与「配置结果」互相依赖。
+    新位置：`<用户级状态根>/paths.json`（随包更新不丢）。
+    旧位置：`<插件仓>/data/paths.json`（旧版约定，仅当新位置不存在时读它，
+    已存在新件则新件说了算——不做自动复制，避免旧件后续编辑静默失效）。
     """
-    return os.path.join(plugin_root(), "data", "paths.json")
+    current = os.path.join(state_root(), "paths.json")
+    if os.path.isfile(current):
+        return current
+    legacy = legacy_paths_file()
+    return legacy if os.path.isfile(legacy) else current
 
 
+# 生效条件：无入参；paths_file() 的所在目录与 state_root() 同路径时返回 "user"，否则返回 "legacy"（兼容读旧包内位置）。
+def paths_file_source() -> str:
+    """生效中的 paths.json 位置来源：`user` / `legacy`。"""
+    return "user" if _same_path(os.path.dirname(paths_file()),
+                                state_root()) else "legacy"
+
+
+# 生效条件：无入参；paths_file() 的 JSON 顶层为 dict 时返回该 dict，JSON 解析或读取抛任何异常、或顶层非 dict 时返回 {}。
 def _user_paths() -> dict:
     try:
         with open(paths_file(), encoding="utf-8") as f:
@@ -54,11 +118,77 @@ def _user_paths() -> dict:
         return {}
 
 
+# 生效条件：无入参，恒返回 state_root() 下 "data" 的拼接路径（插件包目录之外，更新不触碰）。
 def default_data_root() -> str:
-    """默认数据根 = 插件仓自身 data/。"""
-    return os.path.join(plugin_root(), "data")
+    """默认数据根 = 用户级状态根下 data/。"""
+    return os.path.join(state_root(), "data")
+
+
+# 生效条件：p 为目录且其下无任何条目时返回 True，p 不存在/是文件/OSError 时返回 False。
+def _is_empty_dir(p: str) -> bool:
+    try:
+        return os.path.isdir(p) and not os.listdir(p)
+    except OSError:
+        return False
+
+
+# 生效条件：无入参；data_root() 与 default_data_root() 不同路径时返回 {ran:False, reason:"数据根为显式配置（env/paths.json），不迁移", from, to, copied:0, failed:[]}；相同则继续——legacy_data_root() 非目录时返回 reason="旧位置不存在（多为更新时已随包目录被替换）"，其下无条目（除 paths.json 外）时返回 reason="旧位置无数据"，否则把其余顶层条目逐个复制到 default_data_root() 下（目标条目已存在且非空目录则跳过；只复制不删除、不覆盖；单个条目异常记入 failed 不抛），返回 ran=(copied>0)、copied、failed 与失败时的 reason（"目标不可写" 或 "新位置已有数据，未覆盖"）。
+def migrate_legacy_data() -> dict:
+    """一次性迁移：把旧版包内 `data/` 的数据面复制到用户级默认数据根。
 
+    触发条件（三条同时满足，缺一不动）：
+      ① 数据根未被显式配置（env `MDCG_DATA_ROOT` / paths.json 的 "data_root"
+         都未设，即 data_root() 恰为默认值）——显式配置是用户的决定；
+      ② 旧位置存在；③ 目标顶层条目不存在或为空目录（不覆盖、不合并）。
 
+    `paths.json` 不复制（配置走 paths_file() 兼容读，复制会制造两说）。
+    任何异常逐项吞掉并记入 `failed`——迁移是增益，不该成为启动失败源。
+
+    边界（如实）：pnpm 更新是**先替换包目录再启动新代码**，旧数据在升级瞬间即
+    已消失，本函数只能接手「旧位置那时仍在」的情形；已在升级中丢掉的数据无法
+    由此恢复——发布说明须提示 0.4.8 及更早用户升级前备份包内 `data/`。
+    """
+    frm = legacy_data_root()
+    to = default_data_root()
+    out = {"ran": False, "reason": "", "from": frm, "to": to,
+           "copied": 0, "failed": []}
+    if not _same_path(data_root(), to):
+        out["reason"] = "数据根为显式配置（env/paths.json），不迁移"
+        return out
+    if not os.path.isdir(frm):
+        out["reason"] = "旧位置不存在（多为更新时已随包目录被替换）"
+        return out
+    try:
+        names = [n for n in os.listdir(frm) if n != "paths.json"]
+    except OSError:
+        out["reason"] = "旧位置不可读"
+        return out
+    if not names:
+        out["reason"] = "旧位置无数据"
+        return out
+    for name in names:
+        src = os.path.join(frm, name)
+        dst = os.path.join(to, name)
+        # 新位置已有实质内容 → 跳过（宁可少搬，不可覆盖）
+        if os.path.exists(dst) and not _is_empty_dir(dst):
+            continue
+        try:
+            os.makedirs(to, exist_ok=True)
+            if os.path.isdir(src):
+                shutil.copytree(src, dst, dirs_exist_ok=True)
+            else:
+                shutil.copy2(src, dst)
+            out["copied"] += 1
+        except Exception:                  # noqa: BLE001 —— 迁移不得成为启动失败源
+            out["failed"].append(name)
+    out["ran"] = out["copied"] > 0
+    if not out["ran"]:
+        out["reason"] = ("目标不可写" if out["failed"]
+                         else "新位置已有数据，未覆盖")
+    return out
+
+
+# 生效条件：无入参；ENV_DATA_ROOT 环境变量为非空真值时返回其 abspath，为空串/未设时若 paths.json 的 "data_root" 为真值则按其是否为绝对路径决定直接 abspath 还是拼 plugin_root() 后 abspath，该键缺失或为假值时回落 default_data_root()。
 def data_root() -> str:
     """数据根（记忆/账本/运行态的父目录）。"""
     env = os.environ.get(ENV_DATA_ROOT)
@@ -71,6 +201,7 @@ def data_root() -> str:
     return default_data_root()
 
 
+# 生效条件：无入参；ENV_MDCG_ROOT 环境变量为非空真值时返回其 abspath，为空串/未设时若 paths.json 的 "root" 为真值则按其是否为绝对路径决定直接 abspath 还是拼 plugin_root() 后 abspath，该键缺失或为假值时返回 data_root() 下 "mdcg" 的拼接路径。
 def mdcg_root() -> str:
     """认知图（记忆唯一真源）根目录。"""
     env = os.environ.get(ENV_MDCG_ROOT)
@@ -83,6 +214,7 @@ def mdcg_root() -> str:
     return os.path.join(data_root(), "mdcg")
 
 
+# 生效条件：parts 非空时路径为 data_root() 与各 part 的 join，parts 为空时路径即 data_root()；create 为真值（默认 True）时对该路径 makedirs(exist_ok=True)，create 为假值时只返回路径不建目录。
 def state_dir(*parts: str, create: bool = True) -> str:
     """运行态子目录（日志/队列/草稿…），默认挂在数据根下。"""
     p = os.path.join(data_root(), *parts) if parts else data_root()
@@ -91,51 +223,88 @@ def state_dir(*parts: str, create: bool = True) -> str:
     return p
 
 
+# 生效条件：name 依次拼成 data_root()/name、plugin_root()/name、dirname(plugin_root())/[私有归档根]/_archive/ctp-aeis-data/name 三个候选，仅保留其中 os.path.isfile 为真的项并按此顺序返回列表。
+def archive_root() -> str | None:
+    """私有侧归档根（公开仓不含私有库名）：本机配置提供，未配置则没有该候选。
+
+    取值顺序：环境变量 MDCG_ARCHIVE_ROOT -> 插件仓同级的 .mdcg_archive_root 文件内容。
+    """
+    value = os.environ.get("MDCG_ARCHIVE_ROOT", "").strip()
+    if value:
+        return value
+    marker = os.path.join(os.path.dirname(plugin_root()), ".mdcg_archive_root")
+    if os.path.isfile(marker):
+        try:
+            with open(marker, "r", encoding="utf-8") as fh:
+                text = fh.read().strip()
+        except OSError:
+            return None
+        return text or None
+    return None
+
+
+# 生效条件：给定 name 时按 data_root()/name、plugin_root()/name 顺序拼接候选，仅当 archive_root() 不为 None 才追加其下 _archive/ctp-aeis-data/name，最终只返回其中 os.path.isfile 为真的路径（其余被过滤掉），故全都不满足时返回空列表。
 def legacy_candidates(name: str) -> list:
     """历史位置候选（只读兼容：三仓分离前的校验缓存等）。
 
     仅用于「读旧件」，顺序：数据根 → 插件仓根 → 归档区。
     """
     out = [os.path.join(data_root(), name),
-           os.path.join(plugin_root(), name),
-           os.path.join(os.path.dirname(plugin_root()), "AEIS", "_archive",
-                        "ctp-aeis-data", name)]
+           os.path.join(plugin_root(), name)]
+    archive = archive_root()
+    if archive is not None:
+        out.append(os.path.join(archive, "_archive", "ctp-aeis-data", name))
     return [p for p in out if os.path.isfile(p)]
 
 
+# 生效条件：name 对应的 legacy_candidates(name) 列表非空时返回其首个元素，为空列表时返回 None。
 def find_existing(name: str) -> str | None:
     """在数据根/插件仓/归档区中找已存在的同名文件，找不到返回 None。"""
     hits = legacy_candidates(name)
     return hits[0] if hits else None
 
 
+# 生效条件：无入参；恒返回含 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 的字典，其中 source 按 ENV_DATA_ROOT 非空取 "env:MDCG_DATA_ROOT" → 否则 ENV_MDCG_ROOT 非空取 "env:MDCG_MDCG_ROOT" → 否则 _user_paths() 为非空 dict 取 "paths.json(用户级)" 或 "paths.json(兼容读旧包内位置)"（按 paths_file_source()）→ 否则取 "default(用户级状态根 data/)"。
 def describe() -> dict:
     """当前解析结果的完整快照（供心跳/日志留痕）。"""
     dr = data_root()
     mr = mdcg_root()
+    pf_src = paths_file_source()
     return {
         "plugin_root": plugin_root(),
+        "state_root": state_root(),
         "data_root": dr,
         "mdcg_root": mr,
         "default_data_root": default_data_root(),
-        "is_default": (os.path.normcase(dr) ==
-                       os.path.normcase(default_data_root())),
+        "is_default": _same_path(dr, default_data_root()),
         "source": ("env:" + ENV_DATA_ROOT if os.environ.get(ENV_DATA_ROOT)
                    else ("env:" + ENV_MDCG_ROOT if os.environ.get(ENV_MDCG_ROOT)
-                         else ("paths.json" if _user_paths() else "default"))),
+                         else (("paths.json(用户级)" if pf_src == "user"
+                                else "paths.json(兼容读旧包内位置)")
+                               if _user_paths()
+                               else "default(用户级状态根 data/)"))),
         "paths_file": paths_file(),
+        "paths_file_source": pf_src,
+        "legacy_data_root": legacy_data_root(),
+        "legacy_data_exists": os.path.isdir(legacy_data_root()),
         "data_root_exists": os.path.isdir(dr),
         "mdcg_root_exists": os.path.isdir(mr),
     }
 
 
+# 生效条件：path 为传入字符串（写入前反斜杠替换为 "/"），key 默认 "data_root"（传入时写入该键名）；先确保 <state_root()> 存在，读取 _user_paths()（可能来自旧包内位置的兼容读，异常时为 {}，故旧配置在首次改写时被带到新位置并从此由新件说了算）并补 "_comment"，再以该内容覆写 <state_root()>/paths.json 并返回该路径。
 def set_user_root(path: str, key: str = "data_root") -> str:
-    """把用户选择的路径写入 paths.json（不存在则创建）。返回文件路径。"""
-    pf = paths_file()
+    """把用户选择的路径写入**用户级** paths.json（不存在则创建）。返回文件路径。
+
+    永远写新位置（不写旧包内那件）——旧位置会随包更新被删除，写进去等于
+    用户设置迟早丢失；旧件的既有取值经 _user_paths() 带入新件，不丢配置。
+    """
+    pf = os.path.join(state_root(), "paths.json")
     os.makedirs(os.path.dirname(pf), exist_ok=True)
     d = _user_paths()
     d.setdefault("_comment",
-                 "灵枢记忆写入路径（用户可改）。删掉本文件即回落到插件仓自身 data/。")
+                 "灵枢记忆写入路径（用户可改）。删掉本文件即回落到用户级默认数据根"
+                 "（~/.dsh/.dsh-memory/data）。")
     d[key] = path.replace("\\", "/")
     with open(pf, "w", encoding="utf-8") as f:
         json.dump(d, f, ensure_ascii=False, indent=2)
@@ -149,12 +318,18 @@ if __name__ == "__main__":
     sys.stdout.reconfigure(encoding="utf-8", errors="replace")
     ap = argparse.ArgumentParser(description="灵枢数据根解析与设置")
     ap.add_argument("--set-root", metavar="PATH",
-                    help="把数据根写入 <插件仓>/data/paths.json（用户可改）")
+                    help="把数据根写入 <用户级状态根>/paths.json（用户可改）")
     ap.add_argument("--set-mdcg-root", metavar="PATH",
-                    help="把认知图根写入 <插件仓>/data/paths.json")
+                    help="把认知图根写入 <用户级状态根>/paths.json")
+    ap.add_argument("--migrate-legacy", action="store_true",
+                    help="把旧版包内 data/ 的数据面复制到用户级默认数据根"
+                         "（只复制不删除；默认数据根被显式配置时不动作）")
     a = ap.parse_args()
     if a.set_root:
         print("written:", set_user_root(a.set_root, "data_root"))
     if a.set_mdcg_root:
         print("written:", set_user_root(a.set_mdcg_root, "root"))
-    print(json.dumps(describe(), ensure_ascii=False, indent=2))
+    if a.migrate_legacy:
+        print("migrate:", json.dumps(migrate_legacy_data(),
+                                     ensure_ascii=False))
+    print(json.dumps(describe(), ensure_ascii=False, indent=2))