ops-tune-workbench-plugin 0.0.0-stage → 0.0.1-beta.2

package/skills/tool-ops-tune/ops-verdict/scripts/batch_pipeline.py

@@ -0,0 +1,444 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+"""batch_pipeline.py — 全量 case 批量快照与对比（检视 F11）
+
+把 A1 全量 case 铁律（>20 取前 20 逐 case 覆盖）从「主 agent 手工串 20×N
+次命令再手拼表」变成一条命令：输入 cases.csv + 逐 case 性能数据 +
+基线快照，自动逐 case 建 snapshot → 跑 delta_compare → 输出
+comparison_matrix.md（逐 case 表 + geomean + 最差/最好 case + 精度列）。
+
+输入形态（性能数据 CSV，一行一 case×variant）：
+  case_id,variant,kernel_avg_us,precision[,kernel_p50_us,kernel_p95_us,kernel_max_us]
+  c01,baseline,100.0,pass
+  c01,round-01-ub-fusion,92.0,pass
+
+用法：
+  python3 batch_pipeline.py \
+      --cases cases.csv \
+      --perf perf_data.csv \
+      --baseline-variant baseline \
+      --after-variants round-01-ub-fusion,round-01-mte2-preload \
+      --scope tuning_artifacts/gelu/scope.json \
+      --output-dir tuning_artifacts/gelu/matrix
+
+  # 直连模式（P0-1）：collect_cases.py 产物目录直接进来，无需手拼 CSV
+  python3 batch_pipeline.py \
+      --from-collect ./collect_out \
+      --cases cases.csv \
+      --baseline-variant system \
+      --after-variants custom \
+      --scope tuning_artifacts/gelu/scope.json \
+      --output-dir tuning_artifacts/gelu/matrix
+  # --from-collect 读取 <dir>/perf_data.csv（collect_cases.py 产出）；
+  # baseline-variant=system + after-variants=custom 即「vs 标杆」读数。
+
+依赖 scope.json（opstune.scope/1.0）提供 12 HARD 口径字段；逐 case 的
+shape/dtype 从 cases.csv 透传进 snapshot（shape 是 HARD 字段，逐 case 值不同）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+SNAPSHOT = HERE / "snapshot.py"
+DELTA_COMPARE = HERE / "delta_compare.py"
+
+HARD_KEYS = (
+    "op",
+    "soc",
+    "mode",
+    "timing_method",
+    "baseline_kind",
+    "cann_version",
+    "device_id",
+    "shape",
+    "dtype",
+    "format",
+    "warmup",
+    "repeat",
+)
+
+
+def load_cases(path: str) -> list[dict]:
+    with open(path, encoding="utf-8-sig") as f:
+        rows = list(csv.DictReader(f))
+    for r in rows:
+        if not r.get("case_id") or not r.get("shape") or not r.get("dtype"):
+            raise SystemExit(f"ERROR: cases.csv 行缺必需列（case_id/shape/dtype）: {r}")
+    return rows
+
+
+def load_perf(path: str) -> dict[tuple[str, str], dict]:
+    """{(case_id, variant): {kernel_avg_us, precision, 分布字段...}}
+
+    kernel_avg_us 为空（collect 侧采集失败/无数据）的行跳过并 WARN——
+    直连模式下 collect_summary 已有状态，不在此静默编造。"""
+    out = {}
+    with open(path, encoding="utf-8-sig") as f:
+        for row in csv.DictReader(f):
+            key = (row["case_id"], row["variant"])
+            if not str(row.get("kernel_avg_us", "")).strip():
+                print(f"WARN: perf 行无 kernel_avg_us，跳过: {key}", file=sys.stderr)
+                continue
+            out[key] = {
+                "kernel_avg_us": float(row["kernel_avg_us"]),
+                "precision": row.get("precision", "pass"),
+                "kernel_p50_us": float(row["kernel_p50_us"])
+                if row.get("kernel_p50_us")
+                else None,
+                "kernel_p95_us": float(row["kernel_p95_us"])
+                if row.get("kernel_p95_us")
+                else None,
+                "kernel_max_us": float(row["kernel_max_us"])
+                if row.get("kernel_max_us")
+                else None,
+            }
+    return out
+
+
+def run_snapshot(
+    scope: dict, case: dict, variant: str, perf: dict, out_path: Path
+) -> None:
+    cmd = [
+        sys.executable,
+        str(SNAPSHOT),
+        "--op",
+        scope["op"],
+        "--variant",
+        variant,
+        "--mode",
+        scope["mode"],
+        "--soc",
+        scope["soc"],
+        "--precision",
+        perf["precision"],
+        "--kernel-avg-us",
+        str(perf["kernel_avg_us"]),
+        "--timing-method",
+        scope["timing_method"],
+        "--baseline-kind",
+        scope["baseline_kind"],
+        "--cann-version",
+        scope["cann_version"],
+        "--device-id",
+        scope["device_id"],
+        "--shape",
+        case["shape"],
+        "--dtype",
+        case["dtype"],
+        "--format",
+        scope["format"],
+        "--warmup",
+        str(scope["warmup"]),
+        "--repeat",
+        str(scope["repeat"]),
+        "--no-env-probe",
+        "-o",
+        str(out_path),
+    ]
+    for opt, key in (
+        ("--kernel-p50-us", "kernel_p50_us"),
+        ("--kernel-p95-us", "kernel_p95_us"),
+        ("--kernel-max-us", "kernel_max_us"),
+    ):
+        if perf.get(key) is not None:
+            cmd += [opt, str(perf[key])]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise SystemExit(f"ERROR: snapshot 失败 {out_path}: {proc.stderr[:300]}")
+
+
+def run_compare(base: Path, after: Path, out_md: Path) -> tuple[int, str]:
+    proc = subprocess.run(
+        [
+            sys.executable,
+            str(DELTA_COMPARE),
+            "--baseline",
+            str(base),
+            "--after",
+            str(after),
+            "--output",
+            str(out_md),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    return proc.returncode, proc.stdout
+
+
+def parse_conclusion(md_text: str) -> tuple[str, float | None]:
+    """从 comparison.md 提取三段结论类型与 speedup。"""
+    speedup = None
+    for line in md_text.splitlines():
+        # 行形态：| speedup | — | 1.200 |（第三列为值）
+        if line.startswith("| speedup |"):
+            cells = [c.strip() for c in line.split("|")]
+            try:
+                speedup = float(cells[3])
+            except (ValueError, IndexError):
+                pass
+    if "提升" in md_text:
+        return "KEEP", speedup
+    if "劣化" in md_text:
+        return "REVERT", speedup
+    if "噪声带内" in md_text:
+        return "NOISE", speedup
+    return "UNRESOLVED", speedup
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="全量 case 批量快照与对比（A1 铁律工具化）"
+    )
+    ap.add_argument(
+        "--cases", required=True, help="cases.csv（case_id/shape/dtype/attrs）"
+    )
+    ap.add_argument(
+        "--perf",
+        default=None,
+        help="性能数据 CSV（case_id/variant/kernel_avg_us/precision[分布字段]）；"
+        "与 --from-collect 二选一",
+    )
+    ap.add_argument(
+        "--from-collect",
+        default=None,
+        help="collect_cases.py 产物根目录（P0-1 直连：读 <dir>/perf_data.csv，"
+        "消灭手拼 CSV；未完成的 case 行由 collect 侧标注，此处如实跳过）",
+    )
+    ap.add_argument("--baseline-variant", default="baseline")
+    ap.add_argument("--after-variants", required=True, help="逗号分隔的优化变体名")
+    ap.add_argument(
+        "--scope",
+        required=True,
+        help="scope.json（opstune.scope/1.0，提供 12 HARD 字段）",
+    )
+    ap.add_argument("--output-dir", required=True)
+    ap.add_argument(
+        "--max-cases",
+        type=int,
+        default=20,
+        help="case 截断上限（A1 铁律 >20 取前 20；0 = 不截断）",
+    )
+    args = ap.parse_args()
+
+    scope = json.loads(Path(args.scope).read_text(encoding="utf-8"))
+    missing = [k for k in HARD_KEYS if k not in scope]
+    if missing:
+        print(f"ERROR: scope.json 缺 HARD 字段 {missing}", file=sys.stderr)
+        return 1
+
+    cases = load_cases(args.cases)
+    truncated = False
+    if args.max_cases and len(cases) > args.max_cases:
+        cases = cases[: args.max_cases]
+        truncated = True
+        print(
+            f"WARN: cases {len(load_cases(args.cases))} > {args.max_cases}，取前 {args.max_cases}"
+            f"（A1 铁律截断，报告必须告知用户）",
+            file=sys.stderr,
+        )
+
+    if not args.perf and not args.from_collect:
+        print("ERROR: --perf 与 --from-collect 必须提供其一", file=sys.stderr)
+        return 1
+    if args.perf and args.from_collect:
+        print(
+            "ERROR: --perf 与 --from-collect 互斥（直连模式自带 perf_data.csv）",
+            file=sys.stderr,
+        )
+        return 1
+    perf_path = args.perf
+    if args.from_collect:
+        collect_root = Path(args.from_collect)
+        candidate = collect_root / "perf_data.csv"
+        if not candidate.exists():
+            print(
+                f"ERROR: {candidate} 不存在（--from-collect 需要 collect_cases.py 产物目录）",
+                file=sys.stderr,
+            )
+            return 1
+        perf_path = str(candidate)
+        # 伪 Green 防护：collect 侧 failed/partial 如实透传（不静默跳过）
+        summary_path = collect_root / "collect_summary.json"
+        if summary_path.exists():
+            summary = json.loads(summary_path.read_text(encoding="utf-8"))
+            bad = summary.get("failed_or_partial", [])
+            if bad:
+                print(
+                    f"WARN: collect 侧 {len(bad)} 项 failed/partial 将无数据（详见 "
+                    f"{summary_path}，伪 Green 防护不抹掉）",
+                    file=sys.stderr,
+                )
+
+    perf = load_perf(perf_path)
+    variants = [v.strip() for v in args.after_variants.split(",") if v.strip()]
+    out_dir = Path(args.output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # ---- 逐 case × 逐变体：snapshot + delta_compare ----
+    matrix: dict[tuple[str, str], dict] = {}
+    for case in cases:
+        cid = case["case_id"]
+        base_perf = perf.get((cid, args.baseline_variant))
+        if base_perf is None:
+            print(f"WARN: case {cid} 无基线数据，跳过", file=sys.stderr)
+            continue
+        base_snap = out_dir / cid / "baseline.json"
+        run_snapshot(scope, case, args.baseline_variant, base_perf, base_snap)
+        for variant in variants:
+            v_perf = perf.get((cid, variant))
+            if v_perf is None:
+                print(
+                    f"WARN: case {cid} 变体 {variant} 无数据，记 MISSING",
+                    file=sys.stderr,
+                )
+                matrix[(cid, variant)] = {
+                    "status": "MISSING",
+                    "speedup": None,
+                    "precision": "-",
+                    "base_us": base_perf["kernel_avg_us"],
+                    "after_us": None,
+                }
+                continue
+            v_snap = out_dir / cid / f"{variant}.json"
+            comp_md = out_dir / cid / f"{variant}_comparison.md"
+            run_snapshot(scope, case, variant, v_perf, v_snap)
+            rc, stdout = run_compare(base_snap, v_snap, comp_md)
+            if rc == 2:
+                matrix[(cid, variant)] = {
+                    "status": "REJECTED(口径/精度)",
+                    "speedup": None,
+                    "precision": v_perf["precision"],
+                    "base_us": base_perf["kernel_avg_us"],
+                    "after_us": v_perf["kernel_avg_us"],
+                }
+                continue
+            status, speedup = parse_conclusion(comp_md.read_text(encoding="utf-8"))
+            matrix[(cid, variant)] = {
+                "status": status,
+                "speedup": speedup,
+                "precision": v_perf["precision"],
+                "base_us": base_perf["kernel_avg_us"],
+                "after_us": v_perf["kernel_avg_us"],
+            }
+        # 中间快照保留策略（P2-2/G20 ③，反馈修正：此前注释自相矛盾——标题「清理」
+        # 正文「不删」）。决策：**默认全保留**（snapshot 契约文件是审计真源，
+        # delta_compare 的口径指纹复验依赖两侧 json）；目录膨胀用归档清单治理：
+        # comparison_matrix.md 末尾自动生成产物索引（哪些文件可归档/删除由人工
+        # 按清单决策，不自动删除——误删审计链的代价 > 磁盘成本）。
+
+    # ---- comparison_matrix.md ----
+    md = [
+        "# 全量 case 对比矩阵（batch_pipeline 自动生成）",
+        "",
+        f"- 基线变体：{args.baseline_variant}；优化变体：{', '.join(variants)}",
+        f"- case 数：{len(cases)}{'（已按 A1 铁律截断，须告知用户）' if truncated else ''}",
+        f"- 口径：{scope['soc']} / CANN {scope['cann_version']} / device {scope['device_id']}"
+        f" / timing={scope['timing_method']} / warmup={scope['warmup']} repeat={scope['repeat']}",
+        "",
+    ]
+    for variant in variants:
+        md += [
+            f"## {variant}",
+            "",
+            "| Case | Shape | dtype | 基线(us) | 优化后(us) | speedup | 结论 | 精度 |",
+            "|------|-------|-------|---------|-----------|---------|------|------|",
+        ]
+        speeds = []
+        for case in cases:
+            m = matrix.get((case["case_id"], variant))
+            if m is None:
+                continue
+            sp = f"{m['speedup']:.3f}x" if m["speedup"] else "—"
+            md.append(
+                f"| {case['case_id']} | {case['shape']} | {case['dtype']} | "
+                f"{m['base_us']} | {m['after_us'] if m['after_us'] else '—'} | "
+                f"{sp} | {m['status']} | {m['precision']} |"
+            )
+            if m["speedup"]:
+                speeds.append(m["speedup"])
+        md.append("")
+        if speeds:
+            geomean = math.exp(sum(math.log(s) for s in speeds) / len(speeds))
+            best = max(speeds)
+            worst = min(speeds)
+            n_keep = sum(
+                1
+                for c in cases
+                if matrix.get((c["case_id"], variant), {}).get("status") == "KEEP"
+            )
+            n_revert = sum(
+                1
+                for c in cases
+                if matrix.get((c["case_id"], variant), {}).get("status") == "REVERT"
+            )
+            n_noise = sum(
+                1
+                for c in cases
+                if matrix.get((c["case_id"], variant), {}).get("status") == "NOISE"
+            )
+            n_rej = sum(
+                1
+                for c in cases
+                if str(
+                    matrix.get((c["case_id"], variant), {}).get("status", "")
+                ).startswith("REJECTED")
+            )
+            md += [
+                "**汇总**：",
+                f"- geomean speedup：**{geomean:.3f}x**（{len(speeds)}/{len(cases)} case 有可比数据）",
+                f"- 最好 case：{best:.3f}x ｜ 最差 case：{worst:.3f}x",
+                f"- KEEP {n_keep} ｜ REVERT {n_revert} ｜ 噪声带内 {n_noise} ｜ 拒绝比较 {n_rej} ｜ MISSING {len(cases) - len(speeds) - n_rej}",
+                "",
+                "> 汇总口径：拒绝比较（口径漂移/精度 fail）与 MISSING 的 case 不进 geomean；"
+                "REVERT case 计入（负样本是瓶颈证据）。逐 case comparison.md 见各 case 子目录。",
+            ]
+        md.append("")
+
+    # ---- 产物索引（P2-2/G20 ③：目录膨胀治理——归档清单自动生成，删除由人工决策）----
+    n_snap = n_comp = 0
+    for cid_dir in out_dir.iterdir():
+        if not cid_dir.is_dir():
+            continue
+        n_snap += sum(1 for p in cid_dir.glob("*.json"))
+        n_comp += sum(1 for p in cid_dir.glob("*_comparison.md"))
+    md += [
+        "## 产物索引（tuning_artifacts 归档清单）",
+        "",
+        f"- 逐 case snapshot JSON：{n_snap} 份（口径指纹审计真源，delta_compare 复验依赖）",
+        f"- 逐 case comparison.md：{n_comp} 份（三段结论与处置依据）",
+        "- 本矩阵：comparison_matrix.md",
+        "",
+        "> 生命周期：多轮迭代结束后按本清单人工决策归档/删除（ KEEP 轮的两侧 json",
+        "> 与 REVERT 轮的 comparison.md 建议长期保留——回滚记录是瓶颈证据；",
+        "> NOISE 轮中间快照可归档压缩）。本工具不自动删除任何产物。",
+    ]
+
+    out_md = out_dir / "comparison_matrix.md"
+    out_md.write_text("\n".join(md) + "\n", encoding="utf-8")
+    n_rows = sum(1 for k in matrix if k[1] in variants)
+    print(
+        f"matrix → {out_md}（{n_rows} 行 = {len(cases)} case × {len(variants)} 机制；"
+        f"产物索引：{n_snap} snapshot + {n_comp} comparison）"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/tool-ops-tune/ops-verdict/scripts/calibrate.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+"""calibrate.py — 预估-实测校准回路（REVIEW2 G9 / 反馈 P1-2 ①，27-2 回路兑现）
+
+设计对齐：
+  - io-contracts.md 已冻结 calibration_data.json 契约（opstune.calibration/1.0，
+    Step 5 逐轮产出），但全仓无任何脚本消费它——「校准回路」只有入口没有回路。
+  - 本脚本是消费端：读多工程 calibration_data.json → 按 (mechanism, bound_rule)
+    聚合 est vs measured 偏差 → 输出 speedup_range 修订建议（Markdown diff）。
+  - **不自动回写规则 YAML**：修订建议经人工评审后改 YAML，改完必须过
+    evals/run_evals.py 回归（反馈 P1-2 原文要求，阈值纪律不破坏）。
+
+用法：
+  python3 calibrate.py --inputs tuning_artifacts/gelu/calibration_data.json \
+      tuning_artifacts/softmax/calibration_data.json -o calibration_report.md
+
+偏差口径（每聚合组）：
+  est_lo / est_hi ：该组全部条目 speedup_est 区间的均值
+  measured_mean  ：实测 speedup 均值（KEEP 与 REVERT 都算——REVERT 是负样本，
+                   两者都是「预估 vs 实测」的校准输入；噪声带内条目不算——
+                   带内数字无方向信息）
+  verdict        ：est 区间对 measured 的覆盖关系（covered / est_high / est_low /
+                   flipped：KEEP 预估被实测 REVERT 推翻）
+修订建议：
+  est_high（系统性高估）→ 建议区间下压到 measured_mean 的 0.9~1.1 倍带；
+  est_low（系统性低估）→ 建议区间上抬同带；样本 < 3 只提示不给出数值建议
+  （单点不改阈值——阈值纪律的统计底线）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import sys
+from pathlib import Path
+
+
+def load_entries(paths: list[str]) -> list[dict]:
+    """读多份 calibration_data.json，展平为带工程来源的条目列表。"""
+    entries = []
+    for p in paths:
+        data = json.loads(Path(p).read_text(encoding="utf-8"))
+        if data.get("schema") != "opstune.calibration/1.0":
+            print(
+                f"WARN: {p} schema != opstune.calibration/1.0，仍按字段尽力解析",
+                file=sys.stderr,
+            )
+        for e in data.get("entries", []):
+            if not e.get("mechanism") or not e.get("bound_rule"):
+                print(
+                    f"WARN: {p} 存在缺 mechanism/bound_rule 的条目，跳过: {e}",
+                    file=sys.stderr,
+                )
+                continue
+            e["_source"] = data.get("operator", Path(p).parent.name)
+            e["_path"] = p
+            entries.append(e)
+    return entries
+
+
+def group_key(e: dict) -> str:
+    return f"{e['mechanism']}@{e['bound_rule']}"
+
+
+def measured_value(e: dict) -> float | None:
+    v = e.get("speedup_measured")
+    if v is None:
+        return None
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def est_bounds(e: dict) -> tuple[float | None, float | None]:
+    est = e.get("speedup_est")
+    if not isinstance(est, (list, tuple)) or len(est) != 2:
+        return None, None
+    try:
+        return float(est[0]), float(est[1])
+    except (TypeError, ValueError):
+        return None, None
+
+
+def verdict_of(lo: float, hi: float, m: float, e: dict) -> str:
+    """est 区间对 measured 的覆盖关系。"""
+    if e.get("verdict") == "REVERT" and m is not None and m >= 1.0:
+        return "flipped"  # 预估有收益、实测劣化被回滚 → 最强纠偏信号
+    if m is None:
+        return "no-data"
+    if lo <= m <= hi:
+        return "covered"
+    if m < lo:
+        return "est_high"  # 实测低于预估下界 → 系统性高估
+    return "est_low"  # 实测高于预估上界 → 系统性低估
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="预估-实测校准回路（calibration_data.json 消费端）"
+    )
+    ap.add_argument(
+        "--inputs",
+        required=True,
+        nargs="+",
+        help="一份或多份 calibration_data.json（多工程聚合）",
+    )
+    ap.add_argument("-o", "--output", required=True, help="校准报告 Markdown 输出")
+    args = ap.parse_args()
+
+    entries = load_entries(args.inputs)
+    if not entries:
+        print("ERROR: 无有效条目（检查 calibration_data.json）", file=sys.stderr)
+        return 1
+
+    # 噪声带内条目无方向信息，不进聚合（io-contracts 纪律：带内不判收益/劣化）
+    usable = [e for e in entries if e.get("verdict") in ("KEEP", "REVERT")]
+    skipped_band = len(entries) - len(usable)
+    if skipped_band:
+        print(
+            f"NOTE: {skipped_band} 条噪声带内/无 verdict 条目不进聚合", file=sys.stderr
+        )
+
+    groups: dict[str, list[dict]] = {}
+    for e in usable:
+        groups.setdefault(group_key(e), []).append(e)
+
+    md = [
+        "# 预估-实测校准报告（calibrate.py 自动生成）",
+        "",
+        f"- 生成时间：{datetime.datetime.now().isoformat(timespec='seconds')}",
+        f"- 输入：{len(args.inputs)} 份 calibration_data.json，"
+        f"{len(entries)} 条轮次记录（其中 {skipped_band} 条噪声带内不进聚合）",
+        f"- 聚合维度：(mechanism, bound_rule) 共 {len(groups)} 组",
+        "",
+        "> **处置纪律**：本报告只产出修订**建议**（Markdown diff 形态）。修订须人工评审后",
+        "> 手工改规则 YAML 的 speedup_range，改完必须过 `evals/run_evals.py` 回归全绿",
+        "> 才可合入——不自动回写（阈值纪律，反馈 P1-2 原文）。",
+        "",
+    ]
+
+    n_high = n_low = n_flip = 0
+    for key in sorted(groups):
+        g = groups[key]
+        est_pairs = [est_bounds(e) for e in g]
+        est_pairs = [(lo, hi) for lo, hi in est_pairs if lo is not None]
+        measured = [measured_value(e) for e in g]
+        measured = [m for m in measured if m is not None]
+        if not est_pairs:
+            continue
+        lo = sum(p[0] for p in est_pairs) / len(est_pairs)
+        hi = sum(p[1] for p in est_pairs) / len(est_pairs)
+        m_mean = sum(measured) / len(measured) if measured else None
+        m_min = min(measured) if measured else None
+        m_max = max(measured) if measured else None
+        verdicts = [
+            verdict_of(
+                est_bounds(e)[0] or lo, est_bounds(e)[1] or hi, measured_value(e), e
+            )
+            for e in g
+        ]
+        v_high = verdicts.count("est_high")
+        v_low = verdicts.count("est_low")
+        v_flip = verdicts.count("flipped")
+        n_high += v_high
+        n_low += v_low
+        n_flip += v_flip
+
+        md += [
+            f"## {key}（{len(g)} 轮）",
+            "",
+            "| 项 | 值 |",
+            "|---|---|",
+            f"| est 区间（均值口径） | [{lo:.2f}, {hi:.2f}] |",
+            f"| measured | mean {f'{m_mean:.3f}' if m_mean is not None else '—'}"
+            f" / min {f'{m_min:.3f}' if m_min is not None else '—'}"
+            f" / max {f'{m_max:.3f}' if m_max is not None else '—'}（{len(measured)} 条有数值） |",
+            f"| 覆盖判定 | est_high ×{v_high} ｜ est_low ×{v_low} ｜ flipped ×{v_flip} ｜"
+            f" covered ×{verdicts.count('covered')} |",
+            f"| 轮次来源 | {', '.join(sorted({e['_source'] for e in g}))} |",
+        ]
+
+        # 修订建议：样本 ≥3 且方向一致才给数值（单点不改阈值）
+        if len(g) >= 3 and m_mean is not None:
+            if v_high >= 2 and v_high > v_low:
+                md += [
+                    "",
+                    "**建议（est 系统性偏高）**：speedup_range 下压——",
+                    "```diff",
+                    f"- speedup_range: [{lo:.2f}, {hi:.2f}]",
+                    f"+ speedup_range: [{m_mean * 0.9:.2f}, {m_mean * 1.1:.2f}]",
+                    "```",
+                    f"依据：{v_high}/{len(g)} 轮实测低于预估下界，实测均值 {m_mean:.3f}。",
+                ]
+            elif v_low >= 2 and v_low > v_high:
+                md += [
+                    "",
+                    "**建议（est 系统性偏低）**：speedup_range 上抬——",
+                    "```diff",
+                    f"- speedup_range: [{lo:.2f}, {hi:.2f}]",
+                    f"+ speedup_range: [{m_mean * 0.9:.2f}, {m_mean * 1.1:.2f}]",
+                    "```",
+                    f"依据：{v_low}/{len(g)} 轮实测高于预估上界，实测均值 {m_mean:.3f}。",
+                ]
+            elif v_flip >= 2:
+                md += [
+                    "",
+                    f"**建议（方向翻车）**：{v_flip} 轮预估 KEEP 实测 REVERT——"
+                    "先查机制适用前提是否写错（该 (mechanism, bound_rule) 组合的"
+                    "机制卡「适用前提」或反证条目可能漏了排除条件），"
+                    "比压区间更优先。",
+                ]
+            else:
+                md += ["", "覆盖良好（或方向不一致），无需修订。"]
+        else:
+            md += [
+                "",
+                f"样本 {len(g)} < 3：只记录不给出数值建议（单点不改阈值——统计底线）。",
+            ]
+        md.append("")
+
+    md += [
+        "## 汇总",
+        "",
+        f"- est_high（高估）{n_high} 轮 ｜ est_low（低估）{n_low} 轮 ｜ "
+        f"flipped（方向翻车）{n_flip} 轮",
+        "- 跑得越多 🟡 越多的问题开始收敛：上述建议经评审回写后，"
+        "speedup_est 的可信度随调优次数复利提升。",
+    ]
+
+    out = Path(args.output)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("\n".join(md) + "\n", encoding="utf-8")
+    print(f"calibration report → {out}（{len(groups)} 组 / {len(usable)} 轮）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())