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

​
规划文档变更

把信息放到读者会查找的位置： 每个页面应围绕一个明确的读者目标展开。对于共享默认值、CLI 签名、结果结构或 provider 行为，应链接到权威页面，不要在多处重复维护同一说明。 按以下顺序使用事实来源：
  1. docs/docs.json：已发布站点结构和导航。
  2. 同章节已有页面：术语、内容深度和风格。
  3. AgentCompass 实现与配置：行为、默认值、字段和支持组件。
  4. 官方上游文档：provider 专属行为。
不能根据旧示例推断选项、默认值、兼容性或输出字段。相关工具支持时，应使用组件发现和配置文档生成结果；工具无法生成的内容，则直接核对负责该行为的源码；公开命令必须使用当前 CLI 接受的语法。 公开文档只能包含公开 provider 和基础设施信息。不得在公开文档目录中记录组织专属的部署细节、凭证、端点、镜像、挂载或配置流程。

​
组织双语页面

路径与本地化。 中英文页面必须在各自语言根目录下使用相同相对路径：
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 页面都以清晰标题开头，并在第一段说明读者目标：
不要在页面头部配置中添加 description 或 icon。用第一段概括页面目标，并通过导航层级体现页面结构。 导航与链接。 每个发布页面都要添加到 docs/docs.json 的两个语言树中，并保持相同层级和位置。导航应保持浅层；只有标签页和顶层章节组可以使用图标，嵌套组和单页不能使用图标。 内部链接使用相对于站点根目录且不含扩展名的路径：
英文页面链接到 /en/ 目标，中文页面链接到 /zh/ 目标。移动页面时，应更新所有指向该页面的链接，并为已经发布的原路径添加重定向；不能在页面或分组标题前添加空格来模拟层级。翻译后应重新检查标题对应的锚点，因为自动生成的锚点 ID 可能随语言变化；不需要定位具体章节时，优先链接页面根路径。 共享资源。 两种语言共享的图片放在 docs/images/ 下，并为每张图片提供描述性替代文本。可复用的 MDX 或 JSX 组件放在 docs/snippets/ 下，使用站点根路径导入，并显式传入各语言文案。只有当图片、表格、选项卡或交互组件能让关系或选择更容易理解时，才使用这些形式；修改后应检查桌面和窄屏布局。

​
编写代码和命令示例

先说明读者要完成的任务，再给出准确步骤、预期输出字段和常见失败边界。使用直接表达，并称呼读者为“你”。 代码和命令应满足：
  • 每个围栏代码块都包含语言标识符；
  • 使用真实组件 ID 或明确标注的占位符；
  • 凭证放在环境变量中，并使用脱敏值；
  • 根据当前实现核对选项拼写、默认行为、输出路径和可接受的语法；
  • 可复制的命令和路径模板使用围栏代码块，不要塞入过长的行内代码；源码文件与符号分开书写，逐层说明嵌套字段；
  • 对版本敏感的上游行为注明适用的版本范围或官方来源。
通过测试与验证区分组件发现或试运行检查与真实执行验证，并为所改契约选择合适的证据。不能把完整结果目录、大型轨迹、生成的数据集、凭证或私有基础设施细节粘贴到示例或资源中。

​
验证文档改动

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

​
提交文档证据

PR 中只需记录文档变更特有的证据：
  • 中英文页面路径；
  • 受影响的 docs/docs.json 条目和重定向；
  • mint broken-links 和 mint validate 的准确结果；
  • 重要布局变更的预览证据。
实现与测试证据按测试与验证记录；请求审查前，完成 PR 检查表。