42 KiB
B2 · 后端内部耦合与架构分层
审计范围(实际 Read / Grep 过的源文件):
main.pybackend/route_registry.pybackend/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.pybackend/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.pycore/:event_bus.py、config_service.py、security.py、audit_service.py、astrbot_provider_bridge.py、media_proxy.py、storage.pydatabase/:db_helper.py、repositories/workflow_round_repository.py、repositories/workflow_cross_review_repository.py、repositories/profile_card_repository.py、repositories/workflow_repository.pyadapters/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 个漏传点。 -
修复建议:
- 立即修复:把
event_bus=get_default_event_bus()补进 4 处工厂; - 根治:让
WorkflowService.event_bus默认取get_default_event_bus()而非None,并把publish收敛成服务自身的self._publish(...)方法(像QueueService._publish那样),禁止self.<other_service>.event_bus这种穿透写法; - 加一条单测:断言
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 层,任何血缘策略调整都要改仓储;仓储层无法脱离服务层单独测试。 -
修复建议:
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都从下层取;branch_lineage_service保留需要WorkflowRepository的那部分(workflow_metadata_for_branch等),停留在 service 层;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 加载,跟数据库无关。 -
修复建议:
- 把
ApiError/ErrorCode/success_response/response_from_exception从backend/dto/common.py移到core/errors.py,backend/dto/common.py保留 re-export 做过渡; - 把
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_BUS6 个 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的工作线程和请求线程共享,将来加订阅时是竞态温床。
- 已有基础设施但没兑现解耦价值,
-
修复建议:
- 先把
publish改成异常隔离(try/except包每个 handler,失败只记日志不冒泡),并给subscribe/unsubscribe/_handlers加threading.Lock; - 用总线替换 3 组明显的"通知型"直连:
generation_service → workflow_service的节点状态回写、queue_service → 通知回调(目前workflow_round_worker_runtime通过terminal_notification_callback参数手动穿到main.py:1672)、deletion_safety_service → image/media的级联清理; - 如果确认不打算做订阅,就把
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-390vsbackend/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()隐式读取,配置改动的影响面在调用点完全不可见。
- 插件热重载(
-
修复建议:
terminate()中调用configure_astrbot_provider_bridge(None, None)清场;- 把两组 global 收进小对象(
AstrBotRuntimeBridge/RuntimeConfigStore)并暴露reset(),测试用 fixture 统一 setup/teardown; _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:104vs: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 条)vsmain.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 个大文件 |