@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/writepipe.py

@@ -40,11 +40,12 @@ write 的六道闸（audit 校验 / consistency 冲突 / review 审核 / gated
 
 import time
 
-from . import twophase
+from . import twophase, trust
 
 __all__ = ["WritePipeline", "default_pipeline"]
 
 
+# 生效条件：调用即对 cg 执行 flush()（无脏数据时为 no-op），且仅当该调用抛异常而 out 是 dict 时在 out 写入 "flush_error"，异常本身不外抛；
 def _commit_visibility(cg, out):
     """写提交边界（2026-09-16）：把内存脏索引落分片日志，使本次写入对其他进程立即可见。
 
@@ -70,12 +71,14 @@ def _commit_visibility(cg, out):
 class WritePipeline:
     """写入拦截器链（实例级；default_pipeline() 提供进程级默认单例）。"""
 
+# 生效条件：无前置；初始化 _before / _after 两条空链（元素为 (name, fn) 二元组），不做任何注册、不触盘；
     def __init__(self):
         self._before = []  # [(name, fn)]
         self._after = []   # [(name, fn)]
 
     # ---------- 注册表 ----------
 
+# 生效条件：fn 可调用时先按 name 摘除同名项，再在 position 为 None 时把 (str(name), fn) 追加到链尾、否则插入 max(0, int(position))（position=0 非 None，走插入分支）；fn 不可调用则抛 TypeError；
     def register_before(self, name, fn, position=None):
         """注册 before 拦截器（同名幂等替换；position=None 追加到链尾）。
 
@@ -90,11 +93,13 @@ class WritePipeline:
         else:
             self._before.insert(max(0, int(position)), item)
 
+# 生效条件：按 str(name) 过滤 _before，仅保留 x[0] != str(name) 的项（即删除全部同名项），并返回删除前后长度是否不等以表示是否确有移除；
     def unregister_before(self, name):
         n0 = len(self._before)
         self._before = [x for x in self._before if x[0] != str(name)]
         return len(self._before) != n0
 
+# 生效条件：fn 可调用时先按 name 摘除同名项，再把 (str(name), fn) 追加到 _after 链尾；fn 不可调用则抛 TypeError；
     def register_after(self, name, fn):
         """注册 after 观察者：fn(ctx, out)，落盘成功后按序调用。"""
         if not callable(fn):
@@ -102,17 +107,20 @@ class WritePipeline:
         self.unregister_after(name)
         self._after.append((str(name), fn))
 
+# 生效条件：按 str(name) 过滤 _after，仅保留 x[0] != str(name) 的项（即删除全部同名项），并返回删除前后长度是否不等以表示是否确有移除；
     def unregister_after(self, name):
         n0 = len(self._after)
         self._after = [x for x in self._after if x[0] != str(name)]
         return len(self._after) != n0
 
+# 生效条件：无前置；返回 {"before": [...注册名], "after": [...注册名]}，只暴露名字不暴露函数对象，顺序即执行顺序；
     def names(self):
         return {"before": [n for n, _f in self._before],
                 "after": [n for n, _f in self._after]}
 
     # ---------- 执行 ----------
 
+# 生效条件：传入 cg 与 a（a 为假值如 None 时按 {} 处理，nid 取 a.get("node_id") 或其假值回落 "mem_"+毫秒时间戳），任一 before 钩子返回非 None 即记 halted_by 并经 _commit_visibility 短路返回该响应，全部放行则记 twophase 意图后跑 _executor（其抛 BaseException 时记 STATUS_ERROR 并原样重抛）再顺序跑 after 链、_commit_visibility 并返回落盘 out；
     def execute(self, cg, a):
         """写入请求入口：跑 before 链 → 链尾执行器 → after 链。
 
@@ -157,16 +165,23 @@ class WritePipeline:
 # 默认链（原 mcp_server._cg_dispatch op=="write" 分支，行为逐字节搬运）
 # --------------------------------------------------------------------------
 
+# 生效条件：ctx["a"] 经 audit.audit 得出的 state 为 ACCEPT 时返 None 放行，为 REJECT 时经 cg.add_rejected 返回 ok=False/moved_to="rejected"，其余 state 经 cg.propose 返回 moved_to="review_queue"（pr 带 dedup 时再附 dedup/dup_of/dup_status 并改写 hint）；
 def _gate_audit(ctx):
     """校验闸：audit.audit 四态。ACCEPT 放行；REJECT 负记忆；其余入审核队列。"""
     a = ctx["a"]
     cg = ctx["cg"]
     from . import audit
+    payload = {"content": a.get("content", ""), "action": a.get("action"),
+               "sensitivity": a.get("sensitivity"),
+               "topic": a.get("query") or a.get("intent")}
+    if (a.get("content_kind") or "").strip() == "hyperedge":
+        # 超边验证器（回放比对）需要锚与结构键：fm 键平铺在 a 顶层，
+        # 经 hyperedge.audit_payload 装配三键载荷（缺锚由验证器 fail-closed）。
+        from . import hyperedge as _he
+        payload = _he.audit_payload(a)
     verdict = audit.audit(
         (a.get("content_kind") or "").strip(),
-        {"content": a.get("content", ""), "action": a.get("action"),
-         "sensitivity": a.get("sensitivity"),
-         "topic": a.get("query") or a.get("intent")},
+        payload,
         {"cg": cg, "principal": getattr(cg, "principal", None)})
     ctx["verdict"] = verdict
     st = verdict["state"]
@@ -207,6 +222,7 @@ def _gate_audit(ctx):
     return out
 
 
+# 生效条件：ctx["a"]["consistency"] 为假值时返回 None；on_conflict 缺键或假值回落 "defer"，仅当 verdict=REJECT 且 on_conflict=reject（返回 moved_to="conflict_rejected"）或 verdict∈{REJECT,BLINDSPOT} 且 on_conflict=defer（转 review_queue，去重命中时改写 hint）才拦截，其余 on_conflict 取值返回 None；
 def _gate_consistency(ctx):
     """冲突闸：节点间自动冲突检测（三级决策）。
 
@@ -264,6 +280,7 @@ def _gate_consistency(ctx):
     return out
 
 
+# 生效条件：ctx["a"] 的 gated 为假值时返 None 放行；为真值时按 cg.remember_gated 返回的 verdict 落两段式账，且仅 verdict 为 ACCEPT 时 ok/committed 为 True，verdict 为 MERGE 时记 committed 并置 moved_to="merged_into:"+merged_into，verdict 为 DROP/DEFER 时记 aborted 且 moved_to 为其小写值；
 def _gate_gated(ctx):
     """主动遗忘闸（gated=true 时启用）：writelimit 限流 + forgetting 三问四态。
 
@@ -315,9 +332,126 @@ def _gate_gated(ctx):
         out["moved_to"] = "merged_into:" + str(res.get("merged_into"))
     elif v in ("DROP", "DEFER"):
         out["moved_to"] = v.lower()
+    # gated 是**替代落盘路径**（自行落盘/合并后直接返回终态、不跑 after 链），故
+    # 一跳同步传播须在此单独触发——否则 MERGE 类覆写会漏传下游（非对称边界，
+    # 与 `_after_trust` 注释互指）。
+    if committed or v == "MERGE":
+        prop = trust.mark_dependents(
+            cg, ctx["nid"],
+            reason="上游节点被 gated 写入/合并（内容或验证态可能已变）",
+            actor="writepipe:gated", trigger="write_gated")
+        if isinstance(prop, dict) and prop.get("changed"):
+            out["propagation"] = {"changed": prop.get("changed"),
+                                  "updated": (prop.get("updated") or [])[:10]}
     return out
 
 
+# 生效条件：ctx["a"]["content"] 的「# 子功能：」行含显式跨节点引用（`@<节点 id>`）且 depends_on 解析为空时返回 ok=False/error="E050" 的终态；depends_on 含库中不存在的 id 时返回 ok=False/error="E051" 的终态；其余（无该行 / 哨兵 / 自然语言自述 / 声明且目标齐备）返回 None 放行；
+def _gate_deps(ctx):
+    """依赖声明闸（before 链：linkref 之后、audit 之前）：**硬拒条件缺失**。
+
+    「声明」的界定（收窄裁定 b，2026-09-19）：以 `@<节点 id>` 显式引用为界——
+    自然语言**自述子功能**（描述本单元**内部**构成）不构成依赖声明。原因：CCG
+    编译产物六要素必含「子功能」行，若沿用「非哨兵即声明」，每个 CCG 节点落库后
+    都会被自己的闸门永久要求 depends_on（E050 死锁，test_ccgc V16f 实证）。
+    依赖不是必填元数据；**只有显式声称依赖却不落字段**才是违规（声称与落盘不一致）。
+
+    为何是硬拒而非告警：依赖是失效传播的**唯一入口**。声明缺失时，「上游变了
+    下游要存疑」这条链从源头就不存在——它既不报错、也不留任何信号，缺陷以
+    「静默不传播」的形态长期存活（比报错更难发现）。故按契约缺失处理，与
+    `ccgc` 的 E 码体系同构（E050 声明缺失 / E051 目标不存在）。
+
+    张力消解（与 provenance「写路径永不阻断」纪律的边界，二者不冲突）：
+      - **声明缺失 / 目标不可解析 = 契约违规** → 硬拒（本闸只做这件事）；
+      - **传播落盘失败 = 运维降级** → 告警不阻断（见 `_after_trust`）。
+
+    判据基于**入参**而非落盘后回读：首次写入时节点尚不存在，回读式校验会
+    永远放行（等于闸门失效）。
+    """
+    a = ctx["a"]
+    cg = ctx["cg"]
+    from . import nodefile
+    if not nodefile.declares_dependency(a.get("content") or ""):
+        return None
+    deps = trust.as_deps(a.get("depends_on"))
+    if not deps:
+        return {"ok": False, "id": ctx["nid"], "committed": False,
+                "gate": "deps", "error": "E050",
+                "verdict": ctx.get("verdict"),
+                "hint": ("依赖声明缺失（E050）：正文以 " + nodefile.DEP_REF_MARK
+                         + "<节点 id> 显式声明了跨节点依赖（「# 子功能：」行），"
+                           "但 depends_on 未给出可解析目标。依赖必须是**可解析的字段**"
+                           "（形如 depends_on=[\"<被依赖节点 id>\"]），不能只是散文——"
+                           "否则被依赖单元变动时，下游无处可传。补齐后重试；"
+                           "若该行只是描述本单元内部构成（自述），去掉 "
+                         + nodefile.DEP_REF_MARK + " 引用或改填「无」即可。"
+                           "本闸是契约闸门的正常行为，不是工具故障。")}
+    known = set((getattr(cg, "index", None) or {}).get("nodes") or {})
+    missing = [d for d in deps if d not in known]
+    if missing:
+        return {"ok": False, "id": ctx["nid"], "committed": False,
+                "gate": "deps", "error": "E051", "missing": missing[:10],
+                "verdict": ctx.get("verdict"),
+                "hint": "依赖目标不存在（E051）：depends_on 指向 "
+                        + ", ".join(missing[:5])
+                        + "，但库中查无此节点——声称依赖一个并不存在的地基，"
+                          "失效传播会在此处断链。请先建立被依赖节点，或修正 id。"}
+    return None
+
+
+# 生效条件：out 为 dict 且 out["committed"] 为真时，调 trust.mark_dependents 做一跳同步传播（异常吞掉并降级），并在节点时间轴非「时效内」时往 out 写 "validity" 提示；其余情况直接返回不做任何动作；
+def _after_trust(ctx, out):
+    """after 观察者：落盘后触发**一跳同步传播** + 时效提示。
+
+    为何落在 after 而非 before：只有真正落盘（内容确实变了）才构成「地基动了」；
+    before 链短路路径（REJECT / DEFER）本就不跑 after 链，语义天然正确。
+    例外：`gated` 是替代落盘路径（自行落盘并返回终态、不跑 after），故它的
+    传播在 `_gate_gated` 内部单独触发（见该处注释）。
+
+    **永不抛**：传播失败只降级（`trust.mark_dependents` 内部已兜底并写台账），
+    绝不把「写入已成功」改写为失败——与 `_commit_visibility` 同款边界。
+    """
+    if not isinstance(out, dict) or not out.get("committed"):
+        return
+    cg = ctx["cg"]
+    nid = ctx.get("nid")
+    if not nid:
+        return
+    prop = trust.mark_dependents(
+        cg, nid, reason="上游节点被写入/覆写（内容或验证态可能已变）",
+        actor="writepipe:trust", trigger="write")
+    if isinstance(prop, dict) and prop.get("changed"):
+        out["propagation"] = {"changed": prop.get("changed"),
+                              "updated": (prop.get("updated") or [])[:10]}
+    # 热路径失效（2026-09-19 热温冷分层）：写入后清缓存
+    try:
+        from . import hotcache as _hc
+        _hc.invalidate(cg, nid)
+    except Exception:                                  # noqa: BLE001
+        pass  # 缓存失效失败不阻断写入（永不抛）
+
+    # 冷路径入队（2026-09-19 热温冷分层）：异步深度验证
+    try:
+        from . import coldverify as _cv
+        _cv.enqueue(cg, nid, action="reverify",
+                    reason="writepipe:after_trust")
+    except Exception:                                  # noqa: BLE001
+        pass  # 入队失败不阻断写入
+
+
+# 生效条件：a 的 content_kind 非 hyperedge 即返回 {}，为 hyperedge 时延迟导入
+# hyperedge.EXTRA_FM_KEYS 收集 a 中非 None 的对应键返回（其余写入零键透传）；
+def _hyperedge_extra(a):
+    """hyperedge 写入的 fm 扩展键透传。计划决策 2：超边写入走 write 动词既有
+    审核链、不造新通道——链尾执行器是唯一落盘点，cg.add 经 **extra 落 fm，
+    故扩展键在此透传；落盘面丢字段 = 上游声明静默失效。延迟导入防循环依赖。"""
+    if (a.get("content_kind") or "").strip() != "hyperedge":
+        return {}
+    from . import hyperedge as _he
+    return {k: a[k] for k in _he.EXTRA_FM_KEYS if a.get(k) is not None}
+
+
+# 生效条件：由链尾以含 cg 与 a 的 ctx 调用即无条件执行 cg.add 落盘并返回 ok=True/committed=True，ctx["cvd"] 非 None 时附加 consistency 字段；
 def _executor(ctx):
     """链尾执行器（常驻不可卸载）：cg.add 直写落盘。
 
@@ -335,7 +469,13 @@ def _executor(ctx):
            non_applicable_conditions=a.get("non_applicable_conditions"),
            override=bool(a.get("override")), consistency=False,
            derived_from=_split_ids(a.get("derived_from")),
-           relation=a.get("relation"))
+           relation=a.get("relation"),
+           # 可验证记忆单元（裁定 D）：依赖/双时间轴/验证态随写入落 fm。
+           # 透传而非丢弃——落盘面丢字段＝上游声明静默失效（比报错难发现）。
+           depends_on=trust.as_deps(a.get("depends_on")),
+           valid_from=a.get("valid_from"), valid_until=a.get("valid_until"),
+           verification_state=a.get("verification_state"),
+           **_hyperedge_extra(a))
     out = {"ok": True, "id": ctx["nid"], "committed": True,
            "verdict": ctx["verdict"]}
     if ctx.get("cvd") is not None:
@@ -343,6 +483,7 @@ def _executor(ctx):
     return out
 
 
+# 生效条件：value 传入即无条件延迟导入并转调 mcp_server._split_ids 后原样返回其结果（本符号无自身分支）；
 def _split_ids(value):
     # 与 mcp_server._split_ids 同源（延迟导入，单一真源）
     from .mcp_server import _split_ids as _f
@@ -356,17 +497,47 @@ def _split_ids(value):
 _DEFAULT = None
 
 
+# 生效条件：pipe 传入即对其依次注册 before 的 linkref(position=0)/deps/audit/consistency/gated 与 after 的 linkref/trust（同名幂等替换），并返回同一 pipe；
 def install_default_gates(pipe):
-    """把默认六道闸以拦截器形态注册（幂等：同名替换，可重复调用）。"""
+    """把默认闸以拦截器形态注册（幂等：同名替换，可重复调用）。
+
+    链序（2026-09-19 起）：
+        before = linkref(解析) → deps(依赖声明) → audit → consistency → gated
+                 → 链尾执行器
+        after  = linkref(建边) → trust(一跳传播)
+
+    linkref 置于链首的理由：正文引用解析是**纯读、无副作用**，且其结果必须
+    先于任何短路闸写入 ctx，供 after 链消费。短路闸（REJECT/DEFER/gated）
+    返回终态时 `execute` 不跑 after 链，故未落盘的写入不会建边——语义正确。
+
+    deps 夹在 linkref 与 audit 之间的理由：两件事都与内容政策无关，故在 audit
+    之前；linkref 之后是因为它只解析正文引用、不动依赖声明——依赖是**字段域**
+    而非正文域，顺序倒置不会互相污染，但保持「解析在前、裁决在后」的一致读序。
+
+    after 的 trust 置于 linkref 之后：建边先于传播——传播按 `depends_on`
+    反查（字段域）而非边域，故顺序不影响正确性；置于其后只为让 ctx 中的
+    边信息先落定，便于排障时读 ctx。
+
+    linkref 的**落点是 after 而非注入 `a["edges"]`**：`cg.add` 是全量重建
+    fm，注入 edges 会在覆写既有节点时清空其原有边（破坏性副作用）；
+    `append_edge` 是边域窄原语且幂等（见 linkref 模块 docstring）。
+    依赖声明同忌经 `a["edges"]` 注入——走 `depends_on` 字段域。
+    """
+    from . import linkref
+    pipe.register_before("linkref", linkref.before_hook(), position=0)
+    pipe.register_before("deps", _gate_deps)
     pipe.register_before("audit", _gate_audit)
     pipe.register_before("consistency", _gate_consistency)
     pipe.register_before("gated", _gate_gated)
+    pipe.register_after("linkref", linkref.after_hook())
+    pipe.register_after("trust", _after_trust)
     return pipe
 
 
+# 生效条件：模块级 _DEFAULT 为 None 时新建 WritePipeline 并经 install_default_gates 注册后缓存返回，否则直接返回已缓存的 _DEFAULT 单例；
 def default_pipeline():
     """进程级默认写入链（单例）。自定义闸门 register_before 即插即拔。"""
     global _DEFAULT
     if _DEFAULT is None:
         _DEFAULT = install_default_gates(WritePipeline())
-    return _DEFAULT
+    return _DEFAULT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furongjun1999/dsh-memory",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "灵枢（Lingshu·líng shū）DeepSeek Harness 插件：完整大脑——长期记忆/知识飞轮/自我认知/递归反思接入 DSH，对话自动沉淀进 md_cg 认知图（md 文档）",
   "type": "module",
   "main": "lib/index.js",
@@ -78,7 +78,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --import tsx --test \"test/*.test.ts\"",
-    "prepare": "npm run build",
+    "prepare": "node -e \"const fs=require('fs');const tsc='node_modules/typescript/bin/tsc';fs.existsSync(tsc)?require('child_process').execFileSync(process.execPath,[tsc,'-p','tsconfig.json'],{stdio:'inherit'}):console.log('[prepare] 跳过构建：typescript 未安装（NODE_ENV=production 或 --omit=dev 会省略 devDependencies）——需要构建请用 npm install --include=dev')\"",
     "prepublishOnly": "npm run build && npm test"
   },
   "repository": {

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,9 @@
  * 模型请求组装 system prompt 时自动注入灵枢最近记忆
  * （`stg(op=timeline)`，最近记忆节点时间线），让记忆"自动可用"而不只依赖
  * Agent 主动调用 recall/think 工具。失败静默（不影响请求）。
+ * ⚠️ 该注入块的**稳定性**决定宿主是否新追加快照：内容没变时也必须照旧 push
+ * （宿主按渲染后的整段文本去重）；跳过 push 反而会各追加一份「有块/无块」的快照
+ * —— 详见 installMemoryHooks 里的长注释。
  *
  * ⚠️ 注入文本**必经** escapePromptBraces（src/lib/prompt_safety.ts，issue #16）：
  * 宿主对 context 文本做严格 `{{variable}}` 插值，裸 `{{` 会让每轮 assemble 抛错
@@ -126,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
 
 /** 分级递减渲染：按距当前的次序逐档收窄，早期条目信息量更大。
  *
@@ -159,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）时自动记忆整体停用：记忆真源是
@@ -200,19 +190,27 @@ 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}}`）必须保真落库，故只在注入副本上打断 `{{`。
@@ -220,8 +218,6 @@ export function installMemoryHooks(ctx: Context, mdcg: MdcgClient | null, opts:
               name: 'lingshu:auto-recall',
               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}）`)