astrbot_plugin_imagestudio/审计/04-代码精简方案.md

70 KiB

04 · 代码精简方案

面向要动手改这个仓库的工程师。每一条都给位置、削减量、做法骨架和风险。 数字来源:审计/findings/C1-后端精简空间.md、C2-前端精简空间.md、C3-测试与仓库卫生.md,辅以 A3/A6/A8/A9;凡与 _复核结论.md 冲突处,一律以复核为准并标注「经复核降级/修正」。


摘要

先说清楚前提:后端 263 个 pytest 全部通过(188 秒),前端 26 个 node:test 全部通过。代码跑得起来,问题是设计边界和体量。 本报告不修 bug,只处理"同一件事被写了 N 遍"和"写了但没人用"。

三个数字定调:

  • 后端 ~64,100 行里,仓储层连接样板重复 131 次、_optional_text 独立定义 30 次、_json_or_none 13 次,而 backend/routes/params.py:22 早就提供了共享实现,从未被任何模块 import。
  • 前端 39,254 行里,App.vue 一个文件占 22,563 行(script 11,356 / template 2,784 / CSS 8,395)。它的 CSS 块没有 scoped,这是它拆不动的直接原因——搬模板必须同步搬 CSS,否则样式立刻丢。
  • 单个后端服务 advanced_style_set_service.py 4,491 行,其中 _execute_consensus 一个方法 467 行。

保守可净删 ≈3,510 行源码(后端 1,746 + 前端 1,767),另有一个高风险的路由层改造可再减 300 行。App.vue 另有 ≈7,200 行属于"迁出而非删除",拆完后该文件落到 4,000–4,500 行。

总收益表

类别 预计削减行数 风险 优先级
后端 · 纯删死代码(core/queue_manager.py 整文件 + 29 个零引用符号 + EventBus 空转分发 + event_from_bus + config 默认值重复) ≈407 低 P0 · 立即
后端 · 工具函数收敛(_optional_text×30 / _string_list×17 / _json_*×20 / _page族×10 / _signed_url×7 / _now×6 / _mapping×4) ≈429 低–中 P1
后端 · DTO to_dict() 纯镜像 → DictMixin ≈220 低 P1
后端 · 仓储连接样板 131 处 → BaseRepository._connect() ≈390 中 P2
后端 · update 赋值块 ×6 + _create_*_service 工厂集中 + engines provider 基类提取 ≈160 中 P1(顺带消灭 2 个真实缺陷)
后端 · main.py 38 个短命令别名 → 命令表 ≈140 中 P2
后端 · 路由 def action() 闭包 → @route_handler(建议单独立项) ≈300 高 P3
前端 · 死 CSS / 与子组件 scoped 重复的 CSS 副本 ≈518 低 P0 · 立即
前端 · 死类型 / 零引用导出 / 死配置 / 未使用依赖 ≈94 低 P0 · 立即
前端 · 模板与逻辑组件化(素材选择器 / focus trap / 缩放拖拽 / loader 样板 / overlay 表驱动) ≈455 中 P1
前端 · CSS utility/token 层,合并重复声明块 ≈700(上限 1,100) 中 P2
净删除合计(不含路由装饰器立项) ≈3,513 行
含路由装饰器立项 ≈3,813 行
前端 · App.vue 迁出(不减总量,把 22,563 压到 ~4,200) ≈7,200(迁移) 中–高 分 6 阶段
仓库 · release/ 20 个 zip 停止跟踪 0 行 / -38 MB 库内 中 P1
仓库 · 工作树 .tmp/ + .tmp_pytest_* 清理 0 行 / -2.6 GB 磁盘 低(含密钥,需安全删除) P0

口径说明(原始材料不一致处已取保守值):

项 C1/C3 口径 实测复核口径 本报告采用
_string_list 定义数 18 17(多出的 1 处来自 .tmp/ 构建快照) 17
main.py 短命令别名 50 个 / 164 行(:1300-1463) 38 个装饰器(:1304-1461) 38 个,块 :1300-1462,保守削减 ≈140 行
_create_*_service() 工厂 22 处 模块级 19 处(另有转发壳) 19 处
.tmp_pytest_* 目录 20 个 / 507 MB 19 个 / ~515 MB 19 个 / ~515 MB
_optional_text 定义数 A3 记 28、C1 记 30 30(grep -rn "def _optional_text" backend core engines database adapters main.py 实测) 30
App.vue 的 ref/computed 计数 01 报告记 133/135(字面量口径) 206 / 203(= ref( / = computed(,含 ref<T>( 泛型写法) 206 / 203,本报告与 05 统一用此口径
后端总行数 54,551(不含部分目录) 64,100 削减比例按 64,100 计算 → ≈2.7%

第一部分 · 后端精简

按投入产出比排序。前 4 项零/低风险,做完就有约 1,050 行。

1.1 仓储层连接样板重复 131 次 → 上下文管理器(≈390 行,风险中)

现状:每个仓储方法手写 conn = self.database.connect() / try: / finally: conn.close();写方法再额外手写 except Exception: _rollback(conn); raise。_rollback 本身被独立定义了 3 次。

位置:database/repositories/advanced_material_repository.py:346、workflow_repository.py:100、wardrobe_repository.py:84、core/audit_service.py:83 等共 131 处(实测 grep -c 'conn.close()' database/repositories/*.py core/audit_service.py = 132,finally: = 131)。_rollback 三份:advanced_material_repository.py:2119、workflow_cross_review_repository.py:1464、workflow_round_repository.py:1378。

现状代码(advanced_material_repository.py:346-366,同文件两个相邻方法逐字节同构):

def get_import(self, import_id: str) -> AdvancedMaterialImport | None:
    conn = self.database.connect()
    try:
        row = conn.execute(
            f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE import_id = {self.placeholder}",
            (import_id,),
        ).fetchone()
    finally:
        conn.close()
    return _row_to_import(row) if row else None

做法:在 database/repositories/__init__.py 建基类,13 个仓储的 __init__ + placeholder 属性一并收敛。

class BaseRepository:
    def __init__(self, database: Database) -> None:
        self.database = database

    @property
    def placeholder(self) -> str:
        return self.database._placeholder

    @contextmanager
    def _connect(self, *, write: bool = False):
        conn = self.database.connect()
        try:
            yield conn
            if write:
                conn.commit()
        except Exception:
            if write:
                _rollback(conn)
            raise
        finally:
            conn.close()

    def _fetch_one(self, sql: str, params: tuple, mapper): ...
    def _fetch_all(self, sql: str, params: tuple, mapper): ...

上例塌缩成 3 行。

风险(中):131 处机械替换,逐文件做、逐文件跑 python -m pytest tests/ -q。注意 profile_repository.update 当前没有 rollback 分支而 advanced_material_repository.update_import 有——统一到 write=True 会改变前者在异常时的行为(从"不回滚"变成"回滚"),这是修正而非回归,但要在 commit message 里写明。

1.2 _optional_text 独立定义 30 次,共享实现无人 import(≈145 行,风险低)

现状:同一个 5 行函数被复制 30 份(实测 grep -rn "def _optional_text" backend core engines database adapters main.py = 30)。而 backend/routes/params.py:20-22 早就有:

# Both names are used for this coercion across the backend.  Keep the alias so
# route and service code can use the vocabulary that best fits the field.
optional_text = optional_str

注释是错的——optional_text 从未被任何模块 import,它自己就是死代码。

位置:30 个定义点,包括 backend/services/queue_service.py:713、generation_service.py:2112、workflow_round_service.py:1592、database/repositories/workflow_round_repository.py:1343、engines/single_flow.py:241、engines/vision_provider.py:450、core/astrbot_provider_bridge.py:349、adapters/wechat_adapter.py:77、adapters/onebot11_adapter.py:96。

注意有 3 份语义不同:

# core/astrbot_provider_bridge.py:349 / adapters/wechat_adapter.py:77 / adapters/onebot11_adapter.py:96
def _optional_text(value: Any) -> str | None:
    text = str(value or "").strip()   # 0 / False / [] 被当成 None;主流版本不会
    return text or None

做法:新建 core/coerce.py(不要复用 backend/routes/params.py——database/repositories 和 engines 依赖 routes 包是层级倒置),导出 optional_text / optional_int / optional_float / as_bool / mapping / utc_now_iso。30 处改成 from core.coerce import optional_text as _optional_text。删掉 params.py:22 的死别名与错误注释。

风险(低):那 3 个变体要单独确认调用点是否依赖 0 → None 的行为。改之前先在这三个文件里 grep 调用参数类型。

1.3 _string_list 定义 17 次、至少 6 种语义 —— 同名不同义的语义地雷(≈90 行,风险中)

经复核修正:原始材料记为 18 处并声称会导致 tags 静默变空列表、prompt 片段顺序不可预测、数据跨 service 污染。复核逐条查证:真实计数是 17 处(第 18 处来自 .tmp/deploy-* 构建快照,不是源码);17 个实现全部是下划线私有、无一被跨模块 import(grep "from ... import ..._string_list" 零结果),每个调用点都是在本模块信任边界上对刚解析的 dict 做一次本地归一化,不存在接力传递,所以"跨模块数据污染"不可达;被点名的三条影响路径(tags 传给 workflow_round_service 版本、prompt_parts 在两模块间流转)经查根本不存在对应调用。严重度从 P1 降级为 P3。

它仍然值得修,但理由变了:这不是"重复 90 行"的问题,而是17 个同名函数在 4 个维度上自由组合出至少 6 种行为——是否切分逗号字符串、是否去重、是否排序、是否接受 tuple/set。任何人跨模块复制一行调用代码都会拿到与原处不同的结果,而且没有任何工具会报错。

位置:backend/services/composition_builder.py:279、generation_service.py:2417、prompt_expansion_service.py:257、workflow_round_service.py:1544、advanced_style_set_service.py:4288、material_normalization_service.py:368、core/astrbot_provider_bridge.py:344、engines/vision_provider.py:432、engines/review_flow.py:430 等共 17 处。

四种同名不同义的实现:

# core/astrbot_provider_bridge.py:344 —— 逗号切分 + 去重 + 排序
# backend/services/generation_service.py:2417 —— 逗号切分 + 不去重 + 不排序
# backend/services/workflow_round_service.py:1544 —— 拒绝字符串(返回 [])+ 去重保序
# backend/services/prompt_expansion_service.py:257 —— 字符串整体作为单元素,不切分

唯一实测到的真实不一致(复核确认,影响是装饰性的):VisionRecognitionResult.tags 有三个构造点——engines/vision_provider.py:357(sorted)、core/astrbot_provider_bridge.py:278(sorted)、advanced_style_set_service.py:1537(dict.fromkeys 保序),三者中两者一致、第三者顺序不同。下游(material_service.py:472、advanced_style_set_service.py:1765)只把 tags 当集合存储展示,无顺序依赖。

做法:在 core/coerce.py 定义语义显式命名的三个函数,废弃 _string_list 这个名字本身:

def csv_tags(value: Any) -> list[str]:      # 切分逗号 + 去重 + 保序
def prompt_parts(value: Any) -> list[str]:  # 不切分 + 去重 + 保序
def sorted_tags(value: Any) -> list[str]:   # 切分逗号 + 去重 + 排序

17 处按实际语义逐个替换(不是无脑换成同一个)。顺带把三个 tags 构造点统一到 sorted_tags。

风险(中):必须逐处读调用上下文判断该用哪一个,不能批量 sed。这是本项唯一的成本,也是它优先级不高的原因。

1.4 main.py 38 个短命令别名 ≈ 160–190 行纯转发 → 命令表(≈140 行,风险中)

现状:imagestudio_short_command 命令组下 38 个方法,每个只是把参数原样转给同名长命令。实测装饰器 38 个,块区间 main.py:1300–1462。风格还不统一——前 8 个用两行 async for / yield,后 30 个压成一行(:1345 起),说明是分批粘贴出来的。

# main.py:1304-1311
@imagestudio_short_command.command("帮助")
async def imagestudio_short_help(self, event: AstrMessageEvent):
    async for result in self.imagestudio_help(event):
        yield result

@imagestudio_short_command.command("状态")
async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
    async for result in self.imagestudio_status(event, workflow_id):
        yield result

做法:命令名 → 目标方法的映射抽成一张表,类装饰器生成别名:

_SHORT_ALIASES = {"帮助": "imagestudio_help", "状态": "imagestudio_status", ...}

def _bind_short_aliases(cls):
    for zh_name, target in _SHORT_ALIASES.items():
        async def _forward(self, event, *args, _target=target, **kwargs):
            async for result in getattr(self, _target)(event, *args, **kwargs):
                yield result
        setattr(cls, f"_short_{target}", cls.imagestudio_short_command.command(zh_name)(_forward))
    return cls

风险(中):AstrBot 的 @command 装饰器可能对函数签名做内省来解析参数(workflow_id: str = "" 这类),*args/**kwargs 转发会丢掉签名信息。上手前先验证一条:改一个别名(比如"状态")跑通再批量。若确实依赖签名内省,退化方案是保留装饰器形态、改由代码生成脚本从 _SHORT_ALIASES 生成这段代码并加一条测试断言长短命令一一对应——收益从"删 140 行"降为"消除漏注册",但风险归零。

1.5 core/queue_manager.py 整文件死代码(112 行,风险低)

现状:QueueManager / QueueItem 是一套完整的内存队列(enqueue / dequeue / complete / fail / retry / summary + FSM 校验),全仓含 tests/ 零 import、零引用。真实队列走 backend/services/queue_service.py + database/repositories/job_repository.py 的持久化实现。实测 wc -l core/queue_manager.py = 112。

复核已维持此条。

做法:git rm core/queue_manager.py。它单独依赖 core.fsm.task_transition,删掉后 fsm 的消费者数量才是真实的。

风险(低):删前跑一次 grep -rn "queue_manager\|QueueItem\|QueueManager" --include=*.py . 确认(排除 .tmp/)。

1.6 29 个零引用符号(≈263 行,风险低)

已用 grep -rn 在 main.py + backend + core + database + engines + adapters + tests + frontend/src 全范围交叉验证,引用数为 1(只有定义处):

文件:行 符号 行数
database/repositories/workflow_round_repository.py:488 update_pool_preferences 60
backend/dto/material_dto.py:10/32/54 RawAnalysis / NormalizedAssetProfile / GenerationCapsule 51
backend/services/worker_service.py:148 QueueWorker.run_batch 15
core/interactions.py:49 normalize_action 14
core/interop.py:14/29/44/49 PluginRequest / normalize_plugin_request / is_allowed_plugin / daily_outfit_request 41
backend/services/queue_service.py:539 requeue_dead_letters 10
database/repositories/profile_card_repository.py:266 next_version 10
database/repositories/advanced_material_repository.py:357 get_import_by_idempotency_key 10
backend/dto/chat_command_dto.py:21 SingleImageCommand.to_payload 10
backend/services/web_hosting_service.py:42/50/54 三个 asset 解析方法 9
core/event_bus.py:36/41 subscribe / unsubscribe 7
core/webhook.py:33/40 sign_event / verify_signature 6
core/secret_service.py:34/57 SecretResolution.to_public_dict / env_ref 7
其余 10 个小符号 get_runtime_data_root / create_audit_service / fetch_media_metadata / is_cancelled / column_names / sensitive_columns / has_images / _dump_yaml / optional_text / IMPORT_REVIEW_STATUSES / SUPPORTED_IMAGE_MIME_TYPES 23

两个需要单独决策的:

  • requeue_dead_letters(queue_service.py:539)和 update_pool_preferences(workflow_round_repository.py:488)看起来是产品功能(死信恢复、候选池偏好),实际无路由、无 CLI、无测试触发。要么接线要么删——留着最坏,会让人以为功能已交付。
  • core/interop.py 只有 PRIVATE_COMPANION 常量被 integration_token_service.py:16 引用。把常量挪进 integration_token_service.py 后整文件可删,再减 ≈45 行。

顺带:backend/services/settings_service.py:882-884 的注释写着"为已有测试保留",但 grep 显示没有任何测试引用它——注释和 params.py:22 一样是过期的。

1.7 DTO 15 个 to_dict() 是纯字段镜像(≈220 行,风险低)

AST 扫描确认这 15 个 to_dict() 的 key 列表与 value 表达式逐项等于 dataclass 字段声明顺序,无任何重命名或转换,共 234 行。

位置:backend/dto/workflow_round_dto.py:29/69/103、workflow_dto.py:24/61/109/137、profile_dto.py:32、material_dto.py:80/108、image_dto.py:32、job_dto.py:27、wardrobe_dto.py:25、profile_card_dto.py:19、workflow_feedback_dto.py:16。

# backend/dto/common.py 新增
class DictMixin:
    def to_dict(self) -> dict[str, Any]:
        return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}

15 个类继承它并删掉各自的 to_dict;另外 18 个有真实转换逻辑的保持手写(可继续覆写)。

风险(低):这是本报告投入产出比最高的一项——机械、可测、顺带消灭"加字段漏改 to_dict 导致 API 静默少字段"这类无法被类型检查拦住的 bug。

1.8 其余工具函数收敛(≈279 行,风险低)

项 处数 位置样本 削减 附带修复
_json_or_none / _json_loads / _json_object 20 job_repository.py:562、capability_repository.py:150/156、advanced_material_repository.py:2072/2078 ≈75 _json_loads 无 isinstance(parsed, dict) 保护,JSON 列存数组时返回 list,下游 .get() 直接 AttributeError;统一到有保护的版本
_page / _page_size / _limit 10 job_repository.py:609/617、material_repository.py:319/327、profile_repository.py:354/362、advanced_material_repository.py:2111 ≈48 前三份 try/except → max(page,1),第四份 max(int(value or 1), 1) 对非数字字符串直接抛 ValueError——高级素材列表接口对畸形 page 会 500,其他接口降级到第 1 页
_signed_url 7 advanced_material_routes.py:428、image_routes.py:226、material_routes.py:317、profile_card_routes.py:90、round_routes.py:192、workflow_round_worker_runtime.py:257、dashboard_service.py:89 ≈41 advanced_material_routes 版本每次调用 MediaService()(内部 ConfigService() 读盘),列表页 N 张图 = N 次配置加载。改成 MediaService.signed_url() 实例方法
_now ×6 + _mapping ×4 10 advanced_style_set_service.py:4279、queue_service.py:709、worker_service.py:476、history_service.py:313 ≈30 _mapping 对应的内联写法 x.get("y") if isinstance(x.get("y"), dict) else {} 在后端出现 291 次(node_routes.py:329-335 一个函数里连着 5 行),每处把 key 名写两遍——写成 config.get("a") if isinstance(config.get("b"), dict) else {} 没有任何工具会报错
update 赋值构建块 6 workflow_repository.py:141-176/180-227/280-321/324-379 ≈85 四段循环体逐字节相同,allowed 集合各复制两遍。给 node 加可更新字段要改 2 个集合,漏改 = "普通更新生效、CAS 更新静默丢字段"。advanced_material_repository.py:2042 已有更通用的 _update_assignments,提升到 database/repositories/_sql.py 共用即可

1.9 _create_*_service() 工厂集中(≈20 行,风险中,但会修一个真实缺陷)

现状:_create_workflow_service() 在 4 个 route 模块里各一份,其中 backend/routes/branch_routes.py:62-68 漏掉了 event_bus=get_default_event_bus():

# backend/routes/branch_routes.py:62-68  ← 缺 event_bus
def _create_workflow_service() -> WorkflowService:
    database = Database(load_database_settings())
    return WorkflowService(
        workflow_repository=WorkflowRepository(database),
        profile_repository=ProfileRepository(database),
        audit_service=AuditService(database),
    )

# backend/routes/workflow_routes.py:143-150  ← 有 event_bus

而 WorkflowService._publish(workflow_service.py:1012-1014)是空守卫(if self.event_bus:),create_branch(:514)与 switch_branch(:640)都调它。结果:走 HTTP POST /workflows/{id}/branches 和 /switch-branch 时事件被静默吞掉,前端 SSE 永远看不到分支变更,且不报错。典型的"复制粘贴少复制一行"。

做法:把 19 个模块级 _create_*_service()(C1 计 22 处,含转发壳)集中到 backend/services/factory.py,每种 service 只保留一份构造。顺带解决层级倒置:backend/services/workflow_round_worker_runtime.py:10 反向 from backend.routes.node_routes import create_generation_service,而 node_routes.py:393-396 的 create_generation_service() 只是 return _create_generation_service() 的纯转发壳。

风险(中):148 个 handler 的 service= 注入点是测试的入口,集中工厂时不要改这个参数的语义。

1.10 engines/ provider 基类提取(≈55 行,风险低,顺带修一个配置陷阱)

ImageProviderError(image_provider.py:96-110)与 VisionProviderError(vision_provider.py:72-86)除类名外逐字节相同;_post_json 的 urllib 回退分支(image_provider.py:272-303 vs vision_provider.py:295-337)只差异常类和错误文案里的 image/vision 前缀。

真正的代价是分叉:image 版 _post_json 已经加了 httpx 流式读取 + 长度上限(:231-271),vision 版还停留在纯 urllib——视觉调用没有 httpx 的超时/重定向控制,也没有 _provider_json_limit 动态上限。

同一族的第二个分叉(endpoint_url()):

# engines/image_provider.py:51-56
if base.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"):
    endpoint = endpoint[3:]          # ← 去重

# engines/vision_provider.py:40-43  ← 没有去重

vision_endpoint 默认值是 /v1/chat/completions。用户填 base_url: https://api.example.com/v1(OpenAI 兼容服务最常见写法)时,视觉识别打到 /v1/v1/chat/completions → 404,而生图正常。model_provider_runtime.py:210-216 与 :297-303 同样没有去重。

做法:新建 engines/_provider_http.py:

class ProviderError(RuntimeError): ...          # 两个子类只留 pass + 文案前缀
def join_endpoint(base_url: str, endpoint: str) -> str: ...   # /v1 去重,三处共用
def post_json(url, payload, headers, timeout_seconds, *, error_cls, label, max_bytes) -> JsonDict: ...

1.11 advanced_style_set_service.py 4,491 行的拆分边界(迁移,非净删)

现状:4,491 行 = 类体 2,091 行(32 个方法)+ 模块级函数 2,092 行(81 个纯函数)。最长方法 _execute_consensus 单体 467 行(:1347),_execute_validation_case 220 行,_queue_validation_batch 161 行。

更麻烦的是双向循环引用:

# advanced_style_set_service.py:309-318
def __init__(self, owner: Any):     # 无类型标注的反向引用
    self.owner = owner
    self.repository = owner.repository
    ...                              # 共 8 个协作者全从 owner 上扒

# advanced_material_service.py:118
self.style_sets = AdvancedStyleSetService(self)

两边互相调私有方法(self.owner._require_import / _govern_validation_prompt / _generation_route)。owner: Any 让 IDE 和类型检查完全失效,单元测试只能完整 mock owner。

模块划分建议(都是纯搬运、无行为变更):

目标模块 迁入内容 约行数
style_prompt_compiler.py _detailed_style_prompt / _detailed_style_negative_prompt / _scale_specific_* / _style_kernel_parts / _compact_style_prompt_parts / _artist_signature_* / _join_prompt ~600
style_text_sanitizer.py _sanitize_minor_age_text / _strip_mature_body_locks / _normalize_style_prompt_conflicts / _clean_prompt_text / _apply_semantic_risk_rewrites 及其正则常量 ~400
style_review_scoring.py _normalize_style_dimension_scores / _weighted_style_fidelity_score / _cap_inconsistent_dimension_scores / _aggregate_style_review_feedback / STYLE_REVIEW_* 常量 ~400
style_evidence.py _normalized_feature_evidence / _style_trait_is_supported / _prompt_traits_overlap / _extract_head_ratio_range 系列 ~300
剩余类体 → StyleSourceStage / StyleConsensusStage / StyleValidationStage 各自只接收显式依赖(repository / queue / storage / runtime) ~2,090

同步做两件事:

  1. owner: Any 换成一个 StyleSetRuntime Protocol,只暴露 require_import / generation_route / govern_validation_prompt 等 6 个方法,消除双向引用。
  2. _execute_consensus 按 text_only / single_pass / grouped_two_stage 拆三个私有方法,共用一个 _persist_consensus_result。

顺带:advanced_style_set_service.py:33-41 跨模块 import 了 material_service 的 7 个下划线私有函数(_normalize_upload_content_type / _normalize_upload_filename / _normalize_upload_metadata / _normalize_upload_size / _recognition_metadata / _storage_image_data_url / _vision_provider_error)。它们实际上是整个素材域的公共上传校验契约,应去掉下划线提升为公共 API。

风险(中):81 个模块函数是纯函数,搬运零风险;类体拆三个 Stage 需要重新走一遍端到端测试(tests/test_advanced_style_set_workflow.py)。

1.12 engines/ 四个 flow 文件 —— 结论:不建议合并

这是 A6 专项核查的结论,本报告采纳:

文件 行数 性质 与其它 flow 的实质重复
engines/single_flow.py 455 真实生成引擎(provider 调用、字节校验、URI 布局) 无
engines/review_flow.py 451 真实审查引擎(策略校验、评分、阶段结果) 无(内部有自重复,见下)
engines/character_flow.py 145 声明式节点模板目录 + 遗留 node_key 别名 仅 gradual_node_templates() 约 15 行样板
engines/fast_character_flow.py 50 声明式节点模板目录 仅 fast_character_node_templates() 约 11 行样板
engines/quick_profile_flow.py 32 声明式节点模板目录(内联字面量) 无函数,纯字面量

三个模板目录唯一的共性是约 11–15 行的列表推导样板,但三者 metadata 契约各不相同(character_gradual 要 stage_code + canonical_node_key 且支持 per-step node_type 覆盖;character_fast 要 quick_character_target;quick_profile 用 profile_draft/profile_preview 这类完全不同的 node_type)。抽公共构造器需要引入配置参数把这些差异重新表达出来,代码量与理解成本都不会下降,反而把三种工作流的演进耦合在一起。当前形态(声明数据与业务逻辑分离、每种工作流一个独立目录)是合适的,不要动。

引擎侧真正值得做的重复合并(不在上表内):

  • adapters/onebot11_adapter.py 与 adapters/wechat_adapter.py 结构性重复约 90%。
  • engines/review_flow.py:141-159 与 :362-380:_candidate_warnings 的告警判定与文案逐字相同,只有变量名不同。

1.13 路由 def action() 闭包(≈300 行,风险高,建议单独立项)

148 处 def action() + 157 处 return handle_request(ctx, action)(实测)+ 147 处 service or _create_xxx()。每个 handler 固定四段式:

# backend/routes/wardrobe_routes.py:57-70 —— 与另外 147 个同构
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, service=None) -> dict:
    wardrobe_service = service or _create_wardrobe_service()

    def action() -> dict[str, Any]:
        require_permission(ctx, "can_manage_materials")
        return wardrobe_service.delete_item(profile_id, wardrobe_item_id, ctx)

    return handle_request(ctx, action)

同文件 :86-107 已经出现了绕过闭包的"元组下标"写法,说明作者本人也嫌样板烦。

真正的收益不是 300 行,而是权限矩阵可静态校验:现在 RouteSpec.permission(route_registry.py)与 handler 里的 require_xxx(ctx) 是两份独立真相——branch_routes 漏 event_bus 就是这种双真相结构的产物。

@route_handler(permission="materials", service_factory=_create_wardrobe_service)
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, *, service) -> dict[str, Any]:
    return service.delete_item(profile_id, wardrobe_item_id, ctx)

并在启动时断言装饰器声明的 permission 与 route_registry.ROUTES 一致。

风险(高):148 个 handler 的 service= 测试注入点需同步调整,而路由层测试覆盖本身就薄(route_registry 166 条路由中只有 33 条被测试字面量命中——注意这是下界,复核实测 handler 函数名命中 50、模块名命中 8,用字面量 grep 会漏掉直接 import handler 的测试)。先补 1.14 的注册表契约测试,再动这一项。

1.14 做这些之前先加的两条保护

# tests/test_route_registry_contract.py —— 成本极低,一次覆盖 166 条
from backend.route_registry import ROUTES, assert_unique_routes

def test_every_route_handler_resolves_and_declares_permission():
    assert_unique_routes()
    for spec in ROUTES:
        mod, fn = spec.handler.rsplit(".", 1)
        assert callable(getattr(importlib.import_module(mod), fn)), spec.endpoint
        assert spec.permission, spec.endpoint

以及先修 pytest 本身——仓库没有 conftest.py / pytest.ini / pyproject.toml,pytest tests/ 会在收集阶段 ModuleNotFoundError 崩溃,只有 python -m pytest 能跑:

# pyproject.toml
[tool.pytest.ini_options]
pythonpath = ["."]
testpaths = ["tests"]
addopts = "-q --strict-markers --basetemp=.pytest_tmp"

最后一条 --basetemp 直接解决第三部分那 19 个散落在仓库根的 .tmp_pytest_* 目录。

另有两个文件带 UTF-8 BOM(backend/routes/job_routes.py:1、backend/services/profile_document_import_service.py:1),ast.parse(path.read_text(encoding="utf-8")) 会抛 SyntaxError: invalid non-printable character U+FEFF。任何自建的重构脚本都会在这两个文件上失败——批量改造前先去 BOM:

python -c "import pathlib;[p.write_bytes(p.read_bytes()[3:]) for p in map(pathlib.Path,['backend/routes/job_routes.py','backend/services/profile_document_import_service.py']) if p.read_bytes()[:3]==b'\xef\xbb\xbf']"

第二部分 · 前端精简

2.1 App.vue 22,563 行拆分方案(本报告核心)

2.1.1 先看清障碍在哪

指标 数值
总行数 22,563(script 1–11,357 / template 11,359–14,143 / style 14,145–22,540)
<style> 8,395 行,约 1,100 条选择器,没有 scoped
ref() / computed() / 顶层 function 206 / 203 / 365
API 调用点 getJson 59 + postJson 58 + putJson 9 + deleteJson 3 = 129
try / catch 84 / 82
AbortController 0(所有请求不可取消)

拆不动的直接原因就是那 8,395 行未 scoped 的 CSS:任何把模板搬进新组件的动作都必须同步搬走对应的几百行 CSS,否则样式立刻丢失。而全部 44 个子组件用的都是 <style scoped>,两套体系并行。

所以拆分顺序必须是 CSS 先行,而不是模板先行。

2.1.2 分块清单

A. 样式块(14,145–22,540,8,395 行)

块 内容 目标产物 预计行数
S1 rail / brand / brand-mark / brand-copy / icon-nav / nav-scroll / nav-group* / nav-glyph / nav-copy / nav-label / rail-pin* 剪进 components/AppNavigationRail.vue 的 <style scoped>(该文件当前完全没有 <style>) 347
S2 MaterialCategoryCreateDialog 的 4 个类 + materials-detail-card* 分别剪进 MaterialCategoryCreateDialog.vue(无 <style>)与 MaterialDetailDialog.vue(只有 4 行 scoped) 344
S3 quick-profile-* 全族 styles/quick-profile.css 1,268
S4 workflow-*(node / profile / persona / prompt / draft / material / subnode / preview / action / group / section / generation) styles/workflow.css ~1,400
S5 materials-* styles/materials.css ~600
S6 image-*(composer / preview / info / stage) styles/image-workspace.css ~400
S7 死规则(41 条完全由死类构成) 直接删 -277
S8 image-viewer-card/-actions/-stage(与 ImagePreviewDialog.vue:221-324 的 scoped 副本逐字节相同) 直接删 -104
S9 state-card / empty-state-actions / workflow-chat-panel / workflow-composer-panel(子组件已有 scoped 等价副本) 直接删 -32
S10 14 处完全相同的"眼眉标签"规则(color: var(--text-soft); font-size: 12px; font-weight: 800) 合并成一条选择器列表规则 -50
S11 剩余全局 shell / body / token 保留在 App.vue 或并入 styles/workbench.css ~1,500

死类举例(名字极具迷惑性,容易误以为在改生效规则):.workflow-node-card(:17764-17787)——模板里节点卡实际用的是 workflow-node-item;.generate-status-grid / .generate-feature-card / .generate-section / .generate-card-grid 整组(:21129-21286)——generateFeatureCards computed 还在,但渲染它的模板早已改用 quick-profile-command-card。

删 S7 前先固化规则,仓库已有 node --test tests/*.test.mjs 的契约测试习惯:

// frontend/tests/dead-css.test.mjs
// 断言 App.vue 样式块内的类必须能在某个模板中被引用;白名单放 Transition 派生类与动态拼接类

注意保留 .image-viewer-backdrop(App.vue 模板里 4 个内联弹层仍在用),只删 .image-viewer-card/-actions/-stage。

B. 模板块(11,359–14,143,2,784 行)

块 行号区间 职责 目标产物 预计行数
T0 11,360–11,385 app shell + 导航轨 + 标题栏 保留在 App.vue 26
T1 11,386–11,424 全局搜索框 / 结果面板 components/GlobalSearchBox.vue + useGlobalSearch() 39
T2 11,425–11,549 顶栏动作区(通知 / 日志 / 调色板 / 主题) components/TopBarActions.vue 125
T3 11,551–11,570 主题调色板浮层 components/ThemePalettePanel.vue 20
T4 11,571–11,623 通知中心浮层 features/notifications/NotificationPanel.vue 53
T5 11,626–11,646 生成页 hero + 三模式切换 features/generate/GenerateHeader.vue 21
T6 11,648–11,806 单图生成工作台 features/generate/ImageComposerPanel.vue 159
T7 11,807–12,269 快速角色工作台 features/quick-profile/QuickProfileWorkspace.vue 463
T8 12,270–12,987 详细工作流工作台(最大块) features/workflow/WorkflowWorkspace.vue,再内切 5 个子面板 718
T9 12,988–13,075 外部角色卡导入对话框 features/quick-profile/ExternalProfileImportDialog.vue 88
T10 13,077–13,329 角色档案问卷对话框 features/quick-profile/PersonaQuestionnaireDialog.vue 253
T11 13,377–13,630 素材库页 features/materials/MaterialsPage.vue 254
T12 13,631–13,760 队列页 features/queue/QueuePage.vue 130
T13 13,811–13,975 总览仪表盘 features/overview/OverviewPage.vue 165
T14 13,976–14,040 性能详情页 features/overview/PerformancePage.vue 65
T15 14,041–14,142 全局对话框挂载区 components/AppDialogHost.vue 102
T16 12,009–12,117 与 12,658–12,769 素材选择器弹层,逐字复制两份(97 行里只有 5 行不同) features/materials/MaterialPickerPopover.vue,props { category, placement?, extraClass? },事件 select/clear -100

T16 已经开始漂移:reference.advanced 的"进阶素材 · 高优先级"标记只有 workflow 侧有,quickProfile 侧看不到。

C. 脚本块(1–11,357,11,356 行)

块 行号区间 职责 目标产物 预计行数
C1 2,782–3,222 + 3,223–3,282 workflowActionCards 巨型 computed + 标签表 features/workflow/workflow-action-cards.ts(纯数据,零风险搬运) ~500
C2 3,751–3,921 / 3,370–3,512 / 1,346–1,458 / 1,931–2,041 generate / queue / material / quickProfile 四组动作卡 各自 features/*/action-cards.ts ~580
C3 11,243–11,313 + 5,392 + 9,627 色彩工具(materialColorTuple / alphaColor / mixColor / hexToRgb / toHexByte) utils/color.ts ~90
C4 11,024–11,226 图片 URL / 占位图 / 媒体签名解析 composables/useMediaUrls.ts(必须先修 P1 副作用问题,见下) 203
C5 4,302–4,487 后端连接状态机 / bootstrap / 指数退避重连 composables/useBackendConnection.ts 186
C6 4,561–4,609 事件流轮询 composables/useEventStream.ts 49
C7 4,488–4,547 + 4,611–4,698 dashboard / 成本 / 任务 / 日志 / 模型选项加载 composables/useDashboardData.ts 148
C8 4,700–4,786 设置页读写与校验 composables/useSettingsPage.ts 87
C9 4,787–4,862 + 5,316–5,620 + 9,993–10,310 素材库 composables/useMaterialLibrary.ts 663
C10 4,864–5,100 + 5,644–5,775 + 6,287–6,339 角色档案 + 衣橱 + 删除 composables/useProfilePage.ts 340
C11 5,776–6,154 快速角色四联图生成编排 优先下沉到后端,残留 → composables/useQuickCharacterGeneration.ts 379
C12 6,460–6,681 + 6,919–7,100 + 8,462–8,552 轮次 / 候选 / 反馈 / 确认 / 轮询 composables/useWorkflowRounds.ts 476
C13 7,101–7,264 节点素材绑定抽屉 composables/useWorkflowNodeMaterials.ts 164
C14 7,265–7,580 角色工作流创建 / 恢复 / 节点补齐 composables/useCharacterWorkflow.ts 316
C15 7,752–8,056 图片查看器 + 交叉审查对话框 composables/useImageViewer.ts + useWorkflowGenerationReview.ts 305
C16 8,058–9,250 工作流节点动作(最大块) composables/useWorkflowNodeActions.ts 1,193
C17 9,251–9,763 问卷 → 档案 payload 构建 + 外部角色卡导入 composables/useQuickProfileArchive.ts 513
C18 9,765–9,940 12 个受控浮层管理 composables/useOverlayManager.ts,改注册表驱动 176
C19 10,312–10,510 队列动作 + 二次确认 composables/useQueueActions.ts 199

C18 现在是两条 12 分支的 if 链,且 isOverlayOpen 的兜底是 return showLogPanel.value——新增一个 ControlledOverlay 忘了加分支就会静默错判成"日志面板开着":

const overlayRegistry: Record<ControlledOverlay, { isOpen(): boolean; setOpen(v: boolean): void }> = {
  search: { isOpen: () => searchPanelOpen.value, setOpen: (v) => { searchFocused.value = v; searchPanelOpen.value = v } },
  ...
}
const isOverlayOpen = (k: ControlledOverlay) => overlayRegistry[k].isOpen()

省 40 行并消除兜底陷阱。

C4 拆之前必须先修:displayMediaUrl()(App.vue:11146)是被 4 个 computed 和整个模板 render 直接调用的"伪纯函数",它内部会发起网络请求并整体替换 resolvedMediaUrls ref。galleryImages computed(:997)依赖这个 ref 又逐张调用它——每张图解析完成都让整个 galleryImages 重跑,1,000 张图 ≈ 100 万次调用。照搬进 composable 只会把这条 P1 藏得更深。(原判 P0-致命,复核确认缺陷成立、行号逐条无误,仅因"它是性能/内存问题而非数据正确性或安全问题"降为 P1-严重,见 02-BUG清单.md 的 P1-10。)正确做法是把媒体解析从"渲染时惰性触发"改成"数据加载时显式预取":mediaUrl(raw) 纯查表,prefetchMediaUrls(rawUrls[]) 一次性写入,给 resolvedMediaUrls 加 LRU 上限并在淘汰时 URL.revokeObjectURL。

2.1.3 分阶段拆分顺序

阶段 0 · 纯删,零风险(≈550 行) SettingsPage.vue:165 的 .backup-* 死样式(单物理行 1,796 字符,格式化后约 45 行;备份面板早已拆成 BackupPage.vue 且用自己的 scoped 类名)+ :167 媒体查询里的 .backup-grid,.backup-scope>div → workbench.css:442-451 重复媒体查询 → shared/types/workflow.ts:96-130 过期类型副本 → 19 个零引用导出(含 shared/types/integration.ts 整文件)→ tsconfig.json:15-17 死别名 → 删 pinia/vue-router 并重排依赖。 验证:npm run typecheck + npm run test:contracts。

阶段 1 · 删死 CSS,需视觉回归(≈460 行) 先落地 frontend/tests/dead-css.test.mjs,再删 S7/S8/S9/S10。

阶段 2 · 纯数据外迁,零模板改动(≈1,170 行迁出) C1 + C2 五个动作卡工厂 + 4 张标签映射表 → features/*/action-cards.ts;C3 色彩工具 → utils/color.ts。这一步只是把 const x = computed(...) 换成 const x = computed(() => buildXCards(deps)),模板一行不改。这是风险最低的一大块,先做它能立刻把 script 从 11,356 压到 ~10,200。

阶段 3 · 剪归属明确的组件样式(344+347 = 691 行迁出) S1 剪进 AppNavigationRail.vue、S2 剪进两个 Material 对话框。这三个组件当前离开 App.vue 就没有样式,剪进去后它们才自洽、才能单独测试。.rail 这类需要父级配合的定位规则用 :deep() 或留在 workbench.css。

阶段 4 · 无 UI 依赖的 composable(≈690 行迁出) C5 连接状态机 → C6 事件流 → C19 主题偏好 → C7 dashboard 加载。这些不碰模板,只是把函数搬走并 return 出来。

阶段 5 · 按 feature 切样式 + 组件化模板,从小到大 每一个 feature 都是"先切 CSS(S3–S6 对应块)→ 再搬模板 → 再搬 composable"三步。顺序: T9 外部导入对话框(88 行)→ T10 问卷对话框(253)→ T6 单图工作台(159)→ T16 素材选择器(净删 100)→ T11 素材库(254 + C9)→ T12 队列(130 + C19)→ T13/T14 总览(230)→ T7 快速角色(463 + C11/C17)。

阶段 6 · 最后动工作流主工作台 T8(718 行模板)+ C12/C13/C14/C16(2,149 行脚本)+ S4(~1,400 行 CSS)。这是全仓耦合最深的一块(workflowNodeActionError 一个 ref 被 67 处赋值、同时承载成功与失败文案),放到最后做,前面五个阶段积累的 composable 模式此时已经成熟。

拆完后 App.vue ≈ script 3,500 + template 350 + style <300 ≈ 4,200 行。

2.2 跨组件重复模式

模式 处数 位置 削减 关键不一致
焦点陷阱(focus trap) 6 ConfirmDialog.vue:50-67、ImagePreviewDialog.vue:124-141、MaterialOperationDialog.vue:146-160、ProfileWardrobePane.vue:216-238、WorkflowCompareDialog.vue:48-59、WorkflowGenerationReviewDialog.vue:163-175 ≈130 只有 ConfirmDialog 检查 !dialogRef.contains(active) 能把逃逸焦点拉回来,其余 5 份 document.activeElement === first 一旦焦点落到 <body> 就锁不住;WorkflowCompareDialog 的选择器少了 input/select/textarea。另有 WorkflowMaterialDrawer.vue:149 与 SettingsPage.vue:131 声明了 aria-modal="true" 却零键盘管理(Esc 无效、Tab 直接走到背景)
loader loading/error/try/catch/finally 样板 25 App.vue:4488/4511/4611/4624/4638/4673/4700/4787/4864/5010/6872/6894/7028/7115 等 ≈90 loadModelOptions(:4673)忘了 try/finally,直接在末尾赋 loadingModelOptions.value = false,请求抛错时 loading 永久卡死
写操作前置校验样板 27–40 App.vue:10025-10103、:10105-10134、:8222-8298、:8407-8460、:8554-8636 等 ≈400(与上一行部分重叠,计入 App.vue 拆分) 五步骨架(busy 检查 → backendWriteBlockMessage → 置位 → try/catch → finally),漏 finally = 按钮永久卡死,漏 backendWriteBlockMessage = 绕过权限/连接检查
图片缩放/拖拽逻辑 2 App.vue:7952-8011 vs ImagePreviewDialog.vue:58-114(同一套逻辑,变量名从 scale/offset/dragging 改成 imageViewerScale/...) ≈95 魔数各写一遍:0.5/4/0.12/2.2 vs MIN_SCALE/MAX_SCALE/WHEEL_STEP/DOUBLE_CLICK_SCALE;改一边的手感不会同步
"选中项跟随列表" watch 8 App.vue:4055/4069/4083/4097/4184/4212/4226/4240 ≈90 结构完全相同(列表空→清空选中;选中项不在列表→取第一项)→ useSelectionSync(list, selectedId, keyOf)
分页拉全量 4 loadAllJobs(:4686)、loadRemainingMaterialPages(:4840)、loadRemainingProfilePages(:4884)、loadGalleryImages(:4511) ≈70 → fetchAllPages(endpoint, params, keyOf)
生成状态中文标签表 4 App.vue:6927-6939、WorkflowCandidatePool.vue:132-145、WorkflowRoundPanel.vue:113-129、shared/utils/presentation.ts:11-29 ≈40 译法互相冲突:同一候选在候选池显示"已完成"、其它视图显示"已成功";planned 有"待入队"和"已规划"两种说法;App.vue 那份缺 retrying/dead_letter,重试中的候选直接显示英文
图片 URL 白名单校验 4 features/profiles/profile-ui.ts:155、WorkflowCandidatePool.vue:165、WorkflowGenerationReviewDialog.vue:97、ProfileWardrobePane.vue:189 ≈20 同一个正则 /^(?:https?:|data:|blob:|\/)/i 抄 4 遍
errorMessage / normalizeStatus 2 App.vue:11354 vs AdvancedMaterialImportPage.vue:1354;AdvancedMaterialImportPage.vue:1350 vs shared/utils/presentation.ts:7 ≈8 App.vue 版走 readableApiError(识别 ApiClientError、区分预览模式、给中文可读文案),进阶素材页版只 err.message
衣橱分类标签 2 ProfileWardrobePane.vue:40-46 vs material-labels.ts:30-39 ≈10 ProfileWardrobePane.vue:158 的局部 materialCategoryLabel(material: Material) 与共享导出 materialCategoryLabel(value: unknown) 同名不同义,IDE 跳转定义会歧义
跨组件重复 CSS 声明块 — 全前端 CSS 14,698 行 700–1,100(上限 2,251) overflow:hidden;text-overflow:ellipsis;white-space:nowrap 21 次;color:var(--text-soft);font-size:12px;font-weight:800 21 次;display:grid;gap:4px;min-width:0 18 次;height:100%;object-fit:cover;width:100% 14 次;button.primary-button 在 6 个组件各定义一遍
死组件 1 features/workflow/WorkflowDependencyContextCard.vue(整个文件 279 行) ≈279 全仓零引用,但 App.vue 仍在维护数据链路(:792/793/794 三个 ref + loadWorkflowDependencyContext() :6894 + :4129/7214/8324 三处触发)——数据被拉了,展示组件不再挂载,改由 App.vue 内联渲染

CSS utility 层是所有后续 CSS 迁移的前置,先做它:

  1. styles/tokens.css(当前仅 24 行)扩成真正的 token/utility 层:.u-truncate、.u-eyebrow、.u-stack-4、.u-cover-img、.u-btn-primary。
  2. workbench.css 是一层 458 行的事后覆盖层,专门用超长选择器列表去覆盖 App.vue 的既有规则——把它的覆盖规则回填进各自的基础规则,这一层可减到 150 行以内。

共享代码要真的共享:把 readableApiError / backendWriteBlockMessage(App.vue:4356-4387)下沉到 shared/utils/api-error.ts;isBrowserImageUrl 下沉到 shared/utils/media-url.ts;generationStatusLabel 收进 shared/utils/presentation.ts 作为唯一真源。

2.3 plugin-page vs standalone-web —— 重复代码量:0 行,不要动

已实测确认:

  • plugin-page/src/App.vue 只有 7 行,直接 import WorkbenchApp from "../../standalone-web/src/App.vue" 再 re-export。
  • plugin-page/src/main.ts 6 行。
  • 两份 vite.config.ts 各 16 行,只有 base / outDir 不同。

经复核确认:这两份构建产物(web/ 与 pages/imagestudio/)不是"误提交的编译产物",而是 INSTALL.md 明确定义的发布负载——ImageStudio 是 AstrBot 插件,装机路径是把仓库/ZIP 铺到 data/plugins/,安装期没有任何 npm/vite 步骤。两份构建的 base 必须不同(web/index.html 用绝对路径 /api/v1/plugins/extensions/.../web/,pages/imagestudio/index.html 用相对路径 ./assets/),挂载于不同 URL 根,一份产物物理上无法同时服务两个挂载点。若把它们加进 .gitignore,WebHostingService._resolve 会直接抛 RESOURCE_NOT_FOUND, "web asset not built",插件页面全线不可用。

这套双构建方案已经是最优解。 唯一值得补的是构建新鲜度校验(仓库无任何 CI;历史上有 24 次只更新 web/assets、3 次只更新 pages/imagestudio/assets 的提交),frontend/package.json 已提供 "build": "npm run build:plugin && npm run build:web",把它接进 CI 即可。

另:standalone-web/src/components/ 与 features/ 下 25 个 .vue 全部有引用者(7 个走 defineAsyncComponent,App.vue:39-45),无未被引用的组件——WorkflowDependencyContextCard.vue 是唯一例外(见 2.2 末行)。

2.4 Pinia 装了但没用 —— 建议删掉,走 composable 路线

实测:grep -rn "pinia\|vue-router\|createRouter\|defineStore" 在 frontend/{shared,standalone-web,plugin-page,tests} 下 0 命中。main.ts(4 行)从未 createPinia()。导航是 App.vue 里的 activeNav ref(:5102 setActiveNav)+ navigation-config.ts;状态管理是 206 个 ref + 203 个 computed 的巨型局部状态树。两个包在 node_modules 里占 1.1 MB(pinia 407 K + vue-router 691 K)。

迁移成本与收益评估:

方案 成本 收益 结论
引入 pinia store 需先在 main.ts 接入 createPinia();206 个 ref 要按域重新组织并改写全部 .value 访问路径;子组件要从 props/emit 改成 useXxxStore();现有 8 个 frontend/tests/*.mjs 全是源码正则匹配,重构后批量红 跨组件状态共享、devtools 时间旅行 ❌ 本项目是嵌入式插件页、无 SSR、无跨路由状态共享需求,store 的核心卖点都用不上
按 feature 抽 composable 与仓库现有 features/*/xxx-state.ts(如 advanced-material-state.ts)的组织方式一致;每个 composable 返回自己的 state + actions,App.vue 只负责组装;可增量进行,一次一个 feature 同样解决"改一个功能要打开 22,563 行文件";不引入新的心智模型 ✅ 推荐

行动:删 pinia 与 vue-router 依赖(源码 0 行受影响),按 2.1.2 表 C 的清单逐个抽 composable。

2.5 package.json 依赖分类错误(已核实)

"dependencies": {
  "@vitejs/plugin-vue": "^5.2.0",
  "pinia": "^2.3.0",
  "typescript": "^5.7.0",
  "vite": "^6.0.0",
  "vue": "^3.5.0",
  "vue-router": "^4.5.0",
  "vue-tsc": "^2.2.0"
},
"devDependencies": {}

devDependencies 是空对象,typescript(23 MB)/ vite(2.7 MB)/ vue-tsc / @vitejs/plugin-vue 这些纯构建期工具全在 dependencies。

插件发布只带预构建产物(web/、pages/imagestudio/),运行期完全不需要 node_modules——严格说 7 个依赖全部应该是 devDependencies。

"dependencies": {},
"devDependencies": {
  "@vitejs/plugin-vue": "^5.2.0",
  "typescript": "^5.7.0",
  "vite": "^6.0.0",
  "vue": "^3.5.0",
  "vue-tsc": "^2.2.0"
}

同步更新 package-lock.json。收益:npm ci --omit=dev 变得有意义;SCA/许可证扫描不再把 23 MB 的 TypeScript 编译器算作运行期依赖;不再有人以为项目有路由和 store。


第三部分 · 仓库卫生

3.0 数据

项 规模 是否已跟踪
.tmp/ 2.1 GB / 6,303 文件 否(.gitignore: .tmp/ 生效)
根目录 .tmp_pytest_* 19 个目录 / ≈515 MB 否(.gitignore: .tmp_pytest*/ 生效)
release/ 20 个 zip / 38 MB 是
.git 51 MB —

.tmp/ 里有 8 个整仓库快照、22 个部署归档、~60 个一次性 fix_*.py / patch_*.py 脚本(说明有大量修补动作发生在版本控制之外)、40+ 个 pytest 输出目录。deploy-1.0.35 之所以 496 MB,是因为它把根目录的 .tmp_pytest_* 一起复制了进去——直接导致 nas-deploy-worktree-20260724.tar 达到 546 MB(正常插件包约 8 MB,膨胀 68 倍),3,000+ 个 pytest 临时文件被 scp 到 NAS。

3.1 ⚠️ 先做这一步:.tmp/ 里 19 个 tar 包含真实密钥

与 02 号报告呼应。 .env.imagestudio_codex_handoff.yaml 已被 gitignore、从未入库、不在 git 历史里(git ls-files | grep -i env 为空,git log --all --diff-filter=A 确认),但审计实测确认它被整目录复制进 8 个 deploy-* staging 目录,并被打进 19 个 .tar.gz / .tar 部署包,而 .tmp/ 里的 deploy_remote.sh / upload_via_ssh.py 会把这些包 ssh/scp 推送到 NAS。

文件内含(仅描述类型、长度与前 4 位,绝不复述真实值):

凭据 类型 特征
模型站点 A 的 API Key OpenAI 兼容 key 67 位,前 4 位 sk-3
模型站点 B 的 API Key OpenAI 兼容 key 51 位,前 4 位 sk-B
PostgreSQL 连接 host / port / user / 明文口令 内网地址
AstrBot 管理员 token HS256 JWT 136 位
AstrBot 管理员账号 用户名 + 明文口令 永不过期,可随时重签 JWT

讽刺的是文件末尾还写着 rules.redact_secrets: true。

顺序不能颠倒:先轮换,再删除,最后清 NAS。

# 第 1 步:轮换(在删除任何东西之前)
#   - 两个模型站点的 API Key 作废重发
#   - PostgreSQL 用户改密
#   - AstrBot 管理员改密,并更换 JWT secret 使现有 token 失效

# 第 2 步:确认工作树干净,先看清楚要删什么
git status --porcelain
Get-ChildItem .tmp -Recurse -File -Force -Filter '.env*' | Select-Object FullName, Length
Get-ChildItem .tmp -File -Force | Where-Object { $_.Name -match '\.(tar|tar\.gz|zip|b64)$' } |
  Select-Object Name, @{n='MB';e={[math]::Round($_.Length/1MB,2)}}

# 第 3 步:安全删除含密钥的归档与 staging 目录(先覆写再删,避免被恢复)
Get-ChildItem .tmp -Recurse -File -Force -Filter '.env*' | ForEach-Object {
  $len = $_.Length
  [System.IO.File]::WriteAllBytes($_.FullName, (New-Object byte[] $len))
  Remove-Item $_.FullName -Force
}
Remove-Item -Recurse -Force .tmp

# 第 4 步:清理根目录 pytest 临时目录(≈515 MB)
Get-ChildItem . -Directory -Force -Filter '.tmp_pytest*' | Remove-Item -Recurse -Force
Remove-Item -Recurse -Force .pytest_cache -ErrorAction SilentlyContinue
Get-ChildItem . -Directory -Recurse -Force -Filter '__pycache__' |
  Where-Object { $_.FullName -notmatch 'node_modules' } | Remove-Item -Recurse -Force

第 5 步(必须做):到 NAS 上删除已上传的同名包。 本地删除不影响已推送出去的副本。

第 6 步:从源头杜绝。 打包脚本改用 git archive,不再"复制工作树":

git archive --format=tar.gz --prefix=astrbot_plugin_imagestudio/ \
  -o dist/plugin-$(git describe --always).tar.gz HEAD
# 末尾加断言,让泄漏在打包阶段就 fail
tar -tf "$OUT" | grep -qE '(^|/)\.env' && { echo "SECRET LEAK"; exit 1; }

第 7 步:pytest 临时目录统一出口,避免再散落到仓库根(.gitignore 里 .pytest_tmp*/ 规则已存在):

[tool.pytest.ini_options]
addopts = "-q --basetemp=.pytest_tmp"

第 8 步:凭据改为环境变量注入。 _conf_schema.json 里已经有 *_api_key_env_var 字段,说明设计上本就支持——文件里只留 env var 名。

3.2 release/ 停止跟踪(-38 MB 库内)

现状:git ls-files release/ = 20 个 zip / 38 MB,占已跟踪文件体积的大头。更糟的是 astrbot_plugin_imagestudio-1.0.0.zip ~ 1.0.6.zip 每个 4.2 MB,里面装的是运行期数据:

data/temp/provider_probe_B_image2_generation.json   1.76 MB  (真实模型响应,含 b64 图片)
data/temp/provider_probe_B_image2_generation.png    1.32 MB
data/temp/s81_provider_runtime_b.png                0.76 MB
data/db/imagestudio.db                              0.29 MB  (真实 SQLite 库)

这与 DEVELOPMENT.md 自己写的"测试可使用临时目录,且不能把真实运行数据加入发布包"直接冲突。

.gitignore 补丁(只加 release/,见 3.4 的警告):

# 发布产物:用 Git Release / 附件分发,不入库
release/

停止跟踪但保留本地文件:

git rm -r --cached release
git commit -m "chore: stop tracking release archives"

做完这一步,clone 不再拉新的 release 包,但历史里的 38 MB 仍在。

3.3 从历史中剥离 release/(git filter-repo)—— 代价与风险

git rm --cached 只影响未来。要真正把 .git 从 51 MB 降下来,必须改写历史。

# 需先安装 git-filter-repo(pip install git-filter-repo)
# 强烈建议先做一份完整备份
cp -r "AstrBot ImageStudio" "AstrBot ImageStudio.backup"

git filter-repo --path release --invert-paths
git gc --aggressive --prune=now
git push --force --all
git push --force --tags

必须写清楚的代价:

风险 说明
所有现有 clone 立刻失效 每一个 commit SHA 都会改变。团队每个人必须重新 clone,或执行 git fetch && git reset --hard origin/<branch>;任何未推送的本地分支需要 git rebase --onto 手工迁移
引用旧 SHA 的一切都会断 Issue/PR 里的 commit 链接、CHANGELOG 里的 SHA、部署脚本里钉死的 commit、git describe 生成的版本号
需要 force push 若远端启用了分支保护,需要临时解除;解除期间任何人推送都会造成混乱
早期 zip 里的真实数据不可撤销地存在于所有已有克隆中 imagestudio.db 与 provider probe 响应已经分发出去过。改写历史只能防止未来的克隆拿到,不能收回已分发的副本。若这些数据敏感,需按数据泄漏流程处理,而不是只当成仓库瘦身

判断:这是单人/小团队仓库(git user: <ADMIN_USERNAME:已脱敏>),force push 的协调成本低。建议做,但严格按顺序:① 先完成 3.1 的密钥轮换(不要在历史改写的混乱期同时处理凭据);② 备份;③ 通知所有持有 clone 的人;④ 执行;⑤ 验证 git log --oneline | wc -l 与关键 tag 仍在。

如果不想改写历史,至少跑一次 git gc --aggressive --prune=now 回收部分空间——但 release/ 的 38 MB 是可达对象,gc 收不回来。

3.4 ⚠️ 不要把 web/assets 和 pages/imagestudio/assets 加进 .gitignore

经复核推翻:原始材料(C3)建议在 .gitignore 里加 web/assets/ 和 pages/imagestudio/assets/,并断言这两个目录是"误提交的编译产物"、"两份重复 dist"、"每次提交 2MB 噪音淹没 diff"。复核逐条查证后推翻:

  1. 这两个目录是 INSTALL.md 的"最小运行时清单"与"发布包白名单"明确定义的发布负载,与 main.py、metadata.yaml 并列。安装期没有 npm/vite 步骤。加进 .gitignore 会让 WebHostingService._resolve 抛 RESOURCE_NOT_FOUND, "web asset not built",插件页面全线不可用。
  2. "两份重复"不成立——两份构建的 base 不同且必须不同,挂载于不同 URL 根,一份产物物理上无法同时服务两个挂载点。
  3. "2MB 噪音"与实测差一个数量级:最近 5 次 dist 提交的实际 stat 是 24 files changed, 59 insertions(+), 69 deletions(-)(878f1f6)、24 files changed, 37 insertions(+), 27 deletions(-)(2dbf90b)——git 的重命名检测把内容哈希改名识别成 {index-CumvEEtc.js => index-CvjPX4dT.js},压缩产物是单行文件,每次只有几十行 diff。
  4. "git 累积大量永不复用的 blob"的归因也错了:size-pack 44 MB,而 release/ 光当前树就占 37 MB——仓库体积的主因是 release 包,不是 web/assets。

.gitignore 补丁只加 release/ 一行。 同理,DEVELOPMENT.md 里"生产构建必须同时提交 pages/imagestudio/ 的最新插件页面产物"这句是对的,不要改。

真正值得补的是构建新鲜度校验(历史上有 24 次只更新 web/assets、3 次只更新 pages/imagestudio/assets 的提交),加进 CI:

npm run build            # = build:plugin && build:web
git diff --exit-code web pages || { echo "构建产物未与源码同步提交"; exit 1; }

3.5 其余卫生项

项 位置 动作
4 份根目录 v3 设计文档已过期 imagestudio_api_contract_v3_ui_adjusted.md、imagestudio_codex_hermes_dev_flow_v3.md、imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md、imagestudio_ui_navigation_queue_s130.md 写于 2026-07-04~06,而 metadata.yaml 已是 1.0.72,中间隔了 70 个版本 / 约 230 次提交。git mv 到 docs/archive/ 并在每份开头加一行归档说明
未入库的测试文件 tests/test_prompt_expansion_stage_guard.py(git status 显示 ??) 60 行 / 2 个用例,与它守护的 backend/services/prompt_expansion_service.py 改动一起提交——现在随时会被 git clean 抹掉
编码损坏 config.yaml(54 处私有区字符)、metadata.yaml:5 short_desc(1 处,插件市场直接展示)、CHANGELOG.md(649 处) 中文被 GBK 误解码后再存成 UTF-8,已不可逆。手工重写 config.yaml 与 metadata.yaml 优先(config.yaml 那 54 处注释是各字段语义的唯一文档);DEVELOPMENT.md 的 Windows 章节写明:写文件一律 Out-File -Encoding utf8,禁止裸 > 重定向
无 CI 无 .github/、无 Makefile、无任何 workflow DEVELOPMENT.md 的"验证"只有 compileall,一个测试都不跑,而且它引用的 scripts 目录不存在(Can't list 'scripts' 但退出码仍是 0,静默通过)。加最小 CI:python -m pytest -q + npm run typecheck + npm run test:contracts,20 秒出结果
21 个测试文件重复内联同一套 SQLite 夹具 tests/test_resource_access_service.py:15-77 及其余 20 个 建 tests/conftest.py(顺带解决 3.1 里 pytest 的 sys.path 问题),提供 sqlite_db / storage_config / ctx 三个 fixture
测试硬 import Pillow tests/test_material_vision_input.py:6(from PIL import Image) requirements.txt 零依赖且明确写着"为保持插件默认零依赖,不在这里强制安装 Pillow"。业务代码遵守了(软导入),测试没有——干净环境里整个 263 个用例套件一起挂。改成 pytest.importorskip("PIL"),并新建 requirements-dev.txt
assert 被当运行期保护 backend/services/wardrobe_service.py:128(delete_item 的并发保护) python -O 下 assert 会被整体剥除,保护直接消失。 换成显式 if ...: raise ApiError(...)。同处的衣柜分类还缺白名单校验
.part 临时文件残留 backend/services/material_service.py:326 replace() 失败时 .part 文件留在存储根,无任何清理,长期累积。改为 try/finally 中 missing_ok=True 删除
PG 迁移执行器按分号裸切分 database/db_helper.py:280 迁移脚本里出现函数体、DO $$ ... $$ 或字符串内分号即被切错并静默执行半条语句。与 02 报告 P1-8 的 PG 兼容性一并验证
路由正则未 re.escape adapters/astrbot_adapter.py:226(_match_endpoint) 端点模板含正则元字符时会产生非预期匹配。与 02 报告 §6 的路由表预编译缓存(astrbot_adapter.py:47)同一处改

上表后 4 行与其余若干条跨维度漏收项,完整清单见 02-BUG清单.md 的 §6.1 终审补录。


第四部分 · 不建议做的事

判断力体现在知道哪些"看起来能精简"的地方不该动。以下每一条都有明确理由。

4.1 不要合并 engines/ 的四个 flow 文件

single_flow.py(455)与 review_flow.py(451)是真正的引擎,与其它 flow 零重复。character_flow.py(145)/ fast_character_flow.py(50)/ quick_profile_flow.py(32)是纯声明式节点模板目录,三者真正重复的只有约 11–15 行的列表推导样板,而它们的 metadata 契约各不相同(stage_code + canonical_node_key + per-step node_type 覆盖 vs quick_character_target vs profile_draft/profile_preview)。抽公共构造器要引入配置参数把差异重新表达出来,代码量不降、理解成本上升,还把三种工作流的演进耦合在一起。当前"声明数据与业务逻辑分离、每种工作流一个独立目录"的形态是对的。

4.2 不要忽略 web/ 与 pages/imagestudio/

见 3.4。这是被复核推翻的原始建议,照做会让插件页面全线不可用。

4.3 不要合并 plugin-page 与 standalone-web 的双构建

见 2.3。重复代码量实测为 0 行——plugin-page/src/App.vue 只有 7 行 re-export。两份 vite.config.ts 的 base 差异是功能性的,不是冗余。

4.4 不要为了删代码而引入 pinia

见 2.4。pinia 在依赖里但零使用,正确的处理是删掉它而不是"既然装了就用起来"。嵌入式插件页、无 SSR、无跨路由状态共享,store 的核心卖点全用不上;引入它意味着 206 个 ref 全部改写 + 8 个源码正则测试批量红。走 composable 路线,与仓库现有 features/*/xxx-state.ts 的组织方式一致。

4.5 不要把 _string_list 的 17 处无脑合并成一个函数

见 1.3。它们语义确实不同(是否切逗号 / 是否去重 / 是否排序 / 是否收 tuple-set),17 个调用点分别依赖各自的行为。合并成一个"统一实现"会静默改变其中一部分调用点的输出。正确做法是拆成三个语义显式命名的函数,逐处判断该用哪个。这也是它优先级排在 P3、放在工具函数收敛最后做的原因。

4.6 不要在补齐路由层测试之前动 @route_handler 装饰器

见 1.13。148 个 handler 的 service= 参数是现有测试的注入点,而路由层测试本身就薄。先加 1.14 的注册表契约测试(一次覆盖 166 条,成本极低),再谈重构。

4.7 不要为了"减行数"去压行

App.vue:4549-4559、components/MaterialDetailDialog.vue:34-58、features/settings/BackupPage.vue:14-25、features/settings/ReviewPolicyPanel.vue:14(整个 <style scoped> 是一行 1,000+ 字符)已经是压行风格:

// App.vue:4549 —— 与文件其余部分的 Prettier 风格冲突
const prompt=imageGenerationPrompt.value.trim()
if(!prompt||promptExpansionBusy.value)return
...
}catch(err){imageGenerationError.value=`提示词扩写失败:${errorMessage(err)}`}finally{promptExpansionBusy.value=false}

这让行数统计失真、git diff 一行全红/全绿无法审查、无法用 lint 自动格式化。正确方向是反过来——引入 Prettier(printWidth: 110,与现有多数代码一致)把它们展开。 展开后 CSS/TS 总行数会上升约 800 行,但这是把隐藏的复杂度显性化,后续所有重复检测与删除都会更可靠。先展开、再统计、再删除,否则"精简"的账面收益是假的。

4.8 不要删 requeue_dead_letters / update_pool_preferences 之前不问

这两个在 1.6 的死代码表里,但它们看起来是产品功能(死信重入队、候选池偏好)。删之前先确认是"计划中但没做完"还是"已废弃"。如果是前者,转成 issue 再删代码——不要留半成品在代码库里冒充已交付功能,但也不要在没人确认的情况下直接删掉某人正在做的东西。

4.9 不要把 backend/routes/params.py 直接当成共享工具模块

params.py 里确实有想要的实现(optional_str / optional_text),但它在 backend/routes 包下。让 database/repositories/ 和 engines/ 去 import backend.routes.* 是层级倒置——数据层依赖路由层。新建 core/coerce.py 才是对的落点(见 1.2)。同样的教训已经发生过一次:backend/services/workflow_round_worker_runtime.py:10 反向 from backend.routes.node_routes import create_generation_service。

4.10 不要在 App.vue 拆分时"顺手"照搬 displayMediaUrl

见 2.1.2 的 C4 说明。把一个带副作用的伪纯函数原样搬进 composables/useMediaUrls.ts,只会让 O(N²) 重算和 Blob 无界累积藏得更深、更难被发现。拆分是修它的机会,不是搬运它的借口。