8.2 CI 微基准门禁

① 先测出秤的实际误差（±1 kg）
② 警报阈值设成 2 kg（误差的 2 倍）
③ 只有真的涨了 2 kg 才提醒

# ❌ 绝对阈值：换 runner 型号就全线失败
- name: Check performance
  run: |
    SCORE=$(read_score)
    if [ "$SCORE" -lt 16000 ]; then exit 1; fi   # 硬编码数字

# ✅ 相对比较：与仓库中的基线比
- name: Compare against baseline
  run: python3 tools/compare_benchmark.py current.json perf/baseline.json --threshold 0.15

噪声底线（实测）→ 阈值 = 噪声底线 × 1.5 ~ 2

例：微基准的轮间 CV = 4%
    阈值设为 15%（留足安全边际）
    只有退化超过 15% 才失败

# 阶段一（头两周）：只报告，不失败
- name: Compare against baseline
  run: |
    python3 tools/compare_benchmark.py current.json perf/baseline.json \
      --threshold 0.15 --report-only

# 阶段二（确认零误报后）：开启失败
- name: Compare against baseline
  run: |
    python3 tools/compare_benchmark.py current.json perf/baseline.json --threshold 0.15

# .github/workflows/perf-gate.yml
name: perf-gate

on:
  push:
    branches: [main]           # ⚠️ 只在主干跑（PR 上噪声大、成本高）
  workflow_dispatch:           # 允许手动触发

jobs:
  micro-benchmark:
    # ⚠️ 生产项目应使用自建、规格固定的 runner
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0       # 需要历史基线

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'

      - name: Cache Gradle
        uses: actions/cache@v4
        with:
          path: ~/.gradle
          key: gradle-${{ hashFiles('**/*.gradle.kts') }}

      # ① 跑微基准（kotlinx-benchmark 输出 JSON）
      - name: Run benchmarks
        run: ./gradlew benchmark

      # ② 与基线对比（相对比较 + 宽松阈值）
      - name: Compare against baseline
        id: compare
        continue-on-error: true        # ⚠️ 先不失败，收集数据
        run: |
          python3 tools/compare_benchmark.py \
            build/reports/benchmarks/main.json \
            perf/baseline.json \
            --threshold 0.15 \
            --output perf-result.md

      # ③ 把结果发到 PR 评论或 Slack
      - name: Report result
        if: always()
        run: |
          cat perf-result.md >> $GITHUB_STEP_SUMMARY

      # ④ 关闭 continue-on-error 后，这一步会让 CI 失败
      - name: Fail if regression
        if: steps.compare.outcome == 'failure'
        run: exit 1

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: benchmark-results
          path: build/reports/benchmarks/

① 基线文件存放在仓库里：perf/baseline.json（有版本历史、可 review）
② 只在【明确的时机】更新：
   - 发布新版本时（作为新基线）
   - 或经过人工确认的"这是预期的性能变化"
③ 基线的更新必须【单独提交】并写明理由：
   commit message: "perf: update baseline after index optimization (-45% P99)"
④ 更新基线的 PR 需要有性能负责人 review
⑤ 保留历史基线（按版本号命名）：perf/baseline-v2.3.0.json

门禁失败
    │
    ├─ ① 看变化幅度
    │      ├─ 在噪声底线的 1~1.5 倍之间 → 可能是噪声，但也要查
    │      └─ 超过噪声底线的 2 倍以上 → 高度怀疑是真退化
    │
    ├─ ② 看是不是环境问题
    │      ├─ runner 型号变了？（CI 日志里有）
    │      ├─ 同一批次的其他 job 也失败了？
    │      └─ 是否有其他 job 在同一个 runner 上竞争？
    │
    ├─ ③ 看是不是真的退化
    │      ├─ 本地复现（用同样的基准）
    │      ├─ 看这次提交改了什么（是不是碰了热路径）
    │      └─ 看火焰图/分配速率有没有变化
    │
    └─ ④ 处理
           ├─ 真退化 → 修复代码（或明确接受并更新基线）
           └─ 噪声 → 不改基线，重跑一次（并在 issue 里记录这次误报）

## 门禁误报记录

| 日期 | 提交 | 指标 | 变化 | 是否复现 | 处理 |
| --- | --- | --- | --- | --- | --- |
| 2025-01-15 | abc123 | serialize | +16% | 否 | 重跑通过，疑似噪声 |
| 2025-01-18 | def456 | serialize | +18% | 否 | 重跑通过 |
| 2025-01-22 | ghi789 | serialize | +14% | **是** | 确认退化，已修复 |

→ 两周 3 次触发，其中 1 次真实。误报率 67%。
→ 阈值从 15% 调整到 20%（噪声 4% × 5 = 20%，留足余量）