From 84216a4df718e37a13183e6419de05ecc9e4be96 Mon Sep 17 00:00:00 2001 From: UnCLAS-Prommer Date: Thu, 31 Jul 2025 15:01:31 +0800 Subject: [PATCH] =?UTF-8?q?api=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=EF=BC=8C=E6=B3=A8=E9=87=8A=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plugins/api/component-manage-api.md | 26 +++++++-- docs/plugins/api/config-api.md | 2 +- docs/plugins/api/generator-api.md | 19 ++++--- docs/plugins/api/llm-api.md | 12 ++-- docs/plugins/api/tool-api.md | 55 +++++++++++++++++++ docs/plugins/index.md | 8 +-- .../{tool-system.md => tool-components.md} | 7 ++- src/plugin_system/apis/generator_api.py | 6 +- 8 files changed, 104 insertions(+), 31 deletions(-) create mode 100644 docs/plugins/api/tool-api.md rename docs/plugins/{tool-system.md => tool-components.md} (97%) diff --git a/docs/plugins/api/component-manage-api.md b/docs/plugins/api/component-manage-api.md index f6da2adcc..a857fb278 100644 --- a/docs/plugins/api/component-manage-api.md +++ b/docs/plugins/api/component-manage-api.md @@ -100,7 +100,19 @@ def get_registered_command_info(command_name: str) -> Optional[CommandInfo]: **Returns:** - `Optional[CommandInfo]` - Command 信息对象，如果 Command 不存在则返回 `None`。 -### 8. 获取指定 EventHandler 的注册信息 +### 8. 获取指定 Tool 的注册信息 +```python +def get_registered_tool_info(tool_name: str) -> Optional[ToolInfo]: +``` +获取指定 Tool 的注册信息。 + +**Args:** +- `tool_name` (str): Tool 名称。 + +**Returns:** +- `Optional[ToolInfo]` - Tool 信息对象，如果 Tool 不存在则返回 `None`。 + +### 9. 获取指定 EventHandler 的注册信息 ```python def get_registered_event_handler_info(event_handler_name: str) -> Optional[EventHandlerInfo]: ``` @@ -112,7 +124,7 @@ def get_registered_event_handler_info(event_handler_name: str) -> Optional[Event **Returns:** - `Optional[EventHandlerInfo]` - EventHandler 信息对象，如果 EventHandler 不存在则返回 `None`。 -### 9. 全局启用指定组件 +### 10. 全局启用指定组件 ```python def globally_enable_component(component_name: str, component_type: ComponentType) -> bool: ``` @@ -125,12 +137,14 @@ def globally_enable_component(component_name: str, component_type: ComponentType **Returns:** - `bool` - 启用成功返回 `True`，否则返回 `False`。 -### 10. 全局禁用指定组件 +### 11. 全局禁用指定组件 ```python async def globally_disable_component(component_name: str, component_type: ComponentType) -> bool: ``` 全局禁用指定组件。 +**此函数是异步的，确保在异步环境中调用。** + **Args:** - `component_name` (str): 组件名称。 - `component_type` (ComponentType): 组件类型。 @@ -138,7 +152,7 @@ async def globally_disable_component(component_name: str, component_type: Compon **Returns:** - `bool` - 禁用成功返回 `True`，否则返回 `False`。 -### 11. 局部启用指定组件 +### 12. 局部启用指定组件 ```python def locally_enable_component(component_name: str, component_type: ComponentType, stream_id: str) -> bool: ``` @@ -152,7 +166,7 @@ def locally_enable_component(component_name: str, component_type: ComponentType, **Returns:** - `bool` - 启用成功返回 `True`，否则返回 `False`。 -### 12. 局部禁用指定组件 +### 13. 局部禁用指定组件 ```python def locally_disable_component(component_name: str, component_type: ComponentType, stream_id: str) -> bool: ``` @@ -166,7 +180,7 @@ def locally_disable_component(component_name: str, component_type: ComponentType **Returns:** - `bool` - 禁用成功返回 `True`，否则返回 `False`。 -### 13. 获取指定消息流中禁用的组件列表 +### 14. 获取指定消息流中禁用的组件列表 ```python def get_locally_disabled_components(stream_id: str, component_type: ComponentType) -> list[str]: ``` diff --git a/docs/plugins/api/config-api.md b/docs/plugins/api/config-api.md index 2a5691fc4..2ee1cdfca 100644 --- a/docs/plugins/api/config-api.md +++ b/docs/plugins/api/config-api.md @@ -1,6 +1,6 @@ # 配置API -配置API模块提供了配置读取和用户信息获取等功能，让插件能够安全地访问全局配置和用户信息。 +配置API模块提供了配置读取功能，让插件能够安全地访问全局配置和插件配置。 ## 导入方式 diff --git a/docs/plugins/api/generator-api.md b/docs/plugins/api/generator-api.md index 690283df0..afeb6eec6 100644 --- a/docs/plugins/api/generator-api.md +++ b/docs/plugins/api/generator-api.md @@ -17,7 +17,7 @@ from src.plugin_system import generator_api def get_replyer( chat_stream: Optional[ChatStream] = None, chat_id: Optional[str] = None, - model_configs: Optional[List[Dict[str, Any]]] = None, + model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None, request_type: str = "replyer", ) -> Optional[DefaultReplyer]: ``` @@ -30,7 +30,7 @@ def get_replyer( **Args:** - `chat_stream`: 聊天流对象 - `chat_id`: 聊天ID（实际上就是`stream_id`） -- `model_configs`: 模型配置 +- `model_set_with_weight`: 模型配置列表，每个元素为 `(TaskConfig, weight)` 元组 - `request_type`: 请求类型，用于记录LLM使用情况，可以不写 **Returns:** @@ -58,8 +58,8 @@ async def generate_reply( enable_splitter: bool = True, enable_chinese_typo: bool = True, return_prompt: bool = False, - model_configs: Optional[List[Dict[str, Any]]] = None, - request_type: str = "", + model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None, + request_type: str = "generator_api", ) -> Tuple[bool, List[Tuple[str, Any]], Optional[str]]: ``` 生成回复 @@ -77,7 +77,8 @@ async def generate_reply( - `enable_splitter`: 是否启用分割器 - `enable_chinese_typo`: 是否启用中文错别字 - `return_prompt`: 是否返回提示词 -- `model_configs`: 模型配置，可选 +- `model_set_with_weight`: 模型配置列表，每个元素为 `(TaskConfig, weight)` 元组 +- `request_type`: 请求类型（可选，记录LLM使用） - `request_type`: 请求类型，用于记录LLM使用情况 **Returns:** @@ -108,7 +109,7 @@ async def rewrite_reply( chat_id: Optional[str] = None, enable_splitter: bool = True, enable_chinese_typo: bool = True, - model_configs: Optional[List[Dict[str, Any]]] = None, + model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None, raw_reply: str = "", reason: str = "", reply_to: str = "", @@ -125,7 +126,7 @@ async def rewrite_reply( - `chat_id`: 聊天ID（实际上就是`stream_id`） - `enable_splitter`: 是否启用分割器 - `enable_chinese_typo`: 是否启用中文错别字 -- `model_configs`: 模型配置，可选 +- `model_set_with_weight`: 模型配置列表，每个元素为 (TaskConfig, weight) 元组 - `raw_reply`: 原始回复内容 - `reason`: 重写原因 - `reply_to`: 回复目标，格式为 `{发送者的person_name:消息内容}` @@ -174,7 +175,7 @@ reply_set = [ async def generate_response_custom( chat_stream: Optional[ChatStream] = None, chat_id: Optional[str] = None, - model_configs: Optional[List[Dict[str, Any]]] = None, + model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None, prompt: str = "", ) -> Optional[str]: ``` @@ -185,7 +186,7 @@ async def generate_response_custom( **Args:** - `chat_stream`: 聊天流对象 - `chat_id`: 聊天ID（备用） -- `model_configs`: 模型配置列表 +- `model_set_with_weight`: 模型集合配置列表 - `prompt`: 自定义提示词 **Returns:** diff --git a/docs/plugins/api/llm-api.md b/docs/plugins/api/llm-api.md index d778ec8d8..9a266933b 100644 --- a/docs/plugins/api/llm-api.md +++ b/docs/plugins/api/llm-api.md @@ -14,26 +14,26 @@ from src.plugin_system import llm_api ### 1. 查询可用模型 ```python -def get_available_models() -> Dict[str, Any]: +def get_available_models() -> Dict[str, TaskConfig]: ``` 获取所有可用的模型配置。 **Return：** -- `Dict[str, Any]`：模型配置字典，key为模型名称，value为模型配置。 +- `Dict[str, TaskConfig]`：模型配置字典，key为模型名称，value为模型配置对象。 ### 2. 使用模型生成内容 ```python async def generate_with_model( - prompt: str, model_config: Dict[str, Any], request_type: str = "plugin.generate", **kwargs -) -> Tuple[bool, str]: + prompt: str, model_config: TaskConfig, request_type: str = "plugin.generate", **kwargs +) -> Tuple[bool, str, str, str]: ``` 使用指定模型生成内容。 **Args:** - `prompt`：提示词。 -- `model_config`：模型配置（从 `get_available_models` 获取）。 +- `model_config`：模型配置对象（从 `get_available_models` 获取）。 - `request_type`：请求类型标识，默认为 `"plugin.generate"`。 - `**kwargs`：其他模型特定参数，如 `temperature`、`max_tokens` 等。 **Return：** -- `Tuple[bool, str]`：返回一个元组，第一个元素表示是否成功，第二个元素为生成的内容或错误信息。 \ No newline at end of file +- `Tuple[bool, str, str, str]`：返回一个元组，包含（是否成功, 生成的内容, 推理过程, 模型名称）。 \ No newline at end of file diff --git a/docs/plugins/api/tool-api.md b/docs/plugins/api/tool-api.md new file mode 100644 index 000000000..d86734fcd --- /dev/null +++ b/docs/plugins/api/tool-api.md @@ -0,0 +1,55 @@ +# 工具API + +工具API模块提供了获取和管理工具实例的功能，让插件能够访问系统中注册的工具。 + +## 导入方式 + +```python +from src.plugin_system.apis import tool_api +# 或者 +from src.plugin_system import tool_api +``` + +## 主要功能 + +### 1. 获取工具实例 + +```python +def get_tool_instance(tool_name: str) -> Optional[BaseTool]: +``` + +获取指定名称的工具实例。 + +**Args**: +- `tool_name`: 工具名称字符串 + +**Returns**: +- `Optional[BaseTool]`: 工具实例，如果工具不存在则返回 None + +### 2. 获取LLM可用的工具定义 + +```python +def get_llm_available_tool_definitions(): +``` + +获取所有LLM可用的工具定义列表。 + +**Returns**: +- `List[Tuple[str, Dict[str, Any]]]`: 工具定义列表，每个元素为 `(工具名称, 工具定义字典)` 的元组 + - 其具体定义请参照[tool-components.md](../tool-components.md)中的工具定义格式。 +#### 示例： + +```python +# 获取所有LLM可用的工具定义 +tools = tool_api.get_llm_available_tool_definitions() +for tool_name, tool_definition in tools: + print(f"工具: {tool_name}") + print(f"定义: {tool_definition}") +``` + +## 注意事项 + +1. **工具存在性检查**：使用前请检查工具实例是否为 None +2. **权限控制**：某些工具可能有使用权限限制 +3. **异步调用**：大多数工具方法是异步的，需要使用 await +4. **错误处理**：调用工具时请做好异常处理 diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 2ca4bb364..2454c98a3 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -10,6 +10,7 @@ - [🧱 Action组件详解](action-components.md) - 掌握最核心的Action组件 - [💻 Command组件详解](command-components.md) - 学习直接响应命令的组件 +- [🔧 Tool组件详解](tool-components.md) - 了解如何扩展信息获取能力 - [⚙️ 配置文件系统指南](configuration-guide.md) - 学会使用自动生成的插件配置文件 - [📄 Manifest系统指南](manifest-guide.md) - 了解插件元数据管理和配置架构 @@ -59,11 +60,8 @@ Command vs Action 选择指南 ### 日志API - [📜 日志API](api/logging-api.md) - logger实例获取接口 - -## 实验性 - -这些功能将在未来重构或移除 -- [🔧 工具系统详解](tool-system.md) - 工具系统的使用和开发 +### 工具API +- [🔧 工具API](api/tool-api.md) - tool获取接口 diff --git a/docs/plugins/tool-system.md b/docs/plugins/tool-components.md similarity index 97% rename from docs/plugins/tool-system.md rename to docs/plugins/tool-components.md index 55e2cb713..cd48a0541 100644 --- a/docs/plugins/tool-system.md +++ b/docs/plugins/tool-components.md @@ -1,4 +1,4 @@ -# 🔧 工具系统详解 +# 🔧 工具组件详解 ## 📖 什么是工具 @@ -75,6 +75,11 @@ class MyTool(BaseTool): | `description` | str | 工具功能描述，帮助LLM理解用途 | | `parameters` | list[tuple] | 参数定义 | +其构造而成的工具定义为: +```python +{"name": cls.name, "description": cls.description, "parameters": cls.parameters} +``` + ### 方法说明 | 方法 | 参数 | 返回值 | 说明 | diff --git a/src/plugin_system/apis/generator_api.py b/src/plugin_system/apis/generator_api.py index 2b7732f08..0e6e65517 100644 --- a/src/plugin_system/apis/generator_api.py +++ b/src/plugin_system/apis/generator_api.py @@ -43,7 +43,7 @@ def get_replyer( Args: chat_stream: 聊天流对象（优先） chat_id: 聊天ID（实际上就是stream_id） - model_configs: 模型配置列表 + model_set_with_weight: 模型配置列表，每个元素为 (TaskConfig, weight) 元组 request_type: 请求类型 Returns: @@ -100,7 +100,7 @@ async def generate_reply( enable_splitter: 是否启用消息分割器 enable_chinese_typo: 是否启用错字生成器 return_prompt: 是否返回提示词 - model_configs: 模型配置列表 + model_set_with_weight: 模型配置列表，每个元素为 (TaskConfig, weight) 元组 request_type: 请求类型（可选，记录LLM使用） Returns: Tuple[bool, List[Tuple[str, Any]], Optional[str]]: (是否成功, 回复集合, 提示词) @@ -169,7 +169,7 @@ async def rewrite_reply( chat_id: 聊天ID（备用） enable_splitter: 是否启用消息分割器 enable_chinese_typo: 是否启用错字生成器 - model_configs: 模型配置列表 + model_set_with_weight: 模型配置列表，每个元素为 (TaskConfig, weight) 元组 raw_reply: 原始回复内容 reason: 回复原因 reply_to: 回复对象