Skip to main content
为 Benchmark 编写用户指南,让用户无需阅读源码,就能完成环境准备、运行评测并理解结果。 新增或修改 Benchmark 时,同步维护以下中英文页面:
页面归属、本地化、导航和公开内容边界遵循文档贡献指南。本页规定 Benchmark 页面应包含的内容,以及“运行示例”和“评测结果”的写法。

必要内容

按用户从了解任务到解读成绩的顺序组织页面,覆盖以下内容:
  • 评测对象与来源:评测目的、官方资源、固定的数据集和评测器版本、任务数量与划分,以及适用的任务浏览器、许可证和访问权限要求。
  • 准备与兼容性:前置依赖、任务镜像、凭证、推荐及其他兼容 Harness、支持的 Environment,并说明 Recipe 会自动推断的镜像、工作区、资源和网络设置。
  • Benchmark 参数:专属参数的含义、类型、默认值、有效值和选择建议。
  • 运行示例:按下文统一模板提供冒烟测试、自定义参数和完整评测命令。
  • 评测结果:按下文章节规范解释指标、单题评分依据和产物。
  • 限制与对齐:已知兼容性约束、与官方评测流程的重要差异及其影响。
字段、默认值、命令和评分行为都须对照当前实现核实。说明推荐 Harness 的依据,区分上游官方推荐与 AgentCompass 提供的集成建议。

保持页面聚焦 Benchmark

通用规则通过链接引用,Benchmark 页面只展开自身的差异:
  • 共享参数链接到 Benchmark 共享字段;专属参数表不收录 k、尝试策略或 Model 位置参数。
  • CLI 参数归属和配置覆盖规则链接到运行参数参考。
  • Harness 安装、步骤与成本限制、命令超时和 Model 接入方式链接到对应 Harness 页面;本页只说明该 Benchmark 所需的额外配置。
  • 多次尝试、公共结果结构和聚合规则按评测结果章节提供索引,避免在多个小节重复解释。

运行示例章节

统一使用“运行示例”标题,按“命令说明 → 三个场景选项卡 → 其他可选 Harness”的顺序组织。

命令说明与 Harness 选择

先说明 agentcompass run 的三个位置参数依次为 Benchmark、Harness 和 Model,并给出本页使用的组件及必要的凭证、环境准备说明。共同的环境变量设置放在选项卡之前。 需要区分多种 Harness 时,将主要运行路径放在“推荐 Harness”小节中,再提供下面的三个场景选项卡。只有一种运行路径时,可以直接展示选项卡,不增加多余层级。

三个场景选项卡

使用 <Tabs> 和 <Tab>,保持以下标题和顺序: 每个选项卡先用一小段说明用途和任务范围,再给出完整命令。用户完成共同的前置设置后,应能单独复制任一选项卡中的命令运行,无需拼接其他选项卡的片段。 存在其他兼容 Harness 时,在这组选项卡之后增加“其他可选 Harness”小节,说明适用场景和配置差异,并为每个 Harness 提供完整评测命令。可以按 Harness 分组选项卡,避免混入前面的三个场景。

命令内容与排版

命令只显式设置必要项和本示例要演示的覆盖项。默认值已满足需求时省略对应参数;只有需要展示多次尝试时,才加入 k 和尝试策略。凭证及 Model 接入配置通过环境变量引用,避免在各示例中重复填写。 以下排版规则适用于用户指南中所有 Benchmark 页面,包括概览页、各选项卡及其他章节中的参数片段:
  • CLI 选项逐行排列:用行尾反斜杠(\)续行,末行不加;反斜杠后不得有空格。
  • JSON 字段逐行缩进:每个字段独立一行,嵌套对象展开;保留包裹整个 JSON 参数的引号,不在 JSON 内添加 shell 续行符。
  • 编译后自动折行:Bash 和 JSON 代码块启用 Mintlify 的 wrap,代码围栏分别写为 ```bash wrap 和 ```json wrap。长字符串由页面自动折行,不为排版改变参数值。

评测结果章节

统一使用“评测结果”标题。修改已发布页面的标题或小节时,保留旧锚点以兼容已有链接。 章节开头链接到运行目录、汇总成绩和单题文件与公共字段,正文固定包含两个小节:
  • 评分指标:说明主指标和辅助指标的含义、二元或标量类型、取值范围或单位、分数方向,以及默认成绩如何解读。只展开 Benchmark 专属的聚合、分母或评分异常规则;通用规则链接到指标与聚合。
  • 单题结果与评分依据:说明每次尝试中专属评分记录、证据和产物的字段位置与含义,以及影响结果核查但不会保存的内容。公共目录结构、文件名和状态字段由通用文档说明。
评分机制已在前文解释时,用锚点引用。不要另设“计分注意事项”重复公共状态、异常或 pass@k、avg@k 定义;影响成绩解读的特殊规则归入“评分指标”,排查所需的字段归入“单题结果与评分依据”。区分诊断字段与汇总指标、逻辑结果对象与落盘文件结构。 可以参考 BrowseComp;包含多级计分和特殊分母时,参考 SciCode。

预览与验证

完成内容修改后,按以下顺序检查:
  1. 核对内容:命令、参数和评分说明与实现一致;三个场景职责清楚,完整评测未遗留冒烟筛选,通用说明通过链接引用。
  2. 检查页面:中英文路径与内容同步,导航、引用和旧锚点有效;新增、移动或删除页面时更新 docs/docs.json 及必要的重定向。
  3. 预览渲染:运行 mint dev,检查桌面与窄屏上的选项卡、表格和代码块,尤其是 --harness-params 的长字符串。确认页面实际折行,复制内容仍保留原始命令;不能仅凭 MDX 源码中的换行判断显示效果。
  4. 执行校验:从文档根目录运行链接和构建检查,修复发现的问题。
文档校验不代替真实评测。冒烟测试、完整评测与官方结果对齐的验证要求见验证与对齐。