@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/md_cg/progressive.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""progressive.py · 渐进式语义检索控制器（Progressive Semantic Retrieval）
+
+理论定位（使用者与 GPT 定稿，2026-09-14）：
+    语义解析的完整性与检索的必要性不是同一个问题——一句话不必完成完整
+    语义解析，往往已含足够检索线索。查询不是固定语义结构，而是**不断
+    收紧的约束集合**；检索本身成为语义理解的一部分。
+
+    不要追求「一句话完成语义理解」，而要从**最小可靠语义**开始，
+    通过检索获得上下文，再逐步增加条件，使语义收敛。
+
+    架构：AI 翻译 → 中文 → 基础语义组合 → 宽检索（少条件）→ 候选集合
+          → 逐步增加条件 → 精确语义判断。
+
+与灵枢既有机制的对接（全部已存在，本模块只补控制器壳）：
+    - 宽检索可行性    = bench_en_atoms_public 臂⑤⑥⑦实证：归一残缺 20%
+                        时 hit@10 仍 99.2-99.8——宽检索不要求完整归一；
+    - 四态控制器      = judge_qualification / judge_ranking（证据防火墙）：
+                        DEFER ≠ 失败 =「当前语义分辨率不足，继续获取条件」；
+    - 主动条件获取    = autonomy.explore 信息差驱动（Active Semantic
+                        Retrieval 的写侧对应物，后续增量汇合点）。
+
+代码职责（纯函数、确定性、评分器注入式）：
+    - core_subset()      Stage-1 宽检索核心子集（保序截断）；
+    - discriminative()   候选间区分度最大的未用原子（覆盖差，None=无
+                         区分性条件可加——诚实停止，不硬选）；
+    - progressive_search()  宽检索 → 区分度引导加条件 → 重排 的循环，
+                         返回逐阶段轨迹（可审计）。
+
+诚实边界：
+    1) 区分性条件词池由调用方给定（bench 侧=归一原子全集；引擎侧真实
+       系统应由 atoms.json 标准词表驱动——手工池只是评测示教）；
+    2) 零干扰池（567 全 gold）上渐进预期 ≈ 一次性全原子——机制价值
+       在归一残缺场景与受控干扰池（见 bench_progressive.py）；
+    3) 本模块不接 AI、不写库——DEFER 驱动的主动问询（向用户/环境获取
+       条件）是后续增量。
+"""
+from __future__ import annotations
+
+#: 区分度阈值：覆盖差 gap = 1-|2cov-1| ∈ (0,1]，低于此值不选
+#: （0 = 全命中/全不命中，加了不产生任何排序差异）。取小正数即可——
+#: 「最大区分度」排序本身已保证质量，阈值只排除零区分的无效条件。
+MIN_DISCRIM = 0.1
+
+
+def core_subset(atoms, ratio=0.5):
+    """Stage-1 宽检索核心子集：归一序列前 int(len*ratio) 个（保序，确定性）。
+
+    「最小可靠语义」的确定性近似——归一产物的前段通常是事件核心
+    （主体/动作），尾段多为修饰限定。ratio=1.0 退化为一次性全原子。
+    """
+    toks = [a for a in (atoms or ()) if a]
+    if not toks:
+        return []
+    n = max(1, int(len(toks) * ratio))
+    return toks[:n]
+
+
+def discriminative(unused, cand_sets, min_gap=MIN_DISCRIM):
+    """候选间区分度最大的未用原子（确定性：同 gap 取归一序列原序靠前者）。
+
+    unused:     候选条件词序列（保序）；
+    cand_sets:  当前 top 候选的原子集序列（frozenset）；
+    返回 gap 最大且 > min_gap 的原子；无 → None（无区分性条件可加）。
+    """
+    n = len(cand_sets)
+    if n < 2 or not unused:
+        return None
+    best, best_gap = None, float(min_gap)
+    for a in unused:
+        cov = sum(1 for s in cand_sets if a in s) / n
+        gap = 1.0 - abs(2.0 * cov - 1.0)     # cov=0.5 → 1.0；0/1 → 0.0
+        if gap > best_gap:
+            best, best_gap = a, gap
+    return best
+
+
+def progressive_search(rank_fn, atoms, cand_atoms,
+                       ratio=0.5, k=10, max_stages=4,
+                       cond_pool=None, min_gap=MIN_DISCRIM):
+    """渐进式语义检索主循环（评分器注入式，纯函数）。
+
+    rank_fn(atoms_list) -> [(cid, score), ...]  分数降序（bench 侧=原子
+        Jaccard；引擎侧=search_rrf 的适配包装——四态终排在引擎内生效）；
+    atoms:      归一原子全集（Stage-1 取 core_subset，后续按区分度补）；
+    cand_atoms: {cid: frozenset} 候选原子集（区分度观测面）；
+    cond_pool:  引擎侧的候选条件词池（bench 原子面缺省=atoms 未用部分）；
+    max_stages: 检索预算（最多 rank 次数，每阶段都被测量，不空转）。
+
+    返回轨迹：
+        stages: [{used, top}]   每阶段使用的条件与 top-k 候选 id；
+        added:  [atom]          逐阶段新增的区分性条件（refinement steps）；
+        converged: bool         无区分性条件可加而提前停止（True）或
+                                预算耗尽（False）。
+    """
+    toks = [a for a in (atoms or ()) if a]
+    if not toks:
+        return {"stages": [], "added": [], "converged": False}
+    used = core_subset(toks, ratio)
+    stages, added = [], []
+    converged = False
+    pool = list(cond_pool) if cond_pool else toks
+    for stage in range(max_stages):
+        ranked = rank_fn(used)
+        top = ranked[:k]
+        stages.append({"used": list(used),
+                       "top": [cid for cid, _s in top]})
+        if stage == max_stages - 1:
+            break
+        nxt = discriminative([a for a in pool if a not in used],
+                             [cand_atoms.get(cid, frozenset())
+                              for cid, _s in top],
+                             min_gap=min_gap)
+        if nxt is None:
+            converged = True          # 无条件可加：当前分辨率下已收敛
+            break
+        used = used + [nxt]
+        added.append(nxt)
+    return {"stages": stages, "added": added, "converged": converged}

package/md_cg/refindex.py

@@ -262,12 +262,16 @@ class Ledger:
 
 def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
               max_items: int = 2000, incremental: bool = False,
-              ledger: "Ledger" = None):
+              ledger: "Ledger" = None, skip_dirs=None):
     """按 kind 调度 codeindex / docindex 的全量（或增量）索引。
 
     incremental=True 且给了 ledger 时：未变文件跳过（`skipped_unchanged`）。
     返回 (items, errors, stats)，与底层 index_dir 的返回一致（多一个
     `skipped_unchanged`）。
+
+    `skip_dirs` 透传给底层：**追加**排除、只增不减（内置 `.git`/`.venv`/
+    `node_modules` 等不可被关闭），见 `codeindex.skip_matcher`。实际排掉了哪些目录
+    由 `stats["skipped_dirs"]` 回报，仍不静默。
     """
     mod = _mod(kind)
     fresh = None
@@ -290,7 +294,7 @@ def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
 
     items, errors, stats = mod.index_dir(
         root, patterns=patterns, max_files=max_files, max_items=max_items,
-        fresh=fresh, on_file=on_file,
+        fresh=fresh, on_file=on_file, skip_dirs=skip_dirs,
     )
     if ledger is not None:
         ledger.prune()
@@ -541,6 +545,167 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
     }
 
 
+# --------------------------------------------------------------------------
+# 节点级对账：孤儿清退 + 悬空清退
+#
+# 水位层的 `Ledger.reconcile` 只剪**水位条目**、`prune` 只剪「源大域已消失」
+# 的条目，两者都不碰**节点**。于是节点层的两类残留无人处置：
+#   · 孤儿（同一文档的过期代）——标题路径一变 id 全量重算，旧代与新代并存；
+#   · 悬空（源文件已删）——回读必然失败，巡检永远报 dangling。
+# 本节的唯一实现同时供 `op=index_code / index_doc`（孤儿）与
+# `op=ref action=prune`（悬空）使用，避免两处各写一套口径。
+# --------------------------------------------------------------------------
+
+def _norm_root(p) -> str:
+    """root 归一：同一目录的大小写/分隔符差异不得影响「同一大域」判定。"""
+    return os.path.normcase(os.path.abspath(str(p or "")))
+
+
+def _same_root(a, b) -> bool:
+    try:
+        return bool(a) and bool(b) and _norm_root(a) == _norm_root(b)
+    except (TypeError, ValueError):
+        return False
+
+
+def _norm_rel(p) -> str:
+    return str(p or "").replace("\\", "/").lstrip("./")
+
+
+def _forget_many(cg, plan, why: str) -> tuple:
+    """逐条软删（进 trash/、写删除清单、可 restore）；受保护节点拦下不删。
+
+    `forget` 属 **MdCGOS 层**能力（保护裁决 + 回收站 + 删除清单），基础层
+    `MdCG` 没有任何删除原语。缺能力时**明确报错、不静默跳过**——否则
+    「清退了 N 条」看着成功、实际一条没删（P27 §10 实测过这个坑）。
+    """
+    fn = getattr(cg, "forget", None)
+    if not callable(fn):
+        err = (f"{type(cg).__name__} 无 forget 能力（对账须能删除节点）；"
+               f"生产路径是 MdCGOS，测试请用 MdCGOS")
+        return [], [{"node_id": nid, "error": err} for nid in sorted(plan)]
+    done, blocked = [], []
+    for nid in sorted(plan):
+        try:
+            res = fn(nid, why) or {}
+        except Exception as exc:            # ProtectionError 等 → 拦下，不越权
+            blocked.append({"node_id": nid, "error": str(exc)[:120]})
+            continue
+        if res.get("ok"):
+            done.append(nid)
+        else:
+            blocked.append({"node_id": nid, "error": str(res.get("error"))[:120]})
+    return done, blocked
+
+
+def prune_orphans(cg, *, kind: str, root: str, items, dry_run: bool = False,
+                  reason: str = "") -> dict:
+    """清退「同 root + 同 path，但已不在本次产出里」的**过期代**节点。
+
+    为什么必须有：`node_id = sha1(相对path + "#" + heading_path)`，而
+    `add_items` 只做**同 id 幂等 upsert**——文档标题结构一变，整篇 id 全量
+    重算，旧代节点无人清退，与新代并存（同一文档召回两份，且旧代引用的区间
+    已失效）。截断的索引由调用方负责不调用本函数（没扫完 ≠ 剩下的都过期）。
+
+    范围**只限本次真正重切过的文件**（`items` 的 path）：增量索引跳过的未变
+    文件不在 items 里，其节点不进判定——否则会把完好的节点整片误删。
+    """
+    nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
+    touched: dict = {}
+    for it in items or []:
+        rel = _norm_rel(it.get("path"))
+        if rel:
+            touched.setdefault(rel, set()).add(node_id_of(it, kind))
+    base = {"scanned": len(nodes), "touched_files": len(touched),
+            "dry_run": bool(dry_run)}
+    if not touched:
+        return {**base, "ok": True, "count": 0, "pruned": [],
+                "skipped_protected": []}
+
+    # ⚠ ref 只存在于**节点 frontmatter**里；`cg.index['nodes']` 是元数据快照
+    # （path/layer/tags/…，见 mdcg._scan_nodes），**不含 ref**。因此必须
+    # `cg.get(nid)` 取回节点再 ref_of —— 否则 ref_of 恒返回 ('', None)、
+    # 整个对账静默失效（P27 §10 实测过这个坑）。标签预筛与 check_refs 同口径，
+    # 免得为全库每条记忆都读一次盘。
+    tag = "doc" if kind == "doc_ref" else "code"
+    plan = []
+    for nid, e in nodes.items():
+        if tag not in ((e or {}).get("tags") or []):
+            continue
+        try:
+            node = cg.get(nid)
+        except Exception:
+            continue
+        if not node:
+            continue
+        k, ref = ref_of(node)
+        if k != kind or not isinstance(ref, dict):
+            continue
+        keep = touched.get(_norm_rel(ref.get("path")))
+        if keep is None or nid in keep or not _same_root(ref.get("root"), root):
+            continue
+        plan.append(nid)
+
+    why = reason or ("索引重建：本节点已不在同文档新代产出中（标题路径变更致 "
+                     "node_id 重算），清退过期代以消除重复召回")
+    if dry_run:
+        return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
+                "skipped_protected": [], "reason": why}
+    done, blocked = _forget_many(cg, plan, why)
+    return {**base, "ok": True, "count": len(done), "pruned": done[:50],
+            "skipped_protected": blocked[:20], "reason": why}
+
+
+def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
+                   max_nodes: int = MAX_CHECK, reason: str = "") -> dict:
+    """清退**悬空**节点：ref 指向的源文件已删除，回读必然失败。
+
+    `check_refs` 只报告不处置（其原话是「悬空需人工处置」），本函数就是那个
+    出口——已删脚本、被搬走的文档留下的残留节点一次清掉，而不是逐条手工
+    `forget`。判定与巡检共用 `probe_ref` 的唯一实现，口径不会打架。
+    """
+    nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
+    # 同 prune_orphans：ref 只在节点 frontmatter 里，索引条目里没有，
+    # 必须 cg.get 取回节点再 ref_of（否则恒空、静默不删）。
+    todo = []
+    for nid, e in nodes.items():
+        tags = (e or {}).get("tags") or []
+        if not any(t in ("code", "doc") for t in tags):
+            continue
+        try:
+            node = cg.get(nid)
+        except Exception:
+            continue
+        if not node:
+            continue
+        _k, ref = ref_of(node)
+        if not ref or not ref.get("root"):
+            continue
+        if only_roots and not any(_same_root(ref.get("root"), r) for r in only_roots):
+            continue
+        todo.append((nid, ref))
+    truncated = len(todo) > max_nodes
+    plan = []
+    for nid, ref in todo[:max_nodes]:
+        try:
+            if probe_ref(ref).get("status") == "dangling":
+                plan.append(nid)
+        except Exception:                   # 探测失败不算悬空（宁可不删）
+            continue
+
+    why = reason or ("源文件已删除，索引节点悬空（回读必然失败），"
+                     "清退以消除永不消失的 dangling")
+    base = {"scanned": len(nodes), "candidates": len(plan),
+            "dry_run": bool(dry_run), "truncated": truncated,
+            "max_nodes": max_nodes}
+    if dry_run:
+        return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
+                "skipped_protected": [], "reason": why}
+    done, blocked = _forget_many(cg, plan, why)
+    return {**base, "ok": True, "count": len(done), "pruned": done[:50],
+            "skipped_protected": blocked[:20], "reason": why}
+
+
 def rebuild(cg, *, ledger: "Ledger" = None, only_roots=None, max_files: int = 500,
             max_items: int = 2000) -> dict:
     """按 ref 记录的 root 重建索引（sustain.heal 的修复动作）。

package/md_cg/self_state.py

@@ -11,12 +11,12 @@
 由此定下本模块的形态：
 
     self 层只放两类一等公民（都很薄）：
-      1. 自我状态卡（单例）——八项自我信息的**当前值 + 指针**
+      1. 自我状态卡（单例）——九项自我信息的**当前值 + 指针**
       2. 关系节点（有向）——自我与其他智能的关系
     具体细节（哪次会话 / 哪个任务 / 哪个人 / 哪个时间窗 / 哪条证据）
     仍然留在原本的层里，由**认知图的标签与边**连接、索引过来。
 
-八项自我信息 → 薄卡字段 / 富索引指向：
+九项自我信息 → 薄卡字段 / 富索引指向：
 
   ┌ 信息差 D   d_current / d1 / d2 / emotion      ← _reflection.jsonl（reflect 留痕）
   ├ 信任 P     p_gap / p_trust / d2t / affect     ← 各节点 evidence_log（verify 留痕）
@@ -25,7 +25,12 @@
   ├ 短期记忆   recent{n, span, roles, ptr}        ← _recent.jsonl（只存摘要 + 指针）
   ├ 重要性     importance_self / important_refs   ← 各节点 frontmatter.importance
   ├ 身份       identity_ref                       ← self 层 identity 锚点
-  └ 关系       relations{out,in}                  ← self_relation_* 关系节点
+  ├ 关系       relations{out,in}                  ← self_relation_* 关系节点
+  └ 预测校准   hit_rate / threshold / reflect / ece  ← _prediction.jsonl + evidence_log
+
+第九项（预测校准）是「SELF = 自我描述」走向「SELF = 关于自身的预测模型」的最小一步：
+它回答**我预测得准吗、该不该反思**，数据只来自 predict 的 feedback 留痕与
+metacognition 的 ECE 校准，样本不足一律 unknown——不新增计算，也不编造。
 
 五个索引维度（「具体任务 / 人物关系 / 会话 / 时间 / 信任」）用 tag 命名空间落地，
 `index(cg, dim, value)` 从全图反查；状态卡只登记维度标签、不搬运内容：
@@ -191,8 +196,9 @@ def snapshot(cg, subject=DEFAULT_SUBJECT):
            "state_ts": fm.get("state_ts"),
            "updated_at": _iso(fm.get("state_ts"))}
     for key in ("information_gap", "trust", "short_term", "relations",
-                "dimensions", "emotion", "affect", "importance_self",
-                "important_refs", "identity_ref", "state_links"):
+                "prediction", "dimensions", "emotion", "affect",
+                "importance_self", "important_refs", "identity_ref",
+                "state_links"):
         out[key] = fm.get(key)
     out["d_current"] = (fm.get("information_gap") or {}).get("d_current")
     out["p_trust"] = (fm.get("trust") or {}).get("p_trust")
@@ -216,6 +222,7 @@ def _fingerprint(state):
         "identity_ref": state.get("identity_ref"),
         "short_term": state.get("short_term"),
         "relations": state.get("relations"),
+        "prediction": state.get("prediction"),
         "dimensions": state.get("dimensions"),
         "state_links": state.get("state_links"),
     }
@@ -223,7 +230,52 @@ def _fingerprint(state):
     return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
 
 
-# ---------------------------------------------------------------- 聚合（八项）
+# ---------------------------------------------------------------- 聚合（九项）
+
+def _prediction_face(cg):
+    """预测校准（第九项）：我预测得准吗、该不该反思？
+
+    数据源（只读留痕，不新增计算负担）：
+      · `predict._hit_history` / `predict.dynamic_hit_threshold`
+        ← `_prediction.jsonl`（predict_feedback 留痕）
+      · `metacognition.calibration` ← evidence_log（verify 留痕）的 ECE
+
+    诚实边界：无预测留痕 → ok=False、hit_rate=None（未知即未知）；
+    ECE 仅在 metacognition 有足够证据时给出，否则 None。绝不编造。
+    """
+    try:
+        from . import predict as _predict
+        hist = list(_predict._hit_history(cg))
+        th = _predict.dynamic_hit_threshold(cg)
+        # P-T-73/74 通道贝叶斯：可信度后验（随样本量向基线收缩，诚实小样本）
+        beta = (_predict.channel_posterior(cg) or {}).get("all") or {}
+    except Exception:                                      # noqa: BLE001
+        hist, th, beta = [], {}, {}
+    samples = len(hist)
+    hit_rate = (sum(1 for x in hist if x) / samples) if samples else None
+    try:
+        cal = metacognition.calibration(cg)
+    except Exception:                                      # noqa: BLE001
+        cal = {}
+    if samples == 0:
+        note = "无预测留痕：先 predict_feedback() 积累命中记录"
+    elif th.get("reflect"):
+        note = "命中率低于动态阈值：建议反思（D-006）"
+    else:
+        note = "命中率正常"
+    return {
+        "ok": samples > 0,
+        "samples": samples,
+        "hit_rate": None if hit_rate is None else round(hit_rate, 4),
+        "beta_mean": beta.get("mean"),
+        "beta_ci95": beta.get("ci95"),
+        "threshold": th.get("threshold"),
+        "reflect": bool(th.get("reflect")),
+        "ece": cal.get("ece") if cal.get("ok") else None,
+        "calibration": cal.get("verdict") if cal.get("ok") else None,
+        "note": note,
+    }
+
 
 def _recent_summary(cg, window):
     """短期记忆：只做窗口摘要，原文仍留在 _recent.jsonl（薄自我的关键取舍）。"""
@@ -287,7 +339,7 @@ def _normalize_dimensions(dimensions):
 
 def _derive(cg, subject, window, importance, important_refs, dimensions,
             links, old):
-    """聚合八项自我信息 → 薄状态（纯读，不写盘）。"""
+    """聚合九项自我信息 → 薄状态（纯读，不写盘）。"""
     tr = metacognition.trace(cg, window=max(2, int(window)))
     tt = metacognition.trust(cg, window=max(3, int(window)))
     d2 = tr.get("d2") if tr.get("ok") else None
@@ -335,6 +387,7 @@ def _derive(cg, subject, window, importance, important_refs, dimensions,
             "short_term": short_term, "importance_self": importance,
             "important_refs": important_refs, "identity_ref": identity_ref,
             "identity_anchors": n_anchors, "relations": relations,
+            "prediction": _prediction_face(cg),
             "dimensions": dims,
             "state_links": [str(x) for x in links if str(x).strip()]}
 
@@ -345,6 +398,7 @@ def _render(state):
     """状态卡正文：人类可读，且与 frontmatter 字段一一对应。"""
     ig, tt = state["information_gap"], state["trust"]
     st = state["short_term"]
+    pd = state.get("prediction") or {}
     dims = state["dimensions"]
     span = st.get("span")
     span_txt = f"{_iso(span[0])} ~ {_iso(span[1])}" if span else "（无）"
@@ -368,6 +422,11 @@ def _render(state):
         f"（共 {state.get('identity_anchors')} 条）",
         f"# 关系：出 {state['relations'].get('out')} / "
         f"入 {state['relations'].get('in')}",
+        f"# 预测：命中率={pd.get('hit_rate')}（样本 {pd.get('samples')}）"
+        f"阈值={pd.get('threshold')} 反思={'是' if pd.get('reflect') else '否'}"
+        f"；后验可信度={pd.get('beta_mean')}"
+        f"（95%CI {pd.get('beta_ci95')}）"
+        f"；ECE={pd.get('ece')}（{pd.get('calibration')}）",
         "# 索引：" + "；".join(
             f"{d}={','.join(dims.get(d) or []) or '-'}" for d in DIMENSIONS),
         "# 说明：本卡是薄自我——只登记当前值与指针；具体任务/人物/会话/"
@@ -379,7 +438,7 @@ def _render(state):
 def refresh(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW, importance=None,
             important_refs=None, dimensions=None, links=None,
             actor="self_state", force=False, strict=False, session=None):
-    """刷新自我状态卡（幂等）：聚合八项 → 写卡 + 版本链留痕。
+    """刷新自我状态卡（幂等）：聚合九项 → 写卡 + 版本链留痕。
 
     dimensions: {"task": "...", "person": "...", "session": "...",
                  "time": "...", "trust": "..."}（值可为列表）
@@ -467,6 +526,7 @@ def refresh(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW, importance=None,
            importance_self=state["importance_self"],
            important_refs=state["important_refs"],
            identity_ref=state["identity_ref"], relations=state["relations"],
+           prediction=state["prediction"],
            dimensions=state["dimensions"], state_links=state["state_links"])
 
     _append_log(cg, {
@@ -486,6 +546,10 @@ def refresh(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW, importance=None,
         "recent_n": state["short_term"].get("n"),
         "identity_ref": state["identity_ref"],
         "relations": state["relations"],
+        "prediction_hit_rate": (state.get("prediction") or {}).get("hit_rate"),
+        "prediction_samples": (state.get("prediction") or {}).get("samples"),
+        "prediction_reflect": (state.get("prediction") or {}).get("reflect"),
+        "prediction_beta_mean": (state.get("prediction") or {}).get("beta_mean"),
         "dimensions": state["dimensions"], "issue": chain_issue})
     return {"ok": True, "changed": True, "subject": subject, "node_id": nid,
             "state_version": version, "state_hash": state["state_hash"],
@@ -693,6 +757,24 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
                                  f"{name} 不可比较：{old_v} vs {new_v}",
                                  field=name))
 
+    # 5b 预测面漂移：预测能力（命中率）随 predict_feedback 演化；卡值过时即为
+    #    漂移——这是「自我模型是否跟上自身预测表现」的可重算判定。
+    pd_old = st.get("prediction") or {}
+    pd_new = now.get("prediction") or {}
+    o_hr, n_hr = pd_old.get("hit_rate"), pd_new.get("hit_rate")
+    if not (o_hr is None and n_hr is None):
+        try:
+            if o_hr is None or n_hr is None or \
+                    abs(float(o_hr) - float(n_hr)) > DRIFT_TOL:
+                issues.append(_issue(
+                    "prediction_drift", "warn",
+                    f"预测命中率 卡值={o_hr} 现算={n_hr}（容差 {DRIFT_TOL}）",
+                    field="hit_rate"))
+        except (TypeError, ValueError):
+            issues.append(_issue("prediction_drift", "warn",
+                                 f"预测命中率不可比较：{o_hr} vs {n_hr}",
+                                 field="hit_rate"))
+
     # 6 身份唯一：identity_ref 必须指向存在的锚点
     ref = st.get("identity_ref")
     if not ref:
@@ -835,6 +917,8 @@ def summary(cg, subject=DEFAULT_SUBJECT, session=None):
             "recent_n": (st.get("short_term") or {}).get("n"),
             "relations": st.get("relations"),
             "identity_ref": st.get("identity_ref"),
+            "hit_rate": (st.get("prediction") or {}).get("hit_rate"),
+            "prediction_reflect": (st.get("prediction") or {}).get("reflect"),
             "text": (f"[{subject}] D={ig.get('d_current')} "
                      f"情绪={st.get('emotion')} P_trust={tt.get('p_trust')} "
                      f"情感={st.get('affect')} "
@@ -844,7 +928,7 @@ def summary(cg, subject=DEFAULT_SUBJECT, session=None):
 
 
 def catalog():
-    """自描述：八项自我信息 + 五维索引 + 审计规则（供协议对照验证）。"""
+    """自描述：九项自我信息 + 五维索引 + 审计规则（供协议对照验证）。"""
     return {
         "module": "self_state",
         "schema": SCHEMA_VERSION,
@@ -864,6 +948,7 @@ def catalog():
             "importance": "importance_self + important_refs",
             "identity": "identity_ref → self 层身份锚点",
             "relations": "self_relation_* 有向关系节点",
+            "prediction": "hit_rate/threshold/reflect + ECE ← _prediction.jsonl",
         },
         "dimensions": list(DIMENSIONS),
         "trust_bands": [b for _lo, b in TRUST_BANDS],
@@ -871,7 +956,8 @@ def catalog():
         "audit_rules": [
             "duplicate_state", "version_gap", "chain_broken",
             "time_regression", "log_tail_mismatch", "fabricated_emotion",
-            "fabricated_affect", "drift", "identity_missing",
+            "fabricated_affect", "drift", "prediction_drift",
+            "identity_missing",
             "identity_dangling", "relation_self_loop", "duplicate_relation",
             "protection_locked", "protection_missing", "unknown_dimension",
             "dimension_orphan", "stale", "missing_state",