@furongjun1999/dsh-memory 0.4.7 → 0.4.9

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

package/md_cg/cond_facts.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""条件事实提取（白箱写注释的原料；确定性、零 LLM）。
+
+# 功能名：符号条件事实提取
+# 生效条件：给定一个 Python 源文件路径时；用于「白箱写功能级生效条件」的原料生成与门禁复核
+# 子功能：逐符号（函数/类，含嵌套）提取：必需/可选形参及默认值源码、体内引用的外部名、前置守卫（if/assert/raise 的首行）、返回表达式、docstring 摘要、行号区间
+# 执行：from md_cg import cond_facts；cond_facts.file_facts(path) -> list[dict]
+# 验证方式：md_cg/test_cond_facts.py（对样例源逐字段断言）
+# 不适用条件：①只取静态可判定事实，**不解释语义**②动态分派/装饰器改写签名时不保证签名即真实契约（须标 ambiguous）③非 Python 文件不支持
+"""
+from __future__ import annotations
+
+import ast
+import os
+
+
+# 生效条件：src_lines 与 node 能让 ast.get_source_segment(chr(10).join(src_lines), node) 成功取到片段时返回该源码段，取段为空或抛异常时返回 ""。
+def _src_seg(src_lines, node):
+    try:
+        return ast.get_source_segment(chr(10).join(src_lines), node) or ""
+    except Exception:
+        return ""
+
+
+# 生效条件：fn 为函数定义节点时，按其 defaults 与 kw_defaults 切分，返回 (排除 self/cls 的必需形参名列表, 含 name 与 default 源码的可选形参列表)。
+def _defaults(fn, src_lines):
+    """必需的形参名 + 可选形参 (名, 默认值源码)。"""
+    args = list(getattr(fn.args, "posonlyargs", [])) + list(fn.args.args)
+    defaults = list(fn.args.defaults)
+    n_opt = len(defaults)
+    head = args[:len(args) - n_opt] if n_opt else args
+    tail = args[len(args) - n_opt:] if n_opt else []
+    required = [a.arg for a in head if a.arg not in ("self", "cls")]
+    optional = []
+    for a, d in zip(tail, defaults):
+        optional.append({"name": a.arg, "default": _src_seg(src_lines, d)[:40]})
+    for a, d in zip(fn.args.kwonlyargs, fn.args.kw_defaults):
+        if d is None:
+            required.append(a.arg)
+        else:
+            optional.append({"name": a.arg, "default": _src_seg(src_lines, d)[:40]})
+    return required, optional
+
+
+# 生效条件：fn 具 body 时，扫描其前 6 条语句中的 If/Assert/Raise 并收集条件源码；If 仅在第 0 条且子树含 Return/Raise 时 early 为 True，Assert 与 Raise 的 early 为 True。
+def _guards(fn):
+    """前置守卫：函数体前若干语句中的 if/assert/raise（条件源码），代表显式前置契约。"""
+    out = []
+    body = getattr(fn, "body", []) or []
+    for i, st in enumerate(body[:6]):
+        if isinstance(st, ast.If):
+            # 仅「首条语句 + 体内含 return/raise」才算早退式前置契约；其余是函数内部分支，不是前置条件
+            early = (i == 0 and any(isinstance(x, (ast.Return, ast.Raise))
+                                    for x in ast.walk(st)))
+            out.append({"kind": "if", "cond": _unparse(st.test), "early": early})
+        elif isinstance(st, ast.Assert):
+            out.append({"kind": "assert", "cond": _unparse(st.test), "early": True})
+        elif isinstance(st, ast.Raise):
+            out.append({"kind": "raise", "cond": _unparse(st.exc)[:60] if st.exc else "",
+                        "early": True})
+    return out
+
+
+# 生效条件：node 能被 ast.unparse 成功解析时返回其源码前 80 字符，抛异常时返回 ""。
+def _unparse(node):
+    try:
+        return ast.unparse(node)[:80]
+    except Exception:
+    
+        return ""
+
+
+# 生效条件：fn 为函数定义节点时，返回其体内 value 非空的 Return 表达式源码去重后的前 3 项列表 out。
+def _returns(fn):
+    out = []
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Return) and node.value is not None:
+            s = _unparse(node.value)
+            if s and s not in out:
+                out.append(s)
+        if len(out) >= 3:
+            break
+    return out
+
+
+# 生效条件：fn 为函数定义节点时，返回其体内 ast.Name 引用名剔除 fn 的形参名、Store/Del 本地名及嵌套函数/异步函数定义名后取前 12 项的名字列表。
+def _externals(fn):
+    """体内引用的外部名（剔除形参与本地赋值）——即状态/常量来源。"""
+    params = set()
+    for a in list(getattr(fn.args, "posonlyargs", [])) + list(fn.args.args) + list(fn.args.kwonlyargs):
+        params.add(a.arg)
+    if getattr(fn.args, "vararg", None):
+        params.add(fn.args.vararg.arg)
+    if getattr(fn.args, "kwarg", None):
+        params.add(fn.args.kwarg.arg)
+    local = set()
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+            local.add(node.id)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node is not fn:
+            local.add(node.name)
+    names = []
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Name) and node.id not in params and node.id not in local:
+            if node.id not in names:
+                names.append(node.id)
+    return names[:12]
+
+
+# 生效条件：node 具非空 docstring 时返回其去空白首行的前 100 字符，无 docstring 时返回 ""。
+def _doc(node):
+    d = ast.get_docstring(node) or ""
+    return d.strip().split(chr(10))[0][:100]
+
+
+# 生效条件：path 指向的内容可按 utf-8 读取且 ast.parse 成功时，返回其中每个 FunctionDef/AsyncFunctionDef/ClassDef 节点的事实列表 out。
+def file_facts(path):
+    text = open(path, encoding="utf-8", errors="replace").read()
+    src_lines = text.split(chr(10))
+    tree = ast.parse(text)
+    out = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        kind = "class" if isinstance(node, ast.ClassDef) else (
+            "async_func" if isinstance(node, ast.AsyncFunctionDef) else "func")
+        if kind == "class":
+            required, optional, guards, returns, externals = [], [], [], [], []
+        else:
+            required, optional = _defaults(node, src_lines)
+            guards = _guards(node)
+            returns = _returns(node)
+            externals = _externals(node)
+        out.append({
+            "name": node.name,
+            "kind": kind,
+            "lineno": getattr(node, "lineno", 0),
+            "end": getattr(node, "end_lineno", 0),
+            "decorators": [ast.unparse(d)[:40] for d in getattr(node, "decorator_list", [])],
+            "required": required,
+            "optional": optional,
+            "externals": externals,
+            "guards": guards,
+            "returns": returns,
+            "doc_head": _doc(node),
+        })
+    return out
+
+
+if __name__ == "__main__":
+    import json
+    import sys
+    for p in sys.argv[1:]:
+        for f in file_facts(p):
+            print(json.dumps(f, ensure_ascii=False))

package/md_cg/cond_template.json

@@ -0,0 +1,107 @@
+{
+ "template": "调用 {symbol} 时，{required_clause}；{optional_clause}；{externals_clause}；{guards_clause}；在这些输入/状态下，{returns_clause}，功能说明为 {doc_clause}。",
+ "slots": [
+  {
+   "name": "symbol",
+   "from": "name",
+   "rule": "直接填 name；kind=func 时句首写“调用 name 时”；不得用 lineno、end、decorators 做条件。"
+  },
+  {
+   "name": "required_clause",
+   "from": "required",
+   "rule": "required 非空时填“必须提供实参 a、b”并列出全部 required；required 为空时填“无必需实参”；若 required 与 externals 均为空，整条输出 BLINDSPOT：缺证据（缺必需实参与外部名锚点）。"
+  },
+  {
+   "name": "optional_clause",
+   "from": "optional",
+   "rule": "optional 非空时逐个填“name 默认 default，可省略”；为空时填“无显式可选实参”；不得据默认值推断类型。"
+  },
+  {
+   "name": "externals_clause",
+   "from": "externals",
+   "rule": "externals 非空时填“体内引用的外部名 a、b 需在作用域中可解析”并列出全部；为空时填“无体内外部名依赖”；若同时 required 为空则整条 BLINDSPOT：缺证据（缺输入锚点）。"
+  },
+  {
+   "name": "guards_clause",
+   "from": "guards",
+   "rule": "guards 非空时逐个填“守卫条件 cond 成立”并保留 cond 源码；为空时填“无显式守卫”；若 cond 中标识符不在 required、optional、externals 中且无赋值证据，整条 BLINDSPOT：缺证据（缺该标识符定义）。"
+  },
+  {
+   "name": "returns_clause",
+   "from": "returns",
+   "rule": "returns 非空时填“返回表达式限定为 r1、r2、r3”并保留前 3 个原文；为空时填“返回未提供”并整条 BLINDSPOT：缺证据（缺返回表达式）。"
+  },
+  {
+   "name": "doc_clause",
+   "from": "doc_head",
+   "rule": "doc_head 非空时填“文档首行：doc_head”；为空时填“未提供文档首行契约”；doc_head 仅作功能说明，不得替代 required、externals、guards 的输入状态约束。"
+  }
+ ],
+ "rules": [
+  "组句顺序固定为 symbol→required_clause→optional_clause→externals_clause→guards_clause→returns_clause→doc_clause，用中文分号连接，整条为单句。",
+  "锚点规则：condition 必须至少包含一个 required 名或一个 externals 名；两者都无时输出 BLINDSPOT：缺证据（缺必需形参与外部名锚点）。",
+  "guards 规则：guards 非空时必须把每个 guard.cond 原样作为状态约束写入；不得改写逻辑；cond 中未解析标识符按 slots 规则触发 BLINDSPOT。",
+  "optional 规则：只写默认值与可省略性；若 guard 中用 optional 名，只按 guard 源码写该名出现，不补充类型或范围。",
+  "returns 规则：只引用 returns 前 3 个表达式原文；不得补全省略号后的结构；returns 为空触发 BLINDSPOT：缺证据（缺返回表达式）。",
+  "doc_head 规则：仅作为功能语义补充；若与 guards 或 returns 冲突，触发 BLINDSPOT：缺证据（契约冲突）。",
+  "禁用规则：输出不得包含门禁枚举的禁用短语；若生成候选含此类短语，删除或 BLINDSPOT。",
+  "BLINDSPOT 格式：证据不足时输出“BLINDSPOT：缺证据（缺什么）”，不得猜；括号内必须指向 required、optional、externals、guards、returns、doc_head 中的具体空项或未解析名。",
+  "机械复核规则：condition 中每个类型、范围、结构断言必须能映射到 optional.default、guards.cond、returns 或 doc_head 原文；映射不到则 BLINDSPOT。",
+  "局部名规则：guards.cond 中标识符若不在 required、optional、externals 中，且 facts 未记录其定义，触发 BLINDSPOT：缺证据（缺局部变量定义）。"
+ ],
+ "checklist": [
+  "condition 非空；若不以“BLINDSPOT：”开头，则必须包含 required 中至少一个名称或 externals 中至少一个名称。",
+  "condition 不得包含禁用短语集合 D 中任一项（D 由门禁枚举）。",
+  "若 condition 不以“BLINDSPOT：”开头且 required 非空，condition 必须出现 required 全部名称，且含“必须提供实参”或“必须提供形参”。",
+  "若 condition 不以“BLINDSPOT：”开头且 optional 非空，condition 必须出现每个 optional.name 及对应 default 原文，或出现“可省略”。",
+  "若 condition 不以“BLINDSPOT：”开头，condition 中裸标识符集合必须来自 required∪optional∪externals∪guards.cond∪returns 原文∪doc_head 原文，且至少一个来自 required∪externals。",
+  "若 condition 不以“BLINDSPOT：”开头且 guards 非空，condition 必须包含每个 guards[i].cond 原文，或包含“守卫条件”+cond+“成立/为真/为假”的原文组合。",
+  "若 condition 不以“BLINDSPOT：”开头且 returns 非空，condition 必须包含 returns 中至少一个表达式的前 20 个字符片段。",
+  "若 required 与 externals 均为空，condition 必须以“BLINDSPOT：缺证据”开头。",
+  "若 guards.cond 中存在标识符不属于 required∪optional∪externals，condition 必须以“BLINDSPOT：缺证据”开头，且括号内出现该标识符。",
+  "condition 必须为单句，以“调用 {name} 时”或“{name} 在”开头；若为 BLINDSPOT，则必须以“BLINDSPOT：缺证据（”开头。",
+  "若 condition 不以“BLINDSPOT：”开头且 doc_head 非空，condition 必须包含 doc_head 原文或 doc_head 首 10 个字符片段；若 doc_head 为空且 returns 为空，必须以“BLINDSPOT：”开头。",
+  "condition 不得把 lineno、end、decorators 的值作为条件文本。"
+ ],
+ "examples": [
+  {
+   "symbol": "_first_def",
+   "facts_used": "name,required,optional,externals,guards,returns,doc_head",
+   "condition": "调用 _first_def 时，必须提供实参 tree；无显式可选实参；体内引用的外部名 ast、isinstance 需在作用域中可解析；无显式守卫；在这些输入/状态下，返回表达式限定为 None、node、sub，功能说明为文档首行：取片段里第一个函数定义（含 async）；只有类时退其 __init__，再退类本身。"
+  },
+  {
+   "symbol": "is_candidate",
+   "facts_used": "name,required,optional,externals,guards,returns,doc_head",
+   "condition": "调用 is_candidate 时，必须提供实参 cg、nid；无显式可选实参；体内引用的外部名 bool、PREFIX、nodefile、str 需在作用域中可解析；守卫条件 not str(nid).startswith(PREFIX) 为假（即 str(nid).startswith(PREFIX) 为真）；在这些输入/状态下，返回表达式限定为 '生效条件' not in comp['required_present']、False，功能说明为文档首行：候选判据：代码节点且正文缺『生效条件』（机械判据，唯一）。"
+  },
+  {
+   "symbol": "plan",
+   "facts_used": "name,required,optional,externals,guards,returns,doc_head",
+   "condition": "调用 plan 时，必须提供实参 x；可选参数 ids、n、seed 默认均为 None，可省略；体内引用的外部名 dict、SAMPLE_SEED、SAMPLE_N、candidates、PREFIX、SPEC、refine、int、sorted、_item、len、round 需在作用域中可解析；守卫条件 ids 成立时进入该分支；在这些输入/状态下，返回表达式以 {'root': cg.root, 'dry_run': True, 'readonly': True, 'action': 'comment_gate', ...} 开头，功能说明为文档首行：抽检工单（只读）：确定性样本 + 源码落点 + 口径声明 + 样本充分性。"
+  },
+  {
+   "symbol": "judge",
+   "facts_used": "name,required,optional,externals,guards,returns,doc_head",
+   "condition": "BLINDSPOT：缺证据（guards 条件为 hits，但 hits 不在 required、optional、externals 中，facts 未提供局部变量定义或前置赋值证据，无法机械复核 hits 的输入或状态取值）。"
+  }
+ ],
+ "_provenance": {
+  "source": "LLM 单次调用（deepseek-flash）",
+  "job_id": "h1789643186033_ba80bc",
+  "prompt_chars": 2939,
+  "generated_for": "白箱条件填充器的槽位与校验清单",
+  "note": "模板由 LLM 产出；填充由 md_cg/cond_compose.py 确定性执行；校验由 md_cg/condition_anchor.py + 后续 LLM 复核"
+ },
+ "refinements": [
+  {
+   "version": "v0.2",
+   "source": "主体依据验证单元/校验者实测修正，待 LLM 复核",
+   "changes": [
+    "C5 原口径『不得补充 facts 未提供的细节』改为：**不得补充源码与 facts 都不支持的断言**——校验者与生成者必须拿到相同证据面（facts + 源码片段）",
+    "C6/C9 增加 `early` 条件：只有『首条语句且含 return/raise』的守卫才是前置条件；函数内部分支不写",
+    "校验输出必须给出禁用短语集合 D（已随提示词提供），否则 C2 不可核验"
+   ],
+   "evidence": "iter-010 两轮 REJECT（模板拼句无功能语义）；iter-011 校验 v2：仅给 facts 时 11 条 C5 误报，其『改写』比原句更含糊"
+  }
+ ]
+}

package/md_cg/condition_anchor.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""条件锚点：判定一条候选「生效条件」是否锚定在该符号的真实输入/状态上（确定性，零 LLM）。
+
+# 功能名：条件锚点机械判据
+# 生效条件：给定候选生效条件文本 + 该符号源码片段（含 def/class 定义）时；用于环二候选的机械门禁与抽检
+# 子功能：ast 取签名（必需/可选参数）+ 函数体内引用的名字 → 与条件文本标识符求交 → 输出 ANCHORED/WEAK/BLINDSPOT/REJECT_META 四类裁决与锚点清单
+# 执行：from md_cg import condition_anchor；condition_anchor.judge(cond, src) -> dict
+# 验证方式：md_cg/test_condition_anchor.py（逐分支断言）
+# 不适用条件：①只判「锚点是否存在」，**不判语义正确性**（不得据此声称条件正确）②非 Python 源码或无法解析时返回 BLINDSPOT ③无参数且体内无外部引用的符号返回 BLINDSPOT（不可判，不猜测）
+"""
+from __future__ import annotations
+
+import ast
+import re
+
+# 索引元条件话术（合成条件特征）：出现即拒——它们不是功能前置条件
+META_MARKS = ("索引元条件", "源文件存在", "全时窗", "本地仓", "仓库存在", "文件存在")
+IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+# 生效条件：tree 为可被 ast.walk 遍历的 AST 时，返回其中首个 FunctionDef/AsyncFunctionDef 节点，无函数而含 ClassDef 时返回该类体的 __init__ 或类自身，否则返回 None。
+def _first_def(tree):
+    """取片段里第一个函数定义（含 async）；只有类时退其 __init__，再退类本身。"""
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            return node
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for sub in node.body:
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)) and sub.name == "__init__":
+                    return sub
+            return node
+    return None
+
+
+# 生效条件：fn 为含 args 的函数定义节点时按 defaults 长度切分，返回 (无默认值且排除 self/cls 的形参名, 有默认值的形参名)；fn 为 ClassDef 时返回 ([], [])。
+def signature(fn):
+    """返回 (required, optional)：required=无默认值的形参（跳过 self/cls），optional=有默认值者。"""
+    if isinstance(fn, ast.ClassDef):
+        return [], []
+    args = list(getattr(fn.args, "posonlyargs", [])) + list(fn.args.args)
+    defaults = list(fn.args.defaults)
+    n_opt = len(defaults)
+    head = args[:len(args) - n_opt] if n_opt else args
+    tail = args[len(args) - n_opt:] if n_opt else []
+    required = [a.arg for a in head if a.arg not in ("self", "cls")]
+    optional = [a.arg for a in tail]
+    for a, d in zip(fn.args.kwonlyargs, fn.args.kw_defaults):
+        (optional if d is not None else required).append(a.arg)
+    return required, optional
+
+
+# 生效条件：fn 为函数定义节点时，返回其体内 Load 名字集合剔除 fn 的形参名、Store/Del 本地名及嵌套函数/异步函数定义名后的差集。
+def referenced(fn):
+    """函数体内引用的名字（剔除形参与本地赋值目标）——代表来自模块/外部的状态与常量。"""
+    if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return set()  # 类（无 __init__）等非函数节点：无「体内引用」语义，返回空集不崩溃
+    params = {a.arg for a in list(getattr(fn.args, "posonlyargs", [])) + list(fn.args.args)}
+    params |= {a.arg for a in fn.args.kwonlyargs}
+    if getattr(fn.args, "vararg", None):
+        params.add(fn.args.vararg.arg)
+    if getattr(fn.args, "kwarg", None):
+        params.add(fn.args.kwarg.arg)
+    local = set()
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+            local.add(node.id)
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node is not fn:
+            local.add(node.name)
+    names = set()
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Name):
+            names.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            base = node
+            while isinstance(base, ast.Attribute):
+                base = base.value
+            if isinstance(base, ast.Name):
+                names.add(base.id)
+    return names - params - local
+
+
+# 生效条件：cond 与 src 给定后：若 str(cond) 含 META_MARKS 则返回 REJECT_META；否则解析 src，取 _first_def、signature、referenced，并按 cond 中标识符是否命中 required 或 referenced 得出 ANCHORED（ok=True）、无 required/refs 时 BLINDSPOT、否则 WEAK；prefix/suffix 仅回显不参与判定。
+def judge(cond, src, prefix="", suffix=""):
+    """判定单条候选条件。返回 dict：verdict/ok/anchors/required/optional/referenced/meta_marks。
+
+    prefix/suffix：编外记录用（如「已声明」），不参与判定，仅回显以便追溯。
+    """
+    out = {"cond": str(cond or ""), "verdict": "", "ok": False, "anchors": [],
+           "required": [], "optional": [], "referenced": [], "meta_marks": [],
+           "prefix": prefix, "suffix": suffix, "reason": ""}
+    text = str(cond or "")
+    hits = [m for m in META_MARKS if m in text]
+    if hits:
+        out.update(verdict="REJECT_META", ok=False, meta_marks=hits,
+                   reason="出现索引元条件话术，非功能前置条件")
+        return out
+    try:
+        tree = ast.parse(str(src or ""))
+    except SyntaxError as exc:
+        out.update(verdict="BLINDSPOT", reason="源码无法解析：" + str(exc)[:60])
+        return out
+    fn = _first_def(tree)
+    if fn is None:
+        out.update(verdict="BLINDSPOT", reason="片段中无函数/类定义")
+        return out
+    if isinstance(fn, ast.ClassDef):
+        _init = None
+        for _sub in fn.body:
+            if isinstance(_sub, (ast.FunctionDef, ast.AsyncFunctionDef)) and _sub.name == "__init__":
+                _init = _sub
+                break
+        fn = _init if _init is not None else fn
+    required, optional = signature(fn)
+    refs = referenced(fn)
+    mentions = set(IDENT.findall(text))
+    strong = sorted(mentions & set(required))
+    weak = sorted(mentions & refs)
+    anchors = sorted(set(strong) | set(weak))
+    out.update(required=required, optional=optional, referenced=sorted(refs), anchors=anchors)
+    if strong or weak:
+        out.update(verdict="ANCHORED", ok=True,
+                   reason="锚定必需参数" if strong else "锚定体内引用（状态/常量）")
+        return out
+    if not required and not refs:
+        out.update(verdict="BLINDSPOT", reason="该符号无参数且无外部引用，条件无从锚定")
+        return out
+    out.update(verdict="WEAK", reason="条件未锚定任何必需参数或体内引用")
+    return out
+
+
+# 生效条件：pairs 为可逐项解包出 (id, cond, src) 的序列时，对每条调用 judge 并回填 id，返回 {'rows': rows, 'stats': 各 verdict 计数, 'ok': rows 中 ok 为真者个数}。
+def judge_batch(pairs):
+    """批量入口：pairs=[(id, cond, src), ...] → 汇总统计（供环二流水线调用）。"""
+    rows = []
+    for pid, cond, src in pairs:
+        r = judge(cond, src)
+        r["id"] = pid
+        rows.append(r)
+    stat = {}
+    for r in rows:
+        stat[r["verdict"]] = stat.get(r["verdict"], 0) + 1
+    return {"rows": rows, "stats": stat, "ok": sum(1 for r in rows if r["ok"])}