astrbot_plugin_imagestudio/审计/findings/A3-素材与风格集.md

445 行
38 KiB
Markdown

# A3 — 素材库 / 高级风格集 / 衣柜 / 素材绑定
> 审计范围(实际逐行读过的文件):
> - `backend/services/advanced_style_set_service.py`(4491 行,全量结构 + 重点方法)
> - `backend/services/advanced_material_service.py`(1856 行)
> - `backend/services/material_service.py`(1087 行)
> - `backend/services/material_normalization_service.py`(411 行,全文)
> - `backend/services/material_binding_schema_service.py`(408 行,全文)
> - `backend/services/material_catalog_resolver.py`(210 行,全文)
> - `backend/services/material_analytics_service.py`(173 行,全文)
> - `backend/services/wardrobe_service.py`(511 行,全文)
> - `backend/services/workflow_node_material_service.py`(503 行,全文)
> - `backend/services/asset_import_service.py`(406 行,全文)
> - `database/repositories/advanced_material_repository.py`(2123 行,结构 + 关键事务/CRUD)
> - 关联交叉验证:`backend/services/workflow_service.py`(`_normalized_metadata` / `_sync_material_bindings_from_node`)、`backend/services/generation_reference_service.py`、`backend/routes/asset_routes.py`、`core/storage.py`、`database/db_helper.py`、`database/migrations/0009|0016|0018*.sql`
## 摘要
这一块的**安全底线基本守住了**:存储 URI 有 `split_uri` + `resolve_uri` 双重防越权,上传走魔数嗅探(`detect_image_format`)而不是信任 `content_type`,生成时解析素材引用会二次校验 `recognition_status == "confirmed"`,`MaterialCatalogResolver` 用不可序列化的属性标记做信任边界,SQLite 已开 `PRAGMA foreign_keys = ON`(级联删除真的生效)。这块代码不是"随手写"的。
但存在**三处真实可触发的缺陷**:(1) `normalize_material_bindings` 对携带正确 `schema_version` 的载荷完全跳过归一化,后续索引函数直接 `rule["target_node_keys"]` 取键,构造一条空规则即可让 `material_bind` 节点被永久毒化(每次更新必 500,且节点元数据已先落库);(2) 资产包导入把清单里的 `material_id` / `recognition_status` 当作可信输入,能静默覆盖已有素材并把未经识别的素材直接写成 `confirmed`;(3) `normalize_category` 用 `alias in text` 子串匹配做分类推断,"landscape" 会被判成 headwear、"rooftop" 会被判成 top。另有一处统计口径完全失效(`workflow_kind` 常量对不上,风格集导入数恒为 0)。
**性能/内存**方面有两处全表加载:`AdvancedMaterialService.list_catalog` 每次分页请求都把两个素材表整表读入内存再切片;`MaterialService.list_materials` 一旦带高级筛选也整表加载。`_reconcile_import_task` 在列表接口里对每个 import 的每个 source/case 单独查队列,是典型 N+1,且 `get_import` 会重复对账两次。
**精简空间很大**:`advanced_style_set_service.py` 4491 行里,类体 2091 行(32 个方法,其中 `_execute_consensus` 单个方法 467 行)、模块级函数 2092 行(81 个纯函数)。这 81 个函数按职责天然分成"提示词编译""风格评审打分""文本安全清洗""证据校验"四组,可无风险拆成 4 个模块;仓库层 12 组实体的 `create/get/list/update/update_if_status` 是几乎逐字复制的连接-提交-回滚模板;`_optional_text` 在 backend/database 下被重复定义 **28 次**,`_string_list` 17 次,`_json_or_none` 13 次。
---
## 发现
### [P1-严重] 素材绑定 schema 校验可被 `schema_version` 直接绕过,并导致 `material_bind` 节点被永久毒化
- **位置**:`backend/services/material_binding_schema_service.py:47`(绕过)、`:326`(KeyError)、`backend/services/workflow_service.py:729`(先落库后同步)
- **问题**:`normalize_material_bindings` 的第一分支只要客户端载荷里 `schema_version` 等于常量值,就 `deepcopy` 原样返回,**完全跳过 `_normalize_rule` 归一化**;随后仅重建 `by_node_id`,而重建路径 `_index_by_node_id` → `_index_by_node_key` 直接对未归一化的 rule 做 `rule["target_node_keys"]` 下标取键。客户端提交 `{"schema_version": "2026-07-09.material-binding-schema.v1", "active_rules": [{}]}` 即触发 `KeyError`。更严重的是 `WorkflowService.update_node` 在 **第 729 行已经把节点元数据写库成功**,第 732 行才调用 `_sync_material_bindings_from_node`,异常发生时脏数据已持久化,此后对该 `material_bind` 节点的每一次更新都会重复走同一路径而 500。
- **代码**:
```python
# material_binding_schema_service.py:47-58
if isinstance(payload, dict) and payload.get("schema_version") == MATERIAL_BINDING_SCHEMA_VERSION:
normalized = deepcopy(payload)
if workflow_nodes:
rules = normalized.get("active_rules")
if not isinstance(rules, list):
rules = [rule for rule in normalized.get("rules", []) if isinstance(rule, dict) and rule.get("use_reference")]
normalized["by_node_id"] = _index_by_node_id(rules, workflow_nodes)
return normalized # <- rules 从未被 _normalize_rule 处理
# material_binding_schema_service.py:326-331
def _index_by_node_key(rules: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
result: dict[str, list[dict[str, Any]]] = {}
for rule in rules:
for node_key in rule["target_node_keys"]: # <- KeyError,非 .get()
result.setdefault(canonical_gradual_node_key(node_key), []).append(rule)
```
```python
# workflow_service.py:729-733
after = self.workflow_repository.update_node(node_id, update_payload) # 已提交
if after is None:
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": node_id})
self._sync_material_bindings_from_node(after) # 才在这里炸
```
- **影响**:任意登录用户可用一次 PUT 让某个 `material_bind` 节点变成"只能读、不能改"的死节点(每次 `update_node` 都 500)。同时该分支意味着绑定规则里的 `material_id` / `prompt` / `reference_strength` 都是未经校验的原样存储——虽然 `GenerationReferenceService._resolve_material_references`(`generation_reference_service.py:88-104`)在生成时补校验了素材存在性与 `confirmed`,堵住了引用图泄露,但 `prompt` 字段仍会经 `prompt_expansion_service._material_prompt_parts` 被拼进最终提示词,等于一条未经素材库校验的任意文本注入通道。
- **修复建议**:
1. 删掉整个 fast-path,或至少把它降级为"仍然逐条 `_normalize_rule`,只跳过 `by_stage/by_node_key` 的重复计算";
2. `_index_by_node_key` / `_node_view` 改用 `rule.get("target_node_keys") or []`、`(rule.get("material") or {}).get("prompt")`;
3. 把 `_sync_material_bindings_from_node` 的归一化提到 `update_node` 写库**之前**(先 `normalize_material_bindings(payload["metadata"]["material_bindings"], nodes)`,校验通过再写节点),归一化失败抛 `ApiError(VALIDATION_FAILED)` 而不是让 `KeyError` 逃逸成 500。
---
### [P1-严重] 资产包清单可静默覆盖已有素材,并把未识别素材直接写成 `confirmed`
- **位置**:`backend/services/asset_import_service.py:141`、`:340`、`:361`
- **问题**:`_apply_manifest` 用清单里显式给出的 `material_id`(`_material_id` 优先取 `item["material_id"] or item["id"]`)去查库,命中已存在的素材就走 `update_material` **整体覆盖**(`display_name`/`image_uri`/`prompt`/`tags`/`metadata`/`recognition_status` 全被替换)。同时 `recognition_status` 直接取自清单,`MaterialService._validate_status` 只检查它属于 `MATERIAL_STATUSES` 集合,因此清单写 `"recognition_status": "confirmed"` 就能造出一条**从未经过任何 VLM 识别、prompt 完全由清单作者指定**的"已确认"素材。
- **代码**:
```python
# asset_import_service.py:141-153
existing = self.material_service.repository.get_material(material_payload["material_id"])
if existing is not None:
self.material_service.get_material(material_payload["material_id"])
self.material_service.validate_material_payload(material_payload, creating=existing is None)
planned_materials.append((material_payload, existing is None))
...
else:
material = self.material_service.update_material(material_payload["material_id"], material_payload, ctx)
# asset_import_service.py:340
"recognition_status": _optional_text(item.get("recognition_status")) or "pending_recognition",
# asset_import_service.py:361-366
def _material_id(item, package_uri, manifest_uri, index, image_uri) -> str:
explicit = _optional_text(item.get("material_id") or item.get("id"))
if explicit:
return explicit # <- 清单完全掌控目标 ID
```
- **影响**:`confirmed` 是整条生成链路的信任标记——`generation_reference_service.py:95` 和 `workflow_node_material_service.py:293` 都只认这一个状态。一个从外部下载的资产包(清单内容对操作者不透明)导入后,既能悄悄改写用户手工确认过的素材(连 `normalized_asset_profile` 一起被清掉),又能把任意 prompt 文本 + 任意存储根下的图片直接注入受信任素材目录。`_asset_uri`(`:352-358`)还允许清单写 `storage://<任意根>/...` 绕过包目录范围。
- **修复建议**:
- 导入产生的素材 ID 一律服务端生成(走 `_material_id` 的 sha1 分支),清单里的 `material_id` 只用作包内去重键,不用作库内主键;
- 覆盖已有素材必须显式确认(`payload["allow_overwrite"]` + 只允许覆盖同一 `metadata.asset_pack.package_uri` 来源的素材);
- `recognition_status` 从清单里**移除**,导入一律落 `pending_recognition`;
- `_asset_uri` 对 `storage://` 前缀的值校验其 root 必须等于包所在 root,且 relative 必须在 `base_relative` 之下。
---
### [P2-中等] `normalize_category` 用子串匹配推断类别:"landscape" → headwear,"rooftop" → top
- **位置**:`backend/services/material_normalization_service.py:314`(配合 `:190`、`:342`)
- **问题**:`normalize_category` 遍历 `CATEGORY_ALIASES` 做 `if alias in text` 的**裸子串包含**判断,而 `_build_profile` 在既无 `value["category"]` 又无 `category_hint` 时会把 `tags + prompt` 拼成一整段自由文本喂进来(`_category_from_text` 就是 `" ".join(...)`)。别名表里有 `"top"`、`"cap"`、`"ring"`、`"hat"`、`"boot"` 这类高频子串。
- **代码**:
```python
# material_normalization_service.py:190
category = normalize_category(value.get("category") or category_hint or _category_from_text([*tags, prompt]))
# material_normalization_service.py:314-321
def normalize_category(value: Any) -> str:
text = _text(value).lower().replace("_", " ").strip()
if text in ASSET_CATEGORIES:
return text
for alias, category in CATEGORY_ALIASES.items():
if alias in text: # <- 子串包含,无词边界
return category
return "other"
# material_normalization_service.py:342
def _category_from_text(values: list[str]) -> str:
return " ".join(_text(item) for item in values)
```
实测(按 dict 声明顺序):`"wide landscape background"` → 先不命中 `top`/`ring`/`hat`,命中 `"cap"`(在 `landscape` 中)→ **headwear**;`"a girl standing on a rooftop"` → 命中 `"top"` → **top**;`"spring flowers"` → 命中 `"ring"` → **jewelry**。
- **影响**:`CATEGORY_SEMANTICS[category]` 直接决定 `role` / `body_slots` / `wear_layer`(`:191`),一个背景素材会被打成"头部配饰、accessory 层",进而污染 `_matches_material_filters` 的 `body_slot`/`wear_layer` 筛选(`material_service.py:1070-1072`)和 `CompositionBuilder` 的槽位冲突判定。用户在"衣柜/素材库"里按部位筛选会查不到自己的素材,且看不出原因。
- **修复建议**:把别名匹配改成词边界匹配,并按别名长度降序尝试:
```python
_ALIAS_PATTERNS = sorted(CATEGORY_ALIASES.items(), key=lambda kv: -len(kv[0]))
def normalize_category(value):
text = _text(value).lower().replace("_", " ").strip()
if text in ASSET_CATEGORIES:
return text
for alias, category in _ALIAS_PATTERNS:
if re.search(rf"(?<![A-Za-z0-9]){re.escape(alias)}(?![A-Za-z0-9])", text):
return category
return "other"
```
(CJK 别名无需词边界,可按 `alias.isascii()` 分两路。)另外建议 `_build_profile` 不再拿整段 prompt 去猜类别,只在 tags 上猜。
---
### [P2-中等] `list_catalog` 每次分页请求都把两张素材表整表读入内存
- **位置**:`backend/services/advanced_material_service.py:605`、`:636`、`:646`
- **问题**:接口签名带 `page/page_size` 且上限 200,看上去是分页的;实现却先 `_all_advanced_materials()` + `_all_standard_materials()` 把两个表**全部**行取出、全部 `to_dict()`(含 `metadata_json`/`capsule_json` 反序列化),拼成 `merged` 后再内存切片。
- **代码**:
```python
# advanced_material_service.py:608-628
advanced = self._all_advanced_materials()
standard = self._all_standard_materials()
advanced_items = [{**item.to_dict(), "library_kind": "advanced", ...} for item in advanced if item.status == "active"]
standard_items = [{**item.to_dict(), "library_kind": "standard", ...} for item in standard if item.recognition_status == "confirmed"]
merged = [*advanced_items, *standard_items]
offset = (normalized_page - 1) * normalized_size
return {"items": merged[offset : offset + normalized_size], ...}
# advanced_material_service.py:646-654
def _all_standard_materials(self) -> list[Material]:
result: list[Material] = []
page = 1
while True:
items, total = self.material_repository.list_materials(page=page, page_size=100)
result.extend(items)
if len(result) >= total or not items:
return result
page += 1
```
- **影响**:素材库到几千条时,每次翻页都是 N/100 次 SQL + N 次 JSON 反序列化 + 全量 dict 构造。进阶素材的 `metadata` 里还嵌着 `style_set.validation_cases`(三条完整 case 的 `to_dict()`,见 `advanced_style_set_service.py:1160`),单条就是几十 KB。前端每翻一页就重跑一次,很容易把插件进程的内存和 SQLite 打满。同样的模式也出现在 `material_service.py:188-216`(一旦带 `color/body_slot/wear_layer/min_confidence` 等高级筛选就整表加载再过滤)和 `material_service.py:423-434`(`renormalize_batch` 无参时整表加载)。
- **修复建议**:把过滤和排序下推到 SQL。两库合并可以用 `UNION ALL` + 统一 `(priority DESC, accepted_at DESC)` 排序在数据库层做 `LIMIT/OFFSET`;如果暂时不想动 SQL,至少改成"先各取 `offset+page_size` 条(仓库层已支持 `page_size` 上限 200),再归并取前 `page_size` 条",避免全表物化。`_matches_material_filters` 里的 `body_slot`/`wear_layer`/`confidence` 都存在 `metadata_json` 里,可以用 SQLite 的 `json_extract` 建生成列 + 索引。
---
### [P2-中等] 素材统计里的风格集口径完全失效:`workflow_kind` 常量对不上,导入数恒为 0
- **位置**:`backend/services/material_analytics_service.py:168`,对照 `backend/services/advanced_style_set_service.py:55` 与 `:389`
- **问题**:`_is_style_set_metadata` 判断 `workflow_kind == "style_set"`,而实际写入的常量是 `STYLE_SET_KIND = "advanced_style_set"`。它的第二、三个兜底条件(`metadata["style_set"]` 是 dict / 是 True)只有**已封存的进阶素材**满足(`accept()` 在 `advanced_style_set_service.py:1153` 写了 `"style_set": {...}` 字典);`advanced_material_imports` 行的 metadata 只有 `workflow_kind`、`style_source_count`、`generation_model_route`、`governance_context`、`material_tier`、`upload`(见 `:388-395`),**没有任何 `style_set` 键**。
- **代码**:
```python
# advanced_style_set_service.py:55
STYLE_SET_KIND = "advanced_style_set"
# advanced_style_set_service.py:388-395(导入行 metadata,无 style_set 键)
"metadata": {
"workflow_kind": STYLE_SET_KIND,
"style_source_count": len(persisted),
"generation_model_route": generation_route,
...
},
# material_analytics_service.py:168-173
def _is_style_set_metadata(metadata: dict[str, Any]) -> bool:
return (
str(metadata.get("workflow_kind") or "").strip().casefold() == "style_set" # 永远 False
or isinstance(metadata.get("style_set"), dict)
or metadata.get("style_set") is True
)
```
- **影响**:`summarize()` 返回的 `advanced_style_sets.imports` 和 `advanced_style_sets.accepted_imports` **恒为 0**(`style_set_import_rows` 永远是空列表,见 `:95-97`、`:127-128`),而同一份响应里 `sources` / `consensus_runs` / `validation_cases` 却是真实数量。看板上会出现"0 个风格集导入,却有 24 个源图识别"的自相矛盾数据,且没有任何报错提示。
- **修复建议**:`material_analytics_service.py` 直接从 `advanced_style_set_service` 导入 `STYLE_SET_KIND`,把第一个条件改成 `== STYLE_SET_KIND.casefold()`(保留旧值 `"style_set"` 作为兼容分支)。更根本的做法是把"是否风格集"下沉成 `advanced_material_imports` 的一个真实列(如 `workflow_kind TEXT`),别再用 JSON 里的约定字符串在三个模块间对暗号。
---
### [P2-中等] 导入列表接口的队列对账是 N+1,且单条详情会重复对账两次
- **位置**:`backend/services/advanced_material_service.py:212`、`:220`,`backend/services/advanced_style_set_service.py:456`、`:474`、`:551`
- **问题**:`list_imports` 对本页每一条 import 调 `_reconcile_import_task`;风格集分支进入 `reconcile_missing_tasks`,它对**每个 source、每个 consensus run、每个 attempt 下的每个 case** 各调一次 `_task_missing` → `queue_service.get_job(task_id)`(一次独立 SQL + 独立连接)。一个 8 源图的风格集,单条记录就是 1(list sources)+8(get_job)+1+K+1(list attempts)+M×(1+3) 次查询;`page_size` 默认 30、上限 100。此外 `get_import` 在第 221 行已经 `_reconcile_import_task(...)` 对账过一次,第 224 行的 `self.style_sets.detail(record)` 在 `advanced_style_set_service.py:456` 又 `record = self.reconcile_missing_tasks(record)` **完整重跑一遍**。
- **代码**:
```python
# advanced_material_service.py:212 / 220-224
reconciled = [self._reconcile_import_task(item) for item in items]
...
record = self._reconcile_import_task(self._require_import(import_id)) # 第 1 次
attempts = self.repository.list_attempts(import_id)
is_style_set = self.style_sets.is_style_set(record)
style_detail = self.style_sets.detail(record) if is_style_set else {} # detail() 内部第 2 次
# advanced_style_set_service.py:551-558
def _task_missing(self, task_id: str | None) -> bool:
if not str(task_id or "").strip():
return True
try:
self.queue_service.get_job(str(task_id)) # 每个子任务一次独立查询
except ApiError:
return True
return False
```
另外 `get_import` 第 259-262 行对 `accepted_material_id` 也是查两次(条件里查一次、取值再查一次)。
- **影响**:进阶素材工作台的列表页在有几十个风格集时会产生上千次 SQLite 查询;SQLite 在 `busy_timeout=30000` 下与生成 worker 的写事务竞争,很容易表现为"素材页面转圈几秒"。而且这是**读接口带写副作用**(会把 source/case 状态改成 failed 并改 import 状态),并发列表请求之间存在重复写。
- **修复建议**:
1. `detail()` 增加 `reconcile: bool = True` 参数,`get_import` 传 `False`,消除重复对账;
2. `_task_missing` 批量化:给 `QueueService` 加 `get_jobs(task_ids: set[str]) -> dict[str, Job]`,一次 `WHERE task_id IN (...)` 拿全,`reconcile_missing_tasks` 先收集所有 task_id 再一次查;
3. 列表接口不做对账,改由后台定时任务或显式的"刷新"动作触发,避免读接口写库。
---
### [P2-中等] 衣柜导入把所有 `sqlite3.IntegrityError` 一律当成"重复条目"
- **位置**:`backend/services/wardrobe_service.py:94`、`:379`
- **问题**:`_is_unique_constraint_error` 对 SQLite 分支只判断 `isinstance(exc, sqlite3.IntegrityError)`,而这个异常类型同时覆盖 UNIQUE、FOREIGN KEY、NOT NULL、CHECK 全部约束违规(PG 分支反倒精确匹配了 `23505`)。`wardrobe_items.material_id` 有 `FOREIGN KEY(material_id) REFERENCES materials(material_id)`(`database/migrations/0009_wardrobe_items.sql`),而 `_repository_for_material_id`(`:328-335`)只有在 `advanced_wardrobe_repository` 与 `material_catalog` **都不为 None** 时才把 `advmat_*` 路由到进阶表——否则进阶素材 ID 会被写进标准 `wardrobe_items` 表,必然触发外键违规。
- **代码**:
```python
# wardrobe_service.py:94-97
except Exception as exc:
if not _is_unique_constraint_error(exc):
raise
raise _duplicate_wardrobe_item_error(profile_id, material_id, wardrobe_category) from None
# wardrobe_service.py:379-382
def _is_unique_constraint_error(exc: Exception) -> bool:
if isinstance(exc, sqlite3.IntegrityError): # UNIQUE / FK / NOT NULL 全中
return True
return getattr(exc, "sqlstate", None) == "23505" or getattr(exc, "pgcode", None) == "23505"
# wardrobe_service.py:328-335
def _repository_for_material_id(self, material_id: str) -> WardrobeRepository:
if (self.advanced_wardrobe_repository is not None
and self.material_catalog is not None
and str(material_id or "").startswith("advmat_")):
return self.advanced_wardrobe_repository
return self.wardrobe_repository
```
- **影响**:外键违规被伪装成 `VALIDATION_FAILED "material already exists in wardrobe category"`。用户看到"素材已在该分类中",去衣柜里找却找不到,反复重试也永远失败,日志里也不留原始异常(`from None`)。以字符串前缀 `advmat_` 决定写哪张表本身也是脆弱耦合。
- **修复建议**:`_is_unique_constraint_error` 改为检查 `"UNIQUE constraint failed" in str(exc)`(SQLite)或 `sqlite3.IntegrityError` 且 `getattr(exc, "sqlite_errorcode", None) == sqlite3.SQLITE_CONSTRAINT_UNIQUE`(Py3.11+);非唯一约束一律 `raise`。仓库路由改用 `MaterialCatalogResolver` 返回的 `metadata["library_kind"]`(已由 `material_catalog_resolver.py:113-188` 在服务端赋值,不可被用户元数据伪造)而不是 ID 前缀。
---
### [P2-中等] `update_material` 中的结构校验会把 `MaterialNormalizationError` 泄漏成 500
- **位置**:`backend/services/material_service.py:246`
- **问题**:`validate_material_payload`(`:276-280`)已经把 `MaterialNormalizationError` 转成 `ApiError(VALIDATION_FAILED)`,但紧接着 `update_material` 里的第二处 `validate_material_structures(metadata)` **没有** try/except。该分支在 payload 顶层直接带 `raw_analysis` / `normalized_asset_profile` / `generation_capsules` 时触发(不是放在 `metadata` 里)。
- **代码**:
```python
# material_service.py:240-247
structured_keys = {"raw_analysis", "normalized_asset_profile", "generation_capsules"}
if structured_keys & update_payload.keys():
metadata = {**before.metadata}
for key in structured_keys:
if key in update_payload:
metadata[key] = update_payload.pop(key)
validate_material_structures(metadata) # <- 抛 MaterialNormalizationError(ValueError),无捕获
update_payload["metadata"] = metadata
```
- **影响**:`PATCH /materials/{id}` 带一个 `{"normalized_asset_profile": {"category": "bogus"}}` 就返回 500 而不是 400,前端拿不到可读的字段级错误,且服务端日志被无意义的堆栈刷屏。同类问题还在仓库层:`advanced_material_repository.py:2078-2089` 的 `_json_object` / `_json_list` 对损坏的 JSON 列直接 `json.loads` 抛 `JSONDecodeError`,一条脏行会让整个列表接口 500。
- **修复建议**:把这里也包成
```python
try:
validate_material_structures(metadata)
except MaterialNormalizationError as exc:
raise ApiError(ErrorCode.VALIDATION_FAILED, str(exc), {"field": "metadata"}) from None
```
并把这段"提取结构键 → 合并 → 校验"的逻辑与 `validate_material_payload` 合并成一个函数,避免两处各写一遍校验。
---
### [P2-中等] Pillow 缺失时,风格集共识会把多张原图以 base64 全量载入单个请求
- **位置**:`backend/services/material_service.py:786`(降级分支)、`backend/services/advanced_style_set_service.py:1447`
- **问题**:`_optimized_vision_input` 在模块顶部 `except ImportError: Image = None`(`material_service.py:13-16`,注释明说 standalone 用户可能没有 Pillow),此时**原样返回**最多 20 MB 的原始字节,`_storage_image_data_url` 再对其做 base64(约 ×1.34)。`_execute_consensus` 的无对比分支会对**全部 succeeded 源图**逐张调用它并放进 `image_urls` 列表。
- **代码**:
```python
# material_service.py:786-787
if Image is None:
return content, content_type # 20 MB 原样返回
# advanced_style_set_service.py:1446-1449
else:
for source in sources:
image_url, _, _ = _storage_image_data_url(source.source_image_uri, {}, self.storage)
image_urls.append(image_url)
```
- **影响**:风格集允许 2–8 张源图(`MIN_STYLE_SOURCES=2 / MAX_STYLE_SOURCES=8`),无 Pillow 时单个 worker 任务峰值常驻 8 × (20 MB 原始 + 27 MB base64) ≈ 375 MB,还要整体 `json.dumps` 进 `VisionRecognitionRequest.prompt`。作为 AstrBot 插件与宿主同进程运行,这足以 OOM 掉整个 bot。
- **修复建议**:为"送进模型的图"设一个独立于存储上限的硬上限(例如 `VISION_INPUT_MAX_BYTES = 3 MB`):Pillow 可用时缩放后仍超限则继续降质;Pillow 不可用且原图超限时直接抛 `ApiError(UPLOAD_TOO_LARGE)` 并提示安装 Pillow,而不是静默把巨图塞给 provider。共识阶段还应改成流式逐张编码 / 用完即弃,而不是先把 8 张全部物化成列表。
---
### [P2-中等] `advanced_style_set_service.py` 是典型 god object:4491 行 = 2091 行类体 + 2092 行模块函数,可无风险拆成 5 个模块
- **位置**:`backend/services/advanced_style_set_service.py:306`(类起点)、`:1347`(467 行的单个方法)、`:2399`–`:4491`(81 个模块级函数)
- **问题**:实测结构为 32 个方法 / 81 个模块函数;最长方法 `_execute_consensus` 单体 **467 行**,`_execute_validation_case` 220 行,`_queue_validation_batch` 161 行。类通过 `self.owner` 反向持有 `AdvancedMaterialService` 的 8 个协作者(`:309-318`),而 `AdvancedMaterialService.__init__` 又持有 `AdvancedStyleSetService`(`advanced_material_service.py:118`)——**双向循环引用**,两边互相调私有方法(`self.owner._require_import` / `self.owner._govern_validation_prompt` / `self.owner._generation_route`)。
- **代码**:
```python
# advanced_style_set_service.py:309-318
def __init__(self, owner: Any):
self.owner = owner # 无类型标注的反向引用
self.repository = owner.repository
self.material_repository = owner.material_repository
self.queue_service = owner.queue_service
self.audit_service = owner.audit_service
self.storage = owner.storage
self.normalization_service = owner.normalization_service
self.model_provider_runtime = owner.model_provider_runtime
self.single_flow_engine = owner.single_flow_engine
# advanced_material_service.py:118
self.style_sets = AdvancedStyleSetService(self)
```
- **影响**:`_execute_consensus` 里 text_only / 单次多图 / 分组两阶段三条 provider 调用路径与状态机、错误分类、图片编码、提示词组装全部纠缠在一个函数里,任何一条分支的改动都要重读 467 行;单元测试只能通过完整 mock `owner` 来构造,实际上 `tests/` 里对这段的覆盖只能走端到端。`Any` 类型的 `owner` 让 IDE 与类型检查完全失效。
- **修复建议**(按依赖方向拆,都是纯搬运,无行为变更):
1. `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 行,全是纯函数);
2. `style_text_sanitizer.py` ← `_sanitize_minor_age_text` / `_strip_mature_body_locks` / `_normalize_style_prompt_conflicts` / `_clean_prompt_text` / `_apply_semantic_risk_rewrites` 及其正则常量(约 400 行);
3. `style_review_scoring.py` ← `_normalize_style_dimension_scores` / `_weighted_style_fidelity_score` / `_cap_inconsistent_dimension_scores` / `_aggregate_style_review_feedback` / `STYLE_REVIEW_*` 常量(约 400 行);
4. `style_evidence.py` ← `_normalized_feature_evidence` / `_style_trait_is_supported` / `_prompt_traits_overlap` / `_extract_head_ratio_range` 系列(约 300 行);
5. 剩余的类拆成 `StyleSourceStage` / `StyleConsensusStage` / `StyleValidationStage` 三个协作者,各自只接收显式依赖(repository、queue、storage、runtime),把 `owner: Any` 换成一个明确的 `StyleSetRuntime` Protocol(只暴露 `require_import` / `generation_route` / `govern_validation_prompt` 等 6 个方法),消除双向引用。
`_execute_consensus` 内部按 `text_only` / `single_pass` / `grouped_two_stage` 拆三个私有方法,共用一个 `_persist_consensus_result`。
---
### [P3-轻微] 仓库层 12 组实体的 CRUD 模板逐字复制,`_optional_text` 在项目里被定义了 28 次
- **位置**:`database/repositories/advanced_material_repository.py:559`/`:646`/`:698`/`:752`/`:837`/`:1159`(同构 CRUD),`:2092`(第 N 份 `_optional_text`)
- **问题**:`create_style_source` / `create_style_consensus_run` / `create_attempt` / `create_material` 是同一段 `conn = self.database.connect(); try: conn.execute(INSERT...); conn.commit(); except: _rollback(conn); raise; finally: conn.close()` 的复制;`update_style_source` / `update_style_consensus_run` / `update_style_validation_case` / `update_attempt` / `update_import` 是同一段 `_update_assignments(...) → 追加 updated_at → 连接执行 → 回读` 的复制;`update_*_if_status` 又是 update 版本加一段 `AND status IN (...)` 与 `rowcount` 判断的复制。全仓 `def _optional_text(` 出现 **28** 次、`def _string_list(` **17** 次、`def _json_or_none(` **13** 次,逻辑完全一致。
- **代码**:
```python
# advanced_material_repository.py:683-696(update_style_source)
conn = self.database.connect()
try:
conn.execute(f"UPDATE advanced_style_sources SET {', '.join(assignments)} WHERE source_id = {self.placeholder}", tuple(params))
conn.commit()
except Exception:
_rollback(conn)
raise
finally:
conn.close()
return self.get_style_source(source_id)
# 上面 14 行在本文件里出现 6 次,仅表名/主键列/回读函数不同
```
- **影响**:主要是维护成本与一致性风险——例如"`status == 'succeeded'` 时自动补 `completed_at`"的规则在 `update_style_source`(:677)和 `update_style_source_if_status`(:729)里各写了一遍,将来只改一处就会产生行为分叉。同时每个方法都自开自关连接,一次 `reconcile_missing_tasks` 会开关几十个 SQLite 连接。
- **修复建议**:
1. 抽 `_ExecutionMixin`(或模块级 `def _write(self, sql, params)` / `def _write_if(self, sql, params) -> int`)承载连接-提交-回滚-关闭,各 CRUD 只提供 SQL 与参数;
2. 抽 `_EntitySpec(table, pk, columns_map, row_factory, json_fields, int_fields)`,把 `create/get/list/update/update_if_status` 做成泛型方法,12 组实体只保留各自的 spec 常量;
3. 把 `_optional_text` / `_string_list` / `_json_or_none` / `_optional_int` / `_optional_float` / `_page` / `_page_size` 统一收进 `core/coercion.py`(或 `database/_coerce.py`),全仓改为 import。仅这一项就能删掉数百行重复代码。
4. 同类问题在服务层:`advanced_material_service.py` 与 `advanced_style_set_service.py` 各有一份 `_safe_failure` / `_optional_score` / `_optional_text` / `_string_list`。
---
### [P3-轻微] `advanced_style_set_service` 从 `material_service` 导入 7 个下划线私有函数,上传校验层没有公共 API
- **位置**:`backend/services/advanced_style_set_service.py:33`、`backend/services/advanced_material_service.py:27`
- **问题**:两个服务都跨模块 import 了 `material_service` 的私有名。这些函数(data URL 解码、文件名/大小/内容类型归一、存储图转 data URL)实际上是整个素材域的**公共上传校验契约**,却因为下划线命名而对静态检查器和 IDE 表现为"不应被外部使用"。
- **代码**:
```python
# advanced_style_set_service.py:33-41
from backend.services.material_service import (
_normalize_upload_content_type,
_normalize_upload_filename,
_normalize_upload_metadata,
_normalize_upload_size,
_recognition_metadata,
_storage_image_data_url,
_vision_provider_error,
)
```
- **影响**:任何人重构 `material_service` 内部时不会预期这些名字有外部调用方;同时 `advanced_material_service` 与 `advanced_style_set_service` 在上传校验上出现了细微分叉(`material_service.upload_material:314` 用 `UPLOAD_ALLOWED_CONTENT_TYPES[detected].__contains__` 校验扩展名,`_persist_source:1571-1579` 却自己维护了一张 `{(".jpg",".jpeg")}` 别名表),说明契约已经开始漂移。
- **修复建议**:新建 `backend/services/material_upload_contract.py`,把这 7 个函数 + `MAX_UPLOAD_BYTES` / `UPLOAD_ALLOWED_*` 常量迁过去并改成公共名(`normalize_upload_filename` 等),三个服务统一 import;同时把 `_persist_source` 的扩展名别名逻辑合并进 `validate_upload_file_type`,消除两套判定。
---
### [P3-轻微] 衣柜分类与删除路径的两个小缺口
- **位置**:`backend/services/wardrobe_service.py:58`、`:128`
- **问题**:
1. `wardrobe_category` 只校验"非空",不校验是否属于 `DEFAULT_WARDROBE_CATEGORIES`(`:31`)。由于唯一索引是 `(profile_id, material_id, wardrobe_category)`,同一素材可以用 `"top"`、`"Top"`、`"上衣 "`(尾空格已 strip)、`"随便写"` 等无限多个分类反复导入,绕过重复检查;而 `match()` 只按 `DEFAULT_WARDROBE_CATEGORIES` 或调用方传入的分类查,这些条目永远匹配不到,成为衣柜里的僵尸数据。
2. `delete_item` 用 `assert deleted is not None` 断言仓库删除结果。`assert` 在 `python -O` 下会被完全剥离,且并发删除(两个请求同时删同一条)时第二个会命中 `AssertionError` → 500 而不是 404。
- **代码**:
```python
# wardrobe_service.py:58-66
wardrobe_category = str(payload.get("wardrobe_category") or "").strip()
if not wardrobe_category:
raise ApiError(ErrorCode.VALIDATION_FAILED, "wardrobe_category is required", {"field": "wardrobe_category"})
# 之后再无任何白名单校验
# wardrobe_service.py:128-129
deleted = repository.delete(wardrobe_item_id)
assert deleted is not None
```
- **影响**:脏分类导致衣柜条目数虚高、`list_items` 返回一堆永不参与匹配的项;`assert` 在并发下把预期内的竞态变成 500。
- **修复建议**:`wardrobe_category` 归一化为小写并校验 `in DEFAULT_WARDROBE_CATEGORIES`(若需要自定义分类,改为从 profile 元数据里读用户自定义白名单)。`assert` 替换为:
```python
if deleted is None:
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "wardrobe item not found", {"wardrobe_item_id": wardrobe_item_id})
```
---
### [P3-轻微] 归档素材在标准库与进阶库产生两种不同的错误语义
- **位置**:`backend/services/material_catalog_resolver.py:75`,`backend/services/generation_reference_service.py:89`
- **问题**:`MaterialCatalogResolver.get_material` 对 `advmat_*` 显式过滤 `status != "active"` 返回 `None`;对标准素材则不看 `recognition_status`,归档素材照样返回 DTO。下游 `_resolve_material_references` 因此给出两种错误。
- **代码**:
```python
# material_catalog_resolver.py:75-81
if normalized_id.startswith(ADVANCED_MATERIAL_ID_PREFIX):
advanced = self.advanced_materials.get_material(normalized_id)
if advanced is None or advanced.status != "active":
return None # -> 404 "does not exist"
material = self.materials.get_material(normalized_id)
return self._normal_material(material) if material is not None else None
# 归档的标准素材 recognition_status == "archived" -> 走到下面的 confirmed 检查
# generation_reference_service.py:95-104 -> 400 "reference material is not confirmed"
```
- **影响**:同样是"用户把素材删了",进阶素材报 404「素材不存在」,标准素材报 400「素材未确认」。用户会误以为标准素材只是没确认,跑去重新识别,结果 `MaterialService.get_material`(`material_service.py:232`)又把归档素材当作不存在,形成前后矛盾的提示闭环。
- **修复建议**:在 `_normal_material` 之前补一行 `if material.recognition_status == "archived": return None`,让两库语义一致;同时给 `_resolve_material_references` 的 404 分支加上 `"reason": "material_missing_or_archived"` 细节字段,前端可据此直接提示"该素材已被删除,请重新绑定"。