Luxx/assets/API.md

# 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}` 接口设置权限级别。