1235 行
101 KiB
Markdown
1235 行
101 KiB
Markdown
|
|
# 03 · 耦合分析
|
|||
|
|
|
|||
|
|
> 材料来源:`审计/findings/B1-前后端耦合.md`、`B2-后端内部耦合.md`,辅以 `A7-路由与插件入口.md`、`A8-前端App主体.md`、`A9-前端功能组件.md`。
|
|||
|
|
> 所有被 `审计/findings/_复核结论.md` 推翻的条目已剔除;复核判定"机制属实但影响被夸大"的,按复核给出的严重度收录并标注**经复核降级**。
|
|||
|
|
> 本文中的量化数字若标 `[实测]`,为撰写本报告时在仓库中重新执行命令核对过的。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 摘要
|
|||
|
|
|
|||
|
|
**这个仓库的耦合问题不是"接错线",而是"没有装配台"。** 后端 263 个 pytest 全部通过、前端 26 个 node:test 全部通过,166 条后端路由与 143 条前端 endpoint 声明逐条比对**零个会 404**,`App.vue` 里 `endpoints.` 引用 183 处、全前端唯一的 `/api/` 字面量就是 `endpoints.ts:1` 的 `API_BASE` 定义本身 `[实测]`。代码跑得起来,URL 也对得上。真正的病灶在于:**组合根(composition root)缺失**,导致 20 个 route 模块各自手写 35 个装配函数、34 处 `Database(load_database_settings())` 各自重读一次 `config.yaml` `[实测]`;同一个 `WorkflowService` 在不同路由下被装配成**行为不一致**的实例,且不一致是静默的。
|
|||
|
|
|
|||
|
|
**后端侧最贵的一条是装配分散,不是分层违规。** 分层违规(`service → route`、`database → backend.services/engines`、`core → backend.dto`)确实存在且方向明确,但它们各自只有 1-3 个调用点,属于"知道位置就能改"的问题。装配分散不一样:它已经产生了**可复现的行为不一致**——`node_material_routes.py:69` 构造 `WorkflowService` 时漏传 `event_bus`,于是 `workflow.node_material_bindings_updated` 事件永远不发;`branch_routes.py:62` 的工厂同样漏传。因为消费端写成 `if self.workflow_service.event_bus:`(穿透邻居属性),短路后没有日志、没有异常、没有任何痕迹。这类缺陷会随着新增路由持续复制,是本项目投入产出比最高的重构点。
|
|||
|
|
|
|||
|
|
> **⚠️ 复核定级(不要按 P1 排工作量)**:这两条事实层面全部核实为真(行号精确、路径可达、无上游兜底),但**复核把它们从 P1 降到 P3**,理由是丢失的事件**当前零消费者**——全仓 `subscribe()` 调用为 0,`workflow.branch_created` 只有一处 publish、无任何订阅方,`workflow.branch_switched` 这个事件全仓根本不存在(初审引用的 `workflow_service.py:640` 实际落在 `create_node` 内,属张冠李戴)。审计链路不受影响(`audit_service.record` 走另一条正确装配的依赖,无条件执行);业务数据不丢(`save` 后直接 `return self.get_node_bindings(...)`,前端同步拿到最新状态)。用户可见影响仅为 overview/performance/logs 三个导航页上一次可能的自动刷新延迟。
|
|||
|
|
>
|
|||
|
|
> **它仍然是本报告推荐优先做的第一项**——因为改动 <20 行、风险极低、且是装配分散这个结构性问题**唯一已实证的出口**。但它的价值在于"堵住结构性缺陷的复制路径",不在于"修一个正在伤害用户的 bug"。
|
|||
|
|
|
|||
|
|
**前后端侧最贵的一条是语义契约缺位,不是 URL 管理。** URL 层收敛得很干净,但 URL 背后的**规则**没有被下发:后端有 `character_gradual_progression().to_dict()`、有 `PERMISSION_MATRIX`、有 `ContractService` 这些"可下发的真相",却没有一条路由把它们送到前端,于是前端只能复刻——顺序进度状态机复刻了四层规则、节点写锁规则复刻后少判一个可达条件(`selected_image_id`)还多出一个后端根本不产出的 `sealed_at` 字段(`grep -rn "sealed_at" --include=*.py` 返回 0 `[实测]`)、快速角色四联图的整条工作流状态机被搬进浏览器里 291 行编排。**注意这三条经复核分别定为 P2 / P3 / P2,不是 P1**(详见 §2.2 的逐条降级说明)——它们是"改起来会越来越贵"的耦合债,不是"现在正在伤害用户"的缺陷。`GET contract` 端点已经把 166 条路由 + 权限矩阵 + 错误码全部发布出来了,唯一的消费者是设置页里一个 `JSON.stringify` 诊断框——**契约自检的数据早就齐了,只差三条 CI 断言**。这是本维度最低成本、最高收益的修复方向。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 第一部分 · 后端内部耦合
|
|||
|
|
|
|||
|
|
## 1.1 分层违规清单
|
|||
|
|
|
|||
|
|
预期分层是 `routes → services → repositories`,`core` 作为无上行依赖的横切基础设施。实际存在 3 类共 9 条方向违规:
|
|||
|
|
|
|||
|
|
| 违规类型 | 位置 | 说明 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| **service → route**(方向最刺眼,但复核定级 **P3**) | `backend/services/workflow_round_worker_runtime.py:10`<br>`from backend.routes.node_routes import create_generation_service` | 后台 round worker 是 service 层组件,却必须反向 import route 层才能拿到装配好的 `GenerationService`。装配根 `_create_generation_service()` 定义在 `backend/routes/node_routes.py:315-390`(私有)+ `:393`(公开包装),在那里完成 Database、9 个 repository、`ModelProviderRuntime`、`SingleFlowEngine`、4 个 governance 服务的构造。后果:`backend/routes` 成为 worker 的不可卸载运行时依赖,HTTP 层与 worker 层无法分开打包或测试。<br>**⚠️ 复核修正(必须如实记录)**:初审附加的两条影响经复核证伪 —— (a) "单测想构造 `GenerationService` 就得连带 import `node_routes` 的 31 个依赖"**是错的**,`tests/test_workflow_round_queue_runtime.py:12` 直接 `from backend.services.generation_service import GenerationService` 并在测试内手工装配,完全绕开 `node_routes`;(b) 无循环导入(`node_routes.py` 内 `worker_runtime`/`round_worker` 零命中),且 `node_routes` 导入期无副作用(装配全在函数体内)。worker 走的 `:393-396` 是带 docstring 的**显式公共出口**(`"""Public runtime factory shared by HTTP routes and background workers."""`),属有意设计的缝。真正不规范的只有 `job_routes.py:311` 舍近求远取私有名。**复核定级 P3-轻微:纯架构整洁度/可打包性问题,无可触发的失败路径。** |
|
|||
|
|
| route → route(取私有符号) | `backend/routes/job_routes.py:311`<br>`from backend.routes.node_routes import _create_generation_service` | 函数体内 import,且取的是**下划线私有名**(同文件 `:393` 有公开的 `create_generation_service`)。注释写着 `Import lazily so route discovery does not construct provider runtimes`——直接说明这条 import 边有启动期副作用压力。 |
|
|||
|
|
| **database → backend.services** | `database/repositories/workflow_round_repository.py:17`<br>`database/repositories/workflow_cross_review_repository.py:17`<br>`from backend.services.branch_lineage_service import branch_state_for, with_branch_state` | 仓储层(最底层)反向 import 业务服务层。分支血缘规则被钉死在 SQL 层。而 `backend/services/branch_lineage_service.py:17` 自己又 `from database.repositories.workflow_repository import WorkflowRepository`——**包级双向依赖已经成立**,模块粒度目前恰好没成环,但只要 `branch_lineage_service` 再多 import 一个 round/cross-review repository 就立刻真成环。 |
|
|||
|
|
| **database → engines** | `database/repositories/profile_card_repository.py:11`<br>`from engines.character_flow import canonical_gradual_node_key` | 同上,仓储层依赖引擎层的节点键归一逻辑。 |
|
|||
|
|
| **core → backend.dto** | `core/security.py:5`<br>`from backend.dto.common import ApiError, ErrorCode` | `backend.dto.common`(扇入 53/54,全仓第三)事实上扮演"全局错误契约"的角色,却被放在 `backend` 包下,逼得 `core` 反向依赖。命名与真实分层错位。 |
|
|||
|
|
| **core → database** | `core/config_service.py:10`<br>`from database.db_helper import load_config_payload` | 把"读配置"和"连数据库"绑在一起——而 `load_config_payload` 本质是 YAML 加载,跟数据库毫无关系。 |
|
|||
|
|
| **core → database** | `core/audit_service.py:12`<br>`from database.db_helper import Database, DatabaseSettings` | 审计服务需要落库可以理解,但代价是 `core` 整体不再是最底层,无法独立复用或测试。 |
|
|||
|
|
| **core → backend/database** | `core/storage.py:11`、`core/media_proxy.py:17` | 同族问题,共 5 个 `core` 模块有上行依赖。 |
|
|||
|
|
|
|||
|
|
**修复顺序**(按"改动面 / 收益"排):
|
|||
|
|
|
|||
|
|
1. `branch_state_for` / `with_branch_state` / `BRANCH_STATE_FIELDS` 是**纯函数 + frozenset**(对 dict 做字段级投影,无 I/O、无状态),下沉到 `core/branch_state.py`,`database` 与 `backend.services` 都从下层取。同理 `canonical_gradual_node_key` 下沉,或由 service 在传参前算好再交给 repository。影响面:3 个 repository + 3 个 service。
|
|||
|
|
2. `ApiError` / `ErrorCode` / `success_response` / `response_from_exception` 从 `backend/dto/common.py` 移到 `core/errors.py`,`backend/dto/common.py` 保留 `re-export` 做过渡——53 个 import 点可以零改动渐进迁移。
|
|||
|
|
3. `load_config_payload` / `load_config_file_payload` / `_RUNTIME_CONFIG_OVERRIDES` 从 `database/db_helper.py:26-83` 抽到 `core/config_loader.py`,`db_helper` 反过来 import 它。做完这两条 `core` 恢复零上行依赖。
|
|||
|
|
4. `service → route` 由 §1.4 的组合根一次性解决。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.2 扇入 / 扇出 Top 10
|
|||
|
|
|
|||
|
|
对 179 个 Python 模块做导入抽取得到的模块级有向图。
|
|||
|
|
|
|||
|
|
### 扇入 Top 10(被最多模块 import)
|
|||
|
|
|
|||
|
|
| 扇入 | 模块 | 层 | 评价 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 65 | `core.identity` | core | **健康**。纯 `RequestContext` 值对象,零下行依赖,这就是横切基础设施该有的样子——它是全仓唯一可以照抄的正面样板。 |
|
|||
|
|
| 56 | `database.db_helper` | db | **不健康**。既是 `Database`/`DatabaseSettings`,又是 YAML 配置加载器(`load_config_payload`),两个完全无关的职责挤在一个 56 扇入的模块里。任何想读配置的模块都被迫依赖数据库层。 |
|
|||
|
|
| 54 | `backend.dto.common` | dto | **位置错误**。事实上的全局错误契约(`ApiError`/`ErrorCode`/响应信封),却被放在 `backend` 包下,直接造成 §1.1 的 `core → backend.dto` 违规。 |
|
|||
|
|
| 31 | `core.security` | core | 健康(摘掉对 `backend.dto.common` 的依赖后就完全干净)。 |
|
|||
|
|
| 31 | `backend.routes.common` | route | 可接受但命名误导。只有 17 行的 `handle_request`,已验证 route 包外无引用。 |
|
|||
|
|
| 30 | `core.audit_service` | core | 中性。审计是横切关注点,高扇入合理;但它 import `database.db_helper` 使 `core` 不再是底层。 |
|
|||
|
|
| 19 | `database.repositories.workflow_repository` | db | 合理,工作流是核心聚合。 |
|
|||
|
|
| 16 | `database.repositories.profile_repository` | db | 合理。 |
|
|||
|
|
| 16 | `backend.routes.params` | route | 同 `routes.common`。 |
|
|||
|
|
| 15 | `backend.services.workflow_service` | service | **风险点**。唯一进入扇入 Top10 的 service,同时扇出 14——典型的枢纽节点,是耦合簇 1 的中心(见 §1.5)。 |
|
|||
|
|
|
|||
|
|
### 扇出 Top 10(import 最多别人)
|
|||
|
|
|
|||
|
|
| 扇出 | 模块 | 行数 | 评价 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 31 | `backend.routes.node_routes` | 490 | **全仓最不健康的模块**。它是事实上的组合根(`_create_generation_service` 装配 20+ 个对象),却挂在 route 层,还被 service 层反向 import(§1.1 第一条)。 |
|
|||
|
|
| 29 | `backend.services.advanced_material_service` | 1856 | God service。45 个方法 + 14 参数构造函数 + 自带装配工厂 `create_advanced_material_service()`(`:1700-1764`)。 |
|
|||
|
|
| 22 | `main` | 2580 | 见 §1.7。 |
|
|||
|
|
| 21 | `backend.services.generation_service` | 2432 | **21 参数构造函数(全仓第一)**,28 个方法,直连 13 个其它 service。 |
|
|||
|
|
| 16 | `backend.routes.material_routes` / `node_material_routes` | — | route 层重复装配的典型。 |
|
|||
|
|
| 16 | `backend.services.workflow_round_service` | 1596 | 耦合簇核心之一。 |
|
|||
|
|
| 15 | `backend.routes.integration_routes` | — | 同上。 |
|
|||
|
|
| 14 | `backend.services.workflow_service` | 1296 | 既高扇入(15)又高扇出(14),枢纽节点。 |
|
|||
|
|
| 13 | `backend.routes.image_routes` / `profile_routes` | — | — |
|
|||
|
|
| 12 | 6 个 route 模块并列 | — | — |
|
|||
|
|
|
|||
|
|
**关键指标**:`backend/routes` 的**平均扇出是 12**,而一个理想的 route 模块只该依赖 1 个 service + 契约层(3-4)。这 3-4 倍的超额**全部来自散落在 route 里的装配代码**——这是把 §1.4 认定为首要重构点的量化依据。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.3 循环依赖证据:36 处函数体内 import 的逐条归因
|
|||
|
|
|
|||
|
|
模块粒度上**没有真循环**(Tarjan SCC 只在 `adapters/__init__` ↔ `adapters.onebot11_adapter` / `adapters.wechat_adapter` 之间,属 `__init__` re-export 的正常形态)。但全仓有 36 处缩进的(函数体内)import `[实测,分布逐条核对]`。这类写法在 Python 项目里通常是循环依赖的"疤痕",因此逐条归因如下——**结论是:36 处里只有 3 处真正在规避 import 环,其余是可选依赖守卫或纯遗漏**。不要把这个数字当作"循环依赖严重"的证据。
|
|||
|
|
|
|||
|
|
| 文件 | 处数 | 行号 | 归因 | 规避的是哪个环 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| `main.py` | 6 | `:178-183` | **可选依赖守卫**。`from astrbot.api.star import Star` 等,在 AstrBot API 缺失时降级为 stub 类 | 无环 |
|
|||
|
|
| `main.py` | 2 | `:390`、`:412` | **真·规避 + 启动韧性**。`from backend.services.workflow_round_worker_runtime import create_workflow_round_worker_runtime`(`:390`)、`advanced_material_worker_runtime`(`:412`)。这两个 worker runtime 顶部 import `backend.routes.node_routes`,若在 `main.py` 顶部 import,模块加载期就会拉起整个 route 图;同时两处都包在 `try/except Exception` 里,让 worker 起不来时插件与恢复 UI 仍可用 | `main → worker_runtime → node_routes →(31 个依赖)` |
|
|||
|
|
| `main.py` | 8 | `:2307`、`:2317`、`:2469-2476`、`:2496`、`:2502`、`:2561` | **可选依赖守卫**。`astrbot.api.web` / `quart` / `starlette` 三套 HTTP 运行时按可用性择一 | 无环 |
|
|||
|
|
| `database/db_helper.py` | 4 | `:197-198`、`:216-217` | **可选依赖守卫**。`psycopg` / `psycopg2` 双驱动探测 | 无环 |
|
|||
|
|
| `backend/services/model_provider_runtime.py` | 3 | `:128`、`:193`、`:282` | **可选运行时守卫**。`from core.astrbot_provider_bridge import astrbot_*`;核查 `core/astrbot_provider_bridge.py` 顶部 import(`core.image_formats`/`core.storage`/`engines.vision_provider`)**无任何回边到 `backend.services`** | 无环(可以安全提到顶部) |
|
|||
|
|
| `backend/routes/job_routes.py` | 2 | `:87`、`:204` | **重型构造延迟**。`from backend.services.advanced_material_service import create_advanced_material_service`(29 扇出的 God service) | 无环,纯性能/启动期考虑 |
|
|||
|
|
| `backend/routes/job_routes.py` | 1 | `:311` | **真·规避**。`from backend.routes.node_routes import _create_generation_service`,取私有名。注释:`Import lazily so route discovery does not construct provider runtimes` | `job_routes ↔ node_routes` 的 route 间横向依赖 |
|
|||
|
|
| `backend/services/generation_service.py` | 2 | `:1493`、`:1506` | **纯遗漏**。顶部 `:17-24` 已经从同一模块 import 了 6 个名字,函数体内又局部 import `PromptModerationDecision` / `GenerationRouteDecision` | **无环**——这两处制造了"这里有循环依赖"的误导信号,直接并入顶部 import 块即可 |
|
|||
|
|
| 其余 8 处 | 8 | `engines/image_provider.py`、`core/runtime_paths.py`、`core/generation_errors.py`、`backend/services/{quick_profile,material,api_discovery}_service.py`、`adapters/{webui_adapter,astrbot_card_renderer}.py` 各 1 | 可选依赖/重型库延迟加载 | 无环 |
|
|||
|
|
|
|||
|
|
**可执行结论**:
|
|||
|
|
- 立刻能做:删掉 `generation_service.py:1493/1506` 两处冗余 import(0 风险),把 `model_provider_runtime.py` 的 3 处提到顶部(需确认 `core.astrbot_provider_bridge` 无启动副作用)。这样 36 降到 31,剩下的每一处都有明确理由。
|
|||
|
|
- `job_routes.py:311` 与 `workflow_round_worker_runtime.py:10` 这两条真环,由 §1.4 的组合根一次性消除。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.4 装配分散:本项目最有价值的重构点
|
|||
|
|
|
|||
|
|
### 1.4.1 事实
|
|||
|
|
|
|||
|
|
`[实测]` `backend/routes/` 下共有 **35 个装配函数**分布在 **20 个 route 模块**里,其中 20 个严格命名为 `_create_*_service()` / `create_*_service()`(A7 按 `_create_*_service` 口径计为 22 个);全仓 **34 处 `Database(load_database_settings())`**。`load_database_settings()` → `load_config_payload()` → `path.read_text()` 全链路**无任何缓存**(`db_helper.py` / `core/config_service.py` 中 `lru_cache` 出现次数为 0)。
|
|||
|
|
|
|||
|
|
`node_routes._create_generation_service()` 内还会额外再调一次 `load_config_payload()`,也就是**一次生成请求至少两次磁盘 YAML 解析**,外加 9 个 repository、1 个 provider runtime、4 个 governance 服务的重新构造:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/node_routes.py:316, 327
|
|||
|
|
database = Database(load_database_settings()) # 第 1 次读盘
|
|||
|
|
...
|
|||
|
|
config_payload = load_config_payload() # 第 2 次读盘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1.4.2 已确认的两例行为不一致
|
|||
|
|
|
|||
|
|
这不是理论风险,是两处可复现的功能缺失。
|
|||
|
|
|
|||
|
|
**例 1:素材绑定事件被静默丢弃**
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/node_material_routes.py:65-73 ← GET/POST node materials 的唯一装配路径
|
|||
|
|
def _create_service() -> WorkflowNodeMaterialService:
|
|||
|
|
database = Database(load_database_settings())
|
|||
|
|
profiles = ProfileRepository(database)
|
|||
|
|
workflows = WorkflowRepository(database)
|
|||
|
|
workflow_service = WorkflowService(
|
|||
|
|
workflow_repository=workflows,
|
|||
|
|
profile_repository=profiles,
|
|||
|
|
audit_service=AuditService(database),
|
|||
|
|
) # ← 没有 event_bus=
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/services/workflow_node_material_service.py:208-218
|
|||
|
|
if self.workflow_service.event_bus: # ← 恒为 None,整块被跳过
|
|||
|
|
self.workflow_service.event_bus.publish(
|
|||
|
|
"workflow.node_material_bindings_updated", {...})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
对照 `backend/routes/profile_routes.py:176-181` 的同类工厂,`event_bus=get_default_event_bus()` 是传了的。8 处 `WorkflowService(...)` 构造中只有 4 处传入 `event_bus`。
|
|||
|
|
|
|||
|
|
**例 2:分支事件不推送**
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/branch_routes.py:62-68
|
|||
|
|
def _create_workflow_service() -> WorkflowService:
|
|||
|
|
database = Database(load_database_settings())
|
|||
|
|
return WorkflowService(
|
|||
|
|
workflow_repository=WorkflowRepository(database),
|
|||
|
|
profile_repository=ProfileRepository(database),
|
|||
|
|
audit_service=AuditService(database),
|
|||
|
|
) # ← 同样没有 event_bus=
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
漏传的还有 `history_routes.py:72`、`review_routes.py:90`。
|
|||
|
|
|
|||
|
|
**为什么排查成本极高**:消费端写的是 `if self.workflow_service.event_bus:`——这是**穿透邻居对象属性**取总线(迪米特法则违规)。判空短路后没有日志、没有异常、没有降级提示。前端 `GET events/stream` 就是看不到这些事件,任何基于事件做增量刷新的功能静默失效。
|
|||
|
|
|
|||
|
|
同源问题还在 `generation_service.py` 内部:同一个类里有两套取总线的写法——`self.event_bus`(构造注入,`_publish()` 用,5 处)和 `self.workflow_service.event_bus`(穿透邻居,`:1416-1427` 处 2 处)。目前在 `_create_generation_service()` 里两者恰好是同一个 `DEFAULT_EVENT_BUS` 所以没暴露;但只要有人拿 `node_material_routes` / `branch_routes` / `history_routes` / `review_routes` 那种未注入 `event_bus` 的 `WorkflowService` 去构造 `GenerationService`,`workflow.node_status_changed` 就会一起静默丢失。
|
|||
|
|
|
|||
|
|
### 1.4.3 装配代码大段复制
|
|||
|
|
|
|||
|
|
同一套 "读 config → sync provider → 解析 prompt_governance → 造 callable → 造 SingleFlowEngine" 流程被逐行复制了三份:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/node_routes.py:331-339
|
|||
|
|
governance_config = config_payload.get("prompt_governance") if isinstance(...) else {}
|
|||
|
|
moderation_config = governance_config.get("moderation") if isinstance(...) else {}
|
|||
|
|
moderation_route = str(moderation_config.get("model_route") or model_assignments.get("cross_review_primary") or "").strip()
|
|||
|
|
moderation_callable = (model_provider_runtime.structured_text_callable(moderation_route)
|
|||
|
|
or astrbot_structured_text_callable(moderation_route)) if moderation_route else None
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/services/advanced_material_service.py:1731-1746 ← 同构复制
|
|||
|
|
moderation_config = governance_config.get("moderation") if isinstance(...) else {}
|
|||
|
|
moderation_route = str(... or model_assignments.get("cross_review_primary") or "").strip()
|
|||
|
|
moderation_callable = (runtime.structured_text_callable(moderation_route)
|
|||
|
|
or astrbot_structured_text_callable(moderation_route)) if moderation_route else None
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
第三处在 `backend/routes/prompt_routes.py:63-64`,又独立造了一遍 `PromptModerationService` 与 `GenerationRouteService`。
|
|||
|
|
|
|||
|
|
**后果**:governance 配置结构一旦变化(新增字段、改默认回退键),必须同步修改 3 处;漏改会造成"网页生成走新策略、素材导入/聊天走旧策略"的行为分叉,**且这种分叉不会报错**。
|
|||
|
|
|
|||
|
|
另有 5 处靠属性穿透拿 `Database`:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/services/workflow_round_worker_runtime.py:192-193 与 backend/routes/round_routes.py:138-139
|
|||
|
|
generation_service = create_generation_service()
|
|||
|
|
database = generation_service.queue_service.repository.database # ← 三级穿透
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/services/workflow_round_service.py:66-71
|
|||
|
|
self.resource_access_service = resource_access_service or ResourceAccessService(
|
|||
|
|
ProfileRepository(round_repository.database), ...) # ← 穿透 repository 的内部 database
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`Repository.database` 因此从实现细节变成了事实上的公开 API:任何仓储重构(例如改持有连接池)会同时打断 5 个调用点,而对象图的真实依赖在构造函数签名上完全看不见。
|
|||
|
|
|
|||
|
|
### 1.4.4 方案:统一装配容器
|
|||
|
|
|
|||
|
|
**目标**:`backend/composition.py` 成为全仓唯一的组合根,依赖方向恢复为 `routes → composition → services → repositories`,`worker → composition → services`。
|
|||
|
|
|
|||
|
|
**代码骨架**:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/composition.py —— 唯一组合根
|
|||
|
|
"""Single composition root. Nothing outside this module may construct a service graph."""
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
import threading
|
|||
|
|
from dataclasses import dataclass
|
|||
|
|
from typing import Any
|
|||
|
|
|
|||
|
|
from core.config_loader import load_config_payload # §1.1 第 3 步下沉后的位置
|
|||
|
|
from core.audit_service import AuditService
|
|||
|
|
from database.db_helper import Database, load_database_settings
|
|||
|
|
from backend.services.event_stream_service import get_default_event_bus
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass(frozen=True)
|
|||
|
|
class _Graph:
|
|||
|
|
"""一次装配的产物;按 config 指纹缓存。"""
|
|||
|
|
config_fingerprint: tuple[str, float]
|
|||
|
|
database: Database
|
|||
|
|
workflow_service: Any
|
|||
|
|
generation_service: Any
|
|||
|
|
round_service: Any
|
|||
|
|
node_material_service: Any
|
|||
|
|
# ... 其余按需
|
|||
|
|
|
|||
|
|
|
|||
|
|
_lock = threading.Lock()
|
|||
|
|
_graph: _Graph | None = None
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _fingerprint() -> tuple[str, float]:
|
|||
|
|
"""(path, mtime) —— config.yaml 变了就重建整棵树。"""
|
|||
|
|
from core.runtime_paths import resolve_config_path
|
|||
|
|
path = resolve_config_path("config.yaml")
|
|||
|
|
return (str(path), path.stat().st_mtime if path.exists() else 0.0)
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _build(fingerprint: tuple[str, float]) -> _Graph:
|
|||
|
|
database = Database(load_database_settings())
|
|||
|
|
config_payload = load_config_payload() # 整棵树只读一次盘
|
|||
|
|
audit = AuditService(database)
|
|||
|
|
bus = get_default_event_bus() # ← 唯一来源,杜绝漏传
|
|||
|
|
|
|||
|
|
# --- 仓储层 ---
|
|||
|
|
from database.repositories.workflow_repository import WorkflowRepository
|
|||
|
|
from database.repositories.profile_repository import ProfileRepository
|
|||
|
|
workflows = WorkflowRepository(database)
|
|||
|
|
profiles = ProfileRepository(database)
|
|||
|
|
# ...
|
|||
|
|
|
|||
|
|
# --- governance bundle:取代三份复制 ---
|
|||
|
|
governance = build_governance_bundle(config_payload, model_provider_runtime)
|
|||
|
|
|
|||
|
|
# --- 服务层 ---
|
|||
|
|
from backend.services.workflow_service import WorkflowService
|
|||
|
|
workflow_service = WorkflowService(
|
|||
|
|
workflow_repository=workflows,
|
|||
|
|
profile_repository=profiles,
|
|||
|
|
audit_service=audit,
|
|||
|
|
event_bus=bus, # ← 显式且唯一
|
|||
|
|
)
|
|||
|
|
# ... generation_service / round_service / node_material_service 同理
|
|||
|
|
return _Graph(fingerprint, database, workflow_service, ..., )
|
|||
|
|
|
|||
|
|
|
|||
|
|
def graph() -> _Graph:
|
|||
|
|
global _graph
|
|||
|
|
fp = _fingerprint()
|
|||
|
|
with _lock:
|
|||
|
|
if _graph is None or _graph.config_fingerprint != fp:
|
|||
|
|
_graph = _build(fp)
|
|||
|
|
return _graph
|
|||
|
|
|
|||
|
|
|
|||
|
|
# --- 公开访问器:route / worker 只用这些 ---
|
|||
|
|
def get_workflow_service(): return graph().workflow_service
|
|||
|
|
def get_generation_service(): return graph().generation_service
|
|||
|
|
def get_round_service(): return graph().round_service
|
|||
|
|
def get_node_material_service(): return graph().node_material_service
|
|||
|
|
def get_database() -> Database: return graph().database # 取代 5 处属性穿透
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
route 侧的调用点退化为一行:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/node_material_routes.py(改后)
|
|||
|
|
from backend.composition import get_node_material_service
|
|||
|
|
|
|||
|
|
def save_node_material_bindings(ctx, node_id, payload=None, service=None) -> dict:
|
|||
|
|
material_service = service or get_node_material_service() # ← 原 10 行工厂消失
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
worker 侧的反向依赖直接消失:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/services/workflow_round_worker_runtime.py:10(改后)
|
|||
|
|
from backend.composition import get_generation_service, get_database # 不再 import backend.routes.*
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**配套的两条护栏测试**(没有这两条,同类漏传还会再犯):
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# tests/test_composition_invariants.py
|
|||
|
|
def test_every_workflow_service_has_event_bus():
|
|||
|
|
"""禁止再出现漏传 event_bus 的装配路径。"""
|
|||
|
|
from backend.composition import get_workflow_service, get_generation_service
|
|||
|
|
assert get_workflow_service().event_bus is not None
|
|||
|
|
assert get_generation_service().event_bus is not None
|
|||
|
|
assert get_generation_service().workflow_service.event_bus is not None
|
|||
|
|
|
|||
|
|
|
|||
|
|
def test_no_route_module_builds_a_service_graph():
|
|||
|
|
"""route 层不得再出现 Database(...) 或 *Service(...) 构造。"""
|
|||
|
|
import pathlib, re
|
|||
|
|
offenders = []
|
|||
|
|
for path in pathlib.Path("backend/routes").glob("*.py"):
|
|||
|
|
src = path.read_text(encoding="utf-8")
|
|||
|
|
if re.search(r"Database\(load_database_settings\(\)\)", src):
|
|||
|
|
offenders.append(str(path))
|
|||
|
|
assert offenders == [], f"route modules must use backend.composition: {offenders}"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**迁移顺序**(可增量,每步都能独立合并):
|
|||
|
|
|
|||
|
|
1. 先建 `backend/composition.py`,只迁 `WorkflowService` 一族 + 那条 `test_every_workflow_service_has_event_bus`。这一步就修掉了两例事件丢失。
|
|||
|
|
2. 迁 `_create_generation_service`(`node_routes.py:315-390`)→ `composition`,`node_routes` 与 `job_routes.py:311` 改为从 composition 取。这一步消除 `service → route` 与 route↔route 两条环。
|
|||
|
|
3. 抽 `build_governance_bundle(config_payload, runtime) -> GovernanceBundle`(含 translation/moderation/routing/image_moderation 四个服务),`node_routes` / `advanced_material_service` / `prompt_routes` 三处统一调用。
|
|||
|
|
4. 逐个迁剩余 route 工厂,最后开启 `test_no_route_module_builds_a_service_graph`。
|
|||
|
|
|
|||
|
|
**收益量化**:`backend/routes` 平均扇出可从 12 降到 3-4;34 处磁盘 YAML 解析降到"每次 config 变更 1 次";两例已确认的事件丢失被修复且不可复发;`node_routes` 从扇出 31 降到个位数。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.5 服务耦合簇
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TD
|
|||
|
|
subgraph C1["簇 1 · workflow / generation(19 条 service→service 直连边)"]
|
|||
|
|
NR["routes.node_routes<br/>扇出31 · 事实组合根(位置错误)"]
|
|||
|
|
GS["generation_service<br/>2432 行 / 21 参数构造函数"]
|
|||
|
|
WS["workflow_service<br/>扇入15 · 扇出14 · 枢纽"]
|
|||
|
|
WRS["workflow_round_service<br/>1596 行"]
|
|||
|
|
WRWR["workflow_round_worker_runtime"]
|
|||
|
|
BLS["branch_lineage_service"]
|
|||
|
|
WNMS["workflow_node_material_service"]
|
|||
|
|
NDCS["node_dependency_context_service"]
|
|||
|
|
WGCRS["workflow_generation_cross_review_service"]
|
|||
|
|
GJRS["generation_job_retry_service"]
|
|||
|
|
WPS["workflow_progression_service"]
|
|||
|
|
IS["image_service"]
|
|||
|
|
QS["queue_service"]
|
|||
|
|
WMSS["workflow_material_snapshot_service"]
|
|||
|
|
WRR[("db · workflow_round_repository")]
|
|||
|
|
WCRR[("db · workflow_cross_review_repository")]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
GS --> WS
|
|||
|
|
GS --> QS
|
|||
|
|
GS --> IS
|
|||
|
|
GS --> WMSS
|
|||
|
|
GS --> NDCS
|
|||
|
|
WRS --> GS
|
|||
|
|
WRS --> WPS
|
|||
|
|
WRWR --> GS
|
|||
|
|
WRWR --> WRS
|
|||
|
|
WRWR -.->|"违规:service→route"| NR
|
|||
|
|
NR --> GS
|
|||
|
|
WGCRS --> WRS
|
|||
|
|
GJRS --> GS
|
|||
|
|
WS --> BLS
|
|||
|
|
WS --> WPS
|
|||
|
|
WS --> QS
|
|||
|
|
WNMS --> WS
|
|||
|
|
WNMS --> BLS
|
|||
|
|
NDCS --> WS
|
|||
|
|
NDCS --> BLS
|
|||
|
|
IS --> WS
|
|||
|
|
IS --> WPS
|
|||
|
|
WRR -.->|"违规:db→service"| BLS
|
|||
|
|
WCRR -.->|"违规:db→service"| BLS
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**簇 1(workflow/generation)**:14 个 service + 1 个 route + 2 个 repository,**19 条 service→service 直连边**。中心是 `workflow_service`(扇入 15 / 扇出 14)与 `generation_service`(扇出 21)。三条虚线为方向违规边。
|
|||
|
|
|
|||
|
|
**簇 2(advanced material / style)**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
advanced_material_service (1856 行, 45 方法, 14 参数构造函数, 自带工厂 :1700-1764)
|
|||
|
|
├─→ advanced_style_set_service (4491 行 · 单类 2092 行 · 31 方法 · 81 个模块级私有函数)
|
|||
|
|
├─→ material_service
|
|||
|
|
├─→ material_normalization_service
|
|||
|
|
├─→ worker_service
|
|||
|
|
├─→ queue_service
|
|||
|
|
├─→ cost_service
|
|||
|
|
├─→ cost_guard_service
|
|||
|
|
├─→ model_provider_service / model_provider_runtime / model_provider_bootstrap
|
|||
|
|
├─→ prompt_governance_service
|
|||
|
|
└─→ event_stream_service
|
|||
|
|
单模块直连 12 个 service
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**全仓没有任何接口/协议隔离**:无 `Protocol`、无 `ABC` 定义的 service 接口,所有 service→service 都是具体类硬 import。唯一的"接口化"痕迹是 `chat_workflow_service.py:22` 的 `Dispatcher = Callable[..., dict[str, Any]]`,但它是完全无类型约束的字符串分发(见下)。
|
|||
|
|
|
|||
|
|
**特别注意 `ChatWorkflowService`**:这个 1315 行的 service 不直接调用任何业务 service,而是把 `dispatch_web_request` 当 HTTP 客户端用,以字符串 method + path **69 次**重新进入路由层,数据流变成 `service → adapter → route → service`:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# main.py:372
|
|||
|
|
self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
|
|||
|
|
|
|||
|
|
# backend/services/chat_workflow_service.py:33-47(典型调用)
|
|||
|
|
active = self._data(self.dispatcher(ctx, "GET", "jobs", query={"status": "running", ...}))
|
|||
|
|
workflow = self._data(self.dispatcher(ctx, "POST", f"profiles/{profile['profile_id']}/workflows", payload={...}))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
代价:(1) **类型安全全失**——路径/参数名拼错只在运行时返回 `RESOURCE_NOT_FOUND`,IDE 与静态检查看不到这 69 条调用边,重命名任一路由会静默打断聊天流程;(2) **性能**——每次 dispatch 走 `inspect.signature` 反射 + route 内 `_create_*_service()` 全量重建(含磁盘读 `config.yaml`),一条聊天命令动辄十几次 dispatch;(3) **错误语义扭曲**——异常被 route 层包成 dict,service 再用 `self._data()` 拆包,异常栈完全丢失。
|
|||
|
|
|
|||
|
|
组合根落地后,`ChatWorkflowService` 应改为依赖 `backend/composition.py` 暴露的具体 service 对象。若要保留"聊天走公开契约"的设计意图,至少把 69 个字符串端点收敛成一个类型化门面(`class ImageStudioApi` + 每端点一方法,内部仍走 dispatcher),让重命名有静态检查保护。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.6 `core/event_bus.py` 使用情况评估
|
|||
|
|
|
|||
|
|
**结论:它不是事件总线,是一个被误命名的环形缓冲区。**
|
|||
|
|
|
|||
|
|
| 指标 | 实际值 |
|
|||
|
|
|---|---|
|
|||
|
|
| `subscribe()` 调用方(含 46 个测试文件) | **0** |
|
|||
|
|
| `unsubscribe()` 调用方 | **0** |
|
|||
|
|
| `publish()` 调用点 | 6 处:`generation_service.py:1417/1427/1703`、`queue_service.py:702`、`workflow_node_material_service.py:209` |
|
|||
|
|
| 实际用途 | `GET events/stream` 的 500 条进程内历史窗口(`EventBus(history_limit=500)`,`event_stream_service.py:11-15`) |
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# core/event_bus.py:36-50
|
|||
|
|
def subscribe(self, event_type: str, handler: EventHandler) -> None: # ← 零调用方
|
|||
|
|
normalized = _normalize_event_type(event_type)
|
|||
|
|
if handler not in self._handlers[normalized]:
|
|||
|
|
self._handlers[normalized].append(handler)
|
|||
|
|
...
|
|||
|
|
def publish(self, event_type: str, payload: dict[str, Any] | None = None) -> Event:
|
|||
|
|
event = Event(...)
|
|||
|
|
self._history.append(event)
|
|||
|
|
for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
|
|||
|
|
handler(event) # ← 永远遍历空列表
|
|||
|
|
return event
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**三条具体问题**:
|
|||
|
|
|
|||
|
|
1. **零解耦价值**。`workflow_round_service → generation_service`、`generation_job_retry_service → generation_service`、`deletion_safety_service → image_service/media_service` 这些"做完 A 顺手通知 B"的调用,本来正是总线该承接的,现在全部是硬 import——所以簇 1 才有 19 条直连边。
|
|||
|
|
2. **一旦有人开始订阅就立刻踩坑**。`publish` 是同步调用,handler 抛异常会直接打断业务事务;`_handlers` 是 `defaultdict(list)`,`subscribe/unsubscribe` **无锁**,而 `DEFAULT_EVENT_BUS` 被 `QueueWorkerPool` 的工作线程和请求线程共享。目前因为没有 handler 所以未暴露。
|
|||
|
|
3. **它伪装成解耦手段,误导架构判断**。看到 `EventBus` 的人会假设跨服务通信有异步通道,实际没有。
|
|||
|
|
|
|||
|
|
**建议二选一,不要维持现状**:
|
|||
|
|
|
|||
|
|
- **方案 A(推荐,若打算用)**:先给 `publish` 加异常隔离(`try/except` 包每个 handler,失败只记日志不冒泡)+ 给 `subscribe/unsubscribe/_handlers` 加 `threading.Lock`;然后把 3 组"通知型"直连迁到总线:`generation_service → workflow_service` 的节点状态回写、`queue_service → 终态通知回调`(目前靠 `workflow_round_worker_runtime` 的 `terminal_notification_callback` 参数手动穿到 `main.py:1672`)、`deletion_safety_service → image/media` 的级联清理。
|
|||
|
|
- **方案 B(若不打算用)**:删掉 `subscribe` / `unsubscribe` / `_handlers`,把类改名为 `EventRecorder`,明确它就是给 `events/stream` 用的历史缓冲。**别让它继续伪装成解耦手段。**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1.7 `main.py` 2,580 行的职责分解
|
|||
|
|
|
|||
|
|
| 行号区间 | 行数 | 职责 | 处置 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1-27 | 27 | import + `PLUGIN_ROOT` | **保留** |
|
|||
|
|
| 28-98 | 71 | `_prepend_plugin_package_path()` 包路径 shim | → `core/plugin_bootstrap.py` |
|
|||
|
|
| 100-172 | 73 | `_RUNTIME_PATH_TO_ASTRBOT_KEY`(66 条配置映射表) | → `core/astrbot_config_mapping.py` |
|
|||
|
|
| 174-221 | 48 | AstrBot API 缺失时的 fallback stub 类 | → `adapters/astrbot_stubs.py` |
|
|||
|
|
| 223-352 | 130 | 模块级门面(`get_plugin_manifest` / `register_plugin` / `dispatch_web_request` / `register_bridge_api`) | **保留**,这是 main 的正当职责 |
|
|||
|
|
| 354-447 | 94 | `Main.__init__` / `initialize` / `terminate` | **保留**,唯一真正的生命周期代码 |
|
|||
|
|
| 449-1297 | 849 | 长命令聊天处理器(约 50 个 `imagestudio_*`),含 `imagestudio_confirm` 里的 session action 分派业务逻辑(549-612) | → `backend/chat/commands/*.py`,按域拆 5-6 个模块 |
|
|||
|
|
| 1299-1463 | 165 | `yp` 短别名,**每个方法都是 3 行纯转发** | **全部删除**,改数据驱动注册(见下) |
|
|||
|
|
| 1465-1751 | 287 | 文本格式化 helper + 后台任务 + 主动推送 + 终态通知重放 | 格式化 → `backend/chat/formatters.py`;推送 → `backend/chat/notifier.py` |
|
|||
|
|
| 1753-1927 | 175 | 桥接注册路由表 + 配置持久化 | → `adapters/astrbot_bridge.py` |
|
|||
|
|
| 1929-2205 | 277 | `_runtime_config_patch_from_mapping`(66 条映射的**反方向手写实现**) | → `core/astrbot_config_mapping.py`,并压到 ~50 行 |
|
|||
|
|
| 2208-2580 | 373 | HTTP 请求/响应适配(`_make_bridge_handler`、`_request_query`、`_to_bridge_response`、`_to_media_http_response` 等 20 个私有函数) | → `adapters/astrbot_http.py` |
|
|||
|
|
|
|||
|
|
**归类占比**:真正的初始化/生命周期 **94 行(3.6%)**;对外门面 130 行(5%);聊天业务与呈现 1301 行(50.4%);AstrBot 配置与 HTTP 桥接 825 行(32%);环境 shim 192 行(7.4%)。
|
|||
|
|
|
|||
|
|
**拆分后 `main.py` 目标规模:约 250 行**(27 + 130 + 94 + 少量粘合)。
|
|||
|
|
|
|||
|
|
两处可以立刻做、零风险的压缩:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 替代 1299-1463 的 165 行手写转发
|
|||
|
|
_SHORT_ALIASES = {
|
|||
|
|
"帮助": "imagestudio_help", "状态": "imagestudio_status",
|
|||
|
|
"快速角色": "imagestudio_quick_profile", ... # 约 40 条
|
|||
|
|
}
|
|||
|
|
for _alias, _target in _SHORT_ALIASES.items():
|
|||
|
|
_bind_short_alias(Main, imagestudio_short_command, _alias, _target)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 替代 1929-2205 的 277 行反向映射:让 :108-172 的 dict 成为唯一真相
|
|||
|
|
def _runtime_config_patch_from_mapping(mapping: Mapping[str, Any]) -> dict[str, Any]:
|
|||
|
|
patch: dict[str, Any] = {}
|
|||
|
|
for path, astrbot_key in _RUNTIME_PATH_TO_ASTRBOT_KEY.items():
|
|||
|
|
value = _runtime_value(mapping, astrbot_key)
|
|||
|
|
if value is _MISSING:
|
|||
|
|
continue
|
|||
|
|
coerce = _COERCIONS.get(path, _runtime_text) # postgresql.port→int、*_enabled→bool、allowlist→list
|
|||
|
|
coerced = coerce(value)
|
|||
|
|
if coerced not in ("", None):
|
|||
|
|
_set_nested(patch, tuple(path.split(".")), coerced)
|
|||
|
|
return patch
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
后者尤其值得做:目前 66 条配置关系被**正反两个方向各写一遍**(声明式 dict 在 `:108-172`,命令式 279 行在 `:1929-2205`,相隔 1800 行)。脚本比对确认两侧当前覆盖的 66 个 AstrBot 键完全一致——**靠人工维持**。新增一个配置项要在两个相隔 1800 行的位置各改一次,只改一边就得到"能读不能写"或"能写不能读"的单向配置,且不会有任何报错。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 第二部分 · 前后端耦合
|
|||
|
|
|
|||
|
|
## 2.1 端点比对三张表
|
|||
|
|
|
|||
|
|
比对方法:从 `backend/route_registry.py` 提取 166 条 `RouteSpec` `[实测]`,与 `frontend/shared/api/endpoints.ts` 的 143 个键 `[实测]` 及全前端 `endpoints.<key>` 引用做交叉。
|
|||
|
|
|
|||
|
|
### 表 ① 后端注册但前端从不调用(14 条死接口)
|
|||
|
|
|
|||
|
|
| # | 方法 | 端点 | handler | 判定 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| 1 | DELETE | `profiles/{profile_id}` | `profile_routes.delete_profile` | 死。UI「删除角色」实际调 `profileArchive`(`App.vue:6300`) |
|
|||
|
|
| 2 | POST | `profiles/{profile_id}/delete` | `profile_routes.delete_profile_via_post` | 死。`endpoints.profileDelete` 定义了但零引用 |
|
|||
|
|
| 3 | POST | `images/{image_id}/moderation-review` | `image_routes.review_moderated_image` | 死。见 §2.2 表外说明 |
|
|||
|
|
| 4 | POST | `advanced-material-imports/{import_id}/cancel` | `advanced_material_routes.cancel_advanced_material_import` | 死。endpoints.ts 里连键都没有 |
|
|||
|
|
| 5 | POST | `nodes/{node_id}/mark-completed` | `node_routes.mark_node_completed` | 死。是 `nodes/{id}/complete` 的同 handler 别名 |
|
|||
|
|
| 6 | POST | `nodes/{node_id}/select-image` | `node_routes.select_node_image` | 死。前端只用 `images/{id}/select` |
|
|||
|
|
| 7 | POST | `prompts/expand` | `prompt_routes.expand_prompt` | 死。前端只用 `prompts/governance-preview` |
|
|||
|
|
| 8 | GET | `profile-cards/{card_id}` | `profile_card_routes.get_profile_card` | 死 |
|
|||
|
|
| 9 | DELETE | `profiles/{profile_id}/wardrobe/{wardrobe_item_id}` | `wardrobe_routes.delete_wardrobe_item` | 死。legacy 别名,前端只用 `/wardrobe/items/{id}` |
|
|||
|
|
| 10 | GET | `materials/analytics` | `material_routes.material_analytics` | 死 |
|
|||
|
|
| 11 | POST | `materials/renormalize-batch` | `material_routes.renormalize_materials_batch` | 死 |
|
|||
|
|
| 12 | POST | `materials/{material_id}/renormalize` | `material_routes.renormalize_material` | 死 |
|
|||
|
|
| 13 | GET | `integrations/logs` | `integration_routes.list_integration_logs` | 死。前端只用 `logs/integrations` |
|
|||
|
|
| 14 | POST | `api-discovery/probe-model` | `api_discovery_routes.probe_model` | 死。前端只用 `probe-provider` |
|
|||
|
|
|
|||
|
|
> `GET media/fetch` 虽不在 endpoints.ts 中,但通过 `MediaService.sign_media()` 返回的签名 URL 被间接消费(`round_routes.py:196`、`image_routes.py:229`),**不算死接口**。它是全仓唯一声明 `auth_required: False` 的路由(`route_registry.py:173`)。
|
|||
|
|
|
|||
|
|
其中 #1 / #2 与 `POST profiles/{id}/archive` 三条路由指向同一个函数体:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/routes/profile_routes.py:101-114
|
|||
|
|
def delete_profile_via_post(ctx, profile_id, payload=None, service=None) -> dict:
|
|||
|
|
return delete_profile(ctx, profile_id, service)
|
|||
|
|
|
|||
|
|
def archive_profile(ctx, profile_id, service=None) -> dict:
|
|||
|
|
return delete_profile(ctx, profile_id, service)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**注意**:初审曾把这条列为「`/archive` 执行删除 → 用户意图被扭曲」的 P1 缺陷,**经复核推翻**——前端唯一调用方是一个文案为「删除」、样式为 `danger-button`、提示为「删除角色档案」的按钮(`ProfileDetailPane.vue:190-198`),用户意图与后端行为一致;profile 状态机里压根没有 `archived` 态。残留的只是 **P3 级 REST 路径命名误导 + 三条等价入口冗余**。若照初审建议把 `/archive` 改成真归档,反而会让当前的删除按钮不删除,引入功能回归。
|
|||
|
|
|
|||
|
|
### 表 ② 前端调用但后端不存在(会 404)
|
|||
|
|
|
|||
|
|
**空表。** 143 个 endpoints.ts 路径模板逐条与 `route_registry.ROUTES` 比对,全部命中,无一遗漏。
|
|||
|
|
|
|||
|
|
### 表 ③ 前端绕过 endpoints.ts 硬编码 URL
|
|||
|
|
|
|||
|
|
| 位置 | 内容 | 判定 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `frontend/standalone-web/vite.config.ts:11` | `base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/"` | 真实重复,但静态资源 base 必须编译期确定,见 §2.4 |
|
|||
|
|
| `frontend/shared/api/astrbot-page-bridge.ts:119-120` | `request<T>("api:get" ...)` | **误报**,是 postMessage 的 kind 常量,不是 HTTP 路径 |
|
|||
|
|
|
|||
|
|
`[实测]` `grep -rn "\"/api/\|'/api/" frontend/standalone-web/src frontend/shared frontend/plugin-page/src` 全树**只有 1 处命中,就是 `endpoints.ts:1` 的 `API_BASE` 定义本身**。`App.vue` 中 `endpoints.` 出现 183 次、覆盖 85 个不同端点;所有 `getJson/postJson/putJson/deleteJson` 的第一参数都来自 `endpoints.*`,`buildUrl`(`client.ts:297-306`)是唯一的 URL 构造点。
|
|||
|
|
|
|||
|
|
**这一维度做得很干净,应当保持。** 唯一的改进点是运行期化:后端已经通过 `bootstrap.api_base` 把 `API_BASE` 下发给前端了(`ui_service.py:10` 是后端侧单点),但前端拿到它之后的唯一用途是拼一句提示文案(`App.vue:4330`),实际请求路径始终来自编译期常量。建议 `client.ts` 的 `buildUrl` 改为优先使用运行期值(模块内 `let runtimeApiBase = API_BASE`,bootstrap 成功后 `setApiBase(...)`),vite base 保持编译期常量但加一条测试断言它以 `endpoints.ts` 的 `API_BASE` 开头。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2.2 业务逻辑重复实现(本节是前后端耦合的核心)
|
|||
|
|
|
|||
|
|
前端重写后端逻辑的位置对照。**严重度一律以 `_复核结论.md` 的逐条判定为准**:**没有一条维持 P1** —— #1/#2 降为 P2,#3/#4/#5/#6 降为 P3,其中 #4/#5/#6 是被整条推翻后只保留残留技术债。
|
|||
|
|
|
|||
|
|
> **终审更正**:本节初稿曾把 #1/#2/#3 标为"维持 P1",与复核结论不符,现已按复核给出的 P2/P2/P3 更正。这三条的**耦合事实全部成立**(代码、行号、可达性均经复核核实),降级的是**影响判定**,不是事实。它们依然是本报告推荐的解耦重点,只是不应按 P1 抢占安全与队列正确性的排期。
|
|||
|
|
|
|||
|
|
### 汇总表
|
|||
|
|
|
|||
|
|
| # | 前端位置 | 后端权威位置 | 严重度 | 已漂移的具体差异 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| 1 | `App.vue:5786-6076`(`generateQuickCharacterImages`,291 行) | `backend/services/quick_character_consistency.py` + 工作流状态机 | **P2**(经复核降级) | 工作流终态由浏览器推断并 PUT;关标签页即产生僵尸工作流 |
|
|||
|
|
| 2 | `App.vue:10837-10859` + `:927` | `workflow_progression_service.py:175-199` | **P2**(经复核降级) | 四层完成判定规则被逐条复刻,含 legacy 兼容分支与版本号字面量 |
|
|||
|
|
| 3 | `workflow-lock-state.ts:8-27`(`sealed_at` 在 `:12`) | `workflow_round_service.py:1145-1155` | **P3**(经复核降级) | 少判 1 个真实条件(`selected_image_id`);多判 1 个后端零产出的字段 |
|
|||
|
|
| 4 | `App.vue:6126`(`quickCharacterPrompt` 指令表) | `character_workflow_service.py:280-285` | P3 **(经复核降级)** | 4 条短指令措辞已漂移;`quick_avatar` 丢了 `keep identity consistent` |
|
|||
|
|
| 5 | `workflow-model-route.ts:36-88` | `generation_service.py:169-176 / 617-624 / 2026-2038` | P3 **(经复核降级)** | 候选链顺序与 `node_key → assignment` 映射表在前端各存一份 |
|
|||
|
|
| 6 | `App.vue:2786 / 3076 / 3139` | `route_registry.py:22-27` + `core/security.py:31-33` | P3 **(经复核降级)** | retry 卡片只判 `can_retry_tasks`,队列面板判了 `canWrite && canRetry` |
|
|||
|
|
| 7 | `App.vue:3285/3293/3628` + `presentation.ts:5` | `queue_service.py:31-34` | P2 | 4 处独立硬编码任务状态集合,第 4 份与后端任何常量都不完全相等 |
|
|||
|
|
| 8 | `App.vue:6927` + `WorkflowCandidatePool.vue:132` + `WorkflowRoundPanel.vue:113` + `presentation.ts:11` | 后端状态码 | P2 | 4 张中文标签表,译法互相冲突 |
|
|||
|
|
| 9 | `model-route-chain.ts:27-39` | `core/model_route_chain.py:52-66` | P2 | 同一线格式的两份独立实现,无跨语言一致性测试 |
|
|||
|
|
| 10 | `workflow-node-catalog.ts:23-32` + `workflow-model-route.ts:61-74` | `engines/character_flow.py:15-20` | P2 | 同一张 legacy 别名表三份,其中两份前端拷贝对 `expression_sheet` 映射不同 |
|
|||
|
|
| 11 | `client.ts:14` + `astrbot-page-bridge.ts:6` | 无(后端不存在 900 秒预算) | P2 | 18 分支正则逐字符重复两份,且固化了一个虚构契约 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### #1 · [P2,经复核降级] 快速角色四联图:291 行工作流状态机跑在浏览器里
|
|||
|
|
|
|||
|
|
- **前端**:`frontend/standalone-web/src/App.vue:5786-6076`(`generateQuickCharacterImages`)
|
|||
|
|
- **后端权威**:工作流状态推进本应由服务端负责;`backend/services/quick_character_consistency.py` 说明这一层后端本来就有
|
|||
|
|
|
|||
|
|
这个函数在浏览器里完成了:创建工作流 → 启动 → 提交锚点任务 → 并行提交 3 个从属任务 → 重新拉节点 → **自行推断工作流终态** → PUT 状态与 metadata → 失败时再 PUT `status: "failed"` 做补偿。
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
// App.vue:5945-5979 —— 前端判定工作流终态
|
|||
|
|
const generationCompleted = completedTargetKeys.length === QUICK_CHARACTER_TARGET_SPECS.length
|
|||
|
|
const nextWorkflowStatus = generationCompleted ? "completed" : pendingTargetKeys.length ? "running" : "failed"
|
|||
|
|
...
|
|||
|
|
if (normalizeStatus(workflow.status) !== nextWorkflowStatus) workflowUpdate.status = nextWorkflowStatus
|
|||
|
|
workflow = await putJson<ProfileWorkflow>(endpoints.workflow(workflow.workflow_id), workflowUpdate)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
// App.vue:6048-6061 —— 失败补偿也在前端
|
|||
|
|
const failedWorkflow = await putJson<ProfileWorkflow>(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`<br>`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`<br>`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`<br>`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`<br>`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 塞进 <pre>
|
|||
|
|
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。
|