refactor(chain): 处理链功能域 mixin 化，清理未使用导入并根治兼容层循环导入

- ChainBase 拆分为 RecognitionMixin/MessageProcessingMixin/NotificationMixin
- TransferChain 拆分为 7 个功能 mixin（_mixins.py），SubscribeChain 音乐订阅域拆出 _music.py
- 斜杠命令交互四件套收敛为 InteractionChainMixin 委托，会话管理器移至 application 层，chain 层不再 re-export
- 模块基础类收敛到 app/modules/_base（notification/mediaserver 语义重命名）
- 清理 app/chain/__init__.py 24 个未使用导入，修正 49 处测试 patch 目标到实际命名空间
- 兼容层 legacy 符号不再并入 __all__，根治 schemas 初始化反向拉起 application.transfer 的循环导入
- 修复 bangumi 集数为字符串时 set_bangumi_info 抛 TypeError
- 新增重复代码等架构门禁测试；capability 清单校验排除下划线内部目录

app/agent/orchestrator.py

@@ -6,7 +6,6 @@ import traceback
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timedelta
-from enum import Enum
 from typing import Any, Callable, Dict, List, Optional
 
 from fastapi.concurrency import run_in_threadpool
@@ -68,7 +67,7 @@ from app.agent.tools.impl.mcp import (
     select_legacy_mcp_tools,
 )
 from app.agent.tools.impl.query_system_settings import QuerySystemSettingsTool
-from app.chain import ChainBase
+from app.chain.agent import AgentChain
 from app.runtime.config import settings
 from app.runtime.events import eventmanager
 from app.runtime.extensions.plugin_manager import PluginManager
@@ -77,17 +76,12 @@ from app.db.oper.agenttask import AgentTaskOper
 from app.db.oper.user import UserOper
 from app.runtime.log import logger
 from app.schemas import AgentLLMProviderEventData, AgentTokensUsageEventData, Notification, NotificationType
+from app.schemas.agent import ReplyMode
 from app.schemas.message import ChannelCapabilityManager, ChannelCapability
 from app.schemas.types import ChainEventType, EventType, MessageChannel
 from app.foundation.identity import SYSTEM_INTERNAL_USER_ID
 
 
-class AgentChain(ChainBase):
-    """Agent 业务处理链。"""
-
-    pass
-
-
 def _finish_processing_status(status: Optional[dict], user_id: Optional[str] = None) -> None:
     """结束入站消息的渠道处理状态。"""
     if not status:
@@ -321,15 +315,6 @@ class _ThinkTagStripper:
             self.buffer = ""
 
 
-class ReplyMode(str, Enum):
-    """
-    Agent 最终回复处理模式。
-    """
-
-    DISPATCH = "dispatch"
-    CAPTURE_ONLY = "capture_only"
-
-
 HEARTBEAT_SESSION_PREFIX = "__agent_heartbeat_"
 UNSUPPORTED_IMAGE_INPUT_MESSAGE = "当前模型不支持图片输入，请更换支持图片输入的模型，或在系统设置中关闭图片输入支持后重试。"
 AGENT_EXECUTION_ERROR_PREFIX = "智能助手执行失败"

app/agent/tools/impl/_plugin_tool_utils.py

@@ -70,14 +70,14 @@ def reload_plugin_runtime(plugin_id: str) -> None:
     重载插件并重新注册其命令、定时任务和 API。
     """
     # 这些依赖只在真正执行重载时才导入，避免普通查询工具引入不必要的初始化开销。
-    from app.api.endpoints.plugin import register_plugin_api
-    from app.command import Command
-    from app.scheduler import Scheduler
+    from app.application.plugins import register_plugin_api
+    from app.application.commands import init_commands
+    from app.application.scheduling import update_plugin_job
 
     plugin_manager = PluginManager()
     plugin_manager.reload_plugin(plugin_id)
-    Scheduler().update_plugin_job(plugin_id)
-    Command().init_commands(plugin_id)
+    update_plugin_job(plugin_id)
+    init_commands(plugin_id)
     register_plugin_api(plugin_id)
 
 
@@ -333,8 +333,11 @@ async def uninstall_plugin_runtime(plugin_id: str) -> dict[str, Any]:
     """
     按现有卸载逻辑移除插件，并清理运行态注册与分组信息。
     """
-    from app.api.endpoints.plugin import _remove_plugin_from_folders, remove_plugin_api
-    from app.scheduler import Scheduler
+    from app.application.plugins import (
+        remove_plugin_api,
+        remove_plugin_from_folders,
+    )
+    from app.application.scheduling import remove_plugin_job
 
     config_oper = SystemConfigOper()
     install_plugins = config_oper.get(SystemConfigKey.UserInstalledPlugins) or []
@@ -343,7 +346,7 @@ async def uninstall_plugin_runtime(plugin_id: str) -> dict[str, Any]:
         await config_oper.async_set(SystemConfigKey.UserInstalledPlugins, install_plugins)
 
     remove_plugin_api(plugin_id)
-    Scheduler().remove_plugin_job(plugin_id)
+    remove_plugin_job(plugin_id)
 
     plugin_manager = PluginManager()
     plugin_class = plugin_manager.plugins.get(plugin_id)
@@ -362,7 +365,7 @@ async def uninstall_plugin_runtime(plugin_id: str) -> dict[str, Any]:
             except Exception:
                 clone_files_removed = False
 
-    _remove_plugin_from_folders(plugin_id)
+    remove_plugin_from_folders(plugin_id)
     plugin_manager.remove_plugin(plugin_id)
 
     return {

app/agent/tools/impl/create_agent_task.py

@@ -99,7 +99,7 @@ class CreateAgentTaskTool(MoviePilotTool):
 
     def _create_task(self, payload: CreateAgentTaskInput) -> dict:
         """持久化任务并立即注册到运行时调度器。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import update_agent_task_job
 
         trigger_value = payload.trigger
         if payload.trigger_type == "date" and payload.delay_minutes is not None:
@@ -130,8 +130,7 @@ class CreateAgentTaskTool(MoviePilotTool):
             source=self._source or (chat.source if chat else None),
             original_chat_id=chat.original_chat_id if chat else None,
         )
-        scheduler = Scheduler()
-        next_run_at = scheduler.update_agent_task_job(task.id)
+        next_run_at = update_agent_task_job(task.id)
         return AgentTaskOper.to_dict(
             task,
             next_run_at=next_run_at,

app/agent/tools/impl/delete_agent_task.py

@@ -31,14 +31,14 @@ class DeleteAgentTaskTool(MoviePilotTool):
 
     def _delete_task(self, task_id: int) -> bool:
         """删除当前用户的任务并移除运行时调度。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import remove_agent_task_job
 
         deleted = AgentTaskOper().delete(
             task_id=task_id,
             user_id=str(self._user_id),
         )
         if deleted:
-            Scheduler().remove_agent_task_job(task_id)
+            remove_agent_task_job(task_id)
         return deleted
 
     async def run(self, task_id: int, **kwargs: object) -> str:

app/agent/tools/impl/list_slash_commands.py

@@ -14,7 +14,6 @@ class ListSlashCommandsInput(BaseModel):
     """查询所有可用斜杠命令工具的输入参数模型"""
 
 
-
 class ListSlashCommandsTool(MoviePilotTool):
     name: str = "list_slash_commands"
     tags: list[str] = [
@@ -41,10 +40,9 @@ class ListSlashCommandsTool(MoviePilotTool):
         logger.info(f"执行工具: {self.name}")
 
         try:
-            from app.command import Command
+            from app.application.commands import get_commands
 
-            command_obj = Command()
-            all_commands = command_obj.get_commands()
+            all_commands = get_commands()
 
             if not all_commands:
                 return "当前没有可用的命令"

app/agent/tools/impl/query_agent_tasks.py

@@ -48,7 +48,7 @@ class QueryAgentTasksTool(MoviePilotTool):
             enabled: Optional[bool],
     ) -> list[dict]:
         """读取当前用户的任务及运行时下一次触发时间。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import get_agent_task_next_run
 
         oper = AgentTaskOper()
         if task_id:
@@ -56,12 +56,11 @@ class QueryAgentTasksTool(MoviePilotTool):
             tasks = [task] if task else []
         else:
             tasks = oper.list(user_id=str(self._user_id), enabled=enabled)
-        scheduler = Scheduler()
         result = []
         for task in tasks:
             data = oper.to_dict(
                 task,
-                next_run_at=scheduler.get_agent_task_next_run(task.id),
+                next_run_at=get_agent_task_next_run(task.id),
                 timezone=settings.TZ,
             )
             if task_id:

app/agent/tools/impl/query_schedulers.py

@@ -39,13 +39,15 @@ class QuerySchedulersTool(MoviePilotTool):
         """查询非 Agent 自主任务的运行时定时服务。"""
         logger.info(f"执行工具: {self.name}")
         try:
-            from app.scheduler import AGENT_TASK_JOB_PREFIX, Scheduler
+            from app.application.scheduling import (
+                AGENT_TASK_JOB_PREFIX,
+                list_scheduler_jobs,
+            )
 
-            scheduler = Scheduler()
             agent_task_prefix = f"{AGENT_TASK_JOB_PREFIX}-"
             schedulers = [
                 scheduler_item
-                for scheduler_item in scheduler.list()
+                for scheduler_item in list_scheduler_jobs()
                 if not str(scheduler_item.id or "").startswith(agent_task_prefix)
             ]
             if schedulers:

app/agent/tools/impl/run_agent_task.py

@@ -56,7 +56,7 @@ class RunAgentTaskTool(MoviePilotTool):
 
     async def run(self, task_id: int, **kwargs: object) -> str:
         """立即执行当前用户拥有且已启用的 Agent 自主定时任务。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import start_agent_task
 
         payload = RunAgentTaskInput(task_id=task_id)
         status, task_name = await self.run_blocking(
@@ -70,7 +70,7 @@ class RunAgentTaskTool(MoviePilotTool):
             return f"Agent 定时任务 {task_id} 已暂停，请先恢复后再执行"
         if status == "running":
             return f"Agent 定时任务 {task_id} 正在执行，请勿重复触发"
-        if not Scheduler().start_agent_task(payload.task_id):
+        if not start_agent_task(payload.task_id):
             return f"Agent 定时任务 {task_id} 尚未注册到运行时调度器，无法立即执行"
         return (
             f"Agent 定时任务 {task_id} 已提交立即执行：{task_name}。"

app/agent/tools/impl/run_scheduler.py

@@ -46,12 +46,14 @@ class RunSchedulerTool(MoviePilotTool):
     @staticmethod
     def _run_scheduler_sync(job_id: str) -> tuple[bool, str]:
         """同步触发定时服务，避免调度器扫描阻塞事件循环。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import (
+            list_scheduler_jobs,
+            start_scheduler_job,
+        )
 
-        scheduler = Scheduler()
-        for scheduler_item in scheduler.list():
+        for scheduler_item in list_scheduler_jobs():
             if scheduler_item.id == job_id:
-                scheduler.start(job_id)
+                start_scheduler_job(job_id)
                 return True, scheduler_item.name
         return False, ""
 
@@ -60,7 +62,7 @@ class RunSchedulerTool(MoviePilotTool):
         logger.info(f"执行工具: {self.name}, 参数: job_id={job_id}")
 
         try:
-            from app.scheduler import AGENT_TASK_JOB_PREFIX
+            from app.application.scheduling import AGENT_TASK_JOB_PREFIX
 
             if job_id.startswith(f"{AGENT_TASK_JOB_PREFIX}-"):
                 return (

app/agent/tools/impl/run_slash_command.py

@@ -57,16 +57,15 @@ class RunSlashCommandTool(MoviePilotTool):
             if not command.startswith("/"):
                 command = f"/{command}"
 
-            # 从全局 Command 单例中验证命令是否存在（包含系统预设命令 + 插件命令 + 其他命令）
-            from app.command import Command
+            # 从命令注册表中验证命令是否存在（包含系统预设命令 + 插件命令 + 其他命令）
+            from app.application.commands import get_command, get_commands
 
             cmd_name = command.split()[0]
-            command_obj = Command()
-            matched_command = command_obj.get(cmd_name)
+            matched_command = get_command(cmd_name)
 
             if not matched_command:
                 # 列出所有可用命令帮助用户
-                all_commands = command_obj.get_commands()
+                all_commands = get_commands()
                 available_cmds = [
                     f"{cmd} - {info.get('description', '无描述')}"
                     for cmd, info in all_commands.items()

app/agent/tools/impl/update_agent_task.py

@@ -100,7 +100,7 @@ class UpdateAgentTaskTool(MoviePilotTool):
 
     def _update_task(self, payload: UpdateAgentTaskInput) -> Optional[dict]:
         """更新当前用户的任务并刷新运行时调度。"""
-        from app.scheduler import Scheduler
+        from app.application.scheduling import update_agent_task_job
 
         oper = AgentTaskOper()
         task = oper.get(task_id=payload.task_id, user_id=str(self._user_id))
@@ -174,8 +174,7 @@ class UpdateAgentTaskTool(MoviePilotTool):
             if current and current.last_status == "running":
                 return {"error": f"Agent 定时任务 {payload.task_id} 正在执行，请稍后再修改"}
             return None
-        scheduler = Scheduler()
-        next_run_at = scheduler.update_agent_task_job(payload.task_id)
+        next_run_at = update_agent_task_job(payload.task_id)
         updated_task = oper.get(task_id=payload.task_id, user_id=str(self._user_id))
         return oper.to_dict(
             updated_task,

app/api/endpoints/plugin.py

@@ -12,7 +12,13 @@ from starlette.responses import StreamingResponse
 
 from app import schemas
 from app.api.response import ResponseAPIRouter
-from app.command import Command
+from app.application.plugins import (
+    register_plugin_api,
+    remove_plugin_api,
+    remove_plugin_from_folders,
+)
+from app.application.commands import init_commands
+from app.application.scheduling import remove_plugin_job, update_plugin_job
 from app.runtime.cache import async_fresh
 from app.runtime.config import settings
 from app.runtime.events import eventmanager
@@ -26,22 +32,12 @@ from app.application.security.access import (
 from app.db.models import User
 from app.db.oper.systemconfig import SystemConfigOper
 from app.api.deps import get_current_active_superuser, get_current_active_superuser_async
-from app.factory import app
 from app.adapters.external.server import MoviePilotServerHelper
 from app.adapters.external.market import PluginHelper
 from app.runtime.log import logger
-from app.scheduler import Scheduler
 from app.schemas.event import PluginDataResetEventData
 from app.schemas.types import ChainEventType, SystemConfigKey
 
-PROTECTED_ROUTES = {
-    "/api/v1/openapi.json",
-    "/docs",
-    "/docs/oauth2-redirect",
-    "/redoc",
-}
-PLUGIN_PREFIX = f"{settings.API_V1_STR}/plugin"
-
 router = ResponseAPIRouter()
 _plugin_release_refresh_tasks: set[asyncio.Task] = set()
 
@@ -106,117 +102,14 @@ def _schedule_plugin_release_refresh(plugin_id: str, repo_url: str) -> None:
     task.add_done_callback(_discard_task)
 
 
-def register_plugin_api(plugin_id: Optional[str] = None):
-    """
-    动态注册插件 API
-    :param plugin_id: 插件 ID，如果为 None，则注册所有插件
-    """
-    _update_plugin_api_routes(plugin_id, action="add")
-
-
-def remove_plugin_api(plugin_id: str):
-    """
-    动态移除单个插件的 API
-    :param plugin_id: 插件 ID
-    """
-    _update_plugin_api_routes(plugin_id, action="remove")
-
-
-def _update_plugin_api_routes(plugin_id: Optional[str], action: str):
-    """
-    插件 API 路由注册和移除
-    :param plugin_id: 插件 ID，如果 action 为 "add" 且 plugin_id 为 None，则处理所有插件
-                      如果 action 为 "remove"，plugin_id 必须是有效的插件 ID
-    :param action: "add" 或 "remove"，决定是添加还是移除路由
-    """
-    if action not in {"add", "remove"}:
-        raise ValueError("Action must be 'add' or 'remove'")
-
-    is_modified = False
-    existing_paths = {route.path: route for route in app.routes}
-
-    plugin_ids = [plugin_id] if plugin_id else PluginManager().get_running_plugin_ids()
-    for plugin_id in plugin_ids:
-        routes_removed = _remove_routes(plugin_id)
-        if routes_removed:
-            is_modified = True
-
-        if action != "add":
-            continue
-        # 获取插件的 API 路由信息
-        plugin_apis = PluginManager().get_plugin_apis(plugin_id)
-        for api in plugin_apis:
-            api_path = f"{PLUGIN_PREFIX}{api.get('path', '')}"
-            try:
-                api["path"] = api_path
-                allow_anonymous = api.pop("allow_anonymous", False)
-                auth_mode = api.pop("auth", "apikey")
-                dependencies = api.setdefault("dependencies", [])
-                if not allow_anonymous:
-                    if (
-                        auth_mode == "bear"
-                        and Depends(verify_token) not in dependencies
-                    ):
-                        dependencies.append(Depends(verify_token))
-                    elif Depends(verify_apikey) not in dependencies:
-                        dependencies.append(Depends(verify_apikey))
-                app.add_api_route(**api, tags=["plugin"])
-                is_modified = True
-                logger.debug(f"Added plugin route: {api_path}")
-            except Exception as e:
-                logger.error(f"Error adding plugin route {api_path}: {str(e)}")
-
-    if is_modified:
-        _clean_protected_routes(existing_paths)
-        app.openapi_schema = None
-        app.setup()
-
-
-def _remove_routes(plugin_id: str) -> bool:
-    """
-    移除与单个插件相关的路由
-    :param plugin_id: 插件 ID
-    :return: 是否有路由被移除
-    """
-    if not plugin_id:
-        return False
-    prefix = f"{PLUGIN_PREFIX}/{plugin_id}/"
-    routes_to_remove = [
-        route for route in app.routes if route.path.startswith(prefix)
-    ]
-    removed = False
-    for route in routes_to_remove:
-        try:
-            app.routes.remove(route)
-            removed = True
-            logger.debug(f"Removed plugin route: {route.path}")
-        except Exception as e:
-            logger.error(f"Error removing plugin route {route.path}: {str(e)}")
-    return removed
-
-
-def _clean_protected_routes(existing_paths: dict):
-    """
-    清理受保护的路由，防止在插件操作中被删除或重复添加
-    :param existing_paths: 当前应用的路由路径映射
-    """
-    for protected_route in PROTECTED_ROUTES:
-        try:
-            existing_route = existing_paths.get(protected_route)
-            if existing_route:
-                app.routes.remove(existing_route)
-        except Exception as e:
-            logger.error(f"Error removing protected route {protected_route}: {str(e)}")
-
-
 def register_plugin(plugin_id: str):
     """
     注册一个插件相关的服务
     """
     # 注册插件服务
-    Scheduler().update_plugin_job(plugin_id)
+    update_plugin_job(plugin_id)
     # 注册菜单命令
-    Command().init_commands(plugin_id)
+    init_commands(plugin_id)
     # 注册插件API
     register_plugin_api(plugin_id)
 
@@ -1045,7 +938,7 @@ def uninstall_plugin(
     # 移除插件API
     remove_plugin_api(plugin_id)
     # 移除插件服务
-    Scheduler().remove_plugin_job(plugin_id)
+    remove_plugin_job(plugin_id)
     # 判断是否为分身
     plugin_manager = PluginManager()
     plugin_class = plugin_manager.plugins.get(plugin_id)
@@ -1062,7 +955,7 @@ def uninstall_plugin(
             except Exception as e:
                 logger.error(f"删除插件分身目录 {plugin_base_dir} 失败: {str(e)}")
     # 从插件文件夹中移除该插件
-    _remove_plugin_from_folders(plugin_id)
+    remove_plugin_from_folders(plugin_id)
     # 移除插件
     plugin_manager.remove_plugin(plugin_id)
     return schemas.Response(success=True)
@@ -1121,42 +1014,3 @@ def _add_clone_to_plugin_folder(original_plugin_id: str, clone_plugin_id: str):
     except Exception as e:
         logger.error(f"处理插件文件夹时出错：{str(e)}")
         # 文件夹处理失败不影响插件分身创建的整体流程
-
-
-def _remove_plugin_from_folders(plugin_id: str):
-    """
-    从所有文件夹中移除指定的插件
-    :param plugin_id: 要移除的插件ID
-    """
-    try:
-        config_oper = SystemConfigOper()
-        # 获取插件文件夹配置
-        folders = config_oper.get(SystemConfigKey.PluginFolders) or {}
-
-        # 标记是否有修改
-        modified = False
-
-        # 遍历所有文件夹，移除指定插件
-        for folder_name, folder_data in folders.items():
-            if isinstance(folder_data, dict) and "plugins" in folder_data:
-                # 新格式：{"plugins": [...], "order": ..., "icon": ...}
-                if plugin_id in folder_data["plugins"]:
-                    folder_data["plugins"].remove(plugin_id)
-                    logger.info(f"已从文件夹 '{folder_name}' 中移除插件 {plugin_id}")
-                    modified = True
-            elif isinstance(folder_data, list):
-                # 旧格式：直接是插件列表
-                if plugin_id in folder_data:
-                    folder_data.remove(plugin_id)
-                    logger.info(f"已从文件夹 '{folder_name}' 中移除插件 {plugin_id}")
-                    modified = True
-
-        # 如果有修改，保存更新后的文件夹配置
-        if modified:
-            config_oper.set(SystemConfigKey.PluginFolders, folders)
-        else:
-            logger.debug(f"插件 {plugin_id} 不在任何文件夹中，无需移除")
-
-    except Exception as e:
-        logger.error(f"从文件夹中移除插件时出错：{str(e)}")
-        # 文件夹处理失败不影响插件卸载的整体流程

app/application/agent.py

@@ -0,0 +1,100 @@
+"""Agent 编排服务门面。
+
+chain 层需要触发 Agent 后台任务、渲染提示词、查询模型能力时统一经本模块调用。
+具体实现由 app.agent 在启动时注册，形成依赖倒置：
+
+    chain -> application.agent <- agent（startup 在导入期注册）
+
+静态依赖图上 application 不依赖 agent，agent 作为入口层向 application
+注册实现，从而拆除 chain <-> agent 的互指环。
+
+注意：本模块禁止静态导入 app.agent 下的任何模块（含函数内导入），
+否则会形成 agent -> chain -> application -> agent 的新环。
+未注册时的兜底注册由 startup/agent_initializer 在导入期完成。
+"""
+
+from typing import Any, Callable, Optional
+
+# 注册表：启动期由 startup/agent_initializer 填充。
+_agent_manager: Any = None
+_prompt_manager: Any = None
+_agent_capability_manager: Any = None
+_llm_helper: Any = None
+_manual_redo_prompt_builder: Optional[Callable[[Any], str]] = None
+
+
+def register_agent_services(
+        agent_manager: Any,
+        prompt_manager: Any,
+        capability_manager: Any,
+        llm_helper: Any,
+        manual_redo_prompt_builder: Optional[Callable[[Any], str]] = None,
+) -> None:
+    """注册 Agent 服务实现（由 startup 组合根在导入期调用）。"""
+    global _agent_manager, _prompt_manager, _agent_capability_manager, _llm_helper
+    global _manual_redo_prompt_builder
+    _agent_manager = agent_manager
+    _prompt_manager = prompt_manager
+    _agent_capability_manager = capability_manager
+    _llm_helper = llm_helper
+    _manual_redo_prompt_builder = manual_redo_prompt_builder
+
+
+def _ensure_registered() -> None:
+    """校验 Agent 服务已注册。
+
+    正常启动路径由 startup/agent_initializer 在导入期注册；未注册时
+    直接抛出带指引的错误，避免在此处静态导入 app.agent 破坏依赖方向。
+    """
+    if _agent_manager is None:
+        raise RuntimeError(
+            "Agent 服务未注册：请先导入 app.startup.agent_initializer 完成组合根装配"
+        )
+
+
+def get_agent_manager() -> Any:
+    """返回 AgentManager 单例。"""
+    _ensure_registered()
+    return _agent_manager
+
+
+def get_prompt_manager() -> Any:
+    """返回提示词管理器。"""
+    _ensure_registered()
+    return _prompt_manager
+
+
+def supports_image_input(
+        provider: Optional[str] = None,
+        model: Optional[str] = None,
+        base_url: Optional[str] = None,
+        base_url_preset: Optional[str] = None,
+) -> bool:
+    """判断当前模型是否启用了图片输入能力。"""
+    _ensure_registered()
+    return _llm_helper.supports_image_input(
+        provider=provider,
+        model=model,
+        base_url=base_url,
+        base_url_preset=base_url_preset,
+    )
+
+
+def is_audio_input_available() -> bool:
+    """判断语音输入能力是否可用。"""
+    _ensure_registered()
+    return _agent_capability_manager.is_audio_input_available()
+
+
+def transcribe_audio(content: bytes, filename: str = "input.ogg") -> Optional[str]:
+    """把音频内容转写为文本。"""
+    _ensure_registered()
+    return _agent_capability_manager.transcribe_audio(content, filename=filename)
+
+
+def build_manual_redo_prompt(history: Any) -> str:
+    """构造整理记录 AI 重新整理提示词（builder 由 agent 层注册）。"""
+    _ensure_registered()
+    if _manual_redo_prompt_builder is None:
+        raise RuntimeError("整理记录重新整理提示词构建器未注册")
+    return _manual_redo_prompt_builder(history)

app/application/commands.py

@@ -0,0 +1,45 @@
+"""命令工具服务门面。
+
+Agent 工具与 API 端点对命令注册表的操作统一经本模块调用，
+Command 实现由 startup 组合根在导入期注册，避免 application 层
+静态依赖顶层 command 模块。
+
+依赖方向：
+
+    agent.tools / api.endpoints -> application.commands <- startup（注册 Command 类）
+"""
+
+from typing import Any, Dict, Optional
+
+# Command 类：由 startup/command_initializer 在导入期注册。
+_command_class: Any = None
+
+
+def register_command_class(command_class: Any) -> None:
+    """注册 Command 类（组合根在导入期调用）。"""
+    global _command_class
+    _command_class = command_class
+
+
+def get_command_object() -> Any:
+    """返回命令注册表实例。"""
+    if _command_class is None:
+        raise RuntimeError(
+            "命令服务未初始化：请先通过 register_command_class 注册 Command 类"
+        )
+    return _command_class()
+
+
+def get_commands() -> Dict[str, Any]:
+    """返回全部已注册命令。"""
+    return get_command_object().get_commands()
+
+
+def get_command(name: str) -> Optional[Any]:
+    """按命令名查询注册表。"""
+    return get_command_object().get(name)
+
+
+def init_commands(plugin_id: Optional[str] = None) -> None:
+    """初始化命令（可指定单个插件）。"""
+    get_command_object().init_commands(plugin_id)

app/application/plugins.py

@@ -0,0 +1,190 @@
+"""插件 API 动态路由服务。
+
+把插件 API 的动态注册/移除从 HTTP 端点层下沉到 application 层：
+FastAPI 实例由组合根（factory 创建应用后）注入，端点与 Agent 工具
+统一经本模块操作路由，消除 api.endpoints 对 factory 的反向依赖。
+
+依赖方向：
+
+    api.endpoints.plugin / agent.tools -> application.plugins <- factory（注入实例）
+"""
+
+from typing import Optional
+
+from fastapi import Depends, FastAPI
+
+from app.application.security.access import verify_apikey, verify_token
+from app.db.oper.systemconfig import SystemConfigOper
+from app.runtime.config import settings
+from app.runtime.extensions.plugin_manager import PluginManager
+from app.runtime.log import logger
+from app.schemas.types import SystemConfigKey
+
+PROTECTED_ROUTES = {
+    "/api/v1/openapi.json",
+    "/docs",
+    "/docs/oauth2-redirect",
+    "/redoc",
+}
+PLUGIN_PREFIX = f"{settings.API_V1_STR}/plugin"
+
+# FastAPI 应用实例：由 factory 在创建应用后调用 register_api_app 注入。
+_api_app: Optional[FastAPI] = None
+
+
+def register_api_app(api_app: FastAPI) -> None:
+    """注入 FastAPI 应用实例（组合根在创建应用后调用）。"""
+    global _api_app
+    _api_app = api_app
+
+
+def get_api_app() -> FastAPI:
+    """返回已注入的 FastAPI 应用实例。"""
+    if _api_app is None:
+        raise RuntimeError("插件路由服务未初始化：请先调用 register_api_app 注入应用实例")
+    return _api_app
+
+
+def register_plugin_api(plugin_id: Optional[str] = None):
+    """
+    动态注册插件 API
+    :param plugin_id: 插件 ID，如果为 None，则注册所有插件
+    """
+    _update_plugin_api_routes(plugin_id, action="add")
+
+
+def remove_plugin_api(plugin_id: str):
+    """
+    动态移除单个插件的 API
+    :param plugin_id: 插件 ID
+    """
+    _update_plugin_api_routes(plugin_id, action="remove")
+
+
+def _update_plugin_api_routes(plugin_id: Optional[str], action: str):
+    """
+    插件 API 路由注册和移除
+    :param plugin_id: 插件 ID，如果 action 为 "add" 且 plugin_id 为 None，则处理所有插件
+                      如果 action 为 "remove"，plugin_id 必须是有效的插件 ID
+    :param action: "add" 或 "remove"，决定是添加还是移除路由
+    """
+    if action not in {"add", "remove"}:
+        raise ValueError("Action must be 'add' or 'remove'")
+
+    app = get_api_app()
+    is_modified = False
+    existing_paths = {route.path: route for route in app.routes}
+
+    plugin_ids = [plugin_id] if plugin_id else PluginManager().get_running_plugin_ids()
+    for plugin_id in plugin_ids:
+        routes_removed = _remove_routes(plugin_id)
+        if routes_removed:
+            is_modified = True
+
+        if action != "add":
+            continue
+        # 获取插件的 API 路由信息
+        plugin_apis = PluginManager().get_plugin_apis(plugin_id)
+        for api in plugin_apis:
+            api_path = f"{PLUGIN_PREFIX}{api.get('path', '')}"
+            try:
+                api["path"] = api_path
+                allow_anonymous = api.pop("allow_anonymous", False)
+                auth_mode = api.pop("auth", "apikey")
+                dependencies = api.setdefault("dependencies", [])
+                if not allow_anonymous:
+                    if (
+                        auth_mode == "bear"
+                        and Depends(verify_token) not in dependencies
+                    ):
+                        dependencies.append(Depends(verify_token))
+                    elif Depends(verify_apikey) not in dependencies:
+                        dependencies.append(Depends(verify_apikey))
+                app.add_api_route(**api, tags=["plugin"])
+                is_modified = True
+                logger.debug(f"Added plugin route: {api_path}")
+            except Exception as e:
+                logger.error(f"Error adding plugin route {api_path}: {str(e)}")
+
+    if is_modified:
+        _clean_protected_routes(existing_paths)
+        app.openapi_schema = None
+        app.setup()
+
+
+def _remove_routes(plugin_id: str) -> bool:
+    """
+    移除与单个插件相关的路由
+    :param plugin_id: 插件 ID
+    :return: 是否有路由被移除
+    """
+    if not plugin_id:
+        return False
+    app = get_api_app()
+    prefix = f"{PLUGIN_PREFIX}/{plugin_id}/"
+    routes_to_remove = [
+        route for route in app.routes if route.path.startswith(prefix)
+    ]
+    removed = False
+    for route in routes_to_remove:
+        try:
+            app.routes.remove(route)
+            removed = True
+            logger.debug(f"Removed plugin route: {route.path}")
+        except Exception as e:
+            logger.error(f"Error removing plugin route {route.path}: {str(e)}")
+    return removed
+
+
+def _clean_protected_routes(existing_paths: dict):
+    """
+    清理受保护的路由，防止在插件操作中被删除或重复添加
+    :param existing_paths: 当前应用的路由路径映射
+    """
+    app = get_api_app()
+    for protected_route in PROTECTED_ROUTES:
+        try:
+            existing_route = existing_paths.get(protected_route)
+            if existing_route:
+                app.routes.remove(existing_route)
+        except Exception as e:
+            logger.error(f"Error removing protected route {protected_route}: {str(e)}")
+
+
+def remove_plugin_from_folders(plugin_id: str):
+    """
+    从所有文件夹中移除指定的插件
+    :param plugin_id: 要移除的插件ID
+    """
+    try:
+        config_oper = SystemConfigOper()
+        # 获取插件文件夹配置
+        folders = config_oper.get(SystemConfigKey.PluginFolders) or {}
+
+        # 标记是否有修改
+        modified = False
+
+        # 遍历所有文件夹，移除指定插件
+        for folder_name, folder_data in folders.items():
+            if isinstance(folder_data, dict) and "plugins" in folder_data:
+                # 新格式：{"plugins": [...], "order": ..., "icon": ...}
+                if plugin_id in folder_data["plugins"]:
+                    folder_data["plugins"].remove(plugin_id)
+                    logger.info(f"已从文件夹 '{folder_name}' 中移除插件 {plugin_id}")
+                    modified = True
+            elif isinstance(folder_data, list):
+                # 旧格式：直接是插件列表
+                if plugin_id in folder_data:
+                    folder_data.remove(plugin_id)
+                    logger.info(f"已从文件夹 '{folder_name}' 中移除插件 {plugin_id}")
+                    modified = True
+
+        # 如果有修改，保存更新后的文件夹配置
+        if modified:
+            config_oper.set(SystemConfigKey.PluginFolders, folders)
+        else:
+            logger.debug(f"插件 {plugin_id} 不在任何文件夹中，无需移除")
+
+    except Exception as e:
+        logger.error(f"从文件夹中移除插件时出错：{str(e)}")
+        # 文件夹处理失败不影响插件卸载的整体流程

app/application/scheduling.py

@@ -0,0 +1,73 @@
+"""调度器工具服务门面。
+
+Agent 工具与 API 端点对运行时调度器的操作统一经本模块调用，
+Scheduler 实现由 startup 组合根在导入期注册，避免 application 层
+静态依赖顶层 scheduler 模块（scheduler 反向依赖 chain，会成环）。
+
+依赖方向：
+
+    agent.tools / api.endpoints -> application.scheduling <- startup（注册 Scheduler 类）
+"""
+
+from typing import Any, List, Optional
+
+# Agent 自主定时任务在运行时调度器中的任务 ID 前缀。
+AGENT_TASK_JOB_PREFIX = "agent-task"
+
+# Scheduler 类：由 startup/scheduler_initializer 在导入期注册。
+_scheduler_class: Any = None
+
+
+def register_scheduler_class(scheduler_class: Any) -> None:
+    """注册 Scheduler 类（组合根在导入期调用）。"""
+    global _scheduler_class
+    _scheduler_class = scheduler_class
+
+
+def get_scheduler() -> Any:
+    """返回调度器实例。"""
+    if _scheduler_class is None:
+        raise RuntimeError(
+            "调度器服务未初始化：请先通过 register_scheduler_class 注册 Scheduler 类"
+        )
+    return _scheduler_class()
+
+
+def list_scheduler_jobs() -> List[Any]:
+    """列出运行时调度器的全部任务。"""
+    return get_scheduler().list()
+
+
+def start_scheduler_job(job_id: str) -> None:
+    """立即运行指定的运行时定时任务。"""
+    get_scheduler().start(job_id)
+
+
+def update_plugin_job(plugin_id: str) -> None:
+    """更新插件的定时任务。"""
+    get_scheduler().update_plugin_job(plugin_id)
+
+
+def remove_plugin_job(plugin_id: str) -> None:
+    """移除插件的定时任务。"""
+    get_scheduler().remove_plugin_job(plugin_id)
+
+
+def start_agent_task(task_id: int) -> bool:
+    """立即执行 Agent 自主定时任务。"""
+    return get_scheduler().start_agent_task(task_id)
+
+
+def get_agent_task_next_run(task_id: int) -> Optional[Any]:
+    """查询 Agent 自主定时任务的下一次运行时间。"""
+    return get_scheduler().get_agent_task_next_run(task_id)
+
+
+def update_agent_task_job(task_id: int) -> Optional[Any]:
+    """更新 Agent 自主定时任务的注册信息，返回下一次运行时间。"""
+    return get_scheduler().update_agent_task_job(task_id)
+
+
+def remove_agent_task_job(task_id: int) -> None:
+    """移除 Agent 自主定时任务的注册信息。"""
+    get_scheduler().remove_agent_task_job(task_id)

app/application/transfer.py

@@ -13,20 +13,38 @@ app.schemas -> app.schemas.transfer -> app.domain.* -> app.schemas.types -> app.
 TransferJob / TransferJobTask，那两个用 app.schemas 的同名 DTO——一个是工作项，一个是
 视图，分开表达之后两边都不必再迁就对方。
 """
+import asyncio
+import threading
+from copy import deepcopy
 from pathlib import Path
-from typing import Callable, List, Optional, Union
+from time import monotonic
+from typing import Callable, Dict, List, Optional, Tuple, Union
 
 from pydantic import BaseModel, ConfigDict
 
+from app import schemas
+from app.adapters.system.host import SystemUtils
+from app.application.agent import get_agent_manager, get_prompt_manager
 from app.domain.context import MediaInfo, MusicInfo
+from app.domain.media import normalize_music_type
 from app.domain.meta.metabase import MetaBase
+from app.domain.meta.metamusic import MetaMusic
+from app.foundation import text as text_tools
+from app.runtime.log import logger
+from app.schemas.agent import ReplyMode
 from app.schemas.file import FileItem
 from app.schemas.history import DownloadHistory
-from app.schemas.media import OptionalMediaIdentityMixin
+from app.schemas.media import OptionalMediaIdentityMixin, resolve_media_identity
 from app.schemas.system import TransferDirectoryConf
 from app.schemas.tmdb import TmdbEpisode
-from app.schemas.transfer import TransferInfo
-from app.schemas.types import MediaSource, MediaType
+from app.schemas.transfer import TransferInfo, TransferJob, TransferJobTask
+from app.schemas.types import (
+    MUSIC_ENTITY_ALBUM,
+    MUSIC_ENTITY_RECORDING,
+    MediaSource,
+    MediaType,
+)
+
 
 
 class TransferTask(OptionalMediaIdentityMixin, BaseModel):
@@ -89,3 +107,869 @@ class TransferQueue(BaseModel):
     callback: Optional[Callable] = None
     # 整理结果
     result: Optional[TransferInfo] = None
+
+
+# 作业锁：JobManager 与 TransferChain 共享，保护整理作业视图。
+job_lock = threading.Lock()
+
+class JobManager:
+    """
+    作业管理器
+    task任务负责一个文件的整理，job作业负责一个媒体的整理
+    """
+
+    # 整理中的作业
+    _job_view: Dict[Tuple, TransferJob] = {}
+    # 汇总季集清单
+    _season_episodes: Dict[Tuple, List[int]] = {}
+    # 记录从 meta 作业迁移到 media 作业的关系，用于清理提前失败后残留的 media 作业
+    _meta_to_media_ids: Dict[Tuple, set[Tuple]] = {}
+    # 记录任务最近一次状态心跳，供外部异步接管任务的失活检测使用
+    _task_state_changed_at: Dict[Tuple[str, str], float] = {}
+    # 记录仍由主程序整理线程直接执行的任务，避免把阻塞中的本地任务误判为失活
+    _active_executions: set[Tuple[str, str]] = set()
+
+    def __init__(self):
+        self._job_view = {}
+        self._season_episodes = {}
+        self._meta_to_media_ids = {}
+        self._task_state_changed_at = {}
+        self._active_executions = set()
+
+    @staticmethod
+    def __get_meta_id(meta: MetaBase = None, season: Optional[int] = None) -> Tuple:
+        """
+        获取元数据ID
+        """
+        return meta.name, season
+
+    @staticmethod
+    def __get_media_id(media: Optional[Union[MediaInfo, MusicInfo]] = None,
+                       season: Optional[int] = None) -> Tuple:
+        """
+        获取媒体ID；音乐额外区分实体类型，并为无远端ID的曲目构造稳定身份。
+        """
+        if not media:
+            return None, season
+        source, media_id = resolve_media_identity(media=media)
+        if getattr(media, "type", None) == MediaType.MUSIC:
+            music_type = normalize_music_type(
+                getattr(media, "music_type", None),
+            ) or MUSIC_ENTITY_RECORDING
+            if source and media_id:
+                return "music", source, media_id, music_type
+
+            artists = tuple(
+                text_tools.normalize_upper(artist)
+                for artist in (getattr(media, "artists", None) or [])
+                if text_tools.normalize_upper(artist)
+            )
+            if music_type == MUSIC_ENTITY_ALBUM:
+                album_artist = text_tools.normalize_upper(
+                    getattr(media, "album_artist", None)
+                    or (artists[0] if artists else "")
+                )
+                album = text_tools.normalize_upper(
+                    getattr(media, "album", None) or getattr(media, "title", None) or ""
+                )
+                return "music", "local", music_type, album_artist, album, getattr(media, "year", None)
+
+            return (
+                "music",
+                "local",
+                music_type,
+                artists,
+                text_tools.normalize_upper(getattr(media, "title", None) or ""),
+                text_tools.normalize_upper(getattr(media, "album", None) or ""),
+                getattr(media, "disc_number", None),
+                getattr(media, "track_number", None),
+            )
+        return (source, media_id), season
+
+    @staticmethod
+    def __get_file_key(fileitem: FileItem) -> Optional[Tuple[str, str]]:
+        """
+        获取源文件唯一键，用于跨媒体作业识别同一个整理任务。
+        """
+        if not fileitem or not fileitem.path:
+            return None
+        normalized_path = (
+            Path(str(fileitem.path).replace("\\", "/")).as_posix().rstrip("/") or "/"
+        )
+        return fileitem.storage or "local", normalized_path
+
+    def __get_id(self, task: TransferTask = None) -> Tuple:
+        """
+        获取作业ID
+        """
+        if task.mediainfo:
+            return self.__get_media_id(
+                media=task.mediainfo, season=task.meta.begin_season
+            )
+        else:
+            return self.__get_meta_id(meta=task.meta, season=task.meta.begin_season)
+
+    def get_job_id(self, task: TransferTask) -> Tuple:
+        """返回任务当前所属的稳定作业身份，供作业级附加状态隔离使用。"""
+        return self.__get_id(task)
+
+    @staticmethod
+    def __get_media(task: TransferTask) -> Union[schemas.MediaInfo, schemas.MusicInfo]:
+        """
+        获取媒体信息
+        """
+        if task.mediainfo:
+            # 有媒体信息
+            mediainfo = deepcopy(task.mediainfo)
+            mediainfo.clear()
+            if isinstance(mediainfo, MusicInfo):
+                return schemas.MusicInfo(**mediainfo.to_dict())
+            return schemas.MediaInfo(**mediainfo.to_dict())
+        else:
+            # 没有媒体信息
+            meta: MetaBase = task.meta
+            if isinstance(meta, MetaMusic):
+                # 未识别的音乐按已解析元数据兜底展示；音乐年份为 int，
+                # 不能复用 MediaInfo（year 为 str），否则触发 pydantic 校验异常
+                return schemas.MusicInfo(
+                    title=meta.name,
+                    artists=list(meta.artists or []),
+                    artist=meta.artist,
+                    album=meta.album,
+                    album_artist=meta.album_artist,
+                    year=meta.year,
+                    title_year=f"{meta.name} ({meta.year})" if meta.year else meta.name,
+                    media_source=meta.media_source,
+                    media_id=meta.media_id,
+                )
+            return schemas.MediaInfo(
+                title=meta.name,
+                year=meta.year,
+                title_year=f"{meta.name} ({meta.year})",
+                type=meta.type.value if meta.type else None,
+            )
+
+    @staticmethod
+    def __get_meta(task: TransferTask) -> schemas.MetaInfo:
+        """
+        获取元数据
+        """
+        if isinstance(task.meta, MetaMusic):
+            return schemas.MusicMeta(**task.meta.to_dict())
+        return schemas.MetaInfo(**task.meta.to_dict())
+
+    def add_task(self, task: TransferTask, state: Optional[str] = "waiting") -> bool:
+        """
+        添加整理任务，自动分组到对应的作业中
+        :return: True表示任务已添加，False表示任务无效或已存在（重复）
+        """
+        if not all([task, task.meta, task.fileitem]):
+            return False
+        file_key = self.__get_file_key(task.fileitem)
+        if not file_key:
+            return False
+        with job_lock:
+            __mediaid__ = self.__get_id(task)
+            # 同一个源文件可能在识别前后落入不同作业，必须跨作业去重。
+            if any(
+                    self.__get_file_key(t.fileitem) == file_key
+                    for job in self._job_view.values()
+                    for t in job.tasks
+            ):
+                logger.debug(f"任务 {task.fileitem.name} 已存在，跳过重复添加")
+                return False
+            if __mediaid__ not in self._job_view:
+                self._job_view[__mediaid__] = TransferJob(
+                    media=self.__get_media(task),
+                    season=task.meta.begin_season,
+                    tasks=[
+                        TransferJobTask(
+                            fileitem=task.fileitem,
+                            meta=self.__get_meta(task),
+                            downloader=task.downloader,
+                            download_hash=task.download_hash,
+                            state=state,
+                        )
+                    ],
+                )
+            else:
+                # 不重复添加任务
+                if any(
+                        [
+                            self.__get_file_key(t.fileitem) == file_key
+                            for t in self._job_view[__mediaid__].tasks
+                        ]
+                ):
+                    logger.debug(f"任务 {task.fileitem.name} 已存在，跳过重复添加")
+                    return False
+                self._job_view[__mediaid__].tasks.append(
+                    TransferJobTask(
+                        fileitem=task.fileitem,
+                        meta=self.__get_meta(task),
+                        downloader=task.downloader,
+                        download_hash=task.download_hash,
+                        state=state,
+                    )
+                )
+            self._task_state_changed_at[file_key] = monotonic()
+            # 添加季集信息
+            if self._season_episodes.get(__mediaid__):
+                self._season_episodes[__mediaid__].extend(task.meta.episode_list)
+                self._season_episodes[__mediaid__] = list(
+                    set(self._season_episodes[__mediaid__])
+                )
+            else:
+                self._season_episodes[__mediaid__] = task.meta.episode_list
+            return True
+
+    def migrate_task(self, task: TransferTask) -> bool:
+        """
+        将任务从 meta 作业迁移到 media 作业
+        """
+        curr_task, source_job_id = self.__remove_task_with_job_id(
+            task.fileitem, preserve_execution=True
+        )
+        if not self.add_task(task, state=curr_task.state if curr_task else "waiting"):
+            return False
+        if curr_task and task.mediainfo:
+            metaid = self.__get_meta_id(
+                meta=task.meta, season=task.meta.begin_season
+            )
+            mediaid = self.__get_id(task)
+            if source_job_id == metaid and mediaid != metaid:
+                with job_lock:
+                    self._meta_to_media_ids.setdefault(metaid, set()).add(mediaid)
+        return True
+
+    def __is_job_done(self, job_id: Tuple) -> bool:
+        """
+        检查指定作业是否已完成
+        """
+        if job_id not in self._job_view:
+            return True
+        return all(
+            task.state in ["completed", "failed"]
+            for task in self._job_view[job_id].tasks
+        )
+
+    def __pop_job(self, job_id: Tuple):
+        """
+        移除指定作业和对应季集缓存
+        """
+        job = self._job_view.pop(job_id, None)
+        self._season_episodes.pop(job_id, None)
+        if not job:
+            return
+        for task in job.tasks:
+            file_key = self.__get_file_key(task.fileitem)
+            if file_key:
+                self._task_state_changed_at.pop(file_key, None)
+                self._active_executions.discard(file_key)
+
+    def __remove_done_job_groups(self, job_ids: set[Tuple]):
+        """
+        清理已进入终态的独立作业或关联作业组。
+        """
+        candidates = set(job_ids)
+        for metaid, mediaids in list(self._meta_to_media_ids.items()):
+            related_ids = {metaid, *mediaids}
+            if not related_ids.intersection(candidates):
+                continue
+            if all(self.__is_job_done(job_id) for job_id in related_ids):
+                for job_id in related_ids:
+                    self.__pop_job(job_id)
+                self._meta_to_media_ids.pop(metaid, None)
+                candidates.difference_update(related_ids)
+
+        referenced_ids = {
+            job_id
+            for metaid, mediaids in self._meta_to_media_ids.items()
+            for job_id in {metaid, *mediaids}
+        }
+        for job_id in candidates - referenced_ids:
+            if self.__is_job_done(job_id):
+                self.__pop_job(job_id)
+
+    def start_execution(self, task: TransferTask):
+        """
+        标记任务仍由主程序整理线程直接执行。
+
+        :param task: 整理任务
+        """
+        if not task or not task.fileitem:
+            return
+        file_key = self.__get_file_key(task.fileitem)
+        if not file_key:
+            return
+        with job_lock:
+            self._active_executions.add(file_key)
+
+    def finish_execution(self, task: TransferTask):
+        """
+        结束主程序整理线程对任务的直接执行标记。
+
+        :param task: 整理任务
+        """
+        if not task or not task.fileitem:
+            return
+        file_key = self.__get_file_key(task.fileitem)
+        if not file_key:
+            return
+        with job_lock:
+            self._active_executions.discard(file_key)
+
+    def expire_stale_running_tasks(
+            self, timeout_seconds: int
+    ) -> List[Tuple[FileItem, int]]:
+        """
+        将外部接管后长期无心跳的运行中任务标记失败并清理作业视图。
+
+        主程序整理线程仍在直接执行的任务不会被清理，以免把阻塞中的真实任务
+        误报为已终止。外部接管方可重复调用 ``running_task`` 刷新状态心跳。
+
+        :param timeout_seconds: 失活超时秒数，小于等于 0 时禁用
+        :return: 已失活任务及其无心跳秒数
+        """
+        if timeout_seconds <= 0:
+            return []
+
+        current_time = monotonic()
+        expired: List[Tuple[FileItem, int]] = []
+        affected_job_ids: set[Tuple] = set()
+        with job_lock:
+            for mediaid, job in self._job_view.items():
+                for task in job.tasks:
+                    file_key = self.__get_file_key(task.fileitem)
+                    if (
+                            not file_key
+                            or task.state != "running"
+                            or file_key in self._active_executions
+                    ):
+                        continue
+                    updated_at = self._task_state_changed_at.get(file_key, current_time)
+                    inactive_seconds = current_time - updated_at
+                    if inactive_seconds < timeout_seconds:
+                        continue
+                    task.state = "failed"
+                    self._task_state_changed_at[file_key] = current_time
+                    episodes = getattr(task.meta, "episode_list", None) or []
+                    if mediaid in self._season_episodes:
+                        self._season_episodes[mediaid] = list(
+                            set(self._season_episodes[mediaid]) - set(episodes)
+                        )
+                    expired.append((task.fileitem, int(inactive_seconds)))
+                    affected_job_ids.add(mediaid)
+
+            self.__remove_done_job_groups(affected_job_ids)
+        return expired
+
+    def running_task(self, task: TransferTask):
+        """
+        设置任务为运行中，并刷新外部异步任务的状态心跳。
+        """
+        with job_lock:
+            __mediaid__ = self.__get_id(task)
+            if __mediaid__ not in self._job_view:
+                return
+            # 更新状态
+            for t in self._job_view[__mediaid__].tasks:
+                if t.fileitem == task.fileitem:
+                    t.state = "running"
+                    file_key = self.__get_file_key(t.fileitem)
+                    if file_key:
+                        self._task_state_changed_at[file_key] = monotonic()
+                    break
+
+    def finish_task(self, task: TransferTask):
+        """
+        设置任务为完成/成功
+        """
+        with job_lock:
+            __mediaid__ = self.__get_id(task)
+            if __mediaid__ not in self._job_view:
+                return
+            # 更新状态
+            for t in self._job_view[__mediaid__].tasks:
+                if t.fileitem == task.fileitem:
+                    t.state = "completed"
+                    file_key = self.__get_file_key(t.fileitem)
+                    if file_key:
+                        self._task_state_changed_at[file_key] = monotonic()
+                    break
+
+    def fail_task(self, task: TransferTask):
+        """
+        设置任务为失败
+        """
+        with job_lock:
+            __mediaid__ = self.__get_id(task)
+            if __mediaid__ not in self._job_view:
+                return
+            # 更新状态
+            for t in self._job_view[__mediaid__].tasks:
+                if t.fileitem == task.fileitem:
+                    t.state = "failed"
+                    file_key = self.__get_file_key(t.fileitem)
+                    if file_key:
+                        self._task_state_changed_at[file_key] = monotonic()
+                    break
+            # 移除剧集信息
+            if __mediaid__ in self._season_episodes:
+                self._season_episodes[__mediaid__] = list(
+                    set(self._season_episodes[__mediaid__])
+                    - set(task.meta.episode_list)
+                )
+
+    def fail_unfinished_task(self, task: TransferTask):
+        """
+        将指定任务视图中的非终态任务标记为失败
+        """
+        if not task or not task.fileitem:
+            return
+        file_key = self.__get_file_key(task.fileitem)
+        if not file_key:
+            return
+        with job_lock:
+            for mediaid, job in self._job_view.items():
+                for job_task in job.tasks:
+                    if self.__get_file_key(job_task.fileitem) != file_key:
+                        continue
+                    if job_task.state not in ["completed", "failed"]:
+                        job_task.state = "failed"
+                        self._task_state_changed_at[file_key] = monotonic()
+                        if mediaid in self._season_episodes:
+                            self._season_episodes[mediaid] = list(
+                                set(self._season_episodes[mediaid])
+                                - set(task.meta.episode_list)
+                            )
+                    return
+
+    def remove_task(self, fileitem: FileItem) -> Optional[TransferJobTask]:
+        """
+        根据文件项移除任务
+        """
+        task, _ = self.__remove_task_with_job_id(fileitem)
+        return task
+
+    def __remove_task_with_job_id(
+            self,
+            fileitem: FileItem,
+            preserve_execution: bool = False,
+    ) -> Tuple[Optional[TransferJobTask], Optional[Tuple]]:
+        """
+        根据文件项移除任务，并返回任务所在的作业ID
+        """
+        file_key = self.__get_file_key(fileitem)
+        if not file_key:
+            return None, None
+        with job_lock:
+            for mediaid in list(self._job_view):
+                job = self._job_view[mediaid]
+                for task in job.tasks:
+                    if self.__get_file_key(task.fileitem) == file_key:
+                        job.tasks.remove(task)
+                        self._task_state_changed_at.pop(file_key, None)
+                        if not preserve_execution:
+                            self._active_executions.discard(file_key)
+                        # 如果没有作业了，则移除作业
+                        if not job.tasks:
+                            self._job_view.pop(mediaid)
+                        # 移除季集信息
+                        if mediaid in self._season_episodes:
+                            episodes = getattr(task.meta, "episode_list", None) or []
+                            self._season_episodes[mediaid] = list(
+                                set(self._season_episodes[mediaid])
+                                - set(episodes)
+                            )
+                        return task, mediaid
+            return None, None
+
+    def remove_job(self, task: TransferTask) -> Optional[TransferJob]:
+        """
+        移除任务对应的作业（强制，线程不安全）
+        """
+        with job_lock:
+            __mediaid__ = self.__get_id(task)
+            if __mediaid__ in self._job_view:
+                job = self._job_view[__mediaid__]
+                self.__pop_job(__mediaid__)
+                return job
+            return None
+
+    def try_remove_job(self, task: TransferTask):
+        """
+        尝试移除任务对应的作业（严格检查未完成作业，线程安全）
+        """
+        with job_lock:
+            __metaid__ = self.__get_meta_id(
+                meta=task.meta, season=task.meta.begin_season
+            )
+            __mediaid__ = self.__get_media_id(
+                media=task.mediainfo, season=task.meta.begin_season
+            )
+
+            related_media_ids = set(self._meta_to_media_ids.get(__metaid__, set()))
+            if task.mediainfo:
+                related_media_ids.add(__mediaid__)
+
+            meta_done = self.__is_job_done(__metaid__)
+            media_done = all(
+                self.__is_job_done(mediaid) for mediaid in related_media_ids
+            )
+
+            if meta_done and media_done:
+                remove_ids = {__metaid__, self.__get_id(task), *related_media_ids}
+                for job_id in remove_ids:
+                    self.__pop_job(job_id)
+                self._meta_to_media_ids.pop(__metaid__, None)
+
+    def is_done(self, task: TransferTask) -> bool:
+        """
+        检查任务对应的作业是否整理完成（不管成功还是失败）
+        """
+        with job_lock:
+            __metaid__ = self.__get_meta_id(
+                meta=task.meta, season=task.meta.begin_season
+            )
+            __mediaid__ = self.__get_media_id(
+                media=task.mediainfo, season=task.meta.begin_season
+            )
+            if __metaid__ in self._job_view:
+                meta_done = all(
+                    task.state in ["completed", "failed"]
+                    for task in self._job_view[__metaid__].tasks
+                )
+            else:
+                meta_done = True
+            if __mediaid__ in self._job_view:
+                media_done = all(
+                    task.state in ["completed", "failed"]
+                    for task in self._job_view[__mediaid__].tasks
+                )
+            else:
+                media_done = True
+            return meta_done and media_done
+
+    def is_finished(self, task: TransferTask) -> bool:
+        """
+        检查任务对应的作业是否已完成且有成功的记录
+        """
+        with job_lock:
+            __metaid__ = self.__get_meta_id(
+                meta=task.meta, season=task.meta.begin_season
+            )
+            __mediaid__ = self.__get_media_id(
+                media=task.mediainfo, season=task.meta.begin_season
+            )
+            if __metaid__ in self._job_view:
+                meta_finished = all(
+                    task.state in ["completed", "failed"]
+                    for task in self._job_view[__metaid__].tasks
+                )
+            else:
+                meta_finished = True
+            if __mediaid__ in self._job_view:
+                tasks = self._job_view[__mediaid__].tasks
+                media_finished = all(
+                    task.state in ["completed", "failed"] for task in tasks
+                ) and any(task.state == "completed" for task in tasks)
+            else:
+                media_finished = True
+            return meta_finished and media_finished
+
+    def is_success(self, task: TransferTask) -> bool:
+        """
+        检查任务对应的作业是否全部成功
+        """
+        with job_lock:
+            __metaid__ = self.__get_meta_id(
+                meta=task.meta, season=task.meta.begin_season
+            )
+            __mediaid__ = self.__get_media_id(
+                media=task.mediainfo, season=task.meta.begin_season
+            )
+            if __metaid__ in self._job_view:
+                meta_success = all(
+                    task.state in ["completed"]
+                    for task in self._job_view[__metaid__].tasks
+                )
+            else:
+                meta_success = True
+            if __mediaid__ in self._job_view:
+                media_success = all(
+                    task.state in ["completed"]
+                    for task in self._job_view[__mediaid__].tasks
+                )
+            else:
+                media_success = True
+            return meta_success and media_success
+
+    def get_all_torrent_hashes(self) -> set[str]:
+        """
+        获取所有种子的哈希值集合
+        """
+        with job_lock:
+            return {
+                task.download_hash
+                for job in self._job_view.values()
+                for task in job.tasks
+            }
+
+    def is_torrent_done(self, download_hash: str) -> bool:
+        """
+        检查指定种子的所有任务是否都已完成
+        """
+        with job_lock:
+            if any(
+                    task.state not in {"completed", "failed"}
+                    for job in self._job_view.values()
+                    for task in job.tasks
+                    if task.download_hash == download_hash
+            ):
+                return False
+            return True
+
+    def is_torrent_success(self, download_hash: str) -> bool:
+        """
+        检查指定种子的所有任务是否都已成功
+        """
+        with job_lock:
+            if any(
+                    task.state != "completed"
+                    for job in self._job_view.values()
+                    for task in job.tasks
+                    if task.download_hash == download_hash
+            ):
+                return False
+            return True
+
+    def has_tasks(
+            self,
+            meta: MetaBase,
+            mediainfo: Optional[MediaInfo] = None,
+            season: Optional[int] = None,
+    ) -> bool:
+        """
+        判断作业是否还有任务正在处理
+        """
+        with job_lock:
+            if mediainfo:
+                __mediaid__ = self.__get_media_id(media=mediainfo, season=season)
+                if __mediaid__ in self._job_view:
+                    return True
+
+            __metaid__ = self.__get_meta_id(meta=meta, season=season)
+            return (
+                    __metaid__ in self._job_view
+                    and len(self._job_view[__metaid__].tasks) > 0
+            )
+
+    def success_tasks(
+            self, media: Union[MediaInfo, MusicInfo], season: Optional[int] = None
+    ) -> List[TransferJobTask]:
+        """
+        获取作业中所有成功的任务
+        """
+        with job_lock:
+            __mediaid__ = self.__get_media_id(media=media, season=season)
+            if __mediaid__ not in self._job_view:
+                return []
+            return [
+                task
+                for task in self._job_view[__mediaid__].tasks
+                if task.state == "completed"
+            ]
+
+    def all_tasks(
+            self, media: MediaInfo, season: Optional[int] = None
+    ) -> List[TransferJobTask]:
+        """
+        获取作业中全部任务
+        """
+        with job_lock:
+            __mediaid__ = self.__get_media_id(media=media, season=season)
+            if __mediaid__ not in self._job_view:
+                return []
+            return self._job_view[__mediaid__].tasks
+
+    def count(self, media: Union[MediaInfo, MusicInfo], season: Optional[int] = None) -> int:
+        """
+        获取作业中成功总数
+        """
+        with job_lock:
+            __mediaid__ = self.__get_media_id(media=media, season=season)
+            if __mediaid__ not in self._job_view:
+                return 0
+            return len(
+                [
+                    task
+                    for task in self._job_view[__mediaid__].tasks
+                    if task.state == "completed"
+                ]
+            )
+
+    def size(self, media: Union[MediaInfo, MusicInfo], season: Optional[int] = None) -> int:
+        """
+        获取作业中所有成功文件总大小
+        """
+        with job_lock:
+            __mediaid__ = self.__get_media_id(media=media, season=season)
+            if __mediaid__ not in self._job_view:
+                return 0
+            return sum(
+                [
+                    task.fileitem.size
+                    if task.fileitem.size is not None
+                    else (
+                        SystemUtils.get_directory_size(Path(task.fileitem.path))
+                        if task.fileitem.storage == "local"
+                        else 0
+                    )
+                    for task in self._job_view[__mediaid__].tasks
+                    if task.state == "completed"
+                ]
+            )
+
+    def total(self) -> int:
+        """
+        获取所有任务总数
+        """
+        with job_lock:
+            return sum([len(job.tasks) for job in self._job_view.values()])
+
+    def pending_total(self) -> int:
+        """
+        获取未到终态的任务总数。
+
+        作业要等关联任务全部终态才整体移除,追更/分批场景下已完成任务会
+        跨批次残留在视图中;批次统计若用全量 total() 会把历史任务计入
+        「当前共 N 个文件」并压低进度百分比,因此只数未终态任务。
+        """
+        with job_lock:
+            return sum(
+                1
+                for job in self._job_view.values()
+                for task in job.tasks
+                if task.state not in ("completed", "failed")
+            )
+
+    def list_jobs(self) -> List[TransferJob]:
+        """
+        获取所有作业的任务列表
+        """
+        with job_lock:
+            return list(self._job_view.values())
+
+    def season_episodes(
+            self, media: Union[MediaInfo, MusicInfo], season: Optional[int] = None
+    ) -> List[int]:
+        """
+        获取作业的季集清单
+        """
+        with job_lock:
+            __mediaid__ = self.__get_media_id(media=media, season=season)
+            return self._season_episodes.get(__mediaid__) or []
+
+
+class FailedRetryScheduler:
+    """
+    负责失败整理记录的 debounce 聚合与 AI 重试调度。
+    """
+
+    RETRY_TRANSFER_DEBOUNCE_SECONDS = 300
+
+    def __init__(self):
+        super().__init__()
+        self._retry_transfer_buffer: dict[str, list[int]] = {}
+        self._retry_transfer_timers: dict[str, asyncio.TimerHandle] = {}
+        self._retry_transfer_lock = asyncio.Lock()
+
+    async def close(self):
+        async with self._retry_transfer_lock:
+            timers = list(self._retry_transfer_timers.values())
+            self._retry_transfer_timers.clear()
+            self._retry_transfer_buffer.clear()
+
+        for timer in timers:
+            timer.cancel()
+
+    @staticmethod
+    def _build_retry_transfer_template_context(
+            history_ids: list[int],
+    ) -> tuple[str, dict[str, int | str]]:
+        """仅负责把失败重试任务的动态数据映射成模板变量。"""
+        is_batch = len(history_ids) > 1
+        task_type = "batch_transfer_failed_retry" if is_batch else "transfer_failed_retry"
+        template_context: dict[str, int | str] = {
+            "history_ids_csv": ", ".join(str(item) for item in history_ids),
+            "history_count": len(history_ids),
+        }
+        if not is_batch:
+            template_context["history_id"] = history_ids[0]
+        return task_type, template_context
+
+    def _build_retry_transfer_prompt(self, history_ids: list[int]) -> str:
+        """根据失败记录数量构建统一的重试整理后台任务提示词。"""
+        task_type, template_context = self._build_retry_transfer_template_context(history_ids)
+        return get_prompt_manager().render_system_task_message(
+            task_type,
+            template_context=template_context,
+        )
+
+    async def schedule_retry(self, history_id: int, group_key: str = ""):
+        """
+        同一 group_key 的失败记录会在缓冲期内合并为一次 agent 调用。
+        """
+        if not group_key:
+            group_key = f"_default_{history_id}"
+
+        async with self._retry_transfer_lock:
+            if group_key not in self._retry_transfer_buffer:
+                self._retry_transfer_buffer[group_key] = []
+            if history_id not in self._retry_transfer_buffer[group_key]:
+                self._retry_transfer_buffer[group_key].append(history_id)
+                logger.info(
+                    f"智能体重试整理：记录 ID={history_id} 已加入缓冲区 "
+                    f"(group={group_key}, 当前{len(self._retry_transfer_buffer[group_key])}条)"
+                )
+
+            if group_key in self._retry_transfer_timers:
+                self._retry_transfer_timers[group_key].cancel()
+
+            loop = asyncio.get_running_loop()
+            self._retry_transfer_timers[group_key] = loop.call_later(
+                self.RETRY_TRANSFER_DEBOUNCE_SECONDS,
+                lambda gk=group_key: asyncio.create_task(self._flush_retry_transfer(gk)),
+            )
+
+    async def _flush_retry_transfer(self, group_key: str):
+        """
+        延迟定时器到期后，取出该分组的所有 history_id 并合并为一次 agent 调用。
+        """
+        async with self._retry_transfer_lock:
+            history_ids = self._retry_transfer_buffer.pop(group_key, [])
+            self._retry_transfer_timers.pop(group_key, None)
+
+        if not history_ids:
+            return
+
+        ids_str = ", ".join(str(item) for item in history_ids)
+        logger.info(
+            f"智能体重试整理：开始批量处理失败记录 IDs=[{ids_str}] (group={group_key})"
+        )
+
+        try:
+            await get_agent_manager().run_background_prompt(
+                message=self._build_retry_transfer_prompt(history_ids),
+                session_prefix="__agent_retry_transfer_batch",
+                reply_mode=ReplyMode.DISPATCH,
+            )
+            logger.info(
+                f"智能体重试整理：批量处理完成 IDs=[{ids_str}] (group={group_key})"
+            )
+        except Exception as err:
+            logger.error(
+                f"智能体重试整理失败 (IDs=[{ids_str}], group={group_key}): {err}"
+            )
+
+

app/chain/_interaction.py

@@ -0,0 +1,86 @@
+from typing import Optional, Tuple, Union
+
+from app.schemas.types import MessageChannel
+
+
+class InteractionChainMixin:
+    """
+    斜杠命令交互四件套委托：remote_list / parse_callback /
+    handle_callback_interaction / handle_text_interaction。
+
+    subscribe、site 等业务链的交互入口完全同构，唯一差异是各自的
+    交互处理器构造参数。本 mixin 将四件套委托提取为公共实现，
+    子类只需注入处理器类并实现 _interaction_handler 构造器。
+
+    子类注入约定：
+    - `_interaction_handler_type`：交互处理器类，提供静态 parse_callback；
+    - `_interaction_handler()`：按各链业务动作构造处理器实例。
+    """
+
+    # 交互处理器类，子类注入（如 SubscribeInteractionHandler / SiteInteractionHandler）
+    _interaction_handler_type: type = None
+
+    def _interaction_handler(self):
+        """
+        构造交互处理器实例，由子类按各自业务动作注入实现。
+        """
+        raise NotImplementedError
+
+    def remote_list(
+            self,
+            arg_str: str = "",
+            channel: MessageChannel = None,
+            userid: Union[str, int] = None,
+            source: Optional[str] = None,
+    ):
+        """
+        斜杠命令统一入口，委托交互处理器。
+        """
+        return self._interaction_handler().remote_list(
+            arg_str=arg_str, channel=channel, userid=userid, source=source
+        )
+
+    @classmethod
+    def parse_callback(cls, callback_data: str) -> Optional[Tuple[str, str]]:
+        """
+        解析斜杠命令按钮回调。
+        """
+        return cls._interaction_handler_type.parse_callback(callback_data)
+
+    def handle_callback_interaction(
+            self,
+            callback_data: str,
+            channel: MessageChannel,
+            source: str,
+            userid: Union[str, int],
+            username: str,
+            original_message_id: Optional[Union[str, int]] = None,
+            original_chat_id: Optional[str] = None,
+    ) -> bool:
+        """委托交互处理器处理按钮回调。"""
+        return self._interaction_handler().handle_callback_interaction(
+            callback_data=callback_data,
+            channel=channel,
+            source=source,
+            userid=userid,
+            username=username,
+            original_message_id=original_message_id,
+            original_chat_id=original_chat_id,
+        )
+
+    def handle_text_interaction(
+            self,
+            channel: MessageChannel,
+            source: str,
+            userid: Union[str, int],
+            username: str,
+            text: str,
+    ) -> bool:
+        """委托交互处理器处理文本输入。"""
+        return self._interaction_handler().handle_text_interaction(
+            channel=channel,
+            source=source,
+            userid=userid,
+            username=username,
+            text=text,
+        )

app/chain/_messaging.py

@@ -0,0 +1,486 @@
+"""消息处理与通知发送 mixin。
+
+从 ChainBase 拆出的消息域：渠道输入状态机、通知派发规范化、消息渲染、
+隔离路由与队列发送。方法经 MRO 解析，依赖 ChainBase 实例的 run_module、
+eventmanager、messageoper、messagequeue 等协作对象。
+"""
+import copy
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from app.db.oper.user import UserOper
+from app.domain.context import Context, MediaInfo, MusicInfo, TorrentInfo
+from app.domain.meta.metabase import MetaBase
+from app.foundation.identity import normalize_internal_user_id
+from app.application.messaging.message import MessageTemplateHelper
+from app.runtime.config import settings
+from app.runtime.extensions.service_registry import ServiceConfigHelper
+from app.runtime.log import logger
+from app.schemas import MessageResponse, Notification, TransferInfo
+from app.schemas.message import ChannelCapability, ChannelCapabilityManager
+from app.schemas.types import EventType, MessageChannel
+
+
+class MessageProcessingMixin:
+    """消息输入/处理状态机与通知派发规范化。"""
+
+    def start_message_processing_status(
+            self,
+            channel: MessageChannel,
+            source: Optional[str],
+            userid: Optional[Union[str, int]] = None,
+            message_id: Optional[Union[str, int]] = None,
+            chat_id: Optional[Union[str, int]] = None,
+            text: Optional[str] = None,
+    ) -> Optional[dict]:
+        """
+        启动渠道侧消息输入/处理状态。
+        具体表现由消息模块实现，例如 typing 保活或消息 reaction。
+        """
+        if not channel or not ChannelCapabilityManager.supports_capability(
+                channel, ChannelCapability.PROCESSING_STATUS
+        ):
+            return None
+        try:
+            status = self.run_module(
+                "mark_message_processing_started",
+                channel=channel,
+                source=source,
+                userid=userid,
+                message_id=message_id,
+                chat_id=chat_id,
+                text=text,
+            )
+        except Exception as err:
+            logger.debug(f"启动消息处理状态失败: {err}")
+            return None
+        return status if isinstance(status, dict) else None
+
+    def finish_message_processing_status(
+            self,
+            status: Optional[dict] = None,
+            channel: Optional[MessageChannel] = None,
+            source: Optional[str] = None,
+            userid: Optional[Union[str, int]] = None,
+            message_id: Optional[Union[str, int]] = None,
+            chat_id: Optional[Union[str, int]] = None,
+    ) -> None:
+        """
+        结束渠道侧消息输入/处理状态。
+        优先使用 start 返回的 status，缺失时使用显式渠道和消息定位参数。
+        """
+        target_channel = channel
+        if status:
+            try:
+                target_channel = MessageChannel(status.get("channel"))
+            except Exception:
+                target_channel = channel
+        if not target_channel or not ChannelCapabilityManager.supports_capability(
+                target_channel, ChannelCapability.PROCESSING_STATUS
+        ):
+            return
+        try:
+            self.run_module(
+                "mark_message_processing_finished",
+                channel=target_channel,
+                source=(status or {}).get("source") or source,
+                userid=(status or {}).get("userid") or userid,
+                message_id=(status or {}).get("message_id") or message_id,
+                chat_id=(status or {}).get("chat_id") or chat_id,
+                status=status,
+            )
+        except Exception as err:
+            logger.debug(f"结束消息处理状态失败: {err}")
+
+    @staticmethod
+    def _normalize_notification_for_dispatch(
+            message: Notification
+    ) -> Notification:
+        """
+        规范化待发送的通知消息。
+        后台任务会复用内部占位用户ID作为会话身份，这里在真正发送前清空，
+        让消息重新走默认通知路由或基于 targets 的目标解析。
+        """
+        dispatch_message = copy.deepcopy(message)
+        dispatch_message.userid = normalize_internal_user_id(
+            dispatch_message.userid
+        )
+        return dispatch_message
+
+    @staticmethod
+    def _build_notice_message_data(message: Notification) -> dict:
+        """
+        构造消息通知事件数据。
+        """
+        return {**message.model_dump(exclude={"save_history"}), "type": message.mtype}
+
+
+class NotificationMixin:
+    """通知消息发送域：渲染、隔离路由、队列发送与消息编辑。"""
+
+    def post_message(
+            self,
+            message: Optional[Notification] = None,
+            meta: Optional[MetaBase] = None,
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]] = None,
+            torrentinfo: Optional[TorrentInfo] = None,
+            transferinfo: Optional[TransferInfo] = None,
+            **kwargs,
+    ) -> None:
+        """
+        发送消息
+        :param message:  Notification实例
+        :param meta:  元数据
+        :param mediainfo:  媒体信息
+        :param torrentinfo:  种子信息
+        :param transferinfo:  文件整理信息
+        :param kwargs:  其他参数(覆盖业务对象属性值)
+        :return: 成功或失败
+        """
+        # 添加格式化的时间参数
+        kwargs.setdefault("current_time", datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+        # 渲染消息
+        message = MessageTemplateHelper.render(
+            message=message,
+            meta=meta,
+            mediainfo=mediainfo,
+            torrentinfo=torrentinfo,
+            transferinfo=transferinfo,
+            **kwargs,
+        )
+        # 检查消息是否有效
+        if not message:
+            logger.warning("消息为空，跳过发送")
+            return
+        if message.save_history:
+            self.messageoper.add(**message.model_dump())
+        dispatch_message = self._normalize_notification_for_dispatch(message)
+        # 发送消息按设置隔离
+        if not dispatch_message.userid and dispatch_message.mtype:
+            # 消息隔离设置
+            notify_action = ServiceConfigHelper.get_notification_switch(
+                dispatch_message.mtype
+            )
+            if notify_action:
+                # 'admin' 'user,admin' 'user' 'all'
+                actions = notify_action.split(",")
+                # 是否已发送管理员标志
+                admin_sended = False
+                send_orignal = False
+                useroper = UserOper()
+                for action in actions:
+                    send_message = copy.deepcopy(dispatch_message)
+                    if action == "admin" and not admin_sended:
+                        # 仅发送管理员
+                        logger.info(f"{send_message.mtype} 的消息已设置发送给管理员")
+                        # 读取管理员消息IDS
+                        send_message.targets = useroper.get_settings(settings.SUPERUSER)
+                        admin_sended = True
+                    elif action == "user" and send_message.username:
+                        # 发送对应用户
+                        logger.info(
+                            f"{send_message.mtype} 的消息已设置发送给用户 {send_message.username}"
+                        )
+                        # 读取用户消息IDS
+                        send_message.targets = useroper.get_settings(
+                            send_message.username
+                        )
+                        if send_message.targets is None:
+                            # 没有找到用户
+                            if not admin_sended:
+                                # 回滚发送管理员
+                                logger.info(
+                                    f"用户 {send_message.username} 不存在，消息将发送给管理员"
+                                )
+                                # 读取管理员消息IDS
+                                send_message.targets = useroper.get_settings(
+                                    settings.SUPERUSER
+                                )
+                                admin_sended = True
+                            else:
+                                # 管理员发过了，此消息不发了
+                                logger.info(
+                                    f"用户 {send_message.username} 不存在，消息无法发送到对应用户"
+                                )
+                                continue
+                        elif send_message.username == settings.SUPERUSER:
+                            # 管理员同名已发送
+                            admin_sended = True
+                    else:
+                        # 按原消息发送全体
+                        if not admin_sended:
+                            send_orignal = True
+                        break
+                    # 按设定发送
+                    self.eventmanager.send_event(
+                        etype=EventType.NoticeMessage,
+                        data=self._build_notice_message_data(send_message),
+                    )
+                    self.messagequeue.send_message(
+                        "post_message", message=send_message, **kwargs
+                    )
+                if not send_orignal:
+                    return
+        # 发送消息事件
+        self.eventmanager.send_event(
+            etype=EventType.NoticeMessage,
+            data=self._build_notice_message_data(dispatch_message),
+        )
+        # 按原消息发送
+        self.messagequeue.send_message(
+            "post_message",
+            message=dispatch_message,
+            immediately=True if dispatch_message.userid else False,
+            **kwargs,
+        )
+
+    async def async_post_message(
+            self,
+            message: Optional[Notification] = None,
+            meta: Optional[MetaBase] = None,
+            mediainfo: Optional[Union[MediaInfo, MusicInfo]] = None,
+            torrentinfo: Optional[TorrentInfo] = None,
+            transferinfo: Optional[TransferInfo] = None,
+            **kwargs,
+    ) -> None:
+        """
+        异步发送消息
+        :param message:  Notification实例
+        :param meta:  元数据
+        :param mediainfo:  媒体信息
+        :param torrentinfo:  种子信息
+        :param transferinfo:  文件整理信息
+        :param kwargs:  其他参数(覆盖业务对象属性值)
+        :return: 成功或失败
+        """
+        # 添加格式化的时间参数
+        kwargs.setdefault("current_time", datetime.now().strftime("%Y-%m-%d %H:%M:%S"))
+        # 渲染消息
+        message = MessageTemplateHelper.render(
+            message=message,
+            meta=meta,
+            mediainfo=mediainfo,
+            torrentinfo=torrentinfo,
+            transferinfo=transferinfo,
+            **kwargs,
+        )
+        # 检查消息是否有效
+        if not message:
+            logger.warning("消息为空，跳过发送")
+            return
+        if message.save_history:
+            await self.messageoper.async_add(**message.model_dump())
+        dispatch_message = self._normalize_notification_for_dispatch(message)
+        # 发送消息按设置隔离
+        if not dispatch_message.userid and dispatch_message.mtype:
+            # 消息隔离设置
+            notify_action = ServiceConfigHelper.get_notification_switch(
+                dispatch_message.mtype
+            )
+            if notify_action:
+                # 'admin' 'user,admin' 'user' 'all'
+                actions = notify_action.split(",")
+                # 是否已发送管理员标志
+                admin_sended = False
+                send_orignal = False
+                useroper = UserOper()
+                for action in actions:
+                    send_message = copy.deepcopy(dispatch_message)
+                    if action == "admin" and not admin_sended:
+                        # 仅发送管理员
+                        logger.info(f"{send_message.mtype} 的消息已设置发送给管理员")
+                        # 读取管理员消息IDS
+                        send_message.targets = useroper.get_settings(settings.SUPERUSER)
+                        admin_sended = True
+                    elif action == "user" and send_message.username:
+                        # 发送对应用户
+                        logger.info(
+                            f"{send_message.mtype} 的消息已设置发送给用户 {send_message.username}"
+                        )
+                        # 读取用户消息IDS
+                        send_message.targets = useroper.get_settings(
+                            send_message.username
+                        )
+                        if send_message.targets is None:
+                            # 没有找到用户
+                            if not admin_sended:
+                                # 回滚发送管理员
+                                logger.info(
+                                    f"用户 {send_message.username} 不存在，消息将发送给管理员"
+                                )
+                                # 读取管理员消息IDS
+                                send_message.targets = useroper.get_settings(
+                                    settings.SUPERUSER
+                                )
+                                admin_sended = True
+                            else:
+                                # 管理员发过了，此消息不发了
+                                logger.info(
+                                    f"用户 {send_message.username} 不存在，消息无法发送到对应用户"
+                                )
+                                continue
+                        elif send_message.username == settings.SUPERUSER:
+                            # 管理员同名已发送
+                            admin_sended = True
+                    else:
+                        # 按原消息发送全体
+                        if not admin_sended:
+                            send_orignal = True
+                        break
+                    # 按设定发送
+                    await self.eventmanager.async_send_event(
+                        etype=EventType.NoticeMessage,
+                        data=self._build_notice_message_data(send_message),
+                    )
+                    await self.messagequeue.async_send_message(
+                        "post_message", message=send_message, **kwargs
+                    )
+                if not send_orignal:
+                    return
+        # 发送消息事件
+        await self.eventmanager.async_send_event(
+            etype=EventType.NoticeMessage,
+            data=self._build_notice_message_data(dispatch_message),
+        )
+        # 按原消息发送
+        await self.messagequeue.async_send_message(
+            "post_message",
+            message=dispatch_message,
+            immediately=True if dispatch_message.userid else False,
+            **kwargs,
+        )
+
+    def post_medias_message(
+            self, message: Notification, medias: List[MediaInfo]
+    ) -> None:
+        """
+        发送媒体信息选择列表
+        :param message:  消息体
+        :param medias:  媒体列表
+        :return: 成功或失败
+        """
+        note_list = [media.to_dict() for media in medias]
+        if message.save_history:
+            self.messageoper.add(**message.model_dump(), note=note_list)
+        dispatch_message = self._normalize_notification_for_dispatch(message)
+        return self.messagequeue.send_message(
+            "post_medias_message",
+            message=dispatch_message,
+            medias=medias,
+            immediately=True if dispatch_message.userid else False,
+        )
+
+    def post_torrents_message(
+            self, message: Notification, torrents: List[Context]
+    ) -> None:
+        """
+        发送种子信息选择列表
+        :param message:  消息体
+        :param torrents:  种子列表
+        :return: 成功或失败
+        """
+        note_list = [torrent.torrent_info.to_dict() for torrent in torrents]
+        if message.save_history:
+            self.messageoper.add(**message.model_dump(), note=note_list)
+        dispatch_message = self._normalize_notification_for_dispatch(message)
+        return self.messagequeue.send_message(
+            "post_torrents_message",
+            message=dispatch_message,
+            torrents=torrents,
+            immediately=True if dispatch_message.userid else False,
+        )
+
+    def delete_message(
+            self,
+            channel: MessageChannel,
+            source: str,
+            message_id: Union[str, int],
+            chat_id: Optional[Union[str, int]] = None,
+    ) -> bool:
+        """
+        删除消息
+        :param channel: 消息渠道
+        :param source: 消息源（指定特定的消息模块）
+        :param message_id: 消息ID
+        :param chat_id: 聊天ID（如群组ID）
+        :return: 删除是否成功
+        """
+        return self.run_module(
+            "delete_message",
+            channel=channel,
+            source=source,
+            message_id=message_id,
+            chat_id=chat_id,
+        )
+
+    def edit_message(
+            self,
+            channel: MessageChannel,
+            source: str,
+            message_id: Union[str, int],
+            chat_id: Union[str, int],
+            text: str,
+            title: Optional[str] = None,
+            buttons: Optional[List[List[dict]]] = None,
+            metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """
+        编辑已发送的消息
+        :param channel: 消息渠道
+        :param source: 消息源（指定特定的消息模块）
+        :param message_id: 消息ID
+        :param chat_id: 聊天ID
+        :param text: 新的消息内容
+        :param title: 消息标题
+        :param buttons: 更新后的按钮列表
+        :param metadata: 其他消息元数据
+        :return: 编辑是否成功
+        """
+        if channel == MessageChannel.WebAgent:
+            try:
+                from app.application.messaging.agent import edit_web_agent_message
+
+                return edit_web_agent_message(
+                    user_id=str((metadata or {}).get("userid") or ""),
+                    message_id=message_id,
+                    title=title,
+                    text=text,
+                    buttons=buttons,
+                )
+            except Exception as err:
+                logger.debug(f"编辑 WebAgent 消息失败: {err}")
+                return False
+
+        return self.run_module(
+            "edit_message",
+            channel=channel,
+            source=source,
+            message_id=message_id,
+            chat_id=chat_id,
+            text=text,
+            title=title,
+            buttons=buttons,
+            metadata=metadata,
+        )
+
+    def send_direct_message(self, message: Notification) -> Optional[MessageResponse]:
+        """
+        直接发送消息并返回消息ID等信息（用于后续编辑消息的场景）
+        不经过消息队列、不保存消息历史
+        :param message: 消息体
+        :return: 消息响应（包含message_id, chat_id等）
+        """
+        return self.run_module(
+            "send_direct_message",
+            message=self._normalize_notification_for_dispatch(message),
+        )
+
+    def finalize_message(
+            self,
+            response: MessageResponse,
+    ) -> bool:
+        """
+        对已发送消息执行渠道收尾动作。
+        例如关闭流式卡片状态；无特殊收尾的渠道直接返回 False。
+        """
+        return self.run_module("finalize_message", response=response)

app/chain/_music.py

@@ -0,0 +1,420 @@
+import copy
+from typing import Any, List, Optional, Tuple
+
+from app.application.torrent import TorrentHelper
+from app.chain.download import DownloadChain
+from app.chain.media import MediaChain
+from app.chain.search import SearchChain
+from app.db.models.subscribe import Subscribe
+from app.db.oper.subscribe import SubscribeOper
+from app.db.oper.systemconfig import SystemConfigOper
+from app.domain.context import Context, MediaInfo, MusicInfo
+from app.domain.media import MUSIC_SUBSCRIBABLE_TYPES
+from app.domain.meta.metamusic import MetaMusic
+from app.runtime.log import logger
+from app.schemas.types import (
+    MUSIC_ENTITY_ALBUM,
+    MUSIC_ENTITY_RECORDING,
+    MediaType,
+    SystemConfigKey,
+)
+
+
+def _normalize_music_total_tracks(value: Any) -> Optional[int]:
+    """将专辑曲目总数归一为正整数，无效或未知值返回 None。"""
+    try:
+        total_tracks = int(value or 0)
+    except (TypeError, ValueError):
+        return None
+    return total_tracks if total_tracks > 0 else None
+
+
+class MusicSubscribeMixin:
+    """
+    音乐订阅功能域 mixin：单曲/专辑目标识别、实体快照同步、候选筛选、
+    择优下载与完成推进。
+
+    该域方法通过 self 复用 SubscribeChain 主体的 get_sub_sites / get_params /
+    filter_torrents / check_and_handle_existing_media / finish_subscribe_or_not /
+    get_subscribe_source_keyword 等编排能力，因此仅作为 mixin 混入 SubscribeChain，
+    不独立成链。build_subscribe_meta / _subscribe_media_key 等订阅通用辅助仍保留在
+    subscribe.py，方法内延迟导入以避免 _music ↔ subscribe 的模块级循环。
+    """
+
+    @staticmethod
+    def _validate_music_subscribe_target(
+            mediainfo: MediaInfo,
+            requested_music_type: Optional[str] = None,
+    ) -> Optional[str]:
+        """校验音乐订阅实体一致性，并确保专辑具备可验证的曲目总数。"""
+        if mediainfo.type != MediaType.MUSIC:
+            return "识别结果不是音乐"
+        music_type = getattr(mediainfo, "music_type", None)
+        if requested_music_type and requested_music_type not in MUSIC_SUBSCRIBABLE_TYPES:
+            return "音乐订阅仅支持单曲或专辑"
+        if music_type not in MUSIC_SUBSCRIBABLE_TYPES:
+            return "音乐订阅仅支持单曲或专辑"
+        if requested_music_type and requested_music_type != music_type:
+            return f"音乐订阅类型不匹配：请求 {requested_music_type}，识别为 {music_type}"
+        if music_type == MUSIC_ENTITY_ALBUM \
+                and _normalize_music_total_tracks(getattr(mediainfo, "total_tracks", None)) is None:
+            return "专辑总曲目数未知，无法校验整张专辑资源"
+        return None
+
+    @staticmethod
+    def _ensure_music_subscribe_entity(
+            subscribe: Subscribe,
+            mediainfo: Optional[MusicInfo],
+    ) -> Optional[MusicInfo]:
+        """保持已持久化的单曲/专辑实体边界，拒绝远端详情把订阅类型改写。"""
+        if not mediainfo:
+            return None
+        expected_type = getattr(subscribe, "music_type", None)
+        actual_type = getattr(mediainfo, "music_type", None)
+        if expected_type and expected_type not in MUSIC_SUBSCRIBABLE_TYPES:
+            logger.warning(f"音乐订阅 {subscribe.name} 的实体类型无效：{expected_type}")
+            return None
+        if actual_type not in MUSIC_SUBSCRIBABLE_TYPES:
+            logger.warning(
+                f"音乐订阅 {subscribe.name} 识别为不可订阅实体：{actual_type}"
+            )
+            if expected_type in MUSIC_SUBSCRIBABLE_TYPES:
+                return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+            return None
+        if expected_type and actual_type != expected_type:
+            logger.warning(
+                f"音乐订阅 {subscribe.name} 实体不匹配："
+                f"订阅为 {expected_type}，远端识别为 {actual_type}，使用订阅快照"
+            )
+            return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+        if actual_type == MUSIC_ENTITY_ALBUM:
+            remote_total = _normalize_music_total_tracks(getattr(mediainfo, "total_tracks", None))
+            stored_total = _normalize_music_total_tracks(getattr(subscribe, "total_tracks", None))
+            resolved_total = remote_total or stored_total
+            if resolved_total is not None and mediainfo.total_tracks != resolved_total:
+                # 识别模块结果可能来自共享缓存，补齐订阅快照时不得原地修改。
+                mediainfo = copy.copy(mediainfo)
+                mediainfo.total_tracks = resolved_total
+        return mediainfo
+
+    @staticmethod
+    def _recognize_music_subscribe(subscribe: Subscribe) -> Optional[MusicInfo]:
+        """按订阅身份恢复音乐目标，远端暂不可用时使用已持久化的稳定快照。"""
+        # 延迟导入订阅通用辅助，避免 _music ↔ subscribe 模块级循环
+        from app.chain.subscribe import build_subscribe_meta
+        if subscribe.media_source and subscribe.media_id:
+            # 与影视共用统一识别入口，按媒体源和原生 ID 恢复音乐详情
+            mediainfo = MediaChain().recognize_media(
+                media_source=subscribe.media_source,
+                media_id=str(subscribe.media_id),
+                mtype=MediaType.MUSIC,
+                music_type=getattr(subscribe, "music_type", None),
+            )
+            if mediainfo:
+                return MusicSubscribeMixin._ensure_music_subscribe_entity(subscribe, mediainfo)
+            if getattr(subscribe, "music_type", None) in {MUSIC_ENTITY_RECORDING, MUSIC_ENTITY_ALBUM}:
+                return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+            # 旧订阅没有保存实体类型时不能猜测为单曲，否则可能误把专辑按单曲完成。
+            return None
+        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
+            # 缺少远端 ID 的专辑不能退化为单曲识别，使用已保存专辑快照更可靠。
+            return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+        # 旧订阅没有实体类型时只允许走 Recording 识别，不能从全局混合搜索中猜成专辑或艺术家。
+        mediainfo = MediaChain().recognize_media(
+            meta=build_subscribe_meta(subscribe),
+            mtype=MediaType.MUSIC,
+            media_source=subscribe.media_source,
+            music_type=MUSIC_ENTITY_RECORDING,
+        )
+        return MusicSubscribeMixin._ensure_music_subscribe_entity(subscribe, mediainfo)
+
+    @staticmethod
+    async def _async_recognize_music_subscribe(subscribe: Subscribe) -> Optional[MusicInfo]:
+        """异步按订阅身份恢复音乐目标，远端暂不可用时使用已持久化的稳定快照。"""
+        # 延迟导入订阅通用辅助，避免 _music ↔ subscribe 模块级循环
+        from app.chain.subscribe import build_subscribe_meta
+        if subscribe.media_source and subscribe.media_id:
+            # 与影视共用统一识别入口，按媒体源和原生 ID 恢复音乐详情
+            mediainfo = await MediaChain().async_recognize_media(
+                media_source=subscribe.media_source,
+                media_id=str(subscribe.media_id),
+                mtype=MediaType.MUSIC,
+                music_type=getattr(subscribe, "music_type", None),
+            )
+            if mediainfo:
+                return MusicSubscribeMixin._ensure_music_subscribe_entity(subscribe, mediainfo)
+            if getattr(subscribe, "music_type", None) in {MUSIC_ENTITY_RECORDING, MUSIC_ENTITY_ALBUM}:
+                return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+            return None
+        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
+            return MusicSubscribeMixin._music_info_from_subscribe(subscribe)
+        mediainfo = await MediaChain().async_recognize_media(
+            meta=build_subscribe_meta(subscribe),
+            mtype=MediaType.MUSIC,
+            media_source=subscribe.media_source,
+            music_type=MUSIC_ENTITY_RECORDING,
+        )
+        return MusicSubscribeMixin._ensure_music_subscribe_entity(subscribe, mediainfo)
+
+    @staticmethod
+    def _music_info_from_subscribe(subscribe: Subscribe) -> MusicInfo:
+        """从订阅行恢复不依赖远端请求的最小音乐目标，保留专辑完成判断所需字段。"""
+        year_text = str(subscribe.year or "")[:4]
+        music_type = getattr(subscribe, "music_type", None)
+        # 音乐订阅的 description 由标准 MusicInfo.overview 生成，首段固定为艺术家。
+        artist_text = str(getattr(subscribe, "description", None) or "") \
+            .split(" · ", maxsplit=1)[0].strip()
+        artists = [
+            artist.strip() for artist in artist_text.split(" / ") if artist.strip()
+        ]
+        return MusicInfo(
+            media_source=subscribe.media_source,
+            media_id=str(subscribe.media_id) if subscribe.media_id is not None else None,
+            music_type=music_type,
+            title=subscribe.name,
+            artists=artists,
+            album=subscribe.name if music_type == MUSIC_ENTITY_ALBUM else None,
+            year=int(year_text) if year_text.isdigit() else None,
+            total_tracks=getattr(subscribe, "total_tracks", None)
+            if music_type == MUSIC_ENTITY_ALBUM else None,
+            cover_url=getattr(subscribe, "poster", None) or getattr(subscribe, "backdrop", None),
+        )
+
+    @staticmethod
+    def _sync_music_subscribe_target(subscribe: Subscribe, mediainfo: MusicInfo) -> None:
+        """把远端识别得到的专辑类型和总曲目数同步到订阅，供搜索失败与完成历史复用。"""
+        update_data = {}
+        if mediainfo.music_type and getattr(subscribe, "music_type", None) != mediainfo.music_type:
+            update_data["music_type"] = mediainfo.music_type
+        if mediainfo.music_type == MUSIC_ENTITY_ALBUM:
+            # 远端详情可能暂时不返回曲目数；已确认的订阅快照不能因此被清空。
+            total_tracks = _normalize_music_total_tracks(mediainfo.total_tracks) \
+                or _normalize_music_total_tracks(getattr(subscribe, "total_tracks", None))
+        else:
+            total_tracks = None
+        if getattr(subscribe, "total_tracks", None) != total_tracks:
+            update_data["total_tracks"] = total_tracks
+        if not update_data:
+            return
+        SubscribeOper().update(subscribe.id, update_data)
+        for key, value in update_data.items():
+            setattr(subscribe, key, value)
+
+    @staticmethod
+    def _is_music_download_complete(
+            subscribe: Subscribe,
+            mediainfo: MusicInfo,
+            downloads: Optional[List[Context]],
+    ) -> bool:
+        """判断音乐下载是否满足订阅完成条件；专辑必须由下载层确认整专曲目覆盖。"""
+        if not downloads:
+            return False
+        music_type = getattr(subscribe, "music_type", None) or mediainfo.music_type
+        if music_type != MUSIC_ENTITY_ALBUM:
+            return True
+        return any(context.confirmed_full_coverage for context in downloads)
+
+    def _prepare_music_subscribe(
+            self,
+            subscribe: Subscribe,
+    ) -> Optional[Tuple[MusicInfo, MetaMusic]]:
+        """识别音乐订阅目标、同步实体快照，并在搜索前处理已完整入库的目标。"""
+        # 延迟导入订阅通用辅助，避免 _music ↔ subscribe 模块级循环
+        from app.chain.subscribe import _subscribe_media_key
+        mediainfo = self._recognize_music_subscribe(subscribe)
+        if not mediainfo:
+            logger.warning(
+                f"未识别到音乐订阅目标：{subscribe.name}，"
+                f"媒体源：{subscribe.media_source}，媒体ID：{subscribe.media_id}"
+            )
+            return None
+        validation_error = self._validate_music_subscribe_target(
+            mediainfo,
+            getattr(subscribe, "music_type", None),
+        )
+        if validation_error:
+            logger.warning(f"音乐订阅 {subscribe.name} 无法继续：{validation_error}")
+            return None
+        self._sync_music_subscribe_target(subscribe, mediainfo)
+        meta = MetaMusic.from_music_info(mediainfo)
+        exists, _ = self.check_and_handle_existing_media(
+            subscribe=subscribe,
+            meta=meta,
+            mediainfo=mediainfo,
+            mediakey=_subscribe_media_key(subscribe),
+        )
+        if exists:
+            return None
+        return mediainfo, meta
+
+    def _filter_music_subscribe_contexts(
+            self,
+            subscribe: Subscribe,
+            mediainfo: MusicInfo,
+            contexts: List[Context],
+    ) -> List[Context]:
+        """按站点、音乐实体、订阅参数和优先级规则筛选并绑定下载上下文。"""
+        sites = self.get_sub_sites(subscribe)
+        default_rule_key = SystemConfigKey.BestVersionFilterRuleGroups \
+            if subscribe.best_version else SystemConfigKey.SubscribeFilterRuleGroups
+        rule_groups = subscribe.filter_groups or SystemConfigOper().get(default_rule_key) or []
+        torrent_helper = TorrentHelper()
+        matched: List[Context] = []
+        for source_context in contexts or []:
+            source_torrent = source_context.torrent_info
+            if not source_torrent or source_torrent.category not in (MediaType.MUSIC, MediaType.MUSIC.value):
+                continue
+            # 过滤模块会就地写入 pri_order；RSS 缓存会被多个订阅复用，必须隔离候选副本。
+            torrent = copy.copy(source_torrent)
+            if sites and torrent.site not in sites:
+                continue
+            if not SearchChain.matches_music_resource(
+                    mediainfo,
+                    torrent.title,
+                    torrent.description,
+            ):
+                continue
+            if not torrent_helper.filter_torrent(torrent, self.get_params(subscribe)):
+                continue
+            filtered = self.filter_torrents(
+                rule_groups=rule_groups,
+                torrent_list=[torrent],
+                mediainfo=mediainfo,
+            )
+            if filtered is not None:
+                if not filtered:
+                    continue
+                torrent = filtered[0]
+
+            context = copy.copy(source_context)
+            context.torrent_info = torrent
+            meta = MetaMusic.from_music_info(mediainfo)
+            meta.org_string = torrent.title
+            meta.apply_audio_quality(f"{torrent.title} {torrent.description or ''}", overwrite=True)
+            if subscribe.best_version:
+                # 用户规则组可用格式、码率等内置规则定义洗版顺序；未命中规则
+                # 优先级时再回退到规范化音质分数，确保零配置也能自动升级。
+                music_priority = torrent.pri_order or meta.audio_quality_score
+                if music_priority <= (subscribe.current_priority or 0):
+                    logger.info(
+                        f"{torrent.title} 音质优先级 {music_priority} "
+                        f"未高于当前版本 {subscribe.current_priority or 0}"
+                    )
+                    continue
+                torrent.pri_order = music_priority
+            context.meta_info = meta
+            context.media_info = mediainfo
+            context.match_source = str(mediainfo.media_source or "title")
+            context.candidate_recognized = False
+            context.media_info_is_target = True
+            if subscribe.media_category:
+                context.media_info.category = subscribe.media_category
+            matched.append(context)
+        return matched
+
+    def _download_music_subscribe(
+            self,
+            subscribe: Subscribe,
+            mediainfo: MusicInfo,
+            contexts: List[Context],
+    ) -> None:
+        """批量择优下载音乐候选，并按单曲或整专完成语义推进订阅。"""
+        if not contexts:
+            return
+        downloads, _ = DownloadChain().batch_download(
+            contexts=contexts,
+            username=subscribe.username,
+            save_path=subscribe.save_path,
+            downloader=subscribe.downloader,
+            source=self.get_subscribe_source_keyword(subscribe),
+            custom_words=subscribe.custom_words,
+        )
+        successful = [
+            context for context in downloads or []
+            if context and context.meta_info and context.torrent_info
+        ]
+        quality_downloads = successful
+        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
+            quality_downloads = [
+                context for context in successful
+                if context.confirmed_full_coverage
+            ]
+        if subscribe.best_version and quality_downloads:
+            best_context = max(quality_downloads, key=lambda item: item.torrent_info.pri_order)
+            best_meta = best_context.meta_info
+            quality_data = {
+                "current_priority": best_context.torrent_info.pri_order,
+                "current_audio_format": best_meta.audio_format,
+                "current_bitrate": best_meta.bitrate,
+                "current_bit_depth": best_meta.bit_depth,
+                "current_sample_rate": best_meta.sample_rate,
+            }
+            SubscribeOper().update(subscribe.id, quality_data)
+            for key, value in quality_data.items():
+                setattr(subscribe, key, value)
+        current_subscribe = SubscribeOper().get(subscribe.id)
+        if current_subscribe:
+            self.finish_subscribe_or_not(
+                subscribe=current_subscribe,
+                meta=MetaMusic.from_music_info(mediainfo),
+                mediainfo=mediainfo,
+                downloads=downloads,
+            )
+
+    def _search_music_subscribe(self, subscribe: Subscribe) -> None:
+        """复用站点标题搜索、订阅过滤和批量下载完成单个音乐订阅。"""
+        target = self._prepare_music_subscribe(subscribe)
+        if not target:
+            return
+        mediainfo, _ = target
+
+        sites = self.get_sub_sites(subscribe)
+        default_rule_key = SystemConfigKey.BestVersionFilterRuleGroups \
+            if subscribe.best_version else SystemConfigKey.SubscribeFilterRuleGroups
+        rule_groups = subscribe.filter_groups or SystemConfigOper().get(default_rule_key) or []
+        keywords = [subscribe.keyword] if subscribe.keyword else SearchChain.music_site_keywords(mediainfo)
+        if not keywords:
+            keywords = [subscribe.name]
+
+        searchchain = SearchChain()
+        contexts: List[Context] = []
+        for keyword in keywords:
+            contexts = searchchain.search_by_title(
+                title=keyword,
+                sites=sites,
+                mtype=MediaType.MUSIC,
+                rule_groups=rule_groups,
+            )
+            contexts = self._filter_music_subscribe_contexts(
+                subscribe=subscribe,
+                mediainfo=mediainfo,
+                contexts=contexts,
+            )
+            if contexts:
+                break
+
+        if not contexts:
+            logger.warning(f"音乐订阅 {subscribe.keyword or subscribe.name} 未搜索到符合条件的资源")
+            return
+
+        self._download_music_subscribe(subscribe, mediainfo, contexts)
+
+    def _match_music_subscribe(
+            self,
+            subscribe: Subscribe,
+            contexts: List[Context],
+    ) -> None:
+        """直接匹配本轮 RSS 缓存中的音乐资源，避免再次调用站点搜索接口。"""
+        target = self._prepare_music_subscribe(subscribe)
+        if not target:
+            return
+        mediainfo, _ = target
+        matched = self._filter_music_subscribe_contexts(
+            subscribe=subscribe,
+            mediainfo=mediainfo,
+            contexts=contexts,
+        )
+        if not matched:
+            logger.info(f"音乐订阅 {subscribe.name} 未匹配到符合条件的 RSS 资源")
+            return
+        self._download_music_subscribe(subscribe, mediainfo, matched)

app/chain/_recognition.py

@@ -0,0 +1,518 @@
+"""媒体识别管线 mixin。
+
+从 ChainBase 拆出的识别域：原生模块识别路由、识别缓存回填、共享识别、
+插件补充识别。方法经 MRO 解析，依赖 ChainBase 实例的 run_module/eventmanager
+等协作对象。
+"""
+import copy
+from typing import Optional
+
+from fastapi.concurrency import run_in_threadpool
+
+from app.adapters.external.server import MoviePilotServerHelper
+from app.db.oper.systemconfig import SystemConfigOper
+from app.domain.context import MediaInfo, MusicInfo
+from app.domain.meta.metabase import MetaBase
+from app.domain.meta.metamusic import MetaMusic
+from app.runtime.cache import fresh, async_fresh
+from app.runtime.config import settings
+from app.runtime.events import Event
+from app.runtime.log import logger
+from app.schemas.media import normalize_media_source, resolve_media_identity
+from app.schemas.types import ChainEventType, MediaSource, MediaType, SystemConfigKey
+
+
+class RecognitionMixin:
+
+    @staticmethod
+    def _can_use_media_recognize_share(
+            meta: Optional[MetaBase],
+            media_source: Optional[MediaSource],
+            media_id: Optional[str],
+    ) -> bool:
+        """
+        仅在名称识别场景下使用共享识别，显式ID识别不再重复回查
+        """
+        return bool(
+            settings.MEDIA_RECOGNIZE_SHARE
+            and meta
+            and not media_source
+            and not media_id
+        )
+
+    @staticmethod
+    def _snapshot_recognize_cache_meta(meta: Optional[MetaBase]) -> Optional[MetaBase]:
+        """
+        保存共享识别前的本地缓存关键元数据，用于共享成功后回填正缓存覆盖负缓存。
+        """
+        if not meta:
+            return None
+        return copy.deepcopy(meta)
+
+    def _update_local_recognize_cache(
+            self,
+            meta: Optional[MetaBase],
+            mediainfo: Optional[MediaInfo],
+    ) -> None:
+        """
+        共享识别成功后回填本地识别缓存，避免名称负缓存导致后续重复回查共享。
+        """
+        if not meta or not mediainfo:
+            return
+        self.run_module(
+            "update_recognize_cache",
+            meta=meta,
+            mediainfo=mediainfo,
+        )
+
+    async def _async_update_local_recognize_cache(
+            self,
+            meta: Optional[MetaBase],
+            mediainfo: Optional[MediaInfo],
+    ) -> None:
+        """
+        异步回填本地识别缓存。
+        """
+        if not meta or not mediainfo:
+            return
+        await self.async_run_module(
+            "async_update_recognize_cache",
+            meta=meta,
+            mediainfo=mediainfo,
+        )
+
+    @staticmethod
+    def _record_media_recognize_share_hit() -> None:
+        """记录一次共享媒体识别成功命中，统计失败不影响识别结果。"""
+        try:
+            SystemConfigOper().increment(SystemConfigKey.MediaRecognizeShareCount)
+        except Exception as err:
+            logger.error(f"记录共享媒体识别命中次数失败：{str(err)}")
+
+    def _run_native_media_recognize(
+            self,
+            module_kwargs: dict,
+            cache: bool,
+    ) -> Optional[MediaInfo]:
+        """执行同步原生媒体模块识别，具体媒体领域可覆写该路由钩子。"""
+        with fresh(not cache):
+            return self.run_module("recognize_media", **module_kwargs)
+
+    async def _async_run_native_media_recognize(
+            self,
+            module_kwargs: dict,
+            cache: bool,
+    ) -> Optional[MediaInfo]:
+        """执行异步原生媒体模块识别，具体媒体领域可覆写该路由钩子。"""
+        async with async_fresh(not cache):
+            return await self.async_run_module(
+                "async_recognize_media", **module_kwargs
+            )
+
+    def recognize_media(
+            self,
+            meta: MetaBase = None,
+            mtype: Optional[MediaType] = None,
+            media_source: Optional[MediaSource] = None,
+            media_id: Optional[str] = None,
+            episode_group: Optional[str] = None,
+            cache: bool = True,
+            share_meta: MetaBase = None,
+            music_type: Optional[str] = None,
+    ) -> Optional[MediaInfo]:
+        """
+        识别媒体信息，不含Fanart图片
+        :param meta:     识别的元数据
+        :param share_meta: 共享识别查询/上报使用的原始元数据
+        :param mtype:    识别的媒体类型
+        :param media_source: 请求级识别数据源
+        :param media_id: 数据源原生ID，必须与media_source成对提供
+        :param episode_group: 剧集组
+        :param cache:    是否使用缓存
+        :param music_type: 音乐实体类型，显式音乐 ID 必须据此区分单曲与专辑
+        :return: 识别的媒体信息，包括剧集信息
+        """
+        # 仅传数据源是请求级识别源约束（按名称识别限定数据源），显式 media_id 才要求来源成对
+        explicit_identity = media_id is not None
+        requested_source = normalize_media_source(media_source) or media_source
+        media_source, media_id = resolve_media_identity(
+            media=meta,
+            media_source=media_source,
+            media_id=media_id,
+        )
+        if explicit_identity and (not media_source or not media_id):
+            logger.warning("媒体识别需要同时提供有效的 media_source 和 media_id")
+            return None
+        if not media_id and requested_source is not None:
+            media_source = requested_source
+            # meta 自带同源身份（如 {tmdbid=} 标题）时直接按身份识别，避免退化为名称搜索
+            meta_source, meta_id = resolve_media_identity(media=meta)
+            if meta_id and meta_source == requested_source:
+                media_source, media_id = meta_source, meta_id
+        if not episode_group and hasattr(meta, "episode_group"):
+            episode_group = meta.episode_group
+        if not mtype and not (media_source and media_id) and meta and meta.type in [
+            MediaType.TV, MediaType.MOVIE, MediaType.MUSIC
+        ]:
+            mtype = meta.type
+        share_query_meta = share_meta or meta
+        module_kwargs = {
+            "meta": meta,
+            "mtype": mtype,
+            "media_source": media_source,
+            "media_id": media_id,
+            "episode_group": episode_group,
+            "cache": cache,
+        }
+        if music_type is not None:
+            module_kwargs["music_type"] = music_type
+        mediainfo = self._run_native_media_recognize(module_kwargs, cache)
+        # 原生识别未取得远端身份时，允许插件按已知要素补充匹配媒体信息（影视与音乐统一）
+        mediainfo = self._supplement_media_recognize(
+            meta=meta, mtype=mtype, media_source=media_source,
+            media_id=media_id, mediainfo=mediainfo,
+            music_type=music_type,
+        )
+        fallback_mediainfo = (
+            mediainfo
+            if mediainfo and not self._media_info_has_identity(mediainfo)
+            else None
+        )
+        if mediainfo and self._media_info_has_identity(mediainfo):
+            # 电影、电视剧、音乐统一上报；音乐的 tmdb 等字段恒为 None，身份取数据源原生 ID
+            if not getattr(mediainfo, "recognize_cache_hit", False):
+                MoviePilotServerHelper.report_recognize_share(
+                    meta=meta,
+                    mediainfo=mediainfo,
+                    keyword_meta=share_query_meta,
+                )
+            return mediainfo
+
+        if self._can_use_media_recognize_share(
+                share_query_meta, media_source, media_id
+        ):
+            shared_cache_meta = self._snapshot_recognize_cache_meta(meta)
+            share_query_kwargs = {
+                "meta": meta,
+                "mtype": mtype,
+                "keyword_meta": share_query_meta,
+            }
+            if music_type is not None:
+                share_query_kwargs["music_type"] = music_type
+            shared_item = MoviePilotServerHelper.query_recognize_share(
+                **share_query_kwargs,
+            )
+            shared_params = MoviePilotServerHelper.to_recognize_params(shared_item)
+            if shared_params:
+                shared_module_kwargs = {
+                        "meta": meta,
+                        "mtype": shared_params.get("mtype") or mtype,
+                        "media_source": shared_params.get("media_source"),
+                        "media_id": shared_params.get("media_id"),
+                        "episode_group": episode_group,
+                        "cache": cache,
+                }
+                shared_music_type = shared_params.get("music_type") or music_type
+                if shared_music_type is not None:
+                    shared_module_kwargs["music_type"] = shared_music_type
+                mediainfo = self._run_native_media_recognize(
+                    shared_module_kwargs,
+                    cache,
+                )
+                if mediainfo and self._media_info_has_identity(mediainfo):
+                    self._update_local_recognize_cache(shared_cache_meta, mediainfo)
+                    self._record_media_recognize_share_hit()
+                    return mediainfo
+                if mediainfo and not fallback_mediainfo:
+                    fallback_mediainfo = mediainfo
+        return fallback_mediainfo
+
+    async def async_recognize_media(
+            self,
+            meta: MetaBase = None,
+            mtype: Optional[MediaType] = None,
+            media_source: Optional[MediaSource] = None,
+            media_id: Optional[str] = None,
+            episode_group: Optional[str] = None,
+            cache: bool = True,
+            share_meta: MetaBase = None,
+            music_type: Optional[str] = None,
+    ) -> Optional[MediaInfo]:
+        """
+        识别媒体信息，不含Fanart图片（异步版本）
+        :param meta:     识别的元数据
+        :param share_meta: 共享识别查询/上报使用的原始元数据
+        :param mtype:    识别的媒体类型
+        :param media_source: 请求级识别数据源
+        :param media_id: 数据源原生ID，必须与media_source成对提供
+        :param episode_group: 剧集组
+        :param cache:    是否使用缓存
+        :param music_type: 音乐实体类型，显式音乐 ID 必须据此区分单曲与专辑
+        :return: 识别的媒体信息，包括剧集信息
+        """
+        # 仅传数据源是请求级识别源约束（按名称识别限定数据源），显式 media_id 才要求来源成对
+        explicit_identity = media_id is not None
+        requested_source = normalize_media_source(media_source) or media_source
+        media_source, media_id = resolve_media_identity(
+            media=meta,
+            media_source=media_source,
+            media_id=media_id,
+        )
+        if explicit_identity and (not media_source or not media_id):
+            logger.warning("媒体识别需要同时提供有效的 media_source 和 media_id")
+            return None
+        if not media_id and requested_source is not None:
+            media_source = requested_source
+            # meta 自带同源身份（如 {tmdbid=} 标题）时直接按身份识别，避免退化为名称搜索
+            meta_source, meta_id = resolve_media_identity(media=meta)
+            if meta_id and meta_source == requested_source:
+                media_source, media_id = meta_source, meta_id
+        if not episode_group and hasattr(meta, "episode_group"):
+            episode_group = meta.episode_group
+        if not mtype and not (media_source and media_id) and meta and meta.type in [
+            MediaType.TV, MediaType.MOVIE, MediaType.MUSIC
+        ]:
+            mtype = meta.type
+        share_query_meta = share_meta or meta
+        module_kwargs = {
+            "meta": meta,
+            "mtype": mtype,
+            "media_source": media_source,
+            "media_id": media_id,
+            "episode_group": episode_group,
+            "cache": cache,
+        }
+        if music_type is not None:
+            module_kwargs["music_type"] = music_type
+        mediainfo = await self._async_run_native_media_recognize(module_kwargs, cache)
+        # 原生识别未取得远端身份时，允许插件按已知要素补充匹配媒体信息（影视与音乐统一）
+        mediainfo = await self._async_supplement_media_recognize(
+            meta=meta, mtype=mtype, media_source=media_source,
+            media_id=media_id, mediainfo=mediainfo,
+            music_type=music_type,
+        )
+        fallback_mediainfo = (
+            mediainfo
+            if mediainfo and not self._media_info_has_identity(mediainfo)
+            else None
+        )
+        if mediainfo and self._media_info_has_identity(mediainfo):
+            # 电影、电视剧、音乐统一上报；音乐的 tmdb 等字段恒为 None，身份取数据源原生 ID
+            if not getattr(mediainfo, "recognize_cache_hit", False):
+                await MoviePilotServerHelper.async_report_recognize_share(
+                    meta=meta,
+                    mediainfo=mediainfo,
+                    keyword_meta=share_query_meta,
+                )
+            return mediainfo
+
+        if self._can_use_media_recognize_share(
+                share_query_meta, media_source, media_id
+        ):
+            shared_cache_meta = self._snapshot_recognize_cache_meta(meta)
+            share_query_kwargs = {
+                "meta": meta,
+                "mtype": mtype,
+                "keyword_meta": share_query_meta,
+            }
+            if music_type is not None:
+                share_query_kwargs["music_type"] = music_type
+            shared_item = await MoviePilotServerHelper.async_query_recognize_share(
+                **share_query_kwargs,
+            )
+            shared_params = MoviePilotServerHelper.to_recognize_params(shared_item)
+            if shared_params:
+                shared_module_kwargs = {
+                        "meta": meta,
+                        "mtype": shared_params.get("mtype") or mtype,
+                        "media_source": shared_params.get("media_source"),
+                        "media_id": shared_params.get("media_id"),
+                        "episode_group": episode_group,
+                        "cache": cache,
+                }
+                shared_music_type = shared_params.get("music_type") or music_type
+                if shared_music_type is not None:
+                    shared_module_kwargs["music_type"] = shared_music_type
+                mediainfo = await self._async_run_native_media_recognize(
+                    shared_module_kwargs,
+                    cache,
+                )
+                if mediainfo and self._media_info_has_identity(mediainfo):
+                    await self._async_update_local_recognize_cache(shared_cache_meta, mediainfo)
+                    await run_in_threadpool(self._record_media_recognize_share_hit)
+                    return mediainfo
+                if mediainfo and not fallback_mediainfo:
+                    fallback_mediainfo = mediainfo
+        return fallback_mediainfo
+
+    @staticmethod
+    def _media_recognize_plugin_payload(
+            meta: Optional[MetaBase],
+            mtype: Optional[MediaType],
+            media_source: Optional[MediaSource],
+            media_id: Optional[str],
+            is_music: bool,
+            music_type: Optional[str] = None,
+    ) -> dict:
+        """
+        构造媒体识别链式事件的已知要素载荷，供插件匹配媒体信息；影视与音乐统一协议，
+        仅要素字段随媒体类型不同
+        """
+        if is_music:
+            return {
+                "title": getattr(meta, "title", None),
+                "artists": list(getattr(meta, "artists", None) or []),
+                "album": getattr(meta, "album", None),
+                "year": getattr(meta, "year", None),
+                "isrc": getattr(meta, "isrc", None),
+                "media_source": media_source,
+                "media_id": media_id,
+                "music_type": music_type,
+            }
+        return {
+            "title": getattr(meta, "title", None) or getattr(meta, "name", None),
+            "year": getattr(meta, "year", None),
+            "season": getattr(meta, "begin_season", None),
+            "type": mtype.value if isinstance(mtype, MediaType) else None,
+            "media_source": media_source,
+            "media_id": media_id,
+        }
+
+    @classmethod
+    def _media_info_from_plugin(
+            cls,
+            event_data: dict,
+            is_music: bool,
+            mtype: Optional[MediaType] = None,
+            music_type: Optional[str] = None,
+    ) -> Optional[MediaInfo]:
+        """
+        解析插件返回的媒体信息，缺少数据源或身份字段的结果不采信；
+        音乐构造 MusicInfo，影视构造 MediaInfo
+        """
+        if not isinstance(event_data, dict):
+            return None
+        plugin_info = event_data.get("mediainfo")
+        if not isinstance(plugin_info, dict):
+            return None
+        if not plugin_info.get("media_source"):
+            logger.warn("插件返回的媒体信息缺少数据源，忽略 ...")
+            return None
+        try:
+            if is_music:
+                if not plugin_info.get("media_id"):
+                    logger.warn("插件返回的音乐媒体信息缺少媒体ID，忽略 ...")
+                    return None
+                info: MediaInfo = MusicInfo.from_dict(plugin_info)
+                if not info.media_source or not info.media_id:
+                    return None
+                if music_type and info.music_type != music_type:
+                    logger.warn(
+                        f"插件返回的音乐实体类型为 {info.music_type}，"
+                        f"与请求的 {music_type} 不一致，忽略 ..."
+                    )
+                    return None
+                return info
+            # 影视：插件未提供类型时使用请求推断的类型
+            if not plugin_info.get("type") and mtype:
+                plugin_info = {**plugin_info, "type": mtype}
+            info = MediaInfo()
+            info.from_dict(plugin_info)
+        except Exception as err:
+            logger.warn(f"插件返回的媒体信息格式错误：{err}")
+            return None
+        # 影视与音乐统一要求远端身份，无身份的结果不采信，避免未验证结果进入识别管线
+        if not info.media_source or not cls._media_info_has_identity(info):
+            logger.warn("插件返回的媒体信息缺少远端身份，忽略 ...")
+            return None
+        return info
+
+    @staticmethod
+    def _media_info_has_identity(mediainfo) -> bool:
+        """判断媒体信息是否具备完整的规范媒体身份。"""
+        media_source, media_id = resolve_media_identity(media=mediainfo)
+        return bool(media_source and media_id)
+
+    def _supplement_media_recognize(
+            self,
+            meta: Optional[MetaBase],
+            mtype: Optional[MediaType],
+            media_source: Optional[MediaSource],
+            media_id: Optional[str],
+            mediainfo,
+            music_type: Optional[str] = None,
+    ):
+        """
+        媒体识别插件补充（影视与音乐统一）：原生模块未给出带远端身份的结果时，
+        广播媒体识别链式事件，允许插件（如第三方媒体源）按已知要素匹配并返回标准信息
+        """
+        is_music = (
+                isinstance(meta, MetaMusic)
+                or mtype == MediaType.MUSIC
+                or isinstance(mediainfo, MusicInfo)
+        )
+        # 已有远端身份时无需插件介入
+        if mediainfo and self._media_info_has_identity(mediainfo):
+            return mediainfo
+        etype = ChainEventType.MusicMediaRecognize if is_music else ChainEventType.MediaRecognize
+        if not self.eventmanager.check(etype):
+            return mediainfo
+        result: Event = self.eventmanager.send_event(
+            etype,
+            self._media_recognize_plugin_payload(
+                meta, mtype, media_source, media_id, is_music, music_type
+            ),
+        )
+        if not result:
+            return mediainfo
+        plugin_info = self._media_info_from_plugin(
+            result.event_data or {}, is_music, mtype, music_type
+        )
+        if not plugin_info:
+            return mediainfo
+        logger.info(
+            f"插件补充媒体识别成功：{plugin_info.title}"
+            f"（{plugin_info.media_source}:{plugin_info.media_id}）"
+        )
+        return plugin_info
+
+    async def _async_supplement_media_recognize(
+            self,
+            meta: Optional[MetaBase],
+            mtype: Optional[MediaType],
+            media_source: Optional[MediaSource],
+            media_id: Optional[str],
+            mediainfo,
+            music_type: Optional[str] = None,
+    ):
+        """媒体识别插件补充的异步版本，影视与音乐统一流程"""
+        is_music = (
+                isinstance(meta, MetaMusic)
+                or mtype == MediaType.MUSIC
+                or isinstance(mediainfo, MusicInfo)
+        )
+        # 已有远端身份时无需插件介入
+        if mediainfo and self._media_info_has_identity(mediainfo):
+            return mediainfo
+        etype = ChainEventType.MusicMediaRecognize if is_music else ChainEventType.MediaRecognize
+        if not self.eventmanager.check(etype):
+            return mediainfo
+        result: Event = await self.eventmanager.async_send_event(
+            etype,
+            self._media_recognize_plugin_payload(
+                meta, mtype, media_source, media_id, is_music, music_type
+            ),
+        )
+        if not result:
+            return mediainfo
+        plugin_info = self._media_info_from_plugin(
+            result.event_data or {}, is_music, mtype, music_type
+        )
+        if not plugin_info:
+            return mediainfo
+        logger.info(
+            f"插件补充媒体识别成功：{plugin_info.title}"
+            f"（{plugin_info.media_source}:{plugin_info.media_id}）"
+        )
+        return plugin_info
+

app/chain/agent.py

@@ -0,0 +1,14 @@
+"""Agent 业务处理链。
+
+AgentChain 是 agent 编排在链层的入口：Agent 运行时会话需要复用
+ChainBase 提供的消息处理状态机（渠道处理状态、直发消息等），
+因此继承关系归属链层；具体 Agent 运行时（MoviePilotAgent 等）留在 app.agent。
+"""
+
+from app.chain import ChainBase
+
+
+class AgentChain(ChainBase):
+    """Agent 业务处理链。"""
+
+    pass

app/chain/message.py

@@ -11,8 +11,12 @@ from pathlib import Path
 from typing import Any, Optional, Dict, Union, List, Tuple
 from urllib.parse import unquote, urlparse
 
-from app.agent.orchestrator import agent_manager
-from app.agent.llm import AgentCapabilityManager, LLMHelper
+from app.application.agent import (
+    get_agent_manager,
+    is_audio_input_available,
+    supports_image_input,
+    transcribe_audio,
+)
 from app.chain import ChainBase
 from app.chain.download import DownloadChain
 from app.chain.media import MediaChain
@@ -68,7 +72,7 @@ class MessageChain(ChainBase):
             return
         clear_task = None
         try:
-            clear_task = agent_manager.clear_session(session_id=session_id, user_id=str(userid))
+            clear_task = get_agent_manager().clear_session(session_id=session_id, user_id=str(userid))
             asyncio.run_coroutine_threadsafe(
                 clear_task,
                 global_vars.loop,
@@ -346,7 +350,7 @@ class MessageChain(ChainBase):
         if not session_info:
             return False
         session_id, _ = session_info
-        if not agent_manager.matches_secret_confirmation(
+        if not get_agent_manager().matches_secret_confirmation(
             session_id,
             str(userid),
             channel=channel.value,
@@ -966,7 +970,7 @@ class MessageChain(ChainBase):
         if session_id:
             clear_task = None
             try:
-                clear_task = agent_manager.clear_session(
+                clear_task = get_agent_manager().clear_session(
                     session_id=session_id, user_id=str(userid)
                 )
                 asyncio.run_coroutine_threadsafe(
@@ -1015,7 +1019,7 @@ class MessageChain(ChainBase):
             session_id, _ = session_info
             try:
                 future = asyncio.run_coroutine_threadsafe(
-                    agent_manager.stop_current_task(session_id=session_id),
+                    get_agent_manager().stop_current_task(session_id=session_id),
                     global_vars.loop,
                 )
                 stopped = future.result(timeout=10)
@@ -1180,7 +1184,7 @@ class MessageChain(ChainBase):
             return
 
         session_id, _ = session_info
-        status = agent_manager.get_session_status(session_id=session_id)
+        status = get_agent_manager().get_session_status(session_id=session_id)
         self.post_message(
             Notification(
                 channel=channel,
@@ -1254,7 +1258,7 @@ class MessageChain(ChainBase):
             # 将可直接输入给 LLM 的附件统一转换为 data URL
             original_images = images
             all_files = list(files or [])
-            if images and LLMHelper.supports_image_input(
+            if images and supports_image_input(
                     provider=settings.LLM_PROVIDER,
                     model=settings.LLM_MODEL,
             ):
@@ -1333,7 +1337,7 @@ class MessageChain(ChainBase):
                 process_kwargs["has_audio_input"] = True
             # 在事件循环中处理
             asyncio.run_coroutine_threadsafe(
-                agent_manager.process_message(**process_kwargs),
+                get_agent_manager().process_message(**process_kwargs),
                 global_vars.loop,
             )
             return True
@@ -1353,7 +1357,7 @@ class MessageChain(ChainBase):
         """
         if not audio_refs:
             return None
-        if not AgentCapabilityManager.is_audio_input_available():
+        if not is_audio_input_available():
             logger.warning("音频输入能力未配置或未启用，跳过语音识别")
             return None
 
@@ -1460,7 +1464,7 @@ class MessageChain(ChainBase):
                     )
                     continue
 
-                transcript = AgentCapabilityManager.transcribe_audio(
+                transcript = transcribe_audio(
                     content=content, filename=filename
                 )
                 if transcript:

app/chain/search.py

@@ -509,10 +509,10 @@ class SearchChain(ChainBase):
         """
         通过统一后台提示词机制执行资源推荐。
         """
-        from app.agent.orchestrator import ReplyMode, agent_manager
-        from app.agent.prompt import prompt_manager
+        from app.application.agent import get_agent_manager, get_prompt_manager
+        from app.schemas.agent import ReplyMode
 
-        prompt = prompt_manager.render_system_task_message(
+        prompt = get_prompt_manager().render_system_task_message(
             "search_recommend",
             template_context={"search_results": search_results_text},
         )
@@ -521,7 +521,7 @@ class SearchChain(ChainBase):
         def on_output(text: str):
             full_output[0] = text
 
-        await agent_manager.run_background_prompt(
+        await get_agent_manager().run_background_prompt(
             message=prompt,
             session_prefix="__agent_search_recommend",
             output_callback=on_output,

app/chain/site.py

@@ -1,13 +1,14 @@
 import base64
 import re
 from datetime import datetime
-from typing import Callable, List, Optional, Tuple, Union, Dict
+from typing import Callable, Optional, Tuple, Union, Dict
 from urllib.parse import urljoin
 
 from app.application.site.sites import SitesHelper  # pylint: disable=no-name-in-module
 from lxml import etree
 
 from app.chain import ChainBase
+from app.chain._interaction import InteractionChainMixin
 from app.runtime.config import global_vars, settings
 from app.runtime.events import Event, eventmanager
 from app.db.models.site import Site
@@ -17,10 +18,7 @@ from app.adapters.network.browser import PlaywrightHelper
 from app.adapters.network.cloudflare import under_challenge
 from app.application.security.cookie import CookieHelper
 from app.adapters.external.cookiecloud import CookieCloudHelper
-from app.application.messaging.site import (
-    SiteInteractionHandler,
-    site_interaction_manager,
-)
+from app.application.messaging.site import SiteInteractionHandler
 from app.application.rss import RssHelper
 from app.runtime.log import logger
 from app.schemas import MessageChannel, Notification, SiteUserData
@@ -33,12 +31,13 @@ from app.foundation import url as url_tools
 from app.foundation.dom import DomUtils
 
 
-
-class SiteChain(ChainBase):
+class SiteChain(InteractionChainMixin, ChainBase):
     """
     站点管理处理链
     """
 
+    # 交互处理器类注入，供 InteractionChainMixin 的 parse_callback 委托
+    _interaction_handler_type = SiteInteractionHandler
 
     def __init__(self):
         """初始化站点管理处理链及特殊站点测试器"""
@@ -752,66 +751,6 @@ class SiteChain(ChainBase):
         """构造 /sites 交互处理器，Cookie 更新动作由本链提供。"""
         return SiteInteractionHandler(messenger=self, cookie_updater=self.update_cookie)
 
-    def remote_list(
-            self,
-            arg_str: str = "",
-            channel: MessageChannel = None,
-            userid: Union[str, int] = None,
-            source: Optional[str] = None,
-    ):
-        """
-        /sites 统一入口，委托交互处理器。
-        """
-        return self._interaction_handler().remote_list(
-            arg_str=arg_str, channel=channel, userid=userid, source=source
-        )
-
-    @staticmethod
-    def parse_callback(callback_data: str) -> Optional[Tuple[str, str]]:
-        """
-        解析 /sites 按钮回调。
-        """
-        return SiteInteractionHandler.parse_callback(callback_data)
-
-    def handle_callback_interaction(
-            self,
-            callback_data: str,
-            channel: MessageChannel,
-            source: str,
-            userid: Union[str, int],
-            username: str,
-            original_message_id: Optional[Union[str, int]] = None,
-            original_chat_id: Optional[str] = None,
-    ) -> bool:
-        """委托交互处理器处理按钮回调。"""
-        return self._interaction_handler().handle_callback_interaction(
-            callback_data=callback_data,
-            channel=channel,
-            source=source,
-            userid=userid,
-            username=username,
-            original_message_id=original_message_id,
-            original_chat_id=original_chat_id,
-        )
-
-    def handle_text_interaction(
-            self,
-            channel: MessageChannel,
-            source: str,
-            userid: Union[str, int],
-            username: str,
-            text: str,
-    ) -> bool:
-        """委托交互处理器处理文本输入。"""
-        return self._interaction_handler().handle_text_interaction(
-            channel=channel,
-            source=source,
-            userid=userid,
-            username=username,
-            text=text,
-        )
-
-
     def remote_disable(self, arg_str: str, channel: MessageChannel,
                        userid: Union[str, int] = None, source: Optional[str] = None):
         """

app/chain/subscribe.py

@@ -1,7 +1,6 @@
 import copy
 import json
 import random
-import re
 import threading
 import time
 from datetime import datetime
@@ -9,6 +8,8 @@ from typing import Any, Callable, Dict, List, Optional, Union, Tuple
 
 from app import schemas
 from app.chain import ChainBase
+from app.chain._interaction import InteractionChainMixin
+from app.chain._music import MusicSubscribeMixin
 from app.chain.download import DownloadChain
 from app.chain.media import MediaChain
 from app.chain.mediaserver import MediaServerChain
@@ -19,7 +20,6 @@ from app.runtime.config import settings, global_vars
 from app.domain.context import (
     Context,
     MediaInfo,
-    MusicInfo,
     TorrentInfo,
 )
 from app.runtime.events import eventmanager, Event
@@ -32,10 +32,7 @@ from app.db.models.subscribe import Subscribe
 from app.db.oper.site import SiteOper
 from app.db.oper.subscribe import SubscribeOper
 from app.db.oper.systemconfig import SystemConfigOper
-from app.application.messaging.subscribe import (
-    SubscribeInteractionHandler,
-    subscribe_interaction_manager,
-)
+from app.application.messaging.subscribe import SubscribeInteractionHandler
 from app.application.mediaserver import MediaServerHelper
 from app.application.subscribe import add_subscribe, async_add_subscribe
 from app.adapters.external.server import MoviePilotServerHelper
@@ -43,22 +40,11 @@ from app.application.torrent import TorrentHelper
 from app.runtime.log import logger
 from app.schemas import (SubscribeEpisodesRefreshEventData,
                          SubscribeCompletionCheckEventData)
-from app.schemas.types import MUSIC_ENTITY_ALBUM, MUSIC_ENTITY_RECORDING, MediaSource, MediaType, SystemConfigKey, MessageChannel, NotificationType, EventType, ChainEventType, \
+from app.schemas.types import MUSIC_ENTITY_ALBUM, MediaSource, MediaType, SystemConfigKey, MessageChannel, NotificationType, EventType, ChainEventType, \
     ContentType
-from app.domain.media import MUSIC_SUBSCRIBABLE_TYPES
 from app.schemas.media import build_media_key, normalize_media_source, resolve_media_identity
 
 
-
-def _normalize_music_total_tracks(value: Any) -> Optional[int]:
-    """将专辑曲目总数归一为正整数，无效或未知值返回 None。"""
-    try:
-        total_tracks = int(value or 0)
-    except (TypeError, ValueError):
-        return None
-    return total_tracks if total_tracks > 0 else None
-
-
 def build_subscribe_meta(subscribe: Subscribe) -> MetaBase:
     """
     按订阅对象构造主程序链路共用的媒体元数据。
@@ -116,7 +102,7 @@ def _subscribe_media_keys(subscribe: Subscribe) -> List[Union[str, int]]:
     return [candidate for candidate in candidates if candidate not in (None, "")]
 
 
-class SubscribeChain(ChainBase):
+class SubscribeChain(MusicSubscribeMixin, InteractionChainMixin, ChainBase):
     """
     订阅管理处理链。
 
@@ -133,6 +119,9 @@ class SubscribeChain(ChainBase):
     电影下载优先级 writer 单独维护。
     """
 
+    # 交互处理器类注入，供 InteractionChainMixin 的 parse_callback 委托
+    _interaction_handler_type = SubscribeInteractionHandler
+
     _rlock = threading.RLock()
     # 避免莫名原因导致长时间持有锁
     _LOCK_TIMOUT = 3600 * 2
@@ -1261,378 +1250,6 @@ class SubscribeChain(ChainBase):
             return True
         return False
 
-    @staticmethod
-    def _validate_music_subscribe_target(
-            mediainfo: MediaInfo,
-            requested_music_type: Optional[str] = None,
-    ) -> Optional[str]:
-        """校验音乐订阅实体一致性，并确保专辑具备可验证的曲目总数。"""
-        if mediainfo.type != MediaType.MUSIC:
-            return "识别结果不是音乐"
-        music_type = getattr(mediainfo, "music_type", None)
-        if requested_music_type and requested_music_type not in MUSIC_SUBSCRIBABLE_TYPES:
-            return "音乐订阅仅支持单曲或专辑"
-        if music_type not in MUSIC_SUBSCRIBABLE_TYPES:
-            return "音乐订阅仅支持单曲或专辑"
-        if requested_music_type and requested_music_type != music_type:
-            return f"音乐订阅类型不匹配：请求 {requested_music_type}，识别为 {music_type}"
-        if music_type == MUSIC_ENTITY_ALBUM \
-                and _normalize_music_total_tracks(getattr(mediainfo, "total_tracks", None)) is None:
-            return "专辑总曲目数未知，无法校验整张专辑资源"
-        return None
-
-    @staticmethod
-    def _ensure_music_subscribe_entity(
-            subscribe: Subscribe,
-            mediainfo: Optional[MusicInfo],
-    ) -> Optional[MusicInfo]:
-        """保持已持久化的单曲/专辑实体边界，拒绝远端详情把订阅类型改写。"""
-        if not mediainfo:
-            return None
-        expected_type = getattr(subscribe, "music_type", None)
-        actual_type = getattr(mediainfo, "music_type", None)
-        if expected_type and expected_type not in MUSIC_SUBSCRIBABLE_TYPES:
-            logger.warning(f"音乐订阅 {subscribe.name} 的实体类型无效：{expected_type}")
-            return None
-        if actual_type not in MUSIC_SUBSCRIBABLE_TYPES:
-            logger.warning(
-                f"音乐订阅 {subscribe.name} 识别为不可订阅实体：{actual_type}"
-            )
-            if expected_type in MUSIC_SUBSCRIBABLE_TYPES:
-                return SubscribeChain._music_info_from_subscribe(subscribe)
-            return None
-        if expected_type and actual_type != expected_type:
-            logger.warning(
-                f"音乐订阅 {subscribe.name} 实体不匹配："
-                f"订阅为 {expected_type}，远端识别为 {actual_type}，使用订阅快照"
-            )
-            return SubscribeChain._music_info_from_subscribe(subscribe)
-        if actual_type == MUSIC_ENTITY_ALBUM:
-            remote_total = _normalize_music_total_tracks(getattr(mediainfo, "total_tracks", None))
-            stored_total = _normalize_music_total_tracks(getattr(subscribe, "total_tracks", None))
-            resolved_total = remote_total or stored_total
-            if resolved_total is not None and mediainfo.total_tracks != resolved_total:
-                # 识别模块结果可能来自共享缓存，补齐订阅快照时不得原地修改。
-                mediainfo = copy.copy(mediainfo)
-                mediainfo.total_tracks = resolved_total
-        return mediainfo
-
-    @staticmethod
-    def _recognize_music_subscribe(subscribe: Subscribe) -> Optional[MusicInfo]:
-        """按订阅身份恢复音乐目标，远端暂不可用时使用已持久化的稳定快照。"""
-        if subscribe.media_source and subscribe.media_id:
-            # 与影视共用统一识别入口，按媒体源和原生 ID 恢复音乐详情
-            mediainfo = MediaChain().recognize_media(
-                media_source=subscribe.media_source,
-                media_id=str(subscribe.media_id),
-                mtype=MediaType.MUSIC,
-                music_type=getattr(subscribe, "music_type", None),
-            )
-            if mediainfo:
-                return SubscribeChain._ensure_music_subscribe_entity(subscribe, mediainfo)
-            if getattr(subscribe, "music_type", None) in {MUSIC_ENTITY_RECORDING, MUSIC_ENTITY_ALBUM}:
-                return SubscribeChain._music_info_from_subscribe(subscribe)
-            # 旧订阅没有保存实体类型时不能猜测为单曲，否则可能误把专辑按单曲完成。
-            return None
-        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
-            # 缺少远端 ID 的专辑不能退化为单曲识别，使用已保存专辑快照更可靠。
-            return SubscribeChain._music_info_from_subscribe(subscribe)
-        # 旧订阅没有实体类型时只允许走 Recording 识别，不能从全局混合搜索中猜成专辑或艺术家。
-        mediainfo = MediaChain().recognize_media(
-            meta=build_subscribe_meta(subscribe),
-            mtype=MediaType.MUSIC,
-            media_source=subscribe.media_source,
-            music_type=MUSIC_ENTITY_RECORDING,
-        )
-        return SubscribeChain._ensure_music_subscribe_entity(subscribe, mediainfo)
-
-    @staticmethod
-    async def _async_recognize_music_subscribe(subscribe: Subscribe) -> Optional[MusicInfo]:
-        """异步按订阅身份恢复音乐目标，远端暂不可用时使用已持久化的稳定快照。"""
-        if subscribe.media_source and subscribe.media_id:
-            # 与影视共用统一识别入口，按媒体源和原生 ID 恢复音乐详情
-            mediainfo = await MediaChain().async_recognize_media(
-                media_source=subscribe.media_source,
-                media_id=str(subscribe.media_id),
-                mtype=MediaType.MUSIC,
-                music_type=getattr(subscribe, "music_type", None),
-            )
-            if mediainfo:
-                return SubscribeChain._ensure_music_subscribe_entity(subscribe, mediainfo)
-            if getattr(subscribe, "music_type", None) in {MUSIC_ENTITY_RECORDING, MUSIC_ENTITY_ALBUM}:
-                return SubscribeChain._music_info_from_subscribe(subscribe)
-            return None
-        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
-            return SubscribeChain._music_info_from_subscribe(subscribe)
-        mediainfo = await MediaChain().async_recognize_media(
-            meta=build_subscribe_meta(subscribe),
-            mtype=MediaType.MUSIC,
-            media_source=subscribe.media_source,
-            music_type=MUSIC_ENTITY_RECORDING,
-        )
-        return SubscribeChain._ensure_music_subscribe_entity(subscribe, mediainfo)
-
-    @staticmethod
-    def _music_info_from_subscribe(subscribe: Subscribe) -> MusicInfo:
-        """从订阅行恢复不依赖远端请求的最小音乐目标，保留专辑完成判断所需字段。"""
-        year_text = str(subscribe.year or "")[:4]
-        music_type = getattr(subscribe, "music_type", None)
-        # 音乐订阅的 description 由标准 MusicInfo.overview 生成，首段固定为艺术家。
-        artist_text = str(getattr(subscribe, "description", None) or "") \
-            .split(" · ", maxsplit=1)[0].strip()
-        artists = [
-            artist.strip() for artist in artist_text.split(" / ") if artist.strip()
-        ]
-        return MusicInfo(
-            media_source=subscribe.media_source,
-            media_id=str(subscribe.media_id) if subscribe.media_id is not None else None,
-            music_type=music_type,
-            title=subscribe.name,
-            artists=artists,
-            album=subscribe.name if music_type == MUSIC_ENTITY_ALBUM else None,
-            year=int(year_text) if year_text.isdigit() else None,
-            total_tracks=getattr(subscribe, "total_tracks", None)
-            if music_type == MUSIC_ENTITY_ALBUM else None,
-            cover_url=getattr(subscribe, "poster", None) or getattr(subscribe, "backdrop", None),
-        )
-
-    @staticmethod
-    def _sync_music_subscribe_target(subscribe: Subscribe, mediainfo: MusicInfo) -> None:
-        """把远端识别得到的专辑类型和总曲目数同步到订阅，供搜索失败与完成历史复用。"""
-        update_data = {}
-        if mediainfo.music_type and getattr(subscribe, "music_type", None) != mediainfo.music_type:
-            update_data["music_type"] = mediainfo.music_type
-        if mediainfo.music_type == MUSIC_ENTITY_ALBUM:
-            # 远端详情可能暂时不返回曲目数；已确认的订阅快照不能因此被清空。
-            total_tracks = _normalize_music_total_tracks(mediainfo.total_tracks) \
-                or _normalize_music_total_tracks(getattr(subscribe, "total_tracks", None))
-        else:
-            total_tracks = None
-        if getattr(subscribe, "total_tracks", None) != total_tracks:
-            update_data["total_tracks"] = total_tracks
-        if not update_data:
-            return
-        SubscribeOper().update(subscribe.id, update_data)
-        for key, value in update_data.items():
-            setattr(subscribe, key, value)
-
-    @staticmethod
-    def _is_music_download_complete(
-            subscribe: Subscribe,
-            mediainfo: MusicInfo,
-            downloads: Optional[List[Context]],
-    ) -> bool:
-        """判断音乐下载是否满足订阅完成条件；专辑必须由下载层确认整专曲目覆盖。"""
-        if not downloads:
-            return False
-        music_type = getattr(subscribe, "music_type", None) or mediainfo.music_type
-        if music_type != MUSIC_ENTITY_ALBUM:
-            return True
-        return any(context.confirmed_full_coverage for context in downloads)
-
-    def _prepare_music_subscribe(
-            self,
-            subscribe: Subscribe,
-    ) -> Optional[Tuple[MusicInfo, MetaMusic]]:
-        """识别音乐订阅目标、同步实体快照，并在搜索前处理已完整入库的目标。"""
-        mediainfo = self._recognize_music_subscribe(subscribe)
-        if not mediainfo:
-            logger.warning(
-                f"未识别到音乐订阅目标：{subscribe.name}，"
-                f"媒体源：{subscribe.media_source}，媒体ID：{subscribe.media_id}"
-            )
-            return None
-        validation_error = self._validate_music_subscribe_target(
-            mediainfo,
-            getattr(subscribe, "music_type", None),
-        )
-        if validation_error:
-            logger.warning(f"音乐订阅 {subscribe.name} 无法继续：{validation_error}")
-            return None
-        self._sync_music_subscribe_target(subscribe, mediainfo)
-        meta = MetaMusic.from_music_info(mediainfo)
-        exists, _ = self.check_and_handle_existing_media(
-            subscribe=subscribe,
-            meta=meta,
-            mediainfo=mediainfo,
-            mediakey=_subscribe_media_key(subscribe),
-        )
-        if exists:
-            return None
-        return mediainfo, meta
-
-    def _filter_music_subscribe_contexts(
-            self,
-            subscribe: Subscribe,
-            mediainfo: MusicInfo,
-            contexts: List[Context],
-    ) -> List[Context]:
-        """按站点、音乐实体、订阅参数和优先级规则筛选并绑定下载上下文。"""
-        sites = self.get_sub_sites(subscribe)
-        default_rule_key = SystemConfigKey.BestVersionFilterRuleGroups \
-            if subscribe.best_version else SystemConfigKey.SubscribeFilterRuleGroups
-        rule_groups = subscribe.filter_groups or SystemConfigOper().get(default_rule_key) or []
-        torrent_helper = TorrentHelper()
-        matched: List[Context] = []
-        for source_context in contexts or []:
-            source_torrent = source_context.torrent_info
-            if not source_torrent or source_torrent.category not in (MediaType.MUSIC, MediaType.MUSIC.value):
-                continue
-            # 过滤模块会就地写入 pri_order；RSS 缓存会被多个订阅复用，必须隔离候选副本。
-            torrent = copy.copy(source_torrent)
-            if sites and torrent.site not in sites:
-                continue
-            if not SearchChain.matches_music_resource(
-                    mediainfo,
-                    torrent.title,
-                    torrent.description,
-            ):
-                continue
-            if not torrent_helper.filter_torrent(torrent, self.get_params(subscribe)):
-                continue
-            filtered = self.filter_torrents(
-                rule_groups=rule_groups,
-                torrent_list=[torrent],
-                mediainfo=mediainfo,
-            )
-            if filtered is not None:
-                if not filtered:
-                    continue
-                torrent = filtered[0]
-
-            context = copy.copy(source_context)
-            context.torrent_info = torrent
-            meta = MetaMusic.from_music_info(mediainfo)
-            meta.org_string = torrent.title
-            meta.apply_audio_quality(f"{torrent.title} {torrent.description or ''}", overwrite=True)
-            if subscribe.best_version:
-                # 用户规则组可用格式、码率等内置规则定义洗版顺序；未命中规则
-                # 优先级时再回退到规范化音质分数，确保零配置也能自动升级。
-                music_priority = torrent.pri_order or meta.audio_quality_score
-                if music_priority <= (subscribe.current_priority or 0):
-                    logger.info(
-                        f"{torrent.title} 音质优先级 {music_priority} "
-                        f"未高于当前版本 {subscribe.current_priority or 0}"
-                    )
-                    continue
-                torrent.pri_order = music_priority
-            context.meta_info = meta
-            context.media_info = mediainfo
-            context.match_source = str(mediainfo.media_source or "title")
-            context.candidate_recognized = False
-            context.media_info_is_target = True
-            if subscribe.media_category:
-                context.media_info.category = subscribe.media_category
-            matched.append(context)
-        return matched
-
-    def _download_music_subscribe(
-            self,
-            subscribe: Subscribe,
-            mediainfo: MusicInfo,
-            contexts: List[Context],
-    ) -> None:
-        """批量择优下载音乐候选，并按单曲或整专完成语义推进订阅。"""
-        if not contexts:
-            return
-        downloads, _ = DownloadChain().batch_download(
-            contexts=contexts,
-            username=subscribe.username,
-            save_path=subscribe.save_path,
-            downloader=subscribe.downloader,
-            source=self.get_subscribe_source_keyword(subscribe),
-            custom_words=subscribe.custom_words,
-        )
-        successful = [
-            context for context in downloads or []
-            if context and context.meta_info and context.torrent_info
-        ]
-        quality_downloads = successful
-        if getattr(subscribe, "music_type", None) == MUSIC_ENTITY_ALBUM:
-            quality_downloads = [
-                context for context in successful
-                if context.confirmed_full_coverage
-            ]
-        if subscribe.best_version and quality_downloads:
-            best_context = max(quality_downloads, key=lambda item: item.torrent_info.pri_order)
-            best_meta = best_context.meta_info
-            quality_data = {
-                "current_priority": best_context.torrent_info.pri_order,
-                "current_audio_format": best_meta.audio_format,
-                "current_bitrate": best_meta.bitrate,
-                "current_bit_depth": best_meta.bit_depth,
-                "current_sample_rate": best_meta.sample_rate,
-            }
-            SubscribeOper().update(subscribe.id, quality_data)
-            for key, value in quality_data.items():
-                setattr(subscribe, key, value)
-        current_subscribe = SubscribeOper().get(subscribe.id)
-        if current_subscribe:
-            self.finish_subscribe_or_not(
-                subscribe=current_subscribe,
-                meta=MetaMusic.from_music_info(mediainfo),
-                mediainfo=mediainfo,
-                downloads=downloads,
-            )
-
-    def _search_music_subscribe(self, subscribe: Subscribe) -> None:
-        """复用站点标题搜索、订阅过滤和批量下载完成单个音乐订阅。"""
-        target = self._prepare_music_subscribe(subscribe)
-        if not target:
-            return
-        mediainfo, _ = target
-
-        sites = self.get_sub_sites(subscribe)
-        default_rule_key = SystemConfigKey.BestVersionFilterRuleGroups \
-            if subscribe.best_version else SystemConfigKey.SubscribeFilterRuleGroups
-        rule_groups = subscribe.filter_groups or SystemConfigOper().get(default_rule_key) or []
-        keywords = [subscribe.keyword] if subscribe.keyword else SearchChain.music_site_keywords(mediainfo)
-        if not keywords:
-            keywords = [subscribe.name]
-
-        searchchain = SearchChain()
-        contexts: List[Context] = []
-        for keyword in keywords:
-            contexts = searchchain.search_by_title(
-                title=keyword,
-                sites=sites,
-                mtype=MediaType.MUSIC,
-                rule_groups=rule_groups,
-            )
-            contexts = self._filter_music_subscribe_contexts(
-                subscribe=subscribe,
-                mediainfo=mediainfo,
-                contexts=contexts,
-            )
-            if contexts:
-                break
-
-        if not contexts:
-            logger.warning(f"音乐订阅 {subscribe.keyword or subscribe.name} 未搜索到符合条件的资源")
-            return
-
-        self._download_music_subscribe(subscribe, mediainfo, contexts)
-
-    def _match_music_subscribe(
-            self,
-            subscribe: Subscribe,
-            contexts: List[Context],
-    ) -> None:
-        """直接匹配本轮 RSS 缓存中的音乐资源，避免再次调用站点搜索接口。"""
-        target = self._prepare_music_subscribe(subscribe)
-        if not target:
-            return
-        mediainfo, _ = target
-        matched = self._filter_music_subscribe_contexts(
-            subscribe=subscribe,
-            mediainfo=mediainfo,
-            contexts=contexts,
-        )
-        if not matched:
-            logger.info(f"音乐订阅 {subscribe.name} 未匹配到符合条件的 RSS 资源")
-            return
-        self._download_music_subscribe(subscribe, mediainfo, matched)
-
     def search(
             self,
             sid: Optional[int] = None,
@@ -3247,66 +2864,6 @@ class SubscribeChain(ChainBase):
         """构造 /subscribes 交互处理器，业务动作由本链提供。"""
         return SubscribeInteractionHandler(messenger=self, actions=self)
 
-    def remote_list(
-            self,
-            arg_str: str = "",
-            channel: MessageChannel = None,
-            userid: Union[str, int] = None,
-            source: Optional[str] = None,
-    ):
-        """
-        /subscribes 统一入口，委托交互处理器。
-        """
-        return self._interaction_handler().remote_list(
-            arg_str=arg_str, channel=channel, userid=userid, source=source
-        )
-
-    @staticmethod
-    def parse_callback(callback_data: str) -> Optional[Tuple[str, str]]:
-        """
-        解析 /subscribes 按钮回调。
-        """
-        return SubscribeInteractionHandler.parse_callback(callback_data)
-
-    def handle_callback_interaction(
-            self,
-            callback_data: str,
-            channel: MessageChannel,
-            source: str,
-            userid: Union[str, int],
-            username: str,
-            original_message_id: Optional[Union[str, int]] = None,
-            original_chat_id: Optional[str] = None,
-    ) -> bool:
-        """委托交互处理器处理按钮回调。"""
-        return self._interaction_handler().handle_callback_interaction(
-            callback_data=callback_data,
-            channel=channel,
-            source=source,
-            userid=userid,
-            username=username,
-            original_message_id=original_message_id,
-            original_chat_id=original_chat_id,
-        )
-
-    def handle_text_interaction(
-            self,
-            channel: MessageChannel,
-            source: str,
-            userid: Union[str, int],
-            username: str,
-            text: str,
-    ) -> bool:
-        """委托交互处理器处理文本输入。"""
-        return self._interaction_handler().handle_text_interaction(
-            channel=channel,
-            source=source,
-            userid=userid,
-            username=username,
-            text=text,
-        )
-
-
     def remote_delete(self, arg_str: str, channel: MessageChannel,
                       userid: Union[str, int] = None, source: Optional[str] = None):
         """

app/domain/context.py

@@ -1490,6 +1490,11 @@ class MediaInfo:
             meta = MetaInfo(self.title)
             season = meta.begin_season if meta.begin_season is not None else 1
             episodes_count = info.get("total_episodes") or info.get("eps")
+            # bangumi 返回的集数可能为字符串，统一转整型避免拼接/范围构造异常
+            try:
+                episodes_count = int(episodes_count) if episodes_count else 0
+            except (TypeError, ValueError):
+                episodes_count = 0
             if episodes_count:
                 self.seasons[season] = list(range(1, episodes_count + 1))
                 self.number_of_episodes = episodes_count

app/factory.py

@@ -8,6 +8,7 @@ from fastapi.responses import JSONResponse
 from starlette.exceptions import HTTPException
 
 from app.api.response import ResponseAPIRoute
+from app.application.plugins import register_api_app
 from app.runtime.config import settings
 from app.runtime.localization import LocaleHelper
 from app.runtime.log import logger
@@ -326,3 +327,7 @@ def create_app() -> FastAPI:
 
 # 创建 FastAPI 应用实例
 app = create_app()
+
+# 向 application 层插件路由服务注入应用实例，插件 API 的动态注册/移除
+# 统一经服务完成，避免 api.endpoints 反向依赖本模块。
+register_api_app(app)

app/modules/_base/__init__.py

@@ -0,0 +1,15 @@
+"""模块业务样板基类包。
+
+沉淀各内置模块逐字复制的业务样板，模块发现规则
+（`ModuleHelper.load`）会跳过 `_` 前缀的包与类，因此本包不会被识别为可实例化模块。
+"""
+
+from app.modules._base.downloader import _DownloaderModuleBase
+from app.modules._base.mediaserver import _MediaServerModuleBase
+from app.modules._base.notification import _MessageChannelModuleBase
+
+__all__ = [
+    "_DownloaderModuleBase",
+    "_MessageChannelModuleBase",
+    "_MediaServerModuleBase",
+]

app/modules/_base/downloader.py

@@ -0,0 +1,109 @@
+"""下载器模块业务样板基类。
+
+沉淀三个内置下载器模块（qbittorrent/transmission/rtorrent）逐字复制的样板：
+连接测试、定时重连、种子信息读取与查询状态归一。差异化逻辑
+（任务添加、原始状态映射、任务列表构建）仍留在各模块。
+"""
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+from torrentool.torrent import Torrent
+
+from app.domain import torrent as torrent_rules
+from app.modules import _DownloaderBase, _ModuleBase, TService
+from app.runtime.cache import FileCache
+from app.runtime.log import logger
+from app.schemas.types import TorrentQueryStatus, TorrentStatus
+
+
+class _DownloaderModuleBase(_ModuleBase, _DownloaderBase[TService]):
+    """
+    下载器模块业务样板基类。
+    """
+
+    def test(self) -> Optional[Tuple[bool, str]]:
+        """
+        测试模块连接性
+        """
+        if not self.get_instances():
+            return None
+        for name, server in self.get_instances().items():
+            if server.is_inactive():
+                server.reconnect()
+            if not server.transfer_info():
+                return False, f"无法连接{self.get_name()}下载器：{name}"
+        return True, ""
+
+    def scheduler_job(self) -> None:
+        """
+        定时任务，每10分钟调用一次
+        """
+        for name, server in self.get_instances().items():
+            if server.is_inactive():
+                logger.info(f"{self.get_name()}下载器 {name} 连接断开，尝试重连 ...")
+                server.reconnect()
+
+    def _get_torrent_info(self, content: Union[Path, str, bytes]) \
+            -> Tuple[Optional[Torrent], Optional[bytes]]:
+        """
+        读取种子内容，返回解析后的种子信息与原始内容，磁力链接不解析
+        """
+        torrent_info, torrent_content = None, None
+        try:
+            if isinstance(content, Path):
+                if content.exists():
+                    torrent_content = content.read_bytes()
+                else:
+                    # 读取缓存的种子文件
+                    torrent_content = FileCache().get(
+                        content.as_posix(), region="torrents"
+                    )
+            else:
+                torrent_content = content
+
+            if torrent_content:
+                # 检查是否为磁力链接
+                if torrent_rules.is_magnet_link(torrent_content):
+                    return None, torrent_content
+                else:
+                    torrent_info = Torrent.from_string(torrent_content)
+
+            return torrent_info, torrent_content
+        except Exception as e:
+            logger.error(f"获取种子名称失败：{e}")
+            return None, None
+
+    @staticmethod
+    def _normalize_query_status(
+            status: Optional[Union[TorrentStatus, TorrentQueryStatus, str]]
+    ) -> TorrentQueryStatus:
+        """
+        归一任务查询状态。
+        """
+        status_value = getattr(status, "value", status)
+        status_text = str(status_value or "").strip().lower()
+        if not status_text or status_text in {"all", "全部"}:
+            return TorrentQueryStatus.ALL
+        if status_text in {
+            TorrentStatus.TRANSFER.value,
+            TorrentQueryStatus.TRANSFER.value,
+            "transfer",
+        }:
+            return TorrentQueryStatus.TRANSFER
+        if status_text in {
+            TorrentStatus.DOWNLOADING.value,
+            TorrentQueryStatus.DOWNLOADING.value,
+            "downloading",
+        }:
+            return TorrentQueryStatus.DOWNLOADING
+        if status_text in {
+            TorrentQueryStatus.COMPLETED.value,
+            "complete",
+            "seeding",
+            "完成",
+            "已完成",
+        }:
+            return TorrentQueryStatus.COMPLETED
+        if status_text in {TorrentQueryStatus.PAUSED.value, "pause", "暂停", "已暂停"}:
+            return TorrentQueryStatus.PAUSED
+        return TorrentQueryStatus.ALL

app/modules/_base/mediaserver.py

@@ -0,0 +1,192 @@
+"""媒体服务器模块业务样板基类。
+
+沉淀各媒体服务器模块逐字复制的样板：用户辅助认证、媒体存在性检查、
+定时重连与连接测试。服务器差异（认证 API、存在性检查端点、连接探测方式）
+通过类属性与钩子方法保留在各模块。
+"""
+from typing import Optional, Tuple
+
+from app import schemas
+from app.application.mediaserver import MusicMediaServerHelper
+from app.domain.context import MediaInfo
+from app.modules import _MediaServerBase, _ModuleBase, TService
+from app.runtime.events import eventmanager
+from app.runtime.log import logger
+from app.schemas.types import ChainEventType, MediaType
+
+
+class _MediaServerModuleBase(_ModuleBase, _MediaServerBase[TService]):
+    """
+    媒体服务器模块业务样板基类。
+    """
+
+    # 媒体库标识（用于 ExistMediaInfo.server_type，如 "emby"），子类覆写
+    _server_type_value: str = ""
+
+    def user_authenticate(
+            self,
+            credentials: schemas.AuthCredentials,
+            service_name: Optional[str] = None,
+    ) -> Optional[schemas.AuthCredentials]:
+        """
+        使用媒体服务器用户辅助完成用户认证
+
+        :param credentials: 认证数据
+        :param service_name: 指定要认证的媒体服务器名称，若为 None 则认证所有服务器
+        :return: 认证数据
+        """
+        if not credentials or credentials.grant_type != "password":
+            return None
+        # 确定要认证的服务器列表
+        if service_name:
+            # 如果指定了服务名，获取该服务实例
+            servers = (
+                [(service_name, server)]
+                if (server := self.get_instance(service_name))
+                else []
+            )
+        else:
+            # 如果没有指定服务名，遍历所有服务
+            servers = self.get_instances().items()
+        # 遍历要认证的服务器
+        for name, server in servers:
+            # 触发认证拦截事件
+            intercept_event = eventmanager.send_event(
+                etype=ChainEventType.AuthIntercept,
+                data=schemas.AuthInterceptCredentials(
+                    username=credentials.username,
+                    channel=self.get_name(),
+                    service=name,
+                    status="triggered",
+                ),
+            )
+            if intercept_event and intercept_event.event_data:
+                intercept_data: schemas.AuthInterceptCredentials = intercept_event.event_data
+                if intercept_data.cancel:
+                    continue
+            token = server.authenticate(credentials.username, credentials.password)
+            if token:
+                credentials.channel = self.get_name()
+                credentials.service = name
+                credentials.token = token
+                return credentials
+        return None
+
+    def media_exists(
+            self,
+            mediainfo: MediaInfo,
+            itemid: Optional[str] = None,
+            server: Optional[str] = None,
+    ) -> Optional[schemas.ExistMediaInfo]:
+        """
+        判断媒体文件是否存在
+
+        :param mediainfo:  识别的媒体信息
+        :param itemid:  媒体服务器ItemID
+        :param server:  媒体服务器名称
+        :return: 如不存在返回None，存在时返回信息，包括每季已存在所有集{type: movie/tv, seasons: {season: [episodes]}}
+        """
+        if server:
+            servers = [(server, self.get_instance(server))]
+        else:
+            servers = self.get_instances().items()
+        for name, s in servers:
+            if not s:
+                continue
+            if mediainfo.type == MediaType.MUSIC:
+                # 部分服务器未实现音乐查询，退化为空列表
+                matches = getattr(s, "get_music", lambda **_: [])(
+                    **MusicMediaServerHelper.search_params(mediainfo)
+                )
+                match = MusicMediaServerHelper.find_match(mediainfo, matches)
+                if match:
+                    return schemas.ExistMediaInfo(
+                        type=MediaType.MUSIC,
+                        server_type=self._server_type_value,
+                        server=name,
+                        itemid=match.item_id,
+                    )
+                continue
+            if mediainfo.type == MediaType.MOVIE:
+                if itemid:
+                    movie = s.get_iteminfo(itemid)
+                    if movie:
+                        logger.info(f"媒体库 {name} 中找到了 {movie}")
+                        return schemas.ExistMediaInfo(
+                            type=MediaType.MOVIE,
+                            server_type=self._server_type_value,
+                            server=name,
+                            itemid=movie.item_id
+                        )
+                movies = s.get_movies(title=mediainfo.title,
+                                      year=mediainfo.year,
+                                      media_source=mediainfo.media_source,
+                                      media_id=mediainfo.media_id)
+                if not movies:
+                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
+                    continue
+                else:
+                    logger.info(f"媒体库 {name} 中找到了 {movies}")
+                    return schemas.ExistMediaInfo(
+                        type=MediaType.MOVIE,
+                        server_type=self._server_type_value,
+                        server=name,
+                        itemid=movies[0].item_id
+                    )
+            else:
+                itemid, tvs = s.get_tv_episodes(title=mediainfo.title,
+                                                year=mediainfo.year,
+                                                media_source=mediainfo.media_source,
+                                                media_id=mediainfo.media_id,
+                                                item_id=itemid)
+                if not tvs:
+                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
+                    continue
+                else:
+                    logger.info(f"{mediainfo.title_year} 在媒体库 {name} 中找到 了这些季集：{tvs}")
+                    return schemas.ExistMediaInfo(
+                        type=MediaType.TV,
+                        seasons=tvs,
+                        server_type=self._server_type_value,
+                        server=name,
+                        itemid=itemid
+                    )
+        return None
+
+    def scheduler_job(self) -> None:
+        """
+        定时任务，每10分钟调用一次
+        """
+        # 定时重连
+        for name, server in self.get_instances().items():
+            if self._is_inactive(server):
+                logger.info(f"{self.get_name()}服务器 {name} 连接断开，尝试重连 ...")
+                server.reconnect()
+
+    def _is_inactive(self, server) -> bool:
+        """
+        定时重连的失活判断钩子，子类可覆写（如增加配置完整性检查）。
+        """
+        return server.is_inactive()
+
+    def test(self) -> Optional[Tuple[bool, str]]:
+        """
+        测试模块连接性
+        """
+        if not self.get_instances():
+            return None
+        for name, server in self.get_instances().items():
+            error = self._test_server(server, name)
+            if error:
+                return False, error
+        return True, ""
+
+    def _test_server(self, server, name: str) -> Optional[str]:
+        """
+        连接测试钩子，返回失败信息，None 表示就绪，子类可覆写。
+        """
+        if server.is_inactive():
+            server.reconnect()
+        if not server.get_user():
+            return f"无法连接{self.get_name()}服务器：{name}"
+        return None

app/modules/_base/notification.py

@@ -0,0 +1,149 @@
+"""消息渠道模块业务样板基类。
+
+沉淀各消息渠道模块逐字复制的样板：管理员判断、连接测试、
+斜杠命令注册。渠道差异（客户端类型、菜单 API、前置条件）通过
+类属性与钩子方法保留在各模块。
+"""
+import copy
+from typing import Dict, List, Optional, Tuple, Union
+
+from app.application.messaging.agent import (
+    matches_channel_admin,
+    resolve_config_principal_ids,
+)
+from app.foundation.collections import DictUtils
+from app.modules import _MessageBase, _ModuleBase, TService
+from app.runtime.events import eventmanager
+from app.runtime.log import logger
+from app.schemas import CommandRegisterEventData
+from app.schemas.types import ChainEventType
+
+
+class _MessageChannelModuleBase(_ModuleBase, _MessageBase[TService]):
+    """
+    消息渠道模块业务样板基类。
+    """
+
+    # 管理员配置键，子类覆写（如 "TELEGRAM_ADMINS"）
+    _admin_config_key: str = ""
+    # 命令注册事件源标识，默认取模块名，子类可覆写
+    _command_origin: Optional[str] = None
+
+    @classmethod
+    def _get_admins(cls, config: Optional[dict]) -> List[str]:
+        """
+        解析渠道管理员配置，兼容逗号分隔和首尾空白。
+        """
+        return sorted(resolve_config_principal_ids(config, cls._admin_config_key))
+
+    def _should_reject_admin_command(
+            self,
+            config: Optional[dict],
+            *user_ids: Optional[Union[str, int]],
+    ) -> bool:
+        """
+        判断命令或命令型按钮回调是否应因非管理员身份被拒绝。
+        """
+        if not self._get_admins(config):
+            return False
+        # 模块实例未初始化时 self._channel 为空，退回静态子类型声明
+        channel = self._channel or self.get_subtype()
+        return not matches_channel_admin(
+            channel,
+            config,
+            *user_ids,
+        )
+
+    def test(self) -> Optional[Tuple[bool, str]]:
+        """
+        测试模块连接性
+        """
+        if not self.get_instances():
+            return None
+        for name, client in self.get_instances().items():
+            state, message = self._test_connection(client)
+            if not state:
+                suffix = f"：{message}" if message else ""
+                return False, f"{self.get_name()} {name} 未就绪{suffix}"
+        return True, ""
+
+    def _test_connection(self, client) -> Tuple[bool, str]:
+        """
+        连接测试钩子，返回 (是否就绪, 失败信息)，子类可覆写。
+        """
+        return bool(client.get_state()), ""
+
+    def register_commands(self, commands: Dict[str, dict]) -> None:
+        """
+        注册命令，实现这个函数接收系统可用的命令菜单
+
+        :param commands: 命令字典
+        """
+        for client_config in self.get_configs().values():
+            if not self._commands_enabled(client_config.config):
+                continue
+
+            client = self.get_instance(client_config.name)
+            if not client:
+                continue
+
+            # 触发事件，允许调整命令数据，这里需要进行深复制，避免实例共享
+            scoped_commands = copy.deepcopy(commands)
+            event = eventmanager.send_event(
+                ChainEventType.CommandRegister,
+                CommandRegisterEventData(
+                    commands=scoped_commands,
+                    origin=self._command_origin or self.get_name(),
+                    service=client_config.name,
+                ),
+            )
+
+            # 如果事件返回有效的 event_data，使用事件中调整后的命令
+            if event and event.event_data:
+                event_data: CommandRegisterEventData = event.event_data
+                # 如果事件被取消，跳过命令注册，并清理菜单
+                if event_data.cancel:
+                    self._delete_commands(client)
+                    logger.debug(
+                        f"Command registration for {client_config.name} canceled by event: {event_data.source}"
+                    )
+                    continue
+                scoped_commands = event_data.commands or {}
+                if not scoped_commands:
+                    logger.debug("Filtered commands are empty, skipping registration.")
+                    self._delete_commands(client)
+
+            # scoped_commands 必须是 commands 的子集
+            filtered_scoped_commands = DictUtils.filter_keys_to_subset(
+                scoped_commands,
+                commands,
+            )
+            # 如果 filtered_scoped_commands 为空，则跳过注册
+            if not filtered_scoped_commands:
+                logger.debug("Filtered commands are empty, skipping registration.")
+                self._delete_commands(client)
+                continue
+            # 对比调整后的命令与当前命令
+            if filtered_scoped_commands != commands:
+                logger.debug(
+                    f"Command set has changed, Updating new commands: {filtered_scoped_commands}"
+                )
+            self._apply_commands(client, filtered_scoped_commands)
+
+    def _commands_enabled(self, config: Optional[dict]) -> bool:
+        """
+        命令注册前置条件钩子，返回 False 时跳过该实例，子类可覆写。
+        """
+        return True
+
+    def _delete_commands(self, client) -> None:
+        """
+        清理已注册命令的钩子，子类可覆写（如改用菜单 API）。
+        """
+        client.delete_commands()
+
+    def _apply_commands(self, client, commands: Dict[str, dict]) -> None:
+        """
+        应用命令集合的钩子，子类可覆写（如改用菜单 API）。
+        """
+        client.register_commands(commands)

app/modules/discord/__init__.py

@@ -1,27 +1,23 @@
-import copy
 import json
 from typing import Any, Dict, List, Optional, Tuple, Union
 from urllib.parse import quote, unquote
 
 from app.domain.context import MediaInfo, Context
-from app.runtime.events import eventmanager
 from app.application.messaging.agent import (
     matches_channel_admin,
     register_channel_admin_resolver,
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.schemas import (
-    CommandRegisterEventData,
     CommingMessage,
     MessageChannel,
     MessageResponse,
     Notification,
 )
-from app.schemas.types import ChainEventType, ModuleType
+from app.schemas.types import ModuleType
 from app.adapters.network.http import RequestUtils
-from app.foundation.collections import DictUtils
 
 try:
     from app.modules.discord.discord import Discord
@@ -36,7 +32,9 @@ register_channel_admin_resolver(
 )
 
 
-class DiscordModule(_ModuleBase, _MessageBase[Discord]):
+class DiscordModule(_MessageChannelModuleBase[Discord]):
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "DISCORD_ADMINS"
     _IMAGE_SUFFIXES = (
         ".png",
         ".jpg",
@@ -107,51 +105,9 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
             except Exception as err:
                 logger.error(f"停止Discord模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"Discord {name} Bot 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 Discord 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("DISCORD_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 Discord 命令或命令型按钮回调是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        candidates = [
-            str(user_id).strip()
-            for user_id in user_ids
-            if user_id is not None and str(user_id).strip()
-        ]
-        return not any(candidate in admins for candidate in candidates)
-
     @staticmethod
     def _send_admin_denied(
             client: Optional[Discord],
@@ -556,54 +512,6 @@ class DiscordModule(_ModuleBase, _MessageBase[Discord]):
                     return True
         return False
 
-    def register_commands(self, commands: Dict[str, dict]) -> None:
-        """
-        注册命令，实现这个函数接收系统可用的命令菜单。
-
-        :param commands: 命令字典
-        """
-        for client_config in self.get_configs().values():
-            client = self.get_instance(client_config.name)
-            if not client:
-                continue
-
-            scoped_commands = copy.deepcopy(commands)
-            event = eventmanager.send_event(
-                ChainEventType.CommandRegister,
-                CommandRegisterEventData(
-                    commands=scoped_commands,
-                    origin="Discord",
-                    service=client_config.name,
-                ),
-            )
-
-            if event and event.event_data:
-                event_data: CommandRegisterEventData = event.event_data
-                if event_data.cancel:
-                    client.delete_commands()
-                    logger.debug(
-                        f"Command registration for {client_config.name} canceled by event: {event_data.source}"
-                    )
-                    continue
-                scoped_commands = event_data.commands or {}
-                if not scoped_commands:
-                    logger.debug("Filtered commands are empty, skipping registration.")
-                    client.delete_commands()
-
-            filtered_scoped_commands = DictUtils.filter_keys_to_subset(
-                scoped_commands,
-                commands,
-            )
-            if not filtered_scoped_commands:
-                logger.debug("Filtered commands are empty, skipping registration.")
-                client.delete_commands()
-                continue
-            if filtered_scoped_commands != commands:
-                logger.debug(
-                    f"Command set has changed, Updating new commands: {filtered_scoped_commands}"
-                )
-            client.register_commands(filtered_scoped_commands)
-
     def mark_message_processing_started(
         self,
         channel: MessageChannel,

app/modules/emby/__init__.py

@@ -1,16 +1,16 @@
 from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
 from app import schemas
-from app.domain.context import MediaInfo
-from app.runtime.events import eventmanager
-from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _MediaServerBase, _ModuleBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.emby.emby import Emby
-from app.schemas.types import MediaType, ModuleType, ChainEventType, MediaServerType
+from app.schemas.types import ModuleType, MediaServerType
 
 
-class EmbyModule(_ModuleBase, _MediaServerBase[Emby]):
+class EmbyModule(_MediaServerModuleBase[Emby]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "emby"
 
     def init_module(self) -> None:
         """
@@ -47,70 +47,9 @@ class EmbyModule(_ModuleBase, _MediaServerBase[Emby]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.get_user():
-                return False, f"无法连接Emby服务器：{name}"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        # 定时重连
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"Emby服务器 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
-
-    def user_authenticate(self, credentials: schemas.AuthCredentials, service_name: Optional[str] = None) \
-            -> Optional[schemas.AuthCredentials]:
-        """
-        使用Emby用户辅助完成用户认证
-        :param credentials: 认证数据
-        :param service_name: 指定要认证的媒体服务器名称，若为 None 则认证所有服务
-        :return: 认证数据
-        """
-        # Emby认证
-        if not credentials or credentials.grant_type != "password":
-            return None
-        # 确定要认证的服务器列表
-        if service_name:
-            # 如果指定了服务名，获取该服务实例
-            servers = [(service_name, server)] if (server := self.get_instance(service_name)) else []
-        else:
-            # 如果没有指定服务名，遍历所有服务
-            servers = self.get_instances().items()
-        # 遍历要认证的服务器
-        for name, server in servers:
-            # 触发认证拦截事件
-            intercept_event = eventmanager.send_event(
-                etype=ChainEventType.AuthIntercept,
-                data=schemas.AuthInterceptCredentials(username=credentials.username, channel=self.get_name(),
-                                                      service=name, status="triggered")
-            )
-            if intercept_event and intercept_event.event_data:
-                intercept_data: schemas.AuthInterceptCredentials = intercept_event.event_data
-                if intercept_data.cancel:
-                    continue
-            token = server.authenticate(credentials.username, credentials.password)
-            if token:
-                credentials.channel = self.get_name()
-                credentials.service = name
-                credentials.token = token
-                return credentials
-        return None
-
     def webhook_parser(self, body: Any, form: Any, args: Any) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Webhook报文体
@@ -136,79 +75,6 @@ class EmbyModule(_ModuleBase, _MediaServerBase[Emby]):
                     return result
         return None
 
-    def media_exists(self, mediainfo: MediaInfo, itemid: Optional[str] = None,
-                     server: Optional[str] = None) -> Optional[schemas.ExistMediaInfo]:
-        """
-        判断媒体文件是否存在
-        :param mediainfo:  识别的媒体信息
-        :param itemid:  媒体服务器ItemID
-        :param server:  媒体服务器名称
-        :return: 如不存在返回None，存在时返回信息，包括每季已存在所有集{type: movie/tv, seasons: {season: [episodes]}}
-        """
-        if server:
-            servers = [(server, self.get_instance(server))]
-        else:
-            servers = self.get_instances().items()
-        for name, s in servers:
-            if not s:
-                continue
-            if mediainfo.type == MediaType.MUSIC:
-                matches = s.get_music(**MusicMediaServerHelper.search_params(mediainfo))
-                match = MusicMediaServerHelper.find_match(mediainfo, matches)
-                if match:
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MUSIC,
-                        server_type="emby",
-                        server=name,
-                        itemid=match.item_id,
-                    )
-                continue
-            if mediainfo.type == MediaType.MOVIE:
-                if itemid:
-                    movie = s.get_iteminfo(itemid)
-                    if movie:
-                        logger.info(f"媒体库 {name} 中找到了 {movie}")
-                        return schemas.ExistMediaInfo(
-                            type=MediaType.MOVIE,
-                            server_type="emby",
-                            server=name,
-                            itemid=movie.item_id
-                        )
-                movies = s.get_movies(title=mediainfo.title,
-                                      year=mediainfo.year,
-                                      media_source=mediainfo.media_source,
-                                      media_id=mediainfo.media_id)
-                if not movies:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"媒体库 {name} 中找到了 {movies}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MOVIE,
-                        server_type="emby",
-                        server=name,
-                        itemid=movies[0].item_id
-                    )
-            else:
-                itemid, tvs = s.get_tv_episodes(title=mediainfo.title,
-                                                year=mediainfo.year,
-                                                media_source=mediainfo.media_source,
-                                                media_id=mediainfo.media_id,
-                                                item_id=itemid)
-                if not tvs:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"{mediainfo.title_year} 在媒体库 {name} 中找到了这些季集：{tvs}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.TV,
-                        seasons=tvs,
-                        server_type="emby",
-                        server=name,
-                        itemid=itemid
-                    )
-        return None
-
     def media_statistic(self, server: Optional[str] = None) -> Optional[List[schemas.Statistic]]:
         """
         媒体数量统计

app/modules/feishu/__init__.py

@@ -3,7 +3,7 @@ from typing import Any, List, Optional, Tuple, Union
 from app.domain.context import Context, MediaInfo
 from app.application.messaging.agent import register_channel_admin_resolver, resolve_config_principal_ids
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.feishu.feishu import Feishu
 from app.schemas import CommingMessage, MessageChannel, MessageResponse, Notification
 from app.schemas.types import ModuleType
@@ -17,7 +17,7 @@ register_channel_admin_resolver(
 )
 
 
-class FeishuModule(_ModuleBase, _MessageBase[Feishu]):
+class FeishuModule(_MessageChannelModuleBase[Feishu]):
     def init_module(self) -> None:
         super().init_service(service_name=Feishu.__name__.lower(), service_type=Feishu)
         self._channel = MessageChannel.Feishu
@@ -46,15 +46,6 @@ class FeishuModule(_ModuleBase, _MessageBase[Feishu]):
             except Exception as err:
                 logger.error(f"停止飞书模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"飞书 {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         """通知模块通过系统通知配置控制实例化，这里不额外设置环境开关。"""
         return None

app/modules/jellyfin/__init__.py

@@ -1,17 +1,16 @@
 from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
 from app import schemas
-from app.domain.context import MediaInfo
-from app.runtime.events import eventmanager
-from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _MediaServerBase, _ModuleBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.jellyfin.jellyfin import Jellyfin
-from app.schemas import AuthCredentials, AuthInterceptCredentials
-from app.schemas.types import MediaType, ModuleType, ChainEventType, MediaServerType
+from app.schemas.types import ModuleType, MediaServerType
 
 
-class JellyfinModule(_ModuleBase, _MediaServerBase[Jellyfin]):
+class JellyfinModule(_MediaServerModuleBase[Jellyfin]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "jellyfin"
 
     def init_module(self) -> None:
         """
@@ -48,70 +47,9 @@ class JellyfinModule(_ModuleBase, _MediaServerBase[Jellyfin]):
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        # 定时重连
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"Jellyfin {name} 服务器连接断开，尝试重连 ...")
-                server.reconnect()
-
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.get_user():
-                return False, f"无法连接Jellyfin服务器：{name}"
-        return True, ""
-
-    def user_authenticate(self, credentials: AuthCredentials, service_name: Optional[str] = None) \
-            -> Optional[AuthCredentials]:
-        """
-        使用Jellyfin用户辅助完成用户认证
-        :param credentials: 认证数据
-        :param service_name: 指定要认证的媒体服务器名称，若为 None 则认证所有服务
-        :return: 认证数据
-        """
-        # Jellyfin认证
-        if not credentials or credentials.grant_type != "password":
-            return None
-        # 确定要认证的服务器列表
-        if service_name:
-            # 如果指定了服务名，获取该服务实例
-            servers = [(service_name, server)] if (server := self.get_instance(service_name)) else []
-        else:
-            # 如果没有指定服务名，遍历所有服务
-            servers = self.get_instances().items()
-        # 遍历要认证的服务器
-        for name, server in servers:
-            # 触发认证拦截事件
-            intercept_event = eventmanager.send_event(
-                etype=ChainEventType.AuthIntercept,
-                data=AuthInterceptCredentials(username=credentials.username, channel=self.get_name(),
-                                              service=name, status="triggered")
-            )
-            if intercept_event and intercept_event.event_data:
-                intercept_data: AuthInterceptCredentials = intercept_event.event_data
-                if intercept_data.cancel:
-                    continue
-            token = server.authenticate(credentials.username, credentials.password)
-            if token:
-                credentials.channel = self.get_name()
-                credentials.service = name
-                credentials.token = token
-                return credentials
-        return None
-
     def webhook_parser(self, body: Any, form: Any, args: Any) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Webhook报文体
@@ -137,79 +75,6 @@ class JellyfinModule(_ModuleBase, _MediaServerBase[Jellyfin]):
                     return result
         return None
 
-    def media_exists(self, mediainfo: MediaInfo, itemid: Optional[str] = None,
-                     server: Optional[str] = None) -> Optional[schemas.ExistMediaInfo]:
-        """
-        判断媒体文件是否存在
-        :param mediainfo:  识别的媒体信息
-        :param itemid:  媒体服务器ItemID
-        :param server:  媒体服务器名称
-        :return: 如不存在返回None，存在时返回信息，包括每季已存在所有集{type: movie/tv, seasons: {season: [episodes]}}
-        """
-        if server:
-            servers = [(server, self.get_instance(server))]
-        else:
-            servers = self.get_instances().items()
-        for name, s in servers:
-            if not s:
-                continue
-            if mediainfo.type == MediaType.MUSIC:
-                matches = s.get_music(**MusicMediaServerHelper.search_params(mediainfo))
-                match = MusicMediaServerHelper.find_match(mediainfo, matches)
-                if match:
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MUSIC,
-                        server_type="jellyfin",
-                        server=name,
-                        itemid=match.item_id,
-                    )
-                continue
-            if mediainfo.type == MediaType.MOVIE:
-                if itemid:
-                    movie = s.get_iteminfo(itemid)
-                    if movie:
-                        logger.info(f"媒体库 {name} 中找到了 {movie}")
-                        return schemas.ExistMediaInfo(
-                            type=MediaType.MOVIE,
-                            server_type="jellyfin",
-                            server=name,
-                            itemid=movie.item_id
-                        )
-                movies = s.get_movies(title=mediainfo.title,
-                                      year=mediainfo.year,
-                                      media_source=mediainfo.media_source,
-                                      media_id=mediainfo.media_id)
-                if not movies:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"媒体库 {name} 中找到了 {movies}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MOVIE,
-                        server_type="jellyfin",
-                        server=name,
-                        itemid=movies[0].item_id
-                    )
-            else:
-                itemid, tvs = s.get_tv_episodes(title=mediainfo.title,
-                                                year=mediainfo.year,
-                                                media_source=mediainfo.media_source,
-                                                media_id=mediainfo.media_id,
-                                                item_id=itemid)
-                if not tvs:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"{mediainfo.title_year} 在媒体库 {name} 中找到了这些季集：{tvs}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.TV,
-                        seasons=tvs,
-                        server_type="jellyfin",
-                        server=name,
-                        itemid=itemid
-                    )
-        return None
-
     def media_statistic(self, server: Optional[str] = None) -> Optional[List[schemas.Statistic]]:
         """
         媒体数量统计

app/modules/plex/__init__.py

@@ -5,13 +5,16 @@ from app.domain.context import MediaInfo
 from app.runtime.events import eventmanager
 from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MediaServerBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.plex.plex import Plex
 from app.schemas import AuthCredentials, AuthInterceptCredentials
 from app.schemas.types import MediaType, ModuleType, ChainEventType, MediaServerType
 
 
-class PlexModule(_ModuleBase, _MediaServerBase[Plex]):
+class PlexModule(_MediaServerModuleBase[Plex]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "plex"
 
     def init_module(self) -> None:
         """
@@ -54,32 +57,17 @@ class PlexModule(_ModuleBase, _MediaServerBase[Plex]):
             except Exception as err:
                 logger.error(f"停止Plex模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.get_librarys():
-                return False, f"无法连接Plex服务器：{name}"
-        return True, ""
+    def _test_server(self, server, name: str) -> Optional[str]:
+        """Plex 用媒体库列表探测连接状态。"""
+        if server.is_inactive():
+            server.reconnect()
+        if not server.get_librarys():
+            return f"无法连接Plex服务器：{name}"
+        return None
 
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        # 定时重连
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"Plex {name} 服务器连接断开，尝试重连 ...")
-                server.reconnect()
-
     def user_authenticate(self, credentials: AuthCredentials, service_name: Optional[str] = None) \
             -> Optional[AuthCredentials]:
         """

app/modules/qbittorrent/__init__.py

@@ -2,14 +2,12 @@ from pathlib import Path
 from typing import Set, Tuple, Optional, Union, List, Dict
 
 from qbittorrentapi import TorrentFilesList
-from torrentool.torrent import Torrent
 
 from app import schemas
-from app.runtime.cache import FileCache
 from app.runtime.config import settings
 from app.domain.metainfo import MetaInfo
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _DownloaderBase
+from app.modules._base import _DownloaderModuleBase
 from app.modules.qbittorrent.qbittorrent import Qbittorrent
 from app.schemas import DownloaderTorrent
 from app.schemas.types import (
@@ -19,7 +17,6 @@ from app.schemas.types import (
     TorrentQueryStatus,
     TorrentStatus,
 )
-from app.domain import torrent as torrent_rules
 from app.foundation import size as size_tools
 from app.foundation import temporal as time_tools
 from app.foundation import text as text_tools
@@ -44,7 +41,7 @@ _TORRENT_FILES_RETRY_TIMES = 5
 _TORRENT_FILES_RETRY_INTERVAL = 1
 
 
-class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
+class QbittorrentModule(_DownloaderModuleBase[Qbittorrent]):
     """
     qBittorrent 下载器模块，负责下载任务添加、文件选择和任务管理。
     """
@@ -90,34 +87,12 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
         """
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.transfer_info():
-                return False, f"无法连接Qbittorrent下载器：{name}"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         """
         返回控制模块启用状态的配置项
         """
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"Qbittorrent下载器 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
-
     def download(self, content: Union[Path, str, bytes], download_dir: Path, cookie: str,
                  episodes: Set[int] = None, category: Optional[str] = None, label: Optional[str] = None,
                  downloader: Optional[str] = None) -> Optional[Tuple[Optional[str], Optional[str], Optional[str], str]]:
@@ -132,39 +107,11 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
         :param downloader:  下载器
         :return: 下载器名称、种子Hash、种子文件布局、错误原因
         """
-
-        def __get_torrent_info() -> Tuple[Optional[Torrent], Optional[bytes]]:
-            """
-            获取种子名称
-            """
-            torrent_info, torrent_content = None, None
-            try:
-                if isinstance(content, Path):
-                    if content.exists():
-                        torrent_content = content.read_bytes()
-                    else:
-                        # 读取缓存的种子文件
-                        torrent_content = FileCache().get(content.as_posix(), region="torrents")
-                else:
-                    torrent_content = content
-
-                if torrent_content:
-                    # 检查是否为磁力链接
-                    if torrent_rules.is_magnet_link(torrent_content):
-                        return None, torrent_content
-                    else:
-                        torrent_info = Torrent.from_string(torrent_content)
-
-                return torrent_info, torrent_content
-            except Exception as e:
-                logger.error(f"获取种子名称失败：{e}")
-                return None, None
-
         if not content:
             return None, None, None, "下载内容为空"
 
         # 读取种子的名称
-        torrent_from_file, content = __get_torrent_info()
+        torrent_from_file, content = self._get_torrent_info(content)
         # 检查是否为磁力链接
         is_magnet = isinstance(content, str) and content.startswith("magnet:") or isinstance(content,
                                                                                              bytes) and content.startswith(
@@ -302,7 +249,7 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
         else:
             servers: Dict[str, Qbittorrent] = self.get_instances()
         ret_torrents = []
-        query_status = self.__normalize_query_status(status)
+        query_status = self._normalize_query_status(status)
         query_tags = None if include_all_tags else settings.TORRENT_TAG
 
         def __get_torrent_path(torrent_data: dict) -> Path:
@@ -408,41 +355,6 @@ class QbittorrentModule(_ModuleBase, _DownloaderBase[Qbittorrent]):
             return None
         return ret_torrents  # noqa
 
-    @staticmethod
-    def __normalize_query_status(
-            status: Optional[Union[TorrentStatus, TorrentQueryStatus, str]]
-    ) -> TorrentQueryStatus:
-        """
-        归一任务查询状态。
-        """
-        status_value = getattr(status, "value", status)
-        status_text = str(status_value or "").strip().lower()
-        if not status_text or status_text in {"all", "全部"}:
-            return TorrentQueryStatus.ALL
-        if status_text in {
-            TorrentStatus.TRANSFER.value,
-            TorrentQueryStatus.TRANSFER.value,
-            "transfer",
-        }:
-            return TorrentQueryStatus.TRANSFER
-        if status_text in {
-            TorrentStatus.DOWNLOADING.value,
-            TorrentQueryStatus.DOWNLOADING.value,
-            "downloading",
-        }:
-            return TorrentQueryStatus.DOWNLOADING
-        if status_text in {
-            TorrentQueryStatus.COMPLETED.value,
-            "complete",
-            "seeding",
-            "完成",
-            "已完成",
-        }:
-            return TorrentQueryStatus.COMPLETED
-        if status_text in {TorrentQueryStatus.PAUSED.value, "pause", "暂停", "已暂停"}:
-            return TorrentQueryStatus.PAUSED
-        return TorrentQueryStatus.ALL
-
     @staticmethod
     def __normalize_torrent_state(state: Optional[Union[str, int]]) -> str:
         """

app/modules/qqbot/__init__.py

@@ -15,7 +15,7 @@ from app.application.messaging.agent import (
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.qqbot.qqbot import QQBot
 from app.schemas import CommingMessage, MessageChannel, Notification
 from app.schemas.types import ModuleType
@@ -30,9 +30,12 @@ register_channel_admin_resolver(
 )
 
 
-class QQBotModule(_ModuleBase, _MessageBase[QQBot]):
+class QQBotModule(_MessageChannelModuleBase[QQBot]):
     """QQ Bot 通知模块"""
 
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "QQBOT_ADMINS"
+
     _IMAGE_SUFFIXES = (
         ".png",
         ".jpg",
@@ -86,46 +89,9 @@ class QQBotModule(_ModuleBase, _MessageBase[QQBot]):
             except Exception as err:
                 logger.error(f"停止QQ Bot模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            if not client.get_state():
-                return False, f"QQ Bot {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 QQ 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("QQBOT_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 QQ 斜杠命令是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        return not matches_channel_admin(
-            MessageChannel.QQ,
-            config,
-            *user_ids,
-        )
-
     @staticmethod
     def _send_admin_denied(
             client: Optional[QQBot], userid: Optional[Union[str, int]]

app/modules/rtorrent/__init__.py

@@ -1,14 +1,11 @@
 from pathlib import Path
 from typing import Set, Tuple, Optional, Union, List, Dict
 
-from torrentool.torrent import Torrent
-
 from app import schemas
-from app.runtime.cache import FileCache
 from app.runtime.config import settings
 from app.domain.metainfo import MetaInfo
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _DownloaderBase
+from app.modules._base import _DownloaderModuleBase
 from app.modules.rtorrent.rtorrent import Rtorrent
 from app.schemas import DownloaderTorrent
 from app.schemas.types import (
@@ -18,13 +15,12 @@ from app.schemas.types import (
     TorrentQueryStatus,
     TorrentStatus,
 )
-from app.domain import torrent as torrent_rules
 from app.foundation import size as size_tools
 from app.foundation import temporal as time_tools
 from app.foundation import text as text_tools
 
 
-class RtorrentModule(_ModuleBase, _DownloaderBase[Rtorrent]):
+class RtorrentModule(_DownloaderModuleBase[Rtorrent]):
     def init_module(self) -> None:
         """
         初始化模块
@@ -61,31 +57,9 @@ class RtorrentModule(_ModuleBase, _DownloaderBase[Rtorrent]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.transfer_info():
-                return False, f"无法连接rTorrent下载器：{name}"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"rTorrent下载器 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
-
     def download(
         self,
         content: Union[Path, str, bytes],
@@ -108,38 +82,11 @@ class RtorrentModule(_ModuleBase, _DownloaderBase[Rtorrent]):
         :return: 下载器名称、种子Hash、种子文件布局、错误原因
         """
 
-        def __get_torrent_info() -> Tuple[Optional[Torrent], Optional[bytes]]:
-            """
-            获取种子名称
-            """
-            torrent_info, torrent_content = None, None
-            try:
-                if isinstance(content, Path):
-                    if content.exists():
-                        torrent_content = content.read_bytes()
-                    else:
-                        torrent_content = FileCache().get(
-                            content.as_posix(), region="torrents"
-                        )
-                else:
-                    torrent_content = content
-
-                if torrent_content:
-                    if torrent_rules.is_magnet_link(torrent_content):
-                        return None, torrent_content
-                    else:
-                        torrent_info = Torrent.from_string(torrent_content)
-
-                return torrent_info, torrent_content
-            except Exception as e:
-                logger.error(f"获取种子名称失败：{e}")
-                return None, None
-
         if not content:
             return None, None, None, "下载内容为空"
 
         # 读取种子的名称
-        torrent_from_file, content = __get_torrent_info()
+        torrent_from_file, content = self._get_torrent_info(content)
         # 检查是否为磁力链接
         is_magnet = (
             isinstance(content, str)
@@ -311,7 +258,7 @@ class RtorrentModule(_ModuleBase, _DownloaderBase[Rtorrent]):
         else:
             servers: Dict[str, Rtorrent] = self.get_instances()
         ret_torrents = []
-        query_status = self.__normalize_query_status(status)
+        query_status = self._normalize_query_status(status)
         query_tags = None if include_all_tags else settings.TORRENT_TAG
 
         def __get_torrent_path(torrent_data: dict) -> Path:
@@ -424,41 +371,6 @@ class RtorrentModule(_ModuleBase, _DownloaderBase[Rtorrent]):
             return None
         return ret_torrents  # noqa
 
-    @staticmethod
-    def __normalize_query_status(
-            status: Optional[Union[TorrentStatus, TorrentQueryStatus, str]]
-    ) -> TorrentQueryStatus:
-        """
-        归一任务查询状态。
-        """
-        status_value = getattr(status, "value", status)
-        status_text = str(status_value or "").strip().lower()
-        if not status_text or status_text in {"all", "全部"}:
-            return TorrentQueryStatus.ALL
-        if status_text in {
-            TorrentStatus.TRANSFER.value,
-            TorrentQueryStatus.TRANSFER.value,
-            "transfer",
-        }:
-            return TorrentQueryStatus.TRANSFER
-        if status_text in {
-            TorrentStatus.DOWNLOADING.value,
-            TorrentQueryStatus.DOWNLOADING.value,
-            "downloading",
-        }:
-            return TorrentQueryStatus.DOWNLOADING
-        if status_text in {
-            TorrentQueryStatus.COMPLETED.value,
-            "complete",
-            "seeding",
-            "完成",
-            "已完成",
-        }:
-            return TorrentQueryStatus.COMPLETED
-        if status_text in {TorrentQueryStatus.PAUSED.value, "pause", "暂停", "已暂停"}:
-            return TorrentQueryStatus.PAUSED
-        return TorrentQueryStatus.ALL
-
     @staticmethod
     def __normalize_torrent_state(
             state: Optional[Union[int, str]],

app/modules/slack/__init__.py

@@ -1,28 +1,24 @@
-import copy
 import json
 import re
 from typing import Any, Dict, List, Optional, Tuple, Union
 from urllib.parse import quote, unquote
 
 from app.domain.context import MediaInfo, Context
-from app.runtime.events import eventmanager
 from app.application.messaging.agent import (
     matches_channel_admin,
     register_channel_admin_resolver,
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.slack.slack import Slack
 from app.schemas import (
-    CommandRegisterEventData,
     CommingMessage,
     MessageChannel,
     MessageResponse,
     Notification,
 )
-from app.schemas.types import ChainEventType, ModuleType
-from app.foundation.collections import DictUtils
+from app.schemas.types import ModuleType
 
 
 register_channel_admin_resolver(
@@ -31,7 +27,9 @@ register_channel_admin_resolver(
 )
 
 
-class SlackModule(_ModuleBase, _MessageBase[Slack]):
+class SlackModule(_MessageChannelModuleBase[Slack]):
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "SLACK_ADMINS"
     PROCESSING_REACTION = "eyes"
     _AUDIO_SUFFIXES = (
         ".mp3",
@@ -88,51 +86,9 @@ class SlackModule(_ModuleBase, _MessageBase[Slack]):
             except Exception as err:
                 logger.error(f"停止Slack模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"Slack {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 Slack 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("SLACK_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 Slack 命令或命令型按钮回调是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        candidates = [
-            str(user_id).strip()
-            for user_id in user_ids
-            if user_id is not None and str(user_id).strip()
-        ]
-        return not any(candidate in admins for candidate in candidates)
-
     @staticmethod
     def _send_admin_denied(client: Optional[Slack], userid: Optional[Union[str, int]]) -> None:
         """
@@ -688,54 +644,6 @@ class SlackModule(_ModuleBase, _MessageBase[Slack]):
                     return True
         return False
 
-    def register_commands(self, commands: Dict[str, dict]) -> None:
-        """
-        注册命令，实现这个函数接收系统可用的命令菜单。
-
-        :param commands: 命令字典
-        """
-        for client_config in self.get_configs().values():
-            client = self.get_instance(client_config.name)
-            if not client:
-                continue
-
-            scoped_commands = copy.deepcopy(commands)
-            event = eventmanager.send_event(
-                ChainEventType.CommandRegister,
-                CommandRegisterEventData(
-                    commands=scoped_commands,
-                    origin="Slack",
-                    service=client_config.name,
-                ),
-            )
-
-            if event and event.event_data:
-                event_data: CommandRegisterEventData = event.event_data
-                if event_data.cancel:
-                    client.delete_commands()
-                    logger.debug(
-                        f"Command registration for {client_config.name} canceled by event: {event_data.source}"
-                    )
-                    continue
-                scoped_commands = event_data.commands or {}
-                if not scoped_commands:
-                    logger.debug("Filtered commands are empty, skipping registration.")
-                    client.delete_commands()
-
-            filtered_scoped_commands = DictUtils.filter_keys_to_subset(
-                scoped_commands,
-                commands,
-            )
-            if not filtered_scoped_commands:
-                logger.debug("Filtered commands are empty, skipping registration.")
-                client.delete_commands()
-                continue
-            if filtered_scoped_commands != commands:
-                logger.debug(
-                    f"Command set has changed, Updating new commands: {filtered_scoped_commands}"
-                )
-            client.register_commands(filtered_scoped_commands)
-
     def mark_message_processing_started(
         self,
         channel: MessageChannel,

app/modules/synologychat/__init__.py

@@ -9,7 +9,7 @@ from app.application.messaging.agent import (
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.synologychat.synologychat import SynologyChat
 from app.schemas import MessageChannel, CommingMessage, Notification
 from app.schemas.types import ModuleType
@@ -22,7 +22,9 @@ register_channel_admin_resolver(
 )
 
 
-class SynologyChatModule(_ModuleBase, _MessageBase[SynologyChat]):
+class SynologyChatModule(_MessageChannelModuleBase[SynologyChat]):
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "SYNOLOGYCHAT_ADMINS"
     _IMAGE_SUFFIXES = (
         ".png",
         ".jpg",
@@ -84,51 +86,9 @@ class SynologyChatModule(_ModuleBase, _MessageBase[SynologyChat]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"Synology Chat {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 Synology Chat 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("SYNOLOGYCHAT_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 Synology Chat 斜杠命令是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        candidates = [
-            str(user_id).strip()
-            for user_id in user_ids
-            if user_id is not None and str(user_id).strip()
-        ]
-        return not any(candidate in admins for candidate in candidates)
-
     @staticmethod
     def _send_admin_denied(
             client: Optional[SynologyChat], userid: Optional[Union[str, int]]

app/modules/telegram/__init__.py

@@ -1,28 +1,24 @@
-import copy
 import json
 import re
 from typing import Dict, Optional, Union, List, Tuple, Any
 
 from app.domain.context import MediaInfo, Context
-from app.runtime.events import eventmanager
 from app.application.messaging.agent import (
     matches_channel_admin,
     register_channel_admin_resolver,
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.telegram.telegram import Telegram
 from app.schemas import (
     MessageChannel,
     CommingMessage,
     Notification,
-    CommandRegisterEventData,
     NotificationConf,
     MessageResponse,
 )
-from app.schemas.types import ModuleType, ChainEventType
-from app.foundation.collections import DictUtils
+from app.schemas.types import ModuleType
 
 
 register_channel_admin_resolver(
@@ -33,11 +29,14 @@ register_channel_admin_resolver(
 )
 
 
-class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
+class TelegramModule(_MessageChannelModuleBase[Telegram]):
     """
     Telegram 通知模块，负责模块生命周期、消息解析和通知发送。
     """
 
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "TELEGRAM_ADMINS"
+
     def init_module(self) -> None:
         """
         初始化模块
@@ -83,53 +82,12 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
             except Exception as err:
                 logger.error(f"停止Telegram模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"Telegram {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         """
         获取模块初始化配置项。
         """
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 Telegram 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("TELEGRAM_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 Telegram 命令或命令型按钮回调是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        return not matches_channel_admin(
-            MessageChannel.Telegram,
-            config,
-            *user_ids,
-        )
-
     def message_parser(
         self, source: str, body: Any, form: Any, args: Any
     ) -> Optional[CommingMessage]:
@@ -795,58 +753,6 @@ class TelegramModule(_ModuleBase, _MessageBase[Telegram]):
                     )
         return None
 
-    def register_commands(self, commands: Dict[str, dict]):
-        """
-        注册命令，实现这个函数接收系统可用的命令菜单
-        :param commands: 命令字典
-        """
-        for client_config in self.get_configs().values():
-            client = self.get_instance(client_config.name)
-            if not client:
-                continue
-
-            # 触发事件，允许调整命令数据，这里需要进行深复制，避免实例共享
-            scoped_commands = copy.deepcopy(commands)
-            event = eventmanager.send_event(
-                ChainEventType.CommandRegister,
-                CommandRegisterEventData(
-                    commands=scoped_commands,
-                    origin="Telegram",
-                    service=client_config.name,
-                ),
-            )
-
-            # 如果事件返回有效的 event_data，使用事件中调整后的命令
-            if event and event.event_data:
-                event_data: CommandRegisterEventData = event.event_data
-                # 如果事件被取消，跳过命令注册，并清理菜单
-                if event_data.cancel:
-                    client.delete_commands()
-                    logger.debug(
-                        f"Command registration for {client_config.name} canceled by event: {event_data.source}"
-                    )
-                    continue
-                scoped_commands = event_data.commands or {}
-                if not scoped_commands:
-                    logger.debug("Filtered commands are empty, skipping registration.")
-                    client.delete_commands()
-
-            # scoped_commands 必须是 commands 的子集
-            filtered_scoped_commands = DictUtils.filter_keys_to_subset(
-                scoped_commands, commands
-            )
-            # 如果 filtered_scoped_commands 为空，则跳过注册
-            if not filtered_scoped_commands:
-                logger.debug("Filtered commands are empty, skipping registration.")
-                client.delete_commands()
-                continue
-            # 对比调整后的命令与当前命令
-            if filtered_scoped_commands != commands:
-                logger.debug(
-                    f"Command set has changed, Updating new commands: {filtered_scoped_commands}"
-                )
-            client.register_commands(filtered_scoped_commands)
-
     def download_telegram_file_to_base64(self, file_id: str, source: str) -> Optional[str]:
         """
         下载Telegram文件并转为base64

app/modules/transmission/__init__.py

@@ -1,15 +1,13 @@
 from pathlib import Path
 from typing import Set, Tuple, Optional, Union, List, Dict
 
-from torrentool.torrent import Torrent
 from transmission_rpc import File
 
 from app import schemas
-from app.runtime.cache import FileCache
 from app.runtime.config import settings
 from app.domain.metainfo import MetaInfo
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _DownloaderBase
+from app.modules._base import _DownloaderModuleBase
 from app.modules.transmission.transmission import Transmission
 from app.schemas import DownloaderTorrent
 from app.schemas.types import (
@@ -19,7 +17,6 @@ from app.schemas.types import (
     TorrentQueryStatus,
     TorrentStatus,
 )
-from app.domain import torrent as torrent_rules
 from app.foundation import size as size_tools
 from app.foundation import temporal as time_tools
 
@@ -32,7 +29,7 @@ _TRANSMISSION_PAUSED_STATES = {
 }
 
 
-class TransmissionModule(_ModuleBase, _DownloaderBase[Transmission]):
+class TransmissionModule(_DownloaderModuleBase[Transmission]):
 
     def init_module(self) -> None:
         """
@@ -69,32 +66,9 @@ class TransmissionModule(_ModuleBase, _DownloaderBase[Transmission]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                server.reconnect()
-            if not server.transfer_info():
-                return False, f"无法连接Transmission下载器：{name}"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        # 定时重连
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"Transmission下载器 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
-
     def download(self, content: Union[Path, str, bytes], download_dir: Path, cookie: str,
                  episodes: Set[int] = None, category: Optional[str] = None, label: Optional[str] = None,
                  downloader: Optional[str] = None) -> Optional[Tuple[Optional[str], Optional[str], Optional[str], str]]:
@@ -110,38 +84,11 @@ class TransmissionModule(_ModuleBase, _DownloaderBase[Transmission]):
         :return: 下载器名称、种子Hash、种子文件布局、错误原因
         """
 
-        def __get_torrent_info() -> Tuple[Optional[Torrent], Optional[bytes]]:
-            """
-            获取种子名称
-            """
-            torrent_info, torrent_content = None, None
-            try:
-                if isinstance(content, Path):
-                    if content.exists():
-                        torrent_content = content.read_bytes()
-                    else:
-                        # 读取缓存的种子文件
-                        torrent_content = FileCache().get(content.as_posix(), region="torrents")
-                else:
-                    torrent_content = content
-
-                if torrent_content:
-                    # 检查是否为磁力链接
-                    if torrent_rules.is_magnet_link(torrent_content):
-                        return None, torrent_content
-                    else:
-                        torrent_info = Torrent.from_string(torrent_content)
-
-                return torrent_info, torrent_content
-            except Exception as e:
-                logger.error(f"获取种子名称失败：{e}")
-                return None, None
-
         if not content:
             return None, None, None, "下载内容为空"
 
         # 读取种子的名称
-        torrent_from_file, content = __get_torrent_info()
+        torrent_from_file, content = self._get_torrent_info(content)
         # 检查是否为磁力链接
         is_magnet = isinstance(content, str) and content.startswith("magnet:") or isinstance(content,
                                                                                              bytes) and content.startswith(
@@ -261,7 +208,7 @@ class TransmissionModule(_ModuleBase, _DownloaderBase[Transmission]):
         else:
             servers: Dict[str, Transmission] = self.get_instances()
         ret_torrents = []
-        query_status = self.__normalize_query_status(status)
+        query_status = self._normalize_query_status(status)
         query_tags = None if include_all_tags else settings.TORRENT_TAG
 
         def __get_torrent_attr(torrent_data, *attr_names):
@@ -406,41 +353,6 @@ class TransmissionModule(_ModuleBase, _DownloaderBase[Transmission]):
             return None
         return ret_torrents  # noqa
 
-    @staticmethod
-    def __normalize_query_status(
-            status: Optional[Union[TorrentStatus, TorrentQueryStatus, str]]
-    ) -> TorrentQueryStatus:
-        """
-        归一任务查询状态。
-        """
-        status_value = getattr(status, "value", status)
-        status_text = str(status_value or "").strip().lower()
-        if not status_text or status_text in {"all", "全部"}:
-            return TorrentQueryStatus.ALL
-        if status_text in {
-            TorrentStatus.TRANSFER.value,
-            TorrentQueryStatus.TRANSFER.value,
-            "transfer",
-        }:
-            return TorrentQueryStatus.TRANSFER
-        if status_text in {
-            TorrentStatus.DOWNLOADING.value,
-            TorrentQueryStatus.DOWNLOADING.value,
-            "downloading",
-        }:
-            return TorrentQueryStatus.DOWNLOADING
-        if status_text in {
-            TorrentQueryStatus.COMPLETED.value,
-            "complete",
-            "seeding",
-            "完成",
-            "已完成",
-        }:
-            return TorrentQueryStatus.COMPLETED
-        if status_text in {TorrentQueryStatus.PAUSED.value, "pause", "暂停", "已暂停"}:
-            return TorrentQueryStatus.PAUSED
-        return TorrentQueryStatus.ALL
-
     @staticmethod
     def __normalize_torrent_state(status: Optional[str]) -> str:
         """

app/modules/trimemedia/__init__.py

@@ -1,17 +1,16 @@
 from typing import Any, Generator, List, Optional, Tuple, Union
 
 from app import schemas
-from app.domain.context import MediaInfo
-from app.runtime.events import eventmanager
-from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _MediaServerBase, _ModuleBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.trimemedia.trimemedia import TrimeMedia
-from app.schemas import AuthCredentials, AuthInterceptCredentials
-from app.schemas.types import ChainEventType, MediaServerType, MediaType, ModuleType
+from app.schemas.types import MediaServerType, ModuleType
 
 
-class TrimeMediaModule(_ModuleBase, _MediaServerBase[TrimeMedia]):
+class TrimeMediaModule(_MediaServerModuleBase[TrimeMedia]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "trimemedia"
 
     def init_module(self) -> None:
         """
@@ -52,15 +51,9 @@ class TrimeMediaModule(_ModuleBase, _MediaServerBase[TrimeMedia]):
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        # 定时重连
-        for name, server in self.get_instances().items():
-            if server.is_configured() and server.is_inactive():
-                logger.info(f"飞牛影视 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
+    def _is_inactive(self, server) -> bool:
+        """未配置的实例不参与定时重连。"""
+        return server.is_configured() and server.is_inactive()
 
     def stop(self) -> None:
         """停止模块"""
@@ -71,65 +64,12 @@ class TrimeMediaModule(_ModuleBase, _MediaServerBase[TrimeMedia]):
             except Exception as err:
                 logger.error(f"停止飞牛影视模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if not server.is_configured():
-                return False, f"飞牛影视配置不完整：{name}"
-            if server.is_inactive() and not server.reconnect():
-                return False, f"无法连接飞牛影视：{name}"
-        return True, ""
-
-    def user_authenticate(
-        self, credentials: AuthCredentials, service_name: Optional[str] = None
-    ) -> Optional[AuthCredentials]:
-        """
-        使用飞牛影视用户辅助完成用户认证
-
-        :param credentials: 认证数据
-        :param service_name: 指定要认证的媒体服务器名称，若为 None 则认证所有服务
-        :return: 认证数据
-        """
-        # 飞牛影视认证
-        if not credentials or credentials.grant_type != "password":
-            return None
-        # 确定要认证的服务器列表
-        if service_name:
-            # 如果指定了服务名，获取该服务实例
-            servers = (
-                [(service_name, server)]
-                if (server := self.get_instance(service_name))
-                else []
-            )
-        else:
-            # 如果没有指定服务名，遍历所有服务
-            servers = self.get_instances().items()
-        # 遍历要认证的服务器
-        for name, server in servers:
-            # 触发认证拦截事件
-            intercept_event = eventmanager.send_event(
-                etype=ChainEventType.AuthIntercept,
-                data=AuthInterceptCredentials(
-                    username=credentials.username,
-                    channel=self.get_name(),
-                    service=name,
-                    status="triggered",
-                ),
-            )
-            if intercept_event and intercept_event.event_data:
-                intercept_data: AuthInterceptCredentials = intercept_event.event_data
-                if intercept_data.cancel:
-                    continue
-            token = server.authenticate(credentials.username, credentials.password)
-            if token:
-                credentials.channel = self.get_name()
-                credentials.service = name
-                credentials.token = token
-                return credentials
+    def _test_server(self, server, name: str) -> Optional[str]:
+        """飞牛影视用配置完整性与重连结果探测连接状态。"""
+        if not server.is_configured():
+            return f"{self.get_name()}配置不完整：{name}"
+        if server.is_inactive() and not server.reconnect():
+            return f"无法连接{self.get_name()}：{name}"
         return None
 
     def webhook_parser(
@@ -160,92 +100,6 @@ class TrimeMediaModule(_ModuleBase, _MediaServerBase[TrimeMedia]):
                     return result
         return None
 
-    def media_exists(
-        self,
-        mediainfo: MediaInfo,
-        itemid: Optional[str] = None,
-        server: Optional[str] = None,
-    ) -> Optional[schemas.ExistMediaInfo]:
-        """
-        判断媒体文件是否存在
-
-        :param mediainfo:  识别的媒体信息
-        :param itemid:  媒体服务器ItemID
-        :param server:  媒体服务器名称
-        :return: 如不存在返回None，存在时返回信息，包括每季已存在所有集{type: movie/tv, seasons: {season: [episodes]}}
-        """
-        if server:
-            servers = [(server, self.get_instance(server))]
-        else:
-            servers = self.get_instances().items()
-        for name, s in servers:
-            if not s:
-                continue
-            if mediainfo.type == MediaType.MUSIC:
-                matches = getattr(s, "get_music", lambda **_: [])(
-                    **MusicMediaServerHelper.search_params(mediainfo)
-                )
-                match = MusicMediaServerHelper.find_match(mediainfo, matches)
-                if match:
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MUSIC,
-                        server_type="trimemedia",
-                        server=name,
-                        itemid=match.item_id,
-                    )
-                continue
-            if mediainfo.type == MediaType.MOVIE:
-                if itemid:
-                    movie = s.get_iteminfo(itemid)
-                    if movie:
-                        logger.info(f"媒体库 {name} 中找到了 {movie}")
-                        return schemas.ExistMediaInfo(
-                            type=MediaType.MOVIE,
-                            server_type="trimemedia",
-                            server=name,
-                            itemid=movie.item_id,
-                        )
-                movies = s.get_movies(
-                    title=mediainfo.title,
-                    year=mediainfo.year,
-                    media_source=mediainfo.media_source,
-                    media_id=mediainfo.media_id,
-                )
-                if not movies:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"媒体库 {name} 中找到了 {movies}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MOVIE,
-                        server_type="trimemedia",
-                        server=name,
-                        itemid=movies[0].item_id,
-                    )
-            else:
-                itemid, tvs = s.get_tv_episodes(
-                    title=mediainfo.title,
-                    year=mediainfo.year,
-                    media_source=mediainfo.media_source,
-                    media_id=mediainfo.media_id,
-                    item_id=itemid,
-                )
-                if not tvs:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(
-                        f"{mediainfo.title_year} 在媒体库 {name} 中找到了这些季集：{tvs}"
-                    )
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.TV,
-                        seasons=tvs,
-                        server_type="trimemedia",
-                        server=name,
-                        itemid=itemid,
-                    )
-        return None
-
     def media_statistic(
         self, server: Optional[str] = None
     ) -> Optional[List[schemas.Statistic]]:

app/modules/ugreen/__init__.py

@@ -1,17 +1,16 @@
 from typing import Any, Generator, List, Optional, Tuple, Union
 
 from app import schemas
-from app.domain.context import MediaInfo
-from app.runtime.events import eventmanager
-from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _MediaServerBase, _ModuleBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.ugreen.ugreen import Ugreen
-from app.schemas import AuthCredentials, AuthInterceptCredentials
-from app.schemas.types import ChainEventType, MediaServerType, MediaType, ModuleType
+from app.schemas.types import MediaServerType, ModuleType
 
 
-class UgreenModule(_ModuleBase, _MediaServerBase[Ugreen]):
+class UgreenModule(_MediaServerModuleBase[Ugreen]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "ugreen"
 
     def init_module(self) -> None:
         """
@@ -52,14 +51,9 @@ class UgreenModule(_ModuleBase, _MediaServerBase[Ugreen]):
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        for name, server in self.get_instances().items():
-            if server.is_configured() and server.is_inactive():
-                logger.info(f"绿联影视 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
+    def _is_inactive(self, server) -> bool:
+        """未配置的实例不参与定时重连。"""
+        return server.is_configured() and server.is_inactive()
 
     def stop(self) -> None:
         """停止模块"""
@@ -70,57 +64,12 @@ class UgreenModule(_ModuleBase, _MediaServerBase[Ugreen]):
             except Exception as err:
                 logger.error(f"停止绿联影视模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if not server.is_configured():
-                return False, f"绿联影视配置不完整：{name}"
-            if server.is_inactive() and not server.reconnect():
-                return False, f"无法连接绿联影视：{name}"
-        return True, ""
-
-    def user_authenticate(
-        self, credentials: AuthCredentials, service_name: Optional[str] = None
-    ) -> Optional[AuthCredentials]:
-        """
-        使用绿联影视用户辅助完成用户认证
-        """
-        if not credentials or credentials.grant_type != "password":
-            return None
-
-        if service_name:
-            servers = (
-                [(service_name, server)]
-                if (server := self.get_instance(service_name))
-                else []
-            )
-        else:
-            servers = self.get_instances().items()
-
-        for name, server in servers:
-            intercept_event = eventmanager.send_event(
-                etype=ChainEventType.AuthIntercept,
-                data=AuthInterceptCredentials(
-                    username=credentials.username,
-                    channel=self.get_name(),
-                    service=name,
-                    status="triggered",
-                ),
-            )
-            if intercept_event and intercept_event.event_data:
-                intercept_data: AuthInterceptCredentials = intercept_event.event_data
-                if intercept_data.cancel:
-                    continue
-            token = server.authenticate(credentials.username, credentials.password)
-            if token:
-                credentials.channel = self.get_name()
-                credentials.service = name
-                credentials.token = token
-                return credentials
+    def _test_server(self, server, name: str) -> Optional[str]:
+        """绿联影视用配置完整性与重连结果探测连接状态。"""
+        if not server.is_configured():
+            return f"{self.get_name()}配置不完整：{name}"
+        if server.is_inactive() and not server.reconnect():
+            return f"无法连接{self.get_name()}：{name}"
         return None
 
     def webhook_parser(
@@ -146,84 +95,6 @@ class UgreenModule(_ModuleBase, _MediaServerBase[Ugreen]):
                     return result
         return None
 
-    def media_exists(
-        self,
-        mediainfo: MediaInfo,
-        itemid: Optional[str] = None,
-        server: Optional[str] = None,
-    ) -> Optional[schemas.ExistMediaInfo]:
-        """
-        判断媒体文件是否存在
-        """
-        if server:
-            servers = [(server, self.get_instance(server))]
-        else:
-            servers = self.get_instances().items()
-
-        for name, s in servers:
-            if not s:
-                continue
-            if mediainfo.type == MediaType.MUSIC:
-                matches = getattr(s, "get_music", lambda **_: [])(
-                    **MusicMediaServerHelper.search_params(mediainfo)
-                )
-                match = MusicMediaServerHelper.find_match(mediainfo, matches)
-                if match:
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MUSIC,
-                        server_type="ugreen",
-                        server=name,
-                        itemid=match.item_id,
-                    )
-                continue
-            if mediainfo.type == MediaType.MOVIE:
-                if itemid:
-                    movie = s.get_iteminfo(itemid)
-                    if movie:
-                        logger.info(f"媒体库 {name} 中找到了 {movie}")
-                        return schemas.ExistMediaInfo(
-                            type=MediaType.MOVIE,
-                            server_type="ugreen",
-                            server=name,
-                            itemid=movie.item_id,
-                        )
-                movies = s.get_movies(
-                    title=mediainfo.title,
-                    year=mediainfo.year,
-                    media_source=mediainfo.media_source,
-                    media_id=mediainfo.media_id,
-                )
-                if not movies:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                logger.info(f"媒体库 {name} 中找到了 {movies}")
-                return schemas.ExistMediaInfo(
-                    type=MediaType.MOVIE,
-                    server_type="ugreen",
-                    server=name,
-                    itemid=movies[0].item_id,
-                )
-
-            itemid, tvs = s.get_tv_episodes(
-                title=mediainfo.title,
-                year=mediainfo.year,
-                media_source=mediainfo.media_source,
-                media_id=mediainfo.media_id,
-                item_id=itemid,
-            )
-            if not tvs:
-                logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                continue
-            logger.info(f"{mediainfo.title_year} 在媒体库 {name} 中找到了这些季集：{tvs}")
-            return schemas.ExistMediaInfo(
-                type=MediaType.TV,
-                seasons=tvs,
-                server_type="ugreen",
-                server=name,
-                itemid=itemid,
-            )
-        return None
-
     def media_statistic(
         self, server: Optional[str] = None
     ) -> Optional[List[schemas.Statistic]]:

app/modules/vocechat/__init__.py

@@ -9,7 +9,7 @@ from app.application.messaging.agent import (
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.vocechat.vocechat import VoceChat
 from app.schemas import MessageChannel, CommingMessage, Notification
 from app.schemas.types import ModuleType
@@ -21,7 +21,9 @@ register_channel_admin_resolver(
 )
 
 
-class VoceChatModule(_ModuleBase, _MessageBase[VoceChat]):
+class VoceChatModule(_MessageChannelModuleBase[VoceChat]):
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "VOCECHAT_ADMINS"
     _IMAGE_SUFFIXES = (
         ".png",
         ".jpg",
@@ -83,51 +85,9 @@ class VoceChatModule(_ModuleBase, _MessageBase[VoceChat]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"VoceChat {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析 VoceChat 管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("VOCECHAT_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls,
-            config: Optional[dict],
-            *user_ids: Optional[Union[str, int]],
-    ) -> bool:
-        """
-        判断 VoceChat 斜杠命令是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        candidates = [
-            str(user_id).strip()
-            for user_id in user_ids
-            if user_id is not None and str(user_id).strip()
-        ]
-        return not any(candidate in admins for candidate in candidates)
-
     @staticmethod
     def _send_admin_denied(
             client: Optional[VoceChat], userid: Optional[Union[str, int]]

app/modules/wechat/__init__.py

@@ -1,4 +1,3 @@
-import copy
 import json
 import re
 import xml.dom.minidom
@@ -6,21 +5,19 @@ from typing import Optional, Union, List, Tuple, Any, Dict
 from urllib.parse import quote
 
 from app.domain.context import Context, MediaInfo
-from app.runtime.events import eventmanager
 from app.application.messaging.agent import (
     matches_channel_admin,
     register_channel_admin_resolver,
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _ModuleBase, _MessageBase
+from app.modules._base import _MessageChannelModuleBase
 from app.adapters.external.wechat_crypt import WXBizMsgCrypt
 from app.modules.wechat.wechat import WeChat
 from app.modules.wechat.wechatbot import WeChatBot
-from app.schemas import MessageChannel, CommingMessage, Notification, CommandRegisterEventData
-from app.schemas.types import ModuleType, ChainEventType
+from app.schemas import MessageChannel, CommingMessage, Notification
+from app.schemas.types import ModuleType
 from app.foundation.dom import DomUtils
-from app.foundation.collections import DictUtils
 
 
 def _resolve_wechat_admin_ids(config: Optional[dict]) -> set[str]:
@@ -34,7 +31,12 @@ def _resolve_wechat_admin_ids(config: Optional[dict]) -> set[str]:
 register_channel_admin_resolver(MessageChannel.Wechat, _resolve_wechat_admin_ids)
 
 
-class WechatModule(_ModuleBase, _MessageBase[WeChat]):
+class WechatModule(_MessageChannelModuleBase[WeChat]):
+
+    # 管理员配置键，与渠道 resolver 保持一致
+    _admin_config_key = "WECHAT_ADMINS"
+    # 命令注册事件源标识固定为 WeChat（get_name 为“企业微信”）
+    _command_origin = "WeChat"
 
     def init_module(self) -> None:
         """
@@ -82,51 +84,12 @@ class WechatModule(_ModuleBase, _MessageBase[WeChat]):
     def _is_bot_mode(config: dict) -> bool:
         return (config or {}).get("WECHAT_MODE", "app") == "bot"
 
-    @staticmethod
-    def _get_admins(config: Optional[dict]) -> List[str]:
-        """
-        解析企业微信管理员配置，兼容逗号分隔和首尾空白。
-        """
-        return [
-            admin.strip()
-            for admin in str((config or {}).get("WECHAT_ADMINS") or "").split(",")
-            if admin.strip()
-        ]
-
-    @classmethod
-    def _should_reject_admin_command(
-            cls, config: Optional[dict], user_id: Optional[str]
-    ) -> bool:
-        """
-        判断企业微信菜单或斜杠命令是否应因非管理员身份被拒绝。
-        """
-        admins = cls._get_admins(config)
-        if not admins:
-            return False
-        return not matches_channel_admin(
-            MessageChannel.Wechat,
-            config,
-            user_id,
-        )
-
     @classmethod
     def _create_client(cls, conf):
         if cls._is_bot_mode(conf.config):
             return WeChatBot(name=conf.name, **conf.config)
         return WeChat(name=conf.name, **conf.config)
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state = client.get_state()
-            if not state:
-                return False, f"企业微信 {name} 未就绪"
-        return True, ""
-
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
@@ -457,54 +420,22 @@ class WechatModule(_ModuleBase, _MessageBase[WeChat]):
                 client.send_torrents_msg(title=message.title, torrents=torrents,
                                          userid=message.userid, link=message.link)
 
-    def register_commands(self, commands: Dict[str, dict]):
+    def _commands_enabled(self, config: Optional[dict]) -> bool:
         """
-        注册命令，实现这个函数接收系统可用的命令菜单
-        :param commands: 命令字典
+        菜单注册前置条件：智能机器人模式无传统菜单，缺少解密参数时无法调用菜单 API。
         """
-        for client_config in self.get_configs().values():
-            if self._is_bot_mode(client_config.config):
-                logger.debug(f"{client_config.name} 为智能机器人模式，跳过传统菜单初始化")
-                continue
-            # 如果没有配置消息解密相关参数，则也没有必要进行菜单初始化
-            if not client_config.config.get("WECHAT_ENCODING_AESKEY") or not client_config.config.get("WECHAT_TOKEN"):
-                logger.debug(f"{client_config.name} 缺少消息解密参数，跳过后续菜单初始化")
-                continue
+        if self._is_bot_mode(config):
+            logger.debug("智能机器人模式，跳过传统菜单初始化")
+            return False
+        if not config.get("WECHAT_ENCODING_AESKEY") or not config.get("WECHAT_TOKEN"):
+            logger.debug("缺少消息解密参数，跳过菜单初始化")
+            return False
+        return True
 
-            client = self.get_instance(client_config.name)
-            if not client:
-                continue
+    def _delete_commands(self, client) -> None:
+        """企业微信使用自定义菜单 API 清理命令。"""
+        client.delete_menus()
 
-            # 触发事件，允许调整命令数据，这里需要进行深复制，避免实例共享
-            scoped_commands = copy.deepcopy(commands)
-            event = eventmanager.send_event(
-                ChainEventType.CommandRegister,
-                CommandRegisterEventData(commands=scoped_commands, origin="WeChat", service=client_config.name)
-            )
-
-            # 如果事件返回有效的 event_data，使用事件中调整后的命令
-            if event and event.event_data:
-                event_data: CommandRegisterEventData = event.event_data
-                # 如果事件被取消，跳过命令注册，并清理菜单
-                if event_data.cancel:
-                    client.delete_menus()
-                    logger.debug(
-                        f"Command registration for {client_config.name} canceled by event: {event_data.source}"
-                    )
-                    continue
-                scoped_commands = event_data.commands or {}
-                if not scoped_commands:
-                    logger.debug("Filtered commands are empty, skipping registration.")
-                    client.delete_menus()
-
-            # scoped_commands 必须是 commands 的子集
-            filtered_scoped_commands = DictUtils.filter_keys_to_subset(scoped_commands, commands)
-            # 如果 filtered_scoped_commands 为空，则跳过注册
-            if not filtered_scoped_commands:
-                logger.debug("Filtered commands are empty, skipping registration.")
-                client.delete_menus()
-                continue
-            # 对比调整后的命令与当前命令
-            if filtered_scoped_commands != commands:
-                logger.debug(f"Command set has changed, Updating new commands: {filtered_scoped_commands}")
-            client.create_menus(filtered_scoped_commands)
+    def _apply_commands(self, client, commands: Dict[str, dict]) -> None:
+        """企业微信使用自定义菜单 API 注册命令。"""
+        client.create_menus(commands)

app/modules/wechatclawbot/__init__.py

@@ -9,7 +9,7 @@ from app.application.messaging.agent import (
     resolve_config_principal_ids,
 )
 from app.runtime.log import logger
-from app.modules import _MessageBase, _ModuleBase
+from app.modules._base import _MessageChannelModuleBase
 from app.modules.wechatclawbot.wechatclawbot import WechatClawBot
 from app.schemas import CommingMessage, Notification
 from app.schemas.types import MessageChannel, ModuleType, NotificationAction
@@ -23,7 +23,7 @@ register_channel_admin_resolver(
 )
 
 
-class WechatClawBotModule(_ModuleBase, _MessageBase[WechatClawBot]):
+class WechatClawBotModule(_MessageChannelModuleBase[WechatClawBot]):
     def __init__(self):
         """初始化模块级去重缓存，拦截 iLink 偶发的重复回放消息。"""
         super().__init__()
@@ -69,15 +69,9 @@ class WechatClawBotModule(_ModuleBase, _MessageBase[WechatClawBot]):
             except Exception as err:
                 logger.error(f"停止微信 ClawBot 模块实例失败：{err}")
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """测试模块连接性。"""
-        if not self.get_instances():
-            return None
-        for name, client in self.get_instances().items():
-            state, message = client.test_connection()
-            if not state:
-                return False, f"微信 ClawBot {name} 未就绪：{message}"
-        return True, ""
+    def _test_connection(self, client) -> Tuple[bool, str]:
+        """微信 ClawBot 的连接探测返回 (状态, 信息)。"""
+        return client.test_connection()
 
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         """初始化模块设置。"""

app/modules/zspace/__init__.py

@@ -1,17 +1,17 @@
 from typing import Any, Generator, List, Optional, Tuple, Union
 
 from app import schemas
-from app.domain.context import MediaInfo
-from app.runtime.events import eventmanager
-from app.application.mediaserver import MusicMediaServerHelper
 from app.runtime.log import logger
-from app.modules import _MediaServerBase, _ModuleBase
+from app.modules._base import _MediaServerModuleBase
 from app.modules.zspace.zspace import ZSpace
 from app.schemas import AuthCredentials, AuthInterceptCredentials
-from app.schemas.types import ChainEventType, MediaServerType, MediaType, ModuleType
+from app.schemas.types import ChainEventType, MediaServerType, ModuleType
 
 
-class ZSpaceModule(_ModuleBase, _MediaServerBase[ZSpace]):
+class ZSpaceModule(_MediaServerModuleBase[ZSpace]):
+
+    # 媒体库标识（ExistMediaInfo.server_type）
+    _server_type_value = "zspace"
 
     def init_module(self) -> None:
         """
@@ -48,63 +48,17 @@ class ZSpaceModule(_ModuleBase, _MediaServerBase[ZSpace]):
     def stop(self):
         pass
 
-    def test(self) -> Optional[Tuple[bool, str]]:
-        """
-        测试模块连接性
-        """
-        if not self.get_instances():
-            return None
-        for name, server in self.get_instances().items():
-            if server.is_inactive() and not server.reconnect():
-                return False, f"无法连接极影视服务器：{name}"
-            if not server.user:
-                return False, f"无法连接极影视服务器：{name}"
-        return True, ""
+    def _test_server(self, server, name: str) -> Optional[str]:
+        """极影视用重连结果与用户信息探测连接状态。"""
+        if server.is_inactive() and not server.reconnect():
+            return f"无法连接{self.get_name()}服务器：{name}"
+        if not server.user:
+            return f"无法连接{self.get_name()}服务器：{name}"
+        return None
 
     def init_setting(self) -> Tuple[str, Union[str, bool]]:
         pass
 
-    def scheduler_job(self) -> None:
-        """
-        定时任务，每10分钟调用一次
-        """
-        for name, server in self.get_instances().items():
-            if server.is_inactive():
-                logger.info(f"极影视服务器 {name} 连接断开，尝试重连 ...")
-                server.reconnect()
-
-    def user_authenticate(self, credentials: AuthCredentials, service_name: Optional[str] = None) \
-            -> Optional[AuthCredentials]:
-        """
-        使用极影视用户辅助完成用户认证
-        :param credentials: 认证数据
-        :param service_name: 指定要认证的媒体服务器名称，若为 None 则认证所有服务
-        :return: 认证数据
-        """
-        if not credentials or credentials.grant_type != "password":
-            return None
-        if service_name:
-            servers = [(service_name, server)] if (server := self.get_instance(service_name)) else []
-        else:
-            servers = self.get_instances().items()
-        for name, server in servers:
-            intercept_event = eventmanager.send_event(
-                etype=ChainEventType.AuthIntercept,
-                data=AuthInterceptCredentials(username=credentials.username, channel=self.get_name(),
-                                              service=name, status="triggered")
-            )
-            if intercept_event and intercept_event.event_data:
-                intercept_data: AuthInterceptCredentials = intercept_event.event_data
-                if intercept_data.cancel:
-                    continue
-            token = server.authenticate(credentials.username, credentials.password)
-            if token:
-                credentials.channel = self.get_name()
-                credentials.service = name
-                credentials.token = token
-                return credentials
-        return None
-
     def webhook_parser(self, body: Any, form: Any, args: Any) -> Optional[schemas.WebhookEventInfo]:
         """
         解析Webhook报文体
@@ -130,81 +84,6 @@ class ZSpaceModule(_ModuleBase, _MediaServerBase[ZSpace]):
                     return result
         return None
 
-    def media_exists(self, mediainfo: MediaInfo, itemid: Optional[str] = None,
-                     server: Optional[str] = None) -> Optional[schemas.ExistMediaInfo]:
-        """
-        判断媒体文件是否存在
-        :param mediainfo:  识别的媒体信息
-        :param itemid:  媒体服务器ItemID
-        :param server:  媒体服务器名称
-        :return: 如不存在返回None，存在时返回信息，包括每季已存在所有集{type: movie/tv, seasons: {season: [episodes]}}
-        """
-        if server:
-            servers = [(server, self.get_instance(server))]
-        else:
-            servers = self.get_instances().items()
-        for name, s in servers:
-            if not s:
-                continue
-            if mediainfo.type == MediaType.MUSIC:
-                matches = getattr(s, "get_music", lambda **_: [])(
-                    **MusicMediaServerHelper.search_params(mediainfo)
-                )
-                match = MusicMediaServerHelper.find_match(mediainfo, matches)
-                if match:
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MUSIC,
-                        server_type="zspace",
-                        server=name,
-                        itemid=match.item_id,
-                    )
-                continue
-            if mediainfo.type == MediaType.MOVIE:
-                if itemid:
-                    movie = s.get_iteminfo(itemid)
-                    if movie:
-                        logger.info(f"媒体库 {name} 中找到了 {movie}")
-                        return schemas.ExistMediaInfo(
-                            type=MediaType.MOVIE,
-                            server_type="zspace",
-                            server=name,
-                            itemid=movie.item_id
-                        )
-                movies = s.get_movies(title=mediainfo.title,
-                                      year=mediainfo.year,
-                                      media_source=mediainfo.media_source,
-                                      media_id=mediainfo.media_id)
-                if not movies:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"媒体库 {name} 中找到了 {movies}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.MOVIE,
-                        server_type="zspace",
-                        server=name,
-                        itemid=movies[0].item_id
-                    )
-            else:
-                itemid, tvs = s.get_tv_episodes(title=mediainfo.title,
-                                                year=mediainfo.year,
-                                                media_source=mediainfo.media_source,
-                                                media_id=mediainfo.media_id,
-                                                item_id=itemid)
-                if not tvs:
-                    logger.info(f"{mediainfo.title_year} 没有在媒体库 {name} 中")
-                    continue
-                else:
-                    logger.info(f"{mediainfo.title_year} 在媒体库 {name} 中找到了这些季集：{tvs}")
-                    return schemas.ExistMediaInfo(
-                        type=MediaType.TV,
-                        seasons=tvs,
-                        server_type="zspace",
-                        server=name,
-                        itemid=itemid
-                    )
-        return None
-
     def media_statistic(self, server: Optional[str] = None) -> Optional[List[schemas.Statistic]]:
         """
         媒体数量统计

app/runtime/compat/imports.py

@@ -188,11 +188,14 @@ class LegacySymbolOverlayLoader(importlib.abc.Loader):
 
         module.__getattr__ = resolve_export
         module.__dir__ = list_exports
+        # 兼容符号不并入 __all__：避免 `from <module> import *` 在包初始化期
+        # 急切解析旧符号、反向拉起应用层模块形成循环导入；显式导入与属性
+        # 访问仍由上方 __getattr__ 惰性解析兜底
         public_names = {
             name for name in module.__dict__ if not name.startswith("_")
         }
         declared_exports = set(previous_all or ()) if had_all else public_names
-        module.__all__ = sorted(declared_exports | set(exports))
+        module.__all__ = sorted(declared_exports)
         module.__dict__[self._STATE_KEY] = {
             "__getattr__": previous_getattr,
             "__dir__": previous_dir,

app/runtime/compat/manifest.py

@@ -680,6 +680,18 @@ PACKAGE_EXPORTS: Dict[str, Dict[str, SymbolAlias]] = {
 # 物理模块仍存在、仅部分公开符号迁走时，由导入器在标准 Loader 执行后叠加惰性符号路由。
 # canonical 源码不反向依赖兼容层，目标符号也只在旧调用方真正取用时加载。
 SYMBOL_ALIASES: Dict[str, Dict[str, SymbolAlias]] = {
+    "app.agent.orchestrator": {
+        "AgentChain": SymbolAlias(
+            target_module="app.chain.agent",
+            target_name="AgentChain",
+            replacement="app.chain.agent.AgentChain",
+        ),
+        "ReplyMode": SymbolAlias(
+            target_module="app.schemas.agent",
+            target_name="ReplyMode",
+            replacement="app.schemas.agent.ReplyMode",
+        ),
+    },
     "app.chain.message": {
         "MediaInteractionChain": SymbolAlias(
             target_module="app.chain.interaction",

app/scheduler.py

@@ -51,7 +51,8 @@ from app.runtime.scheduling import TimerUtils
 
 lock = threading.Lock()
 SCHEDULER_PROGRESS_PREFIX = "scheduler"
-AGENT_TASK_JOB_PREFIX = "agent-task"
+# Agent 自主定时任务前缀下沉到 application 门面，此处保留兼容导出。
+from app.application.scheduling import AGENT_TASK_JOB_PREFIX  # noqa: E402
 
 
 class SchedulerChain(ChainBase):

app/schemas/agent.py

@@ -1,6 +1,7 @@
 """AI智能体相关数据模型"""
 
 from datetime import datetime
+from enum import Enum
 from typing import Any, List, Literal, Optional, Union
 
 from langchain_core.messages import BaseMessage
@@ -9,6 +10,13 @@ from pydantic import BaseModel, Field, ConfigDict, field_serializer
 from app.schemas.common import JsonData
 
 
+class ReplyMode(str, Enum):
+    """Agent 最终回复处理模式（chain 与 agent 层共享的值域）。"""
+
+    DISPATCH = "dispatch"
+    CAPTURE_ONLY = "capture_only"
+
+
 class ConversationMemory(BaseModel):
     """对话记忆模型"""
 

app/startup/agent_initializer.py

@@ -1,7 +1,21 @@
+from app.agent.llm import AgentCapabilityManager, LLMHelper
 from app.agent.orchestrator import agent_manager
+from app.agent.prompt import prompt_manager
+from app.agent.prompt.transfer_redo import build_manual_redo_prompt
+from app.application.agent import register_agent_services
 from app.runtime.config import settings
 from app.runtime.log import logger
 
+# 导入期即向 application 门面注册实现，保证任何先于 initialize 的
+# 链层调用都能通过门面取到 Agent 服务对象。
+register_agent_services(
+    agent_manager=agent_manager,
+    prompt_manager=prompt_manager,
+    capability_manager=AgentCapabilityManager,
+    llm_helper=LLMHelper,
+    manual_redo_prompt_builder=build_manual_redo_prompt,
+)
+
 
 class AgentInitializer:
     """

app/startup/command_initializer.py

@@ -1,5 +1,9 @@
+from app.application.commands import register_command_class
 from app.command import Command
 
+# 导入期即向 application 门面注册命令类，保证工具调用时不依赖静态边。
+register_command_class(Command)
+
 
 def init_command():
     """

app/startup/scheduler_initializer.py

@@ -1,5 +1,9 @@
+from app.application.scheduling import register_scheduler_class
 from app.scheduler import Scheduler
 
+# 导入期即向 application 门面注册调度器类，保证工具调用时不依赖静态边。
+register_scheduler_class(Scheduler)
+
 
 def init_scheduler():
     """