@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/vision_evidence.py

@@ -3,7 +3,7 @@
 
 裁定依据
 --------
-`docs/认知图_G4-G8缺口裁定单_v0.1.md` §三（四态 = ACCEPT，条件 = 脱敏 + 只读 AEIS）。
+`docs/mdcg/认知图_G4-G8缺口裁定单_v0.1.md` §三（四态 = ACCEPT，条件 = 脱敏 + 只读 AEIS）。
 缺口根因（库外只读观测）：产出侧 `vision_pipeline.cg_ingest` 只取
 `p.get("model_evidence")`，白箱 `geometry_parts` 部件不带该键 → 部件节点证据面
 恒为 `{}`。即「证据口径未定义」，不是「没有证据」。
@@ -116,15 +116,18 @@ _RE_DIR_N = re.compile(r"_(\d+)$")
 
 # ---- 通用工具 -------------------------------------------------------------
 
+# 生效条件：x 为 str 时返回 MdCGOS(x) 新实例，否则原样返回 x。
 def _as_cg(x):
     """接受 root 路径或已构造 cg 实例——保持密级隔离与密钥上下文。"""
     return MdCGOS(x) if isinstance(x, str) else x
 
 
+# 生效条件：无必需形参，调用即返回 time.strftime("%Y%m%d-%H%M%S") 的当前批次串。
 def _now_batch() -> str:
     return time.strftime("%Y%m%d-%H%M%S")
 
 
+# 生效条件：base 为字符串批号，先读 _log_path(cg) 的 jsonl 收集 batch 字段中以 base 开头的已有值，base 未被占用则原样返回 base，已占用则返回首个未占用的 f"{base}.{i}"（i 从 2 递增）。
 def _unique_batch(cg, base: str) -> str:
     """同秒重复调用时批号去重（后缀 .2/.3…），保证按批次回滚不打偏。"""
     seen = set()
@@ -140,21 +143,25 @@ def _unique_batch(cg, base: str) -> str:
     return f"{base}.{i}"
 
 
+# 生效条件：cg 具 root 属性时取 cg.root、否则取 str(cg) 作为 root，返回 os.path.join(root, EVIDENCE_LOG)。
 def _log_path(cg) -> str:
     root = cg.root if hasattr(cg, "root") else str(cg)
     return os.path.join(root, EVIDENCE_LOG)
 
 
+# 生效条件：batch 与 nid 恒以 "%s|%s" 拼接成条目号，不做空值或类型校验。
 def _entry_id(batch: str, nid: str) -> str:
     return "%s|%s" % (batch, nid)
 
 
+# 生效条件：v 为 list/tuple 时返回各元素 str(x).strip() 后非空项以「；」连接；否则 v 为 None 返回空串，其余值返回 str(v).strip()。
 def _as_text(v) -> str:
     if isinstance(v, (list, tuple)):
         return "；".join(str(x).strip() for x in v if str(x).strip())
     return "" if v is None else str(v).strip()
 
 
+# 生效条件：path 经 abspath→dirname→basename 取名后匹配 _RE_DIR_N，命中则返回 int(m.group(1))，未命中返回 None。
 def _gallery_no(path: str):
     """图集编号：目录名尾部 `_<N>`；缺省 None（脱敏引用用）。"""
     name = os.path.basename(os.path.dirname(os.path.abspath(path)))
@@ -162,10 +169,12 @@ def _gallery_no(path: str):
     return int(m.group(1)) if m else None
 
 
+# 生效条件：gal 非 None 时返回 "图集_%s" % gal，gal 为 None 时返回 "图集_?"。
 def _gallery_ref(gal) -> str:
     return "图集_%s" % (gal if gal is not None else "?")
 
 
+# 生效条件：无必需形参，按 os.environ.get(VISION_ROOT_ENV) or os.environ.get(LEGACY_VISION_ROOT_ENV) or DEFAULT_VISION_ROOT 取值——某环境变量为空串时视为假值继续回落下一项。
 def vision_root() -> str:
     """视觉证据归档根：env 覆盖 > 遗留 env > 本仓 data/vision 的父目录。"""
     return (os.environ.get(VISION_ROOT_ENV)
@@ -179,6 +188,7 @@ aeis_root = vision_root
 
 # ---- 证据源（只读归档） ---------------------------------------------------
 
+# 生效条件：root 下 data/vision/*/*.json 逐文件读；文件 OSError/ValueError、JSON 顶层非 dict、parts 非非空 list、或过滤后（type 与 cond_hash 皆真值的 dict）无记录时跳过该文件，否则收入含 path/gallery/image_id/algo/identity_cond_hash/by_type/by_cond 的 src 并最终返回 out 列表。
 def load_sources(root: str) -> list:
     """扫描 `AEIS/data/vision/*/*.json`，取逐部件结构化结果（主证据源）。"""
     base = os.path.join(root, "data", "vision")
@@ -215,6 +225,7 @@ def load_sources(root: str) -> list:
 
 # ---- 节点正文解析 ---------------------------------------------------------
 
+# 生效条件：content 为 None 或空串时按 "" 处理；逐行 strip 后跳过空行与以 # 开头的行，返回首个含 ROOT_MARK 或匹配 _RE_PART 的行，全部无命中返回 ""。
 def _find_body_line(content: str) -> str:
     for ln in (content or "").split("\n"):
         s = ln.strip()
@@ -225,6 +236,7 @@ def _find_body_line(content: str) -> str:
     return ""
 
 
+# 生效条件：rest 为 None/假值时按 "" 处理，分别用 _RE_COND/_RE_VERDICT/_RE_REASON/_RE_FG 捕获；fg 命中则转 float、ValueError 时置 None；reason 命中并 strip 后为空则置 None；返回含 cond_hash/verdict/reason/fg_ratio 四键的 dict（未命中键值为 None）。
 def _fields(rest: str) -> dict:
     m = _RE_COND.search(rest or "")
     v = _RE_VERDICT.search(rest or "")
@@ -242,6 +254,7 @@ def _fields(rest: str) -> dict:
             "fg_ratio": fg}
 
 
+# 生效条件：content 无正文行（空串、全为注释/空行、或无 ROOT_MARK 且不匹配 _RE_PART）返回 None；首行含 ROOT_MARK 返回 kind="root" 记录（n_parts 由 _RE_NPARTS 转 int、未命中为 None，cond_hash 取自 _fields）；否则须匹配 _RE_PART，不匹配返回 None，匹配后 bbox 按逗号切分对非空项做 int(float(x))（ValueError 则 bbox=None）并返回 kind="part" 记录。
 def parse_node(content: str):
     """视觉节点正文 → 结构化记录；非视觉节点 → None。"""
     line = _find_body_line(content)
@@ -268,6 +281,7 @@ def parse_node(content: str):
 
 # ---- 节点集合 -------------------------------------------------------------
 
+# 生效条件：layer 透传给 cg._candidates，nid 取 e["id"] 或 path 去 .md 后须以 prefixes 中任一开头且 cg._read 返回非 None 的 fm 才被计数；加密内容记录 locked=True/parsed=None 且不触发 limit 检查，非加密内容 parse_node 后若 limit 非 None 且节点数已达 limit 即 break（因此最多多计该条）。
 def _vision_nodes(cg, layer=None, prefixes=VISION_PREFIXES, limit=None) -> list:
     """收集视觉节点（只读 index）。
 
@@ -295,6 +309,7 @@ def _vision_nodes(cg, layer=None, prefixes=VISION_PREFIXES, limit=None) -> list:
     return nodes
 
 
+# 生效条件：nodes 中 parsed 为 dict、kind=="root" 且 cond_hash 为真值的节点，以其 tags[-1]（无 tags 时为空串）为标签 setdefault 记录首个 cond_hash，返回标签→cond_hash 的 out。
 def _family_root_cond(nodes) -> dict:
     """家族标签(image_id) → 根节点 cond_hash。"""
     out = {}
@@ -306,6 +321,7 @@ def _family_root_cond(nodes) -> dict:
     return out
 
 
+# 生效条件：n["id"] 以 "vpipe_" 开头时先以 roots.get(tags[-1] 或 "") 取 cond——cond 为假返回 (None,"no_family_root")，cond 为真则在 sources 中匹配 identity_cond_hash 成功返回 (s,"identity_cond_hash")、未命中再按该标签匹配 image_id 成功返回 (s,"image_id")、仍失败返回 (None,"no_source_archive")；非 vpipe_ 时取 tags 中首个匹配 _RE_IMG_TAG 的 img<N>（未取到则不匹配）按 image_id 命中返回 (s,"image_tag")，否则返回 (None,"no_source_archive")。
 def _pick_source(n, sources, roots) -> tuple:
     """→ (source, joined_by)；无法定位图集 → (None, 原因)。"""
     nid = n["id"]
@@ -339,6 +355,7 @@ def _pick_source(n, sources, roots) -> tuple:
 
 # ---- 三档映射 -------------------------------------------------------------
 
+# 生效条件：parsed.cond_hash 为真值时按 str(cond_hash) 从 src["by_cond"] 取候选——其中 type 与 parsed["type"] 相同者直接返回 (r,"cond_hash")，否则候选仅 1 条返回 (cands[0],"cond_hash")、多于 1 条返回 (None,None)；候选为空或 cond_hash 为假时若 parsed.type 为真则按 src["by_type"].get(type) 命中返回 (r,"type")，否则返回 (None,None)。
 def _match_record(src, parsed, joined_by):
     """在归档里定位对应部件记录（imgpart 优先 cond_hash 精确，vpipe 按 type）。"""
     if parsed.get("cond_hash"):
@@ -355,6 +372,7 @@ def _match_record(src, parsed, joined_by):
     return None, None
 
 
+# 生效条件：n["locked"] 为真→BLINDSPOT(reason="locked")；否则 parsed 缺失→"unparsed"、kind 非 "part"→"root_no_verdict"；否则 _pick_source(n,sources,roots) 无源→以 why 为 reason；否则 _match_record 无记录→"no_matching_part"；否则 parsed 与 rec 的 verdict 均为真且不等→"verdict_mismatch"；否则 TIER2_FIELDS 中任一字段为 None→"missing_field:…"；全部通过才返回 STATUS_WHITEBOX 与 ev（未用到的形参 aeis_root_used 不参与判定）。
 def build_evidence(n, sources, roots, aeis_root_used):
     """单节点 → (status, evidence, meta)；严格三档，缺源即 BLINDSPOT。"""
     parsed = n.get("parsed")
@@ -397,6 +415,7 @@ def build_evidence(n, sources, roots, aeis_root_used):
 
 # ---- 预演 / 执行 / 回滚 / 留痕 --------------------------------------------
 
+# 生效条件：x 经 _as_cg 转换；prefixes 为假值回落 VISION_PREFIXES、aeis_root_ 为假值回落 aeis_root()；ids 为真值时才按 set(ids) 过滤 nodes；对 nodes 调 build_evidence，locked 节点只累加 skipped_locked，白箱项入 items、其余入 blindspot_items，全程不写盘并返回含 aeis_root/sources/nodes_scanned/targeted/blindspot/by_reason 的报表。
 def plan(x, layer=None, prefixes=None, limit=None,
          aeis_root_=None, ids=None) -> dict:
     """预演：产出证据回填清单，不写盘。"""
@@ -445,6 +464,7 @@ def plan(x, layer=None, prefixes=None, limit=None,
     }
 
 
+# 生效条件：x 经 _as_cg，batch 为假值回落 BATCH_DEFAULT 并交给 _unique_batch(cg, …) 去重；ids 为真值才按 id 过滤、entry_ids 为真值才按 _entry_id(batch,id) 过滤；循环中节点不在 cg.index["nodes"] 记 skipped_drift，fm 为 None 或内容加密记 skipped_locked，fm 已有同 status（白箱还要求 evidence 相同）记 skipped_already，否则改写 fm 并落盘、追加 jsonl、收集 entry_id；written 非 0 时 cg.rebuild_index() 并尝试 evolution.record（异常被吞）后返回 rep。
 def apply(x, ids=None, entry_ids=None, layer=None, prefixes=None,
           limit=None, batch=None, aeis_root_=None, actor=None) -> dict:
     """执行回填：逐节点改写 frontmatter 证据面，写 `_vision_evidence.jsonl`。"""
@@ -528,6 +548,7 @@ def apply(x, ids=None, entry_ids=None, layer=None, prefixes=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg 后读 _log_path(cg) 日志，只处理 action=="vision_evidence" 记录；batch 为真值时仅取 batch 相同记录、entry_ids 为真值时仅取 entry_id 在集合内记录、该 entry_id 已出现在 rollback 日志则记 skipped_done；节点缺失或 _read 返回 fm 为 None 记 missing，EVIDENCE_KEYS 一个都不在 fm 中记 skipped_done，否则删除命中键、写盘并追加 rollback 留痕，reverted 非 0 时重建索引后返回 rep。
 def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """按留痕反向应用：删除本批次写入的证据键（幂等，防覆盖）。"""
     cg = _as_cg(x)
@@ -580,6 +601,7 @@ def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg 后逐条读 _log_path(cg)，batch 为真值时才按 rec.get("batch")==batch 过滤；limit 非 None 且 >=0 时执行 recs = recs[-limit:]（limit=0 因 -0 切片退化为全量），limit 为 None 或负数时不截断，返回 {root,total,returned,records}。
 def history(x, limit=100, batch=None) -> dict:
     cg = _as_cg(x)
     recs = []
@@ -596,6 +618,7 @@ def history(x, limit=100, batch=None) -> dict:
 
 # ---- CLI（真实库预演/执行用；MCP 侧走 maintain action） -------------------
 
+# 生效条件：argv 为 None 时 argparse 取 sys.argv；--prefixes 默认由 ",".join(VISION_PREFIXES) 提供并切出非空前缀；a.rollback 为真调 rollback（entry_ids 切分后为空则传 None）、否则 a.apply 为真调 apply、否则调 plan；--json 为真打印整份 JSON，否则按固定关键字打印并恒返回 0。
 def _main(argv=None) -> int:
     import argparse
     ap = argparse.ArgumentParser(description="G5 视觉证据回填（默认只预演）")
@@ -641,4 +664,4 @@ def _main(argv=None) -> int:
 
 
 if __name__ == "__main__":                                  # pragma: no cover
-    raise SystemExit(_main())
+    raise SystemExit(_main())

package/md_cg/weights.py

@@ -3,7 +3,7 @@
 
 理论出处（本仓原文，非外部知识）
 --------------------------------
-`docs/智能的公理化基石.md` §4.3：信任合成是
+`docs/theory/智能的公理化基石.md` §4.3：信任合成是
     P_trust = f(一致性, 位置可预测性, 版本对齐度)
 其中 `版本对齐度` 已由 `theory` + `links.version_alignment` 提供，
 `位置可预测性` 见 `predict`，`一致性` 见 `consistency`。本模块只补一件
@@ -108,6 +108,7 @@ class WeightError(Exception):
 # 基础查询
 # --------------------------------------------------------------------------
 
+# 生效条件：position 经 str(position or "").strip() 作为 SPEC 的键，命中时返回对应 spec dict，未命中（含 position 为 None/空串/未知）抛 WeightError；
 def _spec(position: str) -> dict:
     s = SPEC.get(str(position or "").strip())
     if s is None:
@@ -115,6 +116,7 @@ def _spec(position: str) -> dict:
     return s
 
 
+# 生效条件：component 经 str(component or "").strip() 后若结果在 COMPONENTS 中返回该规范分量字符串，否则抛 WeightError；
 def _comp(component: str) -> str:
     c = str(component or "").strip()
     if c not in COMPONENTS:
@@ -122,32 +124,38 @@ def _comp(component: str) -> str:
     return c
 
 
+# 生效条件：position 可被 _spec 解析且其结果 "class" 等于 VIEWPOINT 时返回 True，非 VIEWPOINT 返回 False，未知 position 抛 WeightError；
 def is_viewpoint(position: str) -> bool:
     """是否认知视角（3 项都涉及，不设零）。"""
     return _spec(position)["class"] == VIEWPOINT
 
 
+# 生效条件：position 可被 _spec 解析且其结果 "class" 等于 FUNCTIONAL 时返回 True，非 FUNCTIONAL 返回 False，未知 position 抛 WeightError；
 def is_functional(position: str) -> bool:
     """是否功能单元（身份即排除）。"""
     return _spec(position)["class"] == FUNCTIONAL
 
 
+# 生效条件：position 经 _spec(position) 验证可解析后，返回原始 position 是否在模块级 DAILY 中；带首尾空白等未 strip 的值会因不在 DAILY 返回 False，未知 position 抛 WeightError；
 def in_daily_eval(position: str) -> bool:
     """是否参与日常评估（设计者=False，元参照系）。"""
     _spec(position)
     return position in DAILY
 
 
+# 生效条件：position 可被 _spec 解析且其 spec 含 "primary" 键时返回该值，未知 position 抛 WeightError；
 def dominant(position: str) -> str:
     """主导分量（权重最高者）。"""
     return _spec(position)["primary"]
 
 
+# 生效条件：position 可被 _spec 解析且其 spec 含 "secondary" 键时返回该值（视角可为 None），未知 position 抛 WeightError；
 def secondary(position: str):
     """次主导分量；视角返回 None（另两项并列、均 >0）。"""
     return _spec(position)["secondary"]
 
 
+# 生效条件：position 可被 _spec 解析且其 spec 含 "excluded" 键时返回该值（视角可为 None），未知 position 抛 WeightError；
 def excluded(position: str):
     """被排除分量（≈0）；视角返回 None（不设零）。"""
     return _spec(position)["excluded"]
@@ -157,6 +165,7 @@ def excluded(position: str):
 # 序比较（本模块的权威结论：只有序，没有数值）
 # --------------------------------------------------------------------------
 
+# 生效条件：position 与 component 分别经 _spec 与 _comp 验证后，若 component 等于该位置 spec["excluded"] 返回 RANK_EXCLUDED，否则若等于 spec["primary"] 返回 RANK_PRIMARY，否则返回 RANK_SECONDARY；
 def rank(position: str, component: str) -> float:
     """分量在该位置的序秩（占位量级）：2 主导 / 1 参与 / 0 排除。"""
     s = _spec(position)
@@ -168,6 +177,7 @@ def rank(position: str, component: str) -> float:
     return RANK_SECONDARY
 
 
+# 生效条件：position、a、b 经 rank 可得序秩，若 rank(position,a)==rank(position,b) 返回 None，否则返回 ra>rb 的 bool；任一参数未知则抛 WeightError；
 def prefers(position: str, a: str, b: str):
     """该位置是否**严格**偏好 a 胜过 b。
 
@@ -179,6 +189,7 @@ def prefers(position: str, a: str, b: str):
     return ra > rb
 
 
+# 生效条件：position 经 _spec 验证且 COMPONENTS 可用时，按 -rank(position,c) 与 COMPONENTS.index(c) 排序，返回 {"preferred":[rank>0], "excluded":[rank==0], "primary":dominant(position), "secondary":secondary(position)}（无 dominant 键）；
 def order(position: str):
     """从高到低排列的分量（并列者按 COMPONENTS 稳定序）；排除项单独列出。"""
     _spec(position)
@@ -189,6 +200,7 @@ def order(position: str):
             "primary": dominant(position), "secondary": secondary(position)}
 
 
+# 生效条件：position 经 _spec 验证且 COMPONENTS 可用时，将各分量 rank 归一化到 4 位小数返回；若 total 为 0 则按 total=1.0 计算；
 def weights(position: str) -> dict:
     """占位数值权重（序秩归一化）；**未标定**，仅供仿真。"""
     _spec(position)
@@ -201,6 +213,7 @@ def weights(position: str) -> dict:
 # 合成（占位：f(一致性, 位置可预测性, 版本对齐度)）
 # --------------------------------------------------------------------------
 
+# 生效条件：position 经 _spec 可解析且 COMPONENTS 可用时，components 对每个分量经 .get(c,0.0) 取值并截到 [0,1]；若 components 无 .get 或该值不能 float 则该分量值记 0.0，仍按 weights(position) 加权求和返回含 score/values/weights/dominant 的 dict；
 def blend(position: str, components: dict) -> dict:
     """按位置的权重合成单一信任标量。
 
@@ -229,6 +242,7 @@ def blend(position: str, components: dict) -> dict:
 # 不变量自检（把上轮的三条结构约束落成可执行断言）
 # --------------------------------------------------------------------------
 
+# 生效条件：模块级 POSITION_ORDER、COMPONENTS、SPEC、VIEWPOINT、FUNCTIONAL 等常量齐备时，invariants() 逐条自检并返回 {"ok": all(checks[*].ok), "checks": ...}；
 def invariants() -> dict:
     """逐条自检结构约束，返回 {ok, checks{name: {ok, detail}}}。"""
     checks = {}
@@ -294,6 +308,7 @@ def invariants() -> dict:
 # 自描述
 # --------------------------------------------------------------------------
 
+# 生效条件：模块级 COMPONENTS、COMPONENT_LABELS、VIEWPOINT、FUNCTIONAL、SPEC、POSITION_ORDER、DAILY 齐备时，返回位置权重矩阵自描述 dict，其中 components 按 COMPONENT_LABELS、positions 按 SPEC、daily_eval 按 DAILY 展开；
 def catalog() -> dict:
     """位置权重矩阵自描述（供 MCP / 文档对照验证）。"""
     return {
@@ -357,6 +372,7 @@ IMPORTANCE_PROTECT = 0.70   # ≥ 此值：保护下限（已保护/高危节点
 APPLY_DELTA = 0.05          # 变动小于此值不写盘（防 IO 放大）
 
 
+# 生效条件：e 为可 .get 的映射时，遍历 e.get("edges")（假值视为空）逐项按 dict 的 to/target/node/id 或标量转 str 追加非假值，再取 e.get("subgraph")，若为 dict 取其 "nodes" 否则取 subgraph 本身，且当其为 list/tuple 时追加其中 dict 的 id 或标量转 str 的非假值，返回 out；
 def _targets(e: dict):
     """索引快照里的「出边目标」：edges ∪ subgraph.nodes（兼容 dict/str）。"""
     out = []
@@ -377,6 +393,7 @@ def _targets(e: dict):
     return out
 
 
+# 生效条件：basis 为 None 时返回 BASIS_TRUST_MISSING；否则把 str(basis).strip().lower() 作为 BASIS_TRUST 的键，命中返回对应权重，未命中（含空串）返回 BASIS_TRUST_MISSING；
 def basis_trust(basis):
     """验证基底 → 可信权重；缺失/未知一律给最低档（不假装可信）。"""
     if basis is None:
@@ -384,6 +401,7 @@ def basis_trust(basis):
     return BASIS_TRUST.get(str(basis).strip().lower(), BASIS_TRUST_MISSING)
 
 
+# 生效条件：cg 的 index（getattr(cg,"index",None) or {}）与其 "nodes" 同为真值时，返回以这些节点 id 为键的入度表，仅当 _targets(e) 给出的目标 t 也在 nodes 且 t != nid 时计数 +1；index 或 "nodes" 为假值（None/{}）时 nodes 回落 {}，直接返回空 dict。
 def coverage_index(cg) -> dict:
     """入度表：nid → 被多少节点指向（覆盖度，O(N) 免读文件）。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
@@ -395,6 +413,7 @@ def coverage_index(cg) -> dict:
     return indeg
 
 
+# 生效条件：cg.index 的 "nodes" 为 dict 时，layer 真值仅处理 e.get("layer")==layer 的节点，layer 假值不过滤；content_hash 为假值（None/空串/0 等）的节点输出 0.0，同 (e.get("layer"), content_hash) 第二次撞车时当前与首次节点均输出 1.0，否则输出 0.0；
 def redundancy_map(cg, layer=None) -> dict:
     """同层内容哈希撞车 → 冗余度 1.0，否则 0.0（精确冗余，O(N) 免读文件）。
 
@@ -420,6 +439,7 @@ def redundancy_map(cg, layer=None) -> dict:
     return out
 
 
+# 生效条件：cg.index 的 nodes 为 dict 且 entry 非 None 或 nodes.get(nid) 命中时，e 按 entry 优先否则 nodes.get(nid)；indeg/red 分别仅在为 None 时回落 coverage_index(cg)/redundancy_map(cg, layer=e.get("layer"))（空容器不回落）；按 IMPORTANCE_MIX、COV_SAT 及 e.get("verification_basis") 的 basis_trust 计算 coverage/redundancy/basis 分量，按 bool(e.get("protected")) 选择 IMPORTANCE_PROTECT 或 IMPORTANCE_FLOOR 作下限、IMPORTANCE_CEIL 作上限，返回含 before（e.get("importance",0.5) or 0.5）、after、components、protected 的 dict；entry 与 nodes.get(nid) 均为 None 返回 None；
 def node_importance(cg, nid, indeg=None, red=None, entry=None):
     """单节点结构重要性分解（可审计：给出分量而非只给分）。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
@@ -448,6 +468,7 @@ def node_importance(cg, nid, indeg=None, red=None, entry=None):
             "protected_floor": protected}
 
 
+# 生效条件：给定 cg 且 nodes = cg.index["nodes"] 时按 layer 过滤、limit 为真值才 ids = ids[:int(limit)] 逐节点重算，abs(after-before) < float(min_delta) 记 unchanged；仅 apply=True 才把 frontmatter.importance/importance_source/importance_components 写回（after >= IMPORTANCE_PROTECT 且未 protected 时补写 protected/protection_reason），并向 cg.root 下 append_jsonl(..., MAINTAIN_LOG) 记 batch 后 rebuild_index。
 def recalc(cg, layer=None, limit=None, apply=False, min_delta=APPLY_DELTA,
            actor="maintain", dry_run_samples=10):
     """结构重要性重算：覆盖度 + 冗余度 + 验证基底 → 重排节点重要性。
@@ -547,6 +568,7 @@ def recalc(cg, layer=None, limit=None, apply=False, min_delta=APPLY_DELTA,
     }
 
 
+# 生效条件：cg.root/MAINTAIN_LOG 可读出 action=="importance" 记录后，entry_ids 为真值时按记录 id 是否在 {str(x) for x in entry_ids} 过滤；否则 batch 为真值时按 r.get("batch")==batch 过滤；否则取最后一条记录的 batch 再按其过滤；无 importance 记录返回 {"ok":False,"error":"no_records","reverted":0}，过滤后无记录返回 {"ok":False,"error":"batch_not_found",...}；对命中且 cg.get(nid) 为真的记录写回 rec.get("before") 并计数，若 reverted 且 cg 有 rebuild_index 则调用，最后 append_jsonl 写 actor 并返回 {"ok":True,"batch":batch,"reverted":reverted,"ids":ids}；
 def rollback(cg, batch=None, entry_ids=None, actor="maintain"):
     """把重要性重算反向应用（bulk 改写的可回滚兑现）。
 
@@ -594,9 +616,10 @@ def rollback(cg, batch=None, entry_ids=None, actor="maintain"):
     return {"ok": True, "batch": batch, "reverted": reverted, "ids": ids}
 
 
+# 生效条件：cg.root/MAINTAIN_LOG 可读出 JSONL 记录后，action 为真值时按 r.get("action")==action 过滤，假值不过滤；返回 recs[-int(limit):]，其中 limit=0 时 int(0)=0 使切片为 recs[0:] 返回全部而非空；
 def history(cg, limit=100, action=None):
     """维护留痕（最近 limit 条），可按 action 过滤。"""
     recs = list(read_jsonl(os.path.join(cg.root, MAINTAIN_LOG)))
     if action:
         recs = [r for r in recs if r.get("action") == action]
-    return recs[-int(limit):]
+    return recs[-int(limit):]

package/md_cg/whitebox.py

@@ -17,7 +17,7 @@
     才回退外部 MCP stdio 子进程（legacy 路径）。
   · 调用结果：验证结论写回认知图（self 层，tags 含 `whitebox:verify`），可追溯。
 
-显式调用映射（详见 docs/功能调用映射表_v0.1.md）
+显式调用映射（详见 docs/mdcg/功能调用映射表_v0.1.md）
 ------------------------------------------------
   功能                 → 代码                                   → MCP
   白箱问答             → md_cg.whitebox.ask                     → cg(op=whitebox, action=ask)
@@ -63,6 +63,7 @@ DEFAULT_KNOWLEDGE_PROBES = [
 # 启动命令
 # --------------------------------------------------------------------------
 
+# 生效条件：无必需形参；exe 取 MDCG_WHITEBOX_CMD，该值为假时取 sys.executable、再为假时取 "python"，args 取 MDCG_WHITEBOX_ARGS.split()（该值为真时）否则 ["-m","aeis.mcp.server"]，返回 [exe]+args。
 def _launch_cmd():
     """外部白箱 MCP server 启动命令（legacy 路径，需显式配置）。
 
@@ -79,6 +80,7 @@ def _launch_cmd():
 # 白箱 MCP stdio 客户端（零第三方依赖）
 # --------------------------------------------------------------------------
 
+# 生效条件：类无自定义 __init__（无必需构造形参）；实例化后仅当子类覆写 call 时 ask/remember 才走通，否则 call 抛 NotImplementedError。
 class _WhiteboxApi:
     """白箱业务接口（`ask` / `remember`）。
 
@@ -87,10 +89,12 @@ class _WhiteboxApi:
       · `_SubprocessWhiteboxClient` —— MCP stdio 子进程（legacy，显式配置时）
     """
 
+# 生效条件：以 required 形参 name 与 args 调用该抽象方法时无条件抛出 NotImplementedError，不产生任何返回。
     def call(self, name, args):
         """调用白箱工具，返回 {isError, text, data}。"""
         raise NotImplementedError
 
+# 生效条件：给定 required 形参 message（session_id 省略时取默认 "md_cg-whitebox-verify"）即转调 self.call("wisdom_chat", {...})，按返回 r 组装 {ok: not r["isError"], route: _extract_route(data), reply: _extract_reply(data, r.get("text")), raw}，其中 data 由 r.get("data") or {} 得到（data 缺失或为假值时为 {}），故 raw 恒取该 data、不回落到 r.get("text")。
     def ask(self, message, session_id="md_cg-whitebox-verify"):
         """白箱问答（wisdom_chat）。返回归一化的 {ok, route, reply, raw}。"""
         r = self.call("wisdom_chat", {"message": message, "session_id": session_id})
@@ -100,6 +104,7 @@ class _WhiteboxApi:
                 "reply": _extract_reply(data, r.get("text")),
                 "raw": data if data is not None else r.get("text")}
 
+# 生效条件：给定 required 形参 content（importance 省略时取 0.9 并 float() 转换；tags 为 None/[]/"" 等假值时按 tags or ["md_cg","whitebox-probe"] 回落为 list(["md_cg","whitebox-probe"])）即转调 self.call("remember", {...})，返回 {ok: not r["isError"], raw: r.get("data") or r.get("text")}。
     def remember(self, content, importance=0.9, tags=None):
         """白箱编码（remember）：把一条知识交给白箱写入其记忆库。"""
         r = self.call("remember", {"content": content,
@@ -108,6 +113,7 @@ class _WhiteboxApi:
         return {"ok": not r["isError"], "raw": r.get("data") or r.get("text")}
 
 
+# 生效条件：以假值 cmd（None/空序列）构造时 self.cmd 取 _launch_cmd()，真值 cmd 时取 list(cmd)；timeout 与 MDCG_WHITEBOX_TIMEOUT 环境变量都取假值时 self.timeout 为 float(60.0)，否则取其中首个真值；env 为真值时按 str(v) 合并进 os.environ 副本，假值时 self.env 仅为 os.environ 副本。
 class _SubprocessWhiteboxClient(_WhiteboxApi):
     """外部白箱 MCP stdio 客户端（legacy 路径，需显式配置才启用）。
 
@@ -115,6 +121,7 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
     进程懒启动、调用串行化、超时即杀（下次调用自动重启）。
     """
 
+# 生效条件：cmd 为真值时 self.cmd=list(cmd)，否则回落 _launch_cmd()；timeout 为真值则直接用，否则回落 os.environ.get("MDCG_WHITEBOX_TIMEOUT")，再否则 60.0；env 为真值时其键值经 str() 合并进 os.environ 副本。
     def __init__(self, cmd=None, env=None, timeout=None):
         self.cmd = list(cmd) if cmd else _launch_cmd()
         self.timeout = float(timeout or os.environ.get("MDCG_WHITEBOX_TIMEOUT") or 60.0)
@@ -127,6 +134,7 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
         self._lock = threading.Lock()
 
     # -- 生命周期 ---------------------------------------------------------
+# 生效条件：当 self.proc 非 None 且 self.proc.poll() 为 None 时直接返回 self；否则启动 self.cmd 子进程并以模块级常量 PROTOCOL_VERSION 与 CLIENT_NAME 发 initialize 请求和 notifications/initialized 通知后返回 self。
     def start(self):
         if self.proc is not None and self.proc.poll() is None:
             return self
@@ -143,6 +151,7 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
         self._notify("notifications/initialized", {})
         return self
 
+# 生效条件：幂等、可重复调用；self.proc 为 None 时直接返回；否则先关 stdin 再 terminate 并 wait(timeout=3)，超时或异常则 kill 兜底；无返回值、不抛异常；
     def close(self):
         proc, self.proc = self.proc, None
         if proc is None:
@@ -162,6 +171,7 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
                 pass
 
     # -- 内部 IO ----------------------------------------------------------
+# 生效条件：self.proc 为 None 或 proc.stdout 为 None 时直接返回；否则逐行 strip 后跳过空行，非空行 json.loads 成功则放入 self._q，抛 ValueError 则跳过该行。
     def _reader(self):
         stream = self.proc.stdout if self.proc else None
         if stream is None:
@@ -175,15 +185,18 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
             except ValueError:
                 continue
 
+# 生效条件：给定 required 形参 payload 时，若 self.proc is None 或 self.proc.poll() is not None 则抛 RuntimeError("白箱进程未运行（启动失败或已退出）")，否则把 json.dumps(payload, ensure_ascii=False) + "\n" 写入 self.proc.stdin 并 flush，无返回。
     def _write(self, payload):
         if self.proc is None or self.proc.poll() is not None:
             raise RuntimeError("白箱进程未运行（启动失败或已退出）")
         self.proc.stdin.write(json.dumps(payload, ensure_ascii=False) + "\n")
         self.proc.stdin.flush()
 
+# 生效条件：给定 required 形参 method 与 params 时，以 {"jsonrpc": "2.0", "method": method, "params": params}（无 id）调用 self._write，自身无返回。
     def _notify(self, method, params):
         self._write({"jsonrpc": "2.0", "method": method, "params": params})
 
+# 生效条件：给定 required 形参 method 与 params 时在 self._lock 内取自增 id 并写入请求，随后循环取 self._q：remain <= 0 或 queue.Empty 时先 self.close() 再抛 TimeoutError，msg.get("id") 不等于 rid 时 continue，msg.get("error") 为真时抛 RuntimeError，id 匹配且无 error 时返回 msg.get("result")（缺 "result" 键返回 None）。
     def _request(self, method, params):
         with self._lock:
             rid = self._next_id
@@ -208,6 +221,7 @@ class _SubprocessWhiteboxClient(_WhiteboxApi):
                 return msg.get("result")
 
     # -- 业务接口 ---------------------------------------------------------
+# 生效条件：给定 required 形参 name 与 args（args 为假值时按 {"name": name, "arguments": args or {}} 发空字典）即以 "tools/call" 发请求，把结果 content 中 type=="text" 的块文本拼接后 json.loads，失败（ValueError/TypeError）则 data=None，返回 {"isError": bool((result or {}).get("isError")), "text": text, "data": data}。
     def call(self, name, args):
         """调用白箱 MCP 工具，返回 {isError, text, data}。"""
         result = self._request("tools/call", {"name": name, "arguments": args or {}})
@@ -234,32 +248,38 @@ class LocalWhiteboxClient(_WhiteboxApi):
     故 `ask / remember / ping / verify_*` 及其留痕逻辑无需任何改动。
     """
 
+# 生效条件：db_path 为 None 时由引擎按默认路径取库；_ignored 吞掉子进程版遗留形参以保持接口同形；构造只记录路径、不加载引擎（延迟到 self.engine 首次访问）；
     def __init__(self, db_path=None, **_ignored):
         self.db_path = db_path
         self._engine = None
 
     @property
+# 生效条件：self._engine 为 None 时调用 _load_get_engine()(db_path=self.db_path) 创建并缓存后返回它，非 None 时直接返回缓存实例。
     def engine(self):
         if self._engine is None:
             self._engine = _load_get_engine()(db_path=self.db_path)
         return self._engine
 
     # -- 生命周期（与子进程版语义对齐：start 即确保可用，失败即抛） --------
+# 生效条件：先取 self.engine（首次访问才真正加载知识库）并调 service_info() 以确认可服务，不可用即抛；成功后返回 self，可重复调用；
     def start(self):
         _ = self.engine.service_info()
         return self
 
+# 生效条件：幂等；self._engine 为 None 时直接返回，否则关闭引擎并置 None（只释放句柄，不删除落盘数据）；
     def close(self):
         if self._engine is not None:
             self._engine.close()
             self._engine = None
 
     # -- 业务接口 ---------------------------------------------------------
+# 生效条件：给定 required 形参 name 与 args 时直接转调 self.engine.call_tool(name, args) 并返回其结果，不做任何形参改写或校验。
     def call(self, name, args):
         """调用白箱工具，返回 {isError, text, data}（形状对齐 MCP）。"""
         return self.engine.call_tool(name, args)
 
 
+# 生效条件：无必需形参；包内 from .whitebox_kb.engine import get_engine 成功时返回它，ImportError 时改为 from whitebox_kb.engine import get_engine 并返回。
 def _load_get_engine():
     """兼容两种导入方式（包内 / 平铺）。"""
     try:
@@ -269,6 +289,7 @@ def _load_get_engine():
     return get_engine
 
 
+# 生效条件：cmd 或 env 为真，或 MDCG_WHITEBOX_CMD / MDCG_WHITEBOX_ARGS 为真时返回 _SubprocessWhiteboxClient(cmd=cmd, env=env, timeout=timeout)，否则返回 LocalWhiteboxClient(db_path=db_path)。
 def WhiteboxClient(cmd=None, env=None, timeout=None, db_path=None):
     """白箱客户端工厂。
 
@@ -286,6 +307,7 @@ def WhiteboxClient(cmd=None, env=None, timeout=None, db_path=None):
 # 结果归一化
 # --------------------------------------------------------------------------
 
+# 生效条件：data 为 dict 时按 route、mode、path 顺序取首个非空 str 值返回，否则（含 data 非 dict、三键均无或均为空/非 str）返回 ""。
 def _extract_route(data):
     if isinstance(data, dict):
         for key in ("route", "mode", "path"):
@@ -295,6 +317,7 @@ def _extract_route(data):
     return ""
 
 
+# 生效条件：data 为 dict 时先按 reply/answer/text/response/content/message 取首个 strip 后非空的 str 返回，再对 result、data 两键的 dict 值递归取非空结果，均无则返回 fallback or ""。
 def _extract_reply(data, fallback=""):
     if isinstance(data, dict):
         for key in ("reply", "answer", "text", "response", "content", "message"):
@@ -314,6 +337,7 @@ def _extract_reply(data, fallback=""):
 # 验证：编码能力 / 已有知识回答能力
 # --------------------------------------------------------------------------
 
+# 生效条件：client 为 None 时自建 WhiteboxClient() 并在 finally 关闭；marker、fact、question 为假值时分别用带毫秒时间戳的默认口令、默认事实、默认追问，cg 仅传给 _record（cg 为 None 则 node_id 为 None，不自建 client），异常时返回 ok=False 并同样 _record。
 def verify_encoding(cg=None, client=None, marker=None, fact=None,
                     question=None, session_id="md_cg-whitebox-verify"):
     """验证白箱「编码能力」。
@@ -346,6 +370,7 @@ def verify_encoding(cg=None, client=None, marker=None, fact=None,
             cli.close()
 
 
+# 生效条件：client 为 None 时自建 WhiteboxClient() 并在 finally 关闭；questions 为假值（None 或空）时用 DEFAULT_KNOWLEDGE_PROBES，逐问后仅当至少一问 reply 非空且 route 为 self 或 self_fallback 时 ok=True，异常返回 ok=False。
 def verify_existing(cg=None, client=None, questions=None,
                     session_id="md_cg-whitebox-verify"):
     """验证白箱「已有知识回答能力」。
@@ -380,6 +405,7 @@ def verify_existing(cg=None, client=None, questions=None,
             cli.close()
 
 
+# 生效条件：client 为 None 时自建 WhiteboxClient() 并在 finally 关闭；依次对 service_info、mdcg_service_info、info 调用 call，首个 isError 为假即返回 ok=True 与该 tool/info，全部不可用返回 ok=False，start 或整体异常返回 ok=False。
 def ping(client=None, session_id="md_cg-whitebox-ping"):
     """白箱连通性探测：调 service_info（或 info）判断能力库是否在线。"""
     own = client is None
@@ -402,6 +428,7 @@ def ping(client=None, session_id="md_cg-whitebox-ping"):
             cli.close()
 
 
+# 生效条件：client 为 None 时以 WhiteboxClient(timeout=kw.get("timeout")) 自建并在 finally 关闭；随后 cli.start() 并返回 cli.ask(message, session_id=session_id)。
 def ask(message, session_id="md_cg-whitebox-verify", client=None, **kw):
     """显式调用白箱回答一个问题。"""
     own = client is None
@@ -414,6 +441,7 @@ def ask(message, session_id="md_cg-whitebox-verify", client=None, **kw):
             cli.close()
 
 
+# 生效条件：client 为 None 时以 WhiteboxClient(timeout=kw.get("timeout")) 自建并在 finally 关闭；随后 cli.start() 并返回 cli.remember(content, importance=importance, tags=tags)。
 def remember(content, importance=0.9, tags=None, client=None, **kw):
     """显式调用白箱编码一条知识。"""
     own = client is None
@@ -430,6 +458,7 @@ def remember(content, importance=0.9, tags=None, client=None, **kw):
 # 留痕与报告
 # --------------------------------------------------------------------------
 
+# 生效条件：cg 为 None 时返回 None；否则以 whitebox_verify_{kind}_{毫秒时间戳} 为 id 调 cg.add 写入 self 层，成功返回该 nid，cg.add 抛异常时返回 None。
 def _record(cg, kind, ok, payload):
     """把验证结论写入认知图（self 层）。失败不阻断验证本身。"""
     if cg is None:
@@ -446,6 +475,7 @@ def _record(cg, kind, ok, payload):
         return None
 
 
+# 生效条件：cg 为 None 时返回 {'ok': False, 'error': '需要 cg 实例'}；否则以 k=int(limit or 20)（limit 为 0/空串/None 时 k 变 20）调 cg.search("白箱能力验证", layer="self", record=False)，只保留 tags 中任一以 "whitebox:" 开头的项并返回 count 与 items。
 def report(cg=None, limit=20):
     """汇总最近的「白箱能力验证」留痕。"""
     if cg is None:
@@ -467,6 +497,7 @@ def report(cg=None, limit=20):
 # MCP 统一入口（由 mcp_server._whitebox_call 调用）
 # --------------------------------------------------------------------------
 
+# 生效条件：action=(args.action or "ping") 小写后，ask/chat/query 走 ask（question/message/query 均假则传 ""），remember/encode/write 走 remember 且 importance=float(a.get("importance", 0.9))，verify_encoding/encoding 走 verify_encoding，verify_existing/existing/knowledge 走 verify_existing（questions 取 a.questions 或 a.question 单元素列表），report/history 走 report(limit=int(a.get("limit") or 20))，ping/status/info 走 ping()，其余抛 ValueError。
 def dispatch(cg, args):
     """cg(op=whitebox) 的分发：action=ask|remember|verify_encoding|verify_existing|ping|report。"""
     a = args or {}
@@ -494,4 +525,4 @@ def dispatch(cg, args):
 
 
 if __name__ == "__main__":  # 手动自检：python -m md_cg.whitebox
-    print(json.dumps(ping(), ensure_ascii=False, indent=2))
+    print(json.dumps(ping(), ensure_ascii=False, indent=2))