> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# SPEC

# 文档写作规范

本文件约定 AgentKit 文档站（VeADK、AgentKit CLI 与 API 参考）的写作、组织与发布规范，供所有文档贡献者遵循。目标是提供准确、具体、可验证的对外官方文档，而非随手记下的笔记或源码说明。

## 配套技能与规范

[`AGENTS.md`](./AGENTS.md) 提供协作入口与本规范摘要；仓库内的 [`agentkit-docs-spec`](./.agents/skills/agentkit-docs-spec/SKILL.md) 技能提供写作、页面结构、示例核验、双语与审查方法，并链接到对应参考资料和来源清单

编写、改进或审查文档时，先读取本规范，再读取对应产品规范，按任务使用技能中的参考：

* [VeADK 文档规范](./productions/veadk/veadk_SPEC.md)
* [VeADK Go 文档规范](./productions/veadk-go/veadk-go_SPEC.md)
* [VeADK Java 文档规范](./productions/veadk-java/veadk-java_SPEC.md)
* [AgentKit CLI 文档规范](./productions/agentkit-cli/agentkit-cli_SPEC.md)
* [API Reference 文档规范](./productions/api-reference/api-reference_SPEC.md)

本文件是文档要求的最高依据，产品规范与技能作补充。技能中的通用建议不能覆盖本规范，也不能扩大当前任务或发布授权；修改任一规范或技能时，应同步核对这些文件的规则与链接

## 目标读者

文档同时服务以下读者：

* 具备开发经验，需要查询公开 API、配置、命令和运行行为的研发人员；
* 不以开发为主要工作，但需要理解产品能力并按照步骤完成配置或操作的用户。

兼容不同读者不等于删减技术细节。应采用渐进式结构：先用简明语言说明「是什么、解决什么问题、何时使用」，再给出最短可用路径，最后提供完整参数、限制和高级配置。参考文档可以保持技术精度，但入口页、概念页和操作指南必须帮助读者建立必要背景。

不要假设读者了解产品内部概念。运行时、会话、记忆、知识库、区域、项目等术语首次出现时，应在正文中自然解释其作用；不要用冗余的括号译名代替解释。

## 语言与语气

采用书面、正式的中文，避免口语化表达。

使用直接、客观的陈述，避免营销性形容词、无依据的效果承诺和「显然」「只需」「轻松」等弱化实际操作成本的表述。不要用空泛的开场、重复的小结或模板化过渡语填充篇幅。

* 不佳：「本教程带你在几分钟内跑通一个 agent。」
* 推荐：「本教程介绍如何安装 VeADK、配置模型并运行一个最小可用的智能体。」

不要把提问或提示词原封不动搬进文档。所有内容都应以文档自身的口吻重写，而不是复述某次对话里的措辞。

正文中的 “agent” 一律译为「智能体」，如「运行一个最小可用的智能体」「多智能体」。代码标识符、类名（`Agent`）与配置键（`model.agent`）保持原样，不翻译。

## 标题

标题使用描述性的短语，不使用数字序号。

* 不佳：`## 1. 安装` / `## 2. 配置`
* 推荐：`## 安装` / `## 配置模型`

后端类文章的标题使用「使用 xxx 存储」的形式，标题中不附加括号英文。

* 不佳：`title: "SQLite（本地文件）"`
* 推荐：`title: "使用 SQLite 存储"`

新建页面必须在 YAML frontmatter 中提供 `title`，不要添加 `description`。HTTP API 单接口页面还需提供 `openapi`，绑定对应语言的规范文件、方法和路径，以使用原生接口展示。页面标题下不展示副标题；需要说明页面用途时，应在正文首段中自然说明。

保留并维护站点语言切换使用的 `en_link` / `zh_link`，两侧链接应指向对应语言的同一页面，不因简化 frontmatter 删除已有语言关联

## 中文文案约定

除非确有必要，中文中不要给术语附加括号内的翻译或注解，标题同样如此。

* 不佳：「火山方舟（Ark）」「豆包（doubao）」「扣子罗盘（Cozeloop）」`title: "A2UI（智能体驱动 UI）"`
* 推荐：「火山方舟」「豆包」「Cozeloop」`title: "A2UI"`

没有对应中文、且作为技术标识存在的词保留英文，如 extras、A2UI、RAG、Redis、API Key。协议限定语可以保留括号形式，如 `OTLP（HTTP）`。这条规则针对的是「给术语再补一个冗余译名或注解」，而非禁止一切括号。

## 文档类型

根据读者要完成的任务选择文档类型，不要把不同目标混在同一篇文章中：

* **教程**：帮助读者通过一条受控路径完成首次成功，强调学习过程和可见结果。
* **操作指南**：解决一个明确任务，直接说明前提、步骤、结果和限制。
* **概念说明**：解释设计、术语、行为和适用场景，帮助读者形成理解。
* **参考文档**：准确、完整地列出公开 API、配置、命令、字段和默认值，便于查询。
* **故障排查**：按现象、原因、检查方法和解决办法组织，避免只罗列错误信息。

这些类型是组织原则，不是必须机械套用的模板。没有实际内容的章节不要为了结构完整而添加。

## 页面结构

教程和操作指南通常按以下顺序组织：

1. 用一段话说明读者将完成什么，以及适用场景。
2. 列出真实存在的前提条件，包括账号、权限、依赖、版本、凭证和外部资源。
3. 给出可复制执行的步骤；每一步只完成一个明确动作。
4. 说明预期结果和验证方法，让读者能够判断操作是否成功。
5. 说明重要限制、风险和常见失败处理；没有相关内容时可省略。

概念说明应先给出通俗定义和适用场景，再解释关键关系与行为，最后给出最小示例。不要用类继承关系、内部调用链或源码片段代替概念解释。

参考文档应先说明对象的用途，再完整列出语法或公开签名、参数、类型、默认值、返回结果和限制，并至少提供一个可运行示例。复杂工作流应另写操作指南，不要塞进参数表。

## 准确与完整

内容要具体、完整，不要含糊其辞。

提到某项可选安装或配置时，写清它到底包含什么、会引入什么，而不是一笔带过。

* 不佳：「安装扩展能力（如……等）。」
* 推荐：明确列出该 extras 包含哪些扩展、各自的用途。

介绍某个可扩展点时，必须给出使用方法。只说「可以自定义」而不给出如何自定义，等于没写。例如提到 `InstructionProvider` 时，应给出它的实际用法示例，而非仅提及其存在。

每个后端都应有独立、完整的说明：列出全部参数（名称、类型、默认值、说明），并给出可运行的示例。不要因为多个后端相似就合并成一段泛泛描述——可以按后端拆分为多篇文章或采用统一的分节结构，但覆盖必须完整。

命令行文档中，所有子命令与标志都用表格列出，逐项给出说明，并配以示例。

描述行为时，应明确区分以下含义：

* **默认行为**：未显式配置时产品实际采用的行为；
* **推荐做法**：适合多数用户的建议，不代表唯一可用方式；
* **限制**：平台、区域、版本、权限或依赖带来的客观边界；
* **实验性或废弃能力**：明确标注其状态、适用版本和替代方案。

不要把推测写成事实，也不要根据参数名称猜测默认值。无法从可靠来源确认的内容应先核实，不得用模糊措辞掩盖不确定性。

## 信息来源

编写或更新文档时，按以下优先级确认事实：

1. 对应产品当前目标版本的公开行为与公开接口。VeADK 以 `veadk-python` 的公开 API、配置和依赖声明为准；AgentKit CLI 以实际命令帮助、配置格式和公开工作流为准。
2. 可执行示例、测试、公开协议或 OpenAPI 等机器可读定义。
3. 上游官方文档，例如说明继承自 Google ADK 的公开行为时参考 Google ADK 文档。
4. 当前文档和 README。它们可用于理解背景，但可能滞后，不能单独作为参数、默认值或命令行为的依据。

只记录已经对外提供或明确属于目标发布版本的能力。不要把内部管理功能、尚未发布的实现或开发计划写成现有产品能力。

## 变更更新流程

文档更新必须先确定事实基线，再开始改写内容。不得仅根据提交标题、变更摘要或现有 Changelog 推断完整行为。

开始更新前完成以下准备：

1. 同步文档仓库最新 `main`，确认工作分支基于当前主线。
2. 检查同一产品变更是否已有开放、已关闭或已合并的文档 PR，避免重复生成、覆盖已合并修正或继续使用过期基线。
3. 明确目标发布版本或 tag；尚未发布的能力只能进入 Preview，已发布版本的事实修正只能进入对应归档。
4. 建立影响清单，至少检查公开命令与参数、配置与环境变量、概念或操作正文、参数表、示例、限制、Changelog、中英文页面和导航。

一个功能更新只处理该功能直接影响的页面。不要把单个功能说明与整个版本归档混在同一变更中；创建版本归档应使用独立变更，以便核对版本边界和审查完整快照。

Changelog 是变更索引，不是能力说明的替代品。每条 Changelog 必须链接到实际说明该能力的正文；目标页至少覆盖使用方法、相关参数或配置、默认行为、限制和必要示例。链接页面没有出现对应能力时，文档更新视为未完成。

Changelog 的变更描述必须以目标版本的事实基线为参照。只有基线中不存在的能力才写为“新增”或“支持”；既有能力的界面、默认值、筛选范围或配置方式发生变化时，只描述真实增量，不得把整项能力重新写成新增。

仅在 Preview 源码中可用、尚未随稳定发行包发布的能力，正文必须醒目标注可用范围、核验所用的版本基线，以及可复现的公开源码安装方式。普通 PyPI 或稳定版安装示例不得暗示该能力已经可用。

参数、默认值、优先级、支持范围和失败条件必须从目标版本的公开 API、实际 CLI 帮助或可执行行为核验。不得沿用上一版本的数字、默认值或支持范围，也不得根据参数名称猜测行为。

中英文更新必须基于同一份影响清单。完成后逐项比较标题、表格行、默认值、示例、警告和链接；文件数量或路径一致不代表内容已经等价。

固定版本号只用于明确的安装目标、兼容性边界或可复现场景。Preview 的通用操作示例优先使用最新发布版本或省略可选版本参数；出现固定版本号时，必须检查它是否与页面目标版本一致。

对外可见的分支名、提交信息、PR 标题、PR 正文和文档内容只描述用户价值、事实依据、变更范围与验证结果。不得记录使用的撰写工具、模型、执行环境、自动生成过程或不可复现的内部工作记录。

修改规范时必须同时检查根 `SPEC.md`、`AGENTS.md` 和相关产品规范。精简规则只能补充或引用上位规范，不得在归档可变性、版本边界、术语或验证要求上互相冲突。

## 示例与代码

示例应最小、完整、可运行，并使用真实可理解的名称，不使用无意义的 `foo`、`bar`。省略与主题无关的内容时，不得破坏示例的可执行性。

* 代码块必须标注语言；有助于读者创建文件时可标注公开文件名。
* 命令应说明执行目录、必要环境变量和成功后的可见结果。
* 不得在示例中硬编码真实密钥、令牌、账号或内部地址；统一使用明确的占位符或环境变量。
* 同一能力提供多种方式时，先给出推荐路径，再说明替代方案及其差异。
* 发布前应实际运行或以等价的自动化方式验证关键示例。无法执行的示例至少要核对公开签名、依赖和上下文，并明确验证范围。

API 参考应覆盖方法、路径、鉴权、路径参数、查询参数、请求体、响应和常见失败条件。CLI 参考应覆盖命令、别名、参数、标志、默认值、交互行为和破坏性操作，并以实际帮助输出核对。

## 避免源码级表述

以使用者的视角解释「怎么用」，不要暴露实现细节、内部文件名或类型签名。

* 不佳：「该函数也可以是 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` 连接。」
* 推荐：「否则初始化会报错。」「以非加密方式连接。」

作为例外，用户需要直接使用的公开 API——类名、构造参数、配置键、环境变量、用户自己新建的文件路径——应当保留并写清楚，因为那属于「怎么用」而非内部实现。

## 安全与风险

涉及以下情况时，必须在操作前给出醒目的说明，并写清影响范围：

* 删除、覆盖、发布、迁移或其他难以恢复的操作；
* 产生云资源费用、修改线上资源或将服务暴露到公网；
* 需要高权限账号、跨区域资源或额外服务授权；
* 处理用户数据、会话内容、文件、日志或其他敏感信息。

凭证应通过环境变量、密钥管理服务或产品支持的安全配置提供。示例不得鼓励提交 `.env`、配置文件中的明文密钥或其他敏感信息。

## 结构

除非明确要求，不要默认添加「下一步」一类的收尾章节。

文档站为双语：中文为默认语言，英文与之并列。两种语言的目录结构、页面层级保持一致；新增或调整页面时同步更新两侧。导航与页面组织在 `docs.json` 中集中维护。

文档按产品组织在 `productions/` 下。每个产品包含 `preview` 与 `archives`：

```text theme={null}
productions/
└── <product>/
    ├── preview/
    │   ├── zh/
    │   └── en/
    └── archives/
        └── <version>/
            ├── zh/
            └── en/
```

`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`，确认差异格式与站点配置有效；
* 检查最终差异，确保每一处修改都与本次文档目标直接相关。


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