feat(agent): support file attachments and local file replies

app/agent/__init__.py

@@ -1,4 +1,5 @@
 import asyncio
+import json
 import re
 import traceback
 import uuid
@@ -281,13 +282,19 @@ class MoviePilotAgent:
             logger.error(f"创建 Agent 失败: {e}")
             raise e
 
-    async def process(self, message: str, images: List[str] = None) -> str:
+    async def process(
+        self,
+        message: str,
+        images: List[str] = None,
+        files: Optional[List[dict]] = None,
+    ) -> str:
         """
         处理用户消息，流式推理并返回 Agent 回复
         """
         try:
             logger.info(
-                f"Agent推理: session_id={self.session_id}, input={message}, images={len(images) if images else 0}"
+                f"Agent推理: session_id={self.session_id}, input={message}, "
+                f"images={len(images) if images else 0}, files={len(files) if files else 0}"
             )
             self._tool_context = {
                 "incoming_voice": self.reply_with_voice,
@@ -300,16 +307,24 @@ class MoviePilotAgent:
                 session_id=self.session_id, user_id=self.user_id
             )
 
-            # 构建用户消息内容
-            if images:
-                content = []
-                if message:
-                    content.append({"type": "text", "text": message})
-                for img in images:
-                    content.append({"type": "image_url", "image_url": {"url": img}})
-                messages.append(HumanMessage(content=content))
-            else:
-                messages.append(HumanMessage(content=message))
+            # 构建结构化用户消息内容
+            request_payload = {
+                "message": message or "",
+                "images": [
+                    {"index": index + 1, "type": "image"}
+                    for index, _ in enumerate(images or [])
+                ],
+                "files": files or [],
+            }
+            content = [
+                {
+                    "type": "text",
+                    "text": json.dumps(request_payload, ensure_ascii=False, indent=2),
+                }
+            ]
+            for img in images or []:
+                content.append({"type": "image_url", "image_url": {"url": img}})
+            messages.append(HumanMessage(content=content))
 
             # 执行推理
             await self._execute_agent(messages)
@@ -544,6 +559,7 @@ class _MessageTask:
     user_id: str
     message: str
     images: Optional[List[str]] = None
+    files: Optional[List[dict]] = None
     channel: Optional[str] = None
     source: Optional[str] = None
     username: Optional[str] = None
@@ -610,6 +626,7 @@ class AgentManager:
         user_id: str,
         message: str,
         images: List[str] = None,
+        files: Optional[List[dict]] = None,
         channel: str = None,
         source: str = None,
         username: str = None,
@@ -624,6 +641,7 @@ class AgentManager:
             user_id=user_id,
             message=message,
             images=images,
+            files=files,
             channel=channel,
             source=source,
             username=username,
@@ -727,7 +745,7 @@ class AgentManager:
                 agent.username = task.username
         agent.reply_with_voice = task.reply_with_voice
 
-        return await agent.process(task.message, images=task.images)
+        return await agent.process(task.message, images=task.images, files=task.files)
 
     async def stop_current_task(self, session_id: str):
         """

app/agent/prompt/Agent Prompt.txt

@@ -10,6 +10,7 @@ Core Capabilities:
 3. Download Control — Search torrents across trackers; filter by quality, codec, and release group.
 4. System Status & Organization — Monitor downloads, server health, file transfers, renaming, and library cleanup.
 5. Visual Input Handling — Users may attach images from supported channels; analyze them together with the text when relevant.
+6. File Context Handling — User messages may arrive as structured JSON. Treat the `message` field as the user's text. Non-image attachments appear in `files`; when `local_path` is present, use local file tools to inspect the uploaded file directly.
 
 <communication>
 {verbose_spec}
@@ -21,6 +22,7 @@ Core Capabilities:
 - Include key details (year, rating, resolution) but do NOT over-explain.
 - Do not stop for approval on read-only operations. Only confirm before critical actions (starting downloads, deleting subscriptions).
 - If the current channel supports image sending and an image would materially help, you may use the `send_message` tool with `image_url` to send it.
+- If the current channel supports file sending and you need to return a local image/file for the user to download, use `send_local_file`.
 - Voice replies: {voice_reply_spec}
 - NOT a coding assistant. Do not offer code snippets.
 - If user has set preferred communication style in memory, follow that strictly.

app/agent/tools/factory.py

@@ -30,6 +30,7 @@ from app.agent.tools.impl.search_torrents import SearchTorrentsTool
 from app.agent.tools.impl.get_search_results import GetSearchResultsTool
 from app.agent.tools.impl.search_web import SearchWebTool
 from app.agent.tools.impl.send_message import SendMessageTool
+from app.agent.tools.impl.send_local_file import SendLocalFileTool
 from app.agent.tools.impl.send_voice_message import SendVoiceMessageTool
 from app.agent.tools.impl.query_schedulers import QuerySchedulersTool
 from app.agent.tools.impl.run_scheduler import RunSchedulerTool
@@ -119,6 +120,7 @@ class MoviePilotToolFactory:
             QueryTransferHistoryTool,
             TransferFileTool,
             SendMessageTool,
+            SendLocalFileTool,
             SendVoiceMessageTool,
             QuerySchedulersTool,
             RunSchedulerTool,

app/agent/tools/impl/send_local_file.py

@@ -0,0 +1,107 @@
+"""发送本地附件工具。"""
+
+from pathlib import Path
+from typing import Optional, Type
+
+from pydantic import BaseModel, Field, model_validator
+
+from app.agent.tools.base import MoviePilotTool, ToolChain
+from app.log import logger
+from app.schemas import Notification, NotificationType
+from app.schemas.message import ChannelCapabilityManager, ChannelCapability
+from app.schemas.types import MessageChannel
+
+
+class SendLocalFileInput(BaseModel):
+    """发送本地附件工具输入。"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why sending this local file helps the user",
+    )
+    file_path: str = Field(
+        ...,
+        description="Absolute path to the local image or file to send to the user",
+    )
+    message: Optional[str] = Field(
+        None,
+        description="Optional message or caption to send with the attachment",
+    )
+    title: Optional[str] = Field(
+        None,
+        description="Optional short title shown together with the attachment",
+    )
+    file_name: Optional[str] = Field(
+        None,
+        description="Optional override filename presented to the user when downloading",
+    )
+
+    @model_validator(mode="after")
+    def validate_file_path(self):
+        if not self.file_path:
+            raise ValueError("file_path 不能为空")
+        return self
+
+
+class SendLocalFileTool(MoviePilotTool):
+    name: str = "send_local_file"
+    description: str = (
+        "Send a local image or file from the server filesystem to the current user. "
+        "Use this when you have generated or identified a local file the user should download."
+    )
+    args_schema: Type[BaseModel] = SendLocalFileInput
+    require_admin: bool = False
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        file_path = kwargs.get("file_path", "")
+        file_name = Path(file_path).name if file_path else "未知文件"
+        return f"正在发送本地附件: {file_name}"
+
+    async def run(
+        self,
+        file_path: str,
+        message: Optional[str] = None,
+        title: Optional[str] = None,
+        file_name: Optional[str] = None,
+        **kwargs,
+    ) -> str:
+        if not self._channel or not self._source:
+            return "当前不在可回传消息的会话中，无法发送附件"
+
+        try:
+            channel = MessageChannel(self._channel)
+        except ValueError:
+            return f"不支持的消息渠道: {self._channel}"
+
+        if not ChannelCapabilityManager.supports_capability(
+            channel, ChannelCapability.FILE_SENDING
+        ):
+            return f"当前渠道 {channel.value} 暂不支持发送本地文件"
+
+        resolved_path = Path(file_path).expanduser()
+        if not resolved_path.is_absolute():
+            resolved_path = resolved_path.resolve()
+        if not resolved_path.exists() or not resolved_path.is_file():
+            return f"文件不存在: {resolved_path}"
+
+        logger.info(
+            "执行工具: %s, channel=%s, file=%s",
+            self.name,
+            channel.value,
+            resolved_path,
+        )
+
+        await ToolChain().async_post_message(
+            Notification(
+                channel=channel,
+                source=self._source,
+                mtype=NotificationType.Agent,
+                userid=self._user_id,
+                username=self._username,
+                title=title,
+                text=message,
+                file_path=str(resolved_path),
+                file_name=file_name or resolved_path.name,
+            )
+        )
+        return "本地附件已发送"

app/agent/tools/impl/send_message.py

@@ -19,7 +19,7 @@ class SendMessageInput(BaseModel):
         None,
         description="The message content to send to the user (should be clear and informative)",
     )
-    message_type: Optional[str] = Field(
+    title: Optional[str] = Field(
         None,
         description="Title of the message, a short summary of the message content",
     )
@@ -30,8 +30,8 @@ class SendMessageInput(BaseModel):
 
     @model_validator(mode="after")
     def validate_payload(self):
-        if not self.message and not self.message_type and not self.image_url:
-            raise ValueError("message、message_type、image_url 至少需要提供一个")
+        if not self.message and not self.title and not self.image_url:
+            raise ValueError("message、title、image_url 至少需要提供一个")
         return self
 
 
@@ -44,7 +44,7 @@ class SendMessageTool(MoviePilotTool):
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据消息参数生成友好的提示消息"""
         message = kwargs.get("message", "") or ""
-        title = kwargs.get("message_type") or ""
+        title = kwargs.get("title") or ""
         image_url = kwargs.get("image_url")
 
         # 截断过长的消息
@@ -62,11 +62,11 @@ class SendMessageTool(MoviePilotTool):
     async def run(
         self,
         message: Optional[str] = None,
-        message_type: Optional[str] = None,
+        title: Optional[str] = None,
         image_url: Optional[str] = None,
         **kwargs,
     ) -> str:
-        title = message_type or ("图片" if image_url and not message else "")
+        title = title or ("图片" if image_url and not message else "")
         text = message or ""
         logger.info(
             f"执行工具: {self.name}, 参数: title={title}, message={text}, image_url={image_url}"