(endpoints.workflow(activeWorkflowId), {
status: "failed", metadata: { ...(latestFailedWorkflow.workflow.metadata ?? {}), quick_character_failure: message },
})
```
**已漂移/已失效的具体后果**:用户在生成过程中刷新页面或关标签页,工作流永久停留在 `draft` / `running`,**没有任何服务端兜底把它推到终态**——数据库里会累积僵尸工作流。复核逐条确认了这条兜底缺失:`workflow_routes.py:79-84` 的 `start_workflow` 只改状态不托管推进;唯一自动推终态的 `_advance_character_gradual_progression`(`workflow_service.py:760-802`)在 `:766` 被 `workflow_type != "character_gradual"` 排除,而快速角色流是 `character_fast`;`recover_stale_tasks` 是 task 级且只认 `source="workflow_round"`;`App.vue:5816` 传 `forceNew: true` 使每次被中断的运行都新增一条 `draft` 记录,**累积是真实的**。
> **经复核降级为 P2 的理由(必须如实记录)**:初审附加的"metadata 契约完全由前端定义、后端被动接收"**被推翻**。`workflow_service.py:64-72` 定义了 `QUICK_CHARACTER_IMMUTABLE_METADATA_KEYS`(`quick_character_identity_managed` / `quick_character_batch_id` / `identity_lock_hash` / `identity_lock` / `quick_character_route_snapshot` / `quick_character_target` / `quick_character_targets`),`:1032-1042` 对 `character_fast` **强制回填服务端值**,代码注释即 `Browser clients may PUT a stale whole metadata object after the four requests finish. Preserve server-owned batch identity and route fields once initialized so clients cannot clear or mutate the lock`。`anchor_image_id` 语义也由后端强校验(`generation_service.py:1337-1347` 直接抛 `quick-character downstream generation requires the avatar image_id as an identity anchor`,`:1299-1329` 还校验引用图归属与 batch/lock 一致)。真正纯前端定义的只有 `quick_character_pending_target_keys` / `generated_target_keys` / `quick_character_schema` 等展示字段。
>
> 综合:无数据丢失、无损坏、无鉴权问题;卡在 `running` 不阻断后续生成,用户还可通过 `App.vue:8312` 的 start/cancel/archive 手动收尾。实际代价是**工作流状态失真 + 僵尸记录累积**,定为 P2。
**收敛方案**:新增 `POST workflows/{id}/quick-character/run`,后端负责锚点优先 + 并行提交 + 状态推进 + 失败补偿;前端只提交一次请求,然后按 `workflowRoundIsActive` 的模式轮询状态。前端残留部分收进 `composables/useQuickCharacterGeneration.ts`。
---
### #2 · [P2,经复核降级] 顺序进度状态机复刻,且后端从不下发权威结果
- **前端**:`App.vue:10837-10859`(`:10843` 是其中一行),版本号字面量在 `App.vue:927`
- **后端权威**:`backend/services/workflow_progression_service.py:175`(函数定义)/ `:180-199`(函数体)
后端 `is_character_gradual_node_completed()` 是"节点是否已完成"的唯一权威判定,包含 status 白名单、node_type 特例、profile_card 别名归一、legacy 元数据兼容四层规则:
```python
# workflow_progression_service.py:180-199
if node.status in PROGRESSION_COMPLETED_NODE_STATUSES: # {"selected","skipped"}
return True
if node.status == "completed" and (
node.node_type in {"planning", "reference_binding"}
or canonical_gradual_node_key(node.node_key) == "profile_card"
):
return True
if allow_legacy_planning_metadata:
if node.node_key == "prompt_plan":
return "prompt_plan" in metadata and metadata.get("prompt_plan") is not None
if node.node_key == "material_bind":
return "material_bindings" in metadata and metadata.get("material_bindings") is not None
return False
```
前端逐条重写了这四层,连"legacy 兼容只对没有 `sequential-v1` 标记的工作流生效"这种极细的分支都手工复刻:
```ts
// App.vue:10843-10859
if (status === "selected" || status === "skipped") return true
if (status === "completed" && (backendNode.node_type === "planning" ||
backendNode.node_type === "reference_binding" ||
canonicalCharacterWorkflowNodeKey(backendNode.node_key) === "profile_card")) return true
const legacyProgression = isRecord(execution) && execution.progression_version !== CHARACTER_WORKFLOW_PROGRESSION_VERSION
if (!legacyProgression) return false
if (backendNode.node_key === "prompt_plan") return backendNode.metadata?.prompt_plan != null
if (backendNode.node_key === "material_bind") return backendNode.metadata?.material_bindings != null
```
**根因**:后端从不下发进度。`node_routes.py:52-63` 的列表接口只返回裸节点数组;全仓 `progression.to_dict()` 只有一个调用点——`character_workflow_service.py:339`(`execute-character` 的响应体),列表接口拿不到。
**风险**:后端改一条进度规则(给 `style_lock` 加完成条件、或让 `skipped` 不再算完成),前端不报错也不失效,只会静默地在"下一步该点哪个节点"上给出与服务端相反的答案:UI 显示节点可用 → 用户点击 → 后端 `ensure_character_gradual_node_access` 抛 `character_gradual_progression_locked`;反向则是 UI 灰掉一个后端允许的节点。
> **经复核降级为 P2 的理由**:复核逐条核实了四项事实(两份实现、版本号字面量重复、`list_workflow_nodes` 无 `progression` 字段、`progression.to_dict()` 唯一调用点在 `character_workflow_service.py:339`),并进一步排除了"前端可改读元数据快照"这条反驳路径(`character_execution_metadata()` 只在 execute-character 路径落库,节点逐个完成后必然过期)。**根因成立、无守卫消解。** 但降级理由是:`ensure_character_gradual_node_access`(`workflow_progression_service.py:104-172`)在服务端**硬兜底**强制抛 `character_gradual_progression_locked`,前端偏差**无法被用来绕过规则**;且两份实现当前语义**完全等价**。因此这是"UI 与服务端可能不一致"的可维护性缺陷,不涉及越权或数据损坏,定为 P2。
**收敛方案**:
```python
# backend/routes/node_routes.py —— list_workflow_nodes 返回体加 progression
def action() -> dict[str, Any]:
require_authenticated(ctx)
nodes = workflow_service.list_nodes(workflow_id)
workflow = workflow_service.get_workflow(workflow_id)
progression = character_gradual_progression(workflow, nodes)
return {
"items": [n.to_dict() for n in nodes],
"progression": progression.to_dict() if progression else None,
}
```
`CharacterGradualProgression.to_dict()` 已经现成(含 `current_node_id` / `completed_node_ids` / `all_completed` / `import_confirmed`)。前端删除 `App.vue:10836-10861` 与 `:927`,改为 `progression.completed_node_ids.includes(node.node_id)`。返回结构变更需同步 `frontend/shared/types/workflow.ts` 并升 `contract_version`。
---
### #3 · [P3,经复核降级] 节点写锁规则不一致,且前端判据里有一个后端从不产出的字段
- **前端**:`frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27`(`sealed_at` 在 `:12`)
- **后端权威**:`backend/services/workflow_round_service.py:1145-1155`
```ts
// workflow-lock-state.ts:8-27
export function isWorkflowSealed(workflowStatus, metadata) {
const status = normalizedStatus(workflowStatus)
return (
status === "archived" || status === "cancelled" ||
Boolean(metadata?.final_archive_history_id || metadata?.sealed_at) // ← :12 sealed_at
)
}
export function isWorkflowNodeWriteLocked(nodeStatus, workflowStatus, workflowMetadata) {
return normalizedStatus(nodeStatus) === "selected" || isWorkflowSealed(workflowStatus, workflowMetadata)
}
```
```python
# workflow_round_service.py:1145-1155
if node.status == "selected" or node.selected_image_id or (
progression is not None and node.node_id in progression.completed_node_ids
):
raise ApiError(ErrorCode.VALIDATION_FAILED,
"confirmed workflow node is locked; create a branch before adding another round",
{"node_id": node.node_id, "required_action": "create_branch"})
```
**可举证的分歧(已按复核结论修正)**:
1. **真实且可达**:`node.selected_image_id` 已设但 `status != "selected"` 时,前端认为可写并放行"再跑一轮",后端 `:1145` 返回 `VALIDATION_FAILED / required_action: create_branch`。
触发路径是 `backend/services/image_service.py:150-159` 的 `select_image` —— 它**只**写 `update_node(after.node_id, {"selected_image_id": after.image_id})` 而不改 `status`,且 `:249-255` 的守卫明确放行 `completed`(`if node.status in LOCKED_NODE_STATUSES and node.status != "completed"`,注释自称这是 "tentative selection" 设计)。用户入口是 `GalleryPage.vue:121` 的批量"标记选中"按钮。
> **⚠️ 初审引用的 `adopt-image` 路径是错的,已删除。** 复核实测 `backend/services/history_service.py:55` 一次性写入两个字段 `{"status": "selected", "selected_image_id": image.image_id}`,采用路径**两边一致、不产生分歧**;`generation_service.py:473/955` 生成候选时写死 `"is_selected": False`,正常轮次流程也不会凭空产生 `selected_image_id`。
2. **仅理论洞**:`progression.completed_node_ids` 那一条对 `node_type == "generation"` 的节点实际只剩 `status in {"selected","skipped"}` 一种可能(planning / reference_binding / profile_card 与 legacy 分支都不适用于生成节点),因此额外差异仅是 `"skipped"`,而 **UI 未提供把生成节点置为 skipped 的入口**。
3. `metadata.sealed_at` 是永远为 `undefined` 的**死判据**。`[实测]` `grep -rn "sealed_at" --include=*.py`(排除 `.tmp/`、`release/`)返回 **0 命中**——它只存在于前端与前端测试里,给读代码的人制造"存在这个封存机制"的错觉。但它是 OR 链里的恒 undefined 项,**只可能"多加锁"不可能"漏加锁"**,行为上无副作用,属代码卫生问题。
**经复核降级为 P3 的理由**:分歧客观存在且路径 1 可达,但 (a) 可达路径窄(需走图库批量标记选中);(b) **"用户看到无法自恢复的报错"不成立** —— `App.vue:7788-7795` 的 `actionableWorkflowApiError` 会读 `err.details.required_action`,`:7783` 已有映射 `create_branch: "当前节点已锁定或工作流已封存,请先创建可编辑分支"`,用户拿到的是**带明确恢复指引的中文提示**,且 `WorkflowBranchPanel` 提供建分支入口;(c) 方向上前端偏宽松、后端为权威判定,属 fail-safe,不涉及数据损坏、越权或状态不一致落库。
**收敛方案**:把锁状态改为服务端下发而非客户端推导。最小改动是给 `WorkflowNode.to_dict()` 增加 `writable: bool` 与 `lock_reason: str | None`——`WorkflowNodeMaterialBindingDetail` 已经有 `writable` + `lock` 结构可直接复用同一形状(`frontend/shared/types/workflow.ts:108-123`);前端 `workflow-lock-state.ts` 退化为读 `node.writable`。**若暂不改协议,至少立刻做两件事:删掉 `sealed_at`、把 `isWorkflowNodeWriteLocked` 的签名扩成接收整个 backend node 并加上 `Boolean(node.selected_image_id)`。**
---
### #4 · [P3,经复核降级] 快速角色提示词指令表在前后端各写一份
- **前端**:`App.vue:6126`(`instructions` 表)、`:6100-6118`(`quickCharacterIdentityFields`)
- **后端权威**:`character_workflow_service.py:280-285`(`_step_instruction` 的 `fast` 表)
```ts
// App.vue:6126
quick_avatar: "square avatar, close-up portrait, clear face, stable hair and eye details",
```
```python
# character_workflow_service.py:280
"quick_avatar": "square avatar, face, hair, eyes, expression, keep identity consistent",
```
**已漂移的具体差异**:4 条短指令措辞不同;前端 `quick_avatar` 丢掉了后端写的 `keep identity consistent`。
**经复核降级的理由(必须如实记录)**:初审把这条定为 P1,声称"身份一致性不可复现 / prompt 治理被绕过"。复核逐条推翻:
- 前端 `quickCharacterIdentityFields()` 产出的是**原始字段值**,作为 `identity_fields` 上传,这正是后端 `build_identity_lock()`(`quick_character_consistency.py:56-68`)明文定义的输入契约——别名归一、`_normalize_gender`/`_normalize_age_group`、canonical 字段集、锁文案与 `identity_lock_hash` **全部仍在后端**,前端没有复制任何一张别名表。
- `generation_service.py:691` 对**每个** quick-character 节点无条件套用服务端身份锁,代码注释明写此意图(`Direct mode intentionally bypasses LLM rewriting, but it must never bypass the immutable server-owned character identity lock.`);锁文案强度比前端那句高一个数量级,且 `identity_lock_hash()` 对 canonical JSON 做 sha256,一致性是**确定性可复现**的。
- `_govern_prompt()`(`:1456`)显式读取前端串做审核与路由裁决,`route.allowed` 为假时抛 `VALIDATION_FAILED` 阻断——治理照常作用于前端串。
**残留真实问题**:4 条短指令字符串在前后端各写一份、措辞已漂移的 **DRY 瑕疵**。
**收敛方案**:删除 `App.vue:6126` 的 `instructions` 表与身份约束前缀,只把结构化字段(`identityFields`、`materialPrompts`、用户 patch)作为 payload 传给 `endpoints.nodeGenerate`,由后端 `_step_instruction()` + `build_identity_lock()` 组装。若前端确实需要预览,新增一个只读的 `POST prompts/preview` 端点返回后端组装结果。
---
### #5 · [P3,经复核降级] 模型路由解析链在前端重实现
- **前端**:`frontend/standalone-web/src/features/workflow/workflow-model-route.ts:33-88` + `App.vue:2211-2245`
- **后端权威**:`generation_service.py:169-176`(普通节点)、`:617-624`(快速角色,优先级反转)、`:2026-2038`(`node_key → assignment` 映射)
```python
# generation_service.py:169-176 —— 普通节点
requested_model_route = str(payload.get("model_route") or node.model_route or assigned_route
or profile_model_route or self.default_model_route or "image_low")
# :617-624 —— 快速角色:assigned_route 抢在 payload.model_route 之前
if quick_character:
route_candidate = str(assigned_route or payload.get("model_route")
or profile_model_route or self.default_model_route or "image_low")
```
```ts
// workflow-model-route.ts:36-48 —— 单链,多了 round 层,无 image_low 兜底,无 quick_character 分支
const candidates = [["override", input.overrideRoute], ["round", input.roundRoute],
["node", input.nodeRoute], ["assignment", input.assignmentRoute],
["profile", input.profileRoute], ["system", input.systemRoute]]
```
**经复核降级的理由**:初审定 P1,声称"快速角色流模型标签会说谎"。复核逐条推翻:
- **"前端多了 round 层"是错的**——`workflow_round_service.py:596-597` 确实有 `本次覆盖 → 父轮次冻结路由` 这一层,前端是如实镜像。
- **"少了 image_low 兜底"是刻意设计**——`workflow-model-route.ts:28-31` 注释明写 `Mirrors the server-owned route chain without inventing a frontend default.`,返回空值被上游当硬闸门用(`App.vue:8492-8495` 直接拒绝提交并给出文案)。硬编码 `image_low` 反而会让 UI 声称一个后端可能拒绝的路由。
- **"快速角色标签说谎"不可达**——该标签链的输入来自 `selectedWorkflowBackendNode`,其 `workflowId` 字段四处赋值全部只可能是 `character_gradual`(`App.vue:4943-4954 / 7410-7419 / 9455 / 9489`),`quick_*` 节点永远不会成为 `selectedWorkflowBackendNode`。快速角色流有自己独立且**正确**的解析器(`App.vue:6086-6098`,与后端 `quick_generation` 映射完全对齐,为空时直接 `throw` 阻断提交)。
- 实际可达路径下前后端结论**完全一致**:gradual 的 7 个生图节点键在前端 `:76-84` 与后端 `:2026-2033` 逐条相同。
**残留真实问题**:前端存在一份重复的映射表 + 前端直接读取**配置文件原始结构**(`currentSettings.value.config.model_assignments`、`config.generation.default_model`,`App.vue:2218/2231-2233`)——后端改配置键名前端静默失准。这是**可维护性耦合,不是运行期缺陷**。
**收敛方案**:由 `generation_service` 抽出纯函数 `resolve_model_route(node, workflow, profile, assignments, default)`,同时供生成路径与新端点使用;在 `nodeDependencyContext` 响应里加 `{ effective_model_route, source }`。前端 `resolveWorkflowModelRoute` 只保留"用户 override 是否非空"的判断,删除 `workflow-model-route.ts:61-84` 的私有别名/分配表。
---
### #6 · [P3,经复核降级] retry 卡片的权限门禁写法不一致
- **前端**:`App.vue:2786`(`const canRetry = Boolean(permissions?.can_retry_tasks)`)+ `:3076` + `:3139`
- **后端权威**:`route_registry.py:22-27`(`"required_permissions": ["can_write", "can_retry_tasks"]`)+ `core/security.py:31-33`(`require_task_retry` 先 `require_write` 再 `require_permission`)
同文件 `:3373` 的队列面板反而写成了 `const canManageQueue = canWrite && canRetry`。
**经复核降级的理由**:初审定 P1「持有 `can_retry_tasks` 但无 `can_write` 的账号会看到可用按钮」。复核证明**该权限组合在本仓库造不出来**:
- `main.py:104-106` + `:2337`:`BRIDGE_PERMISSIONS = frozenset({"can_write","can_manage_config","can_manage_materials","can_retry_tasks"})`,`permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()` ——要么四个全给,要么一个不给;
- `chat_workflow_service.py:1160`:`{"can_write","can_retry_tasks","can_manage_materials"}`,同样含 `can_write`;
- `chat_command_guard_service.py:42`:空集。
且即便该组合存在,点击路径也有上游守卫:`App.vue:8560` 的 `backendWriteBlockMessage(...)` 里明确含 `if (!bootstrap.value?.permissions.can_write) return ...`,本地就拦下,根本不会发出请求。另外 `App.vue:3818-3821` 也是同样的 `canRetry`-only 写法,说明这是**节点级卡片的一贯约定**(写权限统一由 `backendWriteBlockMessage` 兜底),而 `:3373` 队列面板加 `canWrite` 是因为队列卡片直接调接口、没有同样的兜底函数——两类不同上下文。
**残留真实问题**:UI 文案精确性——`:3073-3074` 的 `canRetry ? "可重试" : "无权限"` 在一个当前造不出的权限组合下会显示乐观文案。无安全影响、无越权、无功能故障。
**收敛方案(依然值得做,因为它顺带解决整类问题)**:不要在前端逐个手写权限组合。`GET contract` 返回的 `routes[].required_permissions` 已经是完整数组:
```ts
const contractRoutes = new Map(contract.routes.map(r => [`${r.method} ${r.endpoint}`, r.required_permissions]))
function canCall(method: string, endpoint: string) {
return (contractRoutes.get(`${method} ${endpoint}`) ?? []).every(p => permissions?.[p])
}
```
所有按钮的 `enabled` 统一走 `canCall()`,权限矩阵从此不需要在前端复写。
---
### #7 · [P2] 队列状态枚举 4 处独立硬编码
```python
# backend/services/queue_service.py:31-34 —— 后端唯一真相
RETRYABLE_TASK_STATUSES = {"failed", "dead_letter", "cancelled"}
FAILED_TASK_STATUSES = ("failed", "dead_letter", "cancelled")
COMPLETED_TASK_STATUSES = ("completed", "succeeded", "superseded")
DELETABLE_TASK_STATUSES = frozenset((*FAILED_TASK_STATUSES, *COMPLETED_TASK_STATUSES))
```
前端四份拷贝:`App.vue:3285`(failed 集)、`App.vue:3293`(completed 集)、`App.vue:3628`(第五次内联 `["failed","dead_letter","cancelled"]`)、`frontend/shared/utils/presentation.ts:5`:
```ts
// presentation.ts:5 —— 与后端任何一个常量都不完全相等
const TERMINAL_JOB_STATUSES = new Set(["completed","succeeded","failed","cancelled","dead_letter","superseded"])
```
**风险**:`TASK_STATUSES`(`queue_service.py:18-29`)新增一个终态(例如 `expired`)时,后端会正确算进 `DELETABLE`,而前端四处判定全部漏掉:任务永远停在"运行中"分组、`waitTime()` 里 `terminal` 为 false 导致耗时读数无限增长、"清理终态任务"按钮的计数与后端实际清理数量对不上。
**收敛方案**:把四个集合加进 `GET ui/bootstrap` 返回体(`UiService.get_bootstrap` 已经在下发 `permissions` 和 `feature_flags`,加 `task_statuses: {retryable, failed, completed, terminal}` 是同性质元数据),前端建 `taskStatusSets.ts` 从 bootstrap 初始化。退一步至少合并成 `frontend/shared/config/task-status.ts` 一份,并加一条正则测试断言它与 `queue_service.py` 的字面量一致。
---
### #8 · [P2] 生成状态中文标签 4 张表,译法互相冲突
| 位置 | `planned` | `succeeded` | `retrying` | `dead_letter` |
|---|---|---|---|---|
| `App.vue:6927-6939` | 已规划 | 已成功 | **缺失**(显示英文原文) | **缺失** |
| `WorkflowCandidatePool.vue:132-145` | 待入队 | 已完成 | 重试中 | 重试耗尽 |
| `WorkflowRoundPanel.vue:113-129` | — | — | — | — |
| `presentation.ts:11-29` | — | 已成功 | 重试执行中 | 死信 |
同一个候选在候选池里显示「已完成」,在 App.vue 其它视图里显示「已成功」;`planned` 有「待入队」和「已规划」两种说法;重试中的候选在 App.vue 直接显示英文 `retrying`。
**收敛方案**:`frontend/shared/utils/presentation.ts` 增加 `export function generationStatusLabel(status: string)` 作唯一真源,覆盖 `planned|queued|running|retrying|succeeded|success|completed|failed|dead_letter|cancelled|superseded`,删掉三份局部表;轮次级状态(`partial_success|all_failed|confirmed`)另建 `roundStatusLabel` 一并放入。
---
### #9 · [P2] `route-chain:` 线格式编解码器被逐字移植到 TS
这不是"逻辑重复",而是**同一个序列化格式的两份独立实现**——前端写出的字符串要被后端解析。
```python
# core/model_route_chain.py:61-66
return ROUTE_CHAIN_PREFIX + json.dumps({"plugin": plugin_route, "astrbot": astrbot_route},
ensure_ascii=False, separators=(",", ":"), sort_keys=True)
```
```ts
// frontend/standalone-web/src/features/settings/model-route-chain.ts:33
return `${MODEL_ROUTE_CHAIN_PREFIX}${JSON.stringify({ astrbot, plugin })}`
```
目前能对上,靠三个巧合同时成立:Python `sort_keys=True` 产出 `astrbot` 在前 ≡ TS 对象字面量恰好写成 `{ astrbot, plugin }` 的插入顺序;`separators=(",", ":")` ≡ `JSON.stringify` 默认无空格;`ensure_ascii=False` ≡ `JSON.stringify` 默认不转义非 ASCII。
**风险**:把 TS 那行改成 `JSON.stringify({ plugin, astrbot })`(更符合语义直觉)就会产出不同字节序列。Python 端 `json.loads` 仍解析成功,**不会立刻报错**,但任何做字符串比较的地方(配置 diff、快照对比、`settings/diff`)会把"没变的配置"报成"变了"。现有 `tests/test_model_route_chain.py` 只验 Python 内部往返,**没有一条测试断言两语言的编码结果相同**。
**收敛方案**:加黄金样本测试固定线格式——Python 侧断言 `encode_model_route_chain("p","astrbot:a") == 'route-chain:{"astrbot":"astrbot:a","plugin":"p"}'`,TS 侧用**同一字符串**断言 `encodeModelRouteChain({plugin:"p",astrbot:"astrbot:a"})`,并加反向 `parse` 用例。更彻底的做法是别让前端编码:让 settings 保存接口接受 `{plugin, astrbot}` 结构体、由后端编码。
---
### #10 · [P2] legacy 节点别名表三份,两份前端拷贝互相冲突
```python
# engines/character_flow.py:15-20
LEGACY_CHARACTER_GRADUAL_NODE_KEYS = {
"half_body": "upper_body", "expression_sheet": "turnaround", # ← turnaround
"pose_sheet": "design_sheet", "final_pack": "profile_card"}
```
```ts
// workflow-node-catalog.ts:23-28 —— 与后端一致
expression_sheet: "turnaround",
```
```ts
// workflow-model-route.ts:61-74 —— 同一前端目录下的第三份,映射不同
expression_sheet: "design_sheet", // ← 与另两处冲突
```
另外 11 个节点的 `node_key` 与展示文案在 `engines/character_flow.py:22-115`(`CHARACTER_GRADUAL_STEPS`)和 `workflow-node-catalog.ts:64-153` 各存一份,中文标题也不同(后端"拆解人设/预选素材" vs 前端"LLM 拆解设定/参考素材绑定")。
**风险**:`expression_sheet` 的冲突目前不产生可见 bug(`turnaround` 与 `design_sheet` 恰好都映射到 `sheet_generation`),**这是巧合不是设计**。真正的风险是:`character_flow.py` 加一个新节点或改一个别名,前端两份表都不会更新,`workflowUiNodeIdForNodeKey` 返回 `undefined`,该节点在工作流面板**直接不显示**——用户看到的步骤列表比后端实际创建的节点少一个。
**收敛方案**:`ui/bootstrap` 或新增 `GET workflows/node-catalog` 下发 `gradual_node_templates()` + `LEGACY_CHARACTER_GRADUAL_NODE_KEYS`(后端已有 `gradual_node_templates()`,`character_flow.py:131-145`,几乎可以直接返回)。前端 `workflow-node-catalog.ts` 只保留纯展示增强(badge/phase/detail),键与别名从接口取;删除 `workflow-model-route.ts:61-74` 的私有表。
---
### #11 · [P2] `LONG_TASK_ENDPOINT` 正则重复两份,且固化了一个虚构契约
```ts
// client.ts:14 与 astrbot-page-bridge.ts:6 —— 逐字符相同的两份
const LONG_TASK_ENDPOINT = /(?:^|\/)(?:generate|retry|review|execute-character|expand|governance-preview|probe-provider|probe-model|recognize|re-recognize|renormalize|renormalize-batch|import-pack|migrate|restore)(?:\/|$)/
```
`frontend/shared/config/timeouts.ts` 声明 `LONG_TASK_TIMEOUT_SECONDS = 900`,而后端 `grep -rn "\b900\b" --include=*.py`(排除 tests/release/.tmp)只有一处命中且与生成无关(`advanced_style_set_service.py:57` 的 `STYLE_VALIDATION_TIMEOUT_SECONDS`)。生成任务的真实预算是 **180 秒**(`generation_service.py:2308`;`config.yaml:25/42`)。
号称守护一致性的测试**只读前端文件**:
```js
// frontend/tests/task-timeout-consistency.test.mjs:11-25
test("uses the backend 900 second task budget throughout the plugin bridge UI", async () => {
const [timeouts, client, bridge, app] = await Promise.all([...]) // ← 四个文件全在 frontend/
assert.match(timeouts, /LONG_TASK_TIMEOUT_SECONDS = 900/)
```
**三条具体后果**:(1) 正则里 `probe-model`、`renormalize`、`renormalize-batch`、`import-pack` 对应的端点前端**根本不调用**(见表 ①),这份列表已与实际调用面脱节;(2) 测试名字断言"后端 900 秒预算"但没读过任何后端文件——它固化的是一个**虚构契约**;(3) 新增慢端点(例如实际走 900 秒样式校验的 `advanced-material-imports/{id}/style-consensus`)不在正则里,客户端 30 秒就超时报错而后端任务还在跑。
**收敛方案**:正则提到 `timeouts.ts` 一份,两个 transport 共同 import。更好的做法是后端在 `ui/bootstrap` 下发 `{ long_task_endpoint_patterns: [...], long_task_timeout_seconds: N }`,N 取 `config.generation.provider.timeout_seconds` 的上界;测试改为读 `config.yaml` / `generation_service.py` 与前端常量做真实比对。
---
### 表外补充:一条"后端做完、前端未接"的完整功能链
`images/{id}/moderation-review` + `include_restricted` 是后端为"内容审核隔离图片"实现的完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点(`image_routes.py:41-49 / 68-73 / 90-91 / 145-160`,`image_service.py:135-143` 会真实改写可见性)。**前端一个都没接**:`grep -rn "include_restricted\|restricted_hidden\|quarantined\|gallery_visibility" frontend/` 全树零命中;`frontend/shared/types/image.ts:28-33` 的 `ImageListResult` 也没有 `restricted_hidden` 字段。
后果:`generation_service.py:491/968` 会把审核不通过的图打上 `gallery_visibility: "restricted"`。这些图对所有人(含管理员)不可见、不可复核、不可解除——UI 既不显示"有 N 张被隐藏",也没有任何 approve 入口。**用户视角是"生成成功了但图库里没有",没有任何解释。** 这是耦合缺口在生产中直接表现为数据丢失的一例(P2)。
修复:图库页加"显示受限图片"开关(仅 `can_manage_materials` 可见)→ 传 `include_restricted=true`;列表底部读 `restricted_hidden`;受限图详情弹窗加 approve/reject;`ImageListResult` 补 `restricted_hidden?: number`。
---
## 2.3 类型契约漂移:`frontend/shared/types/*.ts` vs `backend/dto/*.py`
### 2.3.1 一个让所有联合类型失效的写法
```ts
// frontend/shared/types/advanced-material.ts:168
status: AdvancedMaterialImportStatus | string
```
TypeScript 会把 `"a" | "b" | string` 折叠成 `string`,**联合类型完全不产生任何类型检查**。同样的写法出现在 `AdvancedStyleSource.status`、`AdvancedStyleValidationCase.status`、`AdvancedMaterial.status`、`workflow-round.ts:73/112`(`round_kind`、`preference_status`)等十余处。这是本节所有漂移能长期不被发现的技术原因。
### 2.3.2 字段级差异表
| 类型 | 方向 | 差异 | 后端真源 |
|---|---|---|---|
| `AdvancedMaterialImportStatus`
`advanced-material.ts:1-18` | 前端**缺 6 个** | `recognizing_style_sources`、`style_consensus_failed`、`style_consensus_queued`、`style_consensus_running`、`style_source_recognition_queued`、`style_source_review_required`(整个 style-set 流程的状态一个没有) | `advanced_style_set_service.py:384/527/539/787/1366` 等处的 `update_import(..., {"status": ...})` |
| 同上 | 前端**多 2 个幽灵值** | `pending_validation`、`pending_review`——`grep -rn '"pending_validation"' --include=*.py backend/ database/` → **0 命中** | 后端根本不产出 |
| `AdvancedStyleSource` | DTO 无此字段 | `excluded`、`filename`、`image_uri`、`thumbnail_uri`、`retry_count` | 实际来自 `advanced_style_set_service.py:409/414` 手工构造的 dict |
| `AdvancedStyleValidationCase` | DTO 无此字段 | `scenario`、`title`、`style_prompt`、`style_scores`、`rendering_layers`、`content_novelty` | `advanced_style_set_service.py:2330/2354/3345/3422` |
| `AdvancedMaterialImport` | DTO 无此字段 | `task_id`、`workflow_kind`、`sources`、`consensus`、`validation_cases` | `advanced_style_set_service.py:389/1152` |
| `AdvancedStyleConsensus` | **整个接口无对应 DTO** | `AdvancedStyleConsensusRun` 的字段名完全不同(`consensus_style`/`version_id`/`variable_style_features` 都不在 DTO 里) | `advanced_style_set_service.py:1723` |
| 反向 | DTO 输出但 TS 未声明 | `idempotency_key`(import)、`recognition_model_route`/`provider_id`/`provider_model`(style source)、`width`/`height`/`completed_at`(validation case) | — |
| `CharacterProfile`
`profile.ts:3-21` | TS 缺 4 个 owner 字段 | `owner_platform`、`owner_context_id`、`owner_user_id`、`owner_session_key` | `backend/dto/profile_dto.py:42-45` |
| `CharacterProfile.generation_kind` | TS 多 1 个死枚举 | `"profile_card"`——SQL `CASE` 只可能产出 `detailed`/`quick`/`ungenerated` | `database/repositories/profile_repository.py:32-56` |
| `WorkflowRoundNextRequest.count`
`workflow-round.ts:48-52` | TS 比后端窄 | TS 写死 `4 \| 5`;后端 `maximum = 8 if round_kind == "cross_review" else 5` | `workflow_round_service.py:1159-1171` |
| `ImageListResult`
`image.ts:28-33` | TS 缺字段 | `restricted_hidden` | `image_routes.py:41-49` |
| `WorkflowGenerationCandidate` / `WorkflowRoundCandidatePoolEntry` / `CharacterProfile` 的字面量联合 | **无漂移** | 15 / 11 个字段逐条核对全部精确对应 | 说明人工纪律目前还撑得住,但没有任何机制保证 |
### 2.3.3 根因:`backend/dto/` 对进阶素材已经名存实亡
路由层的序列化只补签名 URL,不加业务字段:
```python
# backend/routes/advanced_material_routes.py:387-392
def _serialize_style_source(payload: dict[str, Any]) -> dict[str, Any]:
return {**payload,
"source_image_url": _signed_url(payload.get("source_image_uri")),
"source_thumbnail_url": _signed_url(payload.get("source_thumbnail_uri"))}
```
响应形状实际由散落在 4,491 行 `advanced_style_set_service.py` 各处的 dict 字面量决定。**想知道接口返回什么,只能全文搜索;改动时没有任何单点可以对照。** 这也是状态枚举漂移的同一个根因。
### 2.3.4 收敛方案
1. **去掉 `| string`**,改为 `status: AdvancedMaterialImportStatus`,让联合类型真正生效;确需容忍未知值的地方在解析边界处显式收窄。
2. **为 style-set 流程补 DTO**(`AdvancedStyleSourceView`、`AdvancedStyleValidationCaseView`、`AdvancedStyleConsensusView`),让 service 返回 DTO 实例而非裸 dict,路由层只调 `to_dict()` + 加签名 URL。这样"接口返回什么"重新有唯一定义点。
3. **状态集合从后端生成而非手抄**:把各 `*_STATUSES` 常量集中到一个 Python 模块,加生成脚本产出 `frontend/shared/types/generated-enums.ts`,CI 校验 `git diff --exit-code`。
4. DTO 与 TS 字段做一次对齐——**不需要的字段就从 `to_dict()` 里删,别只在 TS 侧省略**;删掉 `generation_kind` 里的 `"profile_card"`;`count` 改为 `number` 并由后端在 `round.metadata` 下发 `allowed_count_range: [min, max]`。
---
## 2.4 构建产物入库:取舍分析
### 事实
| 项 | 数据 |
|---|---|
| 提交进 git 的 dist 目录 | `web/`(`standalone-web` 产物)、`pages/imagestudio/`(`plugin-page` 产物) |
| `git ls-files web/ pages/` | 38 个文件,各约 1.1 MB |
| `git log --oneline -- web/assets` | 80 次提交 |
| `.git` 体积 | 51 MB(其中 `git count-objects -vH` 的 size-pack 44.03 MiB) |
| `.gitignore:16` | 只忽略 `frontend/**/dist/`,未忽略这两个输出目录 |
| 两个 vite 配置 | `standalone-web/vite.config.ts:11-15`(`base: "/api/v1/.../web/"`,`outDir: ../../web`,`emptyOutDir: true`);`plugin-page/vite.config.ts:11-15`(`base: "./"`,`outDir: ../../pages/imagestudio`) |
### 取舍:不能简单删
初审给出的建议是「`.gitignore` 加 `/web/` 与 `/pages/imagestudio/`,`git rm -r --cached`」。**这条建议经复核被推翻,照做会导致插件页面全线不可用。**
1. **这两个目录是文档明确定义的发布负载。** `INSTALL.md` 的"最小运行时清单"把 `pages/imagestudio/` 和 `web/` 与 `main.py`、`metadata.yaml` 并列列为安装后必需内容;"发布包白名单"章节要求正式 ZIP 归档 `pages/` 和 `web/`。ImageStudio 是 AstrBot 插件(`metadata.yaml: astrbot_version: ">=4.25.0,<5"`),装机路径是把仓库/ZIP 铺到 `data/plugins/astrbot_plugin_imagestudio/`,**安装期没有任何 npm/vite 步骤**。产物一旦不在仓库,`WebHostingService._resolve` 直接抛 `ErrorCode.RESOURCE_NOT_FOUND, "web asset not built"`。
2. **"两份重复 dist"这个指控不成立。** 两份构建的 `base` 不同且**必须**不同:`web/index.html` 里是绝对路径 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/assets/...`,`pages/imagestudio/index.html` 里是相对路径 `./assets/...`。两者挂载于不同 URL 根(`PLUGIN_PAGE_URL = "/plugin/imagestudio"` vs `STANDALONE_WEB_URL = "/api/v1/..."`),**一份产物物理上无法同时服务两个挂载点**。`plugin-page/src/App.vue` 全文只有一行 `import WorkbenchApp from "../../standalone-web/src/App.vue"`——源码层面已经没有重复,重复的只是两份必需的编译输出。
3. **"2MB 噪音淹没 diff"与实测不符。** 最近几次 dist 提交的实际 stat 是 `24 files changed, 59 insertions(+), 69 deletions(-)`(`878f1f6`)、`24 files changed, 37 insertions(+), 27 deletions(-)`(`2dbf90b`)——git 的重命名检测把内容哈希改名识别成 `web/assets/{index-A.js => index-B.js}`,压缩产物是单行文件,每次只有几十行 diff。
4. **仓库体积的主因不是 dist。** `git ls-files release/` 有 20 个 ZIP、仅当前树就占 37.0 MiB。想瘦身应该先动 `release/`,不是 `web/assets`。
### 残留的真实问题与替代方案
**真实问题只有一条:没有任何机制保证产物与源码同步。** `WebHostingService.manifest()` 只检查 `index.html` 是否存在(`web_hosting_service.py:33/38`)就报告 `built: true`,无法发现版本错位;仓库根本没有 `.github/workflows`;git 历史里有 24 次只更新 `web/assets`、3 次只更新 `pages/imagestudio/assets` 的提交。
**替代方案(按推荐度)**:
1. **加一条构建新鲜度校验**(推荐,改动最小):
```yaml
# CI 步骤:产物必须是当前源码的构建结果
- run: cd frontend && npm ci && npm run build # 已有 "build": "build:plugin && build:web"
- run: git diff --exit-code web pages/imagestudio
```
这一条同时解决"漏跑一次构建"和"产物与源码错位"两个问题,且不改变发布模型。
2. **`manifest()` 增加 `build_hash`**(构建时注入),与 `metadata.yaml` 版本比对,让版本错位在运行时**可观测**而不是靠用户报障。
3. **`release/` 的 20 个 ZIP 迁出主干**——改用 git tag + release artifact 承载。这是真正能压缩 `.git` 的动作(37 MiB / 44 MiB)。
4. **不要**把 `web/` 与 `pages/imagestudio/` 加进 `.gitignore`。若将来 AstrBot 支持安装期构建,再重新评估。
---
## 2.5 契约自检能力评估与自动化契约测试方案
### 2.5.1 现状:数据齐了,没人用
```python
# backend/services/contract_service.py:13-30 —— 数据已经很全
return {
"contract_version": "3.0",
"api_base": API_BASE,
"routes": route_manifest(), # 166 条:method / endpoint / handler / permission / required_permissions
"permissions": permission_matrix(),
"error_codes": [code.value for code in ErrorCode],
"response_shape": {...},
}
```
唯一消费点是设置页的诊断框:
```ts
// SystemManagementPanel.vue:8 —— 拉下来直接 JSON.stringify 塞进
const [contract,actions,manifest]=await Promise.all([
getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
result.value={contract,actions,manifest}
```
`route_registry.py:365-377` 已经写好了两个自检函数 `assert_unique_routes()` / `assert_known_permissions()`,**无人调用**。`api_discovery_routes.py` 提供的是外部 provider 探测(`probe-provider` / `probe-model`),与内部契约自检无关——注意 `probe-model` 本身就在表 ① 的死接口里。
**能力评估**:契约**发布**能力已具备且质量不错(路由 + 权限 + 错误码 + 响应信封);契约**校验**能力为零。缺的一环是"发布出来的东西没有任何一方去比对"。本报告 §2.1 的 14 条死接口、§2.2 的 11 条重复实现、§2.3 的字段级漂移,**全部是人工比对才发现的,每一条都本可以由 CI 自动发现**。
`contract` 目前不发布**请求/响应 schema**——这是它无法覆盖 §2.3 类型漂移的原因。
### 2.5.2 自动化契约测试方案(三层,按实施顺序)
**第一层:后端自检(0.5 天,立刻能做)**
```python
# tests/test_route_contract.py
import importlib
from backend.route_registry import ROUTES, assert_unique_routes, assert_known_permissions
def test_route_manifest_is_wellformed():
assert_unique_routes()
assert_known_permissions()
for route in ROUTES:
mod, _, fn = route.handler.rpartition(".")
assert hasattr(importlib.import_module(mod), fn), route.handler
```
审计过程中已实测:166 条 handler 全部可导入,**这条测试当前会通过**——它是纯回归护栏,零迁移成本。
**第二层:跨语言路由比对(1 天)**
```js
// frontend/tests/api-contract.test.mjs
import { readFile } from "node:fs/promises"
import test from "node:test"
import assert from "node:assert/strict"
// 已知未接入的后端路由;新增一条必须在此显式登记,否则测试失败
const KNOWN_UNUSED = new Set([
"DELETE profiles/{}", "POST profiles/{}/delete", "POST images/{}/moderation-review",
"POST advanced-material-imports/{}/cancel", "POST nodes/{}/mark-completed",
"POST nodes/{}/select-image", "POST prompts/expand", "GET profile-cards/{}",
"DELETE profiles/{}/wardrobe/{}", "GET materials/analytics",
"POST materials/renormalize-batch", "POST materials/{}/renormalize",
"GET integrations/logs", "POST api-discovery/probe-model",
])
const norm = (s) => s.replace(/\$\{[^}]*\}/g, "{}").replace(/\{[^}]*\}/g, "{}")
test("endpoints.ts ⊆ route_registry.ROUTES", async () => {
const registry = await readFile("../backend/route_registry.py", "utf8")
const backend = new Set([...registry.matchAll(/RouteSpec\(\s*"(\w+)",\s*"([^"]+)"/g)]
.map(([, m, p]) => `${m} ${norm(p)}`))
const endpoints = await readFile("./shared/api/endpoints.ts", "utf8")
const frontend = new Set([...endpoints.matchAll(/`([^`]+)`/g)].map(([, p]) => norm(p)))
// 1) 前端调用的每条路径都必须在后端存在 —— 阻止表 ② 出现
for (const path of frontend) {
assert.ok([...backend].some((b) => b.endsWith(` ${path}`)), `endpoints.ts 引用了后端不存在的路径: ${path}`)
}
// 2) 后端新增的未使用路由必须显式登记 —— 逼作者要么接上要么删掉
const unused = [...backend].filter((b) => ![...frontend].some((f) => b.endsWith(` ${f}`)))
assert.deepEqual(unused.filter((u) => !KNOWN_UNUSED.has(u)), [],
"新增了前端未接入的后端路由;请接入或加进 KNOWN_UNUSED")
})
```
**第三层:字段级 DTO 契约(2-3 天,需先修 §2.3.3)**
```js
// frontend/tests/dto-contract.test.mjs
// 读 backend/dto/*.py 每个 to_dict() 的字面量 key 集合,
// 与 frontend/shared/types/*.ts 对应 interface 的字段名集合做双向差集断言。
// 正则提取即可,不需要真正解析 AST。
```
前提:先把 §2.3.3 做掉(让 DTO 重新成为响应真相来源)。DTO 都是 frozen dataclass,`dataclasses.fields()` 可以自动生成字段清单,因此第三层也可以做成"后端导出 schema → CI 比对 TS"的生成式方案,比正则更稳。
**第四层(可选):权限门禁统一**
前端所有按钮的 `enabled` 统一走 §2.2#6 的 `canCall(method, endpoint)`,输入直接来自 contract 的 `required_permissions`——权限矩阵从此不需要在前端复写,§2.2#6 这类问题从根上消失。
**投入产出**:第一层 + 第二层合计约 1.5 天,能自动拦住表 ①/表 ② 类漂移与权限矩阵不一致;第三层再覆盖 §2.3 全部字段级漂移。这是整份耦合报告里**性价比最高的一项投入**。
---
# 第三部分 · 解耦路线
严重度口径:`P0-致命` / `P1-严重` / `P2-中等` / `P3-轻微`。风险栏描述的是**改动本身**的风险。
## 立刻能做(本周内,单个 PR 可完成,风险 ≤ 低)
| # | 动作 | 位置 | 收益 | 风险 |
|---|---|---|---|---|
| 1 | 4 处工厂补 `event_bus=get_default_event_bus()`;`WorkflowService.event_bus` 默认值改为 `get_default_event_bus()` | `node_material_routes.py:69`、`branch_routes.py:62`、`history_routes.py:72`、`review_routes.py:90` | 修复两例**已确认**的事件静默丢失(复核定级 **P3**:事件当前零订阅者,用户可见影响仅为 3 个导航页的自动刷新延迟)。真正价值是堵住装配分散的复制路径。改动 <20 行 | **极低**。补一条断言 `event_bus is not None` 的测试即可 |
| 2 | `generation_service.py:1416-1427` 改用 `self._publish(...)`,删除 `self.workflow_service.event_bus` 穿透 | `generation_service.py:1416-1427` | 消除同类风险的第二个来源(P3,与 #1 同源) | 极低 |
| 3 | 删掉 `workflow-lock-state.ts:12` 的 `sealed_at` 判据,补上 `selected_image_id` | `workflow-lock-state.ts:8-27` | 消除一个后端零产出的死判据 + 补齐一条真实锁条件(§2.2 #3,复核定级 **P3**) | 低。需同步更新前端测试 |
| 4 | 加 `tests/test_route_contract.py`(§2.5 第一层) | 新文件,约 12 行 | 166 条 handler 可导入 + 路由唯一性 + 权限合法性的永久护栏 | **零**。实测当前即通过 |
| 5 | 删除 `generation_service.py:1493/1506` 的冗余函数内 import | 同左 | 消除误导性的"循环依赖"信号 | 零 |
| 6 | 4 张中文状态标签表合并为 `presentation.ts` 的 `generationStatusLabel()` | `App.vue:6927`、`WorkflowCandidatePool.vue:132`、`WorkflowRoundPanel.vue:113`、`presentation.ts:11` | 消除同一状态三种译法 + 补齐 `retrying`/`dead_letter`(P2) | 低。纯展示层 |
| 7 | `LONG_TASK_ENDPOINT` 正则提到 `timeouts.ts` 一份 | `client.ts:14`、`astrbot-page-bridge.ts:6` | 消除逐字符重复(P2) | 零 |
| 8 | 加 `route-chain:` 线格式黄金样本测试(Python + TS 各一条,断言同一字符串) | `tests/test_model_route_chain.py` + `frontend/tests/` | 锁死跨语言序列化格式(P2) | 零 |
| 9 | 删除死组件 `WorkflowDependencyContextCard.vue`(279 行,全仓零引用) | 同左 | 减少 279 行 + 加快 `vue-tsc` | 低。需确认 App.vue 内联版已完全覆盖 |
## 一个迭代内(2-4 周)
| # | 动作 | 收益 | 风险 |
|---|---|---|---|
| 10 | **建 `backend/composition.py` 组合根**,分 4 步迁移(见 §1.4.4):先迁 `WorkflowService` 一族 → 迁 `_create_generation_service` → 抽 `build_governance_bundle` → 迁剩余工厂 | 一次性消除 `service→route`、route↔route 两条环;34 处磁盘 YAML 解析降到按 mtime 缓存;`node_routes` 扇出 31→个位数;route 平均扇出 12→3-4;两例事件丢失不可复发 | **中**。触及 20 个 route 模块。缓解:每步独立可合并、每步都有护栏测试;`_fingerprint()` 按 `(path, mtime)` 失效保证配置热更新语义不变 |
| 11 | 加 `frontend/tests/api-contract.test.mjs`(§2.5 第二层),14 条死接口写成显式 allowlist | 表 ①/② 类漂移永久自动化拦截;新增未接入路由必须显式登记 | 低。首次运行需把当前 14 条登记进 allowlist |
| 12 | **`list_workflow_nodes` 返回体加 `progression`**,前端删除 `App.vue:10836-10861` + `:927` | 消除 §2.2 #2(复核定级 **P2**)复刻的四层状态机;后端改进度规则不再需要前端跟改 | 中。返回结构变更,需同步 `workflow.ts` 并升 `contract_version`。缓解:新增字段而非替换,前端可分两步切换 |
| 13 | `WorkflowNode.to_dict()` 增加 `writable` + `lock_reason`(复用 `WorkflowNodeMaterialBindingDetail` 已有的形状),前端 `workflow-lock-state.ts` 退化为读 `node.writable` | 消除 §2.2 #3(复核定级 **P3**)写锁规则不一致的全部分歧 | 中。同 #12 |
| 14 | `ui/bootstrap` 下发 `task_statuses` 四集合 + `long_task_*` 配置 + 节点目录(`gradual_node_templates()` + legacy 别名表) | 一次性收敛 §2.2 的 #7 / #10 / #11 三条 P2 | 低。纯增量字段 |
| 15 | 下沉 `branch_state_for` / `with_branch_state` / `BRANCH_STATE_FIELDS` → `core/branch_state.py`;`canonical_gradual_node_key` 同理 | 消除 `database → backend.services` 与 `database → engines` 违规;解除包级双向依赖 | 低。都是纯函数,改的是 import 路径 |
| 16 | 下沉 `ApiError`/`ErrorCode` → `core/errors.py`;`load_config_payload` → `core/config_loader.py`(原位置保留 re-export) | `core` 恢复零上行依赖 | 低。re-export 让 53 + 56 个 import 点可以零改动渐进迁移 |
| 17 | 接上 `include_restricted` / `restricted_hidden` / `moderation-review` 功能链 | 修复"生成成功但图库里没有"的用户可见数据丢失 | 低。纯新增 UI |
| 18 | CI 加构建新鲜度校验 `npm run build && git diff --exit-code web pages/imagestudio`;`manifest()` 加 `build_hash` | 产物与源码错位可被拦截/观测(§2.4) | 低。仓库尚无 `.github/workflows`,需先建 |
## 长期(跨迭代,需要专门排期)
| # | 动作 | 收益 | 风险 |
|---|---|---|---|
| 19 | **`main.py` 按 §1.7 拆成 6 个模块**(2580 → ~250 行);`_SHORT_ALIASES` 数据驱动替代 165 行转发;`_runtime_config_patch_from_mapping` 由 `_RUNTIME_PATH_TO_ASTRBOT_KEY` 反向遍历生成(277 → ~50 行) | 消除 66 条配置映射的双向手写;聊天业务从入口文件剥离 | **中高**。`main.py` 是插件入口,改错即插件起不来。缓解:先做 `_SHORT_ALIASES` 与配置映射两块(有明确的等价性判据,可脚本比对 66 个键),拆分留到最后 |
| 20 | 补 style-set 流程 DTO(`AdvancedStyleSourceView` 等),让 `backend/dto/` 重新成为响应真相来源;去掉 TS 的 `\| string`;加 §2.5 第三层字段级契约测试 | 消除 §2.3 全部字段级漂移,并让它不可复发 | 中。触及 4,491 行的 `advanced_style_set_service.py`。必须先做 #21 或至少先隔离其序列化出口 |
| 21 | 拆 `advanced_style_set_service.py`(4,491 行 / 单类 2,092 行 / 31 方法 / 81 个模块级私有函数)与 `advanced_material_service.py`(1,856 行 / 45 方法 / 14 参数构造函数) | 解开耦合簇 2;`generation_service` 的 21 参数构造函数同理 | **高**。这是仓库里最大的两个 service。缓解:先靠 #10 的组合根把装配剥离出去,再按"识别 / 共识 / 校验"三个子流程切 |
| 22 | `ChatWorkflowService` 的 69 处字符串 dispatch 换成类型化门面或直接依赖 composition 提供的 service | 恢复类型安全(重命名路由有静态检查保护);消除每次 dispatch 的反射 + 全量重建开销 | 中。69 个调用点。缓解:先做类型化门面(`class ImageStudioApi` 每端点一方法,内部仍走 dispatcher),行为完全不变,再逐个换实现 |
| 23 | `EventBus` 二选一:加锁 + 异常隔离并把 3 组"通知型"直连迁上总线;**或**删掉 `subscribe/unsubscribe` 改名 `EventRecorder` | 要么兑现解耦价值(簇 1 的 19 条直连边可减少),要么停止误导架构判断 | 迁总线:中(改变调用时序);改名:零。**最忌讳的是维持现状** |
| 24 | 前端快速角色编排下沉为 `POST workflows/{id}/quick-character/run` | 消除 291 行浏览器端状态机与僵尸工作流(§2.2 #1,复核定级 **P2**) | 中高。需要后端实现锚点优先 + 并行提交 + 失败补偿。缓解:`quick_character_consistency.py` 已有基础 |
| 25 | `release/` 的 20 个 ZIP(37 MiB)迁出主干,改用 git tag + release artifact | `.git` 从 51 MB 显著下降 | 中。需要 `git filter-repo` 重写历史或接受只对未来生效。**注意:不要动 `web/` 与 `pages/imagestudio/`**(§2.4) |
---
## 附:本报告不收录的内容
以下条目在原始材料中被列为耦合类缺陷,但经 `_复核结论.md` 的独立复核**被推翻**,本报告不作为成立缺陷收录,仅在此备案以免后续重复调查:
| 原始定位 | 原始定级 | 复核结论 |
|---|---|---|
| `POST profiles/{id}/archive` 执行删除 → 用户意图扭曲 | P1 | 误报。前端唯一调用方是文案/样式/提示均为"删除"的按钮,意图与行为一致;profile 状态机无 `archived` 态。残留 P3 命名整洁度问题,见 §2.1 |
| `events/stream` 无游标 → 事件静默丢失导致 UI 停滞 | P1 | 误报。总线上每条事件都满足 `generation.` 或 `workflow.` 前缀,`.some()` 的 OR 归约无法因窗口退化翻假;刷新是全量重取而非增量应用;轮次面板另有 4 秒自续轮询。残留 P3:`slice(..., -1)` 魔数写法应改为 `slice()`,接口无游标是设计粗糙而非缺陷 |
| `web/` 与 `pages/imagestudio/` 是"误提交的两份重复 dist" | P1 | 误报。两者是 `INSTALL.md` 明确定义的发布负载,`base` 不同且必须不同,一份产物无法服务两个挂载点;照建议加 gitignore 会导致插件页面不可用。残留 P3:缺构建新鲜度校验,见 §2.4 |
| `_string_list` 18 处重复导致数据损坏 / 顺序不可预测 | P1 | 误报。真实为 17 处(多出的来自 `.tmp/` 构建快照),无跨模块导入,各调用点处理的值互不相干。残留 P3:DRY 异味 |
| 23 个 service / 4,579 行零测试 | P1 | 误报。实测覆盖率显示 23 个中有 8 个被实质执行(5 个覆盖率 74%~94%),真正零执行的是 9 个模块约 1,966 行;"同名测试不测同名 service"的论断被证明完全反向 |
(`App.vue:6126`、`workflow-model-route.ts:36`、`App.vue:3076` 三条同样被复核**推翻**,但因其残留问题仍属真实的重复实现耦合,已按 P3 收录在 §2.2 的 #4/#5/#6 并标注"经复核降级"。)
---
## 附二:终审补录的耦合项(初稿漏收)
终审回扫 `_raw.json` 全部 214 条发现后,确认下列 4 条耦合类发现未被本报告任何章节覆盖:
| 严重度 | 位置 | 问题 | 收敛方向 |
|---|---|---|---|
| P2-中等 | `frontend/.../features/profiles/ProfilesPage.vue:10` | **三层 prop drilling**:24 个 props / 13 个 emits,其中 **16 个 props 是纯透传**(`ProfilesPage` 自己一个都不用,只往下传给 `ProfileDetailPane` / `ProfileWardrobePane`) | 随 04 报告 §2.1.2 的 `useProfilePage()` composable 一起做:中间层不再转发 props,叶子组件直接从 composable 取 |
| P2-中等 | `frontend/.../features/profiles/ProfileWardrobePane.vue:249` | **状态归属分裂**:衣橱条目走 props/emits 由父层持有,套装模板却由组件自己调 API —— 同一个面板里两套数据流,父层无法感知模板变更 | 二选一:模板也上提到父层,或衣橱条目也下沉到组件自持。**不要维持现状** |
| P2-中等 | `core/astrbot_provider_bridge.py:22` | **全局可变状态**:AstrBot 桥接对象与配置覆盖是进程级模块变量,插件热重载后旧对象可能残留,测试之间无法隔离 | 由 §1.4.4 的组合根持有并注入;每个 `set_*` 配一个 `reset_*` 供测试 |
| P3-轻微 | `core/config_writer.py:17` | 配置文件锁仅为**进程内** `threading.RLock` —— 多进程部署(或 AstrBot 与外部工具同时写 `config.yaml`)时不提供任何互斥 | 改用文件锁(`portalocker` 或 `fcntl`/`msvcrt` 分支),或在文档里明确声明"单进程写入"约束 |
`backend/services/profile_service.py:160` 的 `_require_owner` 与 `ResourceAccessService._can_access` 语义相反(前者不认管理员权限)也属耦合缺陷,因其直接影响 02 报告 P1-2 的 IDOR 改造,已登记在 [02-BUG清单.md](02-BUG清单.md) 的 §6.1。