文档贡献

修改公开行为时，应在同一 PR 中更新相应的 AgentCompass 文档，并保证中英文页面同步且都能通过验证。

​

规划文档变更

把信息放到读者会查找的位置：

内容	归属章节
安装、前置条件和首次成功运行	快速开始
配置、命令、操作、结果和故障排查	用户指南
架构、源码契约、扩展实现、验证和贡献规范	开发者指南
AgentCompass 团队的研究论文	研究论文

每个页面应围绕一个明确的读者目标展开。对于共享默认值、CLI 签名、结果结构或 provider 行为，应链接到权威页面，不要在多处重复维护同一说明。

新增或修改 Benchmark 用户指南时，遵循评测结果章节规范。

按以下顺序使用事实来源：

1. docs/docs.json：已发布站点结构和导航。
2. 同章节已有页面：术语、内容深度和风格。
3. AgentCompass 实现与配置：行为、默认值、字段和支持组件。
4. 官方上游文档：provider 专属行为。

不能根据旧示例推断选项、默认值、兼容性或输出字段。相关工具支持时，应使用组件发现和配置文档生成结果；工具无法生成的内容，则直接核对负责该行为的源码；公开命令必须使用当前 CLI 接受的语法。

公开文档只能包含公开 provider 和基础设施信息。不得在公开文档目录中记录组织专属的部署细节、凭证、端点、镜像、挂载或配置流程。

​

组织双语页面

路径与本地化。 中英文页面必须在各自语言根目录下使用相同相对路径：

docs/en/developer_guide/extensions/example_integration.mdx
docs/zh/developer_guide/extensions/example_integration.mdx

developer_guide/ 下的页面应放入与 Mint 导航分组对应的 architecture/、extensions/ 或 contributing/ 目录；分组入口页面统一命名为 overview.mdx。除非维护者明确同意分阶段本地化，否则应在同一个 PR 中完成两个语言页面，不能暂时用混合语言内容代替。

中文页面应翻译普通英文术语，同时保留产品名、缩写、代码标识符以及项目术语 agent、Model、Benchmark、Harness、Environment、Recipe、runtime、provider 和 sandbox。每个中文正文段落、列表项和 MDX 组件内正文都应在源码中保持一行，避免软换行引入可见空格。

同时列出四个核心组件时，始终使用 Model、Benchmark、Harness、Environment 的顺序。model 是代码标识符时保留小写，CLI 语法必须保留真实的 BENCHMARK HARNESS MODEL 位置顺序。

页面头部配置。 每个 MDX 页面都以清晰标题开头，并在第一段说明读者目标：

---
title: "示例集成"
---

第一段说明读者目标。

不要在页面头部配置中添加 description 或 icon。用第一段概括页面目标，并通过导航层级体现页面结构。

标题层级。 只有需要区分多个并列主题时才使用子标题。父章节只有一个子标题时，优先合并重复标题；内容可独立查阅时，提升为并列章节；简短补充直接写入正文。不要为凑齐层级拆出空洞小节。调整已发布标题时保留旧锚点，并同步中英文层级。

导航与链接。 每个发布页面都要添加到 docs/docs.json 的两个语言树中，并保持相同层级和位置。导航应保持浅层；只有标签页和顶层章节组可以使用图标，嵌套组和单页不能使用图标。

内部链接使用相对于站点根目录且不含扩展名的路径：

[Testing and Validation](/en/developer_guide/contributing/testing)
[测试与验证](/zh/developer_guide/contributing/testing)

英文页面链接到 /en/ 目标，中文页面链接到 /zh/ 目标。移动页面时，应更新所有指向该页面的链接，并为已经发布的原路径添加重定向；不能在页面或分组标题前添加空格来模拟层级。翻译后应重新检查标题对应的锚点，因为自动生成的锚点 ID 可能随语言变化；不需要定位具体章节时，优先链接页面根路径。

共享资源。 两种语言共享的图片放在 docs/images/ 下，并为每张图片提供描述性替代文本。可复用的 MDX 或 JSX 组件放在 docs/snippets/ 下，使用站点根路径导入，并显式传入各语言文案。只有当图片、表格、选项卡或交互组件能让关系或选择更容易理解时，才使用这些形式；修改后应检查桌面和窄屏布局。

​

收录研究论文

研究论文集合由按时间排序的索引和每篇论文的独立页面组成。仅收录 AgentCompass 团队的论文，并明确说明论文与项目的关系。其他团队的工作即使使用或扩展了 AgentCompass，也不在收录范围内。

1. 在 docs/en/research/papers/ 和 docs/zh/research/papers/ 下添加对应页面。使用稳定且有辨识度的文件名，例如 swebench_pro_verified.mdx；论文修订或被会议接收后，保持路径不变。
2. 参考已有论文页面，提供原文完整标题、arXiv 或出版方链接、首次提交日期、研究方向、简要贡献，以及与 AgentCompass 的关系。按需补充公开代码、数据集和文档链接；运行方法链接到已有使用指南。
3. 在两个语言的 research/overview.mdx 索引中，按首次提交年份分组、日期倒序添加条目。两个语言的索引与论文详情页应同步更新录用情况；尚未记录录用信息时填写 —。论文修订时更新原有条目，不重复收录。
4. 在 docs/docs.json 两个语言的研究论文导航中，将页面加入对应年份的分组。出现新年份时，补充索引中的年份标题和导航分组。
5. 运行下文的文档检查。项目 README 保留集合的固定入口，无需随每篇论文更新。

索引保持简洁，详细介绍和资源链接放在论文页面。新增论文时，研究结论应引用原论文，元数据应与 arXiv 或出版方记录核对。

​

编写代码和命令示例

先说明读者要完成的任务，再给出准确步骤、预期输出字段和常见失败边界。使用直接表达，并称呼读者为“你”。

代码和命令应满足：

• 每个围栏代码块都包含语言标识符；
• 使用真实组件 ID 或明确标注的占位符；
• 凭证放在环境变量中，并使用脱敏值；
• 根据当前实现核对选项拼写、默认行为、输出路径和可接受的语法；
• 可复制的命令和路径模板使用围栏代码块，不要塞入过长的行内代码；源码文件与符号分开书写，逐层说明嵌套字段；
• 对版本敏感的上游行为注明适用的版本范围或官方来源。

通过测试与验证区分组件发现或试运行检查与真实执行验证，并为所改契约选择合适的证据。不能把完整结果目录、大型轨迹、生成的数据集、凭证或私有基础设施细节粘贴到示例或资源中。

​

验证文档改动

从文档根目录运行必需的链接和 MDX 检查：

cd docs
mint broken-links
mint validate

修改导航、MDX 组件、表格、选项卡、样式或命令布局时进行预览：

cd docs
mint dev

预览时检查中英文路由、导航位置、标题、代码换行、链接、表格和响应式布局。还要按照测试与验证运行代码仓库的 pre-commit 检查。应修复验证错误；除非排除页面、资源或链接本来就是预期的公开行为，否则不能通过忽略它们来绕过构建。

​

提交文档证据

PR 中只需记录文档变更特有的证据：

• 中英文页面路径；
• 受影响的 docs/docs.json 条目和重定向；
• mint broken-links 和 mint validate 的准确结果；
• 重要布局变更的预览证据。

实现与测试证据按测试与验证记录；请求审查前，完成 PR 检查表。