@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/validation/test/__init__.py

@@ -0,0 +1,11 @@
+# 子包初始化: 注入 scripts/根 + 所有子包到 sys.path
+# 让跨包 import (旧式不带前缀) 仍可用, 兼容现有代码
+import os as _os, sys as _sys
+_root = _os.path.dirname(_os.path.dirname(_os.path.abspath(__file__)))
+if _root not in _sys.path:
+    _sys.path.insert(0, _root)
+# 注入所有子包目录 (兼容旧式 import xxx)
+for _sub in ('kg', 'build', 'test', 'setup', 'io'):
+    _subdir = _os.path.join(_root, _sub)
+    if _os.path.isdir(_subdir) and _subdir not in _sys.path:
+        _sys.path.insert(0, _subdir)

package/templates/qoder/scripts/validation/test/assertion_gen.py

@@ -0,0 +1,551 @@
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""
+assertion_gen.py — 断言生成器: PRD 验收标准 / GWT 文本 → 可执行 expect 断言
+
+== 为什么有它 (上一轮图谱边界分析的落地) ==
+工作流测试断言层现状:
+  - 操作层已闭环 (图谱定位 + autotest_webaccess.py 执行 anchor 点击/填值)
+  - 断言层断了: _check_expect 能执行 {fetch/dom, jsonpath, equals},
+    但那个 equals 期望值"从哪来"没人管 —— quick 模式靠 LLM 瞎编, 不可信。
+  - 根因: PRD 验收标准是空注释/自由文本, context_pack.py 只取 title+keywords
+    根本不读验收正文 (wl-test/SKILL.md L177 声称能拿到是空头承诺)。
+
+本模块把"PRD 验收标准 → expect 断言"这条断链接上。分工 (呼应三条红线):
+  - 人补语义:    PRD 里写结构化验收 (GWT 或 "条件-操作-预期" 带接口名/状态码)
+  - 图谱补字段:  page_probe 查按钮→接口, field_map 查中文标题→字段名
+  - 真跑定对错:  本模块只产断言 JSON, 跑不跑交给 quick/webaccess
+
+== 两条铁律 ==
+  红线1 (不假装懂业务): PRD 抽不到结构化断言 → 输出"无可抽取", 绝不编造。
+  红线2 (语义不背书):   字段补全命中标 [图谱], 查不到留 {{ask:}} 占位标 [需确认]。
+  (红线3: 本模块不执行, 不import playwright/selenium, 不调 LLM)
+
+== 断言输出格式 (严格对齐 autotest_webaccess.py:314 _check_expect 契约) ==
+  fetch 断言: {intent:"assert", desc, source,
+               expect:{fetch:"/api/x", jsonpath:"code", equals:200, method:"POST", body:{}}}
+  dom 断言:   {intent:"assert", desc, source,
+               expect:{dom:"css", jsonpath:"text", equals:"审批中"}}
+
+Usage (作为库, 被 autotest.py assertion-gen 子命令调用):
+    assertions, report = generate(task='06-24-xxx', gwt=None, page_keyword='保险')
+    assertions, report = generate(task=None, gwt='Given ... When ... Then 接口/api/x code=200')
+
+Usage (CLI):
+    python assertion_gen.py --task <任务名> [--page 保险]
+    python assertion_gen.py --gwt "<GWT文本>" [--page 保险]
+"""
+
+import json
+import os
+import re
+import sys
+from typing import Optional, List, Dict, Any, Tuple
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+
+from foundation.core.paths import get_repo_root, TASKS_DIR, index_path  # noqa: E402
+from foundation.data.task_utils import resolve_task_dir  # noqa: E402
+
+
+# ============================================================
+# 1. 输入: 从 PRD 抽 "验收标准" 章节 (或吃 --gwt 兜底文本)
+# ============================================================
+
+# 验收标准章节的常见标题 (中英, 容错)
+_ACCEPTANCE_HEADINGS = (
+    '验收标准', '验收点', '验收', 'acceptance criteria', 'acceptance',
+)
+
+
+def extract_acceptance_from_prd(prd_path: str) -> Tuple[str, bool]:
+    """从 PRD markdown 抽 "## 验收标准" 章节正文。
+
+    返回 (text, found_section):
+      text          — 章节正文 (去掉标题行, 保留 checkbox/正文)
+      found_section — True=定位到了该章节; False=PRD 里压根没这个章节
+    读不到文件 → (空, False)。
+    """
+    if not os.path.isfile(prd_path):
+        return '', False
+    try:
+        with open(prd_path, encoding='utf-8') as f:
+            lines = f.readlines()
+    except (OSError, UnicodeDecodeError):
+        try:
+            with open(prd_path, encoding='gbk') as f:
+                lines = f.readlines()
+        except (OSError, UnicodeDecodeError):
+            return '', False
+
+    # 找验收章节起始 (## 验收标准 / ## Acceptance ...)
+    start = None
+    for i, ln in enumerate(lines):
+        low = ln.strip().lower().lstrip('#').strip()
+        if low and any(low == h or low.startswith(h) for h in _ACCEPTANCE_HEADINGS):
+            start = i
+            break
+    if start is None:
+        return '', False
+
+    # 截到下一个同级或更高级标题 (## / #) 为止
+    body = []
+    for ln in lines[start + 1:]:
+        stripped = ln.lstrip()
+        if stripped.startswith('#'):  # 下一个章节
+            break
+        body.append(ln)
+    return ''.join(body), True
+
+
+def _meaningful_acceptance(text: str) -> bool:
+    """验收正文里有没有"可翻译的内容" (排除纯注释/空)。
+
+    纯 HTML 注释 <!-- ... --> 或全是空白 → False。
+    """
+    # 去掉 HTML 注释
+    no_comments = re.sub(r'<!--.*?-->', '', text, flags=re.DOTALL)
+    # 去掉 markdown checkbox 符号本身不算内容 (- [ ] 这种, 后面得有字)
+    # 找有没有实际的中文/字母描述 (长度>3 的连续非空白段)
+    tokens = [t for t in re.split(r'[\s\-\[\]（）()【】xX✔✓☐·,，。]', no_comments) if len(t) > 2]
+    return len(tokens) > 0
+
+
+# ============================================================
+# 2. 核心抽取: 验收条目 → 候选断言点 (目标类型, 字段路径, 期望值, 原句)
+# ============================================================
+
+# 把验收正文切成"条目" (每行/每 Then/每 checkbox 算一条)
+def _split_items(text: str) -> List[str]:
+    """把验收正文拆成条目列表。每行一条; GWT 的 Then/And 各算一条。"""
+    items = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        # 去掉 markdown checkbox / 列表前缀
+        line = re.sub(r'^[-*]\s*\[[ xX]\]\s*', '', line)
+        line = re.sub(r'^[-*]\s+', '', line)
+        # GWT: 一个 Then/And 行可能含多个断言 (用 "且/并且/和/," 连), 拆开各处理
+        # 但保留 Given/When 前缀信息 (后面 _classify 用)
+        if not line:
+            continue
+        items.append(line)
+    return items
+
+
+# 接口断言线索: "接口 /api/xxx" / "返回 code=200" / "调用 xxx 接口"
+_RE_API_PATH = re.compile(r'/api/[A-Za-z0-9_/\-]+')
+_RE_CODE_EQ = re.compile(r'(?:code|状态码|返回码)\s*[=＝:]\s*(\d+)', re.IGNORECASE)
+_RE_MSG_EQ = re.compile(r'(?:msg|message|消息|提示)["\']?\s*[=＝:]\s*["\']([^"\']+)["\']', re.IGNORECASE)
+# 数字期望 (单独的 =200, 但要避免和 code= 重复)
+_RE_BARE_NUM = re.compile(r'(?<![A-Za-z])[=＝:]\s*(\d{3})\b')
+# 字段显示断言: "XX列显示YYY" / "显示为YYY" / "XXX变成YYY" / "状态为YYY"
+_RE_FIELD_SHOW = re.compile(
+    r'([\u4e00-\u9fa5A-Za-z]{2,8}?)\s*(?:列|字段|状态|文本|内容|值)?\s*'
+    r'(?:显示|显示为|变成|变为|更改为|更新为|为|是)\s*[:：]?\s*["\']?([\u4e00-\u9fa5A-Za-z0-9_\-]{1,20})["\']?'
+)
+
+
+def _classify_item(item: str) -> List[Dict[str, Any]]:
+    """把一条验收文本分类成 0..N 个候选断言点。
+
+    返回 [{kind, field, equals, raw}, ...]
+      kind: 'fetch' | 'dom'
+      field: fetch 时=jsonpath(code/msg/data); dom 时=待查的中文标题(如"处理状态")
+      equals: 期望值
+      raw: 原句 (供 desc/source 用)
+    没有任何可识别断言线索 → 返回 [] (调用方决定是否降级提示)
+    """
+    raw = item
+    # 去掉 GWT 前缀 (Given/When 是前置条件, Then/And 才是断言; 但保守起见都扫)
+    body = re.sub(r'^(Given|When|Then|And|并且|且|那么|则)\s*:?\s*', '', item, flags=re.IGNORECASE).strip()
+    if not body:
+        return []
+    points = []
+    # ── 接口断言 ──
+    api_hits = _RE_API_PATH.findall(body)
+    code_hit = _RE_CODE_EQ.search(body)
+    msg_hit = _RE_MSG_EQ.search(body)
+    if api_hits:
+        endpoint = api_hits[0]
+        if code_hit:
+            points.append({'kind': 'fetch', 'field': 'code',
+                           'equals': int(code_hit.group(1)), 'raw': raw})
+        if msg_hit:
+            points.append({'kind': 'fetch', 'field': 'msg',
+                           'equals': msg_hit.group(1), 'raw': raw})
+        # 有接口但没显式 code/msg → 默认断 code==200 (最常见成功码), 标 source=规则推断
+        if not code_hit and not msg_hit:
+            points.append({'kind': 'fetch', 'field': 'code',
+                           'equals': 200, 'raw': raw, 'inferred': True})
+    elif code_hit:
+        # 没接口路径但有 "返回 code=200" → 留接口占位
+        points.append({'kind': 'fetch', 'field': 'code',
+                       'equals': int(code_hit.group(1)), 'raw': raw,
+                       'endpoint_missing': True})
+    # ── 字段显示断言 (dom) ──
+    # 注意去重: 一条里 "状态列显示审批中" 匹配一次
+    for m in _RE_FIELD_SHOW.finditer(body):
+        title = m.group(1).strip()
+        value = m.group(2).strip()
+        # 过滤无意义匹配 (如 "在...下" 的 "下")
+        if title in ('在', '条件', '操作', '预期', '结果', '描述', '下'):
+            continue
+        if value in ('描述', '结果'):
+            continue
+        points.append({'kind': 'dom', 'field': title, 'equals': value, 'raw': raw})
+    return points
+
+
+# ============================================================
+# 3. 字段补全: 候选断言点 → 可执行断言 (调 page_probe + field_map)
+# ============================================================
+
+def _load_field_map() -> Dict[str, Dict[str, Any]]:
+    """加载 ui-style.json 的 field_map: {字段名: {titles:[中文标题], count}}。
+    反查用: 中文标题 → 字段名。失败返回 {}。"""
+    try:
+        p = index_path('ui_style')
+        if not p.is_file():
+            return {}
+        with open(p, encoding='utf-8') as f:
+            data = json.load(f)
+        return data.get('field_map', {}) or {}
+    except (OSError, ValueError, KeyError):
+        return {}
+
+
+def _build_title_to_field(field_map: Dict[str, Dict[str, Any]]) -> Dict[str, str]:
+    """中文标题 → 字段名 (取 count 最高的, 即最常用)。
+    titles 可能是 ["处理状态","状态"] 多个, 都建索引。"""
+    title_to_field = {}
+    # 先聚合每个 title 对应的所有 (字段, count)
+    candidates = {}  # title -> [(field, count)]
+    for field, info in field_map.items():
+        titles = info.get('titles', []) if isinstance(info, dict) else []
+        cnt = info.get('count', 0) if isinstance(info, dict) else 0
+        for t in titles:
+            candidates.setdefault(t, []).append((field, cnt))
+    for title, pairs in candidates.items():
+        pairs.sort(key=lambda x: -x[1])  # count 高的优先
+        title_to_field[title] = pairs[0][0]
+    return title_to_field
+
+
+def _query_page_endpoints(page_keyword: Optional[str]) -> Dict[str, str]:
+    """调 page_probe 拿"按钮名→接口路径"映射。失败/无关键字返回 {}。
+
+    用图谱把"延期提交"这种按钮名对上 /api/insurance/delay。
+    """
+    if not page_keyword:
+        return {}
+    try:
+        import page_probe  # noqa: E402
+    except ImportError:
+        sys.path.insert(0, _THIS_DIR)
+        try:
+            import page_probe  # type: ignore  # noqa: E402
+        except ImportError:
+            return {}
+    try:
+        profile = page_probe.build_page_profile(keyword=page_keyword)
+    except Exception:
+        return {}
+    if not profile.get('ok'):
+        return {}
+    btn_to_ep = {}
+    for pg in profile.get('pages', []):
+        for b in pg.get('buttons', []):
+            ep = b.get('endpoint')
+            if ep and ep != 'None':
+                btn_to_ep[b.get('button', '')] = ep
+    return btn_to_ep
+
+
+def _resolve_endpoint(point: Dict[str, Any], btn_to_ep: Dict[str, str]) -> Tuple[Optional[str], str]:
+    """给 fetch 断言补 endpoint。返回 (endpoint, source_note)。
+
+    优先级: 句子里已含 /api/xxx > 图谱按钮匹配 > 留占位。
+    """
+    raw = point.get('raw', '')
+    # 1. 句子里已有接口路径
+    m = _RE_API_PATH.search(raw)
+    if m:
+        return m.group(0), '规则·句中含接口'
+    # 2. 图谱按钮匹配 (句子里有没有按钮名)
+    for btn, ep in btn_to_ep.items():
+        if btn and btn in raw:
+            return ep, '图谱·按钮画像'
+    # 3. endpoint_missing 或匹配不上 → 占位
+    if point.get('endpoint_missing'):
+        return None, '需确认·接口未指明'
+    return None, '需确认·接口未指明'
+
+
+def _resolve_dom_selector(point: Dict[str, Any],
+                          title_to_field: Dict[str, str]) -> Tuple[str, str]:
+    """给 dom 断言补 css 选择器。返回 (dom_css, source_note)。
+
+    中文标题查 field_map → 字段名 → 构造 .vxe-cell 系选择器。
+    查不到 → {{ask:}} 占位 (执行时问用户)。
+    """
+    title = point.get('field', '')
+    value = point.get('equals', '')
+    if title in title_to_field:
+        field = title_to_field[title]
+        # VxeGrid 表格单元格常见 class (项目统一用 vxe), 给一个合理猜测选择器
+        # 真实执行时 autotest_webaccess eval 会读 innerText, 这里给最可能的
+        css = ".vxe-body--row .vxe-cell[title*='%s'], .vxe-cell--column[data-field='%s']" % (value, field)
+        return css, '图谱·字段表命中(%s)' % field
+    # 查不到 → 占位, 让用户补 CSS
+    css = "{{ask:%s列CSS选择器}}" % title
+    return css, '需确认·字段未命中'
+
+
+def _build_assertion(point: Dict[str, Any],
+                     btn_to_ep: Dict[str, str],
+                     title_to_field: Dict[str, str]) -> Optional[Dict[str, Any]]:
+    """把一个候选断言点组装成完整 assertion dict (对齐 _check_expect)。"""
+    kind = point.get('kind')
+    if kind == 'fetch':
+        endpoint, ep_note = _resolve_endpoint(point, btn_to_ep)
+        if endpoint is None:
+            endpoint = '{{ask:接口路径}}'
+        expect = {
+            'fetch': endpoint,
+            'jsonpath': point.get('field', 'code'),
+            'equals': point.get('equals', 200),
+            'method': 'POST',
+            'body': {},
+        }
+        inferred = '·推断' if point.get('inferred') else ''
+        # desc 聚焦断言点本身: jsonpath=期望值, 不取整行长句
+        desc = '%s=%s' % (point.get('field', 'code'), point.get('equals', 200))
+        return {'intent': 'assert', 'desc': desc, 'expect': expect,
+                'source': ep_note + inferred}
+    if kind == 'dom':
+        css, src_note = _resolve_dom_selector(point, title_to_field)
+        expect = {
+            'dom': css,
+            'jsonpath': 'text',
+            'equals': point.get('equals', ''),
+        }
+        # desc 聚焦: 字段标题=期望值
+        desc = '%s=%s' % (point.get('field', ''), point.get('equals', ''))
+        return {'intent': 'assert', 'desc': desc, 'expect': expect,
+                'source': src_note}
+    return None
+
+
+# ============================================================
+# 4. 编排: generate() — 对外主入口
+# ============================================================
+
+def generate(
+    task: Optional[str] = None,
+    gwt: Optional[str] = None,
+    page_keyword: Optional[str] = None,
+) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+    """生成断言。返回 (assertions, report)。
+
+    输入二选一: task=任务名(读其 PRD 验收章节) / gwt=GWT 文本。
+    page_keyword: 业务关键词(如"保险"), 触发图谱字段补全。
+
+    report 说明抽取过程 (供调用方/用户审计: 从哪抽的、抽了几条、为什么没抽到)。
+    """
+    report: Dict[str, Any] = {
+        'input_source': None,      # 'prd' | 'gwt'
+        'prd_found_section': None,  # PRD 是否有验收章节
+        'acceptance_meaningful': None,  # 验收正文是否有可翻译内容
+        'raw_items': 0,
+        'candidate_points': 0,
+        'reason_if_empty': '',      # 抽不到的原因 (诚实降级用)
+    }
+
+    # ── 1. 取验收文本 ──
+    text = ''
+    if gwt and gwt.strip():
+        text = gwt
+        report['input_source'] = 'gwt'
+    elif task:
+        task_dir = resolve_task_dir(task)
+        if not task_dir.is_dir():
+            report['reason_if_empty'] = '任务不存在: %s' % task
+            return [], report
+        prd_path = os.path.join(str(task_dir), 'prd.md')
+        body, found = extract_acceptance_from_prd(prd_path)
+        report['input_source'] = 'prd'
+        report['prd_found_section'] = found
+        if not found:
+            report['reason_if_empty'] = 'PRD 中未找到"验收标准/Acceptance"章节'
+            return [], report
+        text = body
+    else:
+        report['reason_if_empty'] = '未提供输入 (需要 --task 或 --gwt)'
+        return [], report
+
+    # ── 2. 文本是否有可翻译内容 ──
+    meaningful = _meaningful_acceptance(text)
+    report['acceptance_meaningful'] = meaningful
+    if not meaningful:
+        report['reason_if_empty'] = (
+            '验收标准章节无可抽取的结构化断言 (内容为空/仅注释/纯描述性)。'
+            '可能原因: 未按 Given-When-Then 或"条件-操作-预期"书写。'
+        )
+        return [], report
+
+    # ── 3. 拆条 + 分类成候选断言点 ──
+    items = _split_items(text)
+    report['raw_items'] = len(items)
+    candidates: List[Dict[str, Any]] = []
+    for it in items:
+        candidates.extend(_classify_item(it))
+    report['candidate_points'] = len(candidates)
+    if not candidates:
+        report['reason_if_empty'] = (
+            '验收条目无可识别的断言线索 (无接口名/状态码/字段显示断言)。'
+            '提示: 在验收里写明接口路径(如 /api/xxx)、期望 code、或"XX列显示YY"。'
+        )
+        return [], report
+
+    # ── 4. 字段补全 (图谱/字段表) ──
+    btn_to_ep = _query_page_endpoints(page_keyword)
+    field_map = _load_field_map()
+    title_to_field = _build_title_to_field(field_map)
+
+    assertions: List[Dict[str, Any]] = []
+    seen = set()  # 去重: (kind, field, equals)
+    for point in candidates:
+        key = (point.get('kind'), point.get('field'), str(point.get('equals')))
+        if key in seen:
+            continue
+        seen.add(key)
+        a = _build_assertion(point, btn_to_ep, title_to_field)
+        if a:
+            assertions.append(a)
+    return assertions, report
+
+
+# ============================================================
+# 5. 渲染: 人可读报告 + CLI
+# ============================================================
+
+def render_report(assertions: List[Dict[str, Any]], report: Dict[str, Any],
+                  task: Optional[str] = None) -> str:
+    """渲染人可读的抽取报告 (markdown)。"""
+    lines = []
+    lines.append('=' * 56)
+    lines.append('断言生成 · assertion-gen')
+    lines.append('=' * 56)
+    if task:
+        lines.append('任务: %s' % task)
+    src = report.get('input_source')
+    lines.append('输入来源: %s' % ({
+        'prd': 'PRD 验收标准章节', 'gwt': '--gwt 文本',
+    }.get(src, '未知')))
+
+    if not assertions:
+        reason = report.get('reason_if_empty', '无可抽取断言')
+        lines.append('')
+        lines.append('⚠ %s' % reason)
+        lines.append('')
+        lines.append('解决:')
+        lines.append('  ① 用 --gwt 临时补充结构化文本 (Given/When/Then + 接口名/状态码)')
+        lines.append('  ② 或在 PRD 验收标准里补结构化条目后重跑')
+        lines.append('  ③ 业务规则断言本就需要人写语义, 图谱/工具只补字段不编断言')
+        lines.append('=' * 56)
+        return '\n'.join(lines)
+
+    lines.append('候选条目: %d · 生成断言: %d' % (
+        report.get('candidate_points', 0), len(assertions)))
+    lines.append('-' * 56)
+    for i, a in enumerate(assertions, 1):
+        ex = a.get('expect', {})
+        if 'fetch' in ex:
+            lines.append('%d. [接口] %s' % (i, a.get('desc', '')))
+            lines.append('   fetch=%s  %s=%s  (method=%s)'
+                         % (ex.get('fetch'), ex.get('jsonpath'), ex.get('equals'),
+                            ex.get('method')))
+        else:
+            lines.append('%d. [字段] %s' % (i, a.get('desc', '')))
+            lines.append('   dom=%s  equals=%s' % (ex.get('dom'), ex.get('equals')))
+        lines.append('   来源: %s' % a.get('source', '?'))
+    lines.append('-' * 56)
+    # 置信度统计
+    confident = sum(1 for a in assertions if '需确认' not in a.get('source', ''))
+    lines.append('可信断言: %d/%d (%s)'
+                 % (confident, len(assertions),
+                    '可信' if confident == len(assertions) else '含待确认项'))
+    if confident < len(assertions):
+        lines.append('  ⚠ 标"需确认"的项字段未命中, 执行前需补 {{ask:}} 占位')
+    lines.append('=' * 56)
+    return '\n'.join(lines)
+
+
+def main(argv=None):
+    import argparse
+    p = argparse.ArgumentParser(
+        prog='assertion_gen.py',
+        description='断言生成: PRD验收/GWT文本 → 可执行 expect 断言 (不编造, 不执行)',
+    )
+    g = p.add_mutually_exclusive_group(required=False)
+    g.add_argument('--task', help='任务名 (读其 prd.md 的验收标准章节)')
+    g.add_argument('--gwt', help='GWT/验收文本 (兜底输入, 不读PRD)')
+    p.add_argument('--page', default=None, help='业务关键词(如 保险), 触发图谱字段补全')
+    p.add_argument('--out', default=None, help='断言 JSON 输出路径 (默认打印, 不落地)')
+    args = p.parse_args(argv)
+
+    if not args.task and not args.gwt:
+        p.error('需要 --task 或 --gwt 之一作为输入')
+
+    assertions, report = generate(
+        task=args.task, gwt=args.gwt, page_keyword=args.page)
+
+    print(render_report(assertions, report, task=args.task))
+
+    if assertions:
+        out_path = args.out
+        if not out_path and args.task:
+            task_dir = resolve_task_dir(args.task)
+            if task_dir.is_dir():
+                out_path = os.path.join(str(task_dir), 'assertions.json')
+        if out_path:
+            payload = {
+                '_contract': {'type': 'assertions', 'version': 1,
+                              'source': args.task or 'gwt'},
+                'assertions': assertions,
+            }
+            with open(out_path, 'w', encoding='utf-8') as f:
+                json.dump(payload, f, ensure_ascii=False, indent=2)
+            print('断言已写入: %s' % out_path)
+            print('喂给执行器: 把 assertions 数组并进 quick 用例的 steps (intent=assert)')
+        else:
+            print()
+            print('--- assertions.json ---')
+            print(json.dumps(assertions, ensure_ascii=False, indent=2))
+        return 0
+    # 抽不到 = 诚实退出, 非零码让调用方知道
+    return 2
+
+
+if __name__ == '__main__':
+    sys.exit(main())