@furongjun1999/dsh-memory 0.4.8 → 0.4.10

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"])}