885 行
70 KiB
Markdown
885 行
70 KiB
Markdown
# 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`,同文件两个相邻方法逐字节同构):
|
||
|
||
```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) |
|
||
| `<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` 的契约测试习惯:
|
||
|
||
```js
|
||
// 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` 忘了加分支就会静默错判成"日志面板开着":
|
||
|
||
```ts
|
||
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](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` 依赖分类错误(已核实)
|
||
|
||
```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。**
|
||
|
||
```json
|
||
"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。**
|
||
|
||
```powershell
|
||
# 第 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`,不再"复制工作树":
|
||
|
||
```bash
|
||
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*/` 规则已存在):
|
||
|
||
```toml
|
||
[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 的警告**):
|
||
|
||
```gitignore
|
||
# 发布产物:用 Git Release / 附件分发,不入库
|
||
release/
|
||
```
|
||
|
||
**停止跟踪但保留本地文件**:
|
||
|
||
```bash
|
||
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 降下来,必须改写历史。
|
||
|
||
```bash
|
||
# 需先安装 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:
|
||
|
||
```bash
|
||
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](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+ 字符)已经是压行风格:
|
||
|
||
```ts
|
||
// 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 无界累积藏得更深、更难被发现。**拆分是修它的机会,不是搬运它的借口。**
|