From 40e22b1ad2c7aacdf49a7237892a3aca0ba9f887 Mon Sep 17 00:00:00 2001 From: Junyan Qin Date: Fri, 28 Nov 2025 20:13:20 +0800 Subject: [PATCH] docs: add more docs for new apis --- docs/assets/service-api-openapi-en.json | 1319 ++++++++++++++++++++++- docs/assets/service-api-openapi-zh.json | 1315 ++++++++++++++++++++++ 2 files changed, 2632 insertions(+), 2 deletions(-) diff --git a/docs/assets/service-api-openapi-en.json b/docs/assets/service-api-openapi-en.json index 1e81adee2..0a197414a 100644 --- a/docs/assets/service-api-openapi-en.json +++ b/docs/assets/service-api-openapi-en.json @@ -2,7 +2,7 @@ "openapi": "3.0.3", "info": { "title": "LangBot API with API Key Authentication", - "description": "LangBot external service API documentation. These endpoints support API Key authentication \nfor external systems to programmatically access LangBot resources.\n\n**Authentication Methods:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll endpoints documented here accept BOTH authentication methods.\n", + "description": "LangBot External Service API Documentation. These interfaces support API key authentication for external systems to programmatically access LangBot resources.\n\n**Authentication Methods:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll interfaces in this documentation support both authentication methods.\n", "version": "4.4.1", "contact": { "name": "LangBot", @@ -25,7 +25,7 @@ "description": "Large Language Model management operations" }, { - "name": "Models - Embedding", + "name": "Models - Embeddings", "description": "Embedding model management operations" }, { @@ -35,6 +35,18 @@ { "name": "Pipelines", "description": "Pipeline configuration management operations" + }, + { + "name": "Knowledge Bases", + "description": "Built-in knowledge base management operations" + }, + { + "name": "Files", + "description": "File upload and management operations" + }, + { + "name": "Plugins", + "description": "Plugin installation and management operations" } ], "security": [ @@ -1486,6 +1498,1309 @@ } } } + }, + "/api/v1/files/images": { + "post": { + "tags": [ + "Files" + ], + "summary": "Upload Image", + "description": "Upload image file (supports jpg, jpeg, png, gif, webp, max 10MB)", + "operationId": "uploadImage", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Image file" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upload successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_key": { + "type": "string", + "description": "File key" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/files/documents": { + "post": { + "tags": [ + "Files" + ], + "summary": "Upload Document", + "description": "Upload document file (max 10MB)", + "operationId": "uploadDocument", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Document file" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upload successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_id": { + "type": "string", + "description": "File ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins": { + "get": { + "tags": [ + "Plugins" + ], + "summary": "List All Plugins", + "description": "Get list of all installed plugins", + "operationId": "listPlugins", + "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": { + "plugins": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/{author}/{plugin_name}": { + "get": { + "tags": [ + "Plugins" + ], + "summary": "Get Plugin Details", + "description": "Get details of a specific plugin", + "operationId": "getPlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin author" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin name" + } + ], + "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": { + "plugin": { + "type": "object" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Plugins" + ], + "summary": "Delete Plugin", + "description": "Uninstall the specified plugin", + "operationId": "deletePlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin author" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Plugin name" + }, + { + "name": "delete_data", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": false + }, + "description": "Whether to delete plugin data" + } + ], + "responses": { + "200": { + "description": "Deletion task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/local": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install Plugin from Local File", + "description": "Upload and install plugin package file", + "operationId": "installPluginLocal", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Plugin package file (.lbpkg format)" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/github": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install Plugin from GitHub", + "description": "Install plugin from GitHub Release", + "operationId": "installPluginGitHub", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "asset_url" + ], + "properties": { + "asset_url": { + "type": "string", + "description": "GitHub Release asset download URL" + }, + "owner": { + "type": "string", + "description": "Repository owner" + }, + "repo": { + "type": "string", + "description": "Repository name" + }, + "release_tag": { + "type": "string", + "description": "Release tag" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/marketplace": { + "post": { + "tags": [ + "Plugins" + ], + "summary": "Install from Marketplace", + "description": "Install plugin from LangBot plugin marketplace", + "operationId": "installPluginMarketplace", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "plugin_id": { + "type": "string", + "description": "Plugin ID" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Installation task created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/platform/bots/{bot_uuid}/send_message": { + "post": { + "tags": [ + "Bots" + ], + "summary": "Send Message", + "description": "Send a message to a specific target via the specified bot", + "operationId": "sendMessage", + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Bot 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 type" + }, + "target_id": { + "type": "string", + "description": "Target ID (user ID or group ID)" + }, + "message_chain": { + "type": "array", + "items": { + "type": "object" + }, + "description": "Message chain (array of MessageComponent)" + } + } + }, + "examples": { + "Text Message": { + "value": { + "target_type": "group", + "target_id": "123456789", + "message_chain": [ + { + "type": "Plain", + "text": "Hello, World!" + } + ] + } + }, + "Text and Image": { + "value": { + "target_type": "person", + "target_id": "987654321", + "message_chain": [ + { + "type": "Plain", + "text": "Check out this image:" + }, + { + "type": "Image", + "url": "https://example.com/image.jpg" + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Message sent successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "sent": { + "type": "boolean", + "example": true + } + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "target_type is required" + } + } + } + } + } + }, + "500": { + "description": "Failed to send", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "Failed to send message: Bot not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Get All Knowledge Bases", + "description": "Get all builtin knowledge bases", + "operationId": "listKnowledgeBases", + "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": { + "bases": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Create Knowledge Base", + "description": "Create a new knowledge base", + "operationId": "createKnowledgeBase", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name", + "embedding_model_uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "name" + }, + "description": { + "type": "string", + "description": "description" + }, + "embedding_model_uuid": { + "type": "string", + "description": "Embedding model UUID" + } + } + }, + "example": { + "name": "技术文档库", + "description": "存储技术文档和API参考", + "embedding_model_uuid": "uuid-of-embedding-model" + } + } + } + }, + "responses": { + "200": { + "description": "Knowledge base created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Get Knowledge Base Details", + "description": "Get details info of specified knowledge base", + "operationId": "getKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "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": { + "base": { + "type": "object" + } + } + } + } + } + } + } + }, + "404": { + "description": "Knowledge base not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "knowledge base not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Update Knowledge Base Info", + "description": "Update knowledge base information", + "operationId": "updateKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Update successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Delete Knowledge Base", + "description": "Delete a specified knowledge base", + "operationId": "deleteKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "responses": { + "200": { + "description": "Deletion successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files": { + "get": { + "tags": [ + "Knowledge Bases" + ], + "summary": "List Knowledge Base Files", + "description": "Get all files in the specified knowledge base", + "operationId": "listKnowledgeBaseFiles", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Add File to Knowledge Base", + "description": "Add uploaded file to knowledge base for processing", + "operationId": "addFileToKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "file_id" + ], + "properties": { + "file_id": { + "type": "string", + "description": "File ID（从文件上传接口获取）" + } + } + }, + "example": { + "file_id": "document_abc123.pdf" + } + } + } + }, + "responses": { + "200": { + "description": "Addition successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Processing task ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { + "delete": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Delete File from Knowledge Base", + "description": "Delete file from the specified knowledge base", + "operationId": "deleteFileFromKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "File ID" + } + ], + "responses": { + "200": { + "description": "Deletion successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Retrieve Knowledge", + "description": "Search for relevant knowledge in the knowledge base", + "operationId": "retrieveKnowledge", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Knowledge Base UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "Query text" + } + } + }, + "example": { + "query": "如何使用 LangBot 创建机器人？" + } + } + } + }, + "responses": { + "200": { + "description": "Retrieval successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } } }, "components": { diff --git a/docs/assets/service-api-openapi-zh.json b/docs/assets/service-api-openapi-zh.json index 28dfb2508..817c8aa74 100644 --- a/docs/assets/service-api-openapi-zh.json +++ b/docs/assets/service-api-openapi-zh.json @@ -35,6 +35,18 @@ { "name": "流水线", "description": "流水线配置管理操作" + }, + { + "name": "知识库", + "description": "内置知识库管理操作" + }, + { + "name": "文件", + "description": "文件上传和管理操作" + }, + { + "name": "插件", + "description": "插件安装和管理操作" } ], "security": [ @@ -1486,6 +1498,1309 @@ } } } + }, + "/api/v1/platform/bots/{bot_uuid}/send_message": { + "post": { + "tags": [ + "机器人" + ], + "summary": "发送消息", + "description": "通过指定机器人向指定目标发送消息", + "operationId": "sendMessage", + "parameters": [ + { + "name": "bot_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "机器人 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", + "items": { + "type": "object" + }, + "description": "消息链（MessageComponent 数组）" + } + } + }, + "examples": { + "文本消息": { + "value": { + "target_type": "group", + "target_id": "123456789", + "message_chain": [ + { + "type": "Plain", + "text": "Hello, World!" + } + ] + } + }, + "图文消息": { + "value": { + "target_type": "person", + "target_id": "987654321", + "message_chain": [ + { + "type": "Plain", + "text": "查看这张图片：" + }, + { + "type": "Image", + "url": "https://example.com/image.jpg" + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "发送成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "sent": { + "type": "boolean", + "example": true + } + } + } + } + } + } + } + }, + "400": { + "description": "请求参数错误", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "target_type is required" + } + } + } + } + } + }, + "500": { + "description": "发送失败", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "Failed to send message: Bot not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases": { + "get": { + "tags": [ + "知识库" + ], + "summary": "获取所有知识库", + "description": "获取所有内置知识库列表", + "operationId": "listKnowledgeBases", + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "bases": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "知识库" + ], + "summary": "创建知识库", + "description": "创建新的内置知识库", + "operationId": "createKnowledgeBase", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name", + "embedding_model_uuid" + ], + "properties": { + "name": { + "type": "string", + "description": "知识库名称" + }, + "description": { + "type": "string", + "description": "知识库描述" + }, + "embedding_model_uuid": { + "type": "string", + "description": "向量模型 UUID" + } + } + }, + "example": { + "name": "技术文档库", + "description": "存储技术文档和API参考", + "embedding_model_uuid": "uuid-of-embedding-model" + } + } + } + }, + "responses": { + "200": { + "description": "创建成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}": { + "get": { + "tags": [ + "知识库" + ], + "summary": "获取知识库详情", + "description": "获取指定知识库的详细信息", + "operationId": "getKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "base": { + "type": "object" + } + } + } + } + } + } + } + }, + "404": { + "description": "知识库不存在", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string", + "example": "knowledge base not found" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "put": { + "tags": [ + "知识库" + ], + "summary": "更新知识库", + "description": "更新知识库信息", + "operationId": "updateKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "更新成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "知识库" + ], + "summary": "删除知识库", + "description": "删除指定的知识库", + "operationId": "deleteKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "responses": { + "200": { + "description": "删除成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files": { + "get": { + "tags": [ + "知识库" + ], + "summary": "获取知识库文件列表", + "description": "获取指定知识库中的所有文件", + "operationId": "listKnowledgeBaseFiles", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + }, + "post": { + "tags": [ + "知识库" + ], + "summary": "添加文件到知识库", + "description": "将已上传的文件添加到知识库进行处理", + "operationId": "addFileToKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "file_id" + ], + "properties": { + "file_id": { + "type": "string", + "description": "文件 ID（从文件上传接口获取）" + } + } + }, + "example": { + "file_id": "document_abc123.pdf" + } + } + } + }, + "responses": { + "200": { + "description": "添加成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "处理任务 ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { + "delete": { + "tags": [ + "知识库" + ], + "summary": "从知识库删除文件", + "description": "从指定知识库中删除文件", + "operationId": "deleteFileFromKnowledgeBase", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + }, + { + "name": "file_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "文件 ID" + } + ], + "responses": { + "200": { + "description": "删除成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { + "post": { + "tags": [ + "知识库" + ], + "summary": "检索知识库", + "description": "在知识库中搜索相关知识", + "operationId": "retrieveKnowledge", + "parameters": [ + { + "name": "kb_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "知识库 UUID" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "查询文本" + } + } + }, + "example": { + "query": "如何使用 LangBot 创建机器人？" + } + } + } + }, + "responses": { + "200": { + "description": "检索成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "ApiKeyAuth": [] + }, + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/files/images": { + "post": { + "tags": [ + "文件" + ], + "summary": "上传图片", + "description": "上传图片文件（支持 jpg, jpeg, png, gif, webp 格式，最大 10MB）", + "operationId": "uploadImage", + "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 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_key": { + "type": "string", + "description": "文件密钥" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/files/documents": { + "post": { + "tags": [ + "文件" + ], + "summary": "上传文档", + "description": "上传文档文件（最大 10MB）", + "operationId": "uploadDocument", + "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 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "file_id": { + "type": "string", + "description": "文件 ID" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins": { + "get": { + "tags": [ + "插件" + ], + "summary": "获取所有插件", + "description": "获取已安装的所有插件列表", + "operationId": "listPlugins", + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "plugins": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/{author}/{plugin_name}": { + "get": { + "tags": [ + "插件" + ], + "summary": "获取插件详情", + "description": "获取指定插件的详细信息", + "operationId": "getPlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "插件作者" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "插件名称" + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "plugin": { + "type": "object" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "tags": [ + "插件" + ], + "summary": "删除插件", + "description": "卸载指定的插件", + "operationId": "deletePlugin", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "插件作者" + }, + { + "name": "plugin_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "插件名称" + }, + { + "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 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/local": { + "post": { + "tags": [ + "插件" + ], + "summary": "从本地文件安装插件", + "description": "上传并安装插件包文件", + "operationId": "installPluginLocal", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "插件包文件（.lbpkg 格式）" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "安装任务已创建", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/github": { + "post": { + "tags": [ + "插件" + ], + "summary": "从 GitHub 安装插件", + "description": "从 GitHub Release 安装插件", + "operationId": "installPluginGitHub", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "asset_url" + ], + "properties": { + "asset_url": { + "type": "string", + "description": "GitHub Release 资源下载 URL" + }, + "owner": { + "type": "string", + "description": "仓库所有者" + }, + "repo": { + "type": "string", + "description": "仓库名称" + }, + "release_tag": { + "type": "string", + "description": "Release 标签" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "安装任务已创建", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/api/v1/plugins/install/marketplace": { + "post": { + "tags": [ + "插件" + ], + "summary": "从插件市场安装", + "description": "从 LangBot 插件市场安装插件", + "operationId": "installPluginMarketplace", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "plugin_id": { + "type": "string", + "description": "插件 ID" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "安装任务已创建", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "task_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } } }, "components": {