# 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
  }
}
```