@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/comment_gate.py

@@ -0,0 +1,338 @@
+# -*- coding: utf-8 -*-
+"""comment_gate · 代码符号「条件化注释」抽样闸门（计划四环之环二入口）。
+
+**换对象不换机制**：复用 refine.py 的闸门范式（分层抽样 → 只读工单 → 人工裁决留痕 →
+通过率放行），把处理对象从「node_ 前缀的记忆节点 CCG 字段缺口」换成
+「code_ 前缀的代码符号注释缺口」。
+
+候选判据（唯一、机械、不做语义猜测）：**代码节点且正文缺『生效条件』**。
+依 Phase 0 契约，代码节点的生效条件只能来自源码人工声明——缺它即 BLINDSPOT
+（缺证据），正是本闸门要治理的对象。落点按使用者裁决 q-0：写进源码、定义行紧邻的
+井号注释（**两个窗口**，见 docs/mdcg/代码评审与条件化注释_契约_v0.1.md §三.2）。
+
+本模块只做**候选池 / 工单 / 留痕 / 闸门**：不生成注释、不改任何节点。
+生成与评审方式按 q-2（LLM 生成 + 人工抽检，复用 0.90 闸门）。
+
+诚实边界（honest_limits 已随 SPEC 一并输出）：
+· 分层抽样的**分配**沿用 refine.sample_ids 对 code_ 节点的口径（家族=大域），
+  而非对候选池重新分配——故 sample_adequacy 会如实报出样本里的候选产出率；
+  若产出率不足，应先扩大 n 或改用候选池重分配（已知待办，不在本片）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from . import codeindex, nodefile, refine
+
+#: 放行阈值**唯一真源在 refine**（不在此处再定义一份，防口径漂移）
+GATE_MIN_PASS_RATE = refine.GATE_MIN_PASS_RATE
+SAMPLE_N = refine.SAMPLE_N
+#: 本闸门自己的抽样种子（与 refine 的 g6-sample-v1 分离，样本可各自复算）
+SAMPLE_SEED = "comment-gate-v1"
+#: 代码节点 id 前缀（见 codeindex.node_id = code_ + sha1 前 12 位）
+PREFIX = "code_"
+LOG_NAME = "_comment_gate.jsonl"
+
+#: 人工核对清单（与工单逐项对应；对照 refine.SPEC.review_items 的同构位置）
+REVIEW_ITEMS = (
+    "生效条件是否为**功能前置条件**（何种输入/状态下正确），而非索引元条件",
+    "条件可否被机械复核（有输入/状态判据；不是「常用条件默认省略」）",
+    "落点是否为源码定义行紧邻的井号注释（两窗口之一），且不覆盖既有实现说明",
+    "公开仓合规：过第 14 条「内容政策 + 隐私」双清单（补写内容随源码公开）",
+)
+
+SPEC = {
+    "goal": "为代码符号补写功能级生效条件注释，使其在检索侧可判（不再因缺证据恒 BLINDSPOT）",
+    "target": "code_ 前缀节点中正文缺『生效条件』者",
+    "landing": "源码定义行紧邻的井号注释（leading/body 两窗口，物理序合并）",
+    "review_items": list(REVIEW_ITEMS),
+    "gate": {"min_pass_rate": GATE_MIN_PASS_RATE, "basis": "人工核对忠实比例",
+             "rule": "低于阈值不得扩批"},
+    "honest_limits": [
+        "本闸门只覆盖已索引的代码节点；未索引的源码不在面内（先跑 index_code）",
+        "分层分配沿用 code_ 节点口径而非候选池，样本候选产出率由 sample_adequacy 如实上报",
+        "不生成注释、不改节点：生成与评审属另一环节（LLM 生成 + 人工抽检）",
+    ],
+}
+
+
+# 生效条件：cg 传入后返回 os.path.join(cg.root, LOG_NAME)，即以 cg.root 与模块级常量 LOG_NAME 拼接的日志路径（cg 缺 root 属性时抛 AttributeError）。
+def _log_path(cg) -> str:
+    return os.path.join(cg.root, LOG_NAME)
+
+
+# 生效条件：cg 与 nid 传入后，先看 str(nid) 是否以模块级常量 PREFIX 开头（不以则返回 False）；以 PREFIX 开头时取 cg.get(nid)（缺节点按空字典）的 content（假值按空串）经 nodefile.ccg_completeness 判断，若 "生效条件" 不在其 required_present 中则返回 True，否则 False。
+def is_candidate(cg, nid) -> bool:
+    """候选判据：代码节点且正文缺『生效条件』（机械判据，唯一）。"""
+    if not str(nid).startswith(PREFIX):
+        return False
+    node = cg.get(nid) or {}
+    comp = nodefile.ccg_completeness(node.get("content") or "")
+    return "生效条件" not in comp["required_present"]
+
+
+# 生效条件：cg 与 nid 传入后，从 cg.get(nid)（缺节点按空字典）的 frontmatter（假值按空字典）的 code_ref（假值按空字典）中按 path/name/kind/lineno/end/lang/precise 各键取 ref.get(k)（缺键为 None），返回含 code_ref 与固定 landing_rule、landing_note 字段的落点字典。
+def _landing(cg, nid) -> dict:
+    """工单条目 → 源码落点（坐标 + 落点规则），供补写者直接定位。"""
+    node = cg.get(nid) or {}
+    fm = node.get("frontmatter") or {}
+    ref = fm.get("code_ref") or {}
+    return {
+        "code_ref": {k: ref.get(k) for k in
+                     ("path", "name", "kind", "lineno", "end", "lang", "precise")},
+        "landing_rule": "定义行紧邻上方连续井号注释（leading）或定义行紧邻下方、体首语句之前（body）",
+        "landing_note": "两窗口按源码物理行序合并；靠前者胜出（契约 §三.2）",
+    }
+
+
+# 生效条件：cg 与 nid 传入后，取 cg.get(nid)（缺节点按空字典）的 content（假值按空串）算长度与 refine._sha(content)[:16] 作为 source_sha，并结合 refine._entry(cg, nid) 的 layer/tags（tags 假值按空列表）与 nodefile.CCG_MARKS 得出 ccg_missing，最后合并 _landing(cg, nid) 的返回构成工单条目字典。
+def _item(cg, nid) -> dict:
+    node = cg.get(nid) or {}
+    content = node.get("content") or ""
+    comp = nodefile.ccg_completeness(content)
+    e = refine._entry(cg, nid)
+    it = {
+        "id": nid, "family": refine._family(cg, nid),
+        "layer": e.get("layer"), "tags": list(e.get("tags") or []),
+        "ccg_present": comp["present"],
+        "ccg_missing": [m for m in nodefile.CCG_MARKS if m not in comp["present"]],
+        "body_len": len(content),
+        "source_sha": refine._sha(content)[:16],
+    }
+    it.update(_landing(cg, nid))
+    return it
+
+
+# 生效条件：ids 非空时返回经 is_candidate(cg, i) 过滤后的显式候选与 meta.source='explicit_ids'；ids 为空时经 refine._pool(cg, PREFIX) 扫描返回候选与 meta.source='scan'（含 skipped_protected）。
+def candidates(cg, ids=None):
+    """候选池（只读）→ (ids, meta)。"""
+    if ids:
+        pool = sorted({str(i) for i in ids if is_candidate(cg, i)})
+        return pool, {"source": "explicit_ids", "pool": len(pool),
+                      "requested": len(pool), "candidates": len(pool)}
+    all_ids, protected = refine._pool(cg, PREFIX)
+    cands = sorted(i for i in all_ids if is_candidate(cg, i))
+    return cands, {"source": "scan", "prefix": PREFIX, "pool": len(all_ids),
+                   "skipped_protected": protected, "candidates": len(cands)}
+
+
+# 生效条件：seed 为假值（None/空串）时回落模块常量 SAMPLE_SEED，n 仅当为 None 时取 SAMPLE_N、否则 int(n)（n=0 保留 0）；ids 为真值时样本取全部候选，为假值（含空列表）时经 refine.sample_ids 抽样后按 is_candidate 过滤。
+def plan(x, ids=None, n=None, seed=None) -> dict:
+    """抽检工单（只读）：确定性样本 + 源码落点 + 口径声明 + 样本充分性。"""
+    cg = refine._as_cg(x)
+    seed = seed or SAMPLE_SEED
+    n = SAMPLE_N if n is None else int(n)
+    cands, cmeta = candidates(cg, ids=ids)
+    if ids:
+        sample = sorted(cands)
+        smeta = {"pool": len(cands), "sampled": len(cands), "families": 0, "strata": {}}
+    else:
+        picked, smeta = refine.sample_ids(cg, n=n, seed=seed, prefix=PREFIX)
+        sample = sorted(i for i in picked if is_candidate(cg, i))
+    items = [_item(cg, nid) for nid in sample]
+    strata = {}
+    for it in items:
+        s = strata.setdefault(it["family"], {"picked": 0, "missing_fields": {}})
+        s["picked"] += 1
+        for m in it["ccg_missing"]:
+            s["missing_fields"][m] = s["missing_fields"].get(m, 0) + 1
+    adequacy = {
+        "sample_of_code_nodes": smeta.get("sampled", len(sample)),
+        "candidates_in_sample": len(sample),
+        "candidate_yield": round(len(sample) / float(smeta.get("sampled") or 1), 4),
+        "note": "分配沿用 code_ 节点口径；产出率不足时应扩大 n 或改候选池重分配",
+    }
+    return {
+        "root": cg.root, "dry_run": True, "readonly": True,
+        "action": "comment_gate", "op": "maintain",
+        "prefix": PREFIX, "seed": seed, "requested": n,
+        "pool": cmeta, "sampled": len(items), "families": len(strata),
+        "sample": sample, "sample_sha": refine._sha(*sample)[:16] if sample else "",
+        "strata": strata, "items": items, "worklist": items,
+        "spec": SPEC, "gate_rule": SPEC["gate"], "sample_adequacy": adequacy,
+        "note": ("代码注释补写工单（只读）：供人工核对补写口径；"
+                 "核对通过率未达阈值前不得扩批。本动作不改任何节点。"),
+    }
+
+
+# 生效条件：verdicts（None 按 []）中可哈希且属于 okv 字面集合（True/"1"/"true"/"True"/"pass"/"PASS"/"faithful"/"忠实"/"accept"/"ACCEPT"）的项计 passed，dict 项在 `v in okv` 处不可哈希先抛 TypeError，故源码里 v.get("verdict") 的计数分支不可达；reviewed 为 0 时 rate=0.0、expand_allowed=False、reason="no_review"，否则按 rate 与模块常量 GATE_MIN_PASS_RATE 比较给出 expand_allowed 与 reason。
+def _stats(verdicts) -> dict:
+    """通过率（只认忠实/pass/True），阈值取 refine 唯一真源。"""
+    vs = list(verdicts or [])
+    okv = {True, "1", "true", "True", "pass", "PASS", "faithful", "忠实",
+           "accept", "ACCEPT"}
+    passed = 0
+    for v in vs:
+        if v in okv:
+            passed += 1
+        elif isinstance(v, dict) and v.get("verdict") in okv:
+            passed += 1
+    reviewed = len(vs)
+    rate = (passed / float(reviewed)) if reviewed else 0.0
+    allowed = reviewed > 0 and rate >= GATE_MIN_PASS_RATE
+    return {"reviewed": reviewed, "passed": passed, "pass_rate": round(rate, 4),
+            "min_pass_rate": GATE_MIN_PASS_RATE, "expand_allowed": allowed,
+            "reason": ("" if allowed else
+                       ("no_review" if reviewed == 0 else
+                        "rate %.4f < %.2f" % (rate, GATE_MIN_PASS_RATE)))}
+
+
+# 生效条件：x 传入后经 refine._as_cg 得到 cg，若 cg.principal 非 None 则调用其 require_admin("maintain_comment_gate")；随后调用 plan(cg, ids=ids, n=n, seed=seed) 取工单、调用 _stats(verdicts) 取闸门统计，batch 假值回落 time.strftime("%Y%m%d-%H%M%S")，os.makedirs(cg.root, exist_ok=True) 后把含 batch/actor/seed/pool/sample/verdicts/gate 等字段的记录以追加方式写入 _log_path(cg)，并返回 ok=True 的留痕结果。
+def apply(x, ids=None, n=None, seed=None, verdicts=None, actor=None, note=None,
+          batch=None) -> dict:
+    """落抽检批次 + 人工裁决到 _comment_gate.jsonl。**不改写任何节点**。
+
+    权限**自持在模块内**（与 refine 同档）：apply 虽只落留痕，但它决定后续是否放行
+    **扩批**，故按管理面处理。放在此处而非分发层，是为避免「分发面漏挂一道闸」
+    这类易失同步的权限缺口。
+    """
+    cg = refine._as_cg(x)
+    _principal = getattr(cg, "principal", None)
+    if _principal is not None:
+        _principal.require_admin("maintain_comment_gate")
+    p = plan(cg, ids=ids, n=n, seed=seed)
+    batch = batch or time.strftime("%Y%m%d-%H%M%S")
+    stats = _stats(verdicts)
+    rec = {"t": time.time(), "action": "comment_gate", "batch": batch, "actor": actor,
+           "seed": p["seed"], "requested": p["requested"], "pool": p["pool"],
+           "sampled": p["sampled"], "sample": p["sample"], "sample_sha": p["sample_sha"],
+           "sample_adequacy": p["sample_adequacy"], "verdicts": list(verdicts or []),
+           "gate": stats, "note": note}
+    os.makedirs(cg.root, exist_ok=True)
+    with open(_log_path(cg), "a", encoding="utf-8") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + chr(10))
+    return {"ok": True, "action": "comment_gate", "op": "maintain", "batch": batch,
+            "root": cg.root, "sampled": p["sampled"], "gate": stats, "log": LOG_NAME,
+            "note": ("抽检留痕已落盘（未改任何节点）；" +
+                     ("闸门放行扩批" if stats["expand_allowed"] else
+                      "闸门未放行：" + stats["reason"]))}
+
+
+# 生效条件：x 传入后经 refine._as_cg 得到 cg，读取 _log_path(cg) 且仅当 os.path.exists 为真时逐行解析（空行跳过、json.loads 抛 ValueError 的行跳过），batch 为真时仅保留 batch 字段匹配的记录；recs 为空时返回 expand_allowed=False、reason="no_batch"，否则取 recs[-1] 的 verdicts 经 _stats 复算并返回。
+def gate(x, batch=None) -> dict:
+    """扩批闸门：读留痕复算通过率（不写盘）。"""
+    cg = refine._as_cg(x)
+    recs = []
+    path = _log_path(cg)
+    if os.path.exists(path):
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue
+    if batch:
+        recs = [r for r in recs if r.get("batch") == batch]
+    if not recs:
+        return {"ok": True, "action": "comment_gate_gate", "op": "maintain",
+                "root": cg.root, "batch": batch, "batches": 0,
+                "expand_allowed": False, "reason": "no_batch"}
+    rec = recs[-1]
+    stats = _stats(rec.get("verdicts"))
+    return {"ok": True, "action": "comment_gate_gate", "op": "maintain",
+            "root": cg.root, "batch": rec.get("batch"),
+            "batches": len({r.get("batch") for r in recs}), **stats}
+
+
+# 生效条件：root 传入后调用 codeindex.index_dir 扫描（max_files 假值回落 500，max_items 假值回落 2000），对返回 items 的每条 comments（假值按空列表）逐条先 str(c).lstrip("#").strip() 再判断是否以 "生效条件" 开头，全部不以该串开头的项进入候选并返回含 items/errors/stats/examined/candidates 的字典。
+def candidates_from_sources(root, patterns=None, max_files=None, max_items=None,
+                            skip_dirs=None):
+    """**源级**候选枚举（不依赖认知图）：扫源码树，筛出注释里缺『生效条件』的符号。
+
+    为什么需要它（2026-09-17 实测）：真实库 2934 条 code_ 节点的生效条件 **100% 是旧 render
+    的合成值**，故**图内候选池为 0**；而「源码里哪些符号缺条件注释」是**源侧事实**，
+    无须先重索引（重索引会让 2934 条同时失去条件、判 BLINDSPOT）。本入口绕开该一次性代价。
+
+    判据唯一且机械：符号的 **井号注释窗口**（leading + body，见 codeindex）中不存在以
+    『生效条件』开头的行；只认井号注释、不认 docstring——落点按 q-0 裁决。
+    """
+    items, errors, stats = codeindex.index_dir(
+        root, patterns=patterns, max_files=int(max_files or 500),
+        max_items=int(max_items or 2000), skip_dirs=skip_dirs)
+    cands = []
+    for it in items:
+        has = any(str(c).lstrip("#").strip().startswith("生效条件")
+                  for c in (it.get("comments") or []))
+        if not has:
+            cands.append(it)
+    return {"root": root, "items": cands, "errors": errors, "stats": stats,
+            "examined": len(items), "candidates": len(cands),
+            "note": ("源级枚举：判据=井号注释窗口内无『生效条件』行；"
+                     "不含图内节点状态，故不受存量渲染影响")}
+
+
+# 生效条件：it 传入后取 it.get("path")（假值按空串）按 "/" 分割首段作为 family（首段为空则 family="."），并返回含 id=codeindex.node_id(it)、name/kind、code_ref（path/lineno/end/lang/precise 各缺省 None）、comments（假值按空列表逐项 str）、以及固定 landing_rule 与 landing_note 的字典。
+def _landing_src(it) -> dict:
+    return {"id": codeindex.node_id(it), "name": it.get("name"),
+            "kind": it.get("kind"),
+            "family": (it.get("path") or "").split("/")[0] or ".",
+            "code_ref": {"path": it.get("path"), "lineno": it.get("lineno"),
+                         "end": it.get("end"), "lang": it.get("lang"),
+                         "precise": it.get("precise")},
+            "comments": [str(c) for c in (it.get("comments") or [])],
+            "landing_rule": ("定义行紧邻上方连续井号注释（leading）或定义行紧邻下方、"
+                             "体首语句之前（body）"),
+            "landing_note": "两窗口按源码物理行序合并；靠前者胜出（契约 §三.2）"}
+
+
+# 生效条件：root 传入后调用 candidates_from_sources(root, patterns=patterns, skip_dirs=skip_dirs, max_files=max_files, max_items=max_items) 得候选，seed 假值回落 SAMPLE_SEED，n 为 None 时取 SAMPLE_N 否则 int(n)（0 保持 0），按 path 首段（空则 "."）分族与 sha(seed, node_id) 排序后做族间确定性轮转取至多 n 项，返回只读源级工单。
+def plan_sources(root, n=None, seed=None, patterns=None, skip_dirs=None,
+                 max_files=None, max_items=None) -> dict:
+    """**源级**工单（只读）：确定性抽样 + 源码落点；不依赖认知图、不改任何节点。
+
+    抽样口径：按大域（顶层目录）**确定性轮转**（族内按 sha(seed,id) 排序）。
+    刻意**不复制** refine 的浮点最大余数分配——那是第二份实现，会引入漂移；
+    源级候选列表是精确的（无「先抽样再过滤」的口径损失），轮转已给出跨族覆盖。
+    """
+    seed = seed or SAMPLE_SEED
+    n = SAMPLE_N if n is None else int(n)
+    got = candidates_from_sources(root, patterns=patterns, skip_dirs=skip_dirs,
+                                 max_files=max_files, max_items=max_items)
+    fams = {}
+    for it in got["items"]:
+        top = (it.get("path") or "").split("/")[0] or "."
+        fams.setdefault(top, []).append(it)
+    pools = {f: len(v) for f, v in fams.items()}
+    names = sorted(fams)
+    for f in names:
+        fams[f].sort(key=lambda it: refine._sha(seed, codeindex.node_id(it)))
+    picked = []
+    while len(picked) < n and any(fams[f] for f in names):
+        for f in names:
+            if fams[f] and len(picked) < n:
+                picked.append(fams[f].pop(0))
+    work = [_landing_src(it) for it in picked]
+    return {"root": root, "dry_run": True, "readonly": True, "mode": "source_level",
+            "action": "comment_gate_sources", "op": "maintain",
+            "seed": seed, "requested": n, "examined": got["examined"],
+            "candidates": got["candidates"], "sampled": len(work),
+            "families": len(pools), "strata": pools,
+            "items": work, "worklist": work, "spec": SPEC,
+            "scan_errors": list(got["errors"])[:10], "scan_stats": got["stats"],
+            "gate_rule": SPEC["gate"],
+            "note": ("源级工单（只读）：不依赖认知图、不改任何节点；"
+                     "抽样为按大域的确定性轮转。")}
+
+
+# 生效条件：x 与 action 传入后，action=="comment_gate" 时若 kw.get("apply") 为真则转 apply(x, ids,n,seed,verdicts,actor,note,batch)，否则转 plan(x, ids,n,seed)；action=="comment_gate_verdict" 时转 gate(x, batch)；action 为 "comment_gate_sources" 或 "comment_gate_source_plan" 时以 root=kw.get("root") or getattr(x,"root",None) or str(x) 转 plan_sources(...)；其余 action 抛 ValueError。
+def run(x, action, **kw) -> dict:
+    """maintain op 分派入口（与 backfill.run 同形，便于 mcp_server 侧并列分派）。"""
+    if action == "comment_gate":
+        if kw.get("apply"):
+            return apply(x, ids=kw.get("ids"), n=kw.get("n"), seed=kw.get("seed"),
+                         verdicts=kw.get("verdicts"), actor=kw.get("actor"),
+                         note=kw.get("note"), batch=kw.get("batch"))
+        return plan(x, ids=kw.get("ids"), n=kw.get("n"), seed=kw.get("seed"))
+    if action == "comment_gate_verdict":
+        return gate(x, batch=kw.get("batch"))
+    if action in ("comment_gate_sources", "comment_gate_source_plan"):
+        root = kw.get("root") or getattr(x, "root", None) or str(x)
+        return plan_sources(root, n=kw.get("n"), seed=kw.get("seed"),
+                            patterns=kw.get("patterns"), skip_dirs=kw.get("skip_dirs"))
+    raise ValueError("未知 comment_gate action：%s（允许 comment_gate / "
+                     "comment_gate_verdict）" % action)

package/md_cg/cond_compose.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""白箱条件填充器：把 cond_facts 的事实按 LLM 模板填成「功能级生效条件」（确定性、零 LLM）。
+
+# 功能名：生效条件白箱填充
+# 生效条件：已取得模板（md_cg/cond_template.json，由 LLM 产出并留痕）且有 cond_facts 事实时；用于批量生成候选注释文本
+# 子功能：按模板槽位 symbol/required/optional/externals/guards/returns/doc 组句；externals 剔除 import 来源与内置名；证据不足按模板规则输出 BLINDSPOT
+# 执行：python -X utf8 -m md_cg.cond_compose <file>... [--terse] [--json]；库内调用 compose_file(path)
+# 验证方式：md_cg/test_cond_compose.py；生成文本须过 condition_anchor.judge（ANCHORED 或 BLINDSPOT，不得 WEAK/REJECT_META）
+# 不适用条件：①本器只按事实填模板，**不新增语义**；证据不足即 BLINDSPOT ②--terse 会省略空槽位（与模板逐字填充不同，属受控偏离，见 README）③模板变更须同步本器槽位
+"""
+from __future__ import annotations
+
+import ast
+import builtins
+import json
+import os
+import sys
+
+from . import condition_anchor, cond_facts
+
+BUILTINS = set(dir(builtins))
+TPL_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "cond_template.json")
+
+
+# 生效条件：调用 load_template 时可选实参 path 为假值（None/空串等）则打开并 json.load 模块级常量 TPL_PATH，否则打开并解析 path，返回 json.load 得到的对象；
+def load_template(path=None):
+    return json.load(open(path or TPL_PATH, encoding="utf-8"))
+
+
+# 生效条件：调用 import_names 时必须提供 path，且对该 path 内容 ast.parse 抛 SyntaxError 时返回空集合，否则返回 ast.Import 的 (asname 或 name 首段) 与 ast.ImportFrom 的 (asname 或 name) 构成的集合；
+def import_names(path):
+    """该文件里 import 进来的名字（这些不是「状态来源」，是固定依赖，不进条件）。"""
+    names = set()
+    try:
+        tree = ast.parse(open(path, encoding="utf-8", errors="replace").read())
+    except SyntaxError:
+        return names
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for a in node.names:
+                names.add((a.asname or a.name).split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            for a in node.names:
+                names.add(a.asname or a.name)
+    return names
+
+
+# 生效条件：调用 module_constants 时必须提供 path，且对该 path 内容 ast.parse 抛 SyntaxError 时返回空集合，否则返回顶层 ast.Assign 的 Name 目标与 ast.AnnAssign 的 Name 目标构成的集合减去 import_names(path) 的结果；
+def module_constants(path):
+    """模块级常量名（顶层赋值目标）——它们是真正的『状态来源』，函数/类定义不算。"""
+    consts = set()
+    try:
+        tree = ast.parse(open(path, encoding="utf-8", errors="replace").read())
+    except SyntaxError:
+        return consts
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for t in node.targets:
+                if isinstance(t, ast.Name):
+                    consts.add(t.id)
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            consts.add(node.target.id)
+    return consts - import_names(path)
+
+
+# 生效条件：调用 explained_guards 时必须提供 rec、allowed，且 rec.get("guards") 的假值经 or [] 视为空，仅保留其中 g.get("early") 为真、且 g.get("cond")（假值经 or "" 按空串）内所有标识符都在 allowed、BUILTINS 或 self/cls 中的守卫并返回列表；
+def explained_guards(rec, allowed):
+    """只保留「早退式」且标识符全部可解释的守卫（模板校验清单第 6/9 条）。"""
+    out = []
+    for g in rec.get("guards") or []:
+        if not g.get("early"):
+            continue
+        ids = set(__import__("re").findall(r"[A-Za-z_][A-Za-z0-9_]*", g.get("cond") or ""))
+        if any(i not in allowed and i not in BUILTINS and i not in ("self", "cls") for i in ids):
+            continue
+        out.append(g)
+    return out
+
+
+def behavior_anchors(rec, allowed):
+    """可陈述的行为锚点：doc 摘要 / 早退式守卫 / 引用了入参或模块常量的返回表达式。
+
+    只有形参清单而没有任何行为锚点者，判 BLINDSPOT（验证单元实测：仅复述入参/局部变量表达式不算条件）。
+    """
+    import re as _re
+    doc = (rec.get("doc_head") or "").strip()
+    guards = explained_guards(rec, allowed)
+    rets = []
+    for r in rec.get("returns") or []:
+        ids = set(_re.findall(r"[A-Za-z_][A-Za-z0-9_]*", r))
+        if ids & allowed:          # 引用局部变量的返回表达式（如 d.strip()...）不作行为锚点
+            rets.append(r)
+    return doc, guards, rets
+
+
+# 生效条件：调用 compose 时必须提供 rec（且 rec 含 name 键，直接 rec["name"] 取值），imports、consts 为假值时回落为空集合，terse 控制空槽位是否省略；当 rec["required"] 为空且 rec["externals"] 中在 consts 内的项也为空时返回固定 BLINDSPOT 串，否则按 required/optional/externals/explained_guards/returns/doc_head 拼接并返回以“。”结尾的字符串；
+def compose(rec, imports=None, terse=True, consts=None):
+    """按模板把一条事实填成中文生效条件；terse=True 省略空槽位。"""
+    imports = imports or set()
+    consts = consts or set()
+    name = rec["name"]
+    required = list(rec.get("required") or [])
+    optional = list(rec.get("optional") or [])
+    # 外部名只保留「模块级常量」——它们才是可陈述的状态来源（函数与 import 不是条件）
+    externals = [x for x in (rec.get("externals") or []) if x in consts]
+    allowed = set(required) | {o["name"] for o in optional} | set(externals)
+    doc, guards, returns_ok = behavior_anchors(rec, allowed)
+    if not doc and not guards and not returns_ok:
+        return "BLINDSPOT：缺功能证据（仅形参清单，未描述功能前置状态或行为）"
+    returns = list(rec.get("returns") or [])
+    # 模板规则：必需与外部锚点皆无 → BLINDSPOT（不可判，不猜）
+    if not required and not externals:
+        return "BLINDSPOT：缺证据（无必需形参且无体内外部名锚点）"
+    parts = []
+    if required:
+        parts.append("必须提供实参 " + "、".join(required))
+    elif not terse:
+        parts.append("无必需实参")
+    if optional:
+        parts.append("可选 " + "、".join("%s=%s" % (o["name"], o["default"] or "None") for o in optional) + " 可省略")
+    elif not terse:
+        parts.append("无显式可选实参")
+    if externals:
+        parts.append("体内引用 " + "、".join(externals) + " 需已定义")
+    for g in guards:
+        if g["kind"] == "if":
+            parts.append("当 " + g["cond"] + " 成立")
+        elif g["kind"] == "assert":
+            parts.append("断言 " + g["cond"] + " 成立")
+        else:
+            parts.append("可能抛出 " + (g["cond"] or "异常"))
+    if returns_ok:
+        parts.append("返回 " + " 或 ".join(returns_ok[:2]))
+    head = "调用 " + name + " 时" if rec.get("kind") != "class" else "构造/使用 " + name + " 时"
+    body_text = head + "，" + "；".join(parts)
+    if doc:
+        # 不截断半个词：超长时在最近的句读处收口（校验器 C9 曾抓出 'option' ≠ 'referenced'）
+        short = doc if len(doc) <= 120 else doc[:120].rsplit("。", 1)[0] + "。"
+        body_text += "；功能：" + short.rstrip("。")
+    return body_text + "。"
+
+
+# 生效条件：调用 compose_symbol 时必须提供 path、rec（terse 可选），它用 path 取得 import 名与模块常量，以 rec 和 terse 调用 compose 生成 condition，再按 rec["lineno"] 与 rec["end"] 从 path 按换行切分的行列表切片交给 condition_anchor.judge，返回含 name/kind/lineno/end/condition/gate/anchors 的字典；
+def compose_symbol(path, rec, terse=True):
+    """生成并**当场过门禁**（condition_anchor.judge），返回条件与裁决。"""
+    imports = import_names(path)
+    consts = module_constants(path)
+    cond = compose(rec, imports=imports, terse=terse, consts=consts)
+    lines = open(path, encoding="utf-8", errors="replace").read().split(chr(10))
+    seg = chr(10).join(lines[max(0, rec["lineno"] - 1): rec["end"]])
+    verdict = condition_anchor.judge(cond, seg)
+    return {"name": rec["name"], "kind": rec["kind"], "lineno": rec["lineno"],
+            "end": rec["end"], "condition": cond, "gate": verdict["verdict"],
+            "anchors": verdict["anchors"]}
+
+
+# 生效条件：调用 compose_file 时必须提供 path（terse 可选），遍历 cond_facts.file_facts(path) 的每条 rec，调用 compose_symbol(path, rec, terse=terse)，返回全部结果组成的列表 out；
+def compose_file(path, terse=True):
+    out = []
+    for rec in cond_facts.file_facts(path):
+        out.append(compose_symbol(path, rec, terse=terse))
+    return out
+
+
+# 生效条件：调用 main 时省略 argv 或 argv 为 None 则取 sys.argv[1:]，否则使用传入 argv（空列表不回落），argv 含 "--terse" 则 terse=True，含 "--json" 则打印 rows 的 JSON 后返回 0，否则以非 "--" 开头的实参作为文件路径收集 rows，打印每个 gate/path/lineno/name/condition 与 STAT 统计后返回 0；
+def main(argv=None):
+    argv = list(argv if argv is not None else sys.argv[1:])
+    terse = "--terse" in argv
+    as_json = "--json" in argv
+    files = [a for a in argv if not a.startswith("--")]
+    rows = []
+    for f in files:
+        for r in compose_file(f, terse=terse):
+            r["path"] = f
+            rows.append(r)
+    if as_json:
+        print(json.dumps(rows, ensure_ascii=False, indent=1))
+        return 0
+    stat = {}
+    for r in rows:
+        stat[r["gate"]] = stat.get(r["gate"], 0) + 1
+    for r in rows:
+        print("[" + r["gate"] + "] " + r["path"] + ":" + str(r["lineno"]) + " " + r["name"])
+        print("    " + r["condition"][:200])
+    print("STAT " + json.dumps(stat, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())