feat(docs): refine docs

.github/workflows/deploy-docs.yaml

@@ -36,12 +36,12 @@ jobs:
       - name: Build documentation
         run: |
           cd docs
-          npm run docs:build
+          npx nuxt generate --extends docus
 
       - name: Upload artifact for GitHub Pages
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/docs/.vuepress/dist
+          path: docs/.output/public/
 
       - name: Deploy to GitHub Pages
         id: deploy

.gitignore

@@ -185,4 +185,8 @@ cython_debug/
 **/node_modules/
 
 # 忽略所有 .temp 目录
-**/.temp/
+**/.temp/
+
+**/.nuxt
+**/.data
+**./output

docs/content/1.introduction/.navigation.yml

@@ -0,0 +1,2 @@
+title: 介绍
+icon: false

docs/docs/introduction.md → docs/content/1.introduction/1.overview.md

@@ -1,39 +1,25 @@
-# 介绍
+---
+title: VeADK
+description: 欢迎使用火山引擎智能体框架 VeADK
+navigation:
+  icon: i-lucide-house
+seo:
+  title: Introduction
+  description: Discover how to create, manage, and publish documentation
+    effortlessly with Docus.
+---
 
-## 关于VeADK
+欢迎使用火山引擎智能体框架 **VeADK（Volcengine Agent Development Kit）**，是由[火山引擎](https://www.volcengine.com/)推出的为 Agent 智能体的应用构建提供开发、部署、观测、评测等全流程云原生解决方案。
 
-**VeADK（Volcengine Agent Development Kit）** 是由[火山引擎](https://www.volcengine.com/)推出的一套面向智能体（Agent）开发的全流程框架，旨在为开发者提供一套面向智能体构建、云端部署、评测与优化的全流程开发框架。
+相较于现有的智能体开发框架，具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
 
-VeADK 相较于现有的智能体开发框架，具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
+## 特性
 
-VeADK 各组件与火山引擎相关产品的结合矩阵：
+- **生态兼容**：与 Google ADK 完全兼容
+- **快速部署**：本地项目部署到云端的时延在分钟级别，并提供镜像部署、代码部署等多种部署形式
+- **一证通行**：基于火山引擎AK/SK进行企业级统一密钥管理
 
-| **组件** | **火山引擎产品** | **说明** |
-| :-- | :-- | :-- |
-| 大模型 | [火山方舟](https://www.volcengine.com/product/ark) | 提供各类语言模型、多模态模型的推理服务 |
-| 提示词工程 | [PromptPilot](https://promptpilot.volcengine.com/) | 提供提示词管理、优化能力 |
-| 工具 | [火山方舟大模型生态广场](https://www.volcengine.com/mcp-marketplace) | 提供各类 MCP Server |
-| | [Web search](https://www.volcengine.com/docs/85508/1650263) | 提供公域数据搜索功能 |
-| | [VeSearch](https://www.volcengine.com/docs/85508/1512748) | 提供信息搜索与云端自动整合功能 |
-| | [Web Scraper](https://www.volcengine.com/docs/84296/1545470) | 定制化内容查询（邀测） |
-| | 飞书 Lark | 进行飞书相关操作 |
-| | [AI 数据湖服务 LAS](https://www.volcengine.com/product/las) | 提供数据湖内的海量数据存储与查询能力 |
-| 短期记忆 | [Viking 记忆库](https://www.volcengine.com/docs/84313/1783345) | 提供记忆存储、优化、摘要等功能 |
-| | [火山引擎云数据库 MySQL 版](https://www.volcengine.com/product/rds-mysql) | 记忆存储 |
-| 长期记忆 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 记忆向量化存储和检索 |
-| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 记忆向量化存储和检索 |
-| 知识库 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 知识向量化存储和检索 |
-| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 知识向量化存储和检索 |
-| 可观测 | [应用性能监控全链路版](https://www.volcengine.com/product/apmplus)（APMPlus） | 调用链路观测 |
-| |  [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 调用链路观测 |
-| | [日志服务](https://www.volcengine.com/product/tls) | 调用链路观测、日志存储与检索 |
-| 评测 | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 在线评测 |
-| 云部署 | [火山引擎函数服务](https://www.volcengine.com/product/vefaas) （VeFaaS） | 提供一键上云能力 |
-| | [火山引擎 API 网关](https://www.volcengine.com/product/apig) | 提供鉴权、路由等能力 |
-| | [火山引擎持续交付](https://www.volcengine.com/product/cp) | 提供用户仓库向 VeFaaS 进行基于镜像的持续交付部署 |
-| | [火山引擎镜像仓库](https://www.volcengine.com/product/cr) | 提供用户代码镜像托管维护 |
-
-## VeADK 核心优势
+## 核心能力
 
 ### 更快速的企业级部署
 
@@ -70,37 +56,31 @@ VeADK 各组件与火山引擎相关产品的结合矩阵：
 - 提供贴近实际工业场景的各类开发和部署用例，涵盖数据库访问、数据湖读写、复杂任务编排等多样场景。
 - 提供可直接复用的代码模板与配置示例，帮助开发者快速上手并解决实际业务问题。
 
-## 社区支持
-
-您可以扫描下方二维码，加入 VeADK 讨论群组：
-
-<p align="center">
-  <img src="/images/veadk_group_qrcode.jpg" alt="VeADK 讨论组二维码" width="400" />
-</p>
-
-## 整体方案
-
-在 VeADK 中，智能体的构建与生命周期的管理围绕`Agent`，`Runner`等核心组件进行：
-
-### Agent
+## 火山引擎生态
 
-`Agent`是智能体的主体，基于大模型处理用户输入，调用不同的组件及各类工具，最终返回给用户结果。
-
-### Runner
-
-`Runner`是智能体的执行器，负责智能体运行时的生命周期管理。
-
-在多租场景下，`Runner`通过三个属性来确定资源空间：
-
-- `app_name`：应用名称
-- `user_id`：用户ID
-- `session_id`：某个用户某次会话的ID
-
-VeADK 的组件会利用这三个属性来构建某些数据的索引，例如知识库组件将会根据`app_name`与`user_id`来进行空间数据的索引，实现多租场景下数据空间的安全隔离。
-
-## Milestone
+VeADK 各组件与火山引擎相关产品的结合矩阵：
 
-| 时间节点 | 事件 |
-| --- | --- |
-| 2025/08/01 | V0.1.0 版本发布 |
-| 2025/08/14 | V0.2.1 版本发布 |
+| **组件** | **火山引擎产品** | **说明** |
+| :-- | :-- | :-- |
+| 大模型 | [火山方舟](https://www.volcengine.com/product/ark) | 提供各类语言模型、多模态模型的推理服务 |
+| 提示词工程 | [PromptPilot](https://promptpilot.volcengine.com/) | 提供提示词管理、优化能力 |
+| 工具 | [火山方舟大模型生态广场](https://www.volcengine.com/mcp-marketplace) | 提供各类 MCP Server |
+| | [Web search](https://www.volcengine.com/docs/85508/1650263) | 提供公域数据搜索功能 |
+| | [VeSearch](https://www.volcengine.com/docs/85508/1512748) | 提供信息搜索与云端自动整合功能 |
+| | [Web Scraper](https://www.volcengine.com/docs/84296/1545470) | 定制化内容查询（邀测） |
+| | 飞书 Lark | 进行飞书相关操作 |
+| | [AI 数据湖服务 LAS](https://www.volcengine.com/product/las) | 提供数据湖内的海量数据存储与查询能力 |
+| 短期记忆 | [Viking 记忆库](https://www.volcengine.com/docs/84313/1783345) | 提供记忆存储、优化、摘要等功能 |
+| | [火山引擎云数据库 MySQL 版](https://www.volcengine.com/product/rds-mysql) | 记忆存储 |
+| 长期记忆 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 记忆向量化存储和检索 |
+| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 记忆向量化存储和检索 |
+| 知识库 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 知识向量化存储和检索 |
+| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 知识向量化存储和检索 |
+| 可观测 | [应用性能监控全链路版](https://www.volcengine.com/product/apmplus)（APMPlus） | 调用链路观测 |
+| |  [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 调用链路观测 |
+| | [日志服务](https://www.volcengine.com/product/tls) | 调用链路观测、日志存储与检索 |
+| 评测 | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 在线评测 |
+| 云部署 | [火山引擎函数服务](https://www.volcengine.com/product/vefaas) （VeFaaS） | 提供一键上云能力 |
+| | [火山引擎 API 网关](https://www.volcengine.com/product/apig) | 提供鉴权、路由等能力 |
+| | [火山引擎持续交付](https://www.volcengine.com/product/cp) | 提供用户仓库向 VeFaaS 进行基于镜像的持续交付部署 |
+| | [火山引擎镜像仓库](https://www.volcengine.com/product/cr) | 提供用户代码镜像托管维护 |

docs/content/1.introduction/2.installation.md

@@ -0,0 +1,116 @@
+---
+title: 安装
+description: VeADK安装方式
+navigation:
+  icon: i-lucide-download
+---
+
+## 从 PyPI 安装
+
+您可以直接使用 Python 包管理工具 `pip` 从 [PyPI 平台](https://pypi.org/project/veadk-python/) 来安装 `veadk-python`：
+
+:::code-group
+
+```bash [最新稳定版]
+pip install veadk-python
+```
+
+```bash [指定版本]
+pip install veadk-python==0.2.7
+```
+
+:::
+
+<!-- 如果您使用知识库、长期记忆等进阶功能，请进一步安装 `veadk-python` 中的扩展包：
+
+```bash [Terminal]
+pip install veadk-python[extensions]
+``` -->
+
+## 从源码构建
+
+::steps
+
+### 下载源码至本地
+
+将VeADK的代码包从Github下载到本地：
+
+```bash [Terminal]
+git clone https://github.com/volcengine/veadk-python.git
+
+cd veadk-python
+```
+
+### 配置 `uv` 环境
+
+本项目使用 `uv` 进行构建，了解如何（[安装 `uv`](https://docs.astral.sh/uv/getting-started/installation/)）。
+
+创建 `uv` 虚拟环境：
+
+```bash [Terminal]
+# 选择 3.10 及以上版本
+uv venv --python 3.10
+```
+
+激活 `uv` 虚拟环境：
+
+:::code-group
+
+```bash [Linux]
+source .venv/bin/activate
+```
+
+```bash [MacOS]
+source .venv/bin/activate
+```
+
+```bash [Windows CMD]
+.venv\Scripts\activate.bat
+```
+
+```bash [Windows PowerShell]
+.venv\Scripts\Activate.ps1
+```
+
+:::
+
+### 安装 VeADK
+
+```bash [Terminal]
+uv pip install .
+
+# 或以本地可编辑模式安装
+# uv pip install -e .
+```
+
+::
+
+## 贡献代码
+
+我们接受对`veadk-python`的能力扩展或 BUG 修复贡献，请按照以下方式进行代码贡献：
+
+::steps
+
+### 从源码构建、安装
+
+请参考[这里](#从源码构建)。
+
+### 开发
+
+依照开发规范文档进行开发（即将上线）。
+
+### 安装 `pre-commit`
+
+`pre-commit` 将在您提交代码前进行一系列检查，例如代码格式规范检查、密钥泄漏检查等。未使用 `pre-commit` 检查过的提交将不会通过 Github 中的 CI/CD 工作流检查，这意味着代码将不会被合并。
+
+```bash [Terminal]
+pip install pre-commit
+
+pre-commit install .
+```
+
+### 等待代码审查
+
+您提交的代码贡献将会在 1 至 2 个工作日内被处理。
+
+::

docs/content/1.introduction/3.quickstart.md

@@ -0,0 +1,37 @@
+---
+title: 快速开始
+description: 构建您的第一个智能体
+navigation:
+  icon: i-lucide-rocket
+---
+
+我们提供了一个供您完整体验 VeADK 核心功能的[教程](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb)（基于 Jupyter Notebook），或者您也可以直接在 [Google Colab](https://colab.research.google.com/github/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) 中打开。
+
+通过 VeADK，您可以构建一个简易智能体：
+
+::steps
+
+### Agent 文件
+
+```python [agent.py]
+import asyncio
+
+from veadk import Agent
+
+agent = Agent()
+asyncio.run(agent.run("Hello world!"))
+```
+
+### 执行
+
+您需要通过环境变量方式，来设置能够调用大模型的 API Key 或者其它身份验证信息。
+
+```bash [Terminal]
+# 通过 API Key
+MODEL_AGENT_API_KEY=... python agent.py
+
+# 通过火山引擎 AK/SK
+VOLCENGINE_ACCESS_KEY=... VOLCENGINE_SECRET_KEY=... python agent.py
+```
+
+::

docs/content/1.introduction/4.troubleshooting.md

@@ -0,0 +1,26 @@
+---
+title: Troubleshooting
+description: 安装、运行以及使用中的各类常见问题汇总
+navigation:
+  icon: i-lucide-wrench
+---
+
+## 安装
+
+1. **使用知识库时，提示未找到 `llama-index` 等包**
+   - 请使用 `pip install veadk-python[extensions]` 安装扩展包。
+
+## 配置
+
+1. **设置火山引擎 AK/SK 后，提示获取模型 API Key 失败**
+   - VeADK 不会帮助您自动创建火山引擎方舟平台 API Key，请先在平台创建。
+
+## 使用
+
+1. **是否兼容 Google ADK**
+   - 是
+
+## 部署
+
+1. **卡在 release 阶段**
+   - 请先在 VeFaaS 平台开通权限。

docs/content/2.configurations/.navigation.yml

@@ -0,0 +1 @@
+title: 配置

docs/content/2.configurations/1.system.md

@@ -0,0 +1,34 @@
+---
+title: 配置管理系统
+description: 实现自动身份管理、云上资源设施管理等
+navigation:
+  icon: i-lucide-heading-1
+---
+
+VeADK 内置了一套配置管理系统，您能够通过定义一个 `config.yaml` 文件来管理您的各项配置。文件中的配置项将会在运行时被自动加载为对应的环境变量。
+
+为管理配置项，VeADK 提供了根据 `config.yaml` 文件的自动化配置管理方案。您在配置文件中的所有配置将会根据层级，自动转为大写并使用下划线连接，统一注册成为运行时的环境变量。
+
+例如下面的配置项：
+
+```yaml [config.yaml]
+model:
+  name:
+  api_key:
+  api_base:
+    base_a:
+    base_b:
+    ...
+```
+
+将会被转为如下几条环境变量：
+
+```bash
+MODEL_NAME=
+MODEL_API_KEY=
+MODEL_API_BASE_BASE_A=
+MODEL_API_BASE_BASE_B=
+...
+```
+
+VeADK 中提供了 `getenv` 方法来读取相关配置，您无需在各组件中次手动传入某个配置的参数。