@buaa_smat/hometrans 0.1.0 → 0.1.2

package/agents/test-tools/autotest/report_tool.py

@@ -0,0 +1,759 @@
+#!/usr/bin/env python3
+"""Generate or validate the self-test-report.md.
+
+Subcommands:
+    generate --task-subdir ... --app-metadata ... --hap ... --device ... \\
+             --suite ... --out ... [--validate]
+        Render `self-test-report.md` from a task_<ts>/ directory using a strict
+        markdown template; optionally re-validate the output in-process.
+
+    validate <report-path>
+        Check that an existing `self-test-report.md` conforms to the required
+        layout (sections, per-case fields, contiguous Pre/Case indices, etc.).
+        Exit 0 = PASSED, exit 1 = FAILED.
+
+Strategy:
+  - Read summary.json + task_results.jsonl from <task-subdir>.
+  - For each case: open <report_dir>/<date>/<HHMMSS>/<HHMMSS>.json and extract the
+    `<judgment>` block from the final `task_end` event. PASS / FAIL cases always
+    have this block (it is written by the AutoTest planner agent itself).
+  - For UNKNOWN cases (no judgment block — planner exhausted its step budget),
+    fall back to JSONL `reason` plus the last `planner_thinking` event content.
+  - Pre-cases (`case_name` starts with `[PRE] `) render in `## 前置用例` with
+    `### Pre N: <name without prefix>`; regular cases render in `## 用例详情`
+    with `### Case N: <name>`.
+"""
+
+import argparse
+import io
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+PRE_PREFIX = "[PRE] "
+
+
+# =============================================================================
+# Parsers
+# =============================================================================
+
+def parse_judgment_block(content: str) -> dict:
+    """Parse <judgment>...</judgment> from a task_end event.
+
+    Returns a dict with whatever headers were found (e.g., 预期验证, 历史回顾,
+    状态确认, Bug发现, 判定结果). Returns empty dict if no judgment block.
+    """
+    m = re.search(r"<judgment>(.*?)</judgment>", content, re.DOTALL)
+    if not m:
+        return {}
+
+    body = m.group(1).strip()
+    # Header form: **<chinese-word>**[：:] then content until next **header** or end.
+    parts = re.split(r"\*\*([\u4e00-\u9fffA-Za-z]+)\*\*\s*[：:]\s*", body)
+    # parts[0] is preamble before first header; parts[1::2] = headers; parts[2::2] = bodies
+    sections: dict[str, str] = {}
+    for i in range(1, len(parts), 2):
+        header = parts[i].strip()
+        text = parts[i + 1].strip() if i + 1 < len(parts) else ""
+        sections[header] = text
+    return sections
+
+
+def parse_test_steps(test_steps: str) -> tuple[list[str], str]:
+    """Parse `动作：... -> ...\\n预期结果：...` into (action_list, expected_text)."""
+    actions_match = re.search(r"动作[：:]\s*(.+?)(?=\n\s*预期结果[：:]|\Z)", test_steps, re.DOTALL)
+    expected_match = re.search(r"预期结果[：:]\s*(.+)", test_steps, re.DOTALL)
+
+    if actions_match:
+        actions_raw = actions_match.group(1).strip()
+        action_list = [s.strip() for s in re.split(r"\s*->\s*|\s*→\s*", actions_raw) if s.strip()]
+    else:
+        action_list = [test_steps.strip()] if test_steps.strip() else []
+
+    expected = expected_match.group(1).strip() if expected_match else ""
+    return action_list, expected
+
+
+def find_latest_task_json(report_dir: Path) -> Path | None:
+    """Locate <report_dir>/<YYYY-MM-DD>/<HH-MM-SS>/<HH-MM-SS>.json (the structured run log)."""
+    if not report_dir.exists():
+        return None
+
+    date_pat = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+    time_pat = re.compile(r"^\d{2}-\d{2}-\d{2}$")
+
+    date_dirs = sorted(d for d in report_dir.iterdir() if d.is_dir() and date_pat.match(d.name))
+    if not date_dirs:
+        return None
+
+    for date_dir in reversed(date_dirs):
+        time_dirs = sorted(d for d in date_dir.iterdir() if d.is_dir() and time_pat.match(d.name))
+        if not time_dirs:
+            continue
+        for time_dir in reversed(time_dirs):
+            candidate = time_dir / f"{time_dir.name}.json"
+            if candidate.exists():
+                return candidate
+    return None
+
+
+def extract_last_thinking(events: list[dict]) -> str:
+    """Return content of last planner_thinking event."""
+    for ev in reversed(events):
+        if ev.get("event_type") == "planner_thinking":
+            return ev.get("content", "").strip()
+    return ""
+
+
+def load_case_judgment(report_dir: str) -> tuple[dict, str]:
+    """Load the judgment block + last thinking for one case.
+
+    Returns (judgment_dict, last_thinking_text). Either may be empty.
+    """
+    path = find_latest_task_json(Path(report_dir))
+    if path is None:
+        return {}, ""
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}, ""
+
+    events = data.get("events", []) or []
+    if not events:
+        return {}, ""
+
+    # task_end is the last event for completed cases; for UNKNOWN the agent may
+    # not have emitted task_end at all but the last planner_thinking is still useful.
+    task_end_content = ""
+    for ev in reversed(events):
+        if ev.get("event_type") == "task_end":
+            task_end_content = ev.get("content", "")
+            break
+
+    judgment = parse_judgment_block(task_end_content) if task_end_content else {}
+    last_thinking = extract_last_thinking(events)
+    return judgment, last_thinking
+
+
+# =============================================================================
+# Renderers
+# =============================================================================
+
+def render_overview(suite: str, time_range: str, device: str, app_name: str,
+                    bundle_name: str, hap: str, totals: dict) -> str:
+    pre_total = totals["pre_total"]
+    reg_total = totals["regular_total"]
+    total = pre_total + reg_total
+    pass_count = totals["pass"]
+    fail_count = totals["fail"]
+    unknown_count = totals["unknown"]
+    not_passed = fail_count + unknown_count
+
+    primary_rate = totals["regular_pass_rate"]
+    mixed_rate = totals["pass_rate"]
+
+    lines = [
+        "## 测试概览",
+        "",
+        f"- **测试套件**: {suite}",
+        f"- **测试时间**: {time_range}",
+        f"- **设备**: {device}",
+        f"- **应用**: {app_name} ({bundle_name})",
+        f"- **HAP**: {hap}",
+        f"- **总用例数**: {total}（前置 {pre_total} + 常规 {reg_total}）",
+        f"- **通过**: {pass_count}（前置 {totals['pre_pass']} / 常规 {totals['regular_pass']}）",
+        f"- **失败**: {not_passed}（FAIL {fail_count} + UNKNOWN {unknown_count}）",
+        f"- **常规通过率**: {primary_rate}（仅功能场景，反映本次需求质量）",
+        f"- **含前置通过率**: {mixed_rate}（仅供整体参考；前置用例属于数据/环境准备，与本次需求功能无关）",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def render_case_block(idx: int, prefix: str, case: dict) -> str:
+    """Render a single Pre N / Case N block."""
+    case_name = case["case_name"]
+    if prefix == "Pre":
+        title = case_name[len(PRE_PREFIX):] if case_name.startswith(PRE_PREFIX) else case_name
+    else:
+        title = case_name
+
+    status = case["status"]
+    duration = case.get("duration_seconds", 0)
+    report_dir = case.get("report_dir", "")
+    test_steps = case.get("test_steps", "")
+    reason = (case.get("reason") or "").strip()
+    judgment = case.get("_judgment") or {}
+    last_thinking = case.get("_last_thinking") or ""
+
+    actions, expected = parse_test_steps(test_steps)
+
+    # 操作执行 — derived from judgment / status
+    state_conf = judgment.get("状态确认", "").strip()
+    expected_match = judgment.get("预期验证", "").strip()
+    bug_found = judgment.get("Bug发现", "").strip()
+
+    if status == "PASS":
+        op_exec = f"成功 — {expected_match}" if expected_match else "成功 — AutoTest 判定通过"
+    elif status == "FAIL":
+        if bug_found:
+            op_exec = f"失败 — {bug_found.splitlines()[0][:200]}"
+        elif state_conf:
+            op_exec = f"失败 — {state_conf.splitlines()[0][:200]}"
+        else:
+            op_exec = f"失败 — {reason or 'AutoTest 判定不通过'}"
+    else:  # UNKNOWN
+        op_exec = f"未完成 — {reason or 'AutoTest 未能给出确定结论'}"
+
+    lines = [f"### {prefix} {idx}: {title}", ""]
+    lines.append(f"- **执行结果**: {status}")
+    lines.append("- **操作步骤**:")
+    if actions:
+        for i, a in enumerate(actions, 1):
+            lines.append(f"  {i}. {a}")
+    else:
+        lines.append("  1. （未提供动作步骤）")
+    lines.append(f"- **期望结果**: {expected or '（未提供期望结果）'}")
+    lines.append(f"- **操作执行**: {op_exec}")
+    lines.append(f"- **AutoTest 任务路径**: `{report_dir}`")
+    lines.append("- **AutoTest 详情**:")
+    lines.append(f"  - AutoTest 结果: {status}")
+
+    if judgment:
+        # Dump every section the planner emitted, in stable order if known.
+        # 失败原因 is the downstream-facing alias of "Bug发现" — emit it instead of
+        # Bug发现 to avoid duplication and satisfy the validator's literal check.
+        ordered_keys = ["预期验证", "历史回顾", "状态确认", "判定结果"]
+        seen = {"Bug发现"}  # intentionally skipped — surfaced as 失败原因 below
+        for key in ordered_keys:
+            if key in judgment:
+                lines.extend(_emit_judgment_bullet(key, judgment[key]))
+                seen.add(key)
+        for key, value in judgment.items():
+            if key not in seen:
+                lines.extend(_emit_judgment_bullet(key, value))
+        if status == "PASS":
+            lines.append("  - 失败原因: 无")
+        else:
+            bug = judgment.get("Bug发现") or reason or "未知"
+            lines.extend(_emit_judgment_bullet("失败原因", bug))
+    else:
+        # No judgment block (typical for UNKNOWN). Use JSONL reason + last thinking snippet.
+        lines.append(f"  - 失败原因: {reason or '未知'}")
+        if last_thinking:
+            snippet = last_thinking.replace("\n", " ")
+            snippet = (snippet[:400] + "…") if len(snippet) > 400 else snippet
+            lines.append(f"  - 末态思考摘要: {snippet}")
+
+    lines.append(f"  - 耗时: {duration} 秒")
+
+    # UNKNOWN-specific guidance for the fixer agent — must follow the AutoTest 详情
+    # block so the fixer reads it as part of the case context.
+    if status == "UNKNOWN":
+        lines.append("- **⚠️ UNKNOWN 处理规则（fixer 必读）**:")
+        lines.append(
+            "  - 本用例 AutoTest agent **未到达验证步骤**（步数预算耗尽 / 超时 / 异常终止），"
+            "真实通过状态未知，**不等价于 FAIL**。"
+        )
+        lines.append(
+            "  - 即使白盒审查在相邻代码中发现瑕疵，也**不得**把本用例算作 confirmed → 已修复。"
+            "原始 UNKNOWN 的根因（agent 超时）不会因任何代码改动消失，"
+            "必须在 AutoTest 端加大步数上限/人工复测后才能定论。"
+        )
+        lines.append(
+            "  - 处理建议：在 fixer 白盒审查阶段将本用例归类为 `unknown_no_verdict` —— "
+            "记录"
+            "「待重跑确认」，**不计入本轮修复成果**，也不消耗 fixer 的有效尝试预算。"
+        )
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _one_line(s: str) -> str:
+    """Compact a multi-line judgment value into a single line for the report bullet."""
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def _emit_judgment_bullet(key: str, value: str) -> list[str]:
+    """Render `- key: value` under 'AutoTest 详情'.
+
+    If value has multiple non-empty lines or contains list-like markers, render
+    as `- key:\\n    <multi-line, preserved>` so nested bullets stay readable.
+    Otherwise compact to a single inline line.
+    """
+    text = (value or "").strip()
+    raw_lines = [ln for ln in text.splitlines() if ln.strip()]
+    if len(raw_lines) <= 1:
+        return [f"  - {key}: {_one_line(text) or '（空）'}"]
+
+    out = [f"  - {key}:"]
+    for ln in raw_lines:
+        out.append(f"    {ln.rstrip()}")
+    return out
+
+
+def render_summary(cases: list[dict], totals: dict) -> str:
+    pre_total = totals["pre_total"]
+    reg_total = totals["regular_total"]
+    total = pre_total + reg_total
+    pass_count = totals["pass"]
+    fail_count = totals["fail"]
+    unknown_count = totals["unknown"]
+    not_passed = fail_count + unknown_count
+
+    lines = [
+        "## 测试总结",
+        "",
+        f"- **总计用例**: {total}（PRE {pre_total} + Regular {reg_total}）",
+        f"- **常规用例（功能场景）**: {totals['regular_pass']}/{reg_total} 通过，**通过率 {totals['regular_pass_rate']}**（反映本次需求质量）",
+        f"- **前置用例（数据/环境准备）**: {totals['pre_pass']}/{pre_total} 通过（与本次功能需求无关，仅作环境就绪信号）",
+        f"- **总计通过**: {pass_count}",
+        f"- **总计未通过**: {not_passed}（FAIL {fail_count} + UNKNOWN {unknown_count}）",
+        f"- **含前置通过率**: {totals['pass_rate']}（不作为功能质量指标）",
+        "",
+    ]
+
+    not_passed_cases = [c for c in cases if c["status"] != "PASS"]
+    if not_passed_cases:
+        lines.append("### 未通过用例列表")
+        lines.append("")
+        lines.append("| # | 类别 | 用例描述 | 失败类型 | 失败原因 |")
+        lines.append("|---|------|---------|---------|---------|")
+        for i, c in enumerate(not_passed_cases, 1):
+            category = "前置" if c["case_name"].startswith(PRE_PREFIX) else "常规"
+            name = c["case_name"][len(PRE_PREFIX):] if c["case_name"].startswith(PRE_PREFIX) else c["case_name"]
+            j = c.get("_judgment") or {}
+            bug = (j.get("Bug发现") or "").strip()
+            reason = (c.get("reason") or "").strip()
+            fail_reason = _one_line(bug or reason or "未知")
+            if len(fail_reason) > 200:
+                fail_reason = fail_reason[:200] + "…"
+            lines.append(f"| {i} | {category} | {name} | {c['status']} | {fail_reason} |")
+        lines.append("")
+
+    lines.append("### 建议")
+    lines.append("")
+    suggestions = build_suggestions(cases, totals)
+    for s in suggestions:
+        lines.append(f"- {s}")
+    if not suggestions:
+        lines.append("- 全部用例通过，无需进一步动作。")
+    lines.append("")
+    return "\n".join(lines)
+
+
+# Failure-reason keywords that suggest a regular case failed because of unmet
+# test preconditions rather than a genuine app defect. When pre-cases also
+# failed, these are likely cascade failures and should NOT be treated as app
+# bugs by the fixer.
+_CASCADE_PATTERNS = (
+    "测试环境",
+    "环境条件",
+    "环境异常",
+    "前置",
+    "没有音乐", "无音乐",
+    "没有文件", "无文件",
+    "无可用",
+    "库为空", "歌曲库为空",
+    "数据缺失", "数据不足",
+    "no files", "no music", "library is empty",
+)
+
+
+def _cascade_text(case: dict) -> str:
+    """Concatenate the strings the cascade heuristic should scan over.
+
+    Covers both the judgment block (normal completion) AND the last
+    planner_thinking event (abnormal termination — judgment may be absent
+    when the planner exits early on environment errors).
+    """
+    j = case.get("_judgment") or {}
+    return " ".join([
+        case.get("reason") or "",
+        j.get("Bug发现") or "",
+        j.get("状态确认") or "",
+        j.get("历史回顾") or "",
+        case.get("_last_thinking") or "",
+    ]).lower()
+
+
+def _is_cascade_failure(case: dict) -> bool:
+    text = _cascade_text(case)
+    return any(p.lower() in text for p in _CASCADE_PATTERNS)
+
+
+def build_suggestions(cases: list[dict], totals: dict) -> list[str]:
+    """Compose templated suggestions based on failure categories — no LLM needed."""
+    out: list[str] = []
+    pre_fails = [c for c in cases if c["case_name"].startswith(PRE_PREFIX) and c["status"] != "PASS"]
+    reg_non_pass = [c for c in cases if not c["case_name"].startswith(PRE_PREFIX) and c["status"] != "PASS"]
+    reg_unknowns = [c for c in reg_non_pass if c["status"] == "UNKNOWN"]
+    reg_fails = [c for c in reg_non_pass if c["status"] == "FAIL"]
+
+    # Cascade detection only makes sense when pre-cases also failed.
+    cascade_cases: list[dict] = []
+    if pre_fails:
+        cascade_cases = [c for c in reg_non_pass if _is_cascade_failure(c)]
+
+    if pre_fails:
+        names = ", ".join(c["case_name"][len(PRE_PREFIX):][:30] for c in pre_fails)
+        out.append(
+            f"**前置用例失败**（{len(pre_fails)} 条：{names}）：**前置用例不是本次需求功能的测试**，"
+            "它们只是为常规用例准备数据/环境（如导入媒体、授予权限、跳过引导）。失败 90% 以上是"
+            "测试环境/数据问题（缺素材、设备未授权、文件选择器交互异常等），**不应当作应用缺陷处理**。"
+            "建议：人工补齐前置数据后重跑受影响的常规用例；只有当白盒审查确认前置流程触发的是真实代码 Bug 时，"
+            "才进入 self-test-fixer 修复流。"
+        )
+
+    if cascade_cases:
+        cascade_names = ", ".join(
+            (c["case_name"][len(PRE_PREFIX):] if c["case_name"].startswith(PRE_PREFIX) else c["case_name"])[:50]
+            for c in cascade_cases
+        )
+        out.append(
+            f"**⚠️ {len(cascade_cases)} 条常规用例疑似前置连带失败**（{cascade_names}）："
+            "失败原因中出现「测试环境/环境条件/没有音乐文件/前置不满足」等关键词，"
+            "说明这些用例 **可能不是独立的功能 Bug，而是 PRE 失败的传导**——"
+            "在前置数据未准备好的前提下，这些用例根本没机会跑到验证步骤。"
+            "**修复优先级**：先补齐前置 → 重跑这些用例 → 仍 FAIL 才认定为真实应用缺陷再进入修复流。"
+            "self-test-fixer 收到此类 case 应在白盒审查时严格甄别，避免给「环境不就绪」打补丁。"
+        )
+
+    if reg_unknowns:
+        unknown_names = ", ".join(
+            (c["case_name"][len(PRE_PREFIX):] if c["case_name"].startswith(PRE_PREFIX) else c["case_name"])[:50]
+            for c in reg_unknowns
+        )
+        out.append(
+            f"**{len(reg_unknowns)} 条 UNKNOWN**（{unknown_names}）："
+            "AutoTest agent 因步数预算耗尽 / 超时未达验证阶段，**这些用例的真实通过状态未知**，"
+            "与 FAIL 性质不同。**fixer agent 不应把 UNKNOWN 算作「已修复」**——"
+            "即使白盒能找出顺手可修的瑕疵，原始 UNKNOWN 的根因（agent 超时）不会因代码改动消失，"
+            "必须在 AutoTest 端加大步数上限或人工复测后才能定论。"
+            "建议：将 UNKNOWN 案例从本轮修复目标中排除，仅作「待重跑候选」。"
+        )
+
+    # Show "real" regular fails — those that are NOT obvious cascade failures.
+    real_reg_fails = [c for c in reg_fails if c not in cascade_cases]
+    if real_reg_fails:
+        out.append(
+            f"**{len(real_reg_fails)} 条疑似真实常规 FAIL**（已排除前置连带）：交由 `self-test-fixer` agent "
+            "白盒审查后修复，或人工复核失败用例对应的 HarmonyOS 代码与 Android 参考实现。"
+        )
+    elif reg_fails and not real_reg_fails:
+        out.append(
+            "本次所有常规 FAIL 均疑似前置连带，**预计无需修改应用代码**。"
+            "请优先把前置流程跑通，再用同一批用例复跑确认。"
+        )
+
+    return out
+
+
+# =============================================================================
+# Validator (in-process; replaces the former validate_self_test_report.py)
+# =============================================================================
+
+REQUIRED_OVERVIEW_FIELDS = (
+    "测试套件", "测试时间", "设备", "应用", "HAP", "总用例数", "通过", "失败",
+)
+REQUIRED_CASE_FIELDS = (
+    "执行结果", "操作步骤", "期望结果", "AutoTest 任务路径", "AutoTest 详情",
+)
+REQUIRED_SECTIONS = ("测试概览", "前置用例", "用例详情", "测试总结")
+# Sections under which `### ` headings carry case blocks and must match a strict prefix.
+CASE_SECTIONS = (("前置用例", "Pre"), ("用例详情", "Case"))
+
+
+def _extract_md_section(text: str, section_title: str) -> str | None:
+    """Return the body of `## <section_title>` up to the next `## ` (exclusive), or None."""
+    m = re.search(
+        rf"##\s*{re.escape(section_title)}\s*\n(.*?)(?=\n##\s|\Z)",
+        text,
+        re.DOTALL,
+    )
+    return m.group(1) if m else None
+
+
+def _validate_case_section(section_body: str, section_title: str,
+                           expected_prefix: str) -> tuple[list[tuple[str, str]], list[str]]:
+    """Validate one of the case sections.
+
+    Returns (blocks, errors):
+      - blocks: list of (heading_text, block_body) for downstream field checks.
+      - errors: messages collected during heading scanning.
+    """
+    errors: list[str] = []
+
+    chunks = re.split(r"(?m)^###\s+", section_body)
+    # chunks[0] = preamble (e.g., the note line + optional `_无前置用例_`); chunks[1:] = headed blocks.
+    blocks: list[tuple[str, str]] = []
+    for chunk in chunks[1:]:
+        line_end = chunk.find("\n")
+        if line_end == -1:
+            heading, body = chunk.strip(), ""
+        else:
+            heading, body = chunk[:line_end].strip(), chunk[line_end + 1:]
+        blocks.append((heading, body))
+
+    # Empty pre-section is acceptable (no pre-cases). Empty regular section is not.
+    if not blocks and expected_prefix == "Case":
+        errors.append(
+            f"Section '## {section_title}': no '### Case <N>:' blocks found — "
+            "report may be using a table-only format without per-case detail sections"
+        )
+
+    pattern = re.compile(rf"^{re.escape(expected_prefix)}\s+(\d+):\s")
+    indices: list[int] = []
+    for heading, _body in blocks:
+        m = pattern.match(heading)
+        if not m:
+            errors.append(
+                f"Section '## {section_title}': heading does NOT match "
+                f"`### {expected_prefix} <N>: <title>` — got `### {heading}`"
+            )
+        else:
+            indices.append(int(m.group(1)))
+
+    if indices:
+        expected_indices = list(range(1, len(indices) + 1))
+        if indices != expected_indices:
+            errors.append(
+                f"Section '## {section_title}': {expected_prefix} indices not "
+                f"contiguous from 1; expected {expected_indices}, got {indices}"
+            )
+
+    return blocks, errors
+
+
+def validate_report(report_path: str) -> list[str]:
+    """Return a list of validation errors for self-test-report.md. Empty == PASSED."""
+    path = Path(report_path)
+    if not path.exists():
+        return [f"File not found: {report_path}"]
+
+    text = path.read_text(encoding="utf-8")
+    errors: list[str] = []
+
+    for section in REQUIRED_SECTIONS:
+        if section not in text:
+            errors.append(f"Missing section: '{section}'")
+
+    overview = _extract_md_section(text, "测试概览")
+    if overview is None:
+        errors.append("Cannot locate '## 测试概览' section")
+    else:
+        for field in REQUIRED_OVERVIEW_FIELDS:
+            if field not in overview:
+                errors.append(f"Missing overview field: '{field}'")
+
+    all_blocks: list[tuple[str, str, str]] = []  # (section_title, heading, body)
+    for section_title, expected_prefix in CASE_SECTIONS:
+        body = _extract_md_section(text, section_title)
+        if body is None:
+            continue
+        blocks, section_errors = _validate_case_section(body, section_title, expected_prefix)
+        errors.extend(section_errors)
+        for heading, block_body in blocks:
+            all_blocks.append((section_title, heading, block_body))
+
+    for section_title, heading, body in all_blocks:
+        missing = [f for f in REQUIRED_CASE_FIELDS if f not in body]
+        if missing:
+            label = heading[:60] + ("…" if len(heading) > 60 else "")
+            errors.append(
+                f"Section '## {section_title}', block `### {label}`: missing fields: {missing}"
+            )
+
+    has_failures = re.search(r"\*\*失败\*\*:\s*([1-9])", text)
+    if has_failures:
+        if "未通过用例列表" not in text:
+            errors.append("Report has failures but missing '未通过用例列表' section")
+
+        for section_title, heading, body in all_blocks:
+            if re.search(r"\*\*执行结果\*\*:\s*FAIL", body, re.IGNORECASE):
+                detail = body.split("AutoTest 详情", 1)
+                detail_part = detail[1] if len(detail) > 1 else body
+                if "失败原因" not in detail_part and "失败" not in detail_part:
+                    label = heading[:60] + ("…" if len(heading) > 60 else "")
+                    errors.append(
+                        f"Section '## {section_title}', block `### {label}`: "
+                        f"FAIL but missing failure reason in 'AutoTest 详情'"
+                    )
+
+    return errors
+
+
+# =============================================================================
+# Pipeline (generate)
+# =============================================================================
+
+def render_report(task_subdir: Path, app_metadata: Path, hap: str, device: str,
+                  suite: str) -> str:
+    """Compose the complete self-test-report.md text from task_<ts>/ data."""
+    summary_path = task_subdir / "summary.json"
+    jsonl_path = task_subdir / "task_results.jsonl"
+    for p in (summary_path, jsonl_path):
+        if not p.exists():
+            raise FileNotFoundError(f"missing file in task-subdir: {p}")
+
+    summary = json.loads(summary_path.read_text(encoding="utf-8"))
+
+    cases: list[dict] = []
+    for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        case = json.loads(line)
+        report_dir = case.get("report_dir") or ""
+        judgment, last_thinking = load_case_judgment(report_dir) if report_dir else ({}, "")
+        case["_judgment"] = judgment
+        case["_last_thinking"] = last_thinking
+        cases.append(case)
+
+    pre_cases = [c for c in cases if c["case_name"].startswith(PRE_PREFIX)]
+    reg_cases = [c for c in cases if not c["case_name"].startswith(PRE_PREFIX)]
+
+    def count(seq, status):
+        return sum(1 for c in seq if c["status"] == status)
+
+    pre_pass = count(pre_cases, "PASS")
+    regular_pass = count(reg_cases, "PASS")
+    regular_rate = f"{(regular_pass / len(reg_cases) * 100):.2f}%" if reg_cases else "N/A"
+    totals = {
+        "pre_total": len(pre_cases),
+        "regular_total": len(reg_cases),
+        "pre_pass": pre_pass,
+        "regular_pass": regular_pass,
+        "pass": summary.get("pass_count", count(cases, "PASS")),
+        "fail": summary.get("fail_count", count(cases, "FAIL")),
+        "unknown": summary.get("unknown_count", count(cases, "UNKNOWN")),
+        "pass_rate": summary.get("pass_rate", "0%"),
+        "regular_pass_rate": regular_rate,
+    }
+
+    meta = json.loads(app_metadata.read_text(encoding="utf-8"))
+    bundle_name = meta.get("bundle_name", "")
+    app_name = meta.get("app_name", "")
+
+    start_time = summary.get("start_time", "")
+    end_time = summary.get("end_time", "")
+    time_range = f"{start_time} ~ {end_time}" if start_time and end_time else (start_time or "未知")
+
+    hap_basename = os.path.basename(hap)
+
+    parts = [
+        "# Self-Test 测试报告",
+        "",
+        render_overview(suite, time_range, device, app_name, bundle_name, hap_basename, totals),
+        "---",
+        "",
+        "## 前置用例",
+        "",
+    ]
+    if pre_cases:
+        parts.append(
+            "> **前置用例是为常规用例准备数据/环境的设置脚本（来自 `pre_test_case.md`），"
+            "**不属于本次需求功能本身**。此处的 PASS/FAIL 仅反映测试前置条件是否就绪："
+            "FAIL 通常意味着测试环境问题（如缺少素材、权限未授予、首启引导未跳过），"
+            "并非应用功能缺陷。但需注意——前置失败可能让后续依赖该数据的常规用例无效，"
+            "判读常规结果时应将受影响的用例排除或在补齐前置后重跑。"
+        )
+        parts.append("")
+        for i, case in enumerate(pre_cases, 1):
+            parts.append(render_case_block(i, "Pre", case))
+    else:
+        parts.append("_无前置用例_")
+        parts.append("")
+
+    parts.extend(["---", "", "## 用例详情", ""])
+    for i, case in enumerate(reg_cases, 1):
+        parts.append(render_case_block(i, "Case", case))
+
+    parts.extend(["---", "", render_summary(cases, totals)])
+    return "\n".join(parts)
+
+
+def _print_validation(errors: list[str], report_path: Path) -> int:
+    if not errors:
+        print(f"VALIDATION PASSED: {report_path}")
+        return 0
+    print(f"VALIDATION FAILED: {len(errors)} issue(s) in {report_path}")
+    for e in errors:
+        print(f"  - {e}")
+    return 1
+
+
+# =============================================================================
+# CLI
+# =============================================================================
+
+def cmd_generate(args) -> None:
+    task_subdir: Path = args.task_subdir.resolve()
+    if not task_subdir.exists():
+        print(f"ERROR: task-subdir not found: {task_subdir}", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        report_text = render_report(
+            task_subdir=task_subdir,
+            app_metadata=args.app_metadata,
+            hap=args.hap,
+            device=args.device,
+            suite=args.suite,
+        )
+    except FileNotFoundError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    out_path: Path = args.out.resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(report_text, encoding="utf-8")
+    print(f"Generated: {out_path}")
+
+    if args.validate:
+        sys.exit(_print_validation(validate_report(str(out_path)), out_path))
+
+
+def cmd_validate(args) -> None:
+    path = Path(args.path).resolve()
+    sys.exit(_print_validation(validate_report(str(path)), path))
+
+
+def main():
+    if sys.platform == "win32":
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(
+        description="Generate or validate self-test-report.md."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_gen = sub.add_parser("generate", help="Render self-test-report.md from a task_<ts>/ directory")
+    p_gen.add_argument("--task-subdir", required=True, type=Path)
+    p_gen.add_argument("--app-metadata", required=True, type=Path)
+    p_gen.add_argument("--hap", required=True)
+    p_gen.add_argument("--device", required=True)
+    p_gen.add_argument("--suite", required=True)
+    p_gen.add_argument("--out", required=True, type=Path)
+    p_gen.add_argument("--validate", action="store_true",
+                       help="After writing, re-validate the report in-process")
+    p_gen.set_defaults(func=cmd_generate)
+
+    p_val = sub.add_parser("validate", help="Validate an existing self-test-report.md")
+    p_val.add_argument("path", help="Path to the self-test-report.md to validate")
+    p_val.set_defaults(func=cmd_validate)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()