​

VeADK 文档规范

​

内容范围

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

​

目录与导航

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 等部署说明。

​

页面类型

​

入口页

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

​

安装与快速开始

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

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

​

组件说明

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

​

后端页面

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

​

工具与技能页面

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

​

前端与部署页面

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

​

更新日志

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

​

版本变更工作流

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

​

示例与代码

• 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）」。

​

更新检查

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