> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 文档更新

为 Benchmark 编写用户指南，让用户无需阅读源码，就能完成环境准备、运行评测并理解结果。

新增或修改 Benchmark 时，同步维护以下中英文页面：

```text theme={"system"}
docs/zh/user_guide/modules/benchmarks/<benchmark-id>.mdx
docs/en/user_guide/modules/benchmarks/<benchmark-id>.mdx
```

页面归属、本地化、导航和公开内容边界遵循[文档贡献指南](/zh/developer_guide/contributing/documentation)。本页规定 Benchmark 页面应包含的内容，以及“运行示例”和“评测结果”的写法。

## 必要内容

按用户从了解任务到解读成绩的顺序组织页面，覆盖以下内容：

* **评测对象与来源**：评测目的、官方资源、固定的数据集和评测器版本、任务数量与划分，以及适用的任务浏览器、许可证和访问权限要求。
* **准备与兼容性**：前置依赖、任务镜像、凭证、推荐及其他兼容 Harness、支持的 Environment，并说明 Recipe 会自动推断的镜像、工作区、资源和网络设置。
* **Benchmark 参数**：专属参数的含义、类型、默认值、有效值和选择建议。
* **运行示例**：按下文[统一模板](#运行示例章节)提供冒烟测试、自定义参数和完整评测命令。
* **评测结果**：按下文[章节规范](#评测结果章节)解释指标、单题评分依据和产物。
* **限制与对齐**：已知兼容性约束、与官方评测流程的重要差异及其影响。

字段、默认值、命令和评分行为都须对照当前实现核实。说明推荐 Harness 的依据，区分上游官方推荐与 AgentCompass 提供的集成建议。

## 保持页面聚焦 Benchmark

通用规则通过链接引用，Benchmark 页面只展开自身的差异：

* 共享参数链接到 [Benchmark 共享字段](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段)；专属参数表不收录 `k`、尝试策略或 Model 位置参数。
* CLI 参数归属和配置覆盖规则链接到[运行参数参考](/zh/user_guide/using_agentcompass/cli/run#参数参考)。
* Harness 安装、步骤与成本限制、命令超时和 Model 接入方式链接到对应 Harness 页面；本页只说明该 Benchmark 所需的额外配置。
* 多次尝试、公共结果结构和聚合规则按[评测结果章节](#评测结果章节)提供索引，避免在多个小节重复解释。

## 运行示例章节

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

### 命令说明与 Harness 选择

先说明 `agentcompass run` 的三个位置参数依次为 Benchmark、Harness 和 Model，并给出本页使用的组件及必要的凭证、环境准备说明。共同的环境变量设置放在选项卡之前。

需要区分多种 Harness 时，将主要运行路径放在“推荐 Harness”小节中，再提供下面的三个场景选项卡。只有一种运行路径时，可以直接展示选项卡，不增加多余层级。

### 三个场景选项卡

使用 `<Tabs>` 和 `<Tab>`，保持以下标题和顺序：

| 选项卡 | 用途 | 命令要求 |
| - | - | - |
| **冒烟测试（单条跑通）** | 验证任务准备、推理和评分的完整链路。 | 选择一条真实且有效的任务，使用最少必要配置。 |
| **自定义参数** | 展示该 Benchmark 有代表性的配置调整。 | 说明为什么调整，以及任务范围或运行行为会如何变化；避免罗列所有参数。 |
| **AgentCompass 推荐配置** | 提供推荐的完整评测方式。 | 明确任务范围，移除仅用于冒烟测试的任务筛选；保留所选数据划分或版本需要的设置。 |

每个选项卡先用一小段说明用途和任务范围，再给出完整命令。用户完成共同的前置设置后，应能单独复制任一选项卡中的命令运行，无需拼接其他选项卡的片段。

存在其他兼容 Harness 时，在这组选项卡之后增加“其他可选 Harness”小节，说明适用场景和配置差异，并为每个 Harness 提供完整评测命令。可以按 Harness 分组选项卡，避免混入前面的三个场景。

### 命令内容与排版

命令只显式设置必要项和本示例要演示的覆盖项。默认值已满足需求时省略对应参数；只有需要展示多次尝试时，才加入 `k` 和尝试策略。凭证及 Model 接入配置通过环境变量引用，避免在各示例中重复填写。

以下排版规则适用于用户指南中所有 Benchmark 页面，包括概览页、各选项卡及其他章节中的参数片段：

* **CLI 选项逐行排列**：用行尾反斜杠（`\`）续行，末行不加；反斜杠后不得有空格。
* **JSON 字段逐行缩进**：每个字段独立一行，嵌套对象展开；保留包裹整个 JSON 参数的引号，不在 JSON 内添加 shell 续行符。
* **编译后自动折行**：Bash 和 JSON 代码块启用 Mintlify 的 `wrap`，代码围栏分别写为 ` ```bash wrap ` 和 ` ```json wrap `。长字符串由页面自动折行，不为排版改变参数值。

## 评测结果章节

统一使用“评测结果”标题。修改已发布页面的标题或小节时，保留旧锚点以兼容已有链接。

章节开头链接到[运行目录](/zh/user_guide/other_features/results/overview#目录布局)、[汇总成绩](/zh/user_guide/other_features/results/summary_analysis)和[单题文件与公共字段](/zh/user_guide/other_features/results/task_results)，正文固定包含两个小节：

* **评分指标**：说明主指标和辅助指标的含义、二元或标量类型、取值范围或单位、分数方向，以及默认成绩如何解读。只展开 Benchmark 专属的聚合、分母或评分异常规则；通用规则链接到[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。
* **单题结果与评分依据**：说明每次尝试中专属评分记录、证据和产物的字段位置与含义，以及影响结果核查但不会保存的内容。公共目录结构、文件名和状态字段由通用文档说明。

评分机制已在前文解释时，用锚点引用。不要另设“计分注意事项”重复公共状态、异常或 `pass@k`、`avg@k` 定义；影响成绩解读的特殊规则归入“评分指标”，排查所需的字段归入“单题结果与评分依据”。区分诊断字段与汇总指标、逻辑结果对象与落盘文件结构。

可以参考 [BrowseComp](/zh/user_guide/modules/benchmarks/browsecomp#评测结果)；包含多级计分和特殊分母时，参考 [SciCode](/zh/user_guide/modules/benchmarks/scicode#评测结果)。

## 预览与验证

完成内容修改后，按以下顺序检查：

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

```bash wrap theme={"system"}
cd docs
mint broken-links
mint validate
```

文档校验不代替真实评测。冒烟测试、完整评测与官方结果对齐的验证要求见[验证与对齐](/zh/developer_guide/extensions/benchmark/validation_and_alignment)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.