# API 接口文档

## 认证 `/api/auth`

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

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

**响应：**
```json
{
  "success": true,
  "message": "Registration successful",
  "data": {
    "id": 1,
    "username": "string"
  }
}
```

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

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

**响应：**
```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "access_token": "eyJ...",
    "token_type": "bearer",
    "user": {
      "id": 1,
      "username": "string",
      "email": "user@example.com",
      "role": "user",
      "permission_level": 1,
      "workspace_path": null,
      "is_active": true
    }
  }
}
```

**用户权限级别：**
| 级别 | 名称 | 说明 |
|------|------|------|
| 1 | READ_ONLY | 只读权限 |
| 2 | WRITE | 写入权限 |
| 3 | EXECUTE | 执行权限 |
| 4 | ADMIN | 管理员权限 |

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

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

**响应：**
```json
{
  "success": true,
  "message": "Logout successful"
}
```

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

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

**响应：**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "string",
    "email": "user@example.com",
    "role": "user",
    "permission_level": 1,
    "workspace_path": null,
    "is_active": true,
    "created_at": "2024-01-01T00:00:00"
  }
}
```

### GET /api/auth/users
获取所有用户（管理员专用）

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

**响应：**
```json
{
  "success": true,
  "data": {
    "users": [...]
  }
}
```

### PUT /api/auth/users/{user_id}
更新用户权限（管理员专用）

**请求体：**
```json
{
  "permission_level": 2
}
```

---

## 会话 `/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": "deepseek-chat",
  "provider_id": 1,
  "system_prompt": "You are a helpful assistant. (可选)",
  "temperature": 0.7,
  "max_tokens": 2000,
  "thinking_enabled": false
}
```

**响应：**
```json
{
  "success": true,
  "message": "会话创建成功",
  "data": {
    "id": "conv_xxx",
    "user_id": 1,
    "provider_id": 1,
    "title": "新会话",
    "model": "deepseek-chat",
    "system_prompt": "You are a helpful assistant.",
    "temperature": 0.7,
    "max_tokens": 2000,
    "thinking_enabled": false,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

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

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

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

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

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

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

**请求体：**
```json
{
  "title": "新标题",
  "model": "gpt-4",
  "provider_id": 1,
  "system_prompt": "You are...",
  "temperature": 0.8,
  "max_tokens": 4000,
  "thinking_enabled": true
}
```

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

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

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

---

## 消息 `/api/messages`

### GET /api/messages/
获取消息列表

**查询参数：**
- `conversation_id`: 会话ID（必需）
- `limit` (可选): 返回数量，默认100

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

**响应：**
```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_xxx",
        "conversation_id": "conv_xxx",
        "role": "user",
        "content": "用户消息",
        "text": "用户消息",
        "attachments": [],
        "process_steps": [],
        "token_count": 10,
        "usage": null,
        "created_at": "2024-01-01T00:00:00"
      },
      {
        "id": "msg_yyy",
        "conversation_id": "conv_xxx",
        "role": "assistant",
        "content": "AI 回复文本内容",
        "text": "AI 回复文本内容",
        "attachments": [],
        "process_steps": [
          {"id": "step-0", "index": 0, "type": "thinking", "content": "让我思考..."},
          {"id": "step-1", "index": 1, "type": "text", "content": "根据搜索结果..."},
          {"id": "step-2", "index": 2, "type": "tool_call", "id_ref": "call_xxx", "name": "web_search", "arguments": "..."},
          {"id": "step-3", "index": 3, "type": "tool_result", "id_ref": "call_xxx", "name": "web_search", "content": "...", "success": true}
        ],
        "token_count": 100,
        "usage": {"prompt_tokens": 50, "completion_tokens": 50, "total_tokens": 100},
        "created_at": "2024-01-01T00:00:01"
      }
    ],
    "title": "会话标题",
    "first_message": "用户的第一条消息..."
  }
}
```

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

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

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

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

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

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

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

**请求体：**
```json
{
  "conversation_id": "conv_xxx",
  "content": "用户消息",
  "thinking_enabled": true,
  "enabled_tools": ["web_search", "file_read", "python_execute"]
}
```

**SSE 事件类型：**

#### process_step
结构化步骤事件（渲染顺序的唯一数据源）

```json
event: process_step
data: {"step": {"id": "step-0", "index": 0, "type": "thinking", "content": "让我思考一下..."}}

event: process_step
data: {"step": {"id": "step-1", "index": 1, "type": "text", "content": "以下是搜索结果："}}

event: process_step
data: {"step": {"id": "step-2", "index": 2, "type": "tool_call", "id_ref": "call_abc", "name": "web_search", "arguments": "{\"query\": \"...\"}"}}

event: process_step
data: {"step": {"id": "step-3", "index": 3, "type": "tool_result", "id_ref": "call_abc", "name": "web_search", "content": "{...}", "success": true}}
```

**步骤类型说明：**

| type | 说明 | 额外字段 |
|------|------|---------|
| `thinking` | 模型思考过程 | `content` |
| `text` | 文本回复 | `content` |
| `tool_call` | 工具调用 | `id_ref`, `name`, `arguments` |
| `tool_result` | 工具执行结果 | `id_ref`, `name`, `content`, `success` |

#### done
响应完成

```json
event: done
data: {"message_id": "msg_xxx", "token_count": 150, "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150}}
```

#### error
错误信息

```json
event: error
data: {"content": "错误信息描述"}
```

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

**路径参数：** `message_id`: 消息ID

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

---

## LLM 提供商 `/api/providers`

### GET /api/providers/
获取用户的 LLM 提供商列表

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

**响应：**
```json
{
  "success": true,
  "data": {
    "providers": [
      {
        "id": 1,
        "user_id": 1,
        "name": "DeepSeek",
        "provider_type": "openai",
        "base_url": "https://api.deepseek.com/v1",
        "default_model": "deepseek-chat",
        "max_tokens": 8192,
        "is_default": true,
        "enabled": true,
        "created_at": "2024-01-01T00:00:00",
        "updated_at": "2024-01-01T00:00:00"
      }
    ],
    "total": 1
  }
}
```

### POST /api/providers/
创建 LLM 提供商

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

**请求体：**
```json
{
  "name": "DeepSeek",
  "provider_type": "openai",
  "base_url": "https://api.deepseek.com/v1",
  "api_key": "sk-xxxx",
  "default_model": "deepseek-chat",
  "is_default": true
}
```

**provider_type 可选值：**
- `openai` - OpenAI/DeepSeek/GLM 兼容 API
- `anthropic` - Anthropic Claude API

### GET /api/providers/{provider_id}
获取提供商详情

**路径参数：** `provider_id`: 提供商ID

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

### PUT /api/providers/{provider_id}
更新提供商

**路径参数：** `provider_id`: 提供商ID

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

**请求体：**
```json
{
  "name": "新名称",
  "base_url": "https://api.example.com/v1",
  "api_key": "sk-yyyy",
  "default_model": "gpt-4",
  "max_tokens": 16384,
  "is_default": false,
  "enabled": true
}
```

### DELETE /api/providers/{provider_id}
删除提供商

**路径参数：** `provider_id`: 提供商ID

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

### POST /api/providers/{provider_id}/test
测试提供商连接

**路径参数：** `provider_id`: 提供商ID

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

**响应：**
```json
{
  "success": true,
  "message": "HTTP 200: ...",
  "data": {
    "status_code": 200,
    "success": true,
    "response_body": "..."
  }
}
```

---

## 工具 `/api/tools`

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

**查询参数：**
- `category` (可选): 工具分类（code/file/shell/crawler/data）

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

**响应：**
```json
{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "python_execute",
        "description": "Execute Python code",
        "category": "code",
        "parameters": {...}
      },
      ...
    ],
    "categorized": {
      "code": [...],
      "file": [...],
      "shell": [...],
      "crawler": [...],
      "data": [...]
    },
    "total": 11
  }
}
```

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

**路径参数：** `name`: 工具名称

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

**响应：**
```json
{
  "success": true,
  "data": {
    "name": "web_search",
    "description": "Search the web using DuckDuckGo",
    "category": "crawler",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        }
      },
      "required": ["query"]
    }
  }
}
```

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

**路径参数：** `name`: 工具名称

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

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

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

---

## 公共端点

### GET /api/health
健康检查

**响应：**
```json
{
  "status": "ok",
  "message": "Luxx API is running"
}
```

### GET /api/
服务信息

**响应：**
```json
{
  "name": "Luxx",
  "version": "1.0.0",
  "description": "AI Chat API"
}
```

---

## 工具说明

### 内置工具

#### 代码执行 (code)
| 工具 | 功能 | 权限 |
|------|------|------|
| `python_execute` | 执行 Python 代码 | EXECUTE |
| `python_eval` | 计算表达式 | EXECUTE |

#### 文件操作 (file)
| 工具 | 功能 | 权限 |
|------|------|------|
| `file_read` | 读取文件内容 | READ_ONLY |
| `file_write` | 写入文件内容 | WRITE |
| `file_list` | 列出目录内容 | READ_ONLY |
| `file_exists` | 检查文件是否存在 | READ_ONLY |
| `file_grep` | 正则搜索文件 | READ_ONLY |

#### Shell 命令 (shell)
| 工具 | 功能 | 权限 |
|------|------|------|
| `shell_execute` | 执行 Shell 命令 | EXECUTE |

#### 网页爬虫 (crawler)
| 工具 | 功能 | 权限 |
|------|------|------|
| `web_search` | DuckDuckGo 搜索 | READ_ONLY |
| `web_fetch` | 网页抓取 | READ_ONLY |
| `batch_fetch` | 批量并发抓取 | READ_ONLY |

#### 数据处理 (data)
| 工具 | 功能 | 权限 |
|------|------|------|
| `process_data` | JSON 转换、格式化 | READ_ONLY |

### 权限检查

工具执行时自动检查用户权限：

```
工具要求的权限 <= 用户拥有的权限 → 允许执行
工具要求的权限 >  用户拥有的权限 → 返回错误
```

用户通过 `/api/auth/users/{user_id}` 接口设置权限级别。

---

## Agent 管理 `/api/agents`

Agent 是独立的可复用 AI 助手模板，可在聊天室中使用。

### GET /api/agents/
获取用户的所有 Agent

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

**响应：**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "name": "代码助手",
      "role": "专注于 Python 和 JavaScript 开发",
      "provider_id": 1,
      "model": "deepseek-chat",
      "system_prompt": "You are a helpful coding assistant...",
      "color": "#10b981",
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    }
  ]
}
```

### POST /api/agents/
创建 Agent

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

**请求体：**
```json
{
  "name": "代码助手",
  "role": "专注于 Python 和 JavaScript 开发",
  "provider_id": 1,
  "model": "deepseek-chat",
  "system_prompt": "You are a helpful coding assistant.",
  "color": "#10b981"
}
```

**响应：**
```json
{
  "success": true,
  "message": "Agent created",
  "data": {
    "id": 1,
    "name": "代码助手",
    ...
  }
}
```

### GET /api/agents/{agent_id}
获取 Agent 详情

**路径参数：** `agent_id`: Agent ID

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

### PUT /api/agents/{agent_id}
更新 Agent

**路径参数：** `agent_id`: Agent ID

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

**请求体：**
```json
{
  "name": "新名称",
  "role": "新的角色描述",
  "system_prompt": "新的系统提示...",
  "color": "#ff6b6b"
}
```

### DELETE /api/agents/{agent_id}
删除 Agent

**路径参数：** `agent_id`: Agent ID

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

---

## 聊天室 `/api/chat-rooms`

聊天室允许多个 Agent 同时参与讨论，协作完成复杂任务。

### GET /api/chat-rooms/
获取聊天室列表

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

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

**响应：**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "room_xxx",
        "user_id": 1,
        "title": "项目讨论",
        "task": "讨论新功能的实现方案",
        "status": "idle",
        "max_rounds": 5,
        "current_round": 0,
        "agents": [...],
        "created_at": "2024-01-01T00:00:00",
        "updated_at": "2024-01-01T00:00:00"
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}
```

### POST /api/chat-rooms/
创建聊天室

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

**请求体：**
```json
{
  "title": "项目讨论",
  "task": "讨论新功能的实现方案",
  "max_rounds": 5,
  "agents": [
    {
      "agent_id": 1,
      "name": "代码助手",
      "role": "后端开发"
    },
    {
      "name": "测试助手",
      "role": "QA 工程师",
      "provider_id": 1,
      "model": "deepseek-chat",
      "system_prompt": "你是一个测试工程师...",
      "color": "#f59e0b"
    }
  ]
}
```

**响应：**
```json
{
  "success": true,
  "message": "Room created",
  "data": {
    "id": "room_xxx",
    "title": "项目讨论",
    ...
  }
}
```

### GET /api/chat-rooms/{room_id}
获取聊天室详情

**路径参数：** `room_id`: 聊天室 ID

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

**响应：**
```json
{
  "success": true,
  "data": {
    "id": "room_xxx",
    "title": "项目讨论",
    "task": "讨论新功能的实现方案",
    "status": "idle",
    "max_rounds": 5,
    "current_round": 0,
    "message_count": 10,
    "agents": [
      {
        "id": 1,
        "name": "代码助手",
        "role": "后端开发",
        "turn_order": 0,
        ...
      }
    ]
  }
}
```

### PUT /api/chat-rooms/{room_id}
更新聊天室

**路径参数：** `room_id`: 聊天室 ID

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

**请求体：**
```json
{
  "title": "新标题",
  "task": "新的任务描述",
  "max_rounds": 10,
  "status": "idle"
}
```

### DELETE /api/chat-rooms/{room_id}
删除聊天室

**路径参数：** `room_id`: 聊天室 ID

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

### POST /api/chat-rooms/{room_id}/start
启动聊天室（流式响应 - SSE）

**路径参数：** `room_id`: 聊天室 ID

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

**SSE 事件类型：**

#### room_started
聊天室启动
```json
event: room_started
data: {"type": "room_started", "room_id": "room_xxx", "task": "讨论新功能..."}
```

#### round_start
回合开始
```json
event: round_start
data: {"type": "round_start", "round": 1, "max_rounds": 5}
```

#### message_start
消息开始
```json
event: message_start
data: {"type": "message_start", "id": "msg_xxx", "room_id": "room_xxx", "role": "assistant", "sender_name": "代码助手", "sender_color": "#10b981", "round_number": 1}
```

#### message_chunk
消息内容增量
```json
event: message_chunk
data: {"type": "message_chunk", "id": "msg_xxx", "content": "我", "accumulated": "我认为..."}
```

#### message_end
消息结束
```json
event: message_end
data: {"type": "message_end", "id": "msg_xxx", "content": "完整的回复内容...", "token_count": 150}
```

#### message
完整消息（存储用）
```json
event: message
data: {"type": "message", "id": "msg_xxx", "conversation_id": null, "room_id": "room_xxx", "role": "assistant", "content": "...", "text": "...", "sender_name": "代码助手", "sender_color": "#10b981", "round_number": 1}
```

#### round_end
回合结束
```json
event: round_end
data: {"type": "round_end", "round": 1}
```

#### room_completed
聊天室完成
```json
event: room_completed
data: {"type": "room_completed", "room_id": "room_xxx", "total_rounds": 5}
```

#### room_paused
聊天室暂停
```json
event: room_paused
data: {"type": "room_paused", "room_id": "room_xxx", "round": 3}
```

#### agent_error
Agent 错误
```json
event: agent_error
data: {"type": "agent_error", "agent": "代码助手", "error": "错误描述"}
```

#### error
通用错误
```json
event: error
data: {"type": "error", "content": "错误信息"}
```

### POST /api/chat-rooms/{room_id}/stop
停止运行中的聊天室

**路径参数：** `room_id`: 聊天室 ID

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

### POST /api/chat-rooms/{room_id}/reset
重置聊天室（清除所有消息）

**路径参数：** `room_id`: 聊天室 ID

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

### GET /api/chat-rooms/{room_id}/messages
获取聊天室消息

**路径参数：** `room_id`: 聊天室 ID

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

**响应：**
```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_xxx",
        "room_id": "room_xxx",
        "role": "user",
        "text": "讨论新功能...",
        "sender_name": "用户",
        "sender_color": "#10b981",
        "round_number": 0,
        "created_at": "2024-01-01T00:00:00"
      },
      {
        "id": "msg_yyy",
        "room_id": "room_xxx",
        "role": "assistant",
        "text": "我认为应该...",
        "process_steps": [...],
        "sender_name": "代码助手",
        "sender_color": "#2563eb",
        "round_number": 1,
        "created_at": "2024-01-01T00:00:01"
      }
    ],
    "room": {...}
  }
}
```

### POST /api/chat-rooms/{room_id}/agents
向聊天室添加 Agent

**路径参数：** `room_id`: 聊天室 ID

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

**请求体：**
```json
{
  "agent_id": 1,
  "name": "自定义名称（可选）",
  "role": "自定义角色（可选）"
}
```

### PUT /api/chat-rooms/{room_id}/agents/{agent_id}
更新聊天室中的 Agent

**路径参数：**
- `room_id`: 聊天室 ID
- `agent_id`: RoomAgent ID

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

**请求体：**
```json
{
  "name": "新名称",
  "role": "新角色",
  "turn_order": 2
}
```

### DELETE /api/chat-rooms/{room_id}/agents/{agent_id}
从聊天室移除 Agent

**路径参数：**
- `room_id`: 聊天室 ID
- `agent_id`: RoomAgent ID

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

---

## 聊天室状态

| 状态 | 说明 |
|------|------|
| `idle` | 空闲，未开始 |
| `running` | 运行中 |
| `paused` | 已暂停 |
| `completed` | 已完成 |
| `error` | 错误 |

---

## Agent 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | Agent 唯一标识 |
| `user_id` | int | 所属用户 ID |
| `name` | string | Agent 名称 |
| `role` | string | Agent 角色描述 |
| `provider_id` | int | LLM 提供商 ID（可选） |
| `model` | string | 模型名称 |
| `system_prompt` | string | 系统提示词 |
| `color` | string | 颜色代码（用于前端显示） |
| `created_at` | datetime | 创建时间 |
| `updated_at` | datetime | 更新时间 |

---

## 聊天室 Agent 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | RoomAgent 唯一标识 |
| `room_id` | string | 聊天室 ID |
| `agent_id` | int | 关联的 Agent 模板 ID（可选） |
| `name` | string | Agent 名称 |
| `role` | string | Agent 角色描述 |
| `provider_id` | int | LLM 提供商 ID（可选） |
| `model` | string | 模型名称 |
| `system_prompt` | string | 系统提示词 |
| `color` | string | 颜色代码 |
| `turn_order` | int | 发言顺序 |