docs/openhands-benchmark-runbook.md

# OpenHands × SWE-bench 执行手册

规划全文：[`openhands-benchmark-plan.md`](./openhands-benchmark-plan.md)  
**S 档（10 issues）：** [`openhands-s-tier-runbook.md`](./openhands-s-tier-runbook.md)

## P0（本地，无需 OpenHands 集群）

```bash
# 1) 适配器 + 指标
npm test -- tests/unit/openhands-adapter.spec.ts

# 2) JSONL → LogEntry[]
npm run openhands:adapt -- scripts/fixtures/openhands-sample-trace.jsonl artifacts/openhands-adapted-logs.json

# 3) 一键 PoC（有 API Key 时连 staging optimize）
export BENCH_BASE_URL="http://127.0.0.1:3000"   # 或 staging URL
export BENCH_API_KEY="your-key"
npm run openhands:poc

# 4) 仅跑基准（fixtures 目录下所有 *.jsonl）
OPENHANDS_TRACE_DIR=scripts/fixtures/p1-demo/C1 OPENHANDS_ARM=C1 \
  SWE_RESULTS_FILE=scripts/fixtures/p1-demo/swe-results.json \
  npm run bench:openhands

# S 档 10 issues 端到端（fixtures，无需 OpenHands）
npm run openhands:s:demo

# P1 聚合 + Go/Kill（无需 OpenHands 真跑）
npm run openhands:p1:demo
# 或分步：
# OPENHANDS_ARM=C0|C1 … npm run bench:openhands
# npm run openhands:aggregate
# npm run openhands:p1:evaluate

# 5) 门禁（P1 可调 pattern 命中率）
RUN_GATE=true BENCH_GATE_MAX_P95_MS=2000 npm run openhands:poc
```

**P0 过线：** `log_count >= 8`；`repeat_read_rate > 0`；若 live optimize：`p95_latency_ms < 2000` 且 `patterns` 含 `duplicate_context` 或 `context_bloat`（多样本轨迹时）。

## P1（需 OpenHands + 子集）

1. 复制 `artifacts/run-manifest.example.json` → `artifacts/run-manifest.json` 并填写 commit/model。
2. 按 `artifacts/swe-subset-30.json` 跑 C0/C1/C2。
3. 导出 JSONL 到 `artifacts/openhands-traces/`（已 gitignore）。
4. `OPENHANDS_TRACE_DIR=artifacts/openhands-traces npm run bench:openhands`
5. `npm run openhands:aggregate` → `artifacts/openhands-metrics.csv` + `artifacts/figures/pareto-saved-vs-success.svg`
6. `npm run openhands:p1:evaluate`（§2.2 Go/Kill；见 [`openhands-token-budget.md`](./openhands-token-budget.md)）

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `OPENHANDS_TRACE_DIR` | `scripts/fixtures` | `*.jsonl` 轨迹目录 |
| `BENCH_MODE` | `fast` | 传给 `/api/v1/optimize` |
| `BENCH_GATE_MAX_P95_MS` | `2000` | OpenHands 专用 gate |
| `BENCH_GATE_MIN_PATTERN_HIT_RATE` | `0` | P1 可设 `0.4` |