Revamp documentation structure in mkdocs.yml by reorganizing navigation for improved accessibility. Remove outdated content from previous sections and introduce new topics including detailed guides on assistant management, configuration options, and tool integrations. Enhance API reference documentation with comprehensive error codes and WebSocket protocol details. Add new sections for automated testing, data analysis, and knowledge base management, ensuring a cohesive and user-friendly documentation experience.

2026-03-01 22:38:50 +08:00
parent 6a46ec69f4
commit 2418df80e5
33 changed files with 3664 additions and 693 deletions
--- a/docs/content/api-reference/index.md
+++ 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 使用示例