# 05 · 优化路线图 > 决策文档。基于 15 个维度并行审计产出的 214 条发现、其中 56 条 P0/P1 经对抗式复核(推翻 16 条)后的 40 条成立结论。 > 发现明细见 [findings/](findings/);被推翻条目见 [findings/_复核结论.md](findings/_复核结论.md),本文件不再收录。 --- ## 1. 一页纸结论 这个项目**能跑、在被真实使用、且迭代速度很快**:后端 263 个 pytest 用例 188 秒全绿,前端 26 个 node:test 全绿,`npm run typecheck` 在 `strict` 下通过;分层意图清晰(`routes → services → repositories`,`core` 做横切);密码学原语写得认真(HMAC 一律 `hmac.compare_digest`、令牌带过期窗口、`remote_fetch` 的 SSRF 校验覆盖协议/凭据/私网/重定向降级/跨源剥 Authorization);队列的 CAS 原语(`update_task_if_status` / `claim_queued_task` / `delete_if_status`)和仓储里的 `*_atomic` 事务(`BEGIN IMMEDIATE` + `FOR UPDATE` + rollback)都是有意识设计的产物,不是碰运气写出来的。**问题不是"代码跑不起来",而是设计边界与技术债开始收利息。** 真正需要动手的是四件事,优先级严格按下列顺序:**第一,把已经泄漏的凭据轮换掉**——`.env.imagestudio_codex_handoff.yaml` 虽被 gitignore 且从未入库,但被"整目录复制"式的打包脚本带进了 `.tmp/` 下 19 个部署 tar 包,而同目录的部署脚本会 ssh/scp 推到 NAS,包内含 2 个可用的模型站 API Key、内网 PostgreSQL 明文口令、AstrBot 管理员 JWT 与明文管理员口令,这是**唯一一条 24 小时内必须闭环**的事项。**第二,把权限模型真正落地**——`backend/route_registry.py` 里那张六级 `PERMISSION_MATRIX` 目前是纯声明:`adapters/astrbot_adapter.py:171-187` 的分发器解析出 `match.permission` 后直接丢弃,而 `main.py:2337` 把四项权限一次性发给所有登录用户(该处注释写明这是当年因 `PluginRequest` 只暴露 username 而做的**已知妥协**,不是疏忽),叠加 workflow/node/image/job/history 五条链路的 service 方法根本不收 `ctx`,结果是任意登录用户可读写他人资源。**第三,补正确性与可观测性**——队列消费用了展示接口的 `ORDER BY created_at DESC`(实际是 LIFO,积压 >25 条即老任务饿死)、worker 完成写入走无 CAS 的 `update_task`(可覆盖并发取消)、轮次候选两条重试通道同时被关死、178 个 Python 源文件里只有 1 个配了 logger,线上出内部错误时没有任何定位手段。**第四,才是拆分与精简**——`App.vue` 22,563 行、`advanced_style_set_service.py` 4,491 行、仓储层 131 处连接样板,这些是"改起来慢"的成本,不是"现在就出事"的风险,排在最后。 一句话:**前三个阶段(约 4 周)解决"会出事",第四、第五阶段(1-2 月起,持续)解决"改得慢"。不要倒过来做。** --- ## 2. 风险矩阵 > **口径声明(终审补充)**:本表"综合"列是**风险优先级**(可能性 × 影响 × 修复成本),**不等于** 02 报告里逐条发现的**复核后严重度**。两者刻意不同:例如"普通登录用户越权"在本表是 P0(因为它是两条攻击链的共同第一环、且修复成本极低),而对应的两条发现(`main.py:2337` 桥接赋权、五链路 IDOR)经复核均定为 **P1**;"存储根可配为任意绝对路径"本表 P0,对应发现复核定为 **P2**。逐条发现的权威严重度**一律以 [02-BUG清单.md](02-BUG清单.md) 为准**。 | 风险 | 可能性 | 影响 | 综合(风险优先级,非发现severity) | 应对 | |---|---|---|---|---| | 部署包内凭据被第三方取得(NAS 其他用户、备份、误传) | 高(包已上传) | 极高(盗刷额度 + 业务库读写 + 接管 AstrBot 实例) | **P0** | 阶段 0:全量轮换 + 删包 + 打包改 `git archive` | | 普通登录用户越权改配置 / 读写他人资源 | 高(单账号即可,无门槛) | 高(配置篡改、他人提示词与参考图外泄、代花额度) | **P0** | 阶段 1:分发器强制权限 + 五链路归属校验 | | 存储根被改为任意绝对路径 → 经未认证 `media/fetch` 任意文件读取 | 中(需一次 `settings/save`,但人人可发) | 极高(宿主机任意文件外带,签名 URL 可转发给未认证第三方) | **P0** | 阶段 1:`settings_service.validate()` 补 storage 段 + 令牌绑定签发者 | | 队列 LIFO 饿死 / 取消被覆盖 / 候选无重试 | 高(队列稳定 >25 条即必现) | 中高(用户任务永久卡住、已取消仍扣费、一次抖动即终态失败) | **P1** | 阶段 2:FIFO 认领查询 + worker 全面 CAS + 打通重试链路 | | 线上故障无法定位(1/178 文件有日志 + `handle_request` 静默吞异常) | 已发生(结构性) | 中高(任何内部错误只回"服务器内部错误",无栈无上下文) | **P1** | 阶段 2:`core/logging.py` + `handle_request` 强制 `logger.exception` | | 切到 PostgreSQL 后端立刻不可用 | 低(默认 SQLite) | 高(角色列表/详情 100% 500,错误指向驱动层) | **P1** | 阶段 2:`profile_repository.py:46/73/99` 的字面量 `%` 参数化 | | 图库页在批量生图时卡死浏览器 | 中(图多 + 停留图库页即触发) | 中(页面不可用、Blob 内存无界增长) | **P1** | 阶段 2:`displayMediaUrl` 去副作用 + 轮询重入保护 | | 前后端重复实现的状态机/锁规则漂移 | 高(已发生:`sealed_at` 后端零匹配) | 低–中(按钮该禁用却没禁用,点下去得到一次**带恢复指引的**报错;复核已证伪"无法自恢复") | **P3**(写锁)/ **P2**(进度状态机、快速角色编排) | 阶段 3:服务端下发 `writable` / `lock_reason` / `progression`,前端退化为读字段 | | App.vue 巨石阻塞一切改动(含无法写行为测试) | 已发生 | 中(前端 35,638 行实质零行为测试,改动即赌) | **P2** | 阶段 4:按 feature 切分 + 逻辑下沉 composable | | 仓库体积与构建产物噪音 | 已发生 | 低(`.git` 51 MB,review 受干扰) | **P3** | 阶段 4:`release/` 出库;**`web/` 与 `pages/imagestudio/` 必须继续入库**(见 §3.5 注) | --- ## 3. 分阶段路线图 ### 3.0 第 0 阶段 · 止血(24 小时内) **目标**:让已泄漏的凭据全部失效,并堵住继续泄漏的通道。这个阶段**不改任何业务代码**。 **任务清单** | # | 任务 | 位置 / 命令 | |---|---|---| | 0-1 | 作废并重发模型站 API Key(2 个:前缀 `sk-3`、67 位;前缀 `sk-B`、51 位) | 到两家模型站控制台操作,**不要**在任何工单/Issue 里粘贴原值 | | 0-2 | 修改内网 PostgreSQL 实例的业务账号口令(主机/端口/用户名见泄漏文件) | DB 侧改密后同步更新 `config.yaml` 的 `database.postgresql` 或改走环境变量 | | 0-3 | 修改 AstrBot 管理员口令,并轮换 AstrBot 的 JWT 签名 secret(使已泄漏的 136 位 HS256 token 立即失效) | 明文管理员口令永不过期,仅等 JWT 过期**不够** | | 0-4 | 轮换集成令牌(`security.integration_token_*`,泄漏文件同批次暴露过哈希与盐) | `POST integrations/private-companion/token/rotate` | | 0-5 | 删除本地 8 个 staging 目录与 19 个归档 | `.tmp/deploy-1.0.35`、`.tmp/deploy-clean-1.0.3?`、`.tmp/deploy-stage-1.0.4?-*`,以及 `.tmp/` 下全部 `*.tar` / `*.tar.gz` / `*.zip` / `*.b64` | | 0-6 | 到 NAS 上删除已上传的同名包,并检查 NAS 侧访问日志确认下载记录 | 部署脚本:`.tmp/` 下的 `deploy_remote.sh` / `upload_via_ssh.py` | | 0-7 | 打包脚本改用 `git archive`,杜绝未跟踪文件进包 | `git archive --format=tar.gz --prefix=astrbot_plugin_imagestudio/ -o dist/plugin-$(git describe --always).tar.gz HEAD` | | 0-8 | 打包脚本末尾加泄漏断言 | `tar -tf "$OUT" \| grep -qE '(^\|/)\.env' && { echo "SECRET LEAK"; exit 1; }` | | 0-9 | 凭据改为环境变量注入(`_conf_schema.json` 已有 `*_api_key_env_var` 字段,设计上本就支持),本地文件只留 env var 名 | `.env.imagestudio_codex_handoff.yaml` 清空明文段 | | 0-10 | 复核 git 历史确实干净(已核实:`git ls-files \| grep -i env` 为空,`git log --all --diff-filter=A` 无该文件) | 无需改写历史,**不要**因为这条去跑 `filter-repo` | **验收标准** - 用泄漏包里的两个 API Key 调用对应模型站 → 401。 - 用泄漏的 JWT 访问 AstrBot 管理接口 → 401。 - 用泄漏的 PG 账号口令连库 → 认证失败。 - `find .tmp -name '*.tar*' -o -name '*.zip'` 为空;NAS 对应目录已清理。 - 新执行一次打包,`tar -tf` 输出中不含任何 `.env*` 条目,且脚本对人为注入的 `.env` 测试文件会以非零码退出。 **工作量**:0.5–1 人日(大部分是等控制台操作与 NAS 清理)。 **依赖**:无。**这是唯一一个不能被任何其他工作插队的阶段。** **这个阶段不要做什么** - 不要顺手重构打包脚本的其他部分——只换成 `git archive` 加断言,其余保持原样。 - 不要为了"彻底"去改写 git 历史。该文件从未入库,`filter-repo` 只会让所有 clone 失效却不解决任何问题。 - 不要把轮换后的新凭据写进仓库任何文件(包括 `docs/`、`CHANGELOG.md`)。 --- ### 3.1 第 1 阶段 · 安全边界(1 周) **目标**:让 `PERMISSION_MATRIX` 成为运行时强制点而不是注释;让"拿到一个登录态"不再等于"拿到全部权限和全部数据"。 **任务清单** | # | 任务 | 位置 | 说明 | |---|---|---|---| | 1-1 | 分发器集中强制权限 | `adapters/astrbot_adapter.py:171-187` | 解析 `match.permission` 后查 `route_registry.permission_requirement()`:`auth_required` 不满足返 `UNAUTHORIZED`,`required_permissions` 缺项返 `FORBIDDEN`。handler 内既有 `require_*` 保留为纵深防御 | | 1-2 | 桥接权限降级为最小集 + 显式管理员白名单 | `main.py:104`、`main.py:2337` | 优先从 AstrBot 请求上下文探测角色;探测不到时降级为 `frozenset()` 而非 `BRIDGE_PERMISSIONS`。新增 `security.admin_usernames` / `security.material_managers` 配置项来授予 `can_manage_config` / `can_manage_materials` / `can_manage_all_profiles` | | 1-3 | IDOR:workflow / node 链路 | `backend/services/workflow_service.py:146-150`、`:650-654`;`backend/routes/workflow_routes.py:21-32,50-61`;`backend/routes/node_routes.py:81-92` | `list_workflows` / `get_workflow` / `get_node` / `list_nodes` 增加 `ctx` 参数,走已存在的 `ResourceAccessService.require_workflow/require_node`(`workflow_round_service.py:1108-1114` 是现成的正确范例,**复用它,不要重造**) | | 1-4 | IDOR:job / image 链路 | `backend/routes/job_routes.py:19-41`、`backend/routes/image_routes.py:22-52` | `QueueService.list_jobs` / `ImageService.list_images` 增加 `owner_user_id` 过滤;路由层传 `ctx.actor_id`,持 `can_manage_all_profiles` 时传 `None`。注意 `GenerationTask.to_dict()` 含完整 `request`(他人的提示词、参考图 URI、模型路由,见 `backend/dto/job_dto.py:38`) | | 1-5 | IDOR:history 链路 | `backend/routes/history_routes.py:36-50` | `list_workflow_history` / `save_workflow_snapshot` 前置 `require_workflow(workflow_id, ctx)` | | 1-5b | **统一归属校验语义**(终审补录,**必须先于 1-3~1-5 完成**) | `backend/services/profile_service.py:160`(`_require_owner`) | 仓库里存在**两套语义相反**的归属校验:`ResourceAccessService._can_access` 认 `can_manage_all_profiles`,而 `ProfileService._require_owner` 不认。若先推广 `ResourceAccessService` 再回头改这里,矛盾会被扩散到五条链路上。做法:`_require_owner` 直接复用 `ResourceAccessService._can_access`,删除本地实现 | | 1-6 | storage 段校验 | `backend/services/settings_service.py:240`(`validate()`) | 当前 `validate()` 只校验 generation/vision/prompt_governance/advanced_materials,对 `storage` 段**完全不校验**。拒绝绝对路径,或强制 `resolve_data_path(p).resolve()` 必须落在 `get_runtime_data_root().resolve()` 之内 | | 1-7 | 存储根二次防线 | `core/runtime_paths.py:43`、`core/storage.py:100` | `resolve_data_path` 不再无条件放行绝对路径;`VfsStorage._root_paths()` 对越出运行时数据根的 root 直接抛 `FORBIDDEN` | | 1-8 | `media/fetch` 令牌绑定签发者 | `backend/route_registry.py:173`、`core/media_proxy.py` | `media/fetch` 是全仓**唯一** `auth_required: False` 的路由。把 `ctx.actor_id` 放进令牌 payload,fetch 时校验签发者仍有效,避免签名 URL 变成可转发的无主凭据。同时把令牌从查询串移到 header 或短时一次性票据 | | 1-9 | `storage/migrate` 加护栏 | `core/storage.py:45,182`、`backend/routes/storage_routes.py:28` | `will_overwrite` 目前只被算出来放进返回值、无人使用。改为 `will_overwrite and not payload["confirm_overwrite"]` 时抛 `ApiError`;非 dry-run 迁移提升为独立权限;写 `audit_service.record` | | 1-10 | 配置快照写入前脱敏 | `backend/services/settings_service.py:614`(调用点 `:444`、`:556`) | 读取侧(`list_snapshots`/`get_snapshot`)已调 `_mask_sensitive`,唯独写入侧未脱敏。敏感字段替换为哨兵值,`rollback()` 遇哨兵时从当前配置取回原值(`_merge_masked` 已有同类逻辑可复用);给 `config_snapshots` 加保留期清理 | | 1-11 | 服务端重建成人内容闸门参数 | `backend/routes/node_routes.py:132-146`、`backend/services/generation_service.py:2352-2353,2366-2375` | 路由层剥离客户端提交的 `content_permissions` / `adult_user_allowed` / `quota_allowed` / `entrypoint` / `platform` / `source`,由服务端按 `ctx.actor_id` 查白名单重建。聊天侧已经做对了(`chat_workflow_service.py:70/686/761`),复用其 `_content_permissions` | | 1-12 | 聊天媒体导入删掉本地路径兜底 | `backend/services/chat_media_import_service.py:33-36` | 输入来自聊天消息组件的 `url`/`file`/`path`/`image_url`,不可信。删除 `Path(text).read_bytes()` 分支或约束到显式缓存根(`web_hosting_service.py:58-67` 的 `_resolve` 是正确写法)。落盘前统一走 `core.image_formats.detect_image_format` | | 1-13 | 资产包导入不再信任清单 | `backend/services/asset_import_service.py:141,340,361` | `material_id` 一律服务端生成;`recognition_status` 从清单移除、强制落 `pending_recognition`;覆盖已有素材需显式 `allow_overwrite` 且限同一 `package_uri` 来源;`_asset_uri` 校验 root 与包所在 root 一致 | | 1-14 | 素材绑定 schema 快路径 | `backend/services/material_binding_schema_service.py:47,326`、`backend/services/workflow_service.py:729` | 删掉 `schema_version` 命中即 `deepcopy` 返回的快路径;`_index_by_node_key` 改 `.get(...) or []`;归一化提到 `update_node` **写库之前**,避免脏数据落库后节点永久 500 | | 1-15 | 修正"不写入配置"的承诺 | `frontend/standalone-web/src/features/settings/SettingsPage.vue:98,133` | 探测用 API Key 目前被写进 `settings/save` 并落盘到 `config.yaml`。二选一:改用不落盘的探测端点(`api_discovery_service.py:229` 已支持读 `api_key_plaintext`),或改掉 UI 文案并加二次确认。无论哪种,`duplicateAdapter`(`:89`)都不应复制会话密钥 | | 1-16 | 补齐 `_conf_schema.json` 安全开关 | `_conf_schema.json`(64 键)、`main.py:110-175` 的 `_CONFIG_KEY_MAP` | `prompt_governance.*` 整段、`chat_access.adult_group_allowlist` / `adult_user_allowlist`、`security.integration_token_set` / `allowed_integration_plugins` 全部缺失,管理员在 AstrBot 面板里无法配置内容安全开关,且升级覆盖 `config.yaml` 后配置静默回退到默认值 | **验收标准** - 新增一条"越权矩阵"测试:用户 A 建资源,用户 B 对 `ROUTES` 全部 166 条逐条请求,断言全部 403/404,无一 200。 - 新增一条元测试:遍历 `ROUTES`,用 AST 断言每个 handler 体内存在与 `RouteSpec.permission` 声明等价的 guard;同时断言 `auth_required: False` 的路由**有且仅有** `media/fetch` 一条。 - 手工复现审计里的读取链路(把 `storage.temp_path` 设为 `C:/` → `media/index` → `media/sign` → `media/fetch`)在每一步都被拒。 - `POST nodes/{id}/generate` 带 `{"content_permissions":{"adult_user_allowed":true}}` 时,`prompt_governance` 的裁决结果与不带该字段时**完全一致**。 - 263 个既有 pytest 仍全绿。 **工作量**:8–12 人日(1-1/1-2/1-3~1-5 是主体,约占 6 人日)。 **依赖**:阶段 0 完成。1-2 依赖对 AstrBot `PluginRequest` 实际可取字段的一次探测——如果确认取不到角色,就走白名单方案,**不要卡在这里**。1-6/1-7 是 1-8 的前置。 **这个阶段不要做什么** - 不要顺手把 `handle_request` 的错误信封改成真实 HTTP 状态码。那是一个前后端同步改动(前端 `client.ts` 依赖 200 + 信封),放到阶段 3 的契约工作里做。 - 不要在这个阶段重构 22 个 `_create_*_service()` 工厂。装配问题真实存在,但它属于阶段 3,混进来会让安全改动的 diff 无法审查。 - 不要为 IDOR 发明新的权限服务。`ResourceAccessService` 已经存在且在 profile/round 两条链路上被正确使用,把它推广开即可。 - 不要因为"`require_*` 在 service 构造之后"就重排路由代码——复核已证明生产环境不存在"有权限差但能打到 handler"的调用者,这条被推翻了(残留的真问题是"只读 GET 也跑 provider bootstrap 并 upsert",属性能问题,见阶段 2)。 --- ### 3.2 第 2 阶段 · 正确性(2–3 周) **目标**:让队列语义、轮次状态机、重试链路正确;让线上故障可定位。 **任务清单** | # | 任务 | 位置 | 说明 | |---|---|---|---| | 2-1 | worker 三处写入全面 CAS | `backend/services/worker_service.py:116`、`backend/services/queue_service.py:406`、`database/repositories/job_repository.py:206,215` | `update_task` 的 UPDATE 只有 `WHERE task_id = ?`,而 worker 的成功路径与 `_handle_failure` 都走它 → 用户点取消、worker 恰好完成时 `cancelled` 被改写成 `succeeded`(仍扣费)。仓库已有 `update_task_if_status` / `update_if_status_unless_workflow_cancelled` 这套 CAS 原语,**改成调用它们即可**;返回 `None` 时按"任务已被他人接管"处理并清理已生成产物 | | 2-2 | 队列改 FIFO | `database/repositories/job_repository.py:150`、`backend/services/worker_service.py:208` | `_claim_next` 复用了展示用的 `list_jobs`(`ORDER BY created_at DESC`),队列实际是 LIFO,积压 >`claim_batch_size`(round pool 为 25)后最早的任务永远排不到。新增专用认领查询 `ORDER BY created_at ASC, task_id ASC`;`created_at` 提到毫秒精度或加自增 `seq` 列消除同秒歧义 | | 2-3 | 打通轮次候选重试链路 | `backend/services/workflow_round_worker_runtime.py:45`、`backend/services/generation_job_retry_service.py:180`、`backend/services/generation_service.py:361` | 两条通道同时被关死:worker 侧 `RetryPolicy(max_attempts=1)` + `should_retry` 的 `attempt >= max_attempts` 判据使其**永远返回 False**;Web 侧 `_validate_executable` 只接受 `task_type == "generation"`,而候选是 `"workflow_round_candidate"`。改 `max_attempts=3` 并统一 `attempt` 语义;`_validate_executable` 放开候选类型并走 `enqueue_prepared_generation` 重新入队。顺带唤醒当前的死代码:`_retry_deferred` / `next_retry_at` 退避与 `workflow_round_service.py:750` 的 `retry_scheduled` 分支 | | 2-4 | `reconcile_round` 终态守卫 | `backend/services/workflow_round_service.py:806,621`、`database/repositories/workflow_round_repository.py:1355-1375` | 迟到的候选回调会把 `superseded` 父轮次复活成 `completed`,并把节点 `metadata.active_round_id` 指回旧轮次 → UI 上同一节点出现两个"可确认"轮次。改法:`_reconcile_round_locked` 读到 `confirmed`/`superseded`/`cancelled` 时只更新 `metadata.execution_summary`,不写 `status`、不改 `active_round_id`;把 `superseded` 加入 `_ensure_writable_round_row` 的不可写集合 | | 2-5 | `_ensure_round_enqueued` 补终态白名单(**经复核降级 P3**) | `backend/services/workflow_round_service.py:928-940` | 复核证明 `create_round:81` 的 `_ensure_round_creation_allowed` 已经拦住了 confirmed 节点,所谓"幂等重放击穿只读锁"的攻击链**不可达**。残留的是"守卫与写入分离、易被后续重构打破"的健壮性瑕疵:在写 `status="queued"` 处补一个终态白名单即可。**做,但不要按 P0 的规格投入。** | | 2-6 | `update_node` 失败回写改 CAS(**经复核降级 P3**) | `backend/services/generation_service.py:1869-1886` | 复核推翻了"丢更新导致确认后拿不到上游图"这条影响链(`workflow_service.py:1027-1031/1058-1068` 的 `_normalize_workflow_metadata` 已从新鲜快照强制回填 `branch_state`/`character_execution`)。残留的是一处 check-then-act 用了普通 `update_node`,最坏后果是诊断字段被覆盖。换成同仓储已有的 `update_node_if_status` 收尾 | | 2-7 | 陈旧任务恢复覆盖同步生成 + 加重试上限 | `backend/services/queue_service.py:439,470,481`、`backend/services/generation_service.py:574` | `recover_stale_tasks` 唯一调用点是 worker `start()` 且固定 `source="workflow_round"`,而 `nodes.generate` 的任务 `source="nodes.generate"` 被跳过 → 进程被杀后节点永久停在 running,用户再点生成得到"generation is already in progress"且无法自恢复。改为可选白名单 + 周期性巡检;恢复时同步修复 `workflow_nodes.status`;metadata 里累加 `recovery.attempts`,超阈值进 `dead_letter`(该状态目前从未被使用) | | 2-8 | 生成并发隔离与背压 | `backend/services/generation_service.py:119`、`main.py:333`、`backend/services/chat_workflow_service.py:216` | 同步生成在 asyncio 默认线程池(`min(32, cpu+4)`)里阻塞,单次 provider 调用默认 180 秒、上限 3600 秒,十几个并发即可让**所有** ImageStudio API 一起挂起(包括用来取消它们的接口)。建独立的、容量可配的生成 executor(4–8);入口加 `BoundedSemaphore`,取不到时快速返回 `QUEUE_BUSY` 而非排队阻塞;聊天 4 图并发复用同一全局池。
**终审补录(同一个 PR 一起改)**:`worker_service.py:400` 的 `_BoundedWorkerHandler` 并发限流在生产配置下**完全是空操作**,且限流点位于**认领之后** —— 任务已被 CAS 认领才去抢信号量,抢不到只能持锁阻塞等待。限流点必须前移到 `_claim_next` **之前**,上限从生产配置真实读取 | | 2-9 | PostgreSQL 后端修复 | `database/repositories/profile_repository.py:46,73,99` | 三个 CASE 列写死了 `LIKE '%"final_archive_history_id"%'`,PG 的 `%s` paramstyle 下驱动会把它当格式模板 → 角色列表/详情 100% 抛 `ValueError`。改参数绑定;加静态扫描测试断言仓储 SQL 常量中不含未转义的裸 `%`(正则 `%(?!s)`) | | 2-10 | 建立日志基座 | 新建 `core/logging.py`;`backend/services/worker_service.py:5,17` 是全仓唯一现存 logger | 178 个 Python 源文件仅 1 个配 logger,全仓 `logger.` 调用 6 次;对照 180 处 `except Exception`、其中 33 处直接 `pass`/`return None`。导出 `get_logger(name)`,优先桥接 AstrBot 的 `astrbot.api.logger`,回退 `logging.getLogger(f"imagestudio.{name}")` | | 2-11 | `handle_request` 强制记日志 | `backend/routes/common.py:12-16`、`backend/dto/common.py:75-83` | 166 条路由全部经此包装,非 `ApiError` 异常一律返回固定文案 + 仅异常类名,无日志无栈。改成 `except ApiError` 记 info、`except Exception` 记 `logger.exception(request_id, actor)`;`response_from_exception` 的 `details` 补 `request_id` 让前端展示的 ID 可反查 | | 2-12 | 给 5 个外部 IO 模块补日志 | `generation_service` / `advanced_material_service` / `advanced_style_set_service` / `model_provider_runtime` / `astrbot_provider_bridge` | 把 33 处静默 `pass` 改成 `logger.debug/warning` + 保留原兜底逻辑。同时处理 `A1` 的两处裸 `except Exception: pass`(`_record_generation_failure` / `_clear_retry_preparation`) | | 2-12b | **主动通知全链路静默失败**(终审补录) | `backend/services/workflow_round_worker_runtime.py:262` | 签名失败返回 `None`、发送失败返回 `False`、terminal 回调静默 `return` —— **三个失败出口一行日志都没有**。用户收不到轮次完成通知,运维也无从得知。三处各补 `logger.warning`(含 round_id / task_id / 失败阶段)。与 2-10 同一个 PR | | 2-13 | 打通 `request_id` 关联链 | `frontend/shared/api/client.ts`(`unwrapApiResponse` 剥掉 ID)、聊天侧的 `chatreq_*` 从未落库 | 三条链路都断了。前端保留 `request_id` 并在错误提示里展示;聊天侧 ID 写入审计 | | 2-14 | `displayMediaUrl` 去副作用(前端最重的一条,原判 P0 → **复核降为 P1**:缺陷成立、行号无误,降级仅因它是性能/内存问题而非数据正确性或安全问题) | `frontend/standalone-web/src/App.vue:11146`(定义)、`:997-1011`、`:2341-2362`、`:11668/11693/12826/12865/13961` | 它在 computed 与模板 render 中发 HTTP 请求并整体替换 `resolvedMediaUrls` ref → 1000 张图 ≈ 100 万次 `displayMediaUrl` 调用,且 `ownedMediaObjectUrls` 只在 `onBeforeUnmount` 统一 revoke(SPA 中永不卸载)。新建 `composables/useMediaUrls.ts`:纯查表的 `mediaUrl(raw)` + 显式的 `prefetchMediaUrls(urls[])`(一次性写入,N 次 ref 替换压成 1 次);给缓存加 LRU 上限(如 300)并在淘汰时 `revokeObjectURL` | | 2-15 | 事件轮询重入保护 + 图库增量刷新 | `frontend/standalone-web/src/App.vue:4561-4609`、`:4511-4542` | `setInterval(poll, 5000)` 的 `poll` 内 `await` 整库分页拉取,无 in-flight 守卫;`loadGalleryImages` 置了 `loadingGalleryImages` 但从不检查。加 `eventPollInFlight` 标志与 `loadGalleryImages` 自守卫;轮询触发改为只拉第 1 页 merge,全量扫描保留给显式"刷新";循环条件改为按页数而非 `loaded.length`(后者被 `isAuthenticGenerationImage` 过滤后必然多翻一轮) | | 2-16 | `size` → `aspect_ratio` 断链 | `engines/single_flow.py:61`、`backend/services/chat_workflow_service.py:63,929` | 聊天单图与高清修复写入的是 `size`(`"3840x2160"` 等),而引擎只读 `aspect_ratio`,全链路无人做映射 → 尺寸参数与高清修复静默失效 | | 2-17 | 修复已渲染到界面的编码事故 | `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1304-1317`(渲染点 `:1656`) | `styleValidationReviewTrust` 三个分支全部返回 `"????????"`,审核人员看不到评分可信度就在做封存决策。恢复中文文案,并加一条前端断言:`features/` 下 `.vue` 不得出现连续 3 个以上 `?` 的字符串字面量 | | 2-18 | 导入占位提示不再写进档案 | `frontend/standalone-web/src/features/quick-profile/profile-import.ts:149-178,327-337`;消费点 `App.vue:9721-9726,9568-9581` | `resolveImportedProfileField` 的 fallback 是给人看的提示语("性格关键词待从原文继续整理"),未识别时被写进 `.value` → 最终拼进 `base_prompt` 送给模型。fallback 改空串,提示语移到 `placeholder` | | 2-19 | 问卷默认值清空 | `frontend/standalone-web/src/features/quick-profile/profile-import.ts:32-59`;使用点 `App.vue:759` | 快速角色问卷初始值是一个填满的虚构示例角色,用户首次打开直接点生成就会消耗真实额度出四张别人的角色图。改用同文件已存在的 `createEmptyQuickProfileQuestionnaire()`(`:61`);同时把 `frontend/tests/production-data-boundary.test.mjs` 的扫描范围从 2 个文件扩到 `standalone-web/src` 下全部 `.vue`/`.ts` | **验收标准** - 并发取消测试:worker 完成写入与 `cancel_job` 并发 1000 轮,`cancelled` 永不被改写成 `succeeded`。 - FIFO 测试:入队 60 条(>25 的 batch),断言消费顺序严格按 `created_at ASC`,最早一条在前 25 次消费内被认领。 - 重试测试:候选任务首次执行抛 `ImageProviderError`,断言被重排队且 `worker_attempt` 递增,第 4 次才终态 failed;`POST jobs/{候选id}/retry` 返回 200 而非 `TASK_NOT_RETRYABLE`。 - 轮次守卫测试:父轮次标 `superseded` 后,模拟迟到候选回调,断言父轮次 status 与节点 `active_round_id` 均不变。 - PG 冒烟:以 `DatabaseSettings(backend="postgresql")` 跑通角色列表 + 详情两个接口。 - 可观测性:制造一个 `KeyError`,断言 AstrBot 日志里出现带 `request_id` 与 `actor` 的完整栈,且前端返回体的 `details` 含同一个 `request_id`。 - 前端:图库 500 张图场景下,切页/切主题不再触发媒体请求;连续停留 5 分钟后 Blob 数量不超过 LRU 上限。 - 263 + 26 个既有测试全绿,新增测试不少于 20 个。 **工作量**:15–22 人日。后端约 12–16(2-1~2-12 为主),前端约 4–6(2-14/2-15 是主体)。 **依赖**:2-10 是 2-11/2-12/2-13 的前置。2-1 与 2-2 建议同一个 PR(都动 `job_repository` 与 `worker_service`)。2-14 与 2-15 建议同一个 PR(都在 App.vue 的媒体/轮询区)。其余任务相互独立,可并行。 **这个阶段不要做什么** - 不要在这个阶段拆 App.vue。2-14/2-15 是**局部手术**,只碰媒体解析与轮询两块,拆分放阶段 4。 - 不要为了"顺便"给 SQLite 开 WAL 而把它当成 P1 事项。复核已证明"rollback journal 下写事务阻塞全库读"的机理描述错误、事务寿命是毫秒级、声称的并发场景不存在(`confirm_candidate_atomic` 唯一调用方是交互式单用户动作)。**开 WAL 仍是合理的低成本调优,作为 P3 顺手做,但不要为它写压测报告或安排专项。** - 不要引入分布式追踪 / Prometheus / OpenTelemetry。当前的问题是"一行日志都没有",`get_logger` + `logger.exception` 就把 90% 的定位需求解决了。等日志跑满一个月再谈指标。 - 不要动 `handle_request` 的返回信封结构(HTTP 状态码问题)。见阶段 3。 --- ### 3.3 第 3 阶段 · 解耦(1–2 月) **目标**:消除"同一个 service 在不同入口被装配成行为不同的实例"这类问题,并让前后端契约由测试而非人工同步来保证。 **任务清单** | # | 任务 | 位置 | 说明 | |---|---|---|---| | 3-1 | 建统一装配容器(组合根) | 35 个 route 模块里的 `_create_*_service()`;34 处 `Database(load_database_settings())` | 每次路由调用都重读一次 `config.yaml` 并重建整棵对象树,没有任何缓存。建一个 `backend/container.py`(或 `composition_root.py`),提供带生命周期的单例装配 + 显式覆盖入口供测试注入 | | 3-2 | 修掉装配复制造成的真实行为差异 | `backend/routes/branch_routes.py` 的 `_create_workflow_service()` 漏 `event_bus=`;`backend/routes/node_material_routes.py` 构造的 `WorkflowService` 无 `event_bus` | 分支创建/切换事件、素材绑定事件永远不进 SSE。这是复制粘贴的直接后果,容器化后自然消失,但**在容器落地前先单独修掉这两处**(各 1 行) | | 3-3 | 修 `engines/vision_provider.py` 的 `endpoint_url()` | 缺 image 版本里的 `/v1` 去重逻辑 | 会拼出 `/v1/v1/chat/completions`。同样是复制粘贴差异,1 行 | | 3-4 | 消除 `service → route` 反向依赖 | 后台 worker 必须 import route 模块才能拿到装配好的 `GenerationService`;`backend/routes/job_routes.py:311` 用函数内 import 跨 route 取私有 `_create_generation_service` | 容器落地后,worker 直接从容器取 | | 3-5 | 消除 `database → backend.services` / `engines` 反向依赖 | `database/repositories/*` 反向 import `backend.services.branch_lineage_service` 与 `engines` | 把被依赖的纯函数下沉到 `core/` 或仓储自己的 helper | | 3-6 | 消除 `core → backend.dto` 反向依赖 | `core/*` import `backend.dto.common` | `ApiError` / `ErrorCode` 应该住在 `core/`,由 `backend.dto` re-export 以保持兼容 | | 3-7 | 收敛 `ChatWorkflowService` 的进程内自我 HTTP | `backend/services/chat_workflow_service.py`(69 次通过字符串路径调 `dispatch_web_request`) | 把 route 层从 service 层的下游拽回上游:聊天侧改为直接调用容器里的 service。注意 `:903` 是全仓唯一绕过 dispatcher 的直调,收敛时一并处理 | | 3-8 | 服务端下发节点可写状态(**经复核降级 P3**) | `backend/services/workflow_round_service.py:1145-1155` ↔ `frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27` | 前端锁规则多判了一个后端**零匹配**的 `sealed_at`(恒 undefined,只会多加锁不会漏加锁),少判了 `selected_image_id`(可达路径:`GalleryPage.vue:121` 批量"标记选中" → `image_service.select_image` 只写 `selected_image_id` 不改 status)。
**复核推翻了两点**:(a) 初审引用的 `adopt-image` 触发路径**是错的** —— `history_service.py:55` 一次性写 `{"status":"selected","selected_image_id":...}`,两边一致;(b) "无法自恢复的报错"**不成立** —— `App.vue:7788-7795` 的 `actionableWorkflowApiError` 会把 `details.required_action = create_branch` 映射成中文指引"请先创建可编辑分支",`WorkflowBranchPanel` 提供入口。
动作不变:在 `WorkflowNode.to_dict()` 增加 `writable: bool` + `lock_reason`(复用 `WorkflowNodeMaterialBindingDetail` 已有的 `writable`+`lock` 形状),前端退化为读字段 | | 3-9 | 服务端下发顺序进度判定(**经复核降级 P2**) | `backend/services/workflow_progression_service.py:175-199` ↔ `App.vue:10837-10859` | 前端逐条复刻了后端四层规则(含"legacy 兼容只对无 sequential-v1 标记的工作流生效"这种细分支),版本号字面量抄在 `App.vue:927`。根因(后端从不下发进度、`progression.to_dict()` 唯一调用点在 `character_workflow_service.py:339`)经复核核实成立;降级理由是 `ensure_character_gradual_node_access` 在服务端硬兜底,前端偏差**无法被用来绕过规则**,且两份实现当前语义完全等价。改为后端下发权威结果 | | 3-10 | 服务端下发生效模型路由 | `frontend/.../workflow-model-route.ts:36-88` ↔ 后端 `generation_service.py:169-176,617-624,2022-2045` + `workflow_round_service.py:596-597`(**经复核降级 P3**) | 复核证明"优先级相反导致标签说谎"不可达、缺 `image_low` 兜底是刻意 fail-safe、round 层是对后端的正确镜像。残留的是"前端复刻了一份映射表、改键名要两边同改"的耦合。**理想做法**:后端在节点/轮次响应里下发 `effective_model_route` + `source`,前端只显示。低优先级,随 3-8/3-9 顺手做 | | 3-11 | 契约自动化测试 | `contract` 端点目前只被当诊断 JSON dump,无任何自动化消费 | 三条:① `ROUTES` × handler guard 的 AST 元测试(阶段 1 已建,此处扩展到覆盖 `required_permissions` 全集);② 后端 DTO ↔ `frontend/shared/types/` 的字段级比对(当前全靠人工同步,已发现 `CharacterProfile` 缺 owner 四字段、`generation_kind` 含后端不产出的值、`AdvancedMaterialImportStatus` 双向漂移且 `Union \| string` 让联合类型在编译期失效);③ `route-chain:` 线格式编解码器的跨语言一致性测试(被逐字移植到 TS,零测试) | | 3-12 | 统一错误信封与 HTTP 语义 | `backend/routes/common.py`、`backend/dto/common.py`、`frontend/shared/api/client.ts` | 所有错误一律 HTTP 200,`UNAUTHORIZED`/`FORBIDDEN`/`NOT_FOUND` 无法被 HTTP 层识别(反代、监控、浏览器缓存全部失效)。这是前后端同步改动,必须一次性完成并配契约测试 | | 3-13 | 收敛前端错误处理 | `frontend/shared/api/client.ts` 的结构化错误在功能层失效(18+ 处各写各的 catch,英文超时文案直抛给中文用户);`errorMessage` 两处独立实现且行为不一致 | 统一到一个 `useApiError()` | | 3-14 | 统一枚举与常量的单一真相源 | 队列状态枚举前后端共 4 处硬编码;生成状态中文标签 3 处重复且译法冲突;`character_flow` 节点目录与 legacy 别名表在前端重复且两份前端拷贝互不一致;`LONG_TASK_ENDPOINT` 正则前端两份;`API_BASE` 硬编码三份而 `bootstrap.api_base` 下发了没人用 | 由后端下发或由 `frontend/shared/` 单点导出 | | 3-15 | 让 `EventBus` 承担职责或删掉它 | `core/event_bus.py`:全仓 `subscribe()`/`unsubscribe()` 调用方为 0,只有 6 处 `publish()` | 它当前只是 `GET events/stream` 的进程内环形缓冲区。要么真正用它解耦跨服务通信,要么把它降级为一个明确命名的 `EventRingBuffer` 并删掉空转的分发链路 | **验收标准** - 一条测试:对全部 179 个 Python 模块做 AST 导入抽取,断言不存在 `database → backend.services`、`database → engines`、`core → backend.dto`、`backend.services → backend.routes` 四类反向边。 - 一条测试:从容器取两次同名 service,断言依赖注入项(尤其 `event_bus`)完全一致。 - 手工验证:在分支面板创建分支,SSE 事件流中出现 `workflow.branch_created`。 - 契约测试能捕获人为制造的漂移(在 DTO 里加一个字段而不改 TS 类型 → 测试红)。 - 前端不再存在 `sealed_at` 字面量;`grep -rn "sealed_at" frontend/` 为空。 **工作量**:25–40 人日。3-1 是所有后端项的前置,本身约 8–10 人日。 **依赖**:阶段 2 完成(尤其日志基座——容器化过程中一定会暴露装配错误,没有日志会很痛苦)。3-1 → 3-2/3-4/3-7。3-8/3-9/3-10 建议合成一个"节点响应扩展"PR。3-12 必须与前端同步发布。 **这个阶段不要做什么** - 不要引入 DI 框架(`dependency-injector`、`punq` 等)。一个显式的 `container.py` 加几个 `@lru_cache` 就够了,引框架会让 AstrBot 插件的加载路径变复杂。 - 不要一次性把 35 个工厂全迁到容器。按 route 模块分批,每批一个 PR,每批跑全量测试。 - 不要为了"分层纯洁"去拆 `core/`。只修那 9 条明确的方向违规,不做更多。 - 不要在这个阶段把 `chat_workflow_service` 的 69 次自我 HTTP 一次性全改。先改掉 `:903` 那处直调 + 高频的 10 条,剩下的随功能迭代逐步迁移。 --- ### 3.4 第 4 阶段 · 精简(持续) **目标**:把"改起来慢"的成本降下来。这个阶段没有截止日期,按"每次动到某个文件就顺手做掉它那一份"的方式推进。 **任务清单** **A. App.vue 拆分(22,563 → 目标 6,000–7,000)** | 类别 | 当前 | 动作 | |---|---|---| | 死 CSS | 413 行永不命中的规则 | 直接删 | | 重复 CSS 声明块 | 上限 2,251 行,保守可回收 800–1,200 行 | 合并 | | 组件样式泄漏在全局 | 5 个已抽离组件的样式仍在 App.vue,其中 691 行属"隐式全局依赖" | 迁回各组件的 `