{ "openapi": "3.0.3", "info": { "title": "LangBot Service API", "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer `）\n- API 密钥（通过 `X-API-Key: ` 或 `Authorization: Bearer `）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n", "version": "4.9.5", "contact": { "name": "LangBot", "url": "https://langbot.app" }, "license": { "name": "AGPL-3.0", "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE" } }, "servers": [ { "url": "http://localhost:5300", "description": "本地开发服务器" } ], "tags": [ { "name": "模型供应商", "description": "模型供应商管理。供应商定义了 API 地址和密钥，模型通过 provider_uuid 关联到供应商。" }, { "name": "大语言模型", "description": "大语言模型 (LLM) 管理。每个模型关联到一个供应商。" }, { "name": "向量模型", "description": "向量模型 (Embedding) 管理。每个模型关联到一个供应商。" }, { "name": "机器人", "description": "机器人实例管理及消息发送" }, { "name": "流水线", "description": "流水线（Pipeline）配置管理" }, { "name": "知识库", "description": "知识库管理操作" }, { "name": "知识引擎", "description": "知识引擎（插件提供）的查询" }, { "name": "解析器", "description": "文件解析器（插件提供）的查询" }, { "name": "文件", "description": "文件上传操作" }, { "name": "插件", "description": "插件安装、配置和管理" }, { "name": "系统", "description": "系统信息（无需认证）" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/api/v1/system/info": { "get": { "tags": [ "系统" ], "summary": "获取系统信息", "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。", "security": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "version": { "type": "string", "example": "v4.9.5" }, "debug": { "type": "boolean" }, "edition": { "type": "string", "example": "community" }, "enable_marketplace": { "type": "boolean" }, "cloud_service_url": { "type": "string" }, "allow_modify_login_info": { "type": "boolean" }, "disable_models_service": { "type": "boolean" }, "limitation": { "type": "object" }, "wizard_status": { "type": "string", "enum": [ "none", "skipped", "completed" ] }, "wizard_progress": { "type": "object", "nullable": true } } } } } } } } } } }, "/api/v1/provider/providers": { "get": { "tags": [ "模型供应商" ], "summary": "获取所有供应商", "description": "获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProvider" } } } } } } } } } } }, "post": { "tags": [ "模型供应商" ], "summary": "创建供应商", "description": "创建一个新的模型供应商。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderCreate" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/provider/providers/{provider_uuid}": { "get": { "tags": [ "模型供应商" ], "summary": "获取单个供应商", "parameters": [ { "name": "provider_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ModelProvider" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "模型供应商" ], "summary": "更新供应商", "parameters": [ { "name": "provider_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "模型供应商" ], "summary": "删除供应商", "description": "删除供应商。如果还有模型引用该供应商，则无法删除。", "parameters": [ { "name": "provider_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" }, "400": { "description": "供应商仍有模型引用，无法删除", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/provider/models/llm": { "get": { "tags": [ "大语言模型" ], "summary": "获取所有 LLM 模型", "description": "获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。", "parameters": [ { "name": "provider_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "按供应商 UUID 过滤" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/LLMModel" } } } } } } } } } } }, "post": { "tags": [ "大语言模型" ], "summary": "创建 LLM 模型", "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelCreate" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/provider/models/llm/{model_uuid}": { "get": { "tags": [ "大语言模型" ], "summary": "获取单个 LLM 模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/LLMModel" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "大语言模型" ], "summary": "更新 LLM 模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "大语言模型" ], "summary": "删除 LLM 模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { "tags": [ "大语言模型" ], "summary": "测试 LLM 模型", "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "测试用的提示文本", "example": "Hello" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/embedding": { "get": { "tags": [ "向量模型" ], "summary": "获取所有向量模型", "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。", "parameters": [ { "name": "provider_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "按供应商 UUID 过滤" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingModel" } } } } } } } } } } }, "post": { "tags": [ "向量模型" ], "summary": "创建向量模型", "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelCreate" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/provider/models/embedding/{model_uuid}": { "get": { "tags": [ "向量模型" ], "summary": "获取单个向量模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/EmbeddingModel" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "向量模型" ], "summary": "更新向量模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "向量模型" ], "summary": "删除向量模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { "tags": [ "向量模型" ], "summary": "测试向量模型", "description": "向指定的向量模型发送测试请求，验证模型是否可用。", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "测试用的文本", "example": "Hello" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/platform/bots": { "get": { "tags": [ "机器人" ], "summary": "获取所有机器人", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "bots": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } } } } } } } } } } }, "post": { "tags": [ "机器人" ], "summary": "创建机器人", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCreate" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/platform/bots/{bot_uuid}": { "get": { "tags": [ "机器人" ], "summary": "获取单个机器人", "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "bot": { "$ref": "#/components/schemas/Bot" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "机器人" ], "summary": "更新机器人", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "机器人" ], "summary": "删除机器人", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/platform/bots/{bot_uuid}/logs": { "post": { "tags": [ "机器人" ], "summary": "获取机器人事件日志", "description": "获取指定机器人的事件日志记录。", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_index": { "type": "integer", "description": "起始索引（-1 表示从最新开始）", "default": -1 }, "max_count": { "type": "integer", "description": "最大返回数量", "default": 10 } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object" } }, "total_count": { "type": "integer" } } } } } } } } } } }, "/api/v1/platform/bots/{bot_uuid}/send_message": { "post": { "tags": [ "机器人" ], "summary": "通过机器人发送消息", "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_type", "target_id", "message_chain" ], "properties": { "target_type": { "type": "string", "enum": [ "person", "group" ], "description": "目标类型" }, "target_id": { "type": "string", "description": "目标 ID（用户 ID 或群组 ID）" }, "message_chain": { "type": "array", "description": "消息链", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Plain", "Image", "At", "Voice" ], "description": "消息元素类型" }, "text": { "type": "string", "description": "文本内容（Plain 类型）" }, "url": { "type": "string", "description": "图片 URL（Image 类型）" }, "target": { "type": "string", "description": "@ 的目标 ID（At 类型）" } } }, "example": [ { "type": "Plain", "text": "Hello, World!" } ] } } } } } }, "responses": { "200": { "description": "发送成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/pipelines": { "get": { "tags": [ "流水线" ], "summary": "获取所有流水线", "parameters": [ { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at" } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "pipelines": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } } } } } } } } } }, "post": { "tags": [ "流水线" ], "summary": "创建流水线", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineCreate" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/pipelines/_/metadata": { "get": { "tags": [ "流水线" ], "summary": "获取流水线元数据", "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "configs": { "type": "object" } } } } } } } } } } }, "/api/v1/pipelines/{pipeline_uuid}": { "get": { "tags": [ "流水线" ], "summary": "获取单个流水线", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "pipeline": { "$ref": "#/components/schemas/Pipeline" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "流水线" ], "summary": "更新流水线", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "流水线" ], "summary": "删除流水线", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/pipelines/{pipeline_uuid}/copy": { "post": { "tags": [ "流水线" ], "summary": "复制流水线", "description": "复制一个已有的流水线，生成一个新的副本。", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "复制成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/pipelines/{pipeline_uuid}/extensions": { "get": { "tags": [ "流水线" ], "summary": "获取流水线扩展配置", "description": "获取流水线绑定的插件和 MCP 服务器配置。", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "enable_all_plugins": { "type": "boolean" }, "enable_all_mcp_servers": { "type": "boolean" }, "bound_plugins": { "type": "array", "items": { "type": "string" } }, "available_plugins": { "type": "array", "items": { "type": "object" } }, "bound_mcp_servers": { "type": "array", "items": { "type": "string" } }, "available_mcp_servers": { "type": "array", "items": { "type": "object" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "流水线" ], "summary": "更新流水线扩展配置", "description": "更新流水线绑定的插件和 MCP 服务器。", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enable_all_plugins": { "type": "boolean", "default": true }, "enable_all_mcp_servers": { "type": "boolean", "default": true }, "bound_plugins": { "type": "array", "items": { "type": "string" } }, "bound_mcp_servers": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/knowledge/bases": { "get": { "tags": [ "知识库" ], "summary": "获取所有知识库", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "bases": { "type": "array", "items": { "type": "object" } } } } } } } } } } }, "post": { "tags": [ "知识库" ], "summary": "创建知识库", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "engine_plugin_id": { "type": "string", "description": "知识引擎插件 ID（author/name 格式）" }, "creation_settings": { "type": "object", "description": "引擎创建参数" } } } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } } } } }, "/api/v1/knowledge/bases/{kb_uuid}": { "get": { "tags": [ "知识库" ], "summary": "获取单个知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "base": { "type": "object" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "知识库" ], "summary": "更新知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ "知识库" ], "summary": "删除知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { "get": { "tags": [ "知识库" ], "summary": "获取知识库文件列表", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object" } } } } } } } } } } }, "post": { "tags": [ "知识库" ], "summary": "将文件存入知识库", "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "已上传的文件 ID" }, "parser_plugin_id": { "type": "string", "description": "指定的解析器插件 ID（可选）" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "task_id": { "type": "string" } } } } } } } } } } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { "delete": { "tags": [ "知识库" ], "summary": "从知识库删除文件", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { "post": { "tags": [ "知识库" ], "summary": "检索知识库", "description": "对知识库进行语义检索，返回相关文档片段。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "检索查询文本" }, "retrieval_settings": { "type": "object", "description": "检索参数（如 top_k 等）", "properties": { "top_k": { "type": "integer" } } } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }, "/api/v1/knowledge/engines": { "get": { "tags": [ "知识引擎" ], "summary": "获取可用知识引擎列表", "description": "列出所有由插件提供的知识引擎，包含其能力和配置模式。", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "engines": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }, "/api/v1/knowledge/engines/{plugin_id}/creation-schema": { "get": { "tags": [ "知识引擎" ], "summary": "获取知识引擎创建配置模式", "description": "获取指定知识引擎的创建参数 JSON Schema。", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件 ID（author/name 格式）" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "schema": { "type": "object" } } } } } } } } } } }, "/api/v1/knowledge/engines/{plugin_id}/retrieval-schema": { "get": { "tags": [ "知识引擎" ], "summary": "获取知识引擎检索配置模式", "description": "获取指定知识引擎的检索参数 JSON Schema。", "parameters": [ { "name": "plugin_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件 ID（author/name 格式）" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "schema": { "type": "object" } } } } } } } } } } }, "/api/v1/knowledge/parsers": { "get": { "tags": [ "解析器" ], "summary": "获取可用解析器列表", "description": "列出所有由插件提供的文件解析器。可通过 mime_type 过滤。", "parameters": [ { "name": "mime_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按 MIME 类型过滤解析器" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "parsers": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }, "/api/v1/files/images": { "post": { "tags": [ "文件" ], "summary": "上传图片", "description": "上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "图片文件" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "file_key": { "type": "string", "description": "文件标识符，可用于引用图片" } } } } } } } } } } }, "/api/v1/files/documents": { "post": { "tags": [ "文件" ], "summary": "上传文档", "description": "上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "文档文件" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "file_id": { "type": "string", "description": "文件 ID，可用于知识库关联" } } } } } } } } } } }, "/api/v1/plugins": { "get": { "tags": [ "插件" ], "summary": "获取已安装插件列表", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }, "/api/v1/plugins/{author}/{plugin_name}": { "get": { "tags": [ "插件" ], "summary": "获取插件详情", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "plugin": { "type": "object" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "插件" ], "summary": "删除插件", "description": "异步删除插件，返回任务 ID。", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delete_data", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "是否同时删除插件数据" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "task_id": { "type": "integer" } } } } } } } } } } }, "/api/v1/plugins/{author}/{plugin_name}/upgrade": { "post": { "tags": [ "插件" ], "summary": "升级插件", "description": "异步升级插件到最新版本，返回任务 ID。", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "task_id": { "type": "integer" } } } } } } } } } } }, "/api/v1/plugins/{author}/{plugin_name}/config": { "get": { "tags": [ "插件" ], "summary": "获取插件配置", "description": "获取插件的当前配置值和配置模式。", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object" } } } } } } } }, "put": { "tags": [ "插件" ], "summary": "更新插件配置", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "插件配置键值对" } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/plugins/install/marketplace": { "post": { "tags": [ "插件" ], "summary": "从 Marketplace 安装插件", "description": "从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plugin_id" ], "properties": { "plugin_id": { "type": "string", "description": "Marketplace 插件 ID（author/name 格式）", "example": "kellz-dev/disaster-alert" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "task_id": { "type": "integer" } } } } } } } } } } }, "/api/v1/plugins/install/github": { "post": { "tags": [ "插件" ], "summary": "从 GitHub 安装插件", "description": "从 GitHub 仓库安装插件。异步操作，返回任务 ID。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "GitHub 仓库 URL", "example": "https://github.com/rocksclawbot/langbot-community-plugins/tree/main/disaster-alert" } } } } } }, "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "task_id": { "type": "integer" } } } } } } } } } } }, "/api/v1/tools": { "get": { "tags": [ "工具" ], "summary": "获取所有可用工具", "description": "获取当前 LangBot 实例中所有可用的工具，包括插件工具和 MCP 工具。", "operationId": "listTools", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" } } } } } } } } } } } }, "/api/v1/tools/{tool_name}": { "get": { "tags": [ "工具" ], "summary": "获取工具详情", "description": "获取指定工具的详细信息。", "operationId": "getToolDetail", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "tool_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "工具名称" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "tool": { "$ref": "#/components/schemas/ToolSummary" } } } } } } } }, "404": { "description": "Tool not found" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "ModelProvider": { "type": "object", "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "OpenAI" }, "requester": { "type": "string", "description": "请求器类型", "example": "openai-chat-completions" }, "base_url": { "type": "string", "description": "API 基础地址", "example": "https://api.openai.com/v1" }, "api_keys": { "type": "array", "description": "API 密钥列表", "items": { "type": "string" } }, "llm_count": { "type": "integer", "description": "关联的 LLM 模型数量" }, "embedding_count": { "type": "integer", "description": "关联的 Embedding 模型数量" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ModelProviderCreate": { "type": "object", "required": [ "name", "requester", "base_url" ], "properties": { "name": { "type": "string", "example": "OpenAI" }, "requester": { "type": "string", "description": "请求器类型。可通过 GET /api/v1/provider/requesters 获取可用列表。", "example": "openai-chat-completions" }, "base_url": { "type": "string", "example": "https://api.openai.com/v1" }, "api_keys": { "type": "array", "items": { "type": "string" }, "example": [ "sk-xxx" ] } } }, "ModelProviderUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "requester": { "type": "string" }, "base_url": { "type": "string" }, "api_keys": { "type": "array", "items": { "type": "string" } } } }, "LLMModel": { "type": "object", "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）", "example": "gpt-4o" }, "provider_uuid": { "type": "string", "format": "uuid", "description": "关联的供应商 UUID" }, "abilities": { "type": "array", "items": { "type": "string" }, "description": "模型能力标签", "example": [ "chat", "vision", "tool-use" ] }, "extra_args": { "type": "object", "description": "额外参数（如 temperature、max_tokens 等）" }, "prefered_ranking": { "type": "integer", "description": "优先级排序（越大越优先）", "default": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LLMModelCreate": { "type": "object", "required": [ "name", "provider_uuid" ], "properties": { "name": { "type": "string", "description": "模型名称（即模型 ID）", "example": "gpt-4o" }, "provider_uuid": { "type": "string", "format": "uuid", "description": "关联的供应商 UUID" }, "abilities": { "type": "array", "items": { "type": "string" }, "example": [ "chat", "vision" ] }, "extra_args": { "type": "object" }, "prefered_ranking": { "type": "integer", "default": 0 } } }, "LLMModelUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "provider_uuid": { "type": "string", "format": "uuid" }, "abilities": { "type": "array", "items": { "type": "string" } }, "extra_args": { "type": "object" }, "prefered_ranking": { "type": "integer" } } }, "EmbeddingModel": { "type": "object", "description": "向量模型。通过 provider_uuid 关联到供应商。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "模型名称（即模型 ID）", "example": "text-embedding-3-small" }, "provider_uuid": { "type": "string", "format": "uuid", "description": "关联的供应商 UUID" }, "extra_args": { "type": "object" }, "prefered_ranking": { "type": "integer", "default": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmbeddingModelCreate": { "type": "object", "required": [ "name", "provider_uuid" ], "properties": { "name": { "type": "string", "example": "text-embedding-3-small" }, "provider_uuid": { "type": "string", "format": "uuid" }, "extra_args": { "type": "object" }, "prefered_ranking": { "type": "integer", "default": 0 } } }, "EmbeddingModelUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "provider_uuid": { "type": "string", "format": "uuid" }, "extra_args": { "type": "object" }, "prefered_ranking": { "type": "integer" } } }, "Bot": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "adapter": { "type": "string", "example": "telegram" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BotCreate": { "type": "object", "required": [ "name", "adapter", "config" ], "properties": { "name": { "type": "string" }, "adapter": { "type": "string" }, "config": { "type": "object" } } }, "BotUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "adapter": { "type": "string" }, "config": { "type": "object" } } }, "Pipeline": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "config": { "type": "object" }, "is_default": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PipelineCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "config": { "type": "object" } } }, "PipelineUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" }, "is_default": { "type": "boolean" } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string" } } }, "ToolSummary": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name" }, "label": { "type": "object", "description": "Display label (i18n)", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "Tool description (i18n)", "additionalProperties": { "type": "string" } }, "icon": { "type": "string", "description": "Tool icon" }, "spec": { "type": "object", "description": "Tool specification", "properties": { "llm_prompt": { "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema for tool parameters" } } } } } }, "responses": { "Success": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 } } } } } }, "NotFound": { "description": "资源未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }