101 KiB
03 · 耦合分析
材料来源:
审计/findings/B1-前后端耦合.md、B2-后端内部耦合.md,辅以A7-路由与插件入口.md、A8-前端App主体.md、A9-前端功能组件.md。 所有被审计/findings/_复核结论.md推翻的条目已剔除;复核判定"机制属实但影响被夸大"的,按复核给出的严重度收录并标注经复核降级。 本文中的量化数字若标[实测],为撰写本报告时在仓库中重新执行命令核对过的。
摘要
这个仓库的耦合问题不是"接错线",而是"没有装配台"。 后端 263 个 pytest 全部通过、前端 26 个 node:test 全部通过,166 条后端路由与 143 条前端 endpoint 声明逐条比对零个会 404,App.vue 里 endpoints. 引用 183 处、全前端唯一的 /api/ 字面量就是 endpoints.ts:1 的 API_BASE 定义本身 [实测]。代码跑得起来,URL 也对得上。真正的病灶在于:组合根(composition root)缺失,导致 20 个 route 模块各自手写 35 个装配函数、34 处 Database(load_database_settings()) 各自重读一次 config.yaml [实测];同一个 WorkflowService 在不同路由下被装配成行为不一致的实例,且不一致是静默的。
后端侧最贵的一条是装配分散,不是分层违规。 分层违规(service → route、database → backend.services/engines、core → backend.dto)确实存在且方向明确,但它们各自只有 1-3 个调用点,属于"知道位置就能改"的问题。装配分散不一样:它已经产生了可复现的行为不一致——node_material_routes.py:69 构造 WorkflowService 时漏传 event_bus,于是 workflow.node_material_bindings_updated 事件永远不发;branch_routes.py:62 的工厂同样漏传。因为消费端写成 if self.workflow_service.event_bus:(穿透邻居属性),短路后没有日志、没有异常、没有任何痕迹。这类缺陷会随着新增路由持续复制,是本项目投入产出比最高的重构点。
⚠️ 复核定级(不要按 P1 排工作量):这两条事实层面全部核实为真(行号精确、路径可达、无上游兜底),但复核把它们从 P1 降到 P3,理由是丢失的事件当前零消费者——全仓
subscribe()调用为 0,workflow.branch_created只有一处 publish、无任何订阅方,workflow.branch_switched这个事件全仓根本不存在(初审引用的workflow_service.py:640实际落在create_node内,属张冠李戴)。审计链路不受影响(audit_service.record走另一条正确装配的依赖,无条件执行);业务数据不丢(save后直接return self.get_node_bindings(...),前端同步拿到最新状态)。用户可见影响仅为 overview/performance/logs 三个导航页上一次可能的自动刷新延迟。它仍然是本报告推荐优先做的第一项——因为改动 <20 行、风险极低、且是装配分散这个结构性问题唯一已实证的出口。但它的价值在于"堵住结构性缺陷的复制路径",不在于"修一个正在伤害用户的 bug"。
前后端侧最贵的一条是语义契约缺位,不是 URL 管理。 URL 层收敛得很干净,但 URL 背后的规则没有被下发:后端有 character_gradual_progression().to_dict()、有 PERMISSION_MATRIX、有 ContractService 这些"可下发的真相",却没有一条路由把它们送到前端,于是前端只能复刻——顺序进度状态机复刻了四层规则、节点写锁规则复刻后少判一个可达条件(selected_image_id)还多出一个后端根本不产出的 sealed_at 字段(grep -rn "sealed_at" --include=*.py 返回 0 [实测])、快速角色四联图的整条工作流状态机被搬进浏览器里 291 行编排。注意这三条经复核分别定为 P2 / P3 / P2,不是 P1(详见 §2.2 的逐条降级说明)——它们是"改起来会越来越贵"的耦合债,不是"现在正在伤害用户"的缺陷。GET contract 端点已经把 166 条路由 + 权限矩阵 + 错误码全部发布出来了,唯一的消费者是设置页里一个 JSON.stringify 诊断框——契约自检的数据早就齐了,只差三条 CI 断言。这是本维度最低成本、最高收益的修复方向。
第一部分 · 后端内部耦合
1.1 分层违规清单
预期分层是 routes → services → repositories,core 作为无上行依赖的横切基础设施。实际存在 3 类共 9 条方向违规:
| 违规类型 | 位置 | 说明 |
|---|---|---|
| service → route(方向最刺眼,但复核定级 P3) | backend/services/workflow_round_worker_runtime.py:10from backend.routes.node_routes import create_generation_service |
后台 round worker 是 service 层组件,却必须反向 import route 层才能拿到装配好的 GenerationService。装配根 _create_generation_service() 定义在 backend/routes/node_routes.py:315-390(私有)+ :393(公开包装),在那里完成 Database、9 个 repository、ModelProviderRuntime、SingleFlowEngine、4 个 governance 服务的构造。后果:backend/routes 成为 worker 的不可卸载运行时依赖,HTTP 层与 worker 层无法分开打包或测试。⚠️ 复核修正(必须如实记录):初审附加的两条影响经复核证伪 —— (a) "单测想构造 GenerationService 就得连带 import node_routes 的 31 个依赖"是错的,tests/test_workflow_round_queue_runtime.py:12 直接 from backend.services.generation_service import GenerationService 并在测试内手工装配,完全绕开 node_routes;(b) 无循环导入(node_routes.py 内 worker_runtime/round_worker 零命中),且 node_routes 导入期无副作用(装配全在函数体内)。worker 走的 :393-396 是带 docstring 的显式公共出口("""Public runtime factory shared by HTTP routes and background workers."""),属有意设计的缝。真正不规范的只有 job_routes.py:311 舍近求远取私有名。复核定级 P3-轻微:纯架构整洁度/可打包性问题,无可触发的失败路径。 |
| route → route(取私有符号) | backend/routes/job_routes.py:311from backend.routes.node_routes import _create_generation_service |
函数体内 import,且取的是下划线私有名(同文件 :393 有公开的 create_generation_service)。注释写着 Import lazily so route discovery does not construct provider runtimes——直接说明这条 import 边有启动期副作用压力。 |
| database → backend.services | database/repositories/workflow_round_repository.py:17database/repositories/workflow_cross_review_repository.py:17from backend.services.branch_lineage_service import branch_state_for, with_branch_state |
仓储层(最底层)反向 import 业务服务层。分支血缘规则被钉死在 SQL 层。而 backend/services/branch_lineage_service.py:17 自己又 from database.repositories.workflow_repository import WorkflowRepository——包级双向依赖已经成立,模块粒度目前恰好没成环,但只要 branch_lineage_service 再多 import 一个 round/cross-review repository 就立刻真成环。 |
| database → engines | database/repositories/profile_card_repository.py:11from engines.character_flow import canonical_gradual_node_key |
同上,仓储层依赖引擎层的节点键归一逻辑。 |
| core → backend.dto | core/security.py:5from backend.dto.common import ApiError, ErrorCode |
backend.dto.common(扇入 53/54,全仓第三)事实上扮演"全局错误契约"的角色,却被放在 backend 包下,逼得 core 反向依赖。命名与真实分层错位。 |
| core → database | core/config_service.py:10from database.db_helper import load_config_payload |
把"读配置"和"连数据库"绑在一起——而 load_config_payload 本质是 YAML 加载,跟数据库毫无关系。 |
| core → database | core/audit_service.py:12from database.db_helper import Database, DatabaseSettings |
审计服务需要落库可以理解,但代价是 core 整体不再是最底层,无法独立复用或测试。 |
| core → backend/database | core/storage.py:11、core/media_proxy.py:17 |
同族问题,共 5 个 core 模块有上行依赖。 |
修复顺序(按"改动面 / 收益"排):
branch_state_for/with_branch_state/BRANCH_STATE_FIELDS是纯函数 + frozenset(对 dict 做字段级投影,无 I/O、无状态),下沉到core/branch_state.py,database与backend.services都从下层取。同理canonical_gradual_node_key下沉,或由 service 在传参前算好再交给 repository。影响面:3 个 repository + 3 个 service。ApiError/ErrorCode/success_response/response_from_exception从backend/dto/common.py移到core/errors.py,backend/dto/common.py保留re-export做过渡——53 个 import 点可以零改动渐进迁移。load_config_payload/load_config_file_payload/_RUNTIME_CONFIG_OVERRIDES从database/db_helper.py:26-83抽到core/config_loader.py,db_helper反过来 import 它。做完这两条core恢复零上行依赖。service → route由 §1.4 的组合根一次性解决。
1.2 扇入 / 扇出 Top 10
对 179 个 Python 模块做导入抽取得到的模块级有向图。
扇入 Top 10(被最多模块 import)
| 扇入 | 模块 | 层 | 评价 |
|---|---|---|---|
| 65 | core.identity |
core | 健康。纯 RequestContext 值对象,零下行依赖,这就是横切基础设施该有的样子——它是全仓唯一可以照抄的正面样板。 |
| 56 | database.db_helper |
db | 不健康。既是 Database/DatabaseSettings,又是 YAML 配置加载器(load_config_payload),两个完全无关的职责挤在一个 56 扇入的模块里。任何想读配置的模块都被迫依赖数据库层。 |
| 54 | backend.dto.common |
dto | 位置错误。事实上的全局错误契约(ApiError/ErrorCode/响应信封),却被放在 backend 包下,直接造成 §1.1 的 core → backend.dto 违规。 |
| 31 | core.security |
core | 健康(摘掉对 backend.dto.common 的依赖后就完全干净)。 |
| 31 | backend.routes.common |
route | 可接受但命名误导。只有 17 行的 handle_request,已验证 route 包外无引用。 |
| 30 | core.audit_service |
core | 中性。审计是横切关注点,高扇入合理;但它 import database.db_helper 使 core 不再是底层。 |
| 19 | database.repositories.workflow_repository |
db | 合理,工作流是核心聚合。 |
| 16 | database.repositories.profile_repository |
db | 合理。 |
| 16 | backend.routes.params |
route | 同 routes.common。 |
| 15 | backend.services.workflow_service |
service | 风险点。唯一进入扇入 Top10 的 service,同时扇出 14——典型的枢纽节点,是耦合簇 1 的中心(见 §1.5)。 |
扇出 Top 10(import 最多别人)
| 扇出 | 模块 | 行数 | 评价 |
|---|---|---|---|
| 31 | backend.routes.node_routes |
490 | 全仓最不健康的模块。它是事实上的组合根(_create_generation_service 装配 20+ 个对象),却挂在 route 层,还被 service 层反向 import(§1.1 第一条)。 |
| 29 | backend.services.advanced_material_service |
1856 | God service。45 个方法 + 14 参数构造函数 + 自带装配工厂 create_advanced_material_service()(:1700-1764)。 |
| 22 | main |
2580 | 见 §1.7。 |
| 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 模块并列 | — | — |
关键指标:backend/routes 的平均扇出是 12,而一个理想的 route 模块只该依赖 1 个 service + 契约层(3-4)。这 3-4 倍的超额全部来自散落在 route 里的装配代码——这是把 §1.4 认定为首要重构点的量化依据。
1.3 循环依赖证据:36 处函数体内 import 的逐条归因
模块粒度上没有真循环(Tarjan SCC 只在 adapters/__init__ ↔ adapters.onebot11_adapter / adapters.wechat_adapter 之间,属 __init__ re-export 的正常形态)。但全仓有 36 处缩进的(函数体内)import [实测,分布逐条核对]。这类写法在 Python 项目里通常是循环依赖的"疤痕",因此逐条归因如下——结论是:36 处里只有 3 处真正在规避 import 环,其余是可选依赖守卫或纯遗漏。不要把这个数字当作"循环依赖严重"的证据。
| 文件 | 处数 | 行号 | 归因 | 规避的是哪个环 |
|---|---|---|---|---|
main.py |
6 | :178-183 |
可选依赖守卫。from astrbot.api.star import Star 等,在 AstrBot API 缺失时降级为 stub 类 |
无环 |
main.py |
2 | :390、:412 |
真·规避 + 启动韧性。from backend.services.workflow_round_worker_runtime import create_workflow_round_worker_runtime(:390)、advanced_material_worker_runtime(:412)。这两个 worker runtime 顶部 import backend.routes.node_routes,若在 main.py 顶部 import,模块加载期就会拉起整个 route 图;同时两处都包在 try/except Exception 里,让 worker 起不来时插件与恢复 UI 仍可用 |
main → worker_runtime → node_routes →(31 个依赖) |
main.py |
8 | :2307、:2317、:2469-2476、:2496、:2502、:2561 |
可选依赖守卫。astrbot.api.web / quart / starlette 三套 HTTP 运行时按可用性择一 |
无环 |
database/db_helper.py |
4 | :197-198、:216-217 |
可选依赖守卫。psycopg / psycopg2 双驱动探测 |
无环 |
backend/services/model_provider_runtime.py |
3 | :128、:193、:282 |
可选运行时守卫。from core.astrbot_provider_bridge import astrbot_*;核查 core/astrbot_provider_bridge.py 顶部 import(core.image_formats/core.storage/engines.vision_provider)无任何回边到 backend.services |
无环(可以安全提到顶部) |
backend/routes/job_routes.py |
2 | :87、:204 |
重型构造延迟。from backend.services.advanced_material_service import create_advanced_material_service(29 扇出的 God service) |
无环,纯性能/启动期考虑 |
backend/routes/job_routes.py |
1 | :311 |
真·规避。from backend.routes.node_routes import _create_generation_service,取私有名。注释:Import lazily so route discovery does not construct provider runtimes |
job_routes ↔ node_routes 的 route 间横向依赖 |
backend/services/generation_service.py |
2 | :1493、:1506 |
纯遗漏。顶部 :17-24 已经从同一模块 import 了 6 个名字,函数体内又局部 import PromptModerationDecision / GenerationRouteDecision |
无环——这两处制造了"这里有循环依赖"的误导信号,直接并入顶部 import 块即可 |
| 其余 8 处 | 8 | engines/image_provider.py、core/runtime_paths.py、core/generation_errors.py、backend/services/{quick_profile,material,api_discovery}_service.py、adapters/{webui_adapter,astrbot_card_renderer}.py 各 1 |
可选依赖/重型库延迟加载 | 无环 |
可执行结论:
- 立刻能做:删掉
generation_service.py:1493/1506两处冗余 import(0 风险),把model_provider_runtime.py的 3 处提到顶部(需确认core.astrbot_provider_bridge无启动副作用)。这样 36 降到 31,剩下的每一处都有明确理由。 job_routes.py:311与workflow_round_worker_runtime.py:10这两条真环,由 §1.4 的组合根一次性消除。
1.4 装配分散:本项目最有价值的重构点
1.4.1 事实
[实测] backend/routes/ 下共有 35 个装配函数分布在 20 个 route 模块里,其中 20 个严格命名为 _create_*_service() / create_*_service()(A7 按 _create_*_service 口径计为 22 个);全仓 34 处 Database(load_database_settings())。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 服务的重新构造:
# backend/routes/node_routes.py:316, 327
database = Database(load_database_settings()) # 第 1 次读盘
...
config_payload = load_config_payload() # 第 2 次读盘
1.4.2 已确认的两例行为不一致
这不是理论风险,是两处可复现的功能缺失。
例 1:素材绑定事件被静默丢弃
# backend/routes/node_material_routes.py:65-73 ← GET/POST node materials 的唯一装配路径
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", {...})
对照 backend/routes/profile_routes.py:176-181 的同类工厂,event_bus=get_default_event_bus() 是传了的。8 处 WorkflowService(...) 构造中只有 4 处传入 event_bus。
例 2:分支事件不推送
# backend/routes/branch_routes.py:62-68
def _create_workflow_service() -> WorkflowService:
database = Database(load_database_settings())
return WorkflowService(
workflow_repository=WorkflowRepository(database),
profile_repository=ProfileRepository(database),
audit_service=AuditService(database),
) # ← 同样没有 event_bus=
漏传的还有 history_routes.py:72、review_routes.py:90。
为什么排查成本极高:消费端写的是 if self.workflow_service.event_bus:——这是穿透邻居对象属性取总线(迪米特法则违规)。判空短路后没有日志、没有异常、没有降级提示。前端 GET events/stream 就是看不到这些事件,任何基于事件做增量刷新的功能静默失效。
同源问题还在 generation_service.py 内部:同一个类里有两套取总线的写法——self.event_bus(构造注入,_publish() 用,5 处)和 self.workflow_service.event_bus(穿透邻居,:1416-1427 处 2 处)。目前在 _create_generation_service() 里两者恰好是同一个 DEFAULT_EVENT_BUS 所以没暴露;但只要有人拿 node_material_routes / branch_routes / history_routes / review_routes 那种未注入 event_bus 的 WorkflowService 去构造 GenerationService,workflow.node_status_changed 就会一起静默丢失。
1.4.3 装配代码大段复制
同一套 "读 config → sync provider → 解析 prompt_governance → 造 callable → 造 SingleFlowEngine" 流程被逐行复制了三份:
# backend/routes/node_routes.py:331-339
governance_config = config_payload.get("prompt_governance") if isinstance(...) else {}
moderation_config = governance_config.get("moderation") if isinstance(...) 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(...) 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 与 GenerationRouteService。
后果:governance 配置结构一旦变化(新增字段、改默认回退键),必须同步修改 3 处;漏改会造成"网页生成走新策略、素材导入/聊天走旧策略"的行为分叉,且这种分叉不会报错。
另有 5 处靠属性穿透拿 Database:
# backend/services/workflow_round_worker_runtime.py:192-193 与 backend/routes/round_routes.py:138-139
generation_service = create_generation_service()
database = generation_service.queue_service.repository.database # ← 三级穿透
# backend/services/workflow_round_service.py:66-71
self.resource_access_service = resource_access_service or ResourceAccessService(
ProfileRepository(round_repository.database), ...) # ← 穿透 repository 的内部 database
Repository.database 因此从实现细节变成了事实上的公开 API:任何仓储重构(例如改持有连接池)会同时打断 5 个调用点,而对象图的真实依赖在构造函数签名上完全看不见。
1.4.4 方案:统一装配容器
目标:backend/composition.py 成为全仓唯一的组合根,依赖方向恢复为 routes → composition → services → repositories,worker → composition → services。
代码骨架:
# backend/composition.py —— 唯一组合根
"""Single composition root. Nothing outside this module may construct a service graph."""
from __future__ import annotations
import threading
from dataclasses import dataclass
from typing import Any
from core.config_loader import load_config_payload # §1.1 第 3 步下沉后的位置
from core.audit_service import AuditService
from database.db_helper import Database, load_database_settings
from backend.services.event_stream_service import get_default_event_bus
@dataclass(frozen=True)
class _Graph:
"""一次装配的产物;按 config 指纹缓存。"""
config_fingerprint: tuple[str, float]
database: Database
workflow_service: Any
generation_service: Any
round_service: Any
node_material_service: Any
# ... 其余按需
_lock = threading.Lock()
_graph: _Graph | None = None
def _fingerprint() -> tuple[str, float]:
"""(path, mtime) —— config.yaml 变了就重建整棵树。"""
from core.runtime_paths import resolve_config_path
path = resolve_config_path("config.yaml")
return (str(path), path.stat().st_mtime if path.exists() else 0.0)
def _build(fingerprint: tuple[str, float]) -> _Graph:
database = Database(load_database_settings())
config_payload = load_config_payload() # 整棵树只读一次盘
audit = AuditService(database)
bus = get_default_event_bus() # ← 唯一来源,杜绝漏传
# --- 仓储层 ---
from database.repositories.workflow_repository import WorkflowRepository
from database.repositories.profile_repository import ProfileRepository
workflows = WorkflowRepository(database)
profiles = ProfileRepository(database)
# ...
# --- governance bundle:取代三份复制 ---
governance = build_governance_bundle(config_payload, model_provider_runtime)
# --- 服务层 ---
from backend.services.workflow_service import WorkflowService
workflow_service = WorkflowService(
workflow_repository=workflows,
profile_repository=profiles,
audit_service=audit,
event_bus=bus, # ← 显式且唯一
)
# ... generation_service / round_service / node_material_service 同理
return _Graph(fingerprint, database, workflow_service, ..., )
def graph() -> _Graph:
global _graph
fp = _fingerprint()
with _lock:
if _graph is None or _graph.config_fingerprint != fp:
_graph = _build(fp)
return _graph
# --- 公开访问器:route / worker 只用这些 ---
def get_workflow_service(): return graph().workflow_service
def get_generation_service(): return graph().generation_service
def get_round_service(): return graph().round_service
def get_node_material_service(): return graph().node_material_service
def get_database() -> Database: return graph().database # 取代 5 处属性穿透
route 侧的调用点退化为一行:
# backend/routes/node_material_routes.py(改后)
from backend.composition import get_node_material_service
def save_node_material_bindings(ctx, node_id, payload=None, service=None) -> dict:
material_service = service or get_node_material_service() # ← 原 10 行工厂消失
...
worker 侧的反向依赖直接消失:
# backend/services/workflow_round_worker_runtime.py:10(改后)
from backend.composition import get_generation_service, get_database # 不再 import backend.routes.*
配套的两条护栏测试(没有这两条,同类漏传还会再犯):
# tests/test_composition_invariants.py
def test_every_workflow_service_has_event_bus():
"""禁止再出现漏传 event_bus 的装配路径。"""
from backend.composition import get_workflow_service, get_generation_service
assert get_workflow_service().event_bus is not None
assert get_generation_service().event_bus is not None
assert get_generation_service().workflow_service.event_bus is not None
def test_no_route_module_builds_a_service_graph():
"""route 层不得再出现 Database(...) 或 *Service(...) 构造。"""
import pathlib, re
offenders = []
for path in pathlib.Path("backend/routes").glob("*.py"):
src = path.read_text(encoding="utf-8")
if re.search(r"Database\(load_database_settings\(\)\)", src):
offenders.append(str(path))
assert offenders == [], f"route modules must use backend.composition: {offenders}"
迁移顺序(可增量,每步都能独立合并):
- 先建
backend/composition.py,只迁WorkflowService一族 + 那条test_every_workflow_service_has_event_bus。这一步就修掉了两例事件丢失。 - 迁
_create_generation_service(node_routes.py:315-390)→composition,node_routes与job_routes.py:311改为从 composition 取。这一步消除service → route与 route↔route 两条环。 - 抽
build_governance_bundle(config_payload, runtime) -> GovernanceBundle(含 translation/moderation/routing/image_moderation 四个服务),node_routes/advanced_material_service/prompt_routes三处统一调用。 - 逐个迁剩余 route 工厂,最后开启
test_no_route_module_builds_a_service_graph。
收益量化:backend/routes 平均扇出可从 12 降到 3-4;34 处磁盘 YAML 解析降到"每次 config 变更 1 次";两例已确认的事件丢失被修复且不可复发;node_routes 从扇出 31 降到个位数。
1.5 服务耦合簇
graph TD
subgraph C1["簇 1 · workflow / generation(19 条 service→service 直连边)"]
NR["routes.node_routes<br/>扇出31 · 事实组合根(位置错误)"]
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)。三条虚线为方向违规边。
簇 2(advanced material / style):
advanced_material_service (1856 行, 45 方法, 14 参数构造函数, 自带工厂 :1700-1764)
├─→ 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 / model_provider_runtime / model_provider_bootstrap
├─→ prompt_governance_service
└─→ event_stream_service
单模块直连 12 个 service
全仓没有任何接口/协议隔离:无 Protocol、无 ABC 定义的 service 接口,所有 service→service 都是具体类硬 import。唯一的"接口化"痕迹是 chat_workflow_service.py:22 的 Dispatcher = Callable[..., dict[str, Any]],但它是完全无类型约束的字符串分发(见下)。
特别注意 ChatWorkflowService:这个 1315 行的 service 不直接调用任何业务 service,而是把 dispatch_web_request 当 HTTP 客户端用,以字符串 method + path 69 次重新进入路由层,数据流变成 service → adapter → route → service:
# main.py:372
self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
# backend/services/chat_workflow_service.py:33-47(典型调用)
active = self._data(self.dispatcher(ctx, "GET", "jobs", query={"status": "running", ...}))
workflow = self._data(self.dispatcher(ctx, "POST", f"profiles/{profile['profile_id']}/workflows", payload={...}))
代价:(1) 类型安全全失——路径/参数名拼错只在运行时返回 RESOURCE_NOT_FOUND,IDE 与静态检查看不到这 69 条调用边,重命名任一路由会静默打断聊天流程;(2) 性能——每次 dispatch 走 inspect.signature 反射 + route 内 _create_*_service() 全量重建(含磁盘读 config.yaml),一条聊天命令动辄十几次 dispatch;(3) 错误语义扭曲——异常被 route 层包成 dict,service 再用 self._data() 拆包,异常栈完全丢失。
组合根落地后,ChatWorkflowService 应改为依赖 backend/composition.py 暴露的具体 service 对象。若要保留"聊天走公开契约"的设计意图,至少把 69 个字符串端点收敛成一个类型化门面(class ImageStudioApi + 每端点一方法,内部仍走 dispatcher),让重命名有静态检查保护。
1.6 core/event_bus.py 使用情况评估
结论:它不是事件总线,是一个被误命名的环形缓冲区。
| 指标 | 实际值 |
|---|---|
subscribe() 调用方(含 46 个测试文件) |
0 |
unsubscribe() 调用方 |
0 |
publish() 调用点 |
6 处:generation_service.py:1417/1427/1703、queue_service.py:702、workflow_node_material_service.py:209 |
| 实际用途 | GET events/stream 的 500 条进程内历史窗口(EventBus(history_limit=500),event_stream_service.py:11-15) |
# 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
三条具体问题:
- 零解耦价值。
workflow_round_service → generation_service、generation_job_retry_service → generation_service、deletion_safety_service → image_service/media_service这些"做完 A 顺手通知 B"的调用,本来正是总线该承接的,现在全部是硬 import——所以簇 1 才有 19 条直连边。 - 一旦有人开始订阅就立刻踩坑。
publish是同步调用,handler 抛异常会直接打断业务事务;_handlers是defaultdict(list),subscribe/unsubscribe无锁,而DEFAULT_EVENT_BUS被QueueWorkerPool的工作线程和请求线程共享。目前因为没有 handler 所以未暴露。 - 它伪装成解耦手段,误导架构判断。看到
EventBus的人会假设跨服务通信有异步通道,实际没有。
建议二选一,不要维持现状:
- 方案 A(推荐,若打算用):先给
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的级联清理。 - 方案 B(若不打算用):删掉
subscribe/unsubscribe/_handlers,把类改名为EventRecorder,明确它就是给events/stream用的历史缓冲。别让它继续伪装成解耦手段。
1.7 main.py 2,580 行的职责分解
| 行号区间 | 行数 | 职责 | 处置 |
|---|---|---|---|
| 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 行纯转发 |
全部删除,改数据驱动注册(见下) |
| 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,并压到 ~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)
# 替代 1929-2205 的 277 行反向映射:让 :108-172 的 dict 成为唯一真相
def _runtime_config_patch_from_mapping(mapping: Mapping[str, Any]) -> dict[str, Any]:
patch: dict[str, Any] = {}
for path, astrbot_key in _RUNTIME_PATH_TO_ASTRBOT_KEY.items():
value = _runtime_value(mapping, astrbot_key)
if value is _MISSING:
continue
coerce = _COERCIONS.get(path, _runtime_text) # postgresql.port→int、*_enabled→bool、allowlist→list
coerced = coerce(value)
if coerced not in ("", None):
_set_nested(patch, tuple(path.split(".")), coerced)
return patch
后者尤其值得做:目前 66 条配置关系被正反两个方向各写一遍(声明式 dict 在 :108-172,命令式 279 行在 :1929-2205,相隔 1800 行)。脚本比对确认两侧当前覆盖的 66 个 AstrBot 键完全一致——靠人工维持。新增一个配置项要在两个相隔 1800 行的位置各改一次,只改一边就得到"能读不能写"或"能写不能读"的单向配置,且不会有任何报错。
第二部分 · 前后端耦合
2.1 端点比对三张表
比对方法:从 backend/route_registry.py 提取 166 条 RouteSpec [实测],与 frontend/shared/api/endpoints.ts 的 143 个键 [实测] 及全前端 endpoints.<key> 引用做交叉。
表 ① 后端注册但前端从不调用(14 条死接口)
| # | 方法 | 端点 | handler | 判定 |
|---|---|---|---|---|
| 1 | DELETE | profiles/{profile_id} |
profile_routes.delete_profile |
死。UI「删除角色」实际调 profileArchive(App.vue:6300) |
| 2 | POST | profiles/{profile_id}/delete |
profile_routes.delete_profile_via_post |
死。endpoints.profileDelete 定义了但零引用 |
| 3 | POST | images/{image_id}/moderation-review |
image_routes.review_moderated_image |
死。见 §2.2 表外说明 |
| 4 | POST | advanced-material-imports/{import_id}/cancel |
advanced_material_routes.cancel_advanced_material_import |
死。endpoints.ts 里连键都没有 |
| 5 | POST | nodes/{node_id}/mark-completed |
node_routes.mark_node_completed |
死。是 nodes/{id}/complete 的同 handler 别名 |
| 6 | POST | nodes/{node_id}/select-image |
node_routes.select_node_image |
死。前端只用 images/{id}/select |
| 7 | POST | prompts/expand |
prompt_routes.expand_prompt |
死。前端只用 prompts/governance-preview |
| 8 | GET | profile-cards/{card_id} |
profile_card_routes.get_profile_card |
死 |
| 9 | DELETE | profiles/{profile_id}/wardrobe/{wardrobe_item_id} |
wardrobe_routes.delete_wardrobe_item |
死。legacy 别名,前端只用 /wardrobe/items/{id} |
| 10 | GET | materials/analytics |
material_routes.material_analytics |
死 |
| 11 | POST | materials/renormalize-batch |
material_routes.renormalize_materials_batch |
死 |
| 12 | POST | materials/{material_id}/renormalize |
material_routes.renormalize_material |
死 |
| 13 | GET | integrations/logs |
integration_routes.list_integration_logs |
死。前端只用 logs/integrations |
| 14 | POST | api-discovery/probe-model |
api_discovery_routes.probe_model |
死。前端只用 probe-provider |
GET media/fetch虽不在 endpoints.ts 中,但通过MediaService.sign_media()返回的签名 URL 被间接消费(round_routes.py:196、image_routes.py:229),不算死接口。它是全仓唯一声明auth_required: False的路由(route_registry.py:173)。
其中 #1 / #2 与 POST profiles/{id}/archive 三条路由指向同一个函数体:
# backend/routes/profile_routes.py:101-114
def delete_profile_via_post(ctx, profile_id, payload=None, service=None) -> dict:
return delete_profile(ctx, profile_id, service)
def archive_profile(ctx, profile_id, service=None) -> dict:
return delete_profile(ctx, profile_id, service)
注意:初审曾把这条列为「/archive 执行删除 → 用户意图被扭曲」的 P1 缺陷,经复核推翻——前端唯一调用方是一个文案为「删除」、样式为 danger-button、提示为「删除角色档案」的按钮(ProfileDetailPane.vue:190-198),用户意图与后端行为一致;profile 状态机里压根没有 archived 态。残留的只是 P3 级 REST 路径命名误导 + 三条等价入口冗余。若照初审建议把 /archive 改成真归档,反而会让当前的删除按钮不删除,引入功能回归。
表 ② 前端调用但后端不存在(会 404)
空表。 143 个 endpoints.ts 路径模板逐条与 route_registry.ROUTES 比对,全部命中,无一遗漏。
表 ③ 前端绕过 endpoints.ts 硬编码 URL
| 位置 | 内容 | 判定 |
|---|---|---|
frontend/standalone-web/vite.config.ts:11 |
base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/" |
真实重复,但静态资源 base 必须编译期确定,见 §2.4 |
frontend/shared/api/astrbot-page-bridge.ts:119-120 |
request<T>("api:get" ...) |
误报,是 postMessage 的 kind 常量,不是 HTTP 路径 |
[实测] grep -rn "\"/api/\|'/api/" frontend/standalone-web/src frontend/shared frontend/plugin-page/src 全树只有 1 处命中,就是 endpoints.ts:1 的 API_BASE 定义本身。App.vue 中 endpoints. 出现 183 次、覆盖 85 个不同端点;所有 getJson/postJson/putJson/deleteJson 的第一参数都来自 endpoints.*,buildUrl(client.ts:297-306)是唯一的 URL 构造点。
这一维度做得很干净,应当保持。 唯一的改进点是运行期化:后端已经通过 bootstrap.api_base 把 API_BASE 下发给前端了(ui_service.py:10 是后端侧单点),但前端拿到它之后的唯一用途是拼一句提示文案(App.vue:4330),实际请求路径始终来自编译期常量。建议 client.ts 的 buildUrl 改为优先使用运行期值(模块内 let runtimeApiBase = API_BASE,bootstrap 成功后 setApiBase(...)),vite base 保持编译期常量但加一条测试断言它以 endpoints.ts 的 API_BASE 开头。
2.2 业务逻辑重复实现(本节是前后端耦合的核心)
前端重写后端逻辑的位置对照。严重度一律以 _复核结论.md 的逐条判定为准:没有一条维持 P1 —— #1/#2 降为 P2,#3/#4/#5/#6 降为 P3,其中 #4/#5/#6 是被整条推翻后只保留残留技术债。
终审更正:本节初稿曾把 #1/#2/#3 标为"维持 P1",与复核结论不符,现已按复核给出的 P2/P2/P3 更正。这三条的耦合事实全部成立(代码、行号、可达性均经复核核实),降级的是影响判定,不是事实。它们依然是本报告推荐的解耦重点,只是不应按 P1 抢占安全与队列正确性的排期。
汇总表
| # | 前端位置 | 后端权威位置 | 严重度 | 已漂移的具体差异 |
|---|---|---|---|---|
| 1 | App.vue:5786-6076(generateQuickCharacterImages,291 行) |
backend/services/quick_character_consistency.py + 工作流状态机 |
P2(经复核降级) | 工作流终态由浏览器推断并 PUT;关标签页即产生僵尸工作流 |
| 2 | App.vue:10837-10859 + :927 |
workflow_progression_service.py:175-199 |
P2(经复核降级) | 四层完成判定规则被逐条复刻,含 legacy 兼容分支与版本号字面量 |
| 3 | workflow-lock-state.ts:8-27(sealed_at 在 :12) |
workflow_round_service.py:1145-1155 |
P3(经复核降级) | 少判 1 个真实条件(selected_image_id);多判 1 个后端零产出的字段 |
| 4 | App.vue:6126(quickCharacterPrompt 指令表) |
character_workflow_service.py:280-285 |
P3 (经复核降级) | 4 条短指令措辞已漂移;quick_avatar 丢了 keep identity consistent |
| 5 | workflow-model-route.ts:36-88 |
generation_service.py:169-176 / 617-624 / 2026-2038 |
P3 (经复核降级) | 候选链顺序与 node_key → assignment 映射表在前端各存一份 |
| 6 | App.vue:2786 / 3076 / 3139 |
route_registry.py:22-27 + core/security.py:31-33 |
P3 (经复核降级) | retry 卡片只判 can_retry_tasks,队列面板判了 canWrite && canRetry |
| 7 | App.vue:3285/3293/3628 + presentation.ts:5 |
queue_service.py:31-34 |
P2 | 4 处独立硬编码任务状态集合,第 4 份与后端任何常量都不完全相等 |
| 8 | App.vue:6927 + WorkflowCandidatePool.vue:132 + WorkflowRoundPanel.vue:113 + presentation.ts:11 |
后端状态码 | P2 | 4 张中文标签表,译法互相冲突 |
| 9 | model-route-chain.ts:27-39 |
core/model_route_chain.py:52-66 |
P2 | 同一线格式的两份独立实现,无跨语言一致性测试 |
| 10 | workflow-node-catalog.ts:23-32 + workflow-model-route.ts:61-74 |
engines/character_flow.py:15-20 |
P2 | 同一张 legacy 别名表三份,其中两份前端拷贝对 expression_sheet 映射不同 |
| 11 | client.ts:14 + astrbot-page-bridge.ts:6 |
无(后端不存在 900 秒预算) | P2 | 18 分支正则逐字符重复两份,且固化了一个虚构契约 |
#1 · [P2,经复核降级] 快速角色四联图:291 行工作流状态机跑在浏览器里
- 前端:
frontend/standalone-web/src/App.vue:5786-6076(generateQuickCharacterImages) - 后端权威:工作流状态推进本应由服务端负责;
backend/services/quick_character_consistency.py说明这一层后端本来就有
这个函数在浏览器里完成了:创建工作流 → 启动 → 提交锚点任务 → 并行提交 3 个从属任务 → 重新拉节点 → 自行推断工作流终态 → PUT 状态与 metadata → 失败时再 PUT status: "failed" 做补偿。
// App.vue:5945-5979 —— 前端判定工作流终态
const generationCompleted = completedTargetKeys.length === QUICK_CHARACTER_TARGET_SPECS.length
const nextWorkflowStatus = generationCompleted ? "completed" : pendingTargetKeys.length ? "running" : "failed"
...
if (normalizeStatus(workflow.status) !== nextWorkflowStatus) workflowUpdate.status = nextWorkflowStatus
workflow = await putJson<ProfileWorkflow>(endpoints.workflow(workflow.workflow_id), workflowUpdate)
// App.vue:6048-6061 —— 失败补偿也在前端
const failedWorkflow = await putJson<ProfileWorkflow>(endpoints.workflow(activeWorkflowId), {
status: "failed", metadata: { ...(latestFailedWorkflow.workflow.metadata ?? {}), quick_character_failure: message },
})
已漂移/已失效的具体后果:用户在生成过程中刷新页面或关标签页,工作流永久停留在 draft / running,没有任何服务端兜底把它推到终态——数据库里会累积僵尸工作流。复核逐条确认了这条兜底缺失:workflow_routes.py:79-84 的 start_workflow 只改状态不托管推进;唯一自动推终态的 _advance_character_gradual_progression(workflow_service.py:760-802)在 :766 被 workflow_type != "character_gradual" 排除,而快速角色流是 character_fast;recover_stale_tasks 是 task 级且只认 source="workflow_round";App.vue:5816 传 forceNew: true 使每次被中断的运行都新增一条 draft 记录,累积是真实的。
经复核降级为 P2 的理由(必须如实记录):初审附加的"metadata 契约完全由前端定义、后端被动接收"被推翻。
workflow_service.py:64-72定义了QUICK_CHARACTER_IMMUTABLE_METADATA_KEYS(quick_character_identity_managed/quick_character_batch_id/identity_lock_hash/identity_lock/quick_character_route_snapshot/quick_character_target/quick_character_targets),:1032-1042对character_fast强制回填服务端值,代码注释即Browser clients may PUT a stale whole metadata object after the four requests finish. Preserve server-owned batch identity and route fields once initialized so clients cannot clear or mutate the lock。anchor_image_id语义也由后端强校验(generation_service.py:1337-1347直接抛quick-character downstream generation requires the avatar image_id as an identity anchor,:1299-1329还校验引用图归属与 batch/lock 一致)。真正纯前端定义的只有quick_character_pending_target_keys/generated_target_keys/quick_character_schema等展示字段。综合:无数据丢失、无损坏、无鉴权问题;卡在
running不阻断后续生成,用户还可通过App.vue:8312的 start/cancel/archive 手动收尾。实际代价是工作流状态失真 + 僵尸记录累积,定为 P2。
收敛方案:新增 POST workflows/{id}/quick-character/run,后端负责锚点优先 + 并行提交 + 状态推进 + 失败补偿;前端只提交一次请求,然后按 workflowRoundIsActive 的模式轮询状态。前端残留部分收进 composables/useQuickCharacterGeneration.ts。
#2 · [P2,经复核降级] 顺序进度状态机复刻,且后端从不下发权威结果
- 前端:
App.vue:10837-10859(:10843是其中一行),版本号字面量在App.vue:927 - 后端权威:
backend/services/workflow_progression_service.py:175(函数定义)/:180-199(函数体)
后端 is_character_gradual_node_completed() 是"节点是否已完成"的唯一权威判定,包含 status 白名单、node_type 特例、profile_card 别名归一、legacy 元数据兼容四层规则:
# workflow_progression_service.py:180-199
if node.status in PROGRESSION_COMPLETED_NODE_STATUSES: # {"selected","skipped"}
return True
if node.status == "completed" and (
node.node_type in {"planning", "reference_binding"}
or canonical_gradual_node_key(node.node_key) == "profile_card"
):
return True
if allow_legacy_planning_metadata:
if node.node_key == "prompt_plan":
return "prompt_plan" in metadata and metadata.get("prompt_plan") is not None
if node.node_key == "material_bind":
return "material_bindings" in metadata and metadata.get("material_bindings") is not None
return False
前端逐条重写了这四层,连"legacy 兼容只对没有 sequential-v1 标记的工作流生效"这种极细的分支都手工复刻:
// App.vue:10843-10859
if (status === "selected" || status === "skipped") return true
if (status === "completed" && (backendNode.node_type === "planning" ||
backendNode.node_type === "reference_binding" ||
canonicalCharacterWorkflowNodeKey(backendNode.node_key) === "profile_card")) return true
const legacyProgression = isRecord(execution) && execution.progression_version !== CHARACTER_WORKFLOW_PROGRESSION_VERSION
if (!legacyProgression) return false
if (backendNode.node_key === "prompt_plan") return backendNode.metadata?.prompt_plan != null
if (backendNode.node_key === "material_bind") return backendNode.metadata?.material_bindings != null
根因:后端从不下发进度。node_routes.py:52-63 的列表接口只返回裸节点数组;全仓 progression.to_dict() 只有一个调用点——character_workflow_service.py:339(execute-character 的响应体),列表接口拿不到。
风险:后端改一条进度规则(给 style_lock 加完成条件、或让 skipped 不再算完成),前端不报错也不失效,只会静默地在"下一步该点哪个节点"上给出与服务端相反的答案:UI 显示节点可用 → 用户点击 → 后端 ensure_character_gradual_node_access 抛 character_gradual_progression_locked;反向则是 UI 灰掉一个后端允许的节点。
经复核降级为 P2 的理由:复核逐条核实了四项事实(两份实现、版本号字面量重复、
list_workflow_nodes无progression字段、progression.to_dict()唯一调用点在character_workflow_service.py:339),并进一步排除了"前端可改读元数据快照"这条反驳路径(character_execution_metadata()只在 execute-character 路径落库,节点逐个完成后必然过期)。根因成立、无守卫消解。 但降级理由是:ensure_character_gradual_node_access(workflow_progression_service.py:104-172)在服务端硬兜底强制抛character_gradual_progression_locked,前端偏差无法被用来绕过规则;且两份实现当前语义完全等价。因此这是"UI 与服务端可能不一致"的可维护性缺陷,不涉及越权或数据损坏,定为 P2。
收敛方案:
# backend/routes/node_routes.py —— list_workflow_nodes 返回体加 progression
def action() -> dict[str, Any]:
require_authenticated(ctx)
nodes = workflow_service.list_nodes(workflow_id)
workflow = workflow_service.get_workflow(workflow_id)
progression = character_gradual_progression(workflow, nodes)
return {
"items": [n.to_dict() for n in nodes],
"progression": progression.to_dict() if progression else None,
}
CharacterGradualProgression.to_dict() 已经现成(含 current_node_id / completed_node_ids / all_completed / import_confirmed)。前端删除 App.vue:10836-10861 与 :927,改为 progression.completed_node_ids.includes(node.node_id)。返回结构变更需同步 frontend/shared/types/workflow.ts 并升 contract_version。
#3 · [P3,经复核降级] 节点写锁规则不一致,且前端判据里有一个后端从不产出的字段
- 前端:
frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27(sealed_at在:12) - 后端权威:
backend/services/workflow_round_service.py:1145-1155
// workflow-lock-state.ts:8-27
export function isWorkflowSealed(workflowStatus, metadata) {
const status = normalizedStatus(workflowStatus)
return (
status === "archived" || status === "cancelled" ||
Boolean(metadata?.final_archive_history_id || metadata?.sealed_at) // ← :12 sealed_at
)
}
export function isWorkflowNodeWriteLocked(nodeStatus, workflowStatus, workflowMetadata) {
return normalizedStatus(nodeStatus) === "selected" || isWorkflowSealed(workflowStatus, workflowMetadata)
}
# workflow_round_service.py:1145-1155
if node.status == "selected" or node.selected_image_id or (
progression is not None and node.node_id in progression.completed_node_ids
):
raise ApiError(ErrorCode.VALIDATION_FAILED,
"confirmed workflow node is locked; create a branch before adding another round",
{"node_id": node.node_id, "required_action": "create_branch"})
可举证的分歧(已按复核结论修正):
- 真实且可达:
node.selected_image_id已设但status != "selected"时,前端认为可写并放行"再跑一轮",后端:1145返回VALIDATION_FAILED / required_action: create_branch。 触发路径是backend/services/image_service.py:150-159的select_image—— 它只写update_node(after.node_id, {"selected_image_id": after.image_id})而不改status,且:249-255的守卫明确放行completed(if node.status in LOCKED_NODE_STATUSES and node.status != "completed",注释自称这是 "tentative selection" 设计)。用户入口是GalleryPage.vue:121的批量"标记选中"按钮。⚠️ 初审引用的
adopt-image路径是错的,已删除。 复核实测backend/services/history_service.py:55一次性写入两个字段{"status": "selected", "selected_image_id": image.image_id},采用路径两边一致、不产生分歧;generation_service.py:473/955生成候选时写死"is_selected": False,正常轮次流程也不会凭空产生selected_image_id。 - 仅理论洞:
progression.completed_node_ids那一条对node_type == "generation"的节点实际只剩status in {"selected","skipped"}一种可能(planning / reference_binding / profile_card 与 legacy 分支都不适用于生成节点),因此额外差异仅是"skipped",而 UI 未提供把生成节点置为 skipped 的入口。 metadata.sealed_at是永远为undefined的死判据。[实测]grep -rn "sealed_at" --include=*.py(排除.tmp/、release/)返回 0 命中——它只存在于前端与前端测试里,给读代码的人制造"存在这个封存机制"的错觉。但它是 OR 链里的恒 undefined 项,只可能"多加锁"不可能"漏加锁",行为上无副作用,属代码卫生问题。
经复核降级为 P3 的理由:分歧客观存在且路径 1 可达,但 (a) 可达路径窄(需走图库批量标记选中);(b) "用户看到无法自恢复的报错"不成立 —— App.vue:7788-7795 的 actionableWorkflowApiError 会读 err.details.required_action,:7783 已有映射 create_branch: "当前节点已锁定或工作流已封存,请先创建可编辑分支",用户拿到的是带明确恢复指引的中文提示,且 WorkflowBranchPanel 提供建分支入口;(c) 方向上前端偏宽松、后端为权威判定,属 fail-safe,不涉及数据损坏、越权或状态不一致落库。
收敛方案:把锁状态改为服务端下发而非客户端推导。最小改动是给 WorkflowNode.to_dict() 增加 writable: bool 与 lock_reason: str | None——WorkflowNodeMaterialBindingDetail 已经有 writable + lock 结构可直接复用同一形状(frontend/shared/types/workflow.ts:108-123);前端 workflow-lock-state.ts 退化为读 node.writable。若暂不改协议,至少立刻做两件事:删掉 sealed_at、把 isWorkflowNodeWriteLocked 的签名扩成接收整个 backend node 并加上 Boolean(node.selected_image_id)。
#4 · [P3,经复核降级] 快速角色提示词指令表在前后端各写一份
- 前端:
App.vue:6126(instructions表)、:6100-6118(quickCharacterIdentityFields) - 后端权威:
character_workflow_service.py:280-285(_step_instruction的fast表)
// App.vue:6126
quick_avatar: "square avatar, close-up portrait, clear face, stable hair and eye details",
# character_workflow_service.py:280
"quick_avatar": "square avatar, face, hair, eyes, expression, keep identity consistent",
已漂移的具体差异:4 条短指令措辞不同;前端 quick_avatar 丢掉了后端写的 keep identity consistent。
经复核降级的理由(必须如实记录):初审把这条定为 P1,声称"身份一致性不可复现 / prompt 治理被绕过"。复核逐条推翻:
- 前端
quickCharacterIdentityFields()产出的是原始字段值,作为identity_fields上传,这正是后端build_identity_lock()(quick_character_consistency.py:56-68)明文定义的输入契约——别名归一、_normalize_gender/_normalize_age_group、canonical 字段集、锁文案与identity_lock_hash全部仍在后端,前端没有复制任何一张别名表。 generation_service.py:691对每个 quick-character 节点无条件套用服务端身份锁,代码注释明写此意图(Direct mode intentionally bypasses LLM rewriting, but it must never bypass the immutable server-owned character identity lock.);锁文案强度比前端那句高一个数量级,且identity_lock_hash()对 canonical JSON 做 sha256,一致性是确定性可复现的。_govern_prompt()(:1456)显式读取前端串做审核与路由裁决,route.allowed为假时抛VALIDATION_FAILED阻断——治理照常作用于前端串。
残留真实问题:4 条短指令字符串在前后端各写一份、措辞已漂移的 DRY 瑕疵。
收敛方案:删除 App.vue:6126 的 instructions 表与身份约束前缀,只把结构化字段(identityFields、materialPrompts、用户 patch)作为 payload 传给 endpoints.nodeGenerate,由后端 _step_instruction() + build_identity_lock() 组装。若前端确实需要预览,新增一个只读的 POST prompts/preview 端点返回后端组装结果。
#5 · [P3,经复核降级] 模型路由解析链在前端重实现
- 前端:
frontend/standalone-web/src/features/workflow/workflow-model-route.ts:33-88+App.vue:2211-2245 - 后端权威:
generation_service.py:169-176(普通节点)、:617-624(快速角色,优先级反转)、:2026-2038(node_key → assignment映射)
# generation_service.py:169-176 —— 普通节点
requested_model_route = str(payload.get("model_route") or node.model_route or assigned_route
or profile_model_route or self.default_model_route or "image_low")
# :617-624 —— 快速角色:assigned_route 抢在 payload.model_route 之前
if quick_character:
route_candidate = str(assigned_route or payload.get("model_route")
or profile_model_route or self.default_model_route or "image_low")
// workflow-model-route.ts:36-48 —— 单链,多了 round 层,无 image_low 兜底,无 quick_character 分支
const candidates = [["override", input.overrideRoute], ["round", input.roundRoute],
["node", input.nodeRoute], ["assignment", input.assignmentRoute],
["profile", input.profileRoute], ["system", input.systemRoute]]
经复核降级的理由:初审定 P1,声称"快速角色流模型标签会说谎"。复核逐条推翻:
- "前端多了 round 层"是错的——
workflow_round_service.py:596-597确实有本次覆盖 → 父轮次冻结路由这一层,前端是如实镜像。 - "少了 image_low 兜底"是刻意设计——
workflow-model-route.ts:28-31注释明写Mirrors the server-owned route chain without inventing a frontend default.,返回空值被上游当硬闸门用(App.vue:8492-8495直接拒绝提交并给出文案)。硬编码image_low反而会让 UI 声称一个后端可能拒绝的路由。 - "快速角色标签说谎"不可达——该标签链的输入来自
selectedWorkflowBackendNode,其workflowId字段四处赋值全部只可能是character_gradual(App.vue:4943-4954 / 7410-7419 / 9455 / 9489),quick_*节点永远不会成为selectedWorkflowBackendNode。快速角色流有自己独立且正确的解析器(App.vue:6086-6098,与后端quick_generation映射完全对齐,为空时直接throw阻断提交)。 - 实际可达路径下前后端结论完全一致:gradual 的 7 个生图节点键在前端
:76-84与后端:2026-2033逐条相同。
残留真实问题:前端存在一份重复的映射表 + 前端直接读取配置文件原始结构(currentSettings.value.config.model_assignments、config.generation.default_model,App.vue:2218/2231-2233)——后端改配置键名前端静默失准。这是可维护性耦合,不是运行期缺陷。
收敛方案:由 generation_service 抽出纯函数 resolve_model_route(node, workflow, profile, assignments, default),同时供生成路径与新端点使用;在 nodeDependencyContext 响应里加 { effective_model_route, source }。前端 resolveWorkflowModelRoute 只保留"用户 override 是否非空"的判断,删除 workflow-model-route.ts:61-84 的私有别名/分配表。
#6 · [P3,经复核降级] retry 卡片的权限门禁写法不一致
- 前端:
App.vue:2786(const canRetry = Boolean(permissions?.can_retry_tasks))+:3076+:3139 - 后端权威:
route_registry.py:22-27("required_permissions": ["can_write", "can_retry_tasks"])+core/security.py:31-33(require_task_retry先require_write再require_permission)
同文件 :3373 的队列面板反而写成了 const canManageQueue = canWrite && canRetry。
经复核降级的理由:初审定 P1「持有 can_retry_tasks 但无 can_write 的账号会看到可用按钮」。复核证明该权限组合在本仓库造不出来:
main.py:104-106+:2337:BRIDGE_PERMISSIONS = frozenset({"can_write","can_manage_config","can_manage_materials","can_retry_tasks"}),permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()——要么四个全给,要么一个不给;chat_workflow_service.py:1160:{"can_write","can_retry_tasks","can_manage_materials"},同样含can_write;chat_command_guard_service.py:42:空集。
且即便该组合存在,点击路径也有上游守卫:App.vue:8560 的 backendWriteBlockMessage(...) 里明确含 if (!bootstrap.value?.permissions.can_write) return ...,本地就拦下,根本不会发出请求。另外 App.vue:3818-3821 也是同样的 canRetry-only 写法,说明这是节点级卡片的一贯约定(写权限统一由 backendWriteBlockMessage 兜底),而 :3373 队列面板加 canWrite 是因为队列卡片直接调接口、没有同样的兜底函数——两类不同上下文。
残留真实问题:UI 文案精确性——:3073-3074 的 canRetry ? "可重试" : "无权限" 在一个当前造不出的权限组合下会显示乐观文案。无安全影响、无越权、无功能故障。
收敛方案(依然值得做,因为它顺带解决整类问题):不要在前端逐个手写权限组合。GET contract 返回的 routes[].required_permissions 已经是完整数组:
const contractRoutes = new Map(contract.routes.map(r => [`${r.method} ${r.endpoint}`, r.required_permissions]))
function canCall(method: string, endpoint: string) {
return (contractRoutes.get(`${method} ${endpoint}`) ?? []).every(p => permissions?.[p])
}
所有按钮的 enabled 统一走 canCall(),权限矩阵从此不需要在前端复写。
#7 · [P2] 队列状态枚举 4 处独立硬编码
# backend/services/queue_service.py:31-34 —— 后端唯一真相
RETRYABLE_TASK_STATUSES = {"failed", "dead_letter", "cancelled"}
FAILED_TASK_STATUSES = ("failed", "dead_letter", "cancelled")
COMPLETED_TASK_STATUSES = ("completed", "succeeded", "superseded")
DELETABLE_TASK_STATUSES = frozenset((*FAILED_TASK_STATUSES, *COMPLETED_TASK_STATUSES))
前端四份拷贝:App.vue:3285(failed 集)、App.vue:3293(completed 集)、App.vue:3628(第五次内联 ["failed","dead_letter","cancelled"])、frontend/shared/utils/presentation.ts:5:
// presentation.ts:5 —— 与后端任何一个常量都不完全相等
const TERMINAL_JOB_STATUSES = new Set(["completed","succeeded","failed","cancelled","dead_letter","superseded"])
风险:TASK_STATUSES(queue_service.py:18-29)新增一个终态(例如 expired)时,后端会正确算进 DELETABLE,而前端四处判定全部漏掉:任务永远停在"运行中"分组、waitTime() 里 terminal 为 false 导致耗时读数无限增长、"清理终态任务"按钮的计数与后端实际清理数量对不上。
收敛方案:把四个集合加进 GET ui/bootstrap 返回体(UiService.get_bootstrap 已经在下发 permissions 和 feature_flags,加 task_statuses: {retryable, failed, completed, terminal} 是同性质元数据),前端建 taskStatusSets.ts 从 bootstrap 初始化。退一步至少合并成 frontend/shared/config/task-status.ts 一份,并加一条正则测试断言它与 queue_service.py 的字面量一致。
#8 · [P2] 生成状态中文标签 4 张表,译法互相冲突
| 位置 | planned |
succeeded |
retrying |
dead_letter |
|---|---|---|---|---|
App.vue:6927-6939 |
已规划 | 已成功 | 缺失(显示英文原文) | 缺失 |
WorkflowCandidatePool.vue:132-145 |
待入队 | 已完成 | 重试中 | 重试耗尽 |
WorkflowRoundPanel.vue:113-129 |
— | — | — | — |
presentation.ts:11-29 |
— | 已成功 | 重试执行中 | 死信 |
同一个候选在候选池里显示「已完成」,在 App.vue 其它视图里显示「已成功」;planned 有「待入队」和「已规划」两种说法;重试中的候选在 App.vue 直接显示英文 retrying。
收敛方案:frontend/shared/utils/presentation.ts 增加 export function generationStatusLabel(status: string) 作唯一真源,覆盖 planned|queued|running|retrying|succeeded|success|completed|failed|dead_letter|cancelled|superseded,删掉三份局部表;轮次级状态(partial_success|all_failed|confirmed)另建 roundStatusLabel 一并放入。
#9 · [P2] route-chain: 线格式编解码器被逐字移植到 TS
这不是"逻辑重复",而是同一个序列化格式的两份独立实现——前端写出的字符串要被后端解析。
# core/model_route_chain.py:61-66
return ROUTE_CHAIN_PREFIX + json.dumps({"plugin": plugin_route, "astrbot": astrbot_route},
ensure_ascii=False, separators=(",", ":"), sort_keys=True)
// frontend/standalone-web/src/features/settings/model-route-chain.ts:33
return `${MODEL_ROUTE_CHAIN_PREFIX}${JSON.stringify({ astrbot, plugin })}`
目前能对上,靠三个巧合同时成立:Python sort_keys=True 产出 astrbot 在前 ≡ TS 对象字面量恰好写成 { astrbot, plugin } 的插入顺序;separators=(",", ":") ≡ JSON.stringify 默认无空格;ensure_ascii=False ≡ JSON.stringify 默认不转义非 ASCII。
风险:把 TS 那行改成 JSON.stringify({ plugin, astrbot })(更符合语义直觉)就会产出不同字节序列。Python 端 json.loads 仍解析成功,不会立刻报错,但任何做字符串比较的地方(配置 diff、快照对比、settings/diff)会把"没变的配置"报成"变了"。现有 tests/test_model_route_chain.py 只验 Python 内部往返,没有一条测试断言两语言的编码结果相同。
收敛方案:加黄金样本测试固定线格式——Python 侧断言 encode_model_route_chain("p","astrbot:a") == 'route-chain:{"astrbot":"astrbot:a","plugin":"p"}',TS 侧用同一字符串断言 encodeModelRouteChain({plugin:"p",astrbot:"astrbot:a"}),并加反向 parse 用例。更彻底的做法是别让前端编码:让 settings 保存接口接受 {plugin, astrbot} 结构体、由后端编码。
#10 · [P2] legacy 节点别名表三份,两份前端拷贝互相冲突
# engines/character_flow.py:15-20
LEGACY_CHARACTER_GRADUAL_NODE_KEYS = {
"half_body": "upper_body", "expression_sheet": "turnaround", # ← turnaround
"pose_sheet": "design_sheet", "final_pack": "profile_card"}
// workflow-node-catalog.ts:23-28 —— 与后端一致
expression_sheet: "turnaround",
// workflow-model-route.ts:61-74 —— 同一前端目录下的第三份,映射不同
expression_sheet: "design_sheet", // ← 与另两处冲突
另外 11 个节点的 node_key 与展示文案在 engines/character_flow.py:22-115(CHARACTER_GRADUAL_STEPS)和 workflow-node-catalog.ts:64-153 各存一份,中文标题也不同(后端"拆解人设/预选素材" vs 前端"LLM 拆解设定/参考素材绑定")。
风险:expression_sheet 的冲突目前不产生可见 bug(turnaround 与 design_sheet 恰好都映射到 sheet_generation),这是巧合不是设计。真正的风险是:character_flow.py 加一个新节点或改一个别名,前端两份表都不会更新,workflowUiNodeIdForNodeKey 返回 undefined,该节点在工作流面板直接不显示——用户看到的步骤列表比后端实际创建的节点少一个。
收敛方案:ui/bootstrap 或新增 GET workflows/node-catalog 下发 gradual_node_templates() + LEGACY_CHARACTER_GRADUAL_NODE_KEYS(后端已有 gradual_node_templates(),character_flow.py:131-145,几乎可以直接返回)。前端 workflow-node-catalog.ts 只保留纯展示增强(badge/phase/detail),键与别名从接口取;删除 workflow-model-route.ts:61-74 的私有表。
#11 · [P2] LONG_TASK_ENDPOINT 正则重复两份,且固化了一个虚构契约
// client.ts:14 与 astrbot-page-bridge.ts:6 —— 逐字符相同的两份
const LONG_TASK_ENDPOINT = /(?:^|\/)(?:generate|retry|review|execute-character|expand|governance-preview|probe-provider|probe-model|recognize|re-recognize|renormalize|renormalize-batch|import-pack|migrate|restore)(?:\/|$)/
frontend/shared/config/timeouts.ts 声明 LONG_TASK_TIMEOUT_SECONDS = 900,而后端 grep -rn "\b900\b" --include=*.py(排除 tests/release/.tmp)只有一处命中且与生成无关(advanced_style_set_service.py:57 的 STYLE_VALIDATION_TIMEOUT_SECONDS)。生成任务的真实预算是 180 秒(generation_service.py:2308;config.yaml:25/42)。
号称守护一致性的测试只读前端文件:
// frontend/tests/task-timeout-consistency.test.mjs:11-25
test("uses the backend 900 second task budget throughout the plugin bridge UI", async () => {
const [timeouts, client, bridge, app] = await Promise.all([...]) // ← 四个文件全在 frontend/
assert.match(timeouts, /LONG_TASK_TIMEOUT_SECONDS = 900/)
三条具体后果:(1) 正则里 probe-model、renormalize、renormalize-batch、import-pack 对应的端点前端根本不调用(见表 ①),这份列表已与实际调用面脱节;(2) 测试名字断言"后端 900 秒预算"但没读过任何后端文件——它固化的是一个虚构契约;(3) 新增慢端点(例如实际走 900 秒样式校验的 advanced-material-imports/{id}/style-consensus)不在正则里,客户端 30 秒就超时报错而后端任务还在跑。
收敛方案:正则提到 timeouts.ts 一份,两个 transport 共同 import。更好的做法是后端在 ui/bootstrap 下发 { long_task_endpoint_patterns: [...], long_task_timeout_seconds: N },N 取 config.generation.provider.timeout_seconds 的上界;测试改为读 config.yaml / generation_service.py 与前端常量做真实比对。
表外补充:一条"后端做完、前端未接"的完整功能链
images/{id}/moderation-review + include_restricted 是后端为"内容审核隔离图片"实现的完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点(image_routes.py:41-49 / 68-73 / 90-91 / 145-160,image_service.py:135-143 会真实改写可见性)。前端一个都没接:grep -rn "include_restricted\|restricted_hidden\|quarantined\|gallery_visibility" frontend/ 全树零命中;frontend/shared/types/image.ts:28-33 的 ImageListResult 也没有 restricted_hidden 字段。
后果:generation_service.py:491/968 会把审核不通过的图打上 gallery_visibility: "restricted"。这些图对所有人(含管理员)不可见、不可复核、不可解除——UI 既不显示"有 N 张被隐藏",也没有任何 approve 入口。用户视角是"生成成功了但图库里没有",没有任何解释。 这是耦合缺口在生产中直接表现为数据丢失的一例(P2)。
修复:图库页加"显示受限图片"开关(仅 can_manage_materials 可见)→ 传 include_restricted=true;列表底部读 restricted_hidden;受限图详情弹窗加 approve/reject;ImageListResult 补 restricted_hidden?: number。
2.3 类型契约漂移:frontend/shared/types/*.ts vs backend/dto/*.py
2.3.1 一个让所有联合类型失效的写法
// frontend/shared/types/advanced-material.ts:168
status: AdvancedMaterialImportStatus | string
TypeScript 会把 "a" | "b" | string 折叠成 string,联合类型完全不产生任何类型检查。同样的写法出现在 AdvancedStyleSource.status、AdvancedStyleValidationCase.status、AdvancedMaterial.status、workflow-round.ts:73/112(round_kind、preference_status)等十余处。这是本节所有漂移能长期不被发现的技术原因。
2.3.2 字段级差异表
| 类型 | 方向 | 差异 | 后端真源 |
|---|---|---|---|
AdvancedMaterialImportStatusadvanced-material.ts:1-18 |
前端缺 6 个 | recognizing_style_sources、style_consensus_failed、style_consensus_queued、style_consensus_running、style_source_recognition_queued、style_source_review_required(整个 style-set 流程的状态一个没有) |
advanced_style_set_service.py:384/527/539/787/1366 等处的 update_import(..., {"status": ...}) |
| 同上 | 前端多 2 个幽灵值 | pending_validation、pending_review——grep -rn '"pending_validation"' --include=*.py backend/ database/ → 0 命中 |
后端根本不产出 |
AdvancedStyleSource |
DTO 无此字段 | excluded、filename、image_uri、thumbnail_uri、retry_count |
实际来自 advanced_style_set_service.py:409/414 手工构造的 dict |
AdvancedStyleValidationCase |
DTO 无此字段 | scenario、title、style_prompt、style_scores、rendering_layers、content_novelty |
advanced_style_set_service.py:2330/2354/3345/3422 |
AdvancedMaterialImport |
DTO 无此字段 | task_id、workflow_kind、sources、consensus、validation_cases |
advanced_style_set_service.py:389/1152 |
AdvancedStyleConsensus |
整个接口无对应 DTO | AdvancedStyleConsensusRun 的字段名完全不同(consensus_style/version_id/variable_style_features 都不在 DTO 里) |
advanced_style_set_service.py:1723 |
| 反向 | DTO 输出但 TS 未声明 | idempotency_key(import)、recognition_model_route/provider_id/provider_model(style source)、width/height/completed_at(validation case) |
— |
CharacterProfileprofile.ts:3-21 |
TS 缺 4 个 owner 字段 | owner_platform、owner_context_id、owner_user_id、owner_session_key |
backend/dto/profile_dto.py:42-45 |
CharacterProfile.generation_kind |
TS 多 1 个死枚举 | "profile_card"——SQL CASE 只可能产出 detailed/quick/ungenerated |
database/repositories/profile_repository.py:32-56 |
WorkflowRoundNextRequest.countworkflow-round.ts:48-52 |
TS 比后端窄 | TS 写死 4 | 5;后端 maximum = 8 if round_kind == "cross_review" else 5 |
workflow_round_service.py:1159-1171 |
ImageListResultimage.ts:28-33 |
TS 缺字段 | restricted_hidden |
image_routes.py:41-49 |
WorkflowGenerationCandidate / WorkflowRoundCandidatePoolEntry / CharacterProfile 的字面量联合 |
无漂移 | 15 / 11 个字段逐条核对全部精确对应 | 说明人工纪律目前还撑得住,但没有任何机制保证 |
2.3.3 根因:backend/dto/ 对进阶素材已经名存实亡
路由层的序列化只补签名 URL,不加业务字段:
# backend/routes/advanced_material_routes.py:387-392
def _serialize_style_source(payload: dict[str, Any]) -> dict[str, Any]:
return {**payload,
"source_image_url": _signed_url(payload.get("source_image_uri")),
"source_thumbnail_url": _signed_url(payload.get("source_thumbnail_uri"))}
响应形状实际由散落在 4,491 行 advanced_style_set_service.py 各处的 dict 字面量决定。想知道接口返回什么,只能全文搜索;改动时没有任何单点可以对照。 这也是状态枚举漂移的同一个根因。
2.3.4 收敛方案
- 去掉
| string,改为status: AdvancedMaterialImportStatus,让联合类型真正生效;确需容忍未知值的地方在解析边界处显式收窄。 - 为 style-set 流程补 DTO(
AdvancedStyleSourceView、AdvancedStyleValidationCaseView、AdvancedStyleConsensusView),让 service 返回 DTO 实例而非裸 dict,路由层只调to_dict()+ 加签名 URL。这样"接口返回什么"重新有唯一定义点。 - 状态集合从后端生成而非手抄:把各
*_STATUSES常量集中到一个 Python 模块,加生成脚本产出frontend/shared/types/generated-enums.ts,CI 校验git diff --exit-code。 - DTO 与 TS 字段做一次对齐——不需要的字段就从
to_dict()里删,别只在 TS 侧省略;删掉generation_kind里的"profile_card";count改为number并由后端在round.metadata下发allowed_count_range: [min, max]。
2.4 构建产物入库:取舍分析
事实
| 项 | 数据 |
|---|---|
| 提交进 git 的 dist 目录 | web/(standalone-web 产物)、pages/imagestudio/(plugin-page 产物) |
git ls-files web/ pages/ |
38 个文件,各约 1.1 MB |
git log --oneline -- web/assets |
80 次提交 |
.git 体积 |
51 MB(其中 git count-objects -vH 的 size-pack 44.03 MiB) |
.gitignore:16 |
只忽略 frontend/**/dist/,未忽略这两个输出目录 |
| 两个 vite 配置 | standalone-web/vite.config.ts:11-15(base: "/api/v1/.../web/",outDir: ../../web,emptyOutDir: true);plugin-page/vite.config.ts:11-15(base: "./",outDir: ../../pages/imagestudio) |
取舍:不能简单删
初审给出的建议是「.gitignore 加 /web/ 与 /pages/imagestudio/,git rm -r --cached」。这条建议经复核被推翻,照做会导致插件页面全线不可用。
- 这两个目录是文档明确定义的发布负载。
INSTALL.md的"最小运行时清单"把pages/imagestudio/和web/与main.py、metadata.yaml并列列为安装后必需内容;"发布包白名单"章节要求正式 ZIP 归档pages/和web/。ImageStudio 是 AstrBot 插件(metadata.yaml: astrbot_version: ">=4.25.0,<5"),装机路径是把仓库/ZIP 铺到data/plugins/astrbot_plugin_imagestudio/,安装期没有任何 npm/vite 步骤。产物一旦不在仓库,WebHostingService._resolve直接抛ErrorCode.RESOURCE_NOT_FOUND, "web asset not built"。 - "两份重复 dist"这个指控不成立。 两份构建的
base不同且必须不同:web/index.html里是绝对路径/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/assets/...,pages/imagestudio/index.html里是相对路径./assets/...。两者挂载于不同 URL 根(PLUGIN_PAGE_URL = "/plugin/imagestudio"vsSTANDALONE_WEB_URL = "/api/v1/..."),一份产物物理上无法同时服务两个挂载点。plugin-page/src/App.vue全文只有一行import WorkbenchApp from "../../standalone-web/src/App.vue"——源码层面已经没有重复,重复的只是两份必需的编译输出。 - "2MB 噪音淹没 diff"与实测不符。 最近几次 dist 提交的实际 stat 是
24 files changed, 59 insertions(+), 69 deletions(-)(878f1f6)、24 files changed, 37 insertions(+), 27 deletions(-)(2dbf90b)——git 的重命名检测把内容哈希改名识别成web/assets/{index-A.js => index-B.js},压缩产物是单行文件,每次只有几十行 diff。 - 仓库体积的主因不是 dist。
git ls-files release/有 20 个 ZIP、仅当前树就占 37.0 MiB。想瘦身应该先动release/,不是web/assets。
残留的真实问题与替代方案
真实问题只有一条:没有任何机制保证产物与源码同步。 WebHostingService.manifest() 只检查 index.html 是否存在(web_hosting_service.py:33/38)就报告 built: true,无法发现版本错位;仓库根本没有 .github/workflows;git 历史里有 24 次只更新 web/assets、3 次只更新 pages/imagestudio/assets 的提交。
替代方案(按推荐度):
- 加一条构建新鲜度校验(推荐,改动最小):
这一条同时解决"漏跑一次构建"和"产物与源码错位"两个问题,且不改变发布模型。# CI 步骤:产物必须是当前源码的构建结果 - run: cd frontend && npm ci && npm run build # 已有 "build": "build:plugin && build:web" - run: git diff --exit-code web pages/imagestudio manifest()增加build_hash(构建时注入),与metadata.yaml版本比对,让版本错位在运行时可观测而不是靠用户报障。release/的 20 个 ZIP 迁出主干——改用 git tag + release artifact 承载。这是真正能压缩.git的动作(37 MiB / 44 MiB)。- 不要把
web/与pages/imagestudio/加进.gitignore。若将来 AstrBot 支持安装期构建,再重新评估。
2.5 契约自检能力评估与自动化契约测试方案
2.5.1 现状:数据齐了,没人用
# backend/services/contract_service.py:13-30 —— 数据已经很全
return {
"contract_version": "3.0",
"api_base": API_BASE,
"routes": route_manifest(), # 166 条:method / endpoint / handler / permission / required_permissions
"permissions": permission_matrix(),
"error_codes": [code.value for code in ErrorCode],
"response_shape": {...},
}
唯一消费点是设置页的诊断框:
// SystemManagementPanel.vue:8 —— 拉下来直接 JSON.stringify 塞进 <pre>
const [contract,actions,manifest]=await Promise.all([
getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
result.value={contract,actions,manifest}
route_registry.py:365-377 已经写好了两个自检函数 assert_unique_routes() / assert_known_permissions(),无人调用。api_discovery_routes.py 提供的是外部 provider 探测(probe-provider / probe-model),与内部契约自检无关——注意 probe-model 本身就在表 ① 的死接口里。
能力评估:契约发布能力已具备且质量不错(路由 + 权限 + 错误码 + 响应信封);契约校验能力为零。缺的一环是"发布出来的东西没有任何一方去比对"。本报告 §2.1 的 14 条死接口、§2.2 的 11 条重复实现、§2.3 的字段级漂移,全部是人工比对才发现的,每一条都本可以由 CI 自动发现。
contract 目前不发布请求/响应 schema——这是它无法覆盖 §2.3 类型漂移的原因。
2.5.2 自动化契约测试方案(三层,按实施顺序)
第一层:后端自检(0.5 天,立刻能做)
# tests/test_route_contract.py
import importlib
from backend.route_registry import ROUTES, assert_unique_routes, assert_known_permissions
def test_route_manifest_is_wellformed():
assert_unique_routes()
assert_known_permissions()
for route in ROUTES:
mod, _, fn = route.handler.rpartition(".")
assert hasattr(importlib.import_module(mod), fn), route.handler
审计过程中已实测:166 条 handler 全部可导入,这条测试当前会通过——它是纯回归护栏,零迁移成本。
第二层:跨语言路由比对(1 天)
// frontend/tests/api-contract.test.mjs
import { readFile } from "node:fs/promises"
import test from "node:test"
import assert from "node:assert/strict"
// 已知未接入的后端路由;新增一条必须在此显式登记,否则测试失败
const KNOWN_UNUSED = new Set([
"DELETE profiles/{}", "POST profiles/{}/delete", "POST images/{}/moderation-review",
"POST advanced-material-imports/{}/cancel", "POST nodes/{}/mark-completed",
"POST nodes/{}/select-image", "POST prompts/expand", "GET profile-cards/{}",
"DELETE profiles/{}/wardrobe/{}", "GET materials/analytics",
"POST materials/renormalize-batch", "POST materials/{}/renormalize",
"GET integrations/logs", "POST api-discovery/probe-model",
])
const norm = (s) => s.replace(/\$\{[^}]*\}/g, "{}").replace(/\{[^}]*\}/g, "{}")
test("endpoints.ts ⊆ route_registry.ROUTES", async () => {
const registry = await readFile("../backend/route_registry.py", "utf8")
const backend = new Set([...registry.matchAll(/RouteSpec\(\s*"(\w+)",\s*"([^"]+)"/g)]
.map(([, m, p]) => `${m} ${norm(p)}`))
const endpoints = await readFile("./shared/api/endpoints.ts", "utf8")
const frontend = new Set([...endpoints.matchAll(/`([^`]+)`/g)].map(([, p]) => norm(p)))
// 1) 前端调用的每条路径都必须在后端存在 —— 阻止表 ② 出现
for (const path of frontend) {
assert.ok([...backend].some((b) => b.endsWith(` ${path}`)), `endpoints.ts 引用了后端不存在的路径: ${path}`)
}
// 2) 后端新增的未使用路由必须显式登记 —— 逼作者要么接上要么删掉
const unused = [...backend].filter((b) => ![...frontend].some((f) => b.endsWith(` ${f}`)))
assert.deepEqual(unused.filter((u) => !KNOWN_UNUSED.has(u)), [],
"新增了前端未接入的后端路由;请接入或加进 KNOWN_UNUSED")
})
第三层:字段级 DTO 契约(2-3 天,需先修 §2.3.3)
// frontend/tests/dto-contract.test.mjs
// 读 backend/dto/*.py 每个 to_dict() 的字面量 key 集合,
// 与 frontend/shared/types/*.ts 对应 interface 的字段名集合做双向差集断言。
// 正则提取即可,不需要真正解析 AST。
前提:先把 §2.3.3 做掉(让 DTO 重新成为响应真相来源)。DTO 都是 frozen dataclass,dataclasses.fields() 可以自动生成字段清单,因此第三层也可以做成"后端导出 schema → CI 比对 TS"的生成式方案,比正则更稳。
第四层(可选):权限门禁统一
前端所有按钮的 enabled 统一走 §2.2#6 的 canCall(method, endpoint),输入直接来自 contract 的 required_permissions——权限矩阵从此不需要在前端复写,§2.2#6 这类问题从根上消失。
投入产出:第一层 + 第二层合计约 1.5 天,能自动拦住表 ①/表 ② 类漂移与权限矩阵不一致;第三层再覆盖 §2.3 全部字段级漂移。这是整份耦合报告里性价比最高的一项投入。
第三部分 · 解耦路线
严重度口径:P0-致命 / P1-严重 / P2-中等 / P3-轻微。风险栏描述的是改动本身的风险。
立刻能做(本周内,单个 PR 可完成,风险 ≤ 低)
| # | 动作 | 位置 | 收益 | 风险 |
|---|---|---|---|---|
| 1 | 4 处工厂补 event_bus=get_default_event_bus();WorkflowService.event_bus 默认值改为 get_default_event_bus() |
node_material_routes.py:69、branch_routes.py:62、history_routes.py:72、review_routes.py:90 |
修复两例已确认的事件静默丢失(复核定级 P3:事件当前零订阅者,用户可见影响仅为 3 个导航页的自动刷新延迟)。真正价值是堵住装配分散的复制路径。改动 <20 行 | 极低。补一条断言 event_bus is not None 的测试即可 |
| 2 | generation_service.py:1416-1427 改用 self._publish(...),删除 self.workflow_service.event_bus 穿透 |
generation_service.py:1416-1427 |
消除同类风险的第二个来源(P3,与 #1 同源) | 极低 |
| 3 | 删掉 workflow-lock-state.ts:12 的 sealed_at 判据,补上 selected_image_id |
workflow-lock-state.ts:8-27 |
消除一个后端零产出的死判据 + 补齐一条真实锁条件(§2.2 #3,复核定级 P3) | 低。需同步更新前端测试 |
| 4 | 加 tests/test_route_contract.py(§2.5 第一层) |
新文件,约 12 行 | 166 条 handler 可导入 + 路由唯一性 + 权限合法性的永久护栏 | 零。实测当前即通过 |
| 5 | 删除 generation_service.py:1493/1506 的冗余函数内 import |
同左 | 消除误导性的"循环依赖"信号 | 零 |
| 6 | 4 张中文状态标签表合并为 presentation.ts 的 generationStatusLabel() |
App.vue:6927、WorkflowCandidatePool.vue:132、WorkflowRoundPanel.vue:113、presentation.ts:11 |
消除同一状态三种译法 + 补齐 retrying/dead_letter(P2) |
低。纯展示层 |
| 7 | LONG_TASK_ENDPOINT 正则提到 timeouts.ts 一份 |
client.ts:14、astrbot-page-bridge.ts:6 |
消除逐字符重复(P2) | 零 |
| 8 | 加 route-chain: 线格式黄金样本测试(Python + TS 各一条,断言同一字符串) |
tests/test_model_route_chain.py + frontend/tests/ |
锁死跨语言序列化格式(P2) | 零 |
| 9 | 删除死组件 WorkflowDependencyContextCard.vue(279 行,全仓零引用) |
同左 | 减少 279 行 + 加快 vue-tsc |
低。需确认 App.vue 内联版已完全覆盖 |
一个迭代内(2-4 周)
| # | 动作 | 收益 | 风险 |
|---|---|---|---|
| 10 | 建 backend/composition.py 组合根,分 4 步迁移(见 §1.4.4):先迁 WorkflowService 一族 → 迁 _create_generation_service → 抽 build_governance_bundle → 迁剩余工厂 |
一次性消除 service→route、route↔route 两条环;34 处磁盘 YAML 解析降到按 mtime 缓存;node_routes 扇出 31→个位数;route 平均扇出 12→3-4;两例事件丢失不可复发 |
中。触及 20 个 route 模块。缓解:每步独立可合并、每步都有护栏测试;_fingerprint() 按 (path, mtime) 失效保证配置热更新语义不变 |
| 11 | 加 frontend/tests/api-contract.test.mjs(§2.5 第二层),14 条死接口写成显式 allowlist |
表 ①/② 类漂移永久自动化拦截;新增未接入路由必须显式登记 | 低。首次运行需把当前 14 条登记进 allowlist |
| 12 | list_workflow_nodes 返回体加 progression,前端删除 App.vue:10836-10861 + :927 |
消除 §2.2 #2(复核定级 P2)复刻的四层状态机;后端改进度规则不再需要前端跟改 | 中。返回结构变更,需同步 workflow.ts 并升 contract_version。缓解:新增字段而非替换,前端可分两步切换 |
| 13 | WorkflowNode.to_dict() 增加 writable + lock_reason(复用 WorkflowNodeMaterialBindingDetail 已有的形状),前端 workflow-lock-state.ts 退化为读 node.writable |
消除 §2.2 #3(复核定级 P3)写锁规则不一致的全部分歧 | 中。同 #12 |
| 14 | ui/bootstrap 下发 task_statuses 四集合 + long_task_* 配置 + 节点目录(gradual_node_templates() + legacy 别名表) |
一次性收敛 §2.2 的 #7 / #10 / #11 三条 P2 | 低。纯增量字段 |
| 15 | 下沉 branch_state_for / with_branch_state / BRANCH_STATE_FIELDS → core/branch_state.py;canonical_gradual_node_key 同理 |
消除 database → backend.services 与 database → engines 违规;解除包级双向依赖 |
低。都是纯函数,改的是 import 路径 |
| 16 | 下沉 ApiError/ErrorCode → core/errors.py;load_config_payload → core/config_loader.py(原位置保留 re-export) |
core 恢复零上行依赖 |
低。re-export 让 53 + 56 个 import 点可以零改动渐进迁移 |
| 17 | 接上 include_restricted / restricted_hidden / moderation-review 功能链 |
修复"生成成功但图库里没有"的用户可见数据丢失 | 低。纯新增 UI |
| 18 | CI 加构建新鲜度校验 npm run build && git diff --exit-code web pages/imagestudio;manifest() 加 build_hash |
产物与源码错位可被拦截/观测(§2.4) | 低。仓库尚无 .github/workflows,需先建 |
长期(跨迭代,需要专门排期)
| # | 动作 | 收益 | 风险 |
|---|---|---|---|
| 19 | main.py 按 §1.7 拆成 6 个模块(2580 → ~250 行);_SHORT_ALIASES 数据驱动替代 165 行转发;_runtime_config_patch_from_mapping 由 _RUNTIME_PATH_TO_ASTRBOT_KEY 反向遍历生成(277 → ~50 行) |
消除 66 条配置映射的双向手写;聊天业务从入口文件剥离 | 中高。main.py 是插件入口,改错即插件起不来。缓解:先做 _SHORT_ALIASES 与配置映射两块(有明确的等价性判据,可脚本比对 66 个键),拆分留到最后 |
| 20 | 补 style-set 流程 DTO(AdvancedStyleSourceView 等),让 backend/dto/ 重新成为响应真相来源;去掉 TS 的 | string;加 §2.5 第三层字段级契约测试 |
消除 §2.3 全部字段级漂移,并让它不可复发 | 中。触及 4,491 行的 advanced_style_set_service.py。必须先做 #21 或至少先隔离其序列化出口 |
| 21 | 拆 advanced_style_set_service.py(4,491 行 / 单类 2,092 行 / 31 方法 / 81 个模块级私有函数)与 advanced_material_service.py(1,856 行 / 45 方法 / 14 参数构造函数) |
解开耦合簇 2;generation_service 的 21 参数构造函数同理 |
高。这是仓库里最大的两个 service。缓解:先靠 #10 的组合根把装配剥离出去,再按"识别 / 共识 / 校验"三个子流程切 |
| 22 | ChatWorkflowService 的 69 处字符串 dispatch 换成类型化门面或直接依赖 composition 提供的 service |
恢复类型安全(重命名路由有静态检查保护);消除每次 dispatch 的反射 + 全量重建开销 | 中。69 个调用点。缓解:先做类型化门面(class ImageStudioApi 每端点一方法,内部仍走 dispatcher),行为完全不变,再逐个换实现 |
| 23 | EventBus 二选一:加锁 + 异常隔离并把 3 组"通知型"直连迁上总线;或删掉 subscribe/unsubscribe 改名 EventRecorder |
要么兑现解耦价值(簇 1 的 19 条直连边可减少),要么停止误导架构判断 | 迁总线:中(改变调用时序);改名:零。最忌讳的是维持现状 |
| 24 | 前端快速角色编排下沉为 POST workflows/{id}/quick-character/run |
消除 291 行浏览器端状态机与僵尸工作流(§2.2 #1,复核定级 P2) | 中高。需要后端实现锚点优先 + 并行提交 + 失败补偿。缓解:quick_character_consistency.py 已有基础 |
| 25 | release/ 的 20 个 ZIP(37 MiB)迁出主干,改用 git tag + release artifact |
.git 从 51 MB 显著下降 |
中。需要 git filter-repo 重写历史或接受只对未来生效。注意:不要动 web/ 与 pages/imagestudio/(§2.4) |
附:本报告不收录的内容
以下条目在原始材料中被列为耦合类缺陷,但经 _复核结论.md 的独立复核被推翻,本报告不作为成立缺陷收录,仅在此备案以免后续重复调查:
| 原始定位 | 原始定级 | 复核结论 |
|---|---|---|
POST profiles/{id}/archive 执行删除 → 用户意图扭曲 |
P1 | 误报。前端唯一调用方是文案/样式/提示均为"删除"的按钮,意图与行为一致;profile 状态机无 archived 态。残留 P3 命名整洁度问题,见 §2.1 |
events/stream 无游标 → 事件静默丢失导致 UI 停滞 |
P1 | 误报。总线上每条事件都满足 generation. 或 workflow. 前缀,.some() 的 OR 归约无法因窗口退化翻假;刷新是全量重取而非增量应用;轮次面板另有 4 秒自续轮询。残留 P3:slice(..., -1) 魔数写法应改为 slice(),接口无游标是设计粗糙而非缺陷 |
web/ 与 pages/imagestudio/ 是"误提交的两份重复 dist" |
P1 | 误报。两者是 INSTALL.md 明确定义的发布负载,base 不同且必须不同,一份产物无法服务两个挂载点;照建议加 gitignore 会导致插件页面不可用。残留 P3:缺构建新鲜度校验,见 §2.4 |
_string_list 18 处重复导致数据损坏 / 顺序不可预测 |
P1 | 误报。真实为 17 处(多出的来自 .tmp/ 构建快照),无跨模块导入,各调用点处理的值互不相干。残留 P3:DRY 异味 |
| 23 个 service / 4,579 行零测试 | P1 | 误报。实测覆盖率显示 23 个中有 8 个被实质执行(5 个覆盖率 74%~94%),真正零执行的是 9 个模块约 1,966 行;"同名测试不测同名 service"的论断被证明完全反向 |
(App.vue:6126、workflow-model-route.ts:36、App.vue:3076 三条同样被复核推翻,但因其残留问题仍属真实的重复实现耦合,已按 P3 收录在 §2.2 的 #4/#5/#6 并标注"经复核降级"。)
附二:终审补录的耦合项(初稿漏收)
终审回扫 _raw.json 全部 214 条发现后,确认下列 4 条耦合类发现未被本报告任何章节覆盖:
| 严重度 | 位置 | 问题 | 收敛方向 |
|---|---|---|---|
| P2-中等 | frontend/.../features/profiles/ProfilesPage.vue:10 |
三层 prop drilling:24 个 props / 13 个 emits,其中 16 个 props 是纯透传(ProfilesPage 自己一个都不用,只往下传给 ProfileDetailPane / ProfileWardrobePane) |
随 04 报告 §2.1.2 的 useProfilePage() composable 一起做:中间层不再转发 props,叶子组件直接从 composable 取 |
| P2-中等 | frontend/.../features/profiles/ProfileWardrobePane.vue:249 |
状态归属分裂:衣橱条目走 props/emits 由父层持有,套装模板却由组件自己调 API —— 同一个面板里两套数据流,父层无法感知模板变更 | 二选一:模板也上提到父层,或衣橱条目也下沉到组件自持。不要维持现状 |
| P2-中等 | core/astrbot_provider_bridge.py:22 |
全局可变状态:AstrBot 桥接对象与配置覆盖是进程级模块变量,插件热重载后旧对象可能残留,测试之间无法隔离 | 由 §1.4.4 的组合根持有并注入;每个 set_* 配一个 reset_* 供测试 |
| P3-轻微 | core/config_writer.py:17 |
配置文件锁仅为进程内 threading.RLock —— 多进程部署(或 AstrBot 与外部工具同时写 config.yaml)时不提供任何互斥 |
改用文件锁(portalocker 或 fcntl/msvcrt 分支),或在文档里明确声明"单进程写入"约束 |
backend/services/profile_service.py:160 的 _require_owner 与 ResourceAccessService._can_access 语义相反(前者不认管理员权限)也属耦合缺陷,因其直接影响 02 报告 P1-2 的 IDOR 改造,已登记在 02-BUG清单.md 的 §6.1。