12 KiB

Raw Blame History

API 接口文档

认证 `/api/auth`

POST /api/auth/register

用户注册

请求体：

{
  "username": "string",
  "email": "user@example.com",
  "password": "string"
}

响应：

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "id": 1,
    "username": "string"
  }
}

POST /api/auth/login

用户登录

请求体：

{
  "username": "string",
  "password": "string"
}

响应：

{
  "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>

响应：

{
  "success": true,
  "message": "Logout successful"
}

GET /api/auth/me

获取当前用户信息

请求头： Authorization: Bearer <token>

响应：

{
  "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>

响应：

{
  "success": true,
  "data": {
    "users": [...]
  }
}

PUT /api/auth/users/{user_id}

更新用户权限（管理员专用）

请求体：

{
  "permission_level": 2
}

会话 `/api/conversations`

GET /api/conversations/

获取会话列表

查询参数：

project_id (可选): 项目ID
page (可选): 页码，默认1
page_size (可选): 每页数量，默认20

请求头： Authorization: Bearer <token>

响应：

{
  "success": true,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

POST /api/conversations/

创建会话

请求头： Authorization: Bearer <token>

请求体：

{
  "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
}

响应：

{
  "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>

请求体：

{
  "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>

响应：

{
  "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>

请求体：

{
  "conversation_id": "conv_xxx",
  "content": "用户消息",
  "thinking_enabled": false
}

响应：

{
  "success": true,
  "data": {
    "user_message": {...},
    "assistant_message": {...}
  }
}

POST /api/messages/stream

发送消息（流式响应 - SSE）

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

请求头： Authorization: Bearer <token>

请求体：

{
  "conversation_id": "conv_xxx",
  "content": "用户消息",
  "thinking_enabled": true,
  "enabled_tools": ["web_search", "file_read", "python_execute"]
}

SSE 事件类型：

process_step

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

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

响应完成

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

error

错误信息

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>

响应：

{
  "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>

请求体：

{
  "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>

请求体：

{
  "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>

响应：

{
  "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>

响应：

{
  "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>

响应：

{
  "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>

请求体：

{
  "arg1": "value1",
  "arg2": "value2"
}

响应：

{
  "success": true,
  "data": {
    "result": "..."
  }
}

公共端点

GET /api/health

健康检查

响应：

{
  "status": "ok",
  "message": "Luxx API is running"
}

GET /api/

服务信息

响应：

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

12 KiB Raw Blame History Unescape Escape

API 接口文档

认证 /api/auth

POST /api/auth/register

POST /api/auth/login

POST /api/auth/logout

GET /api/auth/me

GET /api/auth/users

PUT /api/auth/users/{user_id}

会话 /api/conversations

GET /api/conversations/

POST /api/conversations/

GET /api/conversations/{id}

PUT /api/conversations/{id}

DELETE /api/conversations/{id}

消息 /api/messages

GET /api/messages/

POST /api/messages/

POST /api/messages/stream

process_step

done

error

DELETE /api/messages/{message_id}

LLM 提供商 /api/providers

GET /api/providers/

POST /api/providers/

GET /api/providers/{provider_id}

PUT /api/providers/{provider_id}

DELETE /api/providers/{provider_id}

POST /api/providers/{provider_id}/test

工具 /api/tools

GET /api/tools/

GET /api/tools/{name}

POST /api/tools/{name}/execute

公共端点

GET /api/health

GET /api/

工具说明

内置工具

代码执行 (code)

文件操作 (file)

Shell 命令 (shell)

网页爬虫 (crawler)

数据处理 (data)

权限检查

12 KiB

Raw Blame History

认证 `/api/auth`

会话 `/api/conversations`

消息 `/api/messages`

LLM 提供商 `/api/providers`

工具 `/api/tools`