astrbot_plugin_imagestudio/审计/findings/B2-后端内部耦合.md

42 KiB

B2 · 后端内部耦合与架构分层

审计范围(实际 Read / Grep 过的源文件): main.py backend/route_registry.py backend/routes/:node_routes.py、node_material_routes.py、job_routes.py、round_routes.py、event_routes.py、common.py、branch_routes.py、history_routes.py、review_routes.py、profile_routes.py、workflow_routes.py backend/services/:generation_service.py、workflow_round_service.py、workflow_round_worker_runtime.py、workflow_node_material_service.py、workflow_service.py(结构)、chat_workflow_service.py、advanced_material_service.py、advanced_style_set_service.py(结构)、event_stream_service.py、queue_service.py、branch_lineage_service.py、quick_profile_service.py core/:event_bus.py、config_service.py、security.py、audit_service.py、astrbot_provider_bridge.py、media_proxy.py、storage.py database/:db_helper.py、repositories/workflow_round_repository.py、repositories/workflow_cross_review_repository.py、repositories/profile_card_repository.py、repositories/workflow_repository.py adapters/astrbot_adapter.py 分析方法:对 179 个 Python 模块做 AST/正则导入抽取,生成模块级有向图(扇入/扇出/SCC/分层违规),再逐条回源码验证。


摘要

整体分层意图是清晰的(routes → services → repositories,core 做横切基础设施),但组合根(composition root)缺失是所有耦合问题的根因:35 个 _create_*_service() 工厂散落在 35 个 route 模块里,34 处 Database(load_database_settings()) 各自从磁盘重读一次 config.yaml,没有任何缓存或容器。这直接导致三类硬伤:(1) 后台 worker 必须反向 import route 模块才能拿到装配好的 GenerationService(service → route 反向依赖);(2) 同一个服务在不同 route 里被装配成行为不一致的实例——node_material_routes.py 构造的 WorkflowService 没有 event_bus,导致素材绑定事件被静默丢弃(P1,可复现);(3) 装配代码大段复制(governance/provider 装配在 node_routes.py:315-390 与 advanced_material_service.py:1700-1764 几乎逐行重复)。

core/event_bus.py 存在但形同虚设:全仓(含 tests)subscribe() / unsubscribe() 的调用方为 0,只有 6 处 publish()。它实际只是 GET events/stream 的进程内环形缓冲区,没有承担任何解耦职责,因此所有跨服务通信仍走硬 import。

另有 9 条明确的分层方向违规:database/repositories/* 反向 import backend.services.branch_lineage_service 和 engines;core/* 反向 import backend.dto.common。模块级无循环导入(SCC 只在 adapters/__init__ 与其成员之间,属包导出正常形态),但 job_routes.py:311 用函数内 import 跨 route 模块取私有函数 _create_generation_service,是循环依赖的规避痕迹。

main.py 2580 行中,真正的插件生命周期初始化只有约 95 行(354-447),其余是 849 行聊天命令、165 行纯转发的短命令别名、828 行 AstrBot HTTP/配置桥接。ChatWorkflowService(1315 行)通过字符串路径调用 dispatch_web_request 做了 69 次进程内"自我 HTTP 调用",把 route 层变成了 service 层的下游。


发现

[P1-严重] 装配分散导致 WorkflowService 实例行为不一致:素材绑定事件被静默丢弃

  • 位置:backend/routes/node_material_routes.py:69(构造点)+ backend/services/workflow_node_material_service.py:208(消费点)

  • 问题:8 处 WorkflowService(...) 构造中,只有 4 处传入了 event_bus。node_material_routes._create_service() 是 GET/POST node materials 两个路由的唯一装配路径,它构造 WorkflowService 时没有传 event_bus;而 WorkflowNodeMaterialService 又是通过 self.workflow_service.event_bus 这种"穿透邻居属性"的方式取总线的,于是判空直接短路,workflow.node_material_bindings_updated 事件永远不会发出。

  • 代码:

    # backend/routes/node_material_routes.py:64-73
    def _create_service() -> WorkflowNodeMaterialService:
        database = Database(load_database_settings())
        profiles = ProfileRepository(database)
        workflows = WorkflowRepository(database)
        workflow_service = WorkflowService(
            workflow_repository=workflows,
            profile_repository=profiles,
            audit_service=AuditService(database),
        )                                    # ← 没有 event_bus=
    
    # backend/services/workflow_node_material_service.py:208-218
    if self.workflow_service.event_bus:      # ← 恒为 None,整块被跳过
        self.workflow_service.event_bus.publish(
            "workflow.node_material_bindings_updated",
            {
                "workflow_id": workflow.workflow_id,
                "branch_name": node.branch_name,
                "node_id": node.node_id,
                "material_count": len(selected_material_ids),
                "temporary_reference_count": len(temporary_references),
            },
        )
    

    对照 backend/routes/profile_routes.py:176-181 同名工厂是传了的:

    return WorkflowService(
        workflow_repository=WorkflowRepository(database),
        profile_repository=ProfileRepository(database),
        audit_service=AuditService(database),
        event_bus=get_default_event_bus(),   # ← 这里传了
    )
    

    未传 event_bus 的还有 backend/routes/branch_routes.py:64、backend/routes/history_routes.py:72、backend/routes/review_routes.py:90。

  • 影响:前端 GET events/stream 永远看不到素材绑定变更事件;任何基于该事件做增量刷新/审计的下游功能静默失效,且因为是 if 短路,没有日志、没有异常,排查成本极高。同类风险覆盖全部 4 个漏传点。

  • 修复建议:

    1. 立即修复:把 event_bus=get_default_event_bus() 补进 4 处工厂;
    2. 根治:让 WorkflowService.event_bus 默认取 get_default_event_bus() 而非 None,并把 publish 收敛成服务自身的 self._publish(...) 方法(像 QueueService._publish 那样),禁止 self.<other_service>.event_bus 这种穿透写法;
    3. 加一条单测:断言 route_registry.ROUTES 里每个 handler 的默认装配路径产出的 WorkflowService.event_bus is not None。

[P1-严重] service → route 反向依赖:后台 worker 必须 import route 模块才能启动

  • 位置:backend/services/workflow_round_worker_runtime.py:10;工厂定义在 backend/routes/node_routes.py:315-390(私有)与 :393(公开包装)

  • 问题:整个应用的组合根(DI 装配逻辑)住在 route 模块里。_create_generation_service() 在 node_routes.py 中完成 Database、9 个 repository、ModelProviderRuntime、SingleFlowEngine、4 个 governance 服务的装配。后台 round worker 是 service 层组件,却必须反向 import route 层才能拿到它。

  • 代码:

    # backend/services/workflow_round_worker_runtime.py:9-16
    from backend.dto.job_dto import GenerationTask
    from backend.routes.node_routes import create_generation_service   # ← service 依赖 route
    from backend.services.generation_service import GenerationService
    
    # backend/routes/node_routes.py:315-343(节选,装配根埋在 route 里)
    def _create_generation_service() -> GenerationService:
        database = Database(load_database_settings())
        audit_service = AuditService(database)
        ...
        config_payload = load_config_payload()
        sync_generation_provider_from_config(model_provider_service, config_payload)
        governance_config = config_payload.get("prompt_governance") if isinstance(...) else {}
        translation_config = governance_config.get("translation") if isinstance(...) else {}
        ...
    

    另有跨 route 模块取私有符号(函数内 import,循环依赖规避痕迹):

    # backend/routes/job_routes.py:309-311
    def _create_generation_job_retry_service() -> GenerationJobRetryService:
        # Import lazily so route discovery does not construct provider runtimes.
        from backend.routes.node_routes import _create_generation_service   # ← 取的是私有名
    
  • 影响:

    • backend/routes 变成不可卸载的运行时依赖,无法把 HTTP 层与 worker 层分开打包/测试;
    • main.py:390 也必须在 initialize() 里函数内 import worker runtime(try/except 包裹)来规避启动期副作用,注释 "Import lazily so route discovery does not construct provider runtimes" 直接说明了这个 import 图已经有环形压力;
    • 单测想构造 GenerationService 就得连带 import 整个 route 模块的 31 个依赖(node_routes 是全仓扇出第一,31)。
  • 修复建议:新建 backend/composition.py(或 backend/container.py)作为唯一组合根,把 node_routes.py:282-390、job_routes.py:300-318、round_routes.py:137+、advanced_material_service.py:1700-1764 里的装配代码全部搬进去,导出 create_generation_service() / create_workflow_service() / create_round_service()。route 与 worker 都从 backend.composition 取,依赖方向恢复为 routes → composition → services。


[P1-严重] database 层反向依赖 backend.services 与 engines

  • 位置:database/repositories/workflow_round_repository.py:17、database/repositories/workflow_cross_review_repository.py:17、database/repositories/profile_card_repository.py:11

  • 问题:仓储层(最底层)反向 import 业务服务层与引擎层。branch_state_for / with_branch_state 是 backend/services/branch_lineage_service.py 里的分支血缘业务规则,被两个 repository 直接调用;profile_card_repository 还 import 了 engines.character_flow.canonical_gradual_node_key。

  • 代码:

    # database/repositories/workflow_round_repository.py:11-17
    from backend.dto.workflow_round_dto import (...)
    from backend.services.branch_lineage_service import branch_state_for, with_branch_state
    
    # database/repositories/workflow_cross_review_repository.py:17
    from backend.services.branch_lineage_service import branch_state_for, with_branch_state
    
    # database/repositories/profile_card_repository.py:8-11
    from backend.dto.common import ApiError, ErrorCode
    from backend.dto.profile_card_dto import CharacterProfileCard, CharacterProfileCardAsset
    from database.db_helper import Database
    from engines.character_flow import canonical_gradual_node_key
    

    而 branch_lineage_service.py:17 自己又 import 了 database.repositories.workflow_repository:

    # backend/services/branch_lineage_service.py:15-17
    from backend.dto.common import ApiError, ErrorCode
    from backend.dto.workflow_dto import WorkflowBranch, WorkflowNode
    from database.repositories.workflow_repository import WorkflowRepository
    
  • 影响:database ↔ backend.services 形成包级双向依赖(模块粒度目前恰好没成环,但只要 branch_lineage_service 再多 import 一个 round/cross-review repository 就立即真成环)。分支血缘规则被钉死在 SQL 层,任何血缘策略调整都要改仓储;仓储层无法脱离服务层单独测试。

  • 修复建议:

    1. branch_state_for / with_branch_state 是纯函数(对 dict 做字段级投影,BRANCH_STATE_FIELDS 是 frozenset),把它们连同 BRANCH_STATE_FIELDS 下沉到 core/branch_state.py 或 backend/dto/workflow_dto.py,database 与 backend.services 都从下层取;
    2. branch_lineage_service 保留需要 WorkflowRepository 的那部分(workflow_metadata_for_branch 等),停留在 service 层;
    3. canonical_gradual_node_key 同理下沉,或由调用方(service)在传参前算好再交给 repository。

[P2-中等] core 层反向依赖 backend.dto 与 database,横切层不再是最底层

  • 位置:core/security.py:5、core/storage.py:11、core/media_proxy.py:17、core/config_service.py:10、core/audit_service.py:12

  • 问题:core 本应是无依赖的横切基础设施(被 65 个模块 import 的 core.identity 就是正确样板),但其中 5 个模块反向依赖了上层包。

  • 代码:

    # core/security.py:5-6
    from backend.dto.common import ApiError, ErrorCode
    from core.identity import RequestContext
    
    # core/config_service.py:9-10
    from core.runtime_paths import resolve_config_path
    from database.db_helper import load_config_payload
    
    # core/audit_service.py:11-12
    from core.identity import RequestContext
    from database.db_helper import Database, DatabaseSettings
    
  • 影响:core 无法被独立复用或测试;backend.dto.common(扇入 53,全仓第三)实际扮演了"最底层错误契约"的角色却被放在 backend 包下,造成命名与真实分层错位。core.config_service 依赖 database.db_helper 更是把"读配置"和"连数据库"绑在一起——而 db_helper 里的 load_config_payload 本质是 YAML 加载,跟数据库无关。

  • 修复建议:

    1. 把 ApiError / ErrorCode / success_response / response_from_exception 从 backend/dto/common.py 移到 core/errors.py,backend/dto/common.py 保留 re-export 做过渡;
    2. 把 load_config_payload / load_config_file_payload / _RUNTIME_CONFIG_OVERRIDES 这套从 database/db_helper.py:26-83 抽到 core/config_loader.py,db_helper 反过来 import 它。这样 core 恢复零上行依赖。

[P2-中等] core/event_bus.py 零订阅者:事件总线不承担任何解耦职责

  • 位置:core/event_bus.py:36-50;backend/services/event_stream_service.py:11-15

  • 问题:全仓(含 tests/ 46 个测试文件)对 EventBus.subscribe() / unsubscribe() 的调用方是 0;publish() 只有 6 处。总线实际只是 GET events/stream 用的 500 条进程内环形缓冲。所有跨服务协作仍然靠硬 import 完成(见服务耦合簇一节)。

  • 代码:

    # core/event_bus.py:36-50
    def subscribe(self, event_type: str, handler: EventHandler) -> None:   # ← 无任何调用方
        normalized = _normalize_event_type(event_type)
        if handler not in self._handlers[normalized]:
            self._handlers[normalized].append(handler)
    ...
    def publish(self, event_type: str, payload: dict[str, Any] | None = None) -> Event:
        event = Event(...)
        self._history.append(event)
        for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
            handler(event)      # ← 永远是空列表
        return event
    
    # backend/services/event_stream_service.py:11-15
    DEFAULT_EVENT_BUS = EventBus(history_limit=500)   # 进程级全局单例
    
    def get_default_event_bus() -> EventBus:
        return DEFAULT_EVENT_BUS
    

    6 个 publish 点:generation_service.py:1417/1427/1703、queue_service.py:702、workflow_node_material_service.py:209。

  • 影响:

    • 已有基础设施但没兑现解耦价值,workflow_round_service → generation_service、generation_job_retry_service → generation_service、deletion_safety_service → image_service/media_service 这类"做完 A 顺手通知 B"的调用本可以完全走总线;
    • 同步 publish 在 handler 里抛异常会直接打断业务事务(目前无 handler 所以未暴露),一旦有人开始订阅就立刻踩坑;
    • _handlers 是 defaultdict(list),subscribe/unsubscribe 无锁;DEFAULT_EVENT_BUS 被 QueueWorkerPool 的工作线程和请求线程共享,将来加订阅时是竞态温床。
  • 修复建议:

    1. 先把 publish 改成异常隔离(try/except 包每个 handler,失败只记日志不冒泡),并给 subscribe/unsubscribe/_handlers 加 threading.Lock;
    2. 用总线替换 3 组明显的"通知型"直连:generation_service → workflow_service 的节点状态回写、queue_service → 通知回调(目前 workflow_round_worker_runtime 通过 terminal_notification_callback 参数手动穿到 main.py:1672)、deletion_safety_service → image/media 的级联清理;
    3. 如果确认不打算做订阅,就把 subscribe/unsubscribe 删掉,把类改名为 EventRecorder,别让它伪装成解耦手段。

[P2-中等] ChatWorkflowService 通过字符串路径反向调用 route 层(69 次进程内"自我 HTTP")

  • 位置:backend/services/chat_workflow_service.py:26-31(注入点);main.py:372(装配点);adapters/astrbot_adapter.py:171-187(分发实现)

  • 问题:1315 行的 ChatWorkflowService 不直接调用任何业务 service,而是把 dispatch_web_request 当成"HTTP 客户端",用字符串 method + path 重新进入路由层,共 69 处 self.dispatcher(...)。数据流变成 service → adapter → route → service。

  • 代码:

    # main.py:372
    self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
    
    # backend/services/chat_workflow_service.py:33-47(典型调用)
    def submit_single_image(self, command: SingleImageCommand, chat: ChatCommandContext) -> dict[str, Any]:
        ctx = self._request_context(chat, "single_image")
        config = self.config_loader()
        active = self._data(self.dispatcher(ctx, "GET", "jobs", query={"status": "running", "page": 1, "page_size": 100}))
        ...
        workflow = self._data(self.dispatcher(
            ctx,
            "POST",
            f"profiles/{profile['profile_id']}/workflows",
            payload={...},
        ))
    
    # adapters/astrbot_adapter.py:179-187 + 233-252
    def dispatch_extension_request(ctx, method, path, *, query=None, payload=None):
        match = resolve_route(method, path)
        if match is None:
            return error_response(error_code=ErrorCode.RESOURCE_NOT_FOUND, ...)
        return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
    
    def _handler_args(match, ctx, query, payload) -> list[Any]:
        args: list[Any] = []
        for index, parameter in enumerate(inspect.signature(match.handler).parameters.values()):
            ...
    
  • 影响:

    • 类型安全全失:路径/参数名拼错只在运行时返回 RESOURCE_NOT_FOUND,IDE 与静态检查完全看不到这 69 条调用边;重命名任一路由都会静默打断聊天流程;
    • 性能:每次 dispatch 走 inspect.signature 反射 + route 内 _create_*_service() 全量重建(含 load_database_settings() → config.yaml 磁盘读取),一条聊天命令动辄十几次 dispatch;
    • 错误语义扭曲:业务异常被 route 层的 handle_request 包成 {"success": False, ...} 字典,service 再用 self._data() 拆包,异常栈完全丢失;
    • 依赖图上 main.py → ChatWorkflowService → dispatch → route → service,main.py 因此被卷入业务闭环。
  • 修复建议:把 ChatWorkflowService 改成依赖 backend/composition.py 暴露的具体 service 对象(复用同一批实例,避免每次重建)。若要保留"聊天走公开契约"的设计意图,至少把 69 个字符串端点收敛成一个类型化的门面(class ImageStudioApi + 每个端点一个方法,内部仍可走 dispatcher),让重命名有编译期/静态检查保护。


[P2-中等] 装配代码大段复制:governance/provider 装配在 route 与 service 中各写一遍

  • 位置:backend/routes/node_routes.py:315-390 vs backend/services/advanced_material_service.py:1700-1764

  • 问题:两处独立实现了同一套 "读 config → sync provider → 解析 prompt_governance → 造 callable → 造 SingleFlowEngine" 装配流程,逐行近似。

  • 代码:

    # backend/routes/node_routes.py:331-339
    governance_config = config_payload.get("prompt_governance") if isinstance(config_payload.get("prompt_governance"), dict) else {}
    translation_config = governance_config.get("translation") if isinstance(governance_config.get("translation"), dict) else {}
    moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
    routing_config   = governance_config.get("routing")    if isinstance(governance_config.get("routing"), dict) else {}
    ...
    moderation_route = str(moderation_config.get("model_route") or model_assignments.get("cross_review_primary") or "").strip()
    moderation_callable = (model_provider_runtime.structured_text_callable(moderation_route) or astrbot_structured_text_callable(moderation_route)) if moderation_route else None
    
    # backend/services/advanced_material_service.py:1731-1746(同构复制)
    moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
    ...
    moderation_route = str(... or model_assignments.get("cross_review_primary") or "").strip()
    moderation_callable = (
        runtime.structured_text_callable(moderation_route)
        or astrbot_structured_text_callable(moderation_route)
    ) if moderation_route else None
    

    第三处 backend/routes/prompt_routes.py:63-64 又独立造了一遍 PromptModerationService(moderation_config, reviewer) 与 GenerationRouteService(routing_config)。

  • 影响:governance 配置结构一旦变化(新增字段、改默认回退键),必须同步修改 3 处;漏改会导致"网页生成走新策略、素材导入/聊天走旧策略"的行为分叉,且这种分叉不会报错。

  • 修复建议:抽 backend/services/prompt_governance_service.py 内新增 build_governance_bundle(config_payload, runtime) -> GovernanceBundle(含 translation/moderation/routing/image_moderation 四个服务),三处调用方统一使用。


[P2-中等] 全局可变状态:AstrBot 桥接与配置覆盖是进程级模块变量,测试隔离困难

  • 位置:core/astrbot_provider_bridge.py:22-31、database/db_helper.py:26-46

  • 问题:跨请求、跨线程共享的运行时状态用模块级 global 承载,无锁、无作用域、无重置入口。

  • 代码:

    # core/astrbot_provider_bridge.py:22-31
    _context: Any | None = None
    _runtime_loop: asyncio.AbstractEventLoop | None = None
    ASTRBOT_VISION_TIMEOUT_SECONDS = 270
    
    def configure_astrbot_provider_bridge(context: Any | None, loop: asyncio.AbstractEventLoop | None) -> None:
        global _context, _runtime_loop
        _context = context
        _runtime_loop = loop
    
    # database/db_helper.py:26-46
    _RUNTIME_CONFIG_OVERRIDES: dict[str, Any] = {}
    _RUNTIME_CONFIG_PERSISTER: Callable[[Mapping[str, Any]], Mapping[str, Any] | None] | None = None
    
    def set_runtime_config_overrides(payload: Mapping[str, Any] | None) -> None:
        global _RUNTIME_CONFIG_OVERRIDES
        _RUNTIME_CONFIG_OVERRIDES = _copy_plain_mapping(payload or {})
    

    _runtime_loop 被工作线程用于 asyncio.run_coroutine_threadsafe(core/astrbot_provider_bridge.py:79/86),读取时无内存屏障保护:

    # core/astrbot_provider_bridge.py:70-86
    loop = _runtime_loop
    if provider is None or loop is None or loop.is_closed():
        return None
    ...
    future = asyncio.run_coroutine_threadsafe(invoke(), loop)
    text = future.result(timeout=180)
    
  • 影响:

    • 插件热重载(terminate() → initialize())期间 _runtime_loop 可能指向已关闭的 loop,工作线程正在 run_coroutine_threadsafe 会拿到 RuntimeError;terminate()(main.py:433)没有把 _context/_runtime_loop 复位;
    • 测试必须靠 tests/test_astrbot_provider_bridge.py、test_astrbot_runtime_config_bridge.py、test_plugin_bootstrap.py 手动 set/复位这些 global,测试之间存在顺序耦合,无法并行;
    • _RUNTIME_CONFIG_OVERRIDES 被 34 处 load_database_settings() 隐式读取,配置改动的影响面在调用点完全不可见。
  • 修复建议:

    1. terminate() 中调用 configure_astrbot_provider_bridge(None, None) 清场;
    2. 把两组 global 收进小对象(AstrBotRuntimeBridge / RuntimeConfigStore)并暴露 reset(),测试用 fixture 统一 setup/teardown;
    3. _runtime_loop 的读改用一次性局部快照 + loop.is_closed() 双检(现有代码已做了一半),并在 run_coroutine_threadsafe 外包 try/except RuntimeError。

[P2-中等] 无组合根导致每次路由调用都重读 config.yaml 并重建整棵对象树

  • 位置:34 处 Database(load_database_settings())(23 个 route 模块 + 4 个 service 模块);database/db_helper.py:64-83, 297-298

  • 问题:load_database_settings() → load_config_payload() → path.read_text(),全链路无缓存(db_helper.py、core/config_service.py 中 lru_cache 出现次数为 0)。node_routes._create_generation_service() 内还额外再调一次 load_config_payload(),即一次生成请求至少两次磁盘 YAML 解析,外加 9 个 repository、1 个 provider runtime、4 个 governance 服务的重新构造。

  • 代码:

    # database/db_helper.py:297-298
    def load_database_settings(config_path: str | Path = "config.yaml") -> DatabaseSettings:
        return DatabaseSettings.from_mapping(load_config_payload(config_path))
    
    # database/db_helper.py:64-69
    def load_config_payload(config_path: str | Path = "config.yaml") -> dict[str, Any]:
        path = resolve_config_path(config_path)
        payload = load_config_file_payload(path)     # ← 每次 read_text + 自研 YAML 子集解析
        if _should_apply_runtime_overrides(path):
            return _merge_mappings(payload, _RUNTIME_CONFIG_OVERRIDES)
        return payload
    
    # backend/routes/node_routes.py:316, 327
    database = Database(load_database_settings())     # 第 1 次读盘
    ...
    config_payload = load_config_payload()            # 第 2 次读盘
    
  • 影响:耦合表现为"每个 route 都必须知道整棵依赖树怎么装",35 个工厂各自维护同一份知识;性能上把配置文件 IO 放进了请求热路径;行为上任何人改 config.yaml 会在下一次请求半途生效,同一次请求内两次读取甚至可能读到不同内容。

  • 修复建议:load_config_payload 加进程级缓存(按 (path, mtime) 失效),set_runtime_config_overrides 时主动 invalidate;组合根(见 P1 第二条)持有单例 service 图,route 只从容器取。


[P3-轻微] 服务穿透邻居对象的私有依赖取 Database(迪米特法则违规)

  • 位置:backend/services/workflow_round_service.py:67、backend/services/workflow_round_worker_runtime.py:193、backend/routes/round_routes.py:139、backend/routes/workflow_routes.py:94、backend/routes/profile_routes.py:156

  • 问题:拿不到 Database 就顺着别的对象的内部属性链摸过去。

  • 代码:

    # backend/services/workflow_round_service.py:66-71
    self.resource_access_service = resource_access_service or ResourceAccessService(
        ProfileRepository(round_repository.database),   # ← 穿透 repository 的内部 database
        workflow_repository, image_repository, job_repository,
    )
    
    # backend/services/workflow_round_worker_runtime.py:192-193
    generation_service = create_generation_service()
    database = generation_service.queue_service.repository.database   # ← 三级穿透
    
    # backend/routes/round_routes.py:138-139
    generation_service = create_generation_service()
    database = generation_service.queue_service.repository.database
    
  • 影响:Repository.database 从实现细节变成了事实上的公开 API,任何仓储重构(例如改为持有连接池而非 Database)会同时打断 5 个调用点;对象图的真实依赖在构造函数签名上完全看不见。

  • 修复建议:组合根统一持有 Database 实例并显式注入;过渡期至少在 ResourceAccessService 等处把 ProfileRepository 作为构造参数传入,而不是就地用穿透来的 database 现造。


[P3-轻微] generation_service 内部 event_bus 取用方式自相矛盾

  • 位置:backend/services/generation_service.py:104 vs :1416-1427

  • 问题:同一个类里有两套取总线的写法:self.event_bus(构造注入,_publish() 用,5 处)和 self.workflow_service.event_bus(穿透邻居,2 处)。

  • 代码:

    # backend/services/generation_service.py:104
    self.event_bus = event_bus
    # :1701-1703
    def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
        if self.event_bus:
            self.event_bus.publish(event_type, payload)
    
    # :1416-1427(同一个类,换了个总线来源)
    if self.workflow_service.event_bus:
        self.workflow_service.event_bus.publish("workflow.node_status_changed", {...})
        self.workflow_service.event_bus.publish("workflow.node_updated", {...})
    
  • 影响:在 _create_generation_service() 里两者恰好是同一个 DEFAULT_EVENT_BUS,所以现在没暴露;但只要有人用未注入 event_bus 的 WorkflowService 构造 GenerationService(node_material_routes、branch_routes、history_routes、review_routes 的 WorkflowService 就是这种),workflow.node_status_changed 就会静默丢失——与 P1 第一条同源。

  • 修复建议:1416-1427 改用 self._publish(...),删除 self.workflow_service.event_bus 引用。


[P3-轻微] 冗余的函数内 import(已在模块顶部导入同一模块)

  • 位置:backend/services/generation_service.py:1493、:1506

  • 问题:模块顶部 generation_service.py:17-24 已经 from backend.services.prompt_governance_service import (...) 导入了 6 个名字,函数体内又对同一模块做了两次局部 import。这不是循环依赖规避(该模块无反向依赖),纯属遗漏。

  • 代码:

    # 顶部 :17-24 已有
    from backend.services.prompt_governance_service import (
        GenerationFailureClassifier, GenerationRouteService, ImageModerationService,
        PromptModerationService, PromptSemanticNormalizer, PromptTranslationService,
    )
    # :1492-1494
    if moderation is None:
        from backend.services.prompt_governance_service import PromptModerationDecision
        moderation = PromptModerationDecision("safe", 1.0, [], ["moderation_not_configured"], "allow", None, "none", None, "")
    # :1505-1507
    else:
        from backend.services.prompt_governance_service import GenerationRouteDecision
        route = GenerationRouteDecision(...)
    
  • 影响:制造"这里有循环依赖"的误导性信号,干扰后续重构判断(本次审计正是靠函数内 import 定位循环依赖痕迹)。

  • 修复建议:把 PromptModerationDecision、GenerationRouteDecision 并入顶部 import 块。


[P3-轻微] main.py 内 66 条配置映射被正反两个方向各写一遍

  • 位置:main.py:108-172(正向映射表,66 条)vs main.py:1929-2205(反向映射,279 行手写代码)

  • 问题:_RUNTIME_PATH_TO_ASTRBOT_KEY 用声明式 dict 表达 "ImageStudio 配置路径 → AstrBot 配置键";_runtime_config_patch_from_mapping() 用 279 行命令式代码表达完全相同的 66 条关系的反方向。脚本比对确认当前两侧覆盖的 66 个 AstrBot 键完全一致——即两份数据现在同步,但靠人工维持。

  • 代码:

    # main.py:108-113(声明式)
    _RUNTIME_PATH_TO_ASTRBOT_KEY = {
        "plugin.display_name": "display_name",
        "generation.default_model": "default_generation_model",
        "generation.provider.provider_id": "generation_provider_id",
        ...  # 共 66 条
    }
    
    # main.py:1929, 1946-1949(命令式,同一批关系的反方向)
    def _runtime_config_patch_from_mapping(mapping: Mapping[str, Any]) -> dict[str, Any]:
        ...
        display_name = _runtime_text(_runtime_value(mapping, "display_name", fallback=plugin.get("display_name", _MISSING)))
        if display_name:
            _set_nested(patch, ("plugin", "display_name"), display_name)
        default_model = _runtime_text(_runtime_value(mapping, "default_generation_model"))
        if default_model:
            _set_nested(patch, ("generation", "default_model"), default_model)
    
  • 影响:新增一个配置项需要在两个相隔 1800 行的位置各改一次;只改一边会造成"能读不能写"或"能写不能读"的单向配置,且不会有任何报错。

  • 修复建议:保留 dict 作为唯一真相,_runtime_config_patch_from_mapping 改为遍历 _RUNTIME_PATH_TO_ASTRBOT_KEY.items() + _set_nested(patch, tuple(path.split(".")), value),只把少数需要特殊类型转换的键(postgresql.port 转 int、*_enabled 转 bool、allowlist 拆列表)保留为显式分支。整块可从 279 行压到 ~50 行,并整体搬到 core/astrbot_config_mapping.py。


附录 A · 扇入 / 扇出排行(179 个模块,模块粒度有向图)

扇入 Top 10(被最多模块 import)

扇入 模块 层 评价
65 core.identity core 健康。纯 RequestContext 值对象,零下行依赖,理想的横切基础。
56 database.db_helper db 不健康。既是 Database/DatabaseSettings,又是 YAML 配置加载器(load_config_payload),两个无关职责挤在一个高扇入模块里。
53 backend.dto.common dto 位置错误。事实上的全局错误契约,却被放在 backend 包下,逼得 core/* 反向依赖(见 P2 第一条)。
31 backend.routes.common route 可接受但命名误导。只有 17 行的 handle_request,且只被 route 模块 import(已验证 route 包外无引用)。
31 core.security core 健康(但需摘掉对 backend.dto.common 的依赖)。
30 core.audit_service core 中性。审计是横切关注点,扇入高合理;但它 import database.db_helper 使 core 不再是底层。
19 database.repositories.workflow_repository db 合理,工作流是核心聚合。
16 backend.routes.params route 同 routes.common。
16 database.repositories.profile_repository db 合理。
15 backend.services.workflow_service service 风险点。唯一进入 Top10 的 service,是耦合簇的中心(见附录 B)。

扇出 Top 10(import 最多别人)

扇出 模块 行数 评价
31 backend.routes.node_routes 490 最不健康。它是事实上的组合根(_create_generation_service 装配 20+ 对象),却挂在 route 层,还被 service 反向 import。
29 backend.services.advanced_material_service 1856 God service。45 个方法 + 14 参数构造函数 + 自带装配工厂 create_advanced_material_service()。
22 main 2580 见附录 C。
21 backend.services.generation_service 2432 21 参数构造函数(全仓第一),28 个方法,直连 13 个其它 service。
16 backend.routes.material_routes / node_material_routes — route 层重复装配的典型。
16 backend.services.workflow_round_service 1596 耦合簇核心之一。
15 backend.routes.integration_routes — 同上。
14 backend.services.workflow_service 1296 既高扇入(15)又高扇出(14),典型的枢纽节点。
13 backend.routes.image_routes / profile_routes — —
12 6 个 route 模块并列 — route 层平均扇出 ~12,全部来自各自的 _create_*_service()。

关键指标:backend/routes 平均扇出 12,而理想 route 模块应只依赖 1 个 service + 契约层(3-4)。这个 3-4 倍的超额完全来自散落的装配代码。


附录 B · Service 间直连耦合簇

模块级无循环导入(Tarjan SCC 只在 adapters/__init__ ↔ adapters.onebot11_adapter / adapters.wechat_adapter 之间,属 __init__ re-export 的正常形态)。但存在两个高密度直连簇。

graph TD
    subgraph 簇1["簇 1:workflow / generation(19 条 service→service 直连边)"]
        NR["routes.node_routes<br/>组合根(位置错误)"]
        GS["generation_service<br/>2432行/21参数"]
        WS["workflow_service<br/>扇入15 扇出14"]
        WRS["workflow_round_service<br/>1596行"]
        WRWR["workflow_round_worker_runtime"]
        BLS["branch_lineage_service"]
        WNMS["workflow_node_material_service"]
        NDCS["node_dependency_context_service"]
        WGCRS["workflow_generation_cross_review_service"]
        GJRS["generation_job_retry_service"]
        WPS["workflow_progression_service"]
        IS["image_service"]
        QS["queue_service"]
        WMSS["workflow_material_snapshot_service"]
        WRR[("db: workflow_round_repository")]
        WCRR[("db: workflow_cross_review_repository")]
    end

    GS --> WS
    GS --> QS
    GS --> IS
    GS --> WMSS
    GS --> NDCS
    WRS --> GS
    WRS --> WPS
    WRWR --> GS
    WRWR --> WRS
    WRWR -.->|"service→route 违规"| NR
    NR --> GS
    WGCRS --> WRS
    GJRS --> GS
    WS --> BLS
    WS --> WPS
    WS --> QS
    WNMS --> WS
    WNMS --> BLS
    NDCS --> WS
    NDCS --> BLS
    IS --> WS
    IS --> WPS
    WRR -.->|"db→service 违规"| BLS
    WCRR -.->|"db→service 违规"| BLS

簇 1(workflow/generation):14 个 service + 1 个 route + 2 个 repository,19 条 service→service 直连边。中心是 workflow_service(扇入 15 / 扇出 14)与 generation_service(扇出 21)。虚线为 3 条方向违规边。

簇 2(advanced material / style):advanced_material_service(1856 行)→ advanced_style_set_service(4491 行,单类 2092 行、31 个方法、81 个模块级私有函数)、material_service、material_normalization_service、worker_service、queue_service、cost_service、cost_guard_service、model_provider_{service,runtime,bootstrap}、prompt_governance_service、event_stream_service —— 单模块直连 12 个 service,且自己承担装配(create_advanced_material_service() 在 advanced_material_service.py:1700-1764)。

没有任何接口/协议隔离:全仓无 Protocol / ABC 定义的 service 接口,所有 service→service 都是具体类硬 import。唯一的"接口化"痕迹是 chat_workflow_service.py:22 的 Dispatcher = Callable[..., dict[str, Any]],但它是完全无类型约束的字符串分发(见 P2 第三条)。


附录 C · main.py 2580 行职责分解

行号区间 行数 职责 归属评价
1-27 27 import + PLUGIN_ROOT 保留
28-98 71 _prepend_plugin_package_path() 包路径 shim 抽到 core/plugin_bootstrap.py
100-172 73 _RUNTIME_PATH_TO_ASTRBOT_KEY(66 条配置映射表) 抽到 core/astrbot_config_mapping.py
174-221 48 AstrBot API 缺失时的 fallback stub 类 抽到 adapters/astrbot_stubs.py
223-352 130 模块级门面(get_plugin_manifest / register_plugin / dispatch_web_request / register_bridge_api) 保留,这是 main 的正当职责
354-447 94 Main.__init__ / initialize / terminate 保留,唯一真正的生命周期代码
449-1297 849 长命令聊天处理器(约 50 个 imagestudio_*),含 imagestudio_confirm 里的 session action 分派业务逻辑(549-612) 抽到 backend/chat/commands/*.py,按域拆 5-6 个模块
1299-1463 165 yp 短别名,每个方法都是 3 行纯转发(async for result in self.imagestudio_X(...): yield result) 全部删除,改用数据驱动注册
1465-1751 287 文本格式化 helper + 后台任务 + 主动推送 + 终态通知重放 格式化抽 backend/chat/formatters.py;推送抽 backend/chat/notifier.py
1753-1927 175 桥接注册路由表 + 配置持久化 抽到 adapters/astrbot_bridge.py
1929-2205 277 _runtime_config_patch_from_mapping(66 条映射的反方向手写实现) 抽到 core/astrbot_config_mapping.py,并按 P3 第三条压缩到 ~50 行
2208-2580 373 HTTP 请求/响应适配(_make_bridge_handler、_request_query、_to_bridge_response、_to_media_http_response 等 20 个私有函数) 抽到 adapters/astrbot_http.py

归类占比:真正的初始化/生命周期 94 行(3.6%);对外门面 130 行(5%);聊天业务与呈现 1301 行(50.4%);AstrBot 配置与 HTTP 桥接 825 行(32%);环境 shim 192 行(7.4%)。

拆分后 main.py 目标规模:约 250 行(27 + 130 + 94,加少量粘合)。

短别名块(1299-1463)的具体替代方案:

# 用注册表替代 165 行手写转发
_SHORT_ALIASES = {
    "帮助": "imagestudio_help", "状态": "imagestudio_status",
    "快速角色": "imagestudio_quick_profile", ...   # 约 40 条
}
for _alias, _target in _SHORT_ALIASES.items():
    _bind_short_alias(Main, imagestudio_short_command, _alias, _target)

附录 D · 解耦方案优先级

优先级 动作 消除的问题 影响面
1 建 backend/composition.py 唯一组合根,迁入 35 个 _create_*_service() P1-2(service→route)、P2-2(装配复制)、P2-4(重复读盘)、P3-1(属性穿透) 35 个 route 文件 + 4 个 service
2 补齐 4 处 event_bus=,并把 event_bus 默认值改为 get_default_event_bus() P1-1(事件静默丢失)、P3-2 5 个文件,改动 <20 行
3 下沉 branch_state_for/with_branch_state/BRANCH_STATE_FIELDS → core/branch_state.py P1-3(db→service) 3 个 repository + 3 个 service
4 下沉 ApiError/ErrorCode → core/errors.py;下沉 load_config_payload → core/config_loader.py P2-1(core→backend、core→db) 53 + 56 个 import 点(可用 re-export 渐进)
5 main.py 按附录 C 拆分为 6 个模块 职责膨胀 仅 main.py + 新增 6 文件
6 ChatWorkflowService 的 69 处字符串 dispatch 换成类型化门面或直接依赖 service P2-3 1 个 service 文件
7 EventBus 加锁 + 异常隔离,并把 3 组"通知型"直连迁到总线;否则删掉 subscribe/unsubscribe P2-2(event_bus 空转) core/event_bus.py + 3 个 service
8 拆 advanced_style_set_service.py(4491 行 / 1 类 / 81 个私有函数)与 advanced_material_service.py(1856 行 / 45 方法) God object 2 个大文件