feat(README): 添加插件中注册智能体工具的说明和示例代码

README.md

@@ -24,6 +24,7 @@ MoviePilot官方插件市场：https://github.com/jxxghp/MoviePilot-Plugins
   - [13. 如何将插件功能集成到工作流？](#13-如何将插件功能集成到工作流)
   - [14. 如何在插件中通过消息持续与用户交互？](#14-如何在插件中通过消息持续与用户交互)
   - [15. 如何在插件中使用系统级统一缓存？](#15-如何在插件中使用系统级统一缓存)
+  - [16. 如何在插件中注册智能体工具？](#16-如何在插件中注册智能体工具)
 - [版本发布](#版本发布)
   - [1. 如何发布插件版本？](#1-如何发布插件版本)
   - [2. 如何开发V2版本的插件以及实现插件多版本兼容？](#2-如何开发v2版本的插件以及实现插件多版本兼容)
@@ -1352,6 +1353,102 @@ def get_actions(self) -> List[Dict[str, Any]]:
     - 大文件或二进制数据建议使用文件缓存后端
     - 在插件卸载时清理相关缓存，避免内存泄漏
 
+### 16. 如何在插件中注册智能体工具？
+**（仅支持 `v2.8.0+` 版本）**
+- MoviePilot的AI智能体功能支持通过插件扩展工具能力，插件可以注册自定义工具供智能体调用，实现更丰富的功能扩展。
+- 1. 实现 `get_agent_tools()` 方法，返回工具类列表：
+    ```python
+    def get_agent_tools(self) -> List[Type]:
+        """
+        获取插件智能体工具
+        返回工具类列表，每个工具类必须继承自 MoviePilotTool
+        """
+        return [MyCustomTool, AnotherTool]
+    ```
+
+- 2. 创建工具类，必须继承自 `MoviePilotTool` 并实现相关要求：
+    ```python
+    from typing import Optional, Type
+    from pydantic import BaseModel, Field
+    from app.agent.tools.base import MoviePilotTool
+    from app.chain import ToolChain
+    
+    class MyToolInput(BaseModel):
+        """工具输入参数模型"""
+        explanation: str = Field(..., description="工具使用说明")
+        query: str = Field(..., description="查询内容")
+        limit: Optional[int] = Field(10, description="返回结果数量限制")
+    
+    class MyCustomTool(MoviePilotTool):
+        """自定义工具示例"""
+        # 工具名称，用于智能体识别和调用
+        name: str = "my_custom_tool"
+        
+        # 工具描述，用于智能体理解工具功能，建议详细描述工具用途和使用场景
+        description: str = "This tool is used to perform custom operations. Use it when you need to query or process specific data."
+        
+        # 输入参数模型，定义工具接收的参数及其类型和说明
+        args_schema: Type[BaseModel] = MyToolInput
+        
+        async def run(self, query: str, limit: Optional[int] = None, **kwargs) -> str:
+            """
+            实现工具的核心逻辑（异步方法）
+            :param query: 查询内容
+            :param limit: 结果数量限制
+            :param kwargs: 其他参数，包含 explanation（工具使用说明）
+            :return: 工具执行结果，返回字符串格式
+            """
+            try:
+                # 获取上下文信息（系统自动注入）
+                session_id = self._session_id
+                user_id = self._user_id
+                channel = self._channel
+                source = self._source
+                username = self._username
+                
+                # 执行工具逻辑
+                result = await self._perform_operation(query, limit)
+                
+                # 可以通过 send_tool_message 发送消息给用户
+                await self.send_tool_message(f"操作完成: {result}", title="工具执行")
+                
+                # 返回执行结果
+                return f"成功处理查询 '{query}'，返回 {len(result)} 条结果"
+            except Exception as e:
+                return f"执行失败: {str(e)}"
+        
+        async def _perform_operation(self, query: str, limit: int):
+            """内部方法，执行具体操作"""
+            # 实现具体业务逻辑
+            pass
+    ```
+
+- 3. 工具类可用的上下文属性和方法：
+    - `self._session_id`: 当前会话ID
+    - `self._user_id`: 用户ID
+    - `self._channel`: 消息渠道（如 Telegram、Slack 等）
+    - `self._source`: 消息来源
+    - `self._username`: 用户名
+    - `self.send_tool_message(message: str, title: str = "")`: 发送消息给用户
+    - `ToolChain()`: 访问处理链功能，可调用系统其他功能
+
+- 4. 工具类实现要求：
+    - **必须继承自 `app.agent.tools.base.MoviePilotTool`**
+    - **必须实现 `run` 方法**（异步方法），接收参数并返回字符串结果
+    - **必须定义 `name` 属性**（字符串），工具的唯一标识
+    - **必须定义 `description` 属性**（字符串），详细描述工具功能，帮助智能体理解何时使用该工具
+    - **可选定义 `args_schema` 属性**（Pydantic模型类），用于定义输入参数的结构和验证
+
+- 5. 注意事项：
+    - 工具的描述（`description`）应该清晰明确，帮助智能体理解工具的功能和使用场景
+    - 工具的参数模型（`args_schema`）应该包含详细的字段描述，帮助智能体正确构造参数
+    - 工具执行结果应该返回有意义的字符串，便于智能体理解和向用户展示
+    - 工具可以通过 `send_tool_message` 方法向用户发送实时消息，提升交互体验
+    - 工具类在初始化时会自动注入会话和用户信息，可以通过私有属性访问
+    - 如果工具需要访问插件实例，需要自行通过 `PluginManager` 获取
+    - 工具执行时间应该尽量短，避免阻塞智能体的响应
+    - 建议在工具执行过程中添加适当的错误处理和日志记录
+
 
 ## 版本发布