# Frontier Model Bench

一个面向个人主页的静态模型评测信息站：把模型卡、论文和 benchmark 榜单里的分数收进可追溯的数据层，并用两种视图呈现模型能力与完整系统运行。

> 当前仓库是 **curated snapshot / static MVP**。目录可以比成绩覆盖更多模型；`catalog-only` 条目会在默认公开覆盖视图中保留为无分数行，不会被当作有成绩的模型。页面不会把不同 benchmark、harness 或协议偷偷合成一个总分。

## 本地运行

```bash
python3 -m http.server 8765
# 打开 http://127.0.0.1:8765/
```

直接双击 `index.html` 会被浏览器的跨域策略阻止读取 JSON；请使用一个本地静态服务器。

## 页面和目录

```text
index.html / styles.css / app.js                 # Evaluations / Matrix + System Runs
benchmarks.html / benchmarks.css / benchmarks.js # benchmark 目录与逐项 profile
models.html / models.css / models.js             # model / config entry 目录与逐项 profile
data/catalog/               # models / model_profiles / benchmarks / sources / harnesses / presets 注册表
data/observations/results.jsonl # 追加式 canonical observation 长表
data/derived/site.json      # 由脚本生成，供静态前端读取
data/derived/public.json    # 公开榜单披露层索引（当前 union 快照 6,461 条已映射行）
data/public/evidence.jsonl  # 全量已映射公开证据长表（未复现，含来源定位）
data/public/unmapped.jsonl  # 14,766 条未安全映射行（本地维护 artifact，gitignored）
data/public/alternatives.jsonl # 超过页面限额的已映射行（本地默认 max=0 全量，故为空）
data/models.json            # 旧 seed 兼容回退（逐步迁移中）
docs/data-contract.md       # 长表 observation 与证据契约
docs/model-catalog.md       # 模型身份、版本、endpoint 与淘汰规则
docs/presets.md             # 比较维度/预设的配置说明
scripts/build_derived.py    # catalog + observations → site index
scripts/validate_data.py    # 只依赖 Python 标准库的数据检查器
scripts/maintenance_report.py # 只读健康检查与缺失/刷新候选
scripts/fetch.py            # 公开 leaderboard adapter → candidate artifact
scripts/review_candidates.py # candidate artifact → 可审阅 Markdown/JSON（不晋升）
skills/frontier-model-bench-maintenance/ # 可复用维护 skill
.github/workflows/validate.yml
.github/workflows/pages.yml      # GitHub Pages build/deploy
.github/workflows/maintenance.yml # 定时 source health + candidate artifact
```

根目录的三套页面资源是有意保留的 GitHub Pages 相对路径契约，不要只为外观整齐而把
HTML、CSS 或 JS 单独搬进子目录。本地缓存和维护产物不属于发布源码：Ruff/Python 缓存、
`artifacts/fetch/`、`artifacts/maintenance/`、`artifacts/review/` 均被忽略，可以在对应
任务结束后删除；`data/public/unmapped.jsonl` 虽然也被忽略，但它保存当前来源快照中
尚未安全映射的完整证据队列，活跃审阅期间应保留，完成后再交给 Actions artifact 的
retention 管理。

站点有三个并列入口：`Evaluations` 看模型 / system 的成绩，`Benchmarks` 先解释每把“尺子”，`Models` 先解释每个 release 的身份与能力边界。三个页面共享同一份 `site.json`，目录页不会复制或另行维护分数。

数据层的形态是：

```text
source snapshots → canonical observations → derived indexes → static UI
```

新增来源时，优先增加独立 adapter 和来源快照，不在前端写爬虫；新增 benchmark 时，先登记版本、指标和可比性说明。完整字段约定见 [`docs/data-contract.md`](docs/data-contract.md)。

## 两种比较主体

- **Model Atlas**：每行一个 model release/config。适合 GPQA、MMLU-Pro、AIME、MMMU、LiveCodeBench 等直接评测；单元格仍显示 shots、effort、tools、evidence 与可比性。若某列只有 system 结果，矩阵只显示可跳转的 run 数量，不把 system 分数提升成裸模型分数；harness 间比较以 System Runs 为准。
- **System Runs**：每行一个精确的 `model × endpoint × harness × protocol × benchmark version`。SWE-bench、Terminal-Bench、BFCL、τ-bench、OSWorld 等必须在这个视图中比较；不跨 harness 取最高值或平均值。

页面默认还会叠加一个 **Public reported** 层：公开 leaderboard、模型卡和 provider
披露的数字会直接进入矩阵，并显示 `披露 · 未复现`。这不是本站执行的结果，也不改变
canonical 排名；点击单元格或公开披露索引，可以查看来源 URL、榜单行定位、抓取时间、
快照 hash、harness/protocol 和原始 JSON。未安全映射的来源原名不猜测成 canonical
release，而保留在维护 artifact/`unmapped.jsonl` 中供后验处理。

预设由 `data/catalog/presets.json` 驱动，可切换 Frontier、Flash/Fast、小模型、数学、代码 Agent、工具、多模态、长上下文、中文/多语、开放权重、可靠性和参数规模等比较维度。默认 `public-coverage` 预设会把目录与公开报告的覆盖地图一起展示；窄预设仍可隐藏 `catalog-only`，缺失始终表示 `—`，不是 0。

## 更新数据

1. 在 catalog 中登记具体 release、endpoint、benchmark version 和 source；不要把 alias、reasoning effort 或速度 variant 当作新模型。
2. 在 `data/observations/results.jsonl` 追加一条事实：分数必须同时带 protocol、harness（如适用）、observed date、evidence 和 comparability。旧事实不覆盖，修订用新 observation 标 superseded/retracted。
3. 生成索引并运行校验：

   ```bash
   python3 scripts/build_derived.py
   python3 scripts/validate_data.py
   python3 scripts/validate_data.py --strict  # 发布前把迁移 warning 也视为失败
   ```

4. 打开页面，检查矩阵横向滚动、筛选、详情抽屉、来源链接和缺失值语义，再提交一个小 PR。

GitHub Actions 会在涉及 `data/`、`scripts/` 或 schema 的 push/PR 上先重建 `site.json` 再校验；Pages 发布同样只上传通过校验的静态产物。公开层可以先展示来源报告值，人工审阅后才追加到 canonical observations；两层都保留来源与状态，避免把“未复现”误读为“未测试”或“已证实”。

### 定期维护

`maintenance.yml` 每天 UTC 02:17 生成只读维护报告，并运行已注册的公开 leaderboard adapters；不会修改 approved 数据。报告作为 Actions artifact 保留 30 天，包含覆盖率、过期来源、缺失/刷新候选、来源探测和 adapter candidates。手动运行或本地预览：

```bash
python3 scripts/maintenance_report.py --root . --output-dir /tmp/fmb-maintenance --check-sources
# 可选：运行已注册公开来源 adapter（只写 candidate artifact）
python3 scripts/fetch.py check --dry-run --root . --output-dir /tmp/fmb-fetch
# 可选：从候选 artifact 重建公开披露层（仍不修改 approved observations）
python3 scripts/build_public_evidence.py --root . --input-dir /tmp/fmb-fetch \
  --output data/derived/public.json --jsonl-output data/public/evidence.jsonl \
  --unmapped-output data/public/unmapped.jsonl \
  --unmapped-summary-output data/public/unmapped-summary.json \
  --alternatives-output data/public/alternatives.jsonl \
  --max-per-key 0
python3 scripts/build_derived.py
# 可选：整理候选为去重/分级审阅包，不修改 approved 数据
python3 scripts/review_candidates.py --root . --input-dir /tmp/fmb-fetch \
  --output-dir /tmp/fmb-review --limit 50
# Arena 人工分批扩展；定时任务默认只取 core subset 的一页
python3 scripts/fetch.py check --sources lmarena-hf-dataset \
  --arena-configs text,text_style_control --arena-max-rows 500 \
  --output-dir /tmp/fmb-arena-refresh
```

候选中的数值行可以先由 `build_public_evidence.py` 放入公开披露层；只有经过来源定位、model/benchmark/version/protocol/evidence 审阅后，才通过 PR 追加到 `data/observations/results.jsonl`。详见 [`docs/maintenance-plan.md`](docs/maintenance-plan.md) 和 [data candidate issue template](.github/ISSUE_TEMPLATE/data-candidate.md)。

目前已接入 Hugging Face leaderboard API、SWE-bench 官方 JSON、LiveBench dated release、Stanford HELM artifacts、Arena 官方 Hugging Face leaderboard dataset、BFCL V4 官方 CSV、Agents' Last Exam（ALE-V1）公开 JSON、Aider Polyglot 官方 YAML、MLE-bench README，以及 Epoch AI Benchmarking Hub 下载快照；`scripts/fetch.py list` 会显示完整清单。BFCL 会保留 native FC / Prompt、固定 evaluator commit、成本、延迟和分类子指标；ALE 会按 `model × source harness × effort variant × split` 生成两项指标（Pass Rate / partial Score），二者都只进入候选审阅，不会伪装成未经协议说明的 model-only 分数。LMArena 互动页面仍只登记为 metadata-only，不抓取未文档化接口；`lmarena-hf-dataset` 只读取官方发布的版本化 dataset rows 并生成候选。SakanaAI 的 ALE-Bench 是独立的 algorithm-engineering benchmark，目前只登记 catalog，不与 Agents' Last Exam 合并。维护步骤也封装在仓库内的 [`frontier-model-bench-maintenance` skill](skills/frontier-model-bench-maintenance/SKILL.md)，便于在其他 Codex 环境复用。

## 设计边界

- 不默认计算跨 benchmark 的“总分”；accuracy、pass@1、Elo 和 agent resolve rate 不能混为一个排名。
- 记录 benchmark version、prompt/tools/reasoning effort、harness/scaffold 和 observed date；SWE-bench 等 agent benchmark 的成绩属于“模型 + scaffold + harness”系统。
- `reported / reproduced / verified` 与 `exact / conditional / none` 分开表达证据等级和可比性。
- source 失效或数据过期时保留旧 observation，并显示 stale/conflict，而不是悄悄删除。

## 发布到 GitHub Pages

这是纯静态目录，不需要 Node 或数据库。当前仓库已配置 GitHub Pages workflow；推送 `main` 会先校验数据，再发布静态产物。也可以把整个目录作为个人主页的 `static/benchmarks/` 构建产物，或仅在主页增加外链。

推荐仓库名：`OptHuang/frontier-model-bench`。个人主页仓库保持独立，避免网站内容和数据抓取权限相互耦合。