必要内容
按用户从了解任务到解读成绩的顺序组织页面,覆盖以下内容:- 评测对象与来源:评测目的、官方资源、固定的数据集和评测器版本、任务数量与划分,以及适用的任务浏览器、许可证和访问权限要求。
- 准备与兼容性:前置依赖、任务镜像、凭证、推荐及其他兼容 Harness、支持的 Environment,并说明 Recipe 会自动推断的镜像、工作区、资源和网络设置。
- Benchmark 参数:专属参数的含义、类型、默认值、有效值和选择建议。
- 运行示例:按下文统一模板提供冒烟测试、自定义参数和完整评测命令。
- 评测结果:按下文章节规范解释指标、单题评分依据和产物。
- 限制与对齐:已知兼容性约束、与官方评测流程的重要差异及其影响。
保持页面聚焦 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。
预览与验证
完成内容修改后,按以下顺序检查:- 核对内容:命令、参数和评分说明与实现一致;三个场景职责清楚,完整评测未遗留冒烟筛选,通用说明通过链接引用。
- 检查页面:中英文路径与内容同步,导航、引用和旧锚点有效;新增、移动或删除页面时更新
docs/docs.json及必要的重定向。 - 预览渲染:运行
mint dev,检查桌面与窄屏上的选项卡、表格和代码块,尤其是--harness-params的长字符串。确认页面实际折行,复制内容仍保留原始命令;不能仅凭 MDX 源码中的换行判断显示效果。 - 执行校验:从文档根目录运行链接和构建检查,修复发现的问题。
