> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 文档贡献

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

## 规划文档变更

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

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

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

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

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

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

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

## 组织双语页面

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

```text theme={"system"}
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 页面都以清晰标题开头，并在第一段说明读者目标：

```mdx theme={"system"}
---
title: "示例集成"
---

第一段说明读者目标。
```

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

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

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

```mdx theme={"system"}
[Testing and Validation](/en/developer_guide/contributing/testing)
[测试与验证](/zh/developer_guide/contributing/testing)
```

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

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

## 编写代码和命令示例

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

代码和命令应满足：

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

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

## 验证文档改动

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

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

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

```bash theme={"system"}
cd docs
mint dev
```

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

## 提交文档证据

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

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

实现与测试证据按[测试与验证](/zh/developer_guide/contributing/testing)记录；请求审查前，完成 [PR 检查表](/zh/developer_guide/contributing/pull_request_checklist)。