@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/md_cg/writelimit.py

@@ -0,0 +1,327 @@
+# -*- coding: utf-8 -*-
+"""自动写入限流与同构聚合（流水污染治理：写入侧前置 + 读侧整理）。
+
+背景（2026-09-15 污染实测）：某环境 contextual 层 355 个自动写入节点中，
+46% 是单日批次流水（「批次247收官记忆」…×163 条同模板），17% 是无结构
+mem_* 节点；主动遗忘闸门（forgetting.assess）MERGE 命中率仅 1%——精确
+内容签名对「每次只换数字的同模板流水」完全无感。
+
+本模块两层治理（只作用 contextual 层——自动写入落层；knowledge 等
+手动纪律写入不受限）：
+
+  写入侧（remember_gated 前置，工程策略独立于三问裁决）：
+    1) 同源频率限制：同 (layer, role) 滑动窗口内超量 → DEFER（防灌水；
+       原始事件仍在 recent log 时间线，可追溯不丢失）
+    2) 同构聚合：短内容模板签名（去数字/URL/长十六进制）命中 →
+       并入既有节点（正文追加一行 + merge_count+1，不新增节点）
+
+  读侧（sustain 周期巡检调 tidy_contextual）：
+    已落盘的同构组（≥min_group 条）→ 保留最早节点追加成员清单，
+    成员降权（importance×0.5，下限 0.1）+ tidy:converged 标记；
+    永不删除节点（可逆、可审计），受保护节点跳过。
+
+状态持久化 <root>/_writelimit.json（进程重启不失效）；
+env MDCG_WRITELIMIT=0 整体关闭；importance_hint≥0.7（保护优先语义）
+跳过所有限流。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import time
+
+from .fsutil import FileLock, atomic_write
+
+STATE_FILE = "_writelimit.json"
+RATE_WINDOW = 60.0            # 频率窗口（秒）
+RATE_MAX = 8                  # 窗口内同 (layer, role) 最大写入数
+CONVERGE_WINDOW = 86400.0     # 同构聚合窗口（秒，24h）
+MAX_CONTENT = 200             # 参与同构聚合的内容长度上限（字符）
+MIN_SKELETON = 4              # 模板骨架最短长度（防「好的/收到」误聚）
+MAX_APPLY = 500               # tidy 单次落盘成员数上限（防一次改爆）
+
+_RE_URL = re.compile(r"https?://\S+")
+_RE_HEX = re.compile(r"\b[0-9a-fA-F]{12,}\b")
+_RE_LONG_NUM = re.compile(r"\d{4,}")
+_RE_NUM = re.compile(r"\d+")
+_RE_WS = re.compile(r"\s+")
+_RE_TITLE = re.compile(r"^\s*#\s*功能名[：:]\s*(.+?)\s*$", re.M)
+
+
+def enabled() -> bool:
+    """总开关：env MDCG_WRITELIMIT=0/false/no 时关闭所有限流。"""
+    return os.environ.get("MDCG_WRITELIMIT", "1").strip().lower() \
+        not in ("0", "false", "no")
+
+
+def template_signature(content: str):
+    """同模板流水签名：标题模板优先，其次全文骨架。
+
+    - 带「# 功能名：X」标题行的节点：对标题做去数字骨架（不受正文长度
+      限制）——批次报告正文各不相同但标题同模板（「批次N收官记忆」），
+      标题是节点身份的最强模板信号
+    - 无标题：去 URL/长十六进制/数字后的全文压缩骨架；长文
+      （≥MAX_CONTENT）是正经记忆不参与聚合
+    - 骨架过短（<MIN_SKELETON）或纯数字 → None（防「好的/收到」误聚）
+    """
+    if not content:
+        return None
+    text = content.strip()
+    m = _RE_TITLE.search(text)
+    if m:
+        s = _skeleton(m.group(1))
+        return ("t:" + s) if s and len(s) >= MIN_SKELETON else None
+    if len(text) >= MAX_CONTENT:
+        return None
+    s = _skeleton(text)
+    return s if s and len(s) >= MIN_SKELETON else None
+
+
+def _skeleton(text: str) -> str:
+    s = _RE_URL.sub(" ", text)
+    s = _RE_HEX.sub(" ", s)
+    s = _RE_LONG_NUM.sub(" ", s)
+    s = _RE_NUM.sub(" ", s)
+    s = _RE_WS.sub("", s)
+    return s
+
+
+# ---------- 状态持久化 ----------
+
+def _state_path(cg) -> str:
+    return os.path.join(cg.root, STATE_FILE)
+
+
+def _load(cg) -> dict:
+    try:
+        with open(_state_path(cg), encoding="utf-8") as f:
+            st = json.load(f)
+        if isinstance(st.get("sigs"), dict) and isinstance(st.get("rate"), dict):
+            return st
+    except (OSError, ValueError):
+        pass
+    return {"sigs": {}, "rate": {}}
+
+
+def _save(cg, st: dict) -> None:
+    p = _state_path(cg)
+    with FileLock(p):
+        atomic_write(p, json.dumps(st, ensure_ascii=False, sort_keys=True))
+
+
+def _push_rate(st: dict, key: str, now: float) -> None:
+    win = [t for t in st["rate"].get(key, []) if now - t < RATE_WINDOW]
+    win.append(now)
+    st["rate"][key] = win[-RATE_MAX * 4:]
+
+
+# ---------- 写入侧：前置限流 + 同构聚合 ----------
+
+def check(cg, content, layer="contextual", role=None, node_id=None,
+          importance_hint=None, now=None):
+    """remember_gated 前置限流。None=放行；否则 {"verdict": DEFER|CONVERGE}。
+
+    - DEFER：同 (layer, role) 滑动窗口内已满 RATE_MAX 条（被拒者也计数，
+      防持续灌水每条都重算窗口）
+    - CONVERGE：签名命中（CONVERGE_WINDOW 内、目标节点仍在）→ 应并入
+      rec["nid"]；签名首见即预占位（nid=node_id），assess 若 DEFER/DROP
+      该节点未落盘，下次 cg.get 失效自动重置——自愈
+    """
+    if layer != "contextual" or not enabled():
+        return None
+    if importance_hint is not None:
+        try:
+            if float(importance_hint) >= 0.7:
+                return None                     # 保护优先语义：跳过限流
+        except (TypeError, ValueError):
+            pass
+    now = float(now if now is not None else time.time())
+    st = _load(cg)
+    key = f"{layer}:{role or 'user'}"
+    # 1) 同源频率限制
+    win = [t for t in st["rate"].get(key, []) if now - t < RATE_WINDOW]
+    if len(win) >= RATE_MAX:
+        win.append(now)
+        st["rate"][key] = win[-RATE_MAX * 4:]
+        _save(cg, st)
+        return {"verdict": "DEFER", "limiter": "rate", "reason":
+                f"ratelimit:{key}:>{RATE_MAX}in{int(RATE_WINDOW)}s"}
+    # 2) 同构聚合
+    sig = template_signature(content)
+    if sig:
+        rec = st["sigs"].get(sig)
+        if rec and now - float(rec.get("t") or 0) < CONVERGE_WINDOW \
+                and rec.get("nid"):
+            tgt = cg.get(rec["nid"])
+            if tgt:
+                if (tgt.get("content") or "").strip() \
+                        == (content or "").strip():
+                    # 与既有节点正文完全一致：零新信息 → 交回旧闸门语义
+                    # DROP（不落库、不追加聚合行、不强化既有）——对齐
+                    # forgetting 闸门「确定性内部冗余 → DROP 先于 MERGE」
+                    # 纪律；同模板但内容不同才走聚合（那才是流水治理）
+                    _push_rate(st, key, now)
+                    _save(cg, st)
+                    return {"verdict": "DROP", "limiter": "exact_dup",
+                            "target": rec["nid"],
+                            "reason": f"exact_dup_of:{rec['nid']}"}
+                rec["n"] = int(rec.get("n") or 1) + 1
+                rec["last"] = now
+                st["sigs"][sig] = rec
+                _push_rate(st, key, now)
+                _save(cg, st)
+                return {"verdict": "CONVERGE", "limiter": "converge",
+                        "target": rec["nid"], "sig": sig[:40], "n": rec["n"],
+                        "reason": f"converge:{sig[:40]}#{rec['n']}"}
+        st["sigs"][sig] = {"nid": node_id, "t": now, "n":
+                           int((rec or {}).get("n") or 1),
+                           "sk": sig[:60]}
+    _push_rate(st, key, now)
+    _save(cg, st)
+    return None
+
+
+def record_accepted(cg, node_id, content, now=None) -> None:
+    """ACCEPT 落盘后确保签名→节点映射存在（check 已预占位，此处兜底）。"""
+    sig = template_signature(content)
+    if not sig:
+        return
+    now = float(now if now is not None else time.time())
+    st = _load(cg)
+    rec = st["sigs"].get(sig)
+    if rec is None or not rec.get("nid"):
+        st["sigs"][sig] = {"nid": node_id, "t": now, "n":
+                           int((rec or {}).get("n") or 1), "sk": sig[:60]}
+        _save(cg, st)
+
+
+def converge_into(cg, target: str, content: str) -> dict:
+    """同构聚合落库：正文追加一行【聚合】摘要，merge_count+1。
+
+    importance **不变**——流水不该越聚越重要（与 forgetting.reinforce
+    的 +0.05 相反）；原始内容截 80 字入行，全文仍在 recent log 可溯。
+    """
+    e = cg.get(target)
+    if not e:
+        return {"ok": False, "error": "target_missing"}
+    fm = dict(e.get("frontmatter") or {})
+    body = " ".join((content or "").split())[:80]
+    stamp = time.strftime("%m-%d %H:%M", time.localtime())
+    fm["merge_count"] = int(fm.get("merge_count") or 0) + 1
+    fm["last_merge_at"] = time.time()
+    cg._write_node(target, os.path.join(cg.root, e["path"]), fm,
+                   (e.get("content") or "") + f"\n- 【聚合 {stamp}】{body}",
+                   durable=True)
+    entry = cg.index["nodes"].get(target)
+    if entry is not None:
+        entry.update({"merge_count": fm["merge_count"],
+                      "last_merge_at": fm["last_merge_at"]})
+        cg._dirty[target] = entry
+    return {"ok": True, "merge_count": fm["merge_count"]}
+
+
+# ---------- 读侧：已落盘同构组的周期整理（sustain 巡检入口）----------
+
+def tidy_contextual(cg, apply=False, min_group=3, actor="sustain_tidy",
+                    limit=2000) -> dict:
+    """扫描 contextual 层已落盘节点，按模板签名分组并整理。
+
+    对 ≥min_group 的同构组（apply=True 时）：
+      · 保留最早节点：正文追加【整理聚合】成员清单段落
+      · 成员节点：tags += tidy:converged、importance×0.5（下限 0.1）
+    永不删除节点（可逆、可审计）；protected/immutable 成员跳过；
+    apply=False 只盘点不动任何节点。
+    """
+    groups: dict = {}
+    scanned = 0
+    for nid, entry in list(getattr(cg, "index", {})
+                           .get("nodes", {}).items()):
+        if scanned >= limit:
+            break
+        if entry.get("layer") != "contextual":
+            continue
+        e = cg.get(nid)
+        if not e:
+            continue
+        scanned += 1
+        sig = template_signature(e.get("content") or "")
+        if sig:
+            groups.setdefault(sig, []).append(e)
+    planned = []
+    for sig, members in groups.items():
+        if len(members) < min_group:
+            continue
+        members.sort(key=lambda m: float((m.get("frontmatter") or {})
+                                         .get("created_at", 0) or 0))
+        planned.append({"sig": sig[:40], "keep": members[0]["id"],
+                        "members": [m["id"] for m in members[1:]]})
+    planned.sort(key=lambda p: -len(p["members"]))
+    out = {"t": time.time(), "actor": actor, "scanned": scanned,
+           "groups": len(planned),
+           "members": sum(len(p["members"]) for p in planned),
+           "apply": bool(apply), "planned": planned[:20], "applied": []}
+    if not apply or not planned:
+        return out
+    n_ap = 0
+    for p in planned:
+        if n_ap >= MAX_APPLY:
+            break
+        keep = cg.get(p["keep"])
+        if not keep:
+            continue
+        lines = [f"\n\n# 整理聚合（tidy {time.strftime('%Y-%m-%d')}）："
+                 f"同模板成员 {len(p['members'])} 条"]
+        for mid in p["members"]:
+            m = cg.get(mid)
+            if not m:
+                continue
+            mfm = dict(m.get("frontmatter") or {})
+            if mfm.get("protected") or mfm.get("immutable"):
+                continue
+            first = " ".join((m.get("content") or "").split())[:48]
+            lines.append(f"- {mid} {first}")
+            _demote(cg, m)
+            n_ap += 1
+        kfm = dict(keep.get("frontmatter") or {})
+        kfm["merge_count"] = int(kfm.get("merge_count")
+                                 or 0) + len(p["members"])
+        kfm["last_merge_at"] = time.time()
+        cg._write_node(keep["id"], os.path.join(cg.root, keep["path"]),
+                       kfm, (keep.get("content") or "") + "\n".join(lines),
+                       durable=True)
+        out["applied"].append({"keep": p["keep"],
+                               "converged": len(p["members"])})
+    out["applied_count"] = n_ap
+    flush = getattr(cg, "flush", None)
+    if callable(flush):
+        flush()
+    return out
+
+
+def _demote(cg, e: dict) -> None:
+    """成员降权：tags += tidy:converged，importance×0.5（下限 0.1）。"""
+    fm = dict(e.get("frontmatter") or {})
+    tags = list(fm.get("tags") or [])
+    if "tidy:converged" not in tags:
+        tags.append("tidy:converged")
+    fm["tags"] = tags
+    fm["importance"] = round(max(0.1, float(fm.get("importance", 0.5)
+                                          or 0) * 0.5), 3)
+    cg._write_node(e["id"], os.path.join(cg.root, e["path"]), fm,
+                   e.get("content") or "")
+    entry = cg.index["nodes"].get(e["id"])
+    if entry is not None:
+        entry.update({"tags": tags, "importance": fm["importance"]})
+        cg._dirty[e["id"]] = entry
+
+
+def stats(cg) -> dict:
+    """限流状态摘要（诊断面）。"""
+    st = _load(cg)
+    live_sigs = sum(1 for r in st["sigs"].values() if r.get("nid"))
+    return {"enabled": enabled(), "sigs_tracked": len(st["sigs"]),
+            "sigs_live": live_sigs,
+            "rate_keys": len(st["rate"]),
+            "state_file": STATE_FILE}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furongjun1999/dsh-memory",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "灵枢（Lingshu·líng shū）DeepSeek Harness 插件：完整大脑——长期记忆/知识飞轮/自我认知/递归反思接入 DSH，对话自动沉淀进 md_cg 认知图（md 文档）",
   "type": "module",
   "main": "lib/index.js",
@@ -17,8 +17,9 @@
     "md_cg",
     "skills",
     "README.md",
-    "cordis.yml.example",
-    "cordis.patch.yml",
+    "dsh",
+    "codebuddy",
+    "zcode",
     "docs"
   ],
   "keywords": [
@@ -89,7 +90,7 @@
   },
   "dsh": {
     "bundle": {
-      "patch": "./cordis.patch.yml"
+      "patch": "./dsh/cordis.patch.yml"
     }
   }
 }

package/src/bridge.ts

@@ -230,7 +230,9 @@ export class LingshuBridge {
         this.unexpectedExits.push(Date.now())
         if (uptimeS >= 0 && uptimeS < 5) {
           console.error(
-            '[lingshu-bridge] 进程启动后 5 秒内即退出——请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检）。')
+            '[lingshu-bridge] 进程启动后 5 秒内即退出——请检查 python 可执行文件与 md_cg 依赖。' +
+            '自检 `python -m md_cg.mcp_server` 须在插件包根目录运行' +
+            '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12）。')
         } else if (this.unexpectedExits.length >= 3) {
           console.error(
             `[lingshu-bridge] 10 分钟内已意外退出 ${this.unexpectedExits.length} 次，` +
@@ -290,7 +292,8 @@ export class LingshuBridge {
       this.flushBootQueue(false)
       console.error(
         `[lingshu-bridge] 连续启动失败 ${this.retries} 次，已停止自动重启（不再后台空转）。` +
-        '请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检），修复后在 DSH 中重新启用 dsh-memory 插件。')
+        '请检查 python 可执行文件与 md_cg 依赖；自检 `python -m md_cg.mcp_server` 须在插件包根目录运行' +
+        '（插件已自动锚定 cwd 与 PYTHONPATH，issue #12），修复后在 DSH 中重新启用 dsh-memory 插件。')
       probe(`give up: ${this.retries} consecutive failures, entering failed terminal state`)
       return
     }
@@ -319,7 +322,7 @@ export class LingshuBridge {
     if (this.gaveUp) {
       return Promise.reject(new Error(
         '灵枢进程不可用：连续启动失败已达上限，已停止重试。' +
-        '请检查 python 可执行文件与 md_cg 依赖（python -m md_cg.mcp_server 可自检），修复后重新启用 dsh-memory 插件。'))
+        '请检查 python 可执行文件与 md_cg 依赖（自检 `python -m md_cg.mcp_server` 须在插件包根目录运行），修复后重新启用 dsh-memory 插件。'))
     }
     const id = this.nextId++
     const timeout = this.options.timeoutMs

package/src/hooks.ts

@@ -88,7 +88,8 @@ export function desensitize(text: string): string | null {
 }
 
 /** 时间线载荷 → 注入文本。
- *  `stg(op=timeline)` 返回 {count, limit, items:[{id, layer, start, end, preview}]}。 */
+ *  `stg(op=timeline)` 返回 {count, limit, items:[{id, layer, start, end, preview}]}。
+ *  （保留原始实现；自动召回改用下面的分级递减渲染） */
 function formatTimeline(payload: unknown): string {
   const items = (payload && typeof payload === 'object'
     && Array.isArray((payload as { items?: unknown }).items))
@@ -105,6 +106,64 @@ function formatTimeline(payload: unknown): string {
     .join('\n')
 }
 
+// ---------------------------------------------------------------- 自动召回渲染
+// 常量写死在此处（而非 config schema）——未知键会被 schema 剥离。
+/** 第 1 档（最新 1 条）每条字符上限。 */
+const RECALL_BASE_CHARS = 160
+/** 每 N 条降一档。 */
+const RECALL_DECAY_EVERY = 1
+/** 每档缩放比例（−10%）。 */
+const RECALL_DECAY_RATIO = 0.9
+/** 最小保留字符。 */
+const RECALL_MIN_CHARS = 24
+/** 整块上限（与调用点 slice 对齐）。 */
+const RECALL_MAX_CHARS = 1400
+/** 永久层不自动注入（按需用 mdcg_recall / lingshu_stg 取）。 */
+const RECALL_SKIP_LAYERS = new Set(['anchor', 'self'])
+/** 连续跳过多少步后强制补一次（内容未变也刷新，防止压缩归档后块消失）。 */
+const RECALL_REPUSH_EVERY = 8
+
+/** 分级递减渲染：按距当前的次序逐档收窄，早期条目信息量更大。
+ *
+ *  动机：注入块总长受限，而"最近 N 条"里越靠前的越可能被用到；线性等宽分配
+ *  会让整块被最旧的一条挤掉。逐档递减后整块实测约 1133 字符（≈472 tok），
+ *  9 条全部保留。（注意：整块仍远小于一条知识节点 500~800 tok，故本块定位是
+ *  「存在性索引/提醒」，不承载知识本身——要知识请显式 mdcg_recall 并给足预算。） */
+function formatTimelineDecayed(payload: unknown): string {
+  const items = (payload && typeof payload === 'object'
+    && Array.isArray((payload as { items?: unknown }).items))
+    ? (payload as { items: Array<Record<string, unknown>> }).items
+    : []
+  const out: string[] = []
+  let rank = 0
+  for (const it of items) {
+    const layer = String(it['layer'] ?? '')
+    if (RECALL_SKIP_LAYERS.has(layer)) continue
+    const preview = String(it['preview'] ?? '').replace(/\s+/g, ' ').trim()
+    if (!preview) continue
+    const tier = Math.floor(rank / RECALL_DECAY_EVERY)
+    const budget = Math.max(
+      RECALL_MIN_CHARS,
+      Math.round(RECALL_BASE_CHARS * Math.pow(RECALL_DECAY_RATIO, tier)),
+    )
+    out.push(`- [${layer}] ` + (preview.length > budget ? preview.slice(0, budget) + '…' : preview))
+    rank += 1
+    if (out.join('\n').length >= RECALL_MAX_CHARS) break
+  }
+  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）时自动记忆整体停用：记忆真源是
@@ -137,16 +196,23 @@ export function installMemoryHooks(ctx: Context, mdcg: MdcgClient | null, opts:
   // 用 system-prompt/assemble 事件（waterfall）而非 llm/stream——后者请求 deep-frozen 不可改写。
   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 = formatTimeline(await graph.timeline(recallLimit))
-          if (text) {
+          const text = formatTimelineDecayed(await graph.timeline(recallLimit))
+          if (shouldPushRecall(text, lastRecallText, skippedSincePush)) {
+            lastRecallText = text
+            skippedSincePush = 0
             assembly.contexts.push({
               name: 'lingshu:auto-recall',
-              text: `【灵枢最近记忆】\n${text.slice(0, 600)}`,
+              text: `【灵枢最近记忆】\n${text.slice(0, RECALL_MAX_CHARS)}`,
             })
+          } else {
+            skippedSincePush += 1
           }
         }
       }

package/src/index.ts

@@ -283,7 +283,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
         'dsh-memory: 认知图写入凭据不可用，以只读 guest 运行——'
         + '读 / 召回 / 时间线可用，但自动记忆、转录、角色落图不会落盘。'
         + (cred.note ? `原因：${cred.note}。` : '')
-        + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 cordis.yml.example），'
+        + '要打开：签发令牌 MDCG_TOKEN 经 config.env 注入（见 dsh/cordis.yml.example），'
         + '或删除密钥环后重启以重新自动签发。')
     } else if (cred.source === 'issued') {
       // 首启引导：自动签发是**改变用户可写权限**的动作，必须留痕（含关闭/吊销方式）。

package/src/lib/datapath.ts

@@ -17,7 +17,7 @@
  *   锚定 `package.json` 所在目录后，默认值稳定且可预期。
  */
 import { existsSync, readFileSync } from 'node:fs'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 export const ENV_DATA_ROOT = 'MDCG_DATA_ROOT'
@@ -89,6 +89,22 @@ export function mdcgRoot(configured?: string): string {
   return join(dataRoot(), 'mdcg')
 }
 
+/**
+ * Python 子进程的 PYTHONPATH 值（issue #12）。
+ *
+ * Python 启动 `-m` 时只把 **cwd** 注入 sys.path——DSH 宿主在插件仓外启动时
+ * `python -m md_cg.mcp_server` / `python -m md_cg.tokens` 必然
+ * ModuleNotFoundError。cwd 与 PYTHONPATH 双保险：后者不依赖 cwd，即使调用方
+ * 显式覆盖了启动参数/工作目录也兜得住。顺序：仓根在前（优先随包 md_cg，
+ * 防宿主环境同名旧包抢先），进程既有 PYTHONPATH 在后。
+ */
+export function pythonPathValue(): string {
+  const prev = process.env.PYTHONPATH ?? ''
+  const parts = [repoRoot()]
+  if (prev && !prev.split(delimiter).includes(repoRoot())) parts.push(prev)
+  return parts.join(delimiter)
+}
+
 /** 当前解析快照（供启动日志留痕——把「记忆真源在哪」写进可审计痕迹）。 */
 export function describeDataPaths(configured?: string): Record<string, string | boolean> {
   const dr = dataRoot()

package/src/lib/mdcg_client.ts

@@ -35,7 +35,9 @@
  *   的**所有写入**（记忆沉淀 / 角色定义 / 对话转录）统一经 `mdcg_remember`。
  */
 
+import { delimiter } from 'node:path'
 import { LingshuBridge, type McpCallResult } from '../bridge.js'
+import { pythonPathValue, repoRoot } from './datapath.js'
 
 /** md_cg 子进程与根目录配置。 */
 export interface MdcgOptions {
@@ -45,6 +47,10 @@ 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）。 */
+  cwd?: string
   /** 调用主体标识（MDCG_ACTOR）。私有内容按 (tenant, actor) 派生 DEK，
    *  故与迁移脚本 --actor 必须一致，否则读不到已迁移节点。 */
   actor?: string
@@ -116,6 +122,10 @@ 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()
     const env: Record<string, string> = {
       // ⚠️ 必须显式 utf-8：Windows 下 piped 子进程默认 gbk + surrogateescape，
       // Node 写出的 UTF-8 中文会被解成孤立代理字符（\udcXX），md_cg 在落盘 /
@@ -128,6 +138,7 @@ export class MdcgClient {
       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 ?? {}),
@@ -136,6 +147,7 @@ export class MdcgClient {
       python: opts.python,
       args: opts.args ?? DEFAULT_ARGS,
       env,
+      cwd,
       timeoutMs: opts.timeoutMs ?? 60_000,
       maxRetryDelayMs: opts.maxRetryDelayMs ?? 30_000,
     })

package/src/lib/mutual.ts

@@ -15,6 +15,7 @@ import { exec, spawn } from 'node:child_process'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 import * as os from 'node:os'
+import { pythonPathValue, repoRoot } from './datapath.js'
 
 export interface MutualOptions {
   /** 心跳间隔（毫秒），默认 10min */
@@ -142,6 +143,10 @@ export async function ensureHarness(python = 'python',
         windowsHide: true,
         detached: true,
         stdio: 'ignore',
+        // issue #12 同类：锚定插件仓根 + PYTHONPATH，与 mdcg_client / token_store
+        // 同口径——不随宿主 cwd 漂移；harness 包不在仓内时注入不劣化（回落用户环境）。
+        cwd: repoRoot(),
+        env: { ...process.env, PYTHONPATH: pythonPathValue() },
       })
     } catch (e) {
       log(opts, `守护失败：${String(e)}`)

package/src/lib/roleplay_web.ts

@@ -9,7 +9,7 @@
  *    转录、历史、翻译、落图全部不依赖「身体」，始终可用。
  *  · 身体（可选 capability 后端）：生成能力 roleplay_chat / role_create /
  *    role_import 属「身」，主仓默认不挂载；未挂载时这些接口 **fail-closed**
- *    返回明确原因（不编造回复）。启用见 config.capability（cordis.yml.example）。
+ *    返回明确原因（不编造回复）。启用见 config.capability（dsh/cordis.yml.example）。
  */
 import { join, dirname } from 'node:path';
 import { readFileSync, mkdirSync, appendFileSync, existsSync, writeFileSync, renameSync } from 'node:fs';

package/src/lib/token_store.ts

@@ -30,6 +30,7 @@ import { spawnSync } from 'node:child_process'
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import { pythonPathValue, repoRoot } from './datapath.js'
 
 /** 凭据来源（用于启动日志与故障定位）。 */
 export type TokenSource =
@@ -111,8 +112,17 @@ function issueToken(python: string, role: string, actor: string, clearance: stri
         encoding: 'utf-8',
         windowsHide: true,
         timeout: 15_000,
-        // 与工作纪律第 15 条同源：显式 UTF-8 + PYTHONUTF8，规避 Windows GBK 解码异常
-        env: { ...process.env, PYTHONUTF8: '1', PYTHONIOENCODING: 'utf-8' },
+        // 与工作纪律第 15 条同源：显式 UTF-8 + PYTHONUTF8，规避 Windows GBK 解码异常。
+        // issue #12：cwd+PYTHONPATH 锚定插件仓根——否则 npm 包形态下宿主在仓外
+        // 启动时 `python -m md_cg.tokens` 找不到随包 md_cg，首启签发静默失败，
+        // md_cg 侧降级只读 guest（写入全不落盘且无报错）。
+        cwd: repoRoot(),
+        env: {
+          ...process.env,
+          PYTHONPATH: pythonPathValue(),
+          PYTHONUTF8: '1',
+          PYTHONIOENCODING: 'utf-8',
+        },
       },
     )
   } catch (e) {