18trees-benchmark-pages-skill

项目是什么

18trees-benchmark-pages-skill 把一份 benchmark 的实验数据、一篇写好的论文和一份分析报告，渲染成能直接托管在 GitHub Pages 上的主页与排行榜：主页负责讲清楚这个 benchmark 是什么，榜单页负责让人横向比较模型。

它处理的是一件被反复重做的问题。做 benchmark 的人都在 fork 同一个学术主页模板，然后手搓自家特有的部分——表格怎么从实验结果生成、模型更新了榜单怎么改、别人怎么把自己的结果加进来。那个模板一样都没有，于是每个团队都把同样的问题重新解一遍。这个 skill 把这些部分做完了。

它的边界写得很清楚：不做评测、不做数据分析、也不做视觉设计，只消费已经完成的分析产物；缺数据就报错让人补齐，不插值、不估算。因此它需要能读写文件、能执行命令的环境——Claude Code、Codex，或任何能执行命令的 agent；网页版聊天机器人跑不了，那种情况下模型只能凭印象编一个 HTML，而它存在的理由恰恰是页面里每个数字都能从 CSV 重算。

具体结构

整个项目分成四层，输入来自外部，其余三层都在仓库里。

输入层。 三样东西：原始评测数据（experiments/<run>/*.jsonl 与 canonical 逐题宽表）、论文（标题、作者、摘要与 BibTeX）、分析报告（REPORT.md 与 figures/ 里的图）。其中逐题宽表最关键——一行一道题、一列一个模型，有了它，榜单上每个数字都能重算。图里论文与分析报告合画在一个框内，因为它们同属叙事来源。

规则层。 skills/benchmark-pages/SKILL.md 是规则的唯一真相，references/ 下的四份规范分别管输入契约、榜单列规范、站点字段和部署与提交。规则把工作固定成六个阶段：盘点输入、锁定评测口径、造三张表、写 site.yaml、渲染并自检、本地验证与部署。

源目录与生成层。 site.yaml 是整站唯一需要手写的文件；data/leaderboard.csv 一行一个参赛者，data/breakdown_*.csv 按维度拆表，data/items.csv 是可选的逐题明细，data/metrics.md 写评测口径。scripts/build_site.py 读这个源目录，配上 assets/template/ 的版面与随仓库分发的 Tabulator 表格引擎，渲染出 _site/（index.html、leaderboard.html 与 static/）。整条链路只有一个 Python 依赖。

交付层。 生成出的静态站直接推到 GitHub Pages。仓库里的 site/ 就是一份真实样例：6 个模型、2492 道四选一题，由 .github/workflows/pages.yml 在数据变动时自动重建；那一页上的排行榜不是截图。

优秀设计

数字不许手写进 HTML。 页面上每一个数字都来自 data/*.csv，经 build_site.py 渲染；想改数字就改 CSV 再重跑。这条管的是机制不是内容——它不校数据对不对，只保证页面由数据生成、随时可以重算。

结构问题挡住，数据问题只提示。 缺列、引用的文件不存在这类「页面渲染不出来」的问题让构建非零退出，不产出半成品；correct / n 与主指标对不上、各参赛者分母不一致这类可信度问题只打印警告，页面照常产出，需要收紧时自己加 --strict。

上游回链是硬校验。 版面模板派生自 Academic Project Page Template 与 Nerfies（均为 CC BY-SA 4.0），生成器用 REQUIRED_BACKLINKS 检查每个产出站点的 footer 是否保留回链，且不提供关闭开关——许可义务写进代码，而不是留给自觉。

一个开关一个分区。 排序筛选、分维度热力图、置信区间、随机基线锚点、评测口径脚注、结果提交指引，都在 site.yaml 里按需开启，没配的整段不出现，不会留下空框。热力图的色阶按列独立归一化，因为跨列的题目难度不同。

生成器跑通不等于页面能用。 仓库把「在浏览器里逐页点一遍」写成硬要求：表格渲染出来、点表头能排序、窄屏不横向溢出、模型列在最左且可见。改过模板或生成器之后必须做这一步。

解决了什么问题

• 页面上的数字不再手工抄进 HTML：改 CSV、重跑一次，页面跟着变，并且始终和 CSV 一致。
• 加一个模型是加一行 CSV，不用改 HTML，也不会出现「表格改了、图表没跟上」。
• 榜单自带排序筛选、分维度热力图、置信区间、随机基线锚点、评测口径脚注与结果提交指引，不用自己写一遍。
• 「75.6% 算好还是差」有答案——随机基线锚点把 25.0% 和最佳成绩放在一起看；「invalid 怎么算的」也有答案，口径从 data/metrics.md 直出到页面脚注。
• 生成的站点自包含：只有一个 Python 依赖，表格引擎随站分发，离线可打开，不依赖任何 CDN。
• 结构性问题在构建阶段就被挡下，不会产出半成品页面；仓库自己的 workflow 就是这么用的。