@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/statushdr.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 状态摘要协议（MCP 输出面一等公民）
+
+【为什么】验证态若只在 frontmatter / 索引里躺着，读面就得「先知道去哪查」——
+与纪律只存在于认知图时执行率近零同构。故把状态**推进每一次返回体**：
+人类与 agent 读面一致，默认开启。
+
+四符号（`HEAD_MARKS`）：
+    ✓ 已验证   证据在位、依赖未动、时效内
+    △ 已修改   复核中（上游动过，复核进行态）
+    ! 异常     已过期（时效失效）或依赖目标悬空——**地基动了**
+    ? 存疑     依赖变动后被自动标记，待复核
+（未验证补 `·`：不是四态之一，但读面需要一个「尚未验证」的可视锚点。）
+
+【怎么做】在 `_cg_call` **单一出口**统一挂 `status_head` 并升级既有 `hint`——
+29+ 个 op 分支一处不改，爆炸半径最小。注入仅对返回体中**实际出现的节点 id**
+计算（O(k)，受 `k` 与 MAX_IDS 约束），不做全库扫描。
+
+【关闭】`MDCG_STATUS_HEAD=0` 回退旧 hint 文本（灰度/排障用）。
+
+零第三方依赖（D-005）。
+"""
+from __future__ import annotations
+
+import os
+
+from . import trust
+
+#: 四符号（读面契约，勿随意改字形——agent 侧提示词按此对齐）
+MARK_VERIFIED = "✓"
+MARK_MODIFIED = "△"
+MARK_ABNORMAL = "!"
+MARK_DOUBTED = "?"
+MARK_UNVERIFIED = "·"
+HEAD_MARKS = (MARK_VERIFIED, MARK_MODIFIED, MARK_ABNORMAL, MARK_DOUBTED)
+
+ENV = "MDCG_STATUS_HEAD"
+#: 注入上限：单次返回体最多为这么多节点计算状态头（防大结果集拖慢出口）
+MAX_IDS = 50
+
+
+def enabled() -> bool:
+    """状态头开关（默认开启；`MDCG_STATUS_HEAD=0` 回退旧 hint 文本）。"""
+    v = (os.environ.get(ENV) or "").strip().lower()
+    return v not in ("0", "false", "no", "off")
+
+
+def _mark(state: str, valid_kind: str, dangling: bool) -> str:
+    if dangling or valid_kind == "expired" or state == "expired":
+        return MARK_ABNORMAL
+    if state == "doubted":
+        return MARK_DOUBTED
+    if state == "rechecking":
+        return MARK_MODIFIED
+    if state == "verified":
+        return MARK_VERIFIED
+    return MARK_UNVERIFIED
+
+
+def _label(mark: str) -> str:
+    return {MARK_VERIFIED: "已验证", MARK_MODIFIED: "已修改",
+            MARK_ABNORMAL: "异常", MARK_DOUBTED: "存疑",
+            MARK_UNVERIFIED: "未验证"}.get(mark, "未验证")
+
+
+def render(cg, node_id: str, *, node: dict = None, index_entry: dict = None,
+           now: float = None) -> str:
+    """单条状态头字符串（附方式 / 时间 / 影响范围 / 待确认条件）。只读不抛。"""
+    try:
+        e = index_entry
+        if e is None:
+            e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
+        fm = (node or {}).get("frontmatter") if node else None
+        if fm is None:
+            fm = e or {}
+        state = trust.state_of(fm)
+        kind, _s, _e = trust.validity(fm, now=now)
+        deps = trust.as_deps(fm.get(trust.DEPS_FIELD))
+        known = set((getattr(cg, "index", None) or {}).get("nodes") or {})
+        dangling = [p for p in deps if p not in known]
+        mark = _mark(state, kind, bool(dangling))
+        bits = []
+        if dangling:
+            bits.append(f"依赖目标缺失：{','.join(dangling[:3])}")
+        if kind == "expired":
+            bits.append("时效已过")
+        elif kind == "not_yet":
+            bits.append("尚未生效")
+        method = (fm.get("verification_method") or fm.get("verification_basis")
+                  or "")
+        if method and mark == MARK_VERIFIED:
+            bits.append(f"方式={str(method)[:40]}")
+        if mark == MARK_DOUBTED:
+            bits.append("上游变动，待复核")
+        if mark in (MARK_VERIFIED, MARK_MODIFIED) and fm.get("verified_at"):
+            try:
+                import time as _t
+                bits.append("验证于 " + _t.strftime(
+                    "%Y-%m-%d", _t.localtime(float(fm["verified_at"]))))
+            except Exception:                              # noqa: BLE001
+                pass
+        return f"{mark} {_label(mark)}" + (f"（{'；'.join(bits)}）" if bits else "")
+    except Exception as exc:                               # noqa: BLE001
+        return f"{MARK_UNVERIFIED} 未验证（状态头降级：{type(exc).__name__}）"
+
+
+#: 返回体中可能承载节点 id 的键（显式枚举，避免把任意字符串误当 id）
+_ID_KEYS = ("node_id", "id", "nid")
+
+
+def _collect_ids(obj, acc: list, depth: int = 0) -> None:
+    """递归收集候选节点 id（深度/数量双上限；找不到就不找，绝不猜）。"""
+    if len(acc) >= MAX_IDS or depth > 4:
+        return
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if k in _ID_KEYS and isinstance(v, str) and v:
+                acc.append(v)
+            elif isinstance(v, (dict, list)):
+                _collect_ids(v, acc, depth + 1)
+                if len(acc) >= MAX_IDS:
+                    return
+    elif isinstance(obj, list):
+        for it in obj:
+            _collect_ids(it, acc, depth + 1)
+            if len(acc) >= MAX_IDS:
+                return
+
+
+def attach_heads(cg, out: dict, *, now: float = None) -> dict:
+    """扫描返回体中的节点 id，批量挂 `status_head`（O(k)，幂等）。"""
+    if not isinstance(out, dict):
+        return out
+    ids, seen = [], set()
+    _collect_ids(out, ids)
+    known = (getattr(cg, "index", None) or {}).get("nodes") or {}
+    heads = {}
+    for nid in ids:
+        if nid in seen or nid not in known:
+            continue
+        seen.add(nid)
+        heads[nid] = render(cg, nid, index_entry=known.get(nid), now=now)
+    if not heads:
+        return out
+    out["status_heads"] = heads
+    out["status_head"] = (next(iter(heads.values())) if len(heads) == 1
+                          else f"{len(heads)} 节点（见 status_heads）")
+    return out
+
+
+def annotate(cg, out: dict, *, now: float = None) -> dict:
+    """**单出口**注入口：挂状态头 + 把既有 `hint` 升级为状态头格式。
+
+    幂等：已注入过（`status_head` 在返回体中）则不再重复改写 hint。
+    """
+    if not enabled() or not isinstance(out, dict):
+        return out
+    if "status_head" in out:
+        return out
+    before_hint = out.get("hint")
+    attach_heads(cg, out, now=now)
+    head = out.get("status_head")
+    if head and before_hint:
+        out["hint"] = f"{head} · {before_hint}"
+    elif head:
+        out["hint"] = head
+    return out
+
+
+def catalog() -> dict:
+    """自描述（供 MCP catalog / 人工核对）。"""
+    return {
+        "layer": "状态摘要协议",
+        "marks": {"verified": MARK_VERIFIED, "modified": MARK_MODIFIED,
+                  "abnormal": MARK_ABNORMAL, "doubted": MARK_DOUBTED,
+                  "unverified": MARK_UNVERIFIED},
+        "env": ENV, "default_on": True, "max_ids": MAX_IDS,
+        "note": "统一在 _cg_call 单出口注入；hint 同步升级（Q3 默认开启）",
+    }

package/md_cg/stg.py

@@ -14,6 +14,8 @@
 """
 from __future__ import annotations
 
+from . import trust
+
 TIME_RELATIONS = ("before", "after", "equals", "contains", "during", "overlaps")
 SPACE_RELATIONS = ("left_of", "right_of", "above", "below",
                    "contains", "inside", "overlaps")
@@ -23,12 +25,26 @@ PLACEHOLDER_LOCKED = "[密文·预览已脱敏]"
 PLACEHOLDER_DENIED = "[无权限·预览已脱敏]"
 
 
-def _interval(fm):
-    """节点时间区间：优先 temporal（事件时刻），回退 condition_space.time_window（观测窗）。
+# 生效条件：time_axis 经 trust.time_axis_of 归一（None → observed，非法轴如 believed 抛 ValueError）；observed 轴下 fm 的 temporal 非 None 且 float(t) 可成功时返回 (float(t), float(t))，temporal 缺失/为 None/转换抛 TypeError 或 ValueError 时回退到 fm["condition_space"]（假值按 {} 处理）的 time_window，仅当其为长度 2 的 list/tuple 且两元素可 float 时返回 (float(tw[0]), float(tw[1]))，否则返回 None；effective 轴下取 trust.time_window_of(fm, "effective") 的两端点，两端均可解析才返回 (float(s), float(e))，任一端缺失或不可解析返回 None。
+def _interval(fm, time_axis="observed"):
+    """节点时间区间；轴语义与 `trust.time_window_of` **同源**（唯一口径，不新写解析）。
+
+    · `observed`（默认，与旧行为**逐位一致**）：优先 `temporal`（事件时刻），
+      回退 `condition_space.time_window`（观测窗）。
+      注意 add() 在调用方未给 time_window 时会以「写入时刻」自动填充；
+      若把它当事件时间，两条不同时刻的节点会得到假的重叠关系，故 temporal 优先。
+    · `effective`（效力轴）：`effective_from` / `effective_until` 及其别名
+      （`trust.FROM_ALIASES` / `UNTIL_ALIASES`，规范键优先、别名回落）。
+      区间语义要求**两端齐备**——单侧缺失/不可解析 → `None`（不可判定，
+      不猜测边界：给半开区间补 `±inf` 会让 `time_relation` 报出假的 contains/during）。
 
-    注意 add() 在调用方未给 time_window 时会以「写入时刻」自动填充；
-    若把它当事件时间，两条不同时刻的节点会得到假的重叠关系，故 temporal 优先。
+    `believed_at` **永不参与任何轴**（同 `trust.BELIEVED_FIELD` 的隔离纪律）。
     """
+    if trust.time_axis_of(time_axis) == "effective":
+        s, e = trust.time_window_of(fm, "effective")
+        if s is None or e is None:
+            return None
+        return (float(s), float(e))
     t = fm.get("temporal")
     if t is not None:
         try:
@@ -45,6 +61,7 @@ def _interval(fm):
     return None
 
 
+# 生效条件：fm["spatial"]（假值按 {} 处理）为 dict 且其 bbox 是长度 4 的 list/tuple 且四元素可 float 时返回浮点四元组，spatial 非 dict、bbox 非长度 4 序列或元素转换抛 TypeError/ValueError 时返回 None。
 def _bbox(fm):
     sp = fm.get("spatial") or {}
     bb = sp.get("bbox") if isinstance(sp, dict) else None
@@ -56,6 +73,7 @@ def _bbox(fm):
     return None
 
 
+# 生效条件：a、b 均非 None 且各可解包为两个元素时，按 a 相对 b 依次返回 equals（两端全等）、before（a2<b1）、after（a1>b2）、contains（a1<=b1 且 a2>=b2）、during（a1>=b1 且 a2<=b2）或 overlaps（其余）；a 或 b 为 None 时返回 None；
 def time_relation(a, b):
     """Allen 区间代数的 6 个基本态。"""
     if a is None or b is None:
@@ -74,6 +92,7 @@ def time_relation(a, b):
     return "overlaps"
 
 
+# 生效条件：a 或 b 为 None 时返回 None，否则按 a=(ax1,ay1,ax2,ay2)、b=(bx1,by1,bx2,by2) 依序判定 ax2<=bx1→"left_of"、ax1>=bx2→"right_of"、ay2<=by1→"above"、ay1>=by2→"below"、四边全含→"contains"、四边全被含→"inside"，全部不满足时返回 "overlaps"。
 def space_relation(a, b):
     """RCC-8 简化的 7 个空间态（图像坐标：y 向下为正）。"""
     if a is None or b is None:
@@ -97,6 +116,7 @@ def space_relation(a, b):
 
 # ---------- 查询实现 ----------
 
+# 生效条件：cg.get(node_id) 为真值（非 None、非空映射）时返回 {"id": node_id, "frontmatter": n.get("frontmatter") or {}（假值回落 {}）, "content": n.get("content") or ""（假值回落 ""）}，cg.get(node_id) 为假值时返回 None。
 def _node(cg, node_id):
     n = cg.get(node_id)
     if not n:
@@ -105,6 +125,7 @@ def _node(cg, node_id):
             "content": n.get("content") or ""}
 
 
+# 生效条件：cg.index["nodes"] 存在时按 list(...items())[:max_scan] 遍历，layer 为真值时仅保留 e.get("layer")==layer 的条目（layer 为假值不筛层），e 含 "temporal" 或 "spatial" 键时直接以快照字段构造 frontmatter、否则调用 cg._read(e) 且在 fm 为 None 时跳过；返回 out 列表（max_scan=None 切片取全部，0 时为空）；
 def _scan(cg, layer=None, max_scan=5000):
     """遍历节点：时空字段直接读索引快照（不读文件，O(1)/节点）。
 
@@ -116,7 +137,14 @@ def _scan(cg, layer=None, max_scan=5000):
         if layer and e.get("layer") != layer:
             continue
         if "temporal" in e or "spatial" in e:
+            # 效力轴四键必须一并从快照带出：否则 `time_axis="effective"` 在快照
+            # 路径上永远「不可判定」（静默全空，比报错更难查）。旧索引快照无这些
+            # 键时 `.get` 得 None → 不可判定，是本轴**如实降级**而非误判。
             fm = {"temporal": e.get("temporal"), "spatial": e.get("spatial"),
+                  trust.EFFECTIVE_FROM_FIELD: e.get(trust.EFFECTIVE_FROM_FIELD),
+                  trust.EFFECTIVE_UNTIL_FIELD: e.get(trust.EFFECTIVE_UNTIL_FIELD),
+                  trust.FROM_FIELD: e.get(trust.FROM_FIELD),
+                  trust.UNTIL_FIELD: e.get(trust.UNTIL_FIELD),
                   "condition_space": {"time_window": e.get("time_window")}}
         else:
             fm, _content = cg._read(e)
@@ -127,6 +155,7 @@ def _scan(cg, layer=None, max_scan=5000):
     return out
 
 
+# 生效条件：cg.index["nodes"].get(node_id) 缺失或为假值时返回 ""；否则 cg._readable 可调用且对其返回假值或抛异常时返回 PLACEHOLDER_DENIED；cg._read(e) 的 frontmatter 为 None 时返回 ""；content 非密文时返回 content[:n]（n 默认 200）；content 为密文时，cg._open_content 可调用且取到非 None 且非密文的 opened 才返回 opened[:n]，opened 为 None、抛异常或仍为密文时返回 PLACEHOLDER_LOCKED。
 def _preview(cg, node_id, n=200):
     """按需读单个节点正文做预览（只发生在最终返回的条目上）。
 
@@ -165,13 +194,15 @@ def _preview(cg, node_id, n=200):
     return opened[:n]
 
 
-def relation(cg, a_id, b_id):
-    """两节点间的时空关系（a 相对 b）。"""
+# 生效条件：cg 上 _node(cg, a_id) 与 _node(cg, b_id) 均返回真值时返回含 a_id/b_id、时间关系、空间关系和 time_known/space_known 的 dict（两侧时间区间均按 time_axis 轴取，见 _interval；time_axis 非法经 trust.time_axis_of 抛 ValueError）；任一 _node 结果为假值时返回 {"error":"node_not_found","missing":[...]}；
+def relation(cg, a_id, b_id, time_axis="observed"):
+    """两节点间的时空关系（a 相对 b）。`time_axis` 决定时间区间取哪条轴（见 `_interval`）。"""
     na, nb = _node(cg, a_id), _node(cg, b_id)
     if not na or not nb:
         return {"error": "node_not_found",
                 "missing": [x for x, n in ((a_id, na), (b_id, nb)) if not n]}
-    ia, ib = _interval(na["frontmatter"]), _interval(nb["frontmatter"])
+    ia, ib = (_interval(na["frontmatter"], time_axis),
+              _interval(nb["frontmatter"], time_axis))
     ba, bb = _bbox(na["frontmatter"]), _bbox(nb["frontmatter"])
     return {"a": a_id, "b": b_id,
             "time": {"relation": time_relation(ia, ib), "a": ia, "b": ib},
@@ -180,23 +211,27 @@ def relation(cg, a_id, b_id):
                      "space_known": ba is not None and bb is not None}}
 
 
-def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000):
-    """按时间排序的节点列表。"""
+# 生效条件：以 _scan(cg,layer=layer,max_scan=max_scan) 为范围，_interval(n["frontmatter"], time_axis) 为 None 的节点被跳过，其余按 (start,end) 以 reverse=bool(desc) 排序，返回 count=全部命中数、limit=传入 limit、items 为排序后前 limit 项（limit=0 时为空列表）且每项附 _preview(cg,id)（time_axis 缺省 observed，与旧行为逐位一致；非法轴抛 ValueError）。
+def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000,
+             time_axis="observed"):
+    """按时间排序的节点列表。`time_axis` 决定排序依据的时间区间（见 `_interval`）。"""
     items = []
     for n in _scan(cg, layer=layer, max_scan=max_scan):
-        iv = _interval(n["frontmatter"])
+        iv = _interval(n["frontmatter"], time_axis)
         if iv is None:
             continue
         items.append((iv[0], iv[1], n["id"], n["layer"]))
-    items.sort(key=lambda x: (x[0], x[1]), reverse=bool(desc))
+    items.sort(key=lambda x: (x[0], x[1], x[2]), reverse=bool(desc))
     return {"count": len(items), "limit": limit,
             "items": [{"id": i, "layer": l, "start": s, "end": e,
                        "preview": _preview(cg, i)}
                       for s, e, i, l in items[:limit]]}
 
 
-def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000):
-    """落在给定时间窗 / 空间范围内的节点。"""
+# 生效条件：time_window 为长度 2 的 list/tuple 时 q_t=(float(time_window[0]),float(time_window[1]))（元素不可转 float 会直接抛异常，源码未捕获），bbox 为长度 4 的 list/tuple 时同理构造 q_b；q_t 与 q_b 均为 None 时返回 {"error":"need_time_window_or_bbox"}；否则扫描节点、每节点时间区间按 _interval(fm, time_axis) 取（time_axis 缺省 observed 与旧行为逐位一致，非法轴抛 ValueError），并要求时间关系在 during/contains/overlaps/equals、空间关系在 inside/contains/overlaps/equals（提供查询侧才检查），返回 hits[:limit]（limit=None 取全部，0/False 取空）；
+def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000,
+            time_axis="observed"):
+    """落在给定时间窗 / 空间范围内的节点。`time_axis` 决定候选时间区间（见 `_interval`）。"""
     q_t = None
     if isinstance(time_window, (list, tuple)) and len(time_window) == 2:
         q_t = (float(time_window[0]), float(time_window[1]))
@@ -209,7 +244,7 @@ def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000
     hits = []
     for n in _scan(cg, layer=layer, max_scan=max_scan):
         fm = n["frontmatter"]
-        iv, bb = _interval(fm), _bbox(fm)
+        iv, bb = _interval(fm, time_axis), _bbox(fm)
         t_rel = time_relation(iv, q_t) if (q_t and iv) else None
         s_rel = space_relation(bb, q_b) if (q_b and bb) else None
         if q_t and t_rel not in ("during", "contains", "overlaps", "equals"):
@@ -224,14 +259,20 @@ def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000
             "items": hits[:limit]}
 
 
-def consistency(cg, layer=None, limit=50, max_scan=5000):
-    """时空字段自洽性检查：非法 bbox / 时间倒置 / 窗口与时刻冲突。"""
+# 生效条件：遍历 _scan(cg,layer=layer,max_scan=max_scan) 每条 frontmatter，bb 非 None 且不满足 bb[0]<=bb[2] and bb[1]<=bb[3] 记 invalid_bbox、iv（由 _interval(fm, time_axis) 取，time_axis 缺省 observed 与旧行为逐位一致、非法轴抛 ValueError）非 None 且 iv[0]>iv[1] 记 inverted_time_window、temporal 非 None 且 time_window 为长度 2 的 list/tuple 且 float 比较成功却不满足 tw[0]<=t<=tw[1] 记 temporal_outside_window（该检查恒按观察轴内部口径、不随 time_axis 漂移；转换抛 TypeError/ValueError 则忽略），返回 scanned 计数、issues 总数与 issues[:limit]（limit 默认 50）。
+def consistency(cg, layer=None, limit=50, max_scan=5000, time_axis="observed"):
+    """时空字段自洽性检查：非法 bbox / 时间倒置 / 窗口与时刻冲突。
+
+    `time_axis` 只决定「时间倒置」按哪条轴判；`temporal_outside_window`
+    恒按**观察轴内部**口径（temporal 与 time_window 的关系）——那是该 issue 的
+    定义本身，换轴会让它变成另一件事（不随参数漂移）。
+    """
     issues = []
     scanned = 0
     for n in _scan(cg, layer=layer, max_scan=max_scan):
         scanned += 1
         fm = n["frontmatter"]
-        bb, iv = _bbox(fm), _interval(fm)
+        bb, iv = _bbox(fm), _interval(fm, time_axis)
         if bb and not (bb[0] <= bb[2] and bb[1] <= bb[3]):
             issues.append({"id": n["id"], "issue": "invalid_bbox", "bbox": bb})
         if iv and iv[0] > iv[1]:
@@ -247,4 +288,4 @@ def consistency(cg, layer=None, limit=50, max_scan=5000):
             except (TypeError, ValueError):
                 pass
     return {"scanned": scanned, "issues": len(issues), "limit": limit,
-            "items": issues[:limit]}
+            "items": issues[:limit]}

package/md_cg/subgraph.py

@@ -40,6 +40,7 @@ SEP_MAX_NODES = 400          # 单次扫描节点上限（防 O(N²) 读盘爆
 SEP_MAX_PAIRS = 50           # 单次返回/落库的候选对上限
 
 
+# 生效条件：fm 为假值或 fm.get("subgraph") 取值为假（None/[]/{}/空串）时直接返回 {'nodes': [], 'edges': []}；subgraph 为 list/tuple 时其元素作节点、边记空列表，为 dict 时节点取 sg.get("nodes")（缺键或假值回落 []）、边取 sg.get("edges")（同样回落），为其他类型仍返回空；节点项为 dict 时取 n.get("id")、否则取元素本身，nid 为 None 跳过，仅当 str(nid).strip() 非空且未出现过才追加；边只保留 isinstance(e, dict) 的项；
 def declared(fm):
     """规范化 `frontmatter.subgraph` → `{"nodes": [id...], "edges": [edge...]}`。
 
@@ -68,6 +69,7 @@ def declared(fm):
     return {"nodes": nodes, "edges": [e for e in raw_edges if isinstance(e, dict)]}
 
 
+# 生效条件：当 getattr(cg,"index",None) 的 nodes 字典中存在 nid（entry 非 None）且 "subgraph" in entry 时，返回 {'id': nid, 'subgraph': entry.get("subgraph"), 'edges': entry.get("edges") or []}（subgraph 值为 None 也照样返回）；否则改走 cg.get(nid)，返回 (node or {}).get("frontmatter") or {}，节点不存在或 frontmatter 为假值时得空 dict；
 def _fm(cg, nid):
     """取节点 frontmatter：优先索引快照（免 IO），快照缺字段时回退读文件。"""
     entry = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid)
@@ -89,6 +91,7 @@ def _fm(cg, nid):
 SRC_REL_MAP = {"hierarchical": "contains"}
 
 
+# 生效条件：rel 先经 str(rel or "").strip().lower() 归一（None/空串得 ""），返回 {'target': str(tgt), 'relation_type': SRC_REL_MAP.get(rel, rel), 'confidence': confidence, 'verified': verified}——归一后的 rel 命中模块常量 SRC_REL_MAP 时用映射值、未命中（含 rel 为空串）时原样保留，confidence/verified 直接透传默认 1.0/0 的实参不做校验；
 def normalize_edge(tgt, rel, confidence=1.0, verified=0):
     """源库边 → md_cg 本地边（迁移器专用）。做两件事：
 
@@ -102,6 +105,7 @@ def normalize_edge(tgt, rel, confidence=1.0, verified=0):
             "confidence": confidence, "verified": verified}
 
 
+# 生效条件：cg 的 `_subgraph_children` 不为 None 时原样返回该缓存字典，否则遍历 cg.index["nodes"] 的键，用 declared(fm)["nodes"] 收子节点、并按边 rel 为 part_of/hierarchical（target 记为父、当前 pid 记为子）或 parent_of/contains（当前 pid 记为父、target 记为子，target 为 None 则该边跳过）补全 parent_id→[child_id] 索引，回写 cg._subgraph_children 后返回 idx；
 def children_index(cg):
     """全局正查：parent_id → [child_id...]（声明式 ∪ 边式，一次 O(N) 后缓存）。"""
     idx = getattr(cg, "_subgraph_children", None)
@@ -140,11 +144,13 @@ def children_index(cg):
     return idx
 
 
+# 生效条件：返回 list(children_index(cg).get(nid) or [])，即 nid 在索引中无键或对应值为空（None/空列表）时得空列表，否则返回其子 id 的浅拷贝列表；
 def children(cg, nid):
     """直接子节点 id 列表：`subgraph.nodes` 声明 ∪ 边式父子关系。"""
     return list(children_index(cg).get(nid) or [])
 
 
+# 生效条件：cg 的 `_subgraph_parents` 不为 None 时原样返回该缓存字典，否则遍历 cg.index["nodes"] 的键，用 declared(fm)["nodes"] 把 pid 记为每个子节点的父、并按边 rel 为 part_of/hierarchical（target 记为 pid 的父）或 parent_of/contains（pid 记为 target 的父，target 为 None 则该边跳过）补全 child_id→[parent_id] 索引，回写 cg._subgraph_parents 后返回 idx；
 def parents_index(cg):
     """全局反查：child_id → [parent_id...]（供 children/validate 复用，一次 O(N)）。"""
     idx = getattr(cg, "_subgraph_parents", None)
@@ -183,6 +189,7 @@ def parents_index(cg):
     return idx
 
 
+# 生效条件：无条件执行——把 cg 的 _subgraph_parents 与 _subgraph_children 依次 setattr 为 None（setattr 抛异常被 except 吞掉后继续下一个），无返回值，与 cg 是否已建有缓存无关；
 def invalidate_cache(cg):
     """写入/删除节点后调用，丢弃父子正查/反查缓存。"""
     for attr in ("_subgraph_parents", "_subgraph_children"):
@@ -192,12 +199,14 @@ def invalidate_cache(cg):
             pass
 
 
+# 生效条件：取 parents_index(cg).get(nid) or []，列表非空时返回其首元素，键缺失或值为空/假（None、[]）时返回 None；多父时只返回第一个，不在此处报歧义；
 def parent_of(cg, nid):
     """唯一父（多父时返回第一个并置 `ambiguous` 标记由 validate 报出）。"""
     ps = parents_index(cg).get(nid) or []
     return ps[0] if ps else None
 
 
+# 生效条件：max_depth 非 None 时先 max(0, min(int(max_depth), MAX_DEPTH_HARD)) 收敛；以 nid 为根迭代 DFS，已入 seen 的节点跳过，len(seen) >= max_nodes（max_nodes 传 0 时首次循环即成立）置 truncated=True 并 break，depth >= max_depth 且 children 非空时置 truncated=True 并 continue，否则对 children(cg,cur) 逆序、对未出现过的 (ch,cur) 追加 part_of 边并压栈；返回 {'root','nodes','paths','edges','n_nodes','n_edges','truncated'}；
 def expand(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
     """递归展开子树（迭代 DFS，防递归深度爆栈）。
 
@@ -237,6 +246,7 @@ def expand(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
             "truncated": truncated}
 
 
+# 生效条件：先调用 expand(cg, nid, max_depth=max_depth, max_nodes=max_nodes)，对其中每条边复制一份并追加 source/target 互换、relation_type="parent_of"、confidence/verified 沿用原边 .get(…,1.0/0) 的反向边；返回 root=nid、nodes=ex["nodes"]、paths=ex["paths"]、n_nodes=ex["n_nodes"]、n_edges=双边后条数、truncated=ex["truncated"]；
 def flatten(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
     """把嵌套子图摊平成「节点 + 边」，父子生成**对称双边**。
 
@@ -257,6 +267,7 @@ def flatten(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
             "truncated": ex["truncated"]}
 
 
+# 生效条件：known 取 cg.index 的 nodes 键集合，仅当 parents_index(cg).get(nid) or [] 为空（键缺失或空列表）的 nid 才视为树根，返回其排序后的 id 列表；
 def roots(cg):
     """无父节点（树根）的 id 列表。"""
     known = set(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys())
@@ -264,6 +275,7 @@ def roots(cg):
     return sorted(nid for nid in known if not (pmap.get(nid) or []))
 
 
+# 生效条件：known 取 cg.index 的 nodes 键列表，max_scan 为真值时截断为 known[:int(max_scan)]；逐 pid 遍历 declared(_fm(cg,pid))["nodes"]：ch==pid 记 self_loop 并 continue（不再进入悬空/多父判断），ch 不在 known_set 记 dangling_child，随后 parent 中已有 ch 且 prev != pid 记 multi_parent、否则写 parent[ch]=pid；再沿 parent 指针上溯，遇本路径已访问节点记 cycle；_issue 仅在 len(issues) < limit*4 时追加（limit 为 0 时 0<0 不成立，不追加任何 issue）；返回 scanned、issues=len(issues)、items=issues[:limit]、truncated=len(issues)>limit；
 def validate(cg, limit=50, max_scan=None):
     """树一致性校验：自环 / 悬空子节点 / 多父 / 环。
 
@@ -276,6 +288,7 @@ def validate(cg, limit=50, max_scan=None):
     known_set = set(known)
     parent, issues = {}, []
 
+# 生效条件：仅当 len(issues) < limit*4 时把 kw 追加进 issues（限流防报告膨胀）；无返回值，只改外层 issues；
     def _issue(**kw):
         if len(issues) < limit * 4:
             issues.append(kw)
@@ -320,6 +333,7 @@ def validate(cg, limit=50, max_scan=None):
 #   · 边携带 reason + 判定分量，供后续重构/审计追溯；
 #   · 条件**相同**的相似对**不是**分离候选（那是重复，该走 MERGE）。
 
+# 生效条件：cg.get(nid) 为假值（None/{}）时返回 None；否则取 fm=node.get("frontmatter") or {}、content=node.get("content") or ""，返回 {'grams': bigrams(forgetting.payload(content)), 'pos','neg': consistency.condition_terms(fm, content) 的结果, 'layer': fm.get("layer")}——grams 为空也照常返回该字典，不返回 None；
 def _node_terms_and_grams(cg, nid):
     """读取节点并返回 (payload 二元组, 正条件词面, 负条件词面)；不可读返回 None。"""
     from . import consistency, forgetting
@@ -334,6 +348,7 @@ def _node_terms_and_grams(cg, nid):
     return {"grams": grams, "pos": pos, "neg": neg, "layer": fm.get("layer")}
 
 
+# 生效条件：pool 初取 cg.index 的 nodes 键，layer 为假值（None/""）时不按层过滤、否则只留 e.get("layer")==layer 的 nid，ids 为真值时只留 str(x) 属于该集合的 nid；pool 排序后 truncated=len(pool)>int(max_nodes)、并截为前 int(max_nodes) 个；只有 _node_terms_and_grams 返回非 None 且 grams 非空的节点进 cache；对 cache 键两两比较——无公共 bigram 跳过、jaccard 小于 float(min_jaccard) 跳过、condition_distinct 的 distinct 为假或 overlap > float(max_cond_overlap) 跳过，其余成候选并按 (-jaccard,a,b) 排序；返回 scanned、compared、candidates=out[:int(limit)]、total_candidates、truncated、note；
 def separation_pairs(cg, layer=None, ids=None, max_nodes=SEP_MAX_NODES,
                      min_jaccard=SEP_MIN_JACCARD,
                      max_cond_overlap=SEP_MAX_COND_OVERLAP,
@@ -393,6 +408,7 @@ def separation_pairs(cg, layer=None, ids=None, max_nodes=SEP_MAX_NODES,
             "note": "只读候选；apply=True 才写分离边"}
 
 
+# 生效条件：batch 为假值（None 或空串）时回落到 time.strftime("%Y%m%d-%H%M%S")；按 (a,b)、(b,a) 两向处理：cg.get(src) 为假值跳过，dst 已出现在 consistency.separation_targets(fm) 中跳过，否则往 fm["edges"] 追加 distinct_from 边、向 fm["pattern_separated_from"] 追加 dst，按 os.path.join(cg.root, e.get("path") or f"{src}.md") 调 cg._write_node 写盘并追加 MAINTAIN_LOG 行，src 记入 written；返回 {'a','b','written','batch'}；
 def mark_separated(cg, a, b, reason="", actor="maintain", batch=None):
     """写入 (a↔b) 对称 `distinct_from` 边（幂等：已存在则不重复写）。"""
     from . import consistency
@@ -427,6 +443,7 @@ def mark_separated(cg, a, b, reason="", actor="maintain", batch=None):
     return {"a": a, "b": b, "written": written, "batch": batch}
 
 
+# 生效条件：pairs 为 None 时调 separation_pairs 取 candidates 与 meta（scanned/compared/truncated/total_candidates），否则 cands=list(pairs) 且 meta 中 scanned/compared 记 0、truncated 记 False、total_candidates=len(cands)；apply 为真值时先生成统一 batch=time.strftime(...)，逐个候选调 mark_separated(..., batch=batch)，written 非空且 cg 有 rebuild_index 时调 cg.rebuild_index()、否则调 invalidate_cache(cg)，apply 为假值时不写盘；返回 ok、action='separate'、dry_run=not apply、layer、candidates、written、written_count、elapsed_ms、log 与 meta、note；
 def separate_run(cg, layer=None, pairs=None, apply=False, ids=None,
                  min_jaccard=SEP_MIN_JACCARD, limit=SEP_MAX_PAIRS,
                  actor="maintain"):
@@ -487,6 +504,7 @@ RECON_COMMON_SHARE = 0.5      # 共同条件判定：≥ 半数锚点共享
 RECON_SCENE_PREFIX = "scene_"
 
 
+# 生效条件：clues 为 None 时返回 []；clues 为 str 时包装成单元素列表；逐项取 str(c or "").strip().lower()，空串跳过，整串去重入 out，再按 re.split(r"[\s,，、;；/|]+") 切词、去重后追加；返回 out；
 def _clue_terms(clues):
     """线索归一化：字符串 / 列表 → 去重词面（保留整串 + 切分后的词）。"""
     if clues is None:
@@ -507,6 +525,7 @@ def _clue_terms(clues):
     return out
 
 
+# 生效条件：term_sets 为假值（None/[]）时返回 []；否则对每个集合的 set(s or ()) 统计词面出现次数，need = max(2, int(len(term_sets)*RECON_COMMON_SHARE) 向上取整)，返回出现次数 >= need 的词面排序列表（阈值取自模块常量 RECON_COMMON_SHARE）；
 def _shared_terms(term_sets):
     """出现在 ≥ RECON_COMMON_SHARE 比例集合中的词面（且至少 2 个集合共享）。"""
     if not term_sets:
@@ -519,6 +538,7 @@ def _shared_terms(term_sets):
     return sorted(t for t, c in cnt.items() if c >= need)
 
 
+# 生效条件：按 term_sets 原顺序遍历每个集合的 sorted(s or ())，首次出现的词面追加到 seen，返回 seen[:limit]（limit 默认 99，传 0 时切片为空列表，无 or 回落）；
 def _uniq_terms(term_sets, limit=99):
     seen = []
     for s in term_sets:
@@ -528,6 +548,7 @@ def _uniq_terms(term_sets, limit=99):
     return seen[:limit]
 
 
+# 生效条件：bigrams(" ".join(clue_terms)) 为空时返回 []；否则遍历 pool，cg.get(nid) 为假值、或 forgetting.payload 后 bigrams 为空、或与 clue_grams 无交集时跳过，否则 jac=inter/len(并集 or 1)、exact 为 clue_terms 中非空且作为子串出现在 body 的个数，score=jac+0.05*exact，仅 score >= RECON_MIN_SCORE 才收录，最终按 (-score, nid) 排序返回；
 def _anchor_scores(cg, pool, clue_terms):
     """按词面重合给候选锚点打分（返回 [(nid, score, shared, exact)]，降序）。"""
     from . import forgetting
@@ -556,6 +577,7 @@ def _anchor_scores(cg, pool, clue_terms):
     return scored
 
 
+# 生效条件：对 anchor_ids 中每个 nid，cg.get(nid) 为假值跳过，否则取 fm 与 consistency.condition_terms 得 pos/neg，per[nid] 记为 {"effective": sorted(pos)[:8], "non_applicable": sorted(neg)[:8]}；返回 common=_shared_terms(pos_sets)、individual=_uniq_terms(pos_sets) 中不在 common 的项、non_applicable=_uniq_terms(neg_sets)、declared=list(declared_terms or [])、per_anchor=per；
 def _condition_space(cg, anchor_ids, declared_terms=None):
     """合成锚点群的条件空间：共同条件 / 个别条件 / 不适用条件 / 逐锚点明细。"""
     from . import consistency
@@ -576,6 +598,7 @@ def _condition_space(cg, anchor_ids, declared_terms=None):
             "declared": list(declared_terms or []), "per_anchor": per}
 
 
+# 生效条件：以 cg.index["nodes"] 为节点池（layer 为真时只保留 layer 等于该值的节点，池按 max_nodes 截断），由 clues 词项与 ids 收集锚点并截取 limit 个，锚点为空则返回 status="blindspot" 且 condition_space=None，否则返回 status="reconstructed"（neighbors 为真时按链邻接补边并在 max_nodes 内补节点，apply 为真且算出的 scene_id 尚不在 nodes 中时再写入该情境节点并记日志）；
 def reconstruct_scene(cg, clues=None, ids=None, conditions=None, layer=None,
                       max_nodes=RECON_MAX_NODES, limit=RECON_MAX_ANCHORS,
                       neighbors=True, apply=False, actor="insight"):