文档写作规范
本文件约定 AgentKit 文档站（VeADK、AgentKit CLI 与 API 参考）的写作、组织与发布规范，供所有文档贡献者遵循。目标是提供准确、具体、可验证的对外官方文档，而非随手记下的笔记或源码说明。配套技能与规范
AGENTS.md 提供协作入口与本规范摘要；仓库内的 agentkit-docs-spec 技能提供写作、页面结构、示例核验、双语与审查方法，并链接到对应参考资料和来源清单
编写、改进或审查文档时，先读取本规范，再读取对应产品规范，按任务使用技能中的参考：
本文件是文档要求的最高依据，产品规范与技能作补充。技能中的通用建议不能覆盖本规范，也不能扩大当前任务或发布授权；修改任一规范或技能时，应同步核对这些文件的规则与链接
目标读者
文档同时服务以下读者：- 具备开发经验，需要查询公开 API、配置、命令和运行行为的研发人员；
- 不以开发为主要工作，但需要理解产品能力并按照步骤完成配置或操作的用户。
语言与语气
采用书面、正式的中文，避免口语化表达。 使用直接、客观的陈述，避免营销性形容词、无依据的效果承诺和「显然」「只需」「轻松」等弱化实际操作成本的表述。不要用空泛的开场、重复的小结或模板化过渡语填充篇幅。- 不佳：「本教程带你在几分钟内跑通一个 agent。」
- 推荐：「本教程介绍如何安装 VeADK、配置模型并运行一个最小可用的智能体。」
Agent）与配置键（model.agent）保持原样，不翻译。
标题
标题使用描述性的短语，不使用数字序号。- 不佳：
## 1. 安装/## 2. 配置 - 推荐：
## 安装/## 配置模型
- 不佳：
title: "SQLite（本地文件）" - 推荐：
title: "使用 SQLite 存储"
title，不要添加 description。HTTP API 单接口页面还需提供 openapi，绑定对应语言的规范文件、方法和路径，以使用原生接口展示。页面标题下不展示副标题；需要说明页面用途时，应在正文首段中自然说明。
保留并维护站点语言切换使用的 en_link / zh_link，两侧链接应指向对应语言的同一页面，不因简化 frontmatter 删除已有语言关联
中文文案约定
除非确有必要，中文中不要给术语附加括号内的翻译或注解，标题同样如此。- 不佳：「火山方舟（Ark）」「豆包（doubao）」「扣子罗盘（Cozeloop）」
title: "A2UI（智能体驱动 UI）" - 推荐：「火山方舟」「豆包」「Cozeloop」
title: "A2UI"
OTLP（HTTP）。这条规则针对的是「给术语再补一个冗余译名或注解」，而非禁止一切括号。
文档类型
根据读者要完成的任务选择文档类型，不要把不同目标混在同一篇文章中：- 教程：帮助读者通过一条受控路径完成首次成功，强调学习过程和可见结果。
- 操作指南：解决一个明确任务，直接说明前提、步骤、结果和限制。
- 概念说明：解释设计、术语、行为和适用场景，帮助读者形成理解。
- 参考文档：准确、完整地列出公开 API、配置、命令、字段和默认值，便于查询。
- 故障排查：按现象、原因、检查方法和解决办法组织，避免只罗列错误信息。
页面结构
教程和操作指南通常按以下顺序组织：- 用一段话说明读者将完成什么，以及适用场景。
- 列出真实存在的前提条件，包括账号、权限、依赖、版本、凭证和外部资源。
- 给出可复制执行的步骤；每一步只完成一个明确动作。
- 说明预期结果和验证方法，让读者能够判断操作是否成功。
- 说明重要限制、风险和常见失败处理；没有相关内容时可省略。
准确与完整
内容要具体、完整，不要含糊其辞。 提到某项可选安装或配置时，写清它到底包含什么、会引入什么，而不是一笔带过。- 不佳：「安装扩展能力（如……等）。」
- 推荐：明确列出该 extras 包含哪些扩展、各自的用途。
InstructionProvider 时，应给出它的实际用法示例，而非仅提及其存在。
每个后端都应有独立、完整的说明：列出全部参数（名称、类型、默认值、说明），并给出可运行的示例。不要因为多个后端相似就合并成一段泛泛描述——可以按后端拆分为多篇文章或采用统一的分节结构，但覆盖必须完整。
命令行文档中，所有子命令与标志都用表格列出，逐项给出说明，并配以示例。
描述行为时，应明确区分以下含义：
- 默认行为：未显式配置时产品实际采用的行为；
- 推荐做法：适合多数用户的建议，不代表唯一可用方式；
- 限制：平台、区域、版本、权限或依赖带来的客观边界；
- 实验性或废弃能力：明确标注其状态、适用版本和替代方案。
信息来源
编写或更新文档时，按以下优先级确认事实：- 对应产品当前目标版本的公开行为与公开接口。VeADK 以
veadk-python的公开 API、配置和依赖声明为准；AgentKit CLI 以实际命令帮助、配置格式和公开工作流为准。 - 可执行示例、测试、公开协议或 OpenAPI 等机器可读定义。
- 上游官方文档，例如说明继承自 Google ADK 的公开行为时参考 Google ADK 文档。
- 当前文档和 README。它们可用于理解背景，但可能滞后，不能单独作为参数、默认值或命令行为的依据。
变更更新流程
文档更新必须先确定事实基线，再开始改写内容。不得仅根据提交标题、变更摘要或现有 Changelog 推断完整行为。 开始更新前完成以下准备：- 同步文档仓库最新
main，确认工作分支基于当前主线。 - 检查同一产品变更是否已有开放、已关闭或已合并的文档 PR，避免重复生成、覆盖已合并修正或继续使用过期基线。
- 明确目标发布版本或 tag；尚未发布的能力只能进入 Preview，已发布版本的事实修正只能进入对应归档。
- 建立影响清单，至少检查公开命令与参数、配置与环境变量、概念或操作正文、参数表、示例、限制、Changelog、中英文页面和导航。
SPEC.md、AGENTS.md 和相关产品规范。精简规则只能补充或引用上位规范，不得在归档可变性、版本边界、术语或验证要求上互相冲突。
示例与代码
示例应最小、完整、可运行，并使用真实可理解的名称，不使用无意义的foo、bar。省略与主题无关的内容时，不得破坏示例的可执行性。
- 代码块必须标注语言；有助于读者创建文件时可标注公开文件名。
- 命令应说明执行目录、必要环境变量和成功后的可见结果。
- 不得在示例中硬编码真实密钥、令牌、账号或内部地址；统一使用明确的占位符或环境变量。
- 同一能力提供多种方式时，先给出推荐路径，再说明替代方案及其差异。
- 发布前应实际运行或以等价的自动化方式验证关键示例。无法执行的示例至少要核对公开签名、依赖和上下文，并明确验证范围。
避免源码级表述
以使用者的视角解释「怎么用」，不要暴露实现细节、内部文件名或类型签名。- 不佳：「该函数也可以是 async 的（返回一个可等待对象）。」
- 推荐：「该函数也可以是异步函数（
async def）。」
- 不佳：「
a2ui/registry.ts将每个组件名映射到 React 渲染器；components/index.ts通过import.meta.glob导入每个*/index.ts。」 - 推荐：「组件类型到渲染器的映射由一张注册表维护，新增的组件目录会被自动发现并注册，无需改动中心配置文件。」
- 不佳：
sender.union_id -> Runner.user_id - 推荐：「以消息发送者作为
Runner的用户标识。」
- 不佳：「否则初始化会抛出
ValueError。」「以insecure=True连接。」 - 推荐：「否则初始化会报错。」「以非加密方式连接。」
安全与风险
涉及以下情况时，必须在操作前给出醒目的说明，并写清影响范围：- 删除、覆盖、发布、迁移或其他难以恢复的操作；
- 产生云资源费用、修改线上资源或将服务暴露到公网；
- 需要高权限账号、跨区域资源或额外服务授权；
- 处理用户数据、会话内容、文件、日志或其他敏感信息。
.env、配置文件中的明文密钥或其他敏感信息。
结构
除非明确要求，不要默认添加「下一步」一类的收尾章节。 文档站为双语：中文为默认语言，英文与之并列。两种语言的目录结构、页面层级保持一致；新增或调整页面时同步更新两侧。导航与页面组织在docs.json 中集中维护。
文档按产品组织在 productions/ 下。每个产品包含 preview 与 archives：
preview 保存下一版本的可编辑文档；archives 保存已发布版本的独立快照。发布版本后，从 Preview 创建新的归档目录。归档内容只做对应版本的事实修正，不得因 Preview 更新而批量覆盖。
Preview 中尚未对应已发布 tag 的变更放在 未发布 / Unreleased 分节；tag 发布后，将这些条目转换为明确版本分节，再创建归档。不得把新能力追加到较早版本的分节中。
创建归档前，必须按目标 tag 逐项核验 Preview 的影响清单，并比较目标 tag 之后是否已有新能力进入 Preview。确认 Preview 只包含目标版本可公开内容后才能复制；不得把当前 Preview 不加区分地作为目标 tag 的事实来源。归档生成后，还要检查其正文、Changelog 和导航均不包含晚于该版本的能力。
每个产品的 changelog.mdx 采用累计式更新：目标版本的页面必须保留首个已发布版本至该版本的全部公开变更，并按版本从新到旧分节排列。新增版本时，在 Preview 顶部增加新版本分节并保留全部历史分节；创建归档时复制截至该版本的完整累计记录，不得只保留相对上一版本的差异。归档 Changelog 不得包含晚于该归档版本的内容。
每个版本分节使用 模块 / 变更细节 / 链接 表格。Preview 中新增条目链接到 Preview 对应说明页；归档中的历史条目保留对应版本的稳定链接。中英文版本顺序、条目和链接必须等价。
中英文页面不仅路径一致，信息也必须等价：参数、默认值、限制、警告、示例和链接不得只更新一侧。英文应自然表达原意，不要逐字翻译中文句式。
内部链接使用站点根路径且不带文件扩展名。链接文字应说明目标内容，避免单独使用「这里」「点击查看」等无法脱离上下文理解的文字。图片必须提供能够说明信息用途的替代文本。
发布检查
提交文档前，至少完成以下检查：- 页面事实与目标版本的公开接口一致，参数、默认值和命令没有依赖旧文档猜测；
- 已检查相同源码变更对应的开放、关闭和已合并文档 PR，没有重复更新或覆盖已合并修正；
- 影响清单中的正文、参数表、示例、Changelog、中英文页面和导航均已更新；
- 每条新增 Changelog 的链接页面确实包含对应能力，Changelog 不是该能力的唯一说明；
- Preview 的未发布内容与已发布版本分节边界清晰，归档不包含目标 tag 之后的能力；
- Preview 中的固定旧版本号已经扫描并逐项确认，通用示例没有无意固定到过期版本；
- 关键示例可运行，命令、导入路径和配置键已经核对；
- 新页面已加入
docs.json，中英文路径、层级与内容保持一致； - frontmatter 包含准确的
title，且不包含description； - 内部链接使用根路径，外部链接指向公开、稳定的官方来源；
- 未包含密钥、内部地址、内部文件路径、私有机制或未发布能力；
- 警告位于危险操作之前，并说明影响和必要的恢复方式；
- 在环境支持时运行
mint validate、mint broken-links和mint a11y，修复构建、链接与无障碍问题； - 运行
git diff --check和jq empty docs.json，确认差异格式与站点配置有效； - 检查最终差异，确保每一处修改都与本次文档目标直接相关。