# 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(` 泛型写法) | **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`,同文件两个相邻方法逐字节同构): ```python 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` 属性一并收敛。 ```python 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` 早就有: ```python # 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 份语义不同**: ```python # 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 处。 **四种同名不同义的实现**: ```python # 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` 这个名字本身: ```python 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` 起),说明是分批粘贴出来的。 ```python # 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 ``` **做法**:命令名 → 目标方法的映射抽成一张表,类装饰器生成别名: ```python _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`。 ```python # 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()`**: ```python # 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()`): ```python # 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`: ```python 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 行。 更麻烦的是**双向循环引用**: ```python # 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 固定四段式: ```python # 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` 就是这种双真相结构的产物。 ```python @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 做这些之前先加的两条保护 ```python # 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` 能跑: ```toml # 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**: ```bash 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) | | `