> ## 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.

# Veadk SPEC

# VeADK 文档规范

本规范适用于 `productions/veadk/preview/{zh,en}` 下的 VeADK 文档。根目录 `SPEC.md` 是上位规范；若本文件与根规范冲突，以根规范为准。本文件只补充 VeADK 子文档库的组织、书写和排版要求。

## 内容范围

* 只把 `preview` 作为当前版本来源；`archives` 仅用于已发布版本事实修正。
* VeADK 文档面向使用 Python SDK 构建、运行、部署和扩展智能体应用的开发者。
* 文档覆盖公开 API、配置、安装、模型、运行时、工具、技能、会话、记忆、知识库、可观测、安全、扩展、前端与部署。
* 不写源码走读，不记录内部文件名、内部函数、私有机制或未发布能力。
* 中文为默认语言，英文并列；`zh` 与 `en` 路径、页面层级、参数、示例、限制和警告必须等价。

## 目录与导航

`preview` 目录固定为双语结构：

```text theme={null}
productions/veadk/preview/
├── zh/
│   ├── index.mdx
│   ├── changelog.mdx
│   ├── get-started/
│   ├── components/
│   └── deploy/
└── en/
    ├── index.mdx
    ├── changelog.mdx
    ├── get-started/
    ├── components/
    └── deploy/
```

主要分区：

* `get-started/`：安装与快速开始。
* `components/agent/`：模型、运行时、系统提示词、提示词管理、结构化输出、技能。
* `components/tools/`：内置工具、自定义函数工具、MCP 工具和火山引擎工具能力。
* `components/session/`：短期会话和会话存储后端。
* `components/memory/`：长期记忆和记忆存储后端。
* `components/knowledge/`：知识库和向量/检索后端。
* `components/observability/`：日志、链路、APMPlus、Cozeloop、TLS、内存导出。
* `components/security/`：入站认证、出站认证、可信 MCP、内容安全。
* `components/extensions/`：飞书等扩展集成。
* `components/frontend/`：VeADK Web、VeADK Frontend、A2UI、Studio。
* `deploy/`：部署到 AgentKit 等部署说明。

新增、删除或移动页面时，必须同步更新 `docs.json` 中 VeADK Preview 导航和中英文页面。

## 页面类型

### 入口页

入口页包括 `index.mdx` 和各组件目录的 `index.mdx`。这类页面应：

* 用首段说明能力范围和适用场景。
* 用表格列出核心组件、使用路径或后端选择。
* 链接使用站点根路径，不带 `.mdx` 后缀。
* 不展开全部参数；详细参数应放到对应子页面。

### 安装与快速开始

安装页应写清：

* Python 版本、包管理器、账号或模型凭证等前置条件。
* PyPI 安装命令。
* extras 可选依赖组及每组包含的能力。
* 从源码构建时的执行目录、虚拟环境和可编辑安装方式。

快速开始应覆盖：

1. 配置模型；
2. 编写最小智能体；
3. 运行并看到结果。

配置方式可以使用 `<Tabs>` 展示环境变量与配置文件，但必须说明各方式的优先级或适用场景。

### 组件说明

组件页面应先回答“是什么、何时使用”，再给出最小示例，最后列出完整参数和限制。推荐结构：

1. 首段说明能力。
2. `## 何时使用` 或 `## 功能说明`。
3. `## 依赖`，仅当需要额外安装或外部服务时出现。
4. `## 使用示例` 或 `## 使用方法`。
5. `## 参数`，覆盖构造参数、配置项、环境变量和默认值。
6. 必要的 `<Note>`、`<Tip>`、`<Warning>`。

不要只写“可以自定义”“支持某后端”而不给出可运行代码和参数说明。

### 后端页面

会话、记忆和知识库后端页面必须独立完整，不能依赖读者去其他后端页面补齐参数。每个后端页面至少包括：

* 标题使用「使用 xxx 存储」或现有产品化标题，不在标题里附加括号英文。
* 首段说明该后端使用的服务或本地资源、是否适合生产、关键能力。
* `## 何时使用`：列出适用场景。
* `## 依赖`：列出 extras 或外部服务，仅在确有依赖时出现。
* `## 使用示例`：给出最小可运行 Python 示例；如支持显式配置，再给一个配置示例。
* `## 参数`：按“构造参数”“连接配置”“环境变量配置”等分节列出。
* 表格列必须包含 `参数/配置项`、`类型`、`默认值`、`说明`；环境变量表包含 `环境变量`、`默认值`、`说明`。
* 对命名规则、区域、凭证获取顺序、自动创建资源、废弃别名和不生效参数必须写清。

参数表可使用左对齐写法：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |

如果某参数只在特定后端生效，可增加“是否生效”列，但必须说明不生效时的原因。

### 工具与技能页面

工具页面应覆盖：

* 工具用途和适用场景。
* 安装或凭证要求。
* 注册到 `Agent` 的方式。
* 最小可运行示例。
* 输入输出结构、长时任务、上下文参数或多模态能力等特殊行为。
* 安全边界，例如外部服务访问、代码执行、文件读取、网络请求和凭证传递。

自定义函数工具必须说明函数签名、Docstring 对工具描述的作用、如何注册到 `Agent`，以及携带运行时上下文或长时任务时的写法。

### 前端与部署页面

前端、Studio、A2UI 和部署页面应采用操作指南结构：

* 写清前置条件、账号权限、运行环境和必要环境变量。
* 给出可复制命令和配置。
* 说明启动、访问、部署和验证方式。
* 涉及公网访问、OAuth、云资源、IAM Role、环境变量透传和用户数据时，必须在操作前说明风险和影响。

### 更新日志

`changelog.mdx` 使用表格组织版本变更，列为 `模块 / 变更细节 / 链接`。要求：

* 更新日志采用累计式记录，而不是只对比上一版本。每个归档页面必须包含 1.0.0 至该归档版本的全部公开变更；Preview 必须包含 1.0.0 至当前版本的全部公开变更。
* 各版本使用独立二级标题，并按版本从新到旧排列。新增版本时只在顶部增加新版本分节，不得覆盖或删除已有历史分节。
* 尚未对应已发布 tag 的 Preview 变更统一放在 `未发布` / `Unreleased` 分节；tag 发布后再转换为明确版本，不得提前归入上一个版本。
* 从 Preview 创建归档时，复制截至目标版本的完整累计更新日志；归档页面不得包含晚于自身版本的分节。
* 每条变更对应用户可感知能力、行为变化或兼容性变化。
* Preview 的新增条目链接到 Preview 中对应说明页；归档中的历史条目保留对应版本的稳定链接。
* Changelog 条目不能代替正文。链接到 Studio、工具、后端或部署页时，目标页必须实际包含对应的使用步骤、参数、配置、限制或示例。
* 不写内部提交、内部任务编号或源码文件。
* 中英文更新日志的版本顺序、条目和链接等价。

## 版本变更工作流

更新 VeADK 文档前，先以目标 tag 建立影响清单，不直接从最新开发分支推断已发布版本。影响清单至少包括：

* 新增或变化的公开类、构造参数、配置键、环境变量和 extras；
* `veadk` 顶级命令、子命令、选项、别名、默认值和凭据优先级；
* Studio、Frontend、部署和云资源操作中的用户可见流程、权限、费用与安全边界；
* 对应正文、参数表、示例、Changelog、中英文页面及 `docs.json` 导航。

对同一源码变更，必须检查已有开放、关闭和已合并文档 PR。已合并内容要作为当前基线审查，不能只检查未合并 PR；已关闭 PR 中可复用的公开说明要与当前 Preview 对照，不得整段照搬过期结构或内部实现。

创建版本归档前，比较目标 tag 与 Preview：属于目标 tag 的缺失说明先补齐，晚于目标 tag 的内容留在 Preview。归档创建后，检查其中所有 Changelog 链接均指向该版本归档，而不是 Preview。

Studio 和其他 CLI 页面必须分别列全本地启动、部署与更新命令的公开选项。新增选项时，同步更新使用示例、参数表、环境变量、默认行为和限制；不能只在 Changelog 中出现。

Studio 新增或调整资源选择器时，正文必须覆盖 Studio 默认值、地域与项目范围、刷新方式、空状态、错误状态、所需权限、凭据来源，以及最终保存或生成的公开配置；不能只写“支持下拉选择”。

必须区分 Studio 界面与 VeADK SDK 的能力边界。Studio 的默认值、隐藏项和筛选范围不等于 SDK 的构造默认值与完整支持范围；Studio 未展示某个后端或选项时，不得写成 SDK 不支持。

## 示例与代码

* Python 示例使用 `python` 代码块；命令使用 `bash`；配置使用 `yaml`；前端示例可使用 `ts` 或 `tsx`。
* 代码块可标注公开示例路径或用户自建文件名，例如 `main.py`，但不要暴露内部源码路径。
* 示例应最小、完整、可运行。导入路径、类名、参数名必须与公开 API 一致。
* 凭证使用环境变量或占位符，不把 AK/SK、API Key、Token 写入配置文件正文。
* 涉及火山引擎、VikingDB、Redis、OpenSearch、Milvus、MySQL、PostgreSQL 等外部服务时，必须说明连接配置、区域、凭证和网络可达性。
* 默认模型、默认区域、默认向量维度、默认数据库路径等事实必须核对后再写。

## 排版与组件

* YAML frontmatter 提供 `title`，保留并维护语言切换使用的 `en_link` / `zh_link`，不添加 `description` 或页面副标题。
* 标题使用描述性短语，不使用数字序号。
* 产品名、类名、构造参数、配置键、环境变量、模型名和协议名使用反引号或原文。
* 优先用普通 Markdown 表格承载参数、依赖组、后端能力矩阵和环境变量。
* Mintlify 组件使用规则：
  * `<Note>`：补充默认行为、兼容性、前置说明。
  * `<Tip>`：推荐实践或便捷路径。
  * `<Warning>`：安全风险、费用、删除、覆盖、废弃和兼容性破坏。
  * `<Steps>` / `<Step>`：必须顺序执行的操作。
  * `<Tabs>` / `<Tab>`：互斥配置方式或平台差异。
* 不添加空泛总结和“下一步”章节，除非该页确实需要引导读者进入下一项任务。

## 术语与命名

* 中文正文中的 “agent” 写作「智能体」；公开类名 `Agent`、`Runner`、`LongTermMemory`、`ShortTermMemory` 等保持原文。
* `runtime` 通常译为「运行时」；`session` 译为「会话」；`memory` 按语境译为「记忆」或「长期记忆」；`knowledge base` 译为「知识库」。
* A2UI、VeADK Web、VeADK Frontend、Studio、Cozeloop、APMPlus、VikingDB、OpenViking、TOS、MCP、RAG、Redis、API Key 等按技术标识保留。
* 中文标题不要写括号译名，例如不写「A2UI（智能体驱动 UI）」。

## 更新检查

更新 VeADK 文档前后至少检查：

* 公开 API、构造参数、默认值、环境变量和依赖组与目标版本一致。
* 已检查相同源码变更的开放、关闭和已合并文档 PR，并以当前主线为修改基线。
* 已按目标 tag 完成影响清单；Preview 的新能力没有写入较早版本分节或归档。
* 后端页面参数覆盖完整，并包含可运行示例。
* 新增能力已说明安装、配置、示例、限制和安全影响。
* Changelog 新增条目的目标页面实际包含对应能力；归档链接指向对应版本。
* 中英文路径和内容等价。
* 新页面已加入 `docs.json` Preview 导航。
* 已扫描 Preview 中的固定旧版本号，并确认每个版本号属于明确的兼容性或复现场景。
* 内部实现细节、源码路径、内部异常类型和未发布能力未出现在正文。
* 关键示例已经运行或按公开签名核对。


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