refactor(messaging): 拆分用户交互模块到 application/messaging 层

- 新增 application/messaging 交互层：router.py 统一会话优先级与回调分发，
  site/subscribe/skill/media/plugin 各交互状态与视图从 Chain 迁出
- MessageChain 改为通过 InteractionRouter 派发文本会话与按钮回调，
  新增结构化 callback_data 通道（兼容 CALLBACK: 文本前缀）
- Transfer 失败重试/AI 接管回调归入 TransferChain
- MediaInteractionChain 拆出为 app/chain/interaction.py（旧路径保留兼容别名）
- WebAgent Endpoint 去重，统一使用 agent.py 回调协议函数
- 删除 app/chain/skills.py（交互逻辑并入 SkillInteractionHandler）
- 同步更新架构文档与测试，全量 4476 通过

app/application/messaging/agent.py

@@ -1,9 +1,177 @@
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
 from queue import Queue
 from threading import Lock
-from typing import Callable, Iterable, Optional, Union
+from typing import Callable, Dict, Iterable, List, Optional, Tuple, Union
 
 from app.schemas.types import MessageChannel
 
+# Agent 选择按钮回调前缀（新旧两种格式都必须继续兼容）
+AGENT_CHOICE_PREFIX = "agent_interaction:choice:"
+LEGACY_AGENT_CHOICE_PREFIX = "agent_choice:"
+
+
+def build_agent_choice_callback(request_id: str, option_index: int) -> str:
+    """构造 Agent 选择按钮回调数据。"""
+    return f"{AGENT_CHOICE_PREFIX}{request_id}:{option_index}"
+
+
+def parse_agent_choice_callback(
+        callback_data: str,
+) -> Optional[Tuple[str, int]]:
+    """解析新旧两种 Agent 选择回调，格式无效时返回 None。"""
+    if callback_data.startswith(AGENT_CHOICE_PREFIX):
+        try:
+            _, _, request_id, option_index = callback_data.split(":", 3)
+        except ValueError:
+            return None
+    elif callback_data.startswith(LEGACY_AGENT_CHOICE_PREFIX):
+        # 兼容旧格式，避免已发送的按钮失效
+        try:
+            _, request_id, option_index = callback_data.split(":", 2)
+        except ValueError:
+            return None
+    else:
+        return None
+    if not request_id or not option_index.isdigit():
+        return None
+    return request_id, int(option_index)
+
+
+def build_agent_choice_button_rows(
+        request: "PendingAgentInteraction",
+) -> Tuple[List[dict], List[List[dict]]]:
+    """根据待选择请求构造 WebAgent 和消息渠道共用的按钮。"""
+    buttons = [
+        {
+            "label": option.label,
+            "callback_data": build_agent_choice_callback(request.request_id, index),
+            "description": option.description or option.label,
+        }
+        for index, option in enumerate(request.options, start=1)
+    ]
+    button_rows = [[button] for button in buttons]
+    return buttons, button_rows
+
+
+@dataclass(frozen=True)
+class AgentInteractionOption:
+    """
+    Agent 交互选项。
+    """
+
+    label: str
+    value: str
+    description: Optional[str] = None
+
+
+@dataclass
+class PendingAgentInteraction:
+    """
+    待处理的 Agent 客户端交互请求。
+    """
+
+    request_id: str
+    session_id: str
+    user_id: str
+    channel: Optional[str]
+    source: Optional[str]
+    username: Optional[str]
+    title: Optional[str]
+    prompt: str
+    options: List[AgentInteractionOption]
+    created_at: datetime = field(default_factory=datetime.now)
+
+
+class AgentInteractionManager:
+    """
+    管理 Agent 发起的客户端交互请求。
+    """
+
+    _ttl = timedelta(hours=24)
+
+    def __init__(self):
+        """初始化待处理的 Agent 交互请求表。"""
+        self._pending_interactions: Dict[str, PendingAgentInteraction] = {}
+        self._lock = Lock()
+
+    def _cleanup_locked(self) -> None:
+        """在持锁状态下移除过期 Agent 交互。"""
+        expire_before = datetime.now() - self._ttl
+        expired_ids = [
+            request_id
+            for request_id, request in self._pending_interactions.items()
+            if request.created_at < expire_before
+        ]
+        for request_id in expired_ids:
+            self._pending_interactions.pop(request_id, None)
+
+    def create_request(
+            self,
+            session_id: str,
+            user_id: str,
+            channel: Optional[str],
+            source: Optional[str],
+            username: Optional[str],
+            title: Optional[str],
+            prompt: str,
+            options: List[AgentInteractionOption],
+    ) -> PendingAgentInteraction:
+        """
+        创建一条待用户确认的 Agent 交互请求。
+        """
+        with self._lock:
+            self._cleanup_locked()
+            request_id = uuid.uuid4().hex[:12]
+            while request_id in self._pending_interactions:
+                request_id = uuid.uuid4().hex[:12]
+            request = PendingAgentInteraction(
+                request_id=request_id,
+                session_id=session_id,
+                user_id=str(user_id),
+                channel=channel,
+                source=source,
+                username=username,
+                title=title,
+                prompt=prompt,
+                options=options,
+            )
+            self._pending_interactions[request_id] = request
+            return request
+
+    def resolve(
+            self,
+            request_id: str,
+            option_index: int,
+            user_id: Optional[str] = None,
+    ) -> Optional[tuple[PendingAgentInteraction, AgentInteractionOption]]:
+        """
+        消费一条 Agent 交互请求，并返回选中的选项。
+        """
+        with self._lock:
+            self._cleanup_locked()
+            request = self._pending_interactions.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_interactions.pop(request_id, None)
+            return request, option
+
+    def clear(self) -> None:
+        """
+        清空所有 Agent 交互请求。
+        """
+        with self._lock:
+            self._pending_interactions.clear()
+
+
+agent_interaction_manager = AgentInteractionManager()
+
 
 _WEB_AGENT_EDIT_QUEUES: dict[str, list[Queue[dict]]] = {}
 _WEB_AGENT_EDIT_LOCK = Lock()