@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/twophase.py

@@ -56,10 +56,12 @@ R_MISMATCH = "content_mismatch"         # 落了别的正文 → interrupted（
 R_UNREADABLE = "node_unreadable"        # 读节点失败 → interrupted（不猜测）
 
 
+# 生效条件：给定 cg 且其 root 属性可参与 os.path.join 时，恒返回 os.path.join(cg.root, LOG_FILE)，无分支与早退。
 def log_path(cg) -> str:
     return os.path.join(cg.root, LOG_FILE)
 
 
+# 生效条件：text 为假值（None/""）时按空串处理，否则用 text 本身，返回去尾换行后的字符串（仅剥 "\n"）。
 def _norm(text: str) -> str:
     """正文口径归一（**对账正确性的前提**）：`nodefile.dumps` 写盘时会给正文补尾
     换行，`loads` 读回即带它。若 intent 按入参原文、对账按读回内容各算一次指纹，
@@ -69,10 +71,12 @@ def _norm(text: str) -> str:
     return (text or "").rstrip("\n")
 
 
+# 生效条件：给定 cg 与 rec 时，把 rec 以 JSONL 追加写入 log_path(cg)，无返回值、无分支。
 def _append(cg, rec: dict) -> None:
     append_jsonl(log_path(cg), rec)
 
 
+# 生效条件：pr 取自 cg.principal 或（假值时）回落 cg.session——pr 为真字符串时 meta["session"]=pr；否则 pr 非 None 时把 pr.session 记入 session、把 pr.writer 或（假值时）pr.unit 记入 writer；actor 为真时 meta["actor"]=actor，最后返回 meta。
 def _ident(cg, actor=None) -> dict:
     """归因字段（尽力而为）：principal 缺省时留空，不编造。"""
     pr = getattr(cg, "principal", None) or getattr(cg, "session", None)
@@ -91,6 +95,7 @@ def _ident(cg, actor=None) -> dict:
     return meta
 
 
+# 生效条件：给定 cg、node_id、content 时生成 iid 与 content_hash（对 _norm(content) 计算），先写 phase="intent" 记录再返回 tok；layer 为真才写入 rec["layer"]，actor 与 **meta 分别经 _ident、rec.update 合入。
 def begin(cg, node_id: str, content: str, layer: str = None,
           actor: str = None, **meta) -> dict:
     """记录写入**意图**（先行持久化）→ 返回令牌 tok（供 `commit` 配对）。
@@ -112,6 +117,7 @@ def begin(cg, node_id: str, content: str, layer: str = None,
     return tok
 
 
+# 生效条件：nid 取 node_id，node_id 为假值（None/""）时回落 (tok or {}).get("node_id")，iid 取 (tok or {}).get("iid")（tok 为假值时两项均为 None）；status 用实参或默认 STATUS_COMMITTED；tok 为真且 tok.get("content_hash") 为真才写入 content_hash；reason 为真才写入 rec["reason"]；追加记录后返回 rec。
 def commit(cg, tok: dict, status: str = STATUS_COMMITTED, node_id: str = None,
            reason: str = None, **meta) -> dict:
     """记录写入**结果**（与 intent 按 iid 配对）。返回结果记录。"""
@@ -131,6 +137,7 @@ def commit(cg, tok: dict, status: str = STATUS_COMMITTED, node_id: str = None,
 # ----------------------------------------------------------------------
 # 读侧：盘点 / 对账
 
+# 生效条件：log_path(cg) 不是文件时直接返回空列表；否则逐行读取，空行跳过，json.loads 抛异常的行跳过，返回成功解析的记录列表。
 def records(cg) -> list:
     """读全部账本记录（append-only，坏行跳过不炸）。"""
     out = []
@@ -149,6 +156,7 @@ def records(cg) -> list:
     return out
 
 
+# 生效条件：遍历 records(cg)，记录 r.get("iid") 为假值（缺键或空串）时跳过；否则按 iid 建槽，仅当槽内 intent/outcome 仍为 None 时分别填入首个 phase=="intent" / phase=="outcome" 的记录，返回 pairs。
 def _pair(cg) -> dict:
     """把账本配成 {iid: {"intent":…, "outcome":…}}（同时计入无 iid 的脏行）。"""
     pairs = {}
@@ -164,6 +172,7 @@ def _pair(cg) -> dict:
     return pairs
 
 
+# 生效条件：遍历 _pair(cg) 取有 intent 且 outcome 为 None 的槽（展开 intent 字段）组成 out，按 r.get("t") or 0 升序排序后返回 out[:max(0, int(limit))]——limit 为 0 或负数时切片为空列表，默认值 200 仅在未传参时生效。
 def pending(cg, limit: int = 200) -> list:
     """未结清的写入意图（有 intent 无 outcome）——只读，不改盘。
 
@@ -177,6 +186,7 @@ def pending(cg, limit: int = 200) -> list:
     return out[:max(0, int(limit))]
 
 
+# 生效条件：intent 的 id 为假值或 cg.get(nid) 抛异常时返回 (STATUS_INTERRUPTED, R_UNREADABLE)；取回 node 为假值时返回 (STATUS_INTERRUPTED, R_NODE_MISSING)；intent 的 content_hash 为真且与 _norm(node.get("content") or "") 的指纹不等时返回 (STATUS_INTERRUPTED, R_MISMATCH)；否则返回 (STATUS_COMMITTED, R_NODE_OK)。
 def _judge(cg, intent: dict):
     """判定一笔未结清意图的真实结局 → `(status, code)`。**不猜测**：读不到就如实说。"""
     nid = intent.get("id")
@@ -195,6 +205,7 @@ def _judge(cg, intent: dict):
     return STATUS_COMMITTED, R_NODE_OK
 
 
+# 生效条件：以 limit 调 pending(cg, limit=limit) 得到未结清意图并统计 unpaired/committed/interrupted；apply 为真时对每笔 intent 调 commit 补写 outcome（reconciled=True、actor="twophase:reconcile"），apply 为假值时只报告不写账本，rep["applied"]=bool(apply)；limit 为 0 或负数时 pending 返回空、details 为空列表。
 def reconcile(cg, apply: bool = True, limit: int = 2000) -> dict:
     """启动/巡检对账：把半途写入**补账或如实标记**。
 
@@ -218,4 +229,4 @@ def reconcile(cg, apply: bool = True, limit: int = 2000) -> dict:
                         "content_hash": intent.get("content_hash")},
                    status=status, reason=code, reconciled=True,
                    actor="twophase:reconcile")
-    return rep
+    return rep

package/md_cg/units.py

@@ -14,7 +14,10 @@ crosscheck 同款 verdicts 通道回填）。理由：使用者的复核是昂
 蜂巢契约（真源 hive/README.md + hive/hive_mcp/mcp_server.py；**复制契约不 import**，
 保持 md_cg 对 hive 零依赖，与 ccgc「同款语义就地实现防 import 环」惯例一致）：
     jobs 目录   = $HIVE_JOBS_DIR | <repo>/hive/jobs
-    serve 判活  = jobs/_serve.json 的 ts（毫秒）距今 < 5s        （同 _serve_alive）
+    serve 判活  = **三层**：jobs/_serve.json 的 ts（毫秒）距今 < FRESH_S(15s)
+                  ∧ pid 存活 ∧ 该 pid 是本程序
+                  （同 hive/serve_start.serve_alive；四路口径由
+                   hive/test_serve_entry.py 机械守卫）
     job 目录    = jobs/<job_id>/{spec.json,status.json,result.json,kill}
     job_id      = h<java_ms>_<uuid6>                             （同 _submit）
     result.json = {"ok":true,"content":...} | {"ok":false,"error":...}
@@ -45,8 +48,16 @@ SERVE_FILE, SPEC_FILE = "_serve.json", "spec.json"
 STATUS_FILE, RESULT_FILE, KILL_FILE = "status.json", "result.json", "kill"
 LOG_NAME = "_units.jsonl"
 TERMINAL_STATES = ("done", "error", "timeout", "killed")
-FRESH_S, DEFAULT_TIMEOUT_S, DEFAULT_POLL_S = 5.0, 120, 1.0
-DEFAULT_MAX_TOKENS = 2048
+#: serve 心跳新鲜窗口（秒）。**须与 hive/serve_start.FRESH_S 同值**——本模块
+#: 只持有「判活的第 4 处实现」（复制契约不 import hive），阈值/判据结构若与
+#: 权威漂移，会在通道选择面复现 v13 的「假存活」病类（v14 缺陷 E：
+#: 旧值 5.0 vs 权威 15，serve 崩溃后 ≤5s 窗口内判「存活」→ 选 hive 通道 →
+#: 提交的 job 永远无人处理）。守卫：hive/test_serve_entry.py。
+FRESH_S, DEFAULT_TIMEOUT_S, DEFAULT_POLL_S = 15.0, 120, 1.0
+#: 复核委派的 completion 预算。**必须对齐统一默认（文档：最大输出 200000）**——
+#: 该模型 reasoning 与正文**共享 completion 预算**，小预算会把正文吃光并静默返回空正文：
+#: 实测 2048 → reasoning 2048 / content 空；16384 → 时好时坏；200000 → 正常出裁决。
+DEFAULT_MAX_TOKENS = 200000
 
 ENV_JOBS_DIR, ENV_EXE = "HIVE_JOBS_DIR", "HIVE_EXE"
 ENV_MODEL, ENV_API_KEY = "MDCG_UNIT_MODEL", "HIVE_API_KEY"
@@ -61,16 +72,19 @@ _VERDICT_MAP = {
 }
 
 
+# 生效条件：无入参，恒返回模块 `__file__` 绝对路径上溯两级的目录（md_cg 的上一级），与 cwd 无关。
 def repo_root() -> str:
     """仓库根（md_cg 的上一级）；不用 cwd——cwd 由宿主决定，不可作判据。"""
     return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
 
+# 生效条件：explicit 为真值时 d=explicit；explicit 为空串等假值而 ENV_JOBS_DIR 有真值时 d=该环境变量；两者皆假值时 d=repo_root()/hive/jobs；最终返回 os.path.abspath(d)。
 def jobs_dir(explicit: str = "") -> str:
     d = explicit or os.environ.get(ENV_JOBS_DIR) or os.path.join(repo_root(), "hive", "jobs")
     return os.path.abspath(d)
 
 
+# 生效条件：ENV_EXE 有真值时原样返回该值；ENV_EXE 缺失或为空串时返回 repo_root()/hive/target/release/ 下按 os.name=="nt" 取 hive.exe、否则取 hive 的拼接路径。
 def exe_path() -> str:
     exe = os.environ.get(ENV_EXE)
     if exe:
@@ -79,13 +93,81 @@ def exe_path() -> str:
                         "hive.exe" if os.name == "nt" else "hive")
 
 
+# 生效条件：explicit 为真值时取 explicit，否则取 ENV_MODEL，两者皆假值时按空串，返回该结果 strip() 后的字符串（可为空串）。
 def model_name(explicit: str = "") -> str:
     """复核模型（LLM 委托型执行器的 spec.model 必填）。"""
     return (explicit or os.environ.get(ENV_MODEL) or "").strip()
 
 
+# 生效条件：pid 为 int 且大于 0 时（否则 False），os.name 为 "nt" 时返回 _tasklist_row(pid) 是否非 None，非 "nt" 时 os.kill(pid, 0) 不抛 OSError 返回 True、抛 OSError 返回 False。
+def pid_alive(pid) -> bool:
+    """该 pid **号**是否存在（Windows tasklist 精确列比对 / unix `kill -0`）。
+
+    只回答「这个号有没有进程」——**不足以判定「serve 还在跑」**（见
+    `pid_is_self_program`）。实现与 hive/serve_start.pid_alive 同口径。
+    """
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    if os.name == "nt":
+        return _tasklist_row(pid) is not None
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+# 生效条件：对传入 pid 执行 tasklist /FO CSV 后，在其 stdout 中遇到的第一个按 '","' 切分、列数≥2 且第 2 列 strip 再 strip('"') 后等于 str(pid) 的行即返回 [映像名, pid 字符串]，无此行或 subprocess.run 抛 OSError 时返回 None。
+def _tasklist_row(pid):
+    """Windows：查该 pid 的 tasklist 行 → [映像名, pid 字符串]；查不到返回 None。
+
+    按列精确比对，**不用子串包含**——子串会让 pid=441 被 4410 命中（假存活）。
+    """
+    try:
+        # 显式 utf-8 + replace：只消费 ASCII 的 pid 列，但**不依赖 locale**——
+        # locale 口径与「后代写 UTF-8」不一致时读线程会崩（见 test_subproc_encoding.py）。
+        r = subprocess.run(["tasklist", "/FI", f"PID eq {pid}", "/NH", "/FO", "CSV"],
+                           capture_output=True, text=True,
+                           encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    for line in (r.stdout or "").splitlines():
+        cols = line.split('","')
+        if len(cols) >= 2 and cols[1].strip().strip('"') == str(pid):
+            return [cols[0].strip().strip('"'), cols[1].strip().strip('"')]
+    return None
+
+
+# 生效条件：exe_path() 的 basename 小写非空且 pid 为 int 大于 0 时（否则 False），"nt" 下要求 _tasklist_row(pid) 非空且映像名小写等于该 basename，非 "nt" 下要求 /proc/<pid>/cmdline 首个 b"\x00" 前 token 的 basename 小写等于它（读取抛 OSError 则 False）。
+def pid_is_self_program(pid) -> bool:
+    """该 pid 是否**就是本程序**（同映像名）——pid 号会被无关进程复用。
+
+    与 hive/serve_start.pid_is_self_program 同口径（复制契约）。零依赖边界：
+    拿不到映像名返回 False（宁可放行启动，也不误报「已有 serve 在跑」）。
+    """
+    want = os.path.basename(exe_path()).lower()
+    if not want or not isinstance(pid, int) or pid <= 0:
+        return False
+    if os.name == "nt":
+        row = _tasklist_row(pid)
+        return bool(row) and row[0].lower() == want
+    try:
+        with open(f"/proc/{pid}/cmdline", "rb") as f:
+            first = f.read().split(b"\x00")[0]
+    except OSError:
+        return False
+    return os.path.basename(first.decode("utf-8", "replace")).lower() == want
+
+
+# 生效条件：以 jobs_dir(jobs) 下的 SERVE_FILE 为心跳路径——该路径不被 isfile 命中时返回 exists/alive 均 False 的未启动 reason；命中但 open/json.load 抛 OSError 或 ValueError 时返回不可读 reason；解析成功后按**三层判据**（age < fresh_s ∧ pid_alive(pid) ∧ pid_is_self_program(pid)）定 alive，回填 age_s/pid/raw 与逐层明细及失败原因。
 def serve_state(jobs: str = "", fresh_s: float = FRESH_S) -> dict:
-    """serve 判活：只认 _serve.json 心跳新鲜度（同 _serve_alive），不试端口/进程名。"""
+    """serve 判活：**三层**（心跳新鲜 ∧ pid 存活 ∧ 该 pid 是本程序）。
+
+    与 `hive/serve_start.serve_alive` 同口径（同值 FRESH_S=15s、同三层判据）。
+    v14 缺陷 E：旧实现只判 ts 新鲜度且阈值 5s——双漂移，serve 崩溃后
+    ≤5s 内判「存活」会让 `probe()` 选 hive 通道（提交的 job 永远无人处理），
+    这正是 v13「假存活」病类从守卫面搬到了**通道选择面**。
+    """
     jd = jobs_dir(jobs)
     p = os.path.join(jd, SERVE_FILE)
     out = {"jobs_dir": jd, "heartbeat": p, "exists": os.path.isfile(p),
@@ -100,13 +182,28 @@ def serve_state(jobs: str = "", fresh_s: float = FRESH_S) -> dict:
         out["reason"] = "心跳不可读：%s: %s" % (type(exc).__name__, exc)
         return out
     age = time.time() - ((hb.get("ts") or 0) / 1000.0)
-    out.update({"age_s": round(age, 3), "pid": hb.get("pid"), "raw": hb})
-    out["alive"] = age < float(fresh_s)
-    out["reason"] = "" if out["alive"] else "心跳过期 %.1fs（阈值 %ss）——serve 可能已退出" % (
-        age, fresh_s)
+    pid = hb.get("pid")
+    fresh_ok = age < float(fresh_s)
+    pid_ok = pid_alive(pid)
+    ident_ok = pid_is_self_program(pid)
+    out.update({"age_s": round(age, 3), "pid": pid, "raw": hb,
+                "fresh": bool(fresh_ok), "pid_alive": bool(pid_ok),
+                "pid_is_self_program": bool(ident_ok)})
+    out["alive"] = bool(fresh_ok and pid_ok and ident_ok)
+    if out["alive"]:
+        out["reason"] = ""
+    elif not fresh_ok:
+        out["reason"] = "心跳过期 %.1fs（阈值 %ss）——serve 可能已退出" % (age, fresh_s)
+    elif not pid_ok:
+        out["reason"] = "心跳新鲜但 pid=%s 已不存在——serve 已退出" % (pid,)
+    else:
+        out["reason"] = ("心跳新鲜且 pid=%s 存活，但该 pid 不属于本程序"
+                         "（非 %s）——pid 号被无关进程复用"
+                         % (pid, os.path.basename(exe_path())))
     return out
 
 
+# 生效条件：jobs 仅经 jobs_dir(jobs) 用于填充指引里的 jobs 路径；reason 为假值时文案首行取“serve 未存活”，否则取 reason 原文；返回模板固定嵌入 exe_path() 的目录与路径、ENV_API_KEY、ENV_MODEL、jd、jd 下的 SERVE_FILE 与 int(FRESH_S)。
 def setup_hint(jobs: str = "", reason: str = "") -> str:
     """不可用时给使用者看的**配置指引**（含降级指引）——提示即责任，须可照着做。"""
     jd = jobs_dir(jobs)
@@ -123,6 +220,7 @@ def setup_hint(jobs: str = "", reason: str = "") -> str:
                ENV_MODEL, exe_path(), jd, os.path.join(jd, SERVE_FILE), int(FRESH_S)))
 
 
+# 生效条件：先取 st=serve_state(jobs, fresh_s) 与 mdl=model_name(model)；st["alive"] 为真且 mdl 非空时返回 state=HIVE；否则 allow_degrade 为真时返回 state=SUBAGENT 且 channel 取 channel 或 "harness-subagent"；否则返回 state=CONFIGURE、transport=None 并附 setup_hint(jobs, why)。
 def probe(jobs: str = "", model: str = "", fresh_s: float = FRESH_S,
           allow_degrade: bool = False, channel: str = "") -> dict:
     """三级能力探测：hive（可派发）→ configure（提示配置）→ subagent（显式降级）。
@@ -147,6 +245,7 @@ def probe(jobs: str = "", model: str = "", fresh_s: float = FRESH_S,
             "hint": setup_hint(jobs, why)}
 
 
+# 生效条件：state/transport/model/jobs_dir/serve/channel/hint 全部直接取自 probe(jobs, model, fresh_s, allow_degrade, channel) 的对应键，本函数不另做判活或模型判断，仅在 chain 文案中固定引用 int(FRESH_S) 与 ENV_MODEL。
 def plan(jobs: str = "", model: str = "", fresh_s: float = FRESH_S,
          allow_degrade: bool = False, channel: str = "") -> dict:
     """优先级链自描述（供 cg op=ccg action=units 与审计查看）。"""
@@ -155,7 +254,8 @@ def plan(jobs: str = "", model: str = "", fresh_s: float = FRESH_S,
             "jobs_dir": p["jobs_dir"], "serve": p["serve"], "channel": p["channel"],
             "chain": [
                 {"order": 1, "transport": HIVE, "action": "派发 reflect/verify 单元并等待 result.json",
-                 "when": "jobs/_serve.json 心跳 < %ss 且 %s 已配置" % (int(FRESH_S), ENV_MODEL)},
+                 "when": ("jobs/_serve.json 心跳 < %ss 且（%s 已配置 **或调用方显式传 model**）"
+                          % (int(FRESH_S), ENV_MODEL))},
                 {"order": 2, "transport": CONFIGURE, "action": "返回配置指引（不自动拉起、不假装通过）",
                  "when": "蜂巢不可用"},
                 {"order": 3, "transport": SUBAGENT, "action": "返回复核请求包，由 harness 端子代理执行并回填",
@@ -166,11 +266,13 @@ def plan(jobs: str = "", model: str = "", fresh_s: float = FRESH_S,
 
 # ---------------------------------------------------------------- 派发与收取
 
+# 生效条件：无入参，恒返回 "h"+int(time.time()*1000)+"_"+uuid.uuid4().hex 前 6 位组成的字符串。
 def _job_id() -> str:
     """同 _submit：serve 侧按 'h' 前缀识别任务目录。"""
     return "h%d_%s" % (int(time.time() * 1000), uuid.uuid4().hex[:6])
 
 
+# 生效条件：cg.root 与 cg.cg.root 都取不到真值时不写、直接返回 None；取到 root 时向 root/LOG_NAME 追加一行 rec（副本，setdefault ts）的 JSON，写入抛 OSError 时被吞掉静默返回 None。
 def _log(cg, rec: dict) -> None:
     """留痕 _units.jsonl（对齐 _crosscheck.jsonl / _backfill.jsonl 纪律）。"""
     root = getattr(cg, "root", None) or getattr(getattr(cg, "cg", None), "root", None)
@@ -185,6 +287,7 @@ def _log(cg, rec: dict) -> None:
         pass
 
 
+# 生效条件：role 不在 ROLES 时返回 ok=False 的未知角色 error；否则 model_name(model) 为空时返回 ok=False 的未配置复核模型；否则 str(prompt or "").strip() 为空时返回 ok=False 的 prompt 为空；否则在 jobs_dir(jobs)/_job_id() 下写 spec.json 与 status.json（context_files 为真、temperature 非 None、extra 为真时才并入 spec），OSError 时返回 ok=False 的写入失败，全部成功返回 ok=True 与 job_id/job_dir/spec/model。
 def submit(*, prompt: str, role: str = REFLECT, model: str = "", system_prompt: str = "",
            context_files=None, timeout_s: int = DEFAULT_TIMEOUT_S,
            max_tokens: int = DEFAULT_MAX_TOKENS, temperature=None, jobs: str = "",
@@ -226,6 +329,7 @@ def submit(*, prompt: str, role: str = REFLECT, model: str = "", system_prompt:
             "unit_role": role, "model": mdl}
 
 
+# 生效条件：jobs_dir(jobs)/str(job_id or "") 不是目录时返回 state=missing、terminal=False 的目录不存在 error；是目录时读 STATUS_FILE（读失败则 status 置 None）并用其 state 覆盖 state/terminal（state 属 TERMINAL_STATES 才 terminal=True）；RESULT_FILE 被 isfile 命中则 terminal=True、state=st or "done"，解析抛 OSError/ValueError 时提前返回该 error；解析为 dict 时取 ok/content/error/usage/model，且 ok 为真而 content 去空白为空时把 ok 改 False 并写空正文 error，解析为非 dict 时 ok=True 且 content 为原值。
 def poll(job_id: str, jobs: str = "") -> dict:
     """读 job 终态视图：**以 result.json 出现为终态主判据**，status.json 仅作辅助。"""
     d = os.path.join(jobs_dir(jobs), str(job_id or ""))
@@ -260,11 +364,19 @@ def poll(job_id: str, jobs: str = "") -> dict:
             out["error"] = res.get("error") or out["error"]
             out["usage"] = res.get("usage")
             out["model"] = res.get("model")
+            # 空正文**不得报成功**：reasoning 与正文共享 completion 预算，预算不足时
+            # job 仍自称 ok 但 content 为空 → 若不拦，会被误读成「复核单元无答复」
+            # （假死锁）。run() 早已有同等校验，此处补齐，消除两处口径不一致。
+            if out["ok"] and not str(out["content"] or "").strip():
+                out["ok"] = False
+                out["error"] = ("空正文：job 自称 ok 但 content 为空（多为 reasoning 吃尽"
+                                "完成预算；提高 max_tokens，勿把预算不足当通道不可用）")
         else:
             out["ok"], out["content"] = True, res
     return out
 
 
+# 生效条件：循环 poll(job_id, jobs)，结果 terminal 为真即补 waited_s 后返回；否则 time.time()-t0 >= float(timeout_s) 时返回 terminal=False、timeout=True 与超时 error；两者皆不满足则 sleep(float(poll_s)) 后重试（timeout_s=0 时首次 poll 非终态即超时返回）。
 def wait(job_id: str, *, jobs: str = "", timeout_s: float = DEFAULT_TIMEOUT_S,
          poll_s: float = DEFAULT_POLL_S) -> dict:
     """阻塞等终态；超时如实返回（不假装成功、不强杀 job）。"""
@@ -282,6 +394,7 @@ def wait(job_id: str, *, jobs: str = "", timeout_s: float = DEFAULT_TIMEOUT_S,
         time.sleep(float(poll_s))
 
 
+# 生效条件：submit(prompt=prompt, role=role, cg=cg, actor=actor, **kw) 的 ok 为假时返回 stage="submit" 的失败 dict（含 **sub）；ok 为真时 wait(sub["job_id"], jobs=kw.get("jobs",""), timeout_s=wait_s)，补 stage="wait"/job_id/unit_role/model，并把 ok 改为 res 的 ok 与 content 同时为真。
 def run(*, prompt: str, role: str = REFLECT, cg=None, actor: str = "",
         wait_s: float = DEFAULT_TIMEOUT_S, **kw) -> dict:
     """submit + wait 组合（阻塞式复核，MCP action=review 主路径）。"""
@@ -300,6 +413,7 @@ def run(*, prompt: str, role: str = REFLECT, cg=None, actor: str = "",
 _FENCE_RE = re.compile(r"```(?:json)?\s*(.+?)\s*```", re.S)
 
 
+# 生效条件：raw 是 dict/list 时原样返回；否则取 str(raw or "").strip()，为空串（含 0/False/None 等假值）返回 None；否则依次尝试 _FENCE_RE 第 1 组、整段文本、首个 "{" 到末个 "}" 及首个 "[" 到末个 "]" 的切片，返回首个能 json.loads 成 dict 或 list 的候选；全部失败返回 None。
 def _json_of(raw):
     """从单元输出抽第一个 JSON 对象/数组（容忍 ```json 围栏与前后噪声）。"""
     if isinstance(raw, (dict, list)):
@@ -326,6 +440,7 @@ def _json_of(raw):
     return None
 
 
+# 生效条件：data=_json_of(raw) 为 list 时取 data[0]（仅当它是 dict，否则 None）；非 dict 时返回 verdict=DEFER、parsed=False；dict 时 word 取 verdict/decision/state/result 中首个真值后 strip().lower()，_VERDICT_MAP.get(word) 为 None 时返回 DEFER、parsed=True 并带 corr 与 reason，命中时返回该裁决及 reason、slot_corrections（取自 slot_corrections/corrections，非 dict 则置 {}）、checks、raw 前 500 字符。
 def verdict_of(raw) -> dict:
     """单元输出 → 裁决四态；解析不出 → DEFER（不猜测、不当通过）。"""
     data = _json_of(raw)
@@ -347,6 +462,7 @@ def verdict_of(raw) -> dict:
             "checks": data.get("checks"), "raw": str(raw)[:500], "parsed": True}
 
 
+# 生效条件：state==HIVE 时返回 "hive:<role>:<job_id 或 'unknown'>"；state==SUBAGENT 时返回 "subagent:<role>:<channel 或 'harness'>"；其余 state 返回空串。
 def transport_name(state: str, role: str, job_id: str = "", channel: str = "") -> str:
     """裁决来源标识：**结构上不可能等于编译者**，保证 A 裁定「不得自证」不被误伤。"""
     if state == HIVE:
@@ -356,6 +472,7 @@ def transport_name(state: str, role: str, job_id: str = "", channel: str = "") -
     return ""
 
 
+# 生效条件：unit 为假值时按 {} 处理；verdict=unit.get("verdict") or DEFER，verifier=transport_name(state, role, job_id, channel)，evidence 取 unit 的 reason，为空则退回 str(unit["raw"])[:300]，job_id 为真时再追加“（job=<job_id>）”；仅当 unit 的 slot_corrections 为真才带该键，仅当 compiled_by 与 verifier 皆非空且相等才置 self_verify=True。
 def to_attest_args(unit: dict, *, state: str = "", role: str = REFLECT, job_id: str = "",
                    channel: str = "", compiled_by: str = "") -> dict:
     """单元裁决 → ccgc.attest(...) 入参（纯函数，离线可测）。
@@ -416,6 +533,7 @@ _VERIFY_TPL = """你是独立**验证单元**（verify）。对下面这份 CCG
 {{"verdict":"accept|drop|defer","reason":"一句话依据","slot_corrections":{{}}}}"""
 
 
+# 生效条件：digest is None 时返回 "{}"；digest 是 str 时原样返回；否则先试 to_dict/as_dict 可调用方法并 json.dumps 其返回值（抛异常即跳出改走后续分支）；是 dict 时 json.dumps(digest)；其余取 vars(digest) 中不以 "_" 开头的属性 json.dumps（default=str）。
 def _digest_of(digest) -> str:
     if digest is None:
         return "{}"
@@ -434,6 +552,7 @@ def _digest_of(digest) -> str:
                       ensure_ascii=False, indent=1, default=str)
 
 
+# 生效条件：role==VERIFY 选 _VERIFY_TPL，否则选 _REFLECT_TPL；reflect_rows 是 str 时直接作为 rows，否则 json.dumps(reflect_rows or [], ensure_ascii=False, indent=1)；最终返回 tpl.format(digest=_digest_of(digest), dialog=str(dialog or "（未提供）")[:6000], reflect_rows=rows[:3000])。
 def prompt_for(role: str, digest=None, *, dialog: str = "", reflect_rows="") -> str:
     """按角色生成复核请求包正文（reflect/verify 共用一处模板真源）。"""
     tpl = _VERIFY_TPL if role == VERIFY else _REFLECT_TPL
@@ -443,6 +562,7 @@ def prompt_for(role: str, digest=None, *, dialog: str = "", reflect_rows="") ->
                       reflect_rows=rows[:3000])
 
 
+# 生效条件：text 取 prompt 真值或 prompt_for(role, digest, dialog=dialog, reflect_rows=reflect_rows)；pr=probe(jobs, model, allow_degrade=allow_degrade, channel=channel) 为 SUBAGENT 时原样返回未派发的 SUBAGENT 包、为 CONFIGURE 时返回未派发的 CONFIGURE 包；为 HIVE 时若 autostart 为真且 serve_state(jobs) 非 alive 先 autostart_serve(jobs)，再 submit(...)，submit 失败回 CONFIGURE 且把 error 拼进 hint，成功则给出 job_id，blocking=False 直接返回；blocking=True 时 wait(sub["job_id"], jobs=jobs, timeout_s=wait_s)，res.ok 为假则 unit 记 DEFER 并附未产出有效结果的 hint，为真则 unit=verdict_of(res.get("content"))，随后填 transport/attest/result_ok/waited_s 并 _log。
 def review(*, prompt: str = "", role: str = REFLECT, digest=None, dialog: str = "",
            reflect_rows="", node_id: str = "", jobs: str = "", model: str = "",
            timeout_s: int = DEFAULT_TIMEOUT_S, allow_degrade: bool = False,
@@ -501,6 +621,7 @@ def review(*, prompt: str = "", role: str = REFLECT, digest=None, dialog: str =
 
 # ---------------------------------------------------------------- serve 拉起（显式）
 
+# 生效条件：serve_state(jobs_dir(jobs)) 已 alive 时返回 started=False 的“serve 存活”；否则 exe_path() 未被 isfile 命中时返回 started=False 并提示先 cargo build --release；否则以 detached/新会话 Popen 拉起 exe serve --jobs jd 并把 stdout/stderr 写入 jd/_serve.log，Popen 抛 OSError 时返回 started=False 的拉起失败；拉起后在 float(wait_s) 内轮询到 alive 返回 started=True 的“serve 已拉起”，轮询超时仍返回 started=True 但标注心跳未就绪。
 def autostart_serve(jobs: str = "", wait_s: float = 5.0) -> dict:
     """**显式**拉起 serve（默认不启用；使用者裁定：不可用即提示配置）。
 
@@ -532,6 +653,7 @@ def autostart_serve(jobs: str = "", wait_s: float = 5.0) -> dict:
     return {"started": True, "note": "serve 已拉起（心跳未就绪，稍后自愈）"}
 
 
+# 生效条件：返回 dict 的 ok=p["state"]==HIVE，其中 p=plan(jobs)（model/fresh_s/allow_degrade/channel 全走默认），state/serve_alive/serve_age_s/chain/hint/model 取自该 p；jobs_dir 取 jobs_dir(jobs)，exe_found 与 exe_path 取 exe_path() 是否被 isfile 命中，model_set=bool(model_name())（无参，读 ENV_MODEL），api_key_set=bool(os.environ.get(ENV_API_KEY))，env 记录 ENV_JOBS_DIR 与 ENV_MODEL 的原值。
 def doctor(jobs: str = "") -> dict:
     """能力体检（形态对齐 hive_doctor）：判活 + exe + 模型 + 优先级链。"""
     jd = jobs_dir(jobs)
@@ -543,4 +665,4 @@ def doctor(jobs: str = "") -> dict:
             "api_key_set": bool(os.environ.get(ENV_API_KEY)),
             "env": {"HIVE_JOBS_DIR": os.environ.get(ENV_JOBS_DIR, ""),
                     "MDCG_UNIT_MODEL": os.environ.get(ENV_MODEL, "")},
-            "chain": p["chain"], "hint": p["hint"]}
+            "chain": p["chain"], "hint": p["hint"]}

package/md_cg/vision_evidence.py

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