279 lines
5.7 KiB
Markdown
279 lines
5.7 KiB
Markdown
# API 接口文档
|
||
|
||
## 认证 `/api/auth`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/auth/register` | 用户注册 |
|
||
| POST | `/api/auth/login` | 用户登录 |
|
||
| POST | `/api/auth/logout` | 用户登出 |
|
||
| GET | `/api/auth/me` | 获取当前用户信息 |
|
||
|
||
### POST /api/auth/register
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"email": "user@example.com",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
### POST /api/auth/login
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 会话 `/api/conversations`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/conversations/` | 获取会话列表 |
|
||
| POST | `/api/conversations/` | 创建会话 |
|
||
| GET | `/api/conversations/{id}` | 获取会话详情 |
|
||
| PUT | `/api/conversations/{id}` | 更新会话 |
|
||
| DELETE | `/api/conversations/{id}` | 删除会话 |
|
||
|
||
### 创建会话请求体
|
||
|
||
```json
|
||
{
|
||
"project_id": "string (可选)",
|
||
"title": "新会话",
|
||
"model": "glm-5",
|
||
"system_prompt": "string (可选)",
|
||
"temperature": 1.0,
|
||
"max_tokens": 65536,
|
||
"thinking_enabled": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 消息 `/api/messages`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/messages/{conversation_id}` | 获取消息列表 |
|
||
| POST | `/api/messages/` | 发送消息（非流式） |
|
||
| POST | `/api/messages/stream` | 发送消息（流式 SSE） |
|
||
| DELETE | `/api/messages/{id}` | 删除消息 |
|
||
|
||
### 发送消息请求体
|
||
|
||
```json
|
||
{
|
||
"conversation_id": "conv_xxx",
|
||
"content": "用户消息",
|
||
"tools_enabled": true
|
||
}
|
||
```
|
||
|
||
### SSE 事件类型
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `text` | 文本增量 |
|
||
| `tool_call` | 工具调用 |
|
||
| `tool_result` | 工具结果 |
|
||
| `done` | 完成 |
|
||
| `error` | 错误 |
|
||
|
||
---
|
||
|
||
## 聊天室 `/api/chat-rooms`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/chat-rooms/` | 获取聊天室列表 |
|
||
| POST | `/api/chat-rooms/` | 创建聊天室 |
|
||
| GET | `/api/chat-rooms/{room_id}` | 获取聊天室详情 |
|
||
| PUT | `/api/chat-rooms/{room_id}` | 更新聊天室 |
|
||
| DELETE | `/api/chat-rooms/{room_id}` | 删除聊天室 |
|
||
| GET | `/api/chat-rooms/{room_id}/agents` | 获取聊天室中的 Agent 列表 |
|
||
| POST | `/api/chat-rooms/{room_id}/agents` | 添加 Agent 到聊天室 |
|
||
| DELETE | `/api/chat-rooms/{room_id}/agents/{agent_id}` | 从聊天室移除 Agent |
|
||
| GET | `/api/chat-rooms/{room_id}/messages` | 获取聊天室消息历史 |
|
||
| POST | `/api/chat-rooms/{room_id}/messages` | 发送消息到聊天室（SSE 流式响应） |
|
||
|
||
### 创建聊天室请求体
|
||
|
||
```json
|
||
{
|
||
"name": "聊天室名称",
|
||
"description": "描述（可选）",
|
||
"agent_ids": ["agent-1", "agent-2"]
|
||
}
|
||
```
|
||
|
||
### 添加 Agent 请求体
|
||
|
||
```json
|
||
{
|
||
"agent_id": "agent-1"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## WebSocket `/ws/chat-room/{room_id}`
|
||
|
||
### 连接参数
|
||
|
||
| 参数 | 类型 | 说明 | 示例 |
|
||
|------|------|------|------|
|
||
| `participant_type` | string | `user` 或 `agent` | `user` |
|
||
| `participant_id` | string | 用户 ID 或 Agent ID | `1` |
|
||
| `participant_name` | string | 显示名称 | `John` |
|
||
|
||
### 连接示例
|
||
|
||
**用户连接：**
|
||
```
|
||
ws://host/ws/chat-room/room-123?participant_type=user&participant_id=1&participant_name=John
|
||
```
|
||
|
||
**Agent 连接：**
|
||
```
|
||
ws://host/ws/chat-room/room-123?participant_type=agent&participant_id=agent-1&participant_name=Assistant
|
||
```
|
||
|
||
### 发送消息
|
||
|
||
```json
|
||
{
|
||
"action": "send_message",
|
||
"content": "Hello everyone!"
|
||
}
|
||
```
|
||
|
||
### 接收事件
|
||
|
||
| 事件 | 说明 | 数据示例 |
|
||
|------|------|---------|
|
||
| `connected` | 连接成功 | `{"room_id": "xxx", "type": "user"}` |
|
||
| `history` | 历史消息 | `{"messages": [...]}` |
|
||
| `agents` | Agent 列表 | `{"agents": [...]}` |
|
||
| `message` | 新消息 | 消息对象 |
|
||
| `typing` | 打字状态 | `{"agent_id": "xxx", "is_typing": true}` |
|
||
| `process_step` | 处理步骤 | 步骤对象 |
|
||
| `done` | 完成 | `{"message_id": "xxx", "token_count": 100}` |
|
||
| `error` | 错误 | `{"content": "error message"}` |
|
||
| `system` | 系统消息 | `{"content": "John joined", "type": "user_join"}` |
|
||
|
||
---
|
||
|
||
## Agent `/api/agents`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/agents/` | 获取 Agent 列表 |
|
||
| POST | `/api/agents/` | 创建 Agent |
|
||
| GET | `/api/agents/{id}` | 获取 Agent 详情 |
|
||
| PUT | `/api/agents/{id}` | 更新 Agent |
|
||
| DELETE | `/api/agents/{id}` | 删除 Agent |
|
||
|
||
---
|
||
|
||
## 工具 `/api/tools`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/tools/` | 获取可用工具列表 |
|
||
| GET | `/api/tools/{name}` | 获取工具详情 |
|
||
| POST | `/api/tools/{name}/execute` | 手动执行工具 |
|
||
|
||
### 工具列表响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"tools": [...],
|
||
"categorized": {
|
||
"crawler": [...],
|
||
"code": [...],
|
||
"data": [...]
|
||
},
|
||
"total": 11
|
||
}
|
||
}
|
||
```
|
||
|
||
### 执行工具请求体
|
||
|
||
```json
|
||
{
|
||
"arg1": "value1",
|
||
"arg2": "value2"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## LLM 提供商 `/api/providers`
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/providers/` | 获取提供商列表 |
|
||
| POST | `/api/providers/` | 创建提供商 |
|
||
| GET | `/api/providers/{id}` | 获取提供商详情 |
|
||
| PUT | `/api/providers/{id}` | 更新提供商 |
|
||
| DELETE | `/api/providers/{id}` | 删除提供商 |
|
||
| POST | `/api/providers/{id}/test` | 测试提供商连接 |
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/health` | 健康检查 |
|
||
| GET | `/` | 服务信息 |
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {...}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误信息",
|
||
"code": 404
|
||
}
|
||
```
|
||
|
||
### 分页响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|