From 2faa821d03565258f0d67165a58e5fe9a3588226 Mon Sep 17 00:00:00 2001 From: RockChinQ Date: Fri, 3 Apr 2026 02:15:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20Service=20API=20=E2=80=94=20P?= =?UTF-8?q?rovider+Model=20architecture,=20add=20missing=20endpoints?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite OpenAPI specs (zh/en/ja) with Provider+Model two-layer architecture - Remove old model schema (requester/requester_config/api_keys on model level) - Add ModelProvider CRUD endpoints - Add missing endpoints: knowledge engines, parsers, plugin config/upgrade, pipeline copy/extensions - Update Service API overview pages (zh/en/ja) with core concepts - Update models config page to explain Provider+Model architecture - Bump API version to 4.9.5 --- en/tags/readme.mdx | 41 +- ja/tags/readme.mdx | 39 +- openapi/service-api-en.json | 3350 +++++++++++++++++----------------- openapi/service-api-ja.json | 3360 +++++++++++++++++----------------- openapi/service-api-zh.json | 3365 +++++++++++++---------------------- zh/tags/readme.mdx | 45 +- zh/usage/models/readme.mdx | 25 +- 7 files changed, 4678 insertions(+), 5547 deletions(-) diff --git a/en/tags/readme.mdx b/en/tags/readme.mdx index a09bd6513..b2b6f7941 100644 --- a/en/tags/readme.mdx +++ b/en/tags/readme.mdx @@ -2,7 +2,7 @@ title: "Service API Overview" --- -LangBot provides a set of APIs for external services to integrate. These APIs are authenticated with API keys, which are a subset of the HTTP API. To view the API documentation for frontend-backend communication, please go to the [Development](/en/develop/dev-config) section. +LangBot provides a set of RESTful APIs for external services to integrate and automate management. These APIs are authenticated with API keys, which are a subset of the HTTP API. Service API is currently in Beta and some APIs may change frequently. @@ -18,6 +18,45 @@ After creation, copy the API Key and save it. ![copy_api_key](/images/zh/api/copy_api_key.png) +## Authentication + +All Service APIs support two authentication methods: + +- **API Key**: Via `X-API-Key: ` or `Authorization: Bearer ` header +- **User Token**: Via `Authorization: Bearer ` header (obtained after login) + ## Use API The left sidebar lists all available APIs. You can fill in your instance address (the port address exposed by the backend, default is `http://localhost:5300`) and API Key, then click the `Try it out` button to call the API. + +## Core Concepts + +### Provider + Model Architecture + +LangBot uses a **Provider + Model** two-layer architecture for AI model management: + +- **Provider**: Defines the API endpoint (`base_url`), requester type, and API keys. A single provider can be associated with multiple models. +- **Model**: Associated with a provider (via `provider_uuid`), defining the specific model name and parameters. Models inherit the provider's API endpoint and keys. + +``` +Provider (OpenAI) +├── base_url: https://api.openai.com/v1 +├── api_keys: [sk-xxx] +├── LLM: gpt-4o +├── LLM: gpt-4o-mini +└── Embedding: text-embedding-3-small +``` + +This architecture allows you to manage multiple models under a single provider, sharing API configuration and avoiding redundant key entries. + +### Requester + +A requester defines the communication protocol with AI services. Use `GET /api/v1/provider/requesters` to list available requesters. Common requesters include: + +- `openai-chat-completions` — OpenAI-compatible chat completions API (also works with SiliconFlow, DeepSeek, etc.) +- `anthropic-messages` — Anthropic Claude API +- `openai-embeddings` — OpenAI-compatible embeddings API + +### Async Tasks + +Some operations (plugin install/delete/upgrade) run asynchronously and return a `task_id`. You can track progress in the WebUI. diff --git a/ja/tags/readme.mdx b/ja/tags/readme.mdx index baba68217..be964867f 100644 --- a/ja/tags/readme.mdx +++ b/ja/tags/readme.mdx @@ -2,7 +2,7 @@ title: "Service API 概要" --- -LangBotは、外部サービスと統合するための一連のAPIを提供します。これらのAPIはAPIキーで認証され、HTTP APIのサブセットです。フロントエンドとバックエンドの通信用APIドキュメントを表示するには、[開発](/en/develop/dev-config)セクションにアクセスしてください。 +LangBotは、外部サービスと統合・自動管理するための RESTful API を提供します。これらのAPIはAPIキーで認証され、HTTP APIのサブセットです。 Service APIは現在ベータ版であり、一部のAPIは頻繁に変更される可能性があります。 @@ -10,7 +10,7 @@ Service APIは現在ベータ版であり、一部のAPIは頻繁に変更され ## APIキーの取得 -WebUIのサイドバーにある`API Keys`ボタンをクリックして、APIキーを作成します。 +WebUIのサイドバーにある `API Keys` ボタンをクリックして、APIキーを作成します。 ![create_api_key](/images/zh/api/create_api_key.png) @@ -18,6 +18,39 @@ WebUIのサイドバーにある`API Keys`ボタンをクリックして、API ![copy_api_key](/images/zh/api/copy_api_key.png) +## 認証方法 + +すべてのService APIは、以下の2つの認証方法をサポートしています： + +- **APIキー**: `X-API-Key: ` または `Authorization: Bearer ` ヘッダー経由 +- **ユーザートークン**: `Authorization: Bearer ` ヘッダー経由（ログイン後に取得） + ## APIの使用 -左サイドバーには、利用可能なすべてのAPIが一覧表示されています。インスタンスアドレス(バックエンドが公開するポートアドレス、デフォルトは`http://localhost:5300`)とAPIキーを入力し、`Try it out`ボタンをクリックしてAPIを呼び出すことができます。 +左サイドバーには、利用可能なすべてのAPIが一覧表示されています。インスタンスアドレス（デフォルトは `http://localhost:5300`）とAPIキーを入力し、`Try it out` ボタンをクリックしてAPIを呼び出せます。 + +## コアコンセプト + +### Provider + Model アーキテクチャ + +LangBotは **プロバイダー（Provider）+ モデル（Model）** の2層アーキテクチャでAIモデルを管理します： + +- **プロバイダー**: APIエンドポイント（`base_url`）、リクエスタータイプ、APIキーを定義。1つのプロバイダーに複数のモデルを関連付け可能。 +- **モデル**: プロバイダーに関連付け（`provider_uuid` 経由）、具体的なモデル名とパラメータを定義。プロバイダーのAPIエンドポイントとキーを継承。 + +``` +Provider (OpenAI) +├── base_url: https://api.openai.com/v1 +├── api_keys: [sk-xxx] +├── LLM: gpt-4o +├── LLM: gpt-4o-mini +└── Embedding: text-embedding-3-small +``` + +### リクエスター + +リクエスターはAIサービスとの通信プロトコルを定義します。`GET /api/v1/provider/requesters` で利用可能なリクエスター一覧を取得できます。 + +### 非同期タスク + +一部の操作（プラグインのインストール/削除/アップグレード）は非同期で実行され、`task_id` を返します。WebUIで進捗を確認できます。 diff --git a/openapi/service-api-en.json b/openapi/service-api-en.json index 0a197414a..b9f8cea69 100644 --- a/openapi/service-api-en.json +++ b/openapi/service-api-en.json @@ -1,9 +1,9 @@ { "openapi": "3.0.3", "info": { - "title": "LangBot API with API Key Authentication", - "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", + "title": "LangBot Service API", + "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n", + "version": "4.9.5", "contact": { "name": "LangBot", "url": "https://langbot.app" @@ -21,32 +21,48 @@ ], "tags": [ { - "name": "Models - LLM", - "description": "Large Language Model management operations" + "name": "Model Providers", + "description": "Model provider management. Providers define API endpoints and keys; models reference providers via provider_uuid." }, { - "name": "Models - Embeddings", - "description": "Embedding model management operations" + "name": "LLM Models", + "description": "Large Language Model (LLM) management. Each model is associated with a provider." + }, + { + "name": "Embedding Models", + "description": "Embedding model management. Each model is associated with a provider." }, { "name": "Bots", - "description": "Bot instance management operations" + "description": "Bot instance management and messaging" }, { "name": "Pipelines", - "description": "Pipeline configuration management operations" + "description": "Pipeline configuration management" }, { "name": "Knowledge Bases", - "description": "Built-in knowledge base management operations" + "description": "Knowledge base management" + }, + { + "name": "Knowledge Engines", + "description": "Knowledge engine (plugin-provided) queries" + }, + { + "name": "Parsers", + "description": "File parser (plugin-provided) queries" }, { "name": "Files", - "description": "File upload and management operations" + "description": "File upload operations" }, { "name": "Plugins", - "description": "Plugin installation and management operations" + "description": "Plugin installation, configuration, and management" + }, + { + "name": "System", + "description": "System information (no auth required)" } ], "security": [ @@ -58,24 +74,17 @@ } ], "paths": { - "/api/v1/provider/models/llm": { + "/api/v1/system/info": { "get": { "tags": [ - "Models - LLM" - ], - "summary": "List all LLM models", - "description": "Retrieve a list of all configured LLM models", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "System" ], + "summary": "获取系统信息", + "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。", + "security": [], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -85,9 +94,282 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "LLM Models" + ], + "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", @@ -104,26 +386,15 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ - "Models - LLM" - ], - "summary": "Create a new LLM model", - "description": "Create and configure a new LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "创建 LLM 模型", + "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { @@ -136,7 +407,7 @@ }, "responses": { "200": { - "description": "Model created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -146,17 +417,12 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "uuid": { "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440000" + "format": "uuid" } } } @@ -164,12 +430,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" } } } @@ -177,26 +437,23 @@ "/api/v1/provider/models/llm/{model_uuid}": { "get": { "tags": [ - "Models - LLM" - ], - "summary": "Get a specific LLM model", - "description": "Retrieve details of a specific LLM model by UUID", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "获取单个 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -206,10 +463,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -223,31 +476,25 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ - "Models - LLM" - ], - "summary": "Update an LLM model", - "description": "Update the configuration of an existing LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "更新 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -262,58 +509,29 @@ }, "responses": { "200": { - "description": "Model updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ - "Models - LLM" - ], - "summary": "Delete an LLM model", - "description": "Remove an LLM model from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "删除 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Model deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -321,21 +539,19 @@ "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { "tags": [ - "Models - LLM" - ], - "summary": "Test an LLM model", - "description": "Test the connectivity and functionality of an LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "测试 LLM 模型", + "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -344,30 +560,20 @@ "application/json": { "schema": { "type": "object", - "description": "Model configuration to test" + "properties": { + "prompt": { + "type": "string", + "description": "测试用的提示文本", + "example": "Hello" + } + } } } } }, "responses": { "200": { - "description": "Model test successful", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/Success" } } } @@ -375,21 +581,25 @@ "/api/v1/provider/models/embedding": { "get": { "tags": [ - "Models - Embedding" + "Embedding Models" ], - "summary": "List all embedding models", - "description": "Retrieve a list of all configured embedding models", - "security": [ + "summary": "获取所有向量模型", + "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。", + "parameters": [ { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] + "name": "provider_uuid", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "按供应商 UUID 过滤" } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -399,10 +609,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -418,26 +624,15 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ - "Models - Embedding" - ], - "summary": "Create a new embedding model", - "description": "Create and configure a new embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "创建向量模型", + "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { @@ -450,7 +645,7 @@ }, "responses": { "200": { - "description": "Model created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -460,10 +655,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -477,9 +668,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -487,25 +675,23 @@ "/api/v1/provider/models/embedding/{model_uuid}": { "get": { "tags": [ - "Models - Embedding" - ], - "summary": "Get a specific embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "获取单个向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -515,10 +701,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -532,30 +714,25 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ - "Models - Embedding" - ], - "summary": "Update an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "更新向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -570,57 +747,29 @@ }, "responses": { "200": { - "description": "Model updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ - "Models - Embedding" - ], - "summary": "Delete an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "删除向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Model deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -628,20 +777,19 @@ "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { "tags": [ - "Models - Embedding" - ], - "summary": "Test an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "测试向量模型", + "description": "向指定的向量模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -649,27 +797,21 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "测试用的文本", + "example": "Hello" + } + } } } } }, "responses": { "200": { - "description": "Model test successful", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -679,19 +821,10 @@ "tags": [ "Bots" ], - "summary": "List all bots", - "description": "Retrieve a list of all configured bot instances", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取所有机器人", "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -701,10 +834,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -720,9 +849,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, @@ -730,16 +856,7 @@ "tags": [ "Bots" ], - "summary": "Create a new bot", - "description": "Create and configure a new bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "创建机器人", "requestBody": { "required": true, "content": { @@ -752,7 +869,7 @@ }, "responses": { "200": { - "description": "Bot created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -762,10 +879,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -779,9 +892,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -791,16 +901,8 @@ "tags": [ "Bots" ], - "summary": "Get a specific bot", - "description": "Retrieve details of a specific bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取单个机器人", + "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。", "parameters": [ { "name": "bot_uuid", @@ -809,13 +911,12 @@ "schema": { "type": "string", "format": "uuid" - }, - "description": "Bot UUID" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -825,10 +926,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -842,11 +939,8 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, @@ -854,16 +948,7 @@ "tags": [ "Bots" ], - "summary": "Update a bot", - "description": "Update the configuration of an existing bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "更新机器人", "parameters": [ { "name": "bot_uuid", @@ -887,20 +972,7 @@ }, "responses": { "200": { - "description": "Bot updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, @@ -908,16 +980,7 @@ "tags": [ "Bots" ], - "summary": "Delete a bot", - "description": "Remove a bot instance from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "删除机器人", "parameters": [ { "name": "bot_uuid", @@ -931,20 +994,7 @@ ], "responses": { "200": { - "description": "Bot deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -954,16 +1004,8 @@ "tags": [ "Bots" ], - "summary": "Get bot event logs", - "description": "Retrieve event logs for a specific bot", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取机器人事件日志", + "description": "获取指定机器人的事件日志记录。", "parameters": [ { "name": "bot_uuid", @@ -984,13 +1026,13 @@ "properties": { "from_index": { "type": "integer", - "default": -1, - "description": "Starting index for logs (-1 for latest)" + "description": "起始索引（-1 表示从最新开始）", + "default": -1 }, "max_count": { "type": "integer", - "default": 10, - "description": "Maximum number of logs to retrieve" + "description": "最大返回数量", + "default": 10 } } } @@ -999,7 +1041,7 @@ }, "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1009,10 +1051,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1031,55 +1069,102 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } }, - "/api/v1/pipelines": { - "get": { + "/api/v1/platform/bots/{bot_uuid}/send_message": { + "post": { "tags": [ - "Pipelines" + "Bots" ], - "summary": "List all pipelines", - "description": "Retrieve a list of all configured pipelines", + "summary": "通过机器人发送消息", + "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。", "security": [ { "ApiKeyAuth": [] - }, - { - "BearerAuth": [] } ], "parameters": [ { - "name": "sort_by", - "in": "query", + "name": "bot_uuid", + "in": "path", + "required": true, "schema": { "type": "string", - "default": "created_at" - }, - "description": "Field to sort by" - }, - { - "name": "sort_order", - "in": "query", - "schema": { - "type": "string", - "enum": [ - "ASC", - "DESC" - ], - "default": "DESC" - }, - "description": "Sort order" + "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": "Successful response", + "description": "发送成功", "content": { "application/json": { "schema": { @@ -1089,9 +1174,74 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" + "data": { + "type": "object", + "properties": { + "sent": { + "type": "boolean", + "example": true + } + } + } + } + } + } + } + }, + "400": { + "description": "参数错误", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/v1/pipelines": { + "get": { + "tags": [ + "Pipelines" + ], + "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", @@ -1108,9 +1258,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, @@ -1118,16 +1265,7 @@ "tags": [ "Pipelines" ], - "summary": "Create a new pipeline", - "description": "Create and configure a new pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "创建流水线", "requestBody": { "required": true, "content": { @@ -1140,7 +1278,7 @@ }, "responses": { "200": { - "description": "Pipeline created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -1150,10 +1288,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1167,9 +1301,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -1179,19 +1310,11 @@ "tags": [ "Pipelines" ], - "summary": "Get pipeline metadata", - "description": "Retrieve metadata and configuration options for pipelines", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取流水线元数据", + "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。", "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1201,10 +1324,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1217,9 +1336,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -1229,16 +1345,7 @@ "tags": [ "Pipelines" ], - "summary": "Get a specific pipeline", - "description": "Retrieve details of a specific pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取单个流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1252,7 +1359,7 @@ ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1262,10 +1369,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1279,11 +1382,8 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, @@ -1291,16 +1391,7 @@ "tags": [ "Pipelines" ], - "summary": "Update a pipeline", - "description": "Update the configuration of an existing pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "更新流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1324,20 +1415,7 @@ }, "responses": { "200": { - "description": "Pipeline updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, @@ -1345,16 +1423,7 @@ "tags": [ "Pipelines" ], - "summary": "Delete a pipeline", - "description": "Remove a pipeline from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "删除流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1368,20 +1437,57 @@ ], "responses": { "200": { - "description": "Pipeline deleted successfully", + "$ref": "#/components/responses/Success" + } + } + } + }, + "/api/v1/pipelines/{pipeline_uuid}/copy": { + "post": { + "tags": [ + "Pipelines" + ], + "summary": "复制流水线", + "description": "复制一个已有的流水线，生成一个新的副本。", + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "复制成功", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SuccessResponse" + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + } + } + } + } } } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } } @@ -1391,16 +1497,8 @@ "tags": [ "Pipelines" ], - "summary": "Get pipeline extensions", - "description": "Retrieve extensions and plugins configured for a pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取流水线扩展配置", + "description": "获取流水线绑定的插件和 MCP 服务器配置。", "parameters": [ { "name": "pipeline_uuid", @@ -1414,7 +1512,7 @@ ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1424,241 +1522,34 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - }, - "put": { - "tags": [ - "Pipelines" - ], - "summary": "Update pipeline extensions", - "description": "Update the extensions configuration for a pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "name": "pipeline_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "responses": { - "200": { - "description": "Extensions updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - } - }, - "/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": { + "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" @@ -1670,373 +1561,28 @@ } } } - } - }, - "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" + "404": { + "$ref": "#/components/responses/NotFound" } - ], - "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": { + "put": { "tags": [ - "Plugins" + "Pipelines" ], - "summary": "Delete Plugin", - "description": "Uninstall the specified plugin", - "operationId": "deletePlugin", + "summary": "更新流水线扩展配置", + "description": "更新流水线绑定的插件和 MCP 服务器。", "parameters": [ { - "name": "author", + "name": "pipeline_uuid", "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" - } - } - } - } - } - } + "type": "string", + "format": "uuid" } } - }, - "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, @@ -2044,60 +1590,26 @@ "application/json": { "schema": { "type": "object", - "required": [ - "target_type", - "target_id", - "message_chain" - ], "properties": { - "target_type": { - "type": "string", - "enum": [ - "person", - "group" - ], - "description": "Target type" + "enable_all_plugins": { + "type": "boolean", + "default": true }, - "target_id": { - "type": "string", - "description": "Target ID (user ID or group ID)" + "enable_all_mcp_servers": { + "type": "boolean", + "default": true }, - "message_chain": { + "bound_plugins": { "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" - } - ] + "type": "string" + } + }, + "bound_mcp_servers": { + "type": "array", + "items": { + "type": "string" + } } } } @@ -2106,80 +1618,9 @@ }, "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases": { @@ -2187,12 +1628,10 @@ "tags": [ "Knowledge Bases" ], - "summary": "Get All Knowledge Bases", - "description": "Get all builtin knowledge bases", - "operationId": "listKnowledgeBases", + "summary": "获取所有知识库", "responses": { "200": { - "description": "Success", + "description": "成功", "content": { "application/json": { "schema": { @@ -2202,10 +1641,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2222,23 +1657,13 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { "tags": [ "Knowledge Bases" ], - "summary": "Create Knowledge Base", - "description": "Create a new knowledge base", - "operationId": "createKnowledgeBase", + "summary": "创建知识库", "requestBody": { "required": true, "content": { @@ -2246,35 +1671,31 @@ "schema": { "type": "object", "required": [ - "name", - "embedding_model_uuid" + "name" ], "properties": { "name": { - "type": "string", - "description": "name" + "type": "string" }, "description": { - "type": "string", - "description": "description" + "type": "string" }, - "embedding_model_uuid": { + "engine_plugin_id": { "type": "string", - "description": "Embedding model UUID" + "description": "知识引擎插件 ID（author/name 格式）" + }, + "creation_settings": { + "type": "object", + "description": "引擎创建参数" } } - }, - "example": { - "name": "技术文档库", - "description": "存储技术文档和API参考", - "embedding_model_uuid": "uuid-of-embedding-model" } } } }, "responses": { "200": { - "description": "Knowledge base created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -2284,15 +1705,12 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "uuid": { - "type": "string" + "type": "string", + "format": "uuid" } } } @@ -2301,15 +1719,7 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}": { @@ -2317,23 +1727,21 @@ "tags": [ "Knowledge Bases" ], - "summary": "Get Knowledge Base Details", - "description": "Get details info of specified knowledge base", - "operationId": "getKnowledgeBase", + "summary": "获取单个知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Success", + "description": "成功", "content": { "application/json": { "schema": { @@ -2343,10 +1751,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2361,51 +1765,24 @@ } }, "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" - } - } - } - } - } + "$ref": "#/components/responses/NotFound" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "put": { "tags": [ "Knowledge Bases" ], - "summary": "Update Knowledge Base Info", - "description": "Update knowledge base information", - "operationId": "updateKnowledgeBase", + "summary": "更新知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2428,89 +1805,31 @@ }, "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "delete": { "tags": [ "Knowledge Bases" ], - "summary": "Delete Knowledge Base", - "description": "Delete a specified knowledge base", - "operationId": "deleteKnowledgeBase", + "summary": "删除知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { @@ -2518,18 +1837,16 @@ "tags": [ "Knowledge Bases" ], - "summary": "List Knowledge Base Files", - "description": "Get all files in the specified knowledge base", - "operationId": "listKnowledgeBaseFiles", + "summary": "获取知识库文件列表", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -2544,10 +1861,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2564,32 +1877,23 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { "tags": [ "Knowledge Bases" ], - "summary": "Add File to Knowledge Base", - "description": "Add uploaded file to knowledge base for processing", - "operationId": "addFileToKnowledgeBase", + "summary": "将文件存入知识库", + "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2604,19 +1908,20 @@ "properties": { "file_id": { "type": "string", - "description": "File ID（从文件上传接口获取）" + "description": "已上传的文件 ID" + }, + "parser_plugin_id": { + "type": "string", + "description": "指定的解析器插件 ID（可选）" } } - }, - "example": { - "file_id": "document_abc123.pdf" } } } }, "responses": { "200": { - "description": "Addition successful", + "description": "成功", "content": { "application/json": { "schema": { @@ -2626,16 +1931,11 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "task_id": { - "type": "string", - "description": "Processing task ID" + "type": "string" } } } @@ -2644,15 +1944,7 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { @@ -2660,18 +1952,16 @@ "tags": [ "Knowledge Bases" ], - "summary": "Delete File from Knowledge Base", - "description": "Delete file from the specified knowledge base", - "operationId": "deleteFileFromKnowledgeBase", + "summary": "从知识库删除文件", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } }, { "name": "file_id", @@ -2679,43 +1969,14 @@ "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { @@ -2723,18 +1984,17 @@ "tags": [ "Knowledge Bases" ], - "summary": "Retrieve Knowledge", - "description": "Search for relevant knowledge in the knowledge base", - "operationId": "retrieveKnowledge", + "summary": "检索知识库", + "description": "对知识库进行语义检索，返回相关文档片段。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2749,19 +2009,25 @@ "properties": { "query": { "type": "string", - "description": "Query text" + "description": "检索查询文本" + }, + "retrieval_settings": { + "type": "object", + "description": "检索参数（如 top_k 等）", + "properties": { + "top_k": { + "type": "integer" + } + } } } - }, - "example": { - "query": "如何使用 LangBot 创建机器人？" } } } }, "responses": { "200": { - "description": "Retrieval successful", + "description": "成功", "content": { "application/json": { "schema": { @@ -2771,10 +2037,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2791,15 +2053,702 @@ } } } - }, - "security": [ + } + } + }, + "/api/v1/knowledge/engines": { + "get": { + "tags": [ + "Knowledge Engines" + ], + "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": [ + "Knowledge Engines" + ], + "summary": "获取知识引擎创建配置模式", + "description": "获取指定知识引擎的创建参数 JSON Schema。", + "parameters": [ { - "ApiKeyAuth": [] + "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": [ + "Knowledge Engines" + ], + "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": [ + "Parsers" + ], + "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": [ + "Files" + ], + "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": [ + "Files" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "summary": "获取插件详情", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + } }, { - "BearerAuth": [] + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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" + } + } + } + } + } + } + } + } + } } } }, @@ -2808,30 +2757,17 @@ "ApiKeyAuth": { "type": "apiKey", "in": "header", - "name": "X-API-Key", - "description": "API Key authentication using X-API-Key header.\nExample: `X-API-Key: lbk_your_api_key_here`\n" + "name": "X-API-Key" }, "BearerAuth": { "type": "http", - "scheme": "bearer", - "description": "Bearer token authentication. Can be either a user JWT token or an API key.\nExample: `Authorization: Bearer `\n" - } - }, - "parameters": { - "ModelUUID": { - "name": "model_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - }, - "description": "Model UUID" + "scheme": "bearer" } }, "schemas": { - "LLMModel": { + "ModelProvider": { "type": "object", + "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。", "properties": { "uuid": { "type": "string", @@ -2839,57 +2775,133 @@ }, "name": { "type": "string", - "example": "GPT-4" - }, - "description": { - "type": "string", - "example": "OpenAI GPT-4 model" + "example": "OpenAI" }, "requester": { "type": "string", + "description": "请求器类型", "example": "openai-chat-completions" }, - "requester_config": { - "type": "object", - "properties": { - "model": { - "type": "string", - "example": "gpt-4" - }, - "args": { - "type": "object" - } + "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": "object", - "properties": { - "name": { - "type": "string" - }, - "keys": { - "type": "array", - "items": { - "type": "string" - } - } - } + "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" + "vision", + "tool-use" ] }, "extra_args": { - "type": "object" + "type": "object", + "description": "额外参数（如 temperature、max_tokens 等）" + }, + "prefered_ranking": { + "type": "integer", + "description": "优先级排序（越大越优先）", + "default": 0 }, "created_at": { "type": "string", @@ -2905,37 +2917,35 @@ "type": "object", "required": [ "name", - "requester", - "requester_config", - "api_keys" + "provider_uuid" ], "properties": { "name": { - "type": "string" + "type": "string", + "description": "模型名称（即模型 ID）", + "example": "gpt-4o" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "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 } } }, @@ -2945,17 +2955,9 @@ "name": { "type": "string" }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "abilities": { "type": "array", @@ -2965,37 +2967,37 @@ }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer" } } }, "EmbeddingModel": { "type": "object", + "description": "向量模型。通过 provider_uuid 关联到供应商。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { - "type": "string" + "type": "string", + "description": "模型名称（即模型 ID）", + "example": "text-embedding-3-small" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "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" @@ -3010,31 +3012,23 @@ "type": "object", "required": [ "name", - "requester", - "requester_config", - "api_keys" + "provider_uuid" ], "properties": { "name": { - "type": "string" + "type": "string", + "example": "text-embedding-3-small" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer", + "default": 0 } } }, @@ -3044,20 +3038,15 @@ "name": { "type": "string" }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer" } } }, @@ -3113,6 +3102,9 @@ "name": { "type": "string" }, + "adapter": { + "type": "string" + }, "config": { "type": "object" } @@ -3147,8 +3139,7 @@ "PipelineCreate": { "type": "object", "required": [ - "name", - "config" + "name" ], "properties": { "name": { @@ -3167,23 +3158,9 @@ }, "config": { "type": "object" - } - } - }, - "SuccessResponse": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "nullable": true + "is_default": { + "type": "boolean" } } }, @@ -3195,61 +3172,34 @@ "example": -1 }, "msg": { - "type": "string", - "example": "Error message" + "type": "string" } } } }, "responses": { - "UnauthorizedError": { - "description": "Authentication required or invalid credentials", + "Success": { + "description": "操作成功", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "no_auth": { - "value": { - "code": -1, - "msg": "No valid authentication provided (user token or API key required)" - } - }, - "invalid_key": { - "value": { - "code": -1, - "msg": "Invalid API key" + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 } } } } } }, - "NotFoundError": { - "description": "Resource not found", + "NotFound": { + "description": "资源未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -1, - "msg": "Resource not found" - } - } - } - }, - "InternalServerError": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -2, - "msg": "Internal server error" } } } diff --git a/openapi/service-api-ja.json b/openapi/service-api-ja.json index 0a197414a..64c3f55af 100644 --- a/openapi/service-api-ja.json +++ b/openapi/service-api-ja.json @@ -1,9 +1,9 @@ { "openapi": "3.0.3", "info": { - "title": "LangBot API with API Key Authentication", - "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", + "title": "LangBot Service API", + "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n", + "version": "4.9.5", "contact": { "name": "LangBot", "url": "https://langbot.app" @@ -21,32 +21,48 @@ ], "tags": [ { - "name": "Models - LLM", - "description": "Large Language Model management operations" + "name": "モデルプロバイダー", + "description": "Model provider management. Providers define API endpoints and keys; models reference providers via provider_uuid." }, { - "name": "Models - Embeddings", - "description": "Embedding model management operations" + "name": "LLMモデル", + "description": "Large Language Model (LLM) management. Each model is associated with a provider." }, { - "name": "Bots", - "description": "Bot instance management operations" + "name": "埋め込みモデル", + "description": "Embedding model management. Each model is associated with a provider." }, { - "name": "Pipelines", - "description": "Pipeline configuration management operations" + "name": "ボット", + "description": "Bot instance management and messaging" }, { - "name": "Knowledge Bases", - "description": "Built-in knowledge base management operations" + "name": "パイプライン", + "description": "Pipeline configuration management" }, { - "name": "Files", - "description": "File upload and management operations" + "name": "ナレッジベース", + "description": "Knowledge base management" }, { - "name": "Plugins", - "description": "Plugin installation and management operations" + "name": "ナレッジエンジン", + "description": "Knowledge engine (plugin-provided) queries" + }, + { + "name": "パーサー", + "description": "File parser (plugin-provided) queries" + }, + { + "name": "ファイル", + "description": "File upload operations" + }, + { + "name": "プラグイン", + "description": "Plugin installation, configuration, and management" + }, + { + "name": "システム", + "description": "System information (no auth required)" } ], "security": [ @@ -58,24 +74,17 @@ } ], "paths": { - "/api/v1/provider/models/llm": { + "/api/v1/system/info": { "get": { "tags": [ - "Models - LLM" - ], - "summary": "List all LLM models", - "description": "Retrieve a list of all configured LLM models", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "System" ], + "summary": "获取系统信息", + "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。", + "security": [], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -85,9 +94,282 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "Model Providers" + ], + "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": [ + "LLM Models" + ], + "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", @@ -104,26 +386,15 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ - "Models - LLM" - ], - "summary": "Create a new LLM model", - "description": "Create and configure a new LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "创建 LLM 模型", + "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { @@ -136,7 +407,7 @@ }, "responses": { "200": { - "description": "Model created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -146,17 +417,12 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "uuid": { "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440000" + "format": "uuid" } } } @@ -164,12 +430,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" } } } @@ -177,26 +437,23 @@ "/api/v1/provider/models/llm/{model_uuid}": { "get": { "tags": [ - "Models - LLM" - ], - "summary": "Get a specific LLM model", - "description": "Retrieve details of a specific LLM model by UUID", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "获取单个 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -206,10 +463,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -223,31 +476,25 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ - "Models - LLM" - ], - "summary": "Update an LLM model", - "description": "Update the configuration of an existing LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "更新 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -262,58 +509,29 @@ }, "responses": { "200": { - "description": "Model updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ - "Models - LLM" - ], - "summary": "Delete an LLM model", - "description": "Remove an LLM model from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "删除 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Model deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -321,21 +539,19 @@ "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { "tags": [ - "Models - LLM" - ], - "summary": "Test an LLM model", - "description": "Test the connectivity and functionality of an LLM model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "LLM Models" ], + "summary": "测试 LLM 模型", + "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -344,30 +560,20 @@ "application/json": { "schema": { "type": "object", - "description": "Model configuration to test" + "properties": { + "prompt": { + "type": "string", + "description": "测试用的提示文本", + "example": "Hello" + } + } } } } }, "responses": { "200": { - "description": "Model test successful", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" + "$ref": "#/components/responses/Success" } } } @@ -375,21 +581,25 @@ "/api/v1/provider/models/embedding": { "get": { "tags": [ - "Models - Embedding" + "Embedding Models" ], - "summary": "List all embedding models", - "description": "Retrieve a list of all configured embedding models", - "security": [ + "summary": "获取所有向量模型", + "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。", + "parameters": [ { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] + "name": "provider_uuid", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "按供应商 UUID 过滤" } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -399,10 +609,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -418,26 +624,15 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ - "Models - Embedding" - ], - "summary": "Create a new embedding model", - "description": "Create and configure a new embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "创建向量模型", + "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { @@ -450,7 +645,7 @@ }, "responses": { "200": { - "description": "Model created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -460,10 +655,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -477,9 +668,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -487,25 +675,23 @@ "/api/v1/provider/models/embedding/{model_uuid}": { "get": { "tags": [ - "Models - Embedding" - ], - "summary": "Get a specific embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "获取单个向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -515,10 +701,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -532,30 +714,25 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ - "Models - Embedding" - ], - "summary": "Update an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "更新向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -570,57 +747,29 @@ }, "responses": { "200": { - "description": "Model updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, "delete": { "tags": [ - "Models - Embedding" - ], - "summary": "Delete an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "删除向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Model deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -628,20 +777,19 @@ "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { "tags": [ - "Models - Embedding" - ], - "summary": "Test an embedding model", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } + "Embedding Models" ], + "summary": "测试向量模型", + "description": "向指定的向量模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -649,27 +797,21 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "测试用的文本", + "example": "Hello" + } + } } } } }, "responses": { "200": { - "description": "Model test successful", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -679,19 +821,10 @@ "tags": [ "Bots" ], - "summary": "List all bots", - "description": "Retrieve a list of all configured bot instances", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取所有机器人", "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -701,10 +834,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -720,9 +849,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, @@ -730,16 +856,7 @@ "tags": [ "Bots" ], - "summary": "Create a new bot", - "description": "Create and configure a new bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "创建机器人", "requestBody": { "required": true, "content": { @@ -752,7 +869,7 @@ }, "responses": { "200": { - "description": "Bot created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -762,10 +879,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -779,9 +892,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -791,16 +901,8 @@ "tags": [ "Bots" ], - "summary": "Get a specific bot", - "description": "Retrieve details of a specific bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取单个机器人", + "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。", "parameters": [ { "name": "bot_uuid", @@ -809,13 +911,12 @@ "schema": { "type": "string", "format": "uuid" - }, - "description": "Bot UUID" + } } ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -825,10 +926,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -842,11 +939,8 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, @@ -854,16 +948,7 @@ "tags": [ "Bots" ], - "summary": "Update a bot", - "description": "Update the configuration of an existing bot instance", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "更新机器人", "parameters": [ { "name": "bot_uuid", @@ -887,20 +972,7 @@ }, "responses": { "200": { - "description": "Bot updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, @@ -908,16 +980,7 @@ "tags": [ "Bots" ], - "summary": "Delete a bot", - "description": "Remove a bot instance from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "删除机器人", "parameters": [ { "name": "bot_uuid", @@ -931,20 +994,7 @@ ], "responses": { "200": { - "description": "Bot deleted successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } } @@ -954,16 +1004,8 @@ "tags": [ "Bots" ], - "summary": "Get bot event logs", - "description": "Retrieve event logs for a specific bot", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取机器人事件日志", + "description": "获取指定机器人的事件日志记录。", "parameters": [ { "name": "bot_uuid", @@ -984,13 +1026,13 @@ "properties": { "from_index": { "type": "integer", - "default": -1, - "description": "Starting index for logs (-1 for latest)" + "description": "起始索引（-1 表示从最新开始）", + "default": -1 }, "max_count": { "type": "integer", - "default": 10, - "description": "Maximum number of logs to retrieve" + "description": "最大返回数量", + "default": 10 } } } @@ -999,7 +1041,7 @@ }, "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1009,10 +1051,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1031,55 +1069,102 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } }, - "/api/v1/pipelines": { - "get": { + "/api/v1/platform/bots/{bot_uuid}/send_message": { + "post": { "tags": [ - "Pipelines" + "Bots" ], - "summary": "List all pipelines", - "description": "Retrieve a list of all configured pipelines", + "summary": "通过机器人发送消息", + "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。", "security": [ { "ApiKeyAuth": [] - }, - { - "BearerAuth": [] } ], "parameters": [ { - "name": "sort_by", - "in": "query", + "name": "bot_uuid", + "in": "path", + "required": true, "schema": { "type": "string", - "default": "created_at" - }, - "description": "Field to sort by" - }, - { - "name": "sort_order", - "in": "query", - "schema": { - "type": "string", - "enum": [ - "ASC", - "DESC" - ], - "default": "DESC" - }, - "description": "Sort order" + "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": "Successful response", + "description": "发送成功", "content": { "application/json": { "schema": { @@ -1089,9 +1174,74 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" + "data": { + "type": "object", + "properties": { + "sent": { + "type": "boolean", + "example": true + } + } + } + } + } + } + } + }, + "400": { + "description": "参数错误", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/v1/pipelines": { + "get": { + "tags": [ + "Pipelines" + ], + "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", @@ -1108,9 +1258,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, @@ -1118,16 +1265,7 @@ "tags": [ "Pipelines" ], - "summary": "Create a new pipeline", - "description": "Create and configure a new pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "创建流水线", "requestBody": { "required": true, "content": { @@ -1140,7 +1278,7 @@ }, "responses": { "200": { - "description": "Pipeline created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -1150,10 +1288,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1167,9 +1301,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -1179,19 +1310,11 @@ "tags": [ "Pipelines" ], - "summary": "Get pipeline metadata", - "description": "Retrieve metadata and configuration options for pipelines", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取流水线元数据", + "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。", "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1201,10 +1324,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1217,9 +1336,6 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } @@ -1229,16 +1345,7 @@ "tags": [ "Pipelines" ], - "summary": "Get a specific pipeline", - "description": "Retrieve details of a specific pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取单个流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1252,7 +1359,7 @@ ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1262,10 +1369,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -1279,11 +1382,8 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } }, @@ -1291,16 +1391,7 @@ "tags": [ "Pipelines" ], - "summary": "Update a pipeline", - "description": "Update the configuration of an existing pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "更新流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1324,20 +1415,7 @@ }, "responses": { "200": { - "description": "Pipeline updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/Success" } } }, @@ -1345,16 +1423,7 @@ "tags": [ "Pipelines" ], - "summary": "Delete a pipeline", - "description": "Remove a pipeline from the system", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "删除流水线", "parameters": [ { "name": "pipeline_uuid", @@ -1368,20 +1437,57 @@ ], "responses": { "200": { - "description": "Pipeline deleted successfully", + "$ref": "#/components/responses/Success" + } + } + } + }, + "/api/v1/pipelines/{pipeline_uuid}/copy": { + "post": { + "tags": [ + "Pipelines" + ], + "summary": "复制流水线", + "description": "复制一个已有的流水线，生成一个新的副本。", + "parameters": [ + { + "name": "pipeline_uuid", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "复制成功", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SuccessResponse" + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "data": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "format": "uuid" + } + } + } + } } } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, "404": { - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/responses/NotFound" } } } @@ -1391,16 +1497,8 @@ "tags": [ "Pipelines" ], - "summary": "Get pipeline extensions", - "description": "Retrieve extensions and plugins configured for a pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "summary": "获取流水线扩展配置", + "description": "获取流水线绑定的插件和 MCP 服务器配置。", "parameters": [ { "name": "pipeline_uuid", @@ -1414,7 +1512,7 @@ ], "responses": { "200": { - "description": "Successful response", + "description": "成功", "content": { "application/json": { "schema": { @@ -1424,241 +1522,34 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - }, - "put": { - "tags": [ - "Pipelines" - ], - "summary": "Update pipeline extensions", - "description": "Update the extensions configuration for a pipeline", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "name": "pipeline_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "responses": { - "200": { - "description": "Extensions updated successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - } - }, - "/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": { + "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" @@ -1670,373 +1561,28 @@ } } } - } - }, - "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" + "404": { + "$ref": "#/components/responses/NotFound" } - ], - "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": { + "put": { "tags": [ - "Plugins" + "Pipelines" ], - "summary": "Delete Plugin", - "description": "Uninstall the specified plugin", - "operationId": "deletePlugin", + "summary": "更新流水线扩展配置", + "description": "更新流水线绑定的插件和 MCP 服务器。", "parameters": [ { - "name": "author", + "name": "pipeline_uuid", "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" - } - } - } - } - } - } + "type": "string", + "format": "uuid" } } - }, - "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, @@ -2044,60 +1590,26 @@ "application/json": { "schema": { "type": "object", - "required": [ - "target_type", - "target_id", - "message_chain" - ], "properties": { - "target_type": { - "type": "string", - "enum": [ - "person", - "group" - ], - "description": "Target type" + "enable_all_plugins": { + "type": "boolean", + "default": true }, - "target_id": { - "type": "string", - "description": "Target ID (user ID or group ID)" + "enable_all_mcp_servers": { + "type": "boolean", + "default": true }, - "message_chain": { + "bound_plugins": { "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" - } - ] + "type": "string" + } + }, + "bound_mcp_servers": { + "type": "array", + "items": { + "type": "string" + } } } } @@ -2106,80 +1618,9 @@ }, "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases": { @@ -2187,12 +1628,10 @@ "tags": [ "Knowledge Bases" ], - "summary": "Get All Knowledge Bases", - "description": "Get all builtin knowledge bases", - "operationId": "listKnowledgeBases", + "summary": "获取所有知识库", "responses": { "200": { - "description": "Success", + "description": "成功", "content": { "application/json": { "schema": { @@ -2202,10 +1641,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2222,23 +1657,13 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { "tags": [ "Knowledge Bases" ], - "summary": "Create Knowledge Base", - "description": "Create a new knowledge base", - "operationId": "createKnowledgeBase", + "summary": "创建知识库", "requestBody": { "required": true, "content": { @@ -2246,35 +1671,31 @@ "schema": { "type": "object", "required": [ - "name", - "embedding_model_uuid" + "name" ], "properties": { "name": { - "type": "string", - "description": "name" + "type": "string" }, "description": { - "type": "string", - "description": "description" + "type": "string" }, - "embedding_model_uuid": { + "engine_plugin_id": { "type": "string", - "description": "Embedding model UUID" + "description": "知识引擎插件 ID（author/name 格式）" + }, + "creation_settings": { + "type": "object", + "description": "引擎创建参数" } } - }, - "example": { - "name": "技术文档库", - "description": "存储技术文档和API参考", - "embedding_model_uuid": "uuid-of-embedding-model" } } } }, "responses": { "200": { - "description": "Knowledge base created successfully", + "description": "创建成功", "content": { "application/json": { "schema": { @@ -2284,15 +1705,12 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "uuid": { - "type": "string" + "type": "string", + "format": "uuid" } } } @@ -2301,15 +1719,7 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}": { @@ -2317,23 +1727,21 @@ "tags": [ "Knowledge Bases" ], - "summary": "Get Knowledge Base Details", - "description": "Get details info of specified knowledge base", - "operationId": "getKnowledgeBase", + "summary": "获取单个知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "Success", + "description": "成功", "content": { "application/json": { "schema": { @@ -2343,10 +1751,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2361,51 +1765,24 @@ } }, "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" - } - } - } - } - } + "$ref": "#/components/responses/NotFound" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "put": { "tags": [ "Knowledge Bases" ], - "summary": "Update Knowledge Base Info", - "description": "Update knowledge base information", - "operationId": "updateKnowledgeBase", + "summary": "更新知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2428,89 +1805,31 @@ }, "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "delete": { "tags": [ "Knowledge Bases" ], - "summary": "Delete Knowledge Base", - "description": "Delete a specified knowledge base", - "operationId": "deleteKnowledgeBase", + "summary": "删除知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { @@ -2518,18 +1837,16 @@ "tags": [ "Knowledge Bases" ], - "summary": "List Knowledge Base Files", - "description": "Get all files in the specified knowledge base", - "operationId": "listKnowledgeBaseFiles", + "summary": "获取知识库文件列表", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -2544,10 +1861,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2564,32 +1877,23 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { "tags": [ "Knowledge Bases" ], - "summary": "Add File to Knowledge Base", - "description": "Add uploaded file to knowledge base for processing", - "operationId": "addFileToKnowledgeBase", + "summary": "将文件存入知识库", + "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2604,19 +1908,20 @@ "properties": { "file_id": { "type": "string", - "description": "File ID（从文件上传接口获取）" + "description": "已上传的文件 ID" + }, + "parser_plugin_id": { + "type": "string", + "description": "指定的解析器插件 ID（可选）" } } - }, - "example": { - "file_id": "document_abc123.pdf" } } } }, "responses": { "200": { - "description": "Addition successful", + "description": "成功", "content": { "application/json": { "schema": { @@ -2626,16 +1931,11 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { "task_id": { - "type": "string", - "description": "Processing task ID" + "type": "string" } } } @@ -2644,15 +1944,7 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { @@ -2660,18 +1952,16 @@ "tags": [ "Knowledge Bases" ], - "summary": "Delete File from Knowledge Base", - "description": "Delete file from the specified knowledge base", - "operationId": "deleteFileFromKnowledgeBase", + "summary": "从知识库删除文件", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } }, { "name": "file_id", @@ -2679,43 +1969,14 @@ "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" - } - } - } - } - } + "$ref": "#/components/responses/Success" } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { @@ -2723,18 +1984,17 @@ "tags": [ "Knowledge Bases" ], - "summary": "Retrieve Knowledge", - "description": "Search for relevant knowledge in the knowledge base", - "operationId": "retrieveKnowledge", + "summary": "检索知识库", + "description": "对知识库进行语义检索，返回相关文档片段。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { - "type": "string" - }, - "description": "Knowledge Base UUID" + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -2749,19 +2009,25 @@ "properties": { "query": { "type": "string", - "description": "Query text" + "description": "检索查询文本" + }, + "retrieval_settings": { + "type": "object", + "description": "检索参数（如 top_k 等）", + "properties": { + "top_k": { + "type": "integer" + } + } } } - }, - "example": { - "query": "如何使用 LangBot 创建机器人？" } } } }, "responses": { "200": { - "description": "Retrieval successful", + "description": "成功", "content": { "application/json": { "schema": { @@ -2771,10 +2037,6 @@ "type": "integer", "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, "data": { "type": "object", "properties": { @@ -2791,15 +2053,702 @@ } } } - }, - "security": [ + } + } + }, + "/api/v1/knowledge/engines": { + "get": { + "tags": [ + "Knowledge Engines" + ], + "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": [ + "Knowledge Engines" + ], + "summary": "获取知识引擎创建配置模式", + "description": "获取指定知识引擎的创建参数 JSON Schema。", + "parameters": [ { - "ApiKeyAuth": [] + "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": [ + "Knowledge Engines" + ], + "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": [ + "Parsers" + ], + "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": [ + "Files" + ], + "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": [ + "Files" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "summary": "获取插件详情", + "parameters": [ + { + "name": "author", + "in": "path", + "required": true, + "schema": { + "type": "string" + } }, { - "BearerAuth": [] + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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": [ + "Plugins" + ], + "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" + } + } + } + } + } + } + } + } + } } } }, @@ -2808,30 +2757,17 @@ "ApiKeyAuth": { "type": "apiKey", "in": "header", - "name": "X-API-Key", - "description": "API Key authentication using X-API-Key header.\nExample: `X-API-Key: lbk_your_api_key_here`\n" + "name": "X-API-Key" }, "BearerAuth": { "type": "http", - "scheme": "bearer", - "description": "Bearer token authentication. Can be either a user JWT token or an API key.\nExample: `Authorization: Bearer `\n" - } - }, - "parameters": { - "ModelUUID": { - "name": "model_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - }, - "description": "Model UUID" + "scheme": "bearer" } }, "schemas": { - "LLMModel": { + "ModelProvider": { "type": "object", + "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。", "properties": { "uuid": { "type": "string", @@ -2839,57 +2775,133 @@ }, "name": { "type": "string", - "example": "GPT-4" - }, - "description": { - "type": "string", - "example": "OpenAI GPT-4 model" + "example": "OpenAI" }, "requester": { "type": "string", + "description": "请求器类型", "example": "openai-chat-completions" }, - "requester_config": { - "type": "object", - "properties": { - "model": { - "type": "string", - "example": "gpt-4" - }, - "args": { - "type": "object" - } + "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": "object", - "properties": { - "name": { - "type": "string" - }, - "keys": { - "type": "array", - "items": { - "type": "string" - } - } - } + "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" + "vision", + "tool-use" ] }, "extra_args": { - "type": "object" + "type": "object", + "description": "额外参数（如 temperature、max_tokens 等）" + }, + "prefered_ranking": { + "type": "integer", + "description": "优先级排序（越大越优先）", + "default": 0 }, "created_at": { "type": "string", @@ -2905,37 +2917,35 @@ "type": "object", "required": [ "name", - "requester", - "requester_config", - "api_keys" + "provider_uuid" ], "properties": { "name": { - "type": "string" + "type": "string", + "description": "模型名称（即模型 ID）", + "example": "gpt-4o" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "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 } } }, @@ -2945,17 +2955,9 @@ "name": { "type": "string" }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "abilities": { "type": "array", @@ -2965,37 +2967,37 @@ }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer" } } }, "EmbeddingModel": { "type": "object", + "description": "向量模型。通过 provider_uuid 关联到供应商。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { - "type": "string" + "type": "string", + "description": "模型名称（即模型 ID）", + "example": "text-embedding-3-small" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "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" @@ -3010,31 +3012,23 @@ "type": "object", "required": [ "name", - "requester", - "requester_config", - "api_keys" + "provider_uuid" ], "properties": { "name": { - "type": "string" + "type": "string", + "example": "text-embedding-3-small" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer", + "default": 0 } } }, @@ -3044,20 +3038,15 @@ "name": { "type": "string" }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid" }, "extra_args": { "type": "object" + }, + "prefered_ranking": { + "type": "integer" } } }, @@ -3113,6 +3102,9 @@ "name": { "type": "string" }, + "adapter": { + "type": "string" + }, "config": { "type": "object" } @@ -3147,8 +3139,7 @@ "PipelineCreate": { "type": "object", "required": [ - "name", - "config" + "name" ], "properties": { "name": { @@ -3167,23 +3158,9 @@ }, "config": { "type": "object" - } - } - }, - "SuccessResponse": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "example": 0 }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "nullable": true + "is_default": { + "type": "boolean" } } }, @@ -3195,61 +3172,34 @@ "example": -1 }, "msg": { - "type": "string", - "example": "Error message" + "type": "string" } } } }, "responses": { - "UnauthorizedError": { - "description": "Authentication required or invalid credentials", + "Success": { + "description": "操作成功", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "no_auth": { - "value": { - "code": -1, - "msg": "No valid authentication provided (user token or API key required)" - } - }, - "invalid_key": { - "value": { - "code": -1, - "msg": "Invalid API key" + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 } } } } } }, - "NotFoundError": { - "description": "Resource not found", + "NotFound": { + "description": "资源未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -1, - "msg": "Resource not found" - } - } - } - }, - "InternalServerError": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -2, - "msg": "Internal server error" } } } diff --git a/openapi/service-api-zh.json b/openapi/service-api-zh.json index 817c8aa74..8f6166c9b 100644 --- a/openapi/service-api-zh.json +++ b/openapi/service-api-zh.json @@ -1,9 +1,9 @@ { "openapi": "3.0.3", "info": { - "title": "LangBot API 与 API 密钥认证", - "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，\n供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer `）\n- API 密钥（通过 `X-API-Key: ` 或 `Authorization: Bearer `）\n\n本文档中的所有接口都同时支持这两种认证方式。\n", - "version": "4.4.1", + "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" @@ -21,32 +21,48 @@ ], "tags": [ { - "name": "模型 - 大语言模型", - "description": "大语言模型管理操作" + "name": "模型供应商", + "description": "模型供应商管理。供应商定义了 API 地址和密钥，模型通过 provider_uuid 关联到供应商。" }, { - "name": "模型 - 向量模型", - "description": "向量模型管理操作" + "name": "大语言模型", + "description": "大语言模型 (LLM) 管理。每个模型关联到一个供应商。" + }, + { + "name": "向量模型", + "description": "向量模型 (Embedding) 管理。每个模型关联到一个供应商。" }, { "name": "机器人", - "description": "机器人实例管理操作" + "description": "机器人实例管理及消息发送" }, { "name": "流水线", - "description": "流水线配置管理操作" + "description": "流水线（Pipeline）配置管理" }, { "name": "知识库", - "description": "内置知识库管理操作" + "description": "知识库管理操作" + }, + { + "name": "知识引擎", + "description": "知识引擎（插件提供）的查询" + }, + { + "name": "解析器", + "description": "文件解析器（插件提供）的查询" }, { "name": "文件", - "description": "文件上传和管理操作" + "description": "文件上传操作" }, { "name": "插件", - "description": "插件安装和管理操作" + "description": "插件安装、配置和管理" + }, + { + "name": "系统", + "description": "系统信息（无需认证）" } ], "security": [ @@ -58,45 +74,64 @@ } ], "paths": { - "/api/v1/provider/models/llm": { + "/api/v1/system/info": { "get": { - "tags": [ - "模型 - 大语言模型" - ], - "summary": "列出所有大语言模型", - "description": "获取所有已配置的大语言模型列表", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["系统"], + "summary": "获取系统信息", + "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。", + "security": [], "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "models": { + "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/LLMModel" - } + "items": { "$ref": "#/components/schemas/ModelProvider" } } } } @@ -104,59 +139,156 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { - "tags": [ - "模型 - 大语言模型" + "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" } + } ], - "summary": "创建新的大语言模型", - "description": "创建并配置一个新的大语言模型", - "security": [ - { - "ApiKeyAuth": [] + "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": [ { - "BearerAuth": [] + "name": "provider_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/LLMModelCreate" - } + "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": "模型创建成功", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "uuid": { - "type": "string", - "format": "uuid", - "example": "550e8400-e29b-41d4-a716-446655440000" + "models": { + "type": "array", + "items": { "$ref": "#/components/schemas/LLMModel" } } } } @@ -164,58 +296,69 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" + } + } + }, + "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": "获取指定的大语言模型", - "description": "通过 UUID 获取指定大语言模型的详细信息", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["大语言模型"], + "summary": "获取单个 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "model": { - "$ref": "#/components/schemas/LLMModel" - } + "model": { "$ref": "#/components/schemas/LLMModel" } } } } @@ -223,119 +366,59 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { - "tags": [ - "模型 - 大语言模型" - ], - "summary": "更新大语言模型", - "description": "更新现有大语言模型的配置", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["大语言模型"], + "summary": "更新 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/LLMModelUpdate" - } + "schema": { "$ref": "#/components/schemas/LLMModelUpdate" } } } }, "responses": { - "200": { - "description": "模型更新成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } }, "delete": { - "tags": [ - "模型 - 大语言模型" - ], - "summary": "删除大语言模型", - "description": "从系统中删除一个大语言模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["大语言模型"], + "summary": "删除 LLM 模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "responses": { - "200": { - "description": "模型删除成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { - "tags": [ - "模型 - 大语言模型" - ], - "summary": "测试大语言模型", - "description": "测试大语言模型的连接性和功能", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["大语言模型"], + "summary": "测试 LLM 模型", + "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -344,73 +427,51 @@ "application/json": { "schema": { "type": "object", - "description": "要测试的模型配置" + "properties": { + "prompt": { + "type": "string", + "description": "测试用的提示文本", + "example": "Hello" + } + } } } } }, "responses": { - "200": { - "description": "模型测试成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - } + "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/embedding": { "get": { - "tags": [ - "模型 - 向量模型" - ], - "summary": "列出所有向量模型", - "description": "获取所有已配置的向量模型列表", - "security": [ + "tags": ["向量模型"], + "summary": "获取所有向量模型", + "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。", + "parameters": [ { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] + "name": "provider_uuid", + "in": "query", + "required": false, + "schema": { "type": "string", "format": "uuid" }, + "description": "按供应商 UUID 过滤" } ], "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "models": { "type": "array", - "items": { - "$ref": "#/components/schemas/EmbeddingModel" - } + "items": { "$ref": "#/components/schemas/EmbeddingModel" } } } } @@ -418,113 +479,69 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { - "tags": [ - "模型 - 向量模型" - ], - "summary": "创建新的向量模型", - "description": "创建并配置一个新的向量模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["向量模型"], + "summary": "创建向量模型", + "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/EmbeddingModelCreate" - } + "schema": { "$ref": "#/components/schemas/EmbeddingModelCreate" } } } }, "responses": { "200": { - "description": "模型创建成功", + "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "uuid": { - "type": "string", - "format": "uuid" - } + "uuid": { "type": "string", "format": "uuid" } } } } } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/provider/models/embedding/{model_uuid}": { "get": { - "tags": [ - "模型 - 向量模型" - ], - "summary": "获取指定的向量模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["向量模型"], + "summary": "获取单个向量模型", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "model": { - "$ref": "#/components/schemas/EmbeddingModel" - } + "model": { "$ref": "#/components/schemas/EmbeddingModel" } } } } @@ -532,116 +549,59 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { - "tags": [ - "模型 - 向量模型" - ], + "tags": ["向量模型"], "summary": "更新向量模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/EmbeddingModelUpdate" - } + "schema": { "$ref": "#/components/schemas/EmbeddingModelUpdate" } } } }, "responses": { - "200": { - "description": "模型更新成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } }, "delete": { - "tags": [ - "模型 - 向量模型" - ], + "tags": ["向量模型"], "summary": "删除向量模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "responses": { - "200": { - "description": "模型删除成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { - "tags": [ - "模型 - 向量模型" - ], + "tags": ["向量模型"], "summary": "测试向量模型", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "description": "向指定的向量模型发送测试请求，验证模型是否可用。", "parameters": [ { - "$ref": "#/components/parameters/ModelUUID" + "name": "model_uuid", + "in": "path", + "required": true, + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -649,70 +609,42 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "测试用的文本", + "example": "Hello" + } + } } } } }, "responses": { - "200": { - "description": "模型测试成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/platform/bots": { "get": { - "tags": [ - "机器人" - ], - "summary": "列出所有机器人", - "description": "获取所有已配置的机器人实例列表", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["机器人"], + "summary": "获取所有机器人", "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "bots": { "type": "array", - "items": { - "$ref": "#/components/schemas/Bot" - } + "items": { "$ref": "#/components/schemas/Bot" } } } } @@ -720,121 +652,69 @@ } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { - "tags": [ - "机器人" - ], - "summary": "创建新的机器人", - "description": "创建并配置一个新的机器人实例", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["机器人"], + "summary": "创建机器人", "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/BotCreate" - } + "schema": { "$ref": "#/components/schemas/BotCreate" } } } }, "responses": { "200": { - "description": "机器人创建成功", + "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "uuid": { - "type": "string", - "format": "uuid" - } + "uuid": { "type": "string", "format": "uuid" } } } } } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/platform/bots/{bot_uuid}": { "get": { - "tags": [ - "机器人" - ], - "summary": "获取指定的机器人", - "description": "获取指定机器人实例的详细信息", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "tags": ["机器人"], + "summary": "获取单个机器人", + "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { - "type": "string", - "format": "uuid" - }, - "description": "机器人 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "bot": { - "$ref": "#/components/schemas/Bot" - } + "bot": { "$ref": "#/components/schemas/Bot" } } } } @@ -842,137 +722,59 @@ } } }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { - "tags": [ - "机器人" - ], + "tags": ["机器人"], "summary": "更新机器人", - "description": "更新现有机器人实例的配置", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { - "type": "string", - "format": "uuid" - } + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/BotUpdate" - } + "schema": { "$ref": "#/components/schemas/BotUpdate" } } } }, "responses": { - "200": { - "description": "机器人更新成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } }, "delete": { - "tags": [ - "机器人" - ], + "tags": ["机器人"], "summary": "删除机器人", - "description": "从系统中删除一个机器人实例", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { - "type": "string", - "format": "uuid" - } + "schema": { "type": "string", "format": "uuid" } } ], "responses": { - "200": { - "description": "机器人删除成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } + "200": { "$ref": "#/components/responses/Success" } } } }, "/api/v1/platform/bots/{bot_uuid}/logs": { "post": { - "tags": [ - "机器人" - ], + "tags": ["机器人"], "summary": "获取机器人事件日志", - "description": "获取指定机器人的事件日志", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], + "description": "获取指定机器人的事件日志记录。", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { - "type": "string", - "format": "uuid" - } + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -984,13 +786,13 @@ "properties": { "from_index": { "type": "integer", - "default": -1, - "description": "日志起始索引（-1 表示最新）" + "description": "起始索引（-1 表示从最新开始）", + "default": -1 }, "max_count": { "type": "integer", - "default": 10, - "description": "要获取的最大日志数量" + "description": "最大返回数量", + "default": 10 } } } @@ -999,523 +801,40 @@ }, "responses": { "200": { - "description": "成功响应", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "logs": { - "type": "array", - "items": { - "type": "object" - } - }, - "total_count": { - "type": "integer" - } + "logs": { "type": "array", "items": { "type": "object" } }, + "total_count": { "type": "integer" } } } } } } } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - } - } - } - }, - "/api/v1/pipelines": { - "get": { - "tags": [ - "流水线" - ], - "summary": "列出所有流水线", - "description": "获取所有已配置的流水线列表", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "name": "sort_by", - "in": "query", - "schema": { - "type": "string", - "default": "created_at" - }, - "description": "排序字段" - }, - { - "name": "sort_order", - "in": "query", - "schema": { - "type": "string", - "enum": [ - "ASC", - "DESC" - ], - "default": "DESC" - }, - "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": { - "pipelines": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pipeline" - } - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - } - } - }, - "post": { - "tags": [ - "流水线" - ], - "summary": "创建新的流水线", - "description": "创建并配置一个新的流水线", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "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 - }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "properties": { - "uuid": { - "type": "string", - "format": "uuid" - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - } - } - } - }, - "/api/v1/pipelines/_/metadata": { - "get": { - "tags": [ - "流水线" - ], - "summary": "获取流水线元数据", - "description": "获取流水线的元数据和配置选项", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "responses": { - "200": { - "description": "成功响应", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "properties": { - "configs": { - "type": "object" - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - } - } - } - }, - "/api/v1/pipelines/{pipeline_uuid}": { - "get": { - "tags": [ - "流水线" - ], - "summary": "获取指定的流水线", - "description": "获取指定流水线的详细信息", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "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 - }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "properties": { - "pipeline": { - "$ref": "#/components/schemas/Pipeline" - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - }, - "put": { - "tags": [ - "流水线" - ], - "summary": "更新流水线", - "description": "更新现有流水线的配置", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "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": { - "description": "流水线更新成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - }, - "delete": { - "tags": [ - "流水线" - ], - "summary": "删除流水线", - "description": "从系统中删除一个流水线", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "name": "pipeline_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "200": { - "description": "流水线删除成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - } - }, - "/api/v1/pipelines/{pipeline_uuid}/extensions": { - "get": { - "tags": [ - "流水线" - ], - "summary": "获取流水线扩展", - "description": "获取流水线配置的扩展和插件", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "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 - }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - } - } - }, - "put": { - "tags": [ - "流水线" - ], - "summary": "更新流水线扩展", - "description": "更新流水线的扩展配置", - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "name": "pipeline_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "responses": { - "200": { - "description": "扩展更新成功", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuccessResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/platform/bots/{bot_uuid}/send_message": { "post": { - "tags": [ - "机器人" - ], - "summary": "发送消息", - "description": "通过指定机器人向指定目标发送消息", - "operationId": "sendMessage", + "tags": ["机器人"], + "summary": "通过机器人发送消息", + "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。", + "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "机器人 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -1524,18 +843,11 @@ "application/json": { "schema": { "type": "object", - "required": [ - "target_type", - "target_id", - "message_chain" - ], + "required": ["target_type", "target_id", "message_chain"], "properties": { "target_type": { "type": "string", - "enum": [ - "person", - "group" - ], + "enum": ["person", "group"], "description": "目标类型" }, "target_id": { @@ -1544,39 +856,31 @@ }, "message_chain": { "type": "array", + "description": "消息链", "items": { - "type": "object" + "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 类型）" + } + } }, - "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" - } + "example": [ + { "type": "Plain", "text": "Hello, World!" } ] } } @@ -1592,21 +896,11 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "sent": { - "type": "boolean", - "example": true - } + "sent": { "type": "boolean", "example": true } } } } @@ -1615,61 +909,34 @@ } }, "400": { - "description": "请求参数错误", + "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" - } - } - } + "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } - }, - "security": [ - { - "ApiKeyAuth": [] - } - ] + } } }, - "/api/v1/knowledge/bases": { + "/api/v1/pipelines": { "get": { - "tags": [ - "知识库" + "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" } + } ], - "summary": "获取所有知识库", - "description": "获取所有内置知识库列表", - "operationId": "listKnowledgeBases", "responses": { "200": { "description": "成功", @@ -1678,22 +945,13 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "bases": { + "pipelines": { "type": "array", - "items": { - "type": "object" - } + "items": { "$ref": "#/components/schemas/Pipeline" } } } } @@ -1702,52 +960,297 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { - "tags": [ - "知识库" + "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" } + } ], - "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" + "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" } } + } + } } } - }, - "example": { - "name": "技术文档库", - "description": "存储技术文档和API参考", - "embedding_model_uuid": "uuid-of-embedding-model" + } + } + } + } + }, + "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": "引擎创建参数" } + } } } } @@ -1760,20 +1263,11 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "uuid": { - "type": "string" - } + "uuid": { "type": "string", "format": "uuid" } } } } @@ -1781,34 +1275,19 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}": { "get": { - "tags": [ - "知识库" - ], - "summary": "获取知识库详情", - "description": "获取指定知识库的详细信息", - "operationId": "getKnowledgeBase", + "tags": ["知识库"], + "summary": "获取单个知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "responses": { @@ -1819,20 +1298,11 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "base": { - "type": "object" - } + "base": { "type": "object" } } } } @@ -1840,52 +1310,18 @@ } } }, - "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": [] - } - ] + "404": { "$ref": "#/components/responses/NotFound" } + } }, "put": { - "tags": [ - "知识库" - ], + "tags": ["知识库"], "summary": "更新知识库", - "description": "更新知识库信息", - "operationId": "updateKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -1895,121 +1331,43 @@ "schema": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" - } + "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": [] - } - ] + "200": { "$ref": "#/components/responses/Success" } + } }, "delete": { - "tags": [ - "知识库" - ], + "tags": ["知识库"], "summary": "删除知识库", - "description": "删除指定的知识库", - "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "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": [] - } - ] + "200": { "$ref": "#/components/responses/Success" } + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { "get": { - "tags": [ - "知识库" - ], + "tags": ["知识库"], "summary": "获取知识库文件列表", - "description": "获取指定知识库中的所有文件", - "operationId": "listKnowledgeBaseFiles", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "responses": { @@ -2020,23 +1378,11 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "files": { - "type": "array", - "items": { - "type": "object" - } - } + "files": { "type": "array", "items": { "type": "object" } } } } } @@ -2044,32 +1390,18 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } }, "post": { - "tags": [ - "知识库" - ], - "summary": "添加文件到知识库", - "description": "将已上传的文件添加到知识库进行处理", - "operationId": "addFileToKnowledgeBase", + "tags": ["知识库"], + "summary": "将文件存入知识库", + "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -2078,45 +1410,28 @@ "application/json": { "schema": { "type": "object", - "required": [ - "file_id" - ], + "required": ["file_id"], "properties": { - "file_id": { - "type": "string", - "description": "文件 ID（从文件上传接口获取）" - } + "file_id": { "type": "string", "description": "已上传的文件 ID" }, + "parser_plugin_id": { "type": "string", "description": "指定的解析器插件 ID（可选）" } } - }, - "example": { - "file_id": "document_abc123.pdf" } } } }, "responses": { "200": { - "description": "添加成功", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "task_id": { - "type": "string", - "description": "处理任务 ID" - } + "task_id": { "type": "string" } } } } @@ -2124,97 +1439,43 @@ } } } - }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { "delete": { - "tags": [ - "知识库" - ], + "tags": ["知识库"], "summary": "从知识库删除文件", - "description": "从指定知识库中删除文件", - "operationId": "deleteFileFromKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } }, { "name": "file_id", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "文件 ID" + "schema": { "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": [] - } - ] + "200": { "$ref": "#/components/responses/Success" } + } } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { "post": { - "tags": [ - "知识库" - ], + "tags": ["知识库"], "summary": "检索知识库", - "description": "在知识库中搜索相关知识", - "operationId": "retrieveKnowledge", + "description": "对知识库进行语义检索，返回相关文档片段。", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "知识库 UUID" + "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { @@ -2223,48 +1484,14 @@ "application/json": { "schema": { "type": "object", - "required": [ - "query" - ], + "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" - } - } - } + "query": { "type": "string", "description": "检索查询文本" }, + "retrieval_settings": { + "type": "object", + "description": "检索参数（如 top_k 等）", + "properties": { + "top_k": { "type": "integer" } } } } @@ -2272,33 +1499,180 @@ } } }, - "security": [ - { - "ApiKeyAuth": [] - }, - { - "BearerAuth": [] + "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": [ - "文件" - ], + "tags": ["文件"], "summary": "上传图片", - "description": "上传图片文件（支持 jpg, jpeg, png, gif, webp 格式，最大 10MB）", - "operationId": "uploadImage", + "description": "上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": [ - "file" - ], + "required": ["file"], "properties": { "file": { "type": "string", @@ -2318,20 +1692,13 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "file_key": { "type": "string", - "description": "文件密钥" + "description": "文件标识符，可用于引用图片" } } } @@ -2340,31 +1707,21 @@ } } } - }, - "security": [ - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/files/documents": { "post": { - "tags": [ - "文件" - ], + "tags": ["文件"], "summary": "上传文档", - "description": "上传文档文件（最大 10MB）", - "operationId": "uploadDocument", + "description": "上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": [ - "file" - ], + "required": ["file"], "properties": { "file": { "type": "string", @@ -2384,20 +1741,13 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { "file_id": { "type": "string", - "description": "文件 ID" + "description": "文件 ID，可用于知识库关联" } } } @@ -2406,22 +1756,13 @@ } } } - }, - "security": [ - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/plugins": { "get": { - "tags": [ - "插件" - ], - "summary": "获取所有插件", - "description": "获取已安装的所有插件列表", - "operationId": "listPlugins", + "tags": ["插件"], + "summary": "获取已安装插件列表", "responses": { "200": { "description": "成功", @@ -2430,23 +1771,11 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "plugins": { - "type": "array", - "items": { - "type": "object" - } - } + "plugins": { "type": "array", "items": { "type": "object" } } } } } @@ -2454,40 +1783,25 @@ } } } - }, - "security": [ - { - "BearerAuth": [] - } - ] + } } }, "/api/v1/plugins/{author}/{plugin_name}": { "get": { - "tags": [ - "插件" - ], + "tags": ["插件"], "summary": "获取插件详情", - "description": "获取指定插件的详细信息", - "operationId": "getPlugin", "parameters": [ { "name": "author", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "插件作者" + "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "插件名称" + "schema": { "type": "string" } } ], "responses": { @@ -2498,93 +1812,59 @@ "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "plugin": { - "type": "object" - } + "plugin": { "type": "object" } } } } } } } - } - }, - "security": [ - { - "BearerAuth": [] - } - ] + }, + "404": { "$ref": "#/components/responses/NotFound" } + } }, "delete": { - "tags": [ - "插件" - ], + "tags": ["插件"], "summary": "删除插件", - "description": "卸载指定的插件", - "operationId": "deletePlugin", + "description": "异步删除插件，返回任务 ID。", "parameters": [ { "name": "author", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "插件作者" + "schema": { "type": "string" } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { - "type": "string" - }, - "description": "插件名称" + "schema": { "type": "string" } }, { "name": "delete_data", "in": "query", "required": false, - "schema": { - "type": "boolean", - "default": false - }, - "description": "是否删除插件数据" + "schema": { "type": "boolean", "default": false }, + "description": "是否同时删除插件数据" } ], "responses": { "200": { - "description": "删除任务已创建", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "task_id": { - "type": "string" - } + "task_id": { "type": "integer" } } } } @@ -2592,64 +1872,41 @@ } } } - }, - "security": [ - { - "BearerAuth": [] - } - ] + } } }, - "/api/v1/plugins/install/local": { + "/api/v1/plugins/{author}/{plugin_name}/upgrade": { "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 格式）" - } - } - } - } + "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": "安装任务已创建", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "task_id": { - "type": "string" - } + "task_id": { "type": "integer" } } } } @@ -2657,108 +1914,95 @@ } } } - }, - "security": [ - { - "BearerAuth": [] - } - ] + } } }, - "/api/v1/plugins/install/github": { - "post": { - "tags": [ - "插件" + "/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" } + } ], - "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 标签" - } - } + "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": [] - } - ] + "200": { "$ref": "#/components/responses/Success" } + } } }, "/api/v1/plugins/install/marketplace": { "post": { - "tags": [ - "插件" - ], - "summary": "从插件市场安装", - "description": "从 LangBot 插件市场安装插件", - "operationId": "installPluginMarketplace", + "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": "插件 ID" + "description": "Marketplace 插件 ID（author/name 格式）", + "example": "kellz-dev/disaster-alert" } } } @@ -2767,26 +2011,17 @@ }, "responses": { "200": { - "description": "安装任务已创建", + "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, + "code": { "type": "integer", "example": 0 }, "data": { "type": "object", "properties": { - "task_id": { - "type": "string" - } + "task_id": { "type": "integer" } } } } @@ -2794,12 +2029,53 @@ } } } - }, - "security": [ - { - "BearerAuth": [] + } + } + }, + "/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" } + } + } + } + } + } + } + } + } } } }, @@ -2808,452 +2084,281 @@ "ApiKeyAuth": { "type": "apiKey", "in": "header", - "name": "X-API-Key", - "description": "使用 X-API-Key 请求头进行 API 密钥认证。\n示例：`X-API-Key: lbk_your_api_key_here`\n" + "name": "X-API-Key" }, "BearerAuth": { "type": "http", - "scheme": "bearer", - "description": "Bearer 令牌认证。可以是用户 JWT 令牌或 API 密钥。\n示例：`Authorization: Bearer `\n" - } - }, - "parameters": { - "ModelUUID": { - "name": "model_uuid", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - }, - "description": "模型 UUID" + "scheme": "bearer" } }, "schemas": { - "LLMModel": { + "ModelProvider": { "type": "object", + "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。", "properties": { - "uuid": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string", - "example": "GPT-4" - }, - "description": { - "type": "string", - "example": "OpenAI GPT-4 model" - }, + "uuid": { "type": "string", "format": "uuid" }, + "name": { "type": "string", "example": "OpenAI" }, "requester": { "type": "string", + "description": "请求器类型", "example": "openai-chat-completions" }, - "requester_config": { - "type": "object", - "properties": { - "model": { - "type": "string", - "example": "gpt-4" - }, - "args": { - "type": "object" - } - } + "base_url": { + "type": "string", + "description": "API 基础地址", + "example": "https://api.openai.com/v1" }, "api_keys": { "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "keys": { - "type": "array", - "items": { - "type": "string" - } - } - } - } + "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" - }, - "example": [ - "chat", - "vision" - ] + "items": { "type": "string" }, + "description": "模型能力标签", + "example": ["chat", "vision", "tool-use"] }, "extra_args": { - "type": "object" + "type": "object", + "description": "额外参数（如 temperature、max_tokens 等）" }, - "created_at": { - "type": "string", - "format": "date-time" + "prefered_ranking": { + "type": "integer", + "description": "优先级排序（越大越优先）", + "default": 0 }, - "updated_at": { - "type": "string", - "format": "date-time" - } + "created_at": { "type": "string", "format": "date-time" }, + "updated_at": { "type": "string", "format": "date-time" } } }, "LLMModelCreate": { "type": "object", - "required": [ - "name", - "requester", - "requester_config", - "api_keys" - ], + "required": ["name", "provider_uuid"], "properties": { "name": { - "type": "string" + "type": "string", + "description": "模型名称（即模型 ID）", + "example": "gpt-4o" }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } + "provider_uuid": { + "type": "string", + "format": "uuid", + "description": "关联的供应商 UUID" }, "abilities": { "type": "array", - "items": { - "type": "string" - } + "items": { "type": "string" }, + "example": ["chat", "vision"] }, - "extra_args": { - "type": "object" - } + "extra_args": { "type": "object" }, + "prefered_ranking": { "type": "integer", "default": 0 } } }, "LLMModelUpdate": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } - }, + "name": { "type": "string" }, + "provider_uuid": { "type": "string", "format": "uuid" }, "abilities": { "type": "array", - "items": { - "type": "string" - } + "items": { "type": "string" } }, - "extra_args": { - "type": "object" - } + "extra_args": { "type": "object" }, + "prefered_ranking": { "type": "integer" } } }, "EmbeddingModel": { "type": "object", + "description": "向量模型。通过 provider_uuid 关联到供应商。", "properties": { - "uuid": { - "type": "string", - "format": "uuid" - }, + "uuid": { "type": "string", "format": "uuid" }, "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } - }, - "extra_args": { - "type": "object" - }, - "created_at": { "type": "string", - "format": "date-time" + "description": "模型名称（即模型 ID）", + "example": "text-embedding-3-small" }, - "updated_at": { + "provider_uuid": { "type": "string", - "format": "date-time" - } + "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", - "requester", - "requester_config", - "api_keys" - ], + "required": ["name", "provider_uuid"], "properties": { "name": { - "type": "string" + "type": "string", + "example": "text-embedding-3-small" }, - "description": { - "type": "string" + "provider_uuid": { + "type": "string", + "format": "uuid" }, - "requester": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } - }, - "extra_args": { - "type": "object" - } + "extra_args": { "type": "object" }, + "prefered_ranking": { "type": "integer", "default": 0 } } }, "EmbeddingModelUpdate": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "requester_config": { - "type": "object" - }, - "api_keys": { - "type": "array", - "items": { - "type": "object" - } - }, - "extra_args": { - "type": "object" - } + "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" - } + "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" - ], + "required": ["name", "adapter", "config"], "properties": { - "name": { - "type": "string" - }, - "adapter": { - "type": "string" - }, - "config": { - "type": "object" - } + "name": { "type": "string" }, + "adapter": { "type": "string" }, + "config": { "type": "object" } } }, "BotUpdate": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "config": { - "type": "object" - } + "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" - } + "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", - "config" - ], + "required": ["name"], "properties": { - "name": { - "type": "string" - }, - "config": { - "type": "object" - } + "name": { "type": "string" }, + "config": { "type": "object" } } }, "PipelineUpdate": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "config": { - "type": "object" - } - } - }, - "SuccessResponse": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "example": 0 - }, - "msg": { - "type": "string", - "example": "ok" - }, - "data": { - "type": "object", - "nullable": true - } + "name": { "type": "string" }, + "config": { "type": "object" }, + "is_default": { "type": "boolean" } } }, "ErrorResponse": { "type": "object", "properties": { - "code": { - "type": "integer", - "example": -1 - }, - "msg": { - "type": "string", - "example": "错误消息" - } + "code": { "type": "integer", "example": -1 }, + "msg": { "type": "string" } } } }, "responses": { - "UnauthorizedError": { - "description": "需要认证或凭据无效", + "Success": { + "description": "操作成功", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "examples": { - "no_auth": { - "value": { - "code": -1, - "msg": "未提供有效认证（需要用户令牌或 API 密钥）" - } - }, - "invalid_key": { - "value": { - "code": -1, - "msg": "无效的 API 密钥" - } + "type": "object", + "properties": { + "code": { "type": "integer", "example": 0 } } } } } }, - "NotFoundError": { + "NotFound": { "description": "资源未找到", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -1, - "msg": "资源未找到" - } - } - } - }, - "InternalServerError": { - "description": "内部服务器错误", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - }, - "example": { - "code": -2, - "msg": "内部服务器错误" - } + "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } -} \ No newline at end of file +} diff --git a/zh/tags/readme.mdx b/zh/tags/readme.mdx index 2df01f875..f3dc47b9b 100644 --- a/zh/tags/readme.mdx +++ b/zh/tags/readme.mdx @@ -2,7 +2,7 @@ title: "Service API 概述" --- -LangBot 提供了一套供外部服务使用的 API 接口，便于集成。这些接口以 API Key 鉴权，是目前 HTTP API 的子集。要查看前后端通信的 API 文档，请前往[开发](/zh/develop/dev-config)部分。 +LangBot 提供了一套供外部服务使用的 RESTful API 接口，便于集成和自动化管理。这些接口以 API Key 鉴权，是目前 HTTP API 的子集。 Service API 目前处于 Beta 阶段，部分接口可能会频繁变动。 @@ -10,7 +10,7 @@ Service API 目前处于 Beta 阶段，部分接口可能会频繁变动。 ## 获取 API Key -点击 WebUI 侧栏的`API Keys`按钮，创建一个 API Key。 +点击 WebUI 侧栏的 `API Keys` 按钮，创建一个 API Key。 ![create_api_key](/images/zh/api/create_api_key.png) @@ -18,6 +18,45 @@ Service API 目前处于 Beta 阶段，部分接口可能会频繁变动。 ![copy_api_key](/images/zh/api/copy_api_key.png) +## 认证方式 + +所有 Service API 都支持以下两种认证方式： + +- **API Key**：通过请求头 `X-API-Key: ` 或 `Authorization: Bearer ` 传递 +- **用户令牌**：通过请求头 `Authorization: Bearer ` 传递（登录后获取） + ## 使用 API -左侧列出了所有可用的 API，您可以填入您的实例地址（后端开放的端口地址，默认为 `http://localhost:5300`）和 API Key，然后点击`Try it out`按钮即可调用 API。 +左侧列出了所有可用的 API，您可以填入您的实例地址（后端开放的端口地址，默认为 `http://localhost:5300`）和 API Key，然后点击 `Try it out` 按钮即可调用 API。 + +## 核心概念 + +### Provider + Model 架构 + +LangBot 采用 **供应商（Provider）+ 模型（Model）** 的两层架构来管理 AI 模型： + +- **供应商（Provider）**：定义 API 地址（base_url）、请求器类型（requester）和 API 密钥（api_keys）。一个供应商可以关联多个模型。 +- **模型（Model）**：关联到一个供应商（通过 `provider_uuid`），定义具体的模型名称和参数。模型继承供应商的 API 地址和密钥。 + +``` +Provider (OpenAI) +├── base_url: https://api.openai.com/v1 +├── api_keys: [sk-xxx] +├── LLM: gpt-4o +├── LLM: gpt-4o-mini +└── Embedding: text-embedding-3-small +``` + +这种架构允许您在同一供应商下管理多个模型，共享 API 配置，避免重复填写密钥。 + +### 请求器（Requester） + +请求器定义了与 AI 服务通信的协议。可通过 `GET /api/v1/provider/requesters` 获取可用请求器列表。常见的请求器包括： + +- `openai-chat-completions` — OpenAI 兼容的聊天补全 API（也适用于国内服务商如硅基流动、DeepSeek 等） +- `anthropic-messages` — Anthropic Claude API +- `openai-embeddings` — OpenAI 兼容的向量嵌入 API + +### 异步任务 + +部分操作（插件安装/删除/升级）为异步执行，接口返回 `task_id`。可通过 WebUI 查看任务进度。 diff --git a/zh/usage/models/readme.mdx b/zh/usage/models/readme.mdx index 75fcee660..bd0622f2c 100644 --- a/zh/usage/models/readme.mdx +++ b/zh/usage/models/readme.mdx @@ -12,7 +12,23 @@ LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Sp ## 自定义模型 -您也可以添加其他来源的模型。 +您也可以添加其他来源的模型。LangBot 采用 **供应商（Provider）+ 模型（Model）** 的两层架构： + +- **供应商**：定义 API 地址（Base URL）和 API 密钥。同一供应商下的所有模型共享这些配置。 +- **模型**：关联到一个供应商，指定具体的模型名称和能力。 + +``` +供应商 (OpenAI) +├── Base URL: https://api.openai.com/v1 +├── API Keys: [sk-xxx] +├── LLM 模型: gpt-4o +├── LLM 模型: gpt-4o-mini +└── 向量模型: text-embedding-3-small +``` + + +同一供应商下可以添加多个模型，它们会自动继承供应商的 API 地址和密钥，无需重复填写。 + ### 对话模型 (LLM Model) @@ -20,16 +36,15 @@ LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Sp ![arch](/images/zh/deploy/models/arch.png) -可以添加多个模型，然后再流水线中选择具体使用什么模型 +可以添加多个模型，然后在流水线中选择具体使用什么模型。 model_config -填入这四个参数`模型名称`、`模型供应商`、`请求 URL`、`API Key`，然后提交即可 +填入 `模型名称`、选择 `模型供应商`（或新建供应商并填入 `请求 URL` 和 `API Key`），然后提交即可。 模型能力方面，请根据具体模型特性来选择： - 视觉能力：需要启用才可以识图 - - 函数调用：需要启用才可以在对话中使用 Agent 工具 ### 嵌入模型 (Embedding Model) @@ -38,7 +53,7 @@ LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Sp embedding_model -填入这四个参数`模型名称`、`模型供应商`、`请求 URL`、`API Key`，然后提交即可，之后请在知识库中配置使用此模型。 +填入 `模型名称`、选择 `模型供应商`，然后提交即可。之后请在知识库中配置使用此模型。 ### 使用 seekdb 内置嵌入模型（零配置） 系统已集成 seekdb 提供的官方嵌入模型，无需填写任何参数。