feat: add agent button choice workflow

app/agent/prompt/Agent Prompt.txt

@@ -23,6 +23,7 @@ Core Capabilities:
 - 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`.
+{button_choice_spec}
 - 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/prompt/__init__.py

@@ -76,6 +76,7 @@ class PromptManager:
             caps = ChannelCapabilityManager.get_capabilities(msg_channel)
             if caps:
                 markdown_spec = self._generate_formatting_instructions(caps)
+        button_choice_spec = self._generate_button_choice_instructions(msg_channel)
 
         # 啰嗦模式
         verbose_spec = ""
@@ -100,6 +101,7 @@ class PromptManager:
             verbose_spec=verbose_spec,
             moviepilot_info=moviepilot_info,
             voice_reply_spec=voice_reply_spec,
+            button_choice_spec=button_choice_spec,
         )
 
         return base_prompt
@@ -187,6 +189,23 @@ class PromptManager:
             "- Do not repeat the same full reply again after calling `send_voice_message`."
         )
 
+    @staticmethod
+    def _generate_button_choice_instructions(
+        channel: MessageChannel = None,
+    ) -> str:
+        if channel and ChannelCapabilityManager.supports_buttons(
+            channel
+        ) and ChannelCapabilityManager.supports_callbacks(channel):
+            return (
+                "- User questions: If you need the user to choose from a few clear options, "
+                "call `ask_user_choice` to send button options. After the user clicks a button, "
+                "the selected value will come back as the user's next message. After calling this tool, "
+                "wait for the user's selection instead of repeating the question in plain text."
+            )
+        return (
+            "- User questions: When you truly need user input, ask briefly in plain text."
+        )
+
     def clear_cache(self):
         """
         清空缓存

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.ask_user_choice import AskUserChoiceTool
 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
@@ -58,6 +59,8 @@ from app.agent.tools.impl.query_custom_identifiers import QueryCustomIdentifiers
 from app.agent.tools.impl.update_custom_identifiers import UpdateCustomIdentifiersTool
 from app.core.plugin import PluginManager
 from app.log import logger
+from app.schemas.message import ChannelCapabilityManager
+from app.schemas.types import MessageChannel
 from .base import MoviePilotTool
 
 
@@ -66,6 +69,18 @@ class MoviePilotToolFactory:
     MoviePilot工具工厂
     """
 
+    @staticmethod
+    def _should_enable_choice_tool(channel: str = None) -> bool:
+        if not channel:
+            return False
+        try:
+            message_channel = MessageChannel(channel)
+        except ValueError:
+            return False
+        return ChannelCapabilityManager.supports_buttons(
+            message_channel
+        ) and ChannelCapabilityManager.supports_callbacks(message_channel)
+
     @staticmethod
     def create_tools(
         session_id: str,
@@ -120,8 +135,6 @@ class MoviePilotToolFactory:
             QueryTransferHistoryTool,
             TransferFileTool,
             SendMessageTool,
-            SendLocalFileTool,
-            SendVoiceMessageTool,
             QuerySchedulersTool,
             RunSchedulerTool,
             QueryWorkflowsTool,
@@ -138,6 +151,14 @@ class MoviePilotToolFactory:
             QueryCustomIdentifiersTool,
             UpdateCustomIdentifiersTool,
         ]
+        if MoviePilotToolFactory._should_enable_choice_tool(channel):
+            tool_definitions.append(AskUserChoiceTool)
+        tool_definitions.extend(
+            [
+                SendLocalFileTool,
+                SendVoiceMessageTool,
+            ]
+        )
         # 创建内置工具
         for ToolClass in tool_definitions:
             tool = ToolClass(session_id=session_id, user_id=user_id)

app/agent/tools/impl/ask_user_choice.py

@@ -0,0 +1,165 @@
+"""让用户通过按钮进行选择的工具。"""
+
+from typing import List, Optional, Type
+
+from pydantic import BaseModel, Field, model_validator
+
+from app.agent.tools.base import MoviePilotTool, ToolChain
+from app.agent.user_choice import AgentChoiceOption, agent_user_choice_manager
+from app.log import logger
+from app.schemas import Notification, NotificationType
+from app.schemas.message import ChannelCapabilityManager
+from app.schemas.types import MessageChannel
+
+
+class UserChoiceOptionInput(BaseModel):
+    """单个按钮选项。"""
+
+    label: str = Field(..., description="Text shown on the button")
+    value: str = Field(
+        ...,
+        description="The exact content that will be sent back to the agent after the user clicks this button",
+    )
+
+    @model_validator(mode="after")
+    def validate_option(self):
+        if not self.label.strip():
+            raise ValueError("label 不能为空")
+        if not self.value.strip():
+            raise ValueError("value 不能为空")
+        return self
+
+
+class AskUserChoiceInput(BaseModel):
+    """按钮选择工具输入。"""
+
+    explanation: str = Field(
+        ...,
+        description="Clear explanation of why the agent needs the user to choose from buttons",
+    )
+    message: str = Field(
+        ...,
+        description="Question or prompt shown to the user together with the buttons",
+    )
+    title: Optional[str] = Field(
+        None,
+        description="Optional short title displayed above the question",
+    )
+    options: List[UserChoiceOptionInput] = Field(
+        ...,
+        description="Button options to show to the user",
+    )
+
+    @model_validator(mode="after")
+    def validate_payload(self):
+        if not self.message.strip():
+            raise ValueError("message 不能为空")
+        if not self.options:
+            raise ValueError("options 至少需要提供一个")
+        return self
+
+
+class AskUserChoiceTool(MoviePilotTool):
+    name: str = "ask_user_choice"
+    description: str = (
+        "Ask the user to choose from button options on channels that support interactive buttons. "
+        "After the user clicks a button, the selected value will come back as the user's next message."
+    )
+    args_schema: Type[BaseModel] = AskUserChoiceInput
+    require_admin: bool = False
+
+    def get_tool_message(self, **kwargs) -> Optional[str]:
+        message = kwargs.get("message", "") or ""
+        if len(message) > 40:
+            message = message[:40] + "..."
+        return f"正在发送按钮选择: {message}"
+
+    @staticmethod
+    def _truncate_button_text(text: str, max_length: int) -> str:
+        if max_length <= 0 or len(text) <= max_length:
+            return text
+        if max_length <= 3:
+            return text[:max_length]
+        return text[: max_length - 3] + "..."
+
+    async def run(
+        self,
+        message: str,
+        options: List[UserChoiceOptionInput],
+        title: 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_buttons(channel)
+            and ChannelCapabilityManager.supports_callbacks(channel)
+        ):
+            return f"当前渠道 {channel.value} 不支持按钮选择"
+
+        max_per_row = ChannelCapabilityManager.get_max_buttons_per_row(channel)
+        max_rows = ChannelCapabilityManager.get_max_button_rows(channel)
+        max_text_length = ChannelCapabilityManager.get_max_button_text_length(channel)
+        max_options = max_per_row * max_rows
+        if len(options) > max_options:
+            return f"当前渠道最多支持 {max_options} 个按钮选项"
+
+        choice_options = [
+            AgentChoiceOption(label=option.label.strip(), value=option.value.strip())
+            for option in options
+        ]
+        request = agent_user_choice_manager.create_request(
+            session_id=self._session_id,
+            user_id=str(self._user_id),
+            channel=channel.value,
+            source=self._source,
+            username=self._username,
+            prompt=message.strip(),
+            options=choice_options,
+        )
+
+        buttons = []
+        current_row = []
+        for index, option in enumerate(choice_options, start=1):
+            current_row.append(
+                {
+                    "text": self._truncate_button_text(option.label, max_text_length),
+                    "callback_data": f"agent_choice:{request.request_id}:{index}",
+                }
+            )
+            if len(current_row) >= max_per_row:
+                buttons.append(current_row)
+                current_row = []
+        if current_row:
+            buttons.append(current_row)
+
+        logger.info(
+            "执行工具: %s, channel=%s, session_id=%s, options=%s",
+            self.name,
+            channel.value,
+            self._session_id,
+            len(choice_options),
+        )
+
+        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.strip(),
+                buttons=buttons,
+            )
+        )
+
+        self._agent_context["user_reply_sent"] = True
+        self._agent_context["reply_mode"] = "button_choice"
+        return f"已发送 {len(choice_options)} 个按钮选项，等待用户选择"

app/agent/user_choice.py

@@ -0,0 +1,104 @@
+"""Agent 用户按钮选择请求管理。"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from threading import Lock
+from typing import Dict, List, Optional
+import uuid
+
+
+@dataclass(frozen=True)
+class AgentChoiceOption:
+    """按钮选项。"""
+
+    label: str
+    value: str
+
+
+@dataclass
+class PendingAgentChoice:
+    """待处理的按钮选择请求。"""
+
+    request_id: str
+    session_id: str
+    user_id: str
+    channel: Optional[str]
+    source: Optional[str]
+    username: Optional[str]
+    prompt: str
+    options: List[AgentChoiceOption]
+    created_at: datetime = field(default_factory=datetime.now)
+
+
+class AgentUserChoiceManager:
+    """管理 Agent 发起的按钮选择请求。"""
+
+    _ttl = timedelta(hours=24)
+
+    def __init__(self):
+        self._pending_choices: Dict[str, PendingAgentChoice] = {}
+        self._lock = Lock()
+
+    def _cleanup_locked(self):
+        expire_before = datetime.now() - self._ttl
+        expired_ids = [
+            request_id
+            for request_id, request in self._pending_choices.items()
+            if request.created_at < expire_before
+        ]
+        for request_id in expired_ids:
+            self._pending_choices.pop(request_id, None)
+
+    def create_request(
+        self,
+        session_id: str,
+        user_id: str,
+        channel: Optional[str],
+        source: Optional[str],
+        username: Optional[str],
+        prompt: str,
+        options: List[AgentChoiceOption],
+    ) -> PendingAgentChoice:
+        with self._lock:
+            self._cleanup_locked()
+            request_id = uuid.uuid4().hex[:12]
+            while request_id in self._pending_choices:
+                request_id = uuid.uuid4().hex[:12]
+            request = PendingAgentChoice(
+                request_id=request_id,
+                session_id=session_id,
+                user_id=str(user_id),
+                channel=channel,
+                source=source,
+                username=username,
+                prompt=prompt,
+                options=options,
+            )
+            self._pending_choices[request_id] = request
+            return request
+
+    def resolve(
+        self,
+        request_id: str,
+        option_index: int,
+        user_id: Optional[str] = None,
+    ) -> Optional[tuple[PendingAgentChoice, AgentChoiceOption]]:
+        with self._lock:
+            self._cleanup_locked()
+            request = self._pending_choices.get(request_id)
+            if not request:
+                return None
+            if user_id is not None and str(request.user_id) != str(user_id):
+                return None
+            if option_index < 1 or option_index > len(request.options):
+                return None
+            option = request.options[option_index - 1]
+            self._pending_choices.pop(request_id, None)
+            return request, option
+
+    def clear(self):
+        with self._lock:
+            self._pending_choices.clear()
+
+
+agent_user_choice_manager = AgentUserChoiceManager()