653 行
42 KiB
Markdown
653 行
42 KiB
Markdown
# 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` 事件永远不会发出。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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=
|
||
```
|
||
|
||
```python
|
||
# 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` 同名工厂是传了的:
|
||
|
||
```python
|
||
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 层才能拿到它。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# 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,循环依赖规避痕迹):
|
||
|
||
```python
|
||
# 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`。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# database/repositories/workflow_cross_review_repository.py:17
|
||
from backend.services.branch_lineage_service import branch_state_for, with_branch_state
|
||
```
|
||
|
||
```python
|
||
# 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`:
|
||
|
||
```python
|
||
# 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 个模块反向依赖了上层包。
|
||
- **代码**:
|
||
|
||
```python
|
||
# core/security.py:5-6
|
||
from backend.dto.common import ApiError, ErrorCode
|
||
from core.identity import RequestContext
|
||
```
|
||
|
||
```python
|
||
# core/config_service.py:9-10
|
||
from core.runtime_paths import resolve_config_path
|
||
from database.db_helper import load_config_payload
|
||
```
|
||
|
||
```python
|
||
# 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 完成(见服务耦合簇一节)。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# 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`。
|
||
- **代码**:
|
||
|
||
```python
|
||
# main.py:372
|
||
self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
|
||
```
|
||
|
||
```python
|
||
# 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={...},
|
||
))
|
||
```
|
||
|
||
```python
|
||
# 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" 装配流程,逐行近似。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# 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` 承载,无锁、无作用域、无重置入口。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# 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`),读取时无内存屏障保护:
|
||
|
||
```python
|
||
# 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 服务的重新构造。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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
|
||
```
|
||
|
||
```python
|
||
# 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` 就顺着别的对象的内部属性链摸过去。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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,
|
||
)
|
||
```
|
||
|
||
```python
|
||
# backend/services/workflow_round_worker_runtime.py:192-193
|
||
generation_service = create_generation_service()
|
||
database = generation_service.queue_service.repository.database # ← 三级穿透
|
||
```
|
||
|
||
```python
|
||
# 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 处)。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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。这不是循环依赖规避(该模块无反向依赖),纯属遗漏。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 顶部 :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 键完全一致——即两份数据现在同步,但靠人工维持。
|
||
- **代码**:
|
||
|
||
```python
|
||
# 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 条
|
||
}
|
||
```
|
||
|
||
```python
|
||
# 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 的正常形态)。但存在两个高密度直连簇。
|
||
|
||
```mermaid
|
||
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)的具体替代方案:
|
||
|
||
```python
|
||
# 用注册表替代 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 个大文件 |
|