astrbot_plugin_imagestudio/审计/05-优化路线图.md

382 行
60 KiB
Markdown

# 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 图并发复用同一全局池。<br>**终审补录(同一个 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)。<br>**复核推翻了两点**:(a) 初审引用的 `adopt-image` 触发路径**是错的** —— `history_service.py:55` 一次性写 `{"status":"selected","selected_image_id":...}`,两边一致;(b) "无法自恢复的报错"**不成立** —— `App.vue:7788-7795` 的 `actionableWorkflowApiError` 会把 `details.required_action = create_branch` 映射成中文指引"请先创建可编辑分支",`WorkflowBranchPanel` 提供入口。<br>动作不变:在 `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 行属"隐式全局依赖" | 迁回各组件的 `<style scoped>` |
| feature 前缀样式 | `quick-profile` 1,268 行 / `workflow-*` ≈1,400 行 / `materials-*` ≈600 行 | 切成 feature CSS 文件 |
| 图片查看器 | 缩放/拖拽脚本 60 行 + 样式 104 行与 `ImagePreviewDialog.vue` 完全重复 | 删 App.vue 那份,改用组件 |
| 焦点陷阱 | 4–6 份几乎一字不差的实现(≈130 行),另有 2 个 `aria-modal` 对话框完全没有键盘管理 | 抽 `useFocusTrap()`,补上缺失的两个 |
| 素材选择器弹层 | 模板被逐字复制两份(109 行) | 抽组件 |
| 卡片工厂 | `workflowActionCards`(441) / `generateFeatureCards`(171) / `queueActionCards`(143) / `materialActionCards`(113) / `quickProfileActionCards`(88) + 4 张标签映射表 ≈1,080 行纯数据 | 搬到独立模块 |
| 请求样板 | 25 个 loader 复读同一套 `loading/error/try/catch/finally`;27 处 `backendWriteBlockMessage` 前置校验 | 抽 `useAsyncResource()` |
| 状态树 | 206 个 `ref` + 203 个 `computed` 代替 store(声明式口径,含 `ref<T>(` 泛型写法;字面量口径为 133/135);`pinia` 已声明但零引用 | 按 feature 抽 composable(**不必然要上 pinia**) |
| 语义污染 | `workflowNodeActionError` 一个 ref 承载成功与失败文案(67 处赋值),模板按错误样式渲染 | 拆成 `message` + `error` 两个 ref |
拆分的关键副产品:**只有拆完才能写真正的行为测试**。当前前端 8 个测试里 7 个是对 `.vue` 源文本做正则匹配(`app.indexOf("async function ...")` + `assert.match(/endpoints\.X/)`),既假阴性(改名即红)又假阳性(`if (false)` 包住也绿),35,638 行 Vue 实质零行为测试。这不是测试作者偷懒,是巨石组件无法挂载的直接后果。拆分后按 `App.vue` 的既有 44 个组件/composable(14,295 行)的模式,逐块引入 `vitest` + `@vue/test-utils`(项目已用 Vite 6,接入边际成本极低)。
**B. 后端样板收敛(保守可削减 ≈1,800 行,含路由层改造 ≈2,100 行)**
| 项 | 现状 | 削减 |
|---|---|---|
| 仓储连接样板 | 13 个 repository + `core/audit_service.py` 共 **131 处** `connect()/try/finally close()` | 一个 `contextmanager` → ≈390 行 |
| `_optional_text` | 独立定义 **30 次**,而 `backend/routes/params.py` 已有同名别名却无人使用 | ≈145 行 |
| `_string_list`(**经复核降级 P3**) | 实为 **17 处**(多出的 1 处在 `.tmp/` 构建产物快照里)。复核证明"数据损坏/静默空列表/顺序不可预测"三条影响均无可达路径——17 个实现全是下划线私有、零跨模块导入,各自在本模块信任边界上做一次本地归一化 | 收敛仍值得做(≈90 行),但按整洁度而非安全隐患对待 |
| 死代码 | `core/queue_manager.py` 整文件 112 行零引用;另有 29 个函数/类/方法全仓零引用 | 112 + ≈263 行 |
| JSON 助手 | `_json_or_none` / `_json_loads` / `_json_object` 在仓储层重复 20 次 | ≈75 行 |
| `to_dict()` | 15 个 DTO 是纯字段镜像 | mixin → ≈220 行 |
| `_signed_url` | 复制 7 份,其中 3 份异常捕获范围不一致 | ≈41 行 |
| 分页工具 | `_page` / `_page_size` / `_limit` 重复 10 次且默认值不一致(上限 100 vs 200) | ≈48 行 |
| `main.py` 短命令 | **38 个** `/yp` 短别名装饰器是纯转发壳(`main.py:1300–1462`)。原始材料记 50 个 / 164 行,实测复核为 38 个 —— 以 38 为准 | ≈140 行 |
| 其他 | `_now` ×6、`_mapping` ×4、`_rollback` ×3;`ImageProviderError` 与 `VisionProviderError` 逐字节相同;2 个源文件带 UTF-8 BOM 导致标准 AST 工具解析失败 | — |
**C. God object 拆分**
- `backend/services/advanced_style_set_service.py`(4,491 行 = 2,091 行类体 + 2,092 行模块函数)→ 可无风险拆成 5 个模块。
- `main.py`(2,580 行):真正的插件生命周期只有约 95 行(`354-447`),其余是 849 行聊天命令 + 165 行短命令别名 + 828 行 AstrBot HTTP/配置桥接 → 至少把聊天命令层拆出去。
- `backend/routes/`:157 个 handler 是完全同构的三行样板(`def action(): require_*; return ...` + `handle_request`)。**这一项风险最高,放在最后,且要有阶段 1 的 guard 元测试兜底才能动。**
**D. 仓库瘦身与测试基建**
| 项 | 位置 | 动作 |
|---|---|---|
| `pytest tests/` 直接崩溃 | 全仓无 `conftest.py` / `pytest.ini` / `pyproject.toml` | 加 `[tool.pytest.ini_options] pythonpath = ["."]`;IDE / CI / pre-commit 全部依赖这个 |
| `release/` 20 个 zip(37 MB) | 已入库,早期几个包内含真实 `imagestudio.db` 与 provider probe 响应 | `.gitignore` 加 `release/` + `git rm -r --cached release`;改用 Git Release 附件分发 |
| 未跟踪垃圾 8,228 文件 / 2.57 GB | `.tmp` 2.1 GB + 20 个根级 `.tmp_pytest_*` 507 MB | 清理;测试临时目录统一改用 `tmp_path_factory` |
| 测试夹具重复 | 21 个测试文件各自内联同一套 SQLite Database 夹具 | 抽到 `conftest.py`;夹具改 session 级建库 + 每用例事务回滚(当前 263 用例 188 秒 / 0.72 s 每用例,主因是每用例真实建库落盘) |
| 前端测试入口 | `frontend/package.json:12-13` 无 `test` 脚本,`test:ui` 是 `test:contracts` 的子集 | `"test": "npm run typecheck && npm run test:contracts"`,删冗余 |
| 依赖声明 | `pinia` / `vue-router` 声明但零引用;`typescript`/`vite`/`vue-tsc`/`@vitejs/plugin-vue` 全在 `dependencies`,`devDependencies` 为空 | 清理并归位 |
| 零执行覆盖的 service | 复核实测(coverage 7.15.2 全量跑)确认 **9 个模块 ≈1,966 行零执行**,其中 `integration_token_service`(202 行,外部插件 token 鉴权)与 `deletion_safety_service`(75 行)是安全相关 | 优先给这两个补测试。**注意**:原始发现的"23 个 service / 4,579 行零测试"经复核证伪(`branch_lineage_service` 实测 93%、`workflow_progression_service` 94%,它们是被再导出的 helper,测试通过前门 service 调用),不要按那个数字排工作量 |
| 编码损坏 | `config.yaml` 54 个私有区乱码字符(已入库)、`metadata.yaml` 的 `short_desc`、`CHANGELOG.md` 649 处 | 统一重存为 UTF-8;加 CI 检查 |
| 无 CI | 仓库无 `.github/workflows`;`DEVELOPMENT.md` 的"验证"流程根本不跑测试 | 最小 CI:`pytest` + `npm run typecheck` + `npm run test:contracts` + 构建新鲜度校验 |
**验收标准**(滚动)
- `App.vue` 每季度净减不少于 4,000 行,且每减一块必须补上对应 composable 的行为测试。
- 后端 `grep -c "def _optional_text"` 从 30 降到 1;`connect()/try/finally` 从 131 降到 0(全走 contextmanager)。
- `pytest tests/`(不带 `-m`)能直接跑通。
- 后端测试总时长从 188 秒降到 60 秒以内。
- `.git` 体积下降,`git log -p` 的 diff 中构建产物噪音占比可接受。
**工作量**:持续。建议按"每个功能 PR 附带一块精简"的方式摊销,不安排专项冲刺。
**依赖**:D 部分的 pytest 配置可以随时做(0.5 人日,收益立竿见影)。A 部分依赖阶段 2 的前端修复先落地(避免在同一区域反复冲突)。C 部分的路由样板改造依赖阶段 1 的 guard 元测试。
**这个阶段不要做什么**
- **不要把 `web/` 与 `pages/imagestudio/` 加进 `.gitignore`。** 复核已证明它们不是误提交的产物,而是 `INSTALL.md` 明确定义的发布负载:ImageStudio 是 AstrBot 插件,装机路径是把仓库/ZIP 铺到 `data/plugins/`,**安装期没有任何 npm/vite 步骤**;忽略它们会让 `WebHostingService._resolve` 直接抛 `web asset not built`,插件页面全线不可用。两份构建的 `base` 不同且必须不同(绝对路径 vs 相对路径,服务于两个不同挂载点),不是重复。真正该做的是加一个**构建产物新鲜度校验脚本**(当前 24 次提交只更新 `web/assets`、3 次只更新 `pages/imagestudio/assets`)。仓库体积的主因是 `release/` 的 20 个 zip(37 MB),不是 `web/assets`。
- 不要为了瘦身 `.git` 去跑 `git filter-repo`。除非团队能同步重建全部 clone,否则收益不抵成本;先 `git rm --cached release` + `git gc` 即可。
- 不要一次性大重构 App.vue。它是 22,563 行、零行为测试、且正在被高频修改的文件——按 feature 逐块搬、每块搬完立刻补测试,否则会引入比技术债更贵的回归。
- 不要为了"消灭重复"去统一那 17 个 `_string_list`**的语义**。复核确认它们各自是本模块信任边界上的本地归一化,语义分叉是有意的;收敛时保留各自行为,只做物理去重。
- 不要动 `backend/routes/` 的 148 个 `def action()` 闭包样板,除非阶段 1 的 guard 元测试已经在跑。这是全仓风险收益比最差的一项。
---
## 4. 量化目标
| 指标 | 现状 | 阶段目标 | 最终目标 |
|---|---|---|---|
| 部署包内泄漏凭据数 | 5 类 / 19 个包 | **阶段 0:0** | 0(打包断言常态化) |
| 运行时被真正强制的权限档 | 2(登录/未登录);矩阵声明 6 档 | 阶段 1:6 档全部在分发器强制 | 6 档 + 每档有越权测试 |
| 无鉴权路由数 | 1(`media/fetch`,`auth_required: False`) | 阶段 1:仍为 1,但令牌绑定签发者 | 1(且有元测试锁死"有且仅有这一条") |
| 无归属校验的资源链路 | 5(workflow/node/image/job/history) | 阶段 1:0 | 0 + 166 条路由的越权矩阵测试 |
| 配置校验覆盖的配置段 | 4 段(storage 段完全不校验) | 阶段 1:5 段(含 storage) | 全部段 |
| `_conf_schema.json` 键数 vs 安全开关缺口 | 64 键 / `prompt_governance` 整段 + 成人白名单缺失 | 阶段 1:补齐安全相关键 | schema ↔ `_CONFIG_KEY_MAP` 双向同步测试 |
| 队列消费顺序 | LIFO(`ORDER BY created_at DESC`) | 阶段 2:FIFO | FIFO + 毫秒精度/`seq` 列 |
| worker 写入使用 CAS 的比例 | 0/3(成功、失败、重排队三条路径全走无条件 UPDATE) | 阶段 2:3/3 | 3/3 + 并发取消测试 |
| 轮次候选可重试次数 | 0(两条通道同时关死) | 阶段 2:3 次带退避 | 3 次 + `dead_letter` 出口 |
| 配了 logger 的后端源文件 | 1 / 178 | 阶段 2:≥30 / 178(覆盖全部含外部 IO 与路由层) | 静默 `except: pass` 从 33 处降到 0 |
| `handle_request` 内部错误留痕率 | 0%(200+ 端点全静默) | 阶段 2:100% 带 `request_id` + 栈 | 100% + `request_id` 三链路贯通 |
| PostgreSQL 后端可用性 | 角色列表/详情 100% 报错 | 阶段 2:冒烟通过 | 全量测试可切 PG 跑一遍 |
| 分层方向违规边 | 9 条 | 阶段 3:0 | 0 + AST 元测试守门 |
| 前后端重复实现的规则 | ≥6 处(进度状态机、写锁、模型路由、状态枚举×4、节点目录、长任务正则) | 阶段 3:≤2 | 0(全部由后端下发或 `shared/` 单点导出) |
| 有自动化契约测试的接口面 | 0(`contract` 端点只做诊断 dump) | 阶段 3:DTO↔TS 字段级 + 路由 guard + 线格式编解码 3 类 | 每次 DTO 变更必须同步 TS 否则 CI 红 |
| `App.vue` 行数 | 22,563(script 11,356 / template 2,784 / CSS 8,395) | 阶段 4 首季:≤16,000 | 6,000–7,000 |
| 前端行为测试用例数 | 0(26 个用例中 7/8 文件是源码正则匹配) | 阶段 4 首季:≥30 个真实行为用例 | 关键 composable 100% 覆盖 |
| 后端可确证死代码 | `core/queue_manager.py` 112 行 + 29 个零引用符号 ≈263 行 | 阶段 4:0 | 0 + 死代码扫描进 CI |
| 重复样板(连接/工具函数) | 连接样板 131 处;`_optional_text` 30 份;JSON 助手 20 份;`_signed_url` 7 份;分页工具 10 份 | 阶段 4:连接 0 / `_optional_text` 1 | 全部单点定义 |
| 后端可削减行数 | — | 阶段 4:≥1,000 行 | ≈1,800(不含路由改造)/ ≈2,100(含) |
| 前端可净删除行数 | — | 阶段 4:≥1,000 行 | 1,900–2,000(另有 ≈6,000 行迁移) |
| 零执行覆盖的 service | 9 个 ≈1,966 行(含 2 个安全模块) | 阶段 4:安全模块 0 | ≤3 个(纯诊断类可豁免) |
| 后端测试时长 | 188 秒 / 263 用例(0.72 s 每用例) | 阶段 4:≤90 秒 | ≤60 秒 |
| `pytest tests/` 直接可跑 | 否(`ModuleNotFoundError`) | 阶段 4(可提前):是 | 是 + CI 常绿 |
| 已入库的二进制/构建产物 | `release/` 20 zip 37 MB;`.git` 51 MB;230 次提交中 86 次(37%)触及产物 | 阶段 4:`release/` 出库 | `.git` 稳定不再因 release 增长(`web/`、`pages/` 保持入库) |
| 工作树未跟踪垃圾 | 8,228 文件 / 2.57 GB | 阶段 0 顺手清 `.tmp` 归档 | <100 MB,测试临时目录走 `tmp_path_factory` |
| CI | 无 | 阶段 4(可提前):pytest + typecheck + 前端契约 + 产物新鲜度 | 加越权矩阵 + 契约测试 + 死代码扫描 |
---
## 5. 投入产出建议
### 如果只有 1 个人 1 周(5 人日)
**做这些(按顺序,不要跳):**
1. **阶段 0 全部**(1 人日)。不可协商。
2. **1-1 分发器强制权限**(1 人日)。这是整个报告里投入产出比最高的一项:改 `adapters/astrbot_adapter.py` 一个函数(约 15 行),加一条元测试,就把"新增路由忘写 `require_*` 即静默未授权写接口"这个结构性风险永久关掉。
3. **1-6 + 1-7 storage 段校验**(0.5 人日)。`settings_service.validate()` 加十几行,直接切断"任意文件读取 + 任意文件写入"两条最重的攻击链的前提。
4. **1-3 ~ 1-5 IDOR 五链路**(1.5 人日)。`ResourceAccessService` 已存在,主要是改签名和传 `ctx`,机械但必须做。job/image 的 owner 过滤稍麻烦。
5. **2-10 + 2-11 日志基座**(1 人日)。新建 `core/logging.py`(30 行)+ 改 `handle_request`(5 行)。这一步不解决任何 bug,但让**后面所有排障从"不可能"变成"可能"**——如果这周之后要交给别人接手,这是最该留下的东西。
**明确不做**:1-2(桥接权限降级,需要先探测 AstrBot 能力,容易卡住)、队列相关全部、前端全部、任何精简。
**这一周结束时的状态**:凭据已轮换、权限矩阵成为强制点、最重的两条文件系统攻击链被切断、越权读写他人资源被堵、线上出错终于有日志。队列的 LIFO 和取消竞态仍在,但它们是"用户体验差 + 偶发扣费",不是"数据泄漏"。
---
### 如果有 1 个人 1 个月(20 人日)
在上面 5 天的基础上,继续:
6. **阶段 1 剩余全部**(+5 人日):1-2 桥接权限降级与管理员白名单、1-8 media/fetch 令牌绑定、1-9 migrate 护栏、1-10 快照脱敏、1-11 成人内容闸门服务端重建、1-12 聊天媒体导入、1-13 资产包导入、1-14 素材绑定 schema、1-15 SettingsPage 承诺、1-16 `_conf_schema.json`。做完这些,安全边界这条线可以宣布收工。
7. **2-1 + 2-2 + 2-3 队列三件套**(+3 人日):CAS、FIFO、重试链路。三者都在 `worker_service` / `queue_service` / `job_repository` 这个小圈子里,一起改比分开改省一半时间。
8. **2-9 PostgreSQL 修复**(+0.5 人日):三行字面量 + 一条静态扫描测试。如果部署形态不打算用 PG,可以只加测试并在文档里标注"PG 后端当前不可用",但**不要装作它能用**——`config.yaml` 现在把它作为受支持配置对外暴露。
9. **2-14 + 2-15 前端两条(P1 / P2)**(+3 人日):`displayMediaUrl` 去副作用 + 轮询重入保护。这是用户最直接感知的"页面卡死"。
10. **2-17 + 2-18 + 2-19 三个小修**(+1 人日):问号串、占位提示污染 `base_prompt`、问卷示例数据。加起来不到一天,但都是"用户一眼看得见"的问题。
11. **阶段 4-D 的 pytest 配置 + 最小 CI**(+1.5 人日):`pyproject.toml` 的四行配置 + 一个 GitHub Actions(或等价物)跑 `pytest` + `typecheck` + 前端契约。有了 CI,前面所有新增的测试才真正起作用。
12. 剩余 1 人日留给 buffer 与回归验证。
**这个月明确不做**:装配容器(阶段 3 的主体,一个人一个月做不完且中途停手比不做更糟)、App.vue 拆分、任何后端样板收敛。
**取舍逻辑**:一个月的预算应该全部花在**"会出事"和"看不见"**上。技术债(App.vue、样板重复、god object)会让下个季度的每个功能都慢 20%,但它们不会让用户数据泄漏、不会让任务永久卡死、不会让线上故障无法定位。**债可以背,事故不能。**
---
## 6. 附:本次审计的方法与局限
### 方法
- **15 个维度并行审计**:A1 生成与队列 / A2 工作流与轮次 / A3 素材与风格集 / A4 数据层 / A5 核心与安全 / A6 引擎与适配器 / A7 路由与插件入口 / A8 前端 App 主体 / A9 前端功能组件 / B1 前后端耦合 / B2 后端内部耦合 / C1 后端精简空间 / C2 前端精简空间 / C3 测试与仓库卫生 / C4 横切关注点,另加 C0 测试实跑。每个维度独立通读源码并给出带 `文件:行号` 的发现,共 **214 条**。
- **对抗式复核**:对全部 **56 条 P0/P1** 各派一名独立复核者,立场预设为"**默认这是误报**",要求实际 Read 源码后才可判定成立。结果 **推翻 16 条,维持 40 条 —— 但维持的 40 条里有 33 条被下调严重度,仅 7 条维持原判。误报率 29%,下调率 59%**。原判 P0 的 6 条只剩 1 条仍是 P0;原判 P1 的 50 条中仅 6 条维持 P1。被推翻的条目**一律未进入本路线图**;复核认为"机制属实但影响被夸大"的,按复核给出的降级严重度收录并在文中标注"经复核降级"(本文件共 **8 处**:2-5、2-6、2-14、3-8、3-9、3-10,以及阶段 4 中的 `_string_list` 与零覆盖 service 计数。其中 2-14 / 3-8 / 3-9 三处是**终审补正**——初稿分别按 P0 / P1 / P1 表述,与复核给出的 P1 / P3 / P2 不符)。
- **实跑验证**:后端 `python -m pytest tests/` → **263 passed in 188.72s**;前端 `node --test` → **pass 26 / fail 0**(411 ms);`npm run typecheck` 在 `strict` 下通过。复核环节另用 `coverage 7.15.2` 对 `backend/services` 做了一次真实行覆盖测量,用于证伪"23 个 service 零测试"这条发现。
- **脚本化取证**:179 个 Python 模块的 AST 导入图(扇入/扇出/SCC/分层违规)、`RouteSpec` 与 handler `require_*` 的逐条比对、CSS 类引用可达性与声明块重复度、导出符号可达性、`git ls-files` / `git log --all` / `tar -tf` 的全量体积与内容统计。部分发现(YAML 往返不等价、存储根越界、`WorkflowFeedbackInterpreter` 的数字误判)由审计者在真实仓库上用 `python -c` 实际执行复现。
### 局限(请据此调整对本报告的信任度)
1. **以静态审计为主。** 绝大多数结论来自源码阅读 + 局部脚本执行,**未做动态渗透测试**。权限与 IDOR 的攻击链是按代码路径推演的,未在真实 AstrBot 实例上端到端打通(唯一例外是存储根越界读取,已用 `python -c` 在仓库内实测复现到签名 URL 这一步)。
2. **未做压力测试。** "队列 LIFO 导致饿死"、"asyncio 默认线程池被占满"、"图库 O(N²) 重算"这三条的**机理**由代码证实,但**触发阈值**(多少并发、多少张图)是按代码常量推算的,未实测。
3. **部分并发问题未实测复现。** `update_task` 无 CAS 的取消覆盖窗口、`reconcile_round` 复活 `superseded` 父轮次,都是代码路径分析的结论,未构造并发场景实际触发。复核环节已经证明这类推演有 29% 的出错率——**在动手修之前,建议先写一个能复现的测试,红了再改。**
4. **前端未做浏览器实跑。** 前端全部结论来自源码阅读与静态脚本分析,**没有在浏览器里打开过这个应用**。`displayMediaUrl` 的 O(N²) 与 Blob 泄漏、事件轮询叠加,都未用 DevTools Performance / Memory 面板验证。
5. **覆盖率数据是下界。** 用端点字面量 grep 得到的"166 条路由中 33 条被测试触及"系统性低估了实际覆盖(复核实测 handler 函数名命中 50 条)。**要给覆盖率结论必须跑 `coverage.py`**,本报告的量化目标表里凡涉及覆盖率的行都应在动手前用真实测量重新校准。
6. **未审计的范围**:`.tmp/` 内部的源码副本、`node_modules/`、`__pycache__/`、`release/` 内的源码、`web/assets/` 与 `pages/imagestudio/assets/` 的构建产物内容。注意 `.tmp/` 里有多份旧版本源码快照,若用全仓 grep 统计会系统性虚高(复核发现的 `_string_list` "18 次 vs 实际 17 次"即由此产生)。
7. **单点时间快照。** 审计基于分支 `codex/character-profile-document-import` @ `8040a1b`,工作树含未提交改动。行号可能随后续提交漂移,动手前请以 `git blame` 复核定位。