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_none13 次,而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.py4,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 |
同步做两件事:
owner: Any换成一个StyleSetRuntimeProtocol,只暴露require_import/generation_route/govern_validation_prompt等 6 个方法,消除双向引用。_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 迁移的前置,先做它:
styles/tokens.css(当前仅 24 行)扩成真正的 token/utility 层:.u-truncate、.u-eyebrow、.u-stack-4、.u-cover-img、.u-btn-primary。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.ts6 行。- 两份
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"。复核逐条查证后推翻:
- 这两个目录是
INSTALL.md的"最小运行时清单"与"发布包白名单"明确定义的发布负载,与main.py、metadata.yaml并列。安装期没有 npm/vite 步骤。加进.gitignore会让WebHostingService._resolve抛RESOURCE_NOT_FOUND, "web asset not built",插件页面全线不可用。- "两份重复"不成立——两份构建的
base不同且必须不同,挂载于不同 URL 根,一份产物物理上无法同时服务两个挂载点。- "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。- "git 累积大量永不复用的 blob"的归因也错了:
size-pack44 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 无界累积藏得更深、更难被发现。拆分是修它的机会,不是搬运它的借口。