refactor: 收口订阅与插件应用边界

app/agent/tools/impl/_plugin_tool_utils.py

@@ -70,7 +70,7 @@ def build_preview_payload(value: Any, max_chars: Optional[int]) -> tuple[bool, i
 def refresh_plugin_registrations(plugin_id: str) -> None:
     """重新注册插件的定时任务、命令和动态 API 路由。"""
     # 这些依赖只在真正执行重载时才导入，避免普通查询工具引入不必要的初始化开销。
-    from app.application.plugins import register_plugin_api
+    from app.application.plugin.routes import register_plugin_api
     from app.application.commands import init_commands
     from app.application.scheduling import update_plugin_job
 
@@ -380,10 +380,8 @@ async def uninstall_plugin_runtime(plugin_id: str) -> dict[str, Any]:
     """
     按现有卸载逻辑移除插件，并清理运行态注册与分组信息。
     """
-    from app.application.plugins import (
-        remove_plugin_api,
-        remove_plugin_from_folders,
-    )
+    from app.application.plugin.folders import remove_plugin_from_folders
+    from app.application.plugin.routes import remove_plugin_api
     from app.application.scheduling import remove_plugin_job
 
     config_oper = SystemConfigOper()

app/api/deps.py

@@ -41,7 +41,7 @@ from app.application.history import (
 )
 from app.application.plugin.config import PluginConfigCommand
 from app.application.commands import init_commands
-from app.application.plugins import register_plugin_api
+from app.application.plugin.routes import register_plugin_api
 from app.application.scheduling import update_plugin_job
 from app.adapters.web.security.access import verify_token
 from app.application.security.user import UserService

app/api/endpoints/plugin.py

@@ -24,11 +24,8 @@ from app.schemas.plugin import PluginSidebarNavItem as _SchemaPluginSidebarNavIt
 from app.schemas.response import Response as _SchemaResponse
 from app.schemas.token import TokenPayload as _SchemaTokenPayload
 from app.api.response import ResponseAPIRouter
-from app.application.plugins import (
-    register_plugin_api,
-    remove_plugin_api,
-    remove_plugin_from_folders,
-)
+from app.application.plugin.folders import remove_plugin_from_folders
+from app.application.plugin.routes import register_plugin_api, remove_plugin_api
 from app.application.plugin.install import PluginInstallCommand
 from app.application.plugin.config import PluginConfigCommand
 from app.application.commands import init_commands

app/application/plugin/folders.py

@@ -0,0 +1,38 @@
+"""插件文件夹应用用例。"""
+
+from app.application.configuration import get_configured_system_config
+from app.runtime.log import logger
+from app.schemas.types import SystemConfigKey
+
+
+def remove_plugin_from_folders(plugin_id: str) -> None:
+    """
+    从所有配置文件夹中移除指定插件。
+
+    同时兼容当前的字典格式和迁移前的插件列表格式，避免卸载旧版本插件时留下
+    不可见的文件夹引用。
+    :param plugin_id: 要移除的插件 ID
+    """
+    try:
+        config_oper = get_configured_system_config()
+        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:
+                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) and 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 error:
+        # 文件夹配置损坏不应阻断插件代码、数据和定时任务的卸载流程。
+        logger.error(f"从文件夹中移除插件时出错：{error}")

app/application/plugin/routes.py

@@ -1,19 +1,47 @@
-"""动态插件路由应用端口。"""
+"""动态插件路由应用端口与注册用例。"""
 
 from typing import Optional, Protocol
 
 
 class DynamicRouteRegistry(Protocol):
-    """插件生命周期操作动态 HTTP 路由所需的最小端口。"""
+    """插件生命周期更新动态 HTTP 路由所需的最小端口。"""
 
     def update(self, plugin_id: Optional[str], action: str) -> None:
         """新增或移除指定插件的动态路由。"""
         ...
 
-    def remove(self, plugin_id: str) -> bool:
-        """移除指定插件的全部动态路由。"""
-        ...
 
-    def clean(self, existing_paths: dict) -> None:
-        """清理重建过程中可能重复的受保护路由。"""
-        ...
+_route_registry: Optional[DynamicRouteRegistry] = None
+
+
+def configure_plugin_routes(registry: DynamicRouteRegistry) -> None:
+    """由 HTTP 组合根注入动态插件路由适配器。"""
+    global _route_registry
+    _route_registry = registry
+
+
+def _get_route_registry() -> DynamicRouteRegistry:
+    """返回已注入的动态插件路由端口。"""
+    if _route_registry is None:
+        raise RuntimeError("插件路由服务尚未由 HTTP 组合根配置")
+    return _route_registry
+
+
+def register_plugin_api(plugin_id: Optional[str] = None) -> None:
+    """动态注册插件 API。"""
+    _update_plugin_api_routes(plugin_id, action="add")
+
+
+def remove_plugin_api(plugin_id: str) -> None:
+    """动态移除单个插件的 API。"""
+    _update_plugin_api_routes(plugin_id, action="remove")
+
+
+def _update_plugin_api_routes(plugin_id: Optional[str], action: str) -> None:
+    """
+    更新插件动态路由。
+
+    :param plugin_id: 插件 ID；注册时为空表示处理全部插件
+    :param action: ``add`` 或 ``remove``
+    """
+    _get_route_registry().update(plugin_id, action)

app/application/plugins.py

@@ -1,114 +0,0 @@
-"""插件 API 动态路由服务。
-
-把插件 API 的动态注册/移除从 HTTP 端点层下沉到 application 层：
-FastAPI 实例由组合根（factory 创建应用后）注入，端点与 Agent 工具
-统一经本模块操作路由，消除 api.endpoints 对 factory 的反向依赖。
-
-依赖方向：
-
-    api.endpoints.plugin / agent.tools -> application.plugins <- factory（注入实例）
-"""
-
-from typing import Optional
-
-from app.application.plugin.routes import DynamicRouteRegistry
-from app.application.configuration import get_configured_system_config
-from app.runtime.log import logger
-from app.schemas.types import SystemConfigKey
-
-_route_registry: Optional[DynamicRouteRegistry] = None
-
-
-def configure_plugin_routes(registry: DynamicRouteRegistry) -> None:
-    """由 HTTP 组合根注入动态插件路由适配器。"""
-    global _route_registry
-    _route_registry = registry
-
-
-def _get_route_registry() -> DynamicRouteRegistry:
-    """返回已注入的动态插件路由端口。"""
-    if _route_registry is None:
-        raise RuntimeError("插件路由服务尚未由 HTTP 组合根配置")
-    return _route_registry
-
-
-def register_plugin_api(plugin_id: Optional[str] = None) -> None:
-    """
-    动态注册插件 API
-    :param plugin_id: 插件 ID，如果为 None，则注册所有插件
-    """
-    _update_plugin_api_routes(plugin_id, action="add")
-
-
-def remove_plugin_api(plugin_id: str) -> None:
-    """
-    动态移除单个插件的 API
-    :param plugin_id: 插件 ID
-    """
-    _update_plugin_api_routes(plugin_id, action="remove")
-
-
-def _update_plugin_api_routes(plugin_id: Optional[str], action: str) -> None:
-    """
-    插件 API 路由注册和移除
-    :param plugin_id: 插件 ID，如果 action 为 "add" 且 plugin_id 为 None，则处理所有插件
-                      如果 action 为 "remove"，plugin_id 必须是有效的插件 ID
-    :param action: "add" 或 "remove"，决定是添加还是移除路由
-    """
-    _get_route_registry().update(plugin_id, action)
-
-
-def _remove_routes(plugin_id: str) -> bool:
-    """
-    移除与单个插件相关的路由
-    :param plugin_id: 插件 ID
-    :return: 是否有路由被移除
-    """
-    return _get_route_registry().remove(plugin_id)
-
-
-def _clean_protected_routes(existing_paths: dict) -> None:
-    """
-    清理受保护的路由，防止在插件操作中被删除或重复添加
-    :param existing_paths: 当前应用的路由路径映射
-    """
-    _get_route_registry().clean(existing_paths)
-
-
-def remove_plugin_from_folders(plugin_id: str):
-    """
-    从所有文件夹中移除指定的插件
-    :param plugin_id: 要移除的插件ID
-    """
-    try:
-        config_oper = get_configured_system_config()
-        # 获取插件文件夹配置
-        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/subscription/write.py

@@ -1,7 +1,7 @@
 """
-订阅的写入路径。
+订阅写入应用用例。
 
-这两个函数把 MediaInfo / MusicInfo 翻译成一行订阅，是订阅表的唯一写入口。翻译此前
+本模块把 MediaInfo / MusicInfo 翻译成一行订阅，是订阅表的唯一业务写入口。翻译此前
 长在 SubscribeOper.add 上，但取标题、选海报尺寸、判音乐实体、决定哪几个字段构成一条
 订阅的身份，都是订阅业务的规则而非数据访问——Oper 只该收敛查询，领域对象不该出现在
 它的入参里。搬上来之后 SubscribeOper 收到的是纯粹的持久化字典，与
@@ -14,6 +14,7 @@ app/application/history.py 里整理历史的写入路径同构。
 张表。同步与异步是两份逐字复制的实现，改一条漏一条就是真实缺陷，故翻译与身份构造由
 下方 _translate 单点承担，两条链路只在「怎么查、怎么写」上分叉。
 """
+
 from collections.abc import Callable
 from typing import Optional, Protocol, Tuple
 
@@ -29,7 +30,12 @@ INCOMPLETE_IDENTITY = (0, "媒体身份不完整")
 class SubscribeWriter(Protocol):
     """订阅写入应用服务使用的数据端口。"""
 
-    def add(self, identity: dict, payload: dict, username: Optional[str] = None) -> Tuple[int, str]:
+    def add(
+        self,
+        identity: dict,
+        payload: dict,
+        username: Optional[str] = None,
+    ) -> Tuple[int, str]:
         """同步新增订阅。"""
 
     async def async_add(
@@ -73,8 +79,10 @@ def _music_entity(mediainfo: MediaInfo | MusicInfo) -> Optional[str]:
     return getattr(mediainfo, "music_type", None)
 
 
-def _translate(mediainfo: MediaInfo | MusicInfo,
-               kwargs: dict) -> Optional[Tuple[dict, dict, Optional[str]]]:
+def _translate(
+    mediainfo: MediaInfo | MusicInfo,
+    kwargs: dict,
+) -> Optional[Tuple[dict, dict, Optional[str]]]:
     """
     把识别结果翻译成查重身份与写入字段。
 
@@ -119,13 +127,16 @@ def _translate(mediainfo: MediaInfo | MusicInfo,
     return identity, payload, username
 
 
-def add_subscribe(mediainfo: MediaInfo | MusicInfo,
-                  subscribe_oper: Optional[SubscribeWriter] = None,
-                  **kwargs) -> Tuple[int, str]:
+def add_subscribe(
+    mediainfo: MediaInfo | MusicInfo,
+    subscribe_oper: Optional[SubscribeWriter] = None,
+    **kwargs,
+) -> Tuple[int, str]:
     """
     新增订阅。
+
     :param mediainfo: 识别结果
-    :param subscribe_oper: 复用的订阅操作对象，未传时新建
+    :param subscribe_oper: 复用的订阅操作对象，未传时由启动组合根提供
     :param kwargs: 订阅设置；owner_scope 为真时按用户名限定查重范围
     :return: (订阅 ID, 结果说明)；ID 为 0 表示未新增
     """
@@ -137,13 +148,16 @@ def add_subscribe(mediainfo: MediaInfo | MusicInfo,
     return oper.add(identity=identity, payload=payload, username=username)
 
 
-async def async_add_subscribe(mediainfo: MediaInfo | MusicInfo,
-                              subscribe_oper: Optional[SubscribeWriter] = None,
-                              **kwargs) -> Tuple[int, str]:
+async def async_add_subscribe(
+    mediainfo: MediaInfo | MusicInfo,
+    subscribe_oper: Optional[SubscribeWriter] = None,
+    **kwargs,
+) -> Tuple[int, str]:
     """
     异步新增订阅。
+
     :param mediainfo: 识别结果
-    :param subscribe_oper: 复用的订阅操作对象，未传时新建
+    :param subscribe_oper: 复用的订阅操作对象，未传时由启动组合根提供
     :param kwargs: 订阅设置；owner_scope 为真时按用户名限定查重范围
     :return: (订阅 ID, 结果说明)；ID 为 0 表示未新增
     """
@@ -153,3 +167,12 @@ async def async_add_subscribe(mediainfo: MediaInfo | MusicInfo,
     identity, payload, username = translated
     oper = _get_subscribe_writer(subscribe_oper)
     return await oper.async_add(identity=identity, payload=payload, username=username)
+
+
+__all__ = [
+    "INCOMPLETE_IDENTITY",
+    "SubscribeWriter",
+    "add_subscribe",
+    "async_add_subscribe",
+    "configure_subscribe_writer",
+]

app/chain/subscribe.py

@@ -41,7 +41,7 @@ from app.application.chain.data import (
 from app.application.configuration import get_configured_system_config
 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.application.subscription.write import add_subscribe, async_add_subscribe
 from app.application.subscription.contract import (
     build_subscribe_meta as _build_subscribe_meta,
     subscribe_media_key,

app/db/oper/subscribe.py

@@ -2,7 +2,7 @@
 订阅数据访问。
 
 本模块只收敛针对订阅表的读写。把 MediaInfo / MusicInfo 翻译成一行订阅是订阅业务的
-规则，住在 app/application/subscribe.py；这里收到的 payload 已经是纯粹的持久化字段，
+规则，住在 app/application/subscription/write.py；这里收到的 payload 已经是纯粹的持久化字段，
 因此不 import 任何领域对象。
 
 留在这一层的只有列类型强转与建库时间戳——它们跟着订阅表的列走，换谁来调都一样。
@@ -97,7 +97,7 @@ class SubscribeOper(DbOper):
         回读不是多余的一次查询——写入可能被唯一约束或事务回滚吞掉，此时若报成功，
         调用方会继续按订阅已建立往下走，用户看到「订阅成功」却永远等不到资源。
         :param identity: 查重身份（media_source/media_id/music_type/season/episode_group）
-        :param payload: 订阅表的写入字段，媒体翻译由 app/application/subscribe.py 完成
+        :param payload: 订阅表的写入字段，媒体翻译由 application/subscription/write.py 完成
         :param username: 非空时把查重限定在该用户的订阅内
         :return: (订阅 ID, 结果说明)；ID 为 0 表示未新增
         """
@@ -115,7 +115,7 @@ class SubscribeOper(DbOper):
         """
         异步新增订阅，语义与 add 完全一致。
         :param identity: 查重身份（media_source/media_id/music_type/season/episode_group）
-        :param payload: 订阅表的写入字段，媒体翻译由 app/application/subscribe.py 完成
+        :param payload: 订阅表的写入字段，媒体翻译由 application/subscription/write.py 完成
         :param username: 非空时把查重限定在该用户的订阅内
         :return: (订阅 ID, 结果说明)；ID 为 0 表示未新增
         """

app/factory.py

@@ -9,7 +9,7 @@ from starlette.exceptions import HTTPException
 
 from app.api.response import ResponseAPIRoute
 from app.adapters.web.plugin.routes import FastAPIDynamicRouteRegistry
-from app.application.plugins import configure_plugin_routes
+from app.application.plugin.routes import configure_plugin_routes
 from app.adapters.web.security.access import (
     configure_token_codec,
     verify_apikey,

app/runtime/compat/manifest.py

@@ -112,7 +112,7 @@ MODULE_ALIASES: Dict[str, ModuleAlias] = {
     ),
     "app.db.subscribe_oper": ModuleAlias(
         target="app.sdk._legacy.subscribe",
-        replacement="app.application.subscribe.add_subscribe",
+        replacement="app.application.subscription.write.add_subscribe",
         introduced="v3.0.0",
         owner="sdk",
     ),

app/sdk/_legacy/subscribe.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Optional
 
-from app.application.subscribe import add_subscribe, async_add_subscribe
+from app.application.subscription.write import add_subscribe, async_add_subscribe
 from app.db.models.subscribe import Subscribe
 from app.db.oper.subscribe import SubscribeOper as CanonicalSubscribeOper
 from app.domain.context import MediaInfo, MusicInfo

app/startup/modules_initializer.py

@@ -54,7 +54,7 @@ from app.application.site.health import SiteHealthService, configure_site_health
 from app.application.workflow import WorkflowQueryService, configure_workflow_query
 from app.application.agentdata import configure_agent_data_ports
 from app.api.data import configure_api_data_ports
-from app.application.subscribe import configure_subscribe_writer
+from app.application.subscription.write import configure_subscribe_writer
 from app.application.maintenance import (
     DataCleanupService,
     configure_cleanup_service_factory,