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

Agent 管理 `/api/agents`

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

GET /api/agents/

获取用户的所有 Agent

请求头： Authorization: Bearer <token>

响应：

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

请求体：

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

响应：

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

请求体：

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

响应：

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

请求体：

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

响应：

{
  "success": true,
  "message": "Room created",
  "data": {
    "id": "room_xxx",
    "title": "项目讨论",
    ...
  }
}

GET /api/chat-rooms/{room_id}

获取聊天室详情

路径参数： room_id: 聊天室 ID

请求头： Authorization: Bearer <token>

响应：

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

请求体：

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

聊天室启动

event: room_started
data: {"type": "room_started", "room_id": "room_xxx", "task": "讨论新功能..."}

round_start

回合开始

event: round_start
data: {"type": "round_start", "round": 1, "max_rounds": 5}

message_start

消息开始

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

消息内容增量

event: message_chunk
data: {"type": "message_chunk", "id": "msg_xxx", "content": "我", "accumulated": "我认为..."}

message_end

消息结束

event: message_end
data: {"type": "message_end", "id": "msg_xxx", "content": "完整的回复内容...", "token_count": 150}

message

完整消息（存储用）

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

回合结束

event: round_end
data: {"type": "round_end", "round": 1}

room_completed

聊天室完成

event: room_completed
data: {"type": "room_completed", "room_id": "room_xxx", "total_rounds": 5}

room_paused

聊天室暂停

event: room_paused
data: {"type": "room_paused", "room_id": "room_xxx", "round": 3}

agent_error

Agent 错误

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

error

通用错误

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>

响应：

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

请求体：

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

请求体：

{
  "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	发言顺序

21 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)

权限检查

Agent 管理 /api/agents

GET /api/agents/

POST /api/agents/

GET /api/agents/{agent_id}

PUT /api/agents/{agent_id}

DELETE /api/agents/{agent_id}

聊天室 /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}

POST /api/chat-rooms/{room_id}/start

room_started

round_start

message_start

message_chunk

message_end

message

round_end

room_completed

room_paused

agent_error

error

POST /api/chat-rooms/{room_id}/stop

POST /api/chat-rooms/{room_id}/reset

GET /api/chat-rooms/{room_id}/messages

POST /api/chat-rooms/{room_id}/agents

PUT /api/chat-rooms/{room_id}/agents/{agent_id}

DELETE /api/chat-rooms/{room_id}/agents/{agent_id}

聊天室状态

Agent 字段说明

聊天室 Agent 字段说明

21 KiB

Raw Blame History

认证 `/api/auth`

会话 `/api/conversations`

消息 `/api/messages`

LLM 提供商 `/api/providers`

工具 `/api/tools`

Agent 管理 `/api/agents`

聊天室 `/api/chat-rooms`