[feat/docs] Add zh-cn docs for veadk-python (#1)

* feat: add docs

* fix: add feat/docs to auto deploy workflow

* fix: correct typos in workflow file

* chore: remove github pages deploy deps

* fix: fix doc pages bugs

* fix: fix doc pages bugs

* fix: fix doc pages bugs

* fix: fix doc pages bugs

* fix: add permissions to deploy-docs

* fix: add static base for Github Pages static resource

Author: yaozheng-fang

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,48 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - feat/docs
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yaml'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          npm install
+
+      - name: Build documentation
+        run: |
+          cd docs
+          npm run docs:build
+
+      - name: Upload artifact for GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/docs/.vuepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

docs/docs/.vuepress/config.js

@@ -0,0 +1,22 @@
+import { viteBundler } from '@vuepress/bundler-vite'
+import { defaultTheme } from '@vuepress/theme-default'
+import { defineUserConfig } from 'vuepress'
+
+export default defineUserConfig({
+  lang: 'en-US',
+
+  title: 'Volcengine Agent Development Kit',
+  description: '火山引擎智能体开发框架',
+
+  theme: defaultTheme({
+    logo: '/images/VEADK.png',
+
+    navbar: ['/', '/introduction'],
+
+    sidebar: ['introduction', 'installation', 'get-started', 'agent', 'memory', 'knowledgebase', 'tracing', 'evaluation', 'deploy', 'cli']
+  }),
+
+  bundler: viteBundler(),
+
+  base: '/veadk-python/', // GitHub Pages required
+})

docs/docs/.vuepress/public/images/VEADK.png

@@ -0,0 +1,29 @@
+---
+home: true
+title: VeADK
+heroImage: /images/VEADK.png
+actions:
+  - text: 使用文档
+    link: /introduction.html
+    type: primary
+
+  - text: Github
+    link: https://github.com/volcengine/veadk-python
+    type: secondary
+
+features:
+  - title: 更丰富的内置工具
+    details: Builtin工具，例如侧重头条、抖音搜索的web_search等；MCP工具，例如飞书Lark、PromptPilot等
+  - title: 更灵活的功能扩展
+    details: 提供Agent各类组件的基础实现，通过插件方式灵活扩展
+  - title: 更完备的数据管理
+    details: 运行时数据无缝衔接APMPlus、Cozeloop；运行时数据无痛落地为测试数据集文件，可直接在Cozeloop中进行测试
+  - title: 更强大的知识管理
+    details: 知识库支持火山引擎各类现有数据库，例如关系型数据库、键值数据库等
+  - title: 更科学的结果评测
+    details: 提供不确定性Tools（例如搜索类）场景下的测评解决方案，弥补传统仅根据输入输出进行评测而导致评测结果不符合预期的问题
+  - title: 更友好的最佳实践
+    details: 贴近实际工业场景的Samples，例如各类数据库、数据湖读写
+
+footer: Apache 2.0 Licensed | Copyright © 2025-present Beijing Volcano Engine Technology Co., Ltd.
+---

docs/docs/README.md

@@ -0,0 +1,34 @@
+# 智能体
+
+## 属性
+
+Agent中主要包括如下属性：
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| name | str | Agent的名称，即标识符 |
+| description | str | Agent的描述，后续会被构建为系统提示词的一部分；也被用来在A2A协议中进行Agent挑选 |
+| instruction | str | Agent中内置模型的系统提示词 |
+| tools | list | Function call中的工具列表，既可以是本地工具，也可以是MCP工具 |
+| sub_agents | list | 子Agent列表，用于多Agent之间交互 |
+| long_term_memory | Vector database | 长期记忆，后端通常为一个向量数据库（Vector database），能够检索 |
+| knowledgebase | Vector database | 知识库，后端通常为一个向量数据库（Vector database），能够检索 |
+| tracers | list | 追踪器列表，能够定义不同的追踪方式，并在Agent执行完毕后对整体Tracing信息保存至本地 |
+
+## 运行
+
+在生产环境中，我们推荐您使用`Runner`来进行多租户服务：
+
+```python
+from veadk import Agent, Runner
+from veadk.memory.short_term_memory import ShortTermMemory
+
+# Define runner config
+APP_NAME = ""
+USER_ID = ""
+SESSION_ID = ""
+
+agent = Agent()
+runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
+response = await runner.run(messages=prompt, session_id=session_id)
+```

docs/docs/agent.md

@@ -0,0 +1,17 @@
+# 命令行工具Vego
+
+## 提示词优化
+
+主要用来优化系统提示词（System prompt）。
+
+```bash
+vego prompt
+```
+
+## 一键上云部署
+
+可直接将本地项目部署到火山引擎FaaS平台上：
+
+```bash
+vego deploy
+```

docs/docs/cli.md

@@ -0,0 +1,25 @@
+# 部署上云
+
+## Cloud Agent Engine
+
+通过定义一个云引擎，能够将本地Agent工程直接部署至VeFaaS中，并自动启动一个A2A Server。
+
+```python
+engine = CloudAgentEngine()
+cloud_app = engine.deploy(path=..., name=...)
+```
+
+## Cloud App
+
+部署完成后，将返回一个`CloudApp`实例，代表云应用，主要功能包括：
+
+- 发起一个远程会话创建请求
+- 发起一个Agent执行任务/对话任务
+
+```python
+# 创建远程会话
+cloud_app.create_session(user_id=..., session_id=...)
+
+# 发起任务
+cloud_app.invoke(user_id=..., session_id=..., message=...)
+```

docs/docs/deploy.md

@@ -0,0 +1,72 @@
+# 评测
+
+VeADK构建一套完整的自动化Evaluation流程，主要能力包括：
+
+- 运行时数据采集：通过collect_runtime_data开启
+- 测试集文件生成：开启后自动dump到本地
+- 评测：通过不同的evaluator或adk eval命令进行测试
+- 反馈优化：自动根据评测结果（score reason等属性）优化prompts
+
+## 运行时数据采集
+
+```python
+from veadk.evaluation import EvalSetRecorder
+
+# 在希望进行数据dump处初始化一个EvalSetRecorder
+eval_set_recorder = EvalSetRecorder(session_service, eval_set_id)
+
+# dump数据，为Json格式
+dump_path = await eval_set_recorder.dump(app_name, user_id, session_id)
+```
+
+## 评测集文件
+
+评测集文件格式兼容Google Evaluation，详见[评测集文件格式](https://google.github.io/adk-docs/evaluate/#how-evaluation-works-with-the-adk)。
+
+评测集本地保存过程中，均考虑当前会话。下面是一些概念对齐：
+
+- `test_case`：所有对话轮次
+- `invocation`：一轮对话
+
+## 评测器
+
+当前VeADK支持Deepeval评测器，通过如下方式定义：
+
+```python
+from veadk.evaluation.deepeval_evaluator import DeepevalEvaluator
+
+# 当然，你还可以传入`judge_model`等相关信息
+evaluator = DeepevalEvaluator()
+```
+
+## 评测方法
+
+启动标准的评测接口：
+
+```python
+await evaluator.eval(eval_set_file_path=dump_path, metrics=metrics)
+```
+
+其中，输入：
+
+- `eval_set_file_path`：评测集文件路径
+- `metrics`：评测指标
+
+不同的评测指标在不同测试框架中可能不同。
+
+## 数据上报
+
+评测结果可以自动上报至火山引擎的VMP平台，只需要在定义评估器的时候传入Prometheus pushgateway的相关参数：
+
+```python
+from veadk.evaluation.utils.prometheus import PrometheusPushgatewayConfig
+
+# 可以自动从环境变量中读取相关配置
+prometheus_config = PrometheusPushgatewayConfig()
+
+# 传入到评估器中
+evaluator = DeepevalEvaluator(
+    ...,
+    prometheus_config=prometheus_config,
+)
+```

docs/docs/evaluation.md

@@ -0,0 +1,73 @@
+# 快速开始
+
+## 最简Agent
+
+当你设置完环境变量后，你可以创建一个最简单的聊天智能体：
+
+```python
+from veadk import Agent
+
+agent = Agent()
+```
+
+由于某些操作是异步的，因此Agent的运行需要在异步环境中进行：
+
+::: warning
+我们在`Agent`类中提供的`run`方法仅为了本地测试和开发使用，由于该函数位于一个异步与同步函数共存的运行环境，可能会产生不可预知的异常。
+
+因此不建议在生产环境中使用。
+:::
+
+```python
+import asyncio
+
+prompt = "Hello!"
+res = asyncio.run(agent.run(prompt))
+```
+
+## 工具调用
+
+你可以给Agent传入`tools`参数，指定想要调用的工具：
+
+```python
+from veadk import Agent
+
+agent = Agent(
+    tools=[...] # fill with tools
+)
+```
+
+### 内置工具
+
+VeADK中集成了多个火山引擎提供的工具：
+
+- Web search
+- Web scraper 邀测，代码见MCP server
+- Vesearch
+- Lark
+
+此外，还提供多种沙箱工具：
+
+- Computer sandbox
+- Code sandbox
+- Mobile sandbox
+
+### MCP工具
+
+采用如下方式定义一个MCP工具：
+
+```python
+# 以飞书Lark MCP工具为例
+lark_tools = MCPToolset(
+    connection_params=StdioServerParameters(
+        command="npx",
+        args=[...],
+        errlog=None,
+    ),
+)
+```
+
+### 系统工具
+
+- `load_knowledgebase`：检索知识库工具，在你给Agent传入`knowledgebase`参数后，将会自动挂载`load_knowledgebase_tool`工具，Agent将在运行时自主决定何时查询知识库；
+- `load_memory`：检索长期记忆工具，在你给Agent传入`memory`参数后，将会自动挂载`load_memory_tool`工具，Agent将在运行时自主决定何时查询长期记忆。