diff --git a/en/plugin/dev/apis/common.mdx b/en/plugin/dev/apis/common.mdx index 2a04140c8..3cb5abd1e 100644 --- a/en/plugin/dev/apis/common.mdx +++ b/en/plugin/dev/apis/common.mdx @@ -249,6 +249,87 @@ parsers = await self.plugin.list_parsers(mime_type="application/pdf") # Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types ``` +### List All Available Tools + +List all available tools in the current LangBot instance (including plugin tools and MCP tools). + +```python +async def list_tools(self) -> list[dict[str, Any]]: + """List all available tools + + Returns: + A list of tool dicts, each containing: + - name: Tool name + - label: Display label (i18n) + - description: Tool description (i18n) + - icon: Tool icon + - spec: Tool specification (includes llm_prompt and parameters) + """ + +# Example +tools = await self.plugin.list_tools() +for tool in tools: + print(f"Tool: {tool['name']}") +``` + +### Get Tool Detail + +Get detailed information about a specific tool. + +```python +async def get_tool_detail(self, tool_name: str) -> dict[str, Any]: + """Get detailed information about a specific tool + + Args: + tool_name: Tool name (metadata.name, e.g. "get_weather_alerts") + + Returns: + Tool detail dict containing name, label, description, spec (with parameters and llm_prompt) + """ + +# Example +detail = await self.plugin.get_tool_detail("get_weather_alerts") +print(detail['spec']['parameters']) +``` + +### Call Tool + +Call a specific tool. + +```python +async def call_tool( + self, + tool_name: str, + parameters: dict[str, Any], + session: dict[str, Any], + query_id: int, +) -> dict[str, Any]: + """Call a specific tool + + Args: + tool_name: Tool name (metadata.name) + parameters: Tool parameters + session: Session info + query_id: Query ID + + Returns: + Tool response dict + """ + +# Example +result = await self.plugin.call_tool( + tool_name="get_weather_alerts", + parameters={"state": "CA"}, + session={}, + query_id=0, +) +print(result) +``` + + +Tool names use `metadata.name` (e.g. `echo_tool`, `get_weather_alerts`), without author or plugin name prefix. + + ### Set Plugin Persistent Data Persistently store plugin data. Data stored through this interface can only be accessed by this plugin. Values need to be converted to bytes manually. diff --git a/en/plugin/dev/basic-info.mdx b/en/plugin/dev/basic-info.mdx index 05086758e..e51fc5a3b 100644 --- a/en/plugin/dev/basic-info.mdx +++ b/en/plugin/dev/basic-info.mdx @@ -50,7 +50,7 @@ For example: spec: config: - name: github_token # Required; configuration item name, used for retrieval in the plugin - type: string # Required; configuration item type, supports string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, etc. + type: string # Required; configuration item type, supports string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, tools-selector, etc. label: # Required; configuration item display name, supports multilingual. Language codes follow RFC 4646 standard. en_US: Github Token zh_Hans: Github Token @@ -274,6 +274,33 @@ bot_uuid = self.get_config()['bot'] print(bot_uuid) # Output: '550e8400-e29b-41d4-a716-446655440000' ``` +### type: tools-selector + +Tool selector. Displays a multi-select tool selector where you can choose registered tools (plugin tools and MCP tools), with the final result represented as an array of tool names. + +```yaml +- name: selected_tools + type: tools-selector + ... +``` + +Using the selected tool names in the plugin: + +```python +# Get selected tool names from config +selected_tools = self.get_config()['selected_tools'] +print(selected_tools) # Output: ['get_weather_alerts', 'web_search'] + +# Call selected tools +for tool_name in selected_tools: + result = await self.plugin.call_tool( + tool_name=tool_name, + parameters={"query": "hello"}, + session={}, + query_id=0, + ) +``` + ## What's Next This tutorial will guide you through step-by-step completion of plugin functionality. diff --git a/ja/plugin/dev/apis/common.mdx b/ja/plugin/dev/apis/common.mdx index 499b1a0e8..7d6d88d0d 100644 --- a/ja/plugin/dev/apis/common.mdx +++ b/ja/plugin/dev/apis/common.mdx @@ -249,6 +249,87 @@ parsers = await self.plugin.list_parsers(mime_type="application/pdf") # 各要素には plugin_id、plugin_author、plugin_name、name、description、supported_mime_types が含まれます ``` +### 利用可能なツール一覧を取得 + +現在の LangBot インスタンスで利用可能なすべてのツール（プラグインツールおよび MCP ツール）を取得します。 + +```python +async def list_tools(self) -> list[dict[str, Any]]: + """利用可能なすべてのツールを取得 + + Returns: + ツールのリスト。各要素に以下が含まれます： + - name: ツール名 + - label: 表示名（多言語） + - description: ツールの説明（多言語） + - icon: ツールアイコン + - spec: ツール仕様（llm_prompt と parameters を含む） + """ + +# 使用例 +tools = await self.plugin.list_tools() +for tool in tools: + print(f"Tool: {tool['name']}") +``` + +### ツール詳細を取得 + +特定のツールの詳細情報を取得します。 + +```python +async def get_tool_detail(self, tool_name: str) -> dict[str, Any]: + """特定のツールの詳細情報を取得 + + Args: + tool_name: ツール名（metadata.name、例: "get_weather_alerts"） + + Returns: + ツール詳細 dict（name、label、description、spec を含む） + """ + +# 使用例 +detail = await self.plugin.get_tool_detail("get_weather_alerts") +print(detail['spec']['parameters']) +``` + +### ツールを呼び出す + +指定されたツールを呼び出します。 + +```python +async def call_tool( + self, + tool_name: str, + parameters: dict[str, Any], + session: dict[str, Any], + query_id: int, +) -> dict[str, Any]: + """特定のツールを呼び出す + + Args: + tool_name: ツール名（metadata.name） + parameters: ツールパラメータ + session: セッション情報 + query_id: クエリ ID + + Returns: + ツールの応答 dict + """ + +# 使用例 +result = await self.plugin.call_tool( + tool_name="get_weather_alerts", + parameters={"state": "CA"}, + session={}, + query_id=0, +) +print(result) +``` + + +ツール名は `metadata.name`（例: `echo_tool`、`get_weather_alerts`）を使用します。作者やプラグイン名のプレフィックスは不要です。 + + ### プラグイン永続データの設定 プラグインデータを永続的に保存します。このインターフェースを通じて保存されたデータは、このプラグインのみがアクセスできます。値は手動でbytesに変換する必要があります。 diff --git a/ja/plugin/dev/basic-info.mdx b/ja/plugin/dev/basic-info.mdx index 80a45a2e4..00426dfdc 100644 --- a/ja/plugin/dev/basic-info.mdx +++ b/ja/plugin/dev/basic-info.mdx @@ -50,7 +50,7 @@ execution: spec: config: - name: github_token # 必須; 設定項目名、プラグイン内での取得に使用 - type: string # 必須; 設定項目タイプ、string、integer、float、boolean、select、prompt-editor、llm-model-selector、bot-selectorなどをサポート + type: string # 必須; 設定項目タイプ、string、integer、float、boolean、select、prompt-editor、llm-model-selector、bot-selector、tools-selectorなどをサポート label: # 必須; 設定項目表示名、多言語サポート。言語コードはRFC 4646標準に従います。 en_US: Github Token zh_Hans: Github Token @@ -274,6 +274,33 @@ bot_uuid = self.get_config()['bot'] print(bot_uuid) # 出力: '550e8400-e29b-41d4-a716-446655440000' ``` +### type: tools-selector + +ツールセレクター。登録済みのツール（プラグインツールおよび MCP ツール）を複数選択できるセレクターを表示します。最終結果はツール名の配列として表現されます。 + +```yaml +- name: selected_tools + type: tools-selector + ... +``` + +プラグインで選択されたツール名を使用する: + +```python +# 設定から選択されたツール名リストを取得 +selected_tools = self.get_config()['selected_tools'] +print(selected_tools) # 出力: ['get_weather_alerts', 'web_search'] + +# 選択されたツールを呼び出す +for tool_name in selected_tools: + result = await self.plugin.call_tool( + tool_name=tool_name, + parameters={"query": "hello"}, + session={}, + query_id=0, + ) +``` + ## 次のステップ このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。 diff --git a/openapi/service-api-en.json b/openapi/service-api-en.json index b9f8cea69..e775076a4 100644 --- a/openapi/service-api-en.json +++ b/openapi/service-api-en.json @@ -2750,6 +2750,113 @@ } } } + }, + "/api/v1/tools": { + "get": { + "tags": [ + "Tools" + ], + "summary": "List all available tools", + "description": "List all available tools in the current LangBot instance, including plugin tools and MCP tools.", + "operationId": "listTools", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tools": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + } + } + } + } + }, + "/api/v1/tools/{tool_name}": { + "get": { + "tags": [ + "Tools" + ], + "summary": "Get tool detail", + "description": "Get detailed information about a specific tool.", + "operationId": "getToolDetail", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "tool_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Tool name" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tool": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + }, + "404": { + "description": "Tool not found" + } + } + } } }, "components": { @@ -3175,6 +3282,46 @@ "type": "string" } } + }, + "ToolSummary": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Tool name" + }, + "label": { + "type": "object", + "description": "Display label (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "description": { + "type": "object", + "description": "Tool description (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "icon": { + "type": "string", + "description": "Tool icon" + }, + "spec": { + "type": "object", + "description": "Tool specification", + "properties": { + "llm_prompt": { + "type": "string" + }, + "parameters": { + "type": "object", + "description": "JSON Schema for tool parameters" + } + } + } + } } }, "responses": { diff --git a/openapi/service-api-ja.json b/openapi/service-api-ja.json index 64c3f55af..8805dcf87 100644 --- a/openapi/service-api-ja.json +++ b/openapi/service-api-ja.json @@ -2750,6 +2750,113 @@ } } } + }, + "/api/v1/tools": { + "get": { + "tags": [ + "ツール" + ], + "summary": "利用可能なツール一覧を取得", + "description": "現在の LangBot インスタンスで利用可能なすべてのツール（プラグインツールおよび MCP ツール）を取得します。", + "operationId": "listTools", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tools": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + } + } + } + } + }, + "/api/v1/tools/{tool_name}": { + "get": { + "tags": [ + "ツール" + ], + "summary": "ツール詳細を取得", + "description": "指定されたツールの詳細情報を取得します。", + "operationId": "getToolDetail", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "tool_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "ツール名" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tool": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + }, + "404": { + "description": "Tool not found" + } + } + } } }, "components": { @@ -3175,6 +3282,46 @@ "type": "string" } } + }, + "ToolSummary": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Tool name" + }, + "label": { + "type": "object", + "description": "Display label (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "description": { + "type": "object", + "description": "Tool description (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "icon": { + "type": "string", + "description": "Tool icon" + }, + "spec": { + "type": "object", + "description": "Tool specification", + "properties": { + "llm_prompt": { + "type": "string" + }, + "parameters": { + "type": "object", + "description": "JSON Schema for tool parameters" + } + } + } + } } }, "responses": { diff --git a/openapi/service-api-zh.json b/openapi/service-api-zh.json index 8f6166c9b..b960eadb6 100644 --- a/openapi/service-api-zh.json +++ b/openapi/service-api-zh.json @@ -76,7 +76,9 @@ "paths": { "/api/v1/system/info": { "get": { - "tags": ["系统"], + "tags": [ + "系统" + ], "summary": "获取系统信息", "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。", "security": [], @@ -88,20 +90,51 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "version": { "type": "string", "example": "v4.9.5" }, - "debug": { "type": "boolean" }, - "edition": { "type": "string", "example": "community" }, - "enable_marketplace": { "type": "boolean" }, - "cloud_service_url": { "type": "string" }, - "allow_modify_login_info": { "type": "boolean" }, - "disable_models_service": { "type": "boolean" }, - "limitation": { "type": "object" }, - "wizard_status": { "type": "string", "enum": ["none", "skipped", "completed"] }, - "wizard_progress": { "type": "object", "nullable": true } + "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 + } } } } @@ -114,7 +147,9 @@ }, "/api/v1/provider/providers": { "get": { - "tags": ["模型供应商"], + "tags": [ + "模型供应商" + ], "summary": "获取所有供应商", "description": "获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。", "responses": { @@ -125,13 +160,18 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { "providers": { "type": "array", - "items": { "$ref": "#/components/schemas/ModelProvider" } + "items": { + "$ref": "#/components/schemas/ModelProvider" + } } } } @@ -143,14 +183,18 @@ } }, "post": { - "tags": ["模型供应商"], + "tags": [ + "模型供应商" + ], "summary": "创建供应商", "description": "创建一个新的模型供应商。", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ModelProviderCreate" } + "schema": { + "$ref": "#/components/schemas/ModelProviderCreate" + } } } }, @@ -162,11 +206,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -179,14 +229,19 @@ }, "/api/v1/provider/providers/{provider_uuid}": { "get": { - "tags": ["模型供应商"], + "tags": [ + "模型供应商" + ], "summary": "获取单个供应商", "parameters": [ { "name": "provider_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -197,11 +252,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "provider": { "$ref": "#/components/schemas/ModelProvider" } + "provider": { + "$ref": "#/components/schemas/ModelProvider" + } } } } @@ -209,34 +269,47 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["模型供应商"], + "tags": [ + "模型供应商" + ], "summary": "更新供应商", "parameters": [ { "name": "provider_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/ModelProviderUpdate" } + "schema": { + "$ref": "#/components/schemas/ModelProviderUpdate" + } } } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["模型供应商"], + "tags": [ + "模型供应商" + ], "summary": "删除供应商", "description": "删除供应商。如果还有模型引用该供应商，则无法删除。", "parameters": [ @@ -244,16 +317,23 @@ "name": "provider_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" }, + "200": { + "$ref": "#/components/responses/Success" + }, "400": { "description": "供应商仍有模型引用，无法删除", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } } } } @@ -262,7 +342,9 @@ }, "/api/v1/provider/models/llm": { "get": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "获取所有 LLM 模型", "description": "获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。", "parameters": [ @@ -270,7 +352,10 @@ "name": "provider_uuid", "in": "query", "required": false, - "schema": { "type": "string", "format": "uuid" }, + "schema": { + "type": "string", + "format": "uuid" + }, "description": "按供应商 UUID 过滤" } ], @@ -282,13 +367,18 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { "models": { "type": "array", - "items": { "$ref": "#/components/schemas/LLMModel" } + "items": { + "$ref": "#/components/schemas/LLMModel" + } } } } @@ -300,14 +390,18 @@ } }, "post": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "创建 LLM 模型", "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/LLMModelCreate" } + "schema": { + "$ref": "#/components/schemas/LLMModelCreate" + } } } }, @@ -319,11 +413,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -336,14 +436,19 @@ }, "/api/v1/provider/models/llm/{model_uuid}": { "get": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "获取单个 LLM 模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -354,11 +459,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "model": { "$ref": "#/components/schemas/LLMModel" } + "model": { + "$ref": "#/components/schemas/LLMModel" + } } } } @@ -366,51 +476,71 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "更新 LLM 模型", "parameters": [ { "name": "model_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/LLMModelUpdate" } + "schema": { + "$ref": "#/components/schemas/LLMModelUpdate" + } } } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "删除 LLM 模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { - "tags": ["大语言模型"], + "tags": [ + "大语言模型" + ], "summary": "测试 LLM 模型", "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。", "parameters": [ @@ -418,7 +548,10 @@ "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -439,13 +572,17 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/provider/models/embedding": { "get": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "获取所有向量模型", "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。", "parameters": [ @@ -453,7 +590,10 @@ "name": "provider_uuid", "in": "query", "required": false, - "schema": { "type": "string", "format": "uuid" }, + "schema": { + "type": "string", + "format": "uuid" + }, "description": "按供应商 UUID 过滤" } ], @@ -465,13 +605,18 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { "models": { "type": "array", - "items": { "$ref": "#/components/schemas/EmbeddingModel" } + "items": { + "$ref": "#/components/schemas/EmbeddingModel" + } } } } @@ -483,14 +628,18 @@ } }, "post": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "创建向量模型", "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EmbeddingModelCreate" } + "schema": { + "$ref": "#/components/schemas/EmbeddingModelCreate" + } } } }, @@ -502,11 +651,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -519,14 +674,19 @@ }, "/api/v1/provider/models/embedding/{model_uuid}": { "get": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "获取单个向量模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -537,11 +697,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "model": { "$ref": "#/components/schemas/EmbeddingModel" } + "model": { + "$ref": "#/components/schemas/EmbeddingModel" + } } } } @@ -549,51 +714,71 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "更新向量模型", "parameters": [ { "name": "model_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/EmbeddingModelUpdate" } + "schema": { + "$ref": "#/components/schemas/EmbeddingModelUpdate" + } } } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "删除向量模型", "parameters": [ { "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { - "tags": ["向量模型"], + "tags": [ + "向量模型" + ], "summary": "测试向量模型", "description": "向指定的向量模型发送测试请求，验证模型是否可用。", "parameters": [ @@ -601,7 +786,10 @@ "name": "model_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -622,13 +810,17 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/platform/bots": { "get": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "获取所有机器人", "responses": { "200": { @@ -638,13 +830,18 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { "bots": { "type": "array", - "items": { "$ref": "#/components/schemas/Bot" } + "items": { + "$ref": "#/components/schemas/Bot" + } } } } @@ -656,13 +853,17 @@ } }, "post": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "创建机器人", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/BotCreate" } + "schema": { + "$ref": "#/components/schemas/BotCreate" + } } } }, @@ -674,11 +875,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -691,7 +898,9 @@ }, "/api/v1/platform/bots/{bot_uuid}": { "get": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "获取单个机器人", "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。", "parameters": [ @@ -699,7 +908,10 @@ "name": "bot_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -710,11 +922,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "bot": { "$ref": "#/components/schemas/Bot" } + "bot": { + "$ref": "#/components/schemas/Bot" + } } } } @@ -722,51 +939,71 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "更新机器人", "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": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "删除机器人", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/platform/bots/{bot_uuid}/logs": { "post": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "获取机器人事件日志", "description": "获取指定机器人的事件日志记录。", "parameters": [ @@ -774,7 +1011,10 @@ "name": "bot_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -807,12 +1047,22 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "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" + } } } } @@ -825,16 +1075,25 @@ }, "/api/v1/platform/bots/{bot_uuid}/send_message": { "post": { - "tags": ["机器人"], + "tags": [ + "机器人" + ], "summary": "通过机器人发送消息", "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。", - "security": [{ "ApiKeyAuth": [] }], + "security": [ + { + "ApiKeyAuth": [] + } + ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -843,11 +1102,18 @@ "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": { @@ -862,7 +1128,12 @@ "properties": { "type": { "type": "string", - "enum": ["Plain", "Image", "At", "Voice"], + "enum": [ + "Plain", + "Image", + "At", + "Voice" + ], "description": "消息元素类型" }, "text": { @@ -880,7 +1151,10 @@ } }, "example": [ - { "type": "Plain", "text": "Hello, World!" } + { + "type": "Plain", + "text": "Hello, World!" + } ] } } @@ -896,11 +1170,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "sent": { "type": "boolean", "example": true } + "sent": { + "type": "boolean", + "example": true + } } } } @@ -912,7 +1192,9 @@ "description": "参数错误", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } } } } @@ -921,20 +1203,32 @@ }, "/api/v1/pipelines": { "get": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "获取所有流水线", "parameters": [ { "name": "sort_by", "in": "query", "required": false, - "schema": { "type": "string", "default": "created_at" } + "schema": { + "type": "string", + "default": "created_at" + } }, { "name": "sort_order", "in": "query", "required": false, - "schema": { "type": "string", "enum": ["ASC", "DESC"], "default": "DESC" } + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ], + "default": "DESC" + } } ], "responses": { @@ -945,13 +1239,18 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { "pipelines": { "type": "array", - "items": { "$ref": "#/components/schemas/Pipeline" } + "items": { + "$ref": "#/components/schemas/Pipeline" + } } } } @@ -963,13 +1262,17 @@ } }, "post": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "创建流水线", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/PipelineCreate" } + "schema": { + "$ref": "#/components/schemas/PipelineCreate" + } } } }, @@ -981,11 +1284,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -998,7 +1307,9 @@ }, "/api/v1/pipelines/_/metadata": { "get": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "获取流水线元数据", "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。", "responses": { @@ -1009,11 +1320,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "configs": { "type": "object" } + "configs": { + "type": "object" + } } } } @@ -1026,14 +1342,19 @@ }, "/api/v1/pipelines/{pipeline_uuid}": { "get": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "获取单个流水线", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1044,11 +1365,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "pipeline": { "$ref": "#/components/schemas/Pipeline" } + "pipeline": { + "$ref": "#/components/schemas/Pipeline" + } } } } @@ -1056,51 +1382,71 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "更新流水线", "parameters": [ { "name": "pipeline_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/PipelineUpdate" } + "schema": { + "$ref": "#/components/schemas/PipelineUpdate" + } } } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "删除流水线", "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/pipelines/{pipeline_uuid}/copy": { "post": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "复制流水线", "description": "复制一个已有的流水线，生成一个新的副本。", "parameters": [ @@ -1108,7 +1454,10 @@ "name": "pipeline_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1119,11 +1468,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -1131,13 +1486,17 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } } }, "/api/v1/pipelines/{pipeline_uuid}/extensions": { "get": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "获取流水线扩展配置", "description": "获取流水线绑定的插件和 MCP 服务器配置。", "parameters": [ @@ -1145,7 +1504,10 @@ "name": "pipeline_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1156,16 +1518,43 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "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" } } + "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" + } + } } } } @@ -1173,11 +1562,15 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["流水线"], + "tags": [ + "流水线" + ], "summary": "更新流水线扩展配置", "description": "更新流水线绑定的插件和 MCP 服务器。", "parameters": [ @@ -1185,7 +1578,10 @@ "name": "pipeline_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -1195,23 +1591,43 @@ "schema": { "type": "object", "properties": { - "enable_all_plugins": { "type": "boolean", "default": true }, - "enable_all_mcp_servers": { "type": "boolean", "default": true }, - "bound_plugins": { "type": "array", "items": { "type": "string" } }, - "bound_mcp_servers": { "type": "array", "items": { "type": "string" } } + "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" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/knowledge/bases": { "get": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "获取所有知识库", "responses": { "200": { @@ -1221,11 +1637,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "bases": { "type": "array", "items": { "type": "object" } } + "bases": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1236,7 +1660,9 @@ } }, "post": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "创建知识库", "requestBody": { "required": true, @@ -1244,12 +1670,24 @@ "application/json": { "schema": { "type": "object", - "required": ["name"], + "required": [ + "name" + ], "properties": { - "name": { "type": "string" }, - "description": { "type": "string" }, - "engine_plugin_id": { "type": "string", "description": "知识引擎插件 ID（author/name 格式）" }, - "creation_settings": { "type": "object", "description": "引擎创建参数" } + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "engine_plugin_id": { + "type": "string", + "description": "知识引擎插件 ID（author/name 格式）" + }, + "creation_settings": { + "type": "object", + "description": "引擎创建参数" + } } } } @@ -1263,11 +1701,17 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "uuid": { "type": "string", "format": "uuid" } + "uuid": { + "type": "string", + "format": "uuid" + } } } } @@ -1280,14 +1724,19 @@ }, "/api/v1/knowledge/bases/{kb_uuid}": { "get": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "获取单个知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1298,11 +1747,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "base": { "type": "object" } + "base": { + "type": "object" + } } } } @@ -1310,18 +1764,25 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "put": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "更新知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -1331,43 +1792,61 @@ "schema": { "type": "object", "properties": { - "name": { "type": "string" }, - "description": { "type": "string" } + "name": { + "type": "string" + }, + "description": { + "type": "string" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } }, "delete": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "删除知识库", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { "get": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "获取知识库文件列表", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1378,11 +1857,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "files": { "type": "array", "items": { "type": "object" } } + "files": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1393,7 +1880,9 @@ } }, "post": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "将文件存入知识库", "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。", "parameters": [ @@ -1401,7 +1890,10 @@ "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -1410,10 +1902,18 @@ "application/json": { "schema": { "type": "object", - "required": ["file_id"], + "required": [ + "file_id" + ], "properties": { - "file_id": { "type": "string", "description": "已上传的文件 ID" }, - "parser_plugin_id": { "type": "string", "description": "指定的解析器插件 ID（可选）" } + "file_id": { + "type": "string", + "description": "已上传的文件 ID" + }, + "parser_plugin_id": { + "type": "string", + "description": "指定的解析器插件 ID（可选）" + } } } } @@ -1427,11 +1927,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "task_id": { "type": "string" } + "task_id": { + "type": "string" + } } } } @@ -1444,30 +1949,41 @@ }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { "delete": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "从知识库删除文件", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } }, { "name": "file_id", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { "post": { - "tags": ["知识库"], + "tags": [ + "知识库" + ], "summary": "检索知识库", "description": "对知识库进行语义检索，返回相关文档片段。", "parameters": [ @@ -1475,7 +1991,10 @@ "name": "kb_uuid", "in": "path", "required": true, - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { @@ -1484,14 +2003,21 @@ "application/json": { "schema": { "type": "object", - "required": ["query"], + "required": [ + "query" + ], "properties": { - "query": { "type": "string", "description": "检索查询文本" }, + "query": { + "type": "string", + "description": "检索查询文本" + }, "retrieval_settings": { "type": "object", "description": "检索参数（如 top_k 等）", "properties": { - "top_k": { "type": "integer" } + "top_k": { + "type": "integer" + } } } } @@ -1507,11 +2033,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "results": { "type": "array", "items": { "type": "object" } } + "results": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1524,7 +2058,9 @@ }, "/api/v1/knowledge/engines": { "get": { - "tags": ["知识引擎"], + "tags": [ + "知识引擎" + ], "summary": "获取可用知识引擎列表", "description": "列出所有由插件提供的知识引擎，包含其能力和配置模式。", "responses": { @@ -1535,11 +2071,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "engines": { "type": "array", "items": { "type": "object" } } + "engines": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1552,7 +2096,9 @@ }, "/api/v1/knowledge/engines/{plugin_id}/creation-schema": { "get": { - "tags": ["知识引擎"], + "tags": [ + "知识引擎" + ], "summary": "获取知识引擎创建配置模式", "description": "获取指定知识引擎的创建参数 JSON Schema。", "parameters": [ @@ -1560,7 +2106,9 @@ "name": "plugin_id", "in": "path", "required": true, - "schema": { "type": "string" }, + "schema": { + "type": "string" + }, "description": "插件 ID（author/name 格式）" } ], @@ -1572,11 +2120,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "schema": { "type": "object" } + "schema": { + "type": "object" + } } } } @@ -1589,7 +2142,9 @@ }, "/api/v1/knowledge/engines/{plugin_id}/retrieval-schema": { "get": { - "tags": ["知识引擎"], + "tags": [ + "知识引擎" + ], "summary": "获取知识引擎检索配置模式", "description": "获取指定知识引擎的检索参数 JSON Schema。", "parameters": [ @@ -1597,7 +2152,9 @@ "name": "plugin_id", "in": "path", "required": true, - "schema": { "type": "string" }, + "schema": { + "type": "string" + }, "description": "插件 ID（author/name 格式）" } ], @@ -1609,11 +2166,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "schema": { "type": "object" } + "schema": { + "type": "object" + } } } } @@ -1626,7 +2188,9 @@ }, "/api/v1/knowledge/parsers": { "get": { - "tags": ["解析器"], + "tags": [ + "解析器" + ], "summary": "获取可用解析器列表", "description": "列出所有由插件提供的文件解析器。可通过 mime_type 过滤。", "parameters": [ @@ -1634,7 +2198,9 @@ "name": "mime_type", "in": "query", "required": false, - "schema": { "type": "string" }, + "schema": { + "type": "string" + }, "description": "按 MIME 类型过滤解析器" } ], @@ -1646,11 +2212,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "parsers": { "type": "array", "items": { "type": "object" } } + "parsers": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1663,7 +2237,9 @@ }, "/api/v1/files/images": { "post": { - "tags": ["文件"], + "tags": [ + "文件" + ], "summary": "上传图片", "description": "上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。", "requestBody": { @@ -1672,7 +2248,9 @@ "multipart/form-data": { "schema": { "type": "object", - "required": ["file"], + "required": [ + "file" + ], "properties": { "file": { "type": "string", @@ -1692,7 +2270,10 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { @@ -1712,7 +2293,9 @@ }, "/api/v1/files/documents": { "post": { - "tags": ["文件"], + "tags": [ + "文件" + ], "summary": "上传文档", "description": "上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。", "requestBody": { @@ -1721,7 +2304,9 @@ "multipart/form-data": { "schema": { "type": "object", - "required": ["file"], + "required": [ + "file" + ], "properties": { "file": { "type": "string", @@ -1741,7 +2326,10 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { @@ -1761,7 +2349,9 @@ }, "/api/v1/plugins": { "get": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "获取已安装插件列表", "responses": { "200": { @@ -1771,11 +2361,19 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "plugins": { "type": "array", "items": { "type": "object" } } + "plugins": { + "type": "array", + "items": { + "type": "object" + } + } } } } @@ -1788,20 +2386,26 @@ }, "/api/v1/plugins/{author}/{plugin_name}": { "get": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "获取插件详情", "parameters": [ { "name": "author", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "responses": { @@ -1812,11 +2416,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "plugin": { "type": "object" } + "plugin": { + "type": "object" + } } } } @@ -1824,11 +2433,15 @@ } } }, - "404": { "$ref": "#/components/responses/NotFound" } + "404": { + "$ref": "#/components/responses/NotFound" + } } }, "delete": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "删除插件", "description": "异步删除插件，返回任务 ID。", "parameters": [ @@ -1836,19 +2449,26 @@ "name": "author", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "delete_data", "in": "query", "required": false, - "schema": { "type": "boolean", "default": false }, + "schema": { + "type": "boolean", + "default": false + }, "description": "是否同时删除插件数据" } ], @@ -1860,11 +2480,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "task_id": { "type": "integer" } + "task_id": { + "type": "integer" + } } } } @@ -1877,7 +2502,9 @@ }, "/api/v1/plugins/{author}/{plugin_name}/upgrade": { "post": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "升级插件", "description": "异步升级插件到最新版本，返回任务 ID。", "parameters": [ @@ -1885,13 +2512,17 @@ "name": "author", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "responses": { @@ -1902,11 +2533,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "task_id": { "type": "integer" } + "task_id": { + "type": "integer" + } } } } @@ -1919,7 +2555,9 @@ }, "/api/v1/plugins/{author}/{plugin_name}/config": { "get": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "获取插件配置", "description": "获取插件的当前配置值和配置模式。", "parameters": [ @@ -1927,13 +2565,17 @@ "name": "author", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "responses": { @@ -1944,8 +2586,13 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, - "data": { "type": "object" } + "code": { + "type": "integer", + "example": 0 + }, + "data": { + "type": "object" + } } } } @@ -1954,20 +2601,26 @@ } }, "put": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "更新插件配置", "parameters": [ { "name": "author", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "plugin_name", "in": "path", "required": true, - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "requestBody": { @@ -1982,13 +2635,17 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/Success" } + "200": { + "$ref": "#/components/responses/Success" + } } } }, "/api/v1/plugins/install/marketplace": { "post": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "从 Marketplace 安装插件", "description": "从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。", "requestBody": { @@ -1997,7 +2654,9 @@ "application/json": { "schema": { "type": "object", - "required": ["plugin_id"], + "required": [ + "plugin_id" + ], "properties": { "plugin_id": { "type": "string", @@ -2017,11 +2676,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "task_id": { "type": "integer" } + "task_id": { + "type": "integer" + } } } } @@ -2034,7 +2698,9 @@ }, "/api/v1/plugins/install/github": { "post": { - "tags": ["插件"], + "tags": [ + "插件" + ], "summary": "从 GitHub 安装插件", "description": "从 GitHub 仓库安装插件。异步操作，返回任务 ID。", "requestBody": { @@ -2043,7 +2709,9 @@ "application/json": { "schema": { "type": "object", - "required": ["url"], + "required": [ + "url" + ], "properties": { "url": { "type": "string", @@ -2063,11 +2731,16 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 }, + "code": { + "type": "integer", + "example": 0 + }, "data": { "type": "object", "properties": { - "task_id": { "type": "integer" } + "task_id": { + "type": "integer" + } } } } @@ -2077,6 +2750,113 @@ } } } + }, + "/api/v1/tools": { + "get": { + "tags": [ + "工具" + ], + "summary": "获取所有可用工具", + "description": "获取当前 LangBot 实例中所有可用的工具，包括插件工具和 MCP 工具。", + "operationId": "listTools", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tools": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + } + } + } + } + }, + "/api/v1/tools/{tool_name}": { + "get": { + "tags": [ + "工具" + ], + "summary": "获取工具详情", + "description": "获取指定工具的详细信息。", + "operationId": "getToolDetail", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "name": "tool_name", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "工具名称" + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "example": 0 + }, + "msg": { + "type": "string", + "example": "ok" + }, + "data": { + "type": "object", + "properties": { + "tool": { + "$ref": "#/components/schemas/ToolSummary" + } + } + } + } + } + } + } + }, + "404": { + "description": "Tool not found" + } + } + } } }, "components": { @@ -2096,8 +2876,14 @@ "type": "object", "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。", "properties": { - "uuid": { "type": "string", "format": "uuid" }, - "name": { "type": "string", "example": "OpenAI" }, + "uuid": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "example": "OpenAI" + }, "requester": { "type": "string", "description": "请求器类型", @@ -2111,7 +2897,9 @@ "api_keys": { "type": "array", "description": "API 密钥列表", - "items": { "type": "string" } + "items": { + "type": "string" + } }, "llm_count": { "type": "integer", @@ -2121,15 +2909,28 @@ "type": "integer", "description": "关联的 Embedding 模型数量" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } } }, "ModelProviderCreate": { "type": "object", - "required": ["name", "requester", "base_url"], + "required": [ + "name", + "requester", + "base_url" + ], "properties": { - "name": { "type": "string", "example": "OpenAI" }, + "name": { + "type": "string", + "example": "OpenAI" + }, "requester": { "type": "string", "description": "请求器类型。可通过 GET /api/v1/provider/requesters 获取可用列表。", @@ -2141,20 +2942,32 @@ }, "api_keys": { "type": "array", - "items": { "type": "string" }, - "example": ["sk-xxx"] + "items": { + "type": "string" + }, + "example": [ + "sk-xxx" + ] } } }, "ModelProviderUpdate": { "type": "object", "properties": { - "name": { "type": "string" }, - "requester": { "type": "string" }, - "base_url": { "type": "string" }, + "name": { + "type": "string" + }, + "requester": { + "type": "string" + }, + "base_url": { + "type": "string" + }, "api_keys": { "type": "array", - "items": { "type": "string" } + "items": { + "type": "string" + } } } }, @@ -2162,7 +2975,10 @@ "type": "object", "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。", "properties": { - "uuid": { "type": "string", "format": "uuid" }, + "uuid": { + "type": "string", + "format": "uuid" + }, "name": { "type": "string", "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）", @@ -2175,9 +2991,15 @@ }, "abilities": { "type": "array", - "items": { "type": "string" }, + "items": { + "type": "string" + }, "description": "模型能力标签", - "example": ["chat", "vision", "tool-use"] + "example": [ + "chat", + "vision", + "tool-use" + ] }, "extra_args": { "type": "object", @@ -2188,13 +3010,22 @@ "description": "优先级排序（越大越优先）", "default": 0 }, - "created_at": { "type": "string", "format": "date-time" }, - "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", "provider_uuid"], + "required": [ + "name", + "provider_uuid" + ], "properties": { "name": { "type": "string", @@ -2208,31 +3039,55 @@ }, "abilities": { "type": "array", - "items": { "type": "string" }, - "example": ["chat", "vision"] + "items": { + "type": "string" + }, + "example": [ + "chat", + "vision" + ] }, - "extra_args": { "type": "object" }, - "prefered_ranking": { "type": "integer", "default": 0 } + "extra_args": { + "type": "object" + }, + "prefered_ranking": { + "type": "integer", + "default": 0 + } } }, "LLMModelUpdate": { "type": "object", "properties": { - "name": { "type": "string" }, - "provider_uuid": { "type": "string", "format": "uuid" }, + "name": { + "type": "string" + }, + "provider_uuid": { + "type": "string", + "format": "uuid" + }, "abilities": { "type": "array", - "items": { "type": "string" } + "items": { + "type": "string" + } }, - "extra_args": { "type": "object" }, - "prefered_ranking": { "type": "integer" } + "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": "模型名称（即模型 ID）", @@ -2243,15 +3098,29 @@ "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" } + "extra_args": { + "type": "object" + }, + "prefered_ranking": { + "type": "integer", + "default": 0 + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } } }, "EmbeddingModelCreate": { "type": "object", - "required": ["name", "provider_uuid"], + "required": [ + "name", + "provider_uuid" + ], "properties": { "name": { "type": "string", @@ -2261,79 +3130,197 @@ "type": "string", "format": "uuid" }, - "extra_args": { "type": "object" }, - "prefered_ranking": { "type": "integer", "default": 0 } + "extra_args": { + "type": "object" + }, + "prefered_ranking": { + "type": "integer", + "default": 0 + } } }, "EmbeddingModelUpdate": { "type": "object", "properties": { - "name": { "type": "string" }, - "provider_uuid": { "type": "string", "format": "uuid" }, - "extra_args": { "type": "object" }, - "prefered_ranking": { "type": "integer" } + "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" }, - "adapter": { "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"], + "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" }, - "is_default": { "type": "boolean" } + "name": { + "type": "string" + }, + "config": { + "type": "object" + }, + "is_default": { + "type": "boolean" + } } }, "ErrorResponse": { "type": "object", "properties": { - "code": { "type": "integer", "example": -1 }, - "msg": { "type": "string" } + "code": { + "type": "integer", + "example": -1 + }, + "msg": { + "type": "string" + } + } + }, + "ToolSummary": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Tool name" + }, + "label": { + "type": "object", + "description": "Display label (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "description": { + "type": "object", + "description": "Tool description (i18n)", + "additionalProperties": { + "type": "string" + } + }, + "icon": { + "type": "string", + "description": "Tool icon" + }, + "spec": { + "type": "object", + "description": "Tool specification", + "properties": { + "llm_prompt": { + "type": "string" + }, + "parameters": { + "type": "object", + "description": "JSON Schema for tool parameters" + } + } + } } } }, @@ -2345,7 +3332,10 @@ "schema": { "type": "object", "properties": { - "code": { "type": "integer", "example": 0 } + "code": { + "type": "integer", + "example": 0 + } } } } @@ -2355,10 +3345,12 @@ "description": "资源未找到", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } } } } } } -} +} \ No newline at end of file diff --git a/zh/plugin/dev/apis/common.mdx b/zh/plugin/dev/apis/common.mdx index 6dfdd1489..88f8eeffb 100644 --- a/zh/plugin/dev/apis/common.mdx +++ b/zh/plugin/dev/apis/common.mdx @@ -249,6 +249,87 @@ parsers = await self.plugin.list_parsers(mime_type="application/pdf") # 返回的每项包含 plugin_id、plugin_author、plugin_name、name、description、supported_mime_types ``` +### 获取所有可用工具 + +列出当前 LangBot 实例中所有可用的工具（包括插件工具和 MCP 工具）。 + +```python +async def list_tools(self) -> list[dict[str, Any]]: + """List all available tools + + Returns: + 工具列表，每个元素包含： + - name: 工具名称 + - label: 工具显示名称（多语言） + - description: 工具描述（多语言） + - icon: 工具图标 + - spec: 工具规格（包含 llm_prompt 和 parameters） + """ + +# 调用示例 +tools = await self.plugin.list_tools() +for tool in tools: + print(f"Tool: {tool['name']}") +``` + +### 获取工具详情 + +获取特定工具的详细信息。 + +```python +async def get_tool_detail(self, tool_name: str) -> dict[str, Any]: + """Get detailed information about a specific tool + + Args: + tool_name: 工具名称（metadata.name，例如 "get_weather_alerts"） + + Returns: + 工具详情 dict，包含 name、label、description、spec（含 parameters 和 llm_prompt） + """ + +# 调用示例 +detail = await self.plugin.get_tool_detail("get_weather_alerts") +print(detail['spec']['parameters']) +``` + +### 调用工具 + +调用指定的工具。 + +```python +async def call_tool( + self, + tool_name: str, + parameters: dict[str, Any], + session: dict[str, Any], + query_id: int, +) -> dict[str, Any]: + """Call a specific tool + + Args: + tool_name: 工具名称（metadata.name） + parameters: 工具参数 + session: 会话信息 + query_id: 查询 ID + + Returns: + 工具返回的结果 dict + """ + +# 调用示例 +result = await self.plugin.call_tool( + tool_name="get_weather_alerts", + parameters={"state": "CA"}, + session={}, + query_id=0, +) +print(result) +``` + + +工具名称使用 `metadata.name`（如 `echo_tool`、`get_weather_alerts`），不需要包含作者或插件名前缀。 + + ### 设置插件持久化数据 持久化存储插件数据。通过这个接口存储的数据，仅可被该插件访问。值需要自行转换为字节。 diff --git a/zh/plugin/dev/basic-info.mdx b/zh/plugin/dev/basic-info.mdx index 072d36a1d..8ffc5f20e 100644 --- a/zh/plugin/dev/basic-info.mdx +++ b/zh/plugin/dev/basic-info.mdx @@ -50,7 +50,7 @@ execution: spec: config: - name: github_token # 必填；配置项名称，用于在插件中获取 - type: string # 必填；配置项类型，支持 string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector 等 + type: string # 必填；配置项类型，支持 string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, tools-selector 等 label: # 必填；配置项显示名称，支持多语言。语言代码采用 RFC 4646 标准。 en_US: Github Token zh_Hans: Github Token @@ -274,6 +274,33 @@ bot_uuid = self.get_config()['bot'] print(bot_uuid) # 输出: '550e8400-e29b-41d4-a716-446655440000' ``` +### type: tools-selector + +工具选择器。会展示一个多选工具选择器，可选择已注册的工具（插件工具和 MCP 工具），最终结果表示为工具名称数组。 + +```yaml +- name: selected_tools + type: tools-selector + ... +``` + +在插件中使用选中的工具名称： + +```python +# 从配置中获取选中的工具名称列表 +selected_tools = self.get_config()['selected_tools'] +print(selected_tools) # 输出: ['get_weather_alerts', 'web_search'] + +# 调用选中的工具 +for tool_name in selected_tools: + result = await self.plugin.call_tool( + tool_name=tool_name, + parameters={"query": "hello"}, + session={}, + query_id=0, + ) +``` + ## 接下来做什么 该教程将指引您逐步完善插件功能。