@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/weights.py

@@ -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

@@ -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))