Agent+模型 评测榜单网站：详细设计

Agent+模型 评测榜单网站：详细设计

本文档设计一个类似 arena.ai/leaderboard 的榜单网站，但评测对象是 Agent 框架 × 模型 × 配置 的组合（如 Claude Code + DeepSeek V4 Flash），分数来自自动化任务评测，而不是人类投票。

1. 目标与范围

目标

• 展示各「Agent+模型」组合在不同任务类别上的得分、成本、耗时、稳定性，并给出排名。
• 支持下钻：从榜单到条目详情，再到单个任务的完整运行轨迹，结果可追溯、可复现。
• 支持内部持续评测：新模型或新 Agent 版本接入后自动跑评测、自动更新榜单。

非目标（首版不做）

• 人类盲测投票与 Elo 排名（后续可作为开放题的补充信号）。
• 面向公众的在线对话或试用功能。
• 多租户开放提交（首版仅内部提交，见第 10 节）。

2. 参考站点分析

从 arena.ai 榜单首页可以看到几个值得借鉴的设计：

• 顶部分类导航：Overview、Agent、Chat、Code、Image、Video，每个分类下还有子榜单（如 WebDev、Search、Document）。
• 概览页是多个模块的聚合：Top 10 榜单、实时 Agent 会话（显示正在运行的模型和当前动作，如 Writing a file、Running bash）、Pareto 前沿、新发布模型排名、博客与更新日志。
• Agent 榜单直接用百分比得分，并在模型名后标注推理强度（如 Max、High），说明「同一模型的不同配置」是独立条目。
• Pareto 前沿：横轴成本（美元/任务），纵轴得分，列出非被支配的条目。这对选型最有价值。
• 透明性内容：How It Works、Leaderboard Changelog，说明方法论和每次榜单变动。
• 其官方博客有专门讨论 Harness 对编码 Agent 影响的文章，侧面印证：把 Harness 作为一等公民放进榜单是合理的。

我们的取舍：保留「分类导航 + 概览聚合 + Pareto + 更新日志」的骨架，把「投票」换成「自动评测运行」，把「实时会话」换成「实时评测运行队列」。

3. 信息架构

/                       概览（Overview）
/leaderboard/:category  分类榜单（overall、coding、terminal、tool-use、enterprise、safety、...）
/entries/:id            条目详情（一个 Agent+模型+配置 的组合）
/compare?a=&b=          两个条目对比
/pareto                 成本-得分 Pareto 前沿
/tasks                  任务浏览（任务库、难度、通过率分布）
/tasks/:id              任务详情（描述、判分方式、各条目在此任务上的表现）
/runs/:id               单次运行详情与轨迹回放
/live                   实时评测队列与进度
/methodology            评测方法、评分公式、已知局限
/changelog              榜单变更日志
/admin/*                管理后台（内部）

4. 页面设计

4.1 概览页

• Top 10 卡片：当前总榜前 10，显示排名、Agent、模型、得分、成本。右上角可切换分类（Best Overall、Best Coding 等）。
• 实时评测：最近运行的若干条，显示条目、任务、状态（排队、运行中、完成、失败）和当前动作。
• Pareto 迷你图：成本-得分散点图加前沿线，点击进入 /pareto。
• 新上榜：最近新增条目及其首次排名。
• 更新日志摘要：最近几次榜单变化。

4.2 分类榜单页（核心页面）

表格列：

列	说明
排名	带置信区间的排名（见 6.3），并列时显示相同名次
Agent	Harness 名称与版本
模型	模型名、版本、推理强度等配置
得分	当前类别加权得分（百分比），带 ±置信区间
稳定性	pass^k 或多次运行方差
成本	平均每任务美元成本
耗时	平均每任务墙钟时间
任务数 / 运行数	样本量，样本不足时置灰并加提示
更新时间	最近一次完整评测时间

交互：

• 筛选：Agent、模型厂商、开源/闭源、是否含已弃用版本、成本区间。
• 排序：任意数值列。
• 视图切换：能力榜、性价比榜、速度榜、稳定性榜（同一张表的不同默认排序和附加列）。
• 行展开：显示各子维度得分的迷你条形图。
• 样本量不足的条目默认折叠在「暂定」分组，避免误导。

4.3 条目详情页

• 头部：Agent、模型、配置、首次上榜时间、当前各类别排名。
• 雷达图：各能力维度得分，可叠加另一个条目对比。
• 成本-耗时-得分三个指标的历史趋势（随评测批次）。
• 任务级结果表：每个任务的通过率、平均成本、失败原因分布，可按维度和难度过滤。
• 失败归因饼图：模型能力、Harness 问题、环境问题、超时预算。
• 版本沿革：同一 Agent 或同一模型的不同版本对比链接。

4.4 运行详情与轨迹回放

• 时间线视图：每一步的思考摘要、工具调用、参数、返回结果、文件 diff、耗时、token。
• 顶部摘要：最终判分结果、检查点明细、失败归因、总成本。
• 文件变更视图：任务结束时与初始状态的 diff，禁区文件被改动会高亮。
• 支持按步骤搜索、折叠长输出、下载原始轨迹 JSON。

4.5 Pareto 页

• 散点图：横轴成本（对数轴可选），纵轴得分，点大小可映射耗时。
• 前沿线与前沿列表：列出所有非被支配条目。
• 可按类别、Agent、开源/闭源筛选，并支持设置成本上限查看「预算内最佳」。

4.6 其他页面

• 对比页：并排展示两个条目的各维度得分、成本、同任务结果差异；差异最大的任务置顶，便于分析原因。
• 任务浏览：展示任务库规模、各类别难度分布、每个任务的平均通过率；隐藏集任务只显示聚合统计，不显示内容。
• 方法论页：评分公式、重复次数、置信区间算法、失败归因规则、版本锁定策略、已知局限。
• 更新日志：每次榜单变更的时间、原因（新增条目、任务集更新、判分修复）、影响范围。

5. 系统架构

┌──────────────┐   提交评测请求    ┌──────────────┐
│ 管理后台/CLI │ ───────────────▶ │  API 服务    │
└──────────────┘                  │ (FastAPI)    │
                                  └──────┬───────┘
                                         │ 入队
                                  ┌──────▼───────┐
                                  │ 任务队列     │
                                  │ (Redis/Temporal)│
                                  └──────┬───────┘
                                         │
                      ┌──────────────────▼──────────────────┐
                      │ Runner 集群（Docker/K8s 沙箱）      │
                      │  Harness 适配器 → 模型网关(LiteLLM) │
                      │  环境镜像 / Mock 服务 / 判分脚本     │
                      └──────┬───────────────────┬──────────┘
                             │ 轨迹/产物         │ 结果
                      ┌──────▼──────┐     ┌──────▼──────┐
                      │ 对象存储    │     │ PostgreSQL  │
                      │ (S3/MinIO)  │     │             │
                      └─────────────┘     └──────┬──────┘
                                                 │ 聚合作业
                                          ┌──────▼──────┐
                                          │ 榜单快照表  │
                                          └──────┬──────┘
                                                 │
                                          ┌──────▼──────┐
                                          │ Web 前端    │
                                          │ (Next.js)   │
                                          └─────────────┘

关键设计原则

• 原始结果与榜单快照分离：Runner 只写原始运行记录；聚合作业读取原始记录，生成不可变的榜单快照。网页只读快照，保证榜单可回溯、不因后台重算而抖动。
• 模型网关统一计量：所有 Agent 的模型请求经过网关，由网关统一记录 token、成本、延迟和完整请求响应，不依赖各 Agent 自带日志。
• 沙箱隔离：每次运行使用全新容器，限制网络，只开放网关和 Mock 服务的地址。
• 判分与执行解耦：Agent 运行结束后，在独立容器里用原始测试文件覆盖并执行判分，防止 Agent 改测试作弊。

6. 评分与排名

6.1 评分口径

• 单次运行得分 s ∈ 0, 1：测试全过为 1，部分检查点通过按比例给分，超时或超预算为 0 并标记原因。
• 条目在某任务上的得分：该任务 k 次运行（默认 3～5 次）的均值。
• 维度得分：该维度任务得分的加权均值，权重按难度设定。
• 类别总分：各维度得分按配置权重加权，权重放在版本化配置中，变更会写入更新日志。
• 稳定性：pass^k，即 k 次运行全部通过的任务比例；另报告任务得分的标准差。

6.2 成本与耗时

• 成本：网关记录的 token 乘以单价，按每次评测批次的价格快照计算，价格变化不回溯改历史。
• 耗时：从容器启动 Agent 到判分前的墙钟时间，不含镜像拉取和判分。

6.3 排名与置信区间

• 对每个条目，按任务做自助法（bootstrap）重采样，得到类别总分的 95% 置信区间。
• 排名规则：条目的名次 = 1 + 置信区间下界高于该条目上界的条目数。区间重叠的条目名次并列，避免把噪声当成差异。
• 样本量门槛：任务数或运行数低于阈值的条目标记为「暂定」，不参与名次计算，只在暂定分组展示。

6.4 Pareto 前沿

• 以（成本，得分）为二维点，条目 A 支配 B 当且仅当 A 成本不高于 B、得分不低于 B，且至少一项严格更优。
• 前沿 = 所有不被任何条目支配的条目；按成本升序排列即得到前沿线。
• 为避免噪声，可选用得分置信区间下界做保守版前沿。

6.5 综合性价比（可选）

使用 TOPSIS：指标为得分（越大越好）、成本（越小越好）、耗时（越小越好）、稳定性（越大越好），按配置权重做加权归一化，计算与理想解的相对接近度，作为「综合榜」排序依据。权重和方法写入方法论页。

7. 数据模型

核心表（PostgreSQL）：

表	关键字段	说明
harnesses	id, name, version, adapter_ref	Agent 框架及版本
models	id, provider, name, version, endpoint, open_source	模型及端点
entries	id, harness_id, model_id, config_json, config_hash, status, first_seen_at	榜单条目，config_hash 由全部会影响结果的变量计算
tasks	id, category, dimension, difficulty, weight, spec_ref, visibility(public/hidden), version	任务元数据，spec_ref 指向任务目录
task_sets	id, name, task_ids, version	评测任务集版本
eval_batches	id, entry_id, task_set_id, price_snapshot, started_at, finished_at, status	一次完整评测批次
runs	id, batch_id, task_id, attempt, score, checkpoints_json, status, failure_class, cost_usd, tokens_in, tokens_out, duration_s, steps, trajectory_uri	单次运行
judgments	id, run_id, judge_model, rubric_version, scores_json, human_checked	LLM 评审记录（仅开放题）
snapshots	id, created_at, task_set_id, config_version, reason	一次榜单快照
snapshot_rows	snapshot_id, entry_id, category, score, ci_low, ci_high, rank, stability, cost, duration, n_tasks, n_runs	快照中的每行数据，网页直接读取
changelog	id, snapshot_id, kind, description, created_at	榜单变更日志

要点：

• entries 以 config_hash 去重，任何变量变化都产生新条目。
• runs 只追加，不修改；重判分产生新的 run 记录并标记 supersedes。
• 轨迹（几十 KB 到几 MB）放对象存储，数据库只存 URI 和摘要字段。
• failure_class 取值：model、harness、env、timeout、budget、judge_error，用于失败归因统计。

8. API 设计

REST + JSON，前端通过 Next.js 服务端渲染调用，榜单类接口可加缓存。

接口	说明
GET /api/leaderboard?category=&snapshot=&agent=&vendor=&sort=	榜单表格数据，默认最新快照
GET /api/entries/:id	条目详情与各维度得分
GET /api/entries/:id/tasks	条目在各任务上的结果汇总
GET /api/compare?a=&b=	两个条目对比数据
GET /api/pareto?category=	散点数据与前沿列表
GET /api/tasks, /api/tasks/:id	任务浏览（隐藏任务只返回聚合统计）
GET /api/runs/:id	运行摘要；/api/runs/:id/trajectory 分页返回轨迹
GET /api/live	当前队列与运行中的任务（SSE 或轮询）
GET /api/changelog	变更日志
POST /api/admin/batches	提交评测批次（管理员）
POST /api/admin/snapshots	触发聚合并生成快照（管理员）

约定：所有榜单接口都可带 snapshot 参数查看历史快照；响应附带 snapshot_id、生成时间和任务集版本，便于前端展示「数据截至」。

9. 前端设计

• 技术栈：Next.js（App Router）+ TypeScript；表格用 TanStack Table；图表用 ECharts（散点、雷达、趋势都能覆盖）；样式用 Tailwind；国际化支持中英文。
• 渲染策略：榜单页服务端渲染并缓存，筛选和排序在客户端完成；轨迹回放页按需分页加载，长输出虚拟滚动。
• 组件：LeaderboardTable、RankBadge（带置信区间提示）、CostScoreScatter、RadarChart、RunTimeline、DiffViewer、CategoryTabs、FilterBar、LiveRunList。
• 体验细节 ：
  • 条目名称统一显示为「Agent · 模型 (配置)」，如 Claude Code · DeepSeek V4 Flash (Max)。
  • 得分旁显示 ± 区间，鼠标悬浮显示样本量与评测批次时间。
  • 暂定条目用虚线边框或置灰，并带说明提示。
  • 支持深色模式、移动端表格横向滚动并固定前两列。
  • 所有图表支持导出 PNG 和 CSV。

10. 后端与评测流水线

10.1 评测批次流程

1. 管理员在后台选择条目与任务集，或由新模型/新 Agent 版本触发。
2. API 创建 eval_batch，把「条目 × 任务 × 重复次数」展开成运行作业入队。
3. Runner 取作业：拉取环境镜像，启动沙箱，注入 Harness 与网关配置，运行 Agent。
4. 运行结束后在独立容器判分，写入 runs；轨迹与产物上传对象存储。
5. 批次完成后，聚合作业计算各类别得分、置信区间、排名、Pareto，写入新快照并追加更新日志。
6. 快照经管理员审核后设为「已发布」，前端才可见。

10.2 Harness 适配器

• 统一接口：run(task, model_config, limits) 返回运行结果与轨迹。
• 每个 Agent 一个适配器，使用其无头或非交互模式；适配器负责配置环境变量、工作目录、工具权限和超时。
• 适配器自身有版本，并计入 config_hash，适配器修复也会产生新条目，避免新旧数据混用。

10.3 失败处理

• 基础设施失败（镜像拉取、网关超时、容器崩溃）自动重试，最多 2 次，不计入模型得分。
• 超时、超步数、超预算：按失败计分并标记 failure_class。
• 失败归因：先按规则分类（如容器退出码、网关错误、判分脚本异常），无法确定的进入人工复核队列。

10.4 防作弊与可信度

• 测试文件和判分脚本放在 Agent 不可写的位置，判分时用原始文件覆盖。
• 检查补丁 diff 是否触碰禁区文件、是否出现硬编码测试答案、是否删除失败用例。
• 任务分「公开」与「隐藏」两组：隐藏集不展示内容，只用于定期复测，对比公开集得分以发现过拟合。
• 新任务上线前用标准解与空解各跑一遍，确认前者满分、后者零分。

11. 权限、安全与运维

• 角色：访客（只读榜单，若部署在内网可走公司 SSO）、评测工程师（提交批次、管理任务）、管理员（发布快照、修改权重、管理用户）。
• 审计：所有发布、权重变更、任务集变更写入审计日志。
• 密钥管理：模型 API Key 只存放在网关，Runner 与 Agent 沙箱拿不到真实密钥，只持有网关颁发的短期令牌，并带预算上限。
• 沙箱安全：禁止访问内网和公网（白名单除外），限制 CPU、内存、磁盘和运行时长。
• 可观测性：Runner 与网关输出指标（队列长度、成功率、平均耗时、成本），接入监控和告警；批次预算超限自动暂停。
• 备份：数据库每日备份，对象存储开启版本和生命周期策略，旧轨迹可转冷存储。

12. 非功能需求

项目	目标
榜单页首屏	缓存命中下 1 秒内
轨迹页加载	首屏 2 秒内，长轨迹分页加载
评测吞吐	以并发 Runner 数线性扩展，单批次可暂停与恢复
可复现性	任何榜单行都能追溯到批次、运行、轨迹和判分脚本版本
数据保留	原始运行记录永久保留，轨迹至少保留 12 个月

13. 里程碑

阶段	内容	产出
M1（约 2 周）	数据模型、网关、Runner 最小可用、跑通一个 Harness 和 2～3 个模型；总榜表格页、条目详情页	可展示的首版榜单
M2（约 2～3 周）	轨迹回放、分类榜单、Pareto、对比页、聚合作业与置信区间、更新日志	可日常使用的内部榜单
M3	任务浏览、隐藏集复测、失败归因统计、管理后台、审核发布流程	可审计、可运营
M4	新版本自动触发回归评测、历史趋势、开放题的 LLM 评审与人工校准、开放外部提交	持续运行的评测平台

14. 主要风险与对策

风险	对策
评测成本过高（长任务、多次重复、多条目）	分层评测：先小集冒烟，再全量；预算上限与自动暂停；按价格快照核算
任务或判分脚本有缺陷导致误判	标准解与空解校验；失败归因与人工抽检；发现问题后重判分并写入更新日志
排名波动被误读为能力差异	展示置信区间，区间重叠并列，样本不足的条目标暂定
过拟合榜单	隐藏集复测、公开任务定期轮换、方法论页明确局限
Harness 或模型版本漂移导致历史不可比	config_hash 锁定全部变量，变化即新条目，不覆盖旧数据
外部模型 API 不稳定	网关层重试与限流，基础设施失败不计入得分

15. 待确认事项

• 榜单只对内部使用，还是计划对外公开？这决定认证方式、隐藏集策略和合规要求。
• 首批要接入的 Agent 与模型清单，以及任务类别的优先级。
• 模型成本口径：按官方定价、公司内部结算价，还是自托管的折算成本。
• 是否需要人类偏好投票作为补充信号，以及开放题的评审方式。