diff --git a/docs/content/features/autotest.md b/docs/content/analysis/autotest.md
similarity index 100%
rename from docs/content/features/autotest.md
rename to docs/content/analysis/autotest.md
diff --git a/docs/content/features/dashboard.md b/docs/content/analysis/dashboard.md
similarity index 100%
rename from docs/content/features/dashboard.md
rename to docs/content/analysis/dashboard.md
diff --git a/docs/content/analysis/evaluation.md b/docs/content/analysis/evaluation.md
new file mode 100644
index 0000000..afe6816
--- /dev/null
+++ b/docs/content/analysis/evaluation.md
@@ -0,0 +1,166 @@
+# 效果评估
+
+效果评估帮助你系统地衡量和改进助手的对话质量。
+
+## 评估维度
+
+### 核心指标
+
+| 指标 | 说明 | 计算方式 |
+|------|------|---------|
+| **解决率** | 用户问题被成功解决的比例 | 已解决 / 总对话数 |
+| **准确率** | 回复内容正确的比例 | 正确回复 / 总回复数 |
+| **满意度** | 用户满意的对话比例 | 满意评价 / 总评价数 |
+| **转人工率** | 需要人工介入的比例 | 转人工数 / 总对话数 |
+
+### 性能指标
+
+| 指标 | 说明 | 建议值 |
+|------|------|--------|
+| **首次响应时间** | 用户输入到首次回复的时间 | < 2s |
+| **平均对话轮次** | 解决问题需要的平均轮数 | < 5 轮 |
+| **平均对话时长** | 单次对话的平均时长 | 视场景而定 |
+
+## 配置评估标准
+
+在助手配置中设置评估标准：
+
+### 解决标准
+
+定义什么情况视为"问题已解决"：
+
+```
+评估标准：solved_inquiry
+描述：用户的问题得到了满意的解答
+
+成功条件：
+- 用户明确表示问题已解决
+- 用户表示感谢并结束对话
+- 用户获得了所需信息
+
+失败条件：
+- 用户要求转人工
+- 用户多次重复相同问题
+- 用户表达不满
+```
+
+### 质量标准
+
+定义回复质量的评估维度：
+
+```
+评估维度：
+1. 准确性 - 信息是否正确
+2. 完整性 - 是否回答了用户所有问题
+3. 相关性 - 回复是否切题
+4. 简洁性 - 是否避免了冗余信息
+5. 语气 - 是否保持了友好专业的态度
+```
+
+## 数据收集
+
+### 自动收集
+
+系统自动收集以下数据：
+
+- 对话内容和时间戳
+- 工具调用记录
+- 错误和异常
+- 转人工事件
+
+### 用户反馈
+
+配置用户反馈收集：
+
+1. 对话结束后显示满意度评价
+2. 收集用户评分（1-5 分）
+3. 可选的文字反馈
+
+### 数据提取
+
+配置需要从对话中提取的信息：
+
+```
+数据提取项：
+
+1. user_intent
+   描述：用户的主要意图
+   类型：string
+
+2. issue_category
+   描述：问题分类
+   类型：enum [产品问题, 订单问题, 技术问题, 其他]
+
+3. resolution_status
+   描述：解决状态
+   类型：enum [已解决, 未解决, 转人工]
+```
+
+## 评估报告
+
+### 查看报告
+
+在 **数据分析** > **效果评估** 页面查看：
+
+1. **总体概览** - 核心指标趋势图
+2. **分类分析** - 按问题类型的评估结果
+3. **时段分析** - 不同时间段的表现
+4. **详细记录** - 单条对话的评估结果
+
+### 报告示例
+
+```
+评估报告 - 2025年1月
+
+总对话数：1,234
+解决率：78.5%
+准确率：85.2%
+平均满意度：4.2/5
+转人工率：12.3%
+
+问题分类分布：
+- 产品问题：45%
+- 订单问题：30%
+- 技术问题：15%
+- 其他：10%
+
+改进建议：
+1. 订单问题解决率较低（65%），建议补充订单相关知识库
+2. 技术问题转人工率高（25%），建议增加技术支持工具
+```
+
+## 持续改进
+
+### 改进流程
+
+1. **收集数据** - 持续收集对话和评估数据
+2. **分析问题** - 找出低分对话的共性
+3. **制定方案** - 针对问题制定改进措施
+4. **实施改进** - 更新提示词、知识库或工具
+5. **验证效果** - 观察改进后的指标变化
+
+### 常见改进措施
+
+| 问题 | 改进措施 |
+|------|---------|
+| 回复不准确 | 优化提示词，补充知识库 |
+| 无法理解问题 | 增加示例，优化 ASR 热词 |
+| 回复太长 | 在提示词中限制长度 |
+| 缺少专业知识 | 上传相关文档到知识库 |
+| 工具调用失败 | 检查工具配置和 API 状态 |
+
+### A/B 测试
+
+对比不同配置的效果：
+
+1. 创建助手的变体版本
+2. 按比例分配流量
+3. 收集两个版本的评估数据
+4. 比较各项指标
+5. 选择效果更好的版本
+
+## 下一步
+
+- [自动化测试](autotest.md) - 批量测试助手
+- [历史记录](history.md) - 查看对话详情
+- [提示词指南](../assistants/prompts.md) - 优化提示词
diff --git a/docs/content/features/history.md b/docs/content/analysis/history.md
similarity index 100%
rename from docs/content/features/history.md
rename to docs/content/analysis/history.md
diff --git a/docs/content/api-reference.md b/docs/content/api-reference.md
deleted file mode 100644
index d1a4366..0000000
--- a/docs/content/api-reference.md
+++ /dev/null
@@ -1,299 +0,0 @@
-# API 参考
-
-本节提供 AI Video Assistant 的 API 接口文档，包括 WebSocket 实时通信协议和后端 REST API。
-
----
-
-## WebSocket 实时通信
-
-WebSocket 端点提供双向实时语音对话能力，支持音频流输入输出和文本消息交互。
-
-### 连接地址
-
-```
-ws://<host>/ws?assistant_id=<assistant_id>
-```
-
-- `assistant_id` 为必填 query 参数，用于从数据库加载该助手的运行时配置。
-
-### 传输规则
-
-- **文本帧**：JSON 格式控制消息
-- **二进制帧**：PCM 音频数据（`pcm_s16le`, 16kHz, 单声道）
-- 帧长度必须是 640 字节的整数倍（20ms 音频 = 640 bytes）
-
----
-
-### 消息流程
-
-```
-Client -> session.start
-Server <- session.started
-Server <- config.resolved
-Client -> (binary pcm frames...)
-Server <- input.speech_started / transcript.delta / transcript.final
-Server <- assistant.response.delta / assistant.response.final
-Server <- output.audio.start
-Server <- (binary pcm frames...)
-Server <- output.audio.end
-Client -> session.stop
-Server <- session.stopped
-```
-
----
-
-### 客户端 -> 服务端消息
-
-#### 1. Session Start: `session.start`
-
-客户端连接后发送的第一个消息，用于启动对话会话。
-
-```json
-{
-  "type": "session.start",
-  "audio": {
-    "encoding": "pcm_s16le",
-    "sample_rate_hz": 16000,
-    "channels": 1
-  },
-  "metadata": {
-    "channel": "web",
-    "source": "web_debug",
-    "history": {
-      "userId": 1
-    },
-    "overrides": {
-      "systemPrompt": "你是简洁助手",
-      "greeting": "你好，我能帮你什么？",
-      "output": {
-        "mode": "audio"
-      }
-    },
-    "dynamicVariables": {
-      "customer_name": "Alice",
-      "plan_tier": "Pro"
-    }
-  }
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `type` | string | 是 | 固定为 `"session.start"` |
-| `audio` | object | 否 | 音频格式描述 |
-| `audio.encoding` | string | 否 | 固定为 `"pcm_s16le"` |
-| `audio.sample_rate_hz` | number | 否 | 固定为 `16000` |
-| `audio.channels` | number | 否 | 固定为 `1` |
-| `metadata` | object | 否 | 运行时配置 |
-
-**metadata 支持的字段**：
-- `channel` - 渠道标识
-- `source` - 来源标识
-- `history.userId` - 历史记录用户 ID
-- `overrides` - 可覆盖字段（仅限安全白名单）
-- `dynamicVariables` - 动态变量（支持 `{{variable}}` 占位符）
-
-**`metadata.overrides` 白名单字段**：
-- `systemPrompt`
-- `greeting`
-- `firstTurnMode`
-- `generatedOpenerEnabled`
-- `output`
-- `bargeIn`
-- `knowledgeBaseId`
-- `knowledge`
-- `tools`
-- `openerAudio`
-
-**限制**：
-- `metadata.workflow` 会被忽略（不触发 workflow 事件）
-- 禁止提交 `metadata.services`
-- 禁止提交 `assistantId` / `appId` / `app_id` / `configVersionId` / `config_version_id`
-- 禁止提交包含密钥语义的字段（如 `apiKey` / `token` / `secret` / `password` / `authorization`）
-
----
-
-#### 2. Text Input: `input.text`
-
-发送文本输入，跳过 ASR 识别，直接触发 LLM 回复。
-
-```json
-{
-  "type": "input.text",
-  "text": "你能做什么？"
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `type` | string | 是 | 固定为 `"input.text"` |
-| `text` | string | 是 | 用户文本内容 |
-
----
-
-#### 3. Response Cancel: `response.cancel`
-
-请求中断当前回答。
-
-```json
-{
-  "type": "response.cancel",
-  "graceful": false
-}
-```
-
-| 字段 | 类型 | 必填 | 默认值 | 说明 |
-|---|---|---|---|---|
-| `type` | string | 是 | - | 固定为 `"response.cancel"` |
-| `graceful` | boolean | 否 | `false` | `false` 立即打断 |
-
----
-
-#### 4. Tool Call Results: `tool_call.results`
-
-回传客户端执行的工具结果。
-
-```json
-{
-  "type": "tool_call.results",
-  "results": [
-    {
-      "tool_call_id": "call_abc123",
-      "name": "weather",
-      "output": { "temp_c": 21, "condition": "sunny" },
-      "status": { "code": 200, "message": "ok" }
-    }
-  ]
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `type` | string | 是 | 固定为 `"tool_call.results"` |
-| `results` | array | 否 | 工具结果列表 |
-| `results[].tool_call_id` | string | 是 | 工具调用 ID |
-| `results[].name` | string | 是 | 工具名称 |
-| `results[].output` | any | 否 | 工具输出 |
-| `results[].status` | object | 是 | 执行状态 |
-
----
-
-#### 5. Session Stop: `session.stop`
-
-结束对话会话。
-
-```json
-{
-  "type": "session.stop",
-  "reason": "client_disconnect"
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `type` | string | 是 | 固定为 `"session.stop"` |
-| `reason` | string | 否 | 结束原因 |
-
----
-
-#### 6. Binary Audio
-
-在 `session.started` 之后可持续发送二进制 PCM 音频。
-
-- **格式**：`pcm_s16le`
-- **采样率**：16000 Hz
-- **声道**：1（单声道）
-- **帧长**：20ms = 640 bytes
-
----
-
-### 服务端 -> 客户端事件
-
-#### 事件包络
-
-所有 JSON 事件都包含统一包络字段：
-
-```json
-{
-  "type": "event.name",
-  "timestamp": 1730000000000,
-  "sessionId": "sess_xxx",
-  "seq": 42,
-  "source": "asr",
-  "trackId": "audio_in",
-  "data": {}
-}
-```
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `type` | string | 事件类型 |
-| `timestamp` | number | 事件时间戳（毫秒） |
-| `sessionId` | string | 会话 ID |
-| `seq` | number | 递增序号 |
-| `source` | string | 事件来源 (`asr`/`llm`/`tts`/`tool`) |
-| `trackId` | string | 事件轨道 (`audio_in`/`audio_out`/`control`) |
-| `data` | object | 业务数据 |
-
----
-
-#### 会话控制类事件
-
-| 事件 | 说明 |
-|---|---|
-| `session.started` | 会话启动成功 |
-| `config.resolved` | 服务端最终配置快照 |
-| `heartbeat` | 保活心跳（默认 50 秒间隔） |
-| `session.stopped` | 会话结束确认 |
-| `error` | 统一错误事件 |
-
----
-
-#### ASR 识别事件
-
-| 事件 | 字段 | 说明 |
-|---|---|---|
-| `input.speech_started` | `probability` | 检测到语音开始 |
-| `input.speech_stopped` | `probability` | 检测到语音结束 |
-| `transcript.delta` | `text` | ASR 增量识别文本 |
-| `transcript.final` | `text` | ASR 最终识别文本 |
-
----
-
-#### LLM/TTS 输出事件
-
-| 事件 | 字段 | 说明 |
-|---|---|---|
-| `assistant.response.delta` | `text` | 助手增量文本输出 |
-| `assistant.response.final` | `text` | 助手完整文本输出 |
-| `assistant.tool_call` | `tool_call_id`, `tool_name`, `arguments` | 工具调用通知 |
-| `assistant.tool_result` | `tool_call_id`, `ok`, `result` | 工具执行结果 |
-| `output.audio.start` | - | TTS 音频开始 |
-| `output.audio.end` | - | TTS 音频结束 |
-| `response.interrupted` | - | 回答被打断 |
-| `metrics.ttfb` | `latencyMs` | 首包音频时延 |
-
----
-
-### 错误码
-
-| 错误码 | 说明 |
-|---|---|
-| `protocol.invalid_json` | JSON 格式错误 |
-| `protocol.invalid_message` | 消息格式错误 |
-| `protocol.order` | 消息顺序错误 |
-| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 |
-| `protocol.invalid_override` | metadata 覆盖字段不合法 |
-| `assistant.not_found` | assistant 不存在 |
-| `assistant.config_unavailable` | assistant 配置不可用 |
-| `audio.invalid_pcm` | PCM 数据无效 |
-| `audio.frame_size_mismatch` | 音频帧大小不匹配 |
-| `server.internal` | 服务端内部错误 |
-
----
-
-### 心跳与超时
-
-- **心跳间隔**：默认 50 秒（`heartbeat_interval_sec`）
-- **空闲超时**：默认 60 秒（`inactivity_timeout_sec`）
-- 客户端应持续发送音频或轻量消息避免被判定闲置
diff --git a/docs/content/api-reference/errors.md b/docs/content/api-reference/errors.md
new file mode 100644
index 0000000..6863e6b
--- /dev/null
+++ b/docs/content/api-reference/errors.md
@@ -0,0 +1,88 @@
+# 错误码
+
+本文档列出 AI Video Assistant API 的所有错误码及其说明。
+
+## 协议错误
+
+| 错误码 | 说明 | 解决方案 |
+|---|---|---|
+| `protocol.invalid_json` | JSON 格式错误 | 检查发送的 JSON 是否合法 |
+| `protocol.invalid_message` | 消息格式错误 | 检查消息结构是否符合协议 |
+| `protocol.order` | 消息顺序错误 | 确保先发送 `session.start` |
+| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 | 在连接 URL 中添加 `assistant_id` 参数 |
+| `protocol.invalid_override` | metadata 覆盖字段不合法 | 检查 overrides 字段是否在白名单内 |
+
+## 助手错误
+
+| 错误码 | 说明 | 解决方案 |
+|---|---|---|
+| `assistant.not_found` | 助手不存在 | 检查 `assistant_id` 是否正确 |
+| `assistant.config_unavailable` | 助手配置不可用 | 确认助手已正确配置并发布 |
+
+## 音频错误
+
+| 错误码 | 说明 | 解决方案 |
+|---|---|---|
+| `audio.invalid_pcm` | PCM 数据无效 | 检查音频格式是否为 `pcm_s16le` |
+| `audio.frame_size_mismatch` | 音频帧大小不匹配 | 确保帧长度是 640 字节的整数倍 |
+
+## 服务器错误
+
+| 错误码 | 说明 | 解决方案 |
+|---|---|---|
+| `server.internal` | 服务端内部错误 | 查看服务端日志排查问题 |
+
+## 错误响应格式
+
+所有错误都通过 `error` 事件返回：
+
+```json
+{
+  "type": "error",
+  "timestamp": 1730000000000,
+  "sessionId": "sess_xxx",
+  "data": {
+    "code": "protocol.invalid_json",
+    "message": "Invalid JSON format",
+    "details": {}
+  }
+}
+```
+
+## HTTP API 错误
+
+REST API 使用标准 HTTP 状态码：
+
+| 状态码 | 说明 |
+|--------|------|
+| 200 | 请求成功 |
+| 201 | 创建成功 |
+| 400 | 请求参数错误 |
+| 401 | 未授权（缺少或无效的认证信息） |
+| 403 | 禁止访问（权限不足） |
+| 404 | 资源不存在 |
+| 422 | 请求实体无法处理 |
+| 500 | 服务器内部错误 |
+
+### HTTP 错误响应示例
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request parameters",
+    "details": {
+      "field": "name",
+      "reason": "required"
+    }
+  }
+}
+```
+
+## 错误处理最佳实践
+
+1. **始终检查错误响应** - 不要假设请求一定成功
+2. **实现重试机制** - 对于临时性错误（如网络问题）实现指数退避重试
+3. **记录错误日志** - 保存错误详情用于问题排查
+4. **友好的用户提示** - 将技术错误转换为用户可理解的提示
diff --git a/docs/content/api-reference/index.md b/docs/content/api-reference/index.md
new file mode 100644
index 0000000..7600383
--- /dev/null
+++ b/docs/content/api-reference/index.md
@@ -0,0 +1,196 @@
+# API 参考
+
+本节提供 AI Video Assistant 的完整 API 文档。
+
+## API 概览
+
+AI Video Assistant 提供两种类型的 API：
+
+| API 类型 | 用途 | 协议 |
+|---------|------|------|
+| **REST API** | 管理助手、模型、知识库等资源 | HTTP |
+| **WebSocket API** | 实时语音对话 | WebSocket |
+
+## REST API
+
+### 基础地址
+
+```
+http://localhost:8080/api/v1
+```
+
+### 认证
+
+REST API 使用 Bearer Token 认证：
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+  http://localhost:8080/api/v1/assistants
+```
+
+### 通用响应格式
+
+**成功响应**
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+**列表响应**
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "total": 100,
+    "page": 1,
+    "page_size": 20
+  }
+}
+```
+
+**错误响应**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "错误描述"
+  }
+}
+```
+
+### 主要端点
+
+#### 助手管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /assistants | 获取助手列表 |
+| POST | /assistants | 创建助手 |
+| GET | /assistants/{id} | 获取助手详情 |
+| PATCH | /assistants/{id} | 更新助手 |
+| DELETE | /assistants/{id} | 删除助手 |
+
+#### 模型管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /llm | 获取 LLM 模型列表 |
+| POST | /llm | 添加 LLM 模型 |
+| GET | /asr | 获取 ASR 模型列表 |
+| POST | /asr | 添加 ASR 模型 |
+| GET | /voices | 获取语音列表 |
+| POST | /voices | 添加语音配置 |
+
+#### 知识库管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /knowledge-bases | 获取知识库列表 |
+| POST | /knowledge-bases | 创建知识库 |
+| POST | /knowledge-bases/{id}/documents | 上传文档 |
+| DELETE | /knowledge-bases/{id}/documents/{doc_id} | 删除文档 |
+
+#### 历史记录
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /history | 获取对话历史 |
+| GET | /history/{id} | 获取对话详情 |
+| GET | /history/stats | 获取统计数据 |
+
+## WebSocket API
+
+### 连接地址
+
+```
+ws://localhost:8000/ws?assistant_id=<assistant_id>
+```
+
+### 协议概述
+
+WebSocket API 使用双向消息通信：
+
+- **文本帧**：JSON 格式的控制消息
+- **二进制帧**：PCM 音频数据
+
+### 详细文档
+
+- [WebSocket 协议](websocket.md) - 完整的消息格式和流程
+- [错误码](errors.md) - 错误码列表和处理方式
+
+## SDK
+
+### JavaScript SDK
+
+```bash
+npm install @ai-video-assistant/sdk
+```
+
+```javascript
+import { AIVideoAssistant } from '@ai-video-assistant/sdk';
+
+const assistant = new AIVideoAssistant({
+  apiUrl: 'http://localhost:8080',
+  wsUrl: 'ws://localhost:8000'
+});
+
+// 创建助手
+const result = await assistant.create({
+  name: '客服助手',
+  prompt: '你是一个友好的客服助手'
+});
+
+// 开始对话
+const conversation = await assistant.connect(result.id);
+conversation.on('response', (text) => {
+  console.log('助手回复:', text);
+});
+```
+
+### Python SDK
+
+```bash
+pip install ai-video-assistant
+```
+
+```python
+from ai_video_assistant import AIVideoAssistant
+
+client = AIVideoAssistant(
+    api_url="http://localhost:8080",
+    ws_url="ws://localhost:8000"
+)
+
+# 创建助手
+assistant = client.assistants.create(
+    name="客服助手",
+    prompt="你是一个友好的客服助手"
+)
+
+# 开始对话
+async with client.connect(assistant.id) as conv:
+    response = await conv.send_text("你好")
+    print(f"助手回复: {response}")
+```
+
+## 速率限制
+
+| 端点类型 | 限制 |
+|---------|------|
+| REST API | 100 请求/分钟 |
+| WebSocket | 10 并发连接/用户 |
+
+超出限制会返回 `429 Too Many Requests`。
+
+## 下一步
+
+- [WebSocket 协议](websocket.md) - 实时对话协议详解
+- [错误码](errors.md) - 错误处理参考
+- [快速开始](../quickstart/api.md) - API 使用示例
diff --git a/docs/content/api-reference/websocket.md b/docs/content/api-reference/websocket.md
new file mode 100644
index 0000000..28d9fb8
--- /dev/null
+++ b/docs/content/api-reference/websocket.md
@@ -0,0 +1,853 @@
+# WebSocket 协议
+
+WebSocket 端点提供双向实时语音对话能力，支持音频流输入输出和文本消息交互。
+
+## 连接地址
+
+```
+ws://<host>/ws?assistant_id=<assistant_id>
+```
+
+- `assistant_id` 为必填 query 参数，用于从数据库加载该助手的运行时配置。
+
+## 传输规则
+
+- **文本帧**：JSON 格式控制消息
+- **二进制帧**：PCM 音频数据（`pcm_s16le`, 16kHz, 单声道）
+- 帧长度必须是 640 字节的整数倍（20ms 音频 = 640 bytes）
+
+---
+
+## 消息流程
+
+```
+Client -> session.start
+Server <- session.started
+Server <- config.resolved
+Client -> (binary pcm frames...)
+Server <- input.speech_started / transcript.delta / transcript.final
+Server <- assistant.response.delta / assistant.response.final
+Server <- output.audio.start
+Server <- (binary pcm frames...)
+Server <- output.audio.end
+Client -> session.stop
+Server <- session.stopped
+```
+
+---
+
+## 客户端 -> 服务端消息
+
+### 1. Session Start: `session.start`
+
+客户端连接后发送的第一个消息，用于启动对话会话。
+
+```json
+{
+  "type": "session.start",
+  "audio": {
+    "encoding": "pcm_s16le",
+    "sample_rate_hz": 16000,
+    "channels": 1
+  },
+  "metadata": {
+    "channel": "web",
+    "source": "web_debug",
+    "history": {
+      "userId": 1
+    },
+    "overrides": {
+      "systemPrompt": "你是简洁助手",
+      "greeting": "你好，我能帮你什么？",
+      "output": {
+        "mode": "audio"
+      }
+    },
+    "dynamicVariables": {
+      "customer_name": "Alice",
+      "plan_tier": "Pro"
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `type` | string | 是 | 固定为 `"session.start"` |
+| `audio` | object | 否 | 音频格式描述 |
+| `audio.encoding` | string | 否 | 固定为 `"pcm_s16le"` |
+| `audio.sample_rate_hz` | number | 否 | 固定为 `16000` |
+| `audio.channels` | number | 否 | 固定为 `1` |
+| `metadata` | object | 否 | 运行时配置 |
+
+**metadata 支持的字段**：
+- `channel` - 渠道标识
+- `source` - 来源标识
+- `history.userId` - 历史记录用户 ID
+- `overrides` - 可覆盖字段（仅限安全白名单）
+- `dynamicVariables` - 动态变量（支持 `{{variable}}` 占位符）
+
+**`metadata.overrides` 白名单字段**：
+- `systemPrompt`
+- `greeting`
+- `firstTurnMode`
+- `generatedOpenerEnabled`
+- `output`
+- `bargeIn`
+- `knowledgeBaseId`
+- `knowledge`
+- `tools`
+- `openerAudio`
+
+**限制**：
+- `metadata.workflow` 会被忽略（不触发 workflow 事件）
+- 禁止提交 `metadata.services`
+- 禁止提交 `assistantId` / `appId` / `app_id` / `configVersionId` / `config_version_id`
+- 禁止提交包含密钥语义的字段（如 `apiKey` / `token` / `secret` / `password` / `authorization`）
+
+---
+
+### 2. Text Input: `input.text`
+
+发送文本输入，跳过 ASR 识别，直接触发 LLM 回复。
+
+```json
+{
+  "type": "input.text",
+  "text": "你能做什么？"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `type` | string | 是 | 固定为 `"input.text"` |
+| `text` | string | 是 | 用户文本内容 |
+
+---
+
+### 3. Response Cancel: `response.cancel`
+
+请求中断当前回答。
+
+```json
+{
+  "type": "response.cancel",
+  "graceful": false
+}
+```
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `type` | string | 是 | - | 固定为 `"response.cancel"` |
+| `graceful` | boolean | 否 | `false` | `false` 立即打断 |
+
+---
+
+### 4. Tool Call Results: `tool_call.results`
+
+回传客户端执行的工具结果。
+
+```json
+{
+  "type": "tool_call.results",
+  "results": [
+    {
+      "tool_call_id": "call_abc123",
+      "name": "weather",
+      "output": { "temp_c": 21, "condition": "sunny" },
+      "status": { "code": 200, "message": "ok" }
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `type` | string | 是 | 固定为 `"tool_call.results"` |
+| `results` | array | 否 | 工具结果列表 |
+| `results[].tool_call_id` | string | 是 | 工具调用 ID |
+| `results[].name` | string | 是 | 工具名称 |
+| `results[].output` | any | 否 | 工具输出 |
+| `results[].status` | object | 是 | 执行状态 |
+| `results[].status.code` | number | 是 | HTTP 状态码（200-299 表示成功） |
+| `results[].status.message` | string | 是 | 状态描述 |
+
+---
+
+### 5. Session Stop: `session.stop`
+
+结束对话会话。
+
+```json
+{
+  "type": "session.stop",
+  "reason": "client_disconnect"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `type` | string | 是 | 固定为 `"session.stop"` |
+| `reason` | string | 否 | 结束原因 |
+
+---
+
+### 6. Binary Audio
+
+在 `session.started` 之后可持续发送二进制 PCM 音频。
+
+- **格式**：`pcm_s16le`
+- **采样率**：16000 Hz
+- **声道**：1（单声道）
+- **帧长**：20ms = 640 bytes
+
+---
+
+## 服务端 -> 客户端事件
+
+### 事件包络
+
+所有 JSON 事件都包含统一包络字段：
+
+```json
+{
+  "type": "event.name",
+  "timestamp": 1730000000000,
+  "sessionId": "sess_xxx",
+  "seq": 42,
+  "source": "asr",
+  "trackId": "audio_in",
+  "data": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `type` | string | 事件类型 |
+| `timestamp` | number | 事件时间戳（Unix 毫秒） |
+| `sessionId` | string | 会话 ID |
+| `seq` | number | 递增序号（用于重放/恢复） |
+| `source` | string | 事件来源：`asr` / `llm` / `tts` / `tool` / `system` / `client` / `server` |
+| `trackId` | string | 事件轨道：`audio_in` / `audio_out` / `control` |
+| `data` | object | 业务数据（可选） |
+
+**轨道 ID 说明**：
+
+| trackId | 说明 | 相关事件 |
+|---------|------|---------|
+| `audio_in` | ASR/VAD 输入侧事件 | `input.*`, `transcript.*` |
+| `audio_out` | 助手输出侧事件 | `assistant.*`, `output.audio.*`, `response.interrupted`, `metrics.ttfb` |
+| `control` | 会话控制事件 | `session.*`, `error`, `config.resolved`, `heartbeat` |
+
+---
+
+### 会话控制类事件
+
+#### `session.started`
+
+会话启动成功，客户端收到此事件后可以开始发送音频。
+
+```json
+{
+  "type": "session.started",
+  "timestamp": 1730000000000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 1,
+  "trackId": "control",
+  "tracks": {
+    "audio_in": "audio_in",
+    "audio_out": "audio_out",
+    "control": "control"
+  },
+  "audio": {
+    "encoding": "pcm_s16le",
+    "sample_rate_hz": 16000,
+    "channels": 1
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sessionId` | string | 会话唯一标识符 |
+| `trackId` | string | 固定为 `"control"` |
+| `tracks` | object | 可用轨道列表 |
+| `tracks.audio_in` | string | 输入轨道 ID |
+| `tracks.audio_out` | string | 输出轨道 ID |
+| `tracks.control` | string | 控制轨道 ID |
+| `audio` | object | 音频格式配置 |
+| `audio.encoding` | string | 编码格式 |
+| `audio.sample_rate_hz` | number | 采样率 |
+| `audio.channels` | number | 声道数 |
+
+---
+
+#### `config.resolved`
+
+服务端最终配置快照，在 `session.started` 后立即发送。
+
+```json
+{
+  "type": "config.resolved",
+  "timestamp": 1730000000001,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 2,
+  "trackId": "control",
+  "config": {
+    "assistantId": "asst_abc123",
+    "configVersionId": "ver_xyz789",
+    "output": {
+      "mode": "audio"
+    },
+    "services": {
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4"
+      },
+      "asr": {
+        "provider": "sensevoice",
+        "model": "paraformer"
+      },
+      "tts": {
+        "provider": "aliyun",
+        "model": "xiaoyun",
+        "enabled": true
+      }
+    },
+    "tools": ["weather", "calculator"]
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"control"` |
+| `config` | object | 已解析的运行时配置 |
+| `config.assistantId` | string | 助手 ID |
+| `config.configVersionId` | string | 配置版本 ID |
+| `config.output` | object | 输出配置 |
+| `config.output.mode` | string | 输出模式：`"audio"` / `"text"` |
+| `config.services` | object | 服务配置（不包含密钥） |
+| `config.tools` | array | 可用工具列表 |
+
+---
+
+#### `heartbeat`
+
+保活心跳事件，默认每 50 秒发送一次。
+
+```json
+{
+  "type": "heartbeat",
+  "timestamp": 1730000050000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 10
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `timestamp` | number | 心跳时间戳 |
+
+---
+
+#### `session.stopped`
+
+会话结束确认。
+
+```json
+{
+  "type": "session.stopped",
+  "timestamp": 1730000100000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 50,
+  "reason": "client_requested"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `reason` | string | 结束原因：`"client_requested"` / `"timeout"` / `"error"` |
+
+---
+
+### ASR 识别事件
+
+#### `input.speech_started`
+
+检测到语音开始（VAD）。
+
+```json
+{
+  "type": "input.speech_started",
+  "timestamp": 1730000010000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 5,
+  "source": "asr",
+  "trackId": "audio_in",
+  "probability": 0.95
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_in"` |
+| `probability` | number | 语音检测置信度（0-1） |
+
+---
+
+#### `input.speech_stopped`
+
+检测到语音结束（VAD）。
+
+```json
+{
+  "type": "input.speech_stopped",
+  "timestamp": 1730000012000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 8,
+  "source": "asr",
+  "trackId": "audio_in",
+  "probability": 0.92
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_in"` |
+| `probability` | number | 静音检测置信度（0-1） |
+
+---
+
+#### `transcript.delta`
+
+ASR 增量识别文本（实时转写）。
+
+```json
+{
+  "type": "transcript.delta",
+  "timestamp": 1730000011000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 6,
+  "source": "asr",
+  "trackId": "audio_in",
+  "text": "你好",
+  "data": {
+    "text": "你好",
+    "turn_id": "turn_001",
+    "utterance_id": "utt_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_in"` |
+| `text` | string | 增量识别文本 |
+| `data.text` | string | 增量识别文本（同 `text`） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+| `data.utterance_id` | string | 当前语句 ID |
+
+**节流说明**：服务端默认每 300ms 合并一次 delta 事件。
+
+---
+
+#### `transcript.final`
+
+ASR 最终识别文本（语句结束）。
+
+```json
+{
+  "type": "transcript.final",
+  "timestamp": 1730000012500,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 9,
+  "source": "asr",
+  "trackId": "audio_in",
+  "text": "你好，请问今天天气怎么样",
+  "data": {
+    "text": "你好，请问今天天气怎么样",
+    "turn_id": "turn_001",
+    "utterance_id": "utt_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_in"` |
+| `text` | string | 最终识别文本 |
+| `data.text` | string | 最终识别文本（同 `text`） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+| `data.utterance_id` | string | 当前语句 ID |
+
+---
+
+### LLM/TTS 输出事件
+
+#### `assistant.response.delta`
+
+助手增量文本输出（流式生成）。
+
+```json
+{
+  "type": "assistant.response.delta",
+  "timestamp": 1730000013000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 12,
+  "source": "llm",
+  "trackId": "audio_out",
+  "text": "今天天气",
+  "data": {
+    "text": "今天天气",
+    "turn_id": "turn_001",
+    "response_id": "resp_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 固定为 `"llm"` |
+| `text` | string | 增量文本内容 |
+| `data.text` | string | 增量文本内容（同 `text`） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+| `data.response_id` | string | 当前回复 ID |
+
+**节流说明**：服务端默认每 80ms 合并一次 delta 事件。
+
+---
+
+#### `assistant.response.final`
+
+助手完整文本输出（回复结束）。
+
+```json
+{
+  "type": "assistant.response.final",
+  "timestamp": 1730000015000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 18,
+  "source": "llm",
+  "trackId": "audio_out",
+  "text": "今天天气晴朗，气温25度，适合外出。",
+  "data": {
+    "text": "今天天气晴朗，气温25度，适合外出。",
+    "turn_id": "turn_001",
+    "response_id": "resp_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 固定为 `"llm"` |
+| `text` | string | 完整回复文本 |
+| `data.text` | string | 完整回复文本（同 `text`） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+| `data.response_id` | string | 当前回复 ID |
+
+---
+
+#### `assistant.tool_call`
+
+工具调用通知，通知客户端 LLM 请求调用工具。
+
+```json
+{
+  "type": "assistant.tool_call",
+  "timestamp": 1730000014000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 14,
+  "source": "llm",
+  "trackId": "audio_out",
+  "tool_call_id": "call_abc123",
+  "tool_name": "weather",
+  "arguments": {
+    "city": "北京"
+  },
+  "executor": "server",
+  "timeout_ms": 30000,
+  "data": {
+    "tool_call": {
+      "id": "call_abc123",
+      "name": "weather",
+      "arguments": "{\"city\":\"北京\"}"
+    },
+    "turn_id": "turn_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 固定为 `"llm"` |
+| `tool_call_id` | string | 工具调用唯一 ID |
+| `tool_name` | string | 工具名称 |
+| `arguments` | object | 工具参数（已解析的 JSON） |
+| `executor` | string | 执行方：`"server"` 服务端执行 / `"client"` 客户端执行 |
+| `timeout_ms` | number | 超时时间（毫秒） |
+| `data.tool_call` | object | 原始工具调用信息 |
+| `data.tool_call.id` | string | 工具调用 ID |
+| `data.tool_call.name` | string | 工具名称 |
+| `data.tool_call.arguments` | string | 工具参数（JSON 字符串） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+
+**注意**：当 `executor = "client"` 时，客户端需要执行工具并返回 `tool_call.results`。
+
+---
+
+#### `assistant.tool_result`
+
+工具执行结果通知。
+
+```json
+{
+  "type": "assistant.tool_result",
+  "timestamp": 1730000014500,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 15,
+  "source": "server",
+  "trackId": "audio_out",
+  "tool_call_id": "call_abc123",
+  "tool_name": "weather",
+  "tool_display_name": "天气查询",
+  "ok": true,
+  "error": null,
+  "result": {
+    "tool_call_id": "call_abc123",
+    "name": "weather",
+    "output": {
+      "temperature": 25,
+      "condition": "晴",
+      "humidity": 40
+    },
+    "status": {
+      "code": 200,
+      "message": "ok"
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 执行方：`"server"` / `"client"` |
+| `tool_call_id` | string | 工具调用 ID |
+| `tool_name` | string | 工具名称 |
+| `tool_display_name` | string | 工具显示名称 |
+| `ok` | boolean | 执行是否成功（状态码 200-299 为 true） |
+| `error` | object \| null | 错误信息（`ok=false` 时存在） |
+| `error.code` | number | 错误状态码 |
+| `error.message` | string | 错误描述 |
+| `error.retryable` | boolean | 是否可重试 |
+| `result` | object | 原始执行结果 |
+| `result.output` | any | 工具返回数据 |
+| `result.status` | object | 执行状态 |
+| `result.status.code` | number | HTTP 状态码 |
+| `result.status.message` | string | 状态描述 |
+
+---
+
+#### `output.audio.start`
+
+TTS 音频播放开始标记。
+
+```json
+{
+  "type": "output.audio.start",
+  "timestamp": 1730000015500,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 19,
+  "source": "tts",
+  "trackId": "audio_out",
+  "data": {
+    "tts_id": "tts_001",
+    "turn_id": "turn_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 固定为 `"tts"` |
+| `data.tts_id` | string | TTS 播放段 ID |
+| `data.turn_id` | string | 当前对话轮次 ID |
+
+**说明**：此事件后服务端将发送二进制 PCM 音频帧。
+
+---
+
+#### `output.audio.end`
+
+TTS 音频播放结束标记。
+
+```json
+{
+  "type": "output.audio.end",
+  "timestamp": 1730000018000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 25,
+  "source": "tts",
+  "trackId": "audio_out",
+  "data": {
+    "tts_id": "tts_001",
+    "turn_id": "turn_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `source` | string | 固定为 `"tts"` |
+| `data.tts_id` | string | TTS 播放段 ID |
+| `data.turn_id` | string | 当前对话轮次 ID |
+
+---
+
+#### `response.interrupted`
+
+回答被打断（用户插话）。
+
+```json
+{
+  "type": "response.interrupted",
+  "timestamp": 1730000016000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 20,
+  "source": "system",
+  "trackId": "audio_out",
+  "data": {
+    "turn_id": "turn_001",
+    "response_id": "resp_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `data.turn_id` | string | 被打断的对话轮次 ID |
+| `data.response_id` | string | 被打断的回复 ID |
+
+---
+
+#### `metrics.ttfb`
+
+首包音频时延指标（Time To First Byte）。
+
+```json
+{
+  "type": "metrics.ttfb",
+  "timestamp": 1730000015600,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 21,
+  "source": "system",
+  "trackId": "audio_out",
+  "latencyMs": 1520,
+  "data": {
+    "latencyMs": 1520,
+    "turn_id": "turn_001"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `trackId` | string | 固定为 `"audio_out"` |
+| `latencyMs` | number | 首包音频时延（毫秒） |
+| `data.latencyMs` | number | 首包音频时延（同 `latencyMs`） |
+| `data.turn_id` | string | 当前对话轮次 ID |
+
+**说明**：从用户输入结束到第一个音频包发送的时间。
+
+---
+
+### 错误事件
+
+#### `error`
+
+统一错误事件。
+
+```json
+{
+  "type": "error",
+  "timestamp": 1730000020000,
+  "sessionId": "ea34e1ca-b417-4a57-b03e-f752cb82e97d",
+  "seq": 30,
+  "sender": "server",
+  "code": "llm.timeout",
+  "message": "LLM request timeout",
+  "stage": "llm",
+  "retryable": true,
+  "trackId": "audio_out",
+  "data": {
+    "error": {
+      "stage": "llm",
+      "code": "llm.timeout",
+      "message": "LLM request timeout",
+      "retryable": true
+    }
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sender` | string | 错误来源：`"server"` / `"client"` |
+| `code` | string | 错误码 |
+| `message` | string | 错误描述 |
+| `stage` | string | 错误阶段：`"protocol"` / `"asr"` / `"llm"` / `"tts"` / `"tool"` / `"audio"` |
+| `retryable` | boolean | 是否可重试 |
+| `trackId` | string | 错误关联的轨道 |
+| `data.error` | object | 结构化错误信息 |
+| `data.error.stage` | string | 错误阶段 |
+| `data.error.code` | string | 错误码 |
+| `data.error.message` | string | 错误描述 |
+| `data.error.retryable` | boolean | 是否可重试 |
+
+**trackId 约定**：
+- `audio_in`：ASR/音频输入相关错误
+- `audio_out`：LLM/TTS/工具相关错误
+- `control`：协议/会话控制相关错误
+
+---
+
+## 关联 ID 说明
+
+事件中的关联 ID 用于追踪对话流程：
+
+| ID 类型 | 说明 | 生命周期 |
+|---------|------|---------|
+| `turn_id` | 对话轮次 ID | 一次用户-助手交互 |
+| `utterance_id` | 语句 ID | 一次 ASR 最终识别结果 |
+| `response_id` | 回复 ID | 一次助手回复生成 |
+| `tool_call_id` | 工具调用 ID | 一次工具调用 |
+| `tts_id` | TTS 播放段 ID | 一段语音合成播放 |
+
+---
+
+## 心跳与超时
+
+- **心跳间隔**：默认 50 秒（`heartbeat_interval_sec`）
+- **空闲超时**：默认 60 秒（`inactivity_timeout_sec`）
+- 客户端应持续发送音频或轻量消息避免被判定闲置
+
+## 事件节流
+
+为保持客户端渲染和服务端负载稳定，v1 协议对部分事件进行节流：
+
+| 事件 | 默认节流间隔 | 说明 |
+|------|-------------|------|
+| `transcript.delta` | 300ms | ASR 增量文本 |
+| `assistant.response.delta` | 80ms | LLM 增量文本 |
+
+## 错误处理
+
+详细错误码请参考 [错误码](errors.md)。
diff --git a/docs/content/assistants/configuration.md b/docs/content/assistants/configuration.md
new file mode 100644
index 0000000..da28d1e
--- /dev/null
+++ b/docs/content/assistants/configuration.md
@@ -0,0 +1,113 @@
+# 配置选项
+
+助手配置界面包含多个标签页，每个标签页负责不同方面的配置。
+
+## 全局设置
+
+全局设置定义助手的核心对话能力。
+
+| 配置项 | 说明 | 建议值 |
+|-------|------|--------|
+| 助手名称 | 用于标识和管理 | 简洁明确 |
+| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](prompts.md) |
+| 开场白 | 对话开始时的问候语 | 简短友好 |
+| 温度参数 | 控制回复随机性 | 0.7（通用）/ 0.3（严谨） |
+| 上下文长度 | 保留的历史消息数 | 10-20 |
+
+### 高级选项
+
+- **首轮模式** - 设置首次对话的触发方式
+- **打断检测** - 用户打断时的处理策略
+- **超时设置** - 无响应时的处理
+
+## 语音配置
+
+配置语音识别和语音合成参数。
+
+### TTS 语音合成
+
+| 配置 | 说明 |
+|------|------|
+| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
+| 音色 | 选择语音风格和性别 |
+| 语速 | 语音播放速度（0.5-2.0） |
+| 音量 | 语音输出音量（0-100） |
+| 音调 | 语音音调高低（0.5-2.0） |
+
+### ASR 语音识别
+
+| 配置 | 说明 |
+|------|------|
+| ASR 引擎 | 选择语音识别服务 |
+| 语言 | 识别语言（中文/英文/多语言） |
+| 热词 | 提高特定词汇识别准确率 |
+
+## 工具绑定
+
+配置助手可调用的外部工具。
+
+### 可用工具类型
+
+| 工具 | 说明 |
+|------|------|
+| 搜索工具 | 网络搜索获取信息 |
+| 天气查询 | 查询天气预报 |
+| 计算器 | 数学计算 |
+| 知识库检索 | RAG 知识检索 |
+| 自定义工具 | HTTP 回调外部 API |
+
+### 配置步骤
+
+1. 在工具列表中勾选需要的工具
+2. 配置工具参数（如有）
+3. 测试工具调用是否正常
+
+## 知识关联
+
+关联 RAG 知识库，让助手能够回答专业领域问题。
+
+### 配置参数
+
+| 参数 | 说明 | 建议值 |
+|------|------|--------|
+| 知识库 | 选择要关联的知识库 | - |
+| 相似度阈值 | 低于此分数不返回 | 0.7 |
+| 返回数量 | 单次检索返回条数 | 3 |
+| 检索策略 | 混合/向量/关键词 | 混合 |
+
+### 多知识库
+
+支持关联多个知识库，系统会自动合并检索结果。
+
+## 外部链接
+
+配置第三方服务集成和 Webhook 回调。
+
+### Webhook 配置
+
+| 字段 | 说明 |
+|------|------|
+| 回调 URL | 接收事件的 HTTP 端点 |
+| 事件类型 | 订阅的事件（对话开始/结束/工具调用等） |
+| 认证方式 | API Key / Bearer Token / 无 |
+
+### 支持的事件
+
+- `conversation.started` - 对话开始
+- `conversation.ended` - 对话结束
+- `tool.called` - 工具被调用
+- `human.transfer` - 转人工
+
+## 配置导入导出
+
+### 导出配置
+
+1. 在助手详情页点击 **更多**
+2. 选择 **导出配置**
+3. 下载 JSON 格式的配置文件
+
+### 导入配置
+
+1. 点击 **新建助手**
+2. 选择 **从配置导入**
+3. 上传配置文件
diff --git a/docs/content/assistants/index.md b/docs/content/assistants/index.md
new file mode 100644
index 0000000..c8b6191
--- /dev/null
+++ b/docs/content/assistants/index.md
@@ -0,0 +1,57 @@
+# 助手管理
+
+助手是 AI Video Assistant 的核心模块，用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
+
+## 概述
+
+![助手管理](../images/assistants.png)
+
+## 助手能力
+
+| 能力 | 说明 |
+|------|------|
+| **智能对话** | 基于 LLM 的自然语言理解和生成 |
+| **语音交互** | 支持语音识别和语音合成 |
+| **知识检索** | 关联知识库回答专业问题 |
+| **工具调用** | 调用外部 API 执行操作 |
+| **工作流** | 支持复杂的多轮对话流程 |
+
+## 创建助手
+
+### 步骤
+
+1. 进入 **助手管理** 页面
+2. 点击 **新建助手** 按钮
+3. 填写基本信息
+4. 配置各项参数
+5. 保存并发布
+
+### 基本信息
+
+| 配置项 | 说明 |
+|-------|------|
+| 助手名称 | 唯一标识，用于区分不同助手 |
+| 提示词 | 定义助手的角色和行为 |
+| 温度参数 | 控制回复的随机性（0-1） |
+
+## 调试助手
+
+在助手详情页可进行实时调试：
+
+- **文本对话测试** - 快速验证回复质量
+- **语音输入测试** - 测试 ASR 识别效果
+- **工具调用验证** - 确认工具正常执行
+
+## 发布助手
+
+配置完成后：
+
+1. 点击 **保存** - 保存当前配置
+2. 点击 **发布** - 发布到生产环境
+3. 获取 API 调用地址 - 用于集成
+
+## 下一步
+
+- [配置选项](configuration.md) - 详细的配置标签页说明
+- [提示词指南](prompts.md) - 如何编写高质量的系统提示词
+- [测试调试](testing.md) - 助手测试与问题排查
diff --git a/docs/content/assistants/prompts.md b/docs/content/assistants/prompts.md
new file mode 100644
index 0000000..d359111
--- /dev/null
+++ b/docs/content/assistants/prompts.md
@@ -0,0 +1,184 @@
+# 提示词指南
+
+系统提示词（System Prompt）是定义助手行为的核心配置。本指南介绍如何编写高质量的提示词。
+
+## 提示词结构
+
+一个完整的系统提示词通常包含以下部分：
+
+```
+[角色定义]
+[任务描述]
+[行为约束]
+[输出格式]
+[示例（可选）]
+```
+
+## 编写原则
+
+### 1. 明确角色
+
+告诉助手它是谁：
+
+```
+你是一个专业的技术支持工程师，专门负责解答产品使用问题。
+```
+
+### 2. 定义任务
+
+明确助手需要完成什么：
+
+```
+你的主要任务是：
+1. 解答用户关于产品功能的问题
+2. 提供使用指导和最佳实践
+3. 帮助用户排查常见故障
+```
+
+### 3. 设置约束
+
+限制不希望出现的行为：
+
+```
+请注意：
+- 不要讨论与产品无关的话题
+- 不要编造不存在的功能
+- 如果不确定答案，请建议用户联系人工客服
+```
+
+### 4. 指定风格
+
+定义回复的语气和风格：
+
+```
+回复风格要求：
+- 使用友好、专业的语气
+- 回答简洁明了，避免冗长
+- 适当使用列表和步骤说明
+```
+
+## 提示词模板
+
+### 客服助手
+
+```
+你是 [公司名称] 的智能客服助手。
+
+## 你的职责
+- 解答用户关于产品和服务的问题
+- 处理常见的投诉和建议
+- 引导用户完成操作流程
+
+## 回复要求
+- 保持友好和耐心
+- 回答简洁，一般不超过 3 句话
+- 如果问题复杂，建议转接人工客服
+
+## 禁止行为
+- 不要讨论竞争对手
+- 不要承诺无法兑现的事项
+- 不要透露内部信息
+```
+
+### 技术支持
+
+```
+你是一个技术支持工程师，专门帮助用户解决技术问题。
+
+## 工作流程
+1. 首先了解用户遇到的具体问题
+2. 询问必要的环境信息（系统版本、错误信息等）
+3. 提供分步骤的解决方案
+4. 确认问题是否解决
+
+## 回复格式
+- 使用编号列表说明操作步骤
+- 提供代码示例时使用代码块
+- 复杂问题可以分多次回复
+```
+
+### 销售顾问
+
+```
+你是一个产品销售顾问，帮助用户了解产品并做出购买决策。
+
+## 沟通策略
+- 先了解用户需求，再推荐合适的产品
+- 突出产品优势，但不贬低竞品
+- 提供真实的价格和优惠信息
+
+## 目标
+- 帮助用户找到最适合的方案
+- 解答购买相关的疑问
+- 促进成交但不过度推销
+```
+
+## 动态变量
+
+提示词支持动态变量，使用 `{{变量名}}` 语法：
+
+```
+你好 {{customer_name}}，欢迎来到 {{company_name}}。
+你当前的会员等级是 {{membership_tier}}。
+```
+
+在 `session.start` 时通过 `dynamicVariables` 传入：
+
+```json
+{
+  "type": "session.start",
+  "metadata": {
+    "dynamicVariables": {
+      "customer_name": "张三",
+      "company_name": "AI 公司",
+      "membership_tier": "黄金会员"
+    }
+  }
+}
+```
+
+## 常见问题
+
+### 回复太长
+
+在提示词中明确限制：
+
+```
+回复长度要求：
+- 一般问题：1-2 句话
+- 复杂问题：不超过 5 句话
+- 避免重复和冗余内容
+```
+
+### 答非所问
+
+增加任务边界说明：
+
+```
+重要提示：
+- 只回答与 [产品/服务] 相关的问题
+- 对于无关问题，礼貌地拒绝并引导回正题
+```
+
+### 编造信息
+
+强调诚实原则：
+
+```
+信息准确性要求：
+- 只提供你确定的信息
+- 不确定时说"我不太确定，建议您..."
+- 绝对不要编造数据或功能
+```
+
+## 最佳实践
+
+1. **迭代优化** - 根据实际对话效果持续调整
+2. **测试覆盖** - 用各种场景测试提示词效果
+3. **版本管理** - 保存历史版本，便于回退
+4. **定期复盘** - 分析对话记录，发现改进点
+
+## 下一步
+
+- [测试调试](testing.md) - 验证提示词效果
+- [知识库配置](../customization/knowledge-base.md) - 补充专业知识
diff --git a/docs/content/assistants/testing.md b/docs/content/assistants/testing.md
new file mode 100644
index 0000000..ca4bd06
--- /dev/null
+++ b/docs/content/assistants/testing.md
@@ -0,0 +1,162 @@
+# 测试调试
+
+本指南介绍如何测试和调试 AI 助手，确保其行为符合预期。
+
+## 测试面板
+
+在助手详情页，点击 **测试** 按钮打开测试面板。
+
+### 功能介绍
+
+| 功能 | 说明 |
+|------|------|
+| 文本对话 | 直接输入文字进行测试 |
+| 语音测试 | 使用麦克风进行语音对话 |
+| 查看日志 | 实时查看系统日志 |
+| 事件追踪 | 查看 WebSocket 事件流 |
+
+## 测试用例设计
+
+### 基础功能测试
+
+| 测试项 | 输入 | 预期结果 |
+|--------|------|---------|
+| 问候响应 | "你好" | 友好的问候回复 |
+| 功能介绍 | "你能做什么？" | 准确描述能力范围 |
+| 开场白 | 连接后自动 | 播放配置的开场白 |
+
+### 业务场景测试
+
+根据助手定位设计测试用例：
+
+```
+场景：产品咨询助手
+
+测试用例 1：常见问题
+- 输入："产品有哪些功能？"
+- 预期：准确列出主要功能
+
+测试用例 2：价格询问
+- 输入："多少钱？"
+- 预期：提供价格信息或引导方式
+
+测试用例 3：超出范围
+- 输入："帮我写一首诗"
+- 预期：礼貌拒绝并引导回业务话题
+```
+
+### 边界测试
+
+| 测试项 | 输入 | 预期结果 |
+|--------|------|---------|
+| 空输入 | "" | 提示用户输入内容 |
+| 超长输入 | 1000+ 字符 | 正常处理或提示过长 |
+| 特殊字符 | "<script>alert(1)</script>" | 安全处理，不执行 |
+| 敏感内容 | 不当言论 | 拒绝回复并提示 |
+
+## 日志分析
+
+### 查看日志
+
+在测试面板的 **日志** 标签页，可以看到：
+
+- ASR 识别结果
+- LLM 推理过程
+- TTS 合成状态
+- 工具调用记录
+
+### 常见日志
+
+```
+[ASR] transcript.final: "你好，请问有什么可以帮你"
+[LLM] request: messages=[...]
+[LLM] response: "您好！我是..."
+[TTS] synthesizing: "您好！我是..."
+[TTS] audio.start
+[TTS] audio.end
+```
+
+## 事件追踪
+
+在 **事件** 标签页查看完整的 WebSocket 事件流：
+
+```json
+{"type": "session.started", "timestamp": 1704067200000}
+{"type": "input.speech_started", "timestamp": 1704067201000}
+{"type": "transcript.delta", "data": {"text": "你"}}
+{"type": "transcript.delta", "data": {"text": "好"}}
+{"type": "transcript.final", "data": {"text": "你好"}}
+{"type": "assistant.response.delta", "data": {"text": "您"}}
+{"type": "assistant.response.final", "data": {"text": "您好！..."}}
+{"type": "output.audio.start"}
+{"type": "output.audio.end"}
+```
+
+## 性能指标
+
+关注以下性能指标：
+
+| 指标 | 说明 | 建议值 |
+|------|------|--------|
+| TTFB | 首字节时间 | < 500ms |
+| 识别延迟 | ASR 处理时间 | < 1s |
+| 回复延迟 | LLM 推理时间 | < 2s |
+| 合成延迟 | TTS 处理时间 | < 500ms |
+
+## 常见问题排查
+
+### 助手不响应
+
+1. **检查连接状态**
+   - 确认 WebSocket 连接成功
+   - 查看是否收到 `session.started` 事件
+
+2. **检查模型配置**
+   - 确认 LLM 模型 API Key 有效
+   - 测试模型连接是否正常
+
+3. **查看错误日志**
+   - 打开浏览器开发者工具
+   - 检查 Console 和 Network 标签
+
+### 回复质量差
+
+1. **优化提示词**
+   - 增加更明确的指令
+   - 添加示例和约束
+
+2. **调整温度参数**
+   - 降低 temperature 提高一致性
+   - 适当值通常在 0.3-0.7
+
+3. **补充知识库**
+   - 上传相关文档
+   - 提高检索相关性
+
+### 语音问题
+
+1. **ASR 识别不准**
+   - 检查麦克风权限
+   - 尝试更换 ASR 引擎
+   - 添加热词提高识别率
+
+2. **TTS 不播放**
+   - 检查浏览器自动播放限制
+   - 确认 TTS 配置正确
+
+## 自动化测试
+
+使用自动化测试功能进行批量测试：
+
+1. 进入 **自动化测试** 页面
+2. 创建测试任务
+3. 配置测试用例
+4. 运行测试并查看报告
+
+详见 [自动化测试](../analysis/autotest.md)。
+
+## 下一步
+
+- [自动化测试](../analysis/autotest.md) - 批量测试
+- [历史记录](../analysis/history.md) - 查看对话记录
+- [效果评估](../analysis/evaluation.md) - 评估对话质量
diff --git a/docs/content/features/knowledge.md b/docs/content/customization/knowledge-base.md
similarity index 100%
rename from docs/content/features/knowledge.md
rename to docs/content/customization/knowledge-base.md
diff --git a/docs/content/features/models.md b/docs/content/customization/models.md
similarity index 100%
rename from docs/content/features/models.md
rename to docs/content/customization/models.md
diff --git a/docs/content/customization/tools.md b/docs/content/customization/tools.md
new file mode 100644
index 0000000..2c5a5b0
--- /dev/null
+++ b/docs/content/customization/tools.md
@@ -0,0 +1,229 @@
+# 工具集成
+
+工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
+
+## 概述
+
+工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
+
+## 内置工具
+
+| 工具 | 说明 | 参数 |
+|------|------|------|
+| `search` | 网络搜索 | query: 搜索关键词 |
+| `weather` | 天气查询 | city: 城市名称 |
+| `calculator` | 数学计算 | expression: 计算表达式 |
+| `knowledge` | 知识库检索 | query: 查询内容 |
+
+### 启用内置工具
+
+在助手配置的 **工具** 标签页：
+
+1. 勾选需要启用的工具
+2. 配置工具参数（如有）
+3. 保存配置
+
+## 自定义工具
+
+支持通过 HTTP 回调实现自定义工具。
+
+### 定义工具
+
+```json
+{
+  "name": "query_order",
+  "description": "查询用户订单信息",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "order_id": {
+        "type": "string",
+        "description": "订单编号"
+      }
+    },
+    "required": ["order_id"]
+  },
+  "endpoint": {
+    "url": "https://api.example.com/orders",
+    "method": "GET",
+    "headers": {
+      "Authorization": "Bearer {{api_key}}"
+    }
+  }
+}
+```
+
+### 工具字段说明
+
+| 字段 | 说明 |
+|------|------|
+| name | 工具名称（英文标识符） |
+| description | 工具描述（LLM 用于理解工具用途） |
+| parameters | 参数定义（JSON Schema 格式） |
+| endpoint | HTTP 调用配置 |
+
+### 参数映射
+
+工具参数自动映射到 HTTP 请求：
+
+- **GET 请求**：参数作为 query string
+- **POST 请求**：参数作为 JSON body
+
+## 客户端工具
+
+某些工具需要在客户端执行（如获取地理位置）。
+
+### 工作流程
+
+1. 助手返回 `assistant.tool_call` 事件
+2. 客户端执行工具并获取结果
+3. 客户端发送 `tool_call.results` 消息
+4. 助手继续生成回复
+
+### 服务端事件
+
+```json
+{
+  "type": "assistant.tool_call",
+  "data": {
+    "tool_call_id": "call_abc123",
+    "tool_name": "get_location",
+    "arguments": {}
+  }
+}
+```
+
+### 客户端响应
+
+```json
+{
+  "type": "tool_call.results",
+  "results": [
+    {
+      "tool_call_id": "call_abc123",
+      "name": "get_location",
+      "output": {
+        "latitude": 39.9042,
+        "longitude": 116.4074,
+        "city": "北京"
+      },
+      "status": {
+        "code": 200,
+        "message": "ok"
+      }
+    }
+  ]
+}
+```
+
+## 工具调用示例
+
+### 天气查询
+
+用户："北京今天天气怎么样？"
+
+助手调用工具：
+```json
+{
+  "tool_name": "weather",
+  "arguments": {
+    "city": "北京"
+  }
+}
+```
+
+工具返回：
+```json
+{
+  "temperature": 25,
+  "condition": "晴",
+  "humidity": 40
+}
+```
+
+助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"
+
+### 订单查询
+
+用户："帮我查一下订单 12345"
+
+助手调用工具：
+```json
+{
+  "tool_name": "query_order",
+  "arguments": {
+    "order_id": "12345"
+  }
+}
+```
+
+工具返回：
+```json
+{
+  "order_id": "12345",
+  "status": "已发货",
+  "tracking": "SF1234567890"
+}
+```
+
+助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"
+
+## 工具配置最佳实践
+
+### 1. 清晰的描述
+
+工具描述应该让 LLM 准确理解何时使用：
+
+```
+好的描述：
+"查询指定城市的实时天气信息，包括温度、天气状况和湿度"
+
+不好的描述：
+"天气工具"
+```
+
+### 2. 完整的参数定义
+
+```json
+{
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "city": {
+        "type": "string",
+        "description": "城市名称，如 '北京'、'上海'"
+      },
+      "date": {
+        "type": "string",
+        "description": "日期，格式 YYYY-MM-DD，可选，默认今天"
+      }
+    },
+    "required": ["city"]
+  }
+}
+```
+
+### 3. 错误处理
+
+工具应返回清晰的错误信息：
+
+```json
+{
+  "status": {
+    "code": 404,
+    "message": "未找到该城市的天气数据"
+  }
+}
+```
+
+## 安全注意事项
+
+1. **验证输入** - 不要直接信任用户输入
+2. **限制权限** - 工具只应有必要的权限
+3. **审计日志** - 记录所有工具调用
+4. **速率限制** - 防止滥用
+
+## 下一步
+
+- [知识库配置](knowledge-base.md) - 让助手具备专业知识
+- [工作流编排](workflows.md) - 复杂对话流程
diff --git a/docs/content/features/voices.md b/docs/content/customization/voices.md
similarity index 100%
rename from docs/content/features/voices.md
rename to docs/content/customization/voices.md
diff --git a/docs/content/features/workflows.md b/docs/content/customization/workflows.md
similarity index 100%
rename from docs/content/features/workflows.md
rename to docs/content/customization/workflows.md
diff --git a/docs/content/deployment.md b/docs/content/deployment.md
deleted file mode 100644
index 82ec939..0000000
--- a/docs/content/deployment.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# 部署指南
-
-## 方式一：Docker 部署（推荐）
-
-### 1. 构建镜像
-
-```bash
-docker build -t ai-video-assistant-web ./web
-```
-
-### 2. 运行容器
-
-```bash
-docker run -d \
-  --name ai-assistant-web \
-  -p 3000:80 \
-  ai-video-assistant-web
-```
-
-### 3. 使用 Docker Compose
-
-```yaml
-version: '3.8'
-
-services:
-  web:
-    build: ./web
-    ports:
-      - "3000:80"
-    environment:
-      - VITE_API_URL=http://api:8080
-```
-
-运行：
-```bash
-docker-compose up -d
-```
-
-## 方式二：Nginx 部署
-
-### 1. 构建前端
-
-```bash
-cd web
-npm run build
-```
-
-### 2. 配置 Nginx
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    root /var/www/ai-assistant/dist;
-    index index.html;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    location /api {
-        proxy_pass http://localhost:8080;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-### 3. 启动 Nginx
-
-```bash
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-## 环境变量配置
-
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| VITE_API_URL | 后端 API 地址 | http://localhost:8080 |
-| VITE_GEMINI_API_KEY | Gemini API Key | - |
-
-## 验证部署
-
-1. 访问 http://your-domain.com
-2. 检查页面是否正常加载
-3. 验证各功能模块是否可用
-
-## 故障排查
-
-| 问题 | 解决方案 |
-|------|---------|
-| 页面空白 | 检查浏览器控制台错误 |
-| API 请求失败 | 确认 VITE_API_URL 配置正确 |
-| 静态资源 404 | 检查 nginx try_files 配置 |
diff --git a/docs/content/deployment/docker.md b/docs/content/deployment/docker.md
new file mode 100644
index 0000000..84d2f8b
--- /dev/null
+++ b/docs/content/deployment/docker.md
@@ -0,0 +1,161 @@
+# Docker 部署
+
+Docker 是推荐的部署方式，可以快速启动服务并确保环境一致性。
+
+## 前提条件
+
+- Docker 20.10+
+- Docker Compose 2.0+（可选）
+
+## 构建镜像
+
+### Web 前端
+
+```bash
+docker build -t ai-video-assistant-web ./web
+```
+
+### API 服务
+
+```bash
+docker build -t ai-video-assistant-api ./api
+```
+
+### Engine 服务
+
+```bash
+docker build -t ai-video-assistant-engine ./engine
+```
+
+## 运行容器
+
+### 单独运行
+
+```bash
+# Web 前端
+docker run -d \
+  --name ai-assistant-web \
+  -p 3000:80 \
+  ai-video-assistant-web
+
+# API 服务
+docker run -d \
+  --name ai-assistant-api \
+  -p 8080:8080 \
+  ai-video-assistant-api
+
+# Engine 服务
+docker run -d \
+  --name ai-assistant-engine \
+  -p 8000:8000 \
+  ai-video-assistant-engine
+```
+
+## Docker Compose
+
+推荐使用 Docker Compose 管理多个服务：
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: ./web
+    ports:
+      - "3000:80"
+    environment:
+      - VITE_API_URL=http://api:8080
+    depends_on:
+      - api
+
+  api:
+    build: ./api
+    ports:
+      - "8080:8080"
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/ai_assistant
+    depends_on:
+      - db
+
+  engine:
+    build: ./engine
+    ports:
+      - "8000:8000"
+    environment:
+      - BACKEND_URL=http://api:8080
+
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_DB=ai_assistant
+      - POSTGRES_PASSWORD=password
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+### 启动服务
+
+```bash
+# 启动所有服务
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止服务
+docker-compose down
+```
+
+## 镜像优化
+
+### 多阶段构建
+
+Web 前端 Dockerfile 示例：
+
+```dockerfile
+# 构建阶段
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# 运行阶段
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/nginx.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+## 健康检查
+
+```yaml
+services:
+  api:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+## 常见问题
+
+### 容器启动失败
+
+```bash
+# 查看容器日志
+docker logs ai-assistant-web
+
+# 进入容器调试
+docker exec -it ai-assistant-web sh
+```
+
+### 端口冲突
+
+修改 `docker-compose.yml` 中的端口映射，例如 `3001:80`。
diff --git a/docs/content/deployment/index.md b/docs/content/deployment/index.md
new file mode 100644
index 0000000..77652f6
--- /dev/null
+++ b/docs/content/deployment/index.md
@@ -0,0 +1,42 @@
+# 部署指南
+
+本章节介绍如何将 AI Video Assistant 部署到生产环境。
+
+## 部署方式
+
+| 方式 | 适用场景 | 复杂度 |
+|------|---------|--------|
+| [Docker 部署](docker.md) | 快速部署、容器化环境 | 简单 |
+| [生产环境](production.md) | Nginx 反向代理、高可用 | 中等 |
+
+## 快速开始
+
+### Docker 一键部署
+
+```bash
+docker build -t ai-video-assistant-web ./web
+docker run -d -p 3000:80 --name ai-assistant-web ai-video-assistant-web
+```
+
+### 验证部署
+
+1. 访问 http://your-domain.com
+2. 检查页面是否正常加载
+3. 验证各功能模块是否可用
+
+## 环境变量配置
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| VITE_API_URL | 后端 API 地址 | http://localhost:8080 |
+| VITE_GEMINI_API_KEY | Gemini API Key | - |
+
+## 故障排查
+
+| 问题 | 解决方案 |
+|------|---------|
+| 页面空白 | 检查浏览器控制台错误 |
+| API 请求失败 | 确认 VITE_API_URL 配置正确 |
+| 静态资源 404 | 检查 nginx try_files 配置 |
+
+更多问题请参考 [故障排查](../resources/troubleshooting.md)。
diff --git a/docs/content/deployment/production.md b/docs/content/deployment/production.md
new file mode 100644
index 0000000..cfd8163
--- /dev/null
+++ b/docs/content/deployment/production.md
@@ -0,0 +1,191 @@
+# 生产环境部署
+
+本文档介绍如何将 AI Video Assistant 部署到生产环境，包括 Nginx 配置、SSL 证书、性能优化等。
+
+## Nginx 部署
+
+### 1. 构建前端
+
+```bash
+cd web
+npm run build
+```
+
+### 2. 部署静态文件
+
+```bash
+sudo mkdir -p /var/www/ai-assistant
+sudo cp -r dist/* /var/www/ai-assistant/
+```
+
+### 3. 配置 Nginx
+
+创建 `/etc/nginx/sites-available/ai-assistant`：
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    root /var/www/ai-assistant;
+    index index.html;
+
+    # Gzip 压缩
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript;
+
+    # 静态文件缓存
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # SPA 路由支持
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API 反向代理
+    location /api {
+        proxy_pass http://localhost:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # WebSocket 代理
+    location /ws {
+        proxy_pass http://localhost:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### 4. 启用站点
+
+```bash
+sudo ln -s /etc/nginx/sites-available/ai-assistant /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+## SSL 证书配置
+
+### 使用 Let's Encrypt
+
+```bash
+# 安装 certbot
+sudo apt install certbot python3-certbot-nginx
+
+# 申请证书
+sudo certbot --nginx -d your-domain.com
+
+# 自动续期
+sudo certbot renew --dry-run
+```
+
+### HTTPS 配置
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL 安全配置
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+
+    # HSTS
+    add_header Strict-Transport-Security "max-age=31536000" always;
+
+    # ... 其他配置同上
+}
+
+# HTTP 重定向到 HTTPS
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+## 性能优化
+
+### Nginx 优化
+
+```nginx
+# 在 http 块中添加
+worker_processes auto;
+worker_connections 1024;
+
+# 开启 sendfile
+sendfile on;
+tcp_nopush on;
+tcp_nodelay on;
+
+# 缓冲区设置
+client_body_buffer_size 10K;
+client_header_buffer_size 1k;
+client_max_body_size 8m;
+```
+
+### 静态资源 CDN
+
+如果使用 CDN，修改构建配置：
+
+```env
+# .env.production
+VITE_CDN_URL=https://cdn.your-domain.com
+```
+
+## 监控与日志
+
+### 访问日志
+
+```nginx
+access_log /var/log/nginx/ai-assistant.access.log;
+error_log /var/log/nginx/ai-assistant.error.log;
+```
+
+### 日志轮转
+
+```bash
+# /etc/logrotate.d/nginx
+/var/log/nginx/*.log {
+    daily
+    rotate 14
+    compress
+    delaycompress
+    missingok
+    notifempty
+}
+```
+
+## 备份策略
+
+### 数据库备份
+
+```bash
+# PostgreSQL 备份
+pg_dump -U postgres ai_assistant > backup_$(date +%Y%m%d).sql
+
+# 定时备份（crontab）
+0 2 * * * pg_dump -U postgres ai_assistant > /backups/backup_$(date +\%Y\%m\%d).sql
+```
+
+## 高可用部署
+
+对于高可用需求，建议：
+
+1. **负载均衡** - 使用 Nginx upstream 或云负载均衡
+2. **数据库主从** - PostgreSQL 主从复制
+3. **Redis 集群** - 会话和缓存高可用
+4. **健康检查** - 定期检测服务状态
diff --git a/docs/content/features/assistants.md b/docs/content/features/assistants.md
deleted file mode 100644
index 13cfdef..0000000
--- a/docs/content/features/assistants.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# 助手管理
-
-助手是 AI Video Assistant 的核心模块，用于创建和配置智能对话机器人。
-
-## 创建助手
-
-![助手管理](../images/assistants.png)
-
-### 基本配置
-
-1. 进入 **助手管理** 页面
-2. 点击 **新建助手** 按钮
-3. 填写基本信息：
-
-| 配置项 | 说明 |
-|-------|------|
-| 助手名称 | 唯一标识，用于区分不同助手 |
-| 提示词 | 定义助手的角色和行为 |
-| 温度参数 | 控制回复的随机性（0-1） |
-
-### 配置标签页
-
-#### 全局设置
-
-- 设置助手的核心对话能力
-- 配置上下文长度
-- 设置对话开场白
-
-#### 语音配置
-
-| 配置 | 说明 |
-|------|------|
-| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
-| 音色 | 选择语音风格和性别 |
-| 语速 | 语音播放速度 |
-| 音量 | 语音输出音量 |
-
-#### 工具绑定
-
-- 配置助手可调用的外部工具
-- 启用/禁用特定功能模块
-
-#### 知识关联
-
-- 关联 RAG 知识库
-- 配置检索参数（相似度阈值、返回数量）
-
-#### 外部链接
-
-- 配置第三方服务集成
-- 设置 Webhook 回调
-
-## 调试助手
-
-在助手详情页可进行实时调试：
-- 文本对话测试
-- 语音输入测试
-- 工具调用验证
-
-## 发布助手
-
-配置完成后：
-1. 点击 **保存**
-2. 点击 **发布**
-3. 获取 API 调用地址
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
deleted file mode 100644
index 107ee81..0000000
--- a/docs/content/getting-started.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# 快速开始
-
-## 环境准备
-
-### 前置条件
-
-| 软件 | 版本要求 |
-|------|---------|
-| Node.js | 18.0 或更高 |
-| npm/yarn/pnpm | 最新版本 |
-| 现代浏览器 | Chrome 90+ / Firefox 90+ / Edge 90+ |
-
-### 检查环境
-
-```bash
-node --version
-npm --version
-```
-
-## 安装步骤
-
-### 1. 克隆项目
-
-```bash
-git clone https://github.com/your-repo/AI-VideoAssistant.git
-cd AI-VideoAssistant
-```
-
-### 2. 安装依赖
-
-```bash
-cd web
-npm install
-```
-
-### 3. 配置环境变量
-
-创建 `.env` 文件：
-
-```env
-VITE_API_URL=http://localhost:8080
-VITE_GEMINI_API_KEY=your_api_key_here
-```
-
-### 4. 启动开发服务器
-
-```bash
-npm run dev
-```
-
-访问 http://localhost:3000
-
-## 构建生产版本
-
-```bash
-npm run build
-```
-
-构建产物在 `dist` 目录。
diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md
new file mode 100644
index 0000000..2dd1763
--- /dev/null
+++ b/docs/content/getting-started/configuration.md
@@ -0,0 +1,83 @@
+# 配置说明
+
+## 环境变量
+
+在项目根目录或 `web` 目录下创建 `.env` 文件：
+
+```env
+# API 服务地址
+VITE_API_URL=http://localhost:8080
+
+# Gemini API Key（可选）
+VITE_GEMINI_API_KEY=your_api_key_here
+```
+
+## 变量说明
+
+| 变量 | 必填 | 说明 | 默认值 |
+|------|------|------|--------|
+| `VITE_API_URL` | 是 | 后端 API 服务地址 | http://localhost:8080 |
+| `VITE_GEMINI_API_KEY` | 否 | Google Gemini API 密钥 | - |
+
+## 后端服务配置
+
+后端服务使用独立的配置文件，位于 `api/config/` 目录：
+
+### 数据库配置
+
+```yaml
+database:
+  host: localhost
+  port: 5432
+  name: ai_assistant
+  user: postgres
+  password: your_password
+```
+
+### Redis 配置
+
+```yaml
+redis:
+  host: localhost
+  port: 6379
+  db: 0
+```
+
+## Engine 服务配置
+
+Engine 服务配置位于 `engine/config/` 目录：
+
+### 助手默认配置
+
+参考 `engine/config/agents/default.yaml`：
+
+```yaml
+agent:
+  name: "默认助手"
+  language: "zh-CN"
+  temperature: 0.7
+  max_tokens: 2048
+```
+
+## 多环境配置
+
+### 开发环境
+
+```env
+# .env.development
+VITE_API_URL=http://localhost:8080
+```
+
+### 生产环境
+
+```env
+# .env.production
+VITE_API_URL=https://api.your-domain.com
+```
+
+## 配置优先级
+
+1. 命令行参数
+2. 环境变量
+3. `.env` 文件
+4. 默认值
diff --git a/docs/content/getting-started/index.md b/docs/content/getting-started/index.md
new file mode 100644
index 0000000..09d6201
--- /dev/null
+++ b/docs/content/getting-started/index.md
@@ -0,0 +1,55 @@
+# 安装部署
+
+本章节介绍如何安装和配置 AI Video Assistant 开发环境。
+
+## 概述
+
+AI Video Assistant 由以下组件构成：
+
+| 组件 | 说明 |
+|------|------|
+| **Web 前端** | React + TypeScript 构建的管理界面 |
+| **API 服务** | Python FastAPI 后端服务 |
+| **Engine 服务** | 实时对话引擎（WebSocket） |
+
+## 安装步骤
+
+### 1. 克隆项目
+
+```bash
+git clone https://github.com/your-repo/AI-VideoAssistant.git
+cd AI-VideoAssistant
+```
+
+### 2. 安装依赖
+
+```bash
+cd web
+npm install
+```
+
+### 3. 配置环境变量
+
+创建 `.env` 文件，详见 [配置说明](configuration.md)。
+
+### 4. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+访问 http://localhost:3000
+
+## 构建生产版本
+
+```bash
+npm run build
+```
+
+构建产物在 `dist` 目录。
+
+## 下一步
+
+- [环境要求](requirements.md) - 详细的软件版本要求
+- [配置说明](configuration.md) - 环境变量配置指南
+- [部署指南](../deployment/index.md) - 生产环境部署
diff --git a/docs/content/getting-started/requirements.md b/docs/content/getting-started/requirements.md
new file mode 100644
index 0000000..c689380
--- /dev/null
+++ b/docs/content/getting-started/requirements.md
@@ -0,0 +1,65 @@
+# 环境要求
+
+## 软件依赖
+
+### 必需软件
+
+| 软件 | 版本要求 | 说明 |
+|------|---------|------|
+| Node.js | 18.0 或更高 | JavaScript 运行时 |
+| npm/yarn/pnpm | 最新版本 | 包管理器 |
+| Python | 3.10+ | 后端服务运行环境 |
+
+### 推荐浏览器
+
+| 浏览器 | 版本要求 |
+|--------|---------|
+| Chrome | 90+ |
+| Firefox | 90+ |
+| Edge | 90+ |
+| Safari | 14+ |
+
+## 检查环境
+
+运行以下命令检查已安装的软件版本：
+
+```bash
+# 检查 Node.js 版本
+node --version
+
+# 检查 npm 版本
+npm --version
+
+# 检查 Python 版本
+python --version
+```
+
+## 硬件建议
+
+### 开发环境
+
+| 资源 | 建议配置 |
+|------|---------|
+| CPU | 4 核心以上 |
+| 内存 | 8GB 以上 |
+| 磁盘 | 20GB 可用空间 |
+
+### 生产环境
+
+| 资源 | 建议配置 |
+|------|---------|
+| CPU | 8 核心以上 |
+| 内存 | 16GB 以上 |
+| 磁盘 | 100GB SSD |
+| 网络 | 100Mbps 以上 |
+
+## 网络要求
+
+以下域名需要可访问（用于 API 调用）：
+
+| 服务 | 域名 |
+|------|------|
+| OpenAI | api.openai.com |
+| DeepSeek | api.deepseek.com |
+| 阿里云 TTS | nls-gateway.cn-shanghai.aliyuncs.com |
+| 火山引擎 | openspeech.bytedance.com |
diff --git a/docs/content/index.md b/docs/content/index.md
index 09e86c8..fcc0aeb 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -1,6 +1,4 @@
-# AI Video Assistant 使用说明
-
-## 产品概述
+# AI Video Assistant
 
 AI Video Assistant 是一款基于大语言模型的智能对话与工作流管理平台，支持多模型集成、语音合成、自动化测试等功能，帮助企业快速构建智能客服系统。
 
@@ -10,190 +8,51 @@ AI Video Assistant 是一款基于大语言模型的智能对话与工作流管
 
 | 功能模块 | 描述 |
 |---------|------|
-| **仪表盘** | 实时数据统计与可视化分析 |
 | **助手管理** | 创建、配置、测试 AI 助手 |
 | **工作流** | 可视化流程编排 |
 | **模型库** | LLM/ASR/语音模型配置 |
 | **知识库** | RAG 文档知识管理 |
 | **历史记录** | 对话日志查询与分析 |
 | **自动化测试** | 批量测试与质量评估 |
+| **仪表盘** | 实时数据统计与可视化分析 |
 
-## 快速开始
+## 快速导航
 
-### 环境要求
+<div class="grid cards" markdown>
 
-- Node.js 18+
-- 现代浏览器（Chrome/Firefox/Edge）
+- :rocket: **[快速开始](quickstart/index.md)**
 
-### 启动服务
+    5 分钟创建你的第一个 AI 助手
 
-```bash
-cd web
-npm install
-npm run dev
-```
+- :wrench: **[安装部署](getting-started/index.md)**
 
-访问 `http://localhost:3000`
+    环境准备与安装配置
 
-## 详细使用指南
+- :robot: **[助手管理](assistants/index.md)**
 
-### 1. 仪表盘
+    创建和配置智能对话助手
 
-![仪表盘](images/dashboard.png)
+- :gear: **[功能定制](customization/knowledge-base.md)**
 
-仪表盘展示系统核心指标：
-- **总对话数** - 累计对话请求数量
-- **回答率** - 成功回答的对话占比
-- **平均时长** - 单次对话平均持续时间
-- **人工转接率** - 需要人工介入的对话比例
+    知识库、工具、语音、工作流
 
-### 2. 助手管理
+- :bar_chart: **[数据分析](analysis/dashboard.md)**
 
-![助手管理](images/assistants.png)
+    仪表盘、历史记录、测试评估
 
-#### 创建助手
+- :book: **[API 参考](api-reference/index.md)**
 
-1. 点击 **创建助手**
-2. 配置助手基本信息（名称、提示词）
-3. 选择对话语言与音色
-4. 绑定知识库和工具
+    WebSocket 协议与接口文档
 
-#### 配置选项
+- :cloud: **[部署指南](deployment/index.md)**
 
-| 标签页 | 配置项 |
-|-------|--------|
-| 全局 | 名称、提示词、温度参数 |
-| 语音 | TTS 引擎、音色、语言 |
-| 工具 | 可用工具列表 |
-| 知识 | RAG 知识库关联 |
-| 链接 | 外部服务配置 |
+    Docker、Nginx 生产部署
 
-### 3. 工作流
+- :question: **[常见问题](resources/faq.md)**
 
-![工作流管理](images/workflows.png)
+    使用问题与故障排查
 
-#### 工作流节点类型
-
-| 节点 | 功能 |
-|------|------|
-| 对话节点 | AI 自动回复 |
-| 工具节点 | 调用外部工具 |
-| 人工节点 | 转接人工客服 |
-| 结束节点 | 结束对话流程 |
-
-### 4. 模型配置
-
-![模型库](images/llms.png)
-
-#### 支持的 LLM 模型
-
-- **OpenAI** - GPT-4/GPT-3.5
-- **DeepSeek** - DeepSeek Chat
-- **SiliconFlow** - 多种开源模型
-- **Google Gemini** - Gemini Pro
-
-#### ASR 语音识别
-
-- **Whisper** - OpenAI 语音识别
-- **SenseVoice** - 高精度中文识别
-
-### 5. 知识库
-
-![知识库](images/knowledge.png)
-
-#### 创建知识库
-
-1. 进入 **知识库** 页面
-2. 点击 **新建知识库**
-3. 上传文档（支持 Markdown/PDF/TXT）
-4. 配置检索参数
-
-### 6. 历史记录
-
-![历史记录](images/history.png)
-
-查询条件：
-- 按时间范围筛选
-- 按助手名称搜索
-- 查看对话详情与统计
-
-### 7. 自动化测试
-
-![自动化测试](images/autotest.png)
-
-#### 测试类型
-
-| 类型 | 说明 |
-|------|------|
-| 固定测试 | 预设问答对测试 |
-| 智能测试 | AI 生成测试用例 |
-
-#### 评估指标
-
-- 回复准确率
-- 回答完整度
-- 响应时间
-
-### 8. 语音合成
-
-![语音合成](images/voices.png)
-
-#### 支持的 TTS 引擎
-
-- **阿里云** - 多音色可选
-- **火山引擎** - 高自然度
-- **Minimax** - 低延迟
-
-### 9. 个人中心
-
-![个人中心](images/profile.png)
-
-管理账户信息与系统设置。
-
-## 部署指南
-
-### Docker 部署（推荐）
-
-```bash
-# 构建镜像
-docker build -t ai-video-assistant .
-
-# 运行容器
-docker run -d -p 3000:3000 --name ai-assistant ai-video-assistant
-```
-
-### Nginx 反向代理
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-## 常见问题
-
-### Q: 如何配置 API Key？
-
-进入 **LLM 库** 或 **语音库** 页面，点击对应模型的配置按钮填写 API Key。
-
-### Q: 助手无法回复？
-
-1. 检查模型配置是否正确
-2. 确认知识库已正确关联
-3. 查看系统日志排查错误
-
-### Q: 语音识别不准确？
-
-- 确认 ASR 模型选择正确
-- 检查音频采样率（推荐 16kHz）
-- 确认语言设置匹配
+</div>
 
 ## 技术支持
 
diff --git a/docs/content/quickstart/api.md b/docs/content/quickstart/api.md
new file mode 100644
index 0000000..ce4ad19
--- /dev/null
+++ b/docs/content/quickstart/api.md
@@ -0,0 +1,241 @@
+# 通过 API 创建助手
+
+本指南介绍如何通过 REST API 程序化创建和管理 AI 助手。
+
+## 前提条件
+
+- 已部署 API 服务（默认端口 8080）
+- 已配置 LLM 和 TTS 模型
+- 有可用的 HTTP 客户端（curl、Postman 等）
+
+## 步骤 1：创建助手
+
+### 请求
+
+```bash
+curl -X POST "http://localhost:8080/api/v1/assistants" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "客服助手",
+    "prompt": "你是一个友好的客服助手，负责解答用户问题。保持简洁、专业的回复风格。",
+    "opener": "你好，我是客服助手，请问有什么可以帮您？",
+    "language": "zh-CN",
+    "temperature": 0.7,
+    "max_tokens": 2048
+  }'
+```
+
+### 响应
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "asst_abc123",
+    "name": "客服助手",
+    "prompt": "你是一个友好的客服助手...",
+    "opener": "你好，我是客服助手...",
+    "language": "zh-CN",
+    "temperature": 0.7,
+    "created_at": "2025-01-01T00:00:00Z"
+  }
+}
+```
+
+记下返回的 `id`，后续步骤需要使用。
+
+## 步骤 2：配置语音
+
+### 配置 TTS
+
+```bash
+curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "voice": {
+      "vendor": "aliyun",
+      "voice_id": "xiaoyun",
+      "speed": 1.0,
+      "volume": 80,
+      "pitch": 1.0
+    }
+  }'
+```
+
+### 配置 ASR
+
+```bash
+curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "asr": {
+      "vendor": "sensevoice",
+      "language": "zh-CN"
+    }
+  }'
+```
+
+## 步骤 3：关联 LLM 模型
+
+```bash
+curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "llm_id": "llm_xyz789"
+  }'
+```
+
+## 步骤 4：关联知识库（可选）
+
+```bash
+curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "knowledge_base_id": "kb_def456",
+    "knowledge": {
+      "similarity_threshold": 0.7,
+      "top_k": 3
+    }
+  }'
+```
+
+## 步骤 5：发布助手
+
+```bash
+curl -X POST "http://localhost:8080/api/v1/assistants/asst_abc123/publish"
+```
+
+## 步骤 6：测试 WebSocket 连接
+
+### JavaScript 示例
+
+```javascript
+const assistantId = 'asst_abc123';
+const ws = new WebSocket(`ws://localhost:8000/ws?assistant_id=${assistantId}`);
+
+ws.onopen = () => {
+  console.log('连接已建立');
+  
+  // 发送 session.start
+  ws.send(JSON.stringify({
+    type: 'session.start',
+    audio: {
+      encoding: 'pcm_s16le',
+      sample_rate_hz: 16000,
+      channels: 1
+    }
+  }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('收到事件:', data.type);
+  
+  if (data.type === 'session.started') {
+    // 发送文本消息测试
+    ws.send(JSON.stringify({
+      type: 'input.text',
+      text: '你好，你能做什么？'
+    }));
+  }
+  
+  if (data.type === 'assistant.response.final') {
+    console.log('助手回复:', data.data.text);
+  }
+};
+
+ws.onerror = (error) => {
+  console.error('连接错误:', error);
+};
+
+ws.onclose = () => {
+  console.log('连接已关闭');
+};
+```
+
+### Python 示例
+
+```python
+import asyncio
+import websockets
+import json
+
+async def test_assistant():
+    uri = "ws://localhost:8000/ws?assistant_id=asst_abc123"
+    
+    async with websockets.connect(uri) as ws:
+        # 发送 session.start
+        await ws.send(json.dumps({
+            "type": "session.start",
+            "audio": {
+                "encoding": "pcm_s16le",
+                "sample_rate_hz": 16000,
+                "channels": 1
+            }
+        }))
+        
+        # 等待 session.started
+        response = await ws.recv()
+        print(f"收到: {response}")
+        
+        # 发送文本消息
+        await ws.send(json.dumps({
+            "type": "input.text",
+            "text": "你好，你能做什么？"
+        }))
+        
+        # 接收响应
+        while True:
+            response = await ws.recv()
+            data = json.loads(response)
+            print(f"事件: {data['type']}")
+            
+            if data['type'] == 'assistant.response.final':
+                print(f"回复: {data['data']['text']}")
+                break
+
+asyncio.run(test_assistant())
+```
+
+## 完整 API 参考
+
+### 助手管理 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/assistants | 获取助手列表 |
+| POST | /api/v1/assistants | 创建助手 |
+| GET | /api/v1/assistants/{id} | 获取助手详情 |
+| PATCH | /api/v1/assistants/{id} | 更新助手 |
+| DELETE | /api/v1/assistants/{id} | 删除助手 |
+| POST | /api/v1/assistants/{id}/publish | 发布助手 |
+
+### 助手字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 助手名称 |
+| prompt | string | 是 | 系统提示词 |
+| opener | string | 否 | 开场白 |
+| language | string | 否 | 语言代码 |
+| temperature | number | 否 | 温度参数（0-1） |
+| max_tokens | number | 否 | 最大输出长度 |
+| llm_id | string | 否 | 关联的 LLM 模型 ID |
+| voice | object | 否 | TTS 配置 |
+| asr | object | 否 | ASR 配置 |
+
+## 错误处理
+
+常见错误及解决方案：
+
+| 错误码 | 说明 | 解决方案 |
+|--------|------|---------|
+| 400 | 请求参数错误 | 检查请求体格式 |
+| 404 | 助手不存在 | 确认 assistant_id 正确 |
+| 500 | 服务器错误 | 查看服务端日志 |
+
+## 下一步
+
+- [WebSocket 协议详解](../api-reference/websocket.md)
+- [错误码参考](../api-reference/errors.md)
+- [配置知识库](../customization/knowledge-base.md)
diff --git a/docs/content/quickstart/dashboard.md b/docs/content/quickstart/dashboard.md
new file mode 100644
index 0000000..1030e35
--- /dev/null
+++ b/docs/content/quickstart/dashboard.md
@@ -0,0 +1,149 @@
+# 通过控制台创建助手
+
+本指南详细介绍如何通过 Web 控制台创建和配置 AI 助手。
+
+## 步骤 1：登录控制台
+
+1. 打开浏览器访问控制台地址（如 `http://localhost:3000`）
+2. 使用账号密码登录
+
+## 步骤 2：创建助手
+
+![创建助手](../images/assistants.png)
+
+1. 在左侧导航栏点击 **助手管理**
+2. 点击右上角 **新建助手** 按钮
+3. 在弹出的对话框中输入：
+   - **助手名称**：为你的助手起一个名字，如 "产品咨询助手"
+   - **描述**：简单描述助手的用途（可选）
+
+4. 点击 **创建**
+
+## 步骤 3：配置基本设置
+
+创建完成后，你将进入助手配置页面。
+
+### 全局设置
+
+| 配置项 | 建议值 | 说明 |
+|-------|--------|------|
+| 系统提示词 | 见下方示例 | 定义助手的角色和行为 |
+| 开场白 | "你好，我是产品咨询助手，请问有什么可以帮您？" | 对话开始时的问候 |
+| 温度 | 0.7 | 平衡创意和准确性 |
+
+### 系统提示词示例
+
+```
+你是一个专业的产品咨询助手。你的主要任务是：
+
+1. 解答用户关于产品功能的问题
+2. 提供使用建议和最佳实践
+3. 帮助用户解决常见问题
+
+请注意：
+- 保持友好和专业的语气
+- 回答简洁明了，避免冗长
+- 如果不确定答案，请如实告知并建议联系人工客服
+- 不要编造不存在的功能或信息
+```
+
+## 步骤 4：配置语音
+
+切换到 **语音配置** 标签页：
+
+### TTS 设置
+
+1. **选择 TTS 引擎**
+   - 阿里云：多音色、高自然度
+   - 火山引擎：低延迟
+   - Minimax：高性价比
+
+2. **选择音色**
+   - 根据助手定位选择合适的声音
+   - 建议先试听再确定
+
+3. **调整参数**
+   - 语速：1.0（正常速度）
+   - 音量：80%
+   - 音调：1.0
+
+### ASR 设置
+
+1. **选择 ASR 引擎**
+   - Whisper：通用识别
+   - SenseVoice：中文识别更准
+
+2. **设置语言**
+   - 选择 "中文" 或 "自动检测"
+
+## 步骤 5：关联知识库（可选）
+
+如果你已创建知识库，可以在 **知识** 标签页进行关联：
+
+1. 点击 **添加知识库**
+2. 选择要关联的知识库
+3. 设置检索参数：
+   - 相似度阈值：0.7
+   - 返回数量：3
+
+## 步骤 6：测试助手
+
+1. 点击页面右上角的 **保存** 按钮
+2. 点击 **测试** 按钮打开测试面板
+3. 进行对话测试：
+
+**测试用例建议：**
+
+| 测试类型 | 示例问题 |
+|---------|---------|
+| 基础问候 | "你好" |
+| 功能询问 | "你能做什么？" |
+| 业务问题 | "产品有哪些功能？" |
+| 边界测试 | "帮我写一首诗" |
+
+4. 检查回复是否符合预期
+5. 如有问题，返回修改配置
+
+## 步骤 7：发布助手
+
+测试通过后：
+
+1. 点击 **发布** 按钮
+2. 确认发布
+3. 复制生成的信息：
+   - `assistant_id`：用于 API 调用
+   - WebSocket 地址：用于实时对话
+
+## 嵌入到网页
+
+发布后，你可以将助手嵌入到你的网站：
+
+```html
+<!-- 添加到你的网页 -->
+<script>
+  const ws = new WebSocket('ws://your-server/ws?assistant_id=YOUR_ASSISTANT_ID');
+  // ... 实现对话逻辑
+</script>
+```
+
+详细集成指南请参考 [API 参考](../api-reference/websocket.md)。
+
+## 常见问题
+
+### 助手不回复？
+
+1. 检查 LLM 模型是否配置正确
+2. 查看浏览器控制台是否有错误
+3. 确认后端服务正常运行
+
+### 语音无法播放？
+
+1. 检查浏览器是否允许自动播放
+2. 确认 TTS 配置正确
+3. 检查音量设置
+
+## 下一步
+
+- [通过 API 创建助手](api.md)
+- [配置知识库](../customization/knowledge-base.md)
+- [添加工具](../customization/tools.md)
diff --git a/docs/content/quickstart/index.md b/docs/content/quickstart/index.md
new file mode 100644
index 0000000..ae6d7b8
--- /dev/null
+++ b/docs/content/quickstart/index.md
@@ -0,0 +1,126 @@
+# 快速开始
+
+5 分钟创建你的第一个 AI 助手。
+
+## 概述
+
+本指南将帮助你快速创建一个能够进行语音对话的智能助手。你可以选择通过控制台或 API 两种方式创建。
+
+## 前提条件
+
+- 已部署 AI Video Assistant 服务
+- 已配置至少一个 LLM 模型
+- 已配置至少一个 TTS 语音
+
+## 选择创建方式
+
+| 方式 | 适用场景 | 复杂度 |
+|------|---------|--------|
+| [通过控制台](dashboard.md) | 快速体验、可视化配置 | 简单 |
+| [通过 API](api.md) | 程序化创建、批量管理 | 中等 |
+
+---
+
+## 方式一：通过控制台创建
+
+### 步骤 1：创建助手
+
+1. 登录控制台，进入 **助手管理** 页面
+2. 点击 **新建助手**
+3. 输入助手名称，如 "客服助手"
+
+### 步骤 2：配置提示词
+
+在 **全局设置** 中配置系统提示词：
+
+```
+你是一个友好的客服助手。你的任务是帮助用户解答问题。
+
+要求：
+- 保持友好和专业的语气
+- 回答要简洁明了
+- 如果不确定答案，请如实告知
+```
+
+### 步骤 3：配置语音
+
+在 **语音配置** 中：
+
+1. 选择 TTS 引擎
+2. 选择合适的音色
+3. 调整语速为 1.0
+
+### 步骤 4：测试助手
+
+1. 点击 **保存**
+2. 点击 **测试** 按钮
+3. 输入 "你好，你能做什么？"
+4. 验证回复是否符合预期
+
+### 步骤 5：发布助手
+
+1. 确认测试通过后，点击 **发布**
+2. 复制生成的 `assistant_id`
+
+---
+
+## 方式二：通过 API 创建
+
+### 步骤 1：创建助手
+
+```bash
+curl -X POST "http://localhost:8080/api/v1/assistants" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "客服助手",
+    "prompt": "你是一个友好的客服助手。",
+    "language": "zh-CN",
+    "temperature": 0.7
+  }'
+```
+
+### 步骤 2：配置语音
+
+```bash
+curl -X PATCH "http://localhost:8080/api/v1/assistants/{assistant_id}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "voice": {
+      "vendor": "aliyun",
+      "voice_id": "xiaoyun",
+      "speed": 1.0
+    }
+  }'
+```
+
+### 步骤 3：测试连接
+
+```javascript
+const ws = new WebSocket('ws://localhost:8000/ws?assistant_id=YOUR_ASSISTANT_ID');
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'session.start',
+    audio: {
+      encoding: 'pcm_s16le',
+      sample_rate_hz: 16000,
+      channels: 1
+    }
+  }));
+};
+
+ws.onmessage = (event) => {
+  console.log('收到消息:', event.data);
+};
+```
+
+---
+
+## 下一步
+
+恭喜！你已成功创建了第一个 AI 助手。接下来可以：
+
+- [配置知识库](../customization/knowledge-base.md) - 让助手回答专业问题
+- [添加工具](../customization/tools.md) - 扩展助手能力
+- [查看 API 文档](../api-reference/websocket.md) - 深入了解协议细节
+- [部署到生产环境](../deployment/index.md) - 正式上线
diff --git a/docs/content/resources/faq.md b/docs/content/resources/faq.md
new file mode 100644
index 0000000..0b1b729
--- /dev/null
+++ b/docs/content/resources/faq.md
@@ -0,0 +1,110 @@
+# 常见问题
+
+## API Key 配置
+
+### Q: 如何配置 API Key？
+
+进入 **LLM 库** 或 **语音库** 页面，点击对应模型的配置按钮填写 API Key。
+
+**步骤：**
+
+1. 在左侧导航栏选择 **模型配置**
+2. 选择 **LLM 库** 或 **语音库**
+3. 点击已添加模型的 **编辑** 按钮
+4. 在 API Key 字段填写你的密钥
+5. 点击 **保存**
+
+## 助手问题
+
+### Q: 助手无法回复？
+
+可能的原因和解决方案：
+
+1. **检查模型配置是否正确**
+   - 确认 API Key 已正确填写
+   - 测试模型连接是否正常
+
+2. **确认知识库已正确关联**
+   - 进入助手配置的 **知识** 标签页
+   - 检查是否已选择知识库
+
+3. **查看系统日志排查错误**
+   - 打开浏览器开发者工具（F12）
+   - 检查 Console 和 Network 标签页
+
+### Q: 助手回复内容不相关？
+
+- 检查系统提示词是否清晰明确
+- 调整 Temperature 参数（降低可提高准确性）
+- 确认知识库内容与问题相关
+- 增加知识库相似度阈值
+
+## 语音识别
+
+### Q: 语音识别不准确？
+
+1. **确认 ASR 模型选择正确**
+   - 中文场景推荐使用 SenseVoice
+   - 英文场景推荐使用 Whisper
+
+2. **检查音频采样率**
+   - 推荐采样率：16kHz
+   - 推荐格式：PCM 16-bit
+
+3. **确认语言设置匹配**
+   - 在 ASR 配置中选择正确的语言
+
+### Q: 语音延迟较高？
+
+- 检查网络连接稳定性
+- 尝试切换 ASR 服务提供商
+- 降低音频质量以减少传输数据量
+
+## 语音合成
+
+### Q: TTS 声音不自然？
+
+- 尝试不同的音色选项
+- 调整语速参数（推荐 0.8-1.2）
+- 选择与内容风格匹配的声音
+
+### Q: TTS 无法播放？
+
+1. 检查浏览器是否允许自动播放音频
+2. 确认 TTS API Key 配置正确
+3. 检查网络连接
+
+## 知识库
+
+### Q: 知识库检索无结果？
+
+- 确认文档已成功上传
+- 降低相似度阈值（默认 0.7）
+- 增加返回结果数量
+- 检查文档内容是否与查询相关
+
+### Q: 文档上传失败？
+
+- 检查文件大小是否超过 10MB
+- 确认文件格式支持（MD/PDF/TXT）
+- 尝试减小文档内容
+
+## 部署问题
+
+### Q: 页面空白或加载失败？
+
+1. 检查浏览器控制台错误信息
+2. 确认后端服务已启动
+3. 检查 VITE_API_URL 环境变量配置
+
+### Q: API 请求失败？
+
+- 确认 VITE_API_URL 配置正确
+- 检查后端服务是否运行
+- 查看网络请求响应状态码
+
+### Q: 静态资源 404？
+
+- 检查 Nginx `try_files` 配置
+- 确认构建产物路径正确
+- 检查文件权限设置
diff --git a/docs/content/resources/troubleshooting.md b/docs/content/resources/troubleshooting.md
new file mode 100644
index 0000000..5bd6833
--- /dev/null
+++ b/docs/content/resources/troubleshooting.md
@@ -0,0 +1,292 @@
+# 故障排查
+
+本文档汇总常见问题的排查步骤和解决方案。
+
+## 连接问题
+
+### WebSocket 连接失败
+
+**症状**：无法建立 WebSocket 连接，控制台显示连接错误。
+
+**排查步骤**：
+
+1. **检查服务状态**
+   ```bash
+   # 检查 Engine 服务是否运行
+   curl http://localhost:8000/health
+   ```
+
+2. **验证连接地址**
+   - 确认 host 和 port 正确
+   - 确认 assistant_id 参数存在
+
+3. **检查网络**
+   - 确认防火墙未阻止 WebSocket
+   - 检查 Nginx 代理配置（如有）
+
+4. **查看服务日志**
+   ```bash
+   docker logs ai-assistant-engine
+   ```
+
+**常见原因**：
+- Engine 服务未启动
+- assistant_id 无效
+- 防火墙阻止 WebSocket 端口
+
+---
+
+### API 请求失败
+
+**症状**：REST API 返回错误或超时。
+
+**排查步骤**：
+
+1. **检查 API 服务**
+   ```bash
+   curl http://localhost:8080/health
+   ```
+
+2. **验证请求格式**
+   - Content-Type 是否为 application/json
+   - 请求体是否为有效 JSON
+
+3. **检查认证**
+   - Authorization header 是否正确
+   - API Key 是否有效
+
+4. **查看响应详情**
+   ```bash
+   curl -v http://localhost:8080/api/v1/assistants
+   ```
+
+---
+
+## 助手问题
+
+### 助手不回复
+
+**症状**：发送消息后没有收到助手回复。
+
+**排查步骤**：
+
+1. **检查会话状态**
+   - 确认收到 `session.started` 事件
+   - 确认没有 `error` 事件
+
+2. **检查 LLM 配置**
+   - API Key 是否有效
+   - 模型配置是否正确
+   - 测试模型连接
+
+3. **查看日志**
+   - 检查 LLM 调用是否成功
+   - 查看是否有超时错误
+
+**常见原因**：
+- LLM API Key 无效或过期
+- 模型服务不可用
+- 请求超时
+
+---
+
+### 回复质量差
+
+**症状**：助手回复不准确、不相关或格式混乱。
+
+**排查步骤**：
+
+1. **检查提示词**
+   - 是否有明确的角色定义
+   - 是否有清晰的任务描述
+   - 是否有必要的约束
+
+2. **调整参数**
+   - 降低 temperature 提高一致性
+   - 调整 max_tokens 控制长度
+
+3. **检查知识库**
+   - 确认知识库已关联
+   - 测试检索结果是否相关
+
+4. **查看对话历史**
+   - 分析问题出现的模式
+   - 收集典型的失败案例
+
+---
+
+## 语音问题
+
+### 语音识别不准确
+
+**症状**：ASR 识别结果与实际说话内容不符。
+
+**排查步骤**：
+
+1. **检查音频质量**
+   - 麦克风是否正常工作
+   - 环境是否嘈杂
+   - 采样率是否正确（16kHz）
+
+2. **验证 ASR 配置**
+   - 语言设置是否正确
+   - 是否配置了热词
+
+3. **测试不同引擎**
+   - 尝试切换 ASR 服务提供商
+   - 对比识别效果
+
+**改进建议**：
+- 添加业务相关的热词
+- 使用降噪麦克风
+- 选择针对中文优化的 ASR 引擎
+
+---
+
+### 语音无法播放
+
+**症状**：TTS 合成成功但没有声音输出。
+
+**排查步骤**：
+
+1. **检查浏览器设置**
+   - 是否允许自动播放音频
+   - 音量是否静音
+
+2. **验证音频数据**
+   - 确认收到 `output.audio.start` 事件
+   - 确认收到二进制音频帧
+   - 确认收到 `output.audio.end` 事件
+
+3. **检查音频解码**
+   - PCM 格式是否正确解析
+   - AudioContext 是否正确初始化
+
+4. **测试 TTS 服务**
+   - 单独测试 TTS 配置
+   - 检查 TTS API 状态
+
+---
+
+## 部署问题
+
+### Docker 容器启动失败
+
+**症状**：容器无法启动或立即退出。
+
+**排查步骤**：
+
+1. **查看容器日志**
+   ```bash
+   docker logs <container_name>
+   ```
+
+2. **检查资源限制**
+   ```bash
+   docker stats
+   ```
+
+3. **验证配置文件**
+   - 环境变量是否正确
+   - 配置文件路径是否存在
+
+4. **检查端口冲突**
+   ```bash
+   netstat -an | grep <port>
+   ```
+
+---
+
+### 页面加载空白
+
+**症状**：浏览器打开页面但内容为空。
+
+**排查步骤**：
+
+1. **检查浏览器控制台**
+   - 打开 F12 开发者工具
+   - 查看 Console 错误信息
+
+2. **验证静态资源**
+   - 检查 Network 标签页
+   - 确认 JS/CSS 文件加载成功
+
+3. **检查 API 连接**
+   - 确认 VITE_API_URL 配置正确
+   - 测试 API 是否可访问
+
+4. **清除缓存**
+   ```bash
+   # 强制刷新
+   Ctrl + Shift + R
+   ```
+
+---
+
+## 性能问题
+
+### 响应延迟高
+
+**症状**：从发送消息到收到回复时间过长。
+
+**排查步骤**：
+
+1. **定位延迟环节**
+   - ASR 处理时间
+   - LLM 推理时间
+   - TTS 合成时间
+
+2. **查看性能指标**
+   - 检查 `metrics.ttfb` 事件
+   - 分析各环节耗时
+
+3. **优化配置**
+   - 使用更快的模型
+   - 减少 max_tokens
+   - 启用流式输出
+
+4. **检查网络**
+   - 测试到各 API 的延迟
+   - 考虑使用更近的服务区域
+
+---
+
+## 日志查看
+
+### 服务端日志
+
+```bash
+# Docker 容器日志
+docker logs -f ai-assistant-engine
+
+# 查看最近 100 行
+docker logs --tail 100 ai-assistant-engine
+```
+
+### 客户端日志
+
+在浏览器开发者工具中：
+
+1. **Console** - 查看 JavaScript 错误和日志
+2. **Network** - 查看网络请求和响应
+3. **WebSocket** - 查看 WS 消息（在 Network 标签页）
+
+### 启用详细日志
+
+设置环境变量启用调试日志：
+
+```bash
+# Engine 服务
+LOG_LEVEL=debug
+
+# API 服务
+DEBUG=true
+```
+
+## 获取帮助
+
+如果以上方法无法解决问题：
+
+1. 收集相关日志和错误信息
+2. 描述复现步骤
+3. 提交 Issue 或联系技术支持
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 4197f78..9ebac79 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -7,17 +7,84 @@ docs_dir: "content"
 site_dir: "site"
 
 nav:
-  - 首页: "index.md"
-  - 快速开始: "getting-started.md"
-  - 功能介绍:
-      - 仪表盘: "features/dashboard.md"
-      - 助手管理: "features/assistants.md"
-      - 工作流: "features/workflows.md"
-      - 模型配置: "features/models.md"
-      - 知识库: "features/knowledge.md"
-      - 历史记录: "features/history.md"
-      - 自动化测试: "features/autotest.md"
-      - 语音合成: "features/voices.md"
-  - 部署指南: "deployment.md"
+  - 首页: index.md
+  - 快速开始:
+      - 概览: quickstart/index.md
+      - 通过控制台: quickstart/dashboard.md
+      - 通过 API: quickstart/api.md
+  - 安装部署:
+      - 概览: getting-started/index.md
+      - 环境要求: getting-started/requirements.md
+      - 配置说明: getting-started/configuration.md
+  - 助手管理:
+      - 概览: assistants/index.md
+      - 配置选项: assistants/configuration.md
+      - 提示词指南: assistants/prompts.md
+      - 测试调试: assistants/testing.md
+  - 功能定制:
+      - 知识库: customization/knowledge-base.md
+      - 工具集成: customization/tools.md
+      - 语音配置: customization/voices.md
+      - 模型配置: customization/models.md
+      - 工作流: customization/workflows.md
+  - 数据分析:
+      - 仪表盘: analysis/dashboard.md
+      - 历史记录: analysis/history.md
+      - 效果评估: analysis/evaluation.md
+      - 自动化测试: analysis/autotest.md
   - API 参考:
-      - WebSocket: "api-reference.md"
+      - 概览: api-reference/index.md
+      - WebSocket 协议: api-reference/websocket.md
+      - 错误码: api-reference/errors.md
+  - 部署指南:
+      - 概览: deployment/index.md
+      - Docker 部署: deployment/docker.md
+      - 生产环境: deployment/production.md
+  - 资源:
+      - 常见问题: resources/faq.md
+      - 故障排查: resources/troubleshooting.md
+
+theme:
+  name: material
+  language: zh
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: 切换到深色模式
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: 切换到浅色模式
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - attr_list
+  - md_in_html
+
+plugins:
+  - search:
+      lang: zh