Luxx/docs/API.md

# API 接口文档

## 认证 `/api/auth`

### POST /api/auth/register
用户注册

**请求体：**
```json
{
  "username": "string",
  "email": "user@example.com",
  "password": "string"
}
```

**响应：**
```json
{
  "success": true,
  "message": "注册成功",
  "data": {
    "id": 1,
    "username": "string"
  }
}
```

### POST /api/auth/login
用户登录

**请求体：**
```json
{
  "username": "string",
  "password": "string"
}
```

**响应：**
```json
{
  "success": true,
  "message": "登录成功",
  "data": {
    "access_token": "eyJ...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "string",
      "role": "user"
    }
  }
}
```

### POST /api/auth/logout
用户登出

**请求头：** `Authorization: Bearer <token>`

**响应：**
```json
{
  "success": true,
  "message": "登出成功"
}
```

### GET /api/auth/me
获取当前用户信息

**请求头：** `Authorization: Bearer <token>`

**响应：**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "string",
    "email": "user@example.com",
    "role": "user",
    "is_active": true
  }
}
```

---

## 会话 `/api/conversations`

### GET /api/conversations/
获取会话列表

**查询参数：**
- `project_id` (可选): 项目ID
- `page` (可选): 页码，默认1
- `page_size` (可选): 每页数量，默认20

**请求头：** `Authorization: Bearer <token>`

**响应：**
```json
{
  "success": true,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}
```

### POST /api/conversations/
创建会话

**请求头：** `Authorization: Bearer <token>`

**请求体：**
```json
{
  "project_id": "string (可选)",
  "title": "新会话",
  "model": "glm-5",
  "system_prompt": "string (可选)",
  "temperature": 1.0,
  "max_tokens": 65536,
  "thinking_enabled": false
}
```

**响应：**
```json
{
  "success": true,
  "message": "会话创建成功",
  "data": {
    "id": "conv_xxx",
    "user_id": 1,
    "title": "新会话",
    "model": "glm-5",
    ...
  }
}
```

### GET /api/conversations/{id}
获取会话详情

**路径参数：**
- `id`: 会话ID

**请求头：** `Authorization: Bearer <token>`

### PUT /api/conversations/{id}
更新会话

### DELETE /api/conversations/{id}
删除会话

---

## 消息 `/api/messages`

### GET /api/messages/{conversation_id}
获取消息列表

**路径参数：**
- `conversation_id`: 会话ID

**查询参数：**
- `limit` (可选): 返回数量，默认100

**请求头：** `Authorization: Bearer <token>`

### POST /api/messages/
发送消息（非流式）

**请求头：** `Authorization: Bearer <token>`

**请求体：**
```json
{
  "conversation_id": "conv_xxx",
  "content": "用户消息",
  "tools_enabled": true
}
```

**响应：**
```json
{
  "success": true,
  "data": {
    "user_message": {...},
    "assistant_message": {...}
  }
}
```

### POST /api/messages/stream
发送消息（流式响应）

使用 Server-Sent Events (SSE) 返回流式响应。

**事件类型：**
- `text`: 文本增量
- `tool_call`: 工具调用
- `tool_result`: 工具结果
- `done`: 完成
- `error`: 错误

### DELETE /api/messages/{id}
删除消息

---

## 工具 `/api/tools`

### GET /api/tools/
获取可用工具列表

**查询参数：**
- `category` (可选): 工具分类

**请求头：** `Authorization: Bearer <token>`

**响应：**
```json
{
  "success": true,
  "data": {
    "tools": [...],
    "categorized": {
      "crawler": [...],
      "code": [...],
      "data": [...],
      "weather": [...]
    },
    "total": 11
  }
}
```

### GET /api/tools/{name}
获取工具详情

### POST /api/tools/{name}/execute
手动执行工具

**请求体：**
```json
{
  "arg1": "value1",
  "arg2": "value2"
}
```