add documents

Author: yaozheng-fang

docs/content/3.agent/3.agent-builder.md

@@ -9,7 +9,7 @@ navigation:
 
 您可以通过一个 Agent 配置文件来构建 Agent 运行时实例，准备如下项目：
 
-::code-tree{default-value="config.yaml"}
+::code-tree{default-value="agent.yaml"}
 
 ```yaml [agent.yaml]
 root_agent:
@@ -48,7 +48,23 @@ print(response)
 
 其中，每个 `agent` 的 `type` 负责指定 Agent 的类型。
 
-可以通过如下代码来实例化这个 Agent:
+可以通过如下代码来实例化这个 Agent：
+
+```python
+import asyncio
+
+from veadk.agent_builder import AgentBuilder
+from veadk.runner import Runner
+
+agent_builder = AgentBuilder()
+
+agent = agent_builder.build(path="agent.yaml")
+
+runner = Runner(agent=agent)
+response = asyncio.run(runner.run("北京天气"))
+
+print(response)
+```
 
 ## 参数定义
 

docs/content/5.tools/1.builtin-tools.md

@@ -14,15 +14,16 @@ VeADK 中集成了多个火山引擎提供的工具：
 | [`web_search`](https://www.volcengine.com/docs/85508/1650263) | 公域搜索 | `from veadk.tools.builtin_tools.web_search import web_search` |
 | [`web_scraper`](https://www.volcengine.com/docs/84296/1545470) | 聚合搜索（邀测阶段），代码见[这里](https://github.com/volcengine/mcp-server/tree/main/server) | `from veadk.tools.builtin_tools.web_scraper import web_scraper` |
 | [`vesearch`](https://www.volcengine.com/docs/85508/1512748) | 联网搜索，头条搜索等 | `from veadk.tools.builtin_tools.vesearch import vesearch` |
-| | | |
-| | | |
-
-## 使用
+| [`image_generate`](https://www.volcengine.com/docs/82379/1541523) | 图片生成 | `from veadk.tools.builtin_tools.image_generate import image_generate` |
+| [`image_edit`](https://www.volcengine.com/docs/82379/1541523) | 图片编辑（图生图） | `from veadk.tools.builtin_tools.image_edit import image_edit` |
+| [`video_generate`](https://www.volcengine.com/docs/82379/1520757) | 视频生成 | `from veadk.tools.builtin_tools.video_generate import video_generate` |
 
 ::note
 使用 `vesearch` 前，请先在火山引擎控制台创建一个搜索智能体，并获取其 Endpoint。
 ::
 
+## 使用
+
 以下示例展示了如何在 VeADK 中集成并调用内置工具 `web_search`，用于获取今天的三条热点新闻：
 
 ```python [agent.py]
@@ -47,5 +48,5 @@ print(response)
 
 ## 系统工具
 
-- `load_knowledgebase`：检索知识库工具，在你给 Agent 传入`knowledgebase`参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询知识库；
-- `load_memory`：检索长期记忆工具，在你给 Agent 传入`long_term_memory`参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询长期记忆。
+- `load_knowledgebase`：检索知识库工具，在你给 Agent 传入 `knowledgebase` 参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询知识库；
+- `load_memory`：检索长期记忆工具，在你给 Agent 传入 `long_term_memory` 参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询长期记忆。

docs/content/6.memory/1.overview.md

@@ -1,8 +1,8 @@
 ---
-title: 记忆功能概述
+title: 概述
 description: 智能体上下文的重要组成部分
 navigation:
-  icon: i-lucide-zap
+  icon: i-lucide-file
 ---
 
 在 VeADK 中，记忆（memory）能够为 Agent 提供上下文支撑，主要分为短期记忆和长期记忆：

docs/content/6.memory/2.short-term-memory.md

@@ -10,20 +10,58 @@ navigation:
 VeADK 通过以下方式定义一个短期记忆（在不进行特殊指定的情况下，记忆默认将会在内存中存储）：
 
 ```python [memory.py]
-from veadk.memory.short_term_memory import ShortTermMemory
+import asyncio
 
-# 创建短期记忆
-short_term_memory = ShortTermMemory()
+from veadk import Agent
+from veadk.memory import ShortTermMemory
+from veadk.runner import Runner
 
-# 在短期记忆中创建一个会话
-await short_term_memory.create_session(
-  app_name=app_name, user_id=user_id, session_id=session_id
-)
+short_term_memory = ShortTermMemory(backend="local")
+agent = Agent(short_term_memory=short_term_memory)
 
-# 获取会话服务
-session_service = short_term_memory.session_service
-```
+runner = Runner(agent=agent)
+
+response = asyncio.run(runner.run("北京天气"))
 
-## 参数
+print(response)
+```
 
 ## 后端适配
+
+通过设置初始化 `ShortTermMemory` 时的 `backend` 参数来指定不同的短期记忆存储后端：
+
+| 类别 | 说明 |
+| :- | :- |
+| `local` | 内存短期记忆，程序结束后即清空 |
+| `mysql` | 使用 MySQL 数据库存储短期记忆，可实现持久化 |
+| `sqlite` | 使用本地 SQLite 数据库存储短期记忆，可实现持久化 |
+| `postgresql` | 使用 PostgreSQL 数据库存储短期记忆，可实现持久化 |
+| `database` | 已废弃，设置后将会自动转为 `sqlite` |
+
+::warning
+后端选项 `database` 已废弃。
+::
+
+## 详细参数
+
+::field-group
+  ::field{name="backend" type="Literal['local','mysql','sqlite','postgresql','database']"}
+  默认 `local` - 短期记忆后端，`local` 表示内存存储，`mysql` 表示 MySQL/PostgreSQL 存储，`sqlite` 表示 SQLite 存储。
+  ::
+
+  ::field{name="backend_configs" type="dict"}
+  后端特定配置。默认空字典。
+  ::
+
+  ::field{name="db_url" type="string"}
+  数据库连接 URL，例如 `sqlite:///./test.db`。最高优先级，设置后会覆盖 `backend` 参数。
+  ::
+
+  ::field{name="local_database_path" type="string"}
+  本地数据库路径，仅在 `backend` 为 `sqlite` 时使用。默认 `/tmp/veadk_local_database.db`。
+  ::
+
+  ::field{name="after_load_memory_callback" type="Callable | None"}
+  加载后端记忆后调用的回调函数。回调函数接收 `Session` 作为输入。默认 `None`。
+  ::
+::

docs/content/6.memory/3.long-term-memory.md

@@ -12,29 +12,10 @@ VeADK 的长期记忆通常存储在数据库中，通过如下方式定义一
 ```python
 from veadk.memory.long_term_memory import LongTermMemory
 
-long_term_memory = LongTermMemory(backend=...) # 默认的数据库为`opensearch`
-
-# 装配到Agent中，同时会自动挂载`load_memory_tool`工具
-agent = Agent(long_term_memory=long_term_memory)
-
-# 运行时可选将某个session存储到长期记忆中
-session = await session_service.get_session(
-    app_name=app_name,
-    user_id=user_id,
-    session_id=session_id,
-) # 获取当前session
-await self.long_term_memory.add_session_to_memory(session) # 添加
+long_term_memory = LongTermMemory()
 ```
 
-长期记忆中的 backend 字段定义如下：
-
-| backend | 说明 |
-| --- | --- |
-| local | GIGO 模式的内存存储，不具备向量检索功能，仅用于测试 |
-| viking | 火山引擎 [Viking 记忆库](https://www.volcengine.com/docs/84313/1783345)服务 |
-| opensearch | OpenSearch 数据库 |
-| redis | Redis 数据库，但不具备向量搜索功能 |
-| mysql | MySQL 数据库，但不具备向量搜索功能 |
+通过如下例子说明长期记忆：
 
 以下示例展示了如何在 VeADK 中使用长期记忆实现跨会话的信息保留与调用。开发者可以通过 `save_session_to_long_term_memory` 方法，将某一会话中的知识性信息存入长期记忆存储后端。在新的会话中，即使上下文为空，Agent 依然能够基于长期记忆准确回忆并回答相关问题。
 
@@ -66,3 +47,43 @@ student_prompt = "..."
 response = await runner.run(messages=student_prompt, session_id=new_session_id)
 print(response)
 ```
+
+## 后端适配
+
+通过设置初始化 `LongTermMemory` 时的 `backend` 参数来指定不同的长期记忆存储后端：
+
+| 类别 | 说明 |
+| :- | :- |
+| `local` | 内存跨 Session 记忆，程序结束后即清空 |
+| `opensearch` | 使用 OpenSearch 作为长期记忆存储，可实现持久化和检索 |
+| `redis` | 使用 Redis 作为长期记忆存储，Redis 需要支持 Redisearch 功能 |
+| `viking` | 使用 VikingDB 记忆库产品作为长期记忆存储 |
+| `viking_mem` | 已废弃，设置后将会自动转为 `viking` |
+
+::warning
+后端选项 `database` 已废弃。
+::
+
+## 详细参数
+
+::field-group
+  ::field{name="backend" type="Literal['local','opensearch','redis','viking','viking_mem'] | BaseLongTermMemoryBackend"}
+  默认为`opensearch` - 长期记忆后端类型
+  ::
+
+  ::field{name="backend_config" type="dict"}
+  长期记忆后端配置，默认空字典。
+  ::
+
+  ::field{name="top_k" type="int"}
+  默认 5 - 检索时返回最相似的文档数量。
+  ::
+
+  ::field{name="app_name" type="string"}
+  Agent 应用名称，用于多应用区分。默认空字符串。
+  ::
+
+  ::field{name="user_id" type="string"}
+  Agent 用户 ID，用于区分不同用户的长期记忆。默认空字符串。
+  ::
+::

docs/content/8.observation/1.tracing.md

@@ -2,10 +2,9 @@
 title: 数据追踪
 description: 火山引擎云平台提供了多种 Tracing 平台
 navigation:
-  icon: i-lucide-code-xml
+  icon: i-lucide-eye
 ---
 
-
 VeADK 提供可观测（Tracing）的能力，用于记录 Agent 执行过程中的关键路径与中间状态。支持将 Trace 数据输出至本地文件，或通过不同的 Exporter 上报至火山引擎平台，包括 CozeLoop、APMPlus、TLS，有助于开发者进行调试、性能分析、行为追踪等任务。
 
 ## 本地观测

docs/content/8.observation/2.evaluation.md

@@ -2,7 +2,7 @@
 title: 评测
 description: 运行、评测、调优闭环支撑，助力 Agent 更加智能
 navigation:
-  icon: i-lucide-code-xml
+  icon: i-lucide-chart-candlestick
 ---
 
 VeADK 构建一套完整的自动化评测（Evaluation）流程，其主要功能包括：

docs/content/9.deploy/1.from-scratch.md

@@ -1,16 +1,16 @@
 ---
 title: 从脚手架开始
-description: Text, title, and styling in standard markdown.
+description: 从零开始创建一个企业级 Agent 模板
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-cloud-upload
 ---
 
 
 #### 初始化
 
 你可以运行`veadk init`命令来初始化一个新的Agent项目：
 
-```bash
+```bash [Terminal]
 $ veadk init
 Welcome use VeADK to create your project. We will generate a `weather-reporter` application for you.
 Local directory name [veadk-cloud-proj]: 

docs/content/9.deploy/2.from-proj.md

@@ -1,8 +1,8 @@
 ---
 title: 部署已有项目
-description: Text, title, and styling in standard markdown.
+description: 将已有 Agent 项目部署到 VeFaaS 平台
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-cloud-upload
 ---
 
 

docs/content/9.deploy/3.from-code.md

@@ -1,8 +1,8 @@
 ---
 title: 代码部署
-description: Text, title, and styling in standard markdown.
+description: 编写代码部署项目
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-cloud-upload
 ---