astrbot_plugin_imagestudio/审计/03-耦合分析.md

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:10
from 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:311
from 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:17
database/repositories/workflow_cross_review_repository.py:17
from 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:11
from engines.character_flow import canonical_gradual_node_key
同上,仓储层依赖引擎层的节点键归一逻辑。
core → backend.dto core/security.py:5
from backend.dto.common import ApiError, ErrorCode
backend.dto.common(扇入 53/54,全仓第三)事实上扮演"全局错误契约"的角色,却被放在 backend 包下,逼得 core 反向依赖。命名与真实分层错位。
core → database core/config_service.py:10
from database.db_helper import load_config_payload
把"读配置"和"连数据库"绑在一起——而 load_config_payload 本质是 YAML 加载,跟数据库毫无关系。
core → database core/audit_service.py:12
from database.db_helper import Database, DatabaseSettings
审计服务需要落库可以理解,但代价是 core 整体不再是最底层,无法独立复用或测试。
core → backend/database core/storage.py:11、core/media_proxy.py:17 同族问题,共 5 个 core 模块有上行依赖。

修复顺序(按"改动面 / 收益"排):

  1. 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。
  2. ApiError / ErrorCode / success_response / response_from_exception 从 backend/dto/common.py 移到 core/errors.py,backend/dto/common.py 保留 re-export 做过渡——53 个 import 点可以零改动渐进迁移。
  3. load_config_payload / load_config_file_payload / _RUNTIME_CONFIG_OVERRIDES 从 database/db_helper.py:26-83 抽到 core/config_loader.py,db_helper 反过来 import 它。做完这两条 core 恢复零上行依赖。
  4. 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}"

迁移顺序(可增量,每步都能独立合并):

  1. 先建 backend/composition.py,只迁 WorkflowService 一族 + 那条 test_every_workflow_service_has_event_bus。这一步就修掉了两例事件丢失。
  2. 迁 _create_generation_service(node_routes.py:315-390)→ composition,node_routes 与 job_routes.py:311 改为从 composition 取。这一步消除 service → route 与 route↔route 两条环。
  3. 抽 build_governance_bundle(config_payload, runtime) -> GovernanceBundle(含 translation/moderation/routing/image_moderation 四个服务),node_routes / advanced_material_service / prompt_routes 三处统一调用。
  4. 逐个迁剩余 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

三条具体问题:

  1. 零解耦价值。workflow_round_service → generation_service、generation_job_retry_service → generation_service、deletion_safety_service → image_service/media_service 这些"做完 A 顺手通知 B"的调用,本来正是总线该承接的,现在全部是硬 import——所以簇 1 才有 19 条直连边。
  2. 一旦有人开始订阅就立刻踩坑。publish 是同步调用,handler 抛异常会直接打断业务事务;_handlers 是 defaultdict(list),subscribe/unsubscribe 无锁,而 DEFAULT_EVENT_BUS 被 QueueWorkerPool 的工作线程和请求线程共享。目前因为没有 handler 所以未暴露。
  3. 它伪装成解耦手段,误导架构判断。看到 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"})

可举证的分歧(已按复核结论修正):

  1. 真实且可达: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。

  2. 仅理论洞:progression.completed_node_ids 那一条对 node_type == "generation" 的节点实际只剩 status in {"selected","skipped"} 一种可能(planning / reference_binding / profile_card 与 legacy 分支都不适用于生成节点),因此额外差异仅是 "skipped",而 UI 未提供把生成节点置为 skipped 的入口。
  3. 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 字段级差异表

类型 方向 差异 后端真源
AdvancedMaterialImportStatus
advanced-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) —
CharacterProfile
profile.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.count
workflow-round.ts:48-52
TS 比后端窄 TS 写死 4 | 5;后端 maximum = 8 if round_kind == "cross_review" else 5 workflow_round_service.py:1159-1171
ImageListResult
image.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 收敛方案

  1. 去掉 | string,改为 status: AdvancedMaterialImportStatus,让联合类型真正生效;确需容忍未知值的地方在解析边界处显式收窄。
  2. 为 style-set 流程补 DTO(AdvancedStyleSourceView、AdvancedStyleValidationCaseView、AdvancedStyleConsensusView),让 service 返回 DTO 实例而非裸 dict,路由层只调 to_dict() + 加签名 URL。这样"接口返回什么"重新有唯一定义点。
  3. 状态集合从后端生成而非手抄:把各 *_STATUSES 常量集中到一个 Python 模块,加生成脚本产出 frontend/shared/types/generated-enums.ts,CI 校验 git diff --exit-code。
  4. 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」。这条建议经复核被推翻,照做会导致插件页面全线不可用。

  1. 这两个目录是文档明确定义的发布负载。 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"。
  2. "两份重复 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" vs STANDALONE_WEB_URL = "/api/v1/..."),一份产物物理上无法同时服务两个挂载点。plugin-page/src/App.vue 全文只有一行 import WorkbenchApp from "../../standalone-web/src/App.vue"——源码层面已经没有重复,重复的只是两份必需的编译输出。
  3. "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。
  4. 仓库体积的主因不是 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 的提交。

替代方案(按推荐度):

  1. 加一条构建新鲜度校验(推荐,改动最小):
    # CI 步骤:产物必须是当前源码的构建结果
    - run: cd frontend && npm ci && npm run build      # 已有 "build": "build:plugin && build:web"
    - run: git diff --exit-code web pages/imagestudio
    
    这一条同时解决"漏跑一次构建"和"产物与源码错位"两个问题,且不改变发布模型。
  2. manifest() 增加 build_hash(构建时注入),与 metadata.yaml 版本比对,让版本错位在运行时可观测而不是靠用户报障。
  3. release/ 的 20 个 ZIP 迁出主干——改用 git tag + release artifact 承载。这是真正能压缩 .git 的动作(37 MiB / 44 MiB)。
  4. 不要把 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。