chore: prepare reproducible 1.0.73 release
这个提交存在于:
父节点
2d680509d7
当前提交
734c92c9f2
共有 34 个文件被更改,包括 15882 次插入 和 114 次删除
5
.gitignore
Vendored
5
.gitignore
Vendored
|
|
@ -34,6 +34,11 @@ data/exports/*
|
|||
!data/temp/.gitkeep
|
||||
!data/exports/.gitkeep
|
||||
|
||||
# Build/release artifacts (published via GitHub Releases, not the repo).
|
||||
# Tracking these grew .git to 51 MB; scripts/package_plugin.sh regenerates them.
|
||||
release/
|
||||
dist/
|
||||
|
||||
# Local machine/editor noise
|
||||
.tmp/
|
||||
.env*
|
||||
|
|
|
|||
48
CHANGELOG.md
48
CHANGELOG.md
|
|
@ -58,10 +58,58 @@
|
|||
|
||||
# Changelog
|
||||
|
||||
## [1.0.73] - 2026-07-27
|
||||
|
||||
- 完成五阶段安全、正确性、服务组合根与前端精简收口:路由权限和归属校验成为统一执行点,storage、迁移、配置快照、成人内容和聊天媒体导入均按服务端边界保护。
|
||||
- 修复队列 CAS/FIFO、轮次重试、PostgreSQL 占位符、归档、请求异常传播与素材绑定 fail-closed 行为,并用针对性回归测试覆盖。
|
||||
- 引入服务组合根并补齐 WorkflowService 事件总线装配;将分层边界固化为测试。
|
||||
- 将发布包改为精确 Git ref 的 tar.gz 归档,拒绝从含未提交 tracked 改动的 HEAD 打包,并移除历史 release ZIP 产物。
|
||||
|
||||
## [1.0.72] - 2026-07-24
|
||||
|
||||
- 修复头像节点候选图回退:没有 round 详情时仍显示节点已有生成图片,不再出现中间预览空白。
|
||||
- 为工作流主预览下方的 LLM 对话框增加固定最小高度,避免被挤成不可见细条。
|
||||
- 为详细工作流头像节点加入服务端硬约束:1:1、单人近景头像,禁止全身、半身、三视图和设定图构图。
|
||||
|
||||
## [1.0.71] - 2026-07-24
|
||||
|
||||
- 强制角色工作流在 AstrBot iframe 中保持节点流、主预览和操作区三栏显示,避免响应式断点把工作区折叠成纵向布局。
|
||||
- 修复工作流区域的 grid-area 绑定,确保主预览、LLM 和操作区落在正确列。
|
||||
- 继续使用 storage:// 媒体解析链路,避免候选图直接渲染不可用的存储 URI。
|
||||
|
||||
## [1.0.70] - 2026-07-24
|
||||
|
||||
- 修复插件 iframe 触发窄屏断点导致工作流节点流整栏占满、主预览和 LLM 被推到下方的问题;工作流在常见插件视口保持节点流 / 主预览+LLM / 操作区三栏。
|
||||
- 保持图片媒体签名与 Blob 解析修复。
|
||||
|
||||
|
||||
|
||||
## [1.0.69] - 2026-07-24
|
||||
|
||||
- 重写角色工作流七大节点工作区布局:主预览、节点绑定 LLM 和操作区明确分栏,移除重复的右侧节点详情。
|
||||
- 修复插件桥接环境下 storage://、image_uri 和 humbnail_uri 图片无法显示的问题,统一签名并转为本地 Blob。
|
||||
|
||||
|
||||
|
||||
鏈」鐩粠 1.0.8 璧蜂娇鐢ㄨ鏂囦欢璁板綍鍙獙鏀剁殑灏忕増鏈€傚紑鍙戜腑鐨勭増鏈粎浠h〃浠g爜閲岀▼纰戯紱瀹屾垚鍏ㄩ儴浜屾瀹¤闃熷垪鍚庡啀缁熶竴閮ㄧ讲銆?
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [1.0.68] - 2026-07-24
|
||||
|
||||
- Rebuild the detailed character workflow into seven major nodes: persona draft, headshot, upper body, lower body, full body, design sheet, and repair.
|
||||
- Split the workspace into node flow, main preview, node actions, node-bound LLM adjustment, and compact node information regions.
|
||||
- Keep signed image URLs renderable while plugin-page Blob resolution runs, and resolve non-round preview images directly from the selected node cache.
|
||||
|
||||
|
||||
|
||||
## [1.0.67] - 2026-07-24
|
||||
|
||||
- Simplify the character workflow into a two-column workspace, remove the low-value node detail panel, move workflow actions above the preview, and place the node-bound LLM adjustment window below the main preview.
|
||||
- Fix generated avatar/headshot previews being hidden when node image payloads omit or mismatch workflow_id by resolving the preview pool from the selected node cache.
|
||||
|
||||
|
||||
|
||||
## [1.0.52] - 2026-07-20
|
||||
|
||||
- Remove source prompt, artist-name and tag anchoring from multi-image style consensus input.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,123 @@
|
|||
# ImageStudio 发布前最终代码审计(2026-07-22)
|
||||
|
||||
## 结论
|
||||
|
||||
当前分支的功能测试、前端类型检查和生产构建均通过,但不建议直接发布。发布前至少应关闭两个灾难级风险:在线恢复备份的非原子覆盖,以及插件终止后仍可能存活的后台 worker。其余权限边界、档案归档语义和前端巨型组件问题建议按下方队列处理。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- 后端:`python -m pytest -q`,260 passed,178.03s。
|
||||
- 前端:`npm.cmd run typecheck` 通过。
|
||||
- 前端契约:`npm.cmd run test:contracts`,26 passed。
|
||||
- 生产构建:`npm.cmd run build` 通过。
|
||||
- 构建警告:插件主 JS 约 645.14 kB,独立 Web 主 JS 约 643.15 kB;主 CSS 约 288.72 kB。
|
||||
- Git:当前分支 `codex/character-profile-document-import`,相对 `main` 增加 5 个提交;无未提交源码改动(审计文档和错题本更新除外)。
|
||||
|
||||
## 发布阻断项
|
||||
|
||||
### P0-1 在线备份恢复可能破坏数据库并产生部分恢复
|
||||
|
||||
- 位置:`backend/services/data_backup_service.py:118`
|
||||
- 证据:恢复流程先覆盖配置,再用恢复后的配置决定数据库目标;随后使用 `shutil.copy2` 直接覆盖正在运行的 SQLite 文件,并用 `copytree(..., dirs_exist_ok=True)` 合并媒体目录。
|
||||
- 灾难路径:worker 或请求仍持有数据库连接时覆盖数据库文件,可能导致活动连接继续写旧 inode/句柄、恢复库被后续写入污染、数据库与媒体不一致;任一复制中途失败还会留下“配置已换、数据库或媒体只恢复一部分”的状态。
|
||||
- 修复要求:恢复必须进入维护模式,停止并确认所有 worker 已退出,拒绝新写请求;全部内容先恢复到同盘 staging,校验和迁移成功后再原子切换;失败时自动回滚配置、数据库和媒体根;恢复成功后重新初始化数据库与 worker。
|
||||
- 发布门禁:增加“活动任务期间恢复”“复制中途失败回滚”“恢复后数据库一致性”“旧媒体清理策略”测试。
|
||||
|
||||
### P0-2 插件终止可能遗留仍在执行的旧 worker
|
||||
|
||||
- 位置:`backend/services/worker_service.py:180`、`backend/services/worker_service.py:251`、`main.py:433`
|
||||
- 证据:单 worker 只 `join` 最多 5 秒并返回 `running` 状态;worker pool 逐个等待;`terminate()` 不检查 stop 结果,随后直接清空 runtime 引用。
|
||||
- 灾难路径:远程模型调用超过 5 秒时,插件卸载/热重载已返回,但旧 daemon 线程仍可继续写任务和数据库;新插件实例会启动新 worker,进阶素材恢复逻辑还会把旧实例正在处理的任务标记失败,形成旧线程回写、重复执行或状态反转。
|
||||
- 修复要求:worker handler 引入可取消/可中断的 provider timeout;pool 统一广播停止后并行等待;若仍存活则 `terminate()` 明确失败并阻止新实例启动 worker;不要在 `running=True` 时丢弃 runtime 引用。
|
||||
- 发布门禁:增加阻塞 provider、热重载、双实例、旧 worker 晚到结果不得复活终态任务的并发测试。
|
||||
|
||||
## 高优先级问题
|
||||
|
||||
### P1-1 Web bridge 对任意已认证用户授予全部管理能力
|
||||
|
||||
- 位置:`main.py:104`、`main.py:2324`、`adapters/astrbot_adapter.py:171`
|
||||
- 证据:只要请求中存在 `username` 或 `user_id`,上下文就获得写入、配置、素材和重试权限;dispatcher 解析了 route permission,但没有中央执行权限矩阵,只依赖各 handler 自觉校验。
|
||||
- 风险:若 AstrBot WebUI 存在非管理员账号或插件入口被反向代理给多用户,普通登录用户可修改模型密钥相关配置、恢复备份、删除素材、重试任务。
|
||||
- 建议:从 AstrBot 请求读取真实角色/能力;无法读取时只授予 read,管理操作要求管理员声明;dispatcher 按 `RouteMatch.permission` 中央 fail-closed,handler 保留二次校验。
|
||||
- 当前可接受边界:仅限明确声明的“可信 AstrBot 管理员工作台”,不可宣传为多租户或普通用户共享服务。
|
||||
|
||||
### P1-2 只读权限可触发付费 LLM 文档识别
|
||||
|
||||
- 位置:`backend/route_registry.py:62`、`backend/route_registry.py:63`、`backend/routes/profile_routes.py:111`
|
||||
- 证据:快速草稿和文档导入被标记为 `read`,handler 仅要求已登录,但服务会调用配置的结构化文本模型;单次文档允许 120000 字符。
|
||||
- 风险:只读用户可以批量消耗模型额度,且没有此端点专属速率、token 或成本预算限制。
|
||||
- 建议:改为 `write` 或独立 `can_use_models` 权限;限制请求字节、估算 token、单用户并发和日配额;把 provider timeout、用量和审计记录纳入返回链路。
|
||||
|
||||
### P1-3 “归档角色”实际执行软删除
|
||||
|
||||
- 位置:`backend/routes/profile_routes.py:101`、`backend/services/profile_service.py:136`
|
||||
- 证据:`archive_profile()` 直接调用 `delete_profile()`,仓储状态写为 `deleted`,审计动作也是 `delete_profile`。
|
||||
- 风险:API 名称、UI 预期和数据状态冲突;归档后角色从正常查询消失,未来清理逻辑可能把本应保留的档案当作已删除数据处理。
|
||||
- 建议:实现独立 `archive_profile`,状态使用 `archived`,读取/恢复规则与 `deleted` 分离;如果产品只支持删除,应移除 archive 路由和文案。
|
||||
|
||||
### P1-4 备份创建与校验缺少磁盘/内存预算
|
||||
|
||||
- 位置:`backend/services/data_backup_service.py:36`、`backend/services/data_backup_service.py:198`
|
||||
- 证据:备份限制文件数但不限制创建总字节或剩余磁盘;校验使用 `archive.read(name)` 计算哈希,会把单个条目整体读入内存。
|
||||
- 风险:大图库可填满数据盘;超大单文件恢复校验可造成进程内存峰值和 OOM。
|
||||
- 建议:创建前统计总量和可用空间,设置可配置上限;哈希校验使用流式读取;压缩包本身也限制大小和压缩比,防止 zip bomb。
|
||||
|
||||
## 中优先级优化
|
||||
|
||||
### P2-1 `App.vue` 已成为不可控的单体应用
|
||||
|
||||
- 位置:`frontend/standalone-web/src/App.vue:1`
|
||||
- 现状:约 22115 行,script 约 11110 行、template 约 2800 行、全局 style 约 8170 行;约 682 个函数/computed/watch 热点。
|
||||
- 影响:任何页面改动都可能触发整文件冲突、状态串扰和主包膨胀;测试难以覆盖局部状态机。
|
||||
- 重构顺序:先抽 `useMediaResolver`、`useThemePreferences`、`useNotifications`、`useGenerationJobs`、`useWorkflowWorkspace`;再把主导航页面变成页面容器;最后把全局 CSS 拆为 token/layout/page 三层。
|
||||
- 约束:插件 iframe 的核心一级页面仍应同步可用,避免重现短时资源令牌导致的分片失效;可以拆源码和 CSS,但对插件构建采用稳定主包或宿主可持久访问的 chunk 策略。
|
||||
|
||||
### P2-2 主包过大且同步页面继续增加
|
||||
|
||||
- 位置:`frontend/standalone-web/src/App.vue:15`、`frontend/standalone-web/src/App.vue:39`
|
||||
- 现状:五个一级页面同步引入是 iframe 稳定性修复,但主 JS 已超过 Vite 500 kB 警戒线。
|
||||
- 建议:把纯工具库、数据字典、非路由弹窗和独立 Web 专用模块拆为稳定 vendor/helper chunk;插件页继续保证一级页面不依赖易过期动态资源。对插件和 standalone 使用不同 chunk 策略,不要一刀切恢复全量懒加载。
|
||||
|
||||
### P2-3 进阶素材页继续扩大,并存在可访问性细节
|
||||
|
||||
- 位置:`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:113`、`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1392`
|
||||
- 现状:组件约 2024 行;分类按钮容器声明 `tablist`,按钮却没有 `role=tab`、`aria-selected` 和键盘方向键行为。
|
||||
- 建议:拆出 `AdvancedMaterialFilterBar`、导入队列、验证面板和封存库网格;如果不实现完整 tab 语义,移除 `tablist` 改为普通筛选按钮组。
|
||||
|
||||
### P2-4 前端备份导出逻辑重复
|
||||
|
||||
- 位置:`frontend/standalone-web/src/features/settings/BackupPage.vue:16`、`frontend/standalone-web/src/features/settings/SettingsPage.vue:109`
|
||||
- 现状:两处重复请求、Blob、文件名和下载逻辑,文案及文件名前缀已经分叉。
|
||||
- 建议:抽 `downloadJsonBackup()` 和统一任务状态 composable;设置页只组合 `BackupPage`,避免保留第二套实现。
|
||||
|
||||
### P2-5 路由权限声明和实际校验存在漂移风险
|
||||
|
||||
- 位置:`backend/route_registry.py:9`、`adapters/astrbot_adapter.py:171`
|
||||
- 现状:权限矩阵目前主要用于清单展示,实际执行依赖每个路由函数内部的 `require_*`。新增路由漏写校验时会直接暴露。
|
||||
- 建议:dispatcher 中央执行权限矩阵;增加自动测试,遍历全部路由验证 permission 与实际行为一致;保留 handler 校验作为纵深防御。
|
||||
|
||||
## 低优先级与工程质量
|
||||
|
||||
- `main.py` 约 2500 行且包含插件生命周期、聊天命令、桥接适配、配置映射和媒体响应兼容,应拆为 bootstrap、chat plugin、bridge、runtime config 四个模块。
|
||||
- `generation_service.py`、`advanced_style_set_service.py` 和两个大型 repository 存在 300-500 行函数;优先按“事务命令 + 纯计算 + provider adapter”拆分,不要只做机械切函数。
|
||||
- 构建生成的两个 `index.html` 带 CRLF/尾随空白,`git diff --check` 不干净;发布流水线应固定换行符并在提交前执行 `git diff --check`。
|
||||
- `metadata.yaml`、部分旧 Markdown/注释在当前终端显示乱码,需确认文件真实编码统一为 UTF-8,避免市场页描述或日志在目标环境乱码。
|
||||
- 固定复用同一个 pytest `--basetemp` 在 Windows 上可能与残留进程/旧目录互相影响;CI 使用唯一临时目录并设置全局超时。正常无 basetemp 全测已通过。
|
||||
|
||||
## 推荐实施队列
|
||||
|
||||
1. P0:实现维护模式、原子恢复和失败回滚。
|
||||
2. P0:修复 worker 可取消停止与热重载双实例竞态。
|
||||
3. P1:收紧 bridge 权限和付费模型端点权限/配额。
|
||||
4. P1:修正角色 archive/delete 语义并迁移已有状态。
|
||||
5. P1:为备份增加容量、流式校验和 zip bomb 防护。
|
||||
6. P2:拆分 `App.vue` 状态域和 CSS,同时保持插件 iframe 一级页面稳定。
|
||||
7. P2:拆分进阶素材页并统一下载、媒体解析、任务状态等重复逻辑。
|
||||
8. 发布门禁:全测、前端契约、typecheck、双构建、`git diff --check`、热重载并发测试、备份恢复故障注入测试。
|
||||
|
||||
## 可立即发布的范围
|
||||
|
||||
- 可用于受信任管理员的内部验证环境。
|
||||
- 不应在修复 P0 前启用“在线恢复备份”。
|
||||
- 不应在未明确管理员边界前作为多用户共享 Web 服务发布。
|
||||
- 当前角色文档导入增量本身已有 5 项后端测试,前端类型/契约/构建通过,但其模型成本权限仍需收紧。
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
# ImageStudio 1.0.73 本地发布收口记录
|
||||
|
||||
日期:2026-07-27
|
||||
|
||||
## 本轮范围
|
||||
|
||||
- 阶段 0:移除历史发布归档并使用 `git archive` 从 Git 树构建发布包,阻断忽略文件被目录复制带入归档。
|
||||
- 阶段 1:权限矩阵、路由归属校验、storage 沙箱、迁移覆盖确认与审计、配置快照脱敏、成人内容复核、聊天媒体目录白名单和魔数校验。
|
||||
- 阶段 2:队列 CAS/FIFO、轮次重试、PostgreSQL 占位符、归档语义、错误传播、尺寸字段和素材绑定 fail-closed。
|
||||
- 阶段 3:服务组合根、WorkflowService 事件总线完整装配、分层边界测试和 core 下沉。
|
||||
- 阶段 4:删除死代码、区分同名异义文本辅助函数、拆分 `App.vue` 样式。
|
||||
|
||||
## 本地发布门禁
|
||||
|
||||
发布前必须在本次最终 commit 上执行并记录输出:
|
||||
|
||||
```powershell
|
||||
python -m pytest -q
|
||||
Push-Location frontend
|
||||
npm.cmd run test:contracts
|
||||
npm.cmd run typecheck
|
||||
npm.cmd run build
|
||||
Pop-Location
|
||||
git diff --check
|
||||
scripts/package_plugin.sh v1.0.73 dist
|
||||
```
|
||||
|
||||
本次实测结果:后端 `371 passed, 1 skipped`(共 372 项,2026-07-27,使用仓库隔离临时目录);前端 26/26 通过;typecheck 和两套前端产物构建通过;工作树通过 whitespace 检查。归档仍须在最终 tag 上验证包含 `metadata.yaml`、`main.py`、`web/index.html` 与 `pages/imagestudio/index.html`,且不含秘密路径。
|
||||
|
||||
## 发布构造边界
|
||||
|
||||
- `scripts/package_plugin.sh` 仅从指定 Git ref 构建 tar.gz,默认 `HEAD` 若含未提交 tracked 改动则拒绝执行。
|
||||
- tar.gz 是 NAS 部署格式;历史 Windows ZIP 曾出现路径分隔符兼容性问题,不能恢复为直接 `Compress-Archive` 流程。
|
||||
- 归档名称必须由同一 SHA 或 tag 推导;部署记录需保存 tag、commit SHA、归档 SHA-256 和构建时间。
|
||||
|
||||
## 外部阻断项
|
||||
|
||||
以下事项不能以仓库提交替代,发布前必须由有对应权限的操作者完成:
|
||||
|
||||
1. 按 `审计/02-BUG清单.md` 第 0.1 节轮换已泄露的五类凭据。
|
||||
2. 轮换确认后删除本机 `.env.imagestudio_codex_handoff.yaml`。
|
||||
3. 清理 NAS 路径 `/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio` 中的旧密钥、历史包和扫描目录内备份。
|
||||
4. 将备份留在 `data/plugin_backups` 或插件扫描树外;不能在 `data/plugins` 下留下隐藏备份目录。
|
||||
5. NAS 部署后验证 AstrBot 日志已加载 `1.0.73`,并执行权限、迁移、队列取消竞争和前端新资源 hash 的冒烟检查。
|
||||
314
docs/错题本.md
314
docs/错题本.md
|
|
@ -1,140 +1,234 @@
|
|||
# 项目错题本
|
||||
# 椤圭洰閿欓鏈?
|
||||
## 2026-07-22 鈥?鎻掍欢 iframe 璧勬簮浠ょ墝瀵艰嚧椤甸潰绌虹櫧
|
||||
|
||||
## 2026-07-22 — 插件 iframe 资源令牌导致页面空白
|
||||
- 闃舵锛氶儴缃?/ 鍔熻兘琛屼负
|
||||
- 绫诲瀷锛氱幆澧?/ 鏋勫缓 / 鍔熻兘琛屼负
|
||||
- 鐜拌薄锛氬湪 AstrBot 鎻掍欢椤靛仠鐣欎竴娈垫椂闂村悗锛岀偣鍑荤礌鏉愩€佽鑹层€佸浘搴撱€佽缃垨鏃ュ織锛屼富澹充粛鍦ㄤ絾椤甸潰鍐呭鍖哄煙娑堝け銆?- 鏍瑰洜锛氭彃浠堕〉杩愯鍦?sandbox iframe 涓紝涓€绾ч〉闈娇鐢ㄥ姩鎬佸垎鐗囧姞杞斤紱瀹夸富鍙戞斁鐨勮祫婧愪护鐗屾湁鏁堟湡杈冪煭锛屽垏椤垫椂 CSS/JS 鍒嗙墖璇锋眰鍙兘澶辨晥銆傞敊璇姞杞芥病鏈夌ǔ瀹氱殑椤甸潰绾у厹搴曪紝涓斾竴娆¢敊璇鐞嗗皾璇曡鍙?sandbox 绂佹璁块棶鐨?sessionStorage锛岃Е鍙?SecurityError銆?- 淇鎴栬閬匡細灏嗙礌鏉愩€佽鑹层€佸浘搴撱€佽缃€佹棩蹇椾簲涓竴绾ч〉闈㈡敼涓轰富鍖呭悓姝ュ姞杞斤紱淇濈暀宸ヤ綔娴佹绾х粍浠舵寜闇€鍔犺浇锛涘绱犳潗鍒嗙被鍜屾爣绛惧瓧娈靛鍔犲紓甯告暟鎹厹搴曘€?- 棰勯槻瑙勫垯锛欰strBot 鎻掍欢 iframe 涓笉瑕佹妸鏍稿績涓€绾ц矾鐢变緷璧栫煭鏃朵护鐗岀殑鍔ㄦ€佸垎鐗囷紱娴忚鍣ㄥ瓨鍌ㄨ闂繀椤诲寘鍦?try/catch 涓紝涓嶈兘璁╁彲閫夊亸濂介樆鏂〉闈㈡覆鏌撱€?- 楠岃瘉璇佹嵁锛氬墠绔被鍨嬫鏌ラ€氳繃锛涘墠绔绾︽祴璇?26/26 閫氳繃锛涙彃浠堕〉鍜岀嫭绔?Web 鐢熶骇鏋勫缓閫氳繃锛汵AS `astrbot-ops-pro` 閲嶅惎鍚庡叆鍙e垏鎹㈠埌鍚屾涓诲寘骞朵繚鐣?`plugin_data`銆?
|
||||
## 2026-07-22 鈥?Windows 鍙戝竷鍖呬笉鑳戒娇鐢?zip 鍙嶅悜瑙e帇閮ㄧ讲
|
||||
|
||||
- 阶段:部署 / 功能行为
|
||||
- 类型:环境 / 构建 / 功能行为
|
||||
- 现象:在 AstrBot 插件页停留一段时间后,点击素材、角色、图库、设置或日志,主壳仍在但页面内容区域消失。
|
||||
- 根因:插件页运行在 sandbox iframe 中,一级页面使用动态分片加载;宿主发放的资源令牌有效期较短,切页时 CSS/JS 分片请求可能失效。错误加载没有稳定的页面级兜底,且一次错误处理尝试读取 sandbox 禁止访问的 sessionStorage,触发 SecurityError。
|
||||
- 修复或规避:将素材、角色、图库、设置、日志五个一级页面改为主包同步加载;保留工作流次级组件按需加载;对素材分类和标签字段增加异常数据兜底。
|
||||
- 预防规则:AstrBot 插件 iframe 中不要把核心一级路由依赖短时令牌的动态分片;浏览器存储访问必须包在 try/catch 中,不能让可选偏好阻断页面渲染。
|
||||
- 验证证据:前端类型检查通过;前端契约测试 26/26 通过;插件页和独立 Web 生产构建通过;NAS `astrbot-ops-pro` 重启后入口切换到同步主包并保留 `plugin_data`。
|
||||
- 闃舵锛氶儴缃?- 绫诲瀷锛氱幆澧?/ 閮ㄧ讲
|
||||
- 鐜拌薄锛歐indows `Compress-Archive` 鐢熸垚鐨?ZIP 鍦?NAS `unzip` 鏃跺嚭鐜板弽鏂滄潬璺緞璀﹀憡锛屾棤娉曚綔涓哄彲闈犳彃浠?staging 鍖呫€?- 鏍瑰洜锛歐indows ZIP 宸ュ叿鍐欏叆鐨勮矾寰勫垎闅旂涓?NAS 瑙e帇宸ュ叿鍏煎鎬т笉绋冲畾锛屼笖 NAS SSH 绂佺敤浜?SFTP锛屼笉鑳戒緷璧?scp 涓婁紶銆?- 淇鎴栬閬匡細鏀圭敤鏈湴 `tar.gz`锛岄€氳繃 SSH 鏍囧噯杈撳叆娴佷笂浼犲埌 NAS锛涘湪 NAS 涓存椂 staging 瑙e帇鍚庯紝浠呰鐩栨彃浠舵簮鐮佺洰褰曪紝涓嶈Е纰?`data/plugin_data`銆?- 棰勯槻瑙勫垯锛歂AS 閮ㄧ讲浼樺厛浣跨敤 `tar.gz + SSH cat`锛涢儴缃插墠鎵ц鍘嬬缉鍖呭垪琛ㄥ拰鍏抽敭鍏ュ彛鏂囦欢妫€鏌ワ紝瑕嗙洊鍓嶅垱寤?`plugin_backups` 澶囦唤銆?- 楠岃瘉璇佹嵁锛歂AS staging 鍙甯歌В鍘嬶紱`pages/imagestudio/index.html` 鎸囧悜鏂颁富鍖咃紱瀹瑰櫒閲嶅惎鍚?ImageStudio 閲嶆柊鍔犺浇銆?
|
||||
## 2026-07-22 鈥?鎻掍欢鐩綍涓嶈兘閫掑綊鍒犻櫎缂撳瓨鏂囦欢
|
||||
|
||||
## 2026-07-22 — Windows 发布包不能使用 zip 反向解压部署
|
||||
- 闃舵锛氶儴缃?- 绫诲瀷锛氱幆澧?/ 閮ㄧ讲
|
||||
- 鐜拌薄锛氫互 `agent` 鐢ㄦ埛鏁翠綋鍒犻櫎 NAS 鎻掍欢鐩綍鏃讹紝瀹瑰櫒鐢熸垚鐨?`__pycache__/*.pyc` 鏂囦欢鍑虹幇鏉冮檺鎷掔粷銆?- 鏍瑰洜锛氶儴鍒嗚繍琛屾椂缂撳瓨鐢卞鍣?root 鐢ㄦ埛鍒涘缓锛屽涓?SSH 鐢ㄦ埛鏃犳潈鍒犻櫎锛涚洿鎺?`rm -rf` 浼氫腑鏂浛鎹㈡祦绋嬨€?- 淇鎴栬閬匡細淇濈暀鎻掍欢鐩綍骞朵娇鐢?staging 鍐呭瑕嗙洊锛涢儴缃插墠澶囦唤鏃ф彃浠剁洰褰曪紝閬垮厤鍒犻櫎杩愯鏃剁紦瀛樺拰鏁版嵁鐩綍銆?- 棰勯槻瑙勫垯锛氫笉瑕佸 NAS 鎻掍欢鐩綍鐩存帴 `rm -rf`锛涗娇鐢ㄦ潈闄愬彲琛岀殑瑕嗙洊寮忛儴缃诧紝蹇呰鏃惰瀹瑰櫒鍋滄鍚庣敱鍏峰鏉冮檺鐨勭淮鎶ゆ祦绋嬫竻鐞嗙紦瀛樸€?- 楠岃瘉璇佹嵁锛氳鐩栧紡閮ㄧ讲鎴愬姛锛屽鍣ㄩ噸鍚悗鎻掍欢姝e父鍔犺浇锛屾暟鎹簱鍜?`plugin_data` 鏈垹闄ゃ€?
|
||||
|
||||
- 阶段:部署
|
||||
- 类型:环境 / 部署
|
||||
- 现象:Windows `Compress-Archive` 生成的 ZIP 在 NAS `unzip` 时出现反斜杠路径警告,无法作为可靠插件 staging 包。
|
||||
- 根因:Windows ZIP 工具写入的路径分隔符与 NAS 解压工具兼容性不稳定,且 NAS SSH 禁用了 SFTP,不能依赖 scp 上传。
|
||||
- 修复或规避:改用本地 `tar.gz`,通过 SSH 标准输入流上传到 NAS;在 NAS 临时 staging 解压后,仅覆盖插件源码目录,不触碰 `data/plugin_data`。
|
||||
- 预防规则:NAS 部署优先使用 `tar.gz + SSH cat`;部署前执行压缩包列表和关键入口文件检查,覆盖前创建 `plugin_backups` 备份。
|
||||
- 验证证据:NAS staging 可正常解压;`pages/imagestudio/index.html` 指向新主包;容器重启后 ImageStudio 重新加载。
|
||||
## 2026-07-22 鈥?鍦ㄧ嚎鎭㈠涓嶈兘鐩存帴瑕嗙洊娲诲姩 SQLite 涓庡獟浣撶洰褰?
|
||||
- 闃舵锛氬彂甯冨墠鏈€缁堝璁?- 绫诲瀷锛氶儴缃?/ 鏁版嵁瀹夊叏 / 骞跺彂
|
||||
- 鐜拌薄锛氬浠芥仮澶嶆帴鍙e彲鍦ㄦ彃浠舵甯歌繍琛屻€亀orker 鍜岃姹備粛鍙兘鍐欏簱鏃讹紝鐩存帴瑕嗙洊閰嶇疆涓?SQLite 鏂囦欢锛屽苟鎶婂獟浣撶洰褰曞悎骞跺埌鐜版湁鐩綍銆?- 鏍瑰洜锛氭仮澶嶆祦绋嬫病鏈夌淮鎶ゆā寮忋€佸啓鍏ラ殧绂汇€佸悓鐩?staging銆佸師瀛愬垏鎹㈠拰鍏ㄩ摼璺け璐ュ洖婊氾紝鎶婂涓湁鐘舵€佽祫婧愬綋鎴愭櫘閫氭枃浠堕€愪釜澶嶅埗銆?- 淇鎴栬閬匡細淇鍓嶇鐢ㄧ敓浜х幆澧冨湪绾挎仮澶嶏紱鎭㈠蹇呴』鍏堝仠姝㈠苟纭 worker 閫€鍑猴紝鎷掔粷鏂板啓鍏ワ紝瀹屾暣鎭㈠鍒?staging 骞舵牎楠屽悗鍘熷瓙鍒囨崲锛屽け璐ヨ嚜鍔ㄥ洖婊氥€?- 棰勯槻瑙勫垯锛氫换浣曟暟鎹簱銆侀厤缃拰濯掍綋鑱斿悎鎭㈠閮藉繀椤诲叿澶?quiesce銆乻taging銆乤tomic switch銆乺ollback 鍥涗釜闃舵锛屼笉鑳藉湪娲诲姩 SQLite 涓婃墽琛?`copy2`銆?- 楠岃瘉璇佹嵁锛氬璁″畾浣?`backend/services/data_backup_service.py` 鐨勬仮澶嶉摼璺紱鐜版湁娴嬭瘯闆嗘病鏈夊浠芥仮澶嶅苟鍙戝拰鏁呴殰娉ㄥ叆瑕嗙洊锛涘畬鏁村缓璁 `docs/final-release-audit-2026-07-22.md`銆?
|
||||
## 2026-07-22 鈥?worker 瓒呮椂鍋滄鍚庝笉鑳戒涪寮冭繍琛屽疄渚?
|
||||
- 闃舵锛氬彂甯冨墠鏈€缁堝璁?- 绫诲瀷锛氬苟鍙?/ 鐢熷懡鍛ㄦ湡 / 鍔熻兘琛屼负
|
||||
- 鐜拌薄锛氳繙绋?provider 璋冪敤瓒呰繃鍋滄绛夊緟鏃堕棿鏃讹紝`stop()` 鍙繑鍥炰粛鍦ㄨ繍琛岋紝浣嗘彃浠?`terminate()` 浠嶆竻绌?runtime 寮曠敤骞跺厑璁稿悗缁疄渚嬪惎鍔ㄦ柊 worker銆?- 鏍瑰洜锛歸orker 鍙湁鍋滄浜嬩欢锛屾棤娉曚腑鏂鍦ㄦ墽琛岀殑 handler锛涚粓姝㈤摼璺拷鐣?`running` 杩斿洖鍊硷紝娌℃湁鍙屽疄渚嬫爡鏍忓拰鏅氬埌缁撴灉淇濇姢銆?- 淇鎴栬閬匡細provider 璋冪敤蹇呴』鏈夊彲鎺?timeout/cancel锛涚粺涓€骞挎挱鍋滄骞剁‘璁ゅ叏閮ㄧ嚎绋嬮€€鍑猴紱浠嶅瓨娲绘椂闃绘閲嶆柊鍚姩 worker骞朵繚鐣?runtime 寮曠敤锛涚粓鎬佹洿鏂颁娇鐢ㄧ姸鎬佹潯浠朵繚鎶ゃ€?- 棰勯槻瑙勫垯锛氱敓鍛藉懆鏈熺粨鏉熷彧鏈夊湪鎵€鏈夊悗鍙版墽琛屽櫒纭鍋滄鍚庢墠鑳芥姤鍛婃垚鍔燂紱绂佹鈥渟top 瓒呮椂浣嗙户缁嵏杞解€濄€?- 楠岃瘉璇佹嵁锛氬璁″畾浣?`backend/services/worker_service.py` 鍜?`main.py`锛涚幇鏈?worker 娴嬭瘯鍙鐩栧彲鍙婃椂閫€鍑哄満鏅紝娌℃湁闃诲 handler 鐑噸杞芥祴璇曘€?
|
||||
## 2026-07-22 鈥?鏈€缁堝璁¢獙璇佷笌娴嬭瘯涓存椂鐩綍闄烽槺
|
||||
|
||||
## 2026-07-22 — 插件目录不能递归删除缓存文件
|
||||
- 闃舵锛氬彂甯冨墠鏈€缁堝璁?- 绫诲瀷锛氭祴璇?/ 鐜
|
||||
- 鐜拌薄锛氬鐢ㄥ浐瀹氫粨搴撳唴 `--basetemp` 杩愯鍏ㄥ娴嬭瘯鏃朵袱娆¤秴鏃朵笖娈嬬暀 pytest 杩涚▼锛涗笉鎸囧畾 basetemp 鍚庡叏濂楁甯稿畬鎴愩€?- 鏍瑰洜锛歐indows 鐜涓嬪浐瀹氫复鏃剁洰褰曚笌娈嬬暀娴嬭瘯杩涚▼/鏃х洰褰曠姸鎬佺浉浜掑奖鍝嶏紝涓斿畨闈欐ā寮忓湪闀挎祴璇曟湡闂寸己灏戣繘搴﹁緭鍑猴紝瀹规槗璇垽涓轰唬鐮佹閿併€?- 淇鎴栬閬匡細缁堟鏈疆娈嬬暀 pytest 杩涚▼锛屾敼鐢?pytest 榛樿鍞竴涓存椂鐩綍锛涘鎱㈡枃浠跺崟鐙獙璇佸悗閲嶈窇鍏ㄥ銆?- 棰勯槻瑙勫垯锛欳I 涓烘瘡娆¤繍琛岀敓鎴愬敮涓€ basetemp锛屽苟璁剧疆鍏ㄥ眬 timeout 鍜岃繘搴﹁緭鍑猴紱娴嬭瘯瓒呮椂鏃跺厛鏌ユ畫鐣欒繘绋嬪拰鍗曟枃浠惰€楁椂锛屼笉瑕佺洿鎺ュ垽瀹氫笟鍔℃閿併€?- 楠岃瘉璇佹嵁锛歚test_advanced_style_set_workflow.py` 46 passed in 31.39s锛涙渶缁?`python -m pytest -q` 260 passed in 178.03s锛涘墠绔?26 椤瑰绾︺€乼ypecheck 鍜屽弻鏋勫缓鍧囬€氳繃銆?
|
||||
|
||||
- 阶段:部署
|
||||
- 类型:环境 / 部署
|
||||
- 现象:以 `agent` 用户整体删除 NAS 插件目录时,容器生成的 `__pycache__/*.pyc` 文件出现权限拒绝。
|
||||
- 根因:部分运行时缓存由容器 root 用户创建,宿主 SSH 用户无权删除;直接 `rm -rf` 会中断替换流程。
|
||||
- 修复或规避:保留插件目录并使用 staging 内容覆盖;部署前备份旧插件目录,避免删除运行时缓存和数据目录。
|
||||
- 预防规则:不要对 NAS 插件目录直接 `rm -rf`;使用权限可行的覆盖式部署,必要时让容器停止后由具备权限的维护流程清理缓存。
|
||||
- 验证证据:覆盖式部署成功,容器重启后插件正常加载,数据库和 `plugin_data` 未删除。
|
||||
## 2026-07-23 鈥?鍏徃鐢佃剳缁?ZeroTier 璁块棶鍚庣瓒呮椂
|
||||
|
||||
## 2026-07-22 — 在线恢复不能直接覆盖活动 SQLite 与媒体目录
|
||||
- 闃舵锛氱綉缁滄帓闅?- 绫诲瀷锛氱幆澧?/ 缃戠粶 / 鍔熻兘琛屼负
|
||||
- 鐜拌薄锛氬鐢ㄧ數鑴戣闂?ImageStudio 姝e父锛屽叕鍙哥數鑴戠粡 ZeroTier 璁块棶鏃跺嚭鐜扳€滃悗绔繛鎺?timeout鈥濄€?- 鏍瑰洜锛氬綋鍓嶅皻鏈嬁鍒板叕鍙哥數鑴戠殑瀹為檯璇锋眰澶辫触鍖咃紱鐜版湁璇佹嵁鎺掗櫎鈥淣AS 绔彛鏈洃鍚€濆拰鈥滄彃浠惰繘绋嬪畬鍏ㄦ湭鍚姩鈥濓紝浼樺厛鎬€鐤戝叕鍙哥綉缁滃埌 ZeroTier 缃戞鐨勮矾鐢便€乑eroTier flow rule/鎴愬憳鎺堟潈銆乄indows 闃茬伀澧欐垨瀹為檯璁块棶绔彛涓嶄竴鑷淬€傚簲鐢ㄤ晶棣栧睆 bootstrap 鍙瓑寰?6 绉掞紝鎻掍欢 bridge GET 绛夊緟 15 绉掞紝閾捐矾鏈変涪鍖?涓户寤惰繜鏃朵細琚墠绔〃鐜颁负鍚庣瓒呮椂銆?- 淇鎴栬閬匡細鍏堝湪鍏徃鐢佃剳楠岃瘉 ZeroTier IP 鍒板疄闄呮槧灏勭鍙?`26385` 鐨?TCP 杩為€氭€э紝骞剁‘璁ゆ祻瑙堝櫒璁块棶鐨勫湴鍧€涓嶆槸鏃х鍙?`6185`锛涜嫢 TCP 涓嶉€氾紝鏀捐鍏徃鐢佃剳鍒?NAS ZeroTier 鍦板潃 `10.147.17.231` 鎴?`172.24.141.75` 鐨勫搴旂鍙e苟妫€鏌?ZeroTier 鎺堟潈/Flow Rules锛涜嫢 TCP 閫氫絾椤甸潰浠嶈秴鏃讹紝鍐嶆鏌ユ祻瑙堝櫒寮€鍙戣€呭伐鍏蜂腑 `ui/bootstrap` 鐨勮姹傘€佽璇佷細璇濆拰鍝嶅簲鑰楁椂銆?- 棰勯槻瑙勫垯锛氫笉瑕佸彧鐢ㄢ€滈〉闈㈣兘鎵撳紑鈥濆垽鏂悗绔摼璺甯革紱蹇呴』鍒嗗埆楠岃瘉闈欐€佸叆鍙c€乣ui/bootstrap` API銆佸疄闄呭鍣ㄦ槧灏勭鍙e拰 ZeroTier path銆傚尯鍒?TCP timeout銆丠TTP 401/403銆丆ORS 鍜屽簲鐢?6 绉?bootstrap timeout 鍚庡啀鏀逛唬鐮併€?- 楠岃瘉璇佹嵁锛歂AS 璺敱瀛樺湪 `10.147.17.0/24` 涓?`172.24.0.0/16` ZeroTier 缃戞锛沗26385/26395/26399` 鐩戝惉鍦?`0.0.0.0`锛汵AS 鏈満閫氳繃 `127.0.0.1`銆乣192.168.31.210`銆乣10.147.17.231`銆乣172.24.141.75` 璁块棶 `26385` 鍧囪繑鍥?HTTP 200锛涙彃浠舵棩蹇楀彲瑙佹甯稿姞杞斤紝浣嗗綋鍓?NAS 鏃ュ織鐗堟湰涓?`1.0.66`銆傞」鐩唬鐮佷腑 bootstrap timeout 涓?6 绉掞紝bridge GET timeout 涓?15 绉掋€?## 2026-07-23 鈥?瑙掕壊鍒犻櫎琚ず渚嬫潵婧愬垽鏂潤榛樻嫤鎴?
|
||||
- 闃舵锛氬姛鑳戒慨澶?- 绫诲瀷锛氬姛鑳借涓?/ API濂戠害
|
||||
- 鐜拌薄锛氳鑹茶鎯呴〉鐐瑰嚮鈥滃垹闄も€濇棤纭寮圭獥銆佹棤璇锋眰銆侀〉闈㈣鑹蹭笉娑堝け銆?- 鏍瑰洜锛氬墠绔垹闄ゅ嚱鏁伴澶栧垽鏂?`profile.metadata.source === "sample"` 鍚庣洿鎺ヨ繑鍥烇紱璇ュ垽鏂病鏈夐敊璇彁绀猴紝涔熶笌鍚庣宸叉巿鏉冭鑹茶蒋鍒犻櫎鎺ュ彛鐨勮兘鍔涜竟鐣屼笉涓€鑷达紝瀵艰嚧鐢ㄦ埛鍙瑙掕壊琚潤榛樺綋浣滀笉鍙垹闄ょず渚嬪鐞嗐€?- 淇鎴栬閬匡細鍒犻櫎娴佺▼鍙繚鐣欒鑹插瓨鍦ㄣ€佹湭澶勪簬鍒犻櫎涓拰鍚庣鍐欐潈闄愭鏌ワ紱绉婚櫎鍒犻櫎涓撶敤鐨?`sample` 闈欓粯鎷︽埅銆傜ず渚嬭鑹茬殑鐢熸垚銆佸伐浣滄祦鍜岀礌鏉愮紪杈戦檺鍒朵繚鎸佷笉鍙樸€?- 棰勯槻瑙勫垯锛氬墠绔姝㈡搷浣滃繀椤绘湁鏄庣‘ UI 鐘舵€佹垨閿欒鎻愮ず锛涗笉瑕佸湪鍗曚釜鎿嶄綔涓鐢ㄤ笌鍏朵粬鎿嶄綔涓嶅悓鐨?`sample` 淇濇姢鏉′欢锛屽厛瀵圭収鍚庣璺敱鏉冮檺鍜岃祫婧愮敓鍛藉懆鏈熴€?- 楠岃瘉璇佹嵁锛氬凡淇敼 `frontend/standalone-web/src/App.vue:6241`锛涘墠绔?`vue-tsc --noEmit` 閫氳繃锛涘绾︽祴璇?26/26 閫氳繃锛沗git diff --check` 閫氳繃銆?
|
||||
|
||||
- 阶段:发布前最终审计
|
||||
- 类型:部署 / 数据安全 / 并发
|
||||
- 现象:备份恢复接口可在插件正常运行、worker 和请求仍可能写库时,直接覆盖配置与 SQLite 文件,并把媒体目录合并到现有目录。
|
||||
- 根因:恢复流程没有维护模式、写入隔离、同盘 staging、原子切换和全链路失败回滚,把多个有状态资源当成普通文件逐个复制。
|
||||
- 修复或规避:修复前禁用生产环境在线恢复;恢复必须先停止并确认 worker 退出,拒绝新写入,完整恢复到 staging 并校验后原子切换,失败自动回滚。
|
||||
- 预防规则:任何数据库、配置和媒体联合恢复都必须具备 quiesce、staging、atomic switch、rollback 四个阶段,不能在活动 SQLite 上执行 `copy2`。
|
||||
- 验证证据:审计定位 `backend/services/data_backup_service.py` 的恢复链路;现有测试集没有备份恢复并发和故障注入覆盖;完整建议见 `docs/final-release-audit-2026-07-22.md`。
|
||||
## 2026-07-23 鈥?NAS 閮ㄧ讲璺緞涓庡鍣ㄩ噸鍚竟鐣?
|
||||
- 闃舵锛氶儴缃?- 绫诲瀷锛氶儴缃?/ 鐜
|
||||
- 鐜拌薄锛氶娆¢儴缃叉牎楠屽け璐ユ槸鎻掍欢鐩綍鎷煎啓閿欒锛涢殢鍚庡湪瀹瑰櫒鍐呮墽琛?`docker restart` 瀵艰嚧鎵ц shell 琚?`context canceled` 缁堟锛屾棫 staging 鐩綍鐭殏鐣欏湪鎻掍欢鎵弿鐩綍骞惰 AstrBot 褰撲綔绗簩涓彃浠跺姞杞姐€?- 鏍瑰洜锛氬疄闄呯洰褰曟槸 `astrbot_plugin_imagestudio`锛屼笉鏄?`astrabot_plugin_imagestudio`锛涘鍣ㄥ唴閲嶅惎鑷韩浼氱珛鍗虫潃鎺夊綋鍓?exec锛汚strBot 浼氭壂鎻?`data/plugins` 涓嬫墍鏈夌洰褰曪紝鏃х洰褰曚笉鑳界敤鏀瑰悕鏂瑰紡鐣欏湪閭i噷銆?- 淇鎴栬閬匡細鏀圭敤姝g‘鐩綍鍚嶏紱鏃х洰褰曠Щ鍏?`/AstrBot/data/plugin_backups`锛涢噸鍚繀椤荤敱 NAS 瀹夸富鏈烘墽琛岋紱閮ㄧ讲鍖呭厛鍋?SHA-256 鏍¢獙鍐嶆浛鎹€?- 棰勯槻瑙勫垯锛氶儴缃茶剼鏈繀椤诲厛楠岃瘉鐩爣鐩綍瀛樺湪锛涚姝㈠湪鐩爣瀹瑰櫒鍐呴儴閲嶅惎鑷韩锛涙彃浠舵棫鐗堟湰鍙厑璁告斁鍦?`plugin_backups`锛屼笉寰楃暀鍦?`data/plugins`銆?- 楠岃瘉璇佹嵁锛歂AS 瀹瑰櫒 `Up`锛涙棩蹇楀彧鍔犺浇涓€涓?`astrbot_plugin_imagestudio (1.0.66)`锛涙彃浠?metadata 涓?`1.0.66`锛沗frontend/standalone-web/src/App.vue:6241` 鍒犻櫎淇鏍囪瀛樺湪锛涘鍣ㄧ姸鎬佷负宸茬煡鐨?`health: starting`銆?## 2026-07-23 鈥?鎻掍欢妗ユ帴涓嶆敮鎸佽鑹插垹闄?DELETE
|
||||
|
||||
## 2026-07-22 — worker 超时停止后不能丢弃运行实例
|
||||
- 闃舵锛氬姛鑳戒慨澶?- 绫诲瀷锛欰PI濂戠害 / 鍔熻兘琛屼负
|
||||
- 鐜拌薄锛氳鑹茶鎯呴〉鍒犻櫎鎸夐挳浠嶆棤鏁堬紱鍓嶇鍦ㄦ彃浠?iframe 涓皟鐢?DELETE锛屼絾閮ㄥ垎 AstrBot Plugin Page bridge 鍙毚闇?`apiPost`锛岃姹傚洖閫€鍒版湭娉ㄥ唽鐨?method override 璺緞銆?- 鏍瑰洜锛氬悗绔彧娉ㄥ唽 `DELETE profiles/{profile_id}`锛屾病鏈夌粰妗ユ帴灞傛彁渚涚ǔ瀹氱殑 POST 鍒犻櫎鍏ュ彛锛汥ELETE 鑳藉姏鏄惁鏆撮湶鍙栧喅浜?AstrBot 鐗堟湰鍜岃繍琛屾椂 bridge 瀹炵幇銆?- 淇鎴栬閬匡細鏂板 `POST profiles/{profile_id}/delete`锛屽鐢ㄥ師鏈夋墍鏈夎€呮牎楠屻€佽蒋鍒犻櫎鍜屽璁¢€昏緫锛涘墠绔鑹插垹闄ょ粺涓€璋冪敤璇?POST 鍏ュ彛锛屼繚鐣欏師 DELETE 鎺ュ彛鍏煎澶栭儴璋冪敤銆?- 棰勯槻瑙勫垯锛氭彃浠?iframe 鍐呯殑鍐欐搷浣滀紭鍏堟彁渚涙槑纭殑 POST 鍔ㄤ綔璺敱锛涗笉鑳藉亣瀹?`apiPut`銆乣apiPatch` 鎴?`apiDelete` 鍦ㄦ墍鏈?AstrBot 鐗堟湰閮藉瓨鍦ㄣ€?- 楠岃瘉璇佹嵁锛氬垹闄?POST 璺敱鍥炲綊娴嬭瘯閫氳繃锛涘墠绔被鍨嬫鏌ラ€氳繃锛涙彃浠堕〉涓?standalone web 鏋勫缓閫氳繃銆?
|
||||
|
||||
- 阶段:发布前最终审计
|
||||
- 类型:并发 / 生命周期 / 功能行为
|
||||
- 现象:远程 provider 调用超过停止等待时间时,`stop()` 可返回仍在运行,但插件 `terminate()` 仍清空 runtime 引用并允许后续实例启动新 worker。
|
||||
- 根因:worker 只有停止事件,无法中断正在执行的 handler;终止链路忽略 `running` 返回值,没有双实例栅栏和晚到结果保护。
|
||||
- 修复或规避:provider 调用必须有可控 timeout/cancel;统一广播停止并确认全部线程退出;仍存活时阻止重新启动 worker并保留 runtime 引用;终态更新使用状态条件保护。
|
||||
- 预防规则:生命周期结束只有在所有后台执行器确认停止后才能报告成功;禁止“stop 超时但继续卸载”。
|
||||
- 验证证据:审计定位 `backend/services/worker_service.py` 和 `main.py`;现有 worker 测试只覆盖可及时退出场景,没有阻塞 handler 热重载测试。
|
||||
## 2026-07-23 鈥?鎻掍欢 iframe 鍘熺敓纭妗嗗悶鎺夊垹闄ゅ姩浣?
|
||||
|
||||
## 2026-07-22 — 最终审计验证与测试临时目录陷阱
|
||||
- 闃舵锛氬姛鑳戒慨澶?
|
||||
- 绫诲瀷锛氬姛鑳借涓?/ 鐜
|
||||
- 鐜拌薄锛氬垹闄ゆ寜閽偣鍑诲悗娌℃湁鍚庣瀹¤璁板綍锛岄〉闈篃娌℃湁鍒犻櫎缁撴灉銆?
|
||||
- 鏍瑰洜锛氳鑹插垹闄ゆ祦绋嬩緷璧?window.confirm锛汚strBot 鎻掍欢 iframe 鐨勫師鐢熺‘璁ゆ鍦ㄩ儴鍒嗚繍琛屾椂鍙兘涓嶆樉绀烘垨鐩存帴杩斿洖鍙栨秷锛屽鑷村嚱鏁板湪璇锋眰鍓嶉潤榛橀€€鍑恒€?
|
||||
- 淇鎴栬閬匡細鍒犻櫎鎿嶄綔涓嶅啀渚濊禆鍘熺敓纭妗嗭紝鐩存帴璋冪敤宸叉湁 POST profiles/{profile_id}/archive 杞垹闄ゆ帴鍙o紱鍚庣浠嶄繚鐣欐潈闄愩€佹墍鏈夎€呭拰瀹¤鏍¢獙銆?
|
||||
- 棰勯槻瑙勫垯锛氭彃浠?iframe 涓笉瑕佹妸鍏抽敭涓氬姟鍔ㄤ綔渚濊禆鍦?window.alert/confirm/prompt 涓婏紱闇€瑕佺‘璁ゆ椂浣跨敤搴旂敤鍐呭璇濇锛屾垨璁╁姩浣滃叿澶囨槑纭殑鍗曞嚮璇箟銆?
|
||||
- 楠岃瘉璇佹嵁锛歂AS 瀹¤鏌ヨ纭姝ゅ墠娌℃湁 delete_profile 鎴?update_profile 璁板綍锛涘墠绔慨鏀瑰悗闇€閲嶆柊鏋勫缓骞堕獙璇?POST 璇锋眰銆?
|
||||
|
||||
- 阶段:发布前最终审计
|
||||
- 类型:测试 / 环境
|
||||
- 现象:复用固定仓库内 `--basetemp` 运行全套测试时两次超时且残留 pytest 进程;不指定 basetemp 后全套正常完成。
|
||||
- 根因:Windows 环境下固定临时目录与残留测试进程/旧目录状态相互影响,且安静模式在长测试期间缺少进度输出,容易误判为代码死锁。
|
||||
- 修复或规避:终止本轮残留 pytest 进程,改用 pytest 默认唯一临时目录;对慢文件单独验证后重跑全套。
|
||||
- 预防规则:CI 为每次运行生成唯一 basetemp,并设置全局 timeout 和进度输出;测试超时时先查残留进程和单文件耗时,不要直接判定业务死锁。
|
||||
- 验证证据:`test_advanced_style_set_workflow.py` 46 passed in 31.39s;最终 `python -m pytest -q` 260 passed in 178.03s;前端 26 项契约、typecheck 和双构建均通过。
|
||||
|
||||
## 2026-07-23 — 公司电脑经 ZeroTier 访问后端超时
|
||||
## 2026-07-23 鈥?鏂囨湰瑙掕壊瀵煎叆鍏ュ彛钘忓湪闂嵎澶栧眰
|
||||
|
||||
- 阶段:网络排障
|
||||
- 类型:环境 / 网络 / 功能行为
|
||||
- 现象:家用电脑访问 ImageStudio 正常,公司电脑经 ZeroTier 访问时出现“后端连接 timeout”。
|
||||
- 根因:当前尚未拿到公司电脑的实际请求失败包;现有证据排除“NAS 端口未监听”和“插件进程完全未启动”,优先怀疑公司网络到 ZeroTier 网段的路由、ZeroTier flow rule/成员授权、Windows 防火墙或实际访问端口不一致。应用侧首屏 bootstrap 只等待 6 秒,插件 bridge GET 等待 15 秒,链路有丢包/中继延迟时会被前端表现为后端超时。
|
||||
- 修复或规避:先在公司电脑验证 ZeroTier IP 到实际映射端口 `26385` 的 TCP 连通性,并确认浏览器访问的地址不是旧端口 `6185`;若 TCP 不通,放行公司电脑到 NAS ZeroTier 地址 `10.147.17.231` 或 `172.24.141.75` 的对应端口并检查 ZeroTier 授权/Flow Rules;若 TCP 通但页面仍超时,再检查浏览器开发者工具中 `ui/bootstrap` 的请求、认证会话和响应耗时。
|
||||
- 预防规则:不要只用“页面能打开”判断后端链路正常;必须分别验证静态入口、`ui/bootstrap` API、实际容器映射端口和 ZeroTier path。区分 TCP timeout、HTTP 401/403、CORS 和应用 6 秒 bootstrap timeout 后再改代码。
|
||||
- 验证证据:NAS 路由存在 `10.147.17.0/24` 与 `172.24.0.0/16` ZeroTier 网段;`26385/26395/26399` 监听在 `0.0.0.0`;NAS 本机通过 `127.0.0.1`、`192.168.31.210`、`10.147.17.231`、`172.24.141.75` 访问 `26385` 均返回 HTTP 200;插件日志可见正常加载,但当前 NAS 日志版本为 `1.0.66`。项目代码中 bootstrap timeout 为 6 秒,bridge GET timeout 为 15 秒。
|
||||
## 2026-07-23 — 角色删除被示例来源判断静默拦截
|
||||
- 闃舵锛氬姛鑳戒紭鍖?
|
||||
- 绫诲瀷锛氬姛鑳借涓?/ UI
|
||||
- 鐜拌薄锛氬垱寤鸿鑹查棶鍗烽噷娌℃湁鐩存帴涓婁紶鏂囨湰璇嗗埆鍏ュ彛锛岀敤鎴峰彧鑳藉厛閫€鍑洪棶鍗峰啀浠庤鑹查〉瀵绘壘澶栭儴瑙掕壊鍗″鍏ャ€?
|
||||
- 鏍瑰洜锛氭枃鏈鍏ュ姛鑳藉凡瀹炵幇锛屼絾鍏ュ彛鍙斁鍦ㄥ伐浣滃彴鍔ㄤ綔鍗★紝鏈笌闂嵎濉啓娴佺▼鐩搁偦銆?
|
||||
- 淇鎴栬閬匡細鍦ㄩ棶鍗锋爣棰樻爮澧炲姞鈥滃鍏ユ枃鏈瘑鍒€濇寜閽紝澶嶇敤鐜版湁 `.txt/.md/.markdown` 涓婁紶銆佺矘璐淬€佹ā鍨嬭瘑鍒拰闂嵎鍥炲~娴佺▼銆?
|
||||
- 棰勯槻瑙勫垯锛氫笌褰撳墠缂栬緫琛ㄥ崟寮虹浉鍏崇殑瀵煎叆鑳藉姏搴旀斁鍦ㄨ〃鍗曟爣棰樻垨棣栧睆鎿嶄綔鍖猴紝涓嶅簲鍙緷璧栧灞傚伐浣滄祦鍗$墖銆?
|
||||
- 楠岃瘉璇佹嵁锛氬墠绔被鍨嬫鏌ュ拰鐢熶骇鏋勫缓閫氳繃鍚庯紝闇€纭鎸夐挳鎵撳紑澶栭儴瑙掕壊鍗¤瘑鍒眰骞惰嚜鍔ㄥ洖濉棶鍗枫€?
|
||||
|
||||
## 2026-07-24 鈥?闂嵎鏍囬鏍忔寜閽€夋嫨鍣ㄨ鍖归厤
|
||||
|
||||
- 闃舵锛氬姛鑳戒慨澶?- 绫诲瀷锛氱紪鐮?/ UI
|
||||
- 鐜拌薄锛氭柊澧炩€滃鍏ユ枃鏈瘑鍒€濆悗锛屾寜閽枃瀛楃珫鎺掑苟涓庡叧闂寜閽敊浣嶏紝娌℃湁鍑虹幇鍦ㄦ爣棰樻爮鍙充笂瑙掋€?- 鏍瑰洜锛歚.persona-questionnaire-card header > div` 鍚屾椂鍖归厤鏍囬鍐呭瀹瑰櫒鍜屽彸渚ф搷浣滃鍣紝瑕嗙洊浜嗘搷浣滃鍣ㄥ師鏈殑 `flex` 甯冨眬銆?- 淇鎴栬閬匡細灏嗘爣棰樺唴瀹归€夋嫨鍣ㄦ敹绐勪负 `.persona-questionnaire-card header > div:first-child`锛屼繚鐣欐搷浣滃鍣ㄧ殑妯悜 `flex` 甯冨眬銆?- 棰勯槻瑙勫垯锛氭柊澧炲祵濂楀竷灞€瀹瑰櫒鏃堕伩鍏嶄娇鐢ㄨ繃瀹界殑缁撴瀯閫夋嫨鍣紝妫€鏌ュ悓绾ф搷浣滃尯鏄惁琚户鎵垮竷灞€瑙勫垯瑕嗙洊銆?- 楠岃瘉璇佹嵁锛歚npm.cmd run typecheck`銆乣npm.cmd run build`銆乣git diff --check` 閫氳繃锛涙彁浜?`2dbf90b` 宸叉帹閫侊紱NAS 瀹瑰櫒鍔犺浇 `astrbot_plugin_imagestudio (1.0.66)`锛岃繙绔簮鐮佸寘鍚敹绐勫悗鐨勯€夋嫨鍣紝鏃ф彃浠跺凡澶囦唤銆?
|
||||
|
||||
## 2026-07-24 鈥?瀵煎叆鎸夐挳搴斾綅浜庨棶鍗峰簳閮ㄦ搷浣滃尯
|
||||
|
||||
- 闃舵锛氬姛鑳戒慨澶?- 绫诲瀷锛氬姛鑳借涓?/ UI
|
||||
- 鐜拌薄锛氭寜閽鏀惧湪闂嵎鏍囬鏍忓叧闂寜閽梺杈癸紝涓旂獎瀹藉害涓嬧€滃鍏ユ枃鏈瘑鍒€濈珫鎺掞紱鐢ㄦ埛瀹為檯闇€瑕佸畠浣嶄簬搴曢儴鈥滅畝鍗曢棶鍗?/ 澶嶆潅闂嵎鈥濇寜閽乏渚с€?- 鏍瑰洜锛氶娆″疄鐜板彧渚濇嵁鏍囬鏍忚涔夋斁缃寜閽紝娌℃湁瀵圭収闂嵎搴曢儴鎿嶄綔鍖虹殑瑙嗚鏍囪锛涙寜閽己灏戜笉鎹㈣鍜屾渶灏忓搴︾害鏉熴€?- 淇鎴栬閬匡細绉婚櫎鏍囬鏍忓鍏ユ寜閽紝灏嗗叾鏀惧叆 `.persona-questionnaire-footer-actions`锛岄『搴忎负瀵煎叆銆侀棶鍗锋ā寮忋€佺敓鎴愭。妗堬紝骞跺鍔?`white-space: nowrap` 涓?`min-width`銆?- 棰勯槻瑙勫垯锛氭秹鍙婃埅鍥惧畾浣嶇殑 UI 淇敼蹇呴』浠ョ敤鎴锋爣璁扮殑瀹為檯瀹瑰櫒涓哄噯锛屽苟鍦ㄦ闈笌绐勫睆甯冨眬妫€鏌ユ寜閽枃瀛楁槸鍚︽崲琛屻€?- 楠岃瘉璇佹嵁锛歚npm.cmd run typecheck`銆乣npm.cmd run build`銆乣git diff --check` 閫氳繃锛涙彁浜?`878f1f6` 宸叉帹閫侊紱NAS 瀹瑰櫒鍔犺浇 `1.0.66`锛岃繙绔簮鐮佺‘璁ゅ鍏ユ寜閽綅浜?footer锛屾爣棰樻爮浠呬繚鐣欏叧闂寜閽€?
|
||||
|
||||
## 2026-07-23 鈥?瑙掕壊宸ヤ綔娴佺粺璁″尯鎸ゅ崰鎷嗚В绌洪棿
|
||||
|
||||
- 闃舵锛氬姛鑳戒紭鍖?- 绫诲瀷锛歎I / 鍔熻兘琛屼负
|
||||
- 鐜拌薄锛氳鑹插伐浣滄祦椤堕儴鍥涗釜缁熻鍗$墖鍗犳嵁鍨傜洿绌洪棿锛屾媶瑙h瀹氬尯鍩熷亸灏忥紱鎷嗚В瀛楁鍙兘鏌ョ湅锛岃皟鏁磋瀹氶渶瑕佸洖鍒板墠缃〃鍗曘€?- 鏍瑰洜锛氬伐浣滄祦妯℃澘灏嗛€氱敤 `generateStatusCards` 鍥哄畾娓叉煋鍦ㄨ鑹插伐浣滄祦涓婃柟锛涙媶瑙h妭鐐瑰瓧娈垫病鏈夋彁渚涚紪杈戞€佸拰鎸佷箙鍖栧叆鍙c€?- 淇鎴栬閬匡細绉婚櫎瑙掕壊宸ヤ綔娴侀《閮ㄧ粺璁″崱鐗囷紝澧炲ぇ涓诲伐浣滃尯楂樺害锛涙媶瑙e瓧娈靛鍔犲唴鑱旂紪杈戙€佷繚瀛?鍙栨秷锛屽苟灏嗘。妗堝瓧娈靛啓鍥?profile metadata锛岃妭鐐瑰瓧娈靛啓鍥炲伐浣滄祦鑺傜偣銆?- 棰勯槻瑙勫垯锛氬伐浣滄祦涓绘搷浣滃尯浼樺厛淇濋殰鍐呭缂栬緫绌洪棿锛涘睍绀哄瀷缁熻鍗$墖涓嶈兘鎸ゅ帇鏍稿績鑺傜偣鍐呭锛涚紪杈?UI 蹇呴』鍚屾椂鏄庣‘淇濆瓨鐩爣鍜屽洖鍐欏绾︺€?- 楠岃瘉璇佹嵁锛歚npm.cmd run typecheck`銆乣npm.cmd run build`銆乣git diff --check` 閫氳繃锛涘綋鍓嶅伐浣滄爲宸叉墦鍖呴儴缃?NAS锛屽鍣ㄥ姞杞?`astrbot_plugin_imagestudio (1.0.66)`锛岃繙绔‘璁ょ粺璁″崱鐗囦笉鍐嶆覆鏌撲笖鎷嗚В瀛楁缂栬緫閫昏緫瀛樺湪銆?
|
||||
|
||||
## 2026-07-24 — 工作流素材绑定入口未区分规划节点
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:功能行为 / UI
|
||||
- 现象:角色工作流的“参考素材绑定”节点点击右侧“素材”操作后,无法稳定打开素材库。
|
||||
- 根因:操作卡片只依赖通用 `nav/module` 回退路径,没有声明工作流专用动作;同时当前 `material_bind` 是 `reference_binding` 规划节点,不能误走仅支持详细图像生成节点的节点素材抽屉接口。
|
||||
- 修复或规避:新增 `workflowMaterialLibrary` 动作,点击后复用快速角色已有的分类素材卡片弹层并自动定位到风格卡片;图像生成节点仍保留节点素材抽屉路径。
|
||||
- 预防规则:工作流操作卡片必须声明语义动作;规划节点与图像生成节点的素材入口不能共用未校验的抽屉接口。
|
||||
- 验证证据:入口改为快速角色式弹层;待执行 `npm.cmd run typecheck`、`npm.cmd run build` 和 `git diff --check`。
|
||||
|
||||
## 2026-07-24 — 素材类别弹层被卡片裁剪
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:UI / 功能行为
|
||||
- 现象:点击风格、构图、服装、鞋袜或配饰卡片后,类别选择逻辑已触发但用户看不到素材选项。
|
||||
- 根因:`workflow-material-bind-card` 使用 `overflow: hidden`,绝对定位的快速角色式素材选择弹层被父卡片裁剪;卡片之间也没有为打开中的弹层提升层级。
|
||||
- 修复或规避:卡片改为允许溢出,打开中的卡片提升 `z-index`,工作流弹层改为在卡片下方展开,直接复用现有类别选择与保存逻辑。
|
||||
- 预防规则:新增绝对定位弹层时必须同时检查所有祖先的 overflow、滚动容器边界和相邻卡片层级。
|
||||
- 验证证据:待执行前端类型检查、生产构建、差异检查及 NAS 重启后的实际资源校验。
|
||||
## 2026-07-24 — 工作流素材弹层被相邻卡片遮挡
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:UI / 功能行为
|
||||
- 现象:类别弹层虽然打开,但显示在下一张卡片上方,素材选项主体不可见。
|
||||
- 根因:弹层仍处于工作流网格和滚动容器的定位上下文中,绝对定位内容受到网格相邻项和滚动边界影响。
|
||||
- 修复或规避:工作流专用素材弹层改为固定定位并居中显示,提升到独立层级,保留快速角色的类别筛选、清空、选择和新增逻辑。
|
||||
- 预防规则:跨卡片选择器不要依赖网格项内的绝对定位;需要完整显示时使用独立浮层定位。
|
||||
- 验证证据:待执行前端类型检查、生产构建、差异检查及 NAS 重启后的资源校验。
|
||||
## 2026-07-24 — 素材弹层需要按视口智能换向
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:UI / 响应式布局
|
||||
- 现象:统一向上展开时,顶部类别卡片的素材弹层会被工作流标题区遮挡。
|
||||
- 根因:弹层方向固定,没有根据当前卡片在视口中的上下剩余空间选择展开方向。
|
||||
- 修复或规避:点击时测量当前卡片上下空间;顶部或下方空间更充足时向下展开,底部空间不足时向上展开,并分别处理左右列对齐。
|
||||
- 预防规则:浮层定位不能只按固定方向,必须根据触发元素的视口位置和可用空间动态决定。
|
||||
- 验证证据:待执行前端类型检查、生产构建、差异检查及 NAS 重启后的资源校验。
|
||||
## 2026-07-24 — 生成入队后预览区空白
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:UI / 功能行为
|
||||
- 现象:点击工作流生成后,右侧提示已加入队列,但中央预览区立即回到“等待节点结果”,用户无法判断任务是否仍在处理。
|
||||
- 根因:`workflowNodeActionExecuting` 只覆盖提交请求本身;入队接口返回后该状态立即清零,而后台图片仍需异步生成,预览模板没有节点级 pending 状态。
|
||||
- 修复或规避:新增 `workflowPendingGenerationByNodeId`;普通节点和轮次节点入队时置 pending,真实图片加载或明确失败/终态时清除;预览区优先显示带动效的“正在生成”占位图。
|
||||
- 预防规则:异步生成 UI 不要把“提交请求完成”当作“媒体结果完成”;必须将提交、队列处理、结果可用拆成独立状态,并为失败终态提供收口路径。
|
||||
- 验证证据:待执行前端类型检查、生产构建、差异检查及 NAS 部署后的资源字符串核验。
|
||||
|
||||
## 2026-07-24 — LLM 调整未自动进入下一轮
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:功能行为 / API契约
|
||||
- 现象:角色详情页点击“删除”无确认弹窗、无请求、页面角色不消失。
|
||||
- 根因:前端删除函数额外判断 `profile.metadata.source === "sample"` 后直接返回;该判断没有错误提示,也与后端已授权角色软删除接口的能力边界不一致,导致用户可见角色被静默当作不可删除示例处理。
|
||||
- 修复或规避:删除流程只保留角色存在、未处于删除中和后端写权限检查;移除删除专用的 `sample` 静默拦截。示例角色的生成、工作流和素材编辑限制保持不变。
|
||||
- 预防规则:前端禁止操作必须有明确 UI 状态或错误提示;不要在单个操作中复用与其他操作不同的 `sample` 保护条件,先对照后端路由权限和资源生命周期。
|
||||
- 验证证据:已修改 `frontend/standalone-web/src/App.vue:6241`;前端 `vue-tsc --noEmit` 通过;契约测试 26/26 通过;`git diff --check` 通过。
|
||||
- 现象:轮次反馈接口只保存 LLM 调整,用户还必须点击“开始下一轮”;当前轮次没有自动封存,下一批候选不会自动生成。
|
||||
- 根因:前端对话入口和现有 `rounds/{round_id}/feedback`、`rounds/{round_id}/next` 接口是串行断开的;手动入口另有一套调用路径。
|
||||
- 修复或规避:LLM 调整成功识别到喜欢候选后复用现有反馈接口和下一轮接口自动创建子轮次;后端创建子轮次后将父轮次标记为 `superseded`,前端自动切换并开始轮询子轮次。
|
||||
- 预防规则:手动下一轮和自然语言调整必须复用同一轮次创建接口;父轮次只有在子轮次创建成功后才封存,重复提交必须使用稳定幂等键。
|
||||
- 验证证据:轮次回归测试断言父轮次为 `superseded`;前端类型检查和构建待执行。
|
||||
|
||||
## 2026-07-23 — NAS 部署路径与容器重启边界
|
||||
## 2026-07-24 ? Workflow avatar preview and detail panel layout
|
||||
|
||||
- 阶段:部署
|
||||
- 类型:部署 / 环境
|
||||
- 现象:首次部署校验失败是插件目录拼写错误;随后在容器内执行 `docker restart` 导致执行 shell 被 `context canceled` 终止,旧 staging 目录短暂留在插件扫描目录并被 AstrBot 当作第二个插件加载。
|
||||
- 根因:实际目录是 `astrbot_plugin_imagestudio`,不是 `astrabot_plugin_imagestudio`;容器内重启自身会立即杀掉当前 exec;AstrBot 会扫描 `data/plugins` 下所有目录,旧目录不能用改名方式留在那里。
|
||||
- 修复或规避:改用正确目录名;旧目录移入 `/AstrBot/data/plugin_backups`;重启必须由 NAS 宿主机执行;部署包先做 SHA-256 校验再替换。
|
||||
- 预防规则:部署脚本必须先验证目标目录存在;禁止在目标容器内部重启自身;插件旧版本只允许放在 `plugin_backups`,不得留在 `data/plugins`。
|
||||
- 验证证据:NAS 容器 `Up`;日志只加载一个 `astrbot_plugin_imagestudio (1.0.66)`;插件 metadata 为 `1.0.66`;`frontend/standalone-web/src/App.vue:6241` 删除修复标记存在;容器状态为已知的 `health: starting`。
|
||||
## 2026-07-23 — 插件桥接不支持角色删除 DELETE
|
||||
- Phase: feature fix
|
||||
- Type: UI / behavior
|
||||
- Symptom: The headshot node had four generated images but the main preview was empty; the right detail panel consumed space and the LLM adjustment window was not near the main preview.
|
||||
- Root cause: The non-round preview pool applied a second workflow_id filter to node images, while older API payloads could omit or mismatch workflow_id; the LLM component was outside the three-column workspace.
|
||||
- Fix or workaround: Resolve the preview pool from the selected node image cache; remove the right detail panel and place workflow actions plus the node-bound LLM window inside the main preview.
|
||||
- Prevention rule: Node-level result display should rely on the node_id result set and not re-filter on optional workflow_id; workflow controls should remain in the same visible area as their preview.
|
||||
- Validation evidence: npm.cmd run typecheck and git diff --check passed; NAS asset verification follows after build.
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:API契约 / 功能行为
|
||||
- 现象:角色详情页删除按钮仍无效;前端在插件 iframe 中调用 DELETE,但部分 AstrBot Plugin Page bridge 只暴露 `apiPost`,请求回退到未注册的 method override 路径。
|
||||
- 根因:后端只注册 `DELETE profiles/{profile_id}`,没有给桥接层提供稳定的 POST 删除入口;DELETE 能力是否暴露取决于 AstrBot 版本和运行时 bridge 实现。
|
||||
- 修复或规避:新增 `POST profiles/{profile_id}/delete`,复用原有所有者校验、软删除和审计逻辑;前端角色删除统一调用该 POST 入口,保留原 DELETE 接口兼容外部调用。
|
||||
- 预防规则:插件 iframe 内的写操作优先提供明确的 POST 动作路由;不能假定 `apiPut`、`apiPatch` 或 `apiDelete` 在所有 AstrBot 版本都存在。
|
||||
- 验证证据:删除 POST 路由回归测试通过;前端类型检查通过;插件页与 standalone web 构建通过。
|
||||
## 2026-07-24 ? Workflow seven-node layout and plugin media fallback
|
||||
|
||||
## 2026-07-23 — 插件 iframe 原生确认框吞掉删除动作
|
||||
- Phase: frontend restructure
|
||||
- Type: UI / media behavior
|
||||
- Symptom: The deployed workflow still presented an unclear three-column layout, while generated images and the node-bound LLM were not visible in the expected regions.
|
||||
- Root cause: The workflow grouped several major stages together, the action/detail/composer regions were not expressed as a stable layout contract, and plugin-page image rendering returned an empty source while signed media Blob resolution was pending.
|
||||
- Fix or workaround: Define seven major workflow groups, render explicit node-flow/main-preview/action/LLM/info regions, retain signed URLs during Blob resolution, and bind non-round previews to the selected node cache.
|
||||
- Prevention rule: Treat workflow regions as a layout contract and test plugin-page media rendering separately from direct standalone rendering.
|
||||
- Validation evidence: vue-tsc typecheck passed; build and NAS deployment follow in this phase.
|
||||
|
||||
- 阶段:功能修复
|
||||
## 2026-07-24 — 工作流图片与旧节点详情残留
|
||||
|
||||
- 阶段:功能开发 / 部署
|
||||
- 类型:功能行为 / 环境
|
||||
- 现象:删除按钮点击后没有后端审计记录,页面也没有删除结果。
|
||||
- 根因:角色删除流程依赖 window.confirm;AstrBot 插件 iframe 的原生确认框在部分运行时可能不显示或直接返回取消,导致函数在请求前静默退出。
|
||||
- 修复或规避:删除操作不再依赖原生确认框,直接调用已有 POST profiles/{profile_id}/archive 软删除接口;后端仍保留权限、所有者和审计校验。
|
||||
- 预防规则:插件 iframe 中不要把关键业务动作依赖在 window.alert/confirm/prompt 上;需要确认时使用应用内对话框,或让动作具备明确的单击语义。
|
||||
- 验证证据:NAS 审计查询确认此前没有 delete_profile 或 update_profile 记录;前端修改后需重新构建并验证 POST 请求。
|
||||
- 现象:插件页仍可能显示旧三栏工作流;生成结果使用 storage:// 或仅有 image_uri 时,候选卡片和主预览为空。
|
||||
- 根因:浏览器缓存旧构建资源;前端只解析签名 URL,没有把存储 URI 统一签名并通过插件桥接转 Blob。
|
||||
- 修复或规避:工作流改为七大节点、主预览下方固定 LLM、右侧只保留操作;图片解析覆盖 URI/签名/Blob 三种路径。
|
||||
- 预防规则:每次前端修改递增插件版本并强制刷新;图片组件必须同时覆盖 *_url 和 *_uri。
|
||||
- 验证证据:本地 typecheck/build 通过;NAS 已切换 1.0.69,容器重启后日志确认插件加载,备份目录已创建。
|
||||
|
||||
## 2026-07-24 — 插件页工作流断点与 storage 图片回退
|
||||
|
||||
- 阶段:前端修复 / 部署
|
||||
- 类型:编码 / UI / 媒体行为
|
||||
- 现象:NAS 插件 iframe 误触发 900px 单列断点,三栏工作区被挤成纵向;候选审查弹窗仍可能直接收到 storage://,图片空白。
|
||||
- 根因:插件 iframe 的 CSS viewport 与物理窗口宽度不同;审查弹窗没有复用父组件的 storage URI 解析结果。
|
||||
- 修复或规避:将三栏布局断点下移到 760px,固定 nodes/main/side 区域;为审查候选增加统一 displayMediaUrl 映射,并过滤不可直接渲染的 storage://。
|
||||
- 预防规则:插件页必须按 iframe viewport 验证响应式断点;所有图片组件同时覆盖 *_url、*_uri 和 Blob 解析完成前的空状态。
|
||||
- 验证证据:frontend typecheck/build 通过;待部署后确认 NAS 加载 1.0.70 与新资源 hash。
|
||||
|
||||
## 2026-07-24 — 1.0.70 三栏修复未覆盖响应式规则
|
||||
|
||||
- 阶段:部署复核
|
||||
- 类型:UI / 部署
|
||||
- 现象:NAS 已加载新资源 hash,但工作流截图仍是节点流独占一整行,主预览和操作区被推到下方。
|
||||
- 根因:1.0.70 只调整了中间断点,后续响应式规则仍可将 workflow-layout 改成单列或两列;节点、主列、侧列也没有在基础样式中明确绑定 grid-area。
|
||||
- 修复或规避:1.0.71 在样式末尾强制三列和 nodes/main/side 区域绑定,窄屏仅压缩列宽,不再切换为单列。
|
||||
- 预防规则:工作流布局覆盖规则必须放在所有通用响应式规则之后,并用真实插件 iframe viewport 验证,而不是只看桌面物理宽度。
|
||||
- 验证证据:1.0.71 typecheck/build 通过;NAS metadata、HTML hash、CSS 构建资源和 AstrBot 加载日志均已确认。
|
||||
|
||||
## 2026-07-24 — 头像预览回退与阶段硬约束
|
||||
|
||||
- 阶段:前端 / 后端算法
|
||||
- 类型:功能行为 / API契约
|
||||
- 现象:头像节点显示 4 个候选计数但主预览为空,LLM 只剩底部细条;图库中的头像批次被模型生成成设定图构图。
|
||||
- 根因:round 候选池条件成立但详情没有候选时,旧节点图片候选池被隐藏;LLM 容器没有最小高度;头像节点只继承通用提示词,没有服务端阶段边界。
|
||||
- 修复或规避:无有效 round 候选时回退节点图片;主列和 LLM 设置最小高度;服务端对 headshot 追加头像专属正负约束和 1:1 约束。
|
||||
- 预防规则:工作流每个阶段必须有“round 候选→节点图片→空状态”的明确回退链;视觉阶段约束必须在服务端提示词快照中追加,不能只依赖前端。
|
||||
- 验证证据:新增 prompt expansion 单测;待 typecheck、pytest、build 和 NAS 1.0.72 验证。
|
||||
|
||||
|
||||
## 2026-07-23 — 文本角色导入入口藏在问卷外层
|
||||
## 2026-07-27 — Frozen ApiError breaks context-manager error handling
|
||||
|
||||
- 阶段:功能优化
|
||||
- 类型:功能行为 / UI
|
||||
- 现象:创建角色问卷里没有直接上传文本识别入口,用户只能先退出问卷再从角色页寻找外部角色卡导入。
|
||||
- 根因:文本导入功能已实现,但入口只放在工作台动作卡,未与问卷填写流程相邻。
|
||||
- 修复或规避:在问卷标题栏增加“导入文本识别”按钮,复用现有 `.txt/.md/.markdown` 上传、粘贴、模型识别和问卷回填流程。
|
||||
- 预防规则:与当前编辑表单强相关的导入能力应放在表单标题或首屏操作区,不应只依赖外层工作流卡片。
|
||||
- 验证证据:前端类型检查和生产构建通过后,需确认按钮打开外部角色卡识别层并自动回填问卷。
|
||||
- 阶段:阶段 2 正确性与发布收口
|
||||
- 类型:API契约 / 编码
|
||||
- 现象:在 `@contextmanager` 中抛出 `ApiError` 时,Python 尝试回写异常链字段,原始错误被 `FrozenInstanceError` 替换,调用方丢失错误码和消息。
|
||||
- 根因:`ApiError` 被声明为 frozen dataclass;异常对象并不适合冻结,因为运行时需要维护异常上下文。
|
||||
- 修复或规避:解除 `ApiError` 的 frozen 限制,并修复 `str(exc)` 的元组表示。
|
||||
- 预防规则:异常类型不得声明为 frozen;新增异常类型时必须覆盖直接抛出和 context-manager 传播两条路径。
|
||||
- 验证证据:后端全量测试通过;配置写入与路由错误封装回归测试通过。
|
||||
|
||||
## 2026-07-24 — 问卷标题栏按钮选择器误匹配
|
||||
## 2026-07-27 — PostgreSQL placeholder refactor missed list path
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:编码 / UI
|
||||
- 现象:新增“导入文本识别”后,按钮文字竖排并与关闭按钮错位,没有出现在标题栏右上角。
|
||||
- 根因:`.persona-questionnaire-card header > div` 同时匹配标题内容容器和右侧操作容器,覆盖了操作容器原本的 `flex` 布局。
|
||||
- 修复或规避:将标题内容选择器收窄为 `.persona-questionnaire-card header > div:first-child`,保留操作容器的横向 `flex` 布局。
|
||||
- 预防规则:新增嵌套布局容器时避免使用过宽的结构选择器,检查同级操作区是否被继承布局规则覆盖。
|
||||
- 验证证据:`npm.cmd run typecheck`、`npm.cmd run build`、`git diff --check` 通过;提交 `2dbf90b` 已推送;NAS 容器加载 `astrbot_plugin_imagestudio (1.0.66)`,远端源码包含收窄后的选择器,旧插件已备份。
|
||||
- 阶段:阶段 2 正确性与发布收口
|
||||
- 类型:编码 / 测试
|
||||
- 现象:PostgreSQL `%` 占位符修复遗漏 `list_profiles` 的绑定,运行时会触发 `NameError`;既有测试未断言 `list()` 成功,且请求包装层曾吞掉底层异常。
|
||||
- 根因:批量脚本化改写只覆盖了主查询路径,测试只验证错误信封而未验证仓储成功返回。
|
||||
- 修复或规避:补齐 `list_profiles` 绑定,新增直接成功路径测试及所有同类插值点扫描测试。
|
||||
- 预防规则:批量数据库方言改写后,必须枚举每个 CRUD 入口并同时测试成功结果和异常传播;不可只测试统一错误外壳。
|
||||
- 验证证据:新增 PostgreSQL 字面量与请求异常回归测试通过,后端全量测试通过。
|
||||
|
||||
## 2026-07-24 — 导入按钮应位于问卷底部操作区
|
||||
## 2026-07-27 — Release archive must name and package the same ref
|
||||
|
||||
- 阶段:功能修复
|
||||
- 类型:功能行为 / UI
|
||||
- 现象:按钮被放在问卷标题栏关闭按钮旁边,且窄宽度下“导入文本识别”竖排;用户实际需要它位于底部“简单问卷 / 复杂问卷”按钮左侧。
|
||||
- 根因:首次实现只依据标题栏语义放置按钮,没有对照问卷底部操作区的视觉标记;按钮缺少不换行和最小宽度约束。
|
||||
- 修复或规避:移除标题栏导入按钮,将其放入 `.persona-questionnaire-footer-actions`,顺序为导入、问卷模式、生成档案,并增加 `white-space: nowrap` 与 `min-width`。
|
||||
- 预防规则:涉及截图定位的 UI 修改必须以用户标记的实际容器为准,并在桌面与窄屏布局检查按钮文字是否换行。
|
||||
- 验证证据:`npm.cmd run typecheck`、`npm.cmd run build`、`git diff --check` 通过;提交 `878f1f6` 已推送;NAS 容器加载 `1.0.66`,远端源码确认导入按钮位于 footer,标题栏仅保留关闭按钮。
|
||||
- 阶段:阶段 0 泄漏止血与发布收口
|
||||
- 类型:发布 / 环境
|
||||
- 现象:打包脚本按 `$REF` 归档,却可能以当前 dirty HEAD 的描述命名,导致包名和包内容无法一一对应。
|
||||
- 根因:`git describe` 未接收 `$REF`,并允许从含未提交 tracked 改动的 HEAD 发包。
|
||||
- 修复或规避:版本描述改为从 `$REF` 推导;默认 HEAD 有 tracked 改动时拒绝打包,要求先提交或传入显式 SHA/tag。
|
||||
- 预防规则:发布产物必须由精确 commit 或 tag 构造;产物名、审计记录和部署 SHA 必须相同。
|
||||
- 验证证据:`scripts/package_plugin.sh` 使用 `git archive` 打包指定 ref,并保留秘密路径和必需前端入口断言。
|
||||
|
||||
|
||||
## 2026-07-27 — Git archive entry separators differ on Windows
|
||||
|
||||
- 阶段:阶段 0 泄漏止血与发布收口
|
||||
- 类型:发布 / 环境
|
||||
- 现象:Windows 上从 Git Bash 生成的 tar.gz 实际包含必需入口,但脚本用正斜杠精确匹配时误判 `metadata.yaml` 缺失并删除归档。
|
||||
- 根因:Git for Windows 在归档条目中使用反斜杠,而脚本的安全和必需文件断言只识别正斜杠。
|
||||
- 修复或规避:在所有归档路径断言前统一把反斜杠转换为正斜杠;同一规范同时覆盖秘密路径和必需入口。
|
||||
- 预防规则:跨平台归档校验必须在比较前规范化路径分隔符,并在 Windows Git Bash 与 POSIX shell 各执行一次。
|
||||
- 验证证据:`v1.0.73` 归档通过必需入口、秘密路径和 SHA-256 检查。
|
||||
|
|
|
|||
4
frontend/package-lock.json
自动生成
4
frontend/package-lock.json
自动生成
|
|
@ -1,12 +1,12 @@
|
|||
{
|
||||
"name": "astrbot-plugin-imagestudio-frontend",
|
||||
"version": "1.0.66",
|
||||
"version": "1.0.73",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "astrbot-plugin-imagestudio-frontend",
|
||||
"version": "1.0.66",
|
||||
"version": "1.0.73",
|
||||
"dependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"pinia": "^2.3.0",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "astrbot-plugin-imagestudio-frontend",
|
||||
"version": "1.0.66",
|
||||
"version": "1.0.73",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ name: astrbot_plugin_imagestudio
|
|||
display_name: ImageStudio
|
||||
desc: AstrBot >=4.25 ImageStudio role asset and image-generation workspace for Windows, Linux, macOS and Docker.
|
||||
short_desc: AstrBot 鍐呯殑瑙掕壊璧勪骇銆佸伐浣滄祦涓庡浘鐗囩敓鎴愮鐞嗗伐浣滃彴銆?
|
||||
version: 1.0.66
|
||||
version: 1.0.73
|
||||
author: YokiiroBW
|
||||
repo: "http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_imagestudio"
|
||||
astrbot_version: ">=4.25.0,<5"
|
||||
|
|
|
|||
68
scripts/package_plugin.sh
普通文件
68
scripts/package_plugin.sh
普通文件
|
|
@ -0,0 +1,68 @@
|
|||
#!/usr/bin/env bash
|
||||
# Build a distributable plugin archive from the *git* view of the tree.
|
||||
#
|
||||
# Why git archive instead of copying the working directory:
|
||||
# The previous deploy scripts copied the whole folder, which swept up
|
||||
# .env.imagestudio_codex_handoff.yaml (real API keys, DB password, admin
|
||||
# credentials) into 19 published archives. .gitignore has no effect on a
|
||||
# plain `cp -r`, but `git archive` only ever emits tracked files, so an
|
||||
# ignored secret can no longer reach a package by construction.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/package_plugin.sh [ref] [outdir]
|
||||
# Defaults: ref=HEAD, outdir=dist
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Git for Windows may invoke this script from PowerShell with a PATH that omits
|
||||
# its Unix core utilities. Restore them so git archive verification remains
|
||||
# portable between Git Bash, PowerShell, and POSIX hosts.
|
||||
if [[ -d /usr/bin ]]; then
|
||||
PATH="/usr/bin:/bin:$PATH"
|
||||
fi
|
||||
|
||||
REF="${1:-HEAD}"
|
||||
OUTDIR="${2:-dist}"
|
||||
PREFIX="astrbot_plugin_imagestudio/"
|
||||
|
||||
repo_root="$(git rev-parse --show-toplevel)"
|
||||
cd "$repo_root"
|
||||
|
||||
if [[ "$REF" == "HEAD" ]] && { ! git diff --quiet || ! git diff --cached --quiet; }; then
|
||||
echo "FATAL: HEAD has uncommitted tracked changes; commit first or pass an explicit ref." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
version="$(git describe --tags --always "$REF" 2>/dev/null || git rev-parse --short "$REF")"
|
||||
mkdir -p "$OUTDIR"
|
||||
archive="$OUTDIR/astrbot_plugin_imagestudio-$version.tar.gz"
|
||||
|
||||
git archive --format=tar.gz --prefix="$PREFIX" -o "$archive" "$REF"
|
||||
|
||||
# Git for Windows writes backslashes in git archive entries. Normalize the
|
||||
# listing once so security and required-file assertions behave identically on
|
||||
# Windows and POSIX hosts.
|
||||
archive_paths() {
|
||||
tar -tzf "$archive" | tr '\\' '/'
|
||||
}
|
||||
|
||||
# Hard assertion: refuse to publish an archive that carries a secret-bearing
|
||||
# file. This is the backstop that would have caught the 2026-07 leak.
|
||||
if archive_paths | grep -nE '(^|/)(\.env|.*\.pem$|.*\.p12$|.*id_rsa.*|secrets?\.ya?ml)' ; then
|
||||
echo "FATAL: secret-bearing path found in $archive — refusing to publish." >&2
|
||||
rm -f "$archive"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# The plugin is unusable without the built frontend; these are tracked on
|
||||
# purpose (AstrBot loads them from the package, there is no build step on the
|
||||
# host). Fail loudly if they went missing rather than shipping a broken plugin.
|
||||
for required in "${PREFIX}metadata.yaml" "${PREFIX}main.py" "${PREFIX}web/index.html" "${PREFIX}pages/imagestudio/index.html"; do
|
||||
if ! archive_paths | grep -qx "$required"; then
|
||||
echo "FATAL: $required missing from $archive — frontend not built?" >&2
|
||||
rm -f "$archive"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
echo "$archive"
|
||||
202
审计/01-总览与架构.md
普通文件
202
审计/01-总览与架构.md
普通文件
|
|
@ -0,0 +1,202 @@
|
|||
# 01 · 总览与架构
|
||||
|
||||
> 审计对象:`AstrBot ImageStudio` 插件仓库
|
||||
> 分支:`codex/character-profile-document-import` @ `8040a1b`
|
||||
> 审计日期:2026-07-27
|
||||
> 排除范围:`.tmp/`、`.tmp_pytest_*`、`node_modules/`、`__pycache__/`、构建产物
|
||||
|
||||
---
|
||||
|
||||
## 1. 规模统计
|
||||
|
||||
### 1.1 代码体量
|
||||
|
||||
| 层 | 文件数 | 行数 | 备注 |
|
||||
|---|---:|---:|---|
|
||||
| `main.py` | 1 | **2,580** | 插件入口 + 全部聊天命令 |
|
||||
| `backend/services/` | 70 | 36,736(含 routes/dto) | 业务层 |
|
||||
| `backend/routes/` | 35 | — | HTTP 路由层 |
|
||||
| `backend/dto/` | 13 | — | 数据传输对象 |
|
||||
| `database/` | 15 repo + models + 18 migration | 9,805 | 数据层 |
|
||||
| `core/` | 23 | 2,494 | 横切基础设施 |
|
||||
| `engines/` | 8 | 2,026 | 模型调用流程 |
|
||||
| `adapters/` | 10 | 910 | 平台适配(AstrBot/OneBot11/WeChat/WebUI) |
|
||||
| **后端小计** | **223** | **~64,100** | |
|
||||
| `frontend/` | 85 | **39,254** | Vue3 + TS |
|
||||
| `tests/` | 45 | 11,559 | pytest |
|
||||
| **总计** | **~350** | **~115,000** | |
|
||||
|
||||
### 1.2 关键"巨石"文件
|
||||
|
||||
| 文件 | 行数 | 性质 |
|
||||
|---|---:|---|
|
||||
| `frontend/standalone-web/src/App.vue` | **22,563** | 单文件组件,全仓最大 |
|
||||
| `backend/services/advanced_style_set_service.py` | **4,491** | 后端最大 service |
|
||||
| `main.py` | 2,580 | 插件入口 |
|
||||
| `backend/services/generation_service.py` | 2,432 | |
|
||||
| `database/repositories/advanced_material_repository.py` | 2,123 | |
|
||||
| `frontend/.../AdvancedMaterialImportPage.vue` | 2,024 | |
|
||||
| `backend/services/advanced_material_service.py` | 1,856 | |
|
||||
| `backend/services/workflow_round_service.py` | 1,596 | |
|
||||
| `database/repositories/workflow_cross_review_repository.py` | 1,467 | |
|
||||
| `database/repositories/workflow_round_repository.py` | 1,381 | |
|
||||
|
||||
**`App.vue` 内部构成**(22,563 行):
|
||||
|
||||
| 区段 | 行号 | 行数 | 占比 |
|
||||
|---|---|---:|---:|
|
||||
| `<script setup>` | 1–11,357 | 11,356 | 50.3% |
|
||||
| `<template>` | 11,359–14,143 | 2,784 | 12.3% |
|
||||
| `<style>` | 14,145–22,540 | **8,395** | **37.2%** |
|
||||
|
||||
script 段内含(**两种口径并列,后续报告一律以「声明式计数」为准**):
|
||||
|
||||
| 指标 | 字面量计数(`grep -o`) | 声明式计数(`= ref(` / `= computed(`,含 `ref<T>(`) |
|
||||
|---|---:|---:|
|
||||
| `ref` | 133 | **206** |
|
||||
| `computed` | 135 | **203** |
|
||||
|
||||
另:`watch(` × 20、顶层函数定义 × 365、`endpoints.` 引用 × **183**(`grep -o "endpoints\." \| wc -l` 实测)。
|
||||
|
||||
> ⚠️ 本表两列的差异来自 `ref<Type>(...)` 这类带泛型参数的写法不含 `ref(` 子串。04 报告的 206/203 与本表第二列一致;若见到 133/135 请理解为字面量口径。
|
||||
|
||||
---
|
||||
|
||||
## 2. 架构分层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 接入层 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │
|
||||
│ │ main.py │ │ adapters/ │ │ frontend/ │ │
|
||||
│ │ 聊天命令 ×77 │ │ AstrBot │ │ standalone-web │ │
|
||||
│ │ (+38 短别名) │ │ OneBot11 │ │ plugin-page │ │
|
||||
│ │ │ │ WeChat/WebUI │ │ shared/ │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └────────┬──────────┘ │
|
||||
└─────────┼─────────────────┼───────────────────┼─────────────┘
|
||||
│ │ │ HTTP
|
||||
┌─────────▼─────────────────▼───────────────────▼─────────────┐
|
||||
│ 路由层 backend/routes/ (35 文件) │
|
||||
│ backend/route_registry.py — 166 条 RouteSpec │
|
||||
│ PERMISSION_MATRIX: read/write/config/materials/ │
|
||||
│ retry/public_token │
|
||||
└─────────┬───────────────────────────────────────────────────┘
|
||||
│ backend/dto/ (13) 出入参
|
||||
┌─────────▼───────────────────────────────────────────────────┐
|
||||
│ 服务层 backend/services/ (70 文件) │
|
||||
│ workflow 簇 · material 簇 · generation 簇 · chat 簇 │
|
||||
└─────────┬───────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────▼───────────────────────────────────────────────────┐
|
||||
│ 引擎层 engines/ — character_flow / fast_character_flow / │
|
||||
│ quick_profile_flow / single_flow / review_flow / │
|
||||
│ image_provider / vision_provider │
|
||||
└─────────┬───────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────▼───────────────────────────────────────────────────┐
|
||||
│ 数据层 database/ — models.py · db_helper.py · │
|
||||
│ repositories/ (15) · migrations/ (0001–0018) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
横切:core/ (23) — identity · security · storage · config_service ·
|
||||
audit_service · event_bus · fsm · queue_manager ·
|
||||
model_router · media_proxy · remote_fetch · secret_service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 依赖热点(扇入 Top10)
|
||||
|
||||
按 `from X import` 出现次数统计:
|
||||
|
||||
| 排名 | 模块 | 被引用次数 | 评价 |
|
||||
|---:|---|---:|---|
|
||||
| 1 | `core.identity` | 65 | 合理(ID 生成为纯工具) |
|
||||
| 2 | `database.db_helper` | 56 | ⚠️ 数据访问入口,几乎人人依赖 |
|
||||
| 3 | `backend.dto.common` | 54 | 合理 |
|
||||
| 4 | `core.security` | 31 | 合理 |
|
||||
| 5 | `backend.routes.common` | 31 | 合理 |
|
||||
| 6 | `core.audit_service` | 30 | ⚠️ 审计横切散布在业务代码中 |
|
||||
| 7 | `database.repositories.workflow_repository` | 19 | ⚠️ 跨层直接引用 |
|
||||
| 8 | `database.repositories.profile_repository` | 16 | ⚠️ 同上 |
|
||||
| 9 | `backend.routes.params` | 16 | 合理 |
|
||||
| 10 | `backend.services.workflow_service` | 15 | ⚠️ service 间强耦合中心 |
|
||||
|
||||
> 详细耦合分析见 [03-耦合分析.md](03-耦合分析.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 已确认的量化问题(本文档直接核实)
|
||||
|
||||
### 4.1 `main.py` 短命令别名:~190 行纯样板
|
||||
|
||||
`main.py:1300–1490` 定义了 38 个 `imagestudio_short_*` 方法,每个都是对同名长命令的 3 行纯转发:
|
||||
|
||||
```python
|
||||
@imagestudio_short_command.command("状态")
|
||||
async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
|
||||
async for result in self.imagestudio_status(event, workflow_id):
|
||||
yield result
|
||||
```
|
||||
|
||||
38 个 × ~4 行 ≈ **190 行**,零业务逻辑。可用一个命令表 + 工厂函数生成,削减约 175 行。
|
||||
|
||||
### 4.2 仓库卫生:2.6 GB 本地垃圾 + 38 MB 已入库产物
|
||||
|
||||
| 目录 | 体积 | 是否入库 | 说明 |
|
||||
|---|---:|---|---|
|
||||
| `.tmp/` | **2.1 GB** | 否(已 gitignore) | 8 份整仓快照 + 22 个发布包 + 60+ 临时脚本,共 **6,303 个文件** |
|
||||
| `.tmp_pytest_*`(根目录 19 个) | **~515 MB** | 否(已 gitignore) | 单个 `.tmp_pytest_full_1022` 就 69 MB |
|
||||
| `release/` | **38 MB** | **是(20 个 zip 已提交)** | ⚠️ 二进制发布包进版本库 |
|
||||
| `web/assets/`、`pages/imagestudio/assets/` | — | **是(38 个文件)** | ⚠️ 前端构建产物进版本库 |
|
||||
|
||||
`.git` 目录已达 **51 MB**,主要由 `release/*.zip` 的历史版本贡献。
|
||||
|
||||
`.gitignore` 已正确忽略 `.tmp/` 与 `.tmp_pytest*/`,但**未忽略 `release/`**,且构建产物是有意提交的(插件分发需要)。
|
||||
|
||||
### 4.3 异常处理
|
||||
|
||||
- `except Exception` × **180**(后端)
|
||||
- 裸 `except:` × 0 ✅
|
||||
- `except ...: pass`(静默吞掉)× **22** ⚠️
|
||||
- `async def` 仅 **93** 个 —— 64k 行后端中异步占比很低,需核查是否有同步阻塞调用混在 async 路径上
|
||||
|
||||
### 4.4 循环依赖信号
|
||||
|
||||
函数体内 `import`(规避循环导入的典型手法)共 **36 处**,集中在:
|
||||
|
||||
| 文件 | 次数 |
|
||||
|---|---:|
|
||||
| `main.py` | 16 |
|
||||
| `database/db_helper.py` | 4 |
|
||||
| `backend/services/model_provider_runtime.py` | 3 |
|
||||
| `backend/routes/job_routes.py` | 3 |
|
||||
| `backend/services/generation_service.py` | 2 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 前后端契约面
|
||||
|
||||
- 后端注册端点:**166** 条(`backend/route_registry.py` 的 `RouteSpec`)
|
||||
- 前端声明端点:**143** 条(`frontend/shared/api/endpoints.ts`)
|
||||
- 前端类型定义:`frontend/shared/types/` 共 15+ 文件,与 `backend/dto/`(13 文件)**手工同步**,无代码生成
|
||||
- `App.vue` 中 `endpoints.` 引用 **183** 次、覆盖 85 个不同端点,**未发现硬编码 `/api/` 字符串** ✅(全前端唯一的 `/api/` 字面量就是 `endpoints.ts:1` 的 `API_BASE` 定义本身)
|
||||
|
||||
> 端点差集、类型漂移逐字段比对见 [03-耦合分析.md](03-耦合分析.md)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 技术栈
|
||||
|
||||
| 层 | 技术 |
|
||||
|---|---|
|
||||
| 后端 | Python 3、AstrBot Star 插件框架、SQL(迁移脚本手写 SQL) |
|
||||
| 前端 | Vue 3.5(`<script setup>`)、TypeScript 5.7、Vite 6、Pinia 2.3、Vue Router 4.5 |
|
||||
| 构建 | 双入口:`plugin-page`(嵌入 AstrBot WebUI)+ `standalone-web`(独立站) |
|
||||
| 测试 | pytest(45 文件 / 11,559 行)、`node --test`(前端契约测试) |
|
||||
|
||||
> ⚠️ `frontend/package.json` 的 `devDependencies` 为空,`typescript`/`vite`/`vue-tsc`/`@vitejs/plugin-vue` 全部错放在 `dependencies`。
|
||||
|
||||
---
|
||||
|
||||
*本文档由人工核实数据写成;各维度详细发现见 [findings/](findings/)。*
|
||||
796
审计/02-BUG清单.md
普通文件
796
审计/02-BUG清单.md
普通文件
|
|
@ -0,0 +1,796 @@
|
|||
# 02 · BUG 清单(缺陷类发现汇总)
|
||||
|
||||
**范围**:`_raw.json` 中 category ∈ {bug, security, perf} 的全部 106 条发现,剔除被对抗式复核推翻的 12 条,**本清单收录 94 条**。
|
||||
**严重度**:以复核结论为准(复核对 P0/P1 逐条重定级),未经复核的沿用原判。
|
||||
**基线事实**:后端 263 个 pytest 全部通过(188 秒),前端 26 个 node:test 全部通过。**代码跑得起来,问题在设计边界与信任边界,不在语法与冒烟。**
|
||||
|
||||
| 最终严重度 | 条数 |
|
||||
| --- | --- |
|
||||
| P0-致命 | 1 |
|
||||
| P1-严重 | 10 |
|
||||
| P2-中等 | 64 |
|
||||
| P3-轻微 | 19 |
|
||||
| **合计** | **94** |
|
||||
|
||||
---
|
||||
|
||||
## 0. 立即处置(今天就要动手,按紧迫度排序)
|
||||
|
||||
### 0.1 【P0】凭据泄露:轮换 + 清理,两件事都要做,缺一无效
|
||||
|
||||
`.env.imagestudio_codex_handoff.yaml`(仓库根,3506 字节)含 5 类可直接使用的真实凭据。该文件**已被 `.gitignore:39` 的 `.env*` 规则覆盖,`git ls-files` / `git log --all --diff-filter=A` 均确认从未入库** —— 但泄露通道根本不走 git:打包脚本用整目录复制而非 `git archive`,`.gitignore` 对它零约束。
|
||||
|
||||
实测确认的扩散面(本次审计逐个 `tar -tf` / `unzip -l` 验证):
|
||||
|
||||
| 载体 | 数量 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `.tmp/*.tar.gz` / `*.tar` 归档 | **19** | 1.0.35/36/37、1.0.38~41-*、1.0.64/65、1.0.67-*/68-*、imagestudio-1.0.66-deploy-*、imagestudio-material-*(5 个)、nas-deploy-worktree-20260724(.clean).tar |
|
||||
| `.tmp/*.zip` 归档 | **2** | 1.0.62.zip、1.0.63.zip(原报告未计入,本次补充确认) |
|
||||
| `.tmp/*.zip.b64` | 1 | `astrbot_plugin_imagestudio-1.0.62.zip.b64`(56 MB,base64 编码的同一份泄露) |
|
||||
| `.tmp/deploy-*` 暂存目录 | 8 | 各含一份 3506 字节副本 |
|
||||
| 仓库根原始文件 | 1 | — |
|
||||
|
||||
`.tmp/deploy_remote.sh:3` 指明推送目标为 NAS 上的 `/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio`,`.tmp/upload_via_ssh.py` / `deploy_imagestudio_10*.sh` 用 ssh/scp 执行推送 —— 即这些归档已经离开本机。
|
||||
|
||||
讽刺点:该文件第 80 行自己写着 `rules.redact_secrets: true`;`grep -rn "redact_secrets" --include=*.py` 全仓零命中,它只是给 AI 看的自然语言备注,没有任何代码强制。
|
||||
|
||||
#### 轮换清单(按此顺序执行,**不要只删文件**)
|
||||
|
||||
> 归档已上传 NAS,必须假定凭据已泄露。删除文件不能撤销泄露,只有轮换可以。
|
||||
|
||||
| # | 凭据 | 文件位置 | 特征(不复述真值) | 处置动作 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | LLM API Key A | `:25` `model_sites.site_a.api_key_plaintext` | 67 字符,前缀 `sk-3`,weilai.chat | 在该站点控制台**作废旧 key**并签发新 key;检查账单是否有异常调用 |
|
||||
| 2 | LLM API Key B | `:45` `model_sites.site_b.api_key_plaintext` | 51 字符,前缀 `sk-B`,botcf.com | 同上 |
|
||||
| 3 | PostgreSQL 口令 | `:57-61` host/port/database/user/password | 主机 `192.` 段内网地址、端口 5 位、用户 9 字符、口令 11 字符明文 | `ALTER ROLE ... WITH PASSWORD`;同时确认该 PG 是否可从 NAS 网段直连,必要时收紧 `pg_hba.conf` |
|
||||
| 4 | AstrBot 管理员 JWT | `:73` `astrbot.admin_token_plaintext` | 136 字符 HS256 JWT,前缀 `eyJh`,exp≈2026-07-12(已过期) | **仍需更换 AstrBot 的 JWT signing secret** —— token 过期不等于安全,持有 #5 即可随时重签新 token |
|
||||
| 5 | AstrBot 管理员口令 | `:75-76` `admin_username` / `admin_password_plaintext` | 用户名 9 字符前缀 `Yoki`,口令 13 字符明文,**永不过期** | 立刻改密;该账号托管本插件全部 166 条 API |
|
||||
|
||||
#### 清理命令
|
||||
|
||||
```bash
|
||||
cd "D:/CODEX/projects/AstrBot ImageStudio"
|
||||
|
||||
# 1) 先确认清单(不要盲删)
|
||||
for f in .tmp/*.tar.gz .tmp/*.tar; do
|
||||
tar -tf "$f" 2>/dev/null | grep -q '\.env\.imagestudio' && echo "LEAK: $f"
|
||||
done
|
||||
for z in .tmp/*.zip; do
|
||||
unzip -l "$z" 2>/dev/null | grep -q '\.env\.imagestudio' && echo "LEAK: $z"
|
||||
done
|
||||
|
||||
# 2) 删除全部泄露归档 + base64 副本 + 8 个 staging 目录
|
||||
rm -f .tmp/astrbot_plugin_imagestudio-1.0.3{5,6,7}.tar.gz \
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.{38,39,40,41}-*.tar.gz \
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.6{4,5}.tar.gz \
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.6{7,8}-*.tar.gz \
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.6{2,3}.zip \
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.62.zip.b64 \
|
||||
.tmp/imagestudio-1.0.66-deploy-*.tar.gz \
|
||||
.tmp/imagestudio-material-*.tar.gz \
|
||||
.tmp/nas-deploy-worktree-20260724*.tar
|
||||
rm -rf .tmp/deploy-1.0.35 .tmp/deploy-clean-1.0.3{5,6,7} .tmp/deploy-stage-1.0.4{0,1}-* .tmp/deploy-stage-1.0.3{8,9}-*
|
||||
|
||||
# 3) NAS 侧:删除已上传的同名包与解包目录内的副本
|
||||
# (HOST 换成 deploy_remote.sh 里实际使用的目标)
|
||||
ssh "$HOST" 'PLUGIN_DIR=/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio; \
|
||||
rm -f "$PLUGIN_DIR"/.env.imagestudio_codex_handoff.yaml; \
|
||||
find /volume2/Dockers/qqbot -maxdepth 4 -name "astrbot_plugin_imagestudio-*.tar.gz" -o -name "imagestudio-*.tar.gz" | xargs -r rm -f'
|
||||
|
||||
# 4) 本地原始文件(轮换完成后再删,删之前先记下要迁移哪些字段)
|
||||
rm -f .env.imagestudio_codex_handoff.yaml
|
||||
```
|
||||
|
||||
#### 防复发(同一天做完)
|
||||
|
||||
打包脚本改用 git 视角,并加硬断言:
|
||||
|
||||
```bash
|
||||
git archive --format=tar.gz --prefix=astrbot_plugin_imagestudio/ \
|
||||
-o "dist/plugin-$(git describe --always).tar.gz" HEAD
|
||||
tar -tf "dist/plugin-$(git describe --always).tar.gz" | grep -qE '(^|/)\.env' \
|
||||
&& { echo "SECRET LEAK IN ARCHIVE"; exit 1; }
|
||||
```
|
||||
|
||||
凭据改走环境变量注入 —— `_conf_schema.json` 已有 `*_api_key_env_var` 字段,设计上本就支持,配置文件里只留变量名。
|
||||
|
||||
> **本节的严重度标签说明**:0.2 与 0.3 的最终定级是 **P2**(复核把它们从 P1 降级,理由见 §5 对应行与 §2 链路 A 的第 ⑥ 环说明)。它们之所以仍排在"立即处置",是因为**修复成本极低(各十几行)而断链收益极高**,不是因为严重度高。0.1 是唯一的 P0,0.4 是 P1(对应 §4 的 P1-8)。
|
||||
|
||||
### 0.2 【P2·但优先做】把 `storage.*` 纳入配置校验(堵住宿主机任意文件读取)
|
||||
|
||||
`settings_service.validate()`(`backend/services/settings_service.py:240` 起)只校验 `generation` / `vision` / `database` / `prompt_governance` / `advanced_materials` 五段,**`storage` 段一次都没出现**(该文件 `grep -i storage` 仅命中 `:195` 的 schema 描述行)。配合 `core/runtime_paths.py:43-45` 对绝对路径原样放行,`VfsStorage` 的沙箱边界完全由可写配置决定。详见 §2 攻击链。
|
||||
|
||||
最小修复(一处即可断链):在 `validate()` 中加 storage 段校验,或在 `VfsStorage._root_paths()`(`core/storage.py:105-108` 的锚点来源)强制把每个 root 收敛到 `get_runtime_data_root().resolve()` 之下。
|
||||
|
||||
### 0.3 【P2·但优先做】给 `storage/migrate` 加覆盖确认与审计
|
||||
|
||||
`core/storage.py:51-53` 计算了 `will_overwrite` 却**只放进返回体、没有任何分支用它阻断**;`_copy_path`(`:182-200`)用 `shutil.copy2` 静默覆盖。`backend/routes/storage_routes.py:46` 的 `dry_run=as_bool(payload.get("dry_run"), default=True)` 可由请求体传 `false`。该路由未 import AuditService,全程无审计记录。
|
||||
|
||||
### 0.4 【P1】PostgreSQL 部署当场不可用 —— 3 行字面量 `%`
|
||||
|
||||
`database/repositories/profile_repository.py:46 / :73 / :99` 三份逐字重复的 `LIKE '%"final_archive_history_id"%'`,在 `backend: postgresql` 下会被 psycopg 当作 %-format 模板展开而报错,`get()` 与 `list()` 两个最核心读接口 100% 失败。`config.yaml:153-167` 把 postgresql 作为受支持配置对外暴露 —— 只要有人切过去,角色列表和详情立刻全挂。改成参数绑定即可,工作量 S。
|
||||
|
||||
---
|
||||
|
||||
## 1. P0 汇总表
|
||||
|
||||
| # | 标题 | 位置 | 影响一句话 | 修复工作量 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P0-1 | 真实 API Key / DB 口令 / 管理员 JWT / 管理员明文口令被打进 19 个 tar 归档 + 2 个 zip 并推送到 NAS | `.env.imagestudio_codex_handoff.yaml:25/45/57-61/73/75-76`;打包链路 `.tmp/deploy_remote.sh:3`、`.tmp/upload_via_ssh.py` | 任何拿到部署包的人可盗刷两个模型站点额度、直连业务 PostgreSQL 读写、以管理员身份接管托管全部 166 条 API 的 AstrBot 实例 | **M**(轮换 5 类凭据 + 清理 NAS + 改打包脚本,均为运维动作,无代码改动) |
|
||||
|
||||
### 1.1 原判 P0,经复核降级(不再计入 P0,但必须知道它们被降级的理由)
|
||||
|
||||
| 原判 | 现判 | 标题 | 位置 | 降级理由(复核结论原意) |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P0 | **P1** | 桥接层给所有登录用户发放全部权限 | `main.py:104-106`、`main.py:2337` | 未登录时权限为空集,`require_authenticated` 会拒绝 —— 这是"已认证用户之间缺乏权限分级",不是未授权访问。单管理员 dashboard 部署下影响退化为无 |
|
||||
| P0 | **P1** | workflow/node/image/job/history 五条链路无归属校验(IDOR) | `backend/routes/workflow_routes.py:50` 等 | 复核确认成立、无上游守卫,但同样受限于"必须先通过 AstrBot 面板认证" |
|
||||
| P0 | **P2** | `dispatch_extension_request` 从不检查 `RouteMatch.permission` | `adapters/astrbot_adapter.py:171-187` | 技术事实全部核实,但 handler 内的 `require_*` 守卫齐整存在(复核逐条验过 round/data_backup/settings/integration/media/storage 各路由),矩阵不强制是纵深防御缺失而非当前可利用漏洞 |
|
||||
| P0 | **P1** | `displayMediaUrl()` 在 computed/render 中产生副作用 | `frontend/standalone-web/src/App.vue:11146` | 缺陷成立且行号逐条核对无误;降级仅因它是性能/内存问题而非数据正确性或安全问题 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 可利用攻击链
|
||||
|
||||
### 链路 A:已认证用户 → 宿主机任意文件读取
|
||||
|
||||
每一环都有代码支撑,环环相扣,任何**一环**被堵住即断链。
|
||||
|
||||
```
|
||||
① 通过 AstrBot 面板登录(任意账号)
|
||||
main.py:2337 permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||||
main.py:104-106 BRIDGE_PERMISSIONS = {"can_write","can_manage_config","can_manage_materials","can_retry_tasks"}
|
||||
→ 只要能取到 username/user_id,就拿到 can_manage_config
|
||||
↓
|
||||
② POST settings/save,把 storage.temp_path 改为 "/" 或 "C:/"
|
||||
route_registry.py:156 settings/save → "config" 档
|
||||
backend/services/settings_service.py:240 起 validate() 完全不校验 storage 段
|
||||
core/config_service.py:74-84 storage.*_path 直接 str() 落库,无 sanitize;load() 无缓存,改完立刻生效
|
||||
main.py 的 _RUNTIME_PATH_TO_ASTRBOT_KEY 白名单里没有 storage.temp_path,不会被 _restore_runtime_managed_fields 还原
|
||||
↓
|
||||
③ resolve_data_path 对绝对路径原样放行
|
||||
core/runtime_paths.py:43-45
|
||||
resolved = Path(path).expanduser()
|
||||
if resolved.is_absolute():
|
||||
return resolved # ← 无白名单、无前缀约束
|
||||
↓
|
||||
④ VfsStorage 的越界检查被架空
|
||||
core/storage.py:105-108
|
||||
resolved_root = resolve_data_path(root_path).resolve()
|
||||
resolved_path = (resolved_root / relative).resolve()
|
||||
if resolved_path != resolved_root and resolved_root not in resolved_path.parents:
|
||||
raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri})
|
||||
→ 该检查只保证"不越出 root",而 root 本身已被②改成 /
|
||||
实测(未改任何源码):
|
||||
StorageConfig(temp_path='C:/Windows')
|
||||
VfsStorage(...).resolve_uri('storage://temp/System32/drivers/etc/hosts')
|
||||
-> C:\Windows\System32\drivers\etc\hosts exists=True
|
||||
↓
|
||||
⑤ GET media/index?root=temp 枚举全盘 → GET media/sign 为任意路径签发令牌
|
||||
route_registry.py:169 media/sign → "read"
|
||||
route_registry.py:170 media/index → "read"
|
||||
core/media_proxy.py:49-51 签名 URL 形如 /api/plug/.../media/fetch?token=<payload>.<sig>,payload 内不含签发者标识
|
||||
↓
|
||||
⑥ GET media/fetch 取走文件内容
|
||||
route_registry.py:173 RouteSpec("GET","media/fetch",...,"public_token")
|
||||
route_registry.py:28 "public_token": {"auth_required": False, "required_permission": None, ...}
|
||||
→ 全仓唯一 auth_required: False 的路由
|
||||
```
|
||||
|
||||
**关于第 ⑥ 环,必须如实说明(这是复核推翻的部分)**:`PERMISSION_MATRIX` 里的 `auth_required` 是一份**说明性清单**,不是执行开关 —— 全仓 `grep "auth_required"` 只命中 `route_registry.py` 自身,消费者仅 `adapters/webui_adapter.py:19` 与 `backend/services/contract_service.py:17-18`,两者都只是把它塞进 manifest/contract 返回给前端。真正的鉴权是两层:handler 内的 `require_authenticated`(`core/security.py:9`)+ 宿主 AstrBot 的中间件。`backend/routes/media_routes.py:56-62` 的注释明确说明 `media/fetch` 仍走宿主已鉴权的扩展路由面(浏览器 `<img>` 拿不到 JWT 才另开 `media/payload`)。
|
||||
|
||||
因此**"把签名 URL 交给任何未认证第三方去取"这一步不成立,链路终点是"已认证用户读取宿主机任意文件",不是"无认证外传"**。这也是复核把该条从 P1 降到 P2 的唯一理由。但请注意:由于第 ① 环,"已认证用户"在插件内部等价于"配置管理员",且插件自身文档 `docs/final-release-audit-2026-07-22.md:36-42` 已把同类问题记为 P1-1,并写明"当前可接受边界:仅限明确声明的可信 AstrBot 管理员工作台" —— 只要部署里存在第二个 WebUI 账号,或面板被反代给多人,这条链就有实际受害者。
|
||||
|
||||
**推荐断链点(按性价比排序)**:③ 或 ④(一次改动堵死全部 storage 相关接口)> ② > ①。
|
||||
|
||||
### 链路 B:同一入口的任意写 → 宿主机代码执行
|
||||
|
||||
```
|
||||
①(同上)拿到 can_manage_config
|
||||
↓
|
||||
② POST storage/migrate {"source_uri": ..., "target_uri": ..., "dry_run": false}
|
||||
route_registry.py:168 storage/migrate → "config"
|
||||
backend/routes/storage_routes.py:36-47 只有 require_config_manager(ctx);dry_run 由请求体控制
|
||||
↓
|
||||
③ 覆盖保护是空的
|
||||
core/storage.py:51-53
|
||||
will_overwrite = target_path.exists()
|
||||
if not dry_run:
|
||||
_copy_path(source_path, target_path) # will_overwrite 从未参与任何判断
|
||||
core/storage.py:182-200 _copy_path -> shutil.copy2,目标已存在时静默覆盖
|
||||
唯一守卫是 :188-191 的 "target 不能在 source 之内",与覆盖保护无关
|
||||
↓
|
||||
④ 结合链路 A 的 ②③④,source/target 的 root 均可指向任意绝对路径
|
||||
→ 覆盖 AstrBot 配置、投毒其他插件目录、写入启动脚本目录
|
||||
全程无审计(storage_routes.py 未 import AuditService)
|
||||
```
|
||||
|
||||
**复核修正**:`resolve_uri` 内的 `split_uri`(`core/storage.py:127-128`)会拒绝 `..` 与绝对相对路径,所以"任意路径写入"必须先经 root 改配置这一步 —— 该链**依赖链路 A 的第②③环**,两条链应一起修,修好 root 约束后 B 链的危害同步收敛为"仅在受限根之间复制"。
|
||||
|
||||
---
|
||||
|
||||
## 3. P0 逐条详述
|
||||
|
||||
### P0-1 · 真实凭据被打进部署归档并推送到 NAS
|
||||
|
||||
**位置**
|
||||
`.env.imagestudio_codex_handoff.yaml:25`(API Key A)、`:45`(API Key B)、`:57-61`(PostgreSQL 连接串)、`:73`(管理员 JWT)、`:75-76`(管理员账号/口令)
|
||||
打包与推送:`.tmp/deploy_remote.sh:3`、`.tmp/upload_via_ssh.py`、`.tmp/deploy_imagestudio_10{35,36,37,64}.sh`
|
||||
|
||||
**问题**
|
||||
文件本身被 `.gitignore:39` 的 `.env*` 正确忽略 —— `git check-ignore -v` 返回 `.gitignore:39:.env*`,`git ls-files | grep env` 只有 `frontend/env.d.ts`,`git log --all --diff-filter=A` 为空。**这恰恰制造了误导性的安全感**:泄露不走 git,走的是"整目录复制打包"。8 个 `.tmp/deploy-*` 暂存目录各留一份 3506 字节副本,19 个 tar/tar.gz + 2 个 zip 归档各封装一份,其中一份还被 base64 展开成 56 MB 的 `.b64`。
|
||||
|
||||
**真实证据**
|
||||
|
||||
```
|
||||
$ git ls-files | grep -i env
|
||||
frontend/env.d.ts # 仅此一条,泄露文件从未入库
|
||||
|
||||
$ tar -tf .tmp/astrbot_plugin_imagestudio-1.0.35.tar.gz | grep env
|
||||
astrbot_plugin_imagestudio/.env.imagestudio_codex_handoff.yaml
|
||||
|
||||
$ tar -tf .tmp/astrbot_plugin_imagestudio-1.0.41-20260720-101338.tar.gz | grep env
|
||||
./.env.imagestudio_codex_handoff.yaml
|
||||
|
||||
# 本次审计复测(19 tar/tar.gz + 2 zip 命中,8 个 staging 目录各含一份)
|
||||
|
||||
# .tmp/deploy_remote.sh:3
|
||||
PLUGIN_DIR=/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio
|
||||
|
||||
# 文件内自称的保护措施(第 80 行),全仓 grep --include=*.py 零命中:
|
||||
rules.redact_secrets: true
|
||||
```
|
||||
|
||||
**影响**
|
||||
拿到任意一个部署包即可:盗刷两个模型站点额度;直连内网 PostgreSQL 读写业务库(角色档案、生成记录、审计日志、配置快照 —— 而配置快照本身又是明文密钥的第二个副本,见 P2 表 `settings_service.py:614`);用管理员口令登录 AstrBot 并重签 JWT,接管托管本插件 166 条 API 的整个实例。JWT 已过期不构成缓解 —— 明文口令永不过期。
|
||||
|
||||
**修复**
|
||||
按 §0.1 执行:先轮换 5 类凭据(这一步不可省略,删文件不能撤销已上传的副本),再清理本地 21 个归档 + 1 个 b64 + 8 个 staging 目录 + 根文件,再清理 NAS,最后把打包脚本换成 `git archive` 并加 `tar -tf | grep -qE '(^|/)\.env' && exit 1` 断言。凭据长期改走 `_conf_schema.json` 已有的 `*_api_key_env_var` 环境变量注入。
|
||||
|
||||
---
|
||||
|
||||
## 4. P1 逐条详述
|
||||
|
||||
### P1-1 · 桥接层给所有登录用户发放全部权限,PERMISSION_MATRIX 在运行时被架空
|
||||
|
||||
**位置** `main.py:104-106`(定义)、`main.py:2337`(赋权);受影响执行点 `core/security.py:17-37`、`backend/route_registry.py:9-29`
|
||||
|
||||
**问题** 插件页是前端唯一通路,其 `RequestContext` 构造只有一个分支:能取到 username/user_id 就给满四项能力,否则给空集。于是 `config`(22条)+`materials`(38条)+`retry`(8条) 共 68 条路由的权限档,对桥接通路全部塌缩成 `read`。
|
||||
|
||||
**真实代码**(逐字核对,含原有注释)
|
||||
|
||||
```python
|
||||
# main.py:104-106
|
||||
BRIDGE_PERMISSIONS = frozenset(
|
||||
{"can_write", "can_manage_config", "can_manage_materials", "can_retry_tasks"}
|
||||
)
|
||||
|
||||
# main.py:2333-2337
|
||||
# AstrBot authenticates extension routes before invoking the plugin, but
|
||||
# PluginRequest currently exposes only the authenticated username. Grant
|
||||
# the capabilities that exist today explicitly instead of a wildcard so a
|
||||
# future permission cannot become enabled accidentally.
|
||||
permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||||
```
|
||||
|
||||
**这不是疏忽。** 注释本身写明了原因(上游 `PluginRequest` 只暴露 username,读不到角色)与取舍(显式列举而非通配符 `*`,避免未来新增权限被意外打开)。仓库文档 `docs/final-release-audit-2026-07-22.md:36-42` 也已把它记为 P1-1 并声明"当前可接受边界:仅限明确声明的可信 AstrBot 管理员工作台"。**这是一个被记录在案、有边界声明的技术债,不是不懂安全。** 问题在于这个边界声明没有任何机制强制 —— 部署方多开一个 WebUI 账号,或把面板反代出去,边界就静默失效了。
|
||||
|
||||
**影响** 已认证用户之间零权限分级:任意登录用户可 `POST settings/save`(改数据库后端与密钥环境变量名)、`POST settings/rollback`、`POST backups/{id}/restore`(覆盖全量数据)、`POST integrations/private-companion/token/rotate`、`POST jobs/failed/clear`。这也是 §2 两条攻击链的第一环。另:`resource_access_service.py:82` 的 `ctx.has_permission("can_manage_all_profiles")` 子条件在 Web 通路上恒假(`RequestContext.system()` 的 `"*"` 分支仍有效,不是整段死代码)。
|
||||
|
||||
**修复**
|
||||
1. 短期、当天可做:在 `config.yaml` 增加显式白名单(如 `security.config_admin_users`),`main.py:2337` 改为按 username 命中白名单才追加 `can_manage_config` / `can_manage_materials`,未命中只给 `can_write` + `can_retry_tasks`。这不需要上游改 `PluginRequest`。
|
||||
2. 中期:从 AstrBot 请求上下文尝试解析角色(`g` 上的 role/claims),解析失败时**降级到最小集**而非最大集。
|
||||
3. 配套:把这条边界写进启动自检 —— 若白名单为空且检测到多个不同 username 访问过,打一条 warning。
|
||||
|
||||
### P1-2 · workflow / node / image / job / history 五条链路无归属校验(IDOR)
|
||||
|
||||
**位置** `backend/routes/workflow_routes.py:50`;同类散布于 `node_routes.py:79`(get_node)、`image_routes.py:22`(list_images)、`job_routes.py:19`(list_jobs)/`:44`(get_job)、`history_routes.py:35`;根因在 `backend/services/workflow_service.py:146-164`、`:960` 与 `backend/services/queue_service.py:91`
|
||||
|
||||
**问题** 仓库里明确存在归属链服务 `backend/services/resource_access_service.py`(模块 docstring:调用方必须拥有资源链末端的 profile),实现了 `require_profile/workflow/node/image/task` 五个方法,`_can_access` 比对 `ctx.actor_id == owner_user_id`。profile 路由和 round 路由都接上了,**这五条链路漏改了** —— service 方法签名里根本没有 `ctx`。
|
||||
|
||||
**真实代码**
|
||||
|
||||
```python
|
||||
# backend/routes/workflow_routes.py:50-61 —— 只校验"已登录"
|
||||
def get_workflow(ctx, workflow_id, service=None) -> dict:
|
||||
workflow_service = service or _create_workflow_service()
|
||||
def action() -> dict[str, Any]:
|
||||
require_authenticated(ctx)
|
||||
return workflow_service.get_workflow(workflow_id).to_dict() # 无 ctx
|
||||
return handle_request(ctx, action)
|
||||
|
||||
# backend/services/workflow_service.py:146-150
|
||||
def list_workflows(self, profile_id: str) -> list[ProfileWorkflow]: # 无 ctx
|
||||
self._ensure_profile_exists(profile_id) # 只判存在,不判归属
|
||||
return self.workflow_repository.list_workflows(profile_id)
|
||||
|
||||
def get_workflow(self, workflow_id: str) -> WorkflowDetail: # 无 ctx
|
||||
|
||||
# backend/services/workflow_service.py:650
|
||||
def get_node(self, node_id: str) -> WorkflowNode: # 无 ctx
|
||||
```
|
||||
|
||||
**影响** 任意登录用户可枚举/读取/修改他人资源:`GET profiles/{他人id}/workflows`、`GET|PUT workflows/{id}`、`POST workflows/{id}/start|cancel|archive|execute-character`(直接花对方模型额度出图)、`POST profiles/{他人id}/workflows`、`GET|PUT nodes/{id}`、`POST nodes/{id}/generate`。`GET jobs` 无任何 owner 维度,且 `GenerationTask.to_dict()` 含完整 `request`(他人提示词、参考图 URI、模型路由)。行为还自相矛盾:`GET nodes/{id}` 能读到他人节点,而 `GET nodes/{id}/rounds` 会正确 404 —— 这正是"漏改"而非"设计如此"的铁证。
|
||||
|
||||
**修复**
|
||||
1. `WorkflowService.list_workflows/get_workflow/get_node/list_nodes` 增加 `ctx` 参数,内部走已有的 `require_workflow` / `require_node`。
|
||||
2. `QueueService.list_jobs` 与 `ImageService.list_images` 增加 `owner_user_id` 过滤参数,路由层传 `ctx.actor_id`(持 `can_manage_all_profiles` 时传 None)。
|
||||
3. `HistoryService` 相关方法前置 `require_workflow`。
|
||||
4. 补越权矩阵测试:用户 A 建资源,用户 B 对全部路由逐条请求,断言 404/403。这类测试一次写好可长期防回归。
|
||||
|
||||
### P1-3 · 客户端自带 `content_permissions` / `entrypoint`,可绕过成人内容路由闸门
|
||||
|
||||
**位置** `backend/services/generation_service.py:2352`(`_entrypoint`)与 `:2366`(`_permission_context`);触发点 `:1461`、`:1503`(`_govern_prompt`)与 `:1578`、`:1581`(`_content_safety_fallback`);入口 `backend/routes/node_routes.py:132-146`
|
||||
|
||||
**问题** `POST nodes/{node_id}/generate` 的 payload 原样透传给 `GenerationService.generate_node`,而"用户是否被允许成人内容"这个裁决输入**直接从请求体里取**,全程不引用 `ctx`。
|
||||
|
||||
**真实代码**
|
||||
|
||||
```python
|
||||
# generation_service.py:2366
|
||||
def _permission_context(payload: dict[str, Any]) -> dict[str, Any]:
|
||||
configured = payload.get("content_permissions") if isinstance(payload.get("content_permissions"), dict) else {}
|
||||
result = {
|
||||
**configured,
|
||||
"adult_user_allowed": bool(configured.get("adult_user_allowed", payload.get("adult_user_allowed", False))),
|
||||
"quota_allowed": bool(configured.get("quota_allowed", payload.get("quota_allowed", True))),
|
||||
}
|
||||
|
||||
# generation_service.py:2352
|
||||
def _entrypoint(payload): value = _optional_text(payload.get("entrypoint") or payload.get("platform") or payload.get("source")) or "web"
|
||||
|
||||
# 消费点 prompt_governance_service.py:262-267
|
||||
entry_allowed = bool((self.config.get("entrypoints") or {}).get(entrypoint, False))
|
||||
user_allowed = bool(permissions.get("adult_user_allowed", False))
|
||||
quota_allowed = bool(permissions.get("quota_allowed", True))
|
||||
```
|
||||
|
||||
`node_routes.py:132` 起的 `generate_node` 中,`action()` 只有一行 `require_write(ctx)`,随后直接把 payload 交给 service。
|
||||
|
||||
**影响** 服务端 `prompt_governance.routing.adult_auto_route_enabled` 为 true 时,任意登录用户 POST `{"content_permissions": {"adult_user_allowed": true, "adult_group_allowed": true, "quota_allowed": true}, "entrypoint": "<配置放行的入口>"}` 即可让 adult_allowed 级提示词自动路由到 `nsfw_route`,同时绕过配额判定。**聊天侧是对的** —— `chat_workflow_service` 由服务端 `_content_permissions(config, chat)` 生成,唯独 Web 路由缺这一步。
|
||||
|
||||
**修复** 在路由层剥离客户端提供的 `content_permissions` / `adult_*` / `quota_allowed` / `entrypoint` / `platform` / `source` 字段,由服务端按 `ctx.actor_id` 查配置白名单重建(直接复用 `chat_workflow_service._content_permissions` 的逻辑),`entrypoint` 在 Web 路径硬编码为 `"web"`。这是一处"删输入"的改动,不引入新逻辑。
|
||||
|
||||
### P1-4 · 聊天媒体导入把任意字符串当本地文件路径读取
|
||||
|
||||
**位置** `backend/services/chat_media_import_service.py:33-36`
|
||||
|
||||
**问题** `import_image` 的兜底分支:既不是 `storage://`、也不是 `data:image/`、也不是 `http(s)://` 时,直接把字符串当本地路径读取,无根目录约束、无白名单、无图片魔数校验。
|
||||
|
||||
**真实代码**
|
||||
|
||||
```python
|
||||
# backend/services/chat_media_import_service.py:30-36
|
||||
elif text.startswith(("http://", "https://")):
|
||||
body = read_http_response_limited(text, timeout_seconds=30, max_bytes=MAX_CHAT_IMAGE_BYTES)
|
||||
extension = Path(urlsplit(text).path).suffix.lstrip(".").lower() or "jpg"
|
||||
else:
|
||||
source = Path(text).expanduser().resolve()
|
||||
body = source.read_bytes() # <- 无任何根目录约束
|
||||
extension = source.suffix.lstrip(".").lower() or "jpg"
|
||||
```
|
||||
|
||||
调用链完全可达且无守卫:`adapters/astrbot_media_adapter.py:15-19` 逐个取消息 Image 组件的 `("url","file","path","image_url")` 属性,首个非空即返回,零格式校验 → `main.py:1161 references = image_references_from_event(event)` → `main.py:1167 asyncio.to_thread(self.chat_workflow_service.import_material, reference, ...)` → `chat_workflow_service.py:948 self.media_importer.import_image(image_reference)`,字符串原样透传。
|
||||
|
||||
**加重情节**:`main.py:1160` 的 `imagestudio_import_material` 处理函数**完全没有** `command_allowed(config, action, context)` 权限门,而同文件其他命令入口都有。
|
||||
|
||||
**影响** 消息组件的路径字段一旦可被影响(`file:///`、相对路径、`~/.astrbot/...`),任意宿主文件被读入并作为素材落盘到 `storage://materials/chat/...`,随后可通过素材列表接口读回 —— 等价于任意文件读取 + 外带。非图片内容也会被当图片存储(扩展名只是被强制改写成 jpg)。超大 data URI 会先完整解码进内存再判超限。
|
||||
|
||||
**修复**
|
||||
1. 删除本地路径兜底分支;确需保留则对显式配置的缓存根做 `Path.resolve()` 前缀约束(`backend/services/web_hosting_service.py:58-67` 的 `_resolve` 已写对同类逻辑,直接照抄)。
|
||||
2. 落盘前统一走 `core.image_formats.detect_image_format(body)`,返回 None 则拒绝,并用检出的 `image_format.extension` 而非用户给的后缀。
|
||||
3. `data:` 分支先按 `len(encoded) > ((MAX_CHAT_IMAGE_BYTES + 2) // 3) * 4` 预检再解码(`engines/single_flow.py:398-404` 已有正确写法)。
|
||||
4. 给 `main.py:1160` 补上 `command_allowed` 权限门,与其他聊天命令对齐。
|
||||
|
||||
### P1-5 · `_conf_schema.json` 缺失 prompt_governance 与成人内容白名单,内容安全开关在生产不可用
|
||||
|
||||
**位置** `_conf_schema.json`(整体缺口);映射表 `main.py:110-175` 的 `_CONFIG_KEY_MAP`
|
||||
|
||||
> 本条未进入对抗式复核批次(复核覆盖 56 条 P0/P1,此条未被抽中),沿用原判 P1。
|
||||
|
||||
**问题** `_CONFIG_KEY_MAP` 逐条把 `config.yaml` 路径映射到 schema 键;schema 里没有的键在 AstrBot 面板中就不存在、也无法持久化。实测缺口:整个 `prompt_governance` 段(translation 6 项、`moderation.llm_review_enabled` / `failure_policy`、`routing.safe_route` / `nsfw_route` / `adult_auto_route_enabled` / `entrypoints`、`image_moderation`、`retention` 4 项含 `redact_sensitive_logs`)全无 schema 键;`chat_access.adult_group_allowlist` 与 `adult_user_allowlist` 缺失(普通 `group_allowlist` / `user_allowlist` 有);`security.integration_token_set` / `allowed_integration_plugins` 缺失;`features` 只有 `private_companion_integration`;`storage` 只有 `advanced_materials_path`。
|
||||
|
||||
**真实代码**(这些键在业务代码里是真的被读的)
|
||||
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:1175
|
||||
adult_users = _id_set(access.get("adult_user_allowlist"))
|
||||
adult_groups = _id_set(access.get("adult_group_allowlist"))
|
||||
|
||||
# backend/services/advanced_material_service.py:1309
|
||||
adult_users = {str(value).strip() for value in access.get("adult_user_allowlist", []) if str(value).strip()}
|
||||
|
||||
# backend/services/settings_service.py:184-185 —— 插件自己的设置页渲染了它们
|
||||
_field("adult_group_allowlist", "list", label="成人内容群聊白名单"),
|
||||
_field("adult_user_allowlist", "list", label="成人内容用户白名单"),
|
||||
|
||||
# 但 main.py:156 附近的映射表里只有:
|
||||
"chat_access.group_allowlist": "chat_group_allowlist",
|
||||
"chat_access.user_allowlist": "chat_user_allowlist",
|
||||
# 没有任何 prompt_governance.* 或 adult_*_allowlist 条目
|
||||
```
|
||||
|
||||
**影响** 真实 AstrBot 部署下,管理员只能手改插件目录里的 `config.yaml` 来打开 NSFW 分流、内容审核、成人白名单和日志脱敏;而**插件更新会覆盖 config.yaml**,配置静默回退到默认值(`adult_auto_route_enabled: false`、`llm_review_enabled: false`、`adult_*_allowlist: []`)。即:内容安全开关在生产实际不可配置,且升级即丢失。
|
||||
|
||||
**修复**
|
||||
1. 补齐 `_conf_schema.json` 的 `prompt_governance.moderation.*` / `prompt_governance.routing.*` / `chat_access.adult_*_allowlist` / `prompt_governance.retention.redact_sensitive_logs`,并在 `_CONFIG_KEY_MAP` 加对应映射。
|
||||
2. 加防漂移测试:断言 `_CONFIG_KEY_MAP.values()` 与 `_conf_schema.json` 键集双向相等;再断言 `config.yaml` 中所有安全相关叶子路径都出现在映射表 key 里。
|
||||
3. `postgresql_password` 在 schema 里是 `type:string`,面板会明文回显 —— 若 AstrBot 支持 password/secret 类型应改用,否则在 description 里引导填 dsn 并把密码放环境变量。
|
||||
|
||||
### P1-6 · 队列实际是 LIFO:`ORDER BY created_at DESC` + 固定 batch 导致老任务永久饿死
|
||||
|
||||
**位置** `database/repositories/job_repository.py:145-154`(排序)+ `backend/services/worker_service.py:207-221`(消费路径)
|
||||
|
||||
**问题** worker 认领任务复用了给前端做"最新在前"的通用列表接口。
|
||||
|
||||
```python
|
||||
# job_repository.py:145-154
|
||||
rows = conn.execute(f"""
|
||||
SELECT {TASK_COLUMNS}
|
||||
FROM generation_tasks
|
||||
{where_clause}
|
||||
ORDER BY created_at DESC # ← 队列消费用了倒序
|
||||
LIMIT {placeholder} OFFSET {placeholder}
|
||||
""", tuple(params + [normalized_page_size, offset])).fetchall()
|
||||
|
||||
# worker_service.py:207-212
|
||||
def _claim_next(self, ctx):
|
||||
queued = self.queue_service.list_jobs(status="queued", page=1, page_size=self.claim_batch_size).items
|
||||
for candidate in queued:
|
||||
if _retry_deferred(candidate):
|
||||
continue
|
||||
```
|
||||
|
||||
`claim_batch_size` 默认 25(`worker_service.py:394`),clamp 到 [1,50](`:92`)。`queue_service.list_jobs`(`:91-114`)只做状态白名单与分页归一,不替换排序。
|
||||
|
||||
**这是遗漏而非设计**:全仓唯一的 FIFO 查询是 `job_repository.py:197` 的 `ORDER BY updated_at ASC, created_at ASC, task_id ASC`(`list_stale`),但它只在 `WorkflowRoundWorkerRuntime.start()` 里经 `recover_stale_tasks` 调一次做启动恢复 —— 作者会写有序查询,claim 路径就是忘了。
|
||||
|
||||
**影响** 待处理队列稳定 > 25 时,最早入队的候选永远排不到(新任务不断插到窗口顶端)。用户表现为某个轮次一直卡在 queued,而后创建的轮次先出图。`_retry_deferred` 被延迟的任务还白占这 25 个名额。SQLite 的 `created_at` 是秒级 `CURRENT_TIMESTAMP`,同一秒创建的 4~8 个候选顺序完全不确定。
|
||||
|
||||
**修复** 给 `JobRepository` 增加专用认领查询 `list_claimable(...)`,`ORDER BY created_at ASC, task_id ASC`(FIFO + 稳定次序),`_claim_next` 改调它;同时把 `created_at` 精度提升到毫秒或增加自增 `seq` 列消除同秒歧义。工作量 S,收益立竿见影。
|
||||
|
||||
### P1-7 · 同步生成占满 asyncio 默认线程池,全插件无并发上限与背压
|
||||
|
||||
**位置** `backend/services/generation_service.py:119`(同步入口)+ `:760`/`:831-836`/`:882`(同栈内 create_task→CAS running→provider 调用);`main.py:333`(共享默认 executor);`backend/services/chat_workflow_service.py:216`(每用户 4 线程)
|
||||
|
||||
**问题** `nodes/generate`(Web 与聊天共用)走完全同步的 `_generate_node_locked`:任务刚 `create_task(status="queued")` 就立刻 CAS 成 running 并在同一调用栈里发起 provider 请求,整个过程持有进程内 per-node RLock。所有 Web/桥接请求又都通过 `asyncio.to_thread` 派发到 **asyncio 默认线程池**(`min(32, cpu+4)`)。没有任何信号量或专用 executor。
|
||||
|
||||
```python
|
||||
# generation_service.py:119-123
|
||||
def generate_node(self, node_id, payload, ctx) -> dict[str, Any]:
|
||||
lock_entry = _retain_node_generation_lock(node_id)
|
||||
lock_entry.lock.acquire()
|
||||
try:
|
||||
return self._generate_node_locked(node_id, payload, ctx) # ← 内含 provider 阻塞调用
|
||||
|
||||
# main.py:333
|
||||
response = await asyncio.to_thread( # ← 默认 executor,全插件共用
|
||||
dispatch_web_request, ctx, dispatch_method, dispatch_endpoint, ...)
|
||||
|
||||
# chat_workflow_service.py:216
|
||||
with ThreadPoolExecutor(max_workers=4, thread_name_prefix="imagestudio-chat-fast") as executor:
|
||||
futures = {executor.submit(self.generate_node, str(node["node_id"]), chat): node for node in nodes}
|
||||
```
|
||||
|
||||
**影响** 单次 provider 调用默认 180 秒、最高允许 3600 秒(`engines/image_provider.py:308-313` 的 `min(max(timeout,10),3600)`)。十几个并发 `nodes/generate` 就能把默认 executor 占满,此后**所有** ImageStudio Web API(列表、状态轮询、取消)一起挂起 —— 包括用来取消这些生成的接口。快速角色命令还会为每个聊天用户额外派生 4 个线程,`with` 退出时 `shutdown(wait=True)` 不可中断,N 个用户 = 4N 路并发 provider 请求,成本无上限。
|
||||
|
||||
**修复**
|
||||
1. 为生成建立独立、容量可配的 `ThreadPoolExecutor`(4~8),`dispatch_web_request` 继续用默认池,二者隔离 —— 这一条单独就能防住"取消接口也卡死"。
|
||||
2. `GenerationService` 入口加进程级 `threading.BoundedSemaphore(max_concurrent_generations)`,取不到时快速返回 429 / `QUEUE_BUSY` 而非排队阻塞。
|
||||
3. `chat_workflow_service` 的 4 图并发改为复用全局生成池,不再每次新建。
|
||||
|
||||
### P1-8 · `profile_repository` 的 SQL 含字面量 `%`,PostgreSQL 后端下角色列表/详情 100% 报错
|
||||
|
||||
**位置** `database/repositories/profile_repository.py:46` / `:73` / `:99`(三份逐字重复);触发点 `get()` `:186-194`、`list()` `:218-232`
|
||||
|
||||
**问题**
|
||||
|
||||
```sql
|
||||
-- profile_repository.py:46(:73 / :99 完全相同)
|
||||
AND COALESCE(legacy_card_workflow.metadata_json, '') LIKE '%"final_archive_history_id"%'
|
||||
```
|
||||
|
||||
三处分别位于 `PROFILE_GENERATION_KIND_COLUMN`(32-57)、`PROFILE_CATEGORY_COLUMN`(59-84)、`DETAILED_WORKFLOW_STATE_COLUMN`(86-117),被拼进带参 SQL:
|
||||
|
||||
```python
|
||||
# profile_repository.py:186-194
|
||||
row = conn.execute(
|
||||
f"""
|
||||
SELECT {PROFILE_COLUMNS}, {PROFILE_GENERATION_KIND_COLUMN},
|
||||
{PROFILE_CATEGORY_COLUMN}, {DETAILED_WORKFLOW_STATE_COLUMN}
|
||||
FROM character_profiles
|
||||
WHERE profile_id = {placeholder}
|
||||
""",
|
||||
(profile_id,),
|
||||
).fetchone()
|
||||
```
|
||||
|
||||
`db_helper.py:288-290` 的 `_placeholder` 在 `backend == "postgresql"` 时返回 `%s`,psycopg 会把整条 query 当 %-format 模板展开;`%"` 是非法格式符。`_Psycopg2ConnectionAdapter.execute`(`db_helper.py:265-268`)写的是 `cursor.execute(query, tuple(params or ()))` —— 永远传元组,"无参跳过展开"这条退路也不存在。全仓 `grep "LIKE '%"` 只有这三处(其余命中都在 `.tmp/` 历史发布包里),是孤例。
|
||||
|
||||
**影响** `config.yaml:153-167` 明确把 `backend: auto|sqlite|postgresql` 作为受支持配置对外暴露。一旦切到 PG,`ProfileRepository.get()` 和 `.list()` 立刻抛 `ValueError: unsupported format character '"'`(psycopg2)或 IndexError(psycopg3),角色详情与角色列表完全不可用,且错误来自驱动层格式化,**完全指向不了根因**。
|
||||
|
||||
**修复**
|
||||
1. 立刻改成参数绑定:定义 `LEGACY_ARCHIVE_MARKER = '%"final_archive_history_id"%'`,SQL 里写 `LIKE {placeholder}`,调用处按 CASE 列出现次数补齐参数。
|
||||
2. 更彻底:把 `final_archive_history_id` 提升为 `profile_workflows` 的真实列(新增 0019 迁移 + 回填),同时解决转义和前缀通配符全表扫描(与 P2 表里 `profile_repository.py:32` 的 10 个相关子查询一起修)。
|
||||
3. 加静态断言测试:正则扫描 `database/repositories/*.py` 中未转义的裸 `%`(模式 `%(?!s)`)。
|
||||
|
||||
### P1-9 · `size` 请求字段全链路无人消费,聊天尺寸参数与高清修复静默失效
|
||||
|
||||
**位置** `engines/single_flow.py:61`(缺失 size→尺寸映射);写入侧 `backend/services/chat_workflow_service.py:63` 与 `:929`
|
||||
|
||||
**真实代码**
|
||||
|
||||
```python
|
||||
# engines/single_flow.py:56-61
|
||||
def generate(self, node: WorkflowNode, task: GenerationTask, request: dict[str, Any]) -> list[MockGeneratedAsset]:
|
||||
count = _bounded_count(request.get("count", 1))
|
||||
...
|
||||
width, height = _dimensions(str(request.get("aspect_ratio") or "1:1")) # ← 只读 aspect_ratio
|
||||
|
||||
# engines/single_flow.py:248-255
|
||||
def _dimensions(aspect_ratio: str) -> tuple[int, int]:
|
||||
if aspect_ratio == "3:4": return 768, 1024
|
||||
if aspect_ratio == "4:3": return 1024, 768
|
||||
if aspect_ratio == "16:9": return 1280, 720
|
||||
return 1024, 1024
|
||||
|
||||
# engines/single_flow.py:154-159 —— 全仓生产代码唯一构造 ImageGenerationRequest 的地方
|
||||
result = provider.generate_image(ImageGenerationRequest(..., size=f"{width}x{height}", ...))
|
||||
```
|
||||
|
||||
而写入侧写的是 `size`:
|
||||
|
||||
```python
|
||||
# chat_workflow_service.py:59-64(/yp 单图)
|
||||
payload={"prompt": ..., "negative_prompt": ..., "model_route": ..., "size": command.size, "count": ...}
|
||||
# chat_workflow_service.py:925-930(高清修复)同样写 size
|
||||
```
|
||||
|
||||
`generation_service.py:733` 的 `runtime_generation_request = {**payload, ...}` 原样透传 `size` 进 `task.request`,但全仓(排除 `.tmp/`、`tests/`)没有任何一处把 `size` 映射成 `aspect_ratio`。
|
||||
|
||||
**影响** `/yp 单图 ... --尺寸 4K` 与 `/yp 高清 <image_id> 4K` 都实际发出 `size="1024x1024"`。**高清修复的唯一价值(提升分辨率)完全失效**,用户只得到一张同尺寸重绘图。`astrbot_command_parser.py:49-52` 精心校验的 1K/2K/4K 参数是纯装饰,数据库记录的 width/height 也全是 1024。
|
||||
|
||||
**修复** 让 `size` 成为一等输入:
|
||||
|
||||
```python
|
||||
width, height = _resolve_dimensions(request.get("size"), request.get("aspect_ratio"))
|
||||
# _resolve_dimensions 先 re.fullmatch(r"(\d{2,5})\s*[x×]\s*(\d{2,5})", text) 解析 size 并 clamp 到 64..4096,
|
||||
# 解析失败再回退 _dimensions(aspect_ratio)
|
||||
```
|
||||
|
||||
补一条端到端断言测试,覆盖 `/yp 高清 <id> 4K` 产出的 `ImageGenerationRequest.size`。
|
||||
|
||||
### P1-10 · `displayMediaUrl()` 在 computed 与模板 render 中产生副作用
|
||||
|
||||
**位置** `frontend/standalone-web/src/App.vue:11146`(`displayMediaUrl`)+ `:11203-11225`(`resolveSignedMediaUrl`)+ `:997-1011`(`galleryImages` computed)+ `:4041`(唯一 revoke 点)
|
||||
|
||||
**问题** 看起来是格式化函数,实际同时做三件带副作用的事:读 `resolvedMediaUrls.value`(建立响应式依赖)、未命中时发起 HTTP 请求、请求返回后**整体替换** ref。它被 `galleryImages` computed(`:997`)、`selectedWorkflowRoundImageUrlByCandidateId`(`:2341`)、`workflowGenerationReviewImageUrlByCandidateId`(`:2352`)、`materialLibraryCardFromBackend`(`:5450`) 调用,也被模板经 `imageUrl()` 在 `:11668`/`:11693`/`:12826`/`:12865`/`:13961` 五处直接调用。这是 Vue 明令禁止的在计算属性/渲染中做副作用。
|
||||
|
||||
**真实代码**
|
||||
|
||||
```js
|
||||
// App.vue:11146
|
||||
function displayMediaUrl(rawUrl?: string | null): string {
|
||||
const value = String(rawUrl || "").trim()
|
||||
if (!value) return ""
|
||||
if (/^storage:\/\//i.test(value)) {
|
||||
const resolved = resolvedMediaUrls.value[value] // ← 建立响应式依赖
|
||||
if (resolved) return resolved
|
||||
if (!resolvingMediaUrls.has(value)) {
|
||||
const resolution = resolveStorageMediaUrl(value) // ← computed 里发请求
|
||||
.finally(() => { resolvingMediaUrls.delete(value) })
|
||||
resolvingMediaUrls.set(value, resolution)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
...
|
||||
}
|
||||
|
||||
// App.vue:11215 —— 每张图 resolve 完成后整体替换 ref
|
||||
const objectUrl = URL.createObjectURL(new Blob([bytes], { type: payload.content_type || "application/octet-stream" }))
|
||||
ownedMediaObjectUrls.add(objectUrl)
|
||||
resolvedMediaUrls.value = { ...resolvedMediaUrls.value, [rawUrl]: objectUrl, [sourceKey]: objectUrl }
|
||||
|
||||
// App.vue:997 —— 图库 computed 对全部图片逐张调用
|
||||
const galleryImages = computed<GalleryImage[]>(() => {
|
||||
const backendImages = uniqueImages([...]).filter(isAuthenticGenerationImage)
|
||||
return [...backendImages].sort(...).map((image) => ({
|
||||
...image,
|
||||
image_url: displayMediaUrl(image.image_url),
|
||||
thumbnail_url: displayMediaUrl(image.thumbnail_url),
|
||||
}))
|
||||
})
|
||||
```
|
||||
|
||||
**无法靠"后端返回普通 http URL"绕开**:`backend/routes/image_routes.py:213-232` 的 `_serialize_image` 显式把每条记录改写成签名 URL(`payload["image_url"] = _signed_url(media_service, image.image_uri)`),所以必然走副作用分支。
|
||||
|
||||
**影响**
|
||||
1. **O(N²) 重算**:`galleryImages` 依赖 `resolvedMediaUrls`,而它自己让 N 张图各触发一次 ref 整体替换 → 每张图解析完成都让整个 `galleryImages`(含排序 + N 次 `displayMediaUrl`)重跑。`loadGalleryImages`(`:4511`) 会拉全库所有页,1000 张图 ≈ 100 万次调用,`watch(galleryImages)`(`:4184`) 跟着抖 1000 次。
|
||||
2. **Blob 内存无界增长**:`ownedMediaObjectUrls` 只在 `onBeforeUnmount`(`:4041`) 统一 revoke,SPA 会话中浏览过的每张图完整二进制常驻内存直到关标签页。
|
||||
3. render 期间发请求:切主题、点通知等任何无关响应式变更重渲染时都可能补发媒体请求。
|
||||
|
||||
**修复** 把媒体解析从"渲染时惰性触发"改成"数据加载时显式预取":
|
||||
1. 新建 `composables/useMediaUrls.ts`,导出纯读表的 `mediaUrl(raw)` 和显式的 `prefetchMediaUrls(rawUrls[])`。
|
||||
2. 在 `loadGalleryImages` / `loadWorkflowRoundDetail` / `hydrateGenerationImages` 拿到数据后批量预取,一次 `resolvedMediaUrls.value = {...}` 写入全部结果(N 次 ref 替换压成 1 次)。
|
||||
3. 给 `resolvedMediaUrls` 加 LRU 上限(如 300 条),淘汰时 `URL.revokeObjectURL` 并从 `ownedMediaObjectUrls` 移除。
|
||||
4. `galleryImages` 改用纯查表的 `mediaUrl()`。
|
||||
|
||||
---
|
||||
|
||||
## 5. P2 汇总表(64 条)
|
||||
|
||||
> 标注「经复核降级」的条目,原判为 P1,复核确认机制属实但影响被夸大,按复核给出的严重度收录。
|
||||
|
||||
| 严重度 | 标题 | 位置 | 修复要点 |
|
||||
| --- | --- | --- | --- |
|
||||
| P2-中等(经复核降级) | reconcile_round 无条件回写状态与节点指针,迟到候选回调会"复活" superseded 父轮次 | `backend/services/workflow_round_service.py:806-861` | `_reconcile_round_locked` 先读 `round_record.status`,confirmed/superseded/cancelled 只更新 `metadata.execution_summary`;把 superseded 加入 `_ensure_writable_round_row` 不可写集合 |
|
||||
| P2-中等(经复核降级) | 轮次候选任务无任何重试路径:worker 侧 `max_attempts=1`,Web 侧 task_type 被硬拒 | `backend/services/workflow_round_worker_runtime.py:45` + `backend/routes/job_routes.py:195-220` | round pool 改 `RetryPolicy(max_attempts=3, ...)`;`_retry_task` 补 `source == "workflow_round"` 分派分支 |
|
||||
| P2-中等(经复核降级) | 存储根可配为任意绝对路径,VfsStorage 沙箱边界由可写配置决定 | `core/runtime_paths.py:43-45` + `core/storage.py:105-108` + `backend/services/settings_service.py:240-370` | `validate()` 增加 storage 段校验;或 `_root_paths()` 强制收敛到 `get_runtime_data_root()` 之下。见 §2 链路 A |
|
||||
| P2-中等(经复核降级) | `storage/migrate` 非 dry-run 可在可配置根之间任意复制/覆盖,且无审计 | `core/storage.py:45-63` + `:182-200`;入口 `backend/routes/storage_routes.py:36-47` | `will_overwrite and not payload.get("confirm_overwrite")` 时抛 ApiError;补审计日志;非 dry-run 提升为独立权限 |
|
||||
| P2-中等(经复核降级) | 配置快照把未脱敏的明文密钥写进数据库 `config_snapshots` | `backend/services/settings_service.py:614`(调用方 `:444`/`:556`) | 写入前脱敏为哨兵值(如 `***PRESERVED***`),rollback 时从 `before_file` 取回原值(`_merge_masked` 已有同类逻辑);加保留期清理 |
|
||||
| P2-中等(经复核降级) | 所有已登录 WebUI 用户被无差别授予 `can_manage_config` | `main.py:2337` | 与 P1-1 同源。最小动作:把 `can_manage_config` 从默认集合移除,改为 `security.config_admin_users` 白名单 |
|
||||
| P2-中等(经复核降级) | `dispatch_extension_request` 从不检查 `RouteMatch.permission` | `adapters/astrbot_adapter.py:171-187` + `backend/route_registry.py:365-377` + `main.py:1753` | 分发器内做集中式强制:取 `permission_requirement(match.permission)`,auth/permission 逐项校验;handler 内 `require_*` 保留为纵深防御;补 AST 元测试 |
|
||||
| P2-中等(经复核降级) | styleValidationReviewTrust 返回编码损坏的问号串,且已渲染到界面 | `frontend/.../AdvancedMaterialImportPage.vue:1304-1317`(渲染点 `:1656`) | 恢复三条中文文案;加测试:`features/` 下 `.vue` 不得出现连续 3 个以上 `?` 的字符串字面量 |
|
||||
| P2-中等(经复核降级) | 文本角色卡导入把「待整理」占位提示当真实设定写入档案,污染 base_prompt | `frontend/.../quick-profile/profile-import.ts:149-172` + `:336` + `App.vue:9710-9739` | 5 个 fallback 改空串,提示语移到 placeholder;或按 `draft.recognizedKeys` 过滤后再赋值 |
|
||||
| P2-中等(经复核降级) | 「仅本次会话使用、不写入配置」的 API Key 被前端写进 `settings/save` 请求体 | `frontend/.../settings/SettingsPage.vue:133`(承诺文案)+ `:98`(注入点) | 二选一:改用不落盘的探测链路(`api_discovery_service.py:229` 已支持读 `api_key_plaintext`),或修正承诺文案并加二次确认。`duplicateAdapter` 一律不复制会话密钥 |
|
||||
| P2-中等(经复核降级) | 快速角色问卷默认值是完整虚构示例角色,绕过 production-data-boundary 防线 | `frontend/.../quick-profile/profile-import.ts:32-59` + `App.vue:759` | `App.vue:759` 改用同文件 `:61` 已存在的 `createEmptyQuickProfileQuestionnaire()`;示例值降级为 placeholder;测试扫描目标扩到 `standalone-web/src` 全部 `.vue`/`.ts` |
|
||||
| P2-中等(经复核降级) | 素材绑定 schema 校验可被 `schema_version` 绕过,导致 material_bind 节点永久毒化 | `backend/services/material_binding_schema_service.py:47` + `:329` + `workflow_service.py:729-732` | 删掉 fast-path 或降级为仍逐条 `_normalize_rule`;`_index_by_node_key` 改用 `.get(...) or []`;把归一化提到 `update_node` 写库**之前** |
|
||||
| P2-中等(经复核降级) | 资产包清单可静默覆盖已有素材,并把未识别素材直接写成 `confirmed` | `backend/services/asset_import_service.py:141-152`(配合 `:340`、`:361-366`) | 导入素材 ID 一律服务端生成;覆盖需 `allow_overwrite` 且限同一 `package_uri` 来源;`recognition_status` 从清单剥离,一律落 `pending_recognition`;`_asset_uri` 校验 root 与 base_relative |
|
||||
| P2-中等(经复核降级) | 事件流轮询无重入保护,且在图库页每 5 秒触发整库分页重扫 | `App.vue:4561-4609` + `:4511-4542` + `:4600` | 加 `eventPollInFlight` 守卫;`loadGalleryImages` 加 `if (loadingGalleryImages.value) return`;轮询触发改增量;循环条件改按页数而非 `loaded.length` |
|
||||
| P2-中等(经复核降级) | 事件流 `slice(-1)` 在事件积压时静默丢弃最多 19 条事件 | `App.vue:4576` | 改为 `slice(previousIndex >= 0 ? previousIndex + 1 : 0)` —— 游标丢失时视全窗口为新事件;同时提高 `limit` |
|
||||
| P2-中等(经复核降级) | `handle_request` 吞掉全部非 ApiError 异常且不记日志,166 条路由内部错误彻底静默 | `backend/routes/common.py:12-16` + `backend/dto/common.py:75-83` | 分层捕获:ApiError 记 info,其余 `logger.exception("api internal error request_id=%s actor=%s", ...)`;`response_from_exception` 的 details 补 `request_id` 便于反查 |
|
||||
| P2-中等 | LLM 返回扁平结构时,候选偏好被静默丢弃(不报错、不回退确定性解析) | `backend/services/workflow_round_feedback_service.py:178` | 四个动作字段做双层回退 `feedback.get(k, parsed.get(k))`;全空但顶层存在同名键时抛 `WorkflowFeedbackInterpretationError` 触发确定性回退 |
|
||||
| P2-中等 | 确定性反馈解析器把普通数字当候选编号:静默误拒 / 合法反馈被 400 | `backend/services/workflow_feedback_interpreter.py:46` | 从 `_DISPLAY_CODE_OR_NUMBER_RE` 移除裸 `\d{1,3}`,要求前置标记(候选/第/#/No./张/号);越界数字忽略而非抛 `unknown_candidate_reference` |
|
||||
| P2-中等 | `create_next_round` 缺"一父轮次只能有一子轮次"守卫,可分叉多条优化链 | `backend/services/workflow_round_service.py:620` | 把 `superseded_by_round_id` 存在性检查移进 `create_round_with_candidates` 同一事务(已有 FOR UPDATE / BEGIN IMMEDIATE),或加 `(parent_round_id, round_kind)` 部分唯一索引 |
|
||||
| P2-中等 | `list_node_rounds` 的 N+1,且每次仓储调用新建一条 SQLite 连接 | `backend/services/workflow_round_service.py:982` | 加批量方法 `list_candidates_for_rounds(round_ids)` / `list_pool_for_rounds`;`ImageRepository`/`JobRepository` 加 `get_many(ids)`;中期加连接复用 |
|
||||
| P2-中等 | 交叉评审幂等重放只按 `idempotency_key` 全表匹配,可命中另一节点/另一种轮次 | `database/repositories/workflow_cross_review_repository.py:969` | `_round_replay` 增加并校验 `round_kind` / `node_id` / `workflow_id` / `parent_round_id`,不匹配抛 `idempotency_key_conflict`(主轮次侧 `workflow_round_service.py:94-114` 已有正确写法) |
|
||||
| P2-中等 | 跨评审 skip 由三段独立事务组成,中途失败留下"已跳过但未定稿"死锁态 | `backend/services/workflow_generation_cross_review_service.py:416` | 合并「记录 skip + 确认候选」为一个事务;或引入 `decision_state='pending_confirm'` 中间态并允许撤销;`create_review_round_atomic` 加 `decision == 'skip'` 互斥校验 |
|
||||
| P2-中等 | `apply_feedback_atomic` 把旧 `_conversation` 无条件带到新快照,复用过期 prompt patch | `database/repositories/workflow_round_repository.py:710` | 结构化 updates 写入时显式 `feedback_snapshot.pop("_conversation", None)`;或在 `_conversation` 记录写入序号与 pool revision,`create_next_round` 只在最新时采用 |
|
||||
| P2-中等 | `recover_stale_tasks` 只在 worker 启动时执行且只认 `source=workflow_round` | `backend/services/queue_service.py:470` | source 过滤改可选白名单,纳入 `nodes.generate`(恢复动作为标 failed + 释放节点);增加周期性巡检;恢复时同步修复 `workflow_nodes.status` |
|
||||
| P2-中等 | `recover_stale_tasks` 无重试上限,会跨进程重启无限重排队 | `backend/services/queue_service.py:481` | metadata 维护 `recovery.attempts` 累加,超阈值(如 3)迁 `dead_letter` 并写明原因;返回值报告 `dead_lettered` 列表 |
|
||||
| P2-中等 | 轮次候选的 `timeout_seconds` 只写进 metadata,执行时从未被读取 | `backend/services/generation_service.py:355` | `execute_claimed_generation` 构造 runtime_request 时 `setdefault("timeout_seconds", task.metadata.get("timeout_seconds"))`;`run_once` 外层加看门狗 |
|
||||
| P2-中等 | worker 执行成功但回写失败时,已落库的图片记录被孤立且不清理 | `backend/services/worker_service.py:104` | 把「落库图片」与「回写任务」放进同一补偿边界:`_execute` 捕获回写失败后调 `_cleanup_generation_outputs`,或返回 image_ids 交 `_on_terminal` 清理 |
|
||||
| P2-中等 | 自研 YAML 往返不等价:空列表退化为字典、注释全丢(已用仓库 config.yaml 实测) | `core/config_writer.py:50` | `dump_yaml` 对空容器显式输出 `key: []` / `key: {}`;或引入 ruamel.yaml round-trip;至少加 `dump(load(x)) == 归一化(x)` 属性测试 |
|
||||
| P2-中等 | `save()` 把打包默认值固化进可写配置,插件升级后新默认值永久失效 | `backend/services/settings_service.py:423` | 写盘基线改用只读可写文件的 loader(跳过打包合并),只把用户显式提交的 diff 落盘 |
|
||||
| P2-中等 | `write_text_atomic` 的 `os.replace` 重置配置文件权限,临时文件短暂全局可读 | `core/config_writer.py:32` | `os.open(path, O_WRONLY|O_CREAT|O_EXCL, 0o600)` 创建临时文件并 `os.fsync`;replace 前用 `os.chmod` 继承目标既有权限位 |
|
||||
| P2-中等 | 群聊日配额统计全表扫描 + Python 侧 JSON 解析 | `backend/services/chat_command_guard_service.py:75` | 建 `chat_command_quota(day, scope_type, scope_id, count)` 计数表 + UPSERT;把配额 action 从通用 `chat_command_allowed` 拆成 `chat_generation_allowed` |
|
||||
| P2-中等 | `remote_fetch` 的 SSRF 防护存在 DNS TOCTOU(rebinding)窗口 | `core/remote_fetch.py:73` | 把校验通过的 IP 固定下来再连接(自定义 HTTPConnection 覆写 connect,Host/SNI 保留原主机名);或在 `http_response` 钩子里用 `getpeername()` 复核对端 IP |
|
||||
| P2-中等 | 分页之后再过滤,total 与页大小失真 | `backend/routes/job_routes.py:36`(`image_routes.py:45-49` 同) | 把可见性下推到仓储 WHERE:`JobRepository.list(..., exclude_sources=(...))`、`ImageRepository.list_images(..., include_restricted)` |
|
||||
| P2-中等 | 缩略图是原图的字节级完整拷贝,存储与带宽直接翻倍 | `engines/single_flow.py:178` | 新增 `_write_thumbnail(uri, image_bytes, max_edge=512)`,用已作为可选依赖存在的 Pillow 等比缩放;不可用时写原图并打 `thumbnail_downscaled: False` |
|
||||
| P2-中等 | vision provider 链路完全没有错误分类与可重试判定,`retryable` 是死代码 | `backend/services/material_service.py:863` | 把 `core/generation_errors.py` 的 `_category`/`_is_retryable`/`_safe_details`/`_safe_message` 提成与异常类型无关的公共函数,新增 `vision_failure_attribution` 共用 |
|
||||
| P2-中等 | vision 请求体无上限,8 张 20MB 图可构造约 213MB 的单次 JSON 请求 | `engines/vision_provider.py:294` | 新增 `MAX_VISION_REQUEST_BYTES`(如 32 MiB),`_post_json` 内超限抛 `VisionProviderError(error_type="invalid_request")`;更好是按张数 × 单张预算约束并先降采样 |
|
||||
| P2-中等 | 三处 fallback 对所有错误一视同仁地换 provider,含不该重试的鉴权/配置错误 | `engines/image_provider.py:191`(另 `model_provider_runtime.py:180-189`、`:264-271`) | 让 `_is_retryable` 成为 fallback 准入条件:`if not attribution["retryable"]: raise`,鉴权/配置/请求错误立即上抛,不消耗其余 provider |
|
||||
| P2-中等 | `structured_text_callable` 用裸 `json.loads` 解析模型输出,缺 vision 侧已有的容错 | `backend/services/model_provider_runtime.py:246` | 把 `vision_provider._json_from_text`(`:398-429`,已实现剥 BOM / 截 `{...}` / 去尾逗号 4 个候选)提到 `core/llm_json.py`,三处共用 |
|
||||
| P2-中等 | 单条聊天消息内的图片数量无上限,放大为 N 次下载 + N 次视觉大模型调用 | `adapters/astrbot_media_adapter.py:12` | `image_references_from_event` 内部截断(`MAX_CHAT_IMAGE_REFERENCES = 4`,与 `MAX_VISION_IMAGES` 对齐);`import_material` 也走 `guard.check_generation` / `guard.record` |
|
||||
| P2-中等 | 聊天身份未按平台命名空间隔离,跨平台同 ID 可互相访问档案 | `backend/services/chat_workflow_service.py:1157` | `user_id=f"{chat.platform or 'astrbot'}:{chat.user_id}"`,WebUI 侧用 `webui:` 前缀;配套一次性迁移脚本按 source 回填 |
|
||||
| P2-中等 | 聊天卡片 PNG 缓存目录无淘汰机制,用户可任意撑爆磁盘 | `adapters/astrbot_card_renderer.py:59` | `CARD_DIR` 加 LRU 上限(超 500 按 `st_mtime` 删最旧);或改为渲染到 `BytesIO` 直接投递不落盘;`lines` 长度与条数做截断 |
|
||||
| P2-中等 | 无组合根导致每次路由调用都重读 `config.yaml` 并重建整棵对象树 | `database/db_helper.py:297`(34 处 `Database(load_database_settings())`) | `load_config_payload` 加进程级缓存(按 `(path, mtime)` 失效),`set_runtime_config_overrides` 时主动 invalidate;组合根持单例 service 图 |
|
||||
| P2-中等 | 跨仓储组合写无事务边界:删图与清 node 指针分属两次提交,且 `selected_image_id` 无外键 | `backend/services/image_service.py:216` | 下沉成 `ImageRepository.delete_with_node_release(image_id)`,同连接内 DELETE + UPDATE 一次 commit(照抄 `job_repository.delete_if_status:382-431`);补 0019 迁移加外键 `ON DELETE SET NULL` |
|
||||
| P2-中等 | 陈旧任务恢复的时间戳比较绑死 SQLite 的 UTC 语义,PostgreSQL 下静默失效 | `backend/services/queue_service.py:457` | 时间差在 SQL 侧算:SQLite 用 `datetime('now', ?)`,PG 用 `NOW() - (?::text)::interval`,按 `Database.backend` 分派;或统一迁 TIMESTAMPTZ + 建连 `SET TIME ZONE 'UTC'` |
|
||||
| P2-中等 | `MaterialAnalyticsService.summarize` 无条件全表扫描 9 张表,含大 JSON 列 | `backend/services/material_analytics_service.py:16` | 加时间窗参数(默认 30 天)+ `idx_generation_tasks_created`;能下推的统计改 `GROUP BY` + 聚合函数;结果加秒级过期缓存 |
|
||||
| P2-中等 | `profile_repository` 每行 10 个相关子查询,同一组谓词复制三份并已开始漂移 | `database/repositories/profile_repository.py:32` | 用 LEFT JOIN 派生表把三个 EXISTS 结果算一遍再在外层 CASE 复用(子查询 10→3);与 P1-8 的列提升合并做 |
|
||||
| P2-中等 | `normalize_category` 用子串匹配推断类别:landscape 判成 headwear、rooftop 判成 top | `backend/services/material_normalization_service.py:314` | 别名匹配改词边界 + 按长度降序:ASCII 用 `re.search(rf"(?<![A-Za-z0-9]){re.escape(alias)}(?![A-Za-z0-9])", text)`,CJK 保持子串;`_build_profile` 不再拿整段 prompt 猜类别 |
|
||||
| P2-中等 | `list_catalog` 每次分页请求都把两张素材表整表读入内存再切片 | `backend/services/advanced_material_service.py:605` | 过滤排序下推 SQL,两库用 `UNION ALL` + 统一排序在数据库层 LIMIT/OFFSET;`metadata_json` 里的过滤键用 `json_extract` 生成列 + 索引 |
|
||||
| P2-中等 | 素材统计里的风格集口径完全失效:`workflow_kind` 常量对不上,导入数恒为 0 | `backend/services/material_analytics_service.py:168` | 从 `advanced_style_set_service` 导入 `STYLE_SET_KIND`(`= "advanced_style_set"`)比较,保留旧值兼容分支;根本做法是把它下沉成 `advanced_material_imports` 的真实列 |
|
||||
| P2-中等 | 导入列表接口的队列对账是 N+1,且单条详情会重复对账两次 | `backend/services/advanced_material_service.py:212` | `detail()` 加 `reconcile: bool = True`,`get_import` 传 False;`QueueService` 加 `get_jobs(task_ids)` 批量查;列表接口不做对账,改后台定时或显式刷新 |
|
||||
| P2-中等 | 衣柜导入把所有 `sqlite3.IntegrityError` 一律当成重复条目 | `backend/services/wardrobe_service.py:379` | 检查 `sqlite_errorcode == sqlite3.SQLITE_CONSTRAINT_UNIQUE`(Py3.11+)或 `"UNIQUE constraint failed" in str(exc)`;非唯一约束一律 raise;仓库路由改用服务端赋值的 `metadata["library_kind"]` |
|
||||
| P2-中等 | `update_material` 中的结构校验会把 `MaterialNormalizationError` 泄漏成 500 | `backend/services/material_service.py:246` | 第二处 `validate_material_structures(metadata)` 也包 try 转 `ApiError(VALIDATION_FAILED)`;并把"提取结构键→合并→校验"与 `validate_material_payload` 合并成一个函数 |
|
||||
| P2-中等 | Pillow 缺失时风格集共识会把多张原图以 base64 全量载入单个请求 | `backend/services/material_service.py:786` | 为送模型的图设独立硬上限(如 `VISION_INPUT_MAX_BYTES = 3 MB`):Pillow 可用则缩放后仍超限继续降质,不可用且超限直接抛 `UPLOAD_TOO_LARGE` 并提示安装;共识阶段改流式逐张编码 |
|
||||
| P2-中等 | 模板中残留字面量 `\n` 字符串,在「创建角色档案问卷」弹窗标题栏渲染出可见 `\n` | `frontend/standalone-web/src/App.vue:13091` | 替换成真正的换行;CI 加 lint:模板段内出现 `\\n` / `\\t` 字面量即失败 |
|
||||
| P2-中等 | `loadCharacterWorkflowForProfile` 的缓存命中分支无条件重拉分支列表 | `frontend/standalone-web/src/App.vue:7273` | 抽出 `ensureWorkflowBranches(workflowId)`,`watch(:4111)` 与 `:7273` 共用同一守卫 |
|
||||
| P2-中等 | `VisionProviderConfig.endpoint_url` 缺 `/v1` 去重,base_url 以 `/v1` 结尾时视觉请求 404 | `engines/vision_provider.py:40` | 把 `endpoint_url` 提到 `engines/_provider_base.py` 的 `join_endpoint(base_url, endpoint)`,image / vision / `model_provider_runtime.py:210-216`、`:297-303` 三处共用 |
|
||||
| P2-中等 | `_signed_url` 复制 7 份,异常范围不一致且其中一份每张图新建一次 MediaService | `backend/routes/advanced_material_routes.py:428`(另 6 处见下) | 在 `MediaService` 上加实例方法 `signed_url(self, uri) -> str | None`,7 处(`image_routes:226`、`material_routes:317`、`profile_card_routes:90`、`round_routes:192`、`workflow_round_worker_runtime:257`、`dashboard_service:89`)全部改调它 |
|
||||
| P2-中等 | `tests/test_material_vision_input.py` 无条件 import Pillow,而 Pillow 是可选依赖 | `tests/test_material_vision_input.py:6` | 改 `pytest.importorskip("PIL")`;新建 `requirements-dev.txt` 钉版本,`requirements.txt` 保持零依赖 |
|
||||
| P2-中等 | SQLite 未开启 WAL,却跑 13 个并发写线程,全靠 30 秒 busy_timeout 硬扛 | `database/db_helper.py:159` | `connect()` 补 `PRAGMA journal_mode = WAL` 与 `PRAGMA synchronous = NORMAL`;`initialize()` 配 `wal_autocheckpoint`。(注:复核已否定"必然阻塞全库读"的机理,这里按吞吐调优而非缺陷修复对待) |
|
||||
| P2-中等 | 每次队列 claim 开 2 个新连接;13 个 worker 空转时约 43 次 connect + COUNT(*) / 秒 | `backend/services/worker_service.py:207` | `JobRepository` 加 `list_items_only(...)` 跳过 COUNT(*);`claim_queued_task` 的 get+update 合成单条 `UPDATE ... WHERE status='queued'`(PG RETURNING / SQLite changes());加线程本地连接复用;idle 指数退避 |
|
||||
| P2-中等 | 前端 direct-fetch 路径完全没有超时,与 plugin-bridge 路径行为不一致 | `frontend/shared/api/client.ts:81` | direct-fetch 分支复用同一套超时常量,用 `AbortController` + `signal`,`AbortError` 映射成 `ApiClientError("bridge_timeout", ...)` |
|
||||
| P2-中等 | `cost_service` 对 `generation_images` 做无 LIMIT 全表扫描,days 过滤在 Python 侧 | `backend/services/cost_service.py:186` | 时间窗下推 SQL(`created_at >= ?`)并加 `LIMIT`(如 20000,超出标 `truncated=True`);长期把 token 数拆成数值列或建汇总表 |
|
||||
| P2-中等 | 高级素材详情 N+1:按 attempt 循环查子表,每次新开数据库连接 | `backend/services/advanced_material_service.py:228` | 加 `list_style_validation_cases_by_attempts(attempt_ids)` 用 `WHERE attempt_id IN (...)` 一次查完;`:258-263` 的 `get_material` 双调改局部变量(顺带消除 TOCTOU) |
|
||||
| P2-中等 | `ChatSessionStore` 构造期无保护地做 naive/aware datetime 比较,脏文件让插件启动崩 | `backend/services/chat_session_service.py:76` | 解析处强制归一化时区:`parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)`。仓库内 `cost_service._parse_datetime` / `worker_service._retry_deferred` / `integration_token_service._parse_time` 三处已写对,应抽成 `core/` 公共函数 |
|
||||
|
||||
---
|
||||
|
||||
## 6. P3 汇总表(30 行 = 收录的 19 条 + 11 条复核推翻后的残留技术债)
|
||||
|
||||
> 本表 19 条计入清单总数(P3 = 19)。另有 11 行标注「经复核降级」且**不计入总数** —— 它们是被复核推翻的发现,原缺陷不成立,此处只保留复核明确认可的残留技术债,供后续重构参考。
|
||||
> `QueueService.update_task() 无 CAS` 一条例外:它未被推翻(复核维持成立),只是从 P1 下调到 P3,**计入总数**。
|
||||
|
||||
| 严重度 | 标题 | 位置 | 修复要点 |
|
||||
| --- | --- | --- | --- |
|
||||
| P3-轻微(经复核降级) | `update_round` 无终态白名单,依赖调用方前置守卫兜底 | `backend/services/workflow_round_service.py:81` / `:928-940` | 复核确认 `create_round:81` 的 `_ensure_round_creation_allowed` 已拦死 confirmed 节点,攻击链不可达。残留问题是"守卫与写入分离、易被后续重构打破":给 `update_round` 加终态白名单校验 |
|
||||
| P3-轻微(经复核降级) | `QueueService.update_task()` 无 CAS | `backend/services/queue_service.py:406-411` | 复核确认 `worker_service.py:106-115` 的 cancelled 早退 + `core/fsm.py:38` 的 FSM 校验已把窗口压到两条相邻语句之间。收尾动作:worker 三处写入改用已有的 `update_task_if_status` |
|
||||
| P3-轻微(经复核降级) | 插件重载后旧 worker 线程仍存活 | `backend/services/worker_service.py:191-206` + `queue_service.py:439+` | 复核确认旧线程停止后不再认领新任务、不累积。残留:`stop()` 返回 `running=True` 时记日志/告警;`recovery` 跳过本进程仍存活的 worker_id |
|
||||
| P3-轻微(经复核降级) | 所有 service 在 `require_*` 之前构造 | `backend/routes/node_routes.py:140`;残留问题在 `adapters/astrbot_adapter.py:171-187` 与 `main.py:315-344` | 复核确认生产两个 ingress 都在构造前完成准入判定,"未授权即触发重型初始化"不可达。残留:给分发器加兜底 try;只读 GET 不应跑 `sync_generation_provider_from_config`(`model_provider_bootstrap.py:68,79` 会 upsert 写库) |
|
||||
| P3-轻微(经复核降级) | `POST profiles/{id}/archive` 实际执行删除 | `backend/routes/profile_routes.py:109-114` | 复核确认前端唯一调用方是红色"删除"按钮(`ProfileDetailPane.vue:190-198`),用户意图与后端行为一致,无数据事故。残留:REST 路径命名误导且与契约文档不符。**不要改成写 `status="archived"`** —— 那会让删除按钮不删除,引入真实回归 |
|
||||
| P3-轻微(经复核降级) | 内容安全审核 provider 解析缺 `provider_type` 校验 | `backend/services/model_provider_runtime.py:285` | 复核指出"安全审核静默绕过"方向写反了:现状是 fail-closed(异常降级为 quarantine)。**修复时必须同时处理 `reviewer is None 即放行` 的语义**,否则会引入比原问题更严重的缺陷 |
|
||||
| P3-轻微(经复核降级) | `metadata_json` 整列覆盖 + 跨连接读改写 | `backend/services/generation_service.py:1869-1886` | 复核确认服务层 `_normalize_workflow_metadata`(`workflow_service.py:1027-1031`、`:1058-1068`)已从新鲜快照强制回填 `branch_state` / `character_execution`,仓储整列覆盖被消解。残留:失败回写的 check-then-act 改用已有的 `update_node_if_status` |
|
||||
| P3-轻微(经复核降级) | `_string_list` 多份实现语义不一 | `backend/services/workflow_round_service.py:1544` / `core/astrbot_provider_bridge.py:344` / `advanced_style_set_service.py:4288` | 复核确认真实是 17 处(多算的在 `.tmp/` 构建快照里)、无跨模块导入、无数据流交汇,三条影响均不可达。唯一实证不一致是 `VisionRecognitionResult.tags` 的三个构造点排序不同,下游只当集合用。按可维护性收敛即可 |
|
||||
| P3-轻微(经复核降级) | 模型路由解析链前端重实现 | `frontend/.../workflow/workflow-model-route.ts:36-88` | 复核确认 round 层是对 `workflow_round_service.py:596-597` 的正确镜像,缺 `image_low` 是刻意 fail-safe(返回空串触发 `App.vue:8492-8495` 的硬闸门),quick_* 节点永不进入该标签链。残留:前端复刻映射表的配置键耦合,理想做法是后端下发 `effective_model_route + source` |
|
||||
| P3-轻微(经复核降级) | retry 类操作前端权限门禁漏判 `can_write` | `frontend/standalone-web/src/App.vue:3073-3077` / `:3136-3140` | 复核确认"有 can_retry_tasks 无 can_write"的组合在本仓库造不出来,且 `backendWriteBlockMessage`(`:4376-4387`)会在本地拦下。残留:文案 tone 不精确。彻底做法是按 contract 的 `required_permissions` 构造统一 `canCall(method, endpoint)` |
|
||||
| P3-轻微(经复核降级) | `events/stream` 无游标 | `App.vue:4575-4582` + `backend/services/event_stream_service.py:22-32` | 复核确认全仓事件只有 `generation.` / `workflow.` 两个前缀,OR 归约不可能因丢事件翻假;轮次面板另有 4 秒自续轮询(`App.vue:6999-7008`)。残留:接口无游标、`body`/`content_type` 白费序列化、`slice(..., -1)` 魔数写法 |
|
||||
| P3-轻微(经复核降级) | `ApiError` 是继承 Exception 的 dataclass,`str(exc)` 返回元组 repr | `backend/services/chat_workflow_service.py:903` | 复核确认 `main.py` 内 `grep -c ApiError` = 0,且 `handle_request` 用 `self.message` 而非 `str(exc)`、`_data`(`:1166-1170`)整体丢弃 details。残留仅 1 处绕过 dispatcher 的直调(对应 `main.py:1134` `/yp 审核`),且 details 只含内部 ID。给 `ApiError` 加显式 `__str__` 即可 |
|
||||
| P3-轻微 | 反馈幂等日志按字典序而非时间序裁剪,会淘汰较新的 key | `database/repositories/workflow_round_repository.py:726` | 按记录里已有的 `updated_at` 排序后再 `[-20:]` |
|
||||
| P3-轻微 | `_ensure_round_enqueued` 的元数据回写在 `_reconcile_lock` 之外 | `backend/services/workflow_round_service.py:928` | 把末尾读-改-写包进 `with self._reconcile_lock:`,或改用仓储条件更新(只更 `task_ids`/`planned_only` 两个键) |
|
||||
| P3-轻微 | 未加引号的配置标量会被 `os.path.expandvars` 展开 | `database/db_helper.py:445` | 只对显式引用语法(`env:NAME` / `${NAME}`)展开,其余原样返回;`core/secret_service.resolve_env_value` 已有这套语义可复用 |
|
||||
| P3-轻微 | 媒体令牌置于 URL 查询串且 payload 内不含签发者标识 | `core/media_proxy.py:51` | payload 增加 `actor_id` 并在 `_resolve_token` 与当前 ctx 比对;响应加 `Referrer-Policy: no-referrer` |
|
||||
| P3-轻微 | `public_token` 权限档与实际暴露面不符,`media/fetch` 绕过分发器不留审计 | `main.py:329` | 把 `public_token` 描述改为"签名 token + 宿主鉴权"以与实际一致;提前返回前记一条 LogService 媒体访问日志(含 request_id、actor、uri) |
|
||||
| P3-轻微 | 装配分散导致 `WorkflowService` 实例行为不一致,素材绑定事件被静默丢弃 | `backend/routes/node_material_routes.py:69`(另 `branch_routes.py:64`、`history_routes.py:72`、`review_routes.py:90`) | 4 处工厂补 `event_bus=get_default_event_bus()`;让 `WorkflowService.event_bus` 默认取全局总线;禁止 `self.<other_service>.event_bus` 穿透写法;加装配断言测试 |
|
||||
| P3-轻微 | `generation_service` 内部 `event_bus` 取用方式自相矛盾 | `backend/services/generation_service.py:1416` | `:1416-1427` 改用 `self._publish(...)`,删除 `self.workflow_service.event_bus` 引用 |
|
||||
| P3-轻微 | 关键词过滤未转义 LIKE 通配符 | `database/repositories/profile_repository.py:305`(`advanced_material_repository.py:493-498` 同) | 转义 `\` `%` `_` 后再拼接,SQL 侧加 `ESCAPE '\'` |
|
||||
| P3-轻微 | `list_stale` 与图库列表的排序键与现有索引不匹配 | `database/repositories/job_repository.py:191` | 补 0019 迁移:`idx_generation_tasks_status_updated(status, updated_at)`、`idx_images_profile_archived(profile_id, is_archived, created_at DESC)` |
|
||||
| P3-轻微 | GalleryPage 批量操作串行执行且完全吞掉错误 | `frontend/.../gallery/GalleryPage.vue:121` | 收集 `failures`,用 `Promise.allSettled` + 并发上限(5)替代串行;失败 id 保留在 `checkedIds` 并展示前几条原因 |
|
||||
| P3-轻微 | 归档素材在标准库与进阶库产生两种不同的错误语义 | `backend/services/material_catalog_resolver.py:75` | `_normal_material` 前补 `if material.recognition_status == "archived": return None`;`_resolve_material_references` 的 404 加 `"reason": "material_missing_or_archived"` |
|
||||
| P3-轻微 | `deleteSelectedProfile` 遗漏清理 6 个 per-profile 缓存 Map | `frontend/standalone-web/src/App.vue:6316` | 合并成 `purgeProfileCaches(profileId)` 辅助函数,与 `invalidateProfileDetailsRequests` / `invalidateProfileWardrobeRequests` 共用 |
|
||||
| P3-轻微 | `EventStreamService._event_to_webhook` 造两次对象再丢弃一次 | `backend/services/event_stream_service.py:42` | 直接构造 `WebhookEvent(event_type=..., data=..., event_id=event.event_id, created_at=event.created_at)`;`core/webhook.py:48-49` 的 `event_from_bus` 随之成死代码,一并删 |
|
||||
| P3-轻微 | 节点写锁规则前后端不一致,前端判据含后端从不产出的 `sealed_at` | `frontend/.../workflow/workflow-lock-state.ts:12,21-27` | 复核确认 `sealed_at` 是 OR 链里的恒 undefined 项,只会多加锁不会漏加锁;`adopt-image` 路径两边一致(`history_service.py:55` 同时写 status+selected_image_id)。彻底做法:`WorkflowNode.to_dict()` 下发 `writable` + `lock_reason`(`workflow.ts:108-123` 已有同形状结构可复用) |
|
||||
| P3-轻微 | `_Psycopg2ConnectionAdapter.execute` 每次新建 cursor 且从不关闭 | `database/db_helper.py:305` | 返回包装对象在 fetch 后自动 close;至少加 try/except 在抛错时 `cursor.close()` 后 re-raise |
|
||||
| P3-轻微 | 每个请求重排 166 条路由 + 逐条编译正则 + `inspect.signature`,全程无缓存 | `adapters/astrbot_adapter.py:47` | 模块加载时预编译 `dict[method] -> [(pattern, RouteSpec)]` 并预排序;`_load_handler` 加 `lru_cache`;handler 参数绑定方案导入时算一次缓存到 RouteSpec |
|
||||
| P3-轻微 | `log_service` / `cost_service` 的 `_json_loads` 无异常保护 | `backend/services/log_service.py:297` | 改 `try: json.loads(v) except (ValueError, TypeError): return {"_parse_error": True, "raw_preview": str(v)[:200]}` |
|
||||
| P3-轻微 | `EventBus.publish` 不隔离订阅者异常 | `core/event_bus.py:48` | `handler(event)` 包 try/except + `logger.exception`;顺带修 `unsubscribe`(`:41-43`)对未订阅类型凭空建键的问题 |
|
||||
|
||||
---
|
||||
|
||||
## 6.1 终审补录:跨维度被漏收的条目(**不计入上表 94 条**)
|
||||
|
||||
> 本清单原按 `category ∈ {bug, security, perf}` 收录。终审逐条回扫 `_raw.json` 全部 214 条发现后,确认下列 10 条虽被归类为 `hygiene`/`coupling`,但**内容属于正确性、安全或性能范畴**,前四份主报告均未收录。补录于此,严重度沿用原判(这些条目未进入 P0/P1 复核批次,除非另行注明)。
|
||||
|
||||
| 严重度 | 维度 | 标题 | 位置 | 修复要点 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| P2-中等 | A5 核心与安全 | `ProfileService._require_owner` 不认管理员权限,与 `ResourceAccessService._can_access` 语义相反 —— 同一套归属校验在两处给出相反答案,**做 §4 P1-2 的 IDOR 改造时必须先统一,否则会把矛盾扩散到五条链路** | `backend/services/profile_service.py:160` | 让 `_require_owner` 复用 `ResourceAccessService._can_access`(含 `can_manage_all_profiles` 分支),删除本地实现 |
|
||||
| P2-中等 | A1 生成与队列 | `_BoundedWorkerHandler` 的并发限流在生产配置下**完全是空操作**,且限流点位于「认领之后」——任务已被 CAS 认领才去抢信号量,抢不到只能阻塞持锁等待 | `backend/services/worker_service.py:400` | 限流点前移到 `_claim_next` **之前**;上限从生产配置真实读取而非落到默认无界值。与 §5 的 `generation_service.py:119` 背压项(阶段 2 的 2-8)同一个 PR 做 |
|
||||
| P2-中等 | C4 横切 | 主动通知全链路静默失败:签名失败返回 `None`、发送失败返回 `False`、terminal 回调静默 `return`,**一行日志都没有** —— 用户不会收到轮次完成通知,运维也无从得知 | `backend/services/workflow_round_worker_runtime.py:262` | 三个失败出口各补 `logger.warning`(含 round_id / task_id / 失败阶段);随阶段 2 的日志基座一起做 |
|
||||
| P2-中等 | C4 横切 | AstrBot 桥接与配置覆盖是**进程级模块全局变量**,热重载与测试隔离困难(插件 reload 后旧桥接对象可能残留) | `core/astrbot_provider_bridge.py:22` | 收进一个显式的 runtime 持有者对象,由组合根(03 报告 §1.4.4)注入;`set_*` 提供对应的 `reset_*` 供测试用 |
|
||||
| P3-轻微 | A4 数据层 | PostgreSQL 迁移执行器**按分号裸切分** SQL —— 迁移脚本里只要出现函数体、`DO $$ ... $$` 或字符串内的分号就会被切错,静默执行半条语句 | `database/db_helper.py:280` | 改用驱动自身的多语句执行,或在迁移文件里显式声明语句边界。与 §4 P1-8 的 PG 兼容性一并验证 |
|
||||
| P3-轻微 | A6 引擎与适配器 | `_match_endpoint` 未对路由字面量做 `re.escape` —— 端点模板里一旦出现正则元字符(`.`、`+`、`(`)就会产生非预期匹配 | `adapters/astrbot_adapter.py:226` | 对非 `{param}` 段一律 `re.escape`;与 §6 的路由表预编译缓存(`astrbot_adapter.py:47`)同一处改 |
|
||||
| P3-轻微 | A3 素材 | 衣柜分类无白名单校验;`delete_item` 用 `assert` 做并发保护 —— **`python -O` 下 assert 被整体剥除,保护直接消失** | `backend/services/wardrobe_service.py:128` | `assert` 换成显式 `if ...: raise ApiError(...)`;分类值加白名单(复用 `material-labels` 的分类集合) |
|
||||
| P3-轻微 | A5 核心与安全 | 敏感键匹配把 `"key"` 当子串 —— `sort_key`、`route_key`、`node_key` 等普通配置项被误当密钥脱敏,配置页显示 `***` 却无法编辑 | `backend/services/settings_service.py:26` | 改为按完整路径白名单或后缀匹配(`_api_key` / `_token` / `_password` / `_secret`) |
|
||||
| P3-轻微 | A1 生成与队列 | `cancel_job` 的重读循环**无次数上限与退避** —— 与 worker 高频写入竞争时可能长时间空转 | `backend/services/queue_service.py:135` | 加最大重试次数(如 5)与指数退避,超限抛 `ApiError(CONFLICT)` 让调用方重试 |
|
||||
| P3-轻微 | A2 工作流与轮次 | approve 响应里对同一个 `next_node_id` 重复查询节点 | `backend/services/workflow_generation_cross_review_service.py:262` | 查一次存局部变量复用 |
|
||||
|
||||
**前端侧另有 3 条被漏收**(归 `coupling`/`hygiene`,已在 03/04 的收敛方案中间接覆盖,此处仅登记):`ProfilesPage.vue:10` 三层 prop drilling(24 props / 13 emits,其中 16 个纯透传)、`ProfileWardrobePane.vue:249` 状态归属分裂(衣橱条目走 props/emits 而套装模板自己调 API)、`App.vue:10504` `queueBatchActionMessage` 内的局部 `errorMessage` 遮蔽同名全局工具函数。
|
||||
|
||||
---
|
||||
|
||||
## 7. 按子系统的缺陷密度
|
||||
|
||||
| 子系统 | 缺陷数 | P0 | P1 | P2 | P3 | 规模参照 | 判断 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| `backend/services/` | **42** | 0 | 3 | 33 | 6 | 70 个文件,`advanced_style_set_service.py` 单文件 4491 行 | **最需要重构。** 缺陷占全部 45%,且高度集中在轮次/队列/素材三条链上。根因不是单点 bug,是没有组合根(34 处各自 `Database(load_database_settings())`)、状态机守卫与写入分离、N+1 与整表加载成为默认写法 |
|
||||
| `database/`(仓储 + db_helper) | **12** | 0 | 2 | 5 | 5 | 131 处重复的 connect/execute/close 样板 | 次要重灾区。PG 兼容性(字面量 `%`、时间戳语义)在两处已实证会崩;连接管理缺失是 `backend/services/` 一半性能问题的下游放大器 |
|
||||
| `core/` | **7** | 0 | 0 | 5 | 2 | — | 安全边界几乎全在这里(runtime_paths / storage / config_writer / remote_fetch / media_proxy),且**每一条都是"约束缺失"而非"逻辑写错"**。§2 两条攻击链的 3 个断链点全在此目录 |
|
||||
| 前端 `App.vue` | **6** | 0 | 1 | 4 | 1 | 22563 行(script 11356 / template 2784 / CSS 8395) | 密度不高,但 P1-10 的 `displayMediaUrl` 是典型的巨型单文件症状:格式化函数里塞了网络 I/O 和响应式写入,在 11356 行的 script 里没人看得出来 |
|
||||
| 前端 `features/` | **6** | 0 | 0 | 4 | 2 | — | 问题集中在"占位数据/示例数据混进生产路径"(2 条)与"前端复刻后端规则"(1 条) |
|
||||
| `engines/` | **5** | 0 | 1 | 4 | 0 | — | `single_flow.py` 是全仓唯一构造 `ImageGenerationRequest` 的地方,尺寸链路断在这里;fallback 无错误分类是 image/vision 共性 |
|
||||
| `backend/routes/` | **5** | 0 | 1 | 3 | 1 | 32 个文件 / 166 条路由 | 缺陷少但杠杆高:`common.py:12` 一处吞异常影响全部 166 条路由;IDOR 是五条链路的共性漏改 |
|
||||
| `adapters/` | **4** | 0 | 0 | 3 | 1 | — | 分发器不强制权限矩阵 + 每请求重算路由表,都是"入口处该做一次的事没做" |
|
||||
| `main.py` | **3** | 0 | 1 | 1 | 1 | 2580 行 | 全部围绕同一行:`:2337` 的权限赋值 |
|
||||
| 仓库根 / 配置 / 打包 | **2** | **1** | 1 | 0 | 0 | — | 条数最少、危害最大。P0 与 `_conf_schema.json` 缺口都不在代码里,而在"代码之外的交付面" |
|
||||
| `tests/` + 前端 `shared/` | **2** | 0 | 0 | 2 | 0 | 后端 45 个测试文件 / 前端 8 个 | — |
|
||||
|
||||
**结论**:重构优先级 `backend/services/` > `core/`(按危害而非条数)> `database/`。`core/` 条数只有 7 但含全部安全边界,且每条修复都是十几行的约束补充 —— 投入产出比最高,应当先做。
|
||||
|
||||
---
|
||||
|
||||
## 8. 复核说明
|
||||
|
||||
本清单的每一条 P0/P1 发现都经过**对抗式复核**:为每条发现派一名独立复核者,立场设为「默认这是误报」,要求实际 Read 源码后才可判定成立。复核覆盖 56 条 P0/P1,**推翻 16 条**,维持 40 条 —— 其中 **33 条被下调严重度**、仅 7 条维持原判。
|
||||
|
||||
维持的 40 条复核后分布为 P0×1 / P1×9 / P2×20 / P3×10;被推翻的 16 条一律给出 P3 的残留定级。换算成"原判 → 现判":原判 P0 的 6 条只剩 1 条仍是 P0(凭据泄露),3 条降 P1、1 条降 P2、1 条被推翻;原判 P1 的 50 条中仅 6 条维持 P1,19 条降 P2、10 条降 P3、15 条被推翻。**误报率 29%,下调率 59%** —— 这个比例本身就是一条结论:动手修之前先写一个能复现的测试。
|
||||
|
||||
被推翻的 16 条中,有 12 条属于本清单的 bug/security/perf 类别,**已全部从"成立的缺陷"中剔除**(另 4 条属 coupling/hygiene 类别,不在本清单范围)。这 12 条中,11 条的残留技术债按复核给出的降级严重度收录在 §6 P3 表并标注「经复核降级」、不计入总数;剩下 1 条(SQLite 未启用 WAL)的残留内容与另一条独立成立的 P2 性能发现(`database/db_helper.py:159`)指向同一处代码,已合并到 §5 P2 表对应行,并在该行注明复核否定了原机理。
|
||||
|
||||
复核也修正了原报告的事实错误,例如:`.env` 泄露的 `api_key_plaintext` 实际在第 **25** 行(原报告写 :26,差一行);`_string_list` 真实是 **17** 处而非 18 处(多算的在 `.tmp/` 构建快照里)。
|
||||
|
||||
### 被推翻的典型案例
|
||||
|
||||
**案例一:`update_round` 无状态机守卫(原判 P0-致命 → 推翻)**
|
||||
原发现称"已 confirmed 的轮次可被幂等重放静默回退"。复核确认引用的代码片段全部真实存在(`:115-117` 的重放分支、`:928-940` 无条件写 `status="queued"`、`update_round` 确是裸 UPDATE),但**发现者漏读了 `create_round` 的第一行守卫**:`_ensure_round_creation_allowed(node, workflow)` 在第 81 行执行,早于第 90 行读取 `idempotency_key`;该守卫对 `node.status == "selected"` 或 `selected_image_id` 非空的节点直接抛 `VALIDATION_FAILED`。复核进一步证明"轮次 confirmed"与"节点 selected"是同一原子事务写入(`workflow_round_repository.py:993-1017`、`workflow_cross_review_repository.py:580-635`),不存在可利用的中间态,也不存在解锁节点但保留轮次 confirmed 的回退路径。整条攻击链对 confirmed 轮次不可达。降级为 P3 防御性编码瑕疵。
|
||||
|
||||
**案例二:`_conf_schema.json`(原判 P1 → 保留)与 SQLite WAL(原判 P1 → 推翻)的对照**
|
||||
WAL 那条的复核最能说明标准。原发现称"写事务持有 RESERVED/EXCLUSIVE 锁会阻塞全库所有读,provider 调用稍慢就 30s 超时"。复核指出:(a) SQLite 语义被说错 —— rollback journal 模式下 RESERVED 不阻塞读者;(b) 通读 `confirm_candidate_atomic` 全文(`workflow_round_repository.py:801-1131`),事务内只有本地 SELECT/UPDATE/INSERT,**没有任何网络或文件 I/O**,事务寿命毫秒级,与 30s busy_timeout 差 4 个数量级;(c) 声称的并发场景是虚构的 —— `confirm_candidate_atomic` 唯一调用方是用户确认候选的交互式 API,聊天侧的 4 线程走的是完全不同的 `nodes/{id}/generate` 链路。开启 WAL 仍是合理调优,但"生成静默失败"级缺陷不成立,已按 P2 性能调优收录(§5 表末)。
|
||||
|
||||
**案例三:`POST profiles/{id}/archive` 实际执行删除(原判 P1 → 推翻)**
|
||||
原发现称"用户点击标注为'归档'的按钮,档案却被删除,两种意图被合并成破坏性操作"。复核把 `profileArchive` 的全部引用查了一遍:全仓唯一调用点在 `App.vue:6300` 的 `deleteSelectedProfile()`,失败文案是"删除角色失败",状态变量叫 `profileDeletingId`,模板绑定是 `@delete`;用户实际看到的控件(`ProfileDetailPane.vue:190-198`)文案是"删除"、hover 提示"删除角色档案"、样式是 `danger-button`。**用户意图 = 删除,后端行为 = soft_delete,两者完全一致**,不存在所称的意图错配。更关键的是,复核指出如果照原修复建议改成写 `status="archived"`,会让这个删除按钮变成不删除、档案继续留在列表里 —— **修复本身会引入真实的功能回归**。仅保留 P3 级的 REST 路径命名整洁度问题。
|
||||
|
||||
---
|
||||
|
||||
*本清单只收录有 `文件:行号` 支撑的内容。所有严重度均为复核后的最终判定,未经复核的条目已在正文中标注。*
|
||||
1234
审计/03-耦合分析.md
普通文件
1234
审计/03-耦合分析.md
普通文件
文件差异内容过多而无法显示
加载差异
885
审计/04-代码精简方案.md
普通文件
885
审计/04-代码精简方案.md
普通文件
|
|
@ -0,0 +1,885 @@
|
|||
# 04 · 代码精简方案
|
||||
|
||||
> 面向要动手改这个仓库的工程师。每一条都给位置、削减量、做法骨架和风险。
|
||||
> 数字来源:`审计/findings/C1-后端精简空间.md`、`C2-前端精简空间.md`、`C3-测试与仓库卫生.md`,辅以 `A3`/`A6`/`A8`/`A9`;凡与 `_复核结论.md` 冲突处,一律以复核为准并标注「经复核降级/修正」。
|
||||
|
||||
---
|
||||
|
||||
## 摘要
|
||||
|
||||
先说清楚前提:**后端 263 个 pytest 全部通过(188 秒),前端 26 个 node:test 全部通过。代码跑得起来,问题是设计边界和体量。** 本报告不修 bug,只处理"同一件事被写了 N 遍"和"写了但没人用"。
|
||||
|
||||
三个数字定调:
|
||||
|
||||
- 后端 ~64,100 行里,仓储层连接样板重复 **131 次**、`_optional_text` 独立定义 **30 次**、`_json_or_none` **13 次**,而 `backend/routes/params.py:22` 早就提供了共享实现,**从未被任何模块 import**。
|
||||
- 前端 39,254 行里,`App.vue` 一个文件占 **22,563 行**(script 11,356 / template 2,784 / CSS 8,395)。它的 CSS 块**没有 `scoped`**,这是它拆不动的直接原因——搬模板必须同步搬 CSS,否则样式立刻丢。
|
||||
- 单个后端服务 `advanced_style_set_service.py` **4,491 行**,其中 `_execute_consensus` 一个方法 **467 行**。
|
||||
|
||||
保守可净删 **≈3,510 行源码**(后端 1,746 + 前端 1,767),另有一个高风险的路由层改造可再减 300 行。App.vue 另有 **≈7,200 行**属于"迁出而非删除",拆完后该文件落到 4,000–4,500 行。
|
||||
|
||||
### 总收益表
|
||||
|
||||
| 类别 | 预计削减行数 | 风险 | 优先级 |
|
||||
|---|---:|---|---|
|
||||
| 后端 · 纯删死代码(`core/queue_manager.py` 整文件 + 29 个零引用符号 + `EventBus` 空转分发 + `event_from_bus` + config 默认值重复) | **≈407** | 低 | P0 · 立即 |
|
||||
| 后端 · 工具函数收敛(`_optional_text`×30 / `_string_list`×17 / `_json_*`×20 / `_page`族×10 / `_signed_url`×7 / `_now`×6 / `_mapping`×4) | **≈429** | 低–中 | P1 |
|
||||
| 后端 · DTO `to_dict()` 纯镜像 → `DictMixin` | **≈220** | 低 | P1 |
|
||||
| 后端 · 仓储连接样板 131 处 → `BaseRepository._connect()` | **≈390** | 中 | P2 |
|
||||
| 后端 · `update` 赋值块 ×6 + `_create_*_service` 工厂集中 + `engines` provider 基类提取 | **≈160** | 中 | P1(顺带消灭 2 个真实缺陷) |
|
||||
| 后端 · `main.py` 38 个短命令别名 → 命令表 | **≈140** | 中 | P2 |
|
||||
| 后端 · 路由 `def action()` 闭包 → `@route_handler`(**建议单独立项**) | ≈300 | **高** | P3 |
|
||||
| 前端 · 死 CSS / 与子组件 scoped 重复的 CSS 副本 | **≈518** | 低 | P0 · 立即 |
|
||||
| 前端 · 死类型 / 零引用导出 / 死配置 / 未使用依赖 | **≈94** | 低 | P0 · 立即 |
|
||||
| 前端 · 模板与逻辑组件化(素材选择器 / focus trap / 缩放拖拽 / loader 样板 / overlay 表驱动) | **≈455** | 中 | P1 |
|
||||
| 前端 · CSS utility/token 层,合并重复声明块 | **≈700**(上限 1,100) | 中 | P2 |
|
||||
| **净删除合计(不含路由装饰器立项)** | **≈3,513 行** | | |
|
||||
| **含路由装饰器立项** | **≈3,813 行** | | |
|
||||
| 前端 · App.vue 迁出(不减总量,把 22,563 压到 ~4,200) | ≈7,200(迁移) | 中–高 | 分 6 阶段 |
|
||||
| 仓库 · `release/` 20 个 zip 停止跟踪 | 0 行 / **-38 MB 库内** | 中 | P1 |
|
||||
| 仓库 · 工作树 `.tmp/` + `.tmp_pytest_*` 清理 | 0 行 / **-2.6 GB 磁盘** | 低(**含密钥,需安全删除**) | P0 |
|
||||
|
||||
**口径说明(原始材料不一致处已取保守值)**:
|
||||
|
||||
| 项 | C1/C3 口径 | 实测复核口径 | 本报告采用 |
|
||||
|---|---|---|---|
|
||||
| `_string_list` 定义数 | 18 | **17**(多出的 1 处来自 `.tmp/` 构建快照) | **17** |
|
||||
| `main.py` 短命令别名 | 50 个 / 164 行(`:1300-1463`) | **38 个装饰器**(`:1304-1461`) | **38 个,块 `:1300-1462`,保守削减 ≈140 行** |
|
||||
| `_create_*_service()` 工厂 | 22 处 | 模块级 19 处(另有转发壳) | **19 处** |
|
||||
| `.tmp_pytest_*` 目录 | 20 个 / 507 MB | 19 个 / ~515 MB | **19 个 / ~515 MB** |
|
||||
| `_optional_text` 定义数 | A3 记 28、C1 记 30 | **30**(`grep -rn "def _optional_text" backend core engines database adapters main.py` 实测) | **30** |
|
||||
| `App.vue` 的 `ref`/`computed` 计数 | 01 报告记 133/135(字面量口径) | **206 / 203**(`= ref(` / `= computed(`,含 `ref<T>(` 泛型写法) | **206 / 203**,本报告与 05 统一用此口径 |
|
||||
| 后端总行数 | 54,551(不含部分目录) | 64,100 | 削减比例按 **64,100** 计算 → ≈2.7% |
|
||||
|
||||
---
|
||||
|
||||
# 第一部分 · 后端精简
|
||||
|
||||
按投入产出比排序。前 4 项零/低风险,做完就有约 1,050 行。
|
||||
|
||||
## 1.1 仓储层连接样板重复 131 次 → 上下文管理器(≈390 行,风险中)
|
||||
|
||||
**现状**:每个仓储方法手写 `conn = self.database.connect()` / `try:` / `finally: conn.close()`;写方法再额外手写 `except Exception: _rollback(conn); raise`。`_rollback` 本身被独立定义了 3 次。
|
||||
|
||||
**位置**:`database/repositories/advanced_material_repository.py:346`、`workflow_repository.py:100`、`wardrobe_repository.py:84`、`core/audit_service.py:83` 等共 131 处(实测 `grep -c 'conn.close()' database/repositories/*.py core/audit_service.py` = **132**,`finally:` = **131**)。`_rollback` 三份:`advanced_material_repository.py:2119`、`workflow_cross_review_repository.py:1464`、`workflow_round_repository.py:1378`。
|
||||
|
||||
**现状代码**(`advanced_material_repository.py:346-366`,同文件两个相邻方法逐字节同构):
|
||||
|
||||
```python
|
||||
def get_import(self, import_id: str) -> AdvancedMaterialImport | None:
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
row = conn.execute(
|
||||
f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE import_id = {self.placeholder}",
|
||||
(import_id,),
|
||||
).fetchone()
|
||||
finally:
|
||||
conn.close()
|
||||
return _row_to_import(row) if row else None
|
||||
```
|
||||
|
||||
**做法**:在 `database/repositories/__init__.py` 建基类,13 个仓储的 `__init__` + `placeholder` 属性一并收敛。
|
||||
|
||||
```python
|
||||
class BaseRepository:
|
||||
def __init__(self, database: Database) -> None:
|
||||
self.database = database
|
||||
|
||||
@property
|
||||
def placeholder(self) -> str:
|
||||
return self.database._placeholder
|
||||
|
||||
@contextmanager
|
||||
def _connect(self, *, write: bool = False):
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
yield conn
|
||||
if write:
|
||||
conn.commit()
|
||||
except Exception:
|
||||
if write:
|
||||
_rollback(conn)
|
||||
raise
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def _fetch_one(self, sql: str, params: tuple, mapper): ...
|
||||
def _fetch_all(self, sql: str, params: tuple, mapper): ...
|
||||
```
|
||||
|
||||
上例塌缩成 3 行。
|
||||
|
||||
**风险(中)**:131 处机械替换,逐文件做、逐文件跑 `python -m pytest tests/ -q`。注意 `profile_repository.update` 当前**没有** rollback 分支而 `advanced_material_repository.update_import` 有——统一到 `write=True` 会改变前者在异常时的行为(从"不回滚"变成"回滚"),这是修正而非回归,但要在 commit message 里写明。
|
||||
|
||||
## 1.2 `_optional_text` 独立定义 30 次,共享实现无人 import(≈145 行,风险低)
|
||||
|
||||
**现状**:同一个 5 行函数被复制 30 份(实测 `grep -rn "def _optional_text" backend core engines database adapters main.py` = **30**)。而 `backend/routes/params.py:20-22` 早就有:
|
||||
|
||||
```python
|
||||
# Both names are used for this coercion across the backend. Keep the alias so
|
||||
# route and service code can use the vocabulary that best fits the field.
|
||||
optional_text = optional_str
|
||||
```
|
||||
|
||||
**注释是错的**——`optional_text` 从未被任何模块 import,它自己就是死代码。
|
||||
|
||||
**位置**:30 个定义点,包括 `backend/services/queue_service.py:713`、`generation_service.py:2112`、`workflow_round_service.py:1592`、`database/repositories/workflow_round_repository.py:1343`、`engines/single_flow.py:241`、`engines/vision_provider.py:450`、`core/astrbot_provider_bridge.py:349`、`adapters/wechat_adapter.py:77`、`adapters/onebot11_adapter.py:96`。
|
||||
|
||||
**注意有 3 份语义不同**:
|
||||
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:349 / adapters/wechat_adapter.py:77 / adapters/onebot11_adapter.py:96
|
||||
def _optional_text(value: Any) -> str | None:
|
||||
text = str(value or "").strip() # 0 / False / [] 被当成 None;主流版本不会
|
||||
return text or None
|
||||
```
|
||||
|
||||
**做法**:新建 `core/coerce.py`(**不要**复用 `backend/routes/params.py`——`database/repositories` 和 `engines` 依赖 `routes` 包是层级倒置),导出 `optional_text / optional_int / optional_float / as_bool / mapping / utc_now_iso`。30 处改成 `from core.coerce import optional_text as _optional_text`。删掉 `params.py:22` 的死别名与错误注释。
|
||||
|
||||
**风险(低)**:那 3 个变体要单独确认调用点是否依赖 `0 → None` 的行为。改之前先在这三个文件里 grep 调用参数类型。
|
||||
|
||||
## 1.3 `_string_list` 定义 17 次、至少 6 种语义 —— 同名不同义的语义地雷(≈90 行,风险中)
|
||||
|
||||
> **经复核修正**:原始材料记为 18 处并声称会导致 tags 静默变空列表、prompt 片段顺序不可预测、数据跨 service 污染。复核逐条查证:真实计数是 **17 处**(第 18 处来自 `.tmp/deploy-*` 构建快照,不是源码);17 个实现**全部是下划线私有、无一被跨模块 import**(`grep "from ... import ..._string_list"` 零结果),每个调用点都是在本模块信任边界上对刚解析的 dict 做一次本地归一化,不存在接力传递,所以"跨模块数据污染"不可达;被点名的三条影响路径(tags 传给 `workflow_round_service` 版本、`prompt_parts` 在两模块间流转)经查根本不存在对应调用。**严重度从 P1 降级为 P3。**
|
||||
|
||||
**它仍然值得修,但理由变了**:这不是"重复 90 行"的问题,而是**17 个同名函数在 4 个维度上自由组合出至少 6 种行为**——是否切分逗号字符串、是否去重、是否排序、是否接受 `tuple/set`。任何人跨模块复制一行调用代码都会拿到与原处不同的结果,而且没有任何工具会报错。
|
||||
|
||||
**位置**:`backend/services/composition_builder.py:279`、`generation_service.py:2417`、`prompt_expansion_service.py:257`、`workflow_round_service.py:1544`、`advanced_style_set_service.py:4288`、`material_normalization_service.py:368`、`core/astrbot_provider_bridge.py:344`、`engines/vision_provider.py:432`、`engines/review_flow.py:430` 等共 17 处。
|
||||
|
||||
**四种同名不同义的实现**:
|
||||
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:344 —— 逗号切分 + 去重 + 排序
|
||||
# backend/services/generation_service.py:2417 —— 逗号切分 + 不去重 + 不排序
|
||||
# backend/services/workflow_round_service.py:1544 —— 拒绝字符串(返回 [])+ 去重保序
|
||||
# backend/services/prompt_expansion_service.py:257 —— 字符串整体作为单元素,不切分
|
||||
```
|
||||
|
||||
**唯一实测到的真实不一致**(复核确认,影响是装饰性的):`VisionRecognitionResult.tags` 有三个构造点——`engines/vision_provider.py:357`(sorted)、`core/astrbot_provider_bridge.py:278`(sorted)、`advanced_style_set_service.py:1537`(`dict.fromkeys` 保序),三者中两者一致、第三者顺序不同。下游(`material_service.py:472`、`advanced_style_set_service.py:1765`)只把 tags 当集合存储展示,无顺序依赖。
|
||||
|
||||
**做法**:在 `core/coerce.py` 定义**语义显式命名**的三个函数,废弃 `_string_list` 这个名字本身:
|
||||
|
||||
```python
|
||||
def csv_tags(value: Any) -> list[str]: # 切分逗号 + 去重 + 保序
|
||||
def prompt_parts(value: Any) -> list[str]: # 不切分 + 去重 + 保序
|
||||
def sorted_tags(value: Any) -> list[str]: # 切分逗号 + 去重 + 排序
|
||||
```
|
||||
|
||||
17 处按**实际语义**逐个替换(不是无脑换成同一个)。顺带把三个 `tags` 构造点统一到 `sorted_tags`。
|
||||
|
||||
**风险(中)**:必须逐处读调用上下文判断该用哪一个,不能批量 sed。这是本项唯一的成本,也是它优先级不高的原因。
|
||||
|
||||
## 1.4 `main.py` 38 个短命令别名 ≈ 160–190 行纯转发 → 命令表(≈140 行,风险中)
|
||||
|
||||
**现状**:`imagestudio_short_command` 命令组下 38 个方法,每个只是把参数原样转给同名长命令。实测装饰器 38 个,块区间 `main.py:1300–1462`。风格还不统一——前 8 个用两行 `async for` / `yield`,后 30 个压成一行(`:1345` 起),说明是分批粘贴出来的。
|
||||
|
||||
```python
|
||||
# main.py:1304-1311
|
||||
@imagestudio_short_command.command("帮助")
|
||||
async def imagestudio_short_help(self, event: AstrMessageEvent):
|
||||
async for result in self.imagestudio_help(event):
|
||||
yield result
|
||||
|
||||
@imagestudio_short_command.command("状态")
|
||||
async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
|
||||
async for result in self.imagestudio_status(event, workflow_id):
|
||||
yield result
|
||||
```
|
||||
|
||||
**做法**:命令名 → 目标方法的映射抽成一张表,类装饰器生成别名:
|
||||
|
||||
```python
|
||||
_SHORT_ALIASES = {"帮助": "imagestudio_help", "状态": "imagestudio_status", ...}
|
||||
|
||||
def _bind_short_aliases(cls):
|
||||
for zh_name, target in _SHORT_ALIASES.items():
|
||||
async def _forward(self, event, *args, _target=target, **kwargs):
|
||||
async for result in getattr(self, _target)(event, *args, **kwargs):
|
||||
yield result
|
||||
setattr(cls, f"_short_{target}", cls.imagestudio_short_command.command(zh_name)(_forward))
|
||||
return cls
|
||||
```
|
||||
|
||||
**风险(中)**:AstrBot 的 `@command` 装饰器可能对函数签名做内省来解析参数(`workflow_id: str = ""` 这类),`*args/**kwargs` 转发会丢掉签名信息。**上手前先验证一条**:改一个别名(比如"状态")跑通再批量。若确实依赖签名内省,退化方案是保留装饰器形态、改由代码生成脚本从 `_SHORT_ALIASES` 生成这段代码并加一条测试断言长短命令一一对应——收益从"删 140 行"降为"消除漏注册",但风险归零。
|
||||
|
||||
## 1.5 `core/queue_manager.py` 整文件死代码(112 行,风险低)
|
||||
|
||||
**现状**:`QueueManager` / `QueueItem` 是一套完整的内存队列(enqueue / dequeue / complete / fail / retry / summary + FSM 校验),**全仓含 `tests/` 零 import、零引用**。真实队列走 `backend/services/queue_service.py` + `database/repositories/job_repository.py` 的持久化实现。实测 `wc -l core/queue_manager.py` = **112**。
|
||||
|
||||
**复核已维持此条。**
|
||||
|
||||
**做法**:`git rm core/queue_manager.py`。它单独依赖 `core.fsm.task_transition`,删掉后 `fsm` 的消费者数量才是真实的。
|
||||
|
||||
**风险(低)**:删前跑一次 `grep -rn "queue_manager\|QueueItem\|QueueManager" --include=*.py .` 确认(排除 `.tmp/`)。
|
||||
|
||||
## 1.6 29 个零引用符号(≈263 行,风险低)
|
||||
|
||||
已用 `grep -rn` 在 `main.py + backend + core + database + engines + adapters + tests + frontend/src` 全范围交叉验证,引用数为 1(只有定义处):
|
||||
|
||||
| 文件:行 | 符号 | 行数 |
|
||||
|---|---|---:|
|
||||
| `database/repositories/workflow_round_repository.py:488` | `update_pool_preferences` | 60 |
|
||||
| `backend/dto/material_dto.py:10/32/54` | `RawAnalysis` / `NormalizedAssetProfile` / `GenerationCapsule` | 51 |
|
||||
| `backend/services/worker_service.py:148` | `QueueWorker.run_batch` | 15 |
|
||||
| `core/interactions.py:49` | `normalize_action` | 14 |
|
||||
| `core/interop.py:14/29/44/49` | `PluginRequest` / `normalize_plugin_request` / `is_allowed_plugin` / `daily_outfit_request` | 41 |
|
||||
| `backend/services/queue_service.py:539` | `requeue_dead_letters` | 10 |
|
||||
| `database/repositories/profile_card_repository.py:266` | `next_version` | 10 |
|
||||
| `database/repositories/advanced_material_repository.py:357` | `get_import_by_idempotency_key` | 10 |
|
||||
| `backend/dto/chat_command_dto.py:21` | `SingleImageCommand.to_payload` | 10 |
|
||||
| `backend/services/web_hosting_service.py:42/50/54` | 三个 asset 解析方法 | 9 |
|
||||
| `core/event_bus.py:36/41` | `subscribe` / `unsubscribe` | 7 |
|
||||
| `core/webhook.py:33/40` | `sign_event` / `verify_signature` | 6 |
|
||||
| `core/secret_service.py:34/57` | `SecretResolution.to_public_dict` / `env_ref` | 7 |
|
||||
| 其余 10 个小符号 | `get_runtime_data_root` / `create_audit_service` / `fetch_media_metadata` / `is_cancelled` / `column_names` / `sensitive_columns` / `has_images` / `_dump_yaml` / `optional_text` / `IMPORT_REVIEW_STATUSES` / `SUPPORTED_IMAGE_MIME_TYPES` | 23 |
|
||||
|
||||
两个需要单独决策的:
|
||||
|
||||
- `requeue_dead_letters`(`queue_service.py:539`)和 `update_pool_preferences`(`workflow_round_repository.py:488`)**看起来是产品功能**(死信恢复、候选池偏好),实际无路由、无 CLI、无测试触发。要么接线要么删——留着最坏,会让人以为功能已交付。
|
||||
- `core/interop.py` 只有 `PRIVATE_COMPANION` 常量被 `integration_token_service.py:16` 引用。把常量挪进 `integration_token_service.py` 后整文件可删,再减 ≈45 行。
|
||||
|
||||
**顺带**:`backend/services/settings_service.py:882-884` 的注释写着"为已有测试保留",但 grep 显示没有任何测试引用它——注释和 `params.py:22` 一样是过期的。
|
||||
|
||||
## 1.7 DTO 15 个 `to_dict()` 是纯字段镜像(≈220 行,风险低)
|
||||
|
||||
AST 扫描确认这 15 个 `to_dict()` 的 key 列表与 value 表达式**逐项等于 dataclass 字段声明顺序**,无任何重命名或转换,共 234 行。
|
||||
|
||||
**位置**:`backend/dto/workflow_round_dto.py:29/69/103`、`workflow_dto.py:24/61/109/137`、`profile_dto.py:32`、`material_dto.py:80/108`、`image_dto.py:32`、`job_dto.py:27`、`wardrobe_dto.py:25`、`profile_card_dto.py:19`、`workflow_feedback_dto.py:16`。
|
||||
|
||||
```python
|
||||
# backend/dto/common.py 新增
|
||||
class DictMixin:
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
|
||||
```
|
||||
|
||||
15 个类继承它并删掉各自的 `to_dict`;另外 18 个有真实转换逻辑的保持手写(可继续覆写)。
|
||||
|
||||
**风险(低)**:这是本报告投入产出比最高的一项——机械、可测、顺带消灭"加字段漏改 `to_dict` 导致 API 静默少字段"这类无法被类型检查拦住的 bug。
|
||||
|
||||
## 1.8 其余工具函数收敛(≈279 行,风险低)
|
||||
|
||||
| 项 | 处数 | 位置样本 | 削减 | 附带修复 |
|
||||
|---|---:|---|---:|---|
|
||||
| `_json_or_none` / `_json_loads` / `_json_object` | 20 | `job_repository.py:562`、`capability_repository.py:150/156`、`advanced_material_repository.py:2072/2078` | ≈75 | `_json_loads` 无 `isinstance(parsed, dict)` 保护,JSON 列存数组时返回 list,下游 `.get()` 直接 AttributeError;统一到有保护的版本 |
|
||||
| `_page` / `_page_size` / `_limit` | 10 | `job_repository.py:609/617`、`material_repository.py:319/327`、`profile_repository.py:354/362`、`advanced_material_repository.py:2111` | ≈48 | 前三份 `try/except → max(page,1)`,第四份 `max(int(value or 1), 1)` 对非数字字符串直接抛 `ValueError`——高级素材列表接口对畸形 `page` 会 500,其他接口降级到第 1 页 |
|
||||
| `_signed_url` | 7 | `advanced_material_routes.py:428`、`image_routes.py:226`、`material_routes.py:317`、`profile_card_routes.py:90`、`round_routes.py:192`、`workflow_round_worker_runtime.py:257`、`dashboard_service.py:89` | ≈41 | `advanced_material_routes` 版本每次调用 `MediaService()`(内部 `ConfigService()` 读盘),列表页 N 张图 = N 次配置加载。改成 `MediaService.signed_url()` 实例方法 |
|
||||
| `_now` ×6 + `_mapping` ×4 | 10 | `advanced_style_set_service.py:4279`、`queue_service.py:709`、`worker_service.py:476`、`history_service.py:313` | ≈30 | `_mapping` 对应的内联写法 `x.get("y") if isinstance(x.get("y"), dict) else {}` 在后端出现 **291 次**(`node_routes.py:329-335` 一个函数里连着 5 行),每处把 key 名写两遍——写成 `config.get("a") if isinstance(config.get("b"), dict) else {}` 没有任何工具会报错 |
|
||||
| `update` 赋值构建块 | 6 | `workflow_repository.py:141-176/180-227/280-321/324-379` | ≈85 | 四段循环体逐字节相同,`allowed` 集合各复制两遍。给 node 加可更新字段要改 2 个集合,漏改 = "普通更新生效、CAS 更新静默丢字段"。`advanced_material_repository.py:2042` 已有更通用的 `_update_assignments`,提升到 `database/repositories/_sql.py` 共用即可 |
|
||||
|
||||
## 1.9 `_create_*_service()` 工厂集中(≈20 行,风险中,**但会修一个真实缺陷**)
|
||||
|
||||
**现状**:`_create_workflow_service()` 在 4 个 route 模块里各一份,其中 `backend/routes/branch_routes.py:62-68` **漏掉了 `event_bus=get_default_event_bus()`**:
|
||||
|
||||
```python
|
||||
# backend/routes/branch_routes.py:62-68 ← 缺 event_bus
|
||||
def _create_workflow_service() -> WorkflowService:
|
||||
database = Database(load_database_settings())
|
||||
return WorkflowService(
|
||||
workflow_repository=WorkflowRepository(database),
|
||||
profile_repository=ProfileRepository(database),
|
||||
audit_service=AuditService(database),
|
||||
)
|
||||
|
||||
# backend/routes/workflow_routes.py:143-150 ← 有 event_bus
|
||||
```
|
||||
|
||||
而 `WorkflowService._publish`(`workflow_service.py:1012-1014`)是空守卫(`if self.event_bus:`),`create_branch`(`:514`)与 `switch_branch`(`:640`)都调它。结果:走 HTTP `POST /workflows/{id}/branches` 和 `/switch-branch` 时事件被静默吞掉,前端 SSE 永远看不到分支变更,**且不报错**。典型的"复制粘贴少复制一行"。
|
||||
|
||||
**做法**:把 19 个模块级 `_create_*_service()`(C1 计 22 处,含转发壳)集中到 `backend/services/factory.py`,每种 service 只保留一份构造。顺带解决层级倒置:`backend/services/workflow_round_worker_runtime.py:10` 反向 `from backend.routes.node_routes import create_generation_service`,而 `node_routes.py:393-396` 的 `create_generation_service()` 只是 `return _create_generation_service()` 的纯转发壳。
|
||||
|
||||
**风险(中)**:148 个 handler 的 `service=` 注入点是测试的入口,集中工厂时不要改这个参数的语义。
|
||||
|
||||
## 1.10 `engines/` provider 基类提取(≈55 行,风险低,**顺带修一个配置陷阱**)
|
||||
|
||||
`ImageProviderError`(`image_provider.py:96-110`)与 `VisionProviderError`(`vision_provider.py:72-86`)**除类名外逐字节相同**;`_post_json` 的 urllib 回退分支(`image_provider.py:272-303` vs `vision_provider.py:295-337`)只差异常类和错误文案里的 `image`/`vision` 前缀。
|
||||
|
||||
**真正的代价是分叉**:image 版 `_post_json` 已经加了 httpx 流式读取 + 长度上限(`:231-271`),vision 版还停留在纯 urllib——视觉调用没有 httpx 的超时/重定向控制,也没有 `_provider_json_limit` 动态上限。
|
||||
|
||||
**同一族的第二个分叉**(`endpoint_url()`):
|
||||
|
||||
```python
|
||||
# engines/image_provider.py:51-56
|
||||
if base.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"):
|
||||
endpoint = endpoint[3:] # ← 去重
|
||||
|
||||
# engines/vision_provider.py:40-43 ← 没有去重
|
||||
```
|
||||
|
||||
`vision_endpoint` 默认值是 `/v1/chat/completions`。用户填 `base_url: https://api.example.com/v1`(OpenAI 兼容服务最常见写法)时,**视觉识别打到 `/v1/v1/chat/completions` → 404,而生图正常**。`model_provider_runtime.py:210-216` 与 `:297-303` 同样没有去重。
|
||||
|
||||
**做法**:新建 `engines/_provider_http.py`:
|
||||
|
||||
```python
|
||||
class ProviderError(RuntimeError): ... # 两个子类只留 pass + 文案前缀
|
||||
def join_endpoint(base_url: str, endpoint: str) -> str: ... # /v1 去重,三处共用
|
||||
def post_json(url, payload, headers, timeout_seconds, *, error_cls, label, max_bytes) -> JsonDict: ...
|
||||
```
|
||||
|
||||
## 1.11 `advanced_style_set_service.py` 4,491 行的拆分边界(迁移,非净删)
|
||||
|
||||
**现状**:4,491 行 = 类体 2,091 行(32 个方法)+ 模块级函数 2,092 行(81 个纯函数)。最长方法 `_execute_consensus` 单体 **467 行**(`:1347`),`_execute_validation_case` 220 行,`_queue_validation_batch` 161 行。
|
||||
|
||||
更麻烦的是**双向循环引用**:
|
||||
|
||||
```python
|
||||
# advanced_style_set_service.py:309-318
|
||||
def __init__(self, owner: Any): # 无类型标注的反向引用
|
||||
self.owner = owner
|
||||
self.repository = owner.repository
|
||||
... # 共 8 个协作者全从 owner 上扒
|
||||
|
||||
# advanced_material_service.py:118
|
||||
self.style_sets = AdvancedStyleSetService(self)
|
||||
```
|
||||
|
||||
两边互相调私有方法(`self.owner._require_import` / `_govern_validation_prompt` / `_generation_route`)。`owner: Any` 让 IDE 和类型检查完全失效,单元测试只能完整 mock `owner`。
|
||||
|
||||
**模块划分建议**(都是纯搬运、无行为变更):
|
||||
|
||||
| 目标模块 | 迁入内容 | 约行数 |
|
||||
|---|---|---:|
|
||||
| `style_prompt_compiler.py` | `_detailed_style_prompt` / `_detailed_style_negative_prompt` / `_scale_specific_*` / `_style_kernel_parts` / `_compact_style_prompt_parts` / `_artist_signature_*` / `_join_prompt` | ~600 |
|
||||
| `style_text_sanitizer.py` | `_sanitize_minor_age_text` / `_strip_mature_body_locks` / `_normalize_style_prompt_conflicts` / `_clean_prompt_text` / `_apply_semantic_risk_rewrites` 及其正则常量 | ~400 |
|
||||
| `style_review_scoring.py` | `_normalize_style_dimension_scores` / `_weighted_style_fidelity_score` / `_cap_inconsistent_dimension_scores` / `_aggregate_style_review_feedback` / `STYLE_REVIEW_*` 常量 | ~400 |
|
||||
| `style_evidence.py` | `_normalized_feature_evidence` / `_style_trait_is_supported` / `_prompt_traits_overlap` / `_extract_head_ratio_range` 系列 | ~300 |
|
||||
| 剩余类体 → `StyleSourceStage` / `StyleConsensusStage` / `StyleValidationStage` | 各自只接收显式依赖(repository / queue / storage / runtime) | ~2,090 |
|
||||
|
||||
**同步做两件事**:
|
||||
|
||||
1. `owner: Any` 换成一个 `StyleSetRuntime` Protocol,只暴露 `require_import` / `generation_route` / `govern_validation_prompt` 等 6 个方法,消除双向引用。
|
||||
2. `_execute_consensus` 按 `text_only` / `single_pass` / `grouped_two_stage` 拆三个私有方法,共用一个 `_persist_consensus_result`。
|
||||
|
||||
**顺带**:`advanced_style_set_service.py:33-41` 跨模块 import 了 `material_service` 的 7 个下划线私有函数(`_normalize_upload_content_type` / `_normalize_upload_filename` / `_normalize_upload_metadata` / `_normalize_upload_size` / `_recognition_metadata` / `_storage_image_data_url` / `_vision_provider_error`)。它们实际上是整个素材域的**公共上传校验契约**,应去掉下划线提升为公共 API。
|
||||
|
||||
**风险(中)**:81 个模块函数是纯函数,搬运零风险;类体拆三个 Stage 需要重新走一遍端到端测试(`tests/test_advanced_style_set_workflow.py`)。
|
||||
|
||||
## 1.12 `engines/` 四个 flow 文件 —— **结论:不建议合并**
|
||||
|
||||
这是 A6 专项核查的结论,本报告采纳:
|
||||
|
||||
| 文件 | 行数 | 性质 | 与其它 flow 的实质重复 |
|
||||
|---|---:|---|---|
|
||||
| `engines/single_flow.py` | 455 | 真实生成引擎(provider 调用、字节校验、URI 布局) | 无 |
|
||||
| `engines/review_flow.py` | 451 | 真实审查引擎(策略校验、评分、阶段结果) | 无(内部有自重复,见下) |
|
||||
| `engines/character_flow.py` | 145 | 声明式节点模板目录 + 遗留 node_key 别名 | 仅 `gradual_node_templates()` 约 15 行样板 |
|
||||
| `engines/fast_character_flow.py` | 50 | 声明式节点模板目录 | 仅 `fast_character_node_templates()` 约 11 行样板 |
|
||||
| `engines/quick_profile_flow.py` | 32 | 声明式节点模板目录(内联字面量) | 无函数,纯字面量 |
|
||||
|
||||
三个模板目录唯一的共性是约 11–15 行的列表推导样板,但三者 metadata 契约各不相同(`character_gradual` 要 `stage_code` + `canonical_node_key` 且支持 per-step `node_type` 覆盖;`character_fast` 要 `quick_character_target`;`quick_profile` 用 `profile_draft`/`profile_preview` 这类完全不同的 node_type)。抽公共构造器需要引入配置参数把这些差异重新表达出来,代码量与理解成本都不会下降,反而把三种工作流的演进耦合在一起。**当前形态(声明数据与业务逻辑分离、每种工作流一个独立目录)是合适的,不要动。**
|
||||
|
||||
**引擎侧真正值得做的重复合并**(不在上表内):
|
||||
|
||||
- `adapters/onebot11_adapter.py` 与 `adapters/wechat_adapter.py` 结构性重复约 **90%**。
|
||||
- `engines/review_flow.py:141-159` 与 `:362-380`:`_candidate_warnings` 的告警判定与文案逐字相同,只有变量名不同。
|
||||
|
||||
## 1.13 路由 `def action()` 闭包(≈300 行,风险**高**,建议单独立项)
|
||||
|
||||
148 处 `def action()` + **157 处 `return handle_request(ctx, action)`**(实测)+ 147 处 `service or _create_xxx()`。每个 handler 固定四段式:
|
||||
|
||||
```python
|
||||
# backend/routes/wardrobe_routes.py:57-70 —— 与另外 147 个同构
|
||||
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, service=None) -> dict:
|
||||
wardrobe_service = service or _create_wardrobe_service()
|
||||
|
||||
def action() -> dict[str, Any]:
|
||||
require_permission(ctx, "can_manage_materials")
|
||||
return wardrobe_service.delete_item(profile_id, wardrobe_item_id, ctx)
|
||||
|
||||
return handle_request(ctx, action)
|
||||
```
|
||||
|
||||
同文件 `:86-107` 已经出现了绕过闭包的"元组下标"写法,说明作者本人也嫌样板烦。
|
||||
|
||||
**真正的收益不是 300 行,而是权限矩阵可静态校验**:现在 `RouteSpec.permission`(`route_registry.py`)与 handler 里的 `require_xxx(ctx)` 是两份独立真相——`branch_routes` 漏 `event_bus` 就是这种双真相结构的产物。
|
||||
|
||||
```python
|
||||
@route_handler(permission="materials", service_factory=_create_wardrobe_service)
|
||||
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, *, service) -> dict[str, Any]:
|
||||
return service.delete_item(profile_id, wardrobe_item_id, ctx)
|
||||
```
|
||||
|
||||
并在启动时断言装饰器声明的 permission 与 `route_registry.ROUTES` 一致。
|
||||
|
||||
**风险(高)**:148 个 handler 的 `service=` 测试注入点需同步调整,而路由层测试覆盖本身就薄(`route_registry` 166 条路由中只有 33 条被测试字面量命中——注意这是**下界**,复核实测 handler 函数名命中 50、模块名命中 8,用字面量 grep 会漏掉直接 import handler 的测试)。**先补 1.14 的注册表契约测试,再动这一项。**
|
||||
|
||||
## 1.14 做这些之前先加的两条保护
|
||||
|
||||
```python
|
||||
# tests/test_route_registry_contract.py —— 成本极低,一次覆盖 166 条
|
||||
from backend.route_registry import ROUTES, assert_unique_routes
|
||||
|
||||
def test_every_route_handler_resolves_and_declares_permission():
|
||||
assert_unique_routes()
|
||||
for spec in ROUTES:
|
||||
mod, fn = spec.handler.rsplit(".", 1)
|
||||
assert callable(getattr(importlib.import_module(mod), fn)), spec.endpoint
|
||||
assert spec.permission, spec.endpoint
|
||||
```
|
||||
|
||||
以及**先修 `pytest` 本身**——仓库没有 `conftest.py` / `pytest.ini` / `pyproject.toml`,`pytest tests/` 会在收集阶段 `ModuleNotFoundError` 崩溃,只有 `python -m pytest` 能跑:
|
||||
|
||||
```toml
|
||||
# pyproject.toml
|
||||
[tool.pytest.ini_options]
|
||||
pythonpath = ["."]
|
||||
testpaths = ["tests"]
|
||||
addopts = "-q --strict-markers --basetemp=.pytest_tmp"
|
||||
```
|
||||
|
||||
最后一条 `--basetemp` 直接解决第三部分那 19 个散落在仓库根的 `.tmp_pytest_*` 目录。
|
||||
|
||||
**另有两个文件带 UTF-8 BOM**(`backend/routes/job_routes.py:1`、`backend/services/profile_document_import_service.py:1`),`ast.parse(path.read_text(encoding="utf-8"))` 会抛 `SyntaxError: invalid non-printable character U+FEFF`。任何自建的重构脚本都会在这两个文件上失败——**批量改造前先去 BOM**:
|
||||
|
||||
```bash
|
||||
python -c "import pathlib;[p.write_bytes(p.read_bytes()[3:]) for p in map(pathlib.Path,['backend/routes/job_routes.py','backend/services/profile_document_import_service.py']) if p.read_bytes()[:3]==b'\xef\xbb\xbf']"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 第二部分 · 前端精简
|
||||
|
||||
## 2.1 `App.vue` 22,563 行拆分方案(本报告核心)
|
||||
|
||||
### 2.1.1 先看清障碍在哪
|
||||
|
||||
| 指标 | 数值 |
|
||||
|---|---|
|
||||
| 总行数 | 22,563(script 1–11,357 / template 11,359–14,143 / style 14,145–22,540) |
|
||||
| `<style>` | **8,395 行,约 1,100 条选择器,没有 `scoped`** |
|
||||
| `ref()` / `computed()` / 顶层 `function` | 206 / 203 / 365 |
|
||||
| API 调用点 | `getJson` 59 + `postJson` 58 + `putJson` 9 + `deleteJson` 3 = **129** |
|
||||
| `try` / `catch` | 84 / 82 |
|
||||
| `AbortController` | **0**(所有请求不可取消) |
|
||||
|
||||
**拆不动的直接原因就是那 8,395 行未 scoped 的 CSS**:任何把模板搬进新组件的动作都必须同步搬走对应的几百行 CSS,否则样式立刻丢失。而全部 44 个子组件用的都是 `<style scoped>`,两套体系并行。
|
||||
|
||||
所以拆分顺序必须是 **CSS 先行**,而不是模板先行。
|
||||
|
||||
### 2.1.2 分块清单
|
||||
|
||||
**A. 样式块(14,145–22,540,8,395 行)**
|
||||
|
||||
| 块 | 内容 | 目标产物 | 预计行数 |
|
||||
|---|---|---|---:|
|
||||
| S1 | `rail / brand / brand-mark / brand-copy / icon-nav / nav-scroll / nav-group* / nav-glyph / nav-copy / nav-label / rail-pin*` | 剪进 `components/AppNavigationRail.vue` 的 `<style scoped>`(该文件**当前完全没有 `<style>`**) | 347 |
|
||||
| S2 | `MaterialCategoryCreateDialog` 的 4 个类 + `materials-detail-card*` | 分别剪进 `MaterialCategoryCreateDialog.vue`(无 `<style>`)与 `MaterialDetailDialog.vue`(只有 4 行 scoped) | 344 |
|
||||
| S3 | `quick-profile-*` 全族 | `styles/quick-profile.css` | 1,268 |
|
||||
| S4 | `workflow-*`(node / profile / persona / prompt / draft / material / subnode / preview / action / group / section / generation) | `styles/workflow.css` | ~1,400 |
|
||||
| S5 | `materials-*` | `styles/materials.css` | ~600 |
|
||||
| S6 | `image-*`(composer / preview / info / stage) | `styles/image-workspace.css` | ~400 |
|
||||
| S7 | **死规则**(41 条完全由死类构成) | 直接删 | **-277** |
|
||||
| S8 | `image-viewer-card/-actions/-stage`(与 `ImagePreviewDialog.vue:221-324` 的 scoped 副本**逐字节相同**) | 直接删 | **-104** |
|
||||
| S9 | `state-card` / `empty-state-actions` / `workflow-chat-panel` / `workflow-composer-panel`(子组件已有 scoped 等价副本) | 直接删 | **-32** |
|
||||
| S10 | 14 处完全相同的"眼眉标签"规则(`color: var(--text-soft); font-size: 12px; font-weight: 800`) | 合并成一条选择器列表规则 | **-50** |
|
||||
| S11 | 剩余全局 shell / body / token | 保留在 App.vue 或并入 `styles/workbench.css` | ~1,500 |
|
||||
|
||||
死类举例(名字极具迷惑性,容易误以为在改生效规则):`.workflow-node-card`(`:17764-17787`)——模板里节点卡实际用的是 `workflow-node-item`;`.generate-status-grid` / `.generate-feature-card` / `.generate-section` / `.generate-card-grid` 整组(`:21129-21286`)——`generateFeatureCards` computed 还在,但渲染它的模板早已改用 `quick-profile-command-card`。
|
||||
|
||||
**删 S7 前先固化规则**,仓库已有 `node --test tests/*.test.mjs` 的契约测试习惯:
|
||||
|
||||
```js
|
||||
// frontend/tests/dead-css.test.mjs
|
||||
// 断言 App.vue 样式块内的类必须能在某个模板中被引用;白名单放 Transition 派生类与动态拼接类
|
||||
```
|
||||
|
||||
注意保留 `.image-viewer-backdrop`(App.vue 模板里 4 个内联弹层仍在用),只删 `.image-viewer-card/-actions/-stage`。
|
||||
|
||||
**B. 模板块(11,359–14,143,2,784 行)**
|
||||
|
||||
| 块 | 行号区间 | 职责 | 目标产物 | 预计行数 |
|
||||
|---|---|---|---|---:|
|
||||
| T0 | 11,360–11,385 | app shell + 导航轨 + 标题栏 | **保留在 App.vue** | 26 |
|
||||
| T1 | 11,386–11,424 | 全局搜索框 / 结果面板 | `components/GlobalSearchBox.vue` + `useGlobalSearch()` | 39 |
|
||||
| T2 | 11,425–11,549 | 顶栏动作区(通知 / 日志 / 调色板 / 主题) | `components/TopBarActions.vue` | 125 |
|
||||
| T3 | 11,551–11,570 | 主题调色板浮层 | `components/ThemePalettePanel.vue` | 20 |
|
||||
| T4 | 11,571–11,623 | 通知中心浮层 | `features/notifications/NotificationPanel.vue` | 53 |
|
||||
| T5 | 11,626–11,646 | 生成页 hero + 三模式切换 | `features/generate/GenerateHeader.vue` | 21 |
|
||||
| T6 | 11,648–11,806 | 单图生成工作台 | `features/generate/ImageComposerPanel.vue` | 159 |
|
||||
| T7 | 11,807–12,269 | 快速角色工作台 | `features/quick-profile/QuickProfileWorkspace.vue` | 463 |
|
||||
| T8 | **12,270–12,987** | **详细工作流工作台(最大块)** | `features/workflow/WorkflowWorkspace.vue`,再内切 5 个子面板 | **718** |
|
||||
| T9 | 12,988–13,075 | 外部角色卡导入对话框 | `features/quick-profile/ExternalProfileImportDialog.vue` | 88 |
|
||||
| T10 | 13,077–13,329 | 角色档案问卷对话框 | `features/quick-profile/PersonaQuestionnaireDialog.vue` | 253 |
|
||||
| T11 | 13,377–13,630 | 素材库页 | `features/materials/MaterialsPage.vue` | 254 |
|
||||
| T12 | 13,631–13,760 | 队列页 | `features/queue/QueuePage.vue` | 130 |
|
||||
| T13 | 13,811–13,975 | 总览仪表盘 | `features/overview/OverviewPage.vue` | 165 |
|
||||
| T14 | 13,976–14,040 | 性能详情页 | `features/overview/PerformancePage.vue` | 65 |
|
||||
| T15 | 14,041–14,142 | 全局对话框挂载区 | `components/AppDialogHost.vue` | 102 |
|
||||
| T16 | 12,009–12,117 与 12,658–12,769 | **素材选择器弹层,逐字复制两份**(97 行里只有 5 行不同) | `features/materials/MaterialPickerPopover.vue`,props `{ category, placement?, extraClass? }`,事件 `select`/`clear` | **-100** |
|
||||
|
||||
T16 已经开始漂移:`reference.advanced` 的"进阶素材 · 高优先级"标记只有 workflow 侧有,quickProfile 侧看不到。
|
||||
|
||||
**C. 脚本块(1–11,357,11,356 行)**
|
||||
|
||||
| 块 | 行号区间 | 职责 | 目标产物 | 预计行数 |
|
||||
|---|---|---|---|---:|
|
||||
| C1 | 2,782–3,222 + 3,223–3,282 | `workflowActionCards` 巨型 computed + 标签表 | `features/workflow/workflow-action-cards.ts`(**纯数据,零风险搬运**) | ~500 |
|
||||
| C2 | 3,751–3,921 / 3,370–3,512 / 1,346–1,458 / 1,931–2,041 | generate / queue / material / quickProfile 四组动作卡 | 各自 `features/*/action-cards.ts` | ~580 |
|
||||
| C3 | 11,243–11,313 + 5,392 + 9,627 | 色彩工具(`materialColorTuple` / `alphaColor` / `mixColor` / `hexToRgb` / `toHexByte`) | `utils/color.ts` | ~90 |
|
||||
| C4 | 11,024–11,226 | 图片 URL / 占位图 / 媒体签名解析 | `composables/useMediaUrls.ts`(**必须先修 P1 副作用问题,见下**) | 203 |
|
||||
| C5 | 4,302–4,487 | 后端连接状态机 / bootstrap / 指数退避重连 | `composables/useBackendConnection.ts` | 186 |
|
||||
| C6 | 4,561–4,609 | 事件流轮询 | `composables/useEventStream.ts` | 49 |
|
||||
| C7 | 4,488–4,547 + 4,611–4,698 | dashboard / 成本 / 任务 / 日志 / 模型选项加载 | `composables/useDashboardData.ts` | 148 |
|
||||
| C8 | 4,700–4,786 | 设置页读写与校验 | `composables/useSettingsPage.ts` | 87 |
|
||||
| C9 | 4,787–4,862 + 5,316–5,620 + 9,993–10,310 | 素材库 | `composables/useMaterialLibrary.ts` | 663 |
|
||||
| C10 | 4,864–5,100 + 5,644–5,775 + 6,287–6,339 | 角色档案 + 衣橱 + 删除 | `composables/useProfilePage.ts` | 340 |
|
||||
| C11 | 5,776–6,154 | 快速角色四联图生成编排 | **优先下沉到后端**,残留 → `composables/useQuickCharacterGeneration.ts` | 379 |
|
||||
| C12 | 6,460–6,681 + 6,919–7,100 + 8,462–8,552 | 轮次 / 候选 / 反馈 / 确认 / 轮询 | `composables/useWorkflowRounds.ts` | 476 |
|
||||
| C13 | 7,101–7,264 | 节点素材绑定抽屉 | `composables/useWorkflowNodeMaterials.ts` | 164 |
|
||||
| C14 | 7,265–7,580 | 角色工作流创建 / 恢复 / 节点补齐 | `composables/useCharacterWorkflow.ts` | 316 |
|
||||
| C15 | 7,752–8,056 | 图片查看器 + 交叉审查对话框 | `composables/useImageViewer.ts` + `useWorkflowGenerationReview.ts` | 305 |
|
||||
| C16 | **8,058–9,250** | **工作流节点动作(最大块)** | `composables/useWorkflowNodeActions.ts` | **1,193** |
|
||||
| C17 | 9,251–9,763 | 问卷 → 档案 payload 构建 + 外部角色卡导入 | `composables/useQuickProfileArchive.ts` | 513 |
|
||||
| C18 | 9,765–9,940 | 12 个受控浮层管理 | `composables/useOverlayManager.ts`,**改注册表驱动** | 176 |
|
||||
| C19 | 10,312–10,510 | 队列动作 + 二次确认 | `composables/useQueueActions.ts` | 199 |
|
||||
|
||||
**C18 现在是两条 12 分支的 `if` 链**,且 `isOverlayOpen` 的兜底是 `return showLogPanel.value`——新增一个 `ControlledOverlay` 忘了加分支就会静默错判成"日志面板开着":
|
||||
|
||||
```ts
|
||||
const overlayRegistry: Record<ControlledOverlay, { isOpen(): boolean; setOpen(v: boolean): void }> = {
|
||||
search: { isOpen: () => searchPanelOpen.value, setOpen: (v) => { searchFocused.value = v; searchPanelOpen.value = v } },
|
||||
...
|
||||
}
|
||||
const isOverlayOpen = (k: ControlledOverlay) => overlayRegistry[k].isOpen()
|
||||
```
|
||||
|
||||
省 40 行并消除兜底陷阱。
|
||||
|
||||
**C4 拆之前必须先修**:`displayMediaUrl()`(`App.vue:11146`)是被 4 个 computed 和整个模板 render 直接调用的"伪纯函数",它内部会发起网络请求并整体替换 `resolvedMediaUrls` ref。`galleryImages` computed(`:997`)依赖这个 ref 又逐张调用它——每张图解析完成都让整个 `galleryImages` 重跑,1,000 张图 ≈ 100 万次调用。**照搬进 composable 只会把这条 P1 藏得更深。**(原判 P0-致命,复核确认缺陷成立、行号逐条无误,仅因"它是性能/内存问题而非数据正确性或安全问题"降为 **P1-严重**,见 [02-BUG清单.md](02-BUG清单.md) 的 P1-10。)正确做法是把媒体解析从"渲染时惰性触发"改成"数据加载时显式预取":`mediaUrl(raw)` 纯查表,`prefetchMediaUrls(rawUrls[])` 一次性写入,给 `resolvedMediaUrls` 加 LRU 上限并在淘汰时 `URL.revokeObjectURL`。
|
||||
|
||||
### 2.1.3 分阶段拆分顺序
|
||||
|
||||
**阶段 0 · 纯删,零风险(≈550 行)**
|
||||
`SettingsPage.vue:165` 的 `.backup-*` 死样式(单物理行 1,796 字符,格式化后约 45 行;备份面板早已拆成 `BackupPage.vue` 且用自己的 scoped 类名)+ `:167` 媒体查询里的 `.backup-grid,.backup-scope>div` → `workbench.css:442-451` 重复媒体查询 → `shared/types/workflow.ts:96-130` 过期类型副本 → 19 个零引用导出(含 `shared/types/integration.ts` 整文件)→ `tsconfig.json:15-17` 死别名 → 删 `pinia`/`vue-router` 并重排依赖。
|
||||
验证:`npm run typecheck` + `npm run test:contracts`。
|
||||
|
||||
**阶段 1 · 删死 CSS,需视觉回归(≈460 行)**
|
||||
先落地 `frontend/tests/dead-css.test.mjs`,再删 S7/S8/S9/S10。
|
||||
|
||||
**阶段 2 · 纯数据外迁,零模板改动(≈1,170 行迁出)**
|
||||
C1 + C2 五个动作卡工厂 + 4 张标签映射表 → `features/*/action-cards.ts`;C3 色彩工具 → `utils/color.ts`。这一步只是把 `const x = computed(...)` 换成 `const x = computed(() => buildXCards(deps))`,模板一行不改。**这是风险最低的一大块**,先做它能立刻把 script 从 11,356 压到 ~10,200。
|
||||
|
||||
**阶段 3 · 剪归属明确的组件样式(344+347 = 691 行迁出)**
|
||||
S1 剪进 `AppNavigationRail.vue`、S2 剪进两个 Material 对话框。这三个组件**当前离开 App.vue 就没有样式**,剪进去后它们才自洽、才能单独测试。`.rail` 这类需要父级配合的定位规则用 `:deep()` 或留在 `workbench.css`。
|
||||
|
||||
**阶段 4 · 无 UI 依赖的 composable(≈690 行迁出)**
|
||||
C5 连接状态机 → C6 事件流 → C19 主题偏好 → C7 dashboard 加载。这些不碰模板,只是把函数搬走并 `return` 出来。
|
||||
|
||||
**阶段 5 · 按 feature 切样式 + 组件化模板,从小到大**
|
||||
每一个 feature 都是"先切 CSS(S3–S6 对应块)→ 再搬模板 → 再搬 composable"三步。顺序:
|
||||
T9 外部导入对话框(88 行)→ T10 问卷对话框(253)→ T6 单图工作台(159)→ T16 素材选择器(**净删 100**)→ T11 素材库(254 + C9)→ T12 队列(130 + C19)→ T13/T14 总览(230)→ T7 快速角色(463 + C11/C17)。
|
||||
|
||||
**阶段 6 · 最后动工作流主工作台**
|
||||
T8(718 行模板)+ C12/C13/C14/C16(2,149 行脚本)+ S4(~1,400 行 CSS)。这是全仓耦合最深的一块(`workflowNodeActionError` 一个 ref 被 67 处赋值、同时承载成功与失败文案),放到最后做,前面五个阶段积累的 composable 模式此时已经成熟。
|
||||
|
||||
拆完后 App.vue ≈ **script 3,500 + template 350 + style <300 ≈ 4,200 行**。
|
||||
|
||||
## 2.2 跨组件重复模式
|
||||
|
||||
| 模式 | 处数 | 位置 | 削减 | 关键不一致 |
|
||||
|---|---:|---|---:|---|
|
||||
| **焦点陷阱(focus trap)** | **6** | `ConfirmDialog.vue:50-67`、`ImagePreviewDialog.vue:124-141`、`MaterialOperationDialog.vue:146-160`、`ProfileWardrobePane.vue:216-238`、`WorkflowCompareDialog.vue:48-59`、`WorkflowGenerationReviewDialog.vue:163-175` | ≈130 | 只有 `ConfirmDialog` 检查 `!dialogRef.contains(active)` 能把逃逸焦点拉回来,其余 5 份 `document.activeElement === first` 一旦焦点落到 `<body>` 就锁不住;`WorkflowCompareDialog` 的选择器少了 `input/select/textarea`。另有 `WorkflowMaterialDrawer.vue:149` 与 `SettingsPage.vue:131` 声明了 `aria-modal="true"` 却**零键盘管理**(Esc 无效、Tab 直接走到背景) |
|
||||
| **loader `loading/error/try/catch/finally` 样板** | **25** | `App.vue:4488/4511/4611/4624/4638/4673/4700/4787/4864/5010/6872/6894/7028/7115` 等 | ≈90 | `loadModelOptions`(`:4673`)**忘了 `try/finally`**,直接在末尾赋 `loadingModelOptions.value = false`,请求抛错时 loading 永久卡死 |
|
||||
| **写操作前置校验样板** | **27–40** | `App.vue:10025-10103`、`:10105-10134`、`:8222-8298`、`:8407-8460`、`:8554-8636` 等 | ≈400(与上一行部分重叠,计入 App.vue 拆分) | 五步骨架(`busy` 检查 → `backendWriteBlockMessage` → 置位 → try/catch → finally),漏 `finally` = 按钮永久卡死,漏 `backendWriteBlockMessage` = 绕过权限/连接检查 |
|
||||
| **图片缩放/拖拽逻辑** | 2 | `App.vue:7952-8011` vs `ImagePreviewDialog.vue:58-114`(同一套逻辑,变量名从 `scale/offset/dragging` 改成 `imageViewerScale/...`) | ≈95 | 魔数各写一遍:`0.5/4/0.12/2.2` vs `MIN_SCALE/MAX_SCALE/WHEEL_STEP/DOUBLE_CLICK_SCALE`;改一边的手感不会同步 |
|
||||
| **"选中项跟随列表" watch** | **8** | `App.vue:4055/4069/4083/4097/4184/4212/4226/4240` | ≈90 | 结构完全相同(列表空→清空选中;选中项不在列表→取第一项)→ `useSelectionSync(list, selectedId, keyOf)` |
|
||||
| **分页拉全量** | **4** | `loadAllJobs(:4686)`、`loadRemainingMaterialPages(:4840)`、`loadRemainingProfilePages(:4884)`、`loadGalleryImages(:4511)` | ≈70 | → `fetchAllPages(endpoint, params, keyOf)` |
|
||||
| **生成状态中文标签表** | **4** | `App.vue:6927-6939`、`WorkflowCandidatePool.vue:132-145`、`WorkflowRoundPanel.vue:113-129`、`shared/utils/presentation.ts:11-29` | ≈40 | 译法互相冲突:同一候选在候选池显示"已完成"、其它视图显示"已成功";`planned` 有"待入队"和"已规划"两种说法;App.vue 那份缺 `retrying`/`dead_letter`,重试中的候选直接显示英文 |
|
||||
| **图片 URL 白名单校验** | **4** | `features/profiles/profile-ui.ts:155`、`WorkflowCandidatePool.vue:165`、`WorkflowGenerationReviewDialog.vue:97`、`ProfileWardrobePane.vue:189` | ≈20 | 同一个正则 `/^(?:https?:\|data:\|blob:\|\/)/i` 抄 4 遍 |
|
||||
| **`errorMessage` / `normalizeStatus`** | 2 | `App.vue:11354` vs `AdvancedMaterialImportPage.vue:1354`;`AdvancedMaterialImportPage.vue:1350` vs `shared/utils/presentation.ts:7` | ≈8 | App.vue 版走 `readableApiError`(识别 `ApiClientError`、区分预览模式、给中文可读文案),进阶素材页版只 `err.message` |
|
||||
| **衣橱分类标签** | 2 | `ProfileWardrobePane.vue:40-46` vs `material-labels.ts:30-39` | ≈10 | `ProfileWardrobePane.vue:158` 的局部 `materialCategoryLabel(material: Material)` 与共享导出 `materialCategoryLabel(value: unknown)` **同名不同义**,IDE 跳转定义会歧义 |
|
||||
| **跨组件重复 CSS 声明块** | — | 全前端 CSS 14,698 行 | **700–1,100**(上限 2,251) | `overflow:hidden;text-overflow:ellipsis;white-space:nowrap` **21 次**;`color:var(--text-soft);font-size:12px;font-weight:800` **21 次**;`display:grid;gap:4px;min-width:0` **18 次**;`height:100%;object-fit:cover;width:100%` **14 次**;`button.primary-button` 在 6 个组件各定义一遍 |
|
||||
| **死组件** | 1 | `features/workflow/WorkflowDependencyContextCard.vue`(整个文件 279 行) | ≈279 | 全仓零引用,但 App.vue 仍在维护数据链路(`:792/793/794` 三个 ref + `loadWorkflowDependencyContext()` `:6894` + `:4129/7214/8324` 三处触发)——数据被拉了,展示组件不再挂载,改由 App.vue 内联渲染 |
|
||||
|
||||
**CSS utility 层是所有后续 CSS 迁移的前置**,先做它:
|
||||
|
||||
1. `styles/tokens.css`(当前仅 24 行)扩成真正的 token/utility 层:`.u-truncate`、`.u-eyebrow`、`.u-stack-4`、`.u-cover-img`、`.u-btn-primary`。
|
||||
2. `workbench.css` 是一层 458 行的**事后覆盖层**,专门用超长选择器列表去覆盖 App.vue 的既有规则——把它的覆盖规则回填进各自的基础规则,这一层可减到 150 行以内。
|
||||
|
||||
**共享代码要真的共享**:把 `readableApiError` / `backendWriteBlockMessage`(`App.vue:4356-4387`)下沉到 `shared/utils/api-error.ts`;`isBrowserImageUrl` 下沉到 `shared/utils/media-url.ts`;`generationStatusLabel` 收进 `shared/utils/presentation.ts` 作为唯一真源。
|
||||
|
||||
## 2.3 `plugin-page` vs `standalone-web` —— **重复代码量:0 行,不要动**
|
||||
|
||||
已实测确认:
|
||||
|
||||
- `plugin-page/src/App.vue` 只有 **7 行**,直接 `import WorkbenchApp from "../../standalone-web/src/App.vue"` 再 re-export。
|
||||
- `plugin-page/src/main.ts` 6 行。
|
||||
- 两份 `vite.config.ts` 各 16 行,**只有 `base` / `outDir` 不同**。
|
||||
|
||||
> **经复核确认**:这两份构建产物(`web/` 与 `pages/imagestudio/`)**不是**"误提交的编译产物",而是 `INSTALL.md` 明确定义的发布负载——ImageStudio 是 AstrBot 插件,装机路径是把仓库/ZIP 铺到 `data/plugins/`,**安装期没有任何 npm/vite 步骤**。两份构建的 `base` 必须不同(`web/index.html` 用绝对路径 `/api/v1/plugins/extensions/.../web/`,`pages/imagestudio/index.html` 用相对路径 `./assets/`),挂载于不同 URL 根,一份产物物理上无法同时服务两个挂载点。若把它们加进 `.gitignore`,`WebHostingService._resolve` 会直接抛 `RESOURCE_NOT_FOUND, "web asset not built"`,插件页面全线不可用。
|
||||
|
||||
**这套双构建方案已经是最优解。** 唯一值得补的是构建新鲜度校验(仓库无任何 CI;历史上有 24 次只更新 `web/assets`、3 次只更新 `pages/imagestudio/assets` 的提交),`frontend/package.json` 已提供 `"build": "npm run build:plugin && npm run build:web"`,把它接进 CI 即可。
|
||||
|
||||
**另**:`standalone-web/src/components/` 与 `features/` 下 25 个 `.vue` 全部有引用者(7 个走 `defineAsyncComponent`,`App.vue:39-45`),无未被引用的组件——`WorkflowDependencyContextCard.vue` 是唯一例外(见 2.2 末行)。
|
||||
|
||||
## 2.4 Pinia 装了但没用 —— **建议删掉,走 composable 路线**
|
||||
|
||||
**实测**:`grep -rn "pinia\|vue-router\|createRouter\|defineStore"` 在 `frontend/{shared,standalone-web,plugin-page,tests}` 下 **0 命中**。`main.ts`(4 行)从未 `createPinia()`。导航是 App.vue 里的 `activeNav` ref(`:5102 setActiveNav`)+ `navigation-config.ts`;状态管理是 206 个 `ref` + 203 个 `computed` 的巨型局部状态树。两个包在 `node_modules` 里占 1.1 MB(pinia 407 K + vue-router 691 K)。
|
||||
|
||||
**迁移成本与收益评估**:
|
||||
|
||||
| 方案 | 成本 | 收益 | 结论 |
|
||||
|---|---|---|---|
|
||||
| 引入 pinia store | 需先在 `main.ts` 接入 `createPinia()`;206 个 ref 要按域重新组织并改写全部 `.value` 访问路径;子组件要从 props/emit 改成 `useXxxStore()`;现有 8 个 `frontend/tests/*.mjs` 全是源码正则匹配,重构后**批量红** | 跨组件状态共享、devtools 时间旅行 | ❌ 本项目是**嵌入式插件页、无 SSR、无跨路由状态共享需求**,store 的核心卖点都用不上 |
|
||||
| 按 feature 抽 composable | 与仓库现有 `features/*/xxx-state.ts`(如 `advanced-material-state.ts`)的组织方式**一致**;每个 composable 返回自己的 state + actions,App.vue 只负责组装;可增量进行,一次一个 feature | 同样解决"改一个功能要打开 22,563 行文件";不引入新的心智模型 | ✅ **推荐** |
|
||||
|
||||
**行动**:删 `pinia` 与 `vue-router` 依赖(源码 0 行受影响),按 2.1.2 表 C 的清单逐个抽 composable。
|
||||
|
||||
## 2.5 `package.json` 依赖分类错误(已核实)
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"pinia": "^2.3.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-router": "^4.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
},
|
||||
"devDependencies": {}
|
||||
```
|
||||
|
||||
`devDependencies` 是空对象,`typescript`(23 MB)/ `vite`(2.7 MB)/ `vue-tsc` / `@vitejs/plugin-vue` 这些纯构建期工具全在 `dependencies`。
|
||||
|
||||
**插件发布只带预构建产物(`web/`、`pages/imagestudio/`),运行期完全不需要 `node_modules`——严格说 7 个依赖全部应该是 devDependencies。**
|
||||
|
||||
```json
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
同步更新 `package-lock.json`。收益:`npm ci --omit=dev` 变得有意义;SCA/许可证扫描不再把 23 MB 的 TypeScript 编译器算作运行期依赖;不再有人以为项目有路由和 store。
|
||||
|
||||
---
|
||||
|
||||
# 第三部分 · 仓库卫生
|
||||
|
||||
## 3.0 数据
|
||||
|
||||
| 项 | 规模 | 是否已跟踪 |
|
||||
|---|---|---|
|
||||
| `.tmp/` | **2.1 GB / 6,303 文件** | 否(`.gitignore:` `.tmp/` 生效) |
|
||||
| 根目录 `.tmp_pytest_*` | **19 个目录 / ≈515 MB** | 否(`.gitignore:` `.tmp_pytest*/` 生效) |
|
||||
| `release/` | **20 个 zip / 38 MB** | **是** |
|
||||
| `.git` | **51 MB** | — |
|
||||
|
||||
`.tmp/` 里有 8 个整仓库快照、22 个部署归档、~60 个一次性 `fix_*.py` / `patch_*.py` 脚本(说明有大量修补动作发生在版本控制之外)、40+ 个 pytest 输出目录。`deploy-1.0.35` 之所以 496 MB,是因为它把根目录的 `.tmp_pytest_*` 一起复制了进去——直接导致 `nas-deploy-worktree-20260724.tar` 达到 **546 MB**(正常插件包约 8 MB,膨胀 68 倍),3,000+ 个 pytest 临时文件被 scp 到 NAS。
|
||||
|
||||
## 3.1 ⚠️ 先做这一步:`.tmp/` 里 19 个 tar 包含真实密钥
|
||||
|
||||
**与 02 号报告呼应。** `.env.imagestudio_codex_handoff.yaml` **已被 gitignore、从未入库、不在 git 历史里**(`git ls-files | grep -i env` 为空,`git log --all --diff-filter=A` 确认),但审计实测确认它被**整目录复制**进 8 个 `deploy-*` staging 目录,并被打进 **19 个 `.tar.gz` / `.tar` 部署包**,而 `.tmp/` 里的 `deploy_remote.sh` / `upload_via_ssh.py` 会把这些包 ssh/scp 推送到 NAS。
|
||||
|
||||
文件内含(**仅描述类型、长度与前 4 位,绝不复述真实值**):
|
||||
|
||||
| 凭据 | 类型 | 特征 |
|
||||
|---|---|---|
|
||||
| 模型站点 A 的 API Key | OpenAI 兼容 key | 67 位,前 4 位 `sk-3` |
|
||||
| 模型站点 B 的 API Key | OpenAI 兼容 key | 51 位,前 4 位 `sk-B` |
|
||||
| PostgreSQL 连接 | host / port / user / **明文口令** | 内网地址 |
|
||||
| AstrBot 管理员 token | HS256 JWT | 136 位 |
|
||||
| AstrBot 管理员账号 | 用户名 + **明文口令** | 永不过期,可随时重签 JWT |
|
||||
|
||||
讽刺的是文件末尾还写着 `rules.redact_secrets: true`。
|
||||
|
||||
**顺序不能颠倒:先轮换,再删除,最后清 NAS。**
|
||||
|
||||
```powershell
|
||||
# 第 1 步:轮换(在删除任何东西之前)
|
||||
# - 两个模型站点的 API Key 作废重发
|
||||
# - PostgreSQL 用户改密
|
||||
# - AstrBot 管理员改密,并更换 JWT secret 使现有 token 失效
|
||||
|
||||
# 第 2 步:确认工作树干净,先看清楚要删什么
|
||||
git status --porcelain
|
||||
Get-ChildItem .tmp -Recurse -File -Force -Filter '.env*' | Select-Object FullName, Length
|
||||
Get-ChildItem .tmp -File -Force | Where-Object { $_.Name -match '\.(tar|tar\.gz|zip|b64)$' } |
|
||||
Select-Object Name, @{n='MB';e={[math]::Round($_.Length/1MB,2)}}
|
||||
|
||||
# 第 3 步:安全删除含密钥的归档与 staging 目录(先覆写再删,避免被恢复)
|
||||
Get-ChildItem .tmp -Recurse -File -Force -Filter '.env*' | ForEach-Object {
|
||||
$len = $_.Length
|
||||
[System.IO.File]::WriteAllBytes($_.FullName, (New-Object byte[] $len))
|
||||
Remove-Item $_.FullName -Force
|
||||
}
|
||||
Remove-Item -Recurse -Force .tmp
|
||||
|
||||
# 第 4 步:清理根目录 pytest 临时目录(≈515 MB)
|
||||
Get-ChildItem . -Directory -Force -Filter '.tmp_pytest*' | Remove-Item -Recurse -Force
|
||||
Remove-Item -Recurse -Force .pytest_cache -ErrorAction SilentlyContinue
|
||||
Get-ChildItem . -Directory -Recurse -Force -Filter '__pycache__' |
|
||||
Where-Object { $_.FullName -notmatch 'node_modules' } | Remove-Item -Recurse -Force
|
||||
```
|
||||
|
||||
**第 5 步(必须做):到 NAS 上删除已上传的同名包。** 本地删除不影响已推送出去的副本。
|
||||
|
||||
**第 6 步:从源头杜绝。** 打包脚本改用 `git archive`,不再"复制工作树":
|
||||
|
||||
```bash
|
||||
git archive --format=tar.gz --prefix=astrbot_plugin_imagestudio/ \
|
||||
-o dist/plugin-$(git describe --always).tar.gz HEAD
|
||||
# 末尾加断言,让泄漏在打包阶段就 fail
|
||||
tar -tf "$OUT" | grep -qE '(^|/)\.env' && { echo "SECRET LEAK"; exit 1; }
|
||||
```
|
||||
|
||||
**第 7 步:pytest 临时目录统一出口**,避免再散落到仓库根(`.gitignore` 里 `.pytest_tmp*/` 规则已存在):
|
||||
|
||||
```toml
|
||||
[tool.pytest.ini_options]
|
||||
addopts = "-q --basetemp=.pytest_tmp"
|
||||
```
|
||||
|
||||
**第 8 步:凭据改为环境变量注入。** `_conf_schema.json` 里已经有 `*_api_key_env_var` 字段,说明设计上本就支持——文件里只留 env var 名。
|
||||
|
||||
## 3.2 `release/` 停止跟踪(-38 MB 库内)
|
||||
|
||||
**现状**:`git ls-files release/` = **20 个 zip / 38 MB**,占已跟踪文件体积的大头。更糟的是 `astrbot_plugin_imagestudio-1.0.0.zip` ~ `1.0.6.zip` 每个 4.2 MB,里面装的是**运行期数据**:
|
||||
|
||||
```
|
||||
data/temp/provider_probe_B_image2_generation.json 1.76 MB (真实模型响应,含 b64 图片)
|
||||
data/temp/provider_probe_B_image2_generation.png 1.32 MB
|
||||
data/temp/s81_provider_runtime_b.png 0.76 MB
|
||||
data/db/imagestudio.db 0.29 MB (真实 SQLite 库)
|
||||
```
|
||||
|
||||
这与 `DEVELOPMENT.md` 自己写的"测试可使用临时目录,且不能把真实运行数据加入发布包"直接冲突。
|
||||
|
||||
**`.gitignore` 补丁**(**只加 `release/`,见 3.4 的警告**):
|
||||
|
||||
```gitignore
|
||||
# 发布产物:用 Git Release / 附件分发,不入库
|
||||
release/
|
||||
```
|
||||
|
||||
**停止跟踪但保留本地文件**:
|
||||
|
||||
```bash
|
||||
git rm -r --cached release
|
||||
git commit -m "chore: stop tracking release archives"
|
||||
```
|
||||
|
||||
做完这一步,`clone` 不再拉新的 release 包,但**历史里的 38 MB 仍在**。
|
||||
|
||||
## 3.3 从历史中剥离 `release/`(`git filter-repo`)—— 代价与风险
|
||||
|
||||
`git rm --cached` 只影响未来。要真正把 `.git` 从 51 MB 降下来,必须改写历史。
|
||||
|
||||
```bash
|
||||
# 需先安装 git-filter-repo(pip install git-filter-repo)
|
||||
# 强烈建议先做一份完整备份
|
||||
cp -r "AstrBot ImageStudio" "AstrBot ImageStudio.backup"
|
||||
|
||||
git filter-repo --path release --invert-paths
|
||||
git gc --aggressive --prune=now
|
||||
git push --force --all
|
||||
git push --force --tags
|
||||
```
|
||||
|
||||
**必须写清楚的代价**:
|
||||
|
||||
| 风险 | 说明 |
|
||||
|---|---|
|
||||
| **所有现有 clone 立刻失效** | 每一个 commit SHA 都会改变。团队每个人必须重新 clone,或执行 `git fetch && git reset --hard origin/<branch>`;任何未推送的本地分支需要 `git rebase --onto` 手工迁移 |
|
||||
| **引用旧 SHA 的一切都会断** | Issue/PR 里的 commit 链接、CHANGELOG 里的 SHA、部署脚本里钉死的 commit、`git describe` 生成的版本号 |
|
||||
| **需要 force push** | 若远端启用了分支保护,需要临时解除;解除期间任何人推送都会造成混乱 |
|
||||
| **早期 zip 里的真实数据不可撤销地存在于所有已有克隆中** | `imagestudio.db` 与 provider probe 响应已经分发出去过。改写历史只能防止**未来**的克隆拿到,不能收回已分发的副本。若这些数据敏感,需按数据泄漏流程处理,而不是只当成仓库瘦身 |
|
||||
|
||||
**判断**:这是单人/小团队仓库(`git user: <ADMIN_USERNAME:已脱敏>`),force push 的协调成本低。**建议做**,但严格按顺序:① 先完成 3.1 的密钥轮换(不要在历史改写的混乱期同时处理凭据);② 备份;③ 通知所有持有 clone 的人;④ 执行;⑤ 验证 `git log --oneline | wc -l` 与关键 tag 仍在。
|
||||
|
||||
**如果不想改写历史**,至少跑一次 `git gc --aggressive --prune=now` 回收部分空间——但 `release/` 的 38 MB 是可达对象,`gc` 收不回来。
|
||||
|
||||
## 3.4 ⚠️ 不要把 `web/assets` 和 `pages/imagestudio/assets` 加进 `.gitignore`
|
||||
|
||||
> **经复核推翻**:原始材料(C3)建议在 `.gitignore` 里加 `web/assets/` 和 `pages/imagestudio/assets/`,并断言这两个目录是"误提交的编译产物"、"两份重复 dist"、"每次提交 2MB 噪音淹没 diff"。复核逐条查证后推翻:
|
||||
>
|
||||
> 1. 这两个目录是 `INSTALL.md` 的"最小运行时清单"与"发布包白名单"明确定义的**发布负载**,与 `main.py`、`metadata.yaml` 并列。安装期没有 npm/vite 步骤。加进 `.gitignore` 会让 `WebHostingService._resolve` 抛 `RESOURCE_NOT_FOUND, "web asset not built"`,**插件页面全线不可用**。
|
||||
> 2. "两份重复"不成立——两份构建的 `base` 不同且必须不同,挂载于不同 URL 根,一份产物物理上无法同时服务两个挂载点。
|
||||
> 3. "2MB 噪音"与实测差一个数量级:最近 5 次 dist 提交的实际 stat 是 `24 files changed, 59 insertions(+), 69 deletions(-)`(`878f1f6`)、`24 files changed, 37 insertions(+), 27 deletions(-)`(`2dbf90b`)——git 的重命名检测把内容哈希改名识别成 `{index-CumvEEtc.js => index-CvjPX4dT.js}`,压缩产物是单行文件,每次只有几十行 diff。
|
||||
> 4. "git 累积大量永不复用的 blob"的归因也错了:`size-pack` 44 MB,而 `release/` 光当前树就占 37 MB——**仓库体积的主因是 release 包,不是 web/assets**。
|
||||
>
|
||||
> **`.gitignore` 补丁只加 `release/` 一行。** 同理,`DEVELOPMENT.md` 里"生产构建必须同时提交 `pages/imagestudio/` 的最新插件页面产物"这句是**对的**,不要改。
|
||||
|
||||
真正值得补的是**构建新鲜度校验**(历史上有 24 次只更新 `web/assets`、3 次只更新 `pages/imagestudio/assets` 的提交),加进 CI:
|
||||
|
||||
```bash
|
||||
npm run build # = build:plugin && build:web
|
||||
git diff --exit-code web pages || { echo "构建产物未与源码同步提交"; exit 1; }
|
||||
```
|
||||
|
||||
## 3.5 其余卫生项
|
||||
|
||||
| 项 | 位置 | 动作 |
|
||||
|---|---|---|
|
||||
| 4 份根目录 v3 设计文档已过期 | `imagestudio_api_contract_v3_ui_adjusted.md`、`imagestudio_codex_hermes_dev_flow_v3.md`、`imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md`、`imagestudio_ui_navigation_queue_s130.md` | 写于 2026-07-04~06,而 `metadata.yaml` 已是 `1.0.72`,中间隔了 70 个版本 / 约 230 次提交。`git mv` 到 `docs/archive/` 并在每份开头加一行归档说明 |
|
||||
| 未入库的测试文件 | `tests/test_prompt_expansion_stage_guard.py`(`git status` 显示 `??`) | 60 行 / 2 个用例,与它守护的 `backend/services/prompt_expansion_service.py` 改动一起提交——现在随时会被 `git clean` 抹掉 |
|
||||
| 编码损坏 | `config.yaml`(54 处私有区字符)、`metadata.yaml:5` `short_desc`(1 处,**插件市场直接展示**)、`CHANGELOG.md`(649 处) | 中文被 GBK 误解码后再存成 UTF-8,已不可逆。手工重写 `config.yaml` 与 `metadata.yaml` 优先(`config.yaml` 那 54 处注释是各字段语义的唯一文档);`DEVELOPMENT.md` 的 Windows 章节写明:写文件一律 `Out-File -Encoding utf8`,禁止裸 `>` 重定向 |
|
||||
| 无 CI | 无 `.github/`、无 `Makefile`、无任何 workflow | `DEVELOPMENT.md` 的"验证"只有 `compileall`,**一个测试都不跑**,而且它引用的 `scripts` 目录不存在(`Can't list 'scripts'` 但退出码仍是 0,静默通过)。加最小 CI:`python -m pytest -q` + `npm run typecheck` + `npm run test:contracts`,20 秒出结果 |
|
||||
| 21 个测试文件重复内联同一套 SQLite 夹具 | `tests/test_resource_access_service.py:15-77` 及其余 20 个 | 建 `tests/conftest.py`(顺带解决 3.1 里 pytest 的 `sys.path` 问题),提供 `sqlite_db` / `storage_config` / `ctx` 三个 fixture |
|
||||
| 测试硬 import Pillow | `tests/test_material_vision_input.py:6`(`from PIL import Image`) | `requirements.txt` **零依赖**且明确写着"为保持插件默认零依赖,不在这里强制安装 Pillow"。业务代码遵守了(软导入),测试没有——干净环境里整个 263 个用例套件一起挂。改成 `pytest.importorskip("PIL")`,并新建 `requirements-dev.txt` |
|
||||
| **`assert` 被当运行期保护** | `backend/services/wardrobe_service.py:128`(`delete_item` 的并发保护) | **`python -O` 下 assert 会被整体剥除,保护直接消失。** 换成显式 `if ...: raise ApiError(...)`。同处的衣柜分类还缺白名单校验 |
|
||||
| **`.part` 临时文件残留** | `backend/services/material_service.py:326` | `replace()` 失败时 `.part` 文件留在存储根,无任何清理,长期累积。改为 `try/finally` 中 `missing_ok=True` 删除 |
|
||||
| **PG 迁移执行器按分号裸切分** | `database/db_helper.py:280` | 迁移脚本里出现函数体、`DO $$ ... $$` 或字符串内分号即被切错并静默执行半条语句。与 02 报告 P1-8 的 PG 兼容性一并验证 |
|
||||
| **路由正则未 `re.escape`** | `adapters/astrbot_adapter.py:226`(`_match_endpoint`) | 端点模板含正则元字符时会产生非预期匹配。与 02 报告 §6 的路由表预编译缓存(`astrbot_adapter.py:47`)同一处改 |
|
||||
|
||||
> 上表后 4 行与其余若干条跨维度漏收项,完整清单见 [02-BUG清单.md](02-BUG清单.md) 的 **§6.1 终审补录**。
|
||||
|
||||
---
|
||||
|
||||
# 第四部分 · 不建议做的事
|
||||
|
||||
判断力体现在知道哪些"看起来能精简"的地方不该动。以下每一条都有明确理由。
|
||||
|
||||
## 4.1 不要合并 `engines/` 的四个 flow 文件
|
||||
|
||||
`single_flow.py`(455)与 `review_flow.py`(451)是**真正的引擎**,与其它 flow 零重复。`character_flow.py`(145)/ `fast_character_flow.py`(50)/ `quick_profile_flow.py`(32)是**纯声明式节点模板目录**,三者真正重复的只有约 11–15 行的列表推导样板,而它们的 metadata 契约各不相同(`stage_code` + `canonical_node_key` + per-step `node_type` 覆盖 vs `quick_character_target` vs `profile_draft`/`profile_preview`)。抽公共构造器要引入配置参数把差异重新表达出来,代码量不降、理解成本上升,还把三种工作流的演进耦合在一起。**当前"声明数据与业务逻辑分离、每种工作流一个独立目录"的形态是对的。**
|
||||
|
||||
## 4.2 不要忽略 `web/` 与 `pages/imagestudio/`
|
||||
|
||||
见 3.4。这是被复核推翻的原始建议,照做会让插件页面全线不可用。
|
||||
|
||||
## 4.3 不要合并 `plugin-page` 与 `standalone-web` 的双构建
|
||||
|
||||
见 2.3。重复代码量实测为 **0 行**——`plugin-page/src/App.vue` 只有 7 行 re-export。两份 `vite.config.ts` 的 `base` 差异是功能性的,不是冗余。
|
||||
|
||||
## 4.4 不要为了删代码而引入 pinia
|
||||
|
||||
见 2.4。pinia 在依赖里但零使用,正确的处理是**删掉它**而不是"既然装了就用起来"。嵌入式插件页、无 SSR、无跨路由状态共享,store 的核心卖点全用不上;引入它意味着 206 个 ref 全部改写 + 8 个源码正则测试批量红。走 composable 路线,与仓库现有 `features/*/xxx-state.ts` 的组织方式一致。
|
||||
|
||||
## 4.5 不要把 `_string_list` 的 17 处无脑合并成一个函数
|
||||
|
||||
见 1.3。它们**语义确实不同**(是否切逗号 / 是否去重 / 是否排序 / 是否收 tuple-set),17 个调用点分别依赖各自的行为。合并成一个"统一实现"会静默改变其中一部分调用点的输出。正确做法是拆成三个**语义显式命名**的函数,逐处判断该用哪个。这也是它优先级排在 P3、放在工具函数收敛最后做的原因。
|
||||
|
||||
## 4.6 不要在补齐路由层测试之前动 `@route_handler` 装饰器
|
||||
|
||||
见 1.13。148 个 handler 的 `service=` 参数是现有测试的注入点,而路由层测试本身就薄。**先加 1.14 的注册表契约测试(一次覆盖 166 条,成本极低),再谈重构。**
|
||||
|
||||
## 4.7 不要为了"减行数"去压行
|
||||
|
||||
`App.vue:4549-4559`、`components/MaterialDetailDialog.vue:34-58`、`features/settings/BackupPage.vue:14-25`、`features/settings/ReviewPolicyPanel.vue:14`(整个 `<style scoped>` 是一行 1,000+ 字符)已经是压行风格:
|
||||
|
||||
```ts
|
||||
// App.vue:4549 —— 与文件其余部分的 Prettier 风格冲突
|
||||
const prompt=imageGenerationPrompt.value.trim()
|
||||
if(!prompt||promptExpansionBusy.value)return
|
||||
...
|
||||
}catch(err){imageGenerationError.value=`提示词扩写失败:${errorMessage(err)}`}finally{promptExpansionBusy.value=false}
|
||||
```
|
||||
|
||||
这让行数统计失真、`git diff` 一行全红/全绿无法审查、无法用 lint 自动格式化。**正确方向是反过来——引入 Prettier(`printWidth: 110`,与现有多数代码一致)把它们展开。** 展开后 CSS/TS 总行数会上升约 800 行,但这是把隐藏的复杂度显性化,后续所有重复检测与删除都会更可靠。**先展开、再统计、再删除**,否则"精简"的账面收益是假的。
|
||||
|
||||
## 4.8 不要删 `requeue_dead_letters` / `update_pool_preferences` 之前不问
|
||||
|
||||
这两个在 1.6 的死代码表里,但它们**看起来是产品功能**(死信重入队、候选池偏好)。删之前先确认是"计划中但没做完"还是"已废弃"。如果是前者,转成 issue 再删代码——**不要留半成品在代码库里冒充已交付功能**,但也不要在没人确认的情况下直接删掉某人正在做的东西。
|
||||
|
||||
## 4.9 不要把 `backend/routes/params.py` 直接当成共享工具模块
|
||||
|
||||
`params.py` 里确实有想要的实现(`optional_str` / `optional_text`),但它在 `backend/routes` 包下。让 `database/repositories/` 和 `engines/` 去 import `backend.routes.*` 是**层级倒置**——数据层依赖路由层。新建 `core/coerce.py` 才是对的落点(见 1.2)。同样的教训已经发生过一次:`backend/services/workflow_round_worker_runtime.py:10` 反向 `from backend.routes.node_routes import create_generation_service`。
|
||||
|
||||
## 4.10 不要在 `App.vue` 拆分时"顺手"照搬 `displayMediaUrl`
|
||||
|
||||
见 2.1.2 的 C4 说明。把一个带副作用的伪纯函数原样搬进 `composables/useMediaUrls.ts`,只会让 O(N²) 重算和 Blob 无界累积藏得更深、更难被发现。**拆分是修它的机会,不是搬运它的借口。**
|
||||
381
审计/05-优化路线图.md
普通文件
381
审计/05-优化路线图.md
普通文件
|
|
@ -0,0 +1,381 @@
|
|||
# 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` 复核定位。
|
||||
118
审计/README.md
普通文件
118
审计/README.md
普通文件
|
|
@ -0,0 +1,118 @@
|
|||
# AstrBot ImageStudio 代码审计
|
||||
|
||||
**审计对象**:`AstrBot ImageStudio` 插件仓库
|
||||
**分支 / 基线**:`codex/character-profile-document-import` @ `8040a1b`(工作树含未提交改动)
|
||||
**审计日期**:2026-07-27
|
||||
**审计范围**:仓库全部源码(后端 Python ~64,100 行、前端 Vue/TS 39,254 行、测试 11,559 行)
|
||||
**排除范围**:`.tmp/` 部署快照、`.tmp_pytest_*`、`node_modules/`、`__pycache__/`、`release/` 内的源码、`web/` 与 `pages/imagestudio/` 的构建产物内容
|
||||
|
||||
---
|
||||
|
||||
## 状态:✅ 已完成(含终审校验)
|
||||
|
||||
| 环节 | 状态 |
|
||||
|---|---|
|
||||
| 15 个维度并行审计 | ✅ 完成 · 产出 214 条发现 |
|
||||
| C0 测试实跑验证 | ✅ 完成 · 后端 263 passed / 188.72s,前端 26 passed,`typecheck` (strict) 通过 |
|
||||
| 对抗式复核(P0/P1 逐条) | ✅ 完成 · 覆盖 56 条,**推翻 16 条**,维持 40 条(其中 **33 条下调**严重度,仅 7 条维持原判) |
|
||||
| 5 份主报告汇总 | ✅ 完成 |
|
||||
| **终审校验**(推翻项回扫 / 密钥泄露检查 / 数字一致性 / 行号抽验 / 漏收回扫) | ✅ 完成 · 见下方「终审记录」 |
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
| 文件 | 一句话摘要 | 关键结论 |
|
||||
|---|---|---|
|
||||
| [01-总览与架构.md](01-总览与架构.md) | 规模统计、五层架构地图、依赖热点、前后端契约面。 | 约 350 文件 / 115,000 行;`App.vue` 22,563 行、`advanced_style_set_service.py` 4,491 行是两座巨石;扇入 Top3 是 `core.identity`(65) / `database.db_helper`(56) / `backend.dto.common`(54)。 |
|
||||
| [02-BUG清单.md](02-BUG清单.md) | 缺陷清单:**94 条**成立缺陷(P0×1 / P1×10 / P2×64 / P3×19),含两条完整可利用攻击链、逐条位置与修复建议。 | 唯一 P0 是打进 19 个部署 tar 并推送到 NAS 的 5 类真实凭据(**必须轮换,删文件无效**)。P1 集中在权限分级缺失、五链路 IDOR、队列 LIFO、PG 后端不可用、`displayMediaUrl` 副作用。 |
|
||||
| [03-耦合分析.md](03-耦合分析.md) | 后端内部耦合 + 前后端耦合:9 条分层违规、35 个分散装配函数、11 处业务逻辑双写、类型契约漂移。 | **病灶不是"接错线",是"没有装配台"**——组合根缺失导致 34 处各自重读 `config.yaml`、同一个 `WorkflowService` 被装配成行为不一致的实例。URL 层很干净(166 条路由 ↔ 143 个 endpoint,**零个会 404**),漏的是"规则"没被下发。 |
|
||||
| [04-代码精简方案.md](04-代码精简方案.md) | 可执行的精简方案:净删 **≈3,513 行**(后端 1,746 / 前端 1,767),另 ≈7,200 行属 App.vue 迁出;含仓库卫生与 **10 条"不建议做的事"**。 | 后端:连接样板 ×131、`_optional_text` ×30、`_string_list` ×17。前端:拆 `App.vue` **必须 CSS 先行**(8,395 行未 `scoped` 的全局样式才是拆不动的直接原因)。 |
|
||||
| [05-优化路线图.md](05-优化路线图.md) | 决策文档:5 个阶段(止血 → 安全边界 → 正确性 → 解耦 → 精简)、风险矩阵、量化目标、5 人日 / 20 人日两套投入方案、方法与 7 条局限声明。 | **前三阶段(≈4 周)解决"会出事",后两阶段解决"改得慢",不要倒过来做。** 阶段 0(凭据轮换)是唯一不可被插队的 24 小时事项。 |
|
||||
| [findings/](findings/) | 15 个维度的原始发现(分维度独立文件)+ `_raw.json` 结构化全量 + `_复核结论.md` 复核意见全文。 | 原始材料,**严重度以主报告为准**(原始发现未经复核校准)。 |
|
||||
|
||||
---
|
||||
|
||||
## 发现总数与复核统计
|
||||
|
||||
### 按维度
|
||||
|
||||
15 个并行维度,共 **214 条**发现:
|
||||
|
||||
| 维度组 | 维度 | 条数 |
|
||||
|---|---|---:|
|
||||
| A · 功能域 | A1 生成与队列 13 · A2 工作流与轮次 11 · A3 素材与风格集 14 · A4 数据层 11 · A5 核心与安全 13 · A6 引擎与适配器 15 · A7 路由与插件入口 13 · A8 前端 App 主体 12 · A9 前端功能组件 15 | 117 |
|
||||
| B · 耦合 | B1 前后端耦合 17 · B2 后端内部耦合 14 | 31 |
|
||||
| C · 横向 | C1 后端精简 20 · C2 前端精简 15 · C3 测试与仓库卫生 14 · C4 横切关注点 17 | 66 |
|
||||
| **合计** | | **214** |
|
||||
|
||||
(另有 C0「测试实跑结果」,为基线事实而非发现。)
|
||||
|
||||
### 按类别与严重度(原始判定)
|
||||
|
||||
| 类别 | 条数 | | 原始严重度 | 条数 |
|
||||
|---|---:|---|---|---:|
|
||||
| bug | 59 | | P0-致命 | 6 |
|
||||
| hygiene | 46 | | P1-严重 | 51 |
|
||||
| coupling | 34 | | P2-中等 | 104 |
|
||||
| simplify | 28 | | P3-轻微 | 53 |
|
||||
| perf | 24 | | | |
|
||||
| security | 23 | | | |
|
||||
|
||||
### 复核统计(对抗式验证)
|
||||
|
||||
对全部 **56 条 P0/P1** 各派一名独立复核者,立场预设为「**默认这是误报**」,要求实际 Read 源码后方可判定成立。
|
||||
|
||||
| 结果 | 条数 | 占比 |
|
||||
|---|---:|---:|
|
||||
| **推翻**(误报,不得作为成立缺陷收录) | **16** | 29% |
|
||||
| 维持但**下调**严重度 | **33** | 59% |
|
||||
| 维持原判 | 7 | 12% |
|
||||
|
||||
复核后严重度分布(56 条):P0 × 1 · P1 × 9 · P2 × 20 · P3 × 26(含 16 条推翻项的 P3 残留定级)。
|
||||
换算成"原判 → 现判":原判 P0 的 6 条只剩 **1** 条仍是 P0(凭据泄露),3 条降 P1、1 条降 P2、1 条被推翻;原判 P1 的 50 条中仅 **6** 条维持 P1,19 条降 P2、10 条降 P3、15 条被推翻。
|
||||
|
||||
> **误报率 29% + 下调率 59% 本身就是一条结论**:并发类与影响链类推演的出错率很高,动手修之前先写一个能复现的测试,红了再改。
|
||||
|
||||
**16 条被推翻的发现按类别**:bug 9 · perf 2 · security 1 · coupling 1 · hygiene 3。其中 12 条属 `bug/security/perf`(02 报告的收录范围),已全部从"成立的缺陷"中剔除 —— 11 条的残留技术债按复核给出的降级严重度收录在 02 §6 的 P3 表并标注「经复核降级」、**不计入 94 条统计**;剩余 1 条(SQLite 未启用 WAL)的残留内容与另一条独立成立的 P2 性能发现指向同一处代码,已合并。
|
||||
|
||||
复核同时修正了原报告的事实错误,例如:泄露文件的 `api_key_plaintext` 实际在第 **25** 行(原报告写 :26);`_string_list` 真实是 **17** 处而非 18 处(多算的在 `.tmp/` 构建快照里);"23 个 service 零测试"经 `coverage 7.15.2` 实测证伪(真实为 9 个模块 ≈1,966 行零执行)。
|
||||
|
||||
被推翻条目的完整复核意见见 [findings/_复核结论.md](findings/_复核结论.md),**16 条逐条附完整反驳论证**。
|
||||
|
||||
---
|
||||
|
||||
## 终审记录(2026-07-27)
|
||||
|
||||
对 5 份主报告做了一轮独立终审,检查项与结果:
|
||||
|
||||
| 检查项 | 结果 |
|
||||
|---|---|
|
||||
| **被推翻的 16 条是否仍被当成立缺陷写进主报告** | 发现 **2 处**并已修正:03 §1.1 复述了被证伪的「单测构造 `GenerationService` 需连带 import 31 个依赖」(`tests/test_workflow_round_queue_runtime.py:12` 直接反证);03 §2.2 #3 复述了被证伪的 `adopt-image` 触发路径(`history_service.py:55` 原子写两字段,真实路径是 `image_service.select_image`)。 |
|
||||
| **是否出现真实密钥值** | ✅ 未发现。全文仅出现类型 / 长度 / 前 4 位(`sk-3` / `sk-B` / `eyJh`),无完整 key、无 JWT、无口令、无 IP。 |
|
||||
| **严重度是否与复核结论一致** | 发现 **7 处**不一致并已修正:03 §2.2 三条误标"维持 P1"(实为 P2/P2/P3);03 三处路线图行沿用 P1;02 §0.2/0.3 标题误标 P1(实为 P2);04/05 三处把 `displayMediaUrl` 标为 P0(复核降为 P1);05 风险矩阵与 3-8 沿用了被证伪的"无法自恢复的报错"。 |
|
||||
| **数字是否自相矛盾** | 发现 **4 处**并已实测校准:`App.vue` 的 `endpoints.` 引用 171 → **183**;`ref`/`computed` 计数 133/135 与 206/203 两种口径混用 → 已统一为 206/203 并注明字面量口径;`main.py` 短命令别名 50 → **38**;`_optional_text` 28 → **30**。已核对无误的数字:`App.vue` 22,563 行(script 11,356 / template 2,784 / style 8,395)、`main.py` 2,580 行、`RouteSpec` 166 条、`endpoints.ts` 143 键、`_string_list` 17 处、`core/queue_manager.py` 112 行、前端 39,254 行。 |
|
||||
| **`文件:行号` 是否编造**(抽验 14 处高危引用) | ✅ **全部命中**。逐条 Read 确认:`main.py:104-106`(BRIDGE_PERMISSIONS) · `main.py:2337`(赋权) · `core/runtime_paths.py:43-45`(绝对路径放行) · `core/storage.py:51-53`(`will_overwrite` 未被使用) · `profile_repository.py:46`(字面量 `%`) · `job_repository.py:150`(`ORDER BY created_at DESC`) · `single_flow.py:61`(只读 `aspect_ratio`) · `chat_media_import_service.py:33-36`(裸 `read_bytes`) · `App.vue:11146`(`displayMediaUrl`) · `App.vue:997`(`galleryImages`) · `App.vue:4576`(`slice(-1)`) · `workflow-lock-state.ts:12`(`sealed_at`) · `routes/common.py:12-16`(吞异常) · `settings_service.py:614`(明文快照)。泄露文件的 5 处凭据行号(:25/:45/:57-61/:73/:75-76)亦经字段名核对无误。 |
|
||||
| **是否有维度被漏收**(回扫 `_raw.json` 全部 214 条) | 发现 **17 条**未被任何主报告覆盖,已补录:10 条集中在 A1/A2/A3/A4/A5/C4(补入 02 §6.1)、4 条耦合项(补入 03 附二)、4 条卫生项(补入 04 §3.5)、3 条并入 05 的阶段 1/2 任务(1-5b 归属校验语义统一、2-8 并发限流空操作、2-12b 通知链路静默失败)。**106 条 `bug/security/perf` 发现经逐条比对,全部在 02 报告中有对应条目**(含复核修正后的定位)。 |
|
||||
|
||||
补录中最值得注意的三条:
|
||||
|
||||
1. `backend/services/profile_service.py:160` —— `ProfileService._require_owner` **不认管理员权限**,与 `ResourceAccessService._can_access` 语义相反。做 IDOR 改造(05 阶段 1 的 1-3~1-5)前必须先统一,否则矛盾会被扩散到五条链路。
|
||||
2. `backend/services/worker_service.py:400` —— `_BoundedWorkerHandler` 的并发限流**在生产配置下是空操作**,且限流点位于「认领之后」,与 05 的 2-8 背压项同源。
|
||||
3. `backend/services/workflow_round_worker_runtime.py:262` —— 主动通知的三个失败出口**一行日志都没有**,用户收不到轮次完成通知且运维无从得知。
|
||||
|
||||
---
|
||||
|
||||
## 阅读顺序建议
|
||||
|
||||
- **决策者 / 只有 10 分钟** → [05-优化路线图.md](05-优化路线图.md) 的「§1 一页纸结论」+「§5 投入产出建议」。
|
||||
- **今天就要动手** → [02-BUG清单.md](02-BUG清单.md) 的「§0 立即处置」(凭据轮换清单 + 3 个低成本断链点)。
|
||||
- **要理解为什么这样改** → [03-耦合分析.md](03-耦合分析.md) 的「§1.4 装配分散」+「§2.2 业务逻辑重复实现」。
|
||||
- **排期与工作量** → [05-优化路线图.md](05-优化路线图.md) 的「§3 分阶段路线图」。
|
||||
- **质疑某条结论** → 先看 [findings/_复核结论.md](findings/_复核结论.md) 是否已被推翻,再看 `findings/` 下对应维度的原始证据。
|
||||
|
||||
## 使用本报告的三条注意
|
||||
|
||||
1. **严重度以主报告为准,不要用 `findings/` 里的原判**。原始发现未经复核校准,误报率实测 29%。
|
||||
2. **动手前先写一个能复现的测试**。并发类与性能类结论以静态分析为主,未做压测与浏览器实跑(局限声明见 05 §6)。
|
||||
3. **行号会漂移**。本报告基于 `8040a1b`,定位前请 `git blame` 复核。
|
||||
29
审计/_泄漏归档清单.txt
普通文件
29
审计/_泄漏归档清单.txt
普通文件
|
|
@ -0,0 +1,29 @@
|
|||
.tmp/astrbot_plugin_imagestudio-1.0.35.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.36.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.37.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.38-20260720-092843.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.39-20260720-095704.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.40-20260720-100538.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.41-20260720-101338.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.64.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.65.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.67-20260724-232031.tar.gz
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.68-20260724-234603.tar.gz
|
||||
.tmp/imagestudio-1.0.66-deploy-20260724-224910.tar.gz
|
||||
.tmp/imagestudio-material-card-popup-20260724.tar.gz
|
||||
.tmp/imagestudio-material-picker-anchored-20260724.tar.gz
|
||||
.tmp/imagestudio-material-picker-modal-20260724.tar.gz
|
||||
.tmp/imagestudio-material-picker-smart-placement-20260724.tar.gz
|
||||
.tmp/imagestudio-material-popup-20260724.tar.gz
|
||||
.tmp/nas-deploy-worktree-20260724-clean.tar
|
||||
.tmp/nas-deploy-worktree-20260724.tar
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.62.zip
|
||||
.tmp/astrbot_plugin_imagestudio-1.0.63.zip
|
||||
.tmp/deploy-1.0.35/
|
||||
.tmp/deploy-clean-1.0.35/
|
||||
.tmp/deploy-clean-1.0.36/
|
||||
.tmp/deploy-clean-1.0.37/
|
||||
.tmp/deploy-stage-1.0.38-20260720-092843/
|
||||
.tmp/deploy-stage-1.0.39-20260720-095704/
|
||||
.tmp/deploy-stage-1.0.40-20260720-100538/
|
||||
.tmp/deploy-stage-1.0.41-20260720-101338/
|
||||
412
审计/findings/A1-生成与队列.md
普通文件
412
审计/findings/A1-生成与队列.md
普通文件
|
|
@ -0,0 +1,412 @@
|
|||
# A1 · 生成流水线 / 任务队列 / 重试 / 并发
|
||||
|
||||
> 审计范围(实际通读的源文件):
|
||||
> - `backend/services/generation_service.py`
|
||||
> - `backend/services/queue_service.py`
|
||||
> - `backend/services/worker_service.py`
|
||||
> - `backend/services/generation_job_retry_service.py`
|
||||
> - `backend/services/workflow_round_service.py`
|
||||
> - `backend/services/workflow_round_worker_runtime.py`
|
||||
> - `backend/services/cost_guard_service.py`、`backend/services/cost_service.py`
|
||||
> - `backend/services/chat_workflow_service.py`(并发相关片段)
|
||||
> - `backend/routes/node_routes.py`、`backend/routes/job_routes.py`
|
||||
> - `core/queue_manager.py`、`core/fsm.py`、`core/event_bus.py`
|
||||
> - `database/repositories/job_repository.py`、`database/db_helper.py`(连接部分)
|
||||
> - `engines/single_flow.py`、`engines/image_provider.py`(超时部分)
|
||||
> - `main.py`(插件生命周期 / asyncio 调度部分)
|
||||
|
||||
## 摘要
|
||||
|
||||
队列的 **状态机 + CAS(compare-and-set)设计整体是认真的**:`update_if_status` / `update_if_status_unless_workflow_cancelled` / `delete_if_status` 都做了单条 SQL 内的条件更新,`cancel_job` 也有重读循环,这一层没有明显的丢更新。真正的问题集中在 **队列语义之外**:
|
||||
|
||||
1. `QueueService.update_task()` 是**无条件 UPDATE**,而 worker 的成功路径和失败路径全都走它,导致"并发取消被覆盖"的竞态真实存在(P1)。
|
||||
2. `QueueWorker._claim_next` 依赖 `JobRepository.list(... ORDER BY created_at DESC)`,队列实际是 **LIFO**,积压超过 `claim_batch_size` 后老任务永久饿死(P1)。
|
||||
3. 插件 `terminate()` 无法保证 worker 线程退出(provider 调用最长 3600s,join 超时 5s),重载后**新旧两套 worker 池同时抢同一批任务**(P1)。
|
||||
4. 详细工作流轮次候选任务 `task_type="workflow_round_candidate"` 被 `GenerationJobRetryService._validate_executable` 硬拒,而 worker 侧 `RetryPolicy(max_attempts=1)` 又等于关闭重试——**异步候选一次网络抖动就是终态失败,无任何重试通道**(P1)。
|
||||
5. 同步生成路径(`generate_node`)在 asyncio 默认线程池里长时间阻塞、无并发上限、无背压;`recover_stale_tasks` 只在 worker 启动时跑且只认 `source=workflow_round`,`nodes.generate` 崩溃残留永远卡在 running。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] `QueueService.update_task()` 无 CAS,worker 完成写入会覆盖并发取消
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:406`、`database/repositories/job_repository.py:206`、`backend/services/worker_service.py:116`
|
||||
- **问题**:`update_task` 只做「读 → 校验迁移 → 无条件 UPDATE」,底层 `JobRepository.update` 的 WHERE 子句只有 `task_id`,没有任何状态谓词。而 `QueueWorker.run_once` 的成功路径、`_handle_failure` 的失败/重排队路径全部调用它。仓库里明明已有 `update_task_if_status` / `update_if_status` 这套 CAS 原语,worker 却没有使用。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# queue_service.py:406
|
||||
def update_task(self, task_id: str, payload: dict[str, Any], ctx: RequestContext) -> GenerationTask:
|
||||
before = self.get_job(task_id) # ← 读
|
||||
status = payload.get("status")
|
||||
if status is not None:
|
||||
self._validate_task_status_transition(before.status, str(status))
|
||||
after = self.repository.update(task_id, payload) # ← 无条件写,before.status 没进 WHERE
|
||||
```
|
||||
|
||||
```python
|
||||
# job_repository.py:215
|
||||
conn.execute(
|
||||
f"""
|
||||
UPDATE generation_tasks
|
||||
SET {", ".join(assignments)}
|
||||
WHERE task_id = {placeholder} # ← 只有 task_id
|
||||
""",
|
||||
```
|
||||
|
||||
```python
|
||||
# worker_service.py:106-134
|
||||
latest = self.queue_service.get_job(task.task_id)
|
||||
if latest.status == "cancelled": # ← 检查点
|
||||
...
|
||||
completed = self.queue_service.update_task( # ← 写入点,两点之间可被取消
|
||||
task.task_id, {"status": update.status, ...}, ctx)
|
||||
```
|
||||
- **影响**:用户点"取消",worker 恰好在此刻出图完成:取消在 `update_task` 的 `get_job` 之后、`UPDATE` 之前提交,则 `cancelled` 被直接改写为 `succeeded`(或 `_handle_failure` 里改写为 `failed` / `queued`)。取消语义失效,已取消的轮次会重新变成"运行中",`cancel_workflow_jobs` 也可能被同样方式回滚。计费与图片记录随之产生(用户已明确取消却仍被扣费)。
|
||||
- **修复建议**:worker 的三处写入全部换成 CAS。`run_once` 成功路径改为 `update_task_if_status(task_id, {"running"}, payload, ctx, require_workflow_not_cancelled=True)`,返回 `None` 时按"任务已被他人接管"处理(清理已生成产物并返回 cancelled 结果);`_handle_failure` 的 `failed` 写入用 `{"running"}` 作为期望态、重排队写入用 `{"failed"}` 作为期望态。长期建议把 `QueueService.update_task` 标记为内部/管理用途,禁止 worker 调用。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 队列是 LIFO:`ORDER BY created_at DESC` + 固定 batch 导致老任务永久饿死
|
||||
|
||||
- **位置**:`database/repositories/job_repository.py:150`、`backend/services/worker_service.py:208`
|
||||
- **问题**:worker 认领任务时复用了通用列表接口 `list_jobs(status="queued", page=1, page_size=claim_batch_size)`,而该接口为了给前端做"最新在前"用的是 `ORDER BY created_at DESC`。于是队列变成后进先出,且每次只看最新的 `claim_batch_size`(round pool 为 25)条。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# job_repository.py:145-154
|
||||
rows = conn.execute(
|
||||
f"""
|
||||
SELECT {TASK_COLUMNS}
|
||||
FROM generation_tasks
|
||||
{where_clause}
|
||||
ORDER BY created_at DESC # ← 队列消费用了倒序
|
||||
LIMIT {placeholder} OFFSET {placeholder}
|
||||
""",
|
||||
```
|
||||
|
||||
```python
|
||||
# worker_service.py:207-221
|
||||
def _claim_next(self, ctx: RequestContext) -> GenerationTask | None:
|
||||
queued = self.queue_service.list_jobs(status="queued", page=1, page_size=self.claim_batch_size).items
|
||||
for candidate in queued:
|
||||
if _retry_deferred(candidate):
|
||||
continue
|
||||
```
|
||||
- **影响**:只要待处理队列长度稳定 > 25,最早入队的候选永远排不到(新任务不断插到窗口顶端)。用户表现为"某个轮次一直卡在 queued,后创建的轮次却先出图"。另外 `_retry_deferred` 被延迟的任务也会白占这 25 个名额,进一步缩小可认领窗口。SQLite 的 `created_at` 是 `CURRENT_TIMESTAMP`(秒级),同一秒创建的 4~8 个候选顺序还完全不确定。
|
||||
- **修复建议**:给 `JobRepository` 增加专用的认领查询,`ORDER BY created_at ASC, task_id ASC`(FIFO + 稳定次序),并让 `_claim_next` 调用它而不是复用展示用的 `list`;同时把 `created_at` 的精度提升到毫秒(或增加自增 `seq` 列)以消除同秒歧义。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 插件重载后旧 worker 线程仍存活,与新 worker 池并发抢占同一队列
|
||||
|
||||
- **位置**:`backend/services/worker_service.py:180`、`backend/services/worker_service.py:428`、`backend/services/workflow_round_worker_runtime.py:67`、`main.py:434`
|
||||
- **问题**:`QueueWorker.stop()` 只是 `set()` 停止事件后 `join(timeout=5s)`。停止事件仅在 `_run_loop` 的循环顶部被检查,而 `run_once` 内部会阻塞在 provider HTTP 调用上(`engines/image_provider.py` 允许 10~3600 秒)。join 超时后 `stop()` 直接返回 `running: True`,而 `Main.terminate()` 无视这个返回值把 runtime 置 None。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# worker_service.py:180-185
|
||||
def stop(self, *, timeout_seconds: float = 5.0) -> dict[str, Any]:
|
||||
self._stop_event.set()
|
||||
thread = self._thread
|
||||
if thread is not None:
|
||||
thread.join(timeout=max(float(timeout_seconds), 0.1))
|
||||
return {"worker_id": self.worker_id, "running": self.is_running()} # ← 可能是 True
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:434-441
|
||||
async def terminate(self) -> None:
|
||||
...
|
||||
if self.round_worker_runtime is not None:
|
||||
self.round_worker_result = self.round_worker_runtime.stop()
|
||||
self.round_worker_runtime = None # ← 不管 running 是否为 True 都丢弃
|
||||
```
|
||||
- **影响**:AstrBot 热重载/插件重启时,旧的 5 个 daemon 线程仍在跑(进程没退出),新的 `create_workflow_round_worker_runtime()` 又起 5 个。两批 worker 共享同一张 `generation_tasks` 表:CAS 能防止同一条任务被同时认领,但**旧线程完成时会用 P1-1 描述的无条件 `update_task` 写回结果**,而新进程的 `recover_stale_tasks()` 又会把超过 300 秒仍在 running 的任务(可能正被旧线程执行)标记 failed 后重新入队 → 同一候选被生成两次,重复计费、重复落图。worker 数量还会随着每次重载线性膨胀。
|
||||
- **修复建议**:
|
||||
1. `QueueWorker.stop()` 在 join 超时后返回明确的 `stopped: False`,`QueueWorkerPool.stop()` 聚合该标志;
|
||||
2. `Main.terminate()` 在 `stopped=False` 时**不要**丢弃 runtime,而是保留引用并拒绝再次 `start()`,或将 stop 超时提升到略大于 provider 超时;
|
||||
3. 给每个 worker 分配 `worker_uuid`(进程级唯一),`update_task` 时用 `metadata.worker.worker_id` 作为 CAS 条件之一,旧进程的写入直接被拒绝;
|
||||
4. `recover_stale_tasks` 增加"当前进程 worker 心跳"判断,避免抢走仍在执行的任务。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 轮次候选任务无任何重试路径:worker 侧 `max_attempts=1`,Web 侧 `task_type` 被硬拒
|
||||
|
||||
- **位置**:`backend/services/workflow_round_worker_runtime.py:45`、`backend/services/generation_job_retry_service.py:180`、`backend/services/generation_service.py:361`
|
||||
- **问题**:两条重试通道同时被关死。
|
||||
- worker 侧:round pool 显式传 `RetryPolicy(max_attempts=1)`,而 `should_retry` 的判定是 `if attempt >= max(int(self.max_attempts), 1): return False`。首次执行 `attempt` 已经是 1(`claim_queued_task` 先自增 `worker_attempt`),所以**永远返回 False**。
|
||||
- Web 侧:候选任务的 `task_type` 是 `"workflow_round_candidate"`,而重试服务只接受 `"generation"`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# workflow_round_worker_runtime.py:39-49
|
||||
self.pool = QueueWorkerPool(
|
||||
self.queue_service, self._execute,
|
||||
retry_policy=RetryPolicy(max_attempts=1), # ← 等于关闭重试
|
||||
task_filter=_is_workflow_round_task, ...)
|
||||
```
|
||||
|
||||
```python
|
||||
# generation_service.py:356-364
|
||||
return self.queue_service.create_task({
|
||||
...
|
||||
"task_type": "workflow_round_candidate", # ← 非 "generation"
|
||||
```
|
||||
|
||||
```python
|
||||
# generation_job_retry_service.py:180-191
|
||||
def _validate_executable(self, task: GenerationTask) -> None:
|
||||
if task.task_type != "generation" or not task.node_id or not isinstance(task.request, dict):
|
||||
raise ApiError(ErrorCode.TASK_NOT_RETRYABLE,
|
||||
"task has no executable generation request", ...)
|
||||
```
|
||||
- **影响**:详细工作流一个候选遇到 429 / 连接重置 / provider 5xx,立即变成终态 `failed`;`/jobs/{id}/retry` 返回 `TASK_NOT_RETRYABLE`;`workflow_round_service` 里也没有候选级重试接口。用户唯一出路是重建整轮(重新走 `prepare_persisted_generation`,成功的候选也一起重做),成本与语义都错。顺带地,`worker_service.py` 的 `_retry_deferred`/`next_retry_at` 退避逻辑和 `workflow_round_service.py:750` 的 `status == "queued" → retry_scheduled` 分支全部成了死代码。
|
||||
- **修复建议**:
|
||||
1. round pool 改为 `RetryPolicy(max_attempts=3, base_delay_seconds=2.0, backoff_multiplier=2.0, retryable_error_types=("ImageProviderError",))`,并确认 `should_retry` 的 `attempt` 语义(当前 `attempt=1` 即首次,`>=` 应改为 `>` 或把 `max_attempts` 理解成"总次数"后统一);
|
||||
2. `GenerationJobRetryService._validate_executable` 放开 `task_type in {"generation", "workflow_round_candidate"}`,并为候选类型走 `enqueue_prepared_generation` 重新入队(而不是 `generate_node` 同步执行);或在 `WorkflowRoundService` 上新增 `retry_candidate(round_id, candidate_id)`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 同步生成占满 asyncio 默认线程池,全插件无并发上限与背压
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:119`、`main.py:333`、`backend/services/chat_workflow_service.py:216`
|
||||
- **问题**:`nodes/generate`(Web 与聊天共用)走的是**完全同步**的 `_generate_node_locked`:任务刚 `create_task(status="queued")` 就立刻 CAS 成 `running` 并在同一个调用栈里发起 provider 请求,整个过程持有进程内的 per-node `RLock`。所有 Web/桥接请求又都通过 `asyncio.to_thread(dispatch_web_request, ...)` 派发到 **asyncio 默认线程池**(`min(32, cpu+4)`)。没有任何信号量或专用 executor 限制并发生成数量。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# generation_service.py:119-126
|
||||
def generate_node(self, node_id, payload, ctx) -> dict[str, Any]:
|
||||
lock_entry = _retain_node_generation_lock(node_id)
|
||||
lock_entry.lock.acquire()
|
||||
try:
|
||||
return self._generate_node_locked(node_id, payload, ctx) # ← 内含 provider 阻塞调用
|
||||
finally:
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:333-340
|
||||
response = await asyncio.to_thread( # ← 默认 executor,全插件共用
|
||||
dispatch_web_request, ctx, dispatch_method, dispatch_endpoint, ...)
|
||||
```
|
||||
|
||||
```python
|
||||
# chat_workflow_service.py:216-220 (已经在一个 to_thread 线程里,再嵌套 4 线程池)
|
||||
with ThreadPoolExecutor(max_workers=4, thread_name_prefix="imagestudio-chat-fast") as executor:
|
||||
futures = {executor.submit(self.generate_node, str(node["node_id"]), chat): node for node in nodes}
|
||||
```
|
||||
- **影响**:单次 provider 调用默认 180 秒、最高允许 3600 秒(`engines/image_provider.py:308-313`)。十几个并发 `nodes/generate` 就能把默认 executor 占满,此后**所有** ImageStudio Web API(列表、状态轮询、取消)一起挂起——包括用来取消这些生成的接口。`快速角色` 命令还会为每个聊天用户额外派生 4 个线程池线程且 `with` 退出时 `shutdown(wait=True)` 不可中断,N 个用户 = 4N 路并发 provider 请求,成本无上限。
|
||||
- **修复建议**:
|
||||
1. 为生成建立独立的、容量可配的 `ThreadPoolExecutor`(例如 4~8),`dispatch_web_request` 继续用默认池,二者隔离;
|
||||
2. 在 `GenerationService` 入口加进程级 `threading.BoundedSemaphore(max_concurrent_generations)`,取不到时快速返回 `429 / QUEUE_BUSY` 而不是排队阻塞;
|
||||
3. `chat_workflow_service` 的 4 图并发改为复用同一个全局生成池,而不是每次新建。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `_BoundedWorkerHandler` 的并发限流在生产配置下完全是空操作,且限流点位于"认领之后"
|
||||
|
||||
- **位置**:`backend/services/worker_service.py:400`、`backend/services/worker_service.py:443`、`backend/services/workflow_round_worker_runtime.py:48`
|
||||
- **问题**:全局信号量容量等于 worker 线程数,per-route 信号量在唯一的生产构造里也等于 worker 线程数(`per_route_limit=worker_count`)。线程数 == 许可数,`acquire()` 永远不会阻塞。更根本的是:限流器包在 `handler` 上,而 `run_once` 是**先 `_claim_next()` 把任务 CAS 成 `running`,再调用 handler**——一旦真的配置成 `per_route_limit < worker_count`,被阻塞的线程会拿着已经 `running` 的任务空等,任务的 `updated_at` 停滞,最终被 `recover_stale_tasks` 误判为"上个进程遗留"。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# worker_service.py:400-405
|
||||
count = min(max(int(worker_count), 1), 16)
|
||||
bounded_handler = _BoundedWorkerHandler(
|
||||
handler,
|
||||
global_limit=count, # ← 等于线程数
|
||||
per_route_limit=min(max(int(per_route_limit or count), 1), count),
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# worker_service.py:451-459
|
||||
def __call__(self, task: GenerationTask) -> ...:
|
||||
route_key = _task_route_key(task)
|
||||
with self._route_guard:
|
||||
route_semaphore = self._route_semaphores.setdefault(route_key, threading.BoundedSemaphore(self.per_route_limit))
|
||||
with self.global_semaphore, route_semaphore: # ← 任务此时已是 running
|
||||
return self.handler(task)
|
||||
```
|
||||
|
||||
```python
|
||||
# workflow_round_worker_runtime.py:39-49
|
||||
per_route_limit=worker_count, # ← 与 worker_count 相同,限流失效
|
||||
```
|
||||
- **影响**:对同一 provider/model 的突发保护形同虚设(本意应是防止把单个模型打爆触发 429)。若日后按注释意图调小 `per_route_limit`,则立刻引入"已认领任务排队等待信号量"的队头阻塞 + 假性 stale 误判。
|
||||
- **修复建议**:把限流前移到认领之前——`_claim_next` 里按 `route_key` 先 `acquire(blocking=False)`,拿不到就跳过该候选去看下一条(不认领);`per_route_limit` 默认值改为小于 `worker_count` 的值(例如 `max(1, worker_count // 2)`)并接入配置。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `recover_stale_tasks` 只在 worker 启动时执行,且只认 `source=workflow_round`,同步生成崩溃后节点永久锁死
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:439`、`backend/services/queue_service.py:470`、`backend/services/workflow_round_worker_runtime.py:55`、`backend/services/generation_service.py:574`
|
||||
- **问题**:全仓库对 `recover_stale_tasks` 的唯一调用点是 `WorkflowRoundWorkerRuntime.start()`,且固定传 `source="workflow_round"`;其它来源的任务被直接 `skipped: source_not_managed`。而 `nodes.generate` 创建的任务 `metadata.source = "nodes.generate"`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# queue_service.py:470-480
|
||||
for candidate in candidates:
|
||||
task_source = str(candidate.metadata.get("source") or "").strip()
|
||||
if source is not None and task_source != source:
|
||||
skipped.append({"task_id": candidate.task_id, "status": candidate.status,
|
||||
"reason": "source_not_managed"})
|
||||
continue
|
||||
```
|
||||
|
||||
```python
|
||||
# generation_service.py:574-585 —— 节点被 running 任务锁住
|
||||
active_task = self._active_generation_task(node)
|
||||
if node.status in {"queued", "running"} and active_task is not None:
|
||||
raise ApiError(ErrorCode.VALIDATION_FAILED, "generation is already in progress for this node", ...)
|
||||
```
|
||||
- **影响**:进程在同步生成中途被杀(AstrBot 重启、容器 OOM)后,该任务永远停在 `running`,节点也停在 `running`。用户再点生成得到"generation is already in progress",且**没有自动恢复**——只能手动去 `/jobs/{id}/cancel` 把任务取消才能解锁节点。另外整个进程生命周期内没有周期性 stale 巡检,运行中挂死的任务只能等下一次插件重载。
|
||||
- **修复建议**:
|
||||
1. 把 `source` 过滤改成可选白名单,`nodes.generate` 也纳入恢复(恢复动作改为"标记 failed + 释放节点",因为它没有 worker 可重新执行);
|
||||
2. 增加一个后台巡检线程(或复用 worker 循环的 idle 分支)周期性调用 `recover_stale_tasks`,而不是只在 `start()` 跑一次;
|
||||
3. 恢复时同步修复 `workflow_nodes.status` / `metadata.last_task_id`,避免任务恢复了但节点还锁着。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `recover_stale_tasks` 无重试次数上限,会跨进程重启无限重排队
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:481`
|
||||
- **问题**:恢复逻辑只在 metadata 里写一个会被覆盖的 `recovery` 字典,没有累加计数,也没有"超过 N 次进 dead_letter"的出口。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# queue_service.py:481-521
|
||||
recovery = {
|
||||
"source": "plugin_startup_stale_recovery",
|
||||
"observed_at": ...,
|
||||
"previous_status": candidate.status,
|
||||
}
|
||||
failed = self.update_task_if_status(candidate.task_id, {candidate.status},
|
||||
{"status": "failed", ..., "metadata": {**candidate.metadata, "recovery": recovery}}, ctx)
|
||||
...
|
||||
queued = self.update_task_if_status(failed.task_id, {"failed"},
|
||||
{"status": "queued", ..., "metadata": {**failed.metadata,
|
||||
"recovery": {**recovery, "status": "requeued"}}}, ctx, require_workflow_not_cancelled=True)
|
||||
```
|
||||
- **影响**:某条任务如果稳定地让 worker 卡死(例如 provider 对该 prompt 永远超时、或反序列化时崩线程),每次插件重启都会把它重新入队,形成跨重启的无限重试。既浪费额度,也可能反复拖垮同一个 worker。`dead_letter` 状态在这条路径上从未被使用。
|
||||
- **修复建议**:在 metadata 里维护 `recovery.attempts`(`int(previous.get("attempts") or 0) + 1`),超过阈值(如 3)时不再 requeue,直接迁移到 `dead_letter` 并在 `error_message` 里写明原因;`recover_stale_tasks` 的返回值中额外报告 `dead_lettered` 列表供诊断 UI 展示。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 轮次候选的 `timeout_seconds` 只写进 metadata,执行时从未被读取
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:355`、`backend/services/generation_service.py:373`、`backend/services/generation_service.py:2305`、`engines/single_flow.py:163`
|
||||
- **问题**:`enqueue_prepared_generation` 计算出路由级超时并存进 `metadata["timeout_seconds"]`,但 `execute_claimed_generation` 构造 `runtime_request` 时既没有把它回填进请求,`single_flow_engine` 也只读 `request.get("timeout_seconds")`。全仓库 grep 显示该 metadata 键没有任何读取点。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# generation_service.py:355-373
|
||||
timeout_seconds = _round_timeout_seconds(request, prepared.get("route_resolution"))
|
||||
return self.queue_service.create_task({
|
||||
...,
|
||||
"metadata": {..., "timeout_seconds": timeout_seconds, ...}, # ← 只写不读
|
||||
}, ctx)
|
||||
```
|
||||
|
||||
```python
|
||||
# single_flow.py:163
|
||||
timeout_seconds=_optional_timeout_seconds(request.get("timeout_seconds")), # ← 读的是 request,不是 metadata
|
||||
```
|
||||
- **影响**:轮次准备阶段基于路由 `settings.timeout_seconds` 算出的超时被静默丢弃,实际生效的是 provider 全局配置(`model_provider_runtime.py` 的 `provider.timeout_seconds or 180`)。为长耗时模型单独调大/为快模型调小的意图无效;同时 metadata 上的数字会误导排障(看到 600 实际生效 180)。此外整个 worker 执行路径**没有任何 wall-clock 上限**,只有 HTTP socket 超时,若 provider 慢速滴数据可以远超预期地占住 worker 线程。
|
||||
- **修复建议**:`execute_claimed_generation` 在构造 `runtime_request` 时加上 `runtime_request.setdefault("timeout_seconds", task.metadata.get("timeout_seconds"))`;并在 `QueueWorker.run_once` 外层加一个基于该值的整体看门狗(例如在独立线程执行 handler 并 `join(timeout)`,超时后写 failed 并记录 `timeout` 错因)。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] worker 执行成功但回写失败时,已落库的图片记录被孤立且不清理
|
||||
|
||||
- **位置**:`backend/services/worker_service.py:104`、`backend/services/generation_service.py:492`
|
||||
- **问题**:`execute_claimed_generation` 内部一旦成功就已经通过 `image_service.create_image` 把图片元数据写进数据库并返回;随后 worker 才调用 `update_task` 回写任务。若这一步抛异常(任务被并发取消导致状态迁移校验失败、数据库瞬时错误),`run_once` 的 `except Exception` 只会走 `_handle_failure` 把任务标记 failed,**不会**回收刚创建的图片记录与磁盘文件。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# generation_service.py:492-496 —— 成功路径已落库
|
||||
created = self.image_service.create_image(image_payload, ctx)
|
||||
...
|
||||
# worker_service.py:104-146
|
||||
try:
|
||||
update = _normalize_update(self.handler(task)) # ← handler 已经建好 image 记录
|
||||
...
|
||||
completed = self.queue_service.update_task(...) # ← 这里抛错
|
||||
except Exception as exc:
|
||||
return self._handle_failure(task, exc, ctx) # ← 只改任务状态,不清理图片
|
||||
```
|
||||
- **影响**:候选在 UI 上显示"失败"(`handle_task_terminal` 写入 `image_id=None`),但图库里多出一张无人引用的图片和磁盘文件,且计费统计(`CostService.usage_summary` 按 `generated_images` 行统计)仍会把它计入成本。反复发生会污染图库。
|
||||
- **修复建议**:把"落库图片"与"回写任务"放进同一个补偿边界:`WorkflowRoundWorkerRuntime._execute` 捕获回写失败后调用 `generation_service._cleanup_generation_outputs`;或让 `_execute` 返回 `image_ids` 并由 `_on_terminal` 在 `current_task.status == "failed"` 且 `claimed_task` 曾产出图片时执行清理。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `cancel_job` 的重读循环无次数上限与退避
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:134`
|
||||
- **问题**:`while True` 在 CAS 失败时无限重试,既无最大轮数也无 sleep。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# queue_service.py:135-172
|
||||
while True:
|
||||
before = self.get_job(task_id)
|
||||
...
|
||||
after = self.repository.update_if_status(task_id, {before.status}, {...})
|
||||
if after is not None:
|
||||
break
|
||||
# The task changed after it was read. Re-evaluate ...
|
||||
```
|
||||
- **影响**:若某条任务被高频写入(例如 P1-1 描述的 worker 无条件 `update_task` 与取消互相打架),该循环会变成忙等,持续开关 SQLite 连接并占住调用线程。正常情况下 1~2 轮即可收敛,属低概率但无兜底。
|
||||
- **修复建议**:加最大重试轮数(如 5)与极短退避;超出后抛 `ApiError(TASK_NOT_CANCELABLE, "task status is changing too fast")`,让调用方重试而不是把线程锁死在服务层。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `_ensure_round_enqueued` 的轮次元数据回写在 `_reconcile_lock` 之外,存在丢更新
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:928`、`backend/services/workflow_round_service.py:799`
|
||||
- **问题**:`reconcile_round` 明确用 `self._reconcile_lock` 串行化"读候选 → 聚合 → 写轮次",但 `_ensure_round_enqueued` 末尾的"读 latest.metadata → 写回 status=queued"这一对读写没有走同一把锁。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# workflow_round_service.py:928-940
|
||||
latest = self.round_repository.get_round(round_record.round_id) or round_record # ← 读
|
||||
self.round_repository.update_round(round_record.round_id, {
|
||||
"status": "queued",
|
||||
"metadata": {**latest.metadata, "planned_only": False, "task_ids": task_ids}, # ← 写,中间无锁
|
||||
})
|
||||
self.reconcile_round(round_record.round_id, ctx)
|
||||
```
|
||||
- **影响**:入队线程(HTTP 请求线程)与 worker 线程的 `reconcile_round` 交错时,worker 刚写入的 `execution_summary` 会被这里的 `{**latest.metadata}` 快照覆盖;轮次 `status` 也会被短暂回退到 `queued`。后面的 `reconcile_round(...)` 通常能纠正 status,但 metadata 里的聚合信息可能丢失一轮。
|
||||
- **修复建议**:把 `_ensure_round_enqueued` 末尾这段读-改-写包进 `with self._reconcile_lock:`,或直接改用仓储层的条件更新(只更新 `task_ids` / `planned_only` 两个键而不是整块 metadata 覆盖)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `_record_generation_failure` 与 `_clear_retry_preparation` 里的裸 `except Exception: pass`
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:1865`、`backend/services/generation_service.py:1887`、`backend/services/generation_job_retry_service.py:388`、`backend/services/generation_job_retry_service.py:399`
|
||||
- **问题**:失败记录与重试准备清理这两条"补偿路径"里的异常被完全静默吞掉,没有 `logger.exception`,也没有任何可观测输出(该模块甚至没有 import logging)。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# generation_service.py:1852-1888
|
||||
try:
|
||||
failed_task = self.queue_service.update_task_if_status(task.task_id, {"queued", "running"}, {...}, ctx)
|
||||
except Exception:
|
||||
pass # ← 任务没能标记 failed,无任何痕迹
|
||||
...
|
||||
except Exception:
|
||||
pass # ← 节点没能标记 failed,无任何痕迹
|
||||
```
|
||||
|
||||
```python
|
||||
# generation_job_retry_service.py:378-399
|
||||
if isinstance(preparation, dict) and ...:
|
||||
metadata.pop("retry_preparation", None)
|
||||
workflow_service.update_node(node.node_id, {"metadata": metadata}, ctx)
|
||||
except Exception:
|
||||
pass # ← retry_preparation 残留在节点/工作流 metadata 上
|
||||
```
|
||||
- **影响**:任务/节点未能落到 `failed` 时,前端会看到一个永远停在 `running` 的节点,而日志里没有任何线索可定位;`retry_preparation` 残留会让后续 `_prepare_node` 的所有权判定读到过期 `task_id`。对比 `worker_service.py` 里同类补偿路径都规范地写了 `logger.exception`,这里属于明确的可观测性缺口。
|
||||
- **修复建议**:在 `generation_service.py` / `generation_job_retry_service.py` 中引入 `logger = logging.getLogger(__name__)`,把这 4 处 `pass` 换成 `logger.exception("...", task_id, node_id)`,并在返回给调用方的 `failure` 字典中加上 `bookkeeping_failed: True` 标志,让 UI 能提示"状态可能不一致,请手动刷新/取消"。
|
||||
426
审计/findings/A2-工作流与轮次.md
普通文件
426
审计/findings/A2-工作流与轮次.md
普通文件
|
|
@ -0,0 +1,426 @@
|
|||
# A2 · 工作流 / 轮次 / 分支 / 交叉评审 状态机
|
||||
|
||||
> 审计范围(实际逐行通读的源文件):
|
||||
> - `backend/services/workflow_round_service.py`
|
||||
> - `backend/services/workflow_service.py`
|
||||
> - `backend/services/workflow_generation_cross_review_service.py`
|
||||
> - `backend/services/generation_cross_review_service.py`
|
||||
> - `backend/services/workflow_feedback_interpreter.py`
|
||||
> - `backend/services/workflow_round_feedback_service.py`
|
||||
> - `backend/services/branch_lineage_service.py`
|
||||
> - `backend/services/workflow_round_worker_runtime.py`
|
||||
> - `backend/services/generation_job_retry_service.py`(前 120 行)
|
||||
> - `backend/routes/round_routes.py`
|
||||
> - `database/repositories/workflow_round_repository.py`
|
||||
> - `database/repositories/workflow_cross_review_repository.py`
|
||||
> - `database/models.py`、`database/migrations/0014_workflow_generation_rounds.sql`、`database/db_helper.py`(connect 部分)
|
||||
> - `frontend/standalone-web/src/App.vue`(轮次相关片段:2336-2340、7030-7075)
|
||||
>
|
||||
> 另:已用 `python -c` 实际执行 `WorkflowFeedbackInterpreter` / `WorkflowRoundFeedbackService` 验证 F4、F5 两条发现。
|
||||
|
||||
## 摘要
|
||||
|
||||
轮次状态机的**写入口分散且没有统一的状态守卫**:`WorkflowRoundRepository.update_round()` 是一个裸 UPDATE,`_ensure_writable_round_row()` 的只读保护只在 `apply_feedback_atomic` / `confirm_candidate_atomic` 等少数事务里生效,而 `_ensure_round_enqueued()` 和 `reconcile_round()` 绕过它无条件改写 `status`。结果是 `confirmed` / `superseded` 这两个终态可以被普通的幂等重放或迟到的 worker 回调**回退成 `queued` / `completed`**,从而击穿"已定稿轮次只读"和"跨评审必须复用已确认候选"两条核心不变量。
|
||||
|
||||
分支层面,`create_next_round` 把父轮次标记 `superseded` 之后没有任何机制阻止父轮次继续被 reconcile 回写,也没有 `next_round_id` 唯一性守卫(交叉评审侧有 `next_review_round_id`,主轮次侧没有),同一父轮次可以分叉出多个"下一轮"并互相覆盖节点的 `active_round_id`。
|
||||
|
||||
反馈解释器方面,LLM 路径对**扁平结构的模型输出会静默丢弃全部候选偏好**(只保留 patch),确定性回退路径会把用户文本里的普通数字("不要 3 个人"、"分辨率 512")当作候选编号,导致**误拒候选**或直接 400。
|
||||
|
||||
性能上 `list_node_rounds → _persisted_detail` 是典型 N+1,且本仓库每次仓储调用都 `sqlite3.connect()` 新建连接,一次轮次列表加载可产生数十条独立连接,而前端还在轮询该接口。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P0-致命] `update_round` 无状态机守卫:已确认(confirmed)轮次可被幂等重放静默回退,击穿只读锁与跨评审校验
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:115`、`backend/services/workflow_round_service.py:928`、`database/repositories/workflow_round_repository.py:416`
|
||||
- **问题**:
|
||||
`create_round` 命中 idempotency_key 重放分支时,会**无条件**调用 `_ensure_round_enqueued(existing, ctx)`;该方法末尾又**无条件**把轮次 `status` 写成 `"queued"`,随后 `reconcile_round` 依据候选聚合把它改成 `completed`。整条链路上没有任何一处检查 `existing.status` 是否已经是 `confirmed` / `superseded` 这类终态,而 `update_round` 本身只是一条裸 UPDATE,`_ensure_writable_round_row()` 的只读保护完全没有参与。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_service.py:115-117 —— 幂等重放路径
|
||||
if self.generation_service is not None:
|
||||
self._ensure_round_enqueued(existing, ctx)
|
||||
return {**self.get_round(existing.round_id).to_dict(), "created": False, "idempotent_replay": True}
|
||||
```
|
||||
```python
|
||||
# workflow_round_service.py:928-940 —— 无条件覆写 status
|
||||
latest = self.round_repository.get_round(round_record.round_id) or round_record
|
||||
self.round_repository.update_round(
|
||||
round_record.round_id,
|
||||
{
|
||||
"status": "queued",
|
||||
"metadata": {
|
||||
**latest.metadata,
|
||||
"planned_only": False,
|
||||
"task_ids": task_ids,
|
||||
},
|
||||
},
|
||||
)
|
||||
self.reconcile_round(round_record.round_id, ctx)
|
||||
```
|
||||
```python
|
||||
# workflow_round_repository.py:416-431 —— 裸 UPDATE,不校验当前 status
|
||||
def update_round(self, round_id: str, payload: dict[str, Any]) -> WorkflowGenerationRound | None:
|
||||
assignments, params = _round_update_assignments(payload, self.placeholder)
|
||||
...
|
||||
conn.execute(
|
||||
f"UPDATE workflow_generation_rounds SET {', '.join(assignments)} WHERE round_id = {self.placeholder}",
|
||||
tuple(params),
|
||||
)
|
||||
```
|
||||
对照被绕过的守卫:
|
||||
```python
|
||||
# workflow_round_repository.py:1364-1369
|
||||
if status == "confirmed":
|
||||
raise WorkflowRoundWriteError(
|
||||
"round_already_confirmed",
|
||||
"confirmed workflow round is read-only",
|
||||
{"round_id": round_id},
|
||||
)
|
||||
```
|
||||
- **影响**:
|
||||
客户端(或 AstrBot 聊天侧)用同一个 `idempotency_key` 重试 `POST nodes/{id}/rounds`(网络超时后的正常重试即可触发,不需要并发),一个已经 `confirmed` 的轮次会退回 `completed`。后果链:
|
||||
1. `_ensure_writable_round_row` 不再拦截 → `apply_feedback_atomic` 可以继续改写已定稿轮次的候选偏好/`_conversation`;
|
||||
2. `WorkflowCrossReviewRepository._load_source_owner`(`workflow_cross_review_repository.py:1066-1076`)只在 `status == "confirmed"` 时校验 `confirmed_candidate_mismatch`,状态被回退后该校验被跳过 → 用户可以对**与已定稿候选不同的候选**发起跨评审;同理 `_ensure_review_after_confirmation_is_safe`(:1108-1111)在非 confirmed 时直接 return,下游节点已完成的保护也一并失效;
|
||||
3. `record_skip_restoration_handoff_atomic`(:795)要求 `status == 'confirmed'`,回退后跳过流程的 XF 交接会永久失败。
|
||||
节点侧 `selected_image_id` 仍指向旧图,轮次侧却重新变成可写,两边彻底不一致。
|
||||
- **修复建议**:
|
||||
1. 在 `WorkflowRoundRepository` 增加 `update_round_if_status(round_id, expected_statuses, payload)`(仓库里已有同模式的 `update_workflow_if_status` / `update_node_if_status` 可参照),或在 `update_round` 内部对 `status` 赋值做终态白名单校验:`confirmed` / `superseded` / `cancelled` 一律拒绝降级。
|
||||
2. `create_round` 的幂等重放分支加前置判断:
|
||||
```python
|
||||
if existing.status in {"confirmed", "superseded", "cancelled"}:
|
||||
return {**self.get_round(existing.round_id).to_dict(), "created": False, "idempotent_replay": True}
|
||||
```
|
||||
3. `_ensure_round_enqueued` 末尾改为 `"status": "queued" if task_ids else latest.status`,并同样跳过终态轮次。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `reconcile_round` 无条件回写状态与节点指针:迟到的候选回调会把 `superseded` 父轮次"复活"并把节点 `active_round_id` 指回旧轮次
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:806`、`backend/services/workflow_round_service.py:621`
|
||||
- **问题**:
|
||||
`create_next_round` 只要求父轮次里有 1~3 个 **succeeded 的 liked 候选**,并**不要求父轮次已经终态**(`get_consistent_round_snapshot` 没有任何 status 校验)。因此完全可以在父轮次还有候选处于 `queued`/`running` 时创建子轮次,父轮次被打上 `superseded`。当那些残留候选随后完成时,worker 的 `handle_task_terminal → reconcile_round(parent)` 会用聚合状态覆盖 `superseded`,同时把节点 metadata 的 `active_round_id` 重新指向**父轮次**。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_service.py:818-847
|
||||
updated_round = self.round_repository.update_round(
|
||||
round_id,
|
||||
{
|
||||
"status": round_status, # 直接覆盖 superseded / confirmed
|
||||
...
|
||||
},
|
||||
) or round_record
|
||||
if self.generation_service is not None:
|
||||
...
|
||||
if node.status not in {"selected", "discarded"}:
|
||||
update_payload = {
|
||||
"status": node_status,
|
||||
"metadata": {
|
||||
**metadata,
|
||||
"active_round_id": round_id, # 指回被 reconcile 的那个轮次
|
||||
"last_round_status": round_status,
|
||||
...
|
||||
```
|
||||
```python
|
||||
# workflow_round_service.py:621-633 —— 父轮次被标 superseded,但没有任何后续保护
|
||||
superseded_parent = self.round_repository.update_round(
|
||||
parent_round_id,
|
||||
{"status": "superseded", "metadata": {..., "superseded_by_round_id": created.get("round_id"), ...}},
|
||||
)
|
||||
```
|
||||
且 `_ensure_writable_round_row`(`workflow_round_repository.py:1355-1375`)的不可写列表里**没有** `superseded`:
|
||||
```python
|
||||
if status in {"cancelled", "all_failed"}:
|
||||
raise WorkflowRoundWriteError("round_not_writable", ...)
|
||||
```
|
||||
- **影响**:
|
||||
1. 父轮次状态从 `superseded` 变回 `completed`/`partial_success`,UI 上同一节点出现两个"可确认"的轮次,用户可能在旧轮次上定稿,绕过刚创建的优化子轮次;
|
||||
2. 节点 `metadata.active_round_id` 被改回父轮次,前端 `App.vue:2336` 的 `selectedWorkflowActiveRoundId` 直接采信该值(不做"是否在已加载轮次列表中"的校验,和 `App.vue:7048` 的加载逻辑不一致),面板会跳回旧轮次;
|
||||
3. 节点 `status` 由父轮次聚合结果决定,子轮次还在跑时节点就被标 `completed`;
|
||||
4. `superseded` 轮次仍可写反馈 → 用户能对已被取代的轮次继续 like/reject,且可以再次 `create_next_round` 生成第二个子轮次(主轮次侧缺少交叉评审那样的 `next_review_round_id` 唯一性守卫,见下一条)。
|
||||
- **修复建议**:
|
||||
1. `_reconcile_round_locked` 读取 `round_record.status`,若已是 `confirmed` / `superseded` / `cancelled`,只更新 `metadata.execution_summary`,**不写 `status`**,也不改节点的 `active_round_id`;
|
||||
2. 更新节点前先确认 `round_id == node.metadata.get("active_round_id")` 或该轮次仍是该节点最新的非终态轮次,避免旧轮次抢占节点指针;
|
||||
3. 把 `superseded` 加入 `_ensure_writable_round_row` 的不可写状态集合。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `create_next_round` 缺少"一个父轮次只能有一个子轮次"的守卫,可分叉出多条优化链
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:465`(`create_next_round` 全流程)
|
||||
- **问题**:交叉评审侧有明确守卫:
|
||||
```python
|
||||
# workflow_cross_review_repository.py:171-182
|
||||
existing_child = _optional_text(parent_metadata.get("next_review_round_id"))
|
||||
if existing_child:
|
||||
raise WorkflowRoundWriteError(
|
||||
"cross_review_followup_exists",
|
||||
"this review round already has a follow-up",
|
||||
{..., "required_action": "open_latest_cross_review"},
|
||||
)
|
||||
```
|
||||
而主轮次的 `create_next_round` 只写 `superseded_by_round_id`,**创建前不检查它是否已存在**:
|
||||
```python
|
||||
# workflow_round_service.py:620-633
|
||||
created = self.create_round(parent.node_id, next_payload, ctx)
|
||||
superseded_parent = self.round_repository.update_round(
|
||||
parent_round_id,
|
||||
{"status": "superseded",
|
||||
"metadata": {**parent.metadata, "superseded_by_round_id": created.get("round_id"), ...}},
|
||||
)
|
||||
```
|
||||
唯一的并发保护是 `parent_feedback_revision` 乐观校验(`workflow_round_repository.py:162-174`),但它只在**父轮次 feedback 发生变化**时才拒绝;两次内容相同的 `create_next_round` 请求(不带 idempotency_key,或带不同 key)revision 一致,两次都会成功。
|
||||
- **影响**:同一父轮次产生两个平级子轮次,`superseded_by_round_id` 被后者覆盖,前者成为无人引用的孤儿优化链;节点的 `active_round_id` 在两条链之间来回跳;`_feedback_summary` / `feedback_context.parent_round_id` 追溯信息失真。
|
||||
- **修复建议**:把 `superseded_by_round_id` 的存在性检查移进 `create_round_with_candidates` 的同一事务(该事务已经对 parent 行加了 `FOR UPDATE` / `BEGIN IMMEDIATE`),存在即抛 `next_round_exists`;或在 `workflow_generation_rounds(parent_round_id, round_kind)` 上加部分唯一索引。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] LLM 返回扁平结构时,候选偏好被静默丢弃(不报错、不回退到确定性解析)
|
||||
|
||||
- **位置**:`backend/services/workflow_round_feedback_service.py:166`(`_normalize_model_payload`)
|
||||
- **问题**:`_model_request` 下发的 `response_schema` 把 liked/rejected/... 嵌在 `feedback` 下,`_normalize_model_payload` 也**只**从 `parsed["feedback"]` 取这些键;模型若按常见习惯返回扁平结构(顶层直接给 `liked`),`feedback` 为空 dict,候选偏好全部丢失,但 `positive_patch` 因为单独从顶层取而被保留,于是校验通过、`source="llm_validated"`、`fallback_used=False`——**没有任何错误、也不会回退到确定性解析器**。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_feedback_service.py:178-189
|
||||
feedback = parsed.get("feedback")
|
||||
feedback = dict(feedback) if isinstance(feedback, Mapping) else {}
|
||||
merged = {
|
||||
**feedback, # 顶层的 liked/rejected/final 在这里被丢掉
|
||||
"positive_patch": parsed.get("positive_patch", feedback.get("positive_patch", parsed.get("next_round_prompt_patch"))),
|
||||
"negative_patch": parsed.get("negative_patch", feedback.get("negative_patch")),
|
||||
"material_intent": parsed.get("material_intent", feedback.get("material_intent")),
|
||||
}
|
||||
return merged
|
||||
```
|
||||
实测(本机执行):
|
||||
```
|
||||
flat payload {'liked': ['TX-01-02'], 'positive_patch': 'more light'}
|
||||
-> source=llm_validated liked=[] patch='more light' fallback_used=False
|
||||
nested payload {'feedback': {'liked': ['TX-01-02']}, 'positive_patch': 'more light'}
|
||||
-> source=llm_validated liked=['TX-01-02']
|
||||
```
|
||||
- **影响**:用户说"保留第 2 张并加点光",系统只记下 patch、丢掉"保留第 2 张"。随后 `create_next_round` 因为 `liked` 为空直接 400(`workflow_round_service.py:504-514` "select one to three liked candidates"),用户看不到任何"模型没理解"的提示,只会认为功能坏了;更糟的情况是同一请求里还有 `rejected`,则用户的拒绝意图被无声吞掉。
|
||||
- **修复建议**:`_normalize_model_payload` 对四个动作字段做 `feedback.get(k, parsed.get(k))` 的双层回退;并在 `merged` 中所有动作字段都为空且 `parsed` 顶层存在同名键时,抛 `WorkflowFeedbackInterpretationError("invalid_llm_result", ...)`,让 `interpret()` 的 `except Exception` 走确定性回退,而不是"半成功"。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 确定性反馈解析器把普通数字当候选编号:静默误拒候选 / 合法反馈被 400
|
||||
|
||||
- **位置**:`backend/services/workflow_feedback_interpreter.py:46`(`_DISPLAY_CODE_OR_NUMBER_RE`)、`:172-208`(`interpret` 主循环)
|
||||
- **问题**:候选 token 正则里包含裸 `\d{1,3}`,任何 1~3 位数字都会被当成候选序号;`interpret` 又会把"没有动作词但有数字"的后续片段挂到上一个动作(`active_prefix_action`)。这是**LLM 不可用时的默认路径**(`round_routes.py:143-150`:未配置 `prompt_planning` 路由时 `feedback_callable=None`)。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_feedback_interpreter.py:46-54
|
||||
_DISPLAY_CODE_OR_NUMBER_RE = re.compile(
|
||||
r"(?<![A-Za-z0-9])"
|
||||
r"(?:"
|
||||
r"(?=[A-Za-z0-9-]*\d)[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+"
|
||||
r"|\d{1,3}" # ← 任意 1~3 位数字
|
||||
r")"
|
||||
r"(?![A-Za-z0-9])",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
```
|
||||
实测(白名单 `TX-01-01..TX-01-04`):
|
||||
```
|
||||
"喜欢 TX-01-01,不要 3 个人" -> liked=['TX-01-01'] rejected=['TX-01-03'] # 静默误拒
|
||||
"拒绝 02,分辨率 512" -> WorkflowFeedbackInterpretationError:
|
||||
reason=unknown_candidate_reference, reference='512'
|
||||
```
|
||||
- **影响**:
|
||||
- 误拒路径:`update_feedback` 会把 TX-01-03 写成 `rejected` 并落 `pool_state='rejected'` + history,用户完全不知情,且该候选此后无法 `confirm`(`confirm_candidate_atomic` 拒绝 rejected 候选);
|
||||
- 400 路径:只要用户反馈里出现 3 位以内数字(尺寸、人数、年龄、角度…),整个反馈请求被 `ApiError(VALIDATION_FAILED, "candidate reference '512' is not in the current whitelist")` 拒绝,错误信息对用户毫无意义。
|
||||
- **修复建议**:
|
||||
1. 裸数字只在**紧邻候选语境**时才视为候选引用——要求前置量词/标记(`候选`、`第`、`#`、`No.`、`张`、`号`);把无标记的 `\d{1,3}` 从 `_DISPLAY_CODE_OR_NUMBER_RE` 移除,交给 `_CHINESE_ORDINAL_RE` 这类带标记的规则;
|
||||
2. 解析出的数字若不在白名单的终端序号集合内,应当**忽略**而不是抛 `unknown_candidate_reference`(仅当该 token 带显式候选标记时才报错);
|
||||
3. `active_prefix_action` 跨片段续接时同样只接受带标记的 token。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `list_node_rounds` 的 N+1,且每次仓储调用都新建一条 SQLite 连接
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:982`(`_persisted_detail`)、`backend/services/workflow_round_service.py:942`(`list_node_rounds`)、`database/db_helper.py:159`(`connect`)
|
||||
- **问题**:`list_node_rounds` 对该节点的**每一个轮次**调用 `_persisted_detail`,后者对**每一个候选**再各查一次 image 和 task;而所有仓储方法都是 `conn = self.database.connect() … conn.close()`,即每次查询都新建一条 `sqlite3.connect()`(还要跑两条 PRAGMA)。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_service.py:982-998
|
||||
def _persisted_detail(self, round_record: WorkflowGenerationRound) -> WorkflowGenerationRoundDetail:
|
||||
candidates = {item.candidate_id: item for item in self.round_repository.list_candidates(round_record.round_id)}
|
||||
views: list[WorkflowRoundCandidateView] = []
|
||||
for pool in self.round_repository.list_pool(round_record.round_id):
|
||||
candidate = candidates.get(pool.candidate_id) or self.round_repository.get_candidate(pool.candidate_id)
|
||||
if candidate is None:
|
||||
continue
|
||||
image = self.image_repository.get(candidate.image_id) if candidate.image_id else None
|
||||
task = self.job_repository.get(candidate.current_task_id) if candidate.current_task_id else None
|
||||
```
|
||||
```python
|
||||
# db_helper.py:159-170
|
||||
def connect(self):
|
||||
if self.backend == "sqlite":
|
||||
...
|
||||
conn = sqlite3.connect(db_path, timeout=30.0)
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.execute("PRAGMA foreign_keys = ON")
|
||||
conn.execute("PRAGMA busy_timeout = 30000")
|
||||
return conn
|
||||
```
|
||||
- **影响**:一个有 6 轮 × 4 候选的节点,单次 `GET nodes/{id}/rounds` 约产生 `3 + 6×(2 + 4×2) ≈ 63` 条独立连接/查询;而前端 `App.vue` 的 `scheduleWorkflowRoundPolling` 在轮次运行期间会周期性重拉该接口。SQLite 单写锁下,这会与 worker 的候选写入争抢 `busy_timeout`,放大 `database is locked` 风险。
|
||||
- **修复建议**:
|
||||
1. 给 `WorkflowRoundRepository` 增加批量方法 `list_candidates_for_rounds(round_ids)` / `list_pool_for_rounds(round_ids)`(`WHERE origin_round_id IN (...)`),一次取回全部轮次的候选与池;
|
||||
2. `ImageRepository` / `JobRepository` 增加 `get_many(ids)`;`_persisted_detail` 改为接收预取好的字典;
|
||||
3. 中期考虑给 `Database` 加连接复用(线程本地连接或连接池),当前"每查询一连接"在轮询场景下代价过高。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 交叉评审的幂等重放只按 `idempotency_key` 全表匹配,可命中另一个节点/另一种轮次并对其改状态
|
||||
|
||||
- **位置**:`database/repositories/workflow_cross_review_repository.py:969`(`_round_replay`)、被 `:57` 与 `:166` 调用
|
||||
- **问题**:`idempotency_key` 在 `workflow_generation_rounds` 上是**全表唯一**(`0014_workflow_generation_rounds.sql`: `idx_workflow_rounds_idempotency`),主轮次、交叉评审轮次、XF 交接轮次共用同一个键空间。但 `_round_replay` 只按 key 查,**不校验命中的轮次是否属于本次请求的 source round / node / round_kind**:
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_cross_review_repository.py:969-978
|
||||
def _round_replay(self, conn: Any, idempotency_key: str | None) -> dict[str, Any] | None:
|
||||
if not idempotency_key:
|
||||
return None
|
||||
row = conn.execute(
|
||||
f"SELECT round_id, display_code FROM workflow_generation_rounds WHERE idempotency_key = {self.placeholder}",
|
||||
(idempotency_key,),
|
||||
).fetchone()
|
||||
if row is None:
|
||||
return None
|
||||
return {"round_id": row["round_id"], "display_code": row["display_code"]}
|
||||
```
|
||||
对照主轮次侧**有**这层校验(`workflow_round_service.py:94-114`:`existing.node_id != node.node_id` / `existing.parent_round_id` 均会报错)。
|
||||
且返回后调用方立刻对这个"重放命中"的轮次做写操作:
|
||||
```python
|
||||
# workflow_generation_cross_review_service.py:389-391
|
||||
self._ensure_enqueued(str(created["round_id"]), ctx)
|
||||
result = {**self.round_service.get_round(str(created["round_id"]), ctx).to_dict(), "review_operation": created}
|
||||
```
|
||||
而 `_ensure_enqueued`(`:668-676`)末尾会 `update_round(status=..., metadata={... "task_ids": ..., "planned_only": False})` 并 `reconcile_round`。
|
||||
- **影响**:客户端在不同操作上复用同一个 `idempotency_key`(UI 用同一个"操作 id"、或聊天侧用消息 id 做 key 都会踩到),交叉评审请求会"成功"返回一个**完全无关的轮次**,并把它的 `status`/`metadata.task_ids` 覆盖掉、触发一次针对该轮次的 reconcile(进而改写其节点的 `active_round_id`)。跨用户场景下 `round_service.get_round(..., ctx)` 的 `require_node` 会在最后一步拦住读取,但**写入已经发生**。
|
||||
- **修复建议**:`_round_replay` 增加参数并校验:命中行的 `round_kind` 必须匹配、`node_id`/`workflow_id` 必须等于 `round_payload` 中的值、`parent_round_id` 必须等于本次的 source/parent;不匹配时抛 `WorkflowRoundWriteError("idempotency_key_conflict", ...)` 而不是当作重放。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 跨评审 `skip` 由三段独立事务组成,中途失败会留下"已跳过但未定稿"的不一致状态
|
||||
|
||||
- **位置**:`backend/services/workflow_generation_cross_review_service.py:407`(`_skip`)
|
||||
- **问题**:跳过流程依次执行三个**各自独立提交**的事务:① `record_skip_atomic`(写 `generation_cross_review.decision='skip'` + history)→ ② `round_service.confirm_candidate`(另一个连接里的 `confirm_candidate_atomic`)→ ③ `record_skip_restoration_handoff_atomic`(要求 `status == 'confirmed'`)。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_generation_cross_review_service.py:416-445
|
||||
try:
|
||||
decision = self.cross_review_repository.record_skip_atomic(...) # ① 已提交
|
||||
except WorkflowRoundWriteError as exc:
|
||||
raise _write_error(exc) from exc
|
||||
if decision.get("already_confirmed"):
|
||||
result = self.round_service.get_round(source_round_id, ctx).to_dict()
|
||||
else:
|
||||
result = self.round_service.confirm_candidate( # ② 可能抛错
|
||||
source_round_id,
|
||||
{"candidate_id": candidate_id, "idempotency_key": f"{idempotency_key}:confirm" if idempotency_key else None},
|
||||
ctx,
|
||||
)
|
||||
try:
|
||||
restoration_handoff = (
|
||||
self.cross_review_repository.record_skip_restoration_handoff_atomic(...) # ③ 要求 confirmed
|
||||
)
|
||||
```
|
||||
② 的失败原因很现实:`confirm_candidate_atomic` 会因 `round_branch_not_active`(另一个标签页切了分支)、`node_already_completed`、`candidate_image_restricted` 而抛错。
|
||||
- **影响**:轮次 metadata 里已经写死 `decision='skip'`,但轮次并未 confirmed、XF 输入库也没有条目。此时用户如果改主意想走 `review`,会被 `record_skip_atomic` 的分支挡住吗?——不会,`existing.get("decision") == "skip"` 分支会当成幂等重放返回 `already_confirmed=False`,然后又去 `confirm_candidate`,**永远卡在同一个失败点**;而走 `review` 分支的 `create_review_round_atomic` 不检查 `decision=='skip'`,会在一个已标记跳过的轮次上再建评审轮次,两个状态并存。
|
||||
- **修复建议**:
|
||||
1. 把"记录 skip + 确认候选"合并为一个事务(`record_skip_atomic` 内部直接完成 confirm 所需的全部写入,或让 `confirm_candidate_atomic` 接受一个 `review_decision` 参数在同一 conn 内落库);
|
||||
2. 若暂时无法合并,则在 `record_skip_atomic` 里区分"已记录但未确认"的中间态(如 `decision_state='pending_confirm'`),并允许用户显式撤销该跳过决定;
|
||||
3. `create_review_round_atomic` 增加 `decision == 'skip'` 的互斥校验。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `apply_feedback_atomic` 会把旧的 `_conversation` 无条件带到新快照,导致 `create_next_round` 复用过期的 prompt patch
|
||||
|
||||
- **位置**:`database/repositories/workflow_round_repository.py:703`、`backend/services/workflow_round_service.py:534`
|
||||
- **问题**:每次反馈写入都会用池里的最新偏好重建 `feedback_snapshot`,然后把上一版快照里所有 `_` 前缀的键**原样复制回来**。当用户第一次用自然语言反馈(写入 `_conversation`),第二次改用结构化 `updates`(此时 `conversation is None`,不覆盖),旧的 `_conversation` 会被保留。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_repository.py:703-716
|
||||
feedback_snapshot = {
|
||||
str(row["candidate_id"]): {...}
|
||||
for row in pool_rows
|
||||
}
|
||||
for key, value in previous_snapshot.items():
|
||||
if str(key).startswith("_"):
|
||||
feedback_snapshot[str(key)] = value # ← 旧 _conversation 原样带过来
|
||||
...
|
||||
if conversation is not None:
|
||||
feedback_snapshot["_conversation"] = conversation
|
||||
```
|
||||
```python
|
||||
# workflow_round_service.py:534-559 —— create_next_round 直接吃这个残留值
|
||||
conversation = parent.feedback_snapshot.get("_conversation")
|
||||
conversation = dict(conversation) if isinstance(conversation, dict) else {}
|
||||
...
|
||||
positive_patch = _bounded_optional_text(conversation.get("positive_patch"), field="positive_patch", maximum=4_000)
|
||||
material_intent = _bounded_optional_text(conversation.get("material_intent"), ...)
|
||||
```
|
||||
- **影响**:用户第一轮说"下一轮加暖光",之后改口用界面按钮重新勾选偏好(不再提暖光),生成的子轮次仍会带上"加暖光"的 `prompt_patch` 与 `material_intent`,且 `feedback_context.source_text` 显示的是那句早已作废的原话。用户无法通过 UI 清除该 patch。
|
||||
- **修复建议**:在 `_conversation` 里记录写入序号/时间戳与其所依据的 `pool_revision`;`create_next_round` 只在 `_conversation` 对应的是**最近一次**反馈写入时才采用其 patch,否则只使用池偏好 + `_strict_rejection_patch`。或者更简单:结构化 `updates` 写入时显式 `feedback_snapshot.pop("_conversation", None)`,并在 API 上暴露"清除对话补丁"的能力。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 反馈幂等日志按字典序而非时间序裁剪,会淘汰掉较新的 key
|
||||
|
||||
- **位置**:`database/repositories/workflow_round_repository.py:719`
|
||||
- **问题**:`request_log` 是从 `metadata_json` 反序列化出来的 dict,而写库时用的是 `json.dumps(..., sort_keys=True)`(`workflow_round_repository.py:1318-1321`),所以**重新读出来的插入顺序是字典序**,不是写入时间顺序。`[-20:]` 因此保留的是"字典序最大的 20 个 key"。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_round_repository.py:719-726
|
||||
if idempotency_key:
|
||||
request_log[idempotency_key] = {...}
|
||||
request_log = dict(list(request_log.items())[-20:])
|
||||
```
|
||||
```python
|
||||
# workflow_round_repository.py:1318-1321
|
||||
def _json_or_none(value: Any | None) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
return json.dumps(value, ensure_ascii=False, sort_keys=True)
|
||||
```
|
||||
- **影响**:在同一轮次上做超过 20 次带 key 的反馈写入后,被淘汰的是字典序小的 key(例如以 `a` 开头的 UUID),而非最旧的。用户对一个刚提交过的请求做重试时,幂等记录可能已被淘汰 → 重复写入一条 `round_feedback_updated` history,并重复触发审计事件。
|
||||
- **修复建议**:在每条记录里已有 `updated_at` 字段,裁剪时按它排序:
|
||||
```python
|
||||
request_log = dict(sorted(request_log.items(), key=lambda kv: str(kv[1].get("updated_at") or ""))[-20:])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `approve` 响应里对同一个 `next_node_id` 重复查询节点
|
||||
|
||||
- **位置**:`backend/services/workflow_generation_cross_review_service.py:259`
|
||||
- **问题**:条件表达式里把 `get_node` 调了两次(一次判空、一次取值),既是多余的 DB 往返,也有 TOCTOU(两次之间节点被删则第二次返回 `None`,`.to_dict()` 抛 `AttributeError`)。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_generation_cross_review_service.py:259-267
|
||||
return {
|
||||
**self.round_service.get_round(round_id, ctx).to_dict(),
|
||||
"approval": approval,
|
||||
"next_node": (
|
||||
self.workflow_repository.get_node(str(approval["next_node_id"])).to_dict()
|
||||
if approval.get("next_node_id") and self.workflow_repository.get_node(str(approval["next_node_id"]))
|
||||
else None
|
||||
),
|
||||
}
|
||||
```
|
||||
- **影响**:多一次数据库连接;极端竞态下 500 而非正常响应。
|
||||
- **修复建议**:
|
||||
```python
|
||||
next_node = (
|
||||
self.workflow_repository.get_node(str(approval["next_node_id"]))
|
||||
if approval.get("next_node_id")
|
||||
else None
|
||||
)
|
||||
...
|
||||
"next_node": next_node.to_dict() if next_node else None,
|
||||
```
|
||||
444
审计/findings/A3-素材与风格集.md
普通文件
444
审计/findings/A3-素材与风格集.md
普通文件
|
|
@ -0,0 +1,444 @@
|
|||
# A3 — 素材库 / 高级风格集 / 衣柜 / 素材绑定
|
||||
|
||||
> 审计范围(实际逐行读过的文件):
|
||||
> - `backend/services/advanced_style_set_service.py`(4491 行,全量结构 + 重点方法)
|
||||
> - `backend/services/advanced_material_service.py`(1856 行)
|
||||
> - `backend/services/material_service.py`(1087 行)
|
||||
> - `backend/services/material_normalization_service.py`(411 行,全文)
|
||||
> - `backend/services/material_binding_schema_service.py`(408 行,全文)
|
||||
> - `backend/services/material_catalog_resolver.py`(210 行,全文)
|
||||
> - `backend/services/material_analytics_service.py`(173 行,全文)
|
||||
> - `backend/services/wardrobe_service.py`(511 行,全文)
|
||||
> - `backend/services/workflow_node_material_service.py`(503 行,全文)
|
||||
> - `backend/services/asset_import_service.py`(406 行,全文)
|
||||
> - `database/repositories/advanced_material_repository.py`(2123 行,结构 + 关键事务/CRUD)
|
||||
> - 关联交叉验证:`backend/services/workflow_service.py`(`_normalized_metadata` / `_sync_material_bindings_from_node`)、`backend/services/generation_reference_service.py`、`backend/routes/asset_routes.py`、`core/storage.py`、`database/db_helper.py`、`database/migrations/0009|0016|0018*.sql`
|
||||
|
||||
## 摘要
|
||||
|
||||
这一块的**安全底线基本守住了**:存储 URI 有 `split_uri` + `resolve_uri` 双重防越权,上传走魔数嗅探(`detect_image_format`)而不是信任 `content_type`,生成时解析素材引用会二次校验 `recognition_status == "confirmed"`,`MaterialCatalogResolver` 用不可序列化的属性标记做信任边界,SQLite 已开 `PRAGMA foreign_keys = ON`(级联删除真的生效)。这块代码不是"随手写"的。
|
||||
|
||||
但存在**三处真实可触发的缺陷**:(1) `normalize_material_bindings` 对携带正确 `schema_version` 的载荷完全跳过归一化,后续索引函数直接 `rule["target_node_keys"]` 取键,构造一条空规则即可让 `material_bind` 节点被永久毒化(每次更新必 500,且节点元数据已先落库);(2) 资产包导入把清单里的 `material_id` / `recognition_status` 当作可信输入,能静默覆盖已有素材并把未经识别的素材直接写成 `confirmed`;(3) `normalize_category` 用 `alias in text` 子串匹配做分类推断,"landscape" 会被判成 headwear、"rooftop" 会被判成 top。另有一处统计口径完全失效(`workflow_kind` 常量对不上,风格集导入数恒为 0)。
|
||||
|
||||
**性能/内存**方面有两处全表加载:`AdvancedMaterialService.list_catalog` 每次分页请求都把两个素材表整表读入内存再切片;`MaterialService.list_materials` 一旦带高级筛选也整表加载。`_reconcile_import_task` 在列表接口里对每个 import 的每个 source/case 单独查队列,是典型 N+1,且 `get_import` 会重复对账两次。
|
||||
|
||||
**精简空间很大**:`advanced_style_set_service.py` 4491 行里,类体 2091 行(32 个方法,其中 `_execute_consensus` 单个方法 467 行)、模块级函数 2092 行(81 个纯函数)。这 81 个函数按职责天然分成"提示词编译""风格评审打分""文本安全清洗""证据校验"四组,可无风险拆成 4 个模块;仓库层 12 组实体的 `create/get/list/update/update_if_status` 是几乎逐字复制的连接-提交-回滚模板;`_optional_text` 在 backend/database 下被重复定义 **28 次**,`_string_list` 17 次,`_json_or_none` 13 次。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] 素材绑定 schema 校验可被 `schema_version` 直接绕过,并导致 `material_bind` 节点被永久毒化
|
||||
|
||||
- **位置**:`backend/services/material_binding_schema_service.py:47`(绕过)、`:326`(KeyError)、`backend/services/workflow_service.py:729`(先落库后同步)
|
||||
- **问题**:`normalize_material_bindings` 的第一分支只要客户端载荷里 `schema_version` 等于常量值,就 `deepcopy` 原样返回,**完全跳过 `_normalize_rule` 归一化**;随后仅重建 `by_node_id`,而重建路径 `_index_by_node_id` → `_index_by_node_key` 直接对未归一化的 rule 做 `rule["target_node_keys"]` 下标取键。客户端提交 `{"schema_version": "2026-07-09.material-binding-schema.v1", "active_rules": [{}]}` 即触发 `KeyError`。更严重的是 `WorkflowService.update_node` 在 **第 729 行已经把节点元数据写库成功**,第 732 行才调用 `_sync_material_bindings_from_node`,异常发生时脏数据已持久化,此后对该 `material_bind` 节点的每一次更新都会重复走同一路径而 500。
|
||||
- **代码**:
|
||||
```python
|
||||
# material_binding_schema_service.py:47-58
|
||||
if isinstance(payload, dict) and payload.get("schema_version") == MATERIAL_BINDING_SCHEMA_VERSION:
|
||||
normalized = deepcopy(payload)
|
||||
if workflow_nodes:
|
||||
rules = normalized.get("active_rules")
|
||||
if not isinstance(rules, list):
|
||||
rules = [rule for rule in normalized.get("rules", []) if isinstance(rule, dict) and rule.get("use_reference")]
|
||||
normalized["by_node_id"] = _index_by_node_id(rules, workflow_nodes)
|
||||
return normalized # <- rules 从未被 _normalize_rule 处理
|
||||
|
||||
# material_binding_schema_service.py:326-331
|
||||
def _index_by_node_key(rules: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
|
||||
result: dict[str, list[dict[str, Any]]] = {}
|
||||
for rule in rules:
|
||||
for node_key in rule["target_node_keys"]: # <- KeyError,非 .get()
|
||||
result.setdefault(canonical_gradual_node_key(node_key), []).append(rule)
|
||||
```
|
||||
```python
|
||||
# workflow_service.py:729-733
|
||||
after = self.workflow_repository.update_node(node_id, update_payload) # 已提交
|
||||
if after is None:
|
||||
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": node_id})
|
||||
self._sync_material_bindings_from_node(after) # 才在这里炸
|
||||
```
|
||||
- **影响**:任意登录用户可用一次 PUT 让某个 `material_bind` 节点变成"只能读、不能改"的死节点(每次 `update_node` 都 500)。同时该分支意味着绑定规则里的 `material_id` / `prompt` / `reference_strength` 都是未经校验的原样存储——虽然 `GenerationReferenceService._resolve_material_references`(`generation_reference_service.py:88-104`)在生成时补校验了素材存在性与 `confirmed`,堵住了引用图泄露,但 `prompt` 字段仍会经 `prompt_expansion_service._material_prompt_parts` 被拼进最终提示词,等于一条未经素材库校验的任意文本注入通道。
|
||||
- **修复建议**:
|
||||
1. 删掉整个 fast-path,或至少把它降级为"仍然逐条 `_normalize_rule`,只跳过 `by_stage/by_node_key` 的重复计算";
|
||||
2. `_index_by_node_key` / `_node_view` 改用 `rule.get("target_node_keys") or []`、`(rule.get("material") or {}).get("prompt")`;
|
||||
3. 把 `_sync_material_bindings_from_node` 的归一化提到 `update_node` 写库**之前**(先 `normalize_material_bindings(payload["metadata"]["material_bindings"], nodes)`,校验通过再写节点),归一化失败抛 `ApiError(VALIDATION_FAILED)` 而不是让 `KeyError` 逃逸成 500。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 资产包清单可静默覆盖已有素材,并把未识别素材直接写成 `confirmed`
|
||||
|
||||
- **位置**:`backend/services/asset_import_service.py:141`、`:340`、`:361`
|
||||
- **问题**:`_apply_manifest` 用清单里显式给出的 `material_id`(`_material_id` 优先取 `item["material_id"] or item["id"]`)去查库,命中已存在的素材就走 `update_material` **整体覆盖**(`display_name`/`image_uri`/`prompt`/`tags`/`metadata`/`recognition_status` 全被替换)。同时 `recognition_status` 直接取自清单,`MaterialService._validate_status` 只检查它属于 `MATERIAL_STATUSES` 集合,因此清单写 `"recognition_status": "confirmed"` 就能造出一条**从未经过任何 VLM 识别、prompt 完全由清单作者指定**的"已确认"素材。
|
||||
- **代码**:
|
||||
```python
|
||||
# asset_import_service.py:141-153
|
||||
existing = self.material_service.repository.get_material(material_payload["material_id"])
|
||||
if existing is not None:
|
||||
self.material_service.get_material(material_payload["material_id"])
|
||||
self.material_service.validate_material_payload(material_payload, creating=existing is None)
|
||||
planned_materials.append((material_payload, existing is None))
|
||||
...
|
||||
else:
|
||||
material = self.material_service.update_material(material_payload["material_id"], material_payload, ctx)
|
||||
|
||||
# asset_import_service.py:340
|
||||
"recognition_status": _optional_text(item.get("recognition_status")) or "pending_recognition",
|
||||
|
||||
# asset_import_service.py:361-366
|
||||
def _material_id(item, package_uri, manifest_uri, index, image_uri) -> str:
|
||||
explicit = _optional_text(item.get("material_id") or item.get("id"))
|
||||
if explicit:
|
||||
return explicit # <- 清单完全掌控目标 ID
|
||||
```
|
||||
- **影响**:`confirmed` 是整条生成链路的信任标记——`generation_reference_service.py:95` 和 `workflow_node_material_service.py:293` 都只认这一个状态。一个从外部下载的资产包(清单内容对操作者不透明)导入后,既能悄悄改写用户手工确认过的素材(连 `normalized_asset_profile` 一起被清掉),又能把任意 prompt 文本 + 任意存储根下的图片直接注入受信任素材目录。`_asset_uri`(`:352-358`)还允许清单写 `storage://<任意根>/...` 绕过包目录范围。
|
||||
- **修复建议**:
|
||||
- 导入产生的素材 ID 一律服务端生成(走 `_material_id` 的 sha1 分支),清单里的 `material_id` 只用作包内去重键,不用作库内主键;
|
||||
- 覆盖已有素材必须显式确认(`payload["allow_overwrite"]` + 只允许覆盖同一 `metadata.asset_pack.package_uri` 来源的素材);
|
||||
- `recognition_status` 从清单里**移除**,导入一律落 `pending_recognition`;
|
||||
- `_asset_uri` 对 `storage://` 前缀的值校验其 root 必须等于包所在 root,且 relative 必须在 `base_relative` 之下。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `normalize_category` 用子串匹配推断类别:"landscape" → headwear,"rooftop" → top
|
||||
|
||||
- **位置**:`backend/services/material_normalization_service.py:314`(配合 `:190`、`:342`)
|
||||
- **问题**:`normalize_category` 遍历 `CATEGORY_ALIASES` 做 `if alias in text` 的**裸子串包含**判断,而 `_build_profile` 在既无 `value["category"]` 又无 `category_hint` 时会把 `tags + prompt` 拼成一整段自由文本喂进来(`_category_from_text` 就是 `" ".join(...)`)。别名表里有 `"top"`、`"cap"`、`"ring"`、`"hat"`、`"boot"` 这类高频子串。
|
||||
- **代码**:
|
||||
```python
|
||||
# material_normalization_service.py:190
|
||||
category = normalize_category(value.get("category") or category_hint or _category_from_text([*tags, prompt]))
|
||||
|
||||
# material_normalization_service.py:314-321
|
||||
def normalize_category(value: Any) -> str:
|
||||
text = _text(value).lower().replace("_", " ").strip()
|
||||
if text in ASSET_CATEGORIES:
|
||||
return text
|
||||
for alias, category in CATEGORY_ALIASES.items():
|
||||
if alias in text: # <- 子串包含,无词边界
|
||||
return category
|
||||
return "other"
|
||||
|
||||
# material_normalization_service.py:342
|
||||
def _category_from_text(values: list[str]) -> str:
|
||||
return " ".join(_text(item) for item in values)
|
||||
```
|
||||
实测(按 dict 声明顺序):`"wide landscape background"` → 先不命中 `top`/`ring`/`hat`,命中 `"cap"`(在 `landscape` 中)→ **headwear**;`"a girl standing on a rooftop"` → 命中 `"top"` → **top**;`"spring flowers"` → 命中 `"ring"` → **jewelry**。
|
||||
- **影响**:`CATEGORY_SEMANTICS[category]` 直接决定 `role` / `body_slots` / `wear_layer`(`:191`),一个背景素材会被打成"头部配饰、accessory 层",进而污染 `_matches_material_filters` 的 `body_slot`/`wear_layer` 筛选(`material_service.py:1070-1072`)和 `CompositionBuilder` 的槽位冲突判定。用户在"衣柜/素材库"里按部位筛选会查不到自己的素材,且看不出原因。
|
||||
- **修复建议**:把别名匹配改成词边界匹配,并按别名长度降序尝试:
|
||||
```python
|
||||
_ALIAS_PATTERNS = sorted(CATEGORY_ALIASES.items(), key=lambda kv: -len(kv[0]))
|
||||
def normalize_category(value):
|
||||
text = _text(value).lower().replace("_", " ").strip()
|
||||
if text in ASSET_CATEGORIES:
|
||||
return text
|
||||
for alias, category in _ALIAS_PATTERNS:
|
||||
if re.search(rf"(?<![A-Za-z0-9]){re.escape(alias)}(?![A-Za-z0-9])", text):
|
||||
return category
|
||||
return "other"
|
||||
```
|
||||
(CJK 别名无需词边界,可按 `alias.isascii()` 分两路。)另外建议 `_build_profile` 不再拿整段 prompt 去猜类别,只在 tags 上猜。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `list_catalog` 每次分页请求都把两张素材表整表读入内存
|
||||
|
||||
- **位置**:`backend/services/advanced_material_service.py:605`、`:636`、`:646`
|
||||
- **问题**:接口签名带 `page/page_size` 且上限 200,看上去是分页的;实现却先 `_all_advanced_materials()` + `_all_standard_materials()` 把两个表**全部**行取出、全部 `to_dict()`(含 `metadata_json`/`capsule_json` 反序列化),拼成 `merged` 后再内存切片。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_material_service.py:608-628
|
||||
advanced = self._all_advanced_materials()
|
||||
standard = self._all_standard_materials()
|
||||
advanced_items = [{**item.to_dict(), "library_kind": "advanced", ...} for item in advanced if item.status == "active"]
|
||||
standard_items = [{**item.to_dict(), "library_kind": "standard", ...} for item in standard if item.recognition_status == "confirmed"]
|
||||
merged = [*advanced_items, *standard_items]
|
||||
offset = (normalized_page - 1) * normalized_size
|
||||
return {"items": merged[offset : offset + normalized_size], ...}
|
||||
|
||||
# advanced_material_service.py:646-654
|
||||
def _all_standard_materials(self) -> list[Material]:
|
||||
result: list[Material] = []
|
||||
page = 1
|
||||
while True:
|
||||
items, total = self.material_repository.list_materials(page=page, page_size=100)
|
||||
result.extend(items)
|
||||
if len(result) >= total or not items:
|
||||
return result
|
||||
page += 1
|
||||
```
|
||||
- **影响**:素材库到几千条时,每次翻页都是 N/100 次 SQL + N 次 JSON 反序列化 + 全量 dict 构造。进阶素材的 `metadata` 里还嵌着 `style_set.validation_cases`(三条完整 case 的 `to_dict()`,见 `advanced_style_set_service.py:1160`),单条就是几十 KB。前端每翻一页就重跑一次,很容易把插件进程的内存和 SQLite 打满。同样的模式也出现在 `material_service.py:188-216`(一旦带 `color/body_slot/wear_layer/min_confidence` 等高级筛选就整表加载再过滤)和 `material_service.py:423-434`(`renormalize_batch` 无参时整表加载)。
|
||||
- **修复建议**:把过滤和排序下推到 SQL。两库合并可以用 `UNION ALL` + 统一 `(priority DESC, accepted_at DESC)` 排序在数据库层做 `LIMIT/OFFSET`;如果暂时不想动 SQL,至少改成"先各取 `offset+page_size` 条(仓库层已支持 `page_size` 上限 200),再归并取前 `page_size` 条",避免全表物化。`_matches_material_filters` 里的 `body_slot`/`wear_layer`/`confidence` 都存在 `metadata_json` 里,可以用 SQLite 的 `json_extract` 建生成列 + 索引。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 素材统计里的风格集口径完全失效:`workflow_kind` 常量对不上,导入数恒为 0
|
||||
|
||||
- **位置**:`backend/services/material_analytics_service.py:168`,对照 `backend/services/advanced_style_set_service.py:55` 与 `:389`
|
||||
- **问题**:`_is_style_set_metadata` 判断 `workflow_kind == "style_set"`,而实际写入的常量是 `STYLE_SET_KIND = "advanced_style_set"`。它的第二、三个兜底条件(`metadata["style_set"]` 是 dict / 是 True)只有**已封存的进阶素材**满足(`accept()` 在 `advanced_style_set_service.py:1153` 写了 `"style_set": {...}` 字典);`advanced_material_imports` 行的 metadata 只有 `workflow_kind`、`style_source_count`、`generation_model_route`、`governance_context`、`material_tier`、`upload`(见 `:388-395`),**没有任何 `style_set` 键**。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_style_set_service.py:55
|
||||
STYLE_SET_KIND = "advanced_style_set"
|
||||
|
||||
# advanced_style_set_service.py:388-395(导入行 metadata,无 style_set 键)
|
||||
"metadata": {
|
||||
"workflow_kind": STYLE_SET_KIND,
|
||||
"style_source_count": len(persisted),
|
||||
"generation_model_route": generation_route,
|
||||
...
|
||||
},
|
||||
|
||||
# material_analytics_service.py:168-173
|
||||
def _is_style_set_metadata(metadata: dict[str, Any]) -> bool:
|
||||
return (
|
||||
str(metadata.get("workflow_kind") or "").strip().casefold() == "style_set" # 永远 False
|
||||
or isinstance(metadata.get("style_set"), dict)
|
||||
or metadata.get("style_set") is True
|
||||
)
|
||||
```
|
||||
- **影响**:`summarize()` 返回的 `advanced_style_sets.imports` 和 `advanced_style_sets.accepted_imports` **恒为 0**(`style_set_import_rows` 永远是空列表,见 `:95-97`、`:127-128`),而同一份响应里 `sources` / `consensus_runs` / `validation_cases` 却是真实数量。看板上会出现"0 个风格集导入,却有 24 个源图识别"的自相矛盾数据,且没有任何报错提示。
|
||||
- **修复建议**:`material_analytics_service.py` 直接从 `advanced_style_set_service` 导入 `STYLE_SET_KIND`,把第一个条件改成 `== STYLE_SET_KIND.casefold()`(保留旧值 `"style_set"` 作为兼容分支)。更根本的做法是把"是否风格集"下沉成 `advanced_material_imports` 的一个真实列(如 `workflow_kind TEXT`),别再用 JSON 里的约定字符串在三个模块间对暗号。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 导入列表接口的队列对账是 N+1,且单条详情会重复对账两次
|
||||
|
||||
- **位置**:`backend/services/advanced_material_service.py:212`、`:220`,`backend/services/advanced_style_set_service.py:456`、`:474`、`:551`
|
||||
- **问题**:`list_imports` 对本页每一条 import 调 `_reconcile_import_task`;风格集分支进入 `reconcile_missing_tasks`,它对**每个 source、每个 consensus run、每个 attempt 下的每个 case** 各调一次 `_task_missing` → `queue_service.get_job(task_id)`(一次独立 SQL + 独立连接)。一个 8 源图的风格集,单条记录就是 1(list sources)+8(get_job)+1+K+1(list attempts)+M×(1+3) 次查询;`page_size` 默认 30、上限 100。此外 `get_import` 在第 221 行已经 `_reconcile_import_task(...)` 对账过一次,第 224 行的 `self.style_sets.detail(record)` 在 `advanced_style_set_service.py:456` 又 `record = self.reconcile_missing_tasks(record)` **完整重跑一遍**。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_material_service.py:212 / 220-224
|
||||
reconciled = [self._reconcile_import_task(item) for item in items]
|
||||
...
|
||||
record = self._reconcile_import_task(self._require_import(import_id)) # 第 1 次
|
||||
attempts = self.repository.list_attempts(import_id)
|
||||
is_style_set = self.style_sets.is_style_set(record)
|
||||
style_detail = self.style_sets.detail(record) if is_style_set else {} # detail() 内部第 2 次
|
||||
|
||||
# advanced_style_set_service.py:551-558
|
||||
def _task_missing(self, task_id: str | None) -> bool:
|
||||
if not str(task_id or "").strip():
|
||||
return True
|
||||
try:
|
||||
self.queue_service.get_job(str(task_id)) # 每个子任务一次独立查询
|
||||
except ApiError:
|
||||
return True
|
||||
return False
|
||||
```
|
||||
另外 `get_import` 第 259-262 行对 `accepted_material_id` 也是查两次(条件里查一次、取值再查一次)。
|
||||
- **影响**:进阶素材工作台的列表页在有几十个风格集时会产生上千次 SQLite 查询;SQLite 在 `busy_timeout=30000` 下与生成 worker 的写事务竞争,很容易表现为"素材页面转圈几秒"。而且这是**读接口带写副作用**(会把 source/case 状态改成 failed 并改 import 状态),并发列表请求之间存在重复写。
|
||||
- **修复建议**:
|
||||
1. `detail()` 增加 `reconcile: bool = True` 参数,`get_import` 传 `False`,消除重复对账;
|
||||
2. `_task_missing` 批量化:给 `QueueService` 加 `get_jobs(task_ids: set[str]) -> dict[str, Job]`,一次 `WHERE task_id IN (...)` 拿全,`reconcile_missing_tasks` 先收集所有 task_id 再一次查;
|
||||
3. 列表接口不做对账,改由后台定时任务或显式的"刷新"动作触发,避免读接口写库。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 衣柜导入把所有 `sqlite3.IntegrityError` 一律当成"重复条目"
|
||||
|
||||
- **位置**:`backend/services/wardrobe_service.py:94`、`:379`
|
||||
- **问题**:`_is_unique_constraint_error` 对 SQLite 分支只判断 `isinstance(exc, sqlite3.IntegrityError)`,而这个异常类型同时覆盖 UNIQUE、FOREIGN KEY、NOT NULL、CHECK 全部约束违规(PG 分支反倒精确匹配了 `23505`)。`wardrobe_items.material_id` 有 `FOREIGN KEY(material_id) REFERENCES materials(material_id)`(`database/migrations/0009_wardrobe_items.sql`),而 `_repository_for_material_id`(`:328-335`)只有在 `advanced_wardrobe_repository` 与 `material_catalog` **都不为 None** 时才把 `advmat_*` 路由到进阶表——否则进阶素材 ID 会被写进标准 `wardrobe_items` 表,必然触发外键违规。
|
||||
- **代码**:
|
||||
```python
|
||||
# wardrobe_service.py:94-97
|
||||
except Exception as exc:
|
||||
if not _is_unique_constraint_error(exc):
|
||||
raise
|
||||
raise _duplicate_wardrobe_item_error(profile_id, material_id, wardrobe_category) from None
|
||||
|
||||
# wardrobe_service.py:379-382
|
||||
def _is_unique_constraint_error(exc: Exception) -> bool:
|
||||
if isinstance(exc, sqlite3.IntegrityError): # UNIQUE / FK / NOT NULL 全中
|
||||
return True
|
||||
return getattr(exc, "sqlstate", None) == "23505" or getattr(exc, "pgcode", None) == "23505"
|
||||
|
||||
# wardrobe_service.py:328-335
|
||||
def _repository_for_material_id(self, material_id: str) -> WardrobeRepository:
|
||||
if (self.advanced_wardrobe_repository is not None
|
||||
and self.material_catalog is not None
|
||||
and str(material_id or "").startswith("advmat_")):
|
||||
return self.advanced_wardrobe_repository
|
||||
return self.wardrobe_repository
|
||||
```
|
||||
- **影响**:外键违规被伪装成 `VALIDATION_FAILED "material already exists in wardrobe category"`。用户看到"素材已在该分类中",去衣柜里找却找不到,反复重试也永远失败,日志里也不留原始异常(`from None`)。以字符串前缀 `advmat_` 决定写哪张表本身也是脆弱耦合。
|
||||
- **修复建议**:`_is_unique_constraint_error` 改为检查 `"UNIQUE constraint failed" in str(exc)`(SQLite)或 `sqlite3.IntegrityError` 且 `getattr(exc, "sqlite_errorcode", None) == sqlite3.SQLITE_CONSTRAINT_UNIQUE`(Py3.11+);非唯一约束一律 `raise`。仓库路由改用 `MaterialCatalogResolver` 返回的 `metadata["library_kind"]`(已由 `material_catalog_resolver.py:113-188` 在服务端赋值,不可被用户元数据伪造)而不是 ID 前缀。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `update_material` 中的结构校验会把 `MaterialNormalizationError` 泄漏成 500
|
||||
|
||||
- **位置**:`backend/services/material_service.py:246`
|
||||
- **问题**:`validate_material_payload`(`:276-280`)已经把 `MaterialNormalizationError` 转成 `ApiError(VALIDATION_FAILED)`,但紧接着 `update_material` 里的第二处 `validate_material_structures(metadata)` **没有** try/except。该分支在 payload 顶层直接带 `raw_analysis` / `normalized_asset_profile` / `generation_capsules` 时触发(不是放在 `metadata` 里)。
|
||||
- **代码**:
|
||||
```python
|
||||
# material_service.py:240-247
|
||||
structured_keys = {"raw_analysis", "normalized_asset_profile", "generation_capsules"}
|
||||
if structured_keys & update_payload.keys():
|
||||
metadata = {**before.metadata}
|
||||
for key in structured_keys:
|
||||
if key in update_payload:
|
||||
metadata[key] = update_payload.pop(key)
|
||||
validate_material_structures(metadata) # <- 抛 MaterialNormalizationError(ValueError),无捕获
|
||||
update_payload["metadata"] = metadata
|
||||
```
|
||||
- **影响**:`PATCH /materials/{id}` 带一个 `{"normalized_asset_profile": {"category": "bogus"}}` 就返回 500 而不是 400,前端拿不到可读的字段级错误,且服务端日志被无意义的堆栈刷屏。同类问题还在仓库层:`advanced_material_repository.py:2078-2089` 的 `_json_object` / `_json_list` 对损坏的 JSON 列直接 `json.loads` 抛 `JSONDecodeError`,一条脏行会让整个列表接口 500。
|
||||
- **修复建议**:把这里也包成
|
||||
```python
|
||||
try:
|
||||
validate_material_structures(metadata)
|
||||
except MaterialNormalizationError as exc:
|
||||
raise ApiError(ErrorCode.VALIDATION_FAILED, str(exc), {"field": "metadata"}) from None
|
||||
```
|
||||
并把这段"提取结构键 → 合并 → 校验"的逻辑与 `validate_material_payload` 合并成一个函数,避免两处各写一遍校验。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] Pillow 缺失时,风格集共识会把多张原图以 base64 全量载入单个请求
|
||||
|
||||
- **位置**:`backend/services/material_service.py:786`(降级分支)、`backend/services/advanced_style_set_service.py:1447`
|
||||
- **问题**:`_optimized_vision_input` 在模块顶部 `except ImportError: Image = None`(`material_service.py:13-16`,注释明说 standalone 用户可能没有 Pillow),此时**原样返回**最多 20 MB 的原始字节,`_storage_image_data_url` 再对其做 base64(约 ×1.34)。`_execute_consensus` 的无对比分支会对**全部 succeeded 源图**逐张调用它并放进 `image_urls` 列表。
|
||||
- **代码**:
|
||||
```python
|
||||
# material_service.py:786-787
|
||||
if Image is None:
|
||||
return content, content_type # 20 MB 原样返回
|
||||
|
||||
# advanced_style_set_service.py:1446-1449
|
||||
else:
|
||||
for source in sources:
|
||||
image_url, _, _ = _storage_image_data_url(source.source_image_uri, {}, self.storage)
|
||||
image_urls.append(image_url)
|
||||
```
|
||||
- **影响**:风格集允许 2–8 张源图(`MIN_STYLE_SOURCES=2 / MAX_STYLE_SOURCES=8`),无 Pillow 时单个 worker 任务峰值常驻 8 × (20 MB 原始 + 27 MB base64) ≈ 375 MB,还要整体 `json.dumps` 进 `VisionRecognitionRequest.prompt`。作为 AstrBot 插件与宿主同进程运行,这足以 OOM 掉整个 bot。
|
||||
- **修复建议**:为"送进模型的图"设一个独立于存储上限的硬上限(例如 `VISION_INPUT_MAX_BYTES = 3 MB`):Pillow 可用时缩放后仍超限则继续降质;Pillow 不可用且原图超限时直接抛 `ApiError(UPLOAD_TOO_LARGE)` 并提示安装 Pillow,而不是静默把巨图塞给 provider。共识阶段还应改成流式逐张编码 / 用完即弃,而不是先把 8 张全部物化成列表。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `advanced_style_set_service.py` 是典型 god object:4491 行 = 2091 行类体 + 2092 行模块函数,可无风险拆成 5 个模块
|
||||
|
||||
- **位置**:`backend/services/advanced_style_set_service.py:306`(类起点)、`:1347`(467 行的单个方法)、`:2399`–`:4491`(81 个模块级函数)
|
||||
- **问题**:实测结构为 32 个方法 / 81 个模块函数;最长方法 `_execute_consensus` 单体 **467 行**,`_execute_validation_case` 220 行,`_queue_validation_batch` 161 行。类通过 `self.owner` 反向持有 `AdvancedMaterialService` 的 8 个协作者(`:309-318`),而 `AdvancedMaterialService.__init__` 又持有 `AdvancedStyleSetService`(`advanced_material_service.py:118`)——**双向循环引用**,两边互相调私有方法(`self.owner._require_import` / `self.owner._govern_validation_prompt` / `self.owner._generation_route`)。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_style_set_service.py:309-318
|
||||
def __init__(self, owner: Any):
|
||||
self.owner = owner # 无类型标注的反向引用
|
||||
self.repository = owner.repository
|
||||
self.material_repository = owner.material_repository
|
||||
self.queue_service = owner.queue_service
|
||||
self.audit_service = owner.audit_service
|
||||
self.storage = owner.storage
|
||||
self.normalization_service = owner.normalization_service
|
||||
self.model_provider_runtime = owner.model_provider_runtime
|
||||
self.single_flow_engine = owner.single_flow_engine
|
||||
|
||||
# advanced_material_service.py:118
|
||||
self.style_sets = AdvancedStyleSetService(self)
|
||||
```
|
||||
- **影响**:`_execute_consensus` 里 text_only / 单次多图 / 分组两阶段三条 provider 调用路径与状态机、错误分类、图片编码、提示词组装全部纠缠在一个函数里,任何一条分支的改动都要重读 467 行;单元测试只能通过完整 mock `owner` 来构造,实际上 `tests/` 里对这段的覆盖只能走端到端。`Any` 类型的 `owner` 让 IDE 与类型检查完全失效。
|
||||
- **修复建议**(按依赖方向拆,都是纯搬运,无行为变更):
|
||||
1. `style_prompt_compiler.py` ← `_detailed_style_prompt` / `_detailed_style_negative_prompt` / `_scale_specific_*` / `_style_kernel_parts` / `_compact_style_prompt_parts` / `_artist_signature_*` / `_join_prompt`(约 600 行,全是纯函数);
|
||||
2. `style_text_sanitizer.py` ← `_sanitize_minor_age_text` / `_strip_mature_body_locks` / `_normalize_style_prompt_conflicts` / `_clean_prompt_text` / `_apply_semantic_risk_rewrites` 及其正则常量(约 400 行);
|
||||
3. `style_review_scoring.py` ← `_normalize_style_dimension_scores` / `_weighted_style_fidelity_score` / `_cap_inconsistent_dimension_scores` / `_aggregate_style_review_feedback` / `STYLE_REVIEW_*` 常量(约 400 行);
|
||||
4. `style_evidence.py` ← `_normalized_feature_evidence` / `_style_trait_is_supported` / `_prompt_traits_overlap` / `_extract_head_ratio_range` 系列(约 300 行);
|
||||
5. 剩余的类拆成 `StyleSourceStage` / `StyleConsensusStage` / `StyleValidationStage` 三个协作者,各自只接收显式依赖(repository、queue、storage、runtime),把 `owner: Any` 换成一个明确的 `StyleSetRuntime` Protocol(只暴露 `require_import` / `generation_route` / `govern_validation_prompt` 等 6 个方法),消除双向引用。
|
||||
`_execute_consensus` 内部按 `text_only` / `single_pass` / `grouped_two_stage` 拆三个私有方法,共用一个 `_persist_consensus_result`。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 仓库层 12 组实体的 CRUD 模板逐字复制,`_optional_text` 在项目里被定义了 28 次
|
||||
|
||||
- **位置**:`database/repositories/advanced_material_repository.py:559`/`:646`/`:698`/`:752`/`:837`/`:1159`(同构 CRUD),`:2092`(第 N 份 `_optional_text`)
|
||||
- **问题**:`create_style_source` / `create_style_consensus_run` / `create_attempt` / `create_material` 是同一段 `conn = self.database.connect(); try: conn.execute(INSERT...); conn.commit(); except: _rollback(conn); raise; finally: conn.close()` 的复制;`update_style_source` / `update_style_consensus_run` / `update_style_validation_case` / `update_attempt` / `update_import` 是同一段 `_update_assignments(...) → 追加 updated_at → 连接执行 → 回读` 的复制;`update_*_if_status` 又是 update 版本加一段 `AND status IN (...)` 与 `rowcount` 判断的复制。全仓 `def _optional_text(` 出现 **28** 次、`def _string_list(` **17** 次、`def _json_or_none(` **13** 次,逻辑完全一致。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_material_repository.py:683-696(update_style_source)
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
conn.execute(f"UPDATE advanced_style_sources SET {', '.join(assignments)} WHERE source_id = {self.placeholder}", tuple(params))
|
||||
conn.commit()
|
||||
except Exception:
|
||||
_rollback(conn)
|
||||
raise
|
||||
finally:
|
||||
conn.close()
|
||||
return self.get_style_source(source_id)
|
||||
# 上面 14 行在本文件里出现 6 次,仅表名/主键列/回读函数不同
|
||||
```
|
||||
- **影响**:主要是维护成本与一致性风险——例如"`status == 'succeeded'` 时自动补 `completed_at`"的规则在 `update_style_source`(:677)和 `update_style_source_if_status`(:729)里各写了一遍,将来只改一处就会产生行为分叉。同时每个方法都自开自关连接,一次 `reconcile_missing_tasks` 会开关几十个 SQLite 连接。
|
||||
- **修复建议**:
|
||||
1. 抽 `_ExecutionMixin`(或模块级 `def _write(self, sql, params)` / `def _write_if(self, sql, params) -> int`)承载连接-提交-回滚-关闭,各 CRUD 只提供 SQL 与参数;
|
||||
2. 抽 `_EntitySpec(table, pk, columns_map, row_factory, json_fields, int_fields)`,把 `create/get/list/update/update_if_status` 做成泛型方法,12 组实体只保留各自的 spec 常量;
|
||||
3. 把 `_optional_text` / `_string_list` / `_json_or_none` / `_optional_int` / `_optional_float` / `_page` / `_page_size` 统一收进 `core/coercion.py`(或 `database/_coerce.py`),全仓改为 import。仅这一项就能删掉数百行重复代码。
|
||||
4. 同类问题在服务层:`advanced_material_service.py` 与 `advanced_style_set_service.py` 各有一份 `_safe_failure` / `_optional_score` / `_optional_text` / `_string_list`。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `advanced_style_set_service` 从 `material_service` 导入 7 个下划线私有函数,上传校验层没有公共 API
|
||||
|
||||
- **位置**:`backend/services/advanced_style_set_service.py:33`、`backend/services/advanced_material_service.py:27`
|
||||
- **问题**:两个服务都跨模块 import 了 `material_service` 的私有名。这些函数(data URL 解码、文件名/大小/内容类型归一、存储图转 data URL)实际上是整个素材域的**公共上传校验契约**,却因为下划线命名而对静态检查器和 IDE 表现为"不应被外部使用"。
|
||||
- **代码**:
|
||||
```python
|
||||
# advanced_style_set_service.py:33-41
|
||||
from backend.services.material_service import (
|
||||
_normalize_upload_content_type,
|
||||
_normalize_upload_filename,
|
||||
_normalize_upload_metadata,
|
||||
_normalize_upload_size,
|
||||
_recognition_metadata,
|
||||
_storage_image_data_url,
|
||||
_vision_provider_error,
|
||||
)
|
||||
```
|
||||
- **影响**:任何人重构 `material_service` 内部时不会预期这些名字有外部调用方;同时 `advanced_material_service` 与 `advanced_style_set_service` 在上传校验上出现了细微分叉(`material_service.upload_material:314` 用 `UPLOAD_ALLOWED_CONTENT_TYPES[detected].__contains__` 校验扩展名,`_persist_source:1571-1579` 却自己维护了一张 `{(".jpg",".jpeg")}` 别名表),说明契约已经开始漂移。
|
||||
- **修复建议**:新建 `backend/services/material_upload_contract.py`,把这 7 个函数 + `MAX_UPLOAD_BYTES` / `UPLOAD_ALLOWED_*` 常量迁过去并改成公共名(`normalize_upload_filename` 等),三个服务统一 import;同时把 `_persist_source` 的扩展名别名逻辑合并进 `validate_upload_file_type`,消除两套判定。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 衣柜分类与删除路径的两个小缺口
|
||||
|
||||
- **位置**:`backend/services/wardrobe_service.py:58`、`:128`
|
||||
- **问题**:
|
||||
1. `wardrobe_category` 只校验"非空",不校验是否属于 `DEFAULT_WARDROBE_CATEGORIES`(`:31`)。由于唯一索引是 `(profile_id, material_id, wardrobe_category)`,同一素材可以用 `"top"`、`"Top"`、`"上衣 "`(尾空格已 strip)、`"随便写"` 等无限多个分类反复导入,绕过重复检查;而 `match()` 只按 `DEFAULT_WARDROBE_CATEGORIES` 或调用方传入的分类查,这些条目永远匹配不到,成为衣柜里的僵尸数据。
|
||||
2. `delete_item` 用 `assert deleted is not None` 断言仓库删除结果。`assert` 在 `python -O` 下会被完全剥离,且并发删除(两个请求同时删同一条)时第二个会命中 `AssertionError` → 500 而不是 404。
|
||||
- **代码**:
|
||||
```python
|
||||
# wardrobe_service.py:58-66
|
||||
wardrobe_category = str(payload.get("wardrobe_category") or "").strip()
|
||||
if not wardrobe_category:
|
||||
raise ApiError(ErrorCode.VALIDATION_FAILED, "wardrobe_category is required", {"field": "wardrobe_category"})
|
||||
# 之后再无任何白名单校验
|
||||
|
||||
# wardrobe_service.py:128-129
|
||||
deleted = repository.delete(wardrobe_item_id)
|
||||
assert deleted is not None
|
||||
```
|
||||
- **影响**:脏分类导致衣柜条目数虚高、`list_items` 返回一堆永不参与匹配的项;`assert` 在并发下把预期内的竞态变成 500。
|
||||
- **修复建议**:`wardrobe_category` 归一化为小写并校验 `in DEFAULT_WARDROBE_CATEGORIES`(若需要自定义分类,改为从 profile 元数据里读用户自定义白名单)。`assert` 替换为:
|
||||
```python
|
||||
if deleted is None:
|
||||
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "wardrobe item not found", {"wardrobe_item_id": wardrobe_item_id})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 归档素材在标准库与进阶库产生两种不同的错误语义
|
||||
|
||||
- **位置**:`backend/services/material_catalog_resolver.py:75`,`backend/services/generation_reference_service.py:89`
|
||||
- **问题**:`MaterialCatalogResolver.get_material` 对 `advmat_*` 显式过滤 `status != "active"` 返回 `None`;对标准素材则不看 `recognition_status`,归档素材照样返回 DTO。下游 `_resolve_material_references` 因此给出两种错误。
|
||||
- **代码**:
|
||||
```python
|
||||
# material_catalog_resolver.py:75-81
|
||||
if normalized_id.startswith(ADVANCED_MATERIAL_ID_PREFIX):
|
||||
advanced = self.advanced_materials.get_material(normalized_id)
|
||||
if advanced is None or advanced.status != "active":
|
||||
return None # -> 404 "does not exist"
|
||||
material = self.materials.get_material(normalized_id)
|
||||
return self._normal_material(material) if material is not None else None
|
||||
# 归档的标准素材 recognition_status == "archived" -> 走到下面的 confirmed 检查
|
||||
# generation_reference_service.py:95-104 -> 400 "reference material is not confirmed"
|
||||
```
|
||||
- **影响**:同样是"用户把素材删了",进阶素材报 404「素材不存在」,标准素材报 400「素材未确认」。用户会误以为标准素材只是没确认,跑去重新识别,结果 `MaterialService.get_material`(`material_service.py:232`)又把归档素材当作不存在,形成前后矛盾的提示闭环。
|
||||
- **修复建议**:在 `_normal_material` 之前补一行 `if material.recognition_status == "archived": return None`,让两库语义一致;同时给 `_resolve_material_references` 的 404 分支加上 `"reason": "material_missing_or_archived"` 细节字段,前端可据此直接提示"该素材已被删除,请重新绑定"。
|
||||
511
审计/findings/A4-数据层.md
普通文件
511
审计/findings/A4-数据层.md
普通文件
|
|
@ -0,0 +1,511 @@
|
|||
# A4 — 数据库层审计(模型 / 仓储 / 迁移 / 事务)
|
||||
|
||||
> 审计范围(实际逐行读过的文件):
|
||||
> - `database/db_helper.py`(全文 473 行)
|
||||
> - `database/models.py`(全文 498 行)
|
||||
> - `database/seed.py`(全文 165 行)
|
||||
> - `database/migrations/0001..0018_*.sql`(全部 18 个迁移脚本全文)
|
||||
> - `database/repositories/job_repository.py`(全文 628 行)
|
||||
> - `database/repositories/profile_repository.py`(全文 367 行)
|
||||
> - `database/repositories/image_repository.py`(全文 311 行)
|
||||
> - `database/repositories/workflow_round_repository.py`(1-1180 行)
|
||||
> - `database/repositories/workflow_repository.py`(82-231、280-324 行)
|
||||
> - `database/repositories/profile_card_repository.py`(80-290 行)
|
||||
> - `database/repositories/advanced_material_repository.py`(471-760、1218-1400、2078-2123 行 + 全文方法轮廓)
|
||||
> - `database/repositories/workflow_cross_review_repository.py`(方法轮廓 + 348-770 结构扫描)
|
||||
> - `database/repositories/wardrobe_repository.py`、`capability_repository.py`、`material_repository.py`(表名/占位符相关片段)
|
||||
> - 交叉验证:`backend/services/queue_service.py`、`backend/services/generation_service.py`、`backend/services/image_service.py`、`backend/services/workflow_service.py`、`backend/services/chat_workflow_service.py`、`backend/services/cross_review_service.py`、`backend/services/material_analytics_service.py`、`backend/services/orphan_media_service.py`、`config.yaml`
|
||||
|
||||
## 摘要
|
||||
|
||||
参数化做得相当干净:全部 SQL 都走 `{placeholder}` 绑定,唯一的动态表名(`wardrobe_repository`)有白名单,未发现可利用的 SQL 注入。真正的问题集中在三处:**(1) PostgreSQL 分支实际是坏的**——`profile_repository` 的三个 CASE 列里有字面量 `%`,在 psycopg 的 `%s` paramstyle 下会直接抛异常,而 `config.yaml` 把 PostgreSQL 作为正式可选后端对外提供;**(2) SQLite 没有开 WAL**,却同时存在 4 线程并发写(`ThreadPoolExecutor(max_workers=4)`)和大量 `BEGIN IMMEDIATE` 长事务,写锁会阻塞全部读;**(3) JSON 列(`metadata_json`)是"整列覆盖"语义**,而服务层普遍在两个独立连接之间做"读—改—写",`generation_service` 甚至专门加了一把进程内 `threading.Lock` 来打补丁,说明丢更新已经是已知痛点但只堵住了一条路径。
|
||||
|
||||
事务边界方面,仓储内部的 `*_atomic` 方法写得很认真(`BEGIN IMMEDIATE` + `FOR UPDATE` + `rollback`),但跨仓储的组合操作完全没有事务包裹,`delete_image_metadata` 这类"先删图、再单独清 node 指针"的序列会留下悬挂引用——而 `workflow_nodes.selected_image_id` 恰恰没有外键。
|
||||
|
||||
工程上最突出的是重复度:14 个仓储手写了 **131 处** `connect()/try/finally close()`、**12 份** `_json_or_none`、**13 份** JSON 解码助手、**4 份** `_page/_page_size`(且分页上限不一致:100 vs 200)、**3 份** `_rollback`。整个数据层没有任何 context manager 或基类。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] `profile_repository` 的 SQL 含字面量 `%`,PostgreSQL 后端下角色列表/详情 100% 报错
|
||||
|
||||
- **位置**:`database/repositories/profile_repository.py:46`、`:73`、`:99`(同一条谓词被复制三份)
|
||||
- **问题**:三个 CASE 列常量里写死了 `LIKE '%"final_archive_history_id"%'`。当 `backend == "postgresql"` 时 `Database._placeholder` 返回 `%s`(`db_helper.py:288-290`),psycopg/psycopg2 会把整条 query 当作 `%`-format 模板去展开参数。SQL 文本里的 `%"` 是非法格式符,驱动会在 `ProfileRepository.get()` / `.list()` 传参时直接抛 `ValueError: unsupported format character '"'`(psycopg2)或 `IndexError`(psycopg3)。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/profile_repository.py:40-47
|
||||
WHEN EXISTS (
|
||||
SELECT 1
|
||||
FROM profile_workflows AS legacy_card_workflow
|
||||
WHERE legacy_card_workflow.profile_id = character_profiles.profile_id
|
||||
AND legacy_card_workflow.workflow_type = 'character_gradual'
|
||||
AND LOWER(COALESCE(legacy_card_workflow.status, '')) IN ('completed', 'archived')
|
||||
AND COALESCE(legacy_card_workflow.metadata_json, '') LIKE '%"final_archive_history_id"%'
|
||||
) THEN 'detailed'
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/profile_repository.py:186-194 —— 带参调用,触发 %-展开
|
||||
row = conn.execute(
|
||||
f"""
|
||||
SELECT {PROFILE_COLUMNS}, {PROFILE_GENERATION_KIND_COLUMN},
|
||||
{PROFILE_CATEGORY_COLUMN}, {DETAILED_WORKFLOW_STATE_COLUMN}
|
||||
FROM character_profiles
|
||||
WHERE profile_id = {placeholder}
|
||||
""",
|
||||
(profile_id,),
|
||||
).fetchone()
|
||||
```
|
||||
|
||||
- **影响**:`config.yaml:153-167` 明确把 `backend: auto | sqlite | postgresql` 作为受支持配置对外暴露(`postgresql.enabled: true` 即自动切换)。一旦用户切到 PG,角色详情、角色列表这两个最核心的读接口立刻 500,且错误信息是驱动层的格式化异常,完全指向不了根因。这不是"性能退化",是功能性完全不可用。
|
||||
- **修复建议**:
|
||||
1. 立刻把三处字面量改成参数绑定,彻底避开 `%` 转义问题:
|
||||
```python
|
||||
LEGACY_ARCHIVE_MARKER = '%"final_archive_history_id"%'
|
||||
# SQL 中写 AND COALESCE(..., '') LIKE {placeholder}
|
||||
# 调用处按 CASE 列出现次数补齐参数(或改用 json_extract / jsonb 谓词)
|
||||
```
|
||||
2. 更好的做法是干掉 `LIKE '%json%'` 这种反模式:`final_archive_history_id` 应该提升为 `profile_workflows` 的真实列(配 `0019` 迁移 + 回填),既解决转义又解决全表扫描。
|
||||
3. 加一条冒烟测试:用 `DatabaseSettings(backend="postgresql")` 构造 `_placeholder == "%s"`,断言所有仓储 SQL 常量中不含未转义的裸 `%`(可用正则 `%(?!s)` 静态扫描 `database/repositories/*.py`)。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] SQLite 未启用 WAL,却同时存在多线程并发写与 `BEGIN IMMEDIATE` 长事务
|
||||
|
||||
- **位置**:`database/db_helper.py:159-171`
|
||||
- **问题**:`connect()` 只设置了 `foreign_keys` 和 `busy_timeout`,**没有 `PRAGMA journal_mode = WAL`**。默认 rollback journal 模式下,任何一个持有 RESERVED/EXCLUSIVE 锁的写事务会阻塞**全库所有读**。而代码里到处是长写事务:`workflow_round_repository.confirm_candidate_atomic` 在一个 `BEGIN IMMEDIATE` 里跑了 12 条语句(`:815-1120`),`get_consistent_round_snapshot` 甚至为了**纯读**也去拿 `BEGIN IMMEDIATE` 写锁(`:312-313`)。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/db_helper.py:159-171
|
||||
def connect(self):
|
||||
if self.backend == "sqlite":
|
||||
db_path = self._resolve_sqlite_path()
|
||||
db_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
# Parallel image tasks briefly overlap while recording queue,
|
||||
# node, image, and audit rows. Give SQLite enough time to hand the
|
||||
# writer lock to the next task instead of failing immediately.
|
||||
conn = sqlite3.connect(db_path, timeout=30.0)
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.execute("PRAGMA foreign_keys = ON")
|
||||
conn.execute("PRAGMA busy_timeout = 30000")
|
||||
return conn
|
||||
return self._connect_postgresql()
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:216-220 —— 4 线程并发跑整条生成链路
|
||||
with ThreadPoolExecutor(max_workers=4, thread_name_prefix="imagestudio-chat-fast") as executor:
|
||||
futures = {
|
||||
executor.submit(self.generate_node, str(node["node_id"]), chat): node
|
||||
for node in nodes
|
||||
}
|
||||
```
|
||||
(`backend/services/cross_review_service.py:62` 同样是 `ThreadPoolExecutor(max_workers=min(len(routes), 4) or 1)`。)
|
||||
|
||||
- **影响**:注释里"give SQLite enough time"这句话本身就是症状——他们观察到了锁竞争,选择了把超时调到 30s 而不是消除竞争。实际后果:快速角色四图并发生成时,任意一个线程进入 `confirm_candidate_atomic`,其余 3 个线程连"读节点状态"都会被阻塞;一旦某个 provider 调用在事务内耗时较久,其他线程 30s 后抛 `sqlite3.OperationalError: database is locked`,而这个异常在 `generation_service.py:1866`、`:1890` 的 `except Exception: pass` 里被静默吞掉,表现为"节点状态莫名其妙没更新"。
|
||||
- **修复建议**:
|
||||
1. `connect()` 里补:
|
||||
```python
|
||||
conn.execute("PRAGMA journal_mode = WAL")
|
||||
conn.execute("PRAGMA synchronous = NORMAL")
|
||||
```
|
||||
WAL 让读写互不阻塞,读并发不再被写事务卡住。注意 `journal_mode` 是持久化属性,只需成功执行一次,但每次连接都执行是幂等的。
|
||||
2. `get_consistent_round_snapshot`(`workflow_round_repository.py:312`)改用 `BEGIN DEFERRED`——它只读不写,在 WAL 下天然拿到一致性快照,不需要写锁。
|
||||
3. 把 provider 调用移出事务边界(目前 `confirm_candidate_atomic` 内部没有网络调用,但 `generate_node` 链路上的 `update_node` → `HTTP` → `update_node` 序列值得复查)。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `metadata_json` 整列覆盖 + 跨连接读改写 = 丢更新,且只有一条路径加了进程内锁
|
||||
|
||||
- **位置**:`database/repositories/workflow_repository.py:298-322`(`update_node`)、`:154-178`(`update_workflow`)
|
||||
- **问题**:仓储的 `update` 语义是**整列覆盖** `metadata_json = ?`,没有任何 merge / 版本号 / CAS。服务层则普遍是"读 DTO → `{**node.metadata, ...}` → 写回",两步跨两个独立连接、两个独立事务。任意两个并发写入者都会互相覆盖对方的键。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/workflow_repository.py:298-318 —— 整列覆盖
|
||||
for key in allowed:
|
||||
if key not in payload:
|
||||
continue
|
||||
column = "metadata_json" if key == "metadata" else key
|
||||
value = _json_or_none(payload[key]) if key == "metadata" else payload[key]
|
||||
assignments.append(f"{column} = {placeholder}")
|
||||
params.append(value)
|
||||
...
|
||||
conn.execute(
|
||||
f"""
|
||||
UPDATE workflow_nodes
|
||||
SET {", ".join(assignments)}
|
||||
WHERE node_id = {placeholder}
|
||||
""",
|
||||
tuple(params),
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/generation_service.py:1870-1886 —— 典型的跨连接读-改-写
|
||||
node = self.workflow_service.get_node(node_id) # 连接 A:读
|
||||
node_metadata = node.metadata if isinstance(node.metadata, dict) else {}
|
||||
if (_optional_text(node_metadata.get("last_task_id")) == task.task_id
|
||||
and node.status in {"queued", "running"}):
|
||||
self.workflow_service.update_node( # 连接 B:整列覆盖
|
||||
node_id,
|
||||
{"status": "failed",
|
||||
"metadata": {**node_metadata, "generation_failure": failure,
|
||||
"last_task_id": task.task_id}},
|
||||
ctx,
|
||||
)
|
||||
```
|
||||
|
||||
作者显然知道这个问题——但只在一条路径上用**进程内**锁打了补丁:
|
||||
|
||||
```python
|
||||
# backend/services/generation_service.py:1145-1149
|
||||
lock_entry = _retain_quick_character_workflow_lock(workflow.workflow_id)
|
||||
lock_entry.lock.acquire()
|
||||
try:
|
||||
current_workflow = self.workflow_service.get_workflow(workflow.workflow_id).workflow
|
||||
metadata = dict(current_workflow.metadata or {})
|
||||
```
|
||||
|
||||
- **影响**:`profile_workflows.metadata_json` 里装着 `branch_state / stage_inputs / character_execution / completed_node_ids` 这些**工作流状态机的真身**(见 `workflow_round_repository.py:1097-1119`)。`confirm_candidate_atomic` 在自己的 DB 事务里正确地写了 `stage_inputs`,但只要 `generation_service._prepare_quick_character` 在此期间用它更早读到的 `metadata` 快照调用 `update_workflow`,`stage_inputs` 就被整个抹掉 —— 表现为"确认了候选图但下一节点拿不到上游图"。`threading.Lock` 只覆盖同一进程内的同一条代码路径,`confirm_candidate_atomic` 完全不参与这把锁。
|
||||
- **修复建议**:
|
||||
1. 短期:给 `update_workflow` / `update_node` 增加乐观并发控制。表已有 `updated_at`,可直接做:
|
||||
```python
|
||||
# WHERE workflow_id = ? AND updated_at = ? (expected_updated_at 由 DTO 带回)
|
||||
changed = int(cursor.rowcount or 0) > 0
|
||||
```
|
||||
写失败则由调用方重读重试,而不是静默覆盖。
|
||||
2. 中期:给仓储加 `patch_metadata(id, patch: dict)` 语义——在**同一个** `BEGIN IMMEDIATE` 事务里 `SELECT metadata_json` → merge → `UPDATE`,把读改写收进仓储,服务层不再手工 `{**node.metadata}`。
|
||||
3. 长期:把 `stage_inputs` / `completed_node_ids` 这类真状态从 JSON blob 里拆成真表(`workflow_branch_state`、`workflow_stage_input`),行级写入天然无冲突。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 跨仓储组合写没有事务边界:删图与清 node 指针分属两次提交,且 `selected_image_id` 无外键
|
||||
|
||||
- **位置**:`backend/services/image_service.py:216-234`、`database/repositories/image_repository.py:256-270`、`database/migrations/0003_profile_workflows_and_nodes.sql:36`
|
||||
- **问题**:`delete_image_metadata` 先在一个连接里 DELETE 并 `commit()`,再在另一个连接里把 `workflow_nodes.selected_image_id` 置空。两步之间进程崩溃 / 第二步抛异常,就留下指向不存在图片的指针。而 `selected_image_id` 在建表时**没有声明外键**,数据库层不会兜底。
|
||||
- **代码**:
|
||||
|
||||
```sql
|
||||
-- database/migrations/0003_profile_workflows_and_nodes.sql:36 —— 无 FOREIGN KEY
|
||||
selected_image_id TEXT,
|
||||
```
|
||||
该表末尾只有一条外键(`:41`):`FOREIGN KEY(workflow_id) REFERENCES profile_workflows(workflow_id) ON DELETE CASCADE`。
|
||||
|
||||
```python
|
||||
# database/repositories/image_repository.py:260-270 —— 独立事务提交
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
conn.execute(
|
||||
f"DELETE FROM generation_images WHERE image_id = {placeholder}",
|
||||
(image_id,),
|
||||
)
|
||||
conn.commit()
|
||||
finally:
|
||||
conn.close()
|
||||
return before
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/image_service.py:219-225 —— 第二次独立提交
|
||||
before = self.image_repository.delete_metadata(image_id)
|
||||
if before is None:
|
||||
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "图片不存在", {"image_id": image_id})
|
||||
if before.node_id:
|
||||
node = self.workflow_repository.get_node(before.node_id)
|
||||
if node and node.selected_image_id == image_id:
|
||||
self.workflow_repository.update_node(before.node_id, {"selected_image_id": None})
|
||||
```
|
||||
|
||||
同样的模式在批量清理里被放大:`backend/services/generation_service.py:1789-1804` 循环调用 `delete_metadata`,每张图一个独立事务,中途失败只把错误塞进 `errors` 列表继续走。
|
||||
- **影响**:`workflow_nodes.selected_image_id` 悬挂后,`node_dependency_context_service.py:81-83` 会去 `get_image(node.selected_image_id)` 拿到 `None`,下游节点的参考图静默丢失;`workflow_service` 判断"节点是否已完成"也会得出错误结论。另外 `character_profile_card_assets.image_id` 是 `ON DELETE RESTRICT`(`0015:32`),所以同一个 `delete_metadata` 在图片被角色卡引用时会抛 `IntegrityError` 且没有任何捕获,直接 500。
|
||||
- **修复建议**:
|
||||
1. 把这组操作下沉成仓储的一个方法 `ImageRepository.delete_with_node_release(image_id)`,在**同一连接**里 DELETE + `UPDATE workflow_nodes SET selected_image_id = NULL WHERE selected_image_id = ?`,一次 `commit()`。参照 `job_repository.delete_if_status`(`:382-431`)已经这么做了——同一个仓库里两种写法并存,说明是遗漏而非有意。
|
||||
2. 补迁移 `0019`:给 `workflow_nodes.selected_image_id` 加 `REFERENCES generation_images(image_id) ON DELETE SET NULL`(SQLite 需 `ALTER TABLE` 重建表,或至少加一条一次性的孤儿清理 UPDATE)。
|
||||
3. `delete_metadata` 捕获 `IntegrityError`,翻译成"该图片已被角色卡引用,无法删除"的业务错误。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 陈旧任务恢复的时间戳比较绑死了 SQLite 的 UTC 语义,PG 下会静默失效
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:457-468`、`database/repositories/job_repository.py:180-201`
|
||||
- **问题**:`cutoff_value` 在 Python 侧按 **UTC** 格式化成 `"%Y-%m-%d %H:%M:%S"` 字符串,与列 `updated_at` 做比较。SQLite 的 `CURRENT_TIMESTAMP` 恰好是 UTC 且恰好是这个格式,所以能工作。PostgreSQL 里 `updated_at TIMESTAMP`(无时区)的 `CURRENT_TIMESTAMP` 返回的是**会话本地时间**,两者相差一个时区偏移。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/queue_service.py:456-468
|
||||
observed_at = now or datetime.now(timezone.utc)
|
||||
...
|
||||
cutoff = observed_at.astimezone(timezone.utc) - timedelta(
|
||||
seconds=max(int(stale_after_seconds), 1)
|
||||
)
|
||||
cutoff_value = cutoff.strftime("%Y-%m-%d %H:%M:%S")
|
||||
candidates = self.repository.list_stale(
|
||||
statuses=("running", "retrying"),
|
||||
updated_before=cutoff_value,
|
||||
limit=min(max(int(limit), 1), 500),
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/job_repository.py:182, 191-201
|
||||
age_clause = f"AND updated_at <= {placeholder}" if updated_before else ""
|
||||
...
|
||||
WHERE status IN ({status_placeholders})
|
||||
{age_clause}
|
||||
ORDER BY updated_at ASC, created_at ASC, task_id ASC
|
||||
```
|
||||
|
||||
- **影响**:PG 服务器在 UTC+8 时,库里的 `updated_at` 永远比 UTC 的 `cutoff` 大 8 小时,`updated_at <= cutoff` 恒不成立 → **`recover_stale_tasks` 永远返回空**,上个进程遗留的 `running` 任务永久卡死,且不报错、日志里只会显示"recovered: 0"。反向时区(UTC-x)则会把刚提交 1 分钟的任务当成陈旧任务抢走,造成重复执行。
|
||||
- **修复建议**:
|
||||
1. 统一在 SQL 侧算时间差,不要在 Python 侧格式化字符串:
|
||||
```sql
|
||||
AND updated_at <= CURRENT_TIMESTAMP - {interval_expr}
|
||||
```
|
||||
SQLite 用 `datetime('now', ?)`,PG 用 `NOW() - (?::text)::interval`,由 `Database.backend` 分派。
|
||||
2. 或者退一步:把所有 `TIMESTAMP` 列迁移成 `TIMESTAMPTZ`(PG)并在建连时 `SET TIME ZONE 'UTC'`,让两个后端的 `CURRENT_TIMESTAMP` 语义对齐。
|
||||
3. 补一条断言:`_row_to_task` 里 `str(row["created_at"])` 在 PG 下返回的是 `datetime` 的 repr(`2026-07-27 03:48:00`),在 SQLite 下是原始字符串——目前碰巧格式一致,但这是巧合而非契约,值得写进测试。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `MaterialAnalyticsService.summarize` 无条件全表扫描 9 张表,含 `generation_tasks` 的 JSON blob
|
||||
|
||||
- **位置**:`backend/services/material_analytics_service.py:16-47`
|
||||
- **问题**:一次汇总调用里发了 9 条 SELECT,全部**没有 WHERE 时间窗、没有 LIMIT、没有聚合下推**,把整张表拉进 Python 内存后用 `Counter` 统计。其中 `generation_tasks` 还带上了 `request_json` / `metadata_json` 两个大 JSON 列。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/material_analytics_service.py:41-45
|
||||
style_validation_cases = conn.execute(
|
||||
"SELECT status, fidelity_score FROM advanced_style_validation_cases"
|
||||
).fetchall()
|
||||
audits = conn.execute("SELECT action, after_snapshot, metadata_json FROM audit_logs WHERE action IN ('wardrobe_match','apply_wardrobe_template','recognize_material','renormalize_material')").fetchall()
|
||||
tasks = conn.execute("SELECT model_route, request_json, metadata_json FROM generation_tasks").fetchall()
|
||||
```
|
||||
|
||||
- **影响**:`generation_tasks` 和 `audit_logs` 是**只增不删**的表(`job_repository.delete_if_status` 只删终态任务且需显式调用)。运行几个月后单次调用就会拉几百 MB 进内存;在没有 WAL 的前提下(见 P1-2),这个长读事务还会把整库读锁住,阻塞所有写。`audit_logs` 那条虽然有 `action IN (...)`,但 `idx_audit_logs_action ON audit_logs(action, created_at)`(`0001:16`)只能过滤,仍要回表读 `after_snapshot`。
|
||||
- **修复建议**:
|
||||
1. 加时间窗参数(默认最近 30 天)并走已有索引:`WHERE created_at >= ?`。`generation_tasks` 需要补 `idx_generation_tasks_created ON generation_tasks(created_at)`(现有三个索引都以 `status`/`workflow_id`/`profile_id` 打头)。
|
||||
2. 能下推的统计直接下推:`recognition_status` 计数、`fidelity_score` 的 AVG/COUNT 全部改成 `GROUP BY` + 聚合函数,只有必须解析 JSON 的部分才拉行。
|
||||
3. 结果加缓存(这是 dashboard 类只读指标,秒级过期完全够用)。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `profile_repository` 每行 10 个相关子查询,且同一组谓词被复制三份
|
||||
|
||||
- **位置**:`database/repositories/profile_repository.py:32-117`(三个常量)、`:186-194`、`:222-232`
|
||||
- **问题**:`PROFILE_GENERATION_KIND_COLUMN`(3 个 EXISTS)、`PROFILE_CATEGORY_COLUMN`(3 个 EXISTS,谓词与前者几乎逐字相同)、`DETAILED_WORKFLOW_STATE_COLUMN`(4 个 EXISTS,前两个又是同样的谓词)被拼进同一条 SELECT。结果集每一行都要跑 10 个相关子查询,其中"sealed 角色卡"和"legacy 归档工作流"这两个判断各被重复计算 3 次。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/profile_repository.py:33-39 与 :60-66 —— 逐字重复
|
||||
WHEN EXISTS (
|
||||
SELECT 1
|
||||
FROM character_profile_cards AS profile_card
|
||||
WHERE profile_card.profile_id = character_profiles.profile_id
|
||||
AND LOWER(COALESCE(profile_card.status, '')) = 'sealed'
|
||||
) THEN 'detailed' # 第二处只有 THEN 分支不同:THEN 'profile_card'
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/profile_repository.py:222-232 —— 三份常量同时拼入
|
||||
rows = conn.execute(
|
||||
f"""
|
||||
SELECT {PROFILE_COLUMNS}, {PROFILE_GENERATION_KIND_COLUMN},
|
||||
{PROFILE_CATEGORY_COLUMN}, {DETAILED_WORKFLOW_STATE_COLUMN}
|
||||
FROM character_profiles
|
||||
{where}
|
||||
ORDER BY updated_at DESC, created_at DESC
|
||||
LIMIT {normalized_page_size} OFFSET {offset}
|
||||
""",
|
||||
tuple(params),
|
||||
).fetchall()
|
||||
```
|
||||
|
||||
- **影响**:`_page_size` 上限 100(`:362-367`),即最坏一次列表请求触发 1000 次相关子查询;其中 3 次带 `LIKE '%...%'` 前缀通配符,无法走索引,必须读出 `profile_workflows.metadata_json` 全文逐行匹配。加上 P1-2 的无 WAL,列表接口会成为写路径的主要阻塞源。另外三份重复的 CASE 是纯粹的维护地雷——改判定规则要同步改三处,而 `'archived'` 这个状态目前只出现在 `PROFILE_CATEGORY_COLUMN:80` 而不在 `PROFILE_GENERATION_KIND_COLUMN:53`,两处已经开始漂移了。
|
||||
- **修复建议**:
|
||||
1. 用一次 `LEFT JOIN LATERAL` / 派生表把三个 EXISTS 结果算一遍,再在外层 CASE 里复用:
|
||||
```sql
|
||||
FROM character_profiles cp
|
||||
LEFT JOIN (
|
||||
SELECT profile_id, 1 AS has_sealed_card FROM character_profile_cards
|
||||
WHERE LOWER(COALESCE(status,'')) = 'sealed' GROUP BY profile_id
|
||||
) sc ON sc.profile_id = cp.profile_id
|
||||
```
|
||||
三个输出列都从这几个标志位派生,子查询数从 10 降到 3。
|
||||
2. `LIKE '%"final_archive_history_id"%'` 提升为真实列(与 P1-1 的修复合并做)。
|
||||
3. `character_profile_cards` 补 `idx_profile_cards_profile_status ON character_profile_cards(profile_id, status)`——现有的 `idx_profile_cards_profile_version(profile_id, version)`(`0015:17-18`)对这个谓词只能用到前缀。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 14 个仓储零抽象:131 处手写连接样板、13 份 JSON 助手、分页上限还不一致
|
||||
|
||||
- **位置**:`database/repositories/` 全目录
|
||||
- **问题**:没有基类、没有 context manager、没有共享 helper 模块。实测重复量:
|
||||
|
||||
| 重复项 | 份数 | 证据 |
|
||||
|---|---|---|
|
||||
| `conn = self.database.connect()` + `try/finally close()` | **131** | `advanced_material_repository` 37、`workflow_repository` 16、`workflow_round_repository` 14、`job_repository` 12、`model_provider_repository` 10 … |
|
||||
| `def placeholder(self)` property | 13 | 每个仓储一份,实现全部是 `return self.database._placeholder` |
|
||||
| `_json_or_none` | 12 | 实现全部是 `json.dumps(value, ensure_ascii=False, sort_keys=True)` |
|
||||
| JSON 解码助手(`_json_loads` / `_json_object` / `_json`) | 13 | 且语义**不一致**(见下) |
|
||||
| `_page` / `_page_size` | 4 组 | 且上限不一致 |
|
||||
| `_rollback(conn)` | 3 | `advanced_material:2119`、`cross_review:1464`、`round:1378` |
|
||||
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/job_repository.py:617-622 —— 上限 100
|
||||
def _page_size(value: Any) -> int:
|
||||
try:
|
||||
page_size = int(value)
|
||||
except (TypeError, ValueError):
|
||||
page_size = 30
|
||||
return min(max(page_size, 1), 100)
|
||||
```
|
||||
```python
|
||||
# database/repositories/advanced_material_repository.py:2115-2116 —— 上限 200,且不吞异常
|
||||
def _page_size(value: int) -> int:
|
||||
return min(max(int(value or 30), 1), 200)
|
||||
```
|
||||
两者行为差两处:上限(100 vs 200)、非法输入处理(回落 30 vs 抛 `ValueError`)。
|
||||
|
||||
JSON 解码同样分裂:
|
||||
```python
|
||||
# database/repositories/job_repository.py:625-628 —— 脏数据直接抛
|
||||
def _json_loads(value: str | None) -> dict[str, Any]:
|
||||
if not value:
|
||||
return {}
|
||||
return json.loads(value)
|
||||
```
|
||||
```python
|
||||
# database/repositories/workflow_round_repository.py:1324-1328 —— 脏数据降级为 {}
|
||||
def _json_object(value: str | None) -> dict[str, Any]:
|
||||
if not value:
|
||||
return {}
|
||||
parsed = json.loads(value)
|
||||
return parsed if isinstance(parsed, dict) else {}
|
||||
```
|
||||
|
||||
另外 `for key in allowed:` 里的 `allowed` 是 **set**(`workflow_repository.py:281-294`、`job_repository.py:569-577`、`profile_repository.py:243-256` 等),Python 的字符串哈希随机化让 SET 子句顺序**每个进程都不同**,生成的 SQL 文本随之变化,SQLite 的 statement cache 命中率被打散。
|
||||
|
||||
- **影响**:
|
||||
- `_json_loads` 遇到非 dict 的 JSON(比如历史遗留写进去的数组)会把 `list` 塞进 `GenerationTask.metadata`,后续 `task.metadata.get(...)` 抛 `AttributeError`;同样的数据在 round 仓储里则安全降级为 `{}` —— 同一份脏数据的行为取决于走哪个仓储。
|
||||
- 分页上限不一致意味着 `/advanced-materials` 单页最多 200 条而其他接口 100 条,前端分页组件无法统一。
|
||||
- 131 处样板意味着任何一次连接层改动(比如加 WAL、加 retry、加慢查询日志)都要改 131 个地方,而这次审计已经发现 `image_repository.delete_metadata` 少了 `rollback`、`profile_repository` 全文没有 `_rollback` 而 `advanced_material_repository` 有——遗漏正是重复的直接产物。
|
||||
- **修复建议**:
|
||||
1. 新建 `database/repositories/base.py`:
|
||||
```python
|
||||
class BaseRepository:
|
||||
def __init__(self, database: Database):
|
||||
self.database = database
|
||||
|
||||
@property
|
||||
def placeholder(self) -> str:
|
||||
return self.database._placeholder
|
||||
|
||||
@contextmanager
|
||||
def connection(self, *, write: bool = False):
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
if write and self.database.backend == "sqlite":
|
||||
conn.execute("BEGIN IMMEDIATE")
|
||||
yield conn
|
||||
if write:
|
||||
conn.commit()
|
||||
except Exception:
|
||||
with suppress(Exception):
|
||||
conn.rollback()
|
||||
raise
|
||||
finally:
|
||||
with suppress(Exception):
|
||||
conn.close()
|
||||
|
||||
def lock_clause(self) -> str:
|
||||
return " FOR UPDATE" if self.database.backend == "postgresql" else ""
|
||||
```
|
||||
131 处 `try/finally` 塌缩成 `with self.connection(write=True) as conn:`,`BEGIN IMMEDIATE` / `FOR UPDATE` / `rollback` 三件事再也不会各写各的。
|
||||
2. 新建 `database/repositories/_sql.py`,唯一实现 `json_or_none` / `json_object` / `page` / `page_size` / `optional_text`,并把分页上限统一成一个常量。JSON 解码统一采用防御式(`_json_object` 那版)。
|
||||
3. `_update_assignments` 里的 `allowed` 一律改成 `tuple`(有序),让同一批字段生成稳定的 SQL 文本。
|
||||
4. 抽出 `build_update(table, pk, allowed, payload)` 通用构造器——目前 `workflow_repository` 里 `update_workflow` / `update_workflow_if_status` / `update_node` / `update_node_if_status` 四份 assignment 循环几乎逐字相同(`:154-160`、`:203-209`、`:298-304`、`:357-363`)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 关键词过滤未转义 LIKE 通配符
|
||||
|
||||
- **位置**:`database/repositories/profile_repository.py:305-310`、`database/repositories/advanced_material_repository.py:493-498`
|
||||
- **问题**:用户输入直接包进 `%...%`,输入里的 `%` 和 `_` 会被当作通配符。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/profile_repository.py:305-310
|
||||
if keyword:
|
||||
clauses.append(
|
||||
f"(name LIKE {placeholder} OR description LIKE {placeholder})"
|
||||
)
|
||||
like_value = f"%{keyword}%"
|
||||
params.extend([like_value, like_value])
|
||||
```
|
||||
|
||||
- **影响**:不是注入(参数是绑定的),但搜索 `50%` 会匹配到所有以 `50` 开头的记录,搜索 `_` 匹配任意单字符——用户可以用单个 `%` 拉出全表。结合前缀通配符导致的全表扫描,是个小的 DoS 面。
|
||||
- **修复建议**:`keyword.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")`,SQL 侧加 `ESCAPE '\'`(SQLite 和 PG 都支持)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] PostgreSQL 迁移执行器按 `;` 裸切分;psycopg2 适配器不关闭游标
|
||||
|
||||
- **位置**:`database/db_helper.py:280-286`、`:301-317`
|
||||
- **问题**:
|
||||
```python
|
||||
# database/db_helper.py:280-286
|
||||
def _execute_script(self, conn, script: str) -> None:
|
||||
if self.backend == "sqlite":
|
||||
conn.executescript(script)
|
||||
return
|
||||
statements = [statement.strip() for statement in script.split(";") if statement.strip()]
|
||||
for statement in statements:
|
||||
conn.execute(statement)
|
||||
```
|
||||
按字面 `;` 切分,任何出现在字符串字面量、`$$ ... $$` 函数体或注释里的分号都会把语句劈成两半。当前 18 个迁移恰好没有触发(唯一带引号的是 `WHERE status IN ('queued', 'running')`),但下一条含触发器 / 函数 / 默认值字符串的迁移就会炸。
|
||||
|
||||
```python
|
||||
# database/db_helper.py:305-308 —— 每次 execute 新建游标,从不关闭
|
||||
def execute(self, query: str, params: tuple[Any, ...] | list[Any] | None = None):
|
||||
cursor = self.connection.cursor()
|
||||
cursor.execute(query, tuple(params or ()))
|
||||
return cursor
|
||||
```
|
||||
- **影响**:迁移切分是一颗定时炸弹(现在无害、下一次改动即爆);游标不关闭因为连接是每次调用即建即关,实际泄漏窗口很短,但 `advanced_material_repository` 有 37 处连接、单个方法内可能连发 5-6 条语句,psycopg2 路径下这些游标要等 `close()` 才释放。
|
||||
- **修复建议**:
|
||||
1. 迁移执行改用 `sqlparse.split()`,或退而求其次:约定迁移脚本用 `-- statement-breakpoint` 分隔符显式切分。
|
||||
2. 适配器改成 `with self.connection.cursor() as cursor:`,或返回一个持有游标并在 `__del__` / 上下文退出时关闭的包装。更彻底的做法是删掉 psycopg2 回退分支——psycopg3 已经是标准,维护两条驱动路径的收益不抵成本。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `list_stale` 与图库列表的排序键与现有索引不匹配
|
||||
|
||||
- **位置**:`database/repositories/job_repository.py:191-201`、`database/repositories/image_repository.py:171-180`
|
||||
- **问题**:
|
||||
- `list_stale` 是 `WHERE status IN (...) AND updated_at <= ? ORDER BY updated_at ASC`,但 `generation_tasks` 上只有 `idx_generation_tasks_status(status, created_at)`(`0005:22-23`),`updated_at` 完全没索引 → 过滤后必须 filesort。
|
||||
- `list_images` 的 `ORDER BY is_archived ASC, created_at DESC, image_id DESC`,首排序键 `is_archived` 不在 `idx_images_profile(profile_id, created_at)`(`0004:30-31`)里,索引的有序性被浪费。
|
||||
- **影响**:任务表只增不删,`recover_stale_tasks` 在启动时还会以 `updated_before=None, limit=None` 全量扫(`advanced_material_worker_runtime.py:82-84`),随数据量线性劣化;图库分页在归档图较多时同理。
|
||||
- **修复建议**:迁移 `0019` 补两条索引:
|
||||
```sql
|
||||
CREATE INDEX IF NOT EXISTS idx_generation_tasks_status_updated
|
||||
ON generation_tasks(status, updated_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_images_profile_archived
|
||||
ON generation_images(profile_id, is_archived, created_at DESC);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 未发现问题的项(已核查,供交叉验证)
|
||||
|
||||
- **SQL 注入**:全部 SQL 走 `?`/`%s` 绑定;唯一的动态表名 `wardrobe_repository.py:36-42` 有 `WARDROBE_TABLES` 白名单并对非法值 `raise ValueError`;`orphan_media_service.py:33-64` 的 `{table}` / `{columns}` 全部来自代码内硬编码元组;`LIMIT/OFFSET` 的直接插值(`profile_repository.py:229`)经过 `_page/_page_size` 的 `int()` + `min/max` 钳制。**未发现可利用点。**
|
||||
- **外键与级联**:`PRAGMA foreign_keys = ON` 在每次连接时执行(`db_helper.py:168`),且是在事务外执行的,生效。级联策略设计合理(工作流 CASCADE、图片 SET NULL、已接受素材 RESTRICT)。除 `workflow_nodes.selected_image_id`(见 P2-1)和 `advanced_material_imports.current_attempt_id / accepted_material_id`(0016 未声明外键,但受 CASCADE 保护,风险低)外无缺失。
|
||||
- **迁移可重入性**:18 个脚本全部使用 `CREATE TABLE/INDEX IF NOT EXISTS`,无破坏性 DDL、无 DROP、无数据变更。`initialize()` 的双重判定(`_migration_applied` + `_migration_tables_exist`,`db_helper.py:180-184`)在部分失败后能自愈重放。**这块做得好。**
|
||||
- **仓储内部原子性**:`create_round_with_candidates`、`apply_feedback_atomic`、`confirm_candidate_atomic`、`profile_card_repository.finalize`、`workflow_cross_review_repository.*_atomic` 均正确使用 `BEGIN IMMEDIATE`(SQLite)/ `FOR UPDATE`(PG)+ `rollback` + 幂等键重放,且 `self.get_*()` 的二次连接调用都发生在 `commit()`/`rollback()` **之后**,不会自锁。**这块也做得好。**
|
||||
- **连接泄漏**:131 处 `connect()` 全部有 `finally: conn.close()` 配对,未发现漏关。
|
||||
283
审计/findings/A5-核心与安全.md
普通文件
283
审计/findings/A5-核心与安全.md
普通文件
|
|
@ -0,0 +1,283 @@
|
|||
# A5 — core/ 核心模块 + 安全
|
||||
|
||||
> 审计范围(均已实际 Read/验证):
|
||||
> `core/security.py`、`core/secret_service.py`、`core/storage.py`、`core/remote_fetch.py`、
|
||||
> `core/media_proxy.py`、`core/config_service.py`、`core/config_writer.py`、`core/runtime_paths.py`、
|
||||
> `core/identity.py`、`core/chat_access_policy.py`、`core/audit_service.py`、`core/webhook.py`、
|
||||
> `core/model_router.py`、`core/model_route_chain.py`、`core/prompt_pipeline.py`、`core/interop.py`、
|
||||
> `core/interactions.py`、`core/image_formats.py`、`core/astrbot_provider_bridge.py`、
|
||||
> `core/generation_errors.py`(部分)、
|
||||
> `backend/services/integration_token_service.py`、`backend/services/chat_command_guard_service.py`、
|
||||
> `backend/services/settings_service.py`、`backend/routes/media_routes.py`、
|
||||
> `backend/routes/storage_routes.py`、`backend/route_registry.py`、`database/db_helper.py`(配置读写部分)、
|
||||
> `main.py`(请求上下文与 media 分发部分)、`config.yaml`
|
||||
>
|
||||
> 已忽略:`.tmp/`、`.tmp_pytest_*`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`
|
||||
|
||||
## 摘要
|
||||
|
||||
密码学原语本身写得不错:HMAC 全部用 `hmac.compare_digest`、令牌带过期校验、`remote_fetch` 对 SSRF 做了协议/凭据/私网/重定向降级/跨源剥 Authorization 的完整校验、`storage.split_uri` 对 `..` 与绝对路径做了双重拦截。真正的问题不在这些原语,而在**信任边界的设计**:所有登录 AstrBot WebUI 的用户被无差别授予 `can_manage_config`(`main.py:104`),而存储根目录允许配置为任意绝对路径(`core/runtime_paths.py:43`),两者叠加把「配置管理」直接升级成**任意文件读取**(经未认证的 `media/fetch` 出站)与**任意文件写入**(经 `storage/migrate`)。我已用真实代码路径完整复现读取链路。
|
||||
|
||||
第二类系统性问题是配置持久化:项目用自研的 `dump_yaml` + `_load_yaml_subset` 做 YAML 往返,我用仓库自带的 `config.yaml` 实测**往返不稳定**——6 个空列表字段被静默变成空字典,15 行注释全部丢失;同时 `save()` 会把打包默认值固化进可写配置,导致插件升级后新默认值永久失效。此外 `_record_snapshot` 把**未脱敏**的完整配置(含 `api_key_plaintext`、Postgres 密码、令牌哈希与盐)明文写进数据库,`write_text_atomic` 的 `os.replace` 会把 `config.yaml` 的权限位重置为 umask 默认值。
|
||||
|
||||
日志脱敏、反序列化(无 pickle / 无 `yaml.load`)、审计 SQL 参数化这几项没有发现问题。
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] 存储根可配为任意绝对路径 + 未认证的 media/fetch = 任意文件读取
|
||||
- **位置**:`core/runtime_paths.py:43`、`core/storage.py:100`、`backend/route_registry.py:173`、`backend/services/settings_service.py:240`
|
||||
- **问题**:`storage.*_path` 是普通配置项,`SettingsService.validate()` 从头到尾**没有任何针对 `storage` 段的校验**(`validate()` 只校验 generation/vision/prompt_governance/advanced_materials)。`resolve_data_path` 对绝对路径直接原样返回,`VfsStorage.resolve_uri` 的越界检查只保证 `resolved_path` 在 `resolved_root` 之内——而 root 本身已经被攻击者设成了 `C:/` 或 `/`。签发出的令牌由 `GET media/fetch` 消费,该路由权限为 `public_token`(`auth_required: False`)。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/runtime_paths.py:43
|
||||
resolved = Path(path).expanduser()
|
||||
if resolved.is_absolute():
|
||||
return resolved # 绝对路径不做任何限制
|
||||
|
||||
# core/storage.py:105
|
||||
resolved_root = resolve_data_path(root_path).resolve()
|
||||
resolved_path = (resolved_root / relative).resolve()
|
||||
if resolved_path != resolved_root and resolved_root not in resolved_path.parents:
|
||||
raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri})
|
||||
|
||||
# backend/route_registry.py:173
|
||||
RouteSpec("GET", "media/fetch", "backend.routes.media_routes.fetch_media", "public_token"),
|
||||
# backend/route_registry.py:28
|
||||
"public_token": {"auth_required": False, "required_permission": None, ...}
|
||||
```
|
||||
- **实测复现**(在仓库根直接运行,未改任何源码):
|
||||
```python
|
||||
StorageConfig(temp_path='C:/Windows')
|
||||
VfsStorage(FakeCS()).resolve_uri('storage://temp/System32/drivers/etc/hosts')
|
||||
# -> C:\Windows\System32\drivers\etc\hosts exists=True
|
||||
MediaProxy(s).sign('storage://temp/System32/drivers/etc/hosts')
|
||||
# -> {'url': '/api/plug/.../media/fetch?token=eyJleHBpcmVzX2F0...', 'size_bytes': 827}
|
||||
```
|
||||
攻击链:任一已登录 WebUI 用户 → `POST settings/save` 把 `storage.temp_path` 改为 `/`(或 `C:/`)→ `GET media/index?root=temp` 枚举全盘 → `GET media/sign?uri=storage://temp/etc/shadow` → 把 URL 交给**任何未认证的第三方**去 `GET media/fetch` 取走内容。
|
||||
- **影响**:宿主机任意文件读取并可无认证外传(AstrBot 的 `data/config/*.json`、`.env`、SSH 私钥、其他插件的凭据)。同时是数据外泄通道——签名 URL 可直接贴给外部。
|
||||
- **修复建议**:
|
||||
1. 在 `SettingsService.validate()` 增加 storage 段校验:拒绝绝对路径,或强制 `resolve_data_path(p).resolve()` 必须落在 `get_runtime_data_root().resolve()` 之内;
|
||||
2. 在 `VfsStorage._root_paths()` 加二次防线,对越出运行时数据根的 root 直接抛 `FORBIDDEN`;
|
||||
3. `resolve_data_path` 不再无条件放行绝对路径,改为白名单(仅允许显式配置的挂载根);
|
||||
4. `media/fetch` 令牌绑定签发者(把 `ctx.actor_id` 放进 payload 并在 fetch 时校验),避免签名 URL 变成可转发的无主凭据。
|
||||
|
||||
### [P1-严重] storage/migrate 非 dry-run 可在可配置根之间任意复制文件/目录
|
||||
- **位置**:`core/storage.py:45`、`core/storage.py:182`、`backend/routes/storage_routes.py:28`
|
||||
- **问题**:`migrate_storage` 仅要求 `require_config_manager(ctx)`(等价于「已登录」,见下条 P2),`dry_run` 由请求体控制且可传 `false`。`_copy_path` 会把 source 整棵目录树 `shutil.copy2` 到 target。结合上一条(root 可为任意绝对路径),这就是**任意文件/目录写入**。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/storage.py:52
|
||||
if not dry_run:
|
||||
_copy_path(source_path, target_path)
|
||||
|
||||
# core/storage.py:183
|
||||
if source_path.is_file():
|
||||
target_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy2(source_path, target_path) # 目标已存在时静默覆盖
|
||||
return
|
||||
```
|
||||
`will_overwrite` 只是被计算出来放进返回值(`core/storage.py:52`),**没有任何一处用它来阻断覆盖**。
|
||||
- **影响**:覆盖 AstrBot 配置、写入计划任务/启动脚本目录、投毒插件目录 → 从「配置管理员」提升到宿主机代码执行。即使 root 全部保持默认,也能无提示覆盖用户素材/存档。
|
||||
- **修复建议**:(a)修完 P1 第一条后 root 天然受限;(b)`migration_plan` 在 `will_overwrite and not payload.get("confirm_overwrite")` 时抛 `ApiError`;(c)把非 dry-run 迁移提升为独立权限而非复用 `can_manage_config`;(d)迁移动作写审计日志(当前完全没有 `audit_service.record`)。
|
||||
|
||||
### [P1-严重] 配置快照把未脱敏的明文密钥写进数据库
|
||||
- **位置**:`backend/services/settings_service.py:614`(调用点 `:444`、`:556`)
|
||||
- **问题**:`save()` / `rollback()` 在写盘前调用 `_record_snapshot(before_file, ...)`,而该方法把 `before_file`(`load_config_file_payload` 的原始返回值)**原样 `json.dumps`** 存入 `config_snapshots.config_json`。项目其它读取路径(`list_snapshots`、`get_snapshot`)都调了 `_mask_sensitive`,唯独写入侧没有。`config.yaml` 里确实存在 `api_key_plaintext`(`backend/services/model_provider_runtime.py:366` 读取该字段)、`database.postgresql.password` / `dsn`(`config.yaml:162,167`)、`security.integration_token_hash` 与 `..._salt`。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/settings_service.py:610-615
|
||||
(
|
||||
snapshot_id,
|
||||
reason,
|
||||
ctx.actor_id,
|
||||
json.dumps(dict(config), ensure_ascii=False, sort_keys=True), # 未脱敏
|
||||
),
|
||||
```
|
||||
- **影响**:每保存一次配置就把当时的全部明文凭据复制一份进 DB,无上限、无保留期、无清理。DB 备份 / SQLite 文件泄露 / Postgres 只读账号即可拿到历史全部 API Key 与数据库口令;令牌盐+哈希外泄后可离线爆破集成令牌。
|
||||
- **修复建议**:写入前脱敏,同时保留回滚能力——建议把敏感字段替换为哨兵值(如 `"***PRESERVED***"`),在 `rollback()` 里遇到哨兵时从当前 `before_file` 取回原值(`_merge_masked` 已有同类逻辑,可直接复用)。另外给 `config_snapshots` 加保留期清理任务。
|
||||
|
||||
### [P2-中等] 自研 YAML 往返不等价:空列表退化为字典、注释全丢(已用仓库 config.yaml 实测)
|
||||
- **位置**:`core/config_writer.py:41`(`dump_yaml`)、`database/db_helper.py:371`(`_load_yaml_subset`);触发点 `backend/services/settings_service.py:445`、`:557`、`backend/services/integration_token_service.py:129`、`backend/services/review_service.py:42`
|
||||
- **问题**:`dump_yaml` 对空 list 只输出 `key:`,`_load_yaml_subset` 把「键后无值」一律解析成空 dict,类型从 `list` 翻成 `dict`。注释在 `_strip_yaml_comment` 里被丢弃且写回时不还原。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/config_writer.py:50-53
|
||||
elif isinstance(child, list):
|
||||
lines.append(f"{prefix}{key}:")
|
||||
for item in child: # 空列表 -> 只剩 "key:"
|
||||
lines.append(f"{prefix} - {_format_scalar(item)}")
|
||||
|
||||
# database/db_helper.py:403-406
|
||||
if value == "":
|
||||
child: dict[str, Any] = {} # "key:" 一律变成 dict
|
||||
parent[key] = child
|
||||
```
|
||||
- **实测**(读仓库自带 `config.yaml` → `dump_yaml` → 再解析):
|
||||
```
|
||||
roundtrip stable: False
|
||||
DIFF .model_assignments.generation_cross_review_routes [] -> {}
|
||||
DIFF .recognition_prompts.category_requirements [] -> {}
|
||||
DIFF .chat_access.group_allowlist [] -> {}
|
||||
DIFF .chat_access.user_allowlist [] -> {}
|
||||
DIFF .chat_access.adult_group_allowlist [] -> {}
|
||||
DIFF .chat_access.adult_user_allowlist [] -> {}
|
||||
comments in src: 15 (写回后全部丢失)
|
||||
```
|
||||
- **影响**:任何一次保存设置/轮换集成令牌/审核写回都会触发。所有 `isinstance(x, list)` 判断在保存一次后失效——例如 `settings_service.py:765` 的 `uses_plugin_adapters = isinstance(generation.get("adapters"), list)`,用户删光 adapters 后该判断永久为 False,`_runtime_override_conflicts` 的兼容分支随之失效。`model_assignments.*_routes` 这类列表字段同理。运维手写的 15 条注释在用户第一次点保存后消失。
|
||||
- **修复建议**:`dump_yaml` 对空容器显式输出 `key: []` / `key: {}`;`_load_yaml_subset` 已能通过 `_parse_scalar` 正确解析 `[]`。更彻底的做法是引入 `ruamel.yaml`(round-trip 模式,保注释)或至少写一个 `dump_yaml(_load_yaml_subset(x)) == 归一化(x)` 的属性测试锁住不变式。
|
||||
|
||||
### [P2-中等] save() 把打包默认值固化进可写配置,插件升级后新默认值永久失效
|
||||
- **位置**:`backend/services/settings_service.py:423`、`:445`、`database/db_helper.py:72`
|
||||
- **问题**:`save()` 的基线 `before = self._load_current_mapping()` 走的是 `load_config_payload`,而后者 = 打包 `config.yaml` ∪ 可写 `config.yaml` ∪ 运行时覆盖。`_restore_runtime_managed_fields` 只剥掉「运行时覆盖」,**打包默认值原封不动地留在 `merged` 里**并被写进可写配置。
|
||||
- **代码**:
|
||||
```python
|
||||
# database/db_helper.py:77-82
|
||||
if _should_apply_runtime_overrides(path):
|
||||
packaged_path = get_packaged_config_path()
|
||||
if not _same_path(path, packaged_path) and packaged_path.exists():
|
||||
payload = _load_yaml_subset(packaged_path.read_text(encoding="utf-8"))
|
||||
if path.exists():
|
||||
payload = _merge_mappings(payload, _load_yaml_subset(path.read_text(encoding="utf-8")))
|
||||
|
||||
# backend/services/settings_service.py:423,445
|
||||
before = self._load_current_mapping() # 已含打包默认值
|
||||
...
|
||||
write_text_atomic(self.config_service.config_path, dump_yaml(merged))
|
||||
```
|
||||
- **影响**:用户第一次点「保存设置」后,可写配置就变成完整快照。此后插件升级修改的任何默认值(新路由、新的 prompt 模板、安全默认开关)都被旧快照覆盖,用户看不到也无法感知,只能手删配置文件。这与 `config_service.py:68-71` 刻意把 `version` 设为不可覆盖的意图直接矛盾——那里已经踩过一次这个坑,但只修了 `version` 一个字段。
|
||||
- **修复建议**:`save()` 的写盘基线改用 `load_config_file_payload(path)` 且**跳过打包合并**(新增一个只读可写文件的 loader),只把用户显式提交的 diff 落盘;打包默认值保持在读取期合并。
|
||||
|
||||
### [P2-中等] write_text_atomic 的 os.replace 重置配置文件权限,且临时文件短暂全局可读
|
||||
- **位置**:`core/config_writer.py:26`
|
||||
- **问题**:每次写配置都新建临时文件再 `replace`。新文件权限是 `0666 & ~umask`(POSIX 下通常 0644),`os.replace` 保留的是**源 inode** 的权限,目标原有的 0600 被丢弃。而 `config.yaml` 里就有 `api_key_plaintext` 和数据库口令。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/config_writer.py:32-37
|
||||
temporary = destination.with_name(f".{destination.name}.{uuid4().hex}.tmp")
|
||||
try:
|
||||
temporary.write_text(content, encoding="utf-8") # 默认 0644,无 os.chmod
|
||||
temporary.replace(destination) # 目标权限位被覆盖为 0644
|
||||
```
|
||||
- **影响**:运维执行 `chmod 600 config.yaml` 加固后,用户第一次在 WebUI 点保存就被静默回退到 0644——同宿主机上的任何本地用户/其他容器进程可读明文 API Key 与 Postgres 密码。写入窗口内临时文件同样全局可读(临时文件竞态)。另外全程没有 `fsync`,崩溃后可能留下截断的 `config.yaml`(无备份)。
|
||||
- **修复建议**:
|
||||
```python
|
||||
import os, stat
|
||||
fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
|
||||
try:
|
||||
os.write(fd, content.encode("utf-8"))
|
||||
os.fsync(fd)
|
||||
finally:
|
||||
os.close(fd)
|
||||
if destination.exists(): # 保留既有权限位
|
||||
os.chmod(temporary, stat.S_IMODE(destination.stat().st_mode))
|
||||
os.replace(temporary, destination)
|
||||
```
|
||||
|
||||
### [P2-中等] 所有已登录 WebUI 用户被无差别授予 can_manage_config,无角色区分
|
||||
- **位置**:`main.py:104`、`main.py:2337`
|
||||
- **问题**:`RequestContext` 的权限集合只有「有 username → 全给」「没有 → 全不给」两种状态。`core/security.py` 精心区分的 `require_write` / `require_task_retry` / `require_config_manager` 在真实运行时全部塌缩成 `require_authenticated`。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:104-106
|
||||
BRIDGE_PERMISSIONS = frozenset(
|
||||
{"can_write", "can_manage_config", "can_manage_materials", "can_retry_tasks"}
|
||||
)
|
||||
# main.py:2337
|
||||
permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||||
```
|
||||
- **影响**:这是上面两条 P1 的**权限前提**——「只有管理员才能改 storage 路径」的假设不成立,任何 WebUI 账号都行。同时任何账号可轮换集成令牌(打断已接入的伴侣插件)、可把 `generation.provider.base_url` 指向 `http://169.254.169.254/` 或内网地址(`backend/services/model_provider_runtime.py:217`、`:304` 与 `engines/image_provider.py:221` 均以 `allow_private=True` 调用 `validate_http_url`,私网防护被主动关闭),构成经认证的 SSRF。
|
||||
- **修复建议**:从 AstrBot 侧读取真实角色(`g` 上的 role/claims)映射到权限集;在拿不到角色信息之前,至少把 `can_manage_config` 从默认集合中移除,改为要求显式配置的管理员用户名白名单(`security.config_admin_users`)。
|
||||
|
||||
### [P2-中等] 群聊日配额统计全表扫描 + Python 侧 JSON 解析
|
||||
- **位置**:`backend/services/chat_command_guard_service.py:70`
|
||||
- **问题**:`_daily_group_count` 把当天**所有** `chat_command_allowed` 审计行全量拉回进程,逐行 `json.loads(metadata_json)` 再比对 `group_id`。SQL 里没有任何 group 过滤条件,也没有索引可用(`metadata_json` 是 TEXT)。
|
||||
- **代码**:
|
||||
```python
|
||||
rows = conn.execute(
|
||||
f"SELECT metadata_json FROM audit_logs WHERE action = {placeholder} AND created_at >= {placeholder}",
|
||||
("chat_command_allowed", start),
|
||||
).fetchall()
|
||||
count = 0
|
||||
for row in rows:
|
||||
try:
|
||||
metadata = json.loads(row["metadata_json"] or "{}")
|
||||
...
|
||||
if str(metadata.get("group_id") or "") == group_id:
|
||||
count += 1
|
||||
```
|
||||
- **影响**:每条群聊生图命令都触发一次当日全表扫描。`audit_logs` 是所有审计动作的公共表(配置保存、令牌轮换、聊天命令全在里面),随部署时间线性膨胀。繁忙群在高峰期会把 SQLite 拖到写锁竞争,成为聊天命令的延迟瓶颈。此外 `_daily_count` 统计的是所有 `chat_command_allowed`,而 `record()` 对**非生图命令**也会记这个 action(`:41-55`),导致「每日生成上限」被非生成类命令误消耗。
|
||||
- **修复建议**:为聊天配额单独建一张 `chat_command_quota(day, scope_type, scope_id, count)` 计数表并加唯一索引,用 UPSERT 累加;或至少给 `audit_logs` 增加独立的 `group_id` 列 + `(action, created_at, group_id)` 复合索引。同时把配额计数的 action 从通用的 `chat_command_allowed` 拆成 `chat_generation_allowed`。
|
||||
|
||||
### [P2-中等] remote_fetch 的 SSRF 防护存在 DNS TOCTOU(rebinding)窗口
|
||||
- **位置**:`core/remote_fetch.py:73`、`core/remote_fetch.py:40`
|
||||
- **问题**:`validate_http_url` 通过 `socket.getaddrinfo` 解析主机名并逐一检查私网地址,随后 `opener.open(request, ...)` 让 urllib **重新解析一次** DNS。攻击者控制的权威 DNS 只需把 TTL 设为 0 并在两次解析间返回不同结果(先返回公网 IP 通过校验,再返回 `127.0.0.1` / `169.254.169.254`),即可绕过全部私网检查。重定向处理器 `_ValidatedRedirectHandler` 同样只校验 URL 不校验最终连接的 IP。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/remote_fetch.py:73-75
|
||||
for address in _resolve_addresses(host, port): # 第一次解析
|
||||
if _is_unsafe_address(address):
|
||||
raise RemoteFetchError("remote URL resolves to a private or local network address")
|
||||
# core/remote_fetch.py:40
|
||||
with opener.open(request, timeout=timeout_seconds) as response: # urllib 第二次解析
|
||||
```
|
||||
- **影响**:`backend/services/chat_media_import_service.py:31` 用**用户在聊天里发的 URL**调用本函数(且正确地未开 `allow_private`),这是唯一的不可信输入入口,也正是 rebinding 最容易被利用的地方 → 可探测并读取内网 HTTP 服务(云元数据、内部 API)。
|
||||
- **修复建议**:把校验通过的 IP **固定**下来再连接——解析一次得到安全 IP,用该 IP 建连并通过 `Host` 头/SNI 保留原主机名(自定义 `HTTPConnection`/`HTTPSConnection` 子类覆写 `connect`),或在 `http_response` 钩子里用 `response.fp.raw._sock.getpeername()` 复核对端 IP,不安全则立即中断。
|
||||
|
||||
### [P3-轻微] 未加引号的配置标量会被 os.path.expandvars 展开
|
||||
- **位置**:`database/db_helper.py:445`
|
||||
- **问题**:`_parse_scalar` 的兜底分支对所有未加引号的标量执行环境变量展开。
|
||||
- **代码**:
|
||||
```python
|
||||
try:
|
||||
return int(value)
|
||||
except ValueError:
|
||||
return os.path.expandvars(value)
|
||||
```
|
||||
- **实测**:`_load_yaml_subset('plugin:\n display_name: $PATH\n')` 返回了完整的 `PATH` 环境变量内容。
|
||||
- **影响**:`display_name` 等非敏感字段会通过 `settings/current`、`settings/export` 直接把环境变量内容回显给前端,而这些路径的 `_mask_sensitive` 按 key 名脱敏、认不出内容里的密钥。因为 `dump_yaml` 写回时所有字符串都会被 `json.dumps` 加引号(加引号后走 `json.loads` 分支、不展开),实际风险局限于**手写**的 `config.yaml`;但 `${AWS_SECRET_ACCESS_KEY}` 这类值一旦被手写进任意字段就会被明文回显。同时含 `$` 的合法值(如密码)会被静默篡改。
|
||||
- **修复建议**:改为仅对显式声明的引用语法展开(如整值为 `env:NAME` / `${NAME}`),其余标量原样返回;`core/secret_service.resolve_env_value` 已经实现了这套显式语义,直接复用即可。
|
||||
|
||||
### [P3-轻微] 媒体令牌置于 URL 查询串且 fetch 端点完全未认证
|
||||
- **位置**:`core/media_proxy.py:51`、`backend/route_registry.py:173`
|
||||
- **问题**:签名 URL 形如 `/api/plug/.../media/fetch?token=<payload>.<sig>`,令牌即凭据,且 fetch 端点 `auth_required: False`。
|
||||
- **代码**:
|
||||
```python
|
||||
"url": f"{MEDIA_FETCH_PATH}?token={token}",
|
||||
```
|
||||
- **影响**:令牌会进入反向代理/网关访问日志、浏览器历史、以及页面外链跳转时的 `Referer` 头。默认 TTL 300 秒(`DEFAULT_MEDIA_TTL_SECONDS`)限制了窗口,但在此期间任何拿到日志的人都可无认证取回媒体。令牌 payload 里也没有绑定签发者,任何人拿到即可用。
|
||||
- **修复建议**:payload 增加 `actor_id` 并在 `_resolve_token` 中与当前 `ctx` 比对(`fetch_media_payload` 已要求认证,可直接校验);响应加 `Referrer-Policy: no-referrer`;或改用短时 Cookie 承载而非 query 参数。
|
||||
|
||||
### [P3-轻微] 敏感键匹配把 "key" 当子串,误伤普通配置项
|
||||
- **位置**:`backend/services/settings_service.py:26`、`:678`
|
||||
- **问题**:`SENSITIVE_KEY_PARTS` 含裸 `"key"`,`_is_sensitive_key` 做的是子串匹配。
|
||||
- **代码**:
|
||||
```python
|
||||
SENSITIVE_KEY_PARTS = ("password", "token", "secret", "api_key", "apikey", "key", "dsn")
|
||||
```
|
||||
- **实测**:`_is_sensitive_key("advanced_materials.cost_budget.price_key")` → `True`。
|
||||
- **影响**:`cost_budget.price_key`(计价键,见 `settings_service.py:143` 的 schema 定义)在 `get_current` / `export` / `diff` 中一律显示为 `***MASKED***`,前端永远读不到当前值,`diff` 也只显示 `before_set/after_set` 布尔量,运维无法确认自己配了什么。写入侧因 `_merge_masked`(`:705`)跳过哨兵值不会被破坏,所以仅是可见性缺陷。
|
||||
- **修复建议**:改为按最后一段键名做精确/后缀匹配(`api_key`、`apikey`、`*_secret`、`*_token`、`password`、`dsn`),或维护显式敏感字段路径清单,与 `core/secret_service.SECRET_KEY_PARTS`(该处未含裸 `key`,两份清单已经不一致)统一到同一份定义。
|
||||
|
||||
### [P3-轻微] 配置文件锁仅为进程内 threading.RLock
|
||||
- **位置**:`core/config_writer.py:17`、`core/config_writer.py:59`
|
||||
- **问题**:`config_file_lock` 返回的是按路径缓存的 `threading.RLock`,只在当前 Python 进程内生效。
|
||||
- **代码**:
|
||||
```python
|
||||
def config_file_lock(path: str | Path) -> threading.RLock:
|
||||
return _lock_for_path(Path(path))
|
||||
```
|
||||
- **影响**:AstrBot 自身通过 `persist_runtime_config_values`(`database/db_helper.py:49`)写同一份插件配置时不受此锁保护;多 worker 部署或外部脚本编辑 `config.yaml` 时,`SettingsService.save()` 的「读—改—写」会整份覆盖对方的修改。`os.replace` 保证了单次写入原子,但保证不了读-改-写序列的隔离。此外 `_PATH_LOCKS` 只增不减(配置路径数量有限,实际不构成泄漏)。
|
||||
- **修复建议**:叠加文件锁(POSIX `fcntl.flock` / Windows `msvcrt.locking`,或跨平台用同目录 `.lock` 文件 + `O_EXCL`);或在写入前比对文件 mtime/内容哈希,发现被外部修改则拒绝并要求前端重新拉取。
|
||||
|
||||
---
|
||||
|
||||
## 未发现问题的检查项(供交叉验证)
|
||||
|
||||
- **反序列化**:全树无 `pickle`、无 `yaml.load`。`database/db_helper.py:420` 的 `ast.literal_eval` 仅用于兼容旧的 Python-repr 值,不能执行代码。
|
||||
- **签名令牌校验**:`core/media_proxy.py:109`、`core/webhook.py:42`、`backend/services/integration_token_service.py:175`/`:115` 全部使用 `hmac.compare_digest`,无时序侧信道;`_resolve_token` 有过期校验(`media_proxy.py:78`);令牌格式固定 HMAC-SHA256,无算法协商,不存在算法混淆。
|
||||
- **集成令牌存储**:`IntegrationTokenService.rotate` 正确地只落盘 salt+HMAC,主动 `security.pop("integration_token")` 清除旧的明文槽位,并保留带过期时间的 previous 槽做优雅轮换(`:51-68`)。
|
||||
- **SQL 注入**:`core/audit_service.py`、`backend/services/settings_service.py`、`chat_command_guard_service.py` 的 SQL 全部使用 `self.database._placeholder` 参数化绑定,`LIMIT` 也走占位符。
|
||||
- **路径遍历(URI 侧)**:`VfsStorage.split_uri`(`core/storage.py:117`)同时拦截绝对路径与 `..` 分量,`resolve_uri` 再用 `resolve()` + `parents` 复核,可正确拦截符号链接逃逸。问题只出在 root 本身可控(见 P1)。
|
||||
- **日志脱敏**:`core/` 下无任何 `logger.*` / `logging.*` 调用,不存在核心模块直接打印密钥的路径;`core/generation_errors.py:11` 另有 `SECRET_KEYWORDS` 对上游错误体做清洗。
|
||||
- **不可信 URL 的 SSRF 基线**:`chat_media_import_service.py:31` 处理聊天来源 URL 时**未**开启 `allow_private`,协议限定 http/https、拒绝带凭据的 URL、拒绝 HTTPS→HTTP 降级重定向、跨源重定向剥离 `Authorization`(`core/remote_fetch.py:64-67`、`:119-126`)——除 DNS rebinding 窗口外防护完整。
|
||||
- **聊天白名单默认安全**:`core/chat_access_policy.py:39` 兜底 `return False`,未识别 action 与空白名单都拒绝,无绕过路径。
|
||||
440
审计/findings/A6-引擎与适配器.md
普通文件
440
审计/findings/A6-引擎与适配器.md
普通文件
|
|
@ -0,0 +1,440 @@
|
|||
# A6 — engines/ 模型引擎 + adapters/ 平台适配器
|
||||
|
||||
> 审计范围(均已完整 Read):
|
||||
> `engines/__init__.py`、`engines/image_provider.py`、`engines/vision_provider.py`、`engines/single_flow.py`、`engines/review_flow.py`、`engines/character_flow.py`、`engines/fast_character_flow.py`、`engines/quick_profile_flow.py`
|
||||
> `adapters/astrbot_adapter.py`、`adapters/astrbot_card_renderer.py`、`adapters/astrbot_command_adapter.py`、`adapters/astrbot_command_parser.py`、`adapters/astrbot_media_adapter.py`、`adapters/chat_commands.py`、`adapters/onebot11_adapter.py`、`adapters/wechat_adapter.py`、`adapters/webui_adapter.py`
|
||||
> `backend/services/chat_workflow_service.py`、`backend/services/chat_session_service.py`、`backend/services/chat_media_import_service.py`、`backend/services/model_provider_runtime.py`、`backend/services/web_hosting_service.py`(节选)、`backend/services/material_service.py`(节选)、`backend/services/generation_service.py`(节选)、`backend/services/profile_service.py`(节选)
|
||||
> `core/generation_errors.py`、`core/image_formats.py`、`core/identity.py`、`core/remote_fetch.py`(节选)、`main.py`(节选)
|
||||
|
||||
## 摘要
|
||||
|
||||
图像 provider(`engines/image_provider.py`)这条链路的工程质量明显高于其余部分:URL 校验、响应字节上限、按图片数动态计算 JSON 上限、错误分类(`core/generation_errors._category`)、密钥脱敏都做到位了。问题集中在**它旁边的三条"次要"链路**上——vision provider、structured_text/structured_vision callable、以及聊天媒体导入——这三条都缺少图像链路已有的防护,属于典型的"主路径加固过、旁路径没跟上"。
|
||||
|
||||
最严重的一条是功能性死链:`size` 请求字段从聊天命令一路透传到 `task.request`,但 `engines/single_flow.py:61` 只读 `aspect_ratio`,全仓库没有任何地方把 `size` 转成 `aspect_ratio`,因此 `/yp 单图 --尺寸 4K` 和 `/yp 高清 <id> 4K` 实际全部产出 1024×1024——高清修复功能等于不生效。
|
||||
|
||||
其次是 `ChatMediaImportService.import_image` 的兜底分支把任意字符串当本地文件路径直接 `read_bytes()`,而输入来自聊天消息组件的 `file`/`path` 字段(`adapters/astrbot_media_adapter.py`),构成任意本地文件读取面。
|
||||
|
||||
关于"四个 flow 文件能否合并":**结论是不建议合并**。`single_flow.py` / `review_flow.py` 是真正的引擎(455/451 行),`character_flow.py` / `fast_character_flow.py` / `quick_profile_flow.py` 是纯声明式节点模板目录(145/50/32 行),三者之间真正重复的只有约 10 行 `*_node_templates()` 构造器样板,抽取收益远低于把不同工作流的语义强行耦合的代价。真正值得合并的重复在别处:`adapters/onebot11_adapter.py` 与 `adapters/wechat_adapter.py` 结构性重复约 90%。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] `size` 请求字段全链路无人消费,聊天尺寸参数与高清修复静默失效
|
||||
|
||||
- **位置**:`engines/single_flow.py:61`(消费端)、`backend/services/chat_workflow_service.py:63` 与 `:929`(生产端)
|
||||
- **问题**:`SingleFlowEngine.generate` 只从请求里读 `aspect_ratio`,而聊天单图与高清修复写入的是 `size`(`"1920x1080"` / `"2560x1440"` / `"3840x2160"`)。`generation_service.py:733` 的 `runtime_generation_request = {**payload, ...}` 原样透传 `size`,全仓库(排除 `.tmp/`、`tests/`)对 `aspect_ratio` 的写入只出现在 `advanced_material_service.py:912`、`advanced_style_set_service.py`、`node_injection_template_service.py`、`prompt_expansion_service.py`——没有任何一处把 `size` 映射成 `aspect_ratio`。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/single_flow.py:56-61
|
||||
def generate(self, node: WorkflowNode, task: GenerationTask, request: dict[str, Any]) -> list[MockGeneratedAsset]:
|
||||
count = _bounded_count(request.get("count", 1))
|
||||
...
|
||||
width, height = _dimensions(str(request.get("aspect_ratio") or "1:1"))
|
||||
```
|
||||
```python
|
||||
# engines/single_flow.py:248-255
|
||||
def _dimensions(aspect_ratio: str) -> tuple[int, int]:
|
||||
if aspect_ratio == "3:4": return 768, 1024
|
||||
if aspect_ratio == "4:3": return 1024, 768
|
||||
if aspect_ratio == "16:9": return 1280, 720
|
||||
return 1024, 1024
|
||||
```
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:925-931(高清修复)
|
||||
generation = self._data(self.dispatcher(ctx, "POST", f"nodes/{node['node_id']}/generate", payload={
|
||||
"prompt": "high resolution restoration, preserve identity, composition, clothing and original style",
|
||||
...
|
||||
"size": size, # <- 写入
|
||||
"count": 1,
|
||||
```
|
||||
```python
|
||||
# engines/single_flow.py:154-159(真正发给 provider 的尺寸)
|
||||
result = provider.generate_image(
|
||||
ImageGenerationRequest(
|
||||
...
|
||||
size=f"{width}x{height}", # 永远来自 aspect_ratio,即 1024x1024
|
||||
```
|
||||
- **影响**:`/yp 单图 ... --尺寸 4K` 与 `/yp 高清 <image_id> 4K` 都发出 `size="1024x1024"`;高清修复的唯一价值(提升分辨率)完全失效,用户只会得到一张同尺寸重绘图。同时 `astrbot_command_parser.py:49-52` 精心校验的 1K/2K/4K 参数是纯装饰。数据库里记录的 `width`/`height` 也随之全是 1024。
|
||||
- **修复建议**:在 `single_flow.generate` 增加显式的尺寸解析优先级,并让 `size` 成为一等输入:
|
||||
```python
|
||||
width, height = _resolve_dimensions(request.get("size"), request.get("aspect_ratio"))
|
||||
|
||||
def _resolve_dimensions(size: Any, aspect_ratio: Any) -> tuple[int, int]:
|
||||
text = str(size or "").strip().lower()
|
||||
if match := re.fullmatch(r"(\d{2,5})\s*[x×]\s*(\d{2,5})", text):
|
||||
w, h = int(match.group(1)), int(match.group(2))
|
||||
return min(max(w, 64), 4096), min(max(h, 64), 4096)
|
||||
return _dimensions(str(aspect_ratio or "1:1"))
|
||||
```
|
||||
同时给 `SIZE_ALIASES` 加一条断言测试,覆盖 `/yp 高清 <id> 4K` 端到端产出的 `ImageGenerationRequest.size`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 聊天媒体导入把任意字符串当本地文件路径读取(任意本地文件读取面)
|
||||
|
||||
- **位置**:`backend/services/chat_media_import_service.py:33-36`,输入来源 `adapters/astrbot_media_adapter.py:15-18` → `main.py:1161,1167`
|
||||
- **问题**:`import_image` 的兜底分支在既不是 `storage://`、也不是 `data:image/`、也不是 `http(s)://` 时,直接把字符串当本地路径 `expanduser().resolve().read_bytes()`,没有任何根目录约束或白名单。而这个字符串来自聊天消息里 Image 组件的 `url` / `file` / `path` / `image_url` 属性——这几个字段在 OneBot/WeChat 协议侧是消息内容的一部分,并非可信的服务端常量。
|
||||
- **代码**:
|
||||
```python
|
||||
# adapters/astrbot_media_adapter.py:12-19
|
||||
for component in chain if isinstance(chain, (list, tuple)) else []:
|
||||
if "image" not in component.__class__.__name__.lower():
|
||||
continue
|
||||
for name in ("url", "file", "path", "image_url"):
|
||||
text = str(getattr(component, name, None) or "").strip()
|
||||
if text and text not in references:
|
||||
references.append(text)
|
||||
```
|
||||
```python
|
||||
# backend/services/chat_media_import_service.py:30-36
|
||||
elif text.startswith(("http://", "https://")):
|
||||
body = read_http_response_limited(text, timeout_seconds=30, max_bytes=MAX_CHAT_IMAGE_BYTES)
|
||||
extension = Path(urlsplit(text).path).suffix.lstrip(".").lower() or "jpg"
|
||||
else:
|
||||
source = Path(text).expanduser().resolve()
|
||||
body = source.read_bytes() # <- 无任何根目录约束
|
||||
extension = source.suffix.lstrip(".").lower() or "jpg"
|
||||
```
|
||||
- **影响**:只要消息组件的路径字段可被影响(`file:///`、相对路径、`~/.astrbot/...`),任意宿主文件即可被读入并作为"素材"落盘到 `storage://materials/chat/...`,随后通过素材列表接口读回——等价于任意文件读取 + 外带。同一条链路上还有第二个缺陷:整个函数**没有任何图片魔数校验**(对比 `engines/single_flow.py:447 _require_image_format` 对 provider 返回图片做了 `detect_image_format`),扩展名只是被强制改写成 `jpg`,非图片内容会被当图片存储。`data:image/` 分支的 `base64.b64decode(encoded)` 也在解码**之后**才检查 `len(body) > MAX_CHAT_IMAGE_BYTES`,一个超大 data URI 会先被完整解码进内存。
|
||||
- **修复建议**:
|
||||
1. 删除本地路径兜底分支,或改为对一个显式配置的缓存根做 `Path.resolve()` 前缀约束(参考 `backend/services/web_hosting_service.py:58-67` 的 `_resolve` 写法,那里做对了)。
|
||||
2. 落盘前统一走 `core.image_formats.detect_image_format(body)`,`None` 则拒绝,并用检出的 `image_format.extension` 而非用户扩展名。
|
||||
3. `data:` 分支先按 `len(encoded) > ((MAX_CHAT_IMAGE_BYTES + 2) // 3) * 4` 预检再解码(`engines/single_flow.py:398-404` 已有这个正确写法可直接复用)。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 内容安全审核 provider 解析时缺 modality 与 provider_type 校验,与同文件其他两处不一致
|
||||
|
||||
- **位置**:`backend/services/model_provider_runtime.py:285-289`(对比 `:131-136` 与 `:196-201`)
|
||||
- **问题**:`_structured_vision_callable_for_single_route` 调用 `resolve_route(route_name)` **不带 `modality=`**,且**没有 `provider_type == "openai_compatible"` 的前置判断**。同文件的 `_vision_provider_for_single_route` 两者都有,`_structured_text_callable_for_single_route` 有 provider_type 判断。这个 callable 承担的是图像内容安全审核(涉政/涉恐/未成年人识别)。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/model_provider_runtime.py:131-136(正确的对照组)
|
||||
resolved = self.model_provider_service.resolve_route(route_name, modality="vision_recognition")
|
||||
if not resolved:
|
||||
return None
|
||||
provider = resolved.get("provider") or {}
|
||||
if str(provider.get("provider_type") or "openai_compatible") != "openai_compatible":
|
||||
return None
|
||||
```
|
||||
```python
|
||||
# backend/services/model_provider_runtime.py:285-289(缺两道校验)
|
||||
resolved = self.model_provider_service.resolve_route(route_name)
|
||||
if not resolved:
|
||||
return None
|
||||
provider = resolved.get("provider") or {}
|
||||
secret = resolve_secret_value(...) # 直接进入取密钥,没有 provider_type 判断
|
||||
```
|
||||
而下面 `review()` 硬编码 OpenAI chat/completions 报文形状(`:331-341`)。
|
||||
- **影响**:同名路由若在 `image_generation` 模态下存在,会被解析成"审核模型";一个非 openai_compatible 的 provider 也会被套上 OpenAI 报文格式发送。两种情况都在审核时抛异常。而 `structured_vision_callable` 的 `review_with_fallback`(`:264-271`)对所有异常一律吞掉换下一条路由,全部失败后抛 `RuntimeError` ——上层若把"审核不可用"当作放行,就是安全审核静默绕过;若当作拒绝,则是全量误杀。无论哪种,都不该由一个可以被静态排除的配置错配触发。
|
||||
- **修复建议**:与 `:131-136` 对齐——补 `modality="vision_recognition"`(或为审核新增独立 modality)与 `provider_type` 判断;并把三处 `resolve_route + 密钥解析 + provider_type 校验` 抽成一个私有方法,杜绝再次漂移。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 缩略图是原图的字节级完整拷贝,存储占用直接翻倍
|
||||
|
||||
- **位置**:`engines/single_flow.py:176-179`
|
||||
- **问题**:provider 返回的图片字节被原样写入 `image_uri` 和 `thumbnail_uri` 两个路径。全仓库(`engines/`、`backend/services/generation_service.py`)不存在任何降采样/缩放代码,`core/image_formats.py` 也只做魔数识别、不解析尺寸。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/single_flow.py:176-179
|
||||
image_format = _require_image_format(image_bytes, provider_id=result.provider_id)
|
||||
image_uri, thumbnail_uri = _output_uris(task, request, index, image_format.extension)
|
||||
self._write_image(image_uri, image_bytes)
|
||||
self._write_image(thumbnail_uri, image_bytes) # 同一份字节写两遍
|
||||
```
|
||||
- **影响**:单张图上限 `MAX_PROVIDER_IMAGE_BYTES = 25 MiB`(`engines/image_provider.py:21`),意味着最坏情况每张生成图占 50 MiB。候选池默认一轮 4 张、快速角色 4 节点并发,磁盘增长是设计预期的 2 倍。同时前端列表页加载"缩略图"实际拉的是全尺寸原图,网络与内存开销同样翻倍。
|
||||
- **修复建议**:在 `_write_image` 之外新增 `_write_thumbnail(uri, image_bytes, max_edge=512)`,用已经作为可选依赖存在的 Pillow(`adapters/astrbot_card_renderer.py:56` 已 `from PIL import Image`)做等比缩放;Pillow 不可用时退化为写原图并在 metadata 打 `thumbnail_downscaled: False`,便于后续补偿任务识别。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] vision provider 链路完全没有错误分类与可重试判定,`retryable` 字段是死代码
|
||||
|
||||
- **位置**:`engines/vision_provider.py:304-326`、`backend/services/material_service.py:857-871`
|
||||
- **问题**:图像链路有 `core/generation_errors.provider_failure_attribution`,把 401/403 → `auth_error`、429 → `rate_limited`、5xx → `provider_unavailable`,并计算 `retryable`(`core/generation_errors.py:102-125`)。vision 链路没有任何等价物:`_vision_provider_error` 只是把 `error_type` 原样搬运,`retryable` 依赖 `exc.details.get("retryable")`——而 `engines/vision_provider.py` 全文从未往 `details` 里写过 `retryable`,因此那两行永远不会执行。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/material_service.py:863-865
|
||||
"response_issue": str(exc)[:300],
|
||||
}
|
||||
if isinstance(exc.details.get("retryable"), bool): # vision_provider 从不设置该键
|
||||
failure["retryable"] = exc.details["retryable"]
|
||||
```
|
||||
```python
|
||||
# engines/vision_provider.py:304-312(唯一写 details 的地方,只有 body_preview / body_truncated)
|
||||
except urllib.error.HTTPError as exc:
|
||||
body = exc.read(MAX_PROVIDER_ERROR_BYTES + 1).decode("utf-8", errors="replace")
|
||||
raise VisionProviderError(
|
||||
"vision provider returned an HTTP error",
|
||||
provider_id="unknown",
|
||||
status_code=exc.code,
|
||||
error_type="http_error", # 401 / 429 / 503 全都是 "http_error"
|
||||
details={"body_preview": body[:500], "body_truncated": len(body) > MAX_PROVIDER_ERROR_BYTES},
|
||||
) from exc
|
||||
```
|
||||
- **影响**:素材识别失败时,鉴权错误(用户必须改配置)、限流(应退避重试)、上游 5xx(应重试)在 `error_type` 上完全无法区分;`_record_recognition_failure` 记录的失败态没有可操作信息,重试策略无从制定,UI 也只能给出通用文案。`_vision_provider_error` 还绕过了 `core/generation_errors._safe_message` 的密钥脱敏正则,`reason`(来自 `str(exc.reason)`)与 `parse_error` 未经清洗即落入 `ApiError.details` 并返回给客户端(`advanced_material_service.py:787`、`advanced_style_set_service.py:1283`)。
|
||||
- **修复建议**:把 `core/generation_errors.py` 的 `_category` / `_is_retryable` / `_safe_details` / `_safe_message` 提成与异常类型无关的公共函数(入参 `error_type` + `status_code` + `details`),让 `provider_failure_attribution` 与新增的 `vision_failure_attribution` 共用;`material_service._vision_provider_error` 改为调用后者,删掉那两行死代码。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] vision 请求体无上限,8 张 20 MB 图可构造 ~213 MB 的单次 JSON 请求
|
||||
|
||||
- **位置**:`engines/vision_provider.py:17-19`、`:294`;调用方 `backend/services/advanced_style_set_service.py:1545-1548,1654-1657,2281-2284`
|
||||
- **问题**:`vision_provider` 只对**响应**设了 `MAX_PROVIDER_JSON_BYTES = 4 MiB`,对**请求体**没有任何限制。多图分析路径用 `image_uris` 一次传最多 `MAX_VISION_IMAGES = 8` 张,每张经 `material_service._storage_image_data_url` 转成 base64 data URI,单张原图上限是 `MAX_UPLOAD_BYTES = 20 MiB`(`backend/services/material_service.py:43`),base64 后约 27 MiB。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/vision_provider.py:17-19
|
||||
MAX_PROVIDER_JSON_BYTES = 4 * 1024 * 1024 # 只约束响应
|
||||
MAX_PROVIDER_ERROR_BYTES = 64 * 1024
|
||||
MAX_VISION_IMAGES = 8
|
||||
```
|
||||
```python
|
||||
# engines/vision_provider.py:294
|
||||
data = json.dumps(payload, ensure_ascii=False).encode("utf-8") # 完整物化,无上限
|
||||
```
|
||||
- **影响**:单次风格集共识分析峰值内存约为 payload dict + json 字符串 + utf-8 bytes ≈ 3 份 213 MB。插件运行在 AstrBot 主进程内,OOM 会拖垮整个 Bot。且几乎所有上游都会以 413 拒收,等于一条注定失败但先把宿主打爆的路径。对比 `engines/image_provider.py:392-401` 的 `_provider_json_limit`——图像链路已经按图片数动态算过上限了,vision 没跟上。
|
||||
- **修复建议**:新增 `MAX_VISION_REQUEST_BYTES`(如 32 MiB),在 `_post_json` 里 `if len(data) > MAX_VISION_REQUEST_BYTES: raise VisionProviderError(..., error_type="invalid_request")`;更好的做法是在 `_storage_image_data_url` 之前按"张数 × 单张预算"约束,超限时先降采样再编码。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 三处 fallback 对所有错误一视同仁地换下一个 provider,包括不该重试的鉴权/配置/内容策略错误
|
||||
|
||||
- **位置**:`engines/image_provider.py:179-198`、`engines/vision_provider.py:150-184`、`backend/services/model_provider_runtime.py:180-189` 与 `:264-271`
|
||||
- **问题**:`core/generation_errors._is_retryable`(`core/generation_errors.py:122-125`)已经把可重试语义定义清楚了,但四个 fallback 循环没有一个使用它。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/image_provider.py:191-192
|
||||
except ImageProviderError as exc:
|
||||
failures.append({"provider_id": provider.provider_id, "error_type": exc.error_type, "status_code": exc.status_code})
|
||||
# 无论 configuration_error / 401 / 400 内容策略拒绝,一律继续下一个 provider
|
||||
```
|
||||
```python
|
||||
# backend/services/model_provider_runtime.py:182-186
|
||||
for completion in callables:
|
||||
try:
|
||||
return completion(request_payload)
|
||||
except Exception as exc: # 连 ValueError/JSONDecodeError 都算"该换路由"
|
||||
failures.append(str(exc)[:500])
|
||||
```
|
||||
- **影响**:一个被内容策略拒绝的提示词(400)会依次打完所有已启用路由——而 `image_provider_for_route` 在 `fallback_enabled` 时会把**全部启用的 image_generation 路由**追加进候选(`model_provider_runtime.py:60-71`)。结果是一次用户请求放大成 N 次必然失败的付费调用,同时 N 倍地推高各家的限流计数。同样地,密钥填错时用户看到的是"所有候选生成服务均调用失败"而不是"鉴权失败",排障方向被彻底带偏。
|
||||
- **修复建议**:让 `_is_retryable` 成为 fallback 的准入条件:
|
||||
```python
|
||||
from core.generation_errors import provider_failure_attribution
|
||||
except ImageProviderError as exc:
|
||||
attribution = provider_failure_attribution(exc)
|
||||
failures.append(attribution)
|
||||
if not attribution["retryable"]:
|
||||
raise # 鉴权/配置/请求错误立即上抛,不消耗其余 provider
|
||||
```
|
||||
`structured_text_callable` / `structured_vision_callable` 需要先给 HTTP 错误分类(见上一条),才能做同样的判断。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `structured_text_callable` 用裸 `json.loads` 解析模型输出,缺 vision 侧已有的容错
|
||||
|
||||
- **位置**:`backend/services/model_provider_runtime.py:244-249`(对比 `engines/vision_provider.py:398-429`)
|
||||
- **问题**:`engines/vision_provider._json_from_text` 实现了一套克制的修复策略——剥离 BOM、从首个 `{` 到末个 `}` 截取(处理 markdown 代码围栏)、去尾逗号,共 4 个候选依次尝试。`structured_text_callable` 走的是同类 OpenAI chat/completions 接口、同样带 `response_format: json_object`,却直接 `json.loads(content)`。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/model_provider_runtime.py:244-249
|
||||
response = json.loads(raw)
|
||||
content = _completion_content(response)
|
||||
parsed = json.loads(content) # 模型多输出一个 ```json 围栏就炸
|
||||
if not isinstance(parsed, dict):
|
||||
raise ValueError("structured completion must return an object")
|
||||
```
|
||||
```python
|
||||
# engines/vision_provider.py:402-411(同一问题的正确解法,已存在)
|
||||
candidates = [text]
|
||||
start, end = text.find("{"), text.rfind("}")
|
||||
if start >= 0 and end > start:
|
||||
extracted = text[start : end + 1]
|
||||
if extracted != text:
|
||||
candidates.append(extracted)
|
||||
candidates.extend(re.sub(r",\s*([}\]])", r"\1", item) for item in list(candidates))
|
||||
```
|
||||
- **影响**:`structured_text_callable` 是提示词扩写/结构化处理的入口。大量 OpenAI 兼容网关(尤其国产模型代理)不真正支持 `response_format: json_object`,会返回带围栏的 JSON——这些模型在 vision 路径能用、在 text 路径必失败,且失败形态是裸 `json.JSONDecodeError` 冒泡,`complete_with_fallback` 把它当作"换路由"信号继续烧下一条路由(与上一条叠加)。
|
||||
- **修复建议**:把 `vision_provider._json_from_text` 提到 `core/`(例如 `core/llm_json.py`),vision、structured_text、structured_vision 三处共用。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 单条聊天消息内的图片数量无上限,直接放大为 N 次下载 + N 次视觉大模型调用
|
||||
|
||||
- **位置**:`adapters/astrbot_media_adapter.py:8-20`、`main.py:1161-1167`
|
||||
- **问题**:`image_references_from_event` 遍历整个消息链、对每个 image 组件收集一个引用,没有任何数量截断;`main.py` 随后对每个引用串行执行完整的"导入 + 识别"流程,每次识别都是一次视觉大模型调用。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:1161-1167
|
||||
references = image_references_from_event(event)
|
||||
if not category.strip() or not references:
|
||||
...
|
||||
results = [await asyncio.to_thread(self.chat_workflow_service.import_material, reference, category.strip(), context) for reference in references]
|
||||
```
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:948-954(每个引用的代价)
|
||||
uri, filename, size_bytes = self.media_importer.import_image(image_reference) # 最多 20MB 下载
|
||||
material = self._data(self.dispatcher(ctx, "POST", "materials/upload", payload={...}))
|
||||
recognized = self._data(self.dispatcher(ctx, "POST", f"materials/{material['material_id']}/recognize", payload={})) # 视觉大模型调用
|
||||
```
|
||||
- **影响**:QQ 合并转发或一条多图消息可轻易携带数十张图。一条命令即触发数十次 20 MB 下载与数十次付费视觉调用,全部在 `asyncio.to_thread` 里串行执行,期间该用户的其它聊天命令排队等待。`ChatCommandGuardService` 的配额校验在 `submit_single_image` 里有(`chat_workflow_service.py:38`),`import_material` 路径上完全没有。
|
||||
- **修复建议**:在 `image_references_from_event` 内部截断(`MAX_CHAT_IMAGE_REFERENCES = 4`,与 `MAX_VISION_IMAGES` 语义对齐),超出部分在回复里明示"仅处理前 N 张";并让 `import_material` 也走 `self.guard.check_generation` / `self.guard.record`,与单图命令一致。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `onebot11_adapter.py` 与 `wechat_adapter.py` 结构性重复约 90%
|
||||
|
||||
- **位置**:`adapters/onebot11_adapter.py:12-98`、`adapters/wechat_adapter.py:12-79`
|
||||
- **问题**:两个文件各定义一个仅字段名不同的消息 dataclass,然后逐字复制 `match_workbench_command`、`workbench_reply`、`handle_message_event`、`quick_profile_reply`、`_optional_text` 五个函数。除了 `platform` 常量、群标识字段名(`group_id` vs `room_id`)、以及回复字典的键(`"message"` vs `"text"`)之外没有任何差异。
|
||||
- **代码**:
|
||||
```python
|
||||
# adapters/onebot11_adapter.py:53-71
|
||||
def handle_message_event(event, *, api_base=API_BASE):
|
||||
message = normalize_message_event(event)
|
||||
command = parse_chat_command(message.text)
|
||||
if command is None: return None
|
||||
if command.action == "quick_profile":
|
||||
return {"platform": "onebot11", "action": command.action, "payload": command.payload,
|
||||
"source": message.to_dict(), "reply": quick_profile_reply(command.payload["questionnaire"]["name"])}
|
||||
return {"platform": "onebot11", "action": "open_workbench", "source": message.to_dict(), "reply": workbench_reply(api_base)}
|
||||
|
||||
# adapters/wechat_adapter.py:49-67 —— 逐行相同,仅 "onebot11" -> "wechat"
|
||||
```
|
||||
- **影响**:`chat_commands.py` 每次新增命令,都必须记得同步改两个文件;两者已经开始漂移(onebot11 的 `workbench_reply` 用 `"message"` 键、wechat 用 `"text"` 键,且都额外带一个重复的 `"url"`)。新增第三个平台(Telegram/Discord,`_chat_entrypoint` 已为它们预留分支)会变成第三份拷贝。
|
||||
- **修复建议**:抽 `adapters/chat_platform_adapter.py`,定义 `PlatformSpec(platform, group_field_names, user_field_names, reply_text_key)` 与一个通用 `handle_message_event(event, spec, *, api_base)`;两个现有模块退化为 spec 常量加薄封装,保持导出符号不变以免破坏 `adapters/__init__.py`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 聊天身份未按平台命名空间隔离,跨平台同 ID 可互相访问档案
|
||||
|
||||
- **位置**:`backend/services/chat_workflow_service.py:1157-1164`(对比 `main.py:2329-2344`)
|
||||
- **问题**:`RequestContext.from_astrbot(user_id=chat.user_id)` 直接用平台原始用户 ID;`ProfileService` 的归属判定基于 `ctx.actor_id`(`backend/services/profile_service.py:36,92,161`),即 `user_id or username`。`source` 字段虽然带了平台(`f"astrbot_chat:{chat.platform}"`),但它不参与任何归属判定。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:1157-1164
|
||||
return RequestContext.from_astrbot(
|
||||
username=chat.user_id or "chat-user",
|
||||
user_id=chat.user_id or "chat-user", # 无平台前缀
|
||||
permissions={"can_write", "can_retry_tasks", "can_manage_materials"},
|
||||
source=f"astrbot_chat:{chat.platform}", # 平台信息只进了这里,不参与鉴权
|
||||
...
|
||||
```
|
||||
```python
|
||||
# backend/services/profile_service.py:160-163
|
||||
def _require_owner(self, profile: CharacterProfile, ctx: RequestContext) -> None:
|
||||
if ctx.actor_id and ctx.actor_id == profile.owner_user_id:
|
||||
return
|
||||
```
|
||||
- **影响**:QQ 号 `12345` 与 Telegram 用户 ID `12345`(两者都是纯数字)会落进同一个 `owner_user_id`,互相看到并操作对方的全部角色档案、工作流、图片。WebUI 侧的 `actor_id` 是 AstrBot 登录名(`main.py:2325-2332`),与聊天 ID 共用同一命名空间,一个用户名恰好是纯数字的 WebUI 账号同样会与聊天用户撞车。ID 越界不需要任何攻击技巧,是配置巧合即触发。
|
||||
- **修复建议**:`_request_context` 里改用带平台前缀的复合标识:`user_id=f"{chat.platform or 'astrbot'}:{chat.user_id}"`,WebUI 侧对应用 `webui:` 前缀。这会改变已有数据的 `owner_user_id`,需要配套一次性迁移脚本(把现存无前缀记录按 `source` 字段回填),建议在迁移里对无法判定来源的记录保守地归入 `webui:`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 聊天卡片 PNG 缓存目录无淘汰机制,用户可任意撑爆磁盘
|
||||
|
||||
- **位置**:`adapters/astrbot_card_renderer.py:55-78`,调用方 `main.py:524-531`
|
||||
- **问题**:`_render_card` 以内容 sha256 前 16 位为文件名缓存到 `data/chat_cards/`,命中即复用。缓存永不过期、永不清理,而 key 的输入完全由用户提供。
|
||||
- **代码**:
|
||||
```python
|
||||
# adapters/astrbot_card_renderer.py:58-61
|
||||
CARD_DIR.mkdir(parents=True, exist_ok=True)
|
||||
target = CARD_DIR / f"{hashlib.sha256(key.encode('utf-8')).hexdigest()[:16]}.png"
|
||||
if target.exists():
|
||||
return target
|
||||
```
|
||||
```python
|
||||
# main.py:526-529 —— key 的四个组成部分全部来自用户输入的角色描述
|
||||
lambda: render_profile_card(
|
||||
name=str(preview.get("name") or ""), base=str(preview.get("base_prompt") or ""),
|
||||
appearance=str(preview.get("appearance_prompt") or ""), style=str(preview.get("style_prompt") or ""),
|
||||
),
|
||||
```
|
||||
- **影响**:每次 `/yp 快速角色 <任意不同描述>` 都产生一个新 sha256 → 一张新的 1000×560 PNG(约 50–200 KB)。反复调用可无限增长;且 `height = 300 + max(len(lines), 1) * 66`(`:63`)在 `render_status_card` 的 `details` 变长时会线性放大画布,进一步放大单文件体积。这是插件进程内的磁盘写入,撑爆的是 AstrBot 宿主的数据盘。
|
||||
- **修复建议**:给 `CARD_DIR` 加简单的 LRU 上限——渲染前统计目录文件数,超过阈值(如 500)时按 `st_mtime` 删除最旧的一批;或改为渲染到内存 `BytesIO` 直接投递,完全不落盘(AstrBot 的图片回复支持字节流)。另外把 `lines` 的长度与条数做截断,避免画布尺寸被输入放大。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `dispatch_extension_request` 解析出了路由声明的 permission 却从不校验
|
||||
|
||||
- **位置**:`adapters/astrbot_adapter.py:171-187`
|
||||
- **问题**:`RouteMatch` 携带 `permission` 字段(来自 `backend/route_registry.ROUTES`,实测分布为 read×62 / write×37 / materials×36 / config×22 / retry×8 / public_token×1),但 dispatch 时只用 `handler` 和 `path_params`,`permission` 从未参与判断。全部权限校验依赖每个 handler 自己记得调 `core.security.require_*`。
|
||||
- **代码**:
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:179-187
|
||||
match = resolve_route(method, path)
|
||||
if match is None:
|
||||
return error_response(...)
|
||||
return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
|
||||
# match.permission 在此之后再无引用
|
||||
```
|
||||
- **影响**:路由清单里声明的权限是纯文档,不构成任何强制力。目前抽查的 10 个"未直接调用 require_*"的 handler 都通过内层委托做了校验(如 `profile_routes.archive_profile` → `delete_profile`、`image_routes.review_moderated_image` 内联 `ctx.has_permission`),所以当下没有实际漏洞——但这是纯靠约定维系的状态,任何新增 handler 漏掉一行 `require_permission` 就是静默的越权入口,且没有任何测试会发现。
|
||||
- **修复建议**:在 dispatch 层做统一的前置校验,把 `RouteSpec.permission` 映射到 `core.security` 的检查函数(`read`→`require_authenticated`、`write`→`require_write`、`config`→`require_permission(ctx, "can_manage_config")`、`public_token`→跳过),handler 内的细粒度检查保留为纵深防御。这样清单即契约,新增路由无法绕过。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `review_flow.review_node` 内联复制了 `_candidate_warnings` 的告警逻辑
|
||||
|
||||
- **位置**:`engines/review_flow.py:141-159` 与 `engines/review_flow.py:362-380`
|
||||
- **问题**:`MODEL_ROUTE_MISMATCH` 与 `PROMPT_MISMATCH` 两条告警的判定条件、消息文案、附加字段在同一文件里写了两遍,一遍针对 `selected_image`、一遍针对候选图。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/review_flow.py:150-159
|
||||
if selected_image and node.prompt and selected_image.positive_prompt:
|
||||
node_prompt = _normalize_prompt(node.prompt)
|
||||
image_prompt = _normalize_prompt(selected_image.positive_prompt)
|
||||
if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt:
|
||||
warnings.append({"code": "PROMPT_MISMATCH", "message": "selected image prompt differs from node prompt"})
|
||||
|
||||
# engines/review_flow.py:375-379 —— 判定与文案逐字相同,仅变量名不同
|
||||
if node.prompt and image.positive_prompt:
|
||||
node_prompt = _normalize_prompt(node.prompt)
|
||||
image_prompt = _normalize_prompt(image.positive_prompt)
|
||||
if node_prompt and image_prompt and node_prompt not in image_prompt and image_prompt not in node_prompt:
|
||||
warnings.append({"code": "PROMPT_MISMATCH", "message": "candidate prompt differs from node prompt"})
|
||||
```
|
||||
- **影响**:`review_node` 返回的 `warnings` 与其内部 `stage_review.candidates[*].warnings` 存在漂移风险——一致性规则改了一处忘了另一处,同一张图在两个字段里会给出矛盾结论,而 `_candidate_score`(`:392`)直接用 `len(warnings)` 打分,漂移会体现在分数上。
|
||||
- **修复建议**:`review_node` 里对 `selected_image` 直接复用 `_candidate_warnings(node, selected_image)`,删除 141-159 的内联副本(注意保留 `MODEL_ROUTE_MISMATCH` 在 node 级别携带的 `node_model_route`/`image_model_route` 字段,`_candidate_warnings` 已经带了)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `_match_endpoint` 未对路由字面量做 `re.escape`
|
||||
|
||||
- **位置**:`adapters/astrbot_adapter.py:224-230`
|
||||
- **问题**:把路由模板直接拼进正则,只替换了 `{param}` 占位符,字面量部分未转义。
|
||||
- **代码**:
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:225-227
|
||||
param_names = re.findall(r"\{([^{}]+)\}", pattern)
|
||||
regex = "^" + re.sub(r"\{([^{}]+)\}", r"([^/]+)", pattern) + "$"
|
||||
match = re.match(regex, endpoint)
|
||||
```
|
||||
- **影响**:实测当前 `ROUTES` 里没有任何 endpoint 含正则元字符(已用脚本枚举验证),所以现在是安全的。但这是一个只靠"恰好没人写带点号的路由"维持的隐性约束——将来出现 `files/{name}.json` 这类端点时,`.` 会变成任意字符匹配,产生静默的路由串台。
|
||||
- **修复建议**:先 `re.escape(pattern)`,再把被转义后的 `\{name\}` 换回捕获组;或改用逐段比较(split `/` 后按段匹配),既更快也不需要正则。
|
||||
|
||||
---
|
||||
|
||||
## 关于 flow 文件合并可行性的专项结论
|
||||
|
||||
| 文件 | 行数 | 性质 | 与其它 flow 的实质重复 |
|
||||
|---|---|---|---|
|
||||
| `engines/single_flow.py` | 455 | 真实生成引擎(provider 调用、字节校验、URI 布局) | 无 |
|
||||
| `engines/review_flow.py` | 451 | 真实审查引擎(策略校验、评分、阶段审查结果) | 无(内部有自重复,见上) |
|
||||
| `engines/character_flow.py` | 145 | 声明式节点模板目录 + 遗留 node_key 别名映射 | 仅 `gradual_node_templates()` 约 15 行样板 |
|
||||
| `engines/fast_character_flow.py` | 50 | 声明式节点模板目录 | 仅 `fast_character_node_templates()` 约 11 行样板 |
|
||||
| `engines/quick_profile_flow.py` | 32 | 声明式节点模板目录(内联字面量) | 无函数,纯字面量 |
|
||||
|
||||
三个模板目录的唯一共性是这段构造器样板:
|
||||
|
||||
```python
|
||||
# engines/fast_character_flow.py:40-50
|
||||
return [
|
||||
{**step, "node_type": "generation", "status": "draft", "branch_name": "main",
|
||||
"metadata": {"template": "character_fast_v2", "quick_character_target": step["node_key"]}}
|
||||
for step in FAST_CHARACTER_STEPS
|
||||
]
|
||||
# engines/character_flow.py:131-145 —— 同形,但要额外剥离 stage_code、支持 per-step node_type 覆盖
|
||||
```
|
||||
|
||||
**建议不合并。** 三者的 metadata 契约各不相同(`character_gradual` 要 `stage_code` + `canonical_node_key` 且支持 per-step `node_type` 覆盖;`character_fast` 要 `quick_character_target`;`quick_profile` 用的是 `profile_draft`/`profile_preview` 这类完全不同的 node_type),抽公共构造器需要引入配置参数把这些差异重新表达出来,代码量与理解成本都不会下降,反而把三种工作流的演进耦合在一起。这几个文件当前的形态——声明数据与业务逻辑分离、每种工作流一个独立目录——是合适的。
|
||||
|
||||
真正值得做的合并是本报告里的 **onebot11/wechat 适配器(约 90% 重复)** 与 **`review_flow` 的内联告警副本**,以及把 `_json_from_text` / 错误分类 / 大小预检这三段"图像链路已做对、其它链路缺失"的逻辑提取到 `core/` 供全部 provider 共用。
|
||||
475
审计/findings/A7-路由与插件入口.md
普通文件
475
审计/findings/A7-路由与插件入口.md
普通文件
|
|
@ -0,0 +1,475 @@
|
|||
# A7 · main.py 插件入口 + backend/routes 路由层 + 权限矩阵
|
||||
|
||||
> 审计范围(实际逐行读过的文件):
|
||||
> `main.py`、`backend/route_registry.py`、`adapters/astrbot_adapter.py`、`core/identity.py`、`core/security.py`、`core/media_proxy.py`、
|
||||
> `backend/routes/`(`common.py` `params.py` `profile_routes.py` `workflow_routes.py` `node_routes.py` `round_routes.py` `job_routes.py`
|
||||
> `image_routes.py` `media_routes.py` `log_routes.py` `history_routes.py` `settings_routes.py` `data_backup_routes.py` `wardrobe_routes.py`
|
||||
> `integration_routes.py` `advanced_material_routes.py` `prompt_routes.py` `event_routes.py`,其余 17 个文件通过脚本提取 def+guard 全量比对)、
|
||||
> `backend/dto/common.py`、`backend/dto/job_dto.py`、`backend/dto/workflow_round_dto.py`、
|
||||
> `backend/services/profile_service.py`、`workflow_service.py`、`workflow_round_service.py`、`resource_access_service.py`、`image_service.py`、
|
||||
> `queue_service.py`、`media_service.py`、`generation_service.py`(权限相关片段)、`prompt_governance_service.py`、`wardrobe_service.py`、
|
||||
> `profile_document_import_service.py`、`model_provider_bootstrap.py`、`database/db_helper.py`(Database 构造)、
|
||||
> `frontend/shared/api/client.ts`、`frontend/shared/api/endpoints.ts`
|
||||
>
|
||||
> 已按要求忽略 `.tmp/`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`。
|
||||
|
||||
## 摘要
|
||||
|
||||
`PERMISSION_MATRIX` 只是一张**声明式清单**——`dispatch_extension_request()` 从头到尾没有读过 `RouteMatch.permission`,真正的鉴权全靠每个 handler 里手写的 `require_*(ctx)`。我用脚本把 169 条 `RouteSpec` 与 handler 内实际调用的 `require_*` 逐条比对,**声明与实现在权限"类别"上基本对得上**(这点做得不错),但矩阵本身在运行时被上游架空:`main.py` 的桥接层给任何登录用户无条件发放 `can_write / can_manage_config / can_manage_materials / can_retry_tasks` 全部四项,于是六级权限矩阵在生产路径上塌缩成"登录 / 未登录"两级。
|
||||
|
||||
更严重的是**归属校验的覆盖不完整**:profile 与 round 两条链路正确接入了 owner 校验(`ProfileService._require_owner` / `ResourceAccessService.require_node`),而 workflow / node / image / job / history 五条链路的 service 方法**根本不接收 ctx**,任何登录用户凭 ID 即可读写他人的工作流、节点、图片与任务队列(`GET jobs` 甚至直接返回他人完整的生成请求体)。
|
||||
|
||||
此外还有三个结构性问题:客户端可自带 `content_permissions` / `entrypoint` 绕过成人内容路由闸门;所有 service 构造都发生在 `require_*` 之前(未授权请求即可触发重型 provider 初始化 + DB 写入,且构造期异常逃出 `handle_request` 直接 500);157 个 handler 是完全同构的三行样板 + 22 个各自为政的 `_create_*_service()` 工厂。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P0-致命] 桥接层给所有登录用户发放全部权限,PERMISSION_MATRIX 在运行时被架空
|
||||
|
||||
- **位置**:`main.py:104`、`main.py:2337`
|
||||
- **问题**:`_request_context_from_astrbot_request()` 只要能取到 username/user_id,就把 `BRIDGE_PERMISSIONS`(四项全部)塞进 `RequestContext.permissions`。而 AstrBot Plugin Page 桥接(`register_bridge_api` → `_make_bridge_handler`)是前端真正走的通路。结果 `config`(改配置、导入配置、回滚快照、恢复备份、轮换 private-companion token)、`materials`、`retry` 三档权限与 `read` 完全等价。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:104
|
||||
BRIDGE_PERMISSIONS = frozenset(
|
||||
{"can_write", "can_manage_config", "can_manage_materials", "can_retry_tasks"}
|
||||
)
|
||||
|
||||
# main.py:2333-2344
|
||||
# AstrBot authenticates extension routes before invoking the plugin, but
|
||||
# PluginRequest currently exposes only the authenticated username. Grant
|
||||
# the capabilities that exist today explicitly instead of a wildcard so a
|
||||
# future permission cannot become enabled accidentally.
|
||||
permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||||
return RequestContext.from_astrbot(
|
||||
username=username,
|
||||
user_id=user_id,
|
||||
client_ip=_client_ip(request),
|
||||
source="astrbot_plugin_page",
|
||||
permissions=permissions,
|
||||
)
|
||||
```
|
||||
- **影响**:任意一个 AstrBot WebUI 普通登录用户可以:`POST settings/save` 改数据库后端/模型密钥环境变量名、`POST settings/rollback`、`POST backups/{id}/restore` 覆盖全量数据、`POST integrations/private-companion/token/rotate` 轮换外部集成令牌、`POST jobs/failed/clear` 清空他人失败队列。`route_registry.py` 里 `config`(22 条)、`materials`(38 条)、`retry`(8 条)三档共 68 条路由的权限边界形同虚设。同时因为没人拥有 `can_manage_all_profiles`,`ResourceAccessService._can_access` 的管理员分支是死代码。
|
||||
- **修复建议**:
|
||||
1. 从 AstrBot 请求上下文里真正解析角色/权限(`_attr(request, "roles")` / `request.user.permissions` 等,按 AstrBot 版本探测),映射成 ImageStudio 的四项能力;探测不到时**降级为最小集** `frozenset()`(只读),而不是最大集。
|
||||
2. 在 `config.yaml` 增加显式的管理员白名单(`security.admin_usernames` / `security.material_managers`),`_request_context_from_astrbot_request` 据此授予 `can_manage_config` / `can_manage_materials` / `can_manage_all_profiles`。
|
||||
3. 把 `permission` 真正接进分发器(见下一条),让矩阵成为强制点而非注释。
|
||||
|
||||
---
|
||||
|
||||
### [P0-致命] `dispatch_extension_request` 从不检查 `RouteMatch.permission`,矩阵与实现只靠人工同步
|
||||
|
||||
- **位置**:`adapters/astrbot_adapter.py:171-187`
|
||||
- **问题**:分发器解析出 `match.permission` 后直接丢弃,立刻 `match.handler(...)`。鉴权 100% 依赖每个 handler 内部手写 `require_*`。仓库里没有任何测试或启动断言校验"`RouteSpec.permission` == handler 实际 guard",`runtime_health()` 只校验路由唯一性与权限名已知,不校验一致性。
|
||||
- **代码**:
|
||||
```python
|
||||
def dispatch_extension_request(ctx, method, path, *, query=None, payload=None) -> dict[str, Any]:
|
||||
match = resolve_route(method, path)
|
||||
if match is None:
|
||||
return error_response(...)
|
||||
return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
|
||||
# ↑ match.permission 从未被使用
|
||||
```
|
||||
对照 `route_registry.py:365-377`:
|
||||
```python
|
||||
def assert_unique_routes() -> None: ... # 只查重复
|
||||
def assert_known_permissions() -> None: ... # 只查权限名拼写
|
||||
```
|
||||
- **影响**:新增一条路由时只要忘写 `require_write(ctx)`,就是一个静默的未授权写接口,CI 与 `runtime_health()` 都不会报警。当前 169 条路由靠人工维持一致(我逐条比对确认目前没有漏挂),但这是**一次疏忽即破防**的结构。同时 `_register_route()` 虽然把 `permission=` 传给 AstrBot,但真正生效的桥接注册 `_bridge_registration_routes()` 是 `<path:endpoint>` 通配符,**不携带任何权限元数据**(`main.py:1753-1758`)。
|
||||
- **修复建议**:在分发器里做集中式强制:
|
||||
```python
|
||||
from backend.route_registry import permission_requirement
|
||||
from backend.dto.common import ErrorCode, error_response
|
||||
|
||||
def dispatch_extension_request(ctx, method, path, *, query=None, payload=None):
|
||||
match = resolve_route(method, path)
|
||||
if match is None: ...
|
||||
rule = permission_requirement(match.permission)
|
||||
if rule["auth_required"] and not ctx.is_authenticated:
|
||||
return error_response(error_code=ErrorCode.UNAUTHORIZED, message="...", request_id=ctx.request_id)
|
||||
required = rule.get("required_permissions") or ([rule["required_permission"]] if rule["required_permission"] else [])
|
||||
missing = [p for p in required if not ctx.has_permission(p)]
|
||||
if missing:
|
||||
return error_response(error_code=ErrorCode.FORBIDDEN, message="...", details={"permissions": missing}, request_id=ctx.request_id)
|
||||
return match.handler(...)
|
||||
```
|
||||
handler 内的 `require_*` 保留为纵深防御,并补一个测试:遍历 `ROUTES`,用 AST 断言每个 handler 体内存在与声明等价的 guard。
|
||||
|
||||
---
|
||||
|
||||
### [P0-致命] workflow / node / image / job / history 五条链路无归属校验(IDOR)
|
||||
|
||||
- **位置**:`backend/routes/workflow_routes.py:21-32`、`50-61`、`backend/routes/node_routes.py:81-92`、`backend/routes/job_routes.py:19-41`、`backend/routes/image_routes.py:22-52`、`backend/routes/history_routes.py:36-50`
|
||||
- **问题**:profile 路由(`ProfileService.get_profile(profile_id, ctx)` → `_require_owner`)和 round 路由(`WorkflowRoundService._node_and_workflow(node_id, ctx)` → `ResourceAccessService.require_node`)都做了归属校验;但 workflow / node / image / job / history 的 service 方法**签名里根本没有 ctx**,路由层也没有额外校验。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/workflow_routes.py:50-61 —— 只校验"已登录"
|
||||
def get_workflow(ctx, workflow_id, service=None) -> dict:
|
||||
workflow_service = service or _create_workflow_service()
|
||||
def action() -> dict[str, Any]:
|
||||
require_authenticated(ctx)
|
||||
return workflow_service.get_workflow(workflow_id).to_dict() # ← 无 ctx
|
||||
return handle_request(ctx, action)
|
||||
|
||||
# backend/services/workflow_service.py:146-150
|
||||
def list_workflows(self, profile_id: str) -> list[ProfileWorkflow]: # ← 无 ctx
|
||||
self._ensure_profile_exists(profile_id) # 只判存在,不判归属
|
||||
return self.workflow_repository.list_workflows(profile_id)
|
||||
|
||||
def get_workflow(self, workflow_id: str) -> WorkflowDetail: # ← 无 ctx
|
||||
workflow = self.workflow_repository.get_workflow(workflow_id)
|
||||
|
||||
# backend/services/workflow_service.py:650-654
|
||||
def get_node(self, node_id: str) -> WorkflowNode: # ← 无 ctx
|
||||
|
||||
# backend/routes/job_routes.py:29-35 —— 列表参数里没有任何 owner 维度
|
||||
result = queue_service.list_jobs(
|
||||
status=..., workflow_id=..., profile_id=..., page=..., page_size=...
|
||||
).to_dict()
|
||||
|
||||
# backend/routes/image_routes.py:34-40 —— 同样没有 owner 维度
|
||||
result = image_service.list_images(profile_id=..., workflow_id=..., ...)
|
||||
```
|
||||
对照做对了的那条链路:
|
||||
```python
|
||||
# backend/services/workflow_round_service.py:1108-1114
|
||||
node = (
|
||||
self.resource_access_service.require_node(node_id, ctx)
|
||||
if ctx is not None
|
||||
else self.workflow_repository.get_node(node_id)
|
||||
)
|
||||
```
|
||||
- **影响**:任意登录用户可枚举/读取/**修改**他人资源:
|
||||
- `GET profiles/{他人profile_id}/workflows`、`GET workflows/{id}`、`PUT workflows/{id}`、`POST workflows/{id}/start|cancel|archive|execute-character`(execute-character 直接花对方的模型额度出图);
|
||||
- `POST profiles/{他人profile_id}/workflows` 在他人档案下建工作流(`create_workflow` 只调 `_ensure_profile_exists`);
|
||||
- `GET nodes/{id}`、`PUT nodes/{id}`、`POST nodes/{id}/generate`;
|
||||
- `GET jobs`(无任何过滤,`GenerationTask.to_dict()` 含 `request` 全量生成请求,即他人的完整提示词、参考图 URI、模型路由,见 `backend/dto/job_dto.py:38`);
|
||||
- `GET images`(无 owner 过滤,仅按 `metadata.quarantined` 过滤受限图)。
|
||||
|
||||
行为还自相矛盾:`GET nodes/{id}` 能读到他人节点,而 `GET nodes/{id}/rounds` 会正确 404——同一个节点两种答案。
|
||||
- **修复建议**:把已存在的 `ResourceAccessService` 推广到这五条链路,而不是每处重造:
|
||||
1. `WorkflowService.list_workflows/get_workflow/get_node/list_nodes` 增加 `ctx: RequestContext | None = None`,非 None 时走 `ResourceAccessService.require_workflow/require_node`;
|
||||
2. `QueueService.list_jobs` / `ImageService.list_images` 增加 `owner_user_id` 过滤参数,路由层传 `ctx.actor_id`(拥有 `can_manage_all_profiles` 时传 `None`);
|
||||
3. `HistoryService.list_workflow_history/save_workflow_snapshot` 前置 `require_workflow(workflow_id, ctx)`;
|
||||
4. 补一个"越权矩阵"测试:用户 A 建资源,用户 B 对 169 条路由逐条请求,断言全部 404/403。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 客户端自带 `content_permissions` / `entrypoint`,可绕过成人内容路由闸门
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:2366-2375`、`2352-2353`、`1497-1504`;入口 `backend/routes/node_routes.py:132-146`
|
||||
- **问题**:`POST nodes/{node_id}/generate` 的 payload 原样透传给 `GenerationService.generate_node`,而路由裁决所依赖的"用户是否被允许成人内容"直接从**请求体**里取,从未与 `ctx` 校验。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/generation_service.py:2366-2375
|
||||
def _permission_context(payload: dict[str, Any]) -> dict[str, Any]:
|
||||
configured = payload.get("content_permissions") if isinstance(payload.get("content_permissions"), dict) else {}
|
||||
result = {
|
||||
**configured,
|
||||
"adult_user_allowed": bool(configured.get("adult_user_allowed", payload.get("adult_user_allowed", False))),
|
||||
"quota_allowed": bool(configured.get("quota_allowed", payload.get("quota_allowed", True))),
|
||||
}
|
||||
...
|
||||
|
||||
# backend/services/generation_service.py:2352-2353
|
||||
def _entrypoint(payload: dict[str, Any]) -> str:
|
||||
value = _optional_text(payload.get("entrypoint") or payload.get("platform") or payload.get("source")) or "web"
|
||||
|
||||
# backend/services/prompt_governance_service.py:262-267 —— 消费点
|
||||
entry_allowed = bool((self.config.get("entrypoints") or {}).get(entrypoint, False))
|
||||
user_allowed = bool(permissions.get("adult_user_allowed", False))
|
||||
group_allowed = bool(permissions.get("adult_group_allowed", group_id is None))
|
||||
quota_allowed = bool(permissions.get("quota_allowed", True))
|
||||
if not all((enabled, entry_allowed, user_allowed, group_allowed, quota_allowed)):
|
||||
return self._decision(..., "adult_route_permission_denied", ...)
|
||||
```
|
||||
- **影响**:只要服务端 `prompt_governance.routing.adult_auto_route_enabled` 为 true,任意登录用户 POST
|
||||
`{"content_permissions": {"adult_user_allowed": true, "adult_group_allowed": true, "quota_allowed": true}, "entrypoint": "<配置里放行的任一入口>"}`
|
||||
即可让 `adult_allowed` 级别的提示词自动路由到 nsfw_route,同时 `quota_allowed: true` 还能绕过配额判定。聊天侧是对的(`chat_workflow_service.py:70/686/761` 由服务端 `_content_permissions(config, chat)` 生成),唯独 Web 路由这条缺失。
|
||||
- **修复建议**:在路由层剥离客户端提供的这两个字段,由服务端重建:
|
||||
```python
|
||||
# node_routes.generate_node / round_routes 内
|
||||
sanitized = {k: v for k, v in request_payload.items()
|
||||
if k not in {"content_permissions", "adult_user_allowed", "adult_group_allowed",
|
||||
"quota_allowed", "entrypoint", "platform", "source"}}
|
||||
sanitized["entrypoint"] = "web"
|
||||
sanitized["content_permissions"] = build_content_permissions(load_config_payload(), ctx)
|
||||
```
|
||||
`build_content_permissions` 复用 `chat_workflow_service._content_permissions` 的逻辑,按 `ctx.actor_id` 查配置白名单。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 所有 service 在 `require_*` 之前构造:未授权即可触发重型初始化 + DB 写入,且构造期异常逃出 `handle_request`
|
||||
|
||||
- **位置**:`backend/routes/node_routes.py:139-140`、`backend/routes/round_routes.py:28`、`137-162`、`backend/routes/node_routes.py:315-390`、`backend/routes/common.py:12-16`
|
||||
- **问题**:每个 handler 的固定写法是"先在函数体里造 service,再把 `require_*` 放进闭包 `action`"。于是**鉴权发生在最贵的操作之后**。`_create_generation_service()` 会:读 `load_config_payload()`、建 `Database`、调 `sync_generation_provider_from_config()`(**向数据库 upsert provider/route 行**)、构造 provider runtime 与多个 governance service。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/node_routes.py:132-146
|
||||
def generate_node(ctx, node_id, payload=None, service=None, generation_service=None) -> dict:
|
||||
workflow_service = service or _create_workflow_service()
|
||||
resolved_generation_service = generation_service or (None if service else _create_generation_service()) # ← 鉴权之前
|
||||
request_payload = payload or {}
|
||||
|
||||
def action() -> dict[str, Any]:
|
||||
require_write(ctx) # ← 鉴权在这里,已经太晚
|
||||
|
||||
# backend/routes/round_routes.py:21-33 —— 一个只读接口也走全量 provider 初始化
|
||||
def list_node_rounds(ctx, node_id, query=None, service=None, media_service=None) -> dict:
|
||||
round_service = service or _create_round_service() # → create_generation_service() → sync_..._from_config()
|
||||
...
|
||||
def action(): require_authenticated(ctx)
|
||||
|
||||
# backend/routes/node_routes.py:327-328
|
||||
config_payload = load_config_payload()
|
||||
sync_generation_provider_from_config(model_provider_service, config_payload) # 写库
|
||||
```
|
||||
而 `handle_request` 的 try 只包住 `callback`:
|
||||
```python
|
||||
# backend/routes/common.py:12-16
|
||||
def handle_request(ctx, callback):
|
||||
try:
|
||||
return success_response(callback(), request_id=ctx.request_id)
|
||||
except Exception as exc:
|
||||
return response_from_exception(exc, request_id=ctx.request_id)
|
||||
```
|
||||
- **影响**:
|
||||
1. **未授权资源消耗**:未登录/无权限用户狂刷 `GET nodes/x/rounds` 或 `POST nodes/x/generate`,每次请求都触发一轮配置解析 + provider 表写入,SQLite 写锁争用(`db_helper.py:166` timeout=30s)会拖垮整个插件;
|
||||
2. **500 泄漏**:service 构造发生在 try 之外,配置损坏/数据库锁死/provider 参数非法时异常直接穿透 `dispatch_extension_request`(该函数也无 try)→ `dispatch_bridge_request` → AstrBot Quart,返回带 traceback 的 500,而不是规范的 `{"ok": false, ...}`;
|
||||
3. 只读接口产生写副作用,违反 HTTP 语义。
|
||||
- **修复建议**:
|
||||
1. 把 service 构造挪进 `action` 闭包(最小改动,一行位置调整 × 157 处,可脚本化);
|
||||
2. 或按下面 P2「样板代码」条目引入 `@route(permission=...)` 装饰器,由装饰器统一"先鉴权 → 再懒构造 service → 再统一异常包装";
|
||||
3. `sync_generation_provider_from_config` 从请求路径移出,改为启动时执行一次 + 配置变更事件触发(`initialize_runtime_database` 已经调过一次);
|
||||
4. `dispatch_extension_request` 外层加兜底 try,任何逃逸异常也转成 `UNKNOWN_ERROR` 响应。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `POST profiles/{profile_id}/archive` 实际执行的是删除
|
||||
|
||||
- **位置**:`backend/routes/profile_routes.py:109-114`,注册于 `backend/route_registry.py:69`
|
||||
- **问题**:`archive_profile` 直接把调用转给 `delete_profile`,语义与端点名、与前端 `profileArchive` 按钮的用户预期完全不符。
|
||||
- **代码**:
|
||||
```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) # ← "归档" == "删除"
|
||||
```
|
||||
对照 workflow 侧是真归档(`workflow_routes.py:106-111` → `_set_workflow_status(..., "archived", ...)`)。
|
||||
- **影响**:前端 `profileArchive`(`frontend/shared/api/endpoints.ts:11`)标注为"归档",用户点击后档案被 `repository.soft_delete()` 置为 `status="deleted"`,随后 `get_profile` 会对 `status == "deleted"` 抛 404 —— 该档案及其下所有工作流从 UI 彻底消失且无归档列表可恢复。归档与删除是两种不同的用户意图,被合并成一种破坏性操作。
|
||||
- **修复建议**:
|
||||
```python
|
||||
def archive_profile(ctx, profile_id, service=None) -> dict:
|
||||
profile_service = service or _create_profile_service()
|
||||
def action() -> dict:
|
||||
require_write(ctx)
|
||||
return profile_service.update_profile(profile_id, {"status": "archived"}, ctx).to_dict()
|
||||
return handle_request(ctx, action)
|
||||
```
|
||||
并确认 `ProfileService.get_profile` / `ProfileRepository.list` 对 `archived` 状态可查(`list_profiles` 已支持 `status` 参数)。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 所有错误一律 HTTP 200,UNAUTHORIZED/FORBIDDEN/NOT_FOUND 无法被 HTTP 层识别
|
||||
|
||||
- **位置**:`backend/dto/common.py:58-72`、`main.py:2439-2452`
|
||||
- **问题**:`error_response()` 返回普通 dict,`_to_bridge_response()` 也只是把它包成 `{"status": "error", ...}`,全程没有任何 HTTP 状态码映射。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:2439-2452
|
||||
def _to_bridge_response(response: dict[str, Any]) -> dict[str, Any]:
|
||||
if response.get("ok"):
|
||||
return {"status": "ok", "message": "", "data": response.get("data"), "request_id": response.get("request_id")}
|
||||
return {"status": "error", "message": str(response.get("message") or "request failed"),
|
||||
"data": response, "request_id": response.get("request_id")}
|
||||
# ← 无论 UNAUTHORIZED / FORBIDDEN / RESOURCE_NOT_FOUND / UNKNOWN_ERROR,AstrBot 都按 200 返回
|
||||
```
|
||||
- **影响**:AstrBot 侧的访问日志、反向代理限流、监控告警、浏览器 devtools 全部看到 200,权限拒绝与服务器内部错误在 HTTP 层不可观测;前端 `client.ts:96` 里的 `!response.ok` 分支在桥接模式下永远不触发,只能靠 body 判定。安全审计("谁被拒绝了多少次")无法从访问日志得出。
|
||||
- **修复建议**:给 `ErrorCode` 建立状态码映射表并在 `_to_bridge_response` / `_to_media_http_response` 层构造带状态码的响应:
|
||||
```python
|
||||
ERROR_STATUS = {ErrorCode.UNAUTHORIZED: 401, ErrorCode.FORBIDDEN: 403,
|
||||
ErrorCode.RESOURCE_NOT_FOUND: 404, ErrorCode.VALIDATION_FAILED: 422,
|
||||
ErrorCode.UPLOAD_TOO_LARGE: 413, ErrorCode.UNKNOWN_ERROR: 500}
|
||||
```
|
||||
桥接返回 `Response(json.dumps(body), status=ERROR_STATUS.get(code, 200), content_type="application/json")`;前端 `unwrapApiResponse` 已能同时处理两种包装,改动是向后兼容的。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `handle_request` 吞掉全部异常且不写日志,未知错误无从定位
|
||||
|
||||
- **位置**:`backend/routes/common.py:12-16`、`backend/dto/common.py:75-83`
|
||||
- **问题**:任何非 `ApiError` 异常都被转成 `UNKNOWN_ERROR / "服务器内部错误"`,`details` 只留一个异常类名,**既不 logging 也不保留 traceback**。157 个 handler 全部走这一条路径。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/dto/common.py:75-83
|
||||
def response_from_exception(exc: Exception, request_id: str | None = None) -> dict[str, Any]:
|
||||
if isinstance(exc, ApiError):
|
||||
return exc.to_response(request_id=request_id)
|
||||
return error_response(
|
||||
error_code=ErrorCode.UNKNOWN_ERROR,
|
||||
message="服务器内部错误",
|
||||
details={"exception": exc.__class__.__name__}, # ← 只有类名
|
||||
request_id=request_id,
|
||||
)
|
||||
```
|
||||
- **影响**:生产环境出现 `KeyError` / `sqlite3.OperationalError` 时,运维只能看到"服务器内部错误 + KeyError",没有文件行号、没有 request_id 关联的堆栈,排障必须靠复现。项目自带 `LogService`(`logs/errors` 端点)却没有被这条路径喂数据。
|
||||
- **修复建议**:
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger("imagestudio.routes")
|
||||
|
||||
def handle_request(ctx, callback):
|
||||
try:
|
||||
return success_response(callback(), request_id=ctx.request_id)
|
||||
except ApiError as exc:
|
||||
logger.info("api_error request_id=%s code=%s", ctx.request_id, exc.error_code)
|
||||
return exc.to_response(request_id=ctx.request_id)
|
||||
except Exception as exc:
|
||||
logger.exception("unhandled route error request_id=%s actor=%s", ctx.request_id, ctx.actor_id)
|
||||
return response_from_exception(exc, request_id=ctx.request_id)
|
||||
```
|
||||
同时把未捕获异常落一条 `LogService` 错误日志,让 `GET logs/errors` 真正有内容。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 分页之后再过滤,`total` 与页大小失真
|
||||
|
||||
- **位置**:`backend/routes/job_routes.py:36-38`、`backend/routes/image_routes.py:45-49`
|
||||
- **问题**:service 已按 `page/page_size` 从数据库分页取回,路由层再对**当前页**做可见性过滤,然后用当前页的隐藏数去修正**全局 total**。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/job_routes.py:36-38
|
||||
if not ctx.has_permission("can_manage_materials"):
|
||||
visible = [item for item in result["items"] if item.get("metadata", {}).get("source") != "advanced_material"]
|
||||
result = {**result, "items": visible,
|
||||
"total": max(int(result.get("total") or 0) - (len(result["items"]) - len(visible)), 0)}
|
||||
|
||||
# backend/routes/image_routes.py:45-49
|
||||
visible = [item for item in payload["items"] if not _is_restricted_image(item)]
|
||||
payload["restricted_hidden"] = len(payload["items"]) - len(visible)
|
||||
payload["items"] = visible
|
||||
payload["total"] = max(len(visible), int(payload.get("total") or 0) - payload["restricted_hidden"])
|
||||
```
|
||||
- **影响**:`total` 是全表计数(`JobListResult.total` 来自 `repository.list()` 的第二个返回值),减去的却只是当前页被隐藏的条数 → 分页器页数算错;每页实际条数少于 `page_size` 且各页不等长;极端情况下某一页全是受限项,前端会显示空页却还有下一页。用户看到"共 87 条"但翻完只有 40 条。
|
||||
- **修复建议**:把可见性下推到仓储层的 WHERE 条件:
|
||||
- `JobRepository.list(..., exclude_sources=("advanced_material",))`;
|
||||
- `ImageRepository.list_images(..., include_restricted: bool)`,SQL 里过滤 `metadata->>'quarantined'` / `gallery_visibility`。
|
||||
这样 `total` 与分页天然一致,路由层只剩权限判定,不再做数据裁剪。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `ProfileService._require_owner` 不认管理员权限,与 `ResourceAccessService._can_access` 语义相反
|
||||
|
||||
- **位置**:`backend/services/profile_service.py:160-169` vs `backend/services/resource_access_service.py:80-84`
|
||||
- **问题**:同一套归属判定,两处实现规则不同——一处认 `can_manage_all_profiles` / `*`,另一处只认 `actor_id` 相等。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/profile_service.py:160-169
|
||||
def _require_owner(self, profile: CharacterProfile, ctx: RequestContext) -> None:
|
||||
if ctx.actor_id and ctx.actor_id == profile.owner_user_id:
|
||||
return
|
||||
raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "角色档案不存在", {"profile_id": profile.profile_id})
|
||||
|
||||
# backend/services/resource_access_service.py:80-84
|
||||
@staticmethod
|
||||
def _can_access(owner_user_id: str | None, ctx: RequestContext) -> bool:
|
||||
if ctx.has_permission("can_manage_all_profiles") or ctx.has_permission("*"):
|
||||
return True
|
||||
return bool(ctx.actor_id and owner_user_id and ctx.actor_id == owner_user_id)
|
||||
```
|
||||
- **影响**:即使按 P0-1 的建议把 `can_manage_all_profiles` 正确授予管理员,`GET profiles/{id}` / `PUT profiles/{id}` / `DELETE profiles/{id}` 依然会对管理员 404,而 `GET nodes/{id}/rounds` 却放行——管理能力在两条链路上表现相反,运维无法完成跨用户支持工单。连 `RequestContext.system()`(`permissions={"*"}`)在 profile 路径上也会被拒。
|
||||
- **修复建议**:删掉 `_require_owner`,`ProfileService` 改为注入/复用 `ResourceAccessService._can_access` 同一份判定(或把该静态方法提到 `core/security.py` 作为唯一实现 `can_access_owner(owner_user_id, ctx)`),两处共用。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 157 个 handler 是同构样板 + 22 个各自为政的 service 工厂 + 30 处 `Database(load_database_settings())`
|
||||
|
||||
- **位置**:`backend/routes/` 全目录;典型对照 `backend/routes/settings_routes.py:16-164`、`backend/routes/data_backup_routes.py:9-28`、`backend/routes/wardrobe_routes.py:89-106`
|
||||
- **问题**:每个 handler 都是同一个五行骨架(`service = service or _create_X()` → `def action(): require_*(ctx); return svc.foo(...)` → `return handle_request(ctx, action)`);每个路由模块自己写一份 `_create_*_service()`,每份都 `Database(load_database_settings())` + `AuditService(database)` + 一堆 repository 手工装配。统计:`return handle_request` 157 处,`Database(load_database_settings())` 30 处,`_create_*_service` 工厂 22 个。`node_routes._create_workflow_service`、`workflow_routes._create_workflow_service`、`history_routes` 里的同名装配是逐字重复的三份代码。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/settings_routes.py:42-53 与 56-67 与 70-81 …… 仅函数名和一行调用不同
|
||||
def validate_settings(ctx, payload, service=None) -> dict:
|
||||
settings_service = service or SettingsService()
|
||||
def action() -> dict[str, Any]:
|
||||
require_config_manager(ctx)
|
||||
return settings_service.validate(payload)
|
||||
return handle_request(ctx, action)
|
||||
|
||||
# backend/routes/data_backup_routes.py:9-11 —— 为了压行改用元组副作用,可读性极差
|
||||
def list_backups(ctx:RequestContext,service:DataBackupService|None=None)->dict:
|
||||
instance=service or DataBackupService()
|
||||
return handle_request(ctx,lambda:(require_config_manager(ctx),instance.list_backups())[1])
|
||||
|
||||
# backend/routes/wardrobe_routes.py:94-96 —— 同样的元组 hack
|
||||
return handle_request(ctx, lambda: (require_permission(ctx, "can_manage_materials"), wardrobe_service.save_template(profile_id, payload, ctx))[1])
|
||||
```
|
||||
- **影响**:新增路由的成本与出错面都被放大——P0-2 的越权、P1 的"构造在鉴权前"正是因为骨架靠复制粘贴而非统一封装才会成片出现;改一处横切逻辑(日志、审计、限流、状态码)要动 157 个地方。三份重复的 `WorkflowService` 装配意味着任何依赖变更要改三处,漏一处就是运行时 TypeError。`(guard, call())[1]` 的写法把"鉴权"伪装成表达式的一部分,静态检查与人眼 review 都极易漏看。
|
||||
- **修复建议**:
|
||||
1. 引入统一装饰器,把"鉴权 → 懒构造 service → 异常包装"收敛到一处:
|
||||
```python
|
||||
# backend/routes/common.py
|
||||
def route(permission: str, factory: Callable[[], Any] | None = None):
|
||||
def decorator(fn):
|
||||
@functools.wraps(fn)
|
||||
def wrapper(ctx, *args, service=None, **kwargs):
|
||||
def action():
|
||||
enforce(ctx, permission) # 复用 route_registry.permission_requirement
|
||||
svc = service or (factory() if factory else None)
|
||||
return fn(ctx, *args, service=svc, **kwargs)
|
||||
return handle_request(ctx, action)
|
||||
return wrapper
|
||||
return decorator
|
||||
```
|
||||
handler 退化成一行业务调用,`permission` 参数与 `RouteSpec.permission` 可用测试断言强制一致(顺带闭合 P0-2)。
|
||||
2. 建 `backend/routes/container.py`,提供 `get_workflow_service()` / `get_image_service()` / `get_queue_service()` 等**进程级单例或按 request 缓存**的工厂,删掉 22 份重复装配与 30 处 `Database(load_database_settings())`。
|
||||
3. 用普通 `def action()` 替换 `data_backup_routes.py` / `wardrobe_routes.py` 里的 `(guard, call())[1]` 元组写法。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `public_token` 权限档与实际暴露面不符,且 `media/fetch` 绕过分发器不留审计
|
||||
|
||||
- **位置**:`backend/route_registry.py:28`、`173`,`main.py:329-332`、`main.py:1753-1758`
|
||||
- **问题**:矩阵里 `public_token` 声明 `auth_required: False`,但真正的注册路径是通配符桥接(`/{PLUGIN_NAME}/<path:endpoint>`,不携带权限元数据),`media/fetch` 与其余 168 条路由共用 AstrBot 的同一层鉴权——项目自己在 `media_routes.py:56-63` 的注释里也承认 `/api/plug` 请求需要登录态。同时该端点在 `dispatch_bridge_request` 里被**提前拦截**,完全不经过 `dispatch_extension_request`。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:329-332
|
||||
if dispatch_method == "GET" and normalize_extension_path(dispatch_endpoint) == "media/fetch":
|
||||
file_response = await _to_media_file_response(dispatch_query)
|
||||
if file_response is not None:
|
||||
return file_response # ← 不经过路由解析、不经过 handle_request、无审计
|
||||
|
||||
# main.py:1753-1758 —— 通配符注册,permission 字段在这条路径上不存在
|
||||
def _bridge_registration_routes() -> list[dict[str, str]]:
|
||||
path = f"/{PLUGIN_NAME}/<path:endpoint>"
|
||||
return [{"method": method, "path": path, "endpoint": ""} for method in sorted({r.method for r in ROUTES})]
|
||||
```
|
||||
- **影响**:矩阵读起来像"这里有一个免鉴权端点",实际不是,误导后续维护者对暴露面的判断;反过来若哪天 AstrBot 放开 `/api/plug` 的鉴权,这条提前返回路径会真的变成公开文件读取(token 由 `MediaProxy` HMAC 签名 + 300s TTL 保护,`core/media_proxy.py:24` 的进程随机密钥算是兜住了,但重启后旧 token 全失效也意味着签名 URL 不能持久化分发)。另外该路径不产生任何访问记录。
|
||||
- **修复建议**:把 `public_token` 的描述改为"签名 token + 宿主鉴权",或在 `_to_media_file_response` 前补一次 `ctx.is_authenticated` 判定使其与声明一致;同时在提前返回前记一条 `LogService` 媒体访问日志(含 request_id、actor、uri)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `node_routes._bool` 与 `params.as_bool` 重复,`images/{id}/moderation-review` 无前端调用方
|
||||
|
||||
- **位置**:`backend/routes/node_routes.py:399-402` vs `backend/routes/params.py:60-82`;`backend/route_registry.py:135` vs `frontend/shared/api/endpoints.ts`
|
||||
- **问题**:
|
||||
1. `node_routes` 自带一份布尔转换,与公共 `params.as_bool(value, non_string_truthiness=True)` 语义完全等价却各写一遍;
|
||||
2. `POST images/{image_id}/moderation-review`(`materials` 权限)在 `endpoints.ts` 全表里没有对应条目,前端无任何调用方。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/node_routes.py:399-402
|
||||
def _bool(value: Any) -> bool:
|
||||
if isinstance(value, str):
|
||||
return value.strip().lower() in {"1", "true", "yes", "on"}
|
||||
return bool(value)
|
||||
|
||||
# backend/routes/params.py:74-82 —— 已有等价实现
|
||||
def as_bool(value, *, default=False, non_string_truthiness=False) -> bool:
|
||||
...
|
||||
```
|
||||
- **影响**:两份布尔语义未来会漂移(例如公共版本新增 `"y"` token 而 node_routes 版本不跟);受限图片复核能力做了后端却在 UI 上不可达,`_is_restricted_image` 隔离的图片实际上没有人工放行入口。
|
||||
- **修复建议**:`node_routes.get_node_dependency_context` 改用 `as_bool(params.get("include_draft"), non_string_truthiness=True)` 并删除 `_bool`;确认 `moderation-review` 是否应在图库详情里补一个"管理员复核"操作,否则从 `ROUTES` 移除以缩小暴露面。
|
||||
490
审计/findings/A8-前端App主体.md
普通文件
490
审计/findings/A8-前端App主体.md
普通文件
|
|
@ -0,0 +1,490 @@
|
|||
# A8 — 前端主体 `frontend/standalone-web/src/App.vue`(22563 行)
|
||||
|
||||
> 审计范围(实际逐块读过的文件):
|
||||
> - `frontend/standalone-web/src/App.vue`(全文分块通读:1-120、640-960、940-1050、1560-1780、2327-2410、2782-2900、3284-3600、3960-4300、4297-4720、4716-5120、5776-6090、6086-6160、6287-6460、6455-6750、6744-6930、6919-7200、7265-7400、7515-7560、8058-8360、8407-8740、9637-9950、9993-10260、10312-10510、11132-11300、模板 11359-14143、样式 14145-22540)
|
||||
> - `frontend/standalone-web/src/features/`(组件/composable 现状清单,含 `workflow/`、`profiles/`、`materials/`、`gallery/`、`settings/`、`quick-profile/profile-import.ts`)
|
||||
> - `frontend/tsconfig.json`、`frontend/package.json`(strict 已开启;`npm run typecheck` 实跑通过)
|
||||
> - 后端对照:`backend/services/character_workflow_service.py`、`backend/services/quick_character_consistency.py`、`backend/services/generation_service.py`、`backend/services/node_injection_template_service.py`
|
||||
|
||||
## 量化数据
|
||||
|
||||
| 指标 | 数值 |
|
||||
|---|---|
|
||||
| 总行数 | 22563(script 1–11357 / template 11359–14143 / style 14145–22540) |
|
||||
| `<script setup>` 行数 | 11356 |
|
||||
| `<template>` 行数 | 2784 |
|
||||
| `<style>`(**非 scoped**)行数 | 8395,约 1100 条选择器 |
|
||||
| `ref()` 声明 | 206(`reactive()` 0 个) |
|
||||
| `computed()` 声明 | 203 |
|
||||
| 顶层 `function` 声明 | 365 |
|
||||
| `watch()` | 20(其中 15 个带 `immediate: true`) |
|
||||
| 模板 `v-if` / `v-else(-if)` / `v-for` | 78 / 61 / 55(**55 个 `v-for` 全部带 `:key`,无 index-key 问题**) |
|
||||
| API 调用点 | `getJson` 59 + `postJson` 58 + `putJson` 9 + `deleteJson` 3 = **129** |
|
||||
| `endpoints.*` 引用 | 183 处 / 85 个不同端点;**0 处硬编码 `/api/...` 字符串** |
|
||||
| `try/catch` 块 | 84 / 82 |
|
||||
| `backendWriteBlockMessage(...)` 前置校验样板 | 27 处 |
|
||||
| loading/busy 类 ref | 37 个;error 类 ref | 25 个 |
|
||||
| 定时器 | `setInterval` 2 / `setTimeout` 4;`addEventListener` 9 / `removeEventListener` 9(一一对应) |
|
||||
| `AbortController` | **0 个**(所有请求不可取消) |
|
||||
|
||||
## 摘要
|
||||
|
||||
App.vue 是全仓唯一的"上帝组件":22.5k 行里塞进了 9 个导航页、3 个生成子工作台、12 个受控浮层、206 个 ref、203 个 computed 和 129 个 API 调用点。值得肯定的是——`v-for` 的 key 全部齐备、事件监听在 `onBeforeUnmount` 中全部成对摘除、定时器全部清理、profile 详情/衣橱两条链路有正经的 request-generation 竞态防护、且**没有任何硬编码 URL**(全部走 `shared/api/endpoints`)。
|
||||
|
||||
真正的致命问题集中在三处:**(1)** `displayMediaUrl()` 是一个被 4 个 computed 和整个模板 render 直接调用的"伪纯函数",它内部会发起网络请求并写回 `resolvedMediaUrls` ref,把整个图库列表拖进 O(N²) 重算 + Blob 无界累积;**(2)** 5 秒事件轮询 `startEventStreamPolling()` 既无重入保护,又会在图库页触发**全量分页重扫**,并且 `slice(-1)` 的写法会在事件积压时静默丢弃最多 19 条事件导致刷新失效;**(3)** 前端在 `quickCharacterPrompt()` 里重写了后端 `character_workflow_service._step_instruction()` 已有的提示词模板,两边措辞已经漂移。
|
||||
|
||||
结构上,`workflowNodeActionError` 这一个 ref 被 67 处复用来同时承载成功与失败文案,`workflowActionCards` 是一个 441 行的巨型 computed,8395 行未 scoped 的全局 CSS 与所有子组件的 `<style scoped>` 形成两套并行体系。仓库里已有 44 个抽好的组件/composable(14295 行),说明拆分模式是现成的,App.vue 只是没有跟进。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P0-致命] `displayMediaUrl()` 在 computed 与模板 render 中产生副作用:触发网络请求 + 写回响应式 ref,导致图库 O(N²) 重算与 Blob 无界泄漏
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:11146`(定义)、`:997-1011`(`galleryImages` computed 调用)、`:2341-2362`(两个候选图 computed 调用)、`:11668/11693/12826/12865/13961`(模板 render 中经 `imageUrl()` 调用)
|
||||
- **问题**:`displayMediaUrl` 看起来是格式化函数,实际做三件带副作用的事:① 读 `resolvedMediaUrls.value`(建立响应式依赖);② 在未命中时**发起 HTTP 请求**(`resolveStorageMediaUrl` / `resolveSignedMediaUrl`);③ 请求返回后 `resolvedMediaUrls.value = { ...resolvedMediaUrls.value, ... }` **整体替换该 ref**。它同时被 computed 和 template render 调用——这是 Vue 明令禁止的"在计算属性/渲染中做副作用"。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:11146
|
||||
function displayMediaUrl(rawUrl?: string | null): string {
|
||||
const value = String(rawUrl || "").trim()
|
||||
if (!value) return ""
|
||||
if (/^storage:\/\//i.test(value)) {
|
||||
const resolved = resolvedMediaUrls.value[value] // ← 建立响应式依赖
|
||||
if (resolved) return resolved
|
||||
if (!resolvingMediaUrls.has(value)) {
|
||||
const resolution = resolveStorageMediaUrl(value) // ← computed 里发请求
|
||||
.finally(() => { resolvingMediaUrls.delete(value) })
|
||||
resolvingMediaUrls.set(value, resolution)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
...
|
||||
}
|
||||
|
||||
// App.vue:11215 —— 每张图 resolve 完成后整体替换 ref
|
||||
const objectUrl = URL.createObjectURL(new Blob([bytes], { ... }))
|
||||
ownedMediaObjectUrls.add(objectUrl)
|
||||
resolvedMediaUrls.value = { ...resolvedMediaUrls.value, [rawUrl]: objectUrl, [sourceKey]: objectUrl }
|
||||
|
||||
// App.vue:997 —— 图库 computed 对全部图片逐张调用
|
||||
const galleryImages = computed<GalleryImage[]>(() => {
|
||||
const backendImages = uniqueImages([...]).filter(isAuthenticGenerationImage)
|
||||
return [...backendImages].sort(...).map((image) => ({
|
||||
...image,
|
||||
image_url: displayMediaUrl(image.image_url),
|
||||
thumbnail_url: displayMediaUrl(image.thumbnail_url),
|
||||
}))
|
||||
})
|
||||
```
|
||||
- **影响**:
|
||||
1. **O(N²) 重算**:`galleryImages` 依赖 `resolvedMediaUrls`,而它自己会让 N 张图各触发一次 `resolvedMediaUrls` 整体替换 → 每张图解析完成都让整个 `galleryImages`(含排序 + N 次 `displayMediaUrl`)重跑一遍。`loadGalleryImages()`(`:4511`)会把整库**所有页**都拉下来(`do...while (loaded.length < total)`,`page_size: 100`),1000 张图就是 1000 次全量重算 ≈ 100 万次 `displayMediaUrl` 调用,外加 `watch(galleryImages, ...)`(`:4184`)跟着抖 1000 次。
|
||||
2. **Blob 内存无界增长**:`ownedMediaObjectUrls` 只在 `onBeforeUnmount`(`:4041`)统一 `revokeObjectURL`。SPA 单页会话中它永不卸载,用户浏览过的每张图的完整二进制都常驻内存直到关闭标签页。
|
||||
3. **不可预期的请求风暴**:render 期间发请求意味着任何一次无关的响应式变更(切主题、点通知)重渲染时都可能补发媒体请求。
|
||||
- **修复建议**:把媒体解析从"渲染时惰性触发"改成"数据加载时显式预取"。
|
||||
- 新建 `composables/useMediaUrls.ts`,导出纯读取的 `mediaUrl(raw): string`(只查表,不发请求)和显式的 `prefetchMediaUrls(rawUrls: string[]): Promise<void>`。
|
||||
- 在 `loadGalleryImages` / `loadWorkflowRoundDetail` / `hydrateGenerationImages` 拿到数据后,**批量**调用 `prefetchMediaUrls(...)`,一次 `resolvedMediaUrls.value = {...}` 写入所有结果(把 N 次 ref 替换压成 1 次)。
|
||||
- 给 `resolvedMediaUrls` 加 LRU 上限(如 300 条),淘汰时 `URL.revokeObjectURL` 并从 `ownedMediaObjectUrls` 移除。
|
||||
- `galleryImages` 改用 `mediaUrl()`(纯查表)。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 事件流轮询无重入保护,且在图库页每 5 秒触发整库分页重扫
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:4561-4609`(`startEventStreamPolling`)、`:4511-4542`(`loadGalleryImages`)
|
||||
- **问题**:`window.setInterval(poll, 5000)` 中的 `poll` 是 async 且内部 `await Promise.allSettled(refreshes)`,其中 `loadGalleryImages()` 会把整个图库**逐页**拉完。没有任何 in-flight 标志,上一轮没跑完下一轮就会启动。`loadGalleryImages` 自身也没有并发去重(只置 `loadingGalleryImages` 但从不检查它)。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:4561
|
||||
function startEventStreamPolling() {
|
||||
if (eventStreamTimer !== undefined) window.clearInterval(eventStreamTimer)
|
||||
const poll = async () => {
|
||||
if (backendConnection.value.state !== "connected" || document.hidden) return
|
||||
...
|
||||
if (activeNav.value === "gallery" && generationChanged) refreshes.push(loadGalleryImages())
|
||||
...
|
||||
await Promise.allSettled(refreshes) // ← 可能远超 5s
|
||||
}
|
||||
void poll()
|
||||
eventStreamTimer = window.setInterval(poll, 5000) // ← 无 in-flight 守卫
|
||||
}
|
||||
|
||||
// App.vue:4519 —— 每次调用把整库翻完
|
||||
do {
|
||||
const result = await getJson<ImageListResult>(endpoints.images, { include_archived: true, page, page_size: pageSize })
|
||||
loaded.push(...result.items.filter(isAuthenticGenerationImage))
|
||||
total = result.total
|
||||
if (!result.items.length) break
|
||||
page += 1
|
||||
} while (loaded.length < total)
|
||||
```
|
||||
- **影响**:用户停留在图库页且后台在批量生图时,每 5 秒发起 `ceil(total/100)` 个 `GET /images` 请求;1000 张图 = 每 5 秒 10 个请求,且上一批未完成时新一批叠加,请求数指数堆积。叠加上一条 P0 的媒体 Blob 解析,页面会在几十秒内卡死。另外 `loaded.length` 只统计通过 `isAuthenticGenerationImage` 过滤后的图,而 `total` 是后端全量计数,只要库里有被过滤掉的占位图,循环就必然多翻一整轮直到返回空页。
|
||||
- **修复建议**:
|
||||
```ts
|
||||
let eventPollInFlight = false
|
||||
const poll = async () => {
|
||||
if (eventPollInFlight) return
|
||||
if (backendConnection.value.state !== "connected" || document.hidden) return
|
||||
eventPollInFlight = true
|
||||
try { /* ... */ } finally { eventPollInFlight = false }
|
||||
}
|
||||
```
|
||||
同时给 `loadGalleryImages` 加 `if (loadingGalleryImages.value) return`,并把轮询触发的图库刷新改成**增量**(只拉第 1 页 `page_size: 100` 并 merge),全量扫描只保留给用户显式点"刷新"。循环条件改为按页数 `page <= Math.ceil(total / pageSize)` 而非按 `loaded.length`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 事件流 `slice(-1)` 在事件积压时静默丢弃最多 19 条事件,导致队列/图库/日志停止刷新
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:4572-4582`
|
||||
- **问题**:`lastEventStreamId` 若不在本次返回的 20 条事件窗口内(`findIndex` 返回 `-1`),代码写成 `slice(-1)`——这是"取最后一条",而不是"取全部"。作者显然想表达"整段都是新事件"。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:4572
|
||||
const previousIndex = hadPrevious
|
||||
? stream.events.findIndex((event) => event.event_id === lastEventStreamId)
|
||||
: -1
|
||||
const freshEvents = hadPrevious
|
||||
? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : -1) // ← previousIndex === -1 时只取最后 1 条
|
||||
: []
|
||||
lastEventStreamId = newest
|
||||
if (!hadPrevious) return
|
||||
const eventTypes = freshEvents.map((event) => String(event.event_type || ""))
|
||||
const generationChanged = eventTypes.some((eventType) => eventType.startsWith("generation."))
|
||||
const workflowChanged = eventTypes.some((eventType) => eventType.startsWith("workflow."))
|
||||
```
|
||||
- **影响**:两个常见场景会命中:① 标签页被切走(`poll` 在 `document.hidden` 时直接 return,`lastEventStreamId` 停止推进),回来时游标早已滑出 20 条窗口;② 批量生图 5 秒内产生 >20 条事件。此时只有最后一条事件参与判定——如果它恰好是 `workflow.*`,`generationChanged` 就是 `false`,队列、图库、日志全部不会刷新,UI 显示的仍是几分钟前的旧数据,且不会有任何报错提示。`reconnectBackendWhenVisible()`(`:4471`)在已连接状态下只补刷当前轮次,补不了这些。
|
||||
- **修复建议**:
|
||||
```ts
|
||||
const freshEvents = hadPrevious
|
||||
? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : 0)
|
||||
: []
|
||||
```
|
||||
游标丢失时应视全窗口为新事件(宁可多刷一次也不能漏)。同时建议把 `limit: 20` 提高,或在 `visibilitychange` 恢复时主动做一次全量 `loadAll()` 级别的对齐。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 前端重写了后端已有的快速角色提示词模板,两边文案已经漂移
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:6120-6154`(`quickCharacterPrompt`)、`:6100-6118`(`quickCharacterIdentityFields`)
|
||||
对照后端:`backend/services/character_workflow_service.py:280-285`、`backend/services/quick_character_consistency.py:13-28`
|
||||
- **问题**:后端 `_step_instruction()` 已经为 `character_fast` 的四个 node_key 定义了权威指令表,`quick_character_consistency.py` 也已经定义了服务端拥有的 identity 字段别名表(`_FIELD_ALIASES`)与身份锁(`build_identity_lock`)。前端把这两张表都重抄了一遍,并且**措辞已经不一致**。
|
||||
- **代码**:
|
||||
```ts
|
||||
// 前端 App.vue:6126
|
||||
const instructions: Record<string, string> = {
|
||||
quick_avatar: "square avatar, close-up portrait, clear face, stable hair and eye details",
|
||||
quick_bust: "half-body character reference, upper-body clothing, natural posture",
|
||||
quick_stand: "full-body standing character illustration, complete outfit, accurate body proportions",
|
||||
quick_sheet: "character design sheet, multiple views, outfit details, material callouts",
|
||||
}
|
||||
```
|
||||
```python
|
||||
# 后端 backend/services/character_workflow_service.py:280
|
||||
fast = {
|
||||
"quick_avatar": "square avatar, face, hair, eyes, expression, keep identity consistent",
|
||||
"quick_bust": "half-body character reference, clothing, posture, keep identity consistent",
|
||||
"quick_stand": "full-body standing character illustration, complete outfit and proportions",
|
||||
"quick_sheet": "character design sheet, multiple views, outfit details and material callouts",
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// 前端 App.vue:6138 —— 连身份一致性约束都在前端拼
|
||||
return [
|
||||
"same single character in every image",
|
||||
"preserve exact gender presentation, age, species, face identity, body type, hair, eyes and distinctive features",
|
||||
identityPrefix, persistedProfile?.base_prompt, persistedProfile?.appearance_prompt,
|
||||
profile.name, profile.identity, profile.personality, quickProfileLibraryAppearance(profile),
|
||||
profile.style, instructions[nodeKey], ...materialPrompts,
|
||||
].filter(Boolean).join(", ")
|
||||
```
|
||||
- **影响**:注意前端 `quick_avatar` 丢掉了后端明确写的 `keep identity consistent`。同一个 `quick_avatar` 节点,走 Web 前端触发和走后端自身触发会产生不同的提示词,四联图身份一致性表现不可复现。后端改提示词策略时前端不会跟着改,这条链路上的任何 prompt 治理(`prompt_expansion_service.py`)都会被前端拼串绕过。
|
||||
- **修复建议**:删除 `quickCharacterPrompt` 里的 `instructions` 表和身份约束前缀,只把结构化字段(`identityFields`、`materialPrompts`、用户自定义 patch)作为 payload 传给 `endpoints.nodeGenerate`,由后端 `_step_instruction()` + `build_identity_lock()` 负责组装最终 prompt。若前端确实需要预览,应新增一个只读的 `POST /prompt/preview` 端点返回后端组装结果,而不是各拼各的。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `generateQuickCharacterImages()` 在前端编排后端工作流状态机(290 行),前端自行判定并 PUT `completed`/`running`/`failed`
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:5786-6076`
|
||||
- **问题**:这个函数在浏览器里完成了:创建工作流 → 启动 → 提交锚点任务 → 并行提交 3 个从属任务 → 重新拉节点 → **自行推断工作流终态** → PUT 状态与 metadata → 失败时再 PUT `status: "failed"` 做补偿。工作流状态推进是后端职责,前端只是一个可以随时被关闭标签页打断的客户端。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:5945-5979
|
||||
const completedTargetKeys = QUICK_CHARACTER_TARGET_SPECS.filter((spec) => { ... }).map((spec) => spec.nodeKey)
|
||||
const pendingTargetKeys = QUICK_CHARACTER_TARGET_SPECS.filter((spec) => {
|
||||
const node = nodes.find((item) => item.node_key === spec.nodeKey)
|
||||
return Boolean(node && ["created","pending","queued","running","retrying"].includes(normalizeStatus(node.status)))
|
||||
}).map((spec) => spec.nodeKey)
|
||||
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 —— 失败补偿也在前端
|
||||
if (activeWorkflowId) {
|
||||
try {
|
||||
const latestFailedWorkflow = await getJson<WorkflowDetail>(endpoints.workflow(activeWorkflowId))
|
||||
const failedWorkflow = await putJson<ProfileWorkflow>(endpoints.workflow(activeWorkflowId), {
|
||||
status: "failed", metadata: { ...(latestFailedWorkflow.workflow.metadata ?? {}), quick_character_failure: message },
|
||||
})
|
||||
```
|
||||
- **影响**:用户在生成过程中刷新页面/关标签页,工作流就永久停留在 `draft` 或 `running`,没有任何服务端兜底把它推到终态——数据库里会累积僵尸工作流。同时 `metadata` 里 `quick_character_batch_id`、`quick_character_pending_target_keys`、`anchor_image_id` 等 10+ 个字段的写入契约完全由前端定义,后端只是被动接收,任何字段改名都是隐式破坏。
|
||||
- **修复建议**:把整段编排下沉为一个后端端点(例如 `POST /workflows/{id}/quick-character/run`),后端负责锚点优先 + 并行提交 + 状态推进 + 失败补偿;前端只提交一次请求并轮询 `workflowRoundIsActive` 式的状态。已有的 `backend/services/quick_character_consistency.py` 说明后端本来就有这一层,前端这段是重复实现。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `workflowNodeActionError` 一个 ref 同时承载成功与失败文案(67 处赋值),模板按错误样式渲染
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:786`(声明)、`:8292`、`:8452`、`:8536`、`:8732`、`:8776`、`:6666` 等(成功文案写入 error ref)、`:12952`(模板)
|
||||
- **问题**:命名为 `...Error` 的 ref 被用作通用状态行,成功、失败、锁定提示混在一起,且状态永不按语义复位。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:8292 —— 成功路径写进 Error ref
|
||||
workflowNodeActionError.value = `档案卡已原子封存:${shortId(card.card_id)} / ${card.branch_name},4 类必填资产均已入库。`
|
||||
// App.vue:8536
|
||||
workflowNodeActionError.value = `轮次 ${detail.round.display_code} 已加入生成队列。`
|
||||
// App.vue:8732
|
||||
workflowNodeActionError.value = successMessage
|
||||
// App.vue:8631 —— 同一个 ref 又装失败
|
||||
workflowNodeActionError.value = `${options.retry ? "节点重试" : "节点生成"}失败:${errorMessage(err)}`
|
||||
```
|
||||
```html
|
||||
<!-- App.vue:12952 -->
|
||||
<em v-else-if="workflowNodeActionError || workflowBranchError">{{ workflowNodeActionError || workflowBranchError }}</em>
|
||||
```
|
||||
- **影响**:成功提示会被渲染成错误样式的 `<em>`;`selectWorkflowNode()`(`:6472`)切换节点时不清空它,用户在 A 节点操作失败后切到 B 节点,B 节点会继续挂着 A 的错误文案;`archiveSelectedWorkflowFinal` 的成功文案会一直留在界面上直到下一次操作。
|
||||
- **修复建议**:拆成 `workflowNodeActionError` 与 `workflowNodeActionNotice` 两个 ref(或一个 `{ kind: "ok" | "error"; text: string } | null`),模板按 kind 分别渲染;在 `selectWorkflowNode()` 里统一复位。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 模板中残留字面量 `\n` 字符串,会在"创建角色档案问卷"弹窗标题栏渲染出可见的 `\n`
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:13091`
|
||||
- **问题**:疑似脚本化编辑时把转义序列直接写进了 SFC 模板。`\n`(反斜杠 + n 两个字符)落在 `<header>` 元素的文本内容位置。
|
||||
- **代码**(`repr` 结果,注意 `</button>` 后的两个字符):
|
||||
```
|
||||
' <button type="button" title="关闭" @click="closeOverlay(\'personaQuestionnaire\')">×</button>\\n </header>'
|
||||
```
|
||||
即模板实际内容为:
|
||||
```html
|
||||
<button type="button" title="关闭" @click="closeOverlay('personaQuestionnaire')">×</button>\n </header>
|
||||
```
|
||||
- **影响**:HTML 中反斜杠和 `n` 是普通文本,会原样显示在弹窗右上角关闭按钮旁边,用户可见的 UI 脏字符。这是"创建角色档案问卷"这个主入口弹窗的标题栏。
|
||||
- **修复建议**:把 `\n` 替换成真正的换行:
|
||||
```html
|
||||
<button type="button" title="关闭" @click="closeOverlay('personaQuestionnaire')">×</button>
|
||||
</header>
|
||||
```
|
||||
并在 CI 里加一条 lint:模板段内出现 `\\n` / `\\t` 字面量即失败。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `loadCharacterWorkflowForProfile` 的缓存命中分支无条件重拉分支列表,与 watch 里的缓存守卫矛盾
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:7271-7275`(无守卫)、`:4111-4122`(有守卫)、`:7515-7531`(触发源)
|
||||
- **问题**:`watch([backendConnection.state, selectedCharacterWorkflow.workflow_id])` 明确用 `workflowBranchesByWorkflowId.value[workflowId]` 做了缓存去重,但 `loadCharacterWorkflowForProfile` 的早退分支绕过了这个守卫。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:4114 —— watch 有缓存守卫
|
||||
if (connectionState !== "connected" || !workflowId || workflowBranchesByWorkflowId.value[workflowId]) return
|
||||
void loadWorkflowBranches(workflowId)
|
||||
|
||||
// App.vue:7271 —— 这里没有
|
||||
const missingWorkflowIds = workflowIds.filter((workflowId) => !workflowNodesByWorkflowId.value[workflowId]?.length)
|
||||
if (!missingWorkflowIds.length) {
|
||||
if (profile.workflowId) await loadWorkflowBranches(profile.workflowId) // ← 每次都发
|
||||
return
|
||||
}
|
||||
```
|
||||
触发链:`updateQuickProfileWorkflowLink`(`:7529-7530`)用 `.map()` 重建 `backendQuickProfileLibraryItems` → `quickProfileLibraryItems` computed → `selectedQuickProfileLibraryItem` 得到新对象引用 → `watch(selectedQuickProfileLibraryItem)`(`:4279`)再次触发 `loadCharacterWorkflowForProfile` → 走进上面这个分支再发一次 `GET /workflows/{id}/branches`。
|
||||
- **影响**:每次角色卡对象被重建(保存工作流链接、快速生成状态更新、profile 详情加载完成)都会多打一次分支列表请求,并把 `workflowBranchError`/`workflowBranchesLoadingId` 抖动一次。虽然不会死循环(第二轮不再改动角色卡数组),但属于确定性的冗余请求。
|
||||
- **修复建议**:早退分支同样加缓存判断,或抽出 `ensureWorkflowBranches(workflowId)`:
|
||||
```ts
|
||||
async function ensureWorkflowBranches(workflowId: string) {
|
||||
if (!workflowId || workflowBranchesByWorkflowId.value[workflowId]) return workflowBranchesByWorkflowId.value[workflowId] ?? []
|
||||
return loadWorkflowBranches(workflowId)
|
||||
}
|
||||
```
|
||||
watch 与 `loadCharacterWorkflowForProfile` 都调用它。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 27 处写操作前置校验 + 40+ 处 `busy/error/try/catch/finally` 请求样板完全复制粘贴
|
||||
|
||||
- **位置**:典型样本 `frontend/standalone-web/src/App.vue:10025-10103`、`:10105-10134`、`:10157-10177`、`:10179-10208`、`:10210-10241`、`:8222-8298`、`:8407-8460`、`:8462-8552`、`:8554-8636`、`:8692-8739`、`:8741-8782`、`:8784-8825`
|
||||
- **问题**:同一段五步骨架在文件里重复了 40 多次,只有 endpoint、busy ref、error ref 和文案不同。
|
||||
- **代码**(`registerMaterialUri` 与 `executeMaterialAssetPack` 结构完全相同):
|
||||
```ts
|
||||
// App.vue:10105
|
||||
async function registerMaterialUri(payload: MaterialRegistrationRequest) {
|
||||
if (materialOperationExecuting.value) return
|
||||
const blocked = backendWriteBlockMessage("登记素材 URI")
|
||||
if (blocked) { materialOperationError.value = blocked; return }
|
||||
materialOperationExecuting.value = true
|
||||
materialOperationError.value = ""
|
||||
let completed = false
|
||||
try {
|
||||
const created = await postJson<Material>(endpoints.materialUpload, { ...payload, metadata: {...} })
|
||||
await loadMaterials()
|
||||
selectedMaterialCategoryId.value = payload.category_id
|
||||
selectedMaterialId.value = created.material_id
|
||||
materialActionMessage.value = `...`
|
||||
completed = true
|
||||
} catch (err) {
|
||||
materialOperationError.value = `登记素材 URI 失败:${errorMessage(err)}`
|
||||
} finally {
|
||||
materialOperationExecuting.value = false
|
||||
if (completed) closeOverlay("materialOperation")
|
||||
}
|
||||
}
|
||||
```
|
||||
- **影响**:37 个 loading ref + 25 个 error ref 的生命周期各自手写,任何一处漏写 `finally` 就是永久卡死的按钮;新增写操作时必须记住 5 个步骤,遗漏 `backendWriteBlockMessage` 就绕过了权限/连接检查。
|
||||
- **修复建议**:抽 `composables/useWriteAction.ts`:
|
||||
```ts
|
||||
export function useWriteAction() {
|
||||
const busy = ref(false)
|
||||
const error = ref("")
|
||||
const notice = ref("")
|
||||
async function run<T>(label: string, fn: () => Promise<T>, opts?: { onDone?: () => void }): Promise<T | null> {
|
||||
if (busy.value) return null
|
||||
const blocked = backendWriteBlockMessage(label)
|
||||
if (blocked) { error.value = blocked; return null }
|
||||
busy.value = true; error.value = ""
|
||||
try { const r = await fn(); opts?.onDone?.(); return r }
|
||||
catch (err) { error.value = `${label}失败:${errorMessage(err)}`; return null }
|
||||
finally { busy.value = false }
|
||||
}
|
||||
return { busy, error, notice, run }
|
||||
}
|
||||
```
|
||||
40 处调用点各自收缩到 5-10 行。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 8395 行未 `scoped` 的全局样式,与全部 44 个子组件的 `<style scoped>` 形成两套并行体系
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:14145`(`<style>` 无 `scoped`),到 `:22540`
|
||||
- **问题**:App.vue 的样式块占全文件 37%,约 1100 条选择器全部注入全局作用域;而 `components/ConfirmDialog.vue:137`、`components/EmptyState.vue:20`、`components/ImagePreviewDialog.vue:209`、`features/**` 等所有子组件都用 `<style scoped>`。
|
||||
- **代码**:
|
||||
```
|
||||
App.vue:14145 <style> ← 无 scoped,1100 条选择器全局生效
|
||||
App.vue:14212 body { ... } ← 直接改 body
|
||||
```
|
||||
- **影响**:① 类名污染——App.vue 定义的 `.workflow-action-card`、`.quick-profile-material-slot` 等泛用名一旦被子组件(或未来新组件)意外命中就会串样式,而 `scoped` 的子组件反过来无法覆写 App.vue 的规则(特异性相同、无 `:deep()` 通道);② 拆分阻力——任何把模板块搬进新组件的动作都必须同步搬走对应的几百行 CSS,否则样式立刻丢失,这也是这个文件迟迟拆不动的直接原因;③ 单文件 8395 行 CSS 无法定位归属。
|
||||
- **修复建议**:按下面的拆分清单,把 CSS 同步切成 `styles/generate.css`、`styles/materials.css`、`styles/queue.css`、`styles/overview.css`、`styles/dialogs.css` 并在对应新组件里 `<style scoped>` 引入;App.vue 只保留真正全局的 shell/token 部分(已有 `styles/tokens.css`、`styles/workbench.css` 可以承接)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `queueBatchActionMessage` 内部局部变量 `errorMessage` 遮蔽同名全局工具函数
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:10504`(局部变量)、`:11354`(被遮蔽的函数)
|
||||
- **问题**:函数内声明 `const errorMessage = ...` 字符串,与文件级 `function errorMessage(err: unknown)` 同名。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:10493
|
||||
function queueBatchActionMessage(result: Record<string, unknown>, fallback: string) {
|
||||
...
|
||||
const errorMessage = errors ? `,${errors} 条处理失败` : "" // ← 遮蔽 App.vue:11354 的 errorMessage()
|
||||
const remainingMessage = remaining > 0 ? `;仍有 ${remaining} 条,可继续清理` : ""
|
||||
return `${fallback} ${count} 条${errorMessage}${remainingMessage}。`
|
||||
}
|
||||
```
|
||||
- **影响**:当前逻辑正确,但这个函数体内再也无法调用错误格式化工具;后续维护者在此处加 `catch` 分支时会拿到一个字符串而不是函数,触发 `errorMessage is not a function`。
|
||||
- **修复建议**:改名为 `failureSuffix`。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `deleteSelectedProfile` 遗漏清理 6 个 per-profile 缓存 Map
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:6287-6339`
|
||||
- **问题**:归档角色后清理了 8 个缓存,但漏掉衣橱/档案卡/请求代次这几组。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:6316-6319 —— 清理了这些
|
||||
profileWorkflowsByProfileId.value = omitRecordKey(profileWorkflowsByProfileId.value, profile.profile_id)
|
||||
profileAvatarUrls.value = omitRecordKey(profileAvatarUrls.value, profile.profile_id)
|
||||
profileGenerationBusyByProfileId.value = omitRecordKey(profileGenerationBusyByProfileId.value, profile.profile_id)
|
||||
profileGenerationErrorsByProfileId.value = omitRecordKey(profileGenerationErrorsByProfileId.value, profile.profile_id)
|
||||
// 未清理:profileWardrobeItemsByProfileId(:665)、profileWardrobeErrorsByProfileId(:666)、
|
||||
// profileWardrobeLoadingByProfileId(:667)、profileCardsByProfileId(:819)、
|
||||
// profileDetailsRequestGenerationByProfileId、profileWardrobeRequestGenerationByProfileId
|
||||
```
|
||||
- **影响**:长会话中反复删除角色会让这几个 Map 单调增长;若 `profileWardrobeLoadingByProfileId` 恰好停留在 `true`,同 id 记录再次出现时会显示假的加载态。
|
||||
- **修复建议**:把 6 个 Map 的清理并进同一个 `purgeProfileCaches(profileId)` 辅助函数,`deleteSelectedProfile` 与 `invalidateProfile*Requests` 共用。
|
||||
|
||||
---
|
||||
|
||||
## 结构:这个文件里有多少个逻辑上独立的"页面/面板/对话框"?
|
||||
|
||||
**统计:9 个导航级页面 + 3 个生成子工作台 + 12 个受控浮层(`controlledOverlays`,`App.vue:904-917`)+ 6 个已组件化但由 App 传 20-40 个 prop 驱动的面板 = 至少 30 个独立单元。**
|
||||
|
||||
### 模板拆分清单(行号区间 → 目标组件)
|
||||
|
||||
| 行号区间 | 行数 | 职责 | 目标组件 |
|
||||
|---|---|---|---|
|
||||
| 11360-11385 | 26 | app shell + 导航轨 + 标题栏 | 保留在 App.vue |
|
||||
| 11386-11424 | 39 | 全局搜索框 / 结果面板 | `components/GlobalSearchBox.vue` + `useGlobalSearch()` |
|
||||
| 11425-11549 | 125 | 顶栏动作区(通知/日志/调色板/主题按钮) | `components/TopBarActions.vue` |
|
||||
| 11551-11570 | 20 | 主题调色板浮层 | `components/ThemePalettePanel.vue` |
|
||||
| 11571-11623 | 53 | 通知中心浮层 | `features/notifications/NotificationPanel.vue` |
|
||||
| **11624-13334** | **1711** | **生成页(最大块)** | 见下方细分 |
|
||||
| ├ 11626-11646 | 21 | 生成页 hero + 三模式切换 | `features/generate/GenerateHeader.vue` |
|
||||
| ├ 11648-11806 | 159 | 单图生成工作台(提示词 / 模型选择 / 结果预览) | `features/generate/ImageComposerPanel.vue` |
|
||||
| ├ 11807-12269 | 463 | 快速角色工作台(角色卡列表 / 图像轮播 / 素材槽位 / 动作卡) | `features/quick-profile/QuickProfileWorkspace.vue` |
|
||||
| ├ 12270-12987 | 718 | 详细工作流工作台(节点分组 / 人设拆解 / 提示词规划 / 素材绑定 / 候选池 / 生命周期条) | `features/workflow/WorkflowWorkspace.vue`,再内切 5 个子面板 |
|
||||
| ├ 12988-13075 | 88 | 外部角色卡导入对话框 | `features/quick-profile/ExternalProfileImportDialog.vue` |
|
||||
| └ 13077-13329 | 253 | 角色档案问卷对话框(简单/复杂两套字段) | `features/quick-profile/PersonaQuestionnaireDialog.vue` |
|
||||
| 13335-13376 | 42 | ProfilesPage 挂载(已组件化,41 个 prop) | 保留,但 prop 收敛为 2-3 个对象 |
|
||||
| 13377-13630 | 254 | 素材库页(分类栏 / 筛选 / 卡片网格 / 动作卡 / 两个内嵌对话框) | `features/materials/MaterialsPage.vue` |
|
||||
| 13631-13760 | 130 | 队列页(过滤 tab / 任务列表 / 详情 / 动作卡) | `features/queue/QueuePage.vue` |
|
||||
| 13761-13810 | 50 | GalleryPage / SettingsPage / LogsPage 挂载(已组件化) | 保留 |
|
||||
| 13811-13975 | 165 | 总览仪表盘(指标卡 / 队列摘要 / 建议 / 最近图片) | `features/overview/OverviewPage.vue` |
|
||||
| 13976-14040 | 65 | 性能详情页 | `features/overview/PerformancePage.vue` |
|
||||
| 14041-14142 | 102 | 全局对话框挂载区(图片查看器 / 对比 / 交叉审查 / 素材抽屉 / 素材操作 / 确认框) | `components/AppDialogHost.vue` |
|
||||
|
||||
### 脚本拆分清单(行号区间 → 目标 composable)
|
||||
|
||||
| 行号区间 | 行数 | 职责 | 目标 composable |
|
||||
|---|---|---|---|
|
||||
| 4302-4487 | 186 | 后端连接状态机 / bootstrap / 指数退避重连 | `composables/useBackendConnection.ts` |
|
||||
| 4561-4609 | 49 | 事件流轮询 | `composables/useEventStream.ts`(**先修 P1 两条**) |
|
||||
| 4488-4547 + 4611-4698 | 148 | dashboard / 成本 / 任务 / 日志 / 模型选项加载 | `composables/useDashboardData.ts` |
|
||||
| 4511-4547 + 997-1011 | 51 | 图库加载与媒体 URL 映射 | `composables/useGalleryData.ts` |
|
||||
| 4700-4786 | 87 | 设置页读写与校验 | `composables/useSettingsPage.ts` |
|
||||
| 4787-4862 + 5316-5620 + 9993-10310 | 663 | 素材库(加载 / 分类 / 识别 / 资产包 / 衣橱导入 / 动作分发) | `composables/useMaterialLibrary.ts` |
|
||||
| 4864-5100 + 5644-5775 + 6287-6339 | 340 | 角色档案页 + 衣橱 + 删除 | `composables/useProfilePage.ts` |
|
||||
| 5776-6154 | 379 | 快速角色四联图生成编排 | **优先下沉到后端**,残留部分 → `composables/useQuickCharacterGeneration.ts` |
|
||||
| 6460-6681 + 6919-7100 + 8462-8552 | 476 | 轮次 / 候选 / 反馈 / 确认 / 轮询 | `composables/useWorkflowRounds.ts` |
|
||||
| 7101-7264 | 164 | 节点素材绑定抽屉 | `composables/useWorkflowNodeMaterials.ts` |
|
||||
| 7265-7580 | 316 | 角色工作流创建/恢复/节点补齐 | `composables/useCharacterWorkflow.ts` |
|
||||
| 7752-8056 | 305 | 图片查看器缩放拖拽 + 交叉审查对话框 | `composables/useImageViewer.ts` + `useWorkflowGenerationReview.ts` |
|
||||
| 8058-9250 | 1193 | 工作流节点动作(分支 / 生成 / 完成 / 审查 / 采用 / 封存 / 快照) | `composables/useWorkflowNodeActions.ts` |
|
||||
| 9251-9763 | 513 | 问卷 → 档案 payload 构建 + 外部角色卡导入 | `composables/useQuickProfileArchive.ts` |
|
||||
| 9765-9940 | 176 | 12 个受控浮层的开关/外部点击/Esc 管理 | `composables/useOverlayManager.ts`(现在是 `if (key === ...)` 长链,应改成注册表 `Record<ControlledOverlay, { isOpen, setOpen }>`) |
|
||||
| 10312-10510 | 199 | 队列动作 + 二次确认 | `composables/useQueueActions.ts` |
|
||||
| 11024-11226 | 203 | 图片 URL / 占位图 / 媒体签名解析 | `composables/useMediaUrls.ts`(**先修 P0**) |
|
||||
| 11243-11313 | 71 | 主题偏好持久化 + 颜色工具 | `composables/useThemePreferences.ts` |
|
||||
| 1346-1458 / 1931-2018 / 2782-3222 / 3370-3511 | 113 / 88 / **441** / 142 | 四组"动作卡"配置巨型 computed | 各自搬进对应 feature 目录的 `*-action-cards.ts`,改为接收显式参数的纯函数 |
|
||||
|
||||
按上表拆完,App.vue 应收缩到 **300-500 行**(shell + 路由分发 + 全局对话框挂载)。
|
||||
|
||||
---
|
||||
|
||||
## 精简机会汇总
|
||||
|
||||
1. **请求样板**(见 P2):40+ 处 `busy/error/try/catch/finally` → `useWriteAction()`,可删约 400 行。
|
||||
2. **"选中项跟随列表"watch**:`App.vue:4055/4069/4083/4097/4184/4212/4226/4240` 共 8 个 watch 结构完全相同(列表空 → 清空选中;选中项不在列表 → 取第一项)。抽 `useSelectionSync(list, selectedId, keyOf)`,可删约 90 行。
|
||||
3. **分页拉全量**:`loadAllJobs`(`:4686`)、`loadRemainingMaterialPages`(`:4840`)、`loadRemainingProfilePages`(`:4884`)、`loadGalleryImages`(`:4511`) 四份几乎相同的分页合并逻辑 → `fetchAllPages(endpoint, params, keyOf)`,可删约 70 行。
|
||||
4. **四组动作卡 computed**:`materialActionCards`/`quickProfileActionCards`/`workflowActionCards`/`queueActionCards` 共 784 行,卡片结构完全一致(`id/title/detail/badge/state/tone/action/enabled/actionKey`),可统一为一份 `ActionCard` 类型 + 一个 `<ActionCardGrid>` 组件 + 四份纯配置函数。
|
||||
5. **`materialColorTuple`/`quickProfileGeneratedColors`/`alphaColor`/`mixColor`/`hexToRgb`/`toHexByte`**(`:11285-11313`、`:5392`、`:9627`):纯色彩工具,直接移到 `utils/color.ts`。
|
||||
6. **两处 4 层 `displayMediaUrl(...) || displayMediaUrl(...) || ...` 链**(`:2345-2348` 与 `:2356-2359`)逐字重复,抽 `candidateImageUrl(candidate)`。
|
||||
|
||||
## 与后端耦合汇总
|
||||
|
||||
- ✅ **无硬编码 URL**:183 处 API 调用全部经 `endpoints.*`(85 个端点),`grep "'/api/"` 零命中。这一点做得干净。
|
||||
- ❌ **提示词模板重复实现**(P1,`:6126` vs `character_workflow_service.py:280`)。
|
||||
- ❌ **工作流状态机在前端推进**(P1,`:5955`、`:5979`、`:6051`)。
|
||||
- ⚠️ **对后端 `metadata` 的深层字段假设 34 处**:`recordString(node.metadata, "active_round_id")`(`:2337`)、`metadata.prompt_plan`(`:2802`)、`metadata.material_bindings`(`:2803`)、`metadata.final_archive_history_id`(`:2792`)、`metadata.character_execution.import_confirmed`(`:7539`)、`metadata.system_key`(`:4870`/`:6738`)、`metadata.source === "sample"`(`:4910`)、`recordString(image.metadata, "candidate_id")`(`:6461`) 等。这些都是无 schema 约束的自由字典字段,后端改名前端静默降级。建议在 `shared/types/workflow.ts` 里为这些 metadata 键定义显式 interface,并让后端在 `WorkflowNode`/`GenerationImage` 响应里提升为一等字段。
|
||||
- ⚠️ **前端直接读原始配置树**:`quickGenerationModelRoute()`(`:6086`) 从 `currentSettings.config.model_assignments.quick_generation` 和 `config.generation.default_model` 里挖路由,而后端 `generation_service.py:2033-2036` 已经有 node_key → `quick_generation` 的映射。同理 `configuredImageModelOptions`(`:1047`) 也在解析 `config.generation`。应改为消费后端提供的解析结果端点,而非解析原始 YAML 配置结构。
|
||||
- ⚠️ **外部角色卡双路径解析**:`importExternalProfileDocumentFile`(`:9637`) 走后端 `endpoints.quickProfileDocumentImport` 做 LLM 识别,但 `applyExternalProfileImport`(`:9710`) 走前端本地正则 `parseExternalProfileImport`(`features/quick-profile/profile-import.ts:90`)。文件导入成功后会把原文写回 `externalProfileImportText`(`:9698`),此时用户若再点"识别并填入问卷",本地正则结果会**覆盖**后端 LLM 的识别结果。建议统一走后端。
|
||||
394
审计/findings/A9-前端功能组件.md
普通文件
394
审计/findings/A9-前端功能组件.md
普通文件
|
|
@ -0,0 +1,394 @@
|
|||
# A9 · 前端功能模块与共享层(App.vue 之外)
|
||||
|
||||
> 审计范围(实际逐行读过的文件):
|
||||
> - `frontend/shared/api/client.ts`、`frontend/shared/api/endpoints.ts`
|
||||
> - `frontend/shared/types/`:`workflow-round.ts`、`workflow.ts`、`profile.ts`、`material.ts`、`image.ts`
|
||||
> - `frontend/shared/utils/`:`presentation.ts`、`collections.ts`
|
||||
> - `frontend/plugin-page/src/App.vue`、`frontend/plugin-page/src/main.ts`、`frontend/plugin-page/vite.config.ts`
|
||||
> - `frontend/standalone-web/vite.config.ts`、`frontend/standalone-web/src/main.ts`、`frontend/package.json`
|
||||
> - `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue`(全文 2024 行)、`advanced-material-state.ts`
|
||||
> - `frontend/standalone-web/src/features/gallery/GalleryPage.vue`、`gallery/types.ts`
|
||||
> - `frontend/standalone-web/src/features/profiles/`:`ProfilesPage.vue`、`ProfileDetailPane.vue`、`ProfileWardrobePane.vue`、`profile-ui.ts`
|
||||
> - `frontend/standalone-web/src/features/workflow/`:`WorkflowCandidatePool.vue`、`WorkflowRoundPanel.vue`、`WorkflowGenerationReviewDialog.vue`、`WorkflowMaterialDrawer.vue`、`WorkflowCompareDialog.vue`、`WorkflowBranchPanel.vue`、`WorkflowComposer.vue`、`WorkflowDependencyContextCard.vue`、`types.ts`、`workflow-lock-state.ts`
|
||||
> - `frontend/standalone-web/src/features/settings/SettingsPage.vue` 及全部子面板
|
||||
> - `frontend/standalone-web/src/features/quick-profile/profile-import.ts`
|
||||
> - `frontend/standalone-web/src/components/`:`MaterialOperationDialog.vue`、`ConfirmDialog.vue`、`ImagePreviewDialog.vue`、`MaterialDetailDialog.vue`、`MaterialCategoryCreateDialog.vue`
|
||||
> - `frontend/standalone-web/src/material-labels.ts`、`safe-backdrop-close.ts`、`frontend/tests/*.test.mjs`
|
||||
> - 交叉验证的后端文件:`backend/dto/workflow_round_dto.py`、`backend/dto/profile_dto.py`、`backend/services/wardrobe_service.py`、`backend/services/settings_service.py`、`core/secret_service.py`、`database/repositories/profile_repository.py`
|
||||
|
||||
## 摘要
|
||||
|
||||
`plugin-page` 与 `standalone-web` 之间**没有代码重复**——`plugin-page/src/App.vue` 只有 7 行,直接 `import WorkbenchApp from "../../standalone-web/src/App.vue"`,两套构建共享同一份源码,这一点做得很干净。真正的问题在别处:**共享层缺失导致同一逻辑在功能组件里被反复手写**。`ApiClientError` 提供了结构化的 `code`/`details`,但唯一的中文化函数 `readableApiError` 被关在 `App.vue` 里没有导出,结果 13 个直接调 API 的组件各写各的 `e instanceof Error ? e.message : String(e)`(共 18+ 处),把 `AstrBot Plugin Page POST request timed out after 30 seconds` 这类英文原文直接抛给中文用户。焦点陷阱被复制了 6 份且行为各不相同,另有 2 个 `aria-modal="true"` 的对话框(`WorkflowMaterialDrawer`、`SettingsPage` 适配器弹窗)完全没有 Esc 和焦点管理。
|
||||
|
||||
有 3 条确凿的功能性缺陷:`AdvancedMaterialImportPage.vue:1314-1316` 存在编码损坏的字面量 `"????????????????"` 且已被模板渲染;`profile-import.ts` 把「性格关键词待从原文继续整理」这类占位提示当作真实值写入问卷并最终进入 `base_prompt`;`SettingsPage.vue:98` 把 UI 明确承诺「不写入配置或日志」的 API Key 以 `api_key_plaintext` 塞进 `settings/save` 请求,后端会原样落盘到 `config.yaml`。
|
||||
|
||||
类型层面与后端 DTO 目前是对齐的(逐字段比对了 `WorkflowRoundCandidatePoolEntry`、`CharacterProfile`、`detailed_workflow_state` 的 SQL 取值),但完全靠人工维护、无契约测试兜底,属于结构性漂移风险。此外 `WorkflowDependencyContextCard.vue`(279 行)已无任何引用成为死组件,`package.json` 里 `pinia`/`vue-router` 声明但零使用。
|
||||
|
||||
`ProfilesPage → ProfileDetailPane → ProfileWardrobePane` 是典型的三层 prop drilling:`App.vue` 传 24 个 props / 13 个 emits,其中 16 个 props 在 `ProfilesPage` 内完全不被使用、只做透传。
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] `styleValidationReviewTrust` 返回编码损坏的问号串,且已渲染到界面
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1304-1317`(渲染点 `:1656`)
|
||||
- **问题**:函数的三个返回分支全部是编码损坏后残留的 ASCII 问号,中文字符在某次保存/转码中被替换成了 `?`。这不是注释也不是占位常量,而是直接返回给模板的显示文本。
|
||||
- **代码**:
|
||||
```ts
|
||||
function styleValidationReviewTrust(validationCase: AdvancedStyleValidationCase) {
|
||||
const review = ...
|
||||
const coverage = Number(calibration.dimension_coverage)
|
||||
const inconsistent = Boolean(calibration.review_inconsistent || calibration.dimension_consistency_capped)
|
||||
const risks = Array.isArray(review.semantic_risks) && review.semantic_risks.length > 0
|
||||
if (inconsistent || risks) return "????????????????"
|
||||
if (Number.isFinite(coverage)) return `????? ? ???? ${Math.round(coverage * 100)}%`
|
||||
return "?????"
|
||||
}
|
||||
```
|
||||
模板侧(1656 行):
|
||||
```html
|
||||
<small v-if="styleValidationFidelityPercent(validationCase) != null" class="advanced-style-review-trust">{{ styleValidationReviewTrust(validationCase) }}</small>
|
||||
```
|
||||
- **影响**:只要画风验证轮返回了 `fidelity_score`,进阶素材审核页就会在每个验证场景卡片下显示一串问号。审核人员本应据此判断「评分可信度/维度覆盖率」,现在这条关键信息完全丢失,等于在缺少可信度提示的情况下做封存决策。全仓库仅此一处出现 `????` 字面量,可以确定是单点编码事故而非设计。
|
||||
- **修复建议**:恢复三条中文文案,例如 `"评分可信度存疑:维度不一致或存在语义风险"` / `` `评分可信 · 维度覆盖 ${pct}%` `` / `"评分可信度未知"`;同时在 `frontend/tests/` 增加一个断言:`features/` 下所有 `.vue` 不得出现连续 3 个以上 `?` 的字符串字面量,防止再次发生编码回退。
|
||||
|
||||
### [P1-严重] 文本角色卡导入把「待整理」占位提示当成真实设定写入档案,最终污染 `base_prompt`
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/quick-profile/profile-import.ts:149-178`、`:327-337`;消费点 `frontend/standalone-web/src/App.vue:9721-9726`、`:9568-9581`
|
||||
- **问题**:`resolveImportedProfileField` 的第 4 个参数 `fallback` 在「没识别到」时会被写进 `.value`。5 个字段的 fallback 不是空串,而是给人看的提示语。调用方只用 `recognizedKeys` 控制 UI 高亮,却把 `.value` 无条件复制进问卷。
|
||||
- **代码**:
|
||||
```ts
|
||||
// profile-import.ts:149
|
||||
const personality = resolveImportedProfileField(source, ["性格", ...], [...], "性格关键词待从原文继续整理")
|
||||
const appearance = resolveImportedProfileField(source, ["外观", ...], [...], "外观特征待从原文继续整理")
|
||||
const outfit = resolveImportedProfileField(source, ["服装", ...], [...], "服装与配饰待从原文继续整理")
|
||||
const scene = resolveImportedProfileField(source, ["场景", ...], [...], "常用场景待补充")
|
||||
|
||||
// :327 —— fallback 直接成为 value
|
||||
function resolveImportedProfileField(source, labels, keywords, fallback) {
|
||||
...
|
||||
return { value: fallback, recognized: false }
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// App.vue:9721 —— 未按 recognized 过滤,整体复制
|
||||
personality: draft.personality,
|
||||
appearance: draft.appearance,
|
||||
outfit: draft.outfit,
|
||||
scene: draft.scene,
|
||||
```
|
||||
```ts
|
||||
// App.vue:9568 —— 进入角色实体
|
||||
personality: [questionnaire.personality, questionnaire.likes, questionnaire.dislikes]
|
||||
.map((item) => item.trim()).filter(Boolean).join(";") || "性格待细化",
|
||||
clothing: questionnaire.outfit.trim() || "服装与配饰待细化",
|
||||
```
|
||||
再经 `App.vue:9367` 拼进 `base_prompt`。
|
||||
- **影响**:导入一份没有「性格:」小节的角色卡后,角色档案的性格字段会变成中文句子「性格关键词待从原文继续整理」,并作为 `personality:` 片段进入 `base_prompt` 送给生图/文本模型。模型会把这句元指令当作角色描述处理,生成结果不可控;用户看到问卷里已经"填好了"也不会去清理。
|
||||
- **修复建议**:把这 5 个 fallback 改为空串,把提示语移到 UI 的 `placeholder` 属性上(`ExternalProfileImportPreviewRow` 已经有 `recognized` 标志可用于渲染灰色提示)。若要保留提示,则在 `App.vue:9721` 处按 `draft.recognizedKeys.includes(key)` 过滤后再赋值。
|
||||
|
||||
### [P1-严重] 「仅本次会话使用、不写入配置」的 API Key 被前端主动写进 `settings/save` 请求体
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/settings/SettingsPage.vue:98`(`saveAndProbeAdapter`);UI 承诺文案在 `:133`
|
||||
- **问题**:输入框标签明确写着「仅本次页面会话使用」「不写入配置或日志」,但 `saveAndProbeAdapter` 把该值作为 `api_key_plaintext` 注入 `config.generation.adapters[]` / `config.generation.provider`,然后调用 `endpoints.settingsSave`。后端 `SettingsService.save()` 会把合并后的 config 通过 `write_text_atomic(config_path, dump_yaml(merged))` 原样落盘(`backend/services/settings_service.py:445`),`_mask_sensitive` 只作用于返回值和审计快照,不作用于写入磁盘的内容。
|
||||
- **代码**:
|
||||
```ts
|
||||
// SettingsPage.vue:98
|
||||
const key = probeApiKeyValue(a.id).trim()
|
||||
if (Array.isArray(generation.adapters)) {
|
||||
generation.adapters = generation.adapters.map(item => {
|
||||
const adapter = obj(item)
|
||||
if (String(adapter.id || adapter.provider_id) !== a.id) return item
|
||||
return { ...adapter, ...(key ? { api_key_plaintext: key } : {}) } // ← 明文写入待保存 config
|
||||
})
|
||||
}
|
||||
const provider = obj(generation.provider)
|
||||
if (String(provider.id || provider.provider_id) === a.id && key)
|
||||
generation.provider = { ...provider, api_key_plaintext: key }
|
||||
config.generation = generation
|
||||
await postJson<ValidateSettingsResult>(endpoints.settingsValidate, { config })
|
||||
const saved = await postJson<SaveSettingsResult>(endpoints.settingsSave, { config }) // ← 落盘
|
||||
```
|
||||
```html
|
||||
<!-- SettingsPage.vue:133 -->
|
||||
<label><span>探测用 API Key</span><input ... placeholder="仅本次页面会话使用" ...>
|
||||
<small>点击测试时会直接读取输入框当前值,兼容浏览器自动填充;不写入配置或日志。</small></label>
|
||||
```
|
||||
另外 `duplicateAdapter`(`:89`)会把该会话密钥复制到新适配器 `probeApiKeys[duplicateId]`,扩大扩散面。
|
||||
- **影响**:用户基于「不落盘」的明确承诺输入生产环境 API Key,实际会以明文形式持久化到 `config.yaml`(该文件在仓库中被跟踪,见根目录 `config.yaml`)。这是承诺与行为的直接背离,属于凭据泄漏风险。
|
||||
- **修复建议**:二选一。(a) 保持承诺:改用一个不落盘的探测端点,把明文 key 只放在 `apiDiscoveryProbeProvider` 的请求体里(`backend/services/api_discovery_service.py:229` 已经支持读取 `api_key_plaintext`),去掉先 save 再探测的链路;(b) 修正承诺:把 `<small>` 文案改成「保存后会写入插件配置文件」,并在按钮上加二次确认。无论哪种,`duplicateAdapter` 都不应复制会话密钥。
|
||||
|
||||
### [P1-严重] 快速角色问卷默认值是一个完整的虚构示例角色,且绕过了 `production-data-boundary` 测试的防线
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/quick-profile/profile-import.ts:32-59`;使用点 `frontend/standalone-web/src/App.vue:759`
|
||||
- **问题**:`quickProfileQuestionnaire` 的初始值不是空表单,而是一个填满的示例角色。仓库里已有 `frontend/tests/production-data-boundary.test.mjs` 专门禁止生产 UI 内联演示数据,但该测试只读取 `App.vue` 和 `MaterialDetailDialog.vue` 两个文件,`profile-import.ts` 不在扫描范围内,因此这批示例数据从防线的缝隙里漏了过去。
|
||||
- **代码**:
|
||||
```ts
|
||||
export function createDefaultQuickProfileQuestionnaire(): QuickProfileQuestionnaire {
|
||||
return {
|
||||
roleCore: "近未来港区巡查员,负责夜间巡逻和异常记录。",
|
||||
genderPresentation: "female",
|
||||
distinctiveFeatures: "发光臂章,青绿色眼睛",
|
||||
personality: "冷静、可靠、行动快,外冷内热。",
|
||||
appearance: "黑色短发,青绿色眼睛,轻机能外套。",
|
||||
outfit: "短靴、发光臂章、便携通讯设备。",
|
||||
scene: "星港、雨夜街区、巡查终端、航灯背景。",
|
||||
...
|
||||
```
|
||||
```ts
|
||||
// App.vue:759
|
||||
const quickProfileQuestionnaire = ref<QuickProfileQuestionnaire>(createDefaultQuickProfileQuestionnaire())
|
||||
```
|
||||
```js
|
||||
// frontend/tests/production-data-boundary.test.mjs:5-8 —— 扫描范围不含 profile-import.ts
|
||||
const appPath = new URL("../standalone-web/src/App.vue", import.meta.url)
|
||||
const materialDialogPath = new URL("../standalone-web/src/components/MaterialDetailDialog.vue", import.meta.url)
|
||||
```
|
||||
- **影响**:任何用户第一次打开快速角色问卷,看到的是一个别人的角色设定。直接点「生成」就会消耗真实 API 额度生成这个虚构角色的四张图并落库。同时它与 `ProfilesPage` 的空态文案「新建或导入角色后即可管理生成设定」自相矛盾。
|
||||
- **修复建议**:把 `App.vue:759` 改为 `createEmptyQuickProfileQuestionnaire()`(该函数已存在于同文件 `:61`),示例值降级为各输入框的 `placeholder`。同时把 `production-data-boundary.test.mjs` 的扫描目标改为 `standalone-web/src` 下全部 `.vue`/`.ts`,让防线真正覆盖 features 层。
|
||||
|
||||
### [P2-中等] `client.ts` 的结构化错误在功能层完全失效:18+ 处各写各的 catch,英文超时文案直抛给中文用户
|
||||
|
||||
- **位置**:`frontend/shared/api/client.ts:18-28`(`ApiClientError`)、`frontend/standalone-web/src/App.vue:4356`(`readableApiError`,未导出)、`frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1355`,以及 settings/gallery/profiles 下 15+ 个内联 catch
|
||||
- **问题**:`ApiClientError` 携带了 `code` 和 `details`,客户端有 8 种明确的错误码。但唯一做码→中文映射的 `readableApiError` 定义在 `App.vue` 内部(`<script setup>` 局部函数,无法被其它组件 import),所以每个直接调 API 的组件都退化成裸 `err.message`。全项目 13 个组件直接调用 `shared/api/client`,其中 12 个没有任何错误码分支。
|
||||
- **代码**:
|
||||
```ts
|
||||
// shared/api/client.ts:143 —— 面向用户的英文文案
|
||||
`AstrBot Plugin Page POST request timed out after ${Math.round(timeoutMs / 1000)} seconds`
|
||||
// :161
|
||||
`AstrBot Plugin Page bridge does not support ${method}`
|
||||
```
|
||||
```ts
|
||||
// AdvancedMaterialImportPage.vue:1355 —— 自己重造一份,丢弃 code/details
|
||||
function errorMessage(err: unknown) {
|
||||
return err instanceof Error ? err.message || "请求失败" : String(err || "请求失败")
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// ProfileWardrobePane.vue:250 / SettingsPage.vue:109,111 / ReviewPolicyPanel.vue:8,9,10 / SystemManagementPanel.vue:8,9,10 / BackupPage.vue:15 / StorageMaintenance.vue:9 ...
|
||||
catch(e){ error.value = e instanceof Error ? e.message : String(e) }
|
||||
```
|
||||
```ts
|
||||
// App.vue:4356 —— 只覆盖 2/8 个错误码,其余仍落到英文原文
|
||||
function readableApiError(err: unknown) {
|
||||
if (err instanceof ApiClientError) {
|
||||
if (err.code === "invalid_api_response") return "接口返回了页面内容或非 JSON 数据..."
|
||||
if (err.code === "network_unreachable") return "无法连接 ImageStudio 后端接口。"
|
||||
return err.message || "ImageStudio 后端接口请求失败。" // bridge_timeout / http_error / bridge_method_unavailable 走这里
|
||||
}
|
||||
```
|
||||
- **影响**:插件桥超时(30 秒 POST / 15 秒 GET,在慢速生图场景很常见)时,设置页、进阶素材页、衣橱模板等处会弹出纯英文的 `AstrBot Plugin Page POST request timed out after 30 seconds`。`details` 里的 `endpoint`/`status`/`url` 等排查信息全部被丢弃,用户和维护者都拿不到可操作线索。
|
||||
- **修复建议**:把 `readableApiError` 提升到 `frontend/shared/api/client.ts` 导出(例如 `export function describeApiError(err: unknown): { message: string; hint?: string }`),补齐 `bridge_timeout`/`bridge_method_unavailable`/`http_error` 的中文分支并把 `details.endpoint` 作为副文本返回;然后用它替换掉全部 18 处内联 catch 和 `AdvancedMaterialImportPage.vue:1355` 的私有副本。
|
||||
|
||||
### [P2-中等] `ProfilesPage` 三层 prop drilling:24 个 props / 13 个 emits,其中 16 个 props 纯透传
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/profiles/ProfilesPage.vue:10-76`、`:121-151`;下游 `ProfileDetailPane.vue:28-82`、`:332-346`;调用点 `frontend/standalone-web/src/App.vue:13336-13374`
|
||||
- **问题**:`ProfilesPage` 自身只使用 `profiles`/`selectedId`/`loading`/`error`/`canWrite`/`backendConnected` 六个 props,其余 18 个(`imageTargets`、`selectedImageId`、`materialCount`、`selectedWorkflowsCount`、`workflowNodeCount`、`selectedAvatarUrl`、`wardrobeItems`、`wardrobeMaterials`、`materialCategories`、`wardrobePermissions`、`wardrobeLoading`、`wardrobeBusy`、`wardrobeError`、`generationBusy`、`generationError`、`deleting` 等)在 `<script>` 中零引用,只在模板里原样往下传。`wardrobe*` 这一组更是穿过两层组件才到达真正的消费者 `ProfileWardrobePane`。emits 同理:`forwardWardrobeAdd` 这个纯转发函数在 `ProfilesPage.vue:78` 和 `ProfileDetailPane.vue:137` 各写了一遍,代码完全相同。
|
||||
- **代码**:
|
||||
```ts
|
||||
// ProfilesPage.vue:78 —— 与 ProfileDetailPane.vue:137 逐字符相同
|
||||
function forwardWardrobeAdd(materialId: string, wardrobeCategory: string) {
|
||||
emit("wardrobeAdd", materialId, wardrobeCategory)
|
||||
}
|
||||
```
|
||||
```html
|
||||
<!-- ProfilesPage.vue:121 —— 21 行里 16 行是透传 -->
|
||||
<ProfileDetailPane
|
||||
:wardrobe-items="wardrobeItems" :wardrobe-materials="wardrobeMaterials"
|
||||
:material-categories="materialCategories" :wardrobe-permissions="wardrobePermissions"
|
||||
:wardrobe-loading="wardrobeLoading" :wardrobe-busy="wardrobeBusy" :wardrobe-error="wardrobeError"
|
||||
... @wardrobe-retry="emit('wardrobeRetry')" @wardrobe-add="forwardWardrobeAdd" @wardrobe-remove="emit('wardrobeRemove', $event)" />
|
||||
```
|
||||
- **影响**:衣橱相关的任何一个新字段(如「常用标记」「排序」)都要在 `App.vue`、`ProfilesPage`、`ProfileDetailPane`、`ProfileWardrobePane` 四处同步修改 props/defaults/emits/模板,共 8 个改动点。`withDefaults` 的默认值也在 `ProfilesPage` 和 `ProfileDetailPane` 里重复声明了两遍(`() => []`、`""`、`false`),两处一旦不一致就会产生难以定位的行为差异。
|
||||
- **修复建议**:把衣橱这一族状态收敛为一个对象 prop(`:wardrobe="{ items, materials, categories, permissions, loading, busy, error }"`),props 数量立刻从 24 降到 ~12;或直接让 `ProfileWardrobePane` 自己按 `profileId` 拉取衣橱数据(它已经在这么做模板部分了,见下一条),彻底断开中间两层的透传链。
|
||||
|
||||
### [P2-中等] `ProfileWardrobePane` 状态归属分裂:衣橱条目走 props/emits,套装模板自己调 API
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/profiles/ProfileWardrobePane.vue:11-37`(props/emits)对比 `:59`、`:151`、`:249-252`(自持状态与 API 调用)
|
||||
- **问题**:同一个组件里存在两套互相矛盾的数据所有权模型。衣橱条目(`wardrobeItems`)、加载态(`loading`/`busy`)、错误(`error`)由父组件持有,增删走 `emit('add')`/`emit('remove')`;而套装模板(`outfitTemplates`)、其加载态(`templateBusy`)、错误(`templateMessage`)由组件自己持有,增删改直接 `getJson`/`postJson`/`deleteJson`。
|
||||
- **代码**:
|
||||
```ts
|
||||
// :59 —— 自持状态,压缩成一行
|
||||
const outfitTemplates=ref<Array<Record<string,unknown>>>([]),templateName=ref(""),templateBusy=ref(false),templateMessage=ref(""),compositionPreview=ref<Record<string,unknown>|null>(null)
|
||||
|
||||
// :151 —— 自己监听 profileId 拉数据
|
||||
watch(()=>props.profileId,()=>{void loadTemplates()},{immediate:true})
|
||||
|
||||
// :249-252 —— 自己写库,父组件完全不知情
|
||||
async function loadTemplates(){...outfitTemplates.value=await getJson(endpoints.wardrobeTemplates(props.profileId))...}
|
||||
async function saveCurrentTemplate(){...await postJson(endpoints.wardrobeTemplates(props.profileId),{name:...,material_ids:props.wardrobeItems.map(item=>item.material_id)})...}
|
||||
async function removeTemplate(templateId:string){...await deleteJson(endpoints.wardrobeTemplate(props.profileId,templateId))...}
|
||||
```
|
||||
另外 `loadTemplates` 的 `catch{outfitTemplates.value=[]}` 完全吞掉错误——权限不足或后端 500 时,用户看到的是「暂无模板」而不是失败提示。
|
||||
- **影响**:`busy`(父级)和 `templateBusy`(自持)互不感知,用户可以在「添加衣橱素材」进行中同时点击「保存当前衣橱」,两个写操作并发命中同一个 profile 的 `metadata`——而后端 `WardrobeService.save_template` 是读-改-写整个 `profile.metadata`(`backend/services/wardrobe_service.py:167`),存在后写覆盖先写的丢更新风险。模板保存后父组件的衣橱数据也不会刷新。
|
||||
- **修复建议**:统一到一侧。推荐让本组件全权负责衣橱域(自己按 `profileId` 拉取 items 和 templates),父组件只传 `profileId` + `permissions`;或反之把 templates 也提到 `App.vue`。同时给 `loadTemplates` 的 catch 加上错误展示,并让 `templateBusy` 与 `props.busy` 合并成一个 `anyBusy` computed 用于禁用所有写按钮。
|
||||
|
||||
### [P2-中等] 焦点陷阱被复制 6 份且实现互不相同,另有 2 个 `aria-modal` 对话框完全没有键盘管理
|
||||
|
||||
- **位置**:
|
||||
- 6 份手写焦点陷阱:`components/ConfirmDialog.vue:50-67`、`components/ImagePreviewDialog.vue:124-141`、`components/MaterialOperationDialog.vue:146-160`、`features/profiles/ProfileWardrobePane.vue:216-238`、`features/workflow/WorkflowCompareDialog.vue:48-59`、`features/workflow/WorkflowGenerationReviewDialog.vue:163-175`
|
||||
- 零键盘管理但声明了 `aria-modal="true"`:`features/workflow/WorkflowMaterialDrawer.vue:149-155`、`features/settings/SettingsPage.vue:131`
|
||||
- **问题**:项目已经有共享的 `safe-backdrop-close.ts` 抽象(背景点击关闭),说明作者知道这类逻辑该提取,但焦点陷阱这块没做。6 份实现分成 3 种行为:`ConfirmDialog` 会检查 `!dialogRef.contains(active)` 从而能把逃逸的焦点拉回来;其余 5 份只比较 `activeElement === first/last`;`WorkflowCompareDialog` 在无可聚焦元素时直接 `return` 不做任何处理,而 `ConfirmDialog`/`ImagePreviewDialog` 会 `preventDefault` 并把焦点还给 dialog。
|
||||
- **代码**:
|
||||
```ts
|
||||
// ConfirmDialog.vue:61 —— 唯一正确处理焦点逃逸的版本
|
||||
if (event.shiftKey && (active === first || !dialogRef.value?.contains(active))) {
|
||||
```
|
||||
```ts
|
||||
// WorkflowGenerationReviewDialog.vue:168 / ImagePreviewDialog.vue:134 / MaterialOperationDialog.vue:153 / ProfileWardrobePane.vue:230 / WorkflowCompareDialog.vue:53 —— 焦点一旦落到 body 就锁不住
|
||||
if (event.shiftKey && document.activeElement === first) {
|
||||
```
|
||||
```html
|
||||
<!-- WorkflowMaterialDrawer.vue:149 —— 没有 @keydown、没有 nextTick focus、没有 Tab 陷阱 -->
|
||||
<aside class="workflow-material-drawer" role="dialog" aria-modal="true" aria-label="节点素材抽屉" :aria-busy="busy">
|
||||
```
|
||||
```html
|
||||
<!-- SettingsPage.vue:131 —— 同样只有 aria 属性,Esc 无效 -->
|
||||
<article ... class="adapter-dialog" role="dialog" aria-modal="true" :aria-label="`${a.name} 配置`">
|
||||
```
|
||||
- **影响**:`aria-modal="true"` 向屏幕阅读器承诺「焦点被限制在此对话框内」。素材抽屉和适配器配置弹窗违背了这个承诺,键盘用户 Tab 几下就会走到被 backdrop 遮住的背景内容上,并且无法用 Esc 关闭。另外 5 个对话框在 busy 态下按钮被 `:disabled` 后当前焦点元素会失焦到 `<body>`,此时 Tab 同样会逃出弹窗。
|
||||
- **修复建议**:把 `ConfirmDialog.vue:41-67` 那份(最完整的)提取为 `standalone-web/src/focus-trap.ts`,导出 `createFocusTrap(dialogRef)` 返回 `{ onKeydown, focusFirst, restore }`,与已有的 `createSafeBackdropClose` 并列。8 处全部改用它,`WorkflowMaterialDrawer` 和 `SettingsPage` 的适配器弹窗补上 `@keydown` 绑定。
|
||||
|
||||
### [P2-中等] 生成状态中文标签在 3 处重复定义且译法互相冲突
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:6927-6939`、`frontend/standalone-web/src/features/workflow/WorkflowCandidatePool.vue:132-145`、`frontend/standalone-web/src/features/workflow/WorkflowRoundPanel.vue:113-129`;另有基础版在 `frontend/shared/utils/presentation.ts:11-29`
|
||||
- **问题**:同一批后端状态码在四个地方各建一张映射表,且译法不一致。
|
||||
- **代码**:
|
||||
```ts
|
||||
// App.vue:6927
|
||||
const labels: Record<string, string> = {
|
||||
planned: "已规划", queued: "排队中", running: "生成中",
|
||||
succeeded: "已成功", success: "已成功", completed: "已成功",
|
||||
failed: "失败", cancelled: "已取消",
|
||||
} // 缺 retrying / dead_letter,落到 `|| status` 显示英文原文
|
||||
```
|
||||
```ts
|
||||
// WorkflowCandidatePool.vue:133 —— 同样的 candidate.generation_status,不同译法
|
||||
const labels: Record<string, string> = {
|
||||
planned: "待入队", queued: "排队中", running: "生成中", retrying: "重试中",
|
||||
succeeded: "已完成", failed: "生成失败", dead_letter: "重试耗尽", cancelled: "已取消",
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// presentation.ts:11 —— 第四份,供任务队列使用
|
||||
succeeded: "已成功", dead_letter: "死信", retrying: "重试执行中", superseded: "已被重试替代",
|
||||
```
|
||||
- **影响**:同一个候选在候选池里显示「已完成」,在 App.vue 的其它视图(如工作流概览、对比弹窗标题)里显示「已成功」,在队列页显示「已成功」;`planned` 更是「待入队」和「已规划」两种说法。用户会误以为是不同状态。`App.vue` 那份还缺 `retrying`/`dead_letter`,重试中的候选会直接显示英文 `retrying`。
|
||||
- **修复建议**:在 `frontend/shared/utils/presentation.ts` 增加 `export function generationStatusLabel(status: string)` 作为唯一真源,覆盖 `planned|queued|running|retrying|succeeded|success|completed|failed|dead_letter|cancelled|superseded`,删掉 App.vue、WorkflowCandidatePool、WorkflowRoundPanel 里的三份局部表(`WorkflowRoundPanel` 的轮次级状态 `partial_success|all_failed|confirmed` 可另建 `roundStatusLabel` 一并放入)。
|
||||
|
||||
### [P2-中等] `WorkflowDependencyContextCard.vue`(279 行)已成为无引用的死组件
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/workflow/WorkflowDependencyContextCard.vue`(整个文件)
|
||||
- **问题**:全仓库(排除 `node_modules`、构建产物)搜索 `WorkflowDependencyContextCard`,除文件自身外零命中。而 `App.vue` 仍在维护对应的数据链路:`workflowDependencyContextByNodeId`(`:792`)、`workflowDependencyContextLoadingId`(`:793`)、`workflowDependencyContextError`(`:794`)、`loadWorkflowDependencyContext()`(`:6894`),并在 `:4129`、`:7214`、`:8324` 三处触发加载——数据被拉取了,但展示组件不再被挂载,改由 App.vue 内联渲染。
|
||||
- **代码**:
|
||||
```ts
|
||||
// WorkflowDependencyContextCard.vue:9-26 —— 完整的 props/emits 定义,无人调用
|
||||
const props = withDefaults(defineProps<{
|
||||
context?: WorkflowNodeDependencyContext | null
|
||||
loading?: boolean; error?: string; locked?: boolean
|
||||
}>(), { context: null, loading: false, error: "", locked: false })
|
||||
const emit = defineEmits<{ refresh: [] }>()
|
||||
```
|
||||
旁证:`git status` 显示构建产物 `web/assets/WorkflowDependencyContextCard-CVx_4GIk.js` 与 `pages/imagestudio/assets/WorkflowDependencyContextCard-Da-Ez1_X.js` 已被删除,说明最近一次重构把它从 App.vue 的模板里摘掉了,但源文件被遗留。
|
||||
- **影响**:279 行代码 + 对应的 scoped CSS 会误导后续维护者以为依赖上下文卡片有独立组件可复用,实际改它不产生任何效果。`vue-tsc --noEmit` 仍会检查它,拖慢类型检查。
|
||||
- **修复建议**:确认 App.vue 内联版本已完全覆盖其功能后删除该文件;若打算复用,则把 App.vue 里内联的依赖上下文渲染换回该组件,并把三个 `workflowDependencyContext*` ref 通过 props 传入。
|
||||
|
||||
### [P3-轻微] `GalleryPage` 批量操作串行执行且完全吞掉错误,用户只看到一个无解释的数字
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/gallery/GalleryPage.vue:115-123`
|
||||
- **问题**:`runBatch` 用 `for...of` 串行 `await` 每一张图的请求,且 `catch{}` 里没有任何记录,最终只把成功计数拼进文案。
|
||||
- **代码**:
|
||||
```ts
|
||||
for(const id of ids){try{if(action==="select")await postJson(endpoints.imageSelect(id));...else await postJson(endpoints.imageSafeDelete(id),{dry_run:false,delete_files:false});success++}catch{/* keep remaining items running */}}
|
||||
actionMessage.value=`已处理 ${success}/${ids.length} 张图片`;checkedIds.value=[];actionBusy.value=false;emit("refresh")
|
||||
```
|
||||
- **影响**:选中 50 张执行「安全删除」,若因引用检查全部失败,用户看到的是「已处理 0/50 张图片」,没有任何原因(后端安全删除会返回引用冲突详情,全被丢弃)。串行 50 次请求在插件桥模式下每次最多 30 秒超时,最坏情况阻塞 25 分钟且无进度反馈。此外 `checkedIds` 被无条件清空,用户无法只重试失败的那些。
|
||||
- **修复建议**:收集失败项 `const failures: Array<{id: string; reason: string}> = []`,用 `Promise.allSettled` 配合并发上限(如 5)替代串行循环,结束后把失败 id 保留在 `checkedIds` 里并在 `actionMessage` 里展示前几条原因。
|
||||
|
||||
### [P3-轻微] `browserImageUrl` / 图片 URL 白名单校验被复制 4 份,衣橱分类标签被复制 2 份且函数名与共享导出冲突
|
||||
|
||||
- **位置**:
|
||||
- URL 校验:`features/profiles/profile-ui.ts:155`(`isBrowserImageUrl`)、`features/workflow/WorkflowCandidatePool.vue:165`、`features/workflow/WorkflowGenerationReviewDialog.vue:97`、`features/profiles/ProfileWardrobePane.vue:189`(`materialThumbnail` 内联)
|
||||
- 分类标签:`features/profiles/ProfileWardrobePane.vue:40-46` 对比 `standalone-web/src/material-labels.ts:30-39`
|
||||
- **问题**:完全相同的正则 `/^(?:https?:|data:|blob:|\/)/i` 出现在 4 个文件里;`top/bottom/dress/shoes/accessory` 五条中文标签在 `ProfileWardrobePane` 的 `WARDROBE_CATEGORY_LABELS` 和 `material-labels.ts` 的 `MATERIAL_CATEGORY_LABELS` 各存一份。更糟的是 `ProfileWardrobePane.vue:158` 定义了一个局部函数 `materialCategoryLabel(material: Material)`,与 `material-labels.ts` 导出的 `materialCategoryLabel(value: unknown)` 同名但签名和语义都不同(一个吃 Material 对象,一个吃字符串)。
|
||||
- **代码**:
|
||||
```ts
|
||||
// ProfileWardrobePane.vue:41 —— 与 material-labels.ts:31-35 五条完全重合
|
||||
const WARDROBE_CATEGORY_LABELS: Readonly<Record<string, string>> = {
|
||||
top: "上装", bottom: "下装", dress: "连衣裙", shoes: "鞋履", accessory: "配饰",
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// ProfileWardrobePane.vue:158 —— 与共享导出同名不同义
|
||||
function materialCategoryLabel(material: Material | undefined) { ... }
|
||||
```
|
||||
```ts
|
||||
// material-labels.ts:42
|
||||
export function materialCategoryLabel(value: unknown) { ... }
|
||||
```
|
||||
- **影响**:新增衣橱分类(例如 `outerwear`)需要改两个文件;`material-labels.ts` 已经有 `outfit`、`style`、`composition` 三条而 `ProfileWardrobePane` 没有,导致同一分类在素材库显示中文、在衣橱显示英文 key。同名函数会让 IDE 的「跳转到定义」和后续 import 产生歧义。
|
||||
- **修复建议**:把 URL 白名单校验提到 `frontend/shared/utils/presentation.ts`(或新建 `shared/utils/media-url.ts`)导出 `isBrowserImageUrl`,4 处统一引用;`ProfileWardrobePane` 删除 `WARDROBE_CATEGORY_LABELS` 改用 `materialCategoryLabel`,并把局部的 `materialCategoryLabel(material)` 改名为 `materialCategoryName(material)` 消除冲突。
|
||||
|
||||
### [P3-轻微] `package.json` 声明了零使用的 `pinia` / `vue-router`,且构建工具全在 `dependencies`、`devDependencies` 为空
|
||||
|
||||
- **位置**:`frontend/package.json:16-25`
|
||||
- **问题**:全仓库搜索 `pinia`、`vue-router`、`createRouter`、`defineStore`,在 `frontend/` 源码(排除 `node_modules`)中零命中——路由由 `App.vue` 的 `activeNav` + `navigation-config.ts` 自己实现,状态管理靠 `ref`/`computed`。同时 `typescript`、`vite`、`vue-tsc`、`@vitejs/plugin-vue` 这些纯构建期依赖被放进 `dependencies`,而 `devDependencies` 是空对象。
|
||||
- **代码**:
|
||||
```json
|
||||
"dependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"pinia": "^2.3.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-router": "^4.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
},
|
||||
"devDependencies": {}
|
||||
```
|
||||
- **影响**:`npm ci --omit=dev` 在 CI/发布环境下不会减少任何体积;`pinia`/`vue-router` 会误导新维护者以为项目有 store 和路由体系,从而按错误的假设写代码(这也间接解释了 App.vue 为何膨胀到 22563 行——没有 store 层可放业务状态)。
|
||||
- **修复建议**:删除 `pinia` 和 `vue-router`;把 `@vitejs/plugin-vue`、`typescript`、`vite`、`vue-tsc` 移到 `devDependencies`,`dependencies` 只保留 `vue`。
|
||||
|
||||
### [P3-轻微] `frontend/shared/types/` 与后端 DTO 全靠人工同步,无契约测试兜底
|
||||
|
||||
- **位置**:`frontend/shared/types/workflow-round.ts:88-121` 对比 `backend/dto/workflow_round_dto.py:50-115`;`frontend/shared/types/profile.ts:3-21` 对比 `backend/dto/profile_dto.py:32-54`;`frontend/tests/*.test.mjs`(8 个文件,无一做类型/字段比对)
|
||||
- **问题**:逐字段核对后,当前**没有发现实际漂移**——`WorkflowGenerationCandidate` 的 15 个字段、`WorkflowRoundCandidatePoolEntry` 的 11 个字段、`CharacterProfile` 的可选字面量联合(`detailed_workflow_state: "in_progress" | "ready_to_archive" | "archived" | null`)与 `database/repositories/profile_repository.py:85-115` 的 SQL `CASE` 取值都精确对应。问题在于这种对齐纯靠人工纪律维持:`endpoints.contract` 端点存在但前端没有任何测试消费它,8 个前端测试全是字符串包含断言(`production-data-boundary`、`ui-theme-contract` 等),没有一个校验类型定义。
|
||||
- **代码**:
|
||||
```py
|
||||
# backend/dto/workflow_round_dto.py:102 —— 后端真源
|
||||
"display_index": self.display_index, "display_code": self.display_code,
|
||||
"pool_state": self.pool_state, "preference_status": self.preference_status,
|
||||
"preference_reason": self.preference_reason, "is_final": self.is_final,
|
||||
```
|
||||
```ts
|
||||
// shared/types/workflow-round.ts:106 —— 手工镜像,无生成、无校验
|
||||
export interface WorkflowRoundCandidateView {
|
||||
round_id: string; candidate_id: string; display_index: number; display_code: string
|
||||
pool_state: string; preference_status: WorkflowCandidatePreference | string
|
||||
preference_reason?: string | null; is_final: boolean
|
||||
```
|
||||
- **影响**:后端 DTO 增删字段时 TypeScript 不会报错(多出的字段被静默忽略,删除的字段在运行时变 `undefined` 而类型上仍是 `string`)。例如 `WorkflowCandidatePool.vue:129` 的 `String(candidate.candidate.generation_status || "planned")` 已经在用防御性写法兜底,说明团队对此有隐忧但没有系统性解法。风险随 DTO 数量增长而累积(`backend/dto/` 下已有多个模块)。
|
||||
- **修复建议**:加一个 node 测试,读取 `backend/dto/*.py` 中每个 `to_dict` 的字面量 key 集合,与 `frontend/shared/types/*.ts` 对应 interface 的字段名集合做双向差集断言(正则提取即可,不需要真正解析 AST)。放进 `frontend/tests/dto-contract.test.mjs`,纳入 `npm run test:contracts`。
|
||||
|
||||
### [P3-轻微] 多个功能文件被压成单行,等同于把源码当构建产物维护
|
||||
|
||||
- **位置**:`features/gallery/GalleryPage.vue:113-122`、`:214`;`features/settings/SettingsPage.vue:41-42`、`:79-111`、`:126-153`、`:160-167`;`features/profiles/ProfileWardrobePane.vue:59`、`:249-252`、`:305`
|
||||
- **问题**:这些不是构建产物(它们在 `frontend/standalone-web/src/` 源码树内、有 `<script setup lang="ts">`),而是被手工去掉换行和空格的源码。`SettingsPage.vue:98` 的 `saveAndProbeAdapter` 单行长度超过 2000 字符,内含 3 次 await、2 个循环、1 个 try/catch 和 6 个条件分支。
|
||||
- **代码**:
|
||||
```ts
|
||||
// GalleryPage.vue:113 —— 与同文件 :99-111 的正常缩进风格并存
|
||||
function toggleChecked(imageId:string){checkedIds.value=checkedIds.value.includes(imageId)?checkedIds.value.filter(id=>id!==imageId):[...checkedIds.value,imageId]}
|
||||
```
|
||||
```ts
|
||||
// ProfileWardrobePane.vue:59 —— 与同文件 :48-57 的每行一个 ref 风格并存
|
||||
const outfitTemplates=ref<Array<Record<string,unknown>>>([]),templateName=ref(""),templateBusy=ref(false),templateMessage=ref(""),compositionPreview=ref<Record<string,unknown>|null>(null)
|
||||
```
|
||||
- **影响**:`git blame`/`git diff` 在这些行上完全失效——改一个字符就是整行重写,code review 无法定位实际变更。`SettingsPage.vue:98` 这样的巨型单行里藏着本文档第 3 条那个凭据落盘缺陷,正是因为它被压成一行才长期未被发现。同一文件内两种排版风格并存,说明是后续增量修改时的临时做法固化了下来。
|
||||
- **修复建议**:对这 3 个文件跑一次 Prettier/ESLint --fix 展开(项目当前没有 formatter 配置,可先加 `.prettierrc` 约定 `printWidth: 120`),单独提一个纯格式化 commit 以免污染后续 blame。
|
||||
|
||||
---
|
||||
|
||||
## 附:确认无问题的项
|
||||
|
||||
- **`plugin-page` 与 `standalone-web` 无代码重复**。`frontend/plugin-page/src/App.vue` 全文 7 行,只做 `import WorkbenchApp from "../../standalone-web/src/App.vue"` 后转发;两个 `vite.config.ts` 仅 `base` 和 `outDir` 不同(`/api/v1/plugins/.../web/` → `web/`,`./` → `pages/imagestudio/`);`main.ts` 唯一差异是 plugin 版多调一次 `installAstrBotPluginPageBridge()`。这是正确的双产物单源码架构,不应因为构建产物目录看起来"重复"而误判。
|
||||
- **`shared/api/client.ts` 的传输层抽象设计合理**。插件桥/直连 fetch 双通道自动探测、`PUT`/`PATCH`/`DELETE` 在桥不支持时降级为带 `__imagestudio_method` 的 POST、长任务端点正则匹配延长超时、`unwrapApiResponse` 的 4 层嵌套解包上限,这些都考虑得比较周全。问题只出在错误**呈现**层(见 P2 那条),不在传输层本身。
|
||||
- **`WorkflowCandidatePool.vue`(952 行)是本次审计中质量最高的组件**。props 全部只读、零 API 调用、状态派生用 computed、`mutationLocked`/`viewLocked` 两级锁语义清晰、`likedDisabled`/`compareDisabled`/`finalDisabled` 三个约束函数各司其职。可作为其它 workflow 组件重构的参照。
|
||||
712
审计/findings/B1-前后端耦合.md
普通文件
712
审计/findings/B1-前后端耦合.md
普通文件
|
|
@ -0,0 +1,712 @@
|
|||
# B1 · 前后端耦合
|
||||
|
||||
> 审计范围(实际读过的文件):
|
||||
>
|
||||
> **后端**:`main.py`、`backend/route_registry.py`、`backend/services/contract_service.py`、`backend/services/ui_service.py`、`backend/services/web_hosting_service.py`、`backend/services/workflow_progression_service.py`、`backend/services/workflow_round_service.py`、`backend/services/queue_service.py`、`backend/services/generation_service.py`、`backend/services/node_injection_template_service.py`、`backend/services/event_stream_service.py`、`backend/services/image_service.py`、`backend/services/advanced_style_set_service.py`、`backend/routes/{contract,api_discovery,node,node_material,round,profile,image,advanced_material,event,job}_routes.py`、`backend/dto/{common,workflow,workflow_round,profile,job,image,advanced_material}_dto.py`、`core/model_route_chain.py`、`core/config_service.py`、`core/security.py`、`core/event_bus.py`、`engines/character_flow.py`、`database/repositories/profile_repository.py`、`adapters/astrbot_adapter.py`
|
||||
>
|
||||
> **前端**:`frontend/shared/api/{endpoints,client,astrbot-page-bridge}.ts`、`frontend/shared/config/timeouts.ts`、`frontend/shared/utils/{presentation,storage-uri}.ts`、`frontend/shared/types/{api,bootstrap,profile,workflow,workflow-round,job,image,advanced-material}.ts`、`frontend/standalone-web/src/App.vue`、`frontend/standalone-web/src/features/workflow/{workflow-lock-state,workflow-model-route,workflow-node-catalog}.ts`、`frontend/standalone-web/src/features/workflow/WorkflowCandidatePool.vue`、`frontend/standalone-web/src/features/materials/advanced-material-state.ts`、`frontend/standalone-web/src/features/settings/{SystemManagementPanel.vue,model-route-chain.ts}`、`frontend/{plugin-page,standalone-web}/vite.config.ts`、`frontend/package.json`、`frontend/tests/*.test.mjs`
|
||||
>
|
||||
> **已按要求忽略**:`.tmp/`、`.tmp_pytest_*`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`(仅在"构建产物入库"一节中作为 git 事实引用,未读其内容)
|
||||
|
||||
## 摘要
|
||||
|
||||
**URL 层面的耦合治理是这个仓库做得最好的部分**:`backend/route_registry.py` 是 166 条路由的唯一真相来源(`adapters/astrbot_adapter.py:44` 的 `resolve_route` 直接消费它),前端 143 个端点全部集中在 `frontend/shared/api/endpoints.ts`,逐条比对后**零个前端调用会 404**,也**几乎没有绕过 endpoints.ts 的硬编码 URL**(表 ③ 只有 vite base 一条)。这一维度可以给高分。
|
||||
|
||||
**问题全部集中在"语义契约"层**:URL 对上了,但 URL 背后的规则没对上。前端在 `App.vue`、`workflow-lock-state.ts`、`workflow-model-route.ts` 里重新实现了后端的顺序进度状态机、节点写锁规则、模型路由解析链、队列状态枚举和 retry 权限矩阵——每一处都与后端存在可举证的不一致(`sealed_at` 后端根本不产出;节点写锁少判两个条件;快速角色流的路由优先级后端是反的;retry 按钮漏判 `can_write`)。后端明明有 `character_gradual_progression().to_dict()`、`PERMISSION_MATRIX`、`ContractService` 这些"可下发的真相",却没有一条路由把它们送到前端,前端只能靠复刻。
|
||||
|
||||
`GET contract` 已提供完整的路由 + 权限 + 错误码自检数据,但前端唯一的消费点是 `SystemManagementPanel.vue:8` 的一个 JSON dump 诊断框,**没有任何自动化测试拿它做契约校验**——而这恰恰是最低成本、最高收益的修复方向(我实测 166 条路由的 handler 全部可导入,做成 CI 断言只需十几行)。
|
||||
|
||||
另外,`web/` 与 `pages/imagestudio/` 两份 1.1MB 的 vite dist 产物被提交进 git,80 次提交里每次改一行 UI 源码都会带上一批内容哈希文件名的增删,这是耦合与仓库卫生的双重问题。
|
||||
|
||||
---
|
||||
|
||||
## 一、路由比对三张表
|
||||
|
||||
### 表 ① 后端注册但前端从不调用(死接口)
|
||||
|
||||
比对方法:从 `backend/route_registry.py:55-342` 提取 166 条 `RouteSpec`,与 `endpoints.ts` 143 个键 + 全前端 `endpoints.<key>` 引用做交叉。
|
||||
|
||||
| # | 方法 | 端点 | 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` | 死。见 P1-6 |
|
||||
| 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`),**不算死接口**。
|
||||
|
||||
其中 #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)
|
||||
```
|
||||
|
||||
### 表 ② 前端调用但后端不存在(会 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/"` | 真实重复,见 P2-13 |
|
||||
| `frontend/shared/api/astrbot-page-bridge.ts:119-120` | `request<T>("api:get" ...)` | 误报,是 postMessage 的 kind 常量,不是 HTTP 路径 |
|
||||
|
||||
除此之外全前端**没有任何**业务组件直接拼 API 路径:所有 `getJson/postJson/putJson/deleteJson` 的第一参数都来自 `endpoints.*`,`buildUrl` 是唯一的 URL 构造点(`client.ts:297-306`)。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] 前端复刻了后端的顺序进度状态机,且后端从不下发权威结果
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:10836-10861`,对应后端 `backend/services/workflow_progression_service.py:175-199`
|
||||
- **问题**:后端 `is_character_gradual_node_completed()` 是"节点是否已完成"的唯一权威判定,包含 status 白名单、node_type 特例、profile_card 别名归一、legacy 元数据兼容四层规则。前端逐条重写了这四层,连"legacy 兼容只对没有 sequential-v1 标记的工作流生效"这种极细的分支都手工复刻,并把版本号字面量抄进了 `App.vue:927`。
|
||||
- **代码**:
|
||||
|
||||
后端:
|
||||
```python
|
||||
# backend/services/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
|
||||
```
|
||||
|
||||
前端(同一套规则,第二份实现):
|
||||
```ts
|
||||
// frontend/standalone-web/src/App.vue:10843-10859
|
||||
const status = normalizeStatus(backendNode.status)
|
||||
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 execution = selectedCharacterWorkflow.value?.metadata?.character_execution
|
||||
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
|
||||
```
|
||||
```ts
|
||||
// frontend/standalone-web/src/App.vue:927
|
||||
const CHARACTER_WORKFLOW_PROGRESSION_VERSION = "character_gradual_sequential_v1"
|
||||
```
|
||||
|
||||
根因是后端从不下发进度:
|
||||
```python
|
||||
# backend/routes/node_routes.py:52-63 —— 只返回裸节点数组,无 progression
|
||||
def action() -> list[dict[str, Any]]:
|
||||
require_authenticated(ctx)
|
||||
return [node.to_dict() for node in workflow_service.list_nodes(workflow_id)]
|
||||
```
|
||||
全仓库 `progression.to_dict()` 只有一个调用点:`backend/services/character_workflow_service.py:339`(`execute-character` 的响应体),列表接口拿不到。
|
||||
- **影响**:后端改一条进度规则(例如给 `style_lock` 加一个完成条件、或让 `skipped` 不再算完成),前端不会报错也不会失效,只会静默地在"下一步应该点哪个节点"上给出与服务端相反的答案:UI 显示节点可用 → 用户点击 → 后端 `ensure_character_gradual_node_access` 抛 `character_gradual_progression_locked`。反之 UI 灰掉一个后端允许的节点,用户彻底卡死且无提示。前端还有一份 `execution.progression_version` 的降级分支,等于把后端的向后兼容策略也复制了一份,双份都要维护。
|
||||
- **修复建议**:
|
||||
1. 在 `list_workflow_nodes` 返回体外层加 `progression` 字段(`CharacterGradualProgression.to_dict()` 已经现成,含 `current_node_id`/`completed_node_ids`/`all_completed`/`import_confirmed`):
|
||||
```python
|
||||
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,
|
||||
}
|
||||
```
|
||||
(返回结构变更需同步 `frontend/shared/types/workflow.ts` 并升 `contract_version`)
|
||||
2. 删除 `App.vue:10836-10861` 与 `App.vue:927`,改为 `progression.completed_node_ids.includes(node.node_id)` / `node.node_id === progression.current_node_id`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 节点写锁规则前后端不一致,且前端判据里有一个后端从不产出的字段
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27`,对应后端 `backend/services/workflow_round_service.py:1145-1155`
|
||||
- **问题**:两条独立的"这个节点还能不能写"规则,条件集合不同;前端多判了一个不存在的字段,少判了两个真实条件。
|
||||
- **代码**:
|
||||
|
||||
前端:
|
||||
```ts
|
||||
// frontend/standalone-web/src/features/workflow/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) // ← sealed_at
|
||||
)
|
||||
}
|
||||
export function isWorkflowNodeWriteLocked(nodeStatus, workflowStatus, workflowMetadata) {
|
||||
return normalizedStatus(nodeStatus) === "selected" || isWorkflowSealed(workflowStatus, workflowMetadata)
|
||||
}
|
||||
```
|
||||
|
||||
后端:
|
||||
```python
|
||||
# backend/services/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"})
|
||||
```
|
||||
|
||||
`sealed_at` 在整个 Python 源码树(`main.py`/`backend/`/`core/`/`database/`/`engines/`/`adapters/`)**零匹配**——`grep -rn "sealed_at" --include=*.py` 返回空。它只存在于前端和前端测试里。
|
||||
- **影响**:三处真实分歧。
|
||||
1. `node.selected_image_id` 已设但 `status != "selected"` 时(例如 `adopt-image` 后 status 仍为 `completed`),前端认为可写并放行"再跑一轮",后端返回 `VALIDATION_FAILED / required_action: create_branch`,用户看到一个无法自恢复的报错。
|
||||
2. 节点已进入 `progression.completed_node_ids`(通过 `skipped` 或 planning 节点 `completed`)时同理。
|
||||
3. `metadata.sealed_at` 是一个永远为 `undefined` 的死判据,给读代码的人制造"存在这个封存机制"的错觉。而 `frontend/tests/workflow-model-route.test.mjs` 只断言 `final_archive_history_id` 分支,`sealed_at` 连测试都没覆盖。
|
||||
- **修复建议**:把锁状态改为服务端下发而非客户端推导。最小改动是在 `WorkflowNode.to_dict()` 增加 `writable: bool` 与 `lock_reason: str | None`(`backend/services/workflow_node_material_service` 返回的 `WorkflowNodeMaterialBindingDetail` 已经有 `writable` + `lock` 结构,直接复用同一形状即可,见 `frontend/shared/types/workflow.ts:108-123`);前端 `workflow-lock-state.ts` 退化为读 `node.writable`。若暂不改协议,至少立刻删掉 `sealed_at`,并补上 `selected_image_id` 判据。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 模型路由解析链在前端重实现,优先级与后端不一致(快速角色流方向相反)
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/workflow/workflow-model-route.ts:33-88` + `App.vue:2211-2245`,对应后端 `backend/services/generation_service.py:167-176`、`605-643`、`2022-2044`
|
||||
- **问题**:前端为了显示"当前生效模型 / 来源标签",把后端的整条路由回退链复刻了一遍——包括 `node_key → model_assignments` 键的映射表——并且直接读取原始配置文件结构 `config.model_assignments` / `config.generation.default_model`。三处不一致。
|
||||
- **代码**:
|
||||
|
||||
后端普通节点(`generation_service.py:169-176`):
|
||||
```python
|
||||
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")
|
||||
```
|
||||
后端**快速角色**节点(`generation_service.py:617-624`)—— 优先级反转,`assigned_route` 抢在 `payload.model_route` 之前:
|
||||
```python
|
||||
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")
|
||||
```
|
||||
前端(唯一一条链,多了 `round` 层,少了 `"image_low"` 兜底,没有 quick_character 分支):
|
||||
```ts
|
||||
// frontend/standalone-web/src/features/workflow/workflow-model-route.ts:36-48
|
||||
const candidates: Array<[WorkflowModelRouteSource, unknown]> = [
|
||||
["override", input.overrideRoute], ["round", input.roundRoute],
|
||||
["node", input.nodeRoute], ["assignment", input.assignmentRoute],
|
||||
["profile", input.profileRoute], ["system", input.systemRoute],
|
||||
]
|
||||
for (const [source, value] of candidates) {
|
||||
const route = normalizeWorkflowModelRoute(value)
|
||||
if (route) return { route, source, explicitOverride: source === "override" }
|
||||
}
|
||||
return { route: "", source: "backend", explicitOverride: false }
|
||||
```
|
||||
前端自带的第二份 `node_key → assignment` 映射(`workflow-model-route.ts:61-84`)与后端 `generation_service.py:2026-2038` 也不同步:后端有 `quick_avatar/quick_bust/quick_stand/quick_sheet → "quick_generation"`、`questionnaire`、`preview`,前端一个都没有;前端多了 `portrait/avatar/standing/three_view/character_sheet/halfbody/fullbody` 七个后端不认识的别名。
|
||||
- **影响**:
|
||||
1. **快速角色流的模型标签会直接说谎**:用户设了本次覆盖,UI 显示"本次覆盖 → route-X",后端实际按 `assigned_route` 出图。
|
||||
2. 对 `quick_*` 节点,`workflowModelAssignmentKey("quick_avatar","generation")` 返回 `"quick_avatar"`(fallback 到 `canonical`),去 `model_assignments` 里查不到,UI 显示"角色默认/系统默认",后端实际用 `quick_generation` 分配的路由。
|
||||
3. 前端读取的是**配置文件的原始结构**(`currentSettings.value.config.model_assignments`、`config.generation.default_model`,`App.vue:2218/2231-2233`),后端换个配置键名前端就静默失准。
|
||||
- **修复建议**:新增 `GET nodes/{node_id}/effective-model-route`,或在 `nodeDependencyContext` 响应里加 `{ effective_model_route, source }`,由 `generation_service` 抽出一个纯函数 `resolve_model_route(node, workflow, profile, assignments, default)` 同时供生成路径与该端点调用。前端 `resolveWorkflowModelRoute` 只保留"用户 override 是否非空"的判断,其余全部读服务端字段。同时删除 `workflow-model-route.ts:61-84` 的别名/分配表。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] retry 类操作的前端权限门禁漏判 `can_write`,而后端要求两个权限
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:2786` + `3076` + `3139`,对应 `backend/route_registry.py:22-27` 与 `core/security.py:31-33`
|
||||
- **问题**:`route_registry` 已经把 retry 定义为**复合权限**并通过 `GET contract` 对外发布,前端却只判了其中一个。
|
||||
- **代码**:
|
||||
|
||||
后端权限矩阵(`backend/route_registry.py:22-27`):
|
||||
```python
|
||||
"retry": {
|
||||
"auth_required": True,
|
||||
"required_permission": "can_retry_tasks",
|
||||
"required_permissions": ["can_write", "can_retry_tasks"],
|
||||
"description": "task retry management (write + retry capabilities)",
|
||||
},
|
||||
```
|
||||
```python
|
||||
# core/security.py:31-33
|
||||
def require_task_retry(ctx: RequestContext) -> None:
|
||||
require_write(ctx) # ← 先判 can_write
|
||||
require_permission(ctx, "can_retry_tasks")
|
||||
```
|
||||
前端节点重试按钮(`App.vue:2786`、`3073-3077`):
|
||||
```ts
|
||||
const canRetry = Boolean(permissions?.can_retry_tasks)
|
||||
...
|
||||
state: canRetry ? "可重试" : "无权限",
|
||||
tone: canRetry ? "warn" : "neutral",
|
||||
enabled: Boolean(canRetry && !selectedNodeWriteLocked && !workflowNodeActionExecuting.value),
|
||||
```
|
||||
同文件 `3373` 处的队列面板反而判对了(`const canManageQueue = canWrite && canRetry`),说明这是遗漏而非有意设计。
|
||||
- **影响**:持有 `can_retry_tasks` 但无 `can_write` 的账号,在工作流面板看到"可重试"的可用按钮(`portrait-retry` 卡片与 `3139` 处的同类卡片),点击后 `nodes/{id}/retry` 与 `nodes/{id}/generate` 一律被 `require_write` 拒为 `FORBIDDEN`。同一份权限模型在同一个文件里出现两种实现,说明这类漏判还会再犯。
|
||||
- **修复建议**:不要在前端逐个手写权限组合。`GET contract` 返回的 `routes[].required_permissions` 已经是完整数组,在 bootstrap 之后拉一次 contract,构造 `canCall(endpointKey)` 工具函数,所有按钮的 `enabled` 统一走它:
|
||||
```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])
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 编译产物 `web/` 与 `pages/imagestudio/` 被提交进 git,且是两份重复的 dist
|
||||
|
||||
- **位置**:`frontend/standalone-web/vite.config.ts:12-15`、`frontend/plugin-page/vite.config.ts:12-15`、`backend/services/web_hosting_service.py:14-17`、`.gitignore`
|
||||
- **问题**:两个 vite 构建把产物直接写进受版本控制的目录,且 `emptyOutDir: true`,每次构建都会整批删除并重建内容哈希文件名。`.gitignore` 忽略了 `frontend/**/dist/`,却没有忽略这两个实际的输出目录。
|
||||
- **代码**:
|
||||
```ts
|
||||
// frontend/standalone-web/vite.config.ts:9-15
|
||||
base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
|
||||
build: { outDir: resolve(rootDir, "../../web"), emptyOutDir: true },
|
||||
```
|
||||
```ts
|
||||
// frontend/plugin-page/vite.config.ts:11-15
|
||||
base: "./",
|
||||
build: { outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true },
|
||||
```
|
||||
```python
|
||||
# backend/services/web_hosting_service.py:14-15
|
||||
PLUGIN_PAGE_DIR = REPO_ROOT / "pages" / "imagestudio"
|
||||
STANDALONE_WEB_DIR = REPO_ROOT / "web"
|
||||
```
|
||||
两份 dist 内容同源——`frontend/plugin-page/src/App.vue` 全文只有:
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import WorkbenchApp from "../../standalone-web/src/App.vue"
|
||||
</script>
|
||||
<template><WorkbenchApp /></template>
|
||||
```
|
||||
git 事实:`git ls-files web/ pages/` = 38 个文件,`du -sh` 各 1.1MB;`git log --oneline -- web/assets | wc -l` = **80 次提交**;最近 15 次改 `frontend/standalone-web/src/App.vue` 的提交**每一次**都同时改了 `web/assets` 与 `pages/imagestudio/assets`。
|
||||
- **影响**:
|
||||
1. **每个 UI 改动的 diff 被 2MB 二进制级噪音淹没**,code review 无法看清真实变更;`git status` 首屏就是二十多行 `D web/assets/...`。
|
||||
2. **产物与源码可能不同步**:目前没有任何 CI 校验 `web/` 是当前 `frontend/` 的构建结果。一个只改源码忘记 build 的提交,会让线上跑的仍是旧 JS,而 `WebHostingService.manifest()` 只检查 `index.html` 是否存在(`web_hosting_service.py:33/38`),报告 `built: true`,无法发现版本错位。
|
||||
3. 内容哈希文件名 + `emptyOutDir` 让每次构建产生全新路径,git 历史里累积了大量永不复用的 blob,仓库体积单向膨胀。
|
||||
4. 两份 dist 意味着**任何 UI 修复都必须记得跑两次构建**,漏一次就出现"插件页正常、独立页是旧版"的诡异现象——git 历史里 `fix: recover material library after stale asset token`、`fix: load material library page without expiring asset chunk` 两条修复正是这一类症状。
|
||||
- **修复建议**:
|
||||
1. `.gitignore` 增加 `/web/` 与 `/pages/imagestudio/`(保留 `.gitkeep`),`git rm -r --cached web pages/imagestudio`。
|
||||
2. 发布流程改为 CI 构建 + 打包进 release artifact;仓库只保留源码。若插件分发形态要求产物随包,则用一次性的 release 分支/tag 承载,不进主干历史。
|
||||
3. 若因 AstrBot 插件安装方式**必须**保留产物在主干,则退而求其次:加一条 CI 检查 `npm run build && git diff --exit-code web pages`,保证产物永远与源码一致;并把两个 vite 配置合并为一次构建两个 base(或让 plugin-page 直接复用 standalone 产物),消除"两份 dist"。
|
||||
4. `WebHostingService.manifest()` 增加一个来自构建时注入的 `build_hash`,与 `metadata.yaml` 版本比对,让版本错位可被观测。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `events/stream` 无游标:后端把 SSE 载荷塞进 JSON,前端 5 秒轮询 20 条,事件会静默丢失
|
||||
|
||||
- **位置**:`backend/services/event_stream_service.py:22-32`、`backend/routes/event_routes.py:22-28`、`frontend/standalone-web/src/App.vue:4561-4608`
|
||||
- **问题**:后端把事件流做成"返回最近 N 条 + 一段预渲染 SSE 文本"的普通 JSON 接口,没有 `after_event_id` / `since` 参数;前端只能轮询固定窗口,靠在返回数组里查找上次的 `event_id` 来切出增量。窗口一旦被冲掉,增量计算就退化。
|
||||
- **代码**:
|
||||
|
||||
后端(无游标,且 `body`/`content_type` 是给 SSE 用的但走的是 JSON 通道):
|
||||
```python
|
||||
# backend/services/event_stream_service.py:22-32
|
||||
def recent_events(self, *, event_type: str | None = None, limit: int = 50) -> dict[str, Any]:
|
||||
events = self.event_bus.history(event_type)
|
||||
selected = events[-_limit(limit):]
|
||||
webhook_events = [_event_to_webhook(event) for event in selected]
|
||||
return {
|
||||
"content_type": "text/event-stream",
|
||||
"events": [event.to_dict() for event in webhook_events],
|
||||
"body": "".join(to_sse(event) for event in webhook_events),
|
||||
"count": len(webhook_events),
|
||||
}
|
||||
```
|
||||
前端:
|
||||
```ts
|
||||
// frontend/standalone-web/src/App.vue:4566-4577, 4608
|
||||
const stream = await getJson<{ events: Array<{ event_id?: string; ... }> }>(
|
||||
endpoints.eventStream, { limit: 20 })
|
||||
const newest = stream.events.at(-1)?.event_id ?? ""
|
||||
if (!newest || newest === lastEventStreamId) return
|
||||
const previousIndex = hadPrevious
|
||||
? stream.events.findIndex((event) => event.event_id === lastEventStreamId) : -1
|
||||
const freshEvents = hadPrevious
|
||||
? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : -1) // ← 找不到时只取最后 1 条
|
||||
: []
|
||||
...
|
||||
eventStreamTimer = window.setInterval(poll, 5000)
|
||||
```
|
||||
- **影响**:一轮 4~8 张候选图的生成会在几秒内产生远超 20 条 `generation.*` / `workflow.*` 事件。此时 `findIndex` 返回 `-1`,`slice(-1)` 只留下**最后一条**事件,`eventTypes` 只有一个元素,于是 `generationChanged` / `workflowChanged` 的判定基于 1/20 的样本——`loadJobs()` / `loadDashboard()` / `loadWorkflowRoundDetail()` 该刷的不刷,UI 停在旧状态直到用户手动刷新。这正是"生成完了界面不动"类问题的结构性来源。同时 `body` 与 `content_type` 两个字段每次都白白序列化传输且被前端丢弃。
|
||||
- **修复建议**:
|
||||
1. `EventStreamService.recent_events` 增加 `after_event_id: str | None`,在 `_history` 中定位后返回其后全部事件(配合 `limit` 上限 200),并返回 `truncated: bool` 告知客户端是否发生了窗口溢出。
|
||||
2. 前端改传 `{ after_event_id: lastEventStreamId, limit: 200 }`;收到 `truncated: true` 时退化为一次全量刷新(`loadJobs + loadDashboard + 当前视图`),而不是静默少刷。
|
||||
3. `content_type` / `body` 两个字段要么删掉(JSON 通道用不上),要么单独开一条真正的 SSE 路由;现在这样两边都不是。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 队列状态枚举在前后端共 4 处独立硬编码
|
||||
|
||||
- **位置**:`backend/services/queue_service.py:31-34` vs `frontend/standalone-web/src/App.vue:3285`、`3293`、`frontend/shared/utils/presentation.ts:5`
|
||||
- **问题**:后端已经把任务状态分类抽成了具名常量,前端把这些集合的字面量抄了三份,还多出一个后端没有的分类。
|
||||
- **代码**:
|
||||
|
||||
后端唯一真相:
|
||||
```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))
|
||||
```
|
||||
前端三份拷贝:
|
||||
```ts
|
||||
// App.vue:3284-3286
|
||||
const failedJobs = computed(() =>
|
||||
queueItems.value.filter((job) => ["failed", "dead_letter", "cancelled"].includes(normalizeStatus(job.status))))
|
||||
// App.vue:3292-3295
|
||||
const completedQueueJobs = computed(() =>
|
||||
queueItems.value.filter((job) => ["completed", "succeeded", "superseded"].includes(normalizeStatus(job.status))))
|
||||
const terminalQueueJobs = computed(() => [...failedJobs.value, ...completedQueueJobs.value])
|
||||
```
|
||||
```ts
|
||||
// frontend/shared/utils/presentation.ts:5 —— 第四份,且集合与后端任何一个常量都不完全相等
|
||||
const TERMINAL_JOB_STATUSES = new Set(["completed", "succeeded", "failed", "cancelled", "dead_letter", "superseded"])
|
||||
```
|
||||
另有 `App.vue:3628` 第五次内联同一个 `["failed","dead_letter","cancelled"]`。
|
||||
- **影响**:`TASK_STATUSES`(`queue_service.py:18-29`)新增一个终态(例如 `expired`)时,后端会正确把它算进 `DELETABLE`,而前端四处判定全部漏掉:任务永远停在"运行中"分组、`waitTime()` 里 `terminal` 为 false 导致耗时读数无限增长、"清理终态任务"按钮的 `enabled` 计数与后端实际清理数量对不上。
|
||||
- **修复建议**:把这四个集合加进 `GET ui/bootstrap` 的返回体(`UiService.get_bootstrap` 已经在下发 `permissions` 和 `feature_flags`,加 `task_statuses: {retryable, failed, completed, terminal}` 是同一性质的元数据),前端建一个 `taskStatusSets.ts` 从 bootstrap 初始化;或退一步,至少把四份合并成 `frontend/shared/config/task-status.ts` 一份,并加一条像 `task-timeout-consistency.test.mjs` 那样的正则测试断言它与 `queue_service.py` 的字面量一致。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `images/{id}/moderation-review` + `include_restricted` 是一条完整但前端零对接的功能链
|
||||
|
||||
- **位置**:`backend/routes/image_routes.py:41-49`、`68-73`、`90-91`、`145-160`;前端零引用
|
||||
- **问题**:后端为"内容审核隔离图片"实现了完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点——前端一个都没接。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/image_routes.py:41-49
|
||||
include_restricted = as_bool(params.get("include_restricted"), default=False, non_string_truthiness=True)
|
||||
if include_restricted and not (ctx.has_permission("can_manage_materials") or ctx.has_permission("*")):
|
||||
include_restricted = False
|
||||
payload = _serialize_image_list(result, signer)
|
||||
if not include_restricted:
|
||||
visible = [item for item in payload["items"] if not _is_restricted_image(item)]
|
||||
payload["restricted_hidden"] = len(payload["items"]) - len(visible)
|
||||
payload["items"] = visible
|
||||
payload["total"] = max(len(visible), int(payload.get("total") or 0) - payload["restricted_hidden"])
|
||||
```
|
||||
```python
|
||||
# backend/services/image_service.py:135-143 —— approve/reject 会真实改写可见性
|
||||
update = {"metadata": {**metadata,
|
||||
"quarantined": False if action == "approve" else True,
|
||||
"gallery_visibility": "normal" if action == "approve" else "restricted",
|
||||
"moderation_admin_review": review},
|
||||
**({"is_archived": True} if action == "reject" else {})}
|
||||
```
|
||||
前端验证:`grep -rn "include_restricted\|restricted_hidden\|quarantined\|gallery_visibility" frontend/` 全树仅命中 `App.vue:4526` 的 `include_archived: true`,与本功能无关。`frontend/shared/types/image.ts:28-33` 的 `ImageListResult` 也没有 `restricted_hidden` 字段。
|
||||
- **影响**:`generation_service.py:491` / `968` 会把审核不通过的图打上 `gallery_visibility: "restricted"`。这些图对所有人(含管理员)永久不可见、不可复核、不可解除——UI 既不显示"有 N 张被隐藏",也没有任何入口调用 approve。用户视角是"生成成功了但图库里没有",没有任何解释。这是一条**后端做完、前端未接、因此在生产中表现为数据丢失**的功能链。
|
||||
- **修复建议**:图库页加"显示受限图片"开关(仅 `can_manage_materials` 可见)→ 传 `include_restricted=true`;列表底部读 `restricted_hidden` 显示"另有 N 张待复核";受限图详情弹窗加 approve/reject,调 `endpoints` 新增的 `imageModerationReview(imageId)`。同时把 `restricted_hidden?: number` 补进 `ImageListResult`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `AdvancedMaterialImportStatus` 双向漂移,且 `Union | string` 写法让所有状态联合类型在编译期失效
|
||||
|
||||
- **位置**:`frontend/shared/types/advanced-material.ts:1-49` vs `backend/services/advanced_style_set_service.py:384/527/539/787/1366` 等
|
||||
- **问题**:两个方向都对不上,而且类型声明方式使 TS 完全无法发现这类漂移。
|
||||
- **代码**:
|
||||
|
||||
后端实际写入 import.status 的取值(扫描 `update_import(..., {"status": ...})` 得到):
|
||||
```
|
||||
adjustment_required, cancelled, ready_for_validation, recognition_failed,
|
||||
recognition_queued, recognizing_style_sources, style_consensus_failed,
|
||||
style_consensus_queued, style_consensus_running, style_source_recognition_queued,
|
||||
style_source_review_required, validating, validation_failed, validation_queued
|
||||
```
|
||||
前端联合类型(`advanced-material.ts:1-18`):
|
||||
```ts
|
||||
export type AdvancedMaterialImportStatus =
|
||||
| "recognition_queued" | "pending_recognition" | "recognizing" | "pending_validation"
|
||||
| "ready_for_validation" | "validation_queued" | "validating" | "validation_failed"
|
||||
| "recognition_failed" | "pending_review" | "awaiting_review" | "adjustment_required"
|
||||
| "accepted" | "rejected" | "failed" | "cancelled" | "archived"
|
||||
```
|
||||
**前端缺 6 个**:`recognizing_style_sources`、`style_consensus_failed`、`style_consensus_queued`、`style_consensus_running`、`style_source_recognition_queued`、`style_source_review_required`(整个 style-set 流程的状态一个没有)。
|
||||
**前端多 2 个后端根本不产出的**:`pending_validation`、`pending_review`(`grep -rn '"pending_validation"' --include=*.py backend/ database/` → 0 命中)。
|
||||
而声明处一律写成:
|
||||
```ts
|
||||
// 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`)等十余处。
|
||||
- **影响**:运行时目前靠 `advanced-material-state.ts:24-67` 的 switch 兜住(它确实手工覆盖了 style_* 状态,甚至还处理了一个后端只在两处出现的 `validation_partial_failed`),但类型层面完全没有护栏:后端加一个新状态,TS 编译通过、review 看不出、只有用户看到"未知状态"文案(`advanced-material-state.ts:65`)才暴露。`pending_validation`/`pending_review` 这两个幽灵值说明漂移已经发生过至少一次且无人察觉。
|
||||
- **修复建议**:
|
||||
1. 把 `| string` 去掉,改为 `status: AdvancedMaterialImportStatus`,让联合类型真正生效;确实需要容忍未知值的地方用显式 `as string` 或在解析边界处收窄。
|
||||
2. 状态集合从后端生成而非手抄:把各 `*_STATUSES` 常量集中到一个 Python 模块,加一个生成脚本产出 `frontend/shared/types/generated-enums.ts`,CI 校验 `git diff --exit-code`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `backend/dto/advanced_material_dto.py` 已不是进阶素材接口的响应真相来源
|
||||
|
||||
- **位置**:`backend/dto/advanced_material_dto.py` vs `backend/services/advanced_style_set_service.py` vs `frontend/shared/types/advanced-material.ts`
|
||||
- **问题**:TS 类型里大量字段在 DTO 的 `to_dict()` 中不存在,而路由层的序列化只补了 `*_url`。
|
||||
- **代码**:
|
||||
|
||||
路由层只做签名 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"))}
|
||||
```
|
||||
但 TS 声明了这些 DTO 里没有的字段(`advanced-material.ts:58-86`、`125-158`、`160-187`):
|
||||
|
||||
| TS 接口 | DTO 无此字段 | 实际来源 |
|
||||
|---|---|---|
|
||||
| `AdvancedStyleSource` | `excluded`、`filename`、`image_uri`、`thumbnail_uri`、`retry_count` | `advanced_style_set_service.py:409/414` 手工构造的 metadata / view dict |
|
||||
| `AdvancedStyleValidationCase` | `scenario`、`title`、`style_prompt`、`style_scores`、`rendering_layers`、`content_novelty` | `advanced_style_set_service.py:2330/2354/3345/3422` |
|
||||
| `AdvancedMaterialImport` | `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)。
|
||||
- **影响**:`backend/dto/` 这一层对进阶素材已经名存实亡——响应形状实际由散落在 3600 行 `advanced_style_set_service.py` 各处的 dict 字面量决定。想知道接口返回什么,只能全文搜索;改动时没有任何单点可以对照。这也是前面状态枚举漂移的同一个根因。
|
||||
- **修复建议**:为 style-set 流程补 DTO(`AdvancedStyleSourceView`、`AdvancedStyleValidationCaseView`、`AdvancedStyleConsensusView`),让 service 返回 DTO 实例而非裸 dict,路由层只调 `to_dict()` + 加签名 URL。这样"接口返回什么"重新有唯一定义点,也让 `contract` 有机会未来发布响应 schema。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `route-chain:` 线格式编解码器被逐字移植到 TS,无任何跨语言一致性测试
|
||||
|
||||
- **位置**:`core/model_route_chain.py:52-66` vs `frontend/standalone-web/src/features/settings/model-route-chain.ts:27-39`
|
||||
- **问题**:这不是"逻辑重复",而是**同一个序列化格式的两份独立实现**——前端写出的字符串要被后端解析,任何一边的细节改动都会破坏另一边,而目前正确性完全依赖手工对齐 `json.dumps` 与 `JSON.stringify` 的输出细节。
|
||||
- **代码**:
|
||||
```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 })`(更符合"plugin 优先"的语义直觉)就会产出 `{"plugin":...,"astrbot":...}`。Python 端 `parse_model_route_chain` 用 `json.loads` 读 dict,解析仍然成功——所以**不会立刻报错**,但两端产出的字符串不再逐字节相等,任何做字符串比较的地方(配置 diff、快照对比、`settings/diff`)都会把"没变的配置"报成"变了"。现有测试 `tests/test_model_route_chain.py` 只验 Python 内部往返,`frontend/tests/workflow-model-route.test.mjs` 根本没测这个模块,**没有一条测试断言两语言的编码结果相同**。
|
||||
- **修复建议**:加一条黄金样本测试固定线格式。Python 侧断言 `encode_model_route_chain("p","astrbot:a") == 'route-chain:{"astrbot":"astrbot:a","plugin":"p"}'`,TS 侧 `frontend/tests/` 里用同一字符串断言 `encodeModelRouteChain({plugin:"p",astrbot:"astrbot:a"})`,并加反向 `parse` 用例。更彻底的做法是别让前端编码:新增 `POST settings/encode-model-route` 或让 settings 保存接口接受 `{plugin, astrbot}` 结构体、由后端编码。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `character_flow` 节点目录与 legacy 别名表在前端重复,且两份前端拷贝之间也不一致
|
||||
|
||||
- **位置**:`engines/character_flow.py:15-20` vs `frontend/standalone-web/src/features/workflow/workflow-node-catalog.ts:23-32` vs `frontend/standalone-web/src/features/workflow/workflow-model-route.ts:61-74`
|
||||
- **问题**:同一张"legacy node_key → canonical node_key"映射表存在三份,其中两份在同一个前端目录下且映射结果不同。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/character_flow.py:15-20
|
||||
LEGACY_CHARACTER_GRADUAL_NODE_KEYS: dict[str, str] = {
|
||||
"half_body": "upper_body",
|
||||
"expression_sheet": "turnaround", # ← turnaround
|
||||
"pose_sheet": "design_sheet",
|
||||
"final_pack": "profile_card",
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// workflow-node-catalog.ts:23-28 —— 与后端一致
|
||||
export const LEGACY_CHARACTER_WORKFLOW_NODE_KEYS = {
|
||||
half_body: "upper_body", expression_sheet: "turnaround",
|
||||
pose_sheet: "design_sheet", final_pack: "profile_card",
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// workflow-model-route.ts:61-74 —— 同一前端内的第三份,expression_sheet 映射不同
|
||||
const canonicalAliases: Record<string, string> = {
|
||||
portrait: "headshot", avatar: "headshot", half_body: "upper_body", halfbody: "upper_body",
|
||||
standing: "full_body", fullbody: "full_body", three_view: "turnaround", three_views: "turnaround",
|
||||
character_sheet: "design_sheet",
|
||||
expression_sheet: "design_sheet", // ← design_sheet,与另两处冲突
|
||||
pose_sheet: "design_sheet", hires_fix: "style_lock",
|
||||
}
|
||||
```
|
||||
另外 11 个节点的 `node_key` 与展示文案在 `engines/character_flow.py:22-115`(`CHARACTER_GRADUAL_STEPS`,含 title/description/sort_order/stage_code)和 `workflow-node-catalog.ts:64-153`(`CHARACTER_WORKFLOW_PREVIEW_NODE_SPECS`,含 title/detail/badge/phase)各存一份,两边的中文标题也不同(后端"拆解人设/预选素材"vs 前端"LLM 拆解设定/参考素材绑定")。
|
||||
- **影响**:`expression_sheet` 的冲突目前不产生可见 bug(`turnaround` 和 `design_sheet` 恰好都映射到 `sheet_generation`),但这是巧合而非设计。真正的风险是:`engines/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` 那张私有别名表,改用 `canonicalCharacterWorkflowNodeKey`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `LONG_TASK_ENDPOINT` 正则在前端重复两份,并把"哪些后端端点慢"编码进了客户端
|
||||
|
||||
- **位置**:`frontend/shared/api/client.ts:14` 与 `frontend/shared/api/astrbot-page-bridge.ts:6`(逐字符相同)
|
||||
- **问题**:一条 18 个分支的正则,枚举了所有"耗时长"的后端端点段,在两个文件里各存一份;而它声称对齐的"后端 900 秒预算"在后端并不存在。
|
||||
- **代码**:
|
||||
```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)(?:\/|$)/
|
||||
```
|
||||
```ts
|
||||
// frontend/shared/config/timeouts.ts
|
||||
export const LONG_TASK_TIMEOUT_SECONDS = 900
|
||||
```
|
||||
而 `grep -rn "\b900\b" --include=*.py`(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关:
|
||||
```python
|
||||
# backend/services/advanced_style_set_service.py:57
|
||||
STYLE_VALIDATION_TIMEOUT_SECONDS = 900
|
||||
```
|
||||
生成任务的真实预算是 180 秒(`generation_service.py:2308` `request.get("timeout_seconds") or settings.get("timeout_seconds") or 180`;`config.yaml:25/42` `timeout_seconds: 180`)。
|
||||
号称守护一致性的测试其实只读前端文件:
|
||||
```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 秒预算",但测试没有读过任何后端文件——它固化的是一个虚构的契约。后端把 `timeout_seconds` 从 180 调到 600,前端不会知道;反过来前端这个 900 也没有任何后端依据。
|
||||
3. 新增一个慢端点(例如 `advanced-material-imports/{id}/style-consensus`,实际走 900 秒的样式校验)不在正则里,客户端 30 秒就超时报错,而后端任务其实还在跑。
|
||||
- **修复建议**:正则提到 `frontend/shared/config/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` 与前端常量做真实比对。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `contract` 端点只被用作诊断 JSON dump,没有任何自动化契约测试消费它
|
||||
|
||||
- **位置**:`backend/services/contract_service.py:12-30`、`backend/routes/contract_routes.py:13-23`、唯一前端消费点 `frontend/standalone-web/src/features/settings/SystemManagementPanel.vue:8`
|
||||
- **问题**:契约自检机制**已经存在且数据完备**,但没有被任何一方真正用起来。
|
||||
- **代码**:
|
||||
```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>
|
||||
else if(props.mode==="diagnostics"){
|
||||
const [contract,actions,manifest]=await Promise.all([
|
||||
getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
|
||||
result.value={contract,actions,manifest}}
|
||||
```
|
||||
`route_registry.py` 已经写好了两个自检函数,但 `grep -rln "route_manifest\|route_registry\|ROUTES" tests/` 只命中 `test_profile_card_finalize.py` 和 `test_workflow_generation_cross_review.py`(都是间接 import),**没有任何测试调用 `assert_unique_routes()` / `assert_known_permissions()`**:
|
||||
```python
|
||||
# backend/route_registry.py:365-377 —— 现成的自检,无人调用
|
||||
def assert_unique_routes() -> None: ...
|
||||
def assert_known_permissions() -> None: ...
|
||||
```
|
||||
- **影响**:契约漂移目前没有任何自动化拦截。本报告里的表 ①(14 条死接口)、P1-4(权限漏判)、P2-9(状态枚举漂移)全部是人工比对才发现的,任何一条都本可以由 CI 自动发现。
|
||||
- **修复建议**:**这是本维度投入产出比最高的一条,建议优先做**。三条测试即可覆盖大部分问题:
|
||||
|
||||
1. **后端自检**(`tests/test_route_contract.py`,我已实测 166 条 handler 全部可导入,此测试当前会通过):
|
||||
```python
|
||||
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
|
||||
```
|
||||
|
||||
2. **跨语言路由比对**(`frontend/tests/api-contract.test.mjs`):解析 `backend/route_registry.py` 的 `RouteSpec("METHOD", "endpoint"` 与 `endpoints.ts` 的模板字符串(把 `${...}` 与 `{...}` 都归一为 `{}`),断言 endpoints.ts ⊆ ROUTES(阻止表 ② 出现),并把当前 14 条死接口写成显式 allowlist,新增未使用路由时测试失败——逼迫作者要么接上要么删掉。
|
||||
|
||||
3. **权限门禁比对**:前端所有按钮的 `enabled` 统一走 P1-4 建议的 `canCall(method, endpoint)`,该函数的输入直接来自 contract 的 `required_permissions`,从此权限矩阵不需要在前端复写。
|
||||
|
||||
另外 `contract` 目前只发布路由与权限,不发布**请求/响应 schema**。若把 `backend/dto/*.py` 的 `to_dict()` 字段清单也纳入(DTO 都是 frozen dataclass,用 `dataclasses.fields()` 自动生成即可),就能把 P2-9、P2-10、P3-16 这类字段级漂移一并自动化——但前提是先修 P2-10(让 DTO 重新成为真相来源)。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `API_BASE` 硬编码三份,而 `bootstrap.api_base` 下发了却没人用
|
||||
|
||||
- **位置**:`backend/services/ui_service.py:10`、`frontend/shared/api/endpoints.ts:1`、`frontend/standalone-web/vite.config.ts:11`
|
||||
- **问题**:同一个字符串三处独立字面量;后端已经通过 bootstrap 把它下发给前端,前端却只拿它拼提示文案。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点)
|
||||
API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
|
||||
```
|
||||
```ts
|
||||
// frontend/shared/api/endpoints.ts:1
|
||||
export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
|
||||
```
|
||||
```ts
|
||||
// frontend/standalone-web/vite.config.ts:11
|
||||
base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
|
||||
```
|
||||
前端拿到 `bootstrap.api_base` 之后的唯一用途:
|
||||
```ts
|
||||
// frontend/standalone-web/src/App.vue:4330
|
||||
: `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,
|
||||
```
|
||||
实际请求路径始终来自编译期常量:
|
||||
```ts
|
||||
// frontend/shared/api/client.ts:299
|
||||
const url = new URL(`${API_BASE}/${trimmed}`, window.location.origin)
|
||||
```
|
||||
- **影响**:插件名一旦变更(`metadata.yaml` 改 name、或 AstrBot 调整挂载前缀),后端 `API_BASE` 改一处即可,前端要改两处且其中一处是 vite 构建配置——漏掉 vite base 会导致所有 chunk 404(这类"资产 404"症状在 git 历史里已经出现过:`fix: load material library page without expiring asset chunk`)。而 `bootstrap.api_base` 这个正确的解耦通道就在那里没被使用。
|
||||
- **修复建议**:`client.ts` 的 `buildUrl` 改为优先使用运行期值:模块内维护 `let runtimeApiBase = API_BASE`,bootstrap 成功后调 `setApiBase(bootstrap.api_base)`。vite base 保持编译期常量(静态资源必须编译期确定),但加一条 `frontend/tests/` 断言 `vite.config.ts` 的 base 以 `endpoints.ts` 的 `API_BASE` 开头。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `CharacterProfile` TS 类型缺 owner 四字段,`generation_kind` 联合含后端不产出的值
|
||||
|
||||
- **位置**:`frontend/shared/types/profile.ts:3-21` vs `backend/dto/profile_dto.py:32-52` 与 `database/repositories/profile_repository.py:32-56`
|
||||
- **问题**:DTO 输出 20 个字段,TS 声明 16 个;且 TS 的枚举值比后端 SQL 实际产出的多一个。
|
||||
- **代码**:
|
||||
后端 `to_dict()` 输出但 TS 未声明:`owner_platform`、`owner_context_id`、`owner_user_id`、`owner_session_key`(`profile_dto.py:42-45`)。
|
||||
TS 声明:
|
||||
```ts
|
||||
// frontend/shared/types/profile.ts:18
|
||||
generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"
|
||||
```
|
||||
而 SQL 表达式只可能产出三个值:
|
||||
```sql
|
||||
-- database/repositories/profile_repository.py:32-56
|
||||
CASE WHEN EXISTS (... profile_card.status = 'sealed') THEN 'detailed'
|
||||
WHEN EXISTS (... final_archive_history_id ...) THEN 'detailed'
|
||||
WHEN EXISTS (... character_fast ...) THEN 'quick'
|
||||
ELSE 'ungenerated' END AS generation_kind
|
||||
```
|
||||
- **影响**:owner 四字段是多租户归属信息,随每个 profile 响应传输但前端不认识——将来若要做"仅显示我创建的角色"这类过滤,会有人再造一份类型。`"profile_card"` 是死枚举值,`switch (profile.generation_kind)` 里为它写的分支永远不执行,读代码的人会误以为存在这个状态(`profile_category` 才有 `profile_card`)。
|
||||
- **修复建议**:DTO 与 TS 字段做一次对齐(不需要的字段就从 `to_dict()` 里删,别只在 TS 侧省略);删掉 `generation_kind` 里的 `"profile_card"`。长期看应由 P2-14 建议的 DTO schema 导出自动生成。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `WorkflowRoundNextRequest.count` 类型比后端窄,掩盖了 cross_review 的 1..8 区间
|
||||
|
||||
- **位置**:`frontend/shared/types/workflow-round.ts:48-52` vs `backend/services/workflow_round_service.py:1159-1171`
|
||||
- **问题**:TS 把候选数收窄为字面量联合 `4 | 5`,后端接受的区间取决于轮次类型。
|
||||
- **代码**:
|
||||
```ts
|
||||
// frontend/shared/types/workflow-round.ts:48-52
|
||||
export interface WorkflowRoundNextRequest {
|
||||
count: 4 | 5
|
||||
idempotency_key: string
|
||||
model_route?: string
|
||||
}
|
||||
```
|
||||
```python
|
||||
# backend/services/workflow_round_service.py:1159-1171
|
||||
def _requested_count(value: Any, round_kind: str) -> int:
|
||||
count = int(value) if value is not None else 4
|
||||
maximum = 8 if round_kind == "cross_review" else 5
|
||||
if count < 1 or count > maximum:
|
||||
raise ApiError(ErrorCode.VALIDATION_FAILED,
|
||||
"round candidate count is outside the supported range",
|
||||
{"field": "count", "minimum": 1, "maximum": maximum})
|
||||
```
|
||||
- **影响**:目前是安全方向的收窄(前端发的值后端一定接受),不会产生 400。但把"业务上只允许 4 或 5"这条产品规则固化在了 TS 类型里而后端并不这么认为,两边对同一规则的理解已经分叉;将来要支持"生成 8 张交叉复核候选"时,类型会成为改动的隐性阻碍,且改动方向不明确(因为没人记得后端其实早就支持)。
|
||||
- **修复建议**:改为 `count: number`,把"4 或 5"的选择限制放在 UI 控件层(下拉框选项),并在 `WorkflowGenerationRoundDetail` 或 `round.metadata` 里由后端下发 `allowed_count_range: [min, max]`,让 UI 选项跟着轮次类型走。
|
||||
653
审计/findings/B2-后端内部耦合.md
普通文件
653
审计/findings/B2-后端内部耦合.md
普通文件
|
|
@ -0,0 +1,653 @@
|
|||
# B2 · 后端内部耦合与架构分层
|
||||
|
||||
> 审计范围(实际 Read / Grep 过的源文件):
|
||||
> `main.py`
|
||||
> `backend/route_registry.py`
|
||||
> `backend/routes/`:`node_routes.py`、`node_material_routes.py`、`job_routes.py`、`round_routes.py`、`event_routes.py`、`common.py`、`branch_routes.py`、`history_routes.py`、`review_routes.py`、`profile_routes.py`、`workflow_routes.py`
|
||||
> `backend/services/`:`generation_service.py`、`workflow_round_service.py`、`workflow_round_worker_runtime.py`、`workflow_node_material_service.py`、`workflow_service.py`(结构)、`chat_workflow_service.py`、`advanced_material_service.py`、`advanced_style_set_service.py`(结构)、`event_stream_service.py`、`queue_service.py`、`branch_lineage_service.py`、`quick_profile_service.py`
|
||||
> `core/`:`event_bus.py`、`config_service.py`、`security.py`、`audit_service.py`、`astrbot_provider_bridge.py`、`media_proxy.py`、`storage.py`
|
||||
> `database/`:`db_helper.py`、`repositories/workflow_round_repository.py`、`repositories/workflow_cross_review_repository.py`、`repositories/profile_card_repository.py`、`repositories/workflow_repository.py`
|
||||
> `adapters/astrbot_adapter.py`
|
||||
> 分析方法:对 179 个 Python 模块做 AST/正则导入抽取,生成模块级有向图(扇入/扇出/SCC/分层违规),再逐条回源码验证。
|
||||
|
||||
---
|
||||
|
||||
## 摘要
|
||||
|
||||
整体分层意图是清晰的(`routes → services → repositories`,`core` 做横切基础设施),但**组合根(composition root)缺失**是所有耦合问题的根因:35 个 `_create_*_service()` 工厂散落在 35 个 route 模块里,34 处 `Database(load_database_settings())` 各自从磁盘重读一次 `config.yaml`,没有任何缓存或容器。这直接导致三类硬伤:(1) 后台 worker 必须反向 import route 模块才能拿到装配好的 `GenerationService`(`service → route` 反向依赖);(2) 同一个服务在不同 route 里被装配成**行为不一致**的实例——`node_material_routes.py` 构造的 `WorkflowService` 没有 `event_bus`,导致素材绑定事件被静默丢弃(P1,可复现);(3) 装配代码大段复制(governance/provider 装配在 `node_routes.py:315-390` 与 `advanced_material_service.py:1700-1764` 几乎逐行重复)。
|
||||
|
||||
`core/event_bus.py` 存在但**形同虚设**:全仓(含 tests)`subscribe()` / `unsubscribe()` 的调用方为 **0**,只有 6 处 `publish()`。它实际只是 `GET events/stream` 的进程内环形缓冲区,没有承担任何解耦职责,因此所有跨服务通信仍走硬 import。
|
||||
|
||||
另有 9 条明确的分层方向违规:`database/repositories/*` 反向 import `backend.services.branch_lineage_service` 和 `engines`;`core/*` 反向 import `backend.dto.common`。模块级无循环导入(SCC 只在 `adapters/__init__` 与其成员之间,属包导出正常形态),但 `job_routes.py:311` 用函数内 import 跨 route 模块取**私有**函数 `_create_generation_service`,是循环依赖的规避痕迹。
|
||||
|
||||
`main.py` 2580 行中,真正的插件生命周期初始化只有约 95 行(354-447),其余是 849 行聊天命令、165 行纯转发的短命令别名、828 行 AstrBot HTTP/配置桥接。`ChatWorkflowService`(1315 行)通过字符串路径调用 `dispatch_web_request` 做了 **69 次**进程内"自我 HTTP 调用",把 route 层变成了 service 层的下游。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] 装配分散导致 `WorkflowService` 实例行为不一致:素材绑定事件被静默丢弃
|
||||
|
||||
- **位置**:`backend/routes/node_material_routes.py:69`(构造点)+ `backend/services/workflow_node_material_service.py:208`(消费点)
|
||||
- **问题**:8 处 `WorkflowService(...)` 构造中,只有 4 处传入了 `event_bus`。`node_material_routes._create_service()` 是 `GET/POST node materials` 两个路由的唯一装配路径,它构造 `WorkflowService` 时**没有传 `event_bus`**;而 `WorkflowNodeMaterialService` 又是通过 `self.workflow_service.event_bus` 这种"穿透邻居属性"的方式取总线的,于是判空直接短路,`workflow.node_material_bindings_updated` 事件永远不会发出。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/routes/node_material_routes.py:64-73
|
||||
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",
|
||||
{
|
||||
"workflow_id": workflow.workflow_id,
|
||||
"branch_name": node.branch_name,
|
||||
"node_id": node.node_id,
|
||||
"material_count": len(selected_material_ids),
|
||||
"temporary_reference_count": len(temporary_references),
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
对照 `backend/routes/profile_routes.py:176-181` 同名工厂是传了的:
|
||||
|
||||
```python
|
||||
return WorkflowService(
|
||||
workflow_repository=WorkflowRepository(database),
|
||||
profile_repository=ProfileRepository(database),
|
||||
audit_service=AuditService(database),
|
||||
event_bus=get_default_event_bus(), # ← 这里传了
|
||||
)
|
||||
```
|
||||
|
||||
未传 `event_bus` 的还有 `backend/routes/branch_routes.py:64`、`backend/routes/history_routes.py:72`、`backend/routes/review_routes.py:90`。
|
||||
- **影响**:前端 `GET events/stream` 永远看不到素材绑定变更事件;任何基于该事件做增量刷新/审计的下游功能静默失效,且因为是 `if` 短路,没有日志、没有异常,排查成本极高。同类风险覆盖全部 4 个漏传点。
|
||||
- **修复建议**:
|
||||
1. 立即修复:把 `event_bus=get_default_event_bus()` 补进 4 处工厂;
|
||||
2. 根治:让 `WorkflowService.event_bus` 默认取 `get_default_event_bus()` 而非 `None`,并把 `publish` 收敛成服务自身的 `self._publish(...)` 方法(像 `QueueService._publish` 那样),禁止 `self.<other_service>.event_bus` 这种穿透写法;
|
||||
3. 加一条单测:断言 `route_registry.ROUTES` 里每个 handler 的默认装配路径产出的 `WorkflowService.event_bus is not None`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `service → route` 反向依赖:后台 worker 必须 import route 模块才能启动
|
||||
|
||||
- **位置**:`backend/services/workflow_round_worker_runtime.py:10`;工厂定义在 `backend/routes/node_routes.py:315-390`(私有)与 `:393`(公开包装)
|
||||
- **问题**:整个应用的**组合根**(DI 装配逻辑)住在 route 模块里。`_create_generation_service()` 在 `node_routes.py` 中完成 Database、9 个 repository、`ModelProviderRuntime`、`SingleFlowEngine`、4 个 governance 服务的装配。后台 round worker 是 service 层组件,却必须反向 import route 层才能拿到它。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/workflow_round_worker_runtime.py:9-16
|
||||
from backend.dto.job_dto import GenerationTask
|
||||
from backend.routes.node_routes import create_generation_service # ← service 依赖 route
|
||||
from backend.services.generation_service import GenerationService
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/routes/node_routes.py:315-343(节选,装配根埋在 route 里)
|
||||
def _create_generation_service() -> GenerationService:
|
||||
database = Database(load_database_settings())
|
||||
audit_service = AuditService(database)
|
||||
...
|
||||
config_payload = load_config_payload()
|
||||
sync_generation_provider_from_config(model_provider_service, config_payload)
|
||||
governance_config = config_payload.get("prompt_governance") if isinstance(...) else {}
|
||||
translation_config = governance_config.get("translation") if isinstance(...) else {}
|
||||
...
|
||||
```
|
||||
|
||||
另有跨 route 模块取私有符号(函数内 import,循环依赖规避痕迹):
|
||||
|
||||
```python
|
||||
# backend/routes/job_routes.py:309-311
|
||||
def _create_generation_job_retry_service() -> GenerationJobRetryService:
|
||||
# Import lazily so route discovery does not construct provider runtimes.
|
||||
from backend.routes.node_routes import _create_generation_service # ← 取的是私有名
|
||||
```
|
||||
- **影响**:
|
||||
- `backend/routes` 变成不可卸载的运行时依赖,无法把 HTTP 层与 worker 层分开打包/测试;
|
||||
- `main.py:390` 也必须在 `initialize()` 里函数内 import worker runtime(`try/except` 包裹)来规避启动期副作用,注释 `"Import lazily so route discovery does not construct provider runtimes"` 直接说明了这个 import 图已经有环形压力;
|
||||
- 单测想构造 `GenerationService` 就得连带 import 整个 route 模块的 31 个依赖(`node_routes` 是全仓扇出第一,31)。
|
||||
- **修复建议**:新建 `backend/composition.py`(或 `backend/container.py`)作为唯一组合根,把 `node_routes.py:282-390`、`job_routes.py:300-318`、`round_routes.py:137+`、`advanced_material_service.py:1700-1764` 里的装配代码全部搬进去,导出 `create_generation_service()` / `create_workflow_service()` / `create_round_service()`。route 与 worker 都从 `backend.composition` 取,依赖方向恢复为 `routes → composition → services`。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `database` 层反向依赖 `backend.services` 与 `engines`
|
||||
|
||||
- **位置**:`database/repositories/workflow_round_repository.py:17`、`database/repositories/workflow_cross_review_repository.py:17`、`database/repositories/profile_card_repository.py:11`
|
||||
- **问题**:仓储层(最底层)反向 import 业务服务层与引擎层。`branch_state_for` / `with_branch_state` 是 `backend/services/branch_lineage_service.py` 里的分支血缘业务规则,被两个 repository 直接调用;`profile_card_repository` 还 import 了 `engines.character_flow.canonical_gradual_node_key`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/repositories/workflow_round_repository.py:11-17
|
||||
from backend.dto.workflow_round_dto import (...)
|
||||
from backend.services.branch_lineage_service import branch_state_for, with_branch_state
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/workflow_cross_review_repository.py:17
|
||||
from backend.services.branch_lineage_service import branch_state_for, with_branch_state
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/profile_card_repository.py:8-11
|
||||
from backend.dto.common import ApiError, ErrorCode
|
||||
from backend.dto.profile_card_dto import CharacterProfileCard, CharacterProfileCardAsset
|
||||
from database.db_helper import Database
|
||||
from engines.character_flow import canonical_gradual_node_key
|
||||
```
|
||||
|
||||
而 `branch_lineage_service.py:17` 自己又 import 了 `database.repositories.workflow_repository`:
|
||||
|
||||
```python
|
||||
# backend/services/branch_lineage_service.py:15-17
|
||||
from backend.dto.common import ApiError, ErrorCode
|
||||
from backend.dto.workflow_dto import WorkflowBranch, WorkflowNode
|
||||
from database.repositories.workflow_repository import WorkflowRepository
|
||||
```
|
||||
- **影响**:`database ↔ backend.services` 形成包级双向依赖(模块粒度目前恰好没成环,但只要 `branch_lineage_service` 再多 import 一个 round/cross-review repository 就立即真成环)。分支血缘规则被钉死在 SQL 层,任何血缘策略调整都要改仓储;仓储层无法脱离服务层单独测试。
|
||||
- **修复建议**:
|
||||
1. `branch_state_for` / `with_branch_state` 是**纯函数**(对 dict 做字段级投影,`BRANCH_STATE_FIELDS` 是 frozenset),把它们连同 `BRANCH_STATE_FIELDS` 下沉到 `core/branch_state.py` 或 `backend/dto/workflow_dto.py`,`database` 与 `backend.services` 都从下层取;
|
||||
2. `branch_lineage_service` 保留需要 `WorkflowRepository` 的那部分(`workflow_metadata_for_branch` 等),停留在 service 层;
|
||||
3. `canonical_gradual_node_key` 同理下沉,或由调用方(service)在传参前算好再交给 repository。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `core` 层反向依赖 `backend.dto` 与 `database`,横切层不再是最底层
|
||||
|
||||
- **位置**:`core/security.py:5`、`core/storage.py:11`、`core/media_proxy.py:17`、`core/config_service.py:10`、`core/audit_service.py:12`
|
||||
- **问题**:`core` 本应是无依赖的横切基础设施(被 65 个模块 import 的 `core.identity` 就是正确样板),但其中 5 个模块反向依赖了上层包。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# core/security.py:5-6
|
||||
from backend.dto.common import ApiError, ErrorCode
|
||||
from core.identity import RequestContext
|
||||
```
|
||||
|
||||
```python
|
||||
# core/config_service.py:9-10
|
||||
from core.runtime_paths import resolve_config_path
|
||||
from database.db_helper import load_config_payload
|
||||
```
|
||||
|
||||
```python
|
||||
# core/audit_service.py:11-12
|
||||
from core.identity import RequestContext
|
||||
from database.db_helper import Database, DatabaseSettings
|
||||
```
|
||||
- **影响**:`core` 无法被独立复用或测试;`backend.dto.common`(扇入 53,全仓第三)实际扮演了"最底层错误契约"的角色却被放在 `backend` 包下,造成命名与真实分层错位。`core.config_service` 依赖 `database.db_helper` 更是把"读配置"和"连数据库"绑在一起——而 `db_helper` 里的 `load_config_payload` 本质是 YAML 加载,跟数据库无关。
|
||||
- **修复建议**:
|
||||
1. 把 `ApiError` / `ErrorCode` / `success_response` / `response_from_exception` 从 `backend/dto/common.py` 移到 `core/errors.py`,`backend/dto/common.py` 保留 re-export 做过渡;
|
||||
2. 把 `load_config_payload` / `load_config_file_payload` / `_RUNTIME_CONFIG_OVERRIDES` 这套从 `database/db_helper.py:26-83` 抽到 `core/config_loader.py`,`db_helper` 反过来 import 它。这样 `core` 恢复零上行依赖。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `core/event_bus.py` 零订阅者:事件总线不承担任何解耦职责
|
||||
|
||||
- **位置**:`core/event_bus.py:36-50`;`backend/services/event_stream_service.py:11-15`
|
||||
- **问题**:全仓(含 `tests/` 46 个测试文件)对 `EventBus.subscribe()` / `unsubscribe()` 的调用方是 **0**;`publish()` 只有 6 处。总线实际只是 `GET events/stream` 用的 500 条进程内环形缓冲。所有跨服务协作仍然靠硬 import 完成(见服务耦合簇一节)。
|
||||
- **代码**:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/event_stream_service.py:11-15
|
||||
DEFAULT_EVENT_BUS = EventBus(history_limit=500) # 进程级全局单例
|
||||
|
||||
def get_default_event_bus() -> EventBus:
|
||||
return DEFAULT_EVENT_BUS
|
||||
```
|
||||
|
||||
6 个 publish 点:`generation_service.py:1417/1427/1703`、`queue_service.py:702`、`workflow_node_material_service.py:209`。
|
||||
- **影响**:
|
||||
- 已有基础设施但没兑现解耦价值,`workflow_round_service → generation_service`、`generation_job_retry_service → generation_service`、`deletion_safety_service → image_service/media_service` 这类"做完 A 顺手通知 B"的调用本可以完全走总线;
|
||||
- 同步 `publish` 在 handler 里抛异常会直接打断业务事务(目前无 handler 所以未暴露),一旦有人开始订阅就立刻踩坑;
|
||||
- `_handlers` 是 `defaultdict(list)`,`subscribe/unsubscribe` 无锁;`DEFAULT_EVENT_BUS` 被 `QueueWorkerPool` 的工作线程和请求线程共享,将来加订阅时是竞态温床。
|
||||
- **修复建议**:
|
||||
1. 先把 `publish` 改成异常隔离(`try/except` 包每个 handler,失败只记日志不冒泡),并给 `subscribe/unsubscribe/_handlers` 加 `threading.Lock`;
|
||||
2. 用总线替换 3 组明显的"通知型"直连:`generation_service → workflow_service` 的节点状态回写、`queue_service → 通知回调`(目前 `workflow_round_worker_runtime` 通过 `terminal_notification_callback` 参数手动穿到 `main.py:1672`)、`deletion_safety_service → image/media` 的级联清理;
|
||||
3. 如果确认不打算做订阅,就把 `subscribe/unsubscribe` 删掉,把类改名为 `EventRecorder`,别让它伪装成解耦手段。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `ChatWorkflowService` 通过字符串路径反向调用 route 层(69 次进程内"自我 HTTP")
|
||||
|
||||
- **位置**:`backend/services/chat_workflow_service.py:26-31`(注入点);`main.py:372`(装配点);`adapters/astrbot_adapter.py:171-187`(分发实现)
|
||||
- **问题**:1315 行的 `ChatWorkflowService` 不直接调用任何业务 service,而是把 `dispatch_web_request` 当成"HTTP 客户端",用字符串 method + path 重新进入路由层,共 **69 处** `self.dispatcher(...)`。数据流变成 `service → adapter → route → service`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# main.py:372
|
||||
self.chat_workflow_service = ChatWorkflowService(dispatch_web_request)
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:33-47(典型调用)
|
||||
def submit_single_image(self, command: SingleImageCommand, chat: ChatCommandContext) -> dict[str, Any]:
|
||||
ctx = self._request_context(chat, "single_image")
|
||||
config = self.config_loader()
|
||||
active = self._data(self.dispatcher(ctx, "GET", "jobs", query={"status": "running", "page": 1, "page_size": 100}))
|
||||
...
|
||||
workflow = self._data(self.dispatcher(
|
||||
ctx,
|
||||
"POST",
|
||||
f"profiles/{profile['profile_id']}/workflows",
|
||||
payload={...},
|
||||
))
|
||||
```
|
||||
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:179-187 + 233-252
|
||||
def dispatch_extension_request(ctx, method, path, *, query=None, payload=None):
|
||||
match = resolve_route(method, path)
|
||||
if match is None:
|
||||
return error_response(error_code=ErrorCode.RESOURCE_NOT_FOUND, ...)
|
||||
return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
|
||||
|
||||
def _handler_args(match, ctx, query, payload) -> list[Any]:
|
||||
args: list[Any] = []
|
||||
for index, parameter in enumerate(inspect.signature(match.handler).parameters.values()):
|
||||
...
|
||||
```
|
||||
- **影响**:
|
||||
- **类型安全全失**:路径/参数名拼错只在运行时返回 `RESOURCE_NOT_FOUND`,IDE 与静态检查完全看不到这 69 条调用边;重命名任一路由都会静默打断聊天流程;
|
||||
- **性能**:每次 dispatch 走 `inspect.signature` 反射 + route 内 `_create_*_service()` 全量重建(含 `load_database_settings()` → `config.yaml` 磁盘读取),一条聊天命令动辄十几次 dispatch;
|
||||
- **错误语义扭曲**:业务异常被 route 层的 `handle_request` 包成 `{"success": False, ...}` 字典,service 再用 `self._data()` 拆包,异常栈完全丢失;
|
||||
- 依赖图上 `main.py → ChatWorkflowService → dispatch → route → service`,`main.py` 因此被卷入业务闭环。
|
||||
- **修复建议**:把 `ChatWorkflowService` 改成依赖 `backend/composition.py` 暴露的具体 service 对象(复用同一批实例,避免每次重建)。若要保留"聊天走公开契约"的设计意图,至少把 69 个字符串端点收敛成一个类型化的门面(`class ImageStudioApi` + 每个端点一个方法,内部仍可走 dispatcher),让重命名有编译期/静态检查保护。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 装配代码大段复制:governance/provider 装配在 route 与 service 中各写一遍
|
||||
|
||||
- **位置**:`backend/routes/node_routes.py:315-390` vs `backend/services/advanced_material_service.py:1700-1764`
|
||||
- **问题**:两处独立实现了同一套 "读 config → sync provider → 解析 prompt_governance → 造 callable → 造 SingleFlowEngine" 装配流程,逐行近似。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/routes/node_routes.py:331-339
|
||||
governance_config = config_payload.get("prompt_governance") if isinstance(config_payload.get("prompt_governance"), dict) else {}
|
||||
translation_config = governance_config.get("translation") if isinstance(governance_config.get("translation"), dict) else {}
|
||||
moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
|
||||
routing_config = governance_config.get("routing") if isinstance(governance_config.get("routing"), dict) 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(governance_config.get("moderation"), dict) 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(moderation_config, reviewer)` 与 `GenerationRouteService(routing_config)`。
|
||||
- **影响**:governance 配置结构一旦变化(新增字段、改默认回退键),必须同步修改 3 处;漏改会导致"网页生成走新策略、素材导入/聊天走旧策略"的行为分叉,且这种分叉不会报错。
|
||||
- **修复建议**:抽 `backend/services/prompt_governance_service.py` 内新增 `build_governance_bundle(config_payload, runtime) -> GovernanceBundle`(含 translation/moderation/routing/image_moderation 四个服务),三处调用方统一使用。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 全局可变状态:AstrBot 桥接与配置覆盖是进程级模块变量,测试隔离困难
|
||||
|
||||
- **位置**:`core/astrbot_provider_bridge.py:22-31`、`database/db_helper.py:26-46`
|
||||
- **问题**:跨请求、跨线程共享的运行时状态用模块级 `global` 承载,无锁、无作用域、无重置入口。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:22-31
|
||||
_context: Any | None = None
|
||||
_runtime_loop: asyncio.AbstractEventLoop | None = None
|
||||
ASTRBOT_VISION_TIMEOUT_SECONDS = 270
|
||||
|
||||
def configure_astrbot_provider_bridge(context: Any | None, loop: asyncio.AbstractEventLoop | None) -> None:
|
||||
global _context, _runtime_loop
|
||||
_context = context
|
||||
_runtime_loop = loop
|
||||
```
|
||||
|
||||
```python
|
||||
# database/db_helper.py:26-46
|
||||
_RUNTIME_CONFIG_OVERRIDES: dict[str, Any] = {}
|
||||
_RUNTIME_CONFIG_PERSISTER: Callable[[Mapping[str, Any]], Mapping[str, Any] | None] | None = None
|
||||
|
||||
def set_runtime_config_overrides(payload: Mapping[str, Any] | None) -> None:
|
||||
global _RUNTIME_CONFIG_OVERRIDES
|
||||
_RUNTIME_CONFIG_OVERRIDES = _copy_plain_mapping(payload or {})
|
||||
```
|
||||
|
||||
`_runtime_loop` 被工作线程用于 `asyncio.run_coroutine_threadsafe`(`core/astrbot_provider_bridge.py:79/86`),读取时无内存屏障保护:
|
||||
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:70-86
|
||||
loop = _runtime_loop
|
||||
if provider is None or loop is None or loop.is_closed():
|
||||
return None
|
||||
...
|
||||
future = asyncio.run_coroutine_threadsafe(invoke(), loop)
|
||||
text = future.result(timeout=180)
|
||||
```
|
||||
- **影响**:
|
||||
- 插件热重载(`terminate()` → `initialize()`)期间 `_runtime_loop` 可能指向已关闭的 loop,工作线程正在 `run_coroutine_threadsafe` 会拿到 `RuntimeError`;`terminate()`(`main.py:433`)没有把 `_context/_runtime_loop` 复位;
|
||||
- 测试必须靠 `tests/test_astrbot_provider_bridge.py`、`test_astrbot_runtime_config_bridge.py`、`test_plugin_bootstrap.py` 手动 set/复位这些 global,测试之间存在顺序耦合,无法并行;
|
||||
- `_RUNTIME_CONFIG_OVERRIDES` 被 34 处 `load_database_settings()` 隐式读取,配置改动的影响面在调用点完全不可见。
|
||||
- **修复建议**:
|
||||
1. `terminate()` 中调用 `configure_astrbot_provider_bridge(None, None)` 清场;
|
||||
2. 把两组 global 收进小对象(`AstrBotRuntimeBridge` / `RuntimeConfigStore`)并暴露 `reset()`,测试用 fixture 统一 setup/teardown;
|
||||
3. `_runtime_loop` 的读改用一次性局部快照 + `loop.is_closed()` 双检(现有代码已做了一半),并在 `run_coroutine_threadsafe` 外包 `try/except RuntimeError`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 无组合根导致每次路由调用都重读 `config.yaml` 并重建整棵对象树
|
||||
|
||||
- **位置**:34 处 `Database(load_database_settings())`(23 个 route 模块 + 4 个 service 模块);`database/db_helper.py:64-83, 297-298`
|
||||
- **问题**:`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
|
||||
# database/db_helper.py:297-298
|
||||
def load_database_settings(config_path: str | Path = "config.yaml") -> DatabaseSettings:
|
||||
return DatabaseSettings.from_mapping(load_config_payload(config_path))
|
||||
|
||||
# database/db_helper.py:64-69
|
||||
def load_config_payload(config_path: str | Path = "config.yaml") -> dict[str, Any]:
|
||||
path = resolve_config_path(config_path)
|
||||
payload = load_config_file_payload(path) # ← 每次 read_text + 自研 YAML 子集解析
|
||||
if _should_apply_runtime_overrides(path):
|
||||
return _merge_mappings(payload, _RUNTIME_CONFIG_OVERRIDES)
|
||||
return payload
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/routes/node_routes.py:316, 327
|
||||
database = Database(load_database_settings()) # 第 1 次读盘
|
||||
...
|
||||
config_payload = load_config_payload() # 第 2 次读盘
|
||||
```
|
||||
- **影响**:耦合表现为"每个 route 都必须知道整棵依赖树怎么装",35 个工厂各自维护同一份知识;性能上把配置文件 IO 放进了请求热路径;行为上任何人改 `config.yaml` 会在下一次请求半途生效,同一次请求内两次读取甚至可能读到不同内容。
|
||||
- **修复建议**:`load_config_payload` 加进程级缓存(按 `(path, mtime)` 失效),`set_runtime_config_overrides` 时主动 invalidate;组合根(见 P1 第二条)持有单例 service 图,route 只从容器取。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 服务穿透邻居对象的私有依赖取 `Database`(迪米特法则违规)
|
||||
|
||||
- **位置**:`backend/services/workflow_round_service.py:67`、`backend/services/workflow_round_worker_runtime.py:193`、`backend/routes/round_routes.py:139`、`backend/routes/workflow_routes.py:94`、`backend/routes/profile_routes.py:156`
|
||||
- **问题**:拿不到 `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
|
||||
workflow_repository, image_repository, job_repository,
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/workflow_round_worker_runtime.py:192-193
|
||||
generation_service = create_generation_service()
|
||||
database = generation_service.queue_service.repository.database # ← 三级穿透
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/routes/round_routes.py:138-139
|
||||
generation_service = create_generation_service()
|
||||
database = generation_service.queue_service.repository.database
|
||||
```
|
||||
- **影响**:`Repository.database` 从实现细节变成了事实上的公开 API,任何仓储重构(例如改为持有连接池而非 `Database`)会同时打断 5 个调用点;对象图的真实依赖在构造函数签名上完全看不见。
|
||||
- **修复建议**:组合根统一持有 `Database` 实例并显式注入;过渡期至少在 `ResourceAccessService` 等处把 `ProfileRepository` 作为构造参数传入,而不是就地用穿透来的 `database` 现造。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `generation_service` 内部 `event_bus` 取用方式自相矛盾
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:104` vs `:1416-1427`
|
||||
- **问题**:同一个类里有两套取总线的写法:`self.event_bus`(构造注入,`_publish()` 用,5 处)和 `self.workflow_service.event_bus`(穿透邻居,2 处)。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/generation_service.py:104
|
||||
self.event_bus = event_bus
|
||||
# :1701-1703
|
||||
def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
|
||||
if self.event_bus:
|
||||
self.event_bus.publish(event_type, payload)
|
||||
|
||||
# :1416-1427(同一个类,换了个总线来源)
|
||||
if self.workflow_service.event_bus:
|
||||
self.workflow_service.event_bus.publish("workflow.node_status_changed", {...})
|
||||
self.workflow_service.event_bus.publish("workflow.node_updated", {...})
|
||||
```
|
||||
- **影响**:在 `_create_generation_service()` 里两者恰好是同一个 `DEFAULT_EVENT_BUS`,所以现在没暴露;但只要有人用未注入 `event_bus` 的 `WorkflowService` 构造 `GenerationService`(`node_material_routes`、`branch_routes`、`history_routes`、`review_routes` 的 `WorkflowService` 就是这种),`workflow.node_status_changed` 就会静默丢失——与 P1 第一条同源。
|
||||
- **修复建议**:`1416-1427` 改用 `self._publish(...)`,删除 `self.workflow_service.event_bus` 引用。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 冗余的函数内 import(已在模块顶部导入同一模块)
|
||||
|
||||
- **位置**:`backend/services/generation_service.py:1493`、`:1506`
|
||||
- **问题**:模块顶部 `generation_service.py:17-24` 已经 `from backend.services.prompt_governance_service import (...)` 导入了 6 个名字,函数体内又对同一模块做了两次局部 import。这不是循环依赖规避(该模块无反向依赖),纯属遗漏。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# 顶部 :17-24 已有
|
||||
from backend.services.prompt_governance_service import (
|
||||
GenerationFailureClassifier, GenerationRouteService, ImageModerationService,
|
||||
PromptModerationService, PromptSemanticNormalizer, PromptTranslationService,
|
||||
)
|
||||
# :1492-1494
|
||||
if moderation is None:
|
||||
from backend.services.prompt_governance_service import PromptModerationDecision
|
||||
moderation = PromptModerationDecision("safe", 1.0, [], ["moderation_not_configured"], "allow", None, "none", None, "")
|
||||
# :1505-1507
|
||||
else:
|
||||
from backend.services.prompt_governance_service import GenerationRouteDecision
|
||||
route = GenerationRouteDecision(...)
|
||||
```
|
||||
- **影响**:制造"这里有循环依赖"的误导性信号,干扰后续重构判断(本次审计正是靠函数内 import 定位循环依赖痕迹)。
|
||||
- **修复建议**:把 `PromptModerationDecision`、`GenerationRouteDecision` 并入顶部 import 块。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `main.py` 内 66 条配置映射被正反两个方向各写一遍
|
||||
|
||||
- **位置**:`main.py:108-172`(正向映射表,66 条)vs `main.py:1929-2205`(反向映射,279 行手写代码)
|
||||
- **问题**:`_RUNTIME_PATH_TO_ASTRBOT_KEY` 用声明式 dict 表达 "ImageStudio 配置路径 → AstrBot 配置键";`_runtime_config_patch_from_mapping()` 用 279 行命令式代码表达完全相同的 66 条关系的反方向。脚本比对确认当前两侧覆盖的 66 个 AstrBot 键完全一致——即两份数据现在同步,但靠人工维持。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# main.py:108-113(声明式)
|
||||
_RUNTIME_PATH_TO_ASTRBOT_KEY = {
|
||||
"plugin.display_name": "display_name",
|
||||
"generation.default_model": "default_generation_model",
|
||||
"generation.provider.provider_id": "generation_provider_id",
|
||||
... # 共 66 条
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:1929, 1946-1949(命令式,同一批关系的反方向)
|
||||
def _runtime_config_patch_from_mapping(mapping: Mapping[str, Any]) -> dict[str, Any]:
|
||||
...
|
||||
display_name = _runtime_text(_runtime_value(mapping, "display_name", fallback=plugin.get("display_name", _MISSING)))
|
||||
if display_name:
|
||||
_set_nested(patch, ("plugin", "display_name"), display_name)
|
||||
default_model = _runtime_text(_runtime_value(mapping, "default_generation_model"))
|
||||
if default_model:
|
||||
_set_nested(patch, ("generation", "default_model"), default_model)
|
||||
```
|
||||
- **影响**:新增一个配置项需要在两个相隔 1800 行的位置各改一次;只改一边会造成"能读不能写"或"能写不能读"的单向配置,且不会有任何报错。
|
||||
- **修复建议**:保留 dict 作为唯一真相,`_runtime_config_patch_from_mapping` 改为遍历 `_RUNTIME_PATH_TO_ASTRBOT_KEY.items()` + `_set_nested(patch, tuple(path.split(".")), value)`,只把少数需要特殊类型转换的键(`postgresql.port` 转 int、`*_enabled` 转 bool、allowlist 拆列表)保留为显式分支。整块可从 279 行压到 ~50 行,并整体搬到 `core/astrbot_config_mapping.py`。
|
||||
|
||||
---
|
||||
|
||||
## 附录 A · 扇入 / 扇出排行(179 个模块,模块粒度有向图)
|
||||
|
||||
### 扇入 Top 10(被最多模块 import)
|
||||
|
||||
| 扇入 | 模块 | 层 | 评价 |
|
||||
|---|---|---|---|
|
||||
| 65 | `core.identity` | core | 健康。纯 `RequestContext` 值对象,零下行依赖,理想的横切基础。 |
|
||||
| 56 | `database.db_helper` | db | **不健康**。既是 `Database`/`DatabaseSettings`,又是 YAML 配置加载器(`load_config_payload`),两个无关职责挤在一个高扇入模块里。 |
|
||||
| 53 | `backend.dto.common` | dto | **位置错误**。事实上的全局错误契约,却被放在 `backend` 包下,逼得 `core/*` 反向依赖(见 P2 第一条)。 |
|
||||
| 31 | `backend.routes.common` | route | 可接受但命名误导。只有 17 行的 `handle_request`,且只被 route 模块 import(已验证 route 包外无引用)。 |
|
||||
| 31 | `core.security` | core | 健康(但需摘掉对 `backend.dto.common` 的依赖)。 |
|
||||
| 30 | `core.audit_service` | core | 中性。审计是横切关注点,扇入高合理;但它 import `database.db_helper` 使 `core` 不再是底层。 |
|
||||
| 19 | `database.repositories.workflow_repository` | db | 合理,工作流是核心聚合。 |
|
||||
| 16 | `backend.routes.params` | route | 同 `routes.common`。 |
|
||||
| 16 | `database.repositories.profile_repository` | db | 合理。 |
|
||||
| 15 | `backend.services.workflow_service` | service | **风险点**。唯一进入 Top10 的 service,是耦合簇的中心(见附录 B)。 |
|
||||
|
||||
### 扇出 Top 10(import 最多别人)
|
||||
|
||||
| 扇出 | 模块 | 行数 | 评价 |
|
||||
|---|---|---|---|
|
||||
| 31 | `backend.routes.node_routes` | 490 | **最不健康**。它是事实上的组合根(`_create_generation_service` 装配 20+ 对象),却挂在 route 层,还被 service 反向 import。 |
|
||||
| 29 | `backend.services.advanced_material_service` | 1856 | **God service**。45 个方法 + 14 参数构造函数 + 自带装配工厂 `create_advanced_material_service()`。 |
|
||||
| 22 | `main` | 2580 | 见附录 C。 |
|
||||
| 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 模块并列 | — | route 层平均扇出 ~12,全部来自各自的 `_create_*_service()`。 |
|
||||
|
||||
**关键指标**:`backend/routes` 平均扇出 12,而理想 route 模块应只依赖 1 个 service + 契约层(3-4)。这个 3-4 倍的超额完全来自散落的装配代码。
|
||||
|
||||
---
|
||||
|
||||
## 附录 B · Service 间直连耦合簇
|
||||
|
||||
模块级**无循环导入**(Tarjan SCC 只在 `adapters/__init__` ↔ `adapters.onebot11_adapter` / `adapters.wechat_adapter` 之间,属 `__init__` re-export 的正常形态)。但存在两个高密度直连簇。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph 簇1["簇 1:workflow / generation(19 条 service→service 直连边)"]
|
||||
NR["routes.node_routes<br/>组合根(位置错误)"]
|
||||
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)。虚线为 3 条方向违规边。
|
||||
|
||||
**簇 2(advanced material / style)**:`advanced_material_service`(1856 行)→ `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,runtime,bootstrap}`、`prompt_governance_service`、`event_stream_service` —— 单模块直连 12 个 service,且自己承担装配(`create_advanced_material_service()` 在 `advanced_material_service.py:1700-1764`)。
|
||||
|
||||
**没有任何接口/协议隔离**:全仓无 `Protocol` / `ABC` 定义的 service 接口,所有 service→service 都是具体类硬 import。唯一的"接口化"痕迹是 `chat_workflow_service.py:22` 的 `Dispatcher = Callable[..., dict[str, Any]]`,但它是完全无类型约束的字符串分发(见 P2 第三条)。
|
||||
|
||||
---
|
||||
|
||||
## 附录 C · `main.py` 2580 行职责分解
|
||||
|
||||
| 行号区间 | 行数 | 职责 | 归属评价 |
|
||||
|---|---|---|---|
|
||||
| 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 行纯转发**(`async for result in self.imagestudio_X(...): yield result`) | **全部删除**,改用数据驱动注册 |
|
||||
| 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`,并按 P3 第三条压缩到 ~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,加少量粘合)。
|
||||
|
||||
短别名块(1299-1463)的具体替代方案:
|
||||
|
||||
```python
|
||||
# 用注册表替代 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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录 D · 解耦方案优先级
|
||||
|
||||
| 优先级 | 动作 | 消除的问题 | 影响面 |
|
||||
|---|---|---|---|
|
||||
| 1 | 建 `backend/composition.py` 唯一组合根,迁入 35 个 `_create_*_service()` | P1-2(service→route)、P2-2(装配复制)、P2-4(重复读盘)、P3-1(属性穿透) | 35 个 route 文件 + 4 个 service |
|
||||
| 2 | 补齐 4 处 `event_bus=`,并把 `event_bus` 默认值改为 `get_default_event_bus()` | P1-1(事件静默丢失)、P3-2 | 5 个文件,改动 <20 行 |
|
||||
| 3 | 下沉 `branch_state_for/with_branch_state/BRANCH_STATE_FIELDS` → `core/branch_state.py` | P1-3(db→service) | 3 个 repository + 3 个 service |
|
||||
| 4 | 下沉 `ApiError/ErrorCode` → `core/errors.py`;下沉 `load_config_payload` → `core/config_loader.py` | P2-1(core→backend、core→db) | 53 + 56 个 import 点(可用 re-export 渐进) |
|
||||
| 5 | `main.py` 按附录 C 拆分为 6 个模块 | 职责膨胀 | 仅 main.py + 新增 6 文件 |
|
||||
| 6 | `ChatWorkflowService` 的 69 处字符串 dispatch 换成类型化门面或直接依赖 service | P2-3 | 1 个 service 文件 |
|
||||
| 7 | `EventBus` 加锁 + 异常隔离,并把 3 组"通知型"直连迁到总线;否则删掉 `subscribe/unsubscribe` | P2-2(event_bus 空转) | `core/event_bus.py` + 3 个 service |
|
||||
| 8 | 拆 `advanced_style_set_service.py`(4491 行 / 1 类 / 81 个私有函数)与 `advanced_material_service.py`(1856 行 / 45 方法) | God object | 2 个大文件 |
|
||||
103
审计/findings/C0-测试实跑结果.md
普通文件
103
审计/findings/C0-测试实跑结果.md
普通文件
|
|
@ -0,0 +1,103 @@
|
|||
# C0 · 测试实跑结果(人工执行)
|
||||
|
||||
> 本文件记录审计者**实际运行**测试套件的结果,而非静态阅读推断。
|
||||
> 执行环境:Windows 11,仓库 `codex/character-profile-document-import` @ `8040a1b`
|
||||
|
||||
---
|
||||
|
||||
## 摘要
|
||||
|
||||
后端 263 个 pytest 用例、前端 26 个 node:test 用例**全部通过**,无失败无跳过。但前端"测试"实为**对 `App.vue` 源码做正则字符串匹配**,不加载组件、不执行任何运行时逻辑,属于极脆弱的防回归快照;后端套件耗时 188 秒(0.72 s/用例)偏慢,提示存在真实 IO 或重复建库开销。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P3-轻微] 后端测试全绿,但单用例耗时 0.72 秒偏高
|
||||
|
||||
- **位置**:`tests/`(45 个文件 / 11,559 行)
|
||||
- **实测**:
|
||||
```
|
||||
263 passed in 188.72s (0:03:08)
|
||||
```
|
||||
- **问题**:263 个用例耗时 188 秒,平均 0.72 s/用例。纯单元测试不应有这个量级。结合审计中发现的 `.tmp_pytest_*` 目录(19 个,单个最大 69 MB,合计约 515 MB),说明测试会**在真实文件系统上建库/落盘**,且**用例间未复用**。
|
||||
- **影响**:CI 反馈周期长;本地开发者倾向于跳过测试;磁盘持续膨胀(已累积 515 MB 残留)。
|
||||
- **修复建议**:
|
||||
1. 用 `pytest --durations=25` 定位最慢用例,优先改造。
|
||||
2. 数据库夹具改为 **session 级** + 每用例事务回滚,替代"每用例重建库":
|
||||
```python
|
||||
@pytest.fixture(scope="session")
|
||||
def _engine(tmp_path_factory): ... # 建库一次
|
||||
@pytest.fixture
|
||||
def db(_engine): # 每用例包事务并回滚
|
||||
conn = _engine.connect(); tx = conn.begin()
|
||||
yield conn
|
||||
tx.rollback(); conn.close()
|
||||
```
|
||||
3. 临时目录统一用 `tmp_path_factory`(pytest 自动清理),停止写入仓库内的 `.tmp_pytest_*`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 前端"契约测试"是源码字符串匹配,不是行为测试
|
||||
|
||||
- **位置**:`frontend/tests/*.test.mjs`(8 个文件 / 26 个用例)
|
||||
- **实测**:全部通过(`pass 26 / fail 0`,耗时 411 ms)
|
||||
- **问题**:这些用例**把 `App.vue` 当纯文本读进来做正则匹配**,从不挂载组件、不执行函数。典型实现(`frontend/tests/workflow-profile-card-wiring.test.mjs:8-30`):
|
||||
|
||||
```js
|
||||
const app = await readFile(appPath, "utf8")
|
||||
const start = app.indexOf("async function archiveSelectedWorkflowFinal()")
|
||||
const end = app.indexOf("async function changeSelectedWorkflowLifecycle", start)
|
||||
assert.notEqual(start, -1)
|
||||
const finalizeFunction = app.slice(start, end)
|
||||
|
||||
assert.match(finalizeFunction, /endpoints\.workflowFinalizeCard\(workflowId\)/)
|
||||
assert.doesNotMatch(finalizeFunction, /endpoints\.workflowHistory/)
|
||||
assert.match(app, /avatar: selectedImageFor\("headshot"\)/)
|
||||
```
|
||||
|
||||
即:**用"函数 A 的源码文本里出现了 endpoints.X 且没出现 endpoints.Y"来代替"调用行为正确"**。
|
||||
|
||||
- **影响**(三重):
|
||||
1. **假阴性**:把 `archiveSelectedWorkflowFinal()` 改名、换成箭头函数、或在参数间加空格 → `indexOf` 返回 -1 → 测试**红**,但代码完全正确。测试成了重构的阻力。
|
||||
2. **假阳性**:函数体里**写着** `endpoints.workflowFinalizeCard(workflowId)` 但被 `if (false)` 包住、或 `await` 漏了、或响应处理错了 → 测试**绿**,功能实际是坏的。它只能证明"字符出现过"。
|
||||
3. **锁死行号依赖**:`app.slice(start, end)` 依赖两个函数在文件中的**相邻顺序**。调整声明顺序会让断言作用在错误的代码段上,静默失效。
|
||||
|
||||
- **根因**:这是 `App.vue` 22,563 行巨石的**直接后果** —— 组件无法被挂载测试(无 props、无边界、全局状态耦合),于是退而求其次去 grep 源码。**测试形态是架构债的症状,不是独立问题。**
|
||||
|
||||
- **修复建议**(与 App.vue 拆分绑定推进):
|
||||
1. 短期:保留这些用例作为"防回归护栏",但**在文件头注释写明它们是文本快照**,避免后来者误以为有行为覆盖。
|
||||
2. 中期:随 `App.vue` 拆分(见 [A8](A8-前端App主体.md) / [C2](C2-前端精简空间.md)),把被测逻辑先抽成**纯函数 composable**(如 `useWorkflowFinalize()`),对 composable 写真实单元测试 —— 无需 DOM,收益最大:
|
||||
```js
|
||||
import { buildFinalizePayload } from "../src/features/workflow/use-workflow-finalize"
|
||||
test("finalize payload targets the atomic card endpoint", () => {
|
||||
const p = buildFinalizePayload(workflowFixture)
|
||||
assert.equal(p.endpoint, endpoints.workflowFinalizeCard("wf_1"))
|
||||
assert.ok(p.body.idempotency_key)
|
||||
})
|
||||
```
|
||||
3. 长期:引入 `@vue/test-utils` + `vitest`,对拆分后的子组件做挂载测试。项目已用 Vite 6,接入 vitest 边际成本极低。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 前端测试脚本未纳入统一入口
|
||||
|
||||
- **位置**:`frontend/package.json:12-13`
|
||||
- **问题**:
|
||||
```json
|
||||
"test:contracts": "node --test tests/*.test.mjs",
|
||||
"test:ui": "node --test tests/ui-redesign-smoke.test.mjs tests/ui-theme-contract.test.mjs"
|
||||
```
|
||||
没有 `"test"` 脚本;`test:ui` 覆盖的 2 个文件是 `test:contracts` 的**子集**(重复定义)。同时**没有 `typecheck` 之外的 CI 聚合入口**。
|
||||
- **影响**:新贡献者 `npm test` 得到 npm 默认报错;CI 容易漏跑。
|
||||
- **修复建议**:
|
||||
```json
|
||||
"test": "npm run typecheck && npm run test:contracts"
|
||||
```
|
||||
并删除冗余的 `test:ui`。
|
||||
|
||||
---
|
||||
|
||||
## 对照:测试覆盖缺口
|
||||
|
||||
后端 `backend/services/` 共 **70** 个 service,`tests/` 共 45 个测试文件。即便一对一映射也存在 25+ 个 service 无专属测试文件。具体缺口清单见 [C3-测试与仓库卫生.md](C3-测试与仓库卫生.md)。
|
||||
692
审计/findings/C1-后端精简空间.md
普通文件
692
审计/findings/C1-后端精简空间.md
普通文件
|
|
@ -0,0 +1,692 @@
|
|||
# C1 · 后端代码精简空间(重复代码 / 死代码 / 过度设计)
|
||||
|
||||
> 审计范围(实际逐行 Read 过的文件):
|
||||
> `main.py`
|
||||
> `backend/route_registry.py`、`backend/routes/common.py`、`backend/routes/params.py`、`backend/routes/wardrobe_routes.py`、`backend/routes/branch_routes.py`、`backend/routes/job_routes.py`、`backend/routes/node_routes.py`、`backend/routes/material_routes.py`、`backend/routes/profile_routes.py`、`backend/routes/workflow_routes.py`、`backend/routes/web_routes.py`、`backend/routes/image_routes.py`、`backend/routes/profile_card_routes.py`、`backend/routes/round_routes.py`、`backend/routes/advanced_material_routes.py`
|
||||
> `backend/dto/common.py`、`backend/dto/material_dto.py`、`backend/dto/workflow_round_dto.py`、`backend/dto/chat_command_dto.py`(+ 全 dto 目录 AST 扫描)
|
||||
> `backend/services/event_stream_service.py`、`backend/services/web_hosting_service.py`、`backend/services/advanced_material_worker_runtime.py`、`backend/services/workflow_round_worker_runtime.py`、`backend/services/settings_service.py`(尾部)、`backend/services/workflow_service.py`(事件发布部分)、`backend/services/advanced_style_set_service.py`(尾部工具函数)、`backend/services/material_service.py`(工厂)、`backend/services/queue_service.py`(尾部)
|
||||
> `core/db_helper` → `database/db_helper.py`、`core/config_service.py`、`core/identity.py`、`core/security.py`、`core/audit_service.py`、`core/event_bus.py`、`core/queue_manager.py`、`core/interop.py`、`core/webhook.py`、`core/interactions.py`、`core/fsm.py`
|
||||
> `database/repositories/profile_repository.py`、`workflow_repository.py`、`wardrobe_repository.py`、`advanced_material_repository.py`、`workflow_cross_review_repository.py`、`job_repository.py`(+ 全 repositories 目录 grep 交叉验证)
|
||||
> `engines/image_provider.py`、`engines/vision_provider.py`
|
||||
> `adapters/webui_adapter.py`、`adapters/wechat_adapter.py`、`adapters/onebot11_adapter.py`
|
||||
|
||||
## 摘要
|
||||
|
||||
后端真实源码约 **54,551 行**(`main.py + backend/ + core/ + database/ + engines/ + adapters/`)。系统性扫描后确认存在三类可量化冗余:**(1) 复制粘贴型工具函数**——`_optional_text` 被独立定义 30 次、`_string_list` 18 次、`_json_or_none` 12 次,且部分同名函数语义已经悄悄分叉(`_string_list` 至少有 6 种不同行为),这已经不只是冗余而是语义地雷;**(2) 仓储层连接样板**——`conn = self.database.connect() / try / finally: conn.close()` 在 13 个 repository + `core/audit_service.py` 中出现 **131 次**,完全可由一个 `contextmanager` 收敛;**(3) 确证死代码**——`core/queue_manager.py` 整文件(112 行)无任何模块引用,`EventBus.subscribe/unsubscribe` 从未被调用导致 `publish` 的 handler 分发链路整体空转,另有 29 个函数/类/方法全仓引用数为 0。
|
||||
|
||||
更值得注意的是,复制粘贴已经造成**两处真实行为差异**:`backend/routes/branch_routes.py` 的 `_create_workflow_service()` 漏掉了 `event_bus=`,导致分支创建/切换事件永远不进 SSE;`engines/vision_provider.py` 的 `endpoint_url()` 缺少 image 版本里的 `/v1` 去重逻辑,会拼出 `/v1/v1/chat/completions`。
|
||||
|
||||
保守估算(不含高风险的路由装饰器改造)可削减 **约 1,800 行**,约占后端 3.3%;含路由层改造约 **2,100 行**。以下按投入产出比排序。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P1-严重] 仓储层连接样板重复 131 次,可用一个上下文管理器收敛(削减 ≈390 行)
|
||||
|
||||
- **位置**:`database/repositories/wardrobe_repository.py:84`、`database/repositories/workflow_repository.py:100`、`database/repositories/advanced_material_repository.py:346`、`core/audit_service.py:83` 等共 131 处(`grep -c 'conn.close()' database/repositories/*.py core/audit_service.py` = 132,`finally:` = 131)
|
||||
- **问题**:每个仓储方法都手写 `conn = self.database.connect()` / `try:` / `finally: conn.close()`,写方法再额外手写 `except Exception: _rollback(conn); raise`。`_rollback` 本身还被独立定义了 3 次(`advanced_material_repository.py:2119`、`workflow_cross_review_repository.py:1464`、`workflow_round_repository.py:1378`)。
|
||||
- **代码**(`database/repositories/advanced_material_repository.py:346-366`,三个方法的样板一模一样):
|
||||
```python
|
||||
def get_import(self, import_id: str) -> AdvancedMaterialImport | None:
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
row = conn.execute(
|
||||
f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE import_id = {self.placeholder}",
|
||||
(import_id,),
|
||||
).fetchone()
|
||||
finally:
|
||||
conn.close()
|
||||
return _row_to_import(row) if row else None
|
||||
|
||||
def get_import_by_idempotency_key(self, idempotency_key: str) -> AdvancedMaterialImport | None:
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
row = conn.execute(
|
||||
f"SELECT {IMPORT_COLUMNS} FROM advanced_material_imports WHERE idempotency_key = {self.placeholder}",
|
||||
(idempotency_key,),
|
||||
).fetchone()
|
||||
finally:
|
||||
conn.close()
|
||||
return _row_to_import(row) if row else None
|
||||
```
|
||||
- **影响**:131 处样板 ≈ 520 行纯噪音;更严重的是"忘记 rollback"只能靠人工 review 保证(`profile_repository.update` 就没有 rollback 分支,`advanced_material_repository.update_import` 有)。任何连接策略变更(连接池 / WAL / 超时)需要改 131 处。
|
||||
- **修复建议**:在 `database/repositories/__init__.py` 建 `BaseRepository`:
|
||||
```python
|
||||
class BaseRepository:
|
||||
def __init__(self, database: Database) -> None:
|
||||
self.database = database
|
||||
|
||||
@property
|
||||
def placeholder(self) -> str:
|
||||
return self.database._placeholder
|
||||
|
||||
@contextmanager
|
||||
def _connect(self, *, write: bool = False):
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
yield conn
|
||||
if write:
|
||||
conn.commit()
|
||||
except Exception:
|
||||
if write:
|
||||
_rollback(conn)
|
||||
raise
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def _fetch_one(self, sql: str, params: tuple, mapper): ...
|
||||
def _fetch_all(self, sql: str, params: tuple, mapper): ...
|
||||
```
|
||||
上例的 `get_import` 塌缩成 3 行。**预计削减 ≈390 行**,并顺带消除 13 份重复的 `__init__` + `placeholder` 属性(`profile_repository.py:121-127`、`wardrobe_repository.py:41-47` 等 13 处)。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `_optional_text` 被独立定义 30 次,且 `backend/routes/params.py` 已有的同名别名却无人使用(削减 ≈145 行)
|
||||
|
||||
- **位置**:30 个定义点,包括 `backend/services/queue_service.py:713`、`backend/services/generation_service.py:2112`、`backend/services/workflow_round_service.py:1592`、`database/repositories/workflow_round_repository.py:1343`、`engines/single_flow.py:241`、`engines/vision_provider.py:450`、`core/astrbot_provider_bridge.py:349`、`adapters/wechat_adapter.py:77`、`adapters/onebot11_adapter.py:96` …
|
||||
- **问题**:同一 5 行函数被复制 30 份;而 `backend/routes/params.py:22` 早就提供了 `optional_text = optional_str` 别名,并且注释宣称"两个名字在后端都在用"——实际 `grep` 显示 `optional_text` 从未被任何模块 import,注释是错的。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/params.py:20-22
|
||||
# Both names are used for this coercion across the backend. Keep the alias so
|
||||
# route and service code can use the vocabulary that best fits the field.
|
||||
optional_text = optional_str
|
||||
```
|
||||
```python
|
||||
# backend/services/queue_service.py:713 —— 与另外 26 份逐字节相同
|
||||
def _optional_text(value: Any) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
text = str(value).strip()
|
||||
return text or None
|
||||
```
|
||||
但另外 3 份语义**不同**:
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:349 / adapters/wechat_adapter.py:77 / adapters/onebot11_adapter.py:96
|
||||
def _optional_text(value: Any) -> str | None:
|
||||
text = str(value or "").strip() # 0 / False / [] 会被当成 None,主流版本不会
|
||||
return text or None
|
||||
```
|
||||
- **影响**:150 行冗余;且 `str(value or "")` 变体对 `0` / `False` 的处理与主流版本不一致,跨模块搬运代码时会静默改变行为。
|
||||
- **修复建议**:新建 `core/coerce.py`(或复用 `backend/routes/params.py`,但要把它从 `routes` 包挪到 `core`,因为 `database/repositories` 和 `engines` 依赖 routes 包是层级倒置),导出 `optional_text/optional_int/optional_float/as_bool/string_list/mapping`;30 处改为 `from core.coerce import optional_text as _optional_text`。删掉 `params.py:22` 的死别名及其错误注释。**预计削减 ≈145 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `_string_list` 定义 18 次且至少有 6 种不同语义——同名不同义的语义地雷(削减 ≈90 行 + 消除隐患)
|
||||
|
||||
- **位置**:`backend/services/composition_builder.py:279`、`backend/services/generation_service.py:2417`、`backend/services/prompt_expansion_service.py:257`、`backend/services/workflow_round_service.py:1544`、`backend/services/advanced_style_set_service.py:4288`、`backend/services/material_normalization_service.py:368`、`core/astrbot_provider_bridge.py:344`、`engines/vision_provider.py:432`、`engines/review_flow.py:430` 等共 18 处
|
||||
- **问题**:同名函数在不同模块行为完全不同——是否对逗号字符串切分、是否去重、是否排序、是否接受 `tuple/set`,四个维度自由组合。
|
||||
- **代码**(同名,四种不同结果):
|
||||
```python
|
||||
# core/astrbot_provider_bridge.py:344 —— 逗号切分 + 去重 + 排序
|
||||
def _string_list(value: Any) -> list[str]:
|
||||
values = value.split(",") if isinstance(value, str) else value if isinstance(value, list) else []
|
||||
return sorted({str(item).strip() for item in values if str(item).strip()})
|
||||
|
||||
# backend/services/generation_service.py:2417 —— 逗号切分 + 不去重 + 不排序
|
||||
def _string_list(value: Any) -> list[str]:
|
||||
if isinstance(value, str):
|
||||
values = value.split(",")
|
||||
elif isinstance(value, (list, tuple, set)):
|
||||
values = value
|
||||
else:
|
||||
return []
|
||||
return [str(item).strip() for item in values if str(item).strip()]
|
||||
|
||||
# backend/services/workflow_round_service.py:1544 —— 不接受字符串(字符串直接返回 [])+ 去重保序
|
||||
def _string_list(value: Any) -> list[str]:
|
||||
values = value if isinstance(value, list) else []
|
||||
return list(dict.fromkeys(str(item).strip() for item in values if str(item).strip()))
|
||||
|
||||
# backend/services/prompt_expansion_service.py:257 —— 字符串整体作为单元素,不切分
|
||||
def _string_list(value: Any) -> list[str]:
|
||||
if isinstance(value, str):
|
||||
return [value] if value.strip() else []
|
||||
...
|
||||
```
|
||||
- **影响**:tags / prompt_parts 这类字段在 service 间流转时,同一份数据经过不同模块会得到顺序不同、元素数不同的列表。已经导致 prompt 片段顺序在 `advanced_style_set_service`(保序去重)与 `astrbot_provider_bridge`(排序)之间不可预测。任何人跨模块复制一行调用都会踩坑。
|
||||
- **修复建议**:在 `core/coerce.py` 定义三个语义**显式命名**的函数替代:`csv_tags(value)`(切分+去重+保序)、`prompt_parts(value)`(不切分+去重+保序)、`sorted_tags(value)`(切分+去重+排序),18 处按实际语义各自替换。**预计削减 ≈90 行**,并把语义分叉从隐式变成显式。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `core/queue_manager.py` 整文件死代码(112 行,零引用)
|
||||
|
||||
- **位置**:`core/queue_manager.py:1-112`
|
||||
- **问题**:`QueueManager` / `QueueItem` 是一套完整的内存队列实现(enqueue / dequeue / complete / fail / retry / summary + FSM 校验),但全仓(含 `tests/`)没有任何模块 import `core.queue_manager`,也没有任何地方引用 `QueueManager` 或 `QueueItem`。真实队列走的是 `backend/services/queue_service.py` + `database/repositories/job_repository.py` 的持久化实现。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/queue_manager.py:42-70
|
||||
class QueueManager:
|
||||
def __init__(self):
|
||||
self._pending: deque[str] = deque()
|
||||
self._items: dict[str, QueueItem] = {}
|
||||
self._idempotency_index: dict[str, str] = {}
|
||||
|
||||
def enqueue(self, payload: dict[str, Any], *, idempotency_key: str | None = None) -> QueueItem:
|
||||
...
|
||||
```
|
||||
验证:`grep -rn "queue_manager|QueueItem" --include=*.py .` 的全部命中都落在 `core/queue_manager.py` 自身。
|
||||
- **影响**:112 行需要维护的"影子队列实现",与真实队列的状态机语义并行存在,新人极易误用;且它单独依赖 `core.fsm.task_transition`,让 `fsm` 看起来比实际有更多消费者。
|
||||
- **修复建议**:整文件删除。**削减 112 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 复制粘贴造成的真实行为差异:`branch_routes` 漏配 `event_bus`,分支事件永不推送
|
||||
|
||||
- **位置**:`backend/routes/branch_routes.py:62-68`(对比 `backend/routes/node_routes.py:305-312`、`backend/routes/workflow_routes.py:143-150`、`backend/routes/profile_routes.py:174-181`)
|
||||
- **问题**:`_create_workflow_service()` 在 4 个 route 模块里各复制了一份,其中 `branch_routes` 那份漏掉了 `event_bus=get_default_event_bus()`。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/branch_routes.py:62-68 ← 缺 event_bus
|
||||
def _create_workflow_service() -> WorkflowService:
|
||||
database = Database(load_database_settings())
|
||||
return WorkflowService(
|
||||
workflow_repository=WorkflowRepository(database),
|
||||
profile_repository=ProfileRepository(database),
|
||||
audit_service=AuditService(database),
|
||||
)
|
||||
|
||||
# backend/routes/workflow_routes.py:143-150 ← 有 event_bus
|
||||
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=get_default_event_bus(),
|
||||
)
|
||||
```
|
||||
而 `WorkflowService._publish` 是空守卫:
|
||||
```python
|
||||
# backend/services/workflow_service.py:1012-1014
|
||||
def _publish(self, event_type: str, payload: dict[str, Any]) -> None:
|
||||
if self.event_bus:
|
||||
self.event_bus.publish(event_type, payload)
|
||||
```
|
||||
`create_branch`(`workflow_service.py:514`)与 `switch_branch`(`workflow_service.py:640`)都调用了 `_publish`。
|
||||
- **影响**:走 HTTP `POST /workflows/{id}/branches` 和 `POST /workflows/{id}/switch-branch` 创建/切换分支时,事件被静默吞掉,前端 SSE(`backend/routes/event_routes.py`)永远看不到分支变更,且不报错——典型的"复制粘贴少复制一行"缺陷。
|
||||
- **修复建议**:把 22 个 `_create_*_service()` 工厂集中到 `backend/services/factory.py`(或 `backend/container.py`),每种 service 只保留一份构造。同时解决另一个层级倒置问题:`backend/services/workflow_round_worker_runtime.py:10` 反向 `from backend.routes.node_routes import create_generation_service`,而 `node_routes.py:393-396` 的 `create_generation_service()` 只是 `return _create_generation_service()` 的纯转发壳。**削减 ≈20 行 + 修一个功能缺陷 + 消除 service→routes 反向依赖**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 复制粘贴造成的第二个行为差异:`VisionProviderConfig.endpoint_url` 缺 `/v1` 去重
|
||||
|
||||
- **位置**:`engines/vision_provider.py:40-43`(对比 `engines/image_provider.py:51-56`)
|
||||
- **问题**:两个 `endpoint_url()` 是明显的复制关系,但 image 版本有 `/v1` 去重规则,vision 版本没有。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/image_provider.py:51-56
|
||||
def endpoint_url(self) -> str:
|
||||
base = self.base_url.rstrip("/")
|
||||
endpoint = self.image_endpoint if self.image_endpoint.startswith("/") else f"/{self.image_endpoint}"
|
||||
if base.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"):
|
||||
endpoint = endpoint[3:] # ← 去重
|
||||
return f"{base}{endpoint}"
|
||||
|
||||
# engines/vision_provider.py:40-43 ← 没有去重
|
||||
def endpoint_url(self) -> str:
|
||||
base = self.base_url.rstrip("/")
|
||||
endpoint = self.vision_endpoint if self.vision_endpoint.startswith("/") else f"/{self.vision_endpoint}"
|
||||
return f"{base}{endpoint}"
|
||||
```
|
||||
`vision_endpoint` 的默认值是 `"/v1/chat/completions"`(`vision_provider.py:35`)。`backend/services/model_provider_runtime.py:210-216` 和 `:297-303` 拼 URL 时同样没有去重。
|
||||
- **影响**:用户在配置里填 `base_url: https://api.example.com/v1`(这是 OpenAI 兼容服务最常见的写法,也是 `_conf_schema.json` 里 provider base_url 的自然填法)时,视觉识别请求会打到 `https://api.example.com/v1/v1/chat/completions` → 404,而生图请求正常。用户很难定位。
|
||||
- **修复建议**:把 `endpoint_url` 提到 `engines/_provider_base.py` 的共享函数 `join_endpoint(base_url, endpoint)`,image / vision / `model_provider_runtime` 三处共用。**削减 ≈10 行 + 修一个配置陷阱**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] DTO 中 15 个 `to_dict()` 是纯字段镜像,可由一个 mixin 替代(削减 ≈220 行)
|
||||
|
||||
- **位置**:`backend/dto/workflow_round_dto.py:29`、`:69`、`:103`;`backend/dto/workflow_dto.py:24`、`:61`、`:109`、`:137`;`backend/dto/profile_dto.py:32`;`backend/dto/material_dto.py:80`、`:108`;`backend/dto/image_dto.py:32`;`backend/dto/job_dto.py:27`;`backend/dto/wardrobe_dto.py:25`;`backend/dto/profile_card_dto.py:19`;`backend/dto/workflow_feedback_dto.py:16`
|
||||
- **问题**:AST 扫描确认这 15 个 `to_dict()` 的 key 列表与 value 表达式**逐项等于 dataclass 字段声明顺序**,没有任何重命名或转换,共 234 行。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/dto/workflow_round_dto.py:9-47 字段声明 17 个,to_dict 原样抄一遍
|
||||
@dataclass(frozen=True)
|
||||
class WorkflowGenerationRound:
|
||||
round_id: str
|
||||
workflow_id: str
|
||||
node_id: str
|
||||
...
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"round_id": self.round_id,
|
||||
"workflow_id": self.workflow_id,
|
||||
"node_id": self.node_id,
|
||||
...
|
||||
}
|
||||
```
|
||||
- **影响**:新增字段必须改两处,漏改会静默导致 API 少字段(这类 bug 没有任何类型检查能拦住)。234 行零信息量代码。
|
||||
- **修复建议**:在 `backend/dto/common.py` 加
|
||||
```python
|
||||
class DictMixin:
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
|
||||
```
|
||||
15 个类改为继承 `DictMixin` 并删除各自的 `to_dict`(另 18 个有转换逻辑的保持手写,可继续覆写)。**预计削减 ≈220 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `main.py` 50 个 `/yp` 短别名命令是纯转发壳(削减 ≈140 行)
|
||||
|
||||
- **位置**:`main.py:1300-1463`(164 行)
|
||||
- **问题**:`imagestudio_short_command` 命令组下的 49 个方法,每一个都只是把参数原样转给同名长命令。
|
||||
- **代码**:
|
||||
```python
|
||||
# main.py:1304-1317
|
||||
@imagestudio_short_command.command("帮助")
|
||||
async def imagestudio_short_help(self, event: AstrMessageEvent):
|
||||
async for result in self.imagestudio_help(event):
|
||||
yield result
|
||||
|
||||
@imagestudio_short_command.command("状态")
|
||||
async def imagestudio_short_status(self, event: AstrMessageEvent, workflow_id: str = ""):
|
||||
async for result in self.imagestudio_status(event, workflow_id):
|
||||
yield result
|
||||
|
||||
@imagestudio_short_command.command("快速角色")
|
||||
async def imagestudio_short_quick_profile(self, event: AstrMessageEvent, description: str = ""):
|
||||
async for result in self.imagestudio_quick_profile(event, description):
|
||||
yield result
|
||||
```
|
||||
代码风格还不统一——前 8 个用两行 `async for` / `yield`,后 41 个压成一行 `async for result in ...: yield result`(`main.py:1345` 起),说明是分批粘贴出来的。
|
||||
- **影响**:164 行样板;新增一条命令必须记得在两个地方注册,漏掉短别名不会报错只会"短命令不存在"。`imagestudio_command` 与 `imagestudio_short_command` 的命令名映射表散落在 100 个装饰器里,无法一眼审计。
|
||||
- **修复建议**:把命令名与处理方法的映射抽成一张表,在类体末尾用循环生成短别名:
|
||||
```python
|
||||
_SHORT_ALIASES = {"帮助": "imagestudio_help", "状态": "imagestudio_status", ...}
|
||||
|
||||
def _bind_short_aliases(cls):
|
||||
for zh_name, target in _SHORT_ALIASES.items():
|
||||
async def _forward(self, event, *args, _target=target, **kwargs):
|
||||
async for result in getattr(self, _target)(event, *args, **kwargs):
|
||||
yield result
|
||||
setattr(cls, f"_short_{target}", cls.imagestudio_short_command.command(zh_name)(_forward))
|
||||
return cls
|
||||
```
|
||||
(若 AstrBot 装饰器要求签名内省,则退化为保留装饰器但由代码生成脚本维护。)**预计削减 ≈140 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `EventBus` 的订阅分发链路全空转——`subscribe`/`unsubscribe` 零调用(过度设计)
|
||||
|
||||
- **位置**:`core/event_bus.py:31-49`
|
||||
- **问题**:`EventBus` 实现了 handler 注册 + 分发,但 `subscribe` / `unsubscribe` 在全仓(含 `tests/`、前端)**零调用**,`self._handlers` 永远是空 defaultdict,`publish` 里的分发循环永远迭代 0 次。唯一消费者 `EventStreamService.recent_events`(`backend/services/event_stream_service.py:22`)只读 `history()`。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/event_bus.py:31-49
|
||||
class EventBus:
|
||||
def __init__(self, *, history_limit: int = 200):
|
||||
self._handlers: DefaultDict[str, list[EventHandler]] = defaultdict(list)
|
||||
self._history: deque[Event] = deque(maxlen=max(int(history_limit), 1))
|
||||
|
||||
def subscribe(self, event_type, handler) -> None: # 零调用
|
||||
...
|
||||
def unsubscribe(self, event_type, handler) -> None: # 零调用
|
||||
...
|
||||
def publish(self, event_type, payload=None) -> Event:
|
||||
event = Event(...)
|
||||
self._history.append(event)
|
||||
for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
|
||||
handler(event) # 永远不执行
|
||||
return event
|
||||
```
|
||||
- **影响**:`EventBus` 实际只是一个有界环形缓冲,却按发布/订阅总线的形态被到处注入(`WorkflowService`、`GenerationService`、`QueueService` 都接受 `event_bus` 参数),误导读者以为存在事件驱动链路——这正是 `branch_routes` 漏配 `event_bus` 一直没被发现的原因。
|
||||
- **修复建议**:删除 `subscribe` / `unsubscribe` 与 `publish` 中的分发循环、`_handlers` 字段、`EventHandler` 类型别名(≈14 行),把类改名为 `EventLog` 或保留名字但在 docstring 明确"仅记录,不分发"。若确实计划做订阅,则应先接一个真实订阅方。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `_json_or_none` / `_json_loads` / `_json_object` 在仓储层重复 20 次(削减 ≈75 行)
|
||||
|
||||
- **位置**:`_json_or_none` 12 处:`advanced_material_repository.py:2072`、`capability_repository.py:150`、`image_repository.py:298`、`integration_repository.py:103`、`job_repository.py:562`、`material_repository.py:313`、`model_provider_repository.py:371`、`profile_repository.py:348`、`wardrobe_repository.py:184`、`workflow_cross_review_repository.py:1442`、`workflow_repository.py:703`、`workflow_round_repository.py:1318`、`core/audit_service.py:113`;`_json_loads` 6 处;`_json_object` 2 处
|
||||
- **问题**:13 份 `_json_or_none` 逐字节相同;`_json_loads`(`capability/image/integration/job/material/model_provider/workflow_repository`)与 `_json_object`(`advanced_material/workflow_round`)是同一功能的两个名字,后者多了 `isinstance(parsed, dict)` 保护,前者没有——JSON 列被写成数组时前者会返回 list,调用方 `dict[str, Any]` 类型标注是假的。
|
||||
- **代码**:
|
||||
```python
|
||||
# 13 份完全相同
|
||||
def _json_or_none(value: Any | None) -> str | None:
|
||||
if value is None:
|
||||
return None
|
||||
return json.dumps(value, ensure_ascii=False, sort_keys=True)
|
||||
|
||||
# capability_repository.py:156 —— 无 dict 保护,类型标注撒谎
|
||||
def _json_loads(value: str | None) -> dict[str, Any]:
|
||||
if not value:
|
||||
return {}
|
||||
return json.loads(value)
|
||||
|
||||
# advanced_material_repository.py:2078 —— 有 dict 保护
|
||||
def _json_object(value: str | None) -> dict[str, Any]:
|
||||
if not value:
|
||||
return {}
|
||||
parsed = json.loads(value)
|
||||
return parsed if isinstance(parsed, dict) else {}
|
||||
```
|
||||
- **影响**:≈100 行冗余;`_json_loads` 的 6 个使用点在遇到非 dict JSON 时会把 list 当 dict 返回,下游 `.get()` 直接 AttributeError。
|
||||
- **修复建议**:`database/repositories/_json.py` 导出 `dump_json`(= `_json_or_none`)与 `load_object`(带 dict 保护的版本),删除全部 20 个本地定义,`_json_loads` 的调用点统一切到有保护的版本。**预计削减 ≈75 行 + 消除一类运行时 AttributeError**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `update` 赋值构建块在 `workflow_repository` 内复制 4 次(削减 ≈85 行)
|
||||
|
||||
- **位置**:`database/repositories/workflow_repository.py:141-176`、`:180-227`、`:280-321`、`:324-379`;同型代码另见 `profile_repository.py:242-283`、`image_repository.py:185`
|
||||
- **问题**:`update_workflow` / `update_workflow_if_status` 用同一份 7 键 `allowed` 集合 + 同一段赋值循环;`update_node` / `update_node_if_status` 用同一份 13 键 `allowed` 集合 + 同一段循环。四段循环体逐字节相同。
|
||||
- **代码**:
|
||||
```python
|
||||
# workflow_repository.py:295-303 与 :348-356 完全相同
|
||||
assignments: list[str] = []
|
||||
params: list[Any] = []
|
||||
placeholder = self.placeholder
|
||||
for key in allowed:
|
||||
if key not in payload:
|
||||
continue
|
||||
column = "metadata_json" if key == "metadata" else key
|
||||
value = _json_or_none(payload[key]) if key == "metadata" else payload[key]
|
||||
assignments.append(f"{column} = {placeholder}")
|
||||
params.append(value)
|
||||
```
|
||||
`allowed` 集合本身也各复制两遍(`:281-294` 与 `:333-346` 的 13 个键完全相同)。
|
||||
- **影响**:给 node 加一个可更新字段要改 2 个 `allowed` 集合,漏改会导致"普通更新生效、CAS 更新静默丢字段",且无任何测试能覆盖到这种不对称。
|
||||
- **修复建议**:模块级常量 `WORKFLOW_UPDATABLE = frozenset({...})` / `NODE_UPDATABLE = frozenset({...})`,加共享函数
|
||||
```python
|
||||
def _assignments(payload, allowed, placeholder, json_keys=frozenset({"metadata"})) -> tuple[list[str], list[Any]]:
|
||||
```
|
||||
(`advanced_material_repository.py:2042` 已有更通用的 `_update_assignments(payload, placeholder, columns)`,直接把它提升到 `database/repositories/_sql.py` 并让 workflow/profile/image/job 四个仓储共用即可。`job_repository.py:568` 是它的第二个分叉实现。)**预计削减 ≈85 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `_signed_url` 复制 7 份,其中 3 份的异常捕获范围不一致(削减 ≈41 行)
|
||||
|
||||
- **位置**:`backend/routes/advanced_material_routes.py:428`、`backend/routes/image_routes.py:226`、`backend/routes/material_routes.py:317`、`backend/routes/profile_card_routes.py:90`、`backend/routes/round_routes.py:192`、`backend/services/workflow_round_worker_runtime.py:257`、`backend/services/dashboard_service.py:89`
|
||||
- **问题**:同一个"签名失败就返回 None"的包装函数复制了 7 份,签名和异常范围各不相同。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/image_routes.py:226-232 —— 只吞 ApiError
|
||||
def _signed_url(media_service: MediaService, uri: str | None) -> str | None:
|
||||
if not uri:
|
||||
return None
|
||||
try:
|
||||
return media_service.sign_media(uri)["url"]
|
||||
except ApiError:
|
||||
return None
|
||||
|
||||
# backend/routes/advanced_material_routes.py:428-435 —— 吞所有异常,且每次调用新建 MediaService()
|
||||
def _signed_url(uri: Any) -> str | None:
|
||||
text = str(uri or "").strip()
|
||||
if not text:
|
||||
return None
|
||||
try:
|
||||
return MediaService().sign_media(text)["url"]
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
# backend/services/workflow_round_worker_runtime.py:257-263 —— 吞所有异常 + .get("url")
|
||||
```
|
||||
- **影响**:49 行冗余;`advanced_material_routes` 版本在列表序列化时每张图新建一次 `MediaService()`(内部会 `ConfigService()` 读盘),列表页 N 张图 = N 次配置加载。
|
||||
- **修复建议**:在 `MediaService` 上加实例方法 `def signed_url(self, uri: Any) -> str | None:`,7 处全部改为 `media_service.signed_url(uri)`。**预计削减 ≈41 行 + 消除 advanced_material 列表页的 N 次配置读盘**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 分页/限流工具函数 `_page` / `_page_size` / `_limit` 重复 10 次且默认值不一致(削减 ≈48 行)
|
||||
|
||||
- **位置**:`_page`/`_page_size`:`job_repository.py:609/617`、`material_repository.py:319/327`、`profile_repository.py:354/362`、`advanced_material_repository.py:2111/2115`;`_limit`:`integration_repository.py:109`、`job_repository.py:601`、`backend/services/log_service.py:293`、`backend/services/event_stream_service.py:35`、`backend/services/settings_service.py:659`
|
||||
- **问题**:三份 `_page` 逐字节相同(try/except → max(page,1)),第四份 `advanced_material_repository.py:2111` 写成 `max(int(value or 1), 1)`——传入非数字字符串时前三份返回 1、第四份抛 `ValueError`。`_limit` 的默认值/上限在 5 处各不相同(50/200、50/200、…)。
|
||||
- **代码**:
|
||||
```python
|
||||
# job_repository.py:609 / material_repository.py:319 / profile_repository.py:354 —— 三份相同
|
||||
def _page(value: Any) -> int:
|
||||
try:
|
||||
page = int(value)
|
||||
except (TypeError, ValueError):
|
||||
page = 1
|
||||
return max(page, 1)
|
||||
|
||||
# advanced_material_repository.py:2111 —— 不吞异常
|
||||
def _page(value: int) -> int:
|
||||
return max(int(value or 1), 1)
|
||||
```
|
||||
- **影响**:60 行冗余;高级素材列表接口对畸形 `page` 参数会 500,而其他列表接口降级为第 1 页——同一套 API 的错误语义不一致。
|
||||
- **修复建议**:`core/coerce.py` 提供 `page(value)` / `page_size(value, *, default, maximum)` / `clamp_limit(value, *, default, maximum)`,10 处替换。**预计削减 ≈48 行 + 统一 API 参数容错语义**。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 确证死代码:29 个函数/类/方法全仓零引用(削减 ≈263 行)
|
||||
|
||||
- **位置与规模**(均已用 `grep -rn` 在 `main.py + backend + core + database + engines + adapters + tests + frontend/src` 全范围交叉验证,引用数为 1,即只有定义处):
|
||||
|
||||
| 文件:行 | 符号 | 行数 |
|
||||
|---|---|---|
|
||||
| `database/repositories/workflow_round_repository.py:488` | `update_pool_preferences` | 60 |
|
||||
| `backend/dto/material_dto.py:10` | `RawAnalysis` | 19 |
|
||||
| `backend/dto/material_dto.py:32` | `NormalizedAssetProfile` | 19 |
|
||||
| `backend/services/worker_service.py:148` | `QueueWorker.run_batch` | 15 |
|
||||
| `core/interactions.py:49` | `normalize_action` | 14 |
|
||||
| `backend/dto/material_dto.py:54` | `GenerationCapsule` | 13 |
|
||||
| `core/interop.py:14` | `PluginRequest` | 13 |
|
||||
| `core/interop.py:29` | `normalize_plugin_request` | 13 |
|
||||
| `core/interop.py:49` | `daily_outfit_request` | 12 |
|
||||
| `backend/dto/chat_command_dto.py:21` | `SingleImageCommand.to_payload` | 10 |
|
||||
| `database/repositories/profile_card_repository.py:266` | `next_version` | 10 |
|
||||
| `database/repositories/advanced_material_repository.py:357` | `get_import_by_idempotency_key` | 10 |
|
||||
| `backend/services/queue_service.py:539` | `requeue_dead_letters` | 10 |
|
||||
| `core/secret_service.py:57` | `env_ref` | 5 |
|
||||
| `core/runtime_paths.py:28` | `get_runtime_data_root` | 4 |
|
||||
| `core/event_bus.py:36/41` | `subscribe` / `unsubscribe` | 7 |
|
||||
| `core/webhook.py:33/40` | `sign_event` / `verify_signature` | 6 |
|
||||
| `backend/services/web_hosting_service.py:42/50/54` | 三个 asset 解析方法 | 9 |
|
||||
| `core/interop.py:44` | `is_allowed_plugin` | 3 |
|
||||
| `core/audit_service.py:109` | `create_audit_service` | 2 |
|
||||
| `backend/services/media_service.py:33` | `fetch_media_metadata` | 2 |
|
||||
| `backend/services/queue_service.py:277` | `is_cancelled` | 2 |
|
||||
| `database/models.py:21/24` | `column_names` / `sensitive_columns` | 4 |
|
||||
| `engines/image_provider.py:92` | `ImageGenerationResult.has_images` | 2 |
|
||||
| `core/secret_service.py:34` | `SecretResolution.to_public_dict` | 2 |
|
||||
| `backend/services/settings_service.py:884` | `_dump_yaml = dump_yaml` 兼容别名 | 3 |
|
||||
| `backend/routes/params.py:22` | `optional_text = optional_str` 别名 | 3 |
|
||||
| `backend/services/advanced_material_service.py:71` | `IMPORT_REVIEW_STATUSES` | 1 |
|
||||
| `core/image_formats.py:22` | `SUPPORTED_IMAGE_MIME_TYPES` | 1 |
|
||||
|
||||
- **代码**(几个值得单独说明的):
|
||||
```python
|
||||
# backend/services/settings_service.py:882-884 —— 注释说"为已有测试保留",但 grep 显示没有任何测试引用
|
||||
# Compatibility alias for existing tests and services that imported the
|
||||
# previous private serializer. New code should import core.config_writer.
|
||||
_dump_yaml = dump_yaml
|
||||
```
|
||||
```python
|
||||
# core/interop.py —— 整个模块只有 PRIVATE_COMPANION 常量被 integration_token_service.py:16 引用,
|
||||
# 其余 PluginRequest / normalize_plugin_request / is_allowed_plugin / daily_outfit_request / ALLOWED_PLUGINS
|
||||
# 组成一条完全无人调用的调用链(daily_outfit_request 是唯一入口,而它自己零引用)
|
||||
```
|
||||
```python
|
||||
# backend/services/queue_service.py:539 —— 死信重入队能力已实现但无路由、无 CLI、无测试触发
|
||||
def requeue_dead_letters(self, ctx, *, limit: int = 50) -> dict[str, Any]:
|
||||
```
|
||||
- **影响**:263 行需要被 review、被 grep 命中、被误认为"有人在用"的代码。`requeue_dead_letters` 和 `update_pool_preferences` 尤其危险——它们看起来是产品功能(死信恢复、候选池偏好),实际从未接线,容易让人误以为功能已交付。
|
||||
- **修复建议**:全部删除(`core/interop.py` 保留 `PRIVATE_COMPANION` 常量,其余删掉;或把常量挪到 `integration_token_service.py` 后整文件删除,可再减 ≈45 行)。若 `requeue_dead_letters` / `update_pool_preferences` 是计划中的功能,应转成 issue 并删代码,不要留半成品。**预计削减 ≈263 行(含 interop 整清理约 300 行)**。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `EventStreamService._event_to_webhook` 造两次对象再丢弃一次(过度设计)
|
||||
|
||||
- **位置**:`backend/services/event_stream_service.py:42-49`,配合 `core/webhook.py:48-49`
|
||||
- **问题**:`event_from_bus()` 造一个带随机 `event_id` 和当前时间的 `WebhookEvent`,紧接着 `_event_to_webhook` 把这两个字段全部丢掉、用 bus event 的值重建一个新对象。中间对象完全是浪费。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/services/event_stream_service.py:42-49
|
||||
def _event_to_webhook(event: Event) -> WebhookEvent:
|
||||
webhook_event = event_from_bus(event.event_type, event.payload) # 造一个
|
||||
return WebhookEvent( # 立刻丢掉重造
|
||||
event_type=webhook_event.event_type,
|
||||
data=webhook_event.data,
|
||||
event_id=event.event_id,
|
||||
created_at=event.created_at,
|
||||
)
|
||||
|
||||
# core/webhook.py:48-49
|
||||
def event_from_bus(event_type: str, payload: dict[str, Any]) -> WebhookEvent:
|
||||
return WebhookEvent(event_type=event_type, data=dict(payload))
|
||||
```
|
||||
- **影响**:每条 SSE 事件多一次 `uuid4()` + `datetime.now()`(`WebhookEvent` 的 `default_factory`)。`recent_events` 默认 limit 50、上限 200,即每次拉取浪费 50~200 次 UUID 生成。可读性上更糟:读者会以为 `event_from_bus` 有转换逻辑。
|
||||
- **修复建议**:
|
||||
```python
|
||||
def _event_to_webhook(event: Event) -> WebhookEvent:
|
||||
return WebhookEvent(
|
||||
event_type=event.event_type,
|
||||
data=dict(event.payload),
|
||||
event_id=event.event_id,
|
||||
created_at=event.created_at,
|
||||
)
|
||||
```
|
||||
`core/webhook.py:48-49` 的 `event_from_bus` 随之成为死代码(唯一调用点消失),一并删除。**削减 ≈6 行**。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `ImageProviderError` 与 `VisionProviderError` 逐字节相同;`_post_json` 的 urllib 分支重复 40 行
|
||||
|
||||
- **位置**:`engines/image_provider.py:96-110` vs `engines/vision_provider.py:72-86`;`engines/image_provider.py:272-303` vs `engines/vision_provider.py:295-337`
|
||||
- **问题**:两个异常类的 `__init__` 与全部字段完全一致,只有类名不同;`_post_json` 的 urllib 回退分支(HTTPError / URLError / RemoteFetchError 三个 except 块)也只差异常类和错误文案里的 `image`/`vision` 前缀。
|
||||
- **代码**:
|
||||
```python
|
||||
# engines/image_provider.py:96-110 / engines/vision_provider.py:72-86 —— 除类名外完全相同
|
||||
class ImageProviderError(RuntimeError):
|
||||
def __init__(self, message: str, *, provider_id: str, status_code: int | None = None,
|
||||
error_type: str = "provider_error", details: dict[str, Any] | None = None):
|
||||
super().__init__(message)
|
||||
self.provider_id = provider_id
|
||||
self.status_code = status_code
|
||||
self.error_type = error_type
|
||||
self.details = details or {}
|
||||
```
|
||||
- **影响**:≈55 行冗余。真正的代价是分叉:image 版 `_post_json` 已经加了 httpx 流式读取 + 长度上限(`image_provider.py:231-271`),vision 版还停留在纯 urllib,所以视觉调用没有 httpx 的超时/重定向控制,也没有 `_provider_json_limit` 动态上限。
|
||||
- **修复建议**:新建 `engines/_provider_http.py`,提供
|
||||
```python
|
||||
class ProviderError(RuntimeError): ... # 两个子类只留 `pass` + 文案前缀
|
||||
def post_json(url, payload, headers, timeout_seconds, *, error_cls, label, max_bytes) -> JsonDict: ...
|
||||
```
|
||||
两个 provider 各传 `error_cls=ImageProviderError, label="image"`。**削减 ≈55 行 + 让 vision 自动获得 httpx 路径**。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `core/config_service.py` 的存储默认值在同文件写了两遍
|
||||
|
||||
- **位置**:`core/config_service.py:24-31`(dataclass 默认值)与 `:74-83`(`load()` 里的 `.get(key, 默认值)`)
|
||||
- **问题**:7 条存储路径的默认值在同一个文件里硬编码两次。
|
||||
- **代码**:
|
||||
```python
|
||||
# core/config_service.py:24-31
|
||||
@dataclass(frozen=True)
|
||||
class StorageConfig:
|
||||
images_path: str = "data/images"
|
||||
thumbnails_path: str = "data/thumbnails"
|
||||
...
|
||||
# core/config_service.py:74-83 —— 同样的字面量再写一遍
|
||||
storage=StorageConfig(
|
||||
images_path=str(storage.get("images_path", "data/images")),
|
||||
thumbnails_path=str(storage.get("thumbnails_path", "data/thumbnails")),
|
||||
...
|
||||
)
|
||||
```
|
||||
- **影响**:改默认路径必须改两处,漏改后"未配置时"和"配置为空字符串时"会落到不同目录。
|
||||
- **修复建议**:
|
||||
```python
|
||||
_STORAGE_FIELDS = {f.name for f in dataclasses.fields(StorageConfig)}
|
||||
storage=StorageConfig(**{k: str(v) for k, v in storage.items() if k in _STORAGE_FIELDS and v})
|
||||
```
|
||||
**削减 ≈12 行**。同类问题:`PLUGIN_VERSION = "1.0.72"` 在 `core/config_service.py:13`、`config.yaml:4`、`metadata.yaml:5` 三处硬编码,而 `config_service.load()` 的注释(`:68-70`)明确说会**忽略** `config.yaml` 里的值——`config.yaml` 的 `plugin.version` 是纯误导,应删除。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `_optional_text` 之外的其他小工具重复:`_now` ×6、`_mapping` ×4、`_rollback` ×3
|
||||
|
||||
- **位置**:`_now`:`backend/services/advanced_style_set_service.py:4279`、`generation_job_retry_service.py:493`、`queue_service.py:709`、`worker_service.py:476`、`core/queue_manager.py:14`(另 `integration_token_service.py:178` 返回 `datetime` 非 `str`);`_mapping`:`backend/services/history_service.py:313`、`model_provider_bootstrap.py:353`、`workflow_round_service.py:1196`、`database/repositories/workflow_cross_review_repository.py:1429`;`_rollback`:见上文
|
||||
- **问题**:`_now()` 的 5 份 `return datetime.now(timezone.utc).isoformat()` 完全相同。`_mapping()` 已经被抽出 4 次却没有共享,而它对应的内联写法 `x.get("y") if isinstance(x.get("y"), dict) else {}` 在后端出现 **291 次**(`advanced_style_set_service.py` 47 次、`generation_service.py` 37 次、`advanced_material_service.py` 24 次)。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/node_routes.py:329-335 —— 一个函数里连着 5 行同款
|
||||
generation_config = config_payload.get("generation") if isinstance(config_payload.get("generation"), dict) else {}
|
||||
model_assignments = config_payload.get("model_assignments") if isinstance(config_payload.get("model_assignments"), dict) else {}
|
||||
governance_config = config_payload.get("prompt_governance") if isinstance(config_payload.get("prompt_governance"), dict) else {}
|
||||
translation_config = governance_config.get("translation") if isinstance(governance_config.get("translation"), dict) else {}
|
||||
moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {}
|
||||
```
|
||||
- **影响**:`_now` ≈15 行冗余;291 处内联写法虽然不减行数,但每处都把 key 名写两遍,是"改 key 名漏改一半"的高发点(写成 `config.get("a") if isinstance(config.get("b"), dict) else {}` 不会有任何工具报错)。
|
||||
- **修复建议**:`core/coerce.py` 提供 `utc_now_iso()` 与 `mapping(value)`;291 处内联改为 `mapping(config_payload.get("generation"))`,key 名只出现一次。**削减 ≈30 行 + 消除一类 key 名不一致隐患**。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 两个源文件带 UTF-8 BOM,导致标准 AST 工具解析失败
|
||||
|
||||
- **位置**:`backend/routes/job_routes.py:1`、`backend/services/profile_document_import_service.py:1`
|
||||
- **问题**:文件以 `\xef\xbb\xbf` 开头。`ast.parse(path.read_text(encoding="utf-8"))` 直接抛 `SyntaxError: invalid non-printable character U+FEFF`。
|
||||
- **代码**:
|
||||
```
|
||||
$ python -c "import pathlib; print(pathlib.Path('backend/routes/job_routes.py').read_bytes()[:6])"
|
||||
b'\xef\xbb\xbf"""'
|
||||
```
|
||||
- **影响**:Python 解释器自身能处理(`tokenize` 会跳过 BOM),但任何自建的 AST 分析、代码生成、lint 插件、批量重构脚本都会在这两个文件上失败。本次审计的死代码扫描就漏掉了这两个文件。
|
||||
- **修复建议**:`python -c "p=...; p.write_bytes(p.read_bytes()[3:])"` 去掉 BOM,并在 `.gitattributes` / pre-commit 加检查。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 148 个路由处理器的 `def action()` 闭包样板(可选,高风险)
|
||||
|
||||
- **位置**:`backend/routes/*.py` 共 148 处 `def action()` + 157 处 `return handle_request(ctx, action)` + 147 处 `service or _create_xxx()`
|
||||
- **问题**:每个路由处理器固定四段式:`xxx_service = service or _create_xxx()` → `def action():` → `require_xxx(ctx)` → `return handle_request(ctx, action)`。
|
||||
- **代码**:
|
||||
```python
|
||||
# backend/routes/wardrobe_routes.py:57-70 —— 与另外 147 个处理器同构
|
||||
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, service=None) -> dict:
|
||||
wardrobe_service = service or _create_wardrobe_service()
|
||||
|
||||
def action() -> dict[str, Any]:
|
||||
require_permission(ctx, "can_manage_materials")
|
||||
return wardrobe_service.delete_item(profile_id, wardrobe_item_id, ctx)
|
||||
|
||||
return handle_request(ctx, action)
|
||||
```
|
||||
同文件 `:86-107` 已经出现了绕过闭包的"元组下标"写法,说明作者本人也觉得样板烦:
|
||||
```python
|
||||
return handle_request(ctx, lambda: (require_permission(ctx, "can_manage_materials"),
|
||||
wardrobe_service.save_template(profile_id, payload, ctx))[1])
|
||||
```
|
||||
- **影响**:≈450 行样板;权限声明散落在闭包第一行,无法从 `route_registry.ROUTES` 静态核对(`RouteSpec.permission` 与 `require_xxx(ctx)` 是两份独立真相,`branch_routes` 的 event_bus 缺失就是这种双真相结构的产物)。
|
||||
- **修复建议**(改动面大,建议单独立项):引入装饰器让权限声明与 `RouteSpec` 单一化:
|
||||
```python
|
||||
@route_handler(permission="materials", service_factory=_create_wardrobe_service)
|
||||
def delete_wardrobe_item(ctx, profile_id, wardrobe_item_id, *, service) -> dict[str, Any]:
|
||||
return service.delete_item(profile_id, wardrobe_item_id, ctx)
|
||||
```
|
||||
并在启动时断言装饰器声明的 permission 与 `route_registry.ROUTES` 一致。**预计削减 ≈300 行 + 权限矩阵可静态校验**。风险:148 个处理器的测试注入点(`service=` 参数)需同步调整,建议分模块灰度。
|
||||
|
||||
---
|
||||
|
||||
## 削减总计
|
||||
|
||||
| # | 项目 | 位置规模 | 预计削减 | 风险 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 仓储连接样板 → `BaseRepository._connect()` | 131 处 | **≈390** | 中 |
|
||||
| 2 | DTO `to_dict` 纯镜像 → `DictMixin` | 15 个类 | **≈220** | 低 |
|
||||
| 3 | 死代码清理(29 符号 + `queue_manager.py` + `interop` 残链) | 30+ 处 | **≈375** | 低 |
|
||||
| 4 | `_optional_text` ×30 → `core/coerce` | 30 处 | **≈145** | 低 |
|
||||
| 5 | `main.py` 短别名 ×50 → 映射表 | 164 行 | **≈140** | 中 |
|
||||
| 6 | `_string_list` ×18 → 三个语义化函数 | 18 处 | **≈90** | 中 |
|
||||
| 7 | `update` 赋值构建块 ×6 → `_update_assignments` | 6 处 | **≈85** | 低 |
|
||||
| 8 | `_json_or_none` / `_json_loads` / `_json_object` ×20 | 20 处 | **≈75** | 低 |
|
||||
| 9 | `engines` `ProviderError` + `_post_json` 提取 | 2 文件 | **≈55** | 低 |
|
||||
| 10 | `_page` / `_page_size` / `_limit` ×10 | 10 处 | **≈48** | 低 |
|
||||
| 11 | `_signed_url` ×7 → `MediaService.signed_url` | 7 处 | **≈41** | 低 |
|
||||
| 12 | `_now` ×6 + `_mapping` ×4 + 291 处内联 dict 守卫 | 300+ 处 | **≈30** | 低 |
|
||||
| 13 | `_create_*_service` 工厂集中(顺带修 `branch_routes` 缺陷) | 22 处 | **≈20** | 中 |
|
||||
| 14 | `EventBus` 空转分发链路 | 1 处 | **≈14** | 低 |
|
||||
| 15 | `config_service` 默认值重复 + `config.yaml` 死版本号 | 2 处 | **≈12** | 低 |
|
||||
| 16 | `_event_to_webhook` 双次造对象 + `event_from_bus` | 2 处 | **≈6** | 低 |
|
||||
| | **小计(不含路由层改造)** | | **≈1,746 行** | |
|
||||
| 17 | 路由 `action` 闭包 → `@route_handler` 装饰器(建议单独立项) | 148 处 | **≈300** | 高 |
|
||||
| | **合计** | | **≈2,046 行 / 后端 54,551 行 ≈ 3.8%** | |
|
||||
|
||||
**推荐执行顺序**(投入产出比降序):
|
||||
1. **第一批(零风险,纯删)**:#3 死代码、#14 EventBus、#16 event_from_bus、#15 config 默认值 → 约 400 行,无行为变更。
|
||||
2. **第二批(低风险,机械替换)**:#2 DictMixin、#4/#8/#10/#11/#12 工具函数统一 → 约 560 行,配合现有 `tests/` 回归即可。
|
||||
3. **第三批(需谨慎,有行为差异要对齐)**:#6 `_string_list` 语义拆分、#13 工厂集中(修 branch_routes 事件缺陷)、#9 provider 提取(修 vision `/v1` 拼接缺陷) → 约 165 行,但同时消灭 3 个真实缺陷,价值最高。
|
||||
4. **第四批(大改动)**:#1 BaseRepository、#5 main.py 别名、#7 update 块 → 约 615 行。
|
||||
5. **单独立项**:#17 路由装饰器。
|
||||
613
审计/findings/C2-前端精简空间.md
普通文件
613
审计/findings/C2-前端精简空间.md
普通文件
|
|
@ -0,0 +1,613 @@
|
|||
# C2 — 前端代码精简空间
|
||||
|
||||
> 审计范围(实际 Read 过的文件):
|
||||
> - `frontend/package.json`、`frontend/tsconfig.json`、`frontend/env.d.ts`
|
||||
> - `frontend/plugin-page/vite.config.ts`、`frontend/plugin-page/src/App.vue`、`frontend/plugin-page/src/main.ts`
|
||||
> - `frontend/standalone-web/vite.config.ts`、`frontend/standalone-web/src/main.ts`
|
||||
> - `frontend/standalone-web/src/App.vue`(22563 行,逐段抽样通读 + 全量脚本分析)
|
||||
> - `frontend/standalone-web/src/styles/workbench.css`、`styles/tokens.css`
|
||||
> - `frontend/standalone-web/src/components/{ConfirmDialog,ImagePreviewDialog,MaterialCategoryCreateDialog,MaterialDetailDialog,EmptyState,StateCard,MetricCardGrid}.vue`
|
||||
> - `frontend/standalone-web/src/features/workflow/{WorkflowCompareDialog,WorkflowGenerationReviewDialog,WorkflowBranchPanel,WorkflowRoundPanel}.vue`
|
||||
> - `frontend/standalone-web/src/features/profiles/{ProfileDetailPane,ProfileMasterPane,ProfileWardrobePane,ProfilesPage}.vue`
|
||||
> - `frontend/standalone-web/src/features/gallery/GalleryPage.vue`
|
||||
> - `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue`
|
||||
> - `frontend/standalone-web/src/features/settings/{SettingsPage,BackupPage}.vue`
|
||||
> - `frontend/shared/utils/{presentation,collections,storage-uri}.ts`、`frontend/shared/types/{workflow,workflow-material,integration}.ts`
|
||||
>
|
||||
> 全量静态分析脚本(自写,跑在真实源码树上):CSS 类引用可达性、CSS 声明块重复度、导出符号可达性、组件样式归属泄漏。
|
||||
|
||||
## 摘要
|
||||
|
||||
前端源码 40182 行,其中 **CSS 占 14698 行(36.6%)**,`standalone-web/src/App.vue` 一个文件就占 22563 行(56%),其样式块 8396 行、模板块 2785 行、脚本块 11357 行,是典型的 god component。
|
||||
|
||||
**可确证的"净删除"空间约 1900–2000 行(≈ 全部前端源码的 5%,CSS 的 13%)**,主要来自:App.vue 内 413 行永远不会命中的死 CSS 规则、`SettingsPage.vue` 里一整段重构后遗留的 `.backup-*` 死样式、素材选择器弹层模板被逐字复制两份(109 行)、4 份几乎一字不差的焦点陷阱实现(130 行)、图片查看器缩放/拖拽逻辑与 `ImagePreviewDialog.vue` 完全重复(脚本 60 行 + 样式 104 行)、以及 2251 行上限的重复 CSS 声明块。
|
||||
|
||||
**"迁移拆分"空间约 6000 行**(不减总量但把 App.vue 压到 6000–7000 行):`quick-profile` 前缀样式 1268 行、`workflow-*` 约 1400 行、`materials-*` 约 600 行可直接切成 feature CSS 文件;`workflowActionCards`(441 行)/`generateFeatureCards`(171)/`queueActionCards`(143)/`materialActionCards`(113)/`quickProfileActionCards`(88) 五个卡片工厂 + 4 张标签映射表共约 1080 行是纯数据,应搬到独立模块。
|
||||
|
||||
**pinia 与 vue-router 声明了但整个代码库零引用**(`grep -rn "pinia\|vue-router"` 在 src 下 0 命中),App.vue 用 206 个 `ref` + 135 个 `computed` 的巨型局部状态树代替 store。**`devDependencies` 为空**,`typescript`/`vite`/`vue-tsc`/`@vitejs/plugin-vue` 全部错放在 `dependencies`。
|
||||
|
||||
**好消息**:`plugin-page` 与 `standalone-web` 两套构建之间**没有代码重复**——`plugin-page/src/App.vue` 只有 7 行、直接 re-export `standalone-web/src/App.vue`,两份 `vite.config.ts` 各 16 行仅 `base`/`outDir` 不同。这一项无精简空间。
|
||||
|
||||
---
|
||||
|
||||
## 发现
|
||||
|
||||
### [P2-中等] App.vue 样式块内 413 行 CSS 规则永远不会命中(死代码)
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:17323`、`:17764-17845`、`:19007-19059`、`:20075-20101`、`:21129-21286`、`:21484-21499`、`:21662-21703`(共 41 条规则);另 `:17213-17316`、`:21491-21499` 等
|
||||
- **问题**:全量扫描 903 个 CSS 类,其中 63 个在任何 `.vue` 模板/脚本(含 Vue `<Transition name>` 派生类、动态 `:class` 绑定)中都无法被引用到。逐条核实后,App.vue 内**由纯死类构成的完整规则块合计 277 行**;另有 136 行是子组件已有 `scoped` 副本的重复定义。
|
||||
- **代码**(真实片段,App.vue:21129-21145):
|
||||
```css
|
||||
.generate-status-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.generate-status-grid article,
|
||||
.generate-feature-card {
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
display: grid;
|
||||
gap: 6px;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 12px;
|
||||
padding: 14px;
|
||||
background: var(--panel);
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
```
|
||||
`generate-status-grid` / `generate-feature-card` / `generate-section` / `generate-card-grid` / `generate-card-top` / `feature-state` 这一整组类在整个前端模板中零出现(`generateFeatureCards` computed 仍在,但渲染它的模板早已改用 `quick-profile-command-card`)。
|
||||
|
||||
同样死掉的还有 App.vue:17764-17787:
|
||||
```css
|
||||
.workflow-node-card {
|
||||
position: relative;
|
||||
display: grid;
|
||||
grid-template-columns: 26px minmax(0, 1fr);
|
||||
align-items: start;
|
||||
gap: 10px;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 10px;
|
||||
padding: 11px;
|
||||
background: var(--panel-muted);
|
||||
}
|
||||
|
||||
.workflow-node-card::after {
|
||||
position: absolute;
|
||||
left: 24px;
|
||||
top: 100%;
|
||||
width: 1px;
|
||||
height: 8px;
|
||||
background: var(--border);
|
||||
content: "";
|
||||
}
|
||||
```
|
||||
模板里节点卡实际用的是 `workflow-node-item`,`workflow-node-card` 从未出现。
|
||||
|
||||
- **影响**:约 413 行 CSS 每次构建都被打进 `web/assets/index-*.css` 与 `pages/imagestudio/assets/index-*.css` 两份产物;改样式时会误导人以为在改生效的规则(`.workflow-node-card` 这种名字极具迷惑性)。
|
||||
- **修复建议**:
|
||||
1. 把我这次的可达性扫描固化成一个 `frontend/tests/dead-css.test.mjs`(项目已有 `node --test tests/*.test.mjs` 的契约测试习惯),断言"App.vue 样式块内的类必须能在某个模板中被引用",白名单里放 `Transition` 派生类与动态拼接类。
|
||||
2. 直接删除上述行区间。删除时注意保留 `.image-viewer-backdrop`(App.vue 模板里 4 个内联弹层仍在用),只删 `.image-viewer-card/-actions/-stage`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `.image-viewer-*` 的 104 行样式与 60 行缩放/拖拽逻辑在 App.vue 和 ImagePreviewDialog.vue 中各存在一份
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:17213-17316`(CSS)与 `frontend/standalone-web/src/components/ImagePreviewDialog.vue:221-324`(CSS,`scoped`);`App.vue:7952-8011`(脚本)与 `ImagePreviewDialog.vue:58-114`(脚本)
|
||||
- **问题**:两处 CSS **逐字节相同**(`diff` 除去尾部一条无关规则后无差异)。App.vue 侧那 104 行的使用者只有 `ImagePreviewDialog.vue` 的模板,而该组件自带 `scoped` 副本,所以 App.vue 的这份是纯冗余。脚本侧同理:同一套 MIN/MAX 缩放、指针捕获拖拽逻辑写了两遍,只是变量名从 `scale/offset/dragging` 改成 `imageViewerScale/imageViewerOffset/imageViewerDragging`。
|
||||
- **代码**(App.vue:7982-8011):
|
||||
```ts
|
||||
function startImageViewerDrag(event: PointerEvent) {
|
||||
if (imageViewerScale.value <= 1) return
|
||||
imageViewerDragging.value = true
|
||||
imageViewerDragStart.value = {
|
||||
pointerId: event.pointerId,
|
||||
x: event.clientX,
|
||||
y: event.clientY,
|
||||
offsetX: imageViewerOffset.value.x,
|
||||
offsetY: imageViewerOffset.value.y,
|
||||
}
|
||||
if (event.currentTarget instanceof HTMLElement) {
|
||||
event.currentTarget.setPointerCapture(event.pointerId)
|
||||
}
|
||||
}
|
||||
```
|
||||
对照 `ImagePreviewDialog.vue:85-98`:
|
||||
```ts
|
||||
function startDrag(event: PointerEvent) {
|
||||
if (scale.value <= 1) return
|
||||
dragging.value = true
|
||||
dragStart.value = {
|
||||
pointerId: event.pointerId,
|
||||
x: event.clientX,
|
||||
y: event.clientY,
|
||||
offsetX: offset.value.x,
|
||||
offsetY: offset.value.y,
|
||||
}
|
||||
if (event.currentTarget instanceof HTMLElement) {
|
||||
event.currentTarget.setPointerCapture(event.pointerId)
|
||||
}
|
||||
}
|
||||
```
|
||||
两处的魔数也各写一遍:`0.5/4/0.12/2.2` vs `MIN_SCALE/MAX_SCALE/WHEEL_STEP/DOUBLE_CLICK_SCALE`。
|
||||
- **影响**:约 164 行冗余;更糟的是缩放行为会漂移——改 `ImagePreviewDialog` 的手感不会同步到 quick-profile 查看器。
|
||||
- **修复建议**:抽 `standalone-web/src/composables/useImageZoomPan.ts`:
|
||||
```ts
|
||||
export function useImageZoomPan(opts?: { min?: number; max?: number }) {
|
||||
const scale = ref(1), offset = ref({ x: 0, y: 0 }), dragging = ref(false)
|
||||
// reset / zoom / zoomFromWheel / toggleZoom / startDrag / drag / endDrag
|
||||
return { scale, offset, dragging, transform, ...handlers }
|
||||
}
|
||||
```
|
||||
`ImagePreviewDialog.vue` 与 App.vue 的 quick-profile 查看器都用它;删掉 App.vue:17213-17316 的 CSS,让 quick-profile 查看器直接复用 `<ImagePreviewDialog>`(模板 `App.vue:12218-12266` 的 49 行也一并消失)。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 素材选择器弹层模板被逐字复制两份(109 行)
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:12009-12117`(quickProfile 模式)与 `App.vue:12658-12769`(workflow 模式)
|
||||
- **问题**:把两段去掉缩进后 `diff`,97 行中只有 5 行不同:`material.category` → `binding.category`(3 处)、一句文案 `取消这个素材参考` → `默认不注入这个参考`、多一条 `<small v-if="reference.advanced">`。其余包括分组 tab、`TransitionGroup`、"不使用"选项、缩略图渲染全部一致。
|
||||
- **代码**(App.vue:12021-12042 与 12672-12693 完全同构):
|
||||
```html
|
||||
<header class="quick-profile-material-picker-header">
|
||||
<div>
|
||||
<span>{{ material.category }}参考</span>
|
||||
<strong>选择素材</strong>
|
||||
</div>
|
||||
<small>{{ activeQuickProfileMaterialPickerCountLabel }}</small>
|
||||
</header>
|
||||
<div
|
||||
v-if="material.category === QUICK_PROFILE_ACCESSORY_CATEGORY"
|
||||
class="quick-profile-material-picker-groups"
|
||||
aria-label="配饰分类"
|
||||
>
|
||||
<button
|
||||
v-for="group in quickProfileAccessoryGroups"
|
||||
:key="group"
|
||||
type="button"
|
||||
:class="{ active: activeQuickProfileMaterialAccessoryGroup === group }"
|
||||
@click="setQuickProfileAccessoryGroup(group)"
|
||||
>
|
||||
{{ group }}
|
||||
</button>
|
||||
</div>
|
||||
```
|
||||
- **影响**:约 109 行模板重复;两侧已经开始漂移(`reference.advanced` 的"进阶素材 · 高优先级"标记只有 workflow 侧有,quickProfile 侧看不到),这是双份维护必然的结果。
|
||||
- **修复建议**:抽 `standalone-web/src/features/materials/MaterialPickerPopover.vue`,props 为 `{ category: string; placement?: 'up'|'down'; extraClass?: string }`,事件 `select` / `clear`。两处调用点各缩到 8 行左右,净省约 100 行,同时消除功能漂移。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 4 份几乎一字不差的焦点陷阱(focus trap)实现
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/components/ConfirmDialog.vue:30,42-83`、`components/ImagePreviewDialog.vue:27,116-151`、`features/workflow/WorkflowCompareDialog.vue:20,34-78`、`features/workflow/WorkflowGenerationReviewDialog.vue:53,149-205`
|
||||
- **问题**:每个弹窗组件都自己写了 `previousFocus` / `focusableElements()` / `trapFocus()`(或 `handleKeydown`) / `restoreFocus()` / `watch(() => props.open, ...)` 这一套约 45 行的样板。四份实现还不一致:
|
||||
- `ConfirmDialog` 与 `ImagePreviewDialog` 的选择器包含 `input/select/textarea`,`WorkflowCompareDialog` 只有 `'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])'` —— 对比弹窗里如果出现输入框,Tab 会跳出弹窗。
|
||||
- `ConfirmDialog` 额外做了 `!dialogRef.value?.contains(active)` 的兜底,另外三份没有。
|
||||
- **代码**(`WorkflowCompareDialog.vue:34-40` vs `ConfirmDialog.vue:42-47`):
|
||||
```ts
|
||||
// WorkflowCompareDialog.vue
|
||||
function focusableElements() {
|
||||
return Array.from(
|
||||
dialogRef.value?.querySelectorAll<HTMLElement>(
|
||||
'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])',
|
||||
) ?? [],
|
||||
)
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// ConfirmDialog.vue
|
||||
function focusableElements() {
|
||||
return Array.from(
|
||||
dialogRef.value?.querySelectorAll<HTMLElement>(
|
||||
'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
|
||||
) ?? [],
|
||||
).filter((element) => !element.hasAttribute("hidden"))
|
||||
}
|
||||
```
|
||||
- **影响**:约 180 行样板,抽成 composable 后剩约 50 行,净省 130 行;顺带统一无障碍行为,消除 `WorkflowCompareDialog` 的 Tab 逃逸。
|
||||
- **修复建议**:新增 `standalone-web/src/composables/useDialogFocusTrap.ts`:
|
||||
```ts
|
||||
export function useDialogFocusTrap(open: Ref<boolean>, opts: {
|
||||
dialogRef: Ref<HTMLElement | null>
|
||||
initialFocus?: () => HTMLElement | null | undefined
|
||||
onEscape?: () => void
|
||||
}) { /* previousFocus / focusables / onKeydown / restore */ return { onKeydown } }
|
||||
```
|
||||
项目已有 `safe-backdrop-close.ts` 这种单一职责工具模块的先例,放在同级即可。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `SettingsPage.vue` 里遗留一整段 1796 字符的 `.backup-*` 死样式
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/features/settings/SettingsPage.vue:165`(单物理行,1796 字符,格式化后约 45 行)
|
||||
- **问题**:备份面板早已拆成独立的 `features/settings/BackupPage.vue`,且该组件用的是自己的 `scoped` 类名(`.page` / `.hero` / `.cards` / `.full` / `.snapshots` / `.file` / `.list`)。`SettingsPage.vue` 的 `scoped` 样式里却仍保留着旧类名的全套定义,而 `SettingsPage.vue` 模板里这些类零出现——因为是 `scoped`,它们绝无可能作用到 `BackupPage.vue` 上。
|
||||
- **代码**(`SettingsPage.vue:165` 开头片段):
|
||||
```css
|
||||
.backup-page{display:grid;gap:15px}.backup-hero{display:flex;align-items:center;gap:13px;border:1px solid var(--border);border-radius:10px;padding:15px;background:linear-gradient(105deg,var(--primary-soft),var(--panel-muted))}.backup-hero>div:last-child{display:grid;gap:4px}.backup-hero p,.backup-grid p{color:var(--text-soft);font-size:12px;line-height:1.5}.backup-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:13px}...
|
||||
```
|
||||
对照 `BackupPage.vue` 模板实际使用的类:
|
||||
```html
|
||||
<div class="page">
|
||||
<section class="hero"><b>↕</b>...</section>
|
||||
<div class="cards"><article>...</article></div>
|
||||
```
|
||||
- **影响**:约 1.8 KB / 45 逻辑行死样式;`SettingsPage.vue:167` 的媒体查询里还引用了 `.backup-grid` / `.backup-scope>div`,同样死。
|
||||
- **修复建议**:删除 `SettingsPage.vue:165` 整行,以及 `:167` 媒体查询中的 `.backup-grid,.backup-scope>div` 选择器项。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] App.vue 全局样式里躺着 5 个已抽离组件的样式,其中 691 行属于"隐式全局依赖"
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue`(样式块);受影响组件 `components/AppNavigationRail.vue`(**整个文件没有 `<style>`**)、`components/MaterialCategoryCreateDialog.vue`(**没有 `<style>`**)、`components/MaterialDetailDialog.vue`(只有 4 行 `<style scoped>`)
|
||||
- **问题**:静态分析发现 31 个类在 App.vue 的全局 `<style>` 中定义、但只被子组件模板使用。分成两类:
|
||||
- **隐式依赖(691 行)**:`AppNavigationRail` 的 `rail / brand / brand-mark / brand-copy / icon-nav / nav-scroll / nav-group / nav-group-label / nav-group-items / nav-glyph / nav-copy / nav-label / rail-pin / rail-pin-label` 共 347 行;`MaterialCategoryCreateDialog` 的 4 个类共 173 行;`MaterialDetailDialog` 的 `materials-detail-card*` 共 171 行。这些组件**离开 App.vue 就没有样式**。
|
||||
- **纯重复(136 行)**:`image-viewer-card/-actions/-stage`(104 行,见上一条)、`state-card` / `empty-state-actions` / `workflow-chat-panel` / `workflow-composer-panel`(32 行),子组件已有等价 `scoped` 副本。
|
||||
- **代码**(`components/AppNavigationRail.vue` 全文 97 行,无 `<style>` 块;其模板):
|
||||
```html
|
||||
<aside :class="['rail', { pinned, visible }]" ...>
|
||||
<div class="brand"><span class="brand-mark">IS</span><div class="brand-copy">...</div></div>
|
||||
<nav class="icon-nav">...
|
||||
```
|
||||
样式却在 `App.vue` 全局块里。
|
||||
- **影响**:组件不自洽,无法单独测试/复用;App.vue 样式块虚胖 691 行;136 行是纯冗余可直接删。
|
||||
- **修复建议**:把 347/173/171 三组规则分别剪切进 `AppNavigationRail.vue`、`MaterialCategoryCreateDialog.vue`、`MaterialDetailDialog.vue` 的 `<style scoped>`(`.rail` 这类需要父级配合的定位规则用 `:deep()` 或保留在 `workbench.css`);136 行重复的直接删。App.vue 样式块净减 827 行。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 全局重复 CSS 声明块:上限 2251 行,保守可回收 800–1200 行
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue`(8396 行样式)、`features/gallery/GalleryPage.vue`(916)、`features/profiles/*.vue`(1741)、`features/workflow/*.vue`(1516)等,全前端 CSS 共 14698 行
|
||||
- **问题**:扫描所有 `.vue`/`.css` 的声明块(≥2 条声明),完全相同的声明体重复出现 —— 按 `(出现次数-1) × (声明数+2)` 计,冗余上限 **2251 行**。高频样本:
|
||||
- `overflow:hidden; text-overflow:ellipsis; white-space:nowrap` —— **21 次**
|
||||
- `color: var(--text-soft); font-size: 12px; font-weight: 800` —— **21 次**(其中 14 次在 App.vue 内且声明完全一致)
|
||||
- `display: grid; gap: 4px; min-width: 0` —— **18 次**
|
||||
- `height:100%; object-fit:cover; width:100%` —— **14 次**
|
||||
- `background: var(--primary); border-color: var(--primary); color: #ffffff` —— **10 次**
|
||||
- **代码**(App.vue 内 14 处完全相同的"眼眉标签"规则,各 5 行):
|
||||
```
|
||||
App.vue:15423 .queue-hero span, .queue-board-panel header span, ...
|
||||
App.vue:15659 .queue-detail-panel dt
|
||||
App.vue:15810 .materials-hero span, .materials-library-panel header span, ...
|
||||
App.vue:16233 .materials-detail-card-preview span, ...
|
||||
App.vue:16358 .materials-category-create-card header span, ...
|
||||
App.vue:16612 .generate-hero span, .generate-section header span
|
||||
App.vue:16712 .image-preview-panel header span, .image-info-card header span, ...
|
||||
App.vue:16899 .image-info-card dt
|
||||
App.vue:17238 .image-viewer-card header span
|
||||
App.vue:19236 .quick-profile-detail-card-portrait span, ...
|
||||
App.vue:19427 .quick-profile-viewer-info header span, .quick-profile-viewer-info dt
|
||||
App.vue:19925 .quick-profile-profile-field span
|
||||
App.vue:20725 .external-profile-import-card > header span, ...
|
||||
App.vue:20959 .persona-questionnaire-card header span, ...
|
||||
```
|
||||
每处都是:
|
||||
```css
|
||||
{
|
||||
color: var(--text-soft);
|
||||
font-size: 12px;
|
||||
font-weight: 800;
|
||||
}
|
||||
```
|
||||
以及 6 个组件各自重复定义主按钮(`GalleryPage.vue:473`、`AdvancedMaterialImportPage.vue:1791`、`ProfileDetailPane.vue:614`、`ProfilesPage.vue:236`、`ProfileWardrobePane.vue:501`、`WorkflowMaterialDrawer.vue:528`):
|
||||
```css
|
||||
button.primary-button {
|
||||
border-color: var(--primary);
|
||||
color: #fff;
|
||||
background: var(--primary);
|
||||
}
|
||||
```
|
||||
- **影响**:约 10% 的 CSS 是复读;主色/字号改一次要改 20 处,`workbench.css` 的存在恰恰证明改不动——它是一层 458 行的"事后覆盖层",专门用超长选择器列表去覆盖 App.vue 的既有规则。
|
||||
- **修复建议**:
|
||||
1. `styles/tokens.css`(当前仅 24 行)扩成真正的 token/utility 层:`.u-truncate`、`.u-eyebrow`、`.u-stack-4`、`.u-cover-img`、`.u-btn-primary`。
|
||||
2. App.vue 内那 14 处合并成一条选择器列表规则(70 行 → 20 行)。
|
||||
3. 把 `workbench.css` 的覆盖规则回填进各自的基础规则,删掉这一层(458 行可减到 150 行以内)。
|
||||
4. `workbench.css:431-451` 是同一个媒体查询写了两遍(第二遍只是加了 `.navigation-shell` 前缀提高优先级),可直接删掉 10 行:
|
||||
```css
|
||||
@media (max-width: 1360px) and (min-width: 901px) {
|
||||
.overview-strip { grid-template-columns: minmax(220px, 1.2fr) repeat(3, minmax(120px, 0.8fr)) minmax(200px, 0.9fr); gap: 10px; }
|
||||
.overview-strip > * { min-width: 0; }
|
||||
}
|
||||
@media (max-width: 1360px) and (min-width: 901px) {
|
||||
.navigation-shell .overview-strip { grid-template-columns: minmax(220px, 1.2fr) repeat(3, minmax(120px, 0.8fr)) minmax(200px, 0.9fr); gap: 10px; }
|
||||
.navigation-shell .overview-strip > * { min-width: 0; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 25 个 loader 函数复读同一套 `loading/error/try/catch/finally` 样板
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:4488`(loadDashboard)、`:4511`(loadGalleryImages)、`:4611`(loadDailyCostUsage)、`:4624`(loadJobs)、`:4638`(loadLogs)、`:4673`(loadModelOptions)、`:4700`(loadSettingsPage)、`:4787`(loadMaterials)、`:4864`(loadBackendQuickProfiles)、`:5010`(loadProfileWardrobe)、`:6872`(loadWorkflowBranches)、`:6894`(loadWorkflowDependencyContext)、`:7028`(loadWorkflowRounds)、`:7115`(loadSelectedWorkflowNodeMaterials) 等
|
||||
- **问题**:App.vue 声明了 **10 个 `loadingXxx` ref + 25 个 `xxxError` ref + 5 个 `xxxBusy` ref**(`:869-892` 集中区 + `:666-814` 分散区),每个 loader 手写同一套开关。全文件 82 处 `try {`、76 处 `catch (err)`。
|
||||
- **代码**(App.vue:4611-4622,与 4488/4624/4700/4787 结构完全一致):
|
||||
```ts
|
||||
async function loadDailyCostUsage() {
|
||||
loadingDailyCostUsage.value = true
|
||||
dailyCostUsageError.value = ""
|
||||
try {
|
||||
dailyCostUsage.value = await getJson<CostUsageSummary>(endpoints.costUsage, { days: 1 })
|
||||
} catch (err) {
|
||||
dailyCostUsage.value = null
|
||||
dailyCostUsageError.value = `今日用量读取失败:${errorMessage(err)}`
|
||||
} finally {
|
||||
loadingDailyCostUsage.value = false
|
||||
}
|
||||
}
|
||||
```
|
||||
- **影响**:约 125 行纯样板 + 40 个平行 ref。样板本身还不一致:`loadModelOptions`(`:4673`) 忘了 `try/finally`,直接在末尾赋 `loadingModelOptions.value = false`,请求抛错时 loading 会永久卡死;`loadJobs`(`:4624`) 的 error 清理带条件分支。
|
||||
- **修复建议**:抽 `standalone-web/src/composables/useAsyncResource.ts`:
|
||||
```ts
|
||||
export function useAsyncResource<T>(loader: () => Promise<T>, opts?: {
|
||||
initial?: T; errorPrefix?: string; onError?: (e: unknown) => void
|
||||
}) {
|
||||
const data = ref(opts?.initial), loading = ref(false), error = ref("")
|
||||
async function reload() { loading.value = true; error.value = ""
|
||||
try { data.value = await loader() } catch (e) { error.value = `${opts?.errorPrefix ?? ""}${errorMessage(e)}`; opts?.onError?.(e) } finally { loading.value = false } }
|
||||
return { data, loading, error, reload }
|
||||
}
|
||||
```
|
||||
25 个 loader 各缩到 1–3 行,40 个 ref 缩到 25 个解构,净省约 90–120 行,并顺手修掉 `loadModelOptions` 的 loading 泄漏。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] pinia 与 vue-router 声明为依赖但整个代码库零引用;构建工具全部错放在 `dependencies`
|
||||
|
||||
- **位置**:`frontend/package.json:15-23`
|
||||
- **问题**:
|
||||
```json
|
||||
"dependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"pinia": "^2.3.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-router": "^4.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
},
|
||||
"devDependencies": {}
|
||||
```
|
||||
实测 `grep -rn "pinia" --include=*.ts --include=*.vue frontend/{shared,standalone-web,plugin-page,tests}` → **0 命中**;`vue-router` 同样 **0 命中**。两者在 `node_modules` 里占 1.1 MB(pinia 407 K + vue-router 691 K)。
|
||||
同时 `devDependencies` 为空,`typescript`(23 MB) / `vite`(2.7 MB) / `vue-tsc` / `@vitejs/plugin-vue` 这些纯构建期工具全在 `dependencies`。插件发布时只带预构建产物(`web/`、`pages/imagestudio/`),运行期完全不需要 `node_modules`,所以严格说 **7 个依赖全部应该是 devDependencies**。
|
||||
- **影响**:`npm ci --omit=dev` 得不到任何东西(无法只装运行期依赖);任何基于 `dependencies` 的 SCA/许可证扫描会把 23 MB 的 TypeScript 编译器算作运行期依赖;pinia/vue-router 的存在会误导人以为项目有路由和 store,实际上导航是 App.vue 里的 `activeNav` ref(`:5102 setActiveNav`)+ `navigation-config.ts`。
|
||||
- **修复建议**:
|
||||
```json
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
}
|
||||
```
|
||||
删除 `pinia`、`vue-router`,同步更新 `package-lock.json`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] App.vue 用 206 个 ref + 135 个 computed 的巨型局部状态树代替 store
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:644-893`(集中 ref 区)、`:894-4296`(computed 区)、`:9834-9935`(overlay 状态机)
|
||||
- **问题**:统计 App.vue 顶层符号:**206 个 `ref`、135 个 `computed`、264 个 `function`、101 个 `async function`**。整个文件只有 1 条区块注释(`:903`)。跨模块状态(bootstrap/permissions、素材库、角色档案、工作流轮次、队列)全部平铺在同一个 setup 作用域里,子组件靠 props 逐层透传 + emit 回传。
|
||||
最典型的症状是 overlay 状态机被写成两条 12 分支的 `if` 链:
|
||||
```ts
|
||||
// App.vue:9846-9894
|
||||
function setOverlayOpen(key: ControlledOverlay, open: boolean) {
|
||||
if (key === "search") { searchFocused.value = open; searchPanelOpen.value = open }
|
||||
if (key === "palette") { showPalette.value = open }
|
||||
if (key === "notifications") { showNotificationPanel.value = open }
|
||||
if (key === "logs") { showLogPanel.value = open }
|
||||
if (key === "imageViewer") { showImageViewer.value = open; if (!open) { imageViewerDragging.value = false } }
|
||||
... // 共 12 个分支
|
||||
}
|
||||
|
||||
// App.vue:9896-9931
|
||||
function isOverlayOpen(key: ControlledOverlay) {
|
||||
if (key === "search") { return searchPanelOpen.value }
|
||||
... // 共 11 个分支
|
||||
return showLogPanel.value // ← 兜底返回 logs,新增 overlay 忘了加分支就会静默错判
|
||||
}
|
||||
```
|
||||
- **影响**:85 行可被 25 行的注册表替代;更重要的是 `isOverlayOpen` 的 fallback 是 `showLogPanel.value`,新增一个 `ControlledOverlay` 而忘记加分支时不报错、行为诡异。整体上 App.vue 的状态树使得任何一个功能改动都要打开 22563 行的文件。
|
||||
- **修复建议**:
|
||||
1. **低成本、立刻可做**:overlay 改注册表驱动 ——
|
||||
```ts
|
||||
const overlayRegistry: Record<ControlledOverlay, { isOpen(): boolean; setOpen(v: boolean): void }> = {
|
||||
search: { isOpen: () => searchPanelOpen.value, setOpen: (v) => { searchFocused.value = v; searchPanelOpen.value = v } },
|
||||
...
|
||||
}
|
||||
const isOverlayOpen = (k: ControlledOverlay) => overlayRegistry[k].isOpen()
|
||||
```
|
||||
省 40 行并消除 fallback 陷阱。
|
||||
2. **中成本**:不必上 pinia。按 feature 抽 composable(`useWorkflowWorkspace()` / `useMaterialLibrary()` / `useQuickProfile()` / `useQueue()`),每个返回自己的 state + actions,App.vue 只负责组装。这条路子和现有 `features/*/xxx-state.ts`(如 `advanced-material-state.ts`)的组织方式一致,迁移成本低于引入 store。
|
||||
3. 若坚持要 store,pinia 已在 `package.json` 里但 `main.ts`(4 行)从未 `createPinia()`,需要先接入;考虑到本项目是嵌入式插件页、无 SSR、无跨路由状态共享需求,**建议走 composable 路线并删掉 pinia**。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `shared/types/workflow.ts` 里 35 行类型是 `workflow-material.ts` 的过期副本
|
||||
|
||||
- **位置**:`frontend/shared/types/workflow.ts:88-130` 与 `frontend/shared/types/workflow-material.ts:1-62`
|
||||
- **问题**:`WorkflowMaterialNavigationContext` 在两个文件里**逐字段完全相同**地定义了两遍;`workflow.ts` 的 `WorkflowNodeMaterialBindingDetail`(:108-123) 与 `WorkflowNodeMaterialBindingSaveRequest`(:125-130) 是 `workflow-material.ts` 的 `WorkflowNodeMaterialBindingsResult` / `WorkflowNodeMaterialBindingsSaveRequest` 的旧版本。全代码库检索显示 `WorkflowNodeMaterialBindingDetail`、`WorkflowNodeMaterialBindingSaveRequest`、`WorkflowTemporaryReference` **只在 `workflow.ts` 内部互相引用,无任何外部使用者**(App.vue:129 导入的是 `workflow-material.ts` 那一版)。
|
||||
- **代码**:
|
||||
```ts
|
||||
// shared/types/workflow.ts:88-94
|
||||
export interface WorkflowMaterialNavigationContext {
|
||||
workflow_id: string
|
||||
branch_name: string
|
||||
node_id: string
|
||||
round_id?: string | null
|
||||
return_view: string
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// shared/types/workflow-material.ts:1-7 ← 一模一样
|
||||
export interface WorkflowMaterialNavigationContext {
|
||||
workflow_id: string
|
||||
branch_name: string
|
||||
node_id: string
|
||||
round_id?: string | null
|
||||
return_view: string
|
||||
}
|
||||
```
|
||||
- **影响**:35 行死类型;两份定义如果后端字段变更时只改一份,类型检查会给出互相矛盾的结论。
|
||||
- **修复建议**:删除 `workflow.ts:96-130`(`WorkflowTemporaryReference` + 两个绑定接口);`workflow.ts:88-94` 改成 `export type { WorkflowMaterialNavigationContext } from "./workflow-material"`(`:82` 仍需引用它)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 19 个导出符号无任何使用者
|
||||
|
||||
- **位置**:`frontend/shared/types/integration.ts:1`(整个文件 7 行只有 `DailyOutfitResult`,零引用)、`shared/api/client.ts`(`patchJson`)、`shared/types/advanced-material.ts`(`AdvancedMaterialImportListResult` / `AdvancedMaterialValidationAttemptListResult` / `AdvancedMaterialListResult` / `MaterialCatalogResult` / `AdvancedMaterialValidationAttemptRequest` / `AdvancedStyleConsensusRequest`)、`shared/types/logs.ts`(`EventStreamResult` / `LogBundle`)、`shared/types/storage.ts`(`StorageStatus` / `StorageMigrationPlan`)、`shared/types/ui.ts`(`UiAction`)、`shared/types/wardrobe.ts`(`WardrobeMatchResult`)、`shared/types/workflow-round.ts`(`WorkflowRoundNextRequest` / `WorkflowRoundConfirmRequest`)、`features/workflow/types.ts`(`WorkflowRoundKnownStatus`)
|
||||
- **问题**:全量扫描 93 个 `.ts`/`.vue`/`.mjs` 源文件,这 19 个导出的标识符在整个代码库中只出现 1 次(即声明自身)。
|
||||
- **代码**(`shared/types/integration.ts` 全文):
|
||||
```ts
|
||||
export interface DailyOutfitResult {
|
||||
matched: boolean
|
||||
selected_materials: Array<Record<string, unknown>>
|
||||
final_prompt: string
|
||||
job_id?: string | null
|
||||
fallback_used: boolean
|
||||
}
|
||||
```
|
||||
`App.vue:4566-4568` 手写了内联的事件流类型而不用 `EventStreamResult`:
|
||||
```ts
|
||||
const stream = await getJson<{
|
||||
events: Array<{ event_id?: string; event_type?: string; data?: Record<string, unknown> }>
|
||||
}>(endpoints.eventStream, { limit: 20 })
|
||||
```
|
||||
- **影响**:约 45 行死类型;`EventStreamResult` 这种"定义了但调用方手写内联类型"的情况还会导致后端字段变更时类型失去保护作用。
|
||||
- **修复建议**:删掉 `integration.ts`(整文件)与其余 18 个;`App.vue:4566` 改用 `getJson<EventStreamResult>(...)` 而不是删 `EventStreamResult`。删除前建议先跑 `npm run typecheck` 确认(该脚本已存在于 `package.json:12`)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `errorMessage` 在两处独立实现且行为不一致
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:11354-11356` 与 `frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1354-1356`
|
||||
- **问题**:
|
||||
```ts
|
||||
// App.vue:11354
|
||||
function errorMessage(err: unknown) {
|
||||
return readableApiError(err) // 会识别 ApiClientError、区分预览模式、给中文可读文案
|
||||
}
|
||||
```
|
||||
```ts
|
||||
// AdvancedMaterialImportPage.vue:1354
|
||||
function errorMessage(err: unknown) {
|
||||
return err instanceof Error ? err.message || "请求失败" : String(err || "请求失败")
|
||||
}
|
||||
```
|
||||
同一个 `ApiClientError` 在主界面显示"后端未连接,当前为预览模式"之类的可读提示,在进阶素材页只会显示原始 message。`AdvancedMaterialImportPage.vue:1350` 还独立重实现了 `normalizeStatus`(`shared/utils/presentation.ts:7` 已有同名导出)。
|
||||
- **影响**:行数很小(约 8 行),但错误提示体验不一致,属于"共享工具没被共享"的信号。
|
||||
- **修复建议**:把 `readableApiError` / `backendWriteBlockMessage`(`App.vue:4356-4387`)下沉到 `shared/utils/api-error.ts`,两处都导入;`AdvancedMaterialImportPage.vue:1350` 的 `normalizeStatus` 改为从 `shared/utils/presentation` 导入。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `tsconfig.json` 的 `@shared/*` 路径别名无人使用,且 Vite 侧没有对应 alias
|
||||
|
||||
- **位置**:`frontend/tsconfig.json:15-17`、`frontend/plugin-page/vite.config.ts`、`frontend/standalone-web/vite.config.ts`
|
||||
- **问题**:
|
||||
```json
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@shared/*": ["shared/*"]
|
||||
}
|
||||
```
|
||||
全代码库检索 `@shared/` → **0 命中**。所有引用走的是相对路径,App.vue 里是 `"../../shared/api/endpoints"`,`features/settings/BackupPage.vue:3` 甚至写到 `"../../../../shared/api/client"`。而且两个 `vite.config.ts` 都没有配 `resolve.alias`,即便有人开始用 `@shared/`,`vue-tsc` 能过、`vite build` 会失败。
|
||||
- **代码**(`BackupPage.vue:3-5`):
|
||||
```ts
|
||||
import { getJson, postJson } from "../../../../shared/api/client"
|
||||
import { endpoints } from "../../../../shared/api/endpoints"
|
||||
import type { DiffSettingsResult, ... } from "../../../../shared/types/settings"
|
||||
```
|
||||
- **影响**:配置死代码 + 潜在的"类型检查通过但构建失败"陷阱;`../../../../` 这种路径也让文件移动变得昂贵。
|
||||
- **修复建议**:二选一 —— 要么删掉 `tsconfig.json` 的 `paths`/`baseUrl`;要么在两个 `vite.config.ts` 补上
|
||||
```ts
|
||||
resolve: { alias: { "@shared": resolve(rootDir, "../../shared") } }
|
||||
```
|
||||
并把全部 `../../shared` / `../../../../shared` 批量替换为 `@shared`(约 60 处 import)。推荐后者。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] App.vue 内出现压缩风格代码,与文件其余部分格式冲突
|
||||
|
||||
- **位置**:`frontend/standalone-web/src/App.vue:4549-4559`;同样风格见 `components/MaterialDetailDialog.vue:34-58`、`features/settings/BackupPage.vue:14-25`、`features/settings/ReviewPolicyPanel.vue:14`
|
||||
- **问题**:同一文件里既有 Prettier 风格的展开代码,又有手工压行的代码:
|
||||
```ts
|
||||
async function expandImageGenerationPrompt() {
|
||||
const prompt=imageGenerationPrompt.value.trim()
|
||||
if(!prompt||promptExpansionBusy.value)return
|
||||
promptExpansionBusy.value=true
|
||||
try{
|
||||
const result=await postJson<{selected_prompt?:string;translation?:{translated_text?:string;status?:string;error?:string}}>(endpoints.promptGovernancePreview,{prompt,entrypoint:"web",translation_consent:true,selection:"translated",model_route:selectedImageModelRoute()})
|
||||
const expanded=String(result.selected_prompt||result.translation?.translated_text||"").trim()
|
||||
if(!expanded||result.translation?.status==="unavailable_fallback"||result.translation?.status==="failed_fallback")throw new Error(result.translation?.error||"未找到可用的提示词扩写模型")
|
||||
imageGenerationPrompt.value=expanded
|
||||
}catch(err){imageGenerationError.value=`提示词扩写失败:${errorMessage(err)}`}finally{promptExpansionBusy.value=false}
|
||||
}
|
||||
```
|
||||
`ReviewPolicyPanel.vue:14` 更极端:整个 `<style scoped>` 是一行 1000+ 字符。
|
||||
- **影响**:行数统计失真(压行让"精简"的账面收益被掩盖)、`git diff` 一行全红/全绿无法审查、无法用 lint 自动格式化。
|
||||
- **修复建议**:引入 Prettier(配 `printWidth: 110`,与现有多数代码一致)并加一个 `npm run format:check` 到 CI。展开后 CSS/TS 总行数会上升约 800 行,但这是把隐藏的复杂度显性化,后续所有重复检测/删除都会更可靠。
|
||||
|
||||
---
|
||||
|
||||
## 量化汇总
|
||||
|
||||
### A. 净删除空间(可直接减少的行数)
|
||||
|
||||
| # | 项目 | 位置 | 预计削减 |
|
||||
|---|---|---|---|
|
||||
| 1 | App.vue 死 CSS 规则(41 条,纯死类构成) | App.vue:17323 / 17764-17845 / 19007-19059 / 20075-20101 / 21129-21286 / 21484-21499 / 21662-21703 | **277** |
|
||||
| 2 | `.image-viewer-card/-actions/-stage` 与子组件 scoped 重复 | App.vue:17213-17316 | **104** |
|
||||
| 3 | `state-card`/`empty-state-actions`/`workflow-chat-panel`/`workflow-composer-panel` 与子组件 scoped 重复 | App.vue 样式块 | **32** |
|
||||
| 4 | `SettingsPage.vue` 遗留 `.backup-*` 死样式 | SettingsPage.vue:165,167 | **45**(1 物理行) |
|
||||
| 5 | `workbench.css` 重复媒体查询 | workbench.css:442-451 | **10** |
|
||||
| 6 | 素材选择器弹层模板重复 | App.vue:12009-12117 / 12658-12769 | **100** |
|
||||
| 7 | 4 份焦点陷阱 → composable | ConfirmDialog / ImagePreviewDialog / WorkflowCompareDialog / WorkflowGenerationReviewDialog | **130** |
|
||||
| 8 | 图片缩放/拖拽逻辑重复 → composable | App.vue:7952-8011 + 12218-12266 | **95** |
|
||||
| 9 | App.vue 内 14 处相同"眼眉"规则等,选择器列表合并 | App.vue(14 处,各 5 行) | **50** |
|
||||
| 10 | 跨组件重复声明块(truncate / cover-img / primary-button / grid-gap 等)→ utility class | 全前端 CSS 14698 行 | **700–1100**(上限 2251) |
|
||||
| 11 | 25 个 loader 样板 → `useAsyncResource` | App.vue:4488-7185 各 loader | **90** |
|
||||
| 12 | `setOverlayOpen`/`isOverlayOpen` 表驱动 | App.vue:9846-9931 | **40** |
|
||||
| 13 | `shared/types/workflow.ts` 过期类型副本 | workflow.ts:96-130 | **35** |
|
||||
| 14 | 19 个零引用导出(含 `integration.ts` 整文件) | shared/types/*、shared/api/client.ts | **45** |
|
||||
| 15 | `errorMessage`/`normalizeStatus` 重复实现 | App.vue:11354 / AdvancedMaterialImportPage.vue:1350-1356 | **8** |
|
||||
| 16 | `tsconfig.json` 死别名配置 | tsconfig.json:15-17 | **4** |
|
||||
| 17 | `pinia` + `vue-router` 依赖(源码 0 行,node_modules 1.1 MB) | package.json:17,21 | **2 行 / 1.1 MB** |
|
||||
| | **合计** | | **约 1770–2170 行**(取中值 **≈ 1970 行**) |
|
||||
|
||||
占前端源码 40182 行的 **4.9%**,占 CSS 14698 行的 **约 13%**。
|
||||
|
||||
### B. 迁移拆分空间(不减总量,但把 App.vue 从 22563 压到 6000–7000)
|
||||
|
||||
| 目标 | 当前位置 | 迁出行数 |
|
||||
|---|---|---|
|
||||
| `styles/quick-profile.css` | App.vue 样式块 `quick-profile-*` | 1268 |
|
||||
| `styles/workflow.css` | `workflow-*`(node/profile/persona/prompt/draft/material/subnode/preview/action/group/section/generation) | ~1400 |
|
||||
| `styles/materials.css` | `materials-*` | ~600 |
|
||||
| `styles/image-workspace.css` | `image-*` (composer/preview/info/stage) | ~400 |
|
||||
| 剪进 `AppNavigationRail.vue` | App.vue 的 `rail/brand/nav-*` 规则 | 347 |
|
||||
| 剪进 `MaterialCategoryCreateDialog.vue` / `MaterialDetailDialog.vue` | App.vue 的对应规则 | 344 |
|
||||
| `features/workflow/WorkflowStages.vue`(×6 stage 子组件) | App.vue:12440-12772、12842-12988 | ~530 |
|
||||
| `features/quick-profile/QuickProfileWorkspace.vue` | App.vue:11809-12268 | ~460 |
|
||||
| `features/image/ImageGenerateWorkspace.vue` | App.vue:11648-11807 | ~160 |
|
||||
| `features/quick-profile/ExternalProfileImportDialog.vue` | App.vue:12988-13075 | ~88 |
|
||||
| `features/quick-profile/PersonaQuestionnaireDialog.vue` | App.vue:13077-13329 | ~252 |
|
||||
| `features/workflow/workflow-action-cards.ts` | App.vue:2782-3222(441 行)+ 标签表 3223-3282 | ~500 |
|
||||
| `features/*/action-cards.ts`(generate/queue/material/quickProfile) | App.vue:3751-3921、3370-3512、1346-1458、1931-2041 | ~580 |
|
||||
| `features/quick-profile/quick-character-generation.ts` | App.vue:5786-6077 | 292 |
|
||||
| **合计迁出** | | **≈ 7200 行** |
|
||||
|
||||
拆分后 App.vue 预计:脚本 ~3500 行 + 模板 ~350 行 + 样式 <300 行 ≈ **4200 行**。
|
||||
|
||||
### C. 无精简空间的项(已核实)
|
||||
|
||||
- **`plugin-page` vs `standalone-web` 重复**:**0 行**。`plugin-page/src/App.vue` 仅 7 行(`import WorkbenchApp from "../../standalone-web/src/App.vue"`),`plugin-page/src/main.ts` 6 行,两个 `vite.config.ts` 各 16 行且只有 `base`/`outDir` 不同。这套双构建方案已经是最优解,不要动。
|
||||
- **未被引用的组件**:无。`standalone-web/src/components/` 与 `features/` 下 25 个 `.vue` 全部有引用者(`WorkflowCompareDialog` 等 7 个走 `defineAsyncComponent`,`App.vue:39-45`)。
|
||||
- **仓库卫生**:`frontend/node_modules`、`frontend/.pytest_cache` 均未被 git 跟踪(`git ls-files` 0 命中),无需清理。
|
||||
|
||||
### D. 建议执行顺序(按 收益/风险 比)
|
||||
|
||||
1. **零风险,立刻做**(约 550 行):#4 `SettingsPage.vue:165`、#5 `workbench.css:442-451`、#13 `workflow.ts:96-130`、#14 19 个死导出、#16 tsconfig 别名、#17 删 pinia/vue-router + 依赖分类。跑 `npm run typecheck` + `npm run test:contracts` 验证。
|
||||
2. **低风险,需视觉回归**(约 460 行):#1/#2/#3 死 CSS 删除。建议先加 `tests/dead-css.test.mjs` 把规则固化,再删。
|
||||
3. **中风险,需功能验证**(约 465 行):#6 素材选择器组件化、#7 focus trap composable、#8 图片查看器复用。这三项都触及交互,建议逐项 PR。
|
||||
4. **大工程**(#10 CSS utility 层 + B 表全部迁移):建议先做 #10 的 token/utility 层(它是所有后续 CSS 迁移的前置),再按 feature 逐个迁样式和模板。
|
||||
569
审计/findings/C3-测试与仓库卫生.md
普通文件
569
审计/findings/C3-测试与仓库卫生.md
普通文件
|
|
@ -0,0 +1,569 @@
|
|||
# C3 · 测试质量 + 仓库卫生 + 配置
|
||||
|
||||
> 审计范围(实际读过 / 实际执行统计的文件):
|
||||
> - 测试:`tests/`(45 个文件 11559 行,逐一统计;完整通读 `tests/test_profile_delete_route.py`、`tests/test_generation_task_display.py`、`tests/test_advanced_style_consensus_route.py`、`tests/test_resource_access_service.py`、`tests/test_material_vision_input.py`、`tests/test_image_provider_timeout.py`、`tests/test_worker_service.py`(150-230)、`tests/test_advanced_style_set_workflow.py`(1-80))
|
||||
> - 前端测试:`frontend/tests/*.mjs`(8 个,通读 `ui-theme-contract.test.mjs`、`workflow-model-route.test.mjs`、`workflow-cross-review-wiring.test.mjs`、`production-data-boundary.test.mjs`)
|
||||
> - 配置:`config.yaml`、`_conf_schema.json`、`metadata.yaml`、`requirements.txt`、`.gitignore`、`main.py:110-175`、`core/config_service.py`、`frontend/package.json`、`DEVELOPMENT.md`
|
||||
> - 源码对照:`backend/services/`(68 个 service,31016 行)、`backend/routes/`(34 个模块)、`backend/route_registry.py`(166 个 endpoint)
|
||||
> - 仓库卫生:`git ls-files` / `git log --all` / `.tmp/` / `.tmp_pytest_*` / `release/` / `web/` / `pages/imagestudio/` 全量文件与体积统计
|
||||
> - **未审计**(按规则排除):`.tmp/` 内部源码副本、`node_modules/`、`__pycache__/`、`release/` 内的源码、`web/assets/` 与 `pages/imagestudio/assets/` 的构建产物内容
|
||||
|
||||
## 摘要
|
||||
|
||||
测试层面:263 个后端用例可全量收集通过,核心工作流(round/queue/cross-review/advanced material)覆盖扎实,但 **166 个 endpoint 中只有 33 个(19.9%)被测试触及,34 个路由模块有 24 个从未出现在测试里**,68 个 service 有 23 个(4579 行)零覆盖,其中包含 `integration_token_service`(外部插件 token 鉴权)、`chat_command_guard_service`(聊天访问控制)、`deletion_safety_service` 三个安全相关模块。8 个前端"测试"里有 7 个是对 `.vue` / `.css` 源文本做正则匹配,不执行任何组件逻辑;35638 行 Vue 代码实质零行为测试。仓库没有 `conftest.py`、没有 `pytest.ini`/`pyproject.toml`,导致 `pytest tests/` 直接 `ModuleNotFoundError` 崩溃收集,只有 `python -m pytest` 能跑;21 个测试文件各自重复内联同一套 SQLite Database 夹具。
|
||||
|
||||
仓库卫生是本维度最严重的问题。工作树里躺着 **8228 个未跟踪垃圾文件 / 2.57 GB**(`.tmp` 6303 文件 2129 MB + 20 个根级 `.tmp_pytest_*` 1925 文件 507 MB)。`.gitignore` 确实挡住了它们,但**没挡住 `release/`(20 个 zip,37 MB 已入库)和 `web/` `pages/imagestudio/` 的构建产物(38 个哈希文件已入库)**;230 次提交里 86 次(37%)在改构建产物,历史上累计 439 个哈希命名的死 blob,`.git` 已膨胀到 51 MB。
|
||||
|
||||
最致命的一条是密钥泄漏:`.env.imagestudio_codex_handoff.yaml` 含 **2 个真实 OpenAI 兼容 API key、PostgreSQL 明文密码、AstrBot 管理员 JWT 与明文管理员密码**,虽然被 `.gitignore` 忽略未入库,但它已经被复制进 8 个 `deploy-*` 打包目录,并被打进 **19 个 `.tar.gz`/`.tar` 部署包**(其中 `nas-deploy-worktree-20260724.tar` 546 MB,还顺带打进了 3000+ 个 pytest 临时文件),这些包脚本会 scp 到 NAS。
|
||||
|
||||
配置层面:`config.yaml` 含 54 个私有区乱码字符(GBK/UTF-8 双重解码损坏),`metadata.yaml` 的 `short_desc`、`CHANGELOG.md`(649 处)同样损坏;`_conf_schema.json` 只暴露 64 个键,**整个 `prompt_governance`(NSFW 自动分流、内容审核 failure_policy、日志留存天数)和 `chat_access.adult_*_allowlist` 成人内容白名单完全没有配置项**,AstrBot 管理员无法在面板里配置这些安全开关。
|
||||
|
||||
## 发现
|
||||
|
||||
### [P0-致命] 真实 API Key / DB 密码 / 管理员 JWT 被打进 19 个部署包并推送到 NAS
|
||||
|
||||
- **位置**:`.env.imagestudio_codex_handoff.yaml:26`、`:45`、`:58`、`:65`、`:66`;打包证据见 `.tmp/deploy-1.0.35/.env.imagestudio_codex_handoff.yaml` 等 8 个目录
|
||||
- **问题**:该文件保存了可直接使用的生产/测试凭据。`.gitignore` 的 `.env*` 规则确实生效(`git ls-files` 确认 0 条匹配,`git log --all --diff-filter=A` 确认从未入库),但**打包脚本用的是"整目录复制"而不是 `git archive`**,于是把它一起带进了部署产物:
|
||||
|
||||
```
|
||||
# git ls-files 确认未入库
|
||||
$ git ls-files | grep -i env
|
||||
(空)
|
||||
|
||||
# 但 8 个 deploy 暂存目录都含有它
|
||||
.tmp\deploy-1.0.35\.env.imagestudio_codex_handoff.yaml 3506 B
|
||||
.tmp\deploy-clean-1.0.35\.env.imagestudio_codex_handoff.yaml 3506 B
|
||||
.tmp\deploy-clean-1.0.36\.env.imagestudio_codex_handoff.yaml 3506 B
|
||||
.tmp\deploy-clean-1.0.37\.env.imagestudio_codex_handoff.yaml 3506 B
|
||||
.tmp\deploy-stage-1.0.38-20260720-092843\.env...yaml 3506 B
|
||||
.tmp\deploy-stage-1.0.39-20260720-095704\.env...yaml 3506 B
|
||||
.tmp\deploy-stage-1.0.40-20260720-100538\.env...yaml 3506 B
|
||||
.tmp\deploy-stage-1.0.41-20260720-101338\.env...yaml 3506 B
|
||||
|
||||
# 19 个归档内含该文件(tar -tf 逐个验证)
|
||||
astrbot_plugin_imagestudio-1.0.35.tar.gz / 1.0.36 / 1.0.37
|
||||
astrbot_plugin_imagestudio-1.0.38~1.0.41-*.tar.gz
|
||||
astrbot_plugin_imagestudio-1.0.64.tar.gz / 1.0.65 / 1.0.67-* / 1.0.68-*
|
||||
imagestudio-1.0.66-deploy-20260724-224910.tar.gz
|
||||
imagestudio-material-*-20260724.tar.gz (5 个)
|
||||
nas-deploy-worktree-20260724.tar / nas-deploy-worktree-20260724-clean.tar
|
||||
```
|
||||
|
||||
归档里的实际条目路径:
|
||||
```
|
||||
$ tar -tf .tmp/astrbot_plugin_imagestudio-1.0.35.tar.gz | grep env
|
||||
astrbot_plugin_imagestudio/.env.imagestudio_codex_handoff.yaml
|
||||
$ tar -tf .tmp/astrbot_plugin_imagestudio-1.0.41-20260720-101338.tar.gz | grep env
|
||||
./.env.imagestudio_codex_handoff.yaml
|
||||
```
|
||||
|
||||
文件内的凭据类型(不复述完整值):
|
||||
```yaml
|
||||
model_sites.site_a.api_key_plaintext: "sk-3af1f9dd7ffd25ff...(64 hex)" # weilai.chat
|
||||
model_sites.site_b.api_key_plaintext: "sk-B6KqCtlccQ2MU5O3z2X2...(48)" # botcf.com
|
||||
postgresql.host/port/user/password: <PG_HOST:内网IP:已脱敏>:25008 / <PG_USER:已脱敏> / 明文密码
|
||||
astrbot.admin_token_plaintext: "eyJhbGciOiJIUzI1NiI..." (HS256 JWT, exp=1783872299)
|
||||
astrbot.admin_username / admin_password_plaintext: 明文管理员账号密码
|
||||
```
|
||||
讽刺的是文件末尾还写着 `rules.redact_secrets: true`。
|
||||
- **影响**:任何拿到部署包的人(NAS 上的其他用户、备份、误传到公开仓库/Issue 附件)可以:① 直接盗刷两个模型站点的额度;② 连上 <PG_HOST:内网IP:已脱敏>:25008 的 PostgreSQL 读写业务库;③ 用 JWT 与管理员密码接管 AstrBot 实例(该实例还托管本插件的全部 166 个 API)。JWT `exp=1783872299` 换算约 2026-07-12 过期,但 `admin_password_plaintext` 永不过期,可随时重签。`deploy_remote.sh` / `upload_via_ssh.py` 表明这些包已经上传到 NAS。
|
||||
- **修复建议**:
|
||||
1. **立刻轮换全部 5 类凭据**:weilai.chat 与 botcf.com 的 API key 作废重发;PG 用户 `<PG_USER:已脱敏>` 改密;AstrBot 管理员改密并使 JWT 失效(改 secret)。
|
||||
2. 删除全部含泄漏的归档与 staging 目录:
|
||||
```powershell
|
||||
Remove-Item -Recurse -Force .tmp\deploy-1.0.35, .tmp\deploy-clean-1.0.3?, .tmp\deploy-stage-1.0.4?-*
|
||||
Get-ChildItem .tmp -File | Where-Object { $_.Name -match '\.(tar|tar\.gz|zip|b64)$' } | Remove-Item -Force
|
||||
```
|
||||
并到 NAS 上删除已上传的同名包。
|
||||
3. 打包改为 `git archive`,从源头杜绝未跟踪文件进包:
|
||||
```bash
|
||||
git archive --format=tar.gz --prefix=astrbot_plugin_imagestudio/ -o dist/plugin-$(git describe --always).tar.gz HEAD
|
||||
```
|
||||
并在打包脚本末尾加断言:`tar -tf "$OUT" | grep -qE '(^|/)\.env' && { echo "SECRET LEAK"; exit 1; }`
|
||||
4. 凭据本身改为环境变量注入(`_conf_schema.json` 里已经有 `*_api_key_env_var` 字段,说明设计上本就支持),文件里只留 env var 名。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `pytest tests/` 直接崩溃:无 conftest.py、无 pytest 配置,测试只能用 `python -m pytest` 跑
|
||||
|
||||
- **位置**:仓库根(缺 `conftest.py` / `pytest.ini` / `pyproject.toml` / `setup.cfg` / `tox.ini`,`find . -name conftest.py` 全仓库 0 命中)
|
||||
- **问题**:45 个测试文件全部用 `from backend...` / `from adapters...` 这类以仓库根为起点的绝对导入,但没有任何机制把仓库根加进 `sys.path`。只有 `python -m pytest`(`-m` 会把 CWD 插到 `sys.path[0]`)才能工作:
|
||||
|
||||
```
|
||||
$ python -m pytest tests/test_profile_delete_route.py -q
|
||||
1 passed in 0.14s
|
||||
|
||||
$ pytest tests/test_profile_delete_route.py -q
|
||||
tests\test_profile_delete_route.py:3: in <module>
|
||||
from adapters.astrbot_adapter import resolve_route
|
||||
E ModuleNotFoundError: No module named 'adapters'
|
||||
=========================== short test summary ===========================
|
||||
ERROR tests/test_profile_delete_route.py
|
||||
!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!
|
||||
```
|
||||
- **影响**:任何 CI 模板、IDE 测试运行器(PyCharm/VSCode 默认调 `pytest`)、`tox`、`pre-commit` 都会在收集阶段全军覆没,且报的是 `ModuleNotFoundError` 这种指向不明的错。新贡献者按直觉敲 `pytest` 会得到"这个仓库的测试是坏的"的结论。同时缺少配置文件也意味着没有 `--strict-markers`、没有超时保护、没有覆盖率门槛。
|
||||
- **修复建议**:新建 `pyproject.toml`(或最小化的 `pytest.ini`):
|
||||
```toml
|
||||
[tool.pytest.ini_options]
|
||||
pythonpath = ["."]
|
||||
testpaths = ["tests"]
|
||||
addopts = "-q --strict-markers"
|
||||
filterwarnings = ["error::DeprecationWarning"]
|
||||
```
|
||||
`pythonpath` 需要 pytest >= 7.0;若要兼容更旧版本,再加一个仓库根 `conftest.py`:
|
||||
```python
|
||||
import sys, pathlib
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 166 个 endpoint 只有 33 个被测试触及,24/31 路由模块零覆盖(含鉴权与文件服务)
|
||||
|
||||
- **位置**:`backend/route_registry.py`(`ROUTES` 共 166 条)对照 `tests/*.py`
|
||||
- **问题**:用 `RouteSpec.endpoint` 字面量与 `handler` 模块名对 45 个测试文件做全文匹配:
|
||||
```
|
||||
total endpoints: 166 referenced in tests: 33 (19.9%)
|
||||
route modules: 31 referenced: 7 (22.6%)
|
||||
|
||||
untested modules:
|
||||
api_discovery_routes asset_routes branch_routes contract_routes
|
||||
cost_routes dashboard_routes data_backup_routes event_routes
|
||||
history_routes image_routes integration_routes job_routes
|
||||
log_routes material_routes media_routes model_runtime_routes
|
||||
prompt_routes round_routes settings_routes storage_routes
|
||||
ui_routes wardrobe_routes web_routes workflow_routes
|
||||
```
|
||||
被测的 7 个是 `advanced_material_routes`、`generation_cross_review_routes`、`node_material_routes`、`node_routes`、`profile_card_routes`、`profile_routes`、`review_routes`。
|
||||
- **影响**:`storage_routes`(签名 URL / 文件下发,直接决定"前端永远不能看到本地绝对路径"这条安全约束能否守住)、`integration_routes`(外部插件集成入口)、`settings_routes`(写配置)、`media_routes`、`data_backup_routes`(导出全量数据)这几个高风险模块,任何一次重构后的权限回归都不会被测试拦住。`round_routes`(工作流轮次的公开入口)虽然 service 层有 1055 行测试,但路由层的参数校验/权限装饰完全裸奔。
|
||||
- **修复建议**:不必给 166 个 endpoint 逐个写用例,优先补两层:
|
||||
1. **注册表级契约测试**(成本极低,一次覆盖 166 条):断言每条 `RouteSpec` 的 `handler` 可 import、可调用、`permission` 非空且属于合法枚举;断言 `assert_unique_routes()` 通过。
|
||||
```python
|
||||
from backend.route_registry import ROUTES, assert_unique_routes
|
||||
def test_every_route_handler_resolves_and_declares_permission():
|
||||
assert_unique_routes()
|
||||
for spec in ROUTES:
|
||||
mod, fn = spec.handler.rsplit(".", 1)
|
||||
assert callable(getattr(importlib.import_module(mod), fn)), spec.endpoint
|
||||
assert spec.permission in {"read", "write", "admin"}, spec.endpoint
|
||||
```
|
||||
2. 对 `storage_routes` / `integration_routes` / `settings_routes` / `data_backup_routes` 补越权用例,复用 `tests/test_resource_access_service.py:96` 已有的 owner-chain 参数化模式。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 23 个 service(4579 行)零测试,其中 3 个是安全边界模块
|
||||
|
||||
- **位置**:`backend/services/`(68 个 service / 31016 行)对照 `tests/*.py` 全文
|
||||
- **问题**:以下 service 名在整个 `tests/` 目录中一次都没出现过:
|
||||
```
|
||||
material_binding_schema_service.py 408 行
|
||||
asset_import_service.py 406
|
||||
prompt_plan_schema_service.py 379
|
||||
model_provider_bootstrap.py 375
|
||||
node_injection_template_service.py 366
|
||||
branch_lineage_service.py 356 ← 注意 tests/test_workflow_branch_lineage.py 存在
|
||||
api_discovery_service.py 351
|
||||
history_service.py 314
|
||||
log_service.py 300
|
||||
workflow_progression_service.py 240 ← tests/test_character_workflow_progression.py 存在
|
||||
integration_token_service.py 202 ← 外部插件 token 鉴权
|
||||
integration_service.py 171
|
||||
dashboard_service.py 117
|
||||
chat_command_guard_service.py 101 ← 聊天侧访问控制
|
||||
chat_session_service.py 86
|
||||
web_hosting_service.py 84
|
||||
deletion_safety_service.py 75 ← 删除前的安全检查
|
||||
reference_binding_mapper.py 69
|
||||
event_stream_service.py 50
|
||||
chat_media_import_service.py 47
|
||||
ui_service.py 37
|
||||
contract_service.py 30
|
||||
media_index_service.py 15
|
||||
------------------------------------------------
|
||||
合计 4579 行 / 23 个模块(占 service 总数 33.8%)
|
||||
```
|
||||
特别值得注意的是 `branch_lineage_service` 和 `workflow_progression_service`:存在同名测试文件(`test_workflow_branch_lineage.py` 332 行、`test_character_workflow_progression.py` 248 行),但它们测的是别的模块,真正的 service 一行没碰——这种"看起来有测试"的假象比明摆着没测试更危险。
|
||||
- **影响**:`integration_token_service`(202 行 token 签发/校验)零测试 = 外部插件鉴权逻辑没有任何回归保护;`chat_command_guard_service`(101 行)零测试 = `chat_access` 白名单/限流的绕过不会被发现;`deletion_safety_service`(75 行)零测试 = 误删保护失效时静默。
|
||||
- **修复建议**:按风险排序补三个模块即可覆盖大部分暴露面:
|
||||
1. `integration_token_service`:签发→校验→过期→篡改签名→重放,5 个用例。
|
||||
2. `chat_command_guard_service`:白名单命中/未命中、成人白名单、并发上限、日限额,4 个用例(可直接复用 `tests/test_chat_workflow_round_commands.py` 的 fixture)。
|
||||
3. `deletion_safety_service`:有引用时拒删、级联引用、强制删除路径,3 个用例。
|
||||
同时把 `test_workflow_branch_lineage.py` / `test_character_workflow_progression.py` 与真实 service 接上,或改名以免误导。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 前端 8 个测试里 7 个是"源码正则匹配",35638 行 Vue 零行为测试
|
||||
|
||||
- **位置**:`frontend/tests/`(8 个 `.mjs`),典型代表 `frontend/tests/production-data-boundary.test.mjs:33-38`、`frontend/tests/workflow-cross-review-wiring.test.mjs:19-33`
|
||||
- **问题**:`grep -l readFile frontend/tests/*.mjs` 命中 7/8 个文件。这些"测试"把 `.vue` / `.css` 当纯文本读进来做正则断言,从不实例化组件:
|
||||
|
||||
```js
|
||||
// frontend/tests/production-data-boundary.test.mjs:33
|
||||
assert.match(app, /const profilePageItems = computed<CharacterProfile\[\]>\(\(\) => backendProfiles\.value\)/)
|
||||
assert.match(app, /const imageGenerationImages[\s\S]*localGenerationImages\.value\.filter\(isAuthenticGenerationImage\)/)
|
||||
```
|
||||
```js
|
||||
// frontend/tests/workflow-cross-review-wiring.test.mjs:19
|
||||
assert.equal((app.match(/<WorkflowGenerationReviewDialog\b/g) ?? []).length, 1)
|
||||
assert.match(app, /loadWorkflowRounds\(result\.round\.node_id, true\)/)
|
||||
assert.match(dialog, /model_routes: \[\.\.\.reviewModelRoutes\.value\]/)
|
||||
```
|
||||
唯一真正 import 被测模块的是 `frontend/tests/workflow-model-route.test.mjs`(导入 `workflow-model-route.ts` 与 `workflow-lock-state.ts` 两个纯函数模块)。`frontend/package.json:11-12` 也证实没有任何组件测试运行器——`test:contracts` 就是 `node --test tests/*.test.mjs`,依赖树里没有 vitest / @vue/test-utils / jsdom。
|
||||
- **影响**:① 假阴性——把 `computed<CharacterProfile[]>` 换成等价的 `computed(() => ...)` 会让测试红,但功能完全正常;把变量重命名、格式化工具重排一次空格,整批测试崩。② 假阳性——组件在运行时抛异常、props 契约破裂、事件不触发,这些测试全部照过。26 个用例 356 ms 跑完就是因为它们只是在做字符串匹配。③ 35638 行 Vue(36 个 `.vue` 文件)实际测试覆盖率为 0。
|
||||
- **修复建议**:
|
||||
1. 引入 `vitest` + `@vue/test-utils` + `jsdom`(放进 `devDependencies`),把 `workflow-cross-review-wiring` / `advanced-material-upload` / `production-data-boundary` 这三个"接线测试"改写成挂载组件、mock `endpoints`、断言实际发出的请求与渲染结果。
|
||||
2. 把纯逻辑(`isAuthenticGenerationImage`、候选池筛选、时间戳归一化)从 `App.vue` 抽到 `.ts` 模块,按 `workflow-model-route.test.mjs` 的模式做真单测——这是目前唯一正确的样板。
|
||||
3. `ui-theme-contract.test.mjs` 这类"CSS token 必须存在"的检查保留即可,它本来就是文本契约,但要从"测试"改名为 lint(如挪到 `scripts/lint-tokens.mjs` 并接进 `npm run lint`),避免和真测试混在一起虚增数字。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `release/` 20 个 zip(37 MB)与前端构建产物已入库,`.git` 膨胀到 51 MB、37% 的提交在改产物
|
||||
|
||||
- **位置**:`.gitignore`(缺 `release/`、`web/assets/`、`pages/imagestudio/assets/` 规则);`release/astrbot_plugin_imagestudio-1.0.0.zip` … `1.0.31.zip`
|
||||
- **问题**:量化结果:
|
||||
```
|
||||
git ls-files 总数 455
|
||||
├─ release/*.zip 20 个,37.02 MB(单个最大 4.23 MB)
|
||||
├─ web/* 19 个(18 个哈希命名构建产物 + index.html)
|
||||
└─ pages/imagestudio/* 19 个(同上)
|
||||
→ 二进制/构建产物占已跟踪文件 12.7%
|
||||
|
||||
.git 目录 51 MB
|
||||
提交总数 230
|
||||
触及 web/ 或 pages/ 的提交 86 (37.4%)
|
||||
历史上出现过的 web/pages 文件路径 439 ← 当前只剩 38 个
|
||||
→ 约 401 个哈希命名的死 blob 永久留在历史里
|
||||
```
|
||||
且当前工作树里 13 个旧产物已删、13 个新产物未跟踪(`git status` 里 `D pages/imagestudio/assets/index-Dp4kkpJ0.js` / `?? pages/imagestudio/assets/index-3MfZqRFA.js`),每次 `npm run build` 都会因为 Vite 的 content-hash 生成一批全新文件名,历史只增不减。
|
||||
|
||||
另外 `release/astrbot_plugin_imagestudio-1.0.0.zip` ~ `1.0.6.zip` 每个 4.2 MB,里面装的是**运行期数据**:
|
||||
```
|
||||
data/temp/provider_probe_B_image2_generation.json 1.76 MB (真实模型响应,含 b64 图片)
|
||||
data/temp/provider_probe_B_image2_generation.png 1.32 MB
|
||||
data/temp/s81_provider_runtime_b.png 0.76 MB
|
||||
data/db/imagestudio.db 0.29 MB (真实 SQLite 库)
|
||||
```
|
||||
这与 `DEVELOPMENT.md` 自己写的"测试可使用临时目录,且不能把真实运行数据加入发布包"直接冲突。
|
||||
- **影响**:① 每个 clone 强制拉 51 MB,其中 ~45 MB 是没人会用的历史产物;② 37% 的提交 diff 被机器生成的 minified JS 淹没,`git log -p`、`git bisect`、code review 全部失效;③ 早期 release zip 里的 `imagestudio.db` 与 provider probe 响应是真实数据,永久留在版本库历史中无法用 `git rm` 撤销。
|
||||
- **修复建议**:
|
||||
1. `.gitignore` 补丁:
|
||||
```gitignore
|
||||
# 发布产物:用 Git Release/附件分发,不入库
|
||||
release/
|
||||
|
||||
# 前端构建产物(哈希命名,每次 build 都变)
|
||||
web/assets/
|
||||
pages/imagestudio/assets/
|
||||
```
|
||||
注意 `web/index.html` 与 `pages/imagestudio/index.html` 需要保留(AstrBot 靠它发现插件页面),所以只忽略 `assets/` 子目录。若决定连 index.html 也不入库,则需要在安装文档里加"必须先 `npm run build`"的前置步骤。
|
||||
2. 停止跟踪但保留本地文件:
|
||||
```bash
|
||||
git rm -r --cached release web/assets pages/imagestudio/assets
|
||||
git commit -m "chore: stop tracking release archives and frontend build output"
|
||||
```
|
||||
3. 若要真正瘦身 `.git`,需要改写历史(会让所有 clone 失效,需团队同步):
|
||||
```bash
|
||||
# 需先安装 git-filter-repo
|
||||
git filter-repo --path release --path web/assets --path pages/imagestudio/assets --invert-paths
|
||||
```
|
||||
不改写历史时,至少跑一次 `git gc --aggressive --prune=now` 回收部分空间。
|
||||
4. `DEVELOPMENT.md` 里"生产构建必须同时提交 `pages/imagestudio/` 的最新插件页面产物"这句要一并改掉,否则规则和 `.gitignore` 打架。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `_conf_schema.json` 缺失 prompt_governance 与成人内容白名单,AstrBot 面板无法配置内容安全开关
|
||||
|
||||
- **位置**:`_conf_schema.json`(共 64 个键)对照 `config.yaml:96-140` 与 `main.py:110-175` 的映射表
|
||||
- **问题**:`main.py` 的 `_CONFIG_KEY_MAP` 逐条把 `config.yaml` 路径映射到 schema 键,schema 里没有的键在 AstrBot 面板中就不存在,也就无法被管理员配置或持久化。实测缺口:
|
||||
|
||||
| `config.yaml` 配置项 | schema 键 | 状态 |
|
||||
|---|---|---|
|
||||
| `prompt_governance.translation.*`(6 项) | — | **全缺** |
|
||||
| `prompt_governance.moderation.llm_review_enabled` / `failure_policy` | — | **全缺** |
|
||||
| `prompt_governance.routing.safe_route` / `nsfw_route` / `adult_auto_route_enabled` / `entrypoints.*` | — | **全缺** |
|
||||
| `prompt_governance.image_moderation.*` | — | **全缺** |
|
||||
| `prompt_governance.retention.*`(4 项,含 `redact_sensitive_logs`) | — | **全缺** |
|
||||
| `chat_access.adult_group_allowlist` | — | **缺**(普通 `group_allowlist` 有) |
|
||||
| `chat_access.adult_user_allowlist` | — | **缺**(普通 `user_allowlist` 有) |
|
||||
| `security.integration_token_set` / `allowed_integration_plugins` | — | **全缺** |
|
||||
| `features.quick_profile` / `workspace` / `material_library` / `wardrobe` / `api_discovery` | — | 缺(只有 `private_companion_integration`) |
|
||||
| `advanced_materials.recognition_concurrency` | — | 缺 |
|
||||
| `storage.images_path` / `thumbnails_path` / `materials_path` / `styles_path` / `archives_path` / `temp_path` | — | 缺(只有 `advanced_materials_path`) |
|
||||
| `recognition_prompts.*` | — | 全缺 |
|
||||
|
||||
而这些键在业务代码里是**真的被读的**:
|
||||
```python
|
||||
# backend/services/chat_workflow_service.py:1175
|
||||
adult_users = _id_set(access.get("adult_user_allowlist"))
|
||||
adult_groups = _id_set(access.get("adult_group_allowlist"))
|
||||
# backend/services/advanced_material_service.py:1309
|
||||
adult_users = {str(value).strip() for value in access.get("adult_user_allowlist", []) if str(value).strip()}
|
||||
```
|
||||
`backend/services/settings_service.py:184-185` 甚至在插件自己的设置页里渲染了这两个字段,说明产品意图上它们是可配置的——只是 AstrBot 侧的通道断了。
|
||||
- **影响**:在 AstrBot 真实部署下,管理员只能靠手改插件目录里的 `config.yaml` 来打开 NSFW 分流、内容审核、成人白名单和日志脱敏;而插件更新会覆盖 `config.yaml`,配置静默回退到默认值——`adult_auto_route_enabled: false`、`llm_review_enabled: false`、`adult_*_allowlist: []`。也就是说内容安全开关在生产环境实际上不可用、且升级即丢失。
|
||||
- **修复建议**:
|
||||
1. 在 `_conf_schema.json` 补齐这些键(至少 `prompt_governance.moderation.*`、`prompt_governance.routing.*`、`chat_access.adult_*_allowlist`、`prompt_governance.retention.redact_sensitive_logs`),并在 `main.py:_CONFIG_KEY_MAP` 加对应映射。
|
||||
2. 加一条防漂移测试,让 schema 与映射表永远同步:
|
||||
```python
|
||||
def test_config_key_map_and_schema_stay_in_sync():
|
||||
schema = json.loads(Path("_conf_schema.json").read_text(encoding="utf-8"))
|
||||
mapped = set(main._CONFIG_KEY_MAP.values())
|
||||
assert mapped - set(schema) == set(), "映射到不存在的 schema 键"
|
||||
assert set(schema) - mapped == set(), "schema 键未接入 config.yaml"
|
||||
```
|
||||
这条测试当前应当是**通过**的(两边都是 64 个),所以还需要第二条:断言 `config.yaml` 中所有安全相关叶子路径都出现在 `_CONFIG_KEY_MAP` 的 key 里。
|
||||
3. `postgresql_password` 在 schema 里是 `"type": "string"`,AstrBot 面板会明文回显。若 AstrBot 支持 `"type": "password"` 或 `"secret": true`,应改用;否则至少在 `description` 里引导用户填 `dsn` 并把密码放环境变量。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `config.yaml` / `metadata.yaml` / `CHANGELOG.md` 存在编码损坏(私有区乱码),且 `config.yaml` 是已入库文件
|
||||
|
||||
- **位置**:`config.yaml:15`(以及全文 54 处)、`metadata.yaml:5`、`CHANGELOG.md`(649 处)
|
||||
- **问题**:三个文件本身是合法 UTF-8,但**内容**是中文被 GBK 误解码后再存成 UTF-8 的产物,包含 Unicode 私有使用区字符(`U+E000`–`U+F8FF`),已不可逆还原:
|
||||
```
|
||||
$ python - <<'PY'
|
||||
print(repr(open('config.yaml',encoding='utf-8').read().splitlines()[14]))
|
||||
PY
|
||||
' # default_model 鏄?ImageStudio 璺敱鍚嶏紱route_name 鐣欑┖鏃跺鐢ㄥ畠銆?'
|
||||
```
|
||||
原文应为「default_model 是 ImageStudio 路由名;route_name 留空时也用它。」
|
||||
|
||||
全仓库扫描(跳过 `web/` `pages/` `release/` `frontend/`):
|
||||
```
|
||||
config.yaml 私有区字符 54 个
|
||||
CHANGELOG.md 私有区字符 649 个
|
||||
metadata.yaml 私有区字符 1 个 ← short_desc
|
||||
受影响的已跟踪文件:3
|
||||
```
|
||||
`metadata.yaml:5` 的 `short_desc` 是 AstrBot 插件市场直接展示的字段:
|
||||
```yaml
|
||||
short_desc: AstrBot 鍐呯殑瑙掕壊璧勪骇銆佸伐浣滄祦涓庡浘鐗囩敓鎴愮鐞嗗伐浣滃彴銆?
|
||||
```
|
||||
值得注意的是同一个 `config.yaml` 里新写的注释是正常的(`config.yaml:57` 「留空时沿用进阶素材识别路由」可读),说明损坏是某次工具链(很可能是 Windows 上的 PowerShell 重定向或 `Set-Content` 默认 ANSI 编码)一次性造成的,之后新增行没受影响。
|
||||
- **影响**:① AstrBot 插件市场/管理面板会展示乱码描述,直接影响用户第一印象;② `config.yaml` 里 54 处注释是解释各字段语义的唯一文档(`vision` 段那 3 行注释解释了"Vision 模型必须单独填写,不能假定生图模型具备视觉理解能力"这种关键约束),现在完全不可读,运维只能靠猜;③ 后续任何人用编辑器打开这些文件再保存,损坏会继续扩散。
|
||||
- **修复建议**:
|
||||
1. 手工重写这三个文件的中文内容(`config.yaml` 54 处、`metadata.yaml` 1 处优先;`CHANGELOG.md` 649 处可从 git 历史或 Release notes 恢复)。
|
||||
2. 在 `DEVELOPMENT.md` 的 Windows 章节明确:写文件一律 `Out-File -Encoding utf8` / `Set-Content -Encoding utf8`,禁止裸 `>` 重定向。
|
||||
3. 加一条 CI/测试守卫防止复发:
|
||||
```python
|
||||
def test_no_mojibake_in_tracked_text_files():
|
||||
for name in ("config.yaml", "metadata.yaml", "_conf_schema.json", "README.md"):
|
||||
text = Path(name).read_text(encoding="utf-8")
|
||||
bad = [c for c in text if "" <= c <= ""]
|
||||
assert not bad, f"{name} 含 {len(bad)} 个私有区字符,疑似编码损坏"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 工作树 8228 个未跟踪垃圾文件 / 2.57 GB,其中 `.tmp` 单目录 2.1 GB
|
||||
|
||||
- **位置**:`.tmp/`、根目录 20 个 `.tmp_pytest_*/`
|
||||
- **问题**:`.gitignore` 里 `.tmp/` 与 `.tmp_pytest*/` 规则**是生效的**(`git ls-files | grep '^\.tmp'` 返回 0),所以不是入库问题,而是纯粹的磁盘/工作流污染。量化:
|
||||
|
||||
| 目录 | 文件数 | 体积 |
|
||||
|---|---:|---:|
|
||||
| `.tmp/` | 6303 | 2129.08 MB |
|
||||
| `.tmp_pytest_full_1022` | 231 | 68.03 MB |
|
||||
| `.tmp_pytest_full_1030` | 232 | 67.94 MB |
|
||||
| `.tmp_pytest_full_1031` | 232 | 67.93 MB |
|
||||
| `.tmp_pytest_full_1022_final` | 231 | 67.92 MB |
|
||||
| `.tmp_pytest_full_1030_x` | 232 | 67.92 MB |
|
||||
| `.tmp_pytest_full` | 223 | 55.76 MB |
|
||||
| `.tmp_pytest_route_refs` | 103 | 18.40 MB |
|
||||
| `.tmp_pytest_auto_round` | 124 | 17.36 MB |
|
||||
| `.tmp_pytest_style_set` / `_2` | 52 / 52 | 16.09 / 16.09 MB |
|
||||
| 其余 10 个 `.tmp_pytest_*` | 89 | 46.81 MB |
|
||||
| **`.tmp_pytest_*` 小计** | **1925** | **507.25 MB** |
|
||||
| **合计** | **8228** | **2636 MB** |
|
||||
|
||||
`.tmp/` 内部有 **8 个整仓库快照**(`deploy-1.0.35` 2180 文件 496 MB、`deploy-clean-1.0.35/36/37` 各 390 文件 8.5 MB、4 个 `deploy-stage-1.0.38~41`)、**22 个部署归档**、**~60 个一次性 patch/fix 脚本**(`fix_age_failures.py`、`fix_soft_asserts.py`、`patch_soft_anatomy_tests.py`、`patch_tests_age2.py` …)、40+ 个 pytest 输出目录,以及若干真实生成图片(`nas_eval_20260720/` 13 个 jpg/png 9.67 MB、`latest_style_audit/` 含一个真实 `imagestudio.db`)。
|
||||
|
||||
`deploy-1.0.35` 之所以是 496 MB,是因为它把根目录的 `.tmp_pytest_*` 一起复制进去了:
|
||||
```
|
||||
$ Get-ChildItem .tmp/deploy-1.0.35 | Select -First 8
|
||||
.tmp_pytest_advanced .tmp_pytest_advanced2 .tmp_pytest_config
|
||||
.tmp_pytest_full .tmp_pytest_full_1022 .tmp_pytest_full_1022_final
|
||||
.tmp_pytest_full_1030 .tmp_pytest_full_1030_x
|
||||
```
|
||||
这个错误直接导致 `nas-deploy-worktree-20260724.tar` 达到 **546 MB**(正常插件包约 8 MB,膨胀 68 倍),其二级目录分布:
|
||||
```
|
||||
601 .tmp_pytest_full_1031 601 .tmp_pytest_full_1030_x 601 .tmp_pytest_full_1030
|
||||
599 .tmp_pytest_full_1022_final 599 .tmp_pytest_full_1022 583 .tmp_pytest_full
|
||||
365 backend 305 .tmp_pytest_route_refs 176 tests
|
||||
```
|
||||
即 3000+ 个 pytest 临时文件被 scp 到了 NAS。
|
||||
- **影响**:① 2.6 GB 拖慢 IDE 索引、`ripgrep`、防病毒扫描与备份;② 更实际的伤害是打包脚本"整目录复制"时会把它们卷进部署包(546 MB 的 tar 已经发生),部署耗时与 NAS 空间双重浪费;③ `.tmp/` 里的 60 多个 `fix_*.py` / `patch_*.py` 脚本表明有大量一次性修补动作发生在版本控制之外,这些修改无法追溯。
|
||||
- **修复建议**:
|
||||
1. 清理(先确认 `git status` 干净):
|
||||
```powershell
|
||||
# 保守:先看要删什么
|
||||
Get-ChildItem . -Directory -Force -Filter '.tmp_pytest*' | Select Name, @{n='MB';e={[math]::Round((Get-ChildItem $_ -Recurse -File -Force | Measure-Object Length -Sum).Sum/1MB,2)}}
|
||||
|
||||
# 执行
|
||||
Get-ChildItem . -Directory -Force -Filter '.tmp_pytest*' | Remove-Item -Recurse -Force
|
||||
Remove-Item -Recurse -Force .tmp
|
||||
Remove-Item -Recurse -Force .pytest_cache
|
||||
Get-ChildItem . -Directory -Recurse -Force -Filter '__pycache__' | Where-Object { $_.FullName -notmatch 'node_modules' } | Remove-Item -Recurse -Force
|
||||
```
|
||||
2. 统一 pytest 临时目录出口,避免再散落到根:在 `pyproject.toml` 里固定 `addopts = "--basetemp=.pytest_tmp"`,`.gitignore` 里 `.pytest_tmp*/` 规则已存在。
|
||||
3. 打包脚本改用 `git archive`(见 P0 条),从根本上不再依赖"复制工作树"。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 21 个测试文件各自重复内联同一套 SQLite Database 夹具,无任何共享 fixture
|
||||
|
||||
- **位置**:`tests/test_resource_access_service.py:15-77`(典型)以及其余 20 个文件的同构代码
|
||||
- **问题**:`grep -l "DatabaseSettings(" tests/*.py` 命中 21 个文件,每一个都手写同一段初始化:
|
||||
```python
|
||||
# tests/test_resource_access_service.py:15
|
||||
def _fixture(tmp_path):
|
||||
database = Database(
|
||||
DatabaseSettings(
|
||||
backend="sqlite",
|
||||
sqlite=SqliteSettings(path=str(tmp_path / "resource-access.sqlite3")),
|
||||
)
|
||||
)
|
||||
database.initialize()
|
||||
profiles = ProfileRepository(database)
|
||||
workflows = WorkflowRepository(database)
|
||||
images = ImageRepository(database)
|
||||
jobs = JobRepository(database)
|
||||
profiles.create({...})
|
||||
workflows.create_workflow({...})
|
||||
workflows.create_node({...})
|
||||
...
|
||||
```
|
||||
同样地,`_StaticConfigService`(把 7 个 storage 路径指到 tmp 目录的桩类)在 `tests/test_advanced_material_workflow.py` 与 `tests/test_advanced_style_set_workflow.py:61-75` 里各写了一份完全相同的实现;`RequestContext(...)` 构造在 3 个文件里各自重复。仓库没有 `conftest.py`,所以没有任何共享位置。
|
||||
- **影响**:新增一个 repository 或改一次 `DatabaseSettings` 签名要动 21 个文件;各文件的种子数据略有差异,导致"同一个 bug 在 A 测试里能复现、B 里不能"这类难查的不一致;也是 11559 行测试代码里相当一部分体积的来源。
|
||||
- **修复建议**:新建 `tests/conftest.py`(顺带解决 P1 的 `sys.path` 问题):
|
||||
```python
|
||||
import sys, pathlib, pytest
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
|
||||
|
||||
from core.config_service import ImageStudioConfig, StorageConfig
|
||||
from core.identity import RequestContext
|
||||
from database.db_helper import Database, DatabaseSettings, SqliteSettings
|
||||
|
||||
@pytest.fixture
|
||||
def sqlite_db(tmp_path):
|
||||
db = Database(DatabaseSettings(backend="sqlite",
|
||||
sqlite=SqliteSettings(path=str(tmp_path / "test.sqlite3"))))
|
||||
db.initialize()
|
||||
yield db
|
||||
|
||||
@pytest.fixture
|
||||
def storage_config(tmp_path):
|
||||
return ImageStudioConfig(storage=StorageConfig(**{
|
||||
f"{k}_path": str(tmp_path / k) for k in
|
||||
("images", "thumbnails", "materials", "advanced_materials", "styles", "archives", "temp")
|
||||
}))
|
||||
|
||||
@pytest.fixture
|
||||
def ctx():
|
||||
def _make(user_id="user-a", *perms):
|
||||
return RequestContext(username=user_id, user_id=user_id, platform="qq",
|
||||
is_authenticated=True, permissions=frozenset(perms))
|
||||
return _make
|
||||
```
|
||||
然后分批把 21 个文件的 `_fixture` 改成注入。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `tests/test_material_vision_input.py` 无条件 import Pillow,而 Pillow 被明确定义为可选依赖
|
||||
|
||||
- **位置**:`tests/test_material_vision_input.py:6`;`requirements.txt:1-2`
|
||||
- **问题**:`requirements.txt` 全文只有注释、**零条实际依赖**(`grep -vE "^\s*#|^\s*$" requirements.txt | wc -l` = 0),且第一段就写明:
|
||||
```
|
||||
# 帮助/状态图片卡片会在运行环境已有 Pillow 时启用;未安装时自动回退文字。
|
||||
# 为保持插件默认零依赖,不在这里强制安装 Pillow。
|
||||
```
|
||||
业务代码确实遵守了这个约定(`engines/image_provider.py:231-235`、`backend/services/api_discovery_service.py:320-324` 都是 `try: import httpx / except ImportError:` 的软导入)。但测试没有:
|
||||
```python
|
||||
# tests/test_material_vision_input.py:6
|
||||
from PIL import Image
|
||||
```
|
||||
模块级硬导入,没有 `pytest.importorskip("PIL")` 也没有 `@pytest.mark.skipif`。仓库里也没有 `requirements-dev.txt` 声明测试期依赖。
|
||||
- **影响**:在任何按照 `requirements.txt`(零依赖)搭起来的干净环境里,`python -m pytest tests/` 会在收集阶段报 `ModuleNotFoundError: No module named 'PIL'`,**整个 263 个用例的套件一起挂掉**,而不是跳过这 2 个。这跟 P1 的 `pytest` 崩溃叠加,等于测试套件在标准环境下有两处一碰就碎。
|
||||
- **修复建议**:
|
||||
1. 改成 `Image = pytest.importorskip("PIL").Image`(或文件顶部 `pytest.importorskip("PIL")`),让缺 Pillow 时只跳过这 2 个用例。
|
||||
2. 新建 `requirements-dev.txt` 显式声明测试期依赖并钉版本:
|
||||
```
|
||||
pytest>=8.0,<9
|
||||
Pillow>=10.0,<12
|
||||
```
|
||||
`requirements.txt` 保持零依赖不变(这个设计本身是对的)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 前端把 vite/typescript/vue-tsc 放进 `dependencies`,`devDependencies` 为空
|
||||
|
||||
- **位置**:`frontend/package.json:15-23`
|
||||
- **问题**:
|
||||
```json
|
||||
"dependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0",
|
||||
"pinia": "^2.3.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
"vue": "^3.5.0",
|
||||
"vue-router": "^4.5.0",
|
||||
"vue-tsc": "^2.2.0"
|
||||
},
|
||||
"devDependencies": {}
|
||||
```
|
||||
`vite`、`typescript`、`vue-tsc`、`@vitejs/plugin-vue` 是纯构建期工具,运行期打包产物里一行都不会出现。
|
||||
- **影响**:`npm ci --omit=dev` 无法瘦身;依赖审计(`npm audit`)会把构建工具的漏洞算作生产依赖漏洞,噪音掩盖真实风险。影响有限(`private: true` 且不发布 npm 包),但会误导任何自动化供应链扫描。
|
||||
- **修复建议**:
|
||||
```json
|
||||
"dependencies": { "pinia": "^2.3.0", "vue": "^3.5.0", "vue-router": "^4.5.0" },
|
||||
"devDependencies": {
|
||||
"@vitejs/plugin-vue": "^5.2.0", "typescript": "^5.7.0",
|
||||
"vite": "^6.0.0", "vue-tsc": "^2.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 无 CI,且 `DEVELOPMENT.md` 的"验证"流程根本不跑测试
|
||||
|
||||
- **位置**:`DEVELOPMENT.md`「## 验证」章节;仓库无 `.github/`、无 `Makefile`、无任何 workflow 文件
|
||||
- **问题**:文档给出的唯一验证命令是:
|
||||
```powershell
|
||||
python -m compileall adapters backend core database engines scripts tests main.py
|
||||
cd frontend
|
||||
npm.cmd run typecheck
|
||||
npm.cmd run build:plugin
|
||||
npm.cmd run build:web
|
||||
```
|
||||
`compileall` 只做语法编译,**不执行任何一个测试**;263 个后端用例和 26 个前端用例都不在流程里。而且 `scripts` 目录根本不存在:
|
||||
```
|
||||
$ python -m compileall -q adapters backend core database engines scripts tests main.py
|
||||
Can't list 'scripts'
|
||||
exit=0 ← 目录缺失,但退出码仍是 0,静默通过
|
||||
```
|
||||
`git ls-files | grep -iE '\.github|workflow'` 无任何命中,确认零 CI。
|
||||
- **影响**:测试写了 11559 行却不在任何门禁上,全靠开发者自觉手跑;`compileall` 对缺失目录返回 0 意味着这个"验证"连自身的完整性都保证不了。230 次提交里没有一次被自动检查拦截过。
|
||||
- **修复建议**:
|
||||
1. 修正 `DEVELOPMENT.md`,把验证改成(先落实 P1 的 pytest 配置):
|
||||
```powershell
|
||||
python -m pytest -q
|
||||
cd frontend
|
||||
npm.cmd run typecheck
|
||||
npm.cmd run test:contracts
|
||||
npm.cmd run build:plugin
|
||||
```
|
||||
并删掉不存在的 `scripts`。
|
||||
2. 加最小 CI(`.github/workflows/ci.yml` 或对应 Forgejo Actions),矩阵只跑 `python -m pytest -q` + `npm run typecheck` + `npm run test:contracts` 即可,20 秒内出结果。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 4 份根目录设计文档已随版本严重过期,且 `tests/test_prompt_expansion_stage_guard.py` 未入库
|
||||
|
||||
- **位置**:`imagestudio_api_contract_v3_ui_adjusted.md`、`imagestudio_codex_hermes_dev_flow_v3.md`、`imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md`、`imagestudio_ui_navigation_queue_s130.md`;`tests/test_prompt_expansion_stage_guard.py`
|
||||
- **问题**:4 份文档写于 2026-07-04 ~ 07-06(`imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md` 31 KB),文件名带 `v3`,而 `metadata.yaml` 当前版本已是 `1.0.72`,中间隔了 70 个版本、约 230 次提交。它们与 `docs/` 下 20 多份带日期的审计/队列文档并存,但没有任何"已归档/已作废"标记。
|
||||
|
||||
另外 `git status --porcelain` 显示 `?? tests/test_prompt_expansion_stage_guard.py` —— 一个 60 行、2 个用例的测试文件写完了但**从未提交**,同时 `backend/services/prompt_expansion_service.py` 处于 `M` 修改状态。
|
||||
- **影响**:新人从根目录看到 4 份体量最大的 `.md` 会误以为它们是当前契约(`imagestudio_api_contract_v3_ui_adjusted.md` 描述的 API 与现在 166 个 endpoint 的实际形态大概率已经对不上)。未入库的测试文件意味着这次改动的回归保护随时可能被 `git clean` 抹掉。
|
||||
- **修复建议**:
|
||||
1. `git mv imagestudio_*.md docs/archive/`,并在每份开头加一行 `> 已归档:本文档对应 v3 设计阶段(2026-07),当前实现以 docs/ 下最新日期文档与 backend/route_registry.py 为准。`
|
||||
2. 立刻提交 `tests/test_prompt_expansion_stage_guard.py`(与它守护的 `backend/services/prompt_expansion_service.py` 改动同一个 commit)。
|
||||
805
审计/findings/C4-横切关注点.md
普通文件
805
审计/findings/C4-横切关注点.md
普通文件
|
|
@ -0,0 +1,805 @@
|
|||
# C4 - 横切关注点(错误处理 / 日志 / 可观测性 / 性能 / 一致性)
|
||||
|
||||
> 审计范围(实际 Read / Grep 过的文件):
|
||||
> `main.py`、`backend/dto/common.py`、`backend/routes/common.py`、`backend/route_registry.py`、
|
||||
> `backend/services/worker_service.py`、`backend/services/queue_service.py`、`backend/services/log_service.py`、
|
||||
> `backend/services/cost_service.py`、`backend/services/event_stream_service.py`、`backend/services/dashboard_service.py`、
|
||||
> `backend/services/generation_service.py`、`backend/services/advanced_material_service.py`、
|
||||
> `backend/services/advanced_style_set_service.py`、`backend/services/material_service.py`、
|
||||
> `backend/services/api_discovery_service.py`、`backend/services/settings_service.py`、
|
||||
> `backend/services/chat_session_service.py`、`backend/services/chat_workflow_service.py`、
|
||||
> `backend/services/integration_token_service.py`、`backend/services/workflow_round_worker_runtime.py`、
|
||||
> `backend/services/advanced_material_worker_runtime.py`、
|
||||
> `core/generation_errors.py`、`core/identity.py`、`core/audit_service.py`、`core/event_bus.py`、`core/remote_fetch.py`、
|
||||
> `core/interop.py`、`core/astrbot_provider_bridge.py`、
|
||||
> `database/db_helper.py`、`database/repositories/job_repository.py`、
|
||||
> `database/repositories/advanced_material_repository.py`、`database/migrations/*.sql`、
|
||||
> `adapters/astrbot_adapter.py`、`adapters/webui_adapter.py`、
|
||||
> `engines/image_provider.py`、
|
||||
> `frontend/shared/api/client.ts`、`frontend/standalone-web/src/**`(grep 全量)
|
||||
>
|
||||
> 已按要求完全跳过 `.tmp*/`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`。
|
||||
|
||||
## 摘要
|
||||
|
||||
本仓库在**局部**做得相当克制:时间处理完全统一为 aware UTC(`utcnow()` 出现 0 次、裸 `datetime.now()` 出现 0 次)、ID 生成统一用 `前缀_uuid4().hex`、没有 `except:` 裸捕获、没有同步 `requests`/`time.sleep`/`subprocess` 混进 async、文件句柄都走 `Path.read_bytes` / `with` 上下文管理器。真正的问题集中在**"看不见"和"扛不住"**两条线上。
|
||||
|
||||
最致命的是可观测性接近于零:178 个 Python 源文件中只有 `worker_service.py` 一个文件配置了 logger(全仓 6 处 `logger.` 调用);同时 200+ 个 API 端点全部经由 `handle_request` 吞掉非 `ApiError` 异常,只回一个 `{"exception": "KeyError"}`,既不打日志也不留栈——一旦线上出内部错误,没有任何手段定位。后端生成的 `request_id` 又在前端 `unwrapApiResponse` 中被剥掉,聊天侧展示的 `chatreq_xxx` 更是从未写入任何存储,三条关联链路全断。
|
||||
|
||||
其次是 `ApiError` 被定义成继承 `Exception` 的 `@dataclass`,导致 `str(exc)` 返回 `args` 元组的 repr(含完整 `details` 字典);`main.py` 有 40 处直接把 `{exc}` 拼进聊天回复,用户看到的是 Python 元组而非中文错误信息。
|
||||
|
||||
性能上,SQLite 未开启 WAL 却跑 13 个并发 worker 线程,且每次 DB 操作都新建连接(全仓 151 处 `.connect()`),空转时约 43 次 connect/秒;`cost_service` 对 `generation_images` 做无 LIMIT 全表扫描后再在 Python 里过滤日期;`advanced_material_service` 存在按 attempt 循环查子表的 N+1。
|
||||
|
||||
## 发现
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] 全后端 178 个源文件只有 1 个配置了日志,生产环境完全不可观测
|
||||
|
||||
- **位置**:`backend/services/worker_service.py:5,17`(全仓唯一 logger)
|
||||
- **问题**:对整个真实源码树做统计,`import logging` / `getLogger` 只出现在 `worker_service.py` 一处,全仓 `logger.` 调用共 **6 次**,全部是 `logger.exception`,全部在这一个文件里。`main.py`(121 KB)、`backend/routes/*`(32 个文件)、`backend/services/*`(60+ 个文件)、`database/`、`engines/`、`core/`、`adapters/` **零日志**。
|
||||
- **代码**:
|
||||
|
||||
```
|
||||
$ grep -rn "import logging|getLogger|logger\." --include="*.py" main.py backend core database engines adapters
|
||||
backend/services/worker_service.py:5:import logging
|
||||
backend/services/worker_service.py:17:logger = logging.getLogger(__name__)
|
||||
backend/services/worker_service.py:198: logger.exception(
|
||||
backend/services/worker_service.py:235: logger.exception(
|
||||
backend/services/worker_service.py:253: logger.exception(
|
||||
backend/services/worker_service.py:290: logger.exception(
|
||||
backend/services/worker_service.py:337: logger.exception(
|
||||
backend/services/worker_service.py:352: logger.exception(
|
||||
```
|
||||
|
||||
作为对照,全仓有 **180 处 `except Exception`**,其中 **33 处**直接 `pass` / `return None` / `continue`。
|
||||
- **影响**:只有队列 worker 崩溃这一条路径会在 AstrBot 日志里留痕。生成失败、素材识别失败、配置写入失败、媒体签名失败、Provider 探测失败全部无声。用户报"点了没反应"时,运维手上除了 `logs/errors` 里那条 `error_message` 文本外没有任何上下文(无栈、无入参、无 provider、无 request_id)。这也是下面 P1-2、P2-1、P2-2 三条问题无法自愈的根因。
|
||||
- **修复建议**:
|
||||
1. 新建 `core/logging.py`,导出 `get_logger(name)`,内部优先桥接 AstrBot 的 `astrbot.api.logger`,回退到 `logging.getLogger(f"imagestudio.{name}")`;
|
||||
2. 在 `backend/routes/common.py:handle_request` 的 `except` 中强制 `logger.exception(...)`(见下条);
|
||||
3. 至少给 `generation_service`、`advanced_material_service`、`advanced_style_set_service`、`model_provider_runtime`、`astrbot_provider_bridge` 这 5 个含外部 IO 的模块补上 `logger.warning/exception`,把当前 33 处静默 `pass` 全部改成 `logger.debug/warning` + 原有兜底逻辑。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `handle_request` 吞掉全部非 ApiError 异常且不记日志,200+ 端点内部错误彻底静默
|
||||
|
||||
- **位置**:`backend/routes/common.py:12-16`、`backend/dto/common.py:75-83`
|
||||
- **问题**:全部 32 个 route 文件、166 条路由(`backend/route_registry.py:55-342` 的 `ROUTES`)都通过 `handle_request` 包装 handler。它 `except Exception` 后交给 `response_from_exception`,后者对任何非 `ApiError` 异常一律返回固定文案 + **仅异常类名**,栈、消息、上下文全部丢弃,且**没有任何日志输出**。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/routes/common.py:12-16
|
||||
def handle_request(ctx: RequestContext, callback: Callable[[], Any]) -> dict[str, Any]:
|
||||
try:
|
||||
return success_response(callback(), request_id=ctx.request_id)
|
||||
except Exception as exc:
|
||||
return response_from_exception(exc, request_id=ctx.request_id)
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/dto/common.py:75-83
|
||||
def response_from_exception(exc: Exception, request_id: str | None = None) -> dict[str, Any]:
|
||||
if isinstance(exc, ApiError):
|
||||
return exc.to_response(request_id=request_id)
|
||||
return error_response(
|
||||
error_code=ErrorCode.UNKNOWN_ERROR,
|
||||
message="服务器内部错误",
|
||||
details={"exception": exc.__class__.__name__}, # 只有类名
|
||||
request_id=request_id,
|
||||
)
|
||||
```
|
||||
|
||||
各 route 文件的 `handle_request` 使用次数(合计 200+ 处):`advanced_material_routes.py:20`、`material_routes.py:17`、`settings_routes.py:12`、`job_routes.py:11`、`image_routes.py:10`、`node_routes.py:10`……
|
||||
- **影响**:任何 `KeyError` / `TypeError` / `sqlite3.OperationalError` / `json.JSONDecodeError` 都变成前端一句"服务器内部错误",服务端没有任何记录。配合 P1-1(全仓无日志),这类 bug 在生产中**不可能被诊断**,只能靠复现。`log_service.py` 提供的 `logs/errors` 端点只覆盖 `generation_tasks` 和 `integration_logs` 两张表,完全不含 API 层错误。
|
||||
- **修复建议**:
|
||||
|
||||
```python
|
||||
# backend/routes/common.py
|
||||
logger = get_logger(__name__)
|
||||
|
||||
def handle_request(ctx: RequestContext, callback: Callable[[], Any]) -> dict[str, Any]:
|
||||
try:
|
||||
return success_response(callback(), request_id=ctx.request_id)
|
||||
except ApiError as exc:
|
||||
logger.info("api business error request_id=%s code=%s", ctx.request_id, exc.error_code)
|
||||
return exc.to_response(request_id=ctx.request_id)
|
||||
except Exception:
|
||||
logger.exception("api internal error request_id=%s actor=%s", ctx.request_id, ctx.actor_id)
|
||||
return response_from_exception(exc, request_id=ctx.request_id)
|
||||
```
|
||||
|
||||
同时在 `response_from_exception` 的 `details` 中补 `{"request_id": request_id}`,让前端展示的 ID 可以直接反查日志。
|
||||
|
||||
---
|
||||
|
||||
### [P1-严重] `ApiError` 是继承 Exception 的 dataclass,`str(exc)` 泄漏完整 details 元组;main.py 有 40 处直接回显给聊天用户
|
||||
|
||||
- **位置**:`backend/dto/common.py:29-33`(定义)、`main.py:515,544,574,...,1591,1618,1646`(共 40 处 `{exc}`)
|
||||
- **问题**:`ApiError` 用 `@dataclass(frozen=True)` 继承 `Exception`。`Exception.__new__` 会把构造时的位置参数塞进 `self.args`,而 `Exception.__str__` 直接返回 `args` 的 repr。全仓 **169 处** `ApiError(ErrorCode.X, "消息", {...})` 全部用位置参数构造,因此 `str(exc)` 得到的是 **`(<ErrorCode.X: 'X'>, '消息', {details 全量})` 这个元组的 repr**,而不是 `message`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/dto/common.py:29-33
|
||||
@dataclass(frozen=True)
|
||||
class ApiError(Exception):
|
||||
error_code: ErrorCode
|
||||
message: str
|
||||
details: dict[str, Any] | None = None
|
||||
```
|
||||
|
||||
实测(本机 Python 运行验证):
|
||||
|
||||
```
|
||||
str(exc) => "(<ErrorCode.VALIDATION_FAILED: 'VALIDATION_FAILED'>, '内容审核未通过,未创建生成任务', {'a': 1})"
|
||||
```
|
||||
|
||||
而 `main.py` 里 40 处这样用:
|
||||
|
||||
```python
|
||||
# main.py:1591
|
||||
await self._send_proactive(context.message_origin, f"❌ 单图生成失败\n请求:{request_id}\n错误:{exc}", [])
|
||||
# main.py:669
|
||||
yield event.plain_result(f"❌ 节点生成失败:{exc}")
|
||||
```
|
||||
|
||||
同一仓库的 `worker_service.py:514-534` `_safe_error_message()` 已经专门为 `ApiError` 做了正确的格式化(提取 `message` + `[code]` + 白名单 hint),说明作者知道这个坑,但聊天路径没有复用。
|
||||
- **影响**:
|
||||
1. **可用性**:QQ/微信用户收到的是 `❌ 节点生成失败:(<ErrorCode.GENERATION_FAILED: 'GENERATION_FAILED'>, '...', {...})`,中文提示被 Python 元组语法淹没。
|
||||
2. **信息泄漏**:`details` 里包含 `provider_id`、`model_id`、`route_name`、`body_preview`(`engines/image_provider.py:253,289,324` 会塞入上游响应体前 500 字节)、内部 `field` 名等,这些本来只该出现在管理端,现在直接推送到群聊。`core/generation_errors.py:_safe_details` 的脱敏逻辑在这条路径上完全没有生效。
|
||||
- **修复建议**:
|
||||
1. 给 `ApiError` 加显式 `__str__`:
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class ApiError(Exception):
|
||||
...
|
||||
def __str__(self) -> str:
|
||||
return f"{self.message} [{self.error_code.value}]"
|
||||
```
|
||||
|
||||
2. 把 `main.py` 的 40 处 `{exc}` 统一改为调用一个共享的 `user_facing_error(exc)`(可直接复用 `worker_service._safe_error_message`,把它提到 `backend/dto/common.py` 或 `core/generation_errors.py`),确保聊天侧永远只看到 message,不看到 details。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] SQLite 未开启 WAL,却跑 13 个并发写线程,全靠 30 秒 busy_timeout 硬扛
|
||||
|
||||
- **位置**:`database/db_helper.py:159-171`
|
||||
- **问题**:默认后端是 SQLite(`DatabaseSettings.selected_backend` 在未配置 PG 时返回 `"sqlite"`)。`connect()` 设了 `foreign_keys` 和 `busy_timeout`,但**没有设 `journal_mode=WAL`**。全仓 grep `PRAGMA` 只有这两行 + 一处 `PRAGMA table_info`。同时系统默认启动 5 个 round worker(`workflow_round_worker_runtime.py:25`)+ 8 个 advanced material worker(`advanced_material_worker_runtime.py:22`),共 13 个后台线程持续读写同一个 db 文件。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# database/db_helper.py:159-171
|
||||
def connect(self):
|
||||
if self.backend == "sqlite":
|
||||
db_path = self._resolve_sqlite_path()
|
||||
db_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
# Parallel image tasks briefly overlap while recording queue,
|
||||
# node, image, and audit rows. Give SQLite enough time to hand the
|
||||
# writer lock to the next task instead of failing immediately.
|
||||
conn = sqlite3.connect(db_path, timeout=30.0)
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.execute("PRAGMA foreign_keys = ON")
|
||||
conn.execute("PRAGMA busy_timeout = 30000")
|
||||
return conn
|
||||
return self._connect_postgresql()
|
||||
```
|
||||
|
||||
注释本身就承认了"并行图片任务会重叠写入",但给出的方案是"给 SQLite 足够时间"(把超时拉到 30 秒),而不是消除读写互斥。
|
||||
- **影响**:在默认 rollback journal 模式下,任何一个写事务(`audit_logs` 插入、`generation_tasks` 状态更新、`generation_images` 落库)会**阻塞所有读**。13 个 worker + 前端轮询 + 每次 `audit_service.record` 都是一次独立写事务,实际表现是 UI 列表接口在批量生成期间随机卡顿数百毫秒到数秒;极端情况下触发 30 秒超时后抛 `sqlite3.OperationalError: database is locked`,而这个异常会被 P1-2 的 `handle_request` 吞成"服务器内部错误"且无日志。
|
||||
- **修复建议**:在 `connect()` 中补两行(WAL 是持久化设置,只需生效一次,但每次设置代价极低):
|
||||
|
||||
```python
|
||||
conn.execute("PRAGMA journal_mode = WAL")
|
||||
conn.execute("PRAGMA synchronous = NORMAL")
|
||||
```
|
||||
|
||||
另外把 `initialize()` 里做一次 `PRAGMA wal_autocheckpoint` 配置,避免 WAL 文件无限增长。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 每次队列 claim 开 2 个新连接;13 个 worker 空转时约 43 次 connect + COUNT(\*) / 秒
|
||||
|
||||
- **位置**:`backend/services/worker_service.py:207-221`、`backend/services/queue_service.py:280-310`、`database/repositories/job_repository.py:90-100,139-157`
|
||||
- **问题**:全仓 **151 处** `self.database.connect()`,没有任何连接池,每个仓储方法自己 `connect()` → `execute()` → `close()`。队列 worker 的轮询链路把这个模式放大了:
|
||||
- `_claim_next` 每轮调 `list_jobs(status="queued", page=1, page_size=claim_batch_size)`,`job_repository.list()` 里**额外跑一次 `COUNT(*)`**,而 worker 只用 `.items`,`total` 被丢弃;
|
||||
- 然后对每个候选调 `claim_queued_task`,它先 `get_job`(1 个连接)再 `update_if_status`(第 2 个连接),**每次 claim 尝试 = 2 个连接**;
|
||||
- 多 worker 抢同一批 queued 行时,失败的 claim 会继续尝试下一个候选,最坏 25 个候选 × 2 = 50 个连接/轮。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/worker_service.py:207-221
|
||||
def _claim_next(self, ctx: RequestContext) -> GenerationTask | None:
|
||||
queued = self.queue_service.list_jobs(status="queued", page=1, page_size=self.claim_batch_size).items
|
||||
for candidate in queued:
|
||||
if _retry_deferred(candidate):
|
||||
continue
|
||||
...
|
||||
claimed = self.queue_service.claim_queued_task(candidate.task_id, ctx, worker_id=self.worker_id)
|
||||
if claimed is not None:
|
||||
return claimed
|
||||
return None
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/queue_service.py:289-294
|
||||
before = self.get_job(task_id) # 连接 1(job_repository.get -> connect/close)
|
||||
if before.status != "queued":
|
||||
return None
|
||||
self._validate_task_status_transition(before.status, "running")
|
||||
attempt = ...
|
||||
after = self.repository.update_if_status(...) # 连接 2
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/job_repository.py:139-157(list 内部多跑一次 COUNT(*))
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
total_row = conn.execute(f"SELECT COUNT(*) AS total FROM generation_tasks {where_clause}", tuple(params)).fetchone()
|
||||
rows = conn.execute(f"SELECT {TASK_COLUMNS} FROM generation_tasks {where_clause} ORDER BY created_at DESC LIMIT ...").fetchall()
|
||||
finally:
|
||||
conn.close()
|
||||
```
|
||||
|
||||
轮询频率:round pool `interval_seconds=0.25` × 5 worker = 20 次/秒;advanced pool `interval_seconds=0.35` × 8 worker ≈ 23 次/秒。**空载合计约 43 次/秒**,每次都是完整的 `mkdir` 系统调用 + `sqlite3.connect` + 2 条 PRAGMA + 1 次 COUNT + 1 次 SELECT。
|
||||
- **影响**:完全空闲的实例也在持续消耗 CPU 和 IO;配合 P2-1(无 WAL)会显著抬高真实任务的写锁等待概率。在 PostgreSQL 后端下更糟——每次 `connect()` 都是一次完整的 TCP + 认证握手,43 次/秒的建连会直接打满 `max_connections`。
|
||||
- **修复建议**:
|
||||
1. 给 `JobRepository` 加 `list_items_only(...)`(或给 `list()` 加 `with_total: bool = True` 参数),worker 路径跳过 `COUNT(*)`;
|
||||
2. 把 `claim_queued_task` 的 `get_job` + `update_if_status` 合成一次 `UPDATE ... WHERE task_id=? AND status='queued' RETURNING *`(PG)/ `UPDATE` + `changes()`(SQLite),单连接单语句完成 CAS;
|
||||
3. 在 `Database` 上加一个线程局部连接缓存或最小连接池(`threading.local()` + 复用),至少让同一个 worker 线程的连续操作共用一条连接;
|
||||
4. worker 空闲时做指数退避(当前固定 0.25s/0.35s),比如连续 N 轮 idle 后把间隔拉到 2 秒。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 前端 direct-fetch 路径完全没有超时,与 plugin-bridge 路径行为不一致
|
||||
|
||||
- **位置**:`frontend/shared/api/client.ts:81-85` vs `frontend/shared/api/client.ts:132-144,186-200`
|
||||
- **问题**:同一个 `request<T>()` 有两条传输路径。plugin-bridge 路径给每个调用都套了 `withClientTimeout`(GET 15s / POST 30s / 长任务 `LONG_TASK_TIMEOUT_MS`),而 direct-fetch(独立部署的 standalone-web)路径的 `fetch()` **没有传 `signal`,也没有任何 AbortController**。
|
||||
- **代码**:
|
||||
|
||||
```ts
|
||||
// frontend/shared/api/client.ts:80-93 —— 无超时
|
||||
try {
|
||||
response = await fetch(url, {
|
||||
method: options.method ?? "GET",
|
||||
headers: options.body === undefined ? undefined : { "Content-Type": "application/json" },
|
||||
body: options.body === undefined ? undefined : JSON.stringify(options.body),
|
||||
})
|
||||
} catch (err) {
|
||||
throw new ApiClientError("network_unreachable", "无法连接 ImageStudio 后端接口", { ... })
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// frontend/shared/api/client.ts:131-144 —— 有超时
|
||||
if (method === "GET" && typeof bridge.apiGet === "function") {
|
||||
return withClientTimeout(
|
||||
bridge.apiGet<...>(endpoint, compactQuery(options.query)),
|
||||
PLUGIN_BRIDGE_GET_TIMEOUT_MS,
|
||||
"AstrBot Plugin Page GET request timed out",
|
||||
)
|
||||
}
|
||||
```
|
||||
- **影响**:standalone-web 模式下,只要后端某个请求 hang 住(结合 P2-1 的 SQLite 写锁等待,或上游 provider 180 秒超时),对应的 UI 按钮会永远停在 loading 状态,没有任何反馈也无法取消。同一份代码在 AstrBot 内嵌模式下 15 秒就报错,两种部署形态行为不一致,问题在 standalone 上更难复现和归因。
|
||||
- **修复建议**:在 direct-fetch 分支复用同一套超时常量:
|
||||
|
||||
```ts
|
||||
const controller = new AbortController()
|
||||
const timeoutMs = options.method === "GET"
|
||||
? PLUGIN_BRIDGE_GET_TIMEOUT_MS
|
||||
: pluginBridgePostTimeout(endpoint)
|
||||
const timer = window.setTimeout(() => controller.abort(), timeoutMs)
|
||||
try {
|
||||
response = await fetch(url, { ..., signal: controller.signal })
|
||||
} finally {
|
||||
window.clearTimeout(timer)
|
||||
}
|
||||
```
|
||||
|
||||
并把 `AbortError` 映射成与 bridge 一致的 `ApiClientError("bridge_timeout" | "request_timeout", ...)`。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] request_id 三条关联链路全断:前端剥掉、错误对象不带、聊天侧的 ID 从未落库
|
||||
|
||||
- **位置**:`frontend/shared/api/client.ts:202-230`、`main.py:1210-1218,1579-1591`、`core/identity.py:10-16`
|
||||
- **问题**:后端为每个请求生成 `req_{uuid4().hex}` 并写进 `audit_logs.request_id`(`core/audit_service.py:51`),响应体里也带了 `request_id`(`backend/dto/common.py:54,71`)。但:
|
||||
1. 前端 `unwrapApiResponse` 成功时直接 `current = current.data`,**request_id 被丢弃**;失败时构造 `ApiClientError(current.error_code, current.message, current.details ?? {})`,**同样不带 request_id**(它在响应的顶层而非 `details` 里)。
|
||||
2. 聊天命令自己造了一套完全独立的 ID(`chatreq_` / `chatfast_` / `chathires_`),只用于回显给用户,**从未传入 `RequestContext`,也从未写入任何表**。
|
||||
- **代码**:
|
||||
|
||||
```ts
|
||||
// frontend/shared/api/client.ts:205-210 —— request_id 在这里蒸发
|
||||
if (isApiResponse(current)) {
|
||||
if (!current.ok) {
|
||||
throw new ApiClientError(current.error_code, current.message, current.details ?? {})
|
||||
}
|
||||
current = current.data
|
||||
continue
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:1210-1218 —— 造一个只给人看的 ID
|
||||
request_id = f"chatreq_{uuid4().hex}"
|
||||
task = asyncio.create_task(self._run_single_image_background(command, context, request_id))
|
||||
...
|
||||
yield event.plain_result(
|
||||
"✅ 单图请求已进入后台执行\n\n"
|
||||
f"请求:{request_id}\n尺寸:{command.size}\n数量:{command.count}\n" ...
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:1579-1591 —— request_id 只参与字符串拼接,没有进 submit_single_image
|
||||
async def _run_single_image_background(self, command: Any, context: Any, request_id: str) -> None:
|
||||
try:
|
||||
result = await asyncio.to_thread(self.chat_workflow_service.submit_single_image, command, context)
|
||||
...
|
||||
f"✅ 单图生成完成\n请求:{request_id}\n任务:{generation.get('task_id') or '—'}\n"
|
||||
```
|
||||
|
||||
注:ID 前缀本身也不一致——`core/identity.py:new_request_id()` 用 `req_`,聊天侧用 `chatreq_`/`chatfast_`/`chathires_`,三者互不相干。
|
||||
- **影响**:用户报障时给出的唯一凭据(Web 端的错误提示 / 聊天里的"请求:chatreq_xxx")在 `audit_logs`、`generation_tasks`、`workflow_history` 里**一条都查不到**。配合 P1-1(无日志)和 P1-2(异常吞掉),线上问题定位手段为零。
|
||||
- **修复建议**:
|
||||
1. `client.ts`:`ApiClientError` 增加 `readonly requestId?: string`,在 `unwrapApiResponse` 里从 `current.request_id` 取;UI 的错误 toast 追加 `(追踪号 req_xxx)`。
|
||||
2. `main.py`:删掉 `chatreq_`/`chatfast_`/`chathires_` 这套平行 ID,改为先构造 `ctx = RequestContext(...)`,把 `ctx.request_id` 同时用于回显和下游调用,让聊天生成的所有审计行都能被这个 ID 反查。
|
||||
3. `RequestContext` 支持从入站 `X-Request-Id` 头继承(`_request_context_from_astrbot_request` 目前只取 username/user_id/ip),便于跨 AstrBot 网关追踪。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `cost_service` 对 generation_images 做无 LIMIT 全表扫描,days 过滤放在 Python 侧
|
||||
|
||||
- **位置**:`backend/services/cost_service.py:168-200`(`_image_rows`)、`40-43`(Python 侧过滤)、`202-234`(另两个同样无 LIMIT 的查询)
|
||||
- **问题**:`GET costs/usage` 是 `read` 权限的普通查询接口。`_image_rows()` 的 SQL **没有 LIMIT、没有时间条件**,把 `generation_images` 全表(含 `metadata_json` 大字段)拉进内存,`days` 过滤在 Python 循环里做;`_advanced_material_attempt_rows()` 和 `_advanced_style_validation_case_rows()` 同样无 LIMIT。每行还要跑一次 `json.loads`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/cost_service.py:186-198
|
||||
where_sql = f"WHERE {' AND '.join(where)}" if where else ""
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
return conn.execute(
|
||||
f"""
|
||||
SELECT image_id, task_id, profile_id, workflow_id, node_id,
|
||||
model_route, metadata_json, created_at
|
||||
FROM generation_images
|
||||
{where_sql}
|
||||
ORDER BY created_at DESC
|
||||
""", # <- 无 LIMIT,无 created_at 过滤
|
||||
tuple(params),
|
||||
).fetchall()
|
||||
finally:
|
||||
conn.close()
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/cost_service.py:40-44 —— 时间过滤在拉完全表之后
|
||||
for row in self._image_rows(profile_id=..., workflow_id=..., node_id=...):
|
||||
created_at = _parse_datetime(row["created_at"])
|
||||
if since and created_at and created_at < since:
|
||||
continue
|
||||
metadata = _json_loads(row["metadata_json"])
|
||||
```
|
||||
- **影响**:仪表盘/成本页每次刷新都把全部历史图片记录 + 全部 metadata JSON 载入内存并逐行解析。跑几个月后 `generation_images` 到十万级时,单次请求就是几百 MB 内存峰值 + 秒级 CPU,而且这次查询会长时间持有 SQLite 读锁(P2-1 无 WAL 时会阻塞写)。`days=7` 这类"只看最近一周"的查询完全没有得到任何加速。
|
||||
- **修复建议**:把时间窗口下推到 SQL 并加上限:
|
||||
|
||||
```python
|
||||
if since is not None:
|
||||
where.append(f"created_at >= {placeholder}")
|
||||
params.append(since.isoformat())
|
||||
...
|
||||
ORDER BY created_at DESC
|
||||
LIMIT {placeholder} # 例如 20000,超出时在响应里标 truncated=True
|
||||
```
|
||||
|
||||
长期建议在写入侧就把 `usage` 的 token 数拆成独立数值列(或建一张 `generation_cost_facts` 汇总表),避免每次聚合都解析 JSON。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 高级素材详情存在 N+1:按 attempt 循环查子表,每次新开一个数据库连接
|
||||
|
||||
- **位置**:`backend/services/advanced_material_service.py:228-239`、`292-303`;`backend/services/advanced_style_set_service.py:1215-1216`、`509-510`;被调方 `database/repositories/advanced_material_repository.py:1147-1157`
|
||||
- **问题**:`get_import` / `list_attempts` 对每个 attempt 单独调 `list_style_validation_cases(attempt.attempt_id)`,而该仓储方法自己 `connect()` / `close()`。attempt 有 N 条就产生 **N 次独立连接 + N 次查询**。`advanced_style_set_service.py` 里还有两层嵌套(`for attempt: for case:`)。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/advanced_material_service.py:225-240
|
||||
attempts = self.repository.list_attempts(import_id)
|
||||
is_style_set = self.style_sets.is_style_set(record)
|
||||
style_detail = self.style_sets.detail(record) if is_style_set else {}
|
||||
attempt_payloads = [
|
||||
{
|
||||
**attempt.to_dict(),
|
||||
**(
|
||||
{
|
||||
"validation_cases": [
|
||||
case.to_dict()
|
||||
for case in self.repository.list_style_validation_cases(attempt.attempt_id) # N+1
|
||||
]
|
||||
}
|
||||
if is_style_set
|
||||
else {}
|
||||
),
|
||||
}
|
||||
for attempt in attempts
|
||||
]
|
||||
```
|
||||
|
||||
```python
|
||||
# database/repositories/advanced_material_repository.py:1147-1157
|
||||
def list_style_validation_cases(self, attempt_id: str) -> list[AdvancedStyleValidationCase]:
|
||||
conn = self.database.connect() # 每次调用一条新连接
|
||||
try:
|
||||
rows = conn.execute(
|
||||
f"SELECT {STYLE_VALIDATION_CASE_COLUMNS} FROM advanced_style_validation_cases "
|
||||
f"WHERE attempt_id = {self.placeholder} ORDER BY sort_order ASC, case_id ASC",
|
||||
(attempt_id,),
|
||||
).fetchall()
|
||||
finally:
|
||||
conn.close()
|
||||
return [_row_to_style_validation_case(row) for row in rows]
|
||||
```
|
||||
|
||||
另外 `advanced_material_service.py:258-263` 把 `get_material` 调了**两次**(一次在条件里,一次在取值里),又是两个连接,还引入了 TOCTOU:
|
||||
|
||||
```python
|
||||
"accepted_material": (
|
||||
self.repository.get_material(record.accepted_material_id).to_dict()
|
||||
if record.accepted_material_id and self.repository.get_material(record.accepted_material_id)
|
||||
else None
|
||||
),
|
||||
```
|
||||
- **影响**:一个做过 20 轮验证的风格集导入,打开详情页就是 20+ 次建连 + 20+ 次查询(PG 后端下是 20+ 次 TCP 握手)。这是前端轮询的接口,会被反复调用。
|
||||
- **修复建议**:加一个批量方法:
|
||||
|
||||
```python
|
||||
def list_style_validation_cases_by_attempts(self, attempt_ids: Sequence[str]) -> dict[str, list[...]]:
|
||||
if not attempt_ids:
|
||||
return {}
|
||||
marks = ", ".join([self.placeholder] * len(attempt_ids))
|
||||
conn = self.database.connect()
|
||||
try:
|
||||
rows = conn.execute(
|
||||
f"SELECT {STYLE_VALIDATION_CASE_COLUMNS} FROM advanced_style_validation_cases "
|
||||
f"WHERE attempt_id IN ({marks}) ORDER BY attempt_id, sort_order ASC, case_id ASC",
|
||||
tuple(attempt_ids),
|
||||
).fetchall()
|
||||
finally:
|
||||
conn.close()
|
||||
grouped: dict[str, list] = defaultdict(list)
|
||||
for row in rows:
|
||||
grouped[row["attempt_id"]].append(_row_to_style_validation_case(row))
|
||||
return grouped
|
||||
```
|
||||
|
||||
`accepted_material` 处改成先 `material = self.repository.get_material(...) if record.accepted_material_id else None`,再用局部变量。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] `ChatSessionStore` 构造期无保护地做 naive/aware datetime 比较,脏持久化文件会让插件启动直接崩
|
||||
|
||||
- **位置**:`backend/services/chat_session_service.py:32,57-60,62-76`
|
||||
- **问题**:`__init__` 无保护地调 `self._load()`。`_load()` 内部对每一行用 `except (KeyError, TypeError, ValueError): continue` 做了容错——但 `datetime.fromisoformat("2026-07-27T10:00:00")`(无时区偏移)**不会抛异常**,它会安静地返回一个 naive datetime 存进 `self._items`。真正爆炸的地方在循环外的 `self._prune()`(第 76 行),那里拿 naive 和 aware 的 `now` 比较,抛 `TypeError: can't compare offset-naive and offset-aware datetimes`,而这个位置**不在任何 try 内**。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/chat_session_service.py:57-76
|
||||
def _prune(self) -> None:
|
||||
now = datetime.now(timezone.utc) # aware
|
||||
for key in [key for key, item in self._items.items() if item.expires_at <= now]: # <- 这里炸
|
||||
self._items.pop(key, None)
|
||||
|
||||
def _load(self) -> None:
|
||||
try:
|
||||
payload = json.loads(self.persistence_path.read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError, TypeError):
|
||||
return
|
||||
for item in payload if isinstance(payload, list) else []:
|
||||
try:
|
||||
session = ChatSession(
|
||||
key=str(item["key"]), action=str(item["action"]), payload=dict(item.get("payload") or {}),
|
||||
expires_at=datetime.fromisoformat(item["expires_at"]), created_at=datetime.fromisoformat(item["created_at"]),
|
||||
) # naive 字符串在这里不会报错
|
||||
self._items[session.key] = session
|
||||
except (KeyError, TypeError, ValueError):
|
||||
continue
|
||||
self._prune() # 无 try 保护
|
||||
```
|
||||
|
||||
同样的问题也在 `put()` 里:`min(self._items.values(), key=lambda item: item.created_at)`(第 38 行)遇到 naive/aware 混排也会 `TypeError`。
|
||||
- **影响**:只要 `data/chat_sessions.json` 里出现一个不带时区的时间戳(旧版本写入、手工编辑、外部工具生成、跨环境迁移),`ChatSessionStore()` 构造就抛异常,整个聊天服务乃至插件加载失败。作者显然想让这个文件"坏了就忽略"(`_load` 开头的 `except (OSError, ValueError, TypeError): return` 已经表明了意图),但这层防护被绕过了。
|
||||
- **修复建议**:在解析处强制归一化时区,并给 `_prune()` 加保护:
|
||||
|
||||
```python
|
||||
def _aware(value: str) -> datetime:
|
||||
parsed = datetime.fromisoformat(value)
|
||||
return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
|
||||
```
|
||||
|
||||
`expires_at=_aware(item["expires_at"])`、`created_at=_aware(item["created_at"])`。仓库里 `cost_service._parse_datetime`(`cost_service.py:319-329`)、`worker_service._retry_deferred`(`worker_service.py:487-493`)、`integration_token_service._parse_time`(`integration_token_service.py:186-198`)三处都已经写对了这段归一化逻辑,应该抽成 `core/` 里的共享工具函数,消除这处漏网。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 路由权限矩阵声明了但 dispatch 从不校验,只有 5 处散落的手工检查
|
||||
|
||||
- **位置**:`adapters/astrbot_adapter.py:171-187`、`backend/route_registry.py:9-29,32-52`
|
||||
- **问题**:`route_registry.py` 定义了完整的 `PERMISSION_MATRIX`(read/write/config/materials/retry/public_token),166 条路由每条都标了 `permission`,`RouteSpec.to_dict()` 还会把 `auth_required` / `required_permissions` 导出到 manifest。但唯一的请求入口 `dispatch_extension_request` 拿到 `RouteMatch.permission` 之后**直接调 handler,从不做任何校验**。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:179-187
|
||||
match = resolve_route(method, path)
|
||||
if match is None:
|
||||
return error_response(error_code=ErrorCode.RESOURCE_NOT_FOUND, ...)
|
||||
return match.handler(*_handler_args(match, ctx, query or {}, payload or {}))
|
||||
# ^ match.permission 被解析出来了,但这里没有任何 ctx.has_permission 判断
|
||||
```
|
||||
|
||||
全仓 `has_permission` 只出现 5 次,集中在 2 个文件:
|
||||
|
||||
```
|
||||
backend/routes/image_routes.py:42,70,90,156
|
||||
backend/routes/job_routes.py:36
|
||||
```
|
||||
- **影响**:当前之所以没出安全事故,是因为 `main.py:2337` 给所有已认证用户一次性授予了全部 4 个权限(`permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()`),矩阵在运行时是恒真的。但这意味着:(1) 这套权限声明是**纯装饰**,任何人读代码会误以为已生效;(2) 一旦将来 AstrBot 暴露细粒度用户角色、或有人把 `BRIDGE_PERMISSIONS` 收窄,166 条路由里只有 5 处会真正拦截,其余 161 条静默放行。这是典型的"策略集中声明、执行处处缺失"的横切一致性缺陷。
|
||||
- **修复建议**:在 dispatch 层统一执行,让声明成为唯一事实来源:
|
||||
|
||||
```python
|
||||
match = resolve_route(method, path)
|
||||
if match is None: ...
|
||||
requirement = permission_requirement(match.permission)
|
||||
if requirement["auth_required"] and not ctx.is_authenticated:
|
||||
return error_response(error_code=ErrorCode.UNAUTHORIZED, ..., request_id=ctx.request_id)
|
||||
for needed in requirement.get("required_permissions") or []:
|
||||
if not ctx.has_permission(needed):
|
||||
return error_response(error_code=ErrorCode.FORBIDDEN,
|
||||
message="缺少所需权限",
|
||||
details={"required_permission": needed},
|
||||
request_id=ctx.request_id)
|
||||
return match.handler(...)
|
||||
```
|
||||
|
||||
然后把 `image_routes` / `job_routes` 里那 5 处手工检查降级为纯业务判断(如"受限图片")或直接删除。
|
||||
|
||||
---
|
||||
|
||||
### [P2-中等] 主动通知全链路静默失败:签名失败返回 None,发送失败返回 False,一行日志都没有
|
||||
|
||||
- **位置**:`main.py:1650-1670`(`_send_proactive`)、`backend/services/workflow_round_worker_runtime.py:257-263`(`_signed_url`)、`backend/services/worker_service.py:366-380`(`_notify_terminal`)
|
||||
- **问题**:轮次完成后主动推图到聊天的这条链路上,有三个连续的静默吞异常点,任何一环失败用户和运维都得不到任何信号:
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/workflow_round_worker_runtime.py:257-263
|
||||
def _signed_url(media_service: MediaService, uri: Any) -> str | None:
|
||||
if not isinstance(uri, str) or not uri:
|
||||
return None
|
||||
try:
|
||||
return media_service.sign_media(uri).get("url")
|
||||
except Exception:
|
||||
return None # 签名失败 -> 通知里图片 URL 变 None -> 图片静默消失
|
||||
```
|
||||
|
||||
```python
|
||||
# main.py:1664-1670
|
||||
message = AstrBotMessageChain(components) if AstrBotMessageChain is not None else components
|
||||
result = sender(message_origin, message)
|
||||
if inspect.isawaitable(result):
|
||||
await result
|
||||
return True
|
||||
except Exception:
|
||||
return False # 发送失败 -> 返回 False -> 调用方也不看返回值
|
||||
```
|
||||
|
||||
```python
|
||||
# backend/services/worker_service.py:372-380
|
||||
if self.terminal_callback is None:
|
||||
return
|
||||
try:
|
||||
self.terminal_callback(claimed_task, current_task, exc)
|
||||
except Exception:
|
||||
# Queue state is authoritative. ...
|
||||
return # 同一文件其余 6 处失败都 logger.exception,唯独这里静默
|
||||
```
|
||||
|
||||
`worker_service.py` 是全仓唯一有 logger 的文件,其他 6 个 `except` 全部 `logger.exception(...)`,`_notify_terminal` 是唯一的例外,明显是遗漏而非有意为之。
|
||||
- **影响**:用户提交生成后一直收不到结果推送,服务端三个环节都"成功"返回(`None` / `False` / 静默 return),队列状态显示 succeeded。这类问题在没有日志的前提下**只能靠加打印重现**。
|
||||
- **修复建议**:三处都改为 `logger.warning(...)` / `logger.exception(...)` 后再返回兜底值。`_send_proactive` 的返回值当前在 `_deliver_round_terminal_notification` 中被忽略,应该至少在返回 `False` 时记一条带 `round_id` 和 `message_origin` 的 warning。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `_Psycopg2ConnectionAdapter.execute` 每次新建 cursor 且从不关闭
|
||||
|
||||
- **位置**:`database/db_helper.py:301-317`
|
||||
- **问题**:psycopg2 回退适配器的 `execute()` 每次调用都 `self.connection.cursor()` 新建游标,返回后没有任何地方 `close()` 它。适配器只暴露 `commit` / `rollback` / `close`,没有 cursor 生命周期管理。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
class _Psycopg2ConnectionAdapter:
|
||||
def __init__(self, connection):
|
||||
self.connection = connection
|
||||
|
||||
def execute(self, query: str, params: tuple[Any, ...] | list[Any] | None = None):
|
||||
cursor = self.connection.cursor()
|
||||
cursor.execute(query, tuple(params or ()))
|
||||
return cursor # 调用方拿去 .fetchall()/.fetchone() 后就丢弃,永不 close
|
||||
```
|
||||
- **影响**:单个连接内每执行一条 SQL 就泄漏一个游标对象,直到 `conn.close()` 才随连接释放。因为本仓库是"每次操作新建连接"(见 P2-2),泄漏窗口很短,所以实际危害有限;但一旦按 P2-2 的建议引入连接复用/连接池,这个泄漏会立刻变成真实的内存和服务端资源问题。而且 psycopg2 只是 `import psycopg` 失败时的回退路径,问题更难被发现。
|
||||
- **修复建议**:返回一个包装对象,在 `fetchall`/`fetchone` 取完后自动 `close`;或者让 `execute` 直接返回结果集:
|
||||
|
||||
```python
|
||||
def execute(self, query, params=None):
|
||||
cursor = self.connection.cursor()
|
||||
try:
|
||||
cursor.execute(query, tuple(params or ()))
|
||||
return _CursorResult(cursor) # __enter__/__exit__ 或 fetch 后自动 close
|
||||
except Exception:
|
||||
cursor.close()
|
||||
raise
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `.part` 临时文件在 `replace()` 失败时残留,无清理
|
||||
|
||||
- **位置**:`backend/services/material_service.py:326-336`、`backend/services/advanced_material_service.py:1584-1594`
|
||||
- **问题**:两处上传落盘都用"先写 `.part` 再 `replace`"的原子写模式,但 `except OSError` 里只抛 `ApiError`,**不删除已经写出的 `.part` 文件**。如果 `write_bytes` 成功而 `replace` 失败(目标被占用、跨设备、权限、磁盘满导致部分写入后失败),临时文件永久留在存储目录。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/material_service.py:326-336
|
||||
try:
|
||||
persisted_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary_path = persisted_path.with_suffix(f"{persisted_path.suffix}.part")
|
||||
temporary_path.write_bytes(content)
|
||||
temporary_path.replace(persisted_path)
|
||||
except OSError as exc:
|
||||
raise ApiError(
|
||||
ErrorCode.STORAGE_WRITE_FAILED,
|
||||
"material image could not be stored",
|
||||
{"uri": image_uri, "exception_type": exc.__class__.__name__},
|
||||
) from None
|
||||
# temporary_path 从未清理
|
||||
```
|
||||
|
||||
`advanced_material_service.py:1584-1594` 是同一段代码的复制。
|
||||
- **影响**:磁盘写失败(最典型是磁盘满)时,每次重试都留下一个和原图等大的 `.part` 残骸,把本就紧张的空间进一步耗尽,形成正反馈。`orphan_media_service` 扫描的是 `storage://` URI 与 DB 的差集,识别不了 `.part` 后缀的孤儿。
|
||||
- **修复建议**:
|
||||
|
||||
```python
|
||||
temporary_path = persisted_path.with_suffix(f"{persisted_path.suffix}.part")
|
||||
try:
|
||||
persisted_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary_path.write_bytes(content)
|
||||
temporary_path.replace(persisted_path)
|
||||
except OSError as exc:
|
||||
temporary_path.unlink(missing_ok=True)
|
||||
raise ApiError(...) from None
|
||||
```
|
||||
|
||||
建议把这段抽成 `core/storage.py` 的 `atomic_write_bytes(path, content)`,两处共用。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] 每个请求重排 166 条路由 + 逐条编译正则 + `inspect.signature`,全程无缓存
|
||||
|
||||
- **位置**:`adapters/astrbot_adapter.py:44-64`(`resolve_route`)、`224-230`(`_match_endpoint`)、`233-252`(`_handler_args`)
|
||||
- **问题**:唯一的请求入口每次都做纯静态的重复计算:`ROUTES` 是模块级常量,路由表和 handler 签名在进程生命周期内不变,但每个请求都重跑一遍。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:44-64
|
||||
def resolve_route(method: str, path: str) -> RouteMatch | None:
|
||||
normalized_method = str(method or "").strip().upper()
|
||||
endpoint = normalize_extension_path(path)
|
||||
candidates = sorted( # 每请求排序
|
||||
(route for route in ROUTES if route.method == normalized_method),
|
||||
key=_route_specificity,
|
||||
reverse=True,
|
||||
)
|
||||
for route in candidates:
|
||||
params = _match_endpoint(route.endpoint, endpoint) # 每候选编译一次正则
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:224-230
|
||||
def _match_endpoint(pattern: str, endpoint: str) -> dict[str, str] | None:
|
||||
param_names = re.findall(r"\{([^{}]+)\}", pattern)
|
||||
regex = "^" + re.sub(r"\{([^{}]+)\}", r"([^/]+)", pattern) + "$"
|
||||
match = re.match(regex, endpoint) # 每次都走 re 的模式缓存查找
|
||||
...
|
||||
```
|
||||
|
||||
```python
|
||||
# adapters/astrbot_adapter.py:240
|
||||
for index, parameter in enumerate(inspect.signature(match.handler).parameters.values()):
|
||||
```
|
||||
|
||||
实测(本机 2000 次循环):`resolve_route + _handler_args` 约 **0.178 ms / 次**,路由总数 166。
|
||||
- **影响**:0.18 ms 本身不致命,但这是所有 166 个端点的固定入口开销,且是纯浪费。前端存在多处轮询(队列状态、导入进度、事件流),这部分开销会持续累加;随着路由表增长呈线性劣化。
|
||||
- **修复建议**:
|
||||
1. 模块加载时预编译一张 `dict[str, list[tuple[re.Pattern, RouteSpec]]]`(按 method 分桶、已按 `_route_specificity` 排好序);
|
||||
2. `_load_handler` 加 `@functools.lru_cache(maxsize=None)`;
|
||||
3. handler 的参数绑定方案在导入时算一次并缓存到 `RouteSpec` 上,避免每请求 `inspect.signature`。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `log_service` / `cost_service` 的 `_json_loads` 无异常保护,单条脏数据可让整个日志端点 500
|
||||
|
||||
- **位置**:`backend/services/log_service.py:297-300`、`backend/services/cost_service.py:332-336`
|
||||
- **问题**:日志查询接口对每一行的 JSON 列做 `json.loads`,没有任何保护。只要 `integration_logs.request_json` / `audit_logs.metadata_json` / `generation_images.metadata_json` 里有一条被截断或写坏的记录,整个列表接口就抛 `json.JSONDecodeError`。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# backend/services/log_service.py:297-300
|
||||
def _json_loads(value: str | None) -> Any:
|
||||
if not value:
|
||||
return None
|
||||
return json.loads(value) # 无 try
|
||||
```
|
||||
|
||||
调用点(每行一次):`log_service.py:162-163`(`request` / `response`)、`284-286`(`before_snapshot` / `after_snapshot` / `metadata`)。
|
||||
- **影响**:日志查询是排障工具,恰恰应该对脏数据最宽容。现在一条坏记录就能让 `logs/integrations` 和 `security/audit-logs` 两个端点永久 500,而且因为 P1-2 该异常被吞成"服务器内部错误"、因为 P1-1 没有日志,运维根本不知道是哪条记录坏了——排障工具自己坏了且无法排障。
|
||||
- **修复建议**:
|
||||
|
||||
```python
|
||||
def _json_loads(value: str | None) -> Any:
|
||||
if not value:
|
||||
return None
|
||||
try:
|
||||
return json.loads(value)
|
||||
except (ValueError, TypeError):
|
||||
return {"_parse_error": True, "raw_preview": str(value)[:200]}
|
||||
```
|
||||
|
||||
`cost_service._json_loads` 同理(它返回 `dict`,失败时返回 `{}` 即可)。
|
||||
|
||||
---
|
||||
|
||||
### [P3-轻微] `EventBus.publish` 不隔离订阅者异常,一个 handler 抛错会中断发布方并跳过后续 handler
|
||||
|
||||
- **位置**:`core/event_bus.py:45-50`
|
||||
- **问题**:`publish` 在循环里直接调 `handler(event)`,没有 try/except。任一订阅者抛异常会向上冒泡到发布方(`generation_service._publish`,`generation_service.py:1701-1703`),同时后续 handler 全部不执行。
|
||||
- **代码**:
|
||||
|
||||
```python
|
||||
# core/event_bus.py:45-50
|
||||
def publish(self, event_type: str, payload: dict[str, Any] | None = None) -> Event:
|
||||
event = Event(event_type=_normalize_event_type(event_type), payload=dict(payload or {}))
|
||||
self._history.append(event)
|
||||
for handler in [*self._handlers.get(event.event_type, []), *self._handlers.get("*", [])]:
|
||||
handler(event) # 无隔离
|
||||
return event
|
||||
```
|
||||
- **影响**:当前全仓 grep 不到任何 `event_bus.subscribe(...)` 调用(事件总线只被当作 `deque(maxlen=500)` 的历史缓冲,供 `event_stream_service.recent_events` 轮询读取),所以这条现在**不会触发**。但 `_publish` 已被 `generation_service` 在生成成功/失败等关键路径调用,一旦将来接入第一个订阅者(例如 webhook 推送),一个下游 HTTP 超时就会把生成流程本身打断。
|
||||
- **修复建议**:
|
||||
|
||||
```python
|
||||
for handler in [...]:
|
||||
try:
|
||||
handler(event)
|
||||
except Exception:
|
||||
logger.exception("event handler failed event_type=%s event_id=%s", event.event_type, event.event_id)
|
||||
```
|
||||
|
||||
顺带修掉 `unsubscribe`(`event_bus.py:41-43`)对未订阅类型会因 `defaultdict` 而凭空建键的小问题。
|
||||
|
||||
---
|
||||
|
||||
## 附:确认无问题的横切项(供后续审计参考)
|
||||
|
||||
以下项经实际 grep/阅读确认**不存在**问题,无需再查:
|
||||
|
||||
| 检查项 | 结论 | 证据 |
|
||||
|---|---|---|
|
||||
| 裸 `except:` | 0 处 | `grep -rn "except:"` 全树无匹配 |
|
||||
| naive datetime | 0 处 | `utcnow()` 0 次;`datetime.now()`(无参)0 次;`datetime.now(timezone.utc)` / `datetime.now(UTC)` 共 29 次 |
|
||||
| async 函数内同步阻塞 | 无 | `requests` / `time.sleep` / `subprocess` 全树 0 次导入;`main.py` 的同步服务调用全部走 `asyncio.to_thread`(30+ 处) |
|
||||
| 裸 `open()` 文件句柄泄漏 | 无 | `with open(` / `= open(` 全树 0 处,统一用 `Path.read_bytes/write_bytes/read_text` |
|
||||
| 临时目录清理 | 正确 | `data_backup_service.py:49,126` 用 `tempfile.TemporaryDirectory` 上下文管理器 |
|
||||
| ID 生成方式 | 统一 | 全部 `f"{前缀}_{uuid4().hex}"`,前缀按实体命名(`req_`/`audit_`/`task_`/`round_`/`img_`…),唯一例外见 P2-3 的聊天侧 ID |
|
||||
| 敏感信息脱敏 | 已实现 | `core/secret_service.redact`、`settings_service._mask_sensitive`(审计快照 `settings_service.py:453-454,564-565`)、`generation_errors._safe_message/_safe_details`、`api_discovery_service._redact_probe_error`、`prompt_governance_service._redact` |
|
||||
| SSRF 防护 | 已实现 | `core/remote_fetch.py` 校验协议/凭据/私网地址/重定向同源,并在跨源重定向时移除 `Authorization`(`remote_fetch.py:124-126`) |
|
||||
| 内存缓存无上限 | 无 | `_NODE_GENERATION_LOCKS` / `_QUICK_CHARACTER_WORKFLOW_LOCKS` 有引用计数并在归零时 `pop`(`generation_service.py:1947-1950,1966-1969`);`EventBus._history` 是 `deque(maxlen=500)`;`ChatSessionStore` 有 `max_sessions=1000` 上限 |
|
||||
| 前端 catch 静默 | 可接受 | 20 处 `catch {}` 均为"降级到默认值"的有意设计(如 `ModelAssignmentsPanel.vue:153` `runtimeModels.value = []`),非错误吞没 |
|
||||
3147
审计/findings/_raw.json
普通文件
3147
审计/findings/_raw.json
普通文件
文件差异因一行或多行过长而隐藏
572
审计/findings/_复核结论.md
普通文件
572
审计/findings/_复核结论.md
普通文件
|
|
@ -0,0 +1,572 @@
|
|||
# 复核结论(对抗式验证)
|
||||
> 对全部 P0/P1 发现各派一名独立复核者,立场设为「默认这是误报」,要求 Read 真实代码后才可判定成立。
|
||||
> 复核 56 条,**推翻 16 条**,维持 40 条。
|
||||
|
||||
## 被推翻的发现(不得进入最终报告,或须按复核意见降级)
|
||||
|
||||
### 推翻 #1
|
||||
- **定位**:`backend/services/workflow_round_service.py:81 (_ensure_round_creation_allowed,定义在 :1129-1156)`
|
||||
- **复核意见**:结论:误报。发现者引用的代码片段本身真实存在(workflow_round_service.py:115-117 的幂等重放分支、:928-940 无条件写 status="queued"、database/repositories/workflow_round_repository.py:1355-1375 的 _ensure_writable_round_row confirmed 只读保护、:416-431 的裸 UPDATE update_round),但它漏读了 create_round 的第一行守卫,导致整条攻击链对 confirmed 轮次不可达。
|
||||
|
||||
1) create_round 在读取 idempotency_key 之前就先跑了节点级锁:
|
||||
```python
|
||||
node, workflow = self._node_and_workflow(node_id, ctx)
|
||||
self._ensure_round_creation_allowed(node, workflow) # line 81
|
||||
...
|
||||
idempotency_key = _optional_text(payload.get("idempotency_key")) # line 90
|
||||
if idempotency_key:
|
||||
existing = self.round_repository.get_round_by_idempotency_key(idempotency_key) # line 92
|
||||
```
|
||||
而 _ensure_round_creation_allowed(:1145-1156)明确拒绝已定稿节点:
|
||||
```python
|
||||
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, "branch_name": node.branch_name, "required_action": "create_branch"},
|
||||
)
|
||||
```
|
||||
即:目标节点一旦定稿,请求在第 81 行就抛 VALIDATION_FAILED,根本走不到第 92 行的 idempotency 查表,更走不到 :116 的 _ensure_round_enqueued。
|
||||
|
||||
2) 「轮次 status=confirmed」与「节点 status=selected / selected_image_id 非空」是同一原子事务里一起写的,不存在“轮次已 confirmed 但节点仍可创建轮次”的中间态。全仓只有两处把轮次写成 confirmed,两处都同时锁死节点:
|
||||
- workflow_round_repository.py:993-1000(confirm_candidate_atomic)先执行
|
||||
```sql
|
||||
UPDATE workflow_nodes SET status = 'selected', selected_image_id = ?, updated_at = CURRENT_TIMESTAMP WHERE node_id = ?
|
||||
```
|
||||
:1010-1017 才写 `UPDATE workflow_generation_rounds SET status = 'confirmed' ...`,同一 conn 同一事务(sqlite BEGIN IMMEDIATE,pg FOR UPDATE 行锁)。
|
||||
- workflow_cross_review_repository.py:580-583 同样先 `UPDATE workflow_nodes SET status = 'selected', selected_image_id = ?`,:599-635 才把评审轮次与 root 轮次写成 confirmed。
|
||||
|
||||
3) 不存在“解锁节点但保留轮次 confirmed”的回退路径。唯一清 selected_image_id 的地方是 image_service.py:179/205/225(unselect/archive/delete_image),三处入口都先调 _ensure_image_node_is_editable(:236-255),对 LOCKED_NODE_STATUSES 内节点直接 raise locked_node_edit_error;即便 selected_image_id 被清空,node.status 仍是 'selected',第 1145 行照样拦得住。
|
||||
|
||||
4) 因此发现列举的三项后果全部不成立:apply_feedback_atomic 的 _ensure_writable_round_row 拦截、workflow_cross_review_repository.py:1066-1076 的 confirmed_candidate_mismatch、:1108-1122 的 _ensure_review_after_confirmation_is_safe、:795 的 record_skip_restoration_handoff_atomic,都不会因为“status 被回退成 completed”而失效——status 压根回退不了。另外跨评审轮次也不走 create_round:backend/routes/generation_cross_review_routes.py 走 workflow_cross_review_repository 的原子路径(:165-169 有独立 _round_replay),与这条 idempotency 分支无关。
|
||||
|
||||
5) 触发条件描述尤其站不住:“网络超时后的正常重试”发生在轮次刚创建、节点尚未定稿时,此时 status 是 draft/queued/running,_ensure_round_enqueued 写成 queued 再 reconcile 成实际聚合态,正是幂等补偿的预期语义,不是缺陷。
|
||||
|
||||
残留的真实问题仅是防御性编码瑕疵:_ensure_round_enqueued 末尾的 status 写入确实没有终态白名单,依赖调用方(create_round:81)的前置守卫兜底,属于“守卫与写入分离、易被后续重构打破”的健壮性问题,最多 P3,需先破坏第 81 行节点锁才可能演变为真实缺陷。
|
||||
|
||||
### 推翻 #2
|
||||
- **定位**:`backend/services/worker_service.py:191-206 (_run_loop) 与 backend/services/queue_service.py:439+ (recover_stale_tasks)`
|
||||
- **复核意见**:代码引用属实,但核心机理与影响链被证伪,标题所述的"并发抢占同一队列 / worker 线性膨胀"不成立。
|
||||
|
||||
1) 引用的代码确实存在、行号对得上:
|
||||
- worker_service.py:180-185 的 stop() 逐字一致(set() 后 join(timeout),返回 running=self.is_running());
|
||||
- main.py:437-439 逐字一致:`self.round_worker_result = self.round_worker_runtime.stop()` / `self.round_worker_runtime = None`,确实不看 running;
|
||||
- engines/image_provider.py:308-313 的 `_generation_request_timeout_seconds` 返回 `min(max(timeout, 10), 3600)` 也属实。
|
||||
|
||||
2) 决定性反证——旧线程停止后不会再认领任何任务。worker_service.py:191-206:
|
||||
```
|
||||
def _run_loop(self, ctx):
|
||||
while not self._stop_event.is_set():
|
||||
result = self.run_once(ctx)
|
||||
...
|
||||
```
|
||||
认领动作只发生在 run_once → _claim_next 内,而 run_once 每次只认领一条任务(_claim_next 返回单个 task,见 207-221 行)。stop_event 被 set 后,阻塞中的 run_once 一旦返回,while 条件立即为假,线程退出。也就是说 join 超时后残留的旧线程**最多把手上那一条已认领任务跑完就自然死亡,绝不会与新 pool 竞争认领新任务**。因此"新旧 worker 池并发抢占同一队列""worker 数量随每次重载线性膨胀"两条结论都不成立——每次重载最多留下 5 个短命线程,各自跑完一条即退出,不累积。
|
||||
|
||||
3) 残余风险存在但被默认配置基本关闭。唯一真实的窄窗口是:旧线程手上那条任务若在新 runtime 启动时已 running 超过 stale_after_seconds,会被 recover_stale_tasks(workflow_round_worker_runtime.py:55-59,默认 stale_after_seconds=300)标 failed 再重新入队,造成同一候选被生成两次。但要触发必须让单条任务的 running 时长超过 300 秒,而 config.yaml:25 / config.yaml:42 的默认 `timeout_seconds: 180`,加上 terminate() 里 5 个 worker 顺序 join(最多 25 秒)才轮到 initialize() 做 recovery,默认配置下窗口实际关闭;只有把 provider 超时手动配到 >300 秒(上限 3600)才可能命中。这属于配置相关的边缘竞态,而非 P0/P1 级的必现重复计费。
|
||||
|
||||
4) 另外 update_task 并非"无条件写回":queue_service.py:405-408 的 update_task 会先走 `_validate_task_status_transition`(673-686 行,依赖 core/fsm.py 的 TASK_TRANSITIONS);run_once 116 行之前还会先 get_job 复查 cancelled(106-115 行)。真正的 CAS 保护(update_task_if_status / claim_queued_task,184-228、280-312 行)确实保证了同一条任务不会被两个线程同时认领。
|
||||
|
||||
结论:机理描述有真实成分(stop() 返回值被忽略、join 可能超时),但被断言的影响链(队列抢占、线程线性膨胀、必然重复计费)经代码验证不成立,严重度严重夸大。按误报处理,若要保留最多记为 P3 的健壮性改进(stop() 返回 running=True 时记日志/告警,或让 recovery 跳过本进程仍存活的 worker_id)。
|
||||
|
||||
### 推翻 #3
|
||||
- **定位**:`backend/routes/profile_routes.py:109-114(仅命名问题);frontend/shared/api/endpoints.ts:10-11(profileDelete 定义后未使用)`
|
||||
- **复核意见**:代码本身存在,但这条发现的"影响"是编造的,P1-严重定级完全站不住脚。
|
||||
|
||||
一、代码事实核对(这部分属实)
|
||||
`backend/routes/profile_routes.py:109-114` 确实是:
|
||||
```python
|
||||
def archive_profile(
|
||||
ctx: RequestContext,
|
||||
profile_id: str,
|
||||
service: ProfileService | None = None,
|
||||
) -> dict:
|
||||
return delete_profile(ctx, profile_id, service)
|
||||
```
|
||||
`backend/route_registry.py:69` 也确实注册了 `RouteSpec("POST", "profiles/{profile_id}/archive", "backend.routes.profile_routes.archive_profile", "write")`。行号无误,非幻觉。
|
||||
|
||||
二、致命反驳:前端根本没有"归档"按钮,唯一调用方是一个红色"删除"按钮
|
||||
发现声称"前端 profileArchive 按钮标注为'归档',用户点击后档案被删除……归档与删除两种不同用户意图被合并成一种破坏性操作"。我把 profileArchive 的全部引用查了一遍,全仓库只有一处调用(`frontend/standalone-web/src/App.vue:6300`),而它所在的函数是:
|
||||
```js
|
||||
async function deleteSelectedProfile() {
|
||||
const profile = selectedProfilePage.value
|
||||
if (!profile || profileDeletingId.value) return
|
||||
const blocked = backendWriteBlockMessage("删除角色档案")
|
||||
...
|
||||
profileDeletingId.value = profile.profile_id
|
||||
try {
|
||||
await postJson<CharacterProfile>(endpoints.profileArchive(profile.profile_id))
|
||||
```
|
||||
失败文案是 `` `删除角色失败:${errorMessage(err)}` ``(App.vue:6334),状态变量叫 `profileDeletingId`,模板绑定是 `@delete="deleteSelectedProfile"`(App.vue:13369)。
|
||||
|
||||
再看用户实际看到的控件(`frontend/standalone-web/src/features/profiles/ProfileDetailPane.vue:190-198`):
|
||||
```html
|
||||
<button
|
||||
type="button"
|
||||
class="danger-button"
|
||||
:disabled="!canWrite || !backendConnected || deleting || Boolean(generationBusy)"
|
||||
title="删除角色档案"
|
||||
@click="emit('delete')"
|
||||
>
|
||||
{{ deleting ? "删除中" : "删除" }}
|
||||
</button>
|
||||
```
|
||||
按钮文案是"删除"、hover 提示是"删除角色档案"、样式是 `danger-button`。用户意图 = 删除,后端行为 = `repository.soft_delete()` 置 `status="deleted"`,两者**完全一致**。不存在任何"用户以为在归档、结果被删除"的场景,也就不存在所声称的"两种不同用户意图被合并"和"破坏性操作"。发现里"该档案及其下所有工作流从 UI 彻底消失"这一后果是删除按钮的**预期行为**,不是缺陷。
|
||||
|
||||
三、被引用的"证据"反而说明这是有意为之
|
||||
发现自己引用的 `delete_profile_via_post`(profile_routes.py:101-107)同样转发 `delete_profile`,对应 `route_registry.py:68` 的 `POST profiles/{profile_id}/delete`。也就是说仓库为软删除提供了 DELETE、POST /delete、POST /archive 三条等价入口(`endpoints.ts:10` 的 `profileDelete` 已定义但全仓库无人调用),前端只是挑了 `/archive` 这条当删除用。这是路径命名/冗余入口的整洁性问题,不是语义错误导致的数据事故。
|
||||
|
||||
四、与 workflow 侧的对照不成立
|
||||
`workflow_routes.py:106-111` 的 `archive_workflow` 走 `_set_workflow_status(ctx, workflow_id, "archived", service)`,确实是真归档,但 workflow 有 `core/fsm.py:9-15` 定义的 `archived` 终态,而 profile 侧的状态机里压根没有 `archived` 这个态——`ProfileService.get_profile`(profile_service.py:70-77)只对 `status == "deleted"` 做 404,`list_profiles` 默认 `status="active"`。profile 从未设计过归档态,拿 workflow 的 FSM 去要求 profile 属于类比失当。
|
||||
|
||||
五、结论
|
||||
唯一站得住的残留问题是:REST 路径叫 `/archive` 却执行删除,命名有误导性,且与 `imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md:657` 的契约文档字面不符,未来若真要加归档功能会撞名。这是 P3 命名/契约整洁度问题。发现给出的"修复建议"(把 archive 改成写入 `status="archived"`)如果照做,反而会让当前这个"删除"按钮变成不删除、档案继续留在列表里——即引入真实的功能回归。故判定为误报。
|
||||
|
||||
### 推翻 #4
|
||||
- **定位**:`backend/routes/node_routes.py:140(构造顺序);真正残留问题在 adapters/astrbot_adapter.py:171-187 与 main.py:315-344 缺少兜底 try`
|
||||
- **复核意见**:代码本身没有幻觉,但这条发现的**核心指控("未授权即触发重型初始化")在本仓库不存在可达路径**,属于误报级别的过度定级。
|
||||
|
||||
一、代码确实如描述(这部分成立)
|
||||
`backend/routes/node_routes.py:132-146` 逐字对得上:
|
||||
```python
|
||||
def generate_node(ctx, node_id, payload=None, service=None, generation_service=None) -> dict:
|
||||
workflow_service = service or _create_workflow_service()
|
||||
resolved_generation_service = generation_service or (None if service else _create_generation_service())
|
||||
def action() -> dict[str, Any]:
|
||||
require_write(ctx)
|
||||
```
|
||||
`_create_generation_service()`(node_routes.py:315-390)确实调 `load_config_payload()`、`Database(...)`、`sync_generation_provider_from_config(...)`;后者在 `backend/services/model_provider_bootstrap.py:68,79` 里确实执行 `service.upsert_provider(...)` 与 `service.upsert_route(...)` 写库。`round_routes.py:137-138` 的只读 `list_node_rounds` 也确实经 `_create_round_service()` → `create_generation_service()` 走同一条重型链路。`backend/routes/common.py:12-16` 的 try 也确实只包住 callback。
|
||||
|
||||
二、致命反驳:不存在"有权限差、但能打到 handler"的调用者
|
||||
生产环境只有两个 ingress,两个都在 service 构造**之前**就完成了准入判定:
|
||||
|
||||
1. Web 桥接(前端唯一通路):`main.py:2324-2344`
|
||||
```python
|
||||
# AstrBot authenticates extension routes before invoking the plugin, but
|
||||
# PluginRequest currently exposes only the authenticated username.
|
||||
permissions = BRIDGE_PERMISSIONS if username or user_id else frozenset()
|
||||
```
|
||||
`BRIDGE_PERMISSIONS`(main.py:104-106)= `{"can_write","can_manage_config","can_manage_materials","can_retry_tasks"}` 全给。也就是说:**凡是能走到 handler 的请求,`require_write` / `require_task_retry` 必然通过**;而未登录请求根本进不来——`docs/project-migration-handoff-2026-07-18.md:263` 是实测证据:"插件 Web 路径直接无认证访问会返回 `Missing API key`,这是正常鉴权行为"。攻击者拿不到 401 之后的执行权,谈不上"未授权用户狂刷 GET nodes/x/rounds"。
|
||||
|
||||
2. 聊天命令通路:`backend/services/chat_workflow_service.py:1149-1164`,白名单校验 `chat_action_allowed(...)` 在**构造 ctx 和 dispatch 之前**,不通过直接 `raise ValueError("当前群聊或用户不满足聊天白名单规则")`;通过者被显式授予 `{"can_write","can_retry_tasks","can_manage_materials"}`。同样不存在"权限不足但已进入 handler"的状态。
|
||||
|
||||
结论:把 `require_*` 提到构造前,唯一能省下的是一个**在生产中永远不会发生**的分支的开销。原文声称的影响 1(未授权资源消耗 / SQLite 写锁被未授权流量拖垮)与影响 3 的"未授权"定性,均不可达。
|
||||
|
||||
三、影响 2(500 泄漏)被夸大
|
||||
`adapters/astrbot_adapter.py:171-187` 的 `dispatch_extension_request` 与 `main.py:315-344` 的 `dispatch_bridge_request` 确实都没有 try,构造期异常会逃逸到 Quart —— 这一条**技术上成立**。但:(a) 只影响响应体格式(丢失 `{"ok": false, ...}` 信封),不是安全问题;(b) "带 traceback 的 500"是臆测,Quart 非 debug 模式只返回通用 Internal Server Error,仓库中没有任何证据显示 AstrBot 以 debug 模式运行;(c) 即便包进 try,`response_from_exception` 也只是把同一个错误换个外壳返回,实际收益是格式一致性而非防泄漏。
|
||||
|
||||
四、残留的真问题与原文定性不同
|
||||
真正值得修的是"**只读 GET 也跑一遍 config bootstrap 并 upsert provider/route**"(node_routes.py:328 + model_provider_bootstrap.py:68,79),这是**已授权用户**的每请求性能/副作用问题,与鉴权顺序无关——把 `require_write` 前移一行也解决不了它。注意默认 `config.yaml`(generation.provider 的 base_url/model_id/route_name 均为空)会在 bootstrap.py:49-51 因 `missing` 直接 continue,只剩 `list_routes()` 读操作,写副作用仅在真实配置好的部署里出现。
|
||||
|
||||
综上:标题与 P0/P1 级的"未授权"框架站不住脚,判定为误报;剩下的"构造放进 try / 只读接口不该跑 provider 同步"属于 P3 级健壮性与设计清洁度整改,且后者应作为独立的性能发现单独提出。
|
||||
|
||||
### 推翻 #5
|
||||
- **定位**:`backend/services/model_provider_runtime.py:285(代码定位属实,但影响判定错误)`
|
||||
- **复核意见**:一、代码事实核对(部分属实):`backend/services/model_provider_runtime.py:285` 确实是 `resolved = self.model_provider_service.resolve_route(route_name)`,其后 `provider = resolved.get("provider") or {}` 直接进入 `resolve_secret_value(...)`,没有 provider_type 判断;对照的 `:131-136` 与 `:200` 也确如描述。行号与代码文本对得上,不是幻觉。但"与同文件其他两处不一致"被夸大了:`_structured_text_callable_for_single_route(:196)` 同样是 `resolve_route(route_name)` 不带 modality,且全库 model_routes 表只存在 `image_generation` / `vision_recognition` 两种 modality(`model_provider_bootstrap.py:75,245`),"结构化 callable 不传 modality"是这一族函数的既有写法,真正唯一缺失的只有 provider_type 一道门。
|
||||
|
||||
二、"安全审核静默绕过"这一条是彻底错误的,方向恰好相反。`backend/services/prompt_governance_service.py:356-366`:
|
||||
```
|
||||
if self.reviewer is None or not bool(self.config.get("enabled", False)):
|
||||
return {"status": "not_configured", "action": "allow", ...}
|
||||
try:
|
||||
result = dict(self.reviewer({...}))
|
||||
except Exception:
|
||||
return {"status": "review_failed", "action": "quarantine", ...}
|
||||
```
|
||||
也就是说,`review_with_fallback(:271)` 抛出的 RuntimeError 会被上游捕获并**降级为 quarantine(fail-closed)**,`generation_service.py:966-971` 随后把该图标记 `quarantined=True` / `gallery_visibility="restricted"` 并放进 `restricted_images`,绝不会当作放行。发现里"上层若把审核不可用当放行即静默绕过"的假设在本仓库不成立。
|
||||
|
||||
更关键的是,如果按发现建议补上 modality 与 provider_type 前置校验,`_structured_vision_callable_for_single_route` 会返回 None → `structured_vision_callable` 返回 None → `node_routes.py:345-348` 得到 `image_moderation_callable = None` → `ImageModerationService.reviewer is None` → 走 `{"status": "not_configured", "action": "allow"}`,**全部图片直接放行**。即:现状的宽松解析是 fail-closed,而所谓的"修复"才会制造真正的审核静默绕过。安全论证被写反了。
|
||||
|
||||
三、可达性也被高估。`config.yaml:120-122` 中 `prompt_governance.image_moderation.enabled: false`、`model_route: ""`,`node_routes.py:344-348` 对空路由直接不构造 callable,功能默认关闭。要触发 modality 串号,还必须管理员在 `image_generation` 和 `vision_recognition` 两个 modality 下配置**同名**路由(bootstrap 的 `_config_route_id` 以 modality 为前缀,同名跨模态是被设计允许的),此时 `model_provider_repository.py:266` 的 `ORDER BY route.priority ASC, route.route_id ASC` 在优先级相同时会让 `route_config_image_generation_*` 胜出。要触发 provider_type 问题,还需管理员在设置页把适配器类型选成"自定义 HTTP"(SettingsPage.vue 的 select 仅 openai_compatible / custom),而 custom 适配器在 `_image_provider_from_resolved(:79-80)` 里本来就返回 None、连生图都不可用。两个前提都是明确的管理员误配。
|
||||
|
||||
四、真实残余影响只有一条:上述误配下每张图会被误判为 quarantine(可用性问题),且图片 metadata 里会留下 `image_moderation.status = "review_failed"`,可诊断、可回溯,既不泄密也不绕过安全。综上:定位属实、影响与严重度判定错误,按"安全审核绕过"定级不成立,最多算 P3 级的一致性/健壮性小瑕疵,且修复时必须同时处理"reviewer 为 None 即放行"的语义,否则会引入比原问题更严重的缺陷。
|
||||
|
||||
### 推翻 #6
|
||||
- **定位**:`database/db_helper.py:159-171`
|
||||
- **复核意见**:代码事实属实但影响链条不成立,按描述的缺陷判为误报。\n\n1) 事实核对通过:database/db_helper.py:159-171 与证据片段逐字一致,`conn = sqlite3.connect(db_path, timeout=30.0)` 后只有 `PRAGMA foreign_keys = ON` 和 `PRAGMA busy_timeout = 30000`;全仓库 backend/core/database/tests 内 grep `journal_mode` 零命中,确实未启用 WAL。BEGIN IMMEDIATE 的两处行号(workflow_round_repository.py:313、:815)也对得上。\n\n2) SQLite 锁语义被说错。rollback journal 模式下 BEGIN IMMEDIATE 只拿 RESERVED 锁,RESERVED 不阻塞读者(读者继续持 SHARED 读原始 db 文件,写者脏页在 page cache/journal 中),只有 commit 瞬间升级 PENDING/EXCLUSIVE 才短暂挡读。"写事务持有 RESERVED/EXCLUSIVE 锁会阻塞全库所有读"不成立。\n\n3) 所谓"长事务"里没有任何慢 I/O。通读 confirm_candidate_atomic(database/repositories/workflow_round_repository.py:801-1131)全文,事务内只有本地 SELECT/UPDATE/INSERT(如 `UPDATE workflow_round_candidate_pool SET is_final = 0 ... WHERE round_id = ?`、`INSERT INTO workflow_history (...)`),配合 `datetime.now(timezone.utc)`、`uuid4()`、json 序列化,没有 provider 调用/网络/文件 I/O;get_consistent_round_snapshot(:300-354)是 3 条 SELECT 后立即 `conn.commit()`。事务寿命毫秒级,与 30s busy_timeout 相差约 4 个数量级,"provider 调用稍慢就 30s 超时"无代码依据。\n\n4) 声称的并发场景是虚构的。grep 全仓库,confirm_candidate_atomic 唯一调用方是 backend/services/workflow_round_service.py:694(用户确认候选的 API),get_consistent_round_snapshot 唯一调用方是 :473 create_next_round,二者均为交互式单用户动作;而 chat_workflow_service.py:216 的 4 线程提交的是 `executor.submit(self.generate_node, str(node["node_id"]), chat)` → `nodes/{id}/generate` 链路,根本不会进入 confirm_candidate_atomic。"任一线程进入 confirm_candidate_atomic 阻塞其余 3 线程"不可能发生。\n\n5) except 引用不准且不相关。真实位置是 generation_service.py:1865-1866 与 1887-1888(:1890 是 `"generation.node_failed"` 事件名,不是 except),且两处都在 `_record_generation_failure` 内,仅在生成已失败后的失败记录路径执行,不覆盖正常写入路径。\n\n6) 另佐证:image_repository.create 等均为 connect→execute→commit→close 的短连接模式(database/repositories/image_repository.py:44-48),generation_service 自身不持有 connection 跨越 provider 调用;仓库内无任何 `database is locked`/OperationalError 处理或文档记录,无该问题实际发生的痕迹。\n\n结论:开启 WAL 仍是合理的低优先级调优(提升并发读写吞吐、减少 fsync),但不构成所描述的"生成静默失败"级缺陷,故降级为 P3 并判定该发现站不住脚。
|
||||
|
||||
### 推翻 #7
|
||||
- **定位**:`backend/services/generation_service.py:1869-1886(残留的弱化问题:check-then-act 未用 update_node_if_status)`
|
||||
- **复核意见**:代码片段本身不是幻觉,但这条发现的**因果链和影响是编造的**,且完全漏掉了服务层已有的合并守卫。
|
||||
|
||||
**1. 代码确实存在(唯一成立的部分)**
|
||||
`database/repositories/workflow_repository.py:298-318` 的 `update_node` 和 `:154-178` 的 `update_workflow` 确实是整列覆盖 `metadata_json = ?`,无 merge/版本号。行号对得上。
|
||||
|
||||
**2. 声称的影响路径在类型上不可达 —— 这是决定性的反驳**
|
||||
发现称"`generation_service._prepare_quick_character` 用旧快照 `update_workflow`,把 `confirm_candidate_atomic` 写的 `stage_inputs` 抹掉"。但这两条路径永远不会碰同一行工作流:
|
||||
|
||||
`backend/services/generation_service.py:612` 只有 `is_quick_character_node(workflow, node)` 为真才进入 `_prepare_quick_character_context`,而 `backend/services/quick_character_consistency.py:49-53`:
|
||||
```python
|
||||
def is_quick_character_node(workflow: Any, node: Any) -> bool:
|
||||
return (
|
||||
str(getattr(workflow, "workflow_type", "") or "").strip() == "character_fast"
|
||||
and str(getattr(node, "node_key", "") or "").strip() in QUICK_CHARACTER_TARGETS
|
||||
)
|
||||
```
|
||||
即该路径**只作用于 `character_fast`**。而回合/候选确认体系(`stage_inputs`/`branch_state`/`character_execution` 的写入者)在 `backend/services/workflow_round_service.py:1130` 与 `:147` 被硬性拒绝非渐进类型:
|
||||
```python
|
||||
if workflow.workflow_type != "character_gradual":
|
||||
raise ApiError(..., {"workflow_id": workflow.workflow_id, "workflow_type": workflow.workflow_type})
|
||||
```
|
||||
`character_fast` 工作流根本不存在 `stage_inputs`,"确认了候选图但下一节点拿不到上游图"的症状无法由此产生。
|
||||
|
||||
**3. "用更早读到的快照"这句是事实错误**
|
||||
`generation_service.py:1145-1149` 恰恰是在锁内**重新读取**,紧接着 :1246 写回,中间没有跨请求的陈旧快照:
|
||||
```python
|
||||
lock_entry.lock.acquire()
|
||||
try:
|
||||
current_workflow = self.workflow_service.get_workflow(workflow.workflow_id).workflow
|
||||
metadata = dict(current_workflow.metadata or {})
|
||||
```
|
||||
而且 :1246 的 `update_workflow` 只在 `else`(尚未 managed,即批次首次初始化)分支执行,二次进入走 `managed` 分支根本不写。
|
||||
|
||||
**4. 服务层存在被完全忽略的合并守卫**
|
||||
`backend/services/workflow_service.py:234` 先 `before = self.get_workflow(workflow_id).workflow`,随后 `:268-275` 强制走 `_normalize_workflow_metadata`。该函数 `:1027-1031` 与 `:1058-1068`:
|
||||
```python
|
||||
if workflow.workflow_type == "character_gradual" and not allow_character_execution_update:
|
||||
if "character_execution" in current_metadata:
|
||||
normalized["character_execution"] = current_metadata["character_execution"]
|
||||
...
|
||||
if workflow.workflow_type == "character_gradual":
|
||||
if isinstance(current_metadata.get("branch_state"), dict):
|
||||
# Clients edit only the active projection. Sibling branch
|
||||
# snapshots are server-owned and must survive stale PUTs.
|
||||
normalized["branch_state"] = current_metadata["branch_state"]
|
||||
```
|
||||
也就是说,发现点名的 `branch_state / character_execution / completed_node_ids` 恰恰是**从新鲜读取的 `before` 强制回填**的,调用方传入的整包 metadata 覆盖不掉它们。仓储层的"整列覆盖"在这几个键上已被服务层消解。
|
||||
|
||||
**5. 写入方本身是原子的,且仓储已提供 CAS 变体**
|
||||
`workflow_round_repository.py:812-818` 的 `confirm_candidate_atomic` 用 `BEGIN IMMEDIATE`(sqlite)/ `FOR UPDATE`(postgresql)在同一事务内读 + 写 `:1112-1120`,本身无丢更新。仓储也已经有 CAS 版本 `update_workflow_if_status`(`workflow_repository.py:180-231`,`cursor.rowcount` 判定)和 `update_node_if_status`(`:324` 起),并非"只靠进程内锁"。
|
||||
|
||||
**残留的、被大幅夸大后剩下的真实点**
|
||||
`generation_service.py:1869-1886` 的失败回写确实是 check-then-act 却用了普通 `update_node` 而非同文件仓储已有的 `update_node_if_status`,理论上存在窗口。但:它包在 `try/except Exception: pass` 内(:1868/:1887),守卫条件为 `last_task_id == task.task_id and node.status in {"queued","running"}`,最坏后果只是某个节点的 `generation_failure` 诊断字段被覆盖,不会破坏工作流状态机。这最多是 P3 的一致性收尾建议,与原发现"工作流状态机真身被抹掉 / 下一节点拿不到上游图"的 P0/P1 级描述完全不是一回事。
|
||||
|
||||
结论:标题所述的"丢更新导致确认后拿不到上游图"站不住脚,判定误报。
|
||||
|
||||
### 推翻 #8
|
||||
- **定位**:`frontend/standalone-web/src/App.vue:6126`
|
||||
- **复核意见**:代码确实存在(App.vue:6126 的 `const instructions` 表、character_workflow_service.py:280 的 `fast = {`,行号完全对得上,非幻觉)。但该发现的**核心影响与一半前提都不成立**,判为误报,仅残留一个 P3 级 DRY 小问题。
|
||||
|
||||
**1)「前端把 _FIELD_ALIASES 重抄一遍」——事实错误。**
|
||||
前端 `quickCharacterIdentityFields()`(App.vue:6100)产出的是**原始字段值**,键名恰好是后端别名表能识别的别名,并作为 `identity_fields` 随 payload/metadata 上传。这正是后端**明文定义的输入契约**,`build_identity_lock()`(quick_character_consistency.py:56-68)把它们列为显式数据源:
|
||||
```python
|
||||
sources = [
|
||||
_record(profile_metadata.get("questionnaire")),
|
||||
_record(profile_metadata.get("identity_fields")),
|
||||
profile_metadata,
|
||||
_record(request_metadata.get("identity_fields")),
|
||||
_record(payload.get("identity_fields")),
|
||||
_lock_fields(payload.get("identity_lock")),
|
||||
]
|
||||
```
|
||||
别名归一、`_normalize_gender`/`_normalize_age_group`、缺省推断、canonical 字段集、锁文案与 `identity_lock_hash` **全部仍在后端**。前端没有复制任何一张别名表。
|
||||
|
||||
**2)「身份锁在前端拼、四联图一致性不可复现」——直接被推翻。**
|
||||
generation_service.py:691 对**每个** quick-character 节点无条件套用服务端身份锁,代码注释明写此意图:
|
||||
```python
|
||||
# Direct mode intentionally bypasses LLM rewriting, but it must
|
||||
# never bypass the immutable server-owned character identity lock.
|
||||
prompt_expansion = _locked_quick_character_prompt_expansion(...)
|
||||
```
|
||||
其内部 `append_identity_lock(base_prompt, quick_context["identity_lock"])`,而锁文案(`_identity_prompt`,:180-190)是:
|
||||
```
|
||||
MANDATORY CHARACTER IDENTITY LOCK; depict the same individual in every image in this quick-character batch; do not change gender presentation, apparent age, species, ancestry, skin tone, facial identity, hair, eyes, body build, distinctive features, or core outfit
|
||||
```
|
||||
前端 quick_avatar 少写的「keep identity consistent」这几个词,被这条强度高出一个数量级的强制锁**完全覆盖**。且 `identity_lock_hash()` 对 canonical JSON 做 sha256,一致性是**确定性可复现**的——恰恰与「不可复现」的断言相反。
|
||||
|
||||
**3)「prompt 治理会被前端拼串绕过」——错误。**
|
||||
`_govern_prompt()`(:1456)显式读取前端串:`original = _optional_text(payload.get("user_prompt") or payload.get("prompt") or payload.get("prompt_patch")) or ...`,随后审核(moderation)、路由裁决、`route.allowed` 为假时抛 `VALIDATION_FAILED` 阻断,**全部照常作用于前端串**。`prompt_processing_mode:"direct"` 只跳过 LLM 翻译/改写,而这是任何调用方都能传的显式开关,与本条「指令表重抄」无因果关系。
|
||||
|
||||
**4)「前端触发 vs 后端自身触发产生不同提示词」——缺乏第二条路径。**
|
||||
`_step_instruction()` 只被 `_node_prompt()` 调用,而 `_node_prompt()` 仅在 `_execute_sequenced`/`_execute_unsequenced`(:123、:201)中用于**准备 node.prompt**,并不存在一条为 quick 四联图独立出图的后端路径。且在非 direct 模式下,`prompt_expansion_service.merge_prompt_sections` 同时并入 `{"parts": [node.prompt]}` 与 `_payload_parts(payload)`(含 prompt_patch),后端指令是**叠加而非被替换**。
|
||||
|
||||
**结论**:真实残留问题仅为「4 条短指令字符串在前后端各写一份、措辞已漂移」的可维护性瑕疵,属 P3-轻微。所声称的身份一致性失效、治理被绕过、行为不可复现均不成立。
|
||||
|
||||
### 推翻 #9
|
||||
- **定位**:`backend/services/workflow_round_service.py:1544 (调用点 163);core/astrbot_provider_bridge.py:344 (调用点 278);backend/services/advanced_style_set_service.py:4288 (调用点 1537)`
|
||||
- **复核意见**:代码片段本身抄写无误、行号对得上,但"18 次"和三条声称的影响全部站不住脚。
|
||||
|
||||
(1)计数错误:真实源码树 `grep -rn "def _string_list" --include=*.py backend core engines` 只有 17 处;多出来的是 `.tmp/deploy-1.0.35/`、`.tmp/deploy-clean-1.0.36/` 等构建产物快照里的重复文件,不是源码。
|
||||
|
||||
(2)"把逗号分隔的 tags 传给 workflow_round_service 版本会得到空列表"——该调用路径不存在。workflow_round_service.py 全文只有一处调用:
|
||||
source_candidate_ids = _string_list(payload.get("source_candidate_ids"))[:3] # 第 163 行
|
||||
处理的是内部 payload 里的候选 ID JSON 数组,用于 optimization_source_candidate_ids / source_candidate_id,tags 永不经过此处。同理 prompt_expansion_service.py:257 全文只用于第 109 行的 selected_draft_image_ids;generation_service.py:2417 只用于 1462 行 locked_terms 和 2250 行 reference_image_uris——均无逗号字符串来源。
|
||||
|
||||
(3)"prompt 片段顺序在 advanced_style_set_service 与 astrbot_provider_bridge 之间不可预测"——两者不处理同一个值。bridge 唯一调用是 `tags=_string_list(payload.get("tags"))`(第 278 行,视觉 provider 的 JSON);advanced_style_set 的调用全部是 representative_source_ids / comparison_source_ids / 反馈计划的 increase|decrease|remove|preserve / 自己那份 tags。prompt_parts 这个字段根本不经过任何一个 _string_list。
|
||||
|
||||
(4)不存在"跨 service 流转":`grep "import _string_list|from ... import ..._string_list"` 零结果,17 个实现全部是下划线私有、无一被跨模块导入。每个调用点都是在本模块自己的信任边界上对刚解析的 dict 做一次本地归一化,而非接力传递已归一化列表,因此不同实现之间不会互相污染。
|
||||
|
||||
(5)唯一真实的不一致:VisionRecognitionResult.tags 有三个构造点——engines/vision_provider.py:357(sorted)、core/astrbot_provider_bridge.py:278(sorted)、advanced_style_set_service.py:1537(dict.fromkeys 保序)。三者中两者一致,第三者顺序不同。但下游消费(material_service.py:472 generated_tags、advanced_style_set_service.py:1765 "tags": recognition.tags 等)只把 tags 当元数据集合存储/展示,无任何依赖顺序的逻辑,影响是装饰性的。
|
||||
|
||||
综上:DRY 违规客观存在、值得统一收敛,但数据损坏 / 静默空列表 / 顺序不可预测三条影响均无可达路径,P1 定级被严重夸大,实际为 P3 可维护性异味。
|
||||
|
||||
### 推翻 #10
|
||||
- **定位**:`tests/(测试目录整体),非 backend/route_registry.py:1`
|
||||
- **复核意见**:【结论:误报 / 不成立】原始统计数字能复现,但定位、证据与影响描述三处均不成立。
|
||||
|
||||
一、定位是伪造的。`backend/route_registry.py:1` 是文件 docstring `"""Route registry manifest for AstrBot Web API mounting."""`。整个文件(377 行)是一张纯声明式的 RouteSpec 清单加 `route_manifest()` / `assert_unique_routes()` / `assert_known_permissions()` 三个工具函数,代码本身没有任何缺陷。所谓"缺陷"是 `tests/` 目录的属性,不是这个文件的属性。把测试债挂到一个正确无误的清单文件第 1 行,不构成一条代码缺陷。
|
||||
|
||||
二、最有杀伤力的那条证据是事实错误。发现称 storage_routes 是"签名 URL / 文件下发,直接决定前端不能看到本地绝对路径这条安全约束"。实读 `backend/routes/storage_routes.py`,全文只有两个 handler:`get_storage_status` 和 `migrate_storage`;registry 里也只挂了两条(route_registry.py:167-168):
|
||||
```
|
||||
RouteSpec("GET", "storage/status", "...storage_routes.get_storage_status", "read"),
|
||||
RouteSpec("POST", "storage/migrate", "...storage_routes.migrate_storage", "config"),
|
||||
```
|
||||
它既不下发文件也不签 URL。签名与取流在 media_routes(route_registry.py:169-173,`media/sign`、`media/fetch`),是另一个模块。旗舰级安全论据属于臆造。
|
||||
|
||||
三、"路由层的参数校验与权限装饰完全裸奔"是假的。所有被点名的"高危未测模块"每个 handler 首行都显式调了 `core.security` 的守卫:
|
||||
- round_routes.py:33/55/71/88/108/128 → `require_authenticated(ctx)` / `require_write(ctx)`
|
||||
- data_backup_routes.py:11/15/23/27 → 四个 handler 全部 `require_config_manager(ctx)`
|
||||
- settings_routes.py:23/36 `require_authenticated`,50/64/78/91/104/118/133/147/161 共 9 处 `require_config_manager`
|
||||
- integration_routes.py:32/47 `require_authenticated`,63/77 `require_config_manager`
|
||||
- media_routes.py:26/68/86/107 `require_authenticated`
|
||||
core/security.py:17-24 的 `require_permission` 会先 `require_authenticated` 再校验 `ctx.has_permission(permission)`,不通过直接抛 `ApiError(FORBIDDEN)`。守卫齐整存在,谈不上"裸奔"。storage_routes 自身同样有 `require_authenticated` / `require_config_manager`。
|
||||
|
||||
四、度量方法系统性低估。用 endpoint 字面量全文 grep 会漏掉直接 import handler 的测试。我实测:endpoint 字面量命中 33,而 handler 函数名命中 50,模块名命中 8(非 7)。实证例子:tests/test_character_workflow_progression.py:6 `from backend.routes.node_routes import generate_node, retry_node`;tests/test_generation_node_completion_guard.py:6 导入 `mark_node_completed`;tests/test_profile_delete_route.py:12 走 adapter 的 `resolve_route` 断言 `handler_path == "backend.routes.profile_routes.delete_profile_via_post"`;tests/test_profile_card_finalize.py:290 与 test_workflow_generation_cross_review.py:9 直接对 ROUTES 做清单断言。19.9% 是下界而非真实覆盖率,要给结论必须跑 coverage.py。
|
||||
|
||||
五、严重度严重夸大。这是一条测试债观察,不是缺陷:没有指出任何真实 bug、不可达守卫或权限漏洞,当前行为没有任何一处是错的。它描述的是"未来重构可能没人拦"的假设性风险。真要保留,合理形态是一条 P3 改进建议(例如补一个遍历 ROUTES、断言每个 handler 源码内出现 require_* 的元测试),而非现在这条带伪造定位和伪造安全论据的发现。
|
||||
|
||||
### 推翻 #11
|
||||
- **定位**:`INSTALL.md(发布包白名单/最小运行时清单)+ frontend/standalone-web/vite.config.ts:12`
|
||||
- **复核意见**:代码引用属实但结论站不住脚,判定为误报(最多是 P3 流程 nit)。
|
||||
|
||||
一、引用的代码确实存在,行号完全对得上:
|
||||
- `frontend/standalone-web/vite.config.ts:11-15`:`base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/"` / `outDir: resolve(rootDir, "../../web")` / `emptyOutDir: true`
|
||||
- `frontend/plugin-page/vite.config.ts:11-15`:`base: "./"` / `outDir: resolve(rootDir, "../../pages/imagestudio")`
|
||||
- `backend/services/web_hosting_service.py:14-15`、`manifest()` 只判断 `(dir/"index.html").exists()`
|
||||
- `.gitignore:16` 只有 `frontend/**/dist/`
|
||||
- `git ls-files web/ pages/` = 38 个文件,`git log -- web/assets` = 80 次提交
|
||||
以上事实核对无误,不是幻觉。
|
||||
|
||||
二、致命反驳:这两个目录不是"误提交的编译产物",而是**被文档明确定义的发布负载**,必须入库。
|
||||
`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 步骤**。若按发现的建议把 `web/` `pages/` 加进 .gitignore,`WebHostingService._resolve` 会直接抛 `ErrorCode.RESOURCE_NOT_FOUND, "web asset not built"`,插件页面全线不可用。.gitignore 忽略 `frontend/**/dist/`(中间产物)而保留这两个目录,恰恰是正确的区分,不是遗漏。
|
||||
|
||||
三、"两份重复 dist"这一核心指控不成立。两份构建的 `base` 不同且必须不同:`web/index.html` 里是绝对路径 `src="/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/assets/index-CvjPX4dT.js"`,`pages/imagestudio/index.html` 里是相对路径 `src="./assets/index-Dp4kkpJ0.js"`。两者挂载于不同 URL 根(`PLUGIN_PAGE_URL = "/plugin/imagestudio"` vs `STANDALONE_WEB_URL = "/api/v1/..."`),一份产物物理上无法同时服务两个挂载点。`plugin-page/src/App.vue` 复用 `standalone-web/src/App.vue` 正是为避免真正的重复。`DEVELOPMENT.md:57` 与 `INSTALL.md` 都说明了两者定位(`pages/imagestudio/` 是正式插件页,`web/` 是兼容产物)。
|
||||
|
||||
四、"必须构建两次、漏一次"的风险已有机制消解:`frontend/package.json` 提供 `"build": "npm run build:plugin && npm run build:web"`,`INSTALL.md:223-224` 与 `DEVELOPMENT.md:72-73` 的验证清单都要求两条一起跑。
|
||||
|
||||
五、影响被显著夸大,实测数据不支持"2MB 噪音淹没 diff":
|
||||
最近 5 次 dist 提交的实际 stat 为 `24 files changed, 59 insertions(+), 69 deletions(-)`(878f1f6)、`24 files changed, 37 insertions(+), 27 deletions(-)`(2dbf90b)。git 的重命名检测把内容哈希改名识别成 `web/assets/{index-CumvEEtc.js => index-CvjPX4dT.js}`,压缩产物是单行文件,因此每次只有几十行 diff,不是 2MB。
|
||||
"git 累积大量永不复用的 blob"归因也错了:`git count-objects -vH` 显示 size-pack 44.03 MiB,而 `git ls-files release/` 有 20 个 ZIP、仅当前树就占 37.0 MiB——仓库体积的主因是被跟踪的 release 包,不是 web/assets。
|
||||
|
||||
六、残余的真实问题很小:确实没有 CI 校验产物新鲜度(仓库根本没有 `.github/workflows`),历史上有 24 次只更新 `web/assets`、3 次只更新 `pages/imagestudio/assets` 的提交。但 `manifest()` 从未声称做版本一致性校验,它只是"是否已构建"的状态位;`_resolve` 另有 `candidate != root and root not in candidate.parents` 的路径逃逸防护,功能上没有可达缺陷。把 `fix: recover material library after stale asset token`(3edec9a)当作双 dist 错位的症状也属牵强——该提交同时改了 `frontend/standalone-web/src/App.vue`、`AdvancedMaterialImportPage.vue` 与两个 assets 目录,是源码修复带构建,不是漏构建导致的错位。
|
||||
|
||||
综上:代码引用真实,但"不该提交产物"的前提与文档化的发布模型直接冲突,"两份重复"是必需的双挂载,量化影响与实测相差一个数量级。判定 refuted=true;若保留,只能降为 P3(建议增加构建新鲜度校验脚本),且位置应落在 INSTALL.md/发布流程而非 vite.config.ts:12。
|
||||
|
||||
### 推翻 #12
|
||||
- **定位**:`frontend/standalone-web/src/App.vue:4575-4582;backend/services/event_stream_service.py:22-32`
|
||||
- **复核意见**:代码事实部分属实(行号对得上),但**因果链在关键一步断裂,声称的影响不成立**,判定为误报。
|
||||
|
||||
一、代码确实存在,无幻觉
|
||||
`backend/services/event_stream_service.py:22-32` 确实只有 `event_type`/`limit`,没有 `after_event_id`:
|
||||
```python
|
||||
def recent_events(self, *, event_type: str | None = None, limit: int = 50) -> dict[str, Any]:
|
||||
events = self.event_bus.history(event_type)
|
||||
normalized_limit = _limit(limit)
|
||||
selected = events[-normalized_limit:]
|
||||
```
|
||||
`App.vue:4575-4577` 也确实是那段 `slice(previousIndex >= 0 ? previousIndex + 1 : -1)`。
|
||||
|
||||
二、决定性反驳:全仓库事件类型只有 `generation.` / `workflow.` 两个前缀,OR 判定不可能因丢事件而翻假
|
||||
我把 `backend/services/` 下所有 `_publish(` / `event_bus.publish(` 的首参字面量全量抽取,共 17 个,**无一例外**:
|
||||
`generation.node_cancelled / node_completed / node_failed / node_queued / node_running / task_created / task_deleted / task_status_changed / task_updated`、`workflow.branch_created / created / node_created / node_material_bindings_updated / node_status_changed / status_changed / updated / node_updated`(含 `workflow_node_material_service.py:209`、`generation_job_retry_service.py:269,278`、`generation_service.py:1417,1426` 这些间接发布点)。
|
||||
|
||||
而判定逻辑是 `.some()` 的 OR 归约:
|
||||
```js
|
||||
const generationChanged = eventTypes.some((t) => t.startsWith("generation."))
|
||||
const workflowChanged = eventTypes.some((t) => t.startsWith("workflow."))
|
||||
```
|
||||
既然总线上**每一条**事件都满足这两个谓词之一,那么退化到 `slice(-1)` 只留 1 条时,`generationChanged || workflowChanged` **恒为 true**。发现里"eventTypes 只有一个元素 → 基于 1/20 样本判定 → 该刷的不刷"是错的:把 20 条样本砍到 1 条,无法把一个所有候选都为真的 OR 归约翻成假。生成爆发期最后一条几乎必然是 `generation.task_updated`/`task_status_changed`,`generationChanged` 为真,`loadJobs()`/`loadDashboard()` 照常触发。
|
||||
|
||||
三、刷新是全量重取而非增量应用,丢中间事件不产生状态失配
|
||||
`loadJobs()` / `loadDashboard()` / `loadWorkflowRoundDetail()` 都是重新 GET 全量状态,事件只当"触发器"用。因此丢掉 19 条冗余触发器不会让 UI 停在旧状态——只要有 1 条触发,取回的就是最新完整状态。
|
||||
|
||||
四、workflow 轮次面板另有一条与事件流完全无关的 4 秒自续轮询,直接推翻"生成完了界面不动的结构性来源"
|
||||
`App.vue:6999-7008`:
|
||||
```js
|
||||
function scheduleWorkflowRoundPolling(detail = selectedWorkflowRound.value) {
|
||||
stopWorkflowRoundPolling()
|
||||
if (!detail || !workflowRoundIsActive(detail.round.status) || document.hidden) return
|
||||
workflowRoundPollTimer = window.setTimeout(() => { ... void loadWorkflowRoundDetail(roundId, true) }, 4000)
|
||||
}
|
||||
```
|
||||
它在轮次入队时就被武装(`App.vue:8538`,紧跟 `已加入生成队列` 分支),并在每次 `loadWorkflowRoundDetail` 成功后自续(`App.vue:7017`),轮次一旦不再 active 才停。另有 `reconnectBackendWhenVisible()`(`App.vue:4471-4477`)在页面重新可见时强制刷新活动轮次。即使事件流一条都不处理,轮次面板也是 4 秒一刷。
|
||||
|
||||
五、爆发结束后必然自愈
|
||||
`lastEventStreamId` 每轮都推进到 `newest`;爆发一停,下一次 5 秒轮询窗口内新增 <20 条,`findIndex` 就能命中锚点,恢复精确增量。不存在"直到用户手动刷新"的持久卡死。
|
||||
|
||||
六、"窗口太小"也不是接口设计缺陷
|
||||
`_limit` 上限是 200(`min(max(limit,1),200)`),总线 `EventBus(history_limit=500)`。前端自己传的 `{ limit: 20 }`,要扩窗口改一个数字即可,不需要引入游标。
|
||||
|
||||
七、真正站得住的只有边角问题
|
||||
(1) 接口确实无游标;(2) `body`/`content_type` 预渲染的 SSE 文本被前端丢弃,属白费序列化——但每 5 秒 20 条小 payload,量级可忽略;(3) `slice(..., -1)` 这个魔数兜底写法确实不优雅,应改成 `previousIndex >= 0 ? slice(previousIndex+1) : slice()`(退化时取全窗口而非 1 条)。这些合计至多 P3 代码质量,与原发现声称的"事件静默丢失 → UI 停滞的结构性来源"不是一回事。
|
||||
|
||||
### 推翻 #13
|
||||
- **定位**:`frontend/standalone-web/src/App.vue:3073-3077 / 3136-3140(仅为文案/tone 层面的一致性问题)`
|
||||
- **复核意见**:代码本身不是幻觉,但"声称的影响"链条站不住脚,判为误报。
|
||||
|
||||
一、引用的代码确实存在,行号对得上:
|
||||
- backend/route_registry.py:22-27 确为 `"retry": {... "required_permission": "can_retry_tasks", "required_permissions": ["can_write", "can_retry_tasks"] ...}`;
|
||||
- core/security.py:31-33 确为 `def require_task_retry(ctx): require_write(ctx); require_permission(ctx, "can_retry_tasks")`;
|
||||
- App.vue:2786 `const canRetry = Boolean(permissions?.can_retry_tasks)`,3076 与 3139 两处 retry 卡片确实只判 `canRetry && !selectedNodeWriteLocked && !workflowNodeActionExecuting`;3372-3373 队列面板确实是 `canManageQueue = canWrite && canRetry`。
|
||||
|
||||
二、但前提条件在本仓库中不可产生(不可达)。全仓 RequestContext 的构造只有三处非测试路径,没有任何一处能产出"有 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()` —— 要么四个全给,要么一个不给。全不给时 `canRetry` 为 false,卡片就显示"无权限"且 disabled,正是期望行为;
|
||||
- backend/services/chat_workflow_service.py:1160 `permissions={"can_write", "can_retry_tasks", "can_manage_materials"}` —— 同样含 can_write;
|
||||
- backend/services/chat_command_guard_service.py:42 `permissions=set()` —— 空集。
|
||||
bootstrap 的权限来源 backend/services/ui_service.py:24-29 只是逐项透传 `ctx.has_permission(...)`,不会额外派生。也就是说"持有 can_retry_tasks 但无 can_write 的账号"在当前代码里根本造不出来。
|
||||
|
||||
三、即便假设该组合存在,点击路径也有上游守卫,"一律被 require_write 拒为 FORBIDDEN"的描述是错的。App.vue:8092-8094 的 workflowNodeRetry 走 `runSelectedWorkflowNodeGeneration({ retry: true })`,而该函数 8560 行第一件事就是:
|
||||
const blocked = backendWriteBlockMessage(options.retry ? "节点重跑" : "节点生成")
|
||||
if (blocked) { workflowNodeActionError.value = blocked; return false }
|
||||
而 backendWriteBlockMessage(4376-4387)里明确含 `if (!bootstrap.value?.permissions.can_write) return \`${action}需要后端写入权限。\``。所以无 can_write 时前端本地就拦下,根本不会发出 nodes/{id}/retry 或 nodes/{id}/generate 请求,也就没有所谓的 FORBIDDEN 回包。发现描述的核心危害链在此断裂。
|
||||
(唯一未被该守卫覆盖的是 8559 行 `if (isSelectedWorkflowRoundNode.value) return submitSelectedWorkflowRound(options)` 的提前分支,submitSelectedWorkflowRound(8462-)只判 workflowLockedNodeWriteMessage 而不判 can_write;但它打的是 rounds 接口,route_registry.py:92/95 标注为 "write" 而非 "retry",与本条发现主张的 retry 复合权限无关,且同样受前述"权限不可分离"约束。)
|
||||
|
||||
四、严重度被夸大。真正剩下的只是 UI 文案层面的不一致:3073-3074 用 `canRetry ? "可重试" : "无权限"` 作 state/tone,理论上会在一个当前造不出的权限组合下显示乐观文案,按钮点下去也只会得到一句本地提示。另外 App.vue:3818-3821 也是同样的 canRetry-only 写法,说明这是节点级卡片的一贯写法(节点级操作的写权限统一由 backendWriteBlockMessage 兜底),而 3373 队列面板加 canWrite 是因为队列卡片直接调接口、没有同样的兜底函数——这是两类不同上下文,不能据此推断"遗漏"。无安全影响,无越权,无功能故障,最多是 P3 的文案精确性问题。
|
||||
|
||||
### 推翻 #14
|
||||
- **定位**:`frontend/standalone-web/src/features/workflow/workflow-model-route.ts:36-88(代码属实,但所述影响不可达)`
|
||||
- **复核意见**:代码位置属实(前端 36-48 的候选链、59-88 的 assignment 映射,后端 generation_service.py:169-176 / 617-624 / 2022-2045 全部对得上,不是幻觉),但三条"不一致"的结论逐条站不住脚,核心影响不可达。
|
||||
|
||||
【1. "前端多了 round 层" —— 错误,backend 确实有这一层】
|
||||
指控者只看了 generation_service.py,漏了续轮真正的服务。backend/services/workflow_round_service.py:596-597:
|
||||
"model_route": _optional_text(payload.get("model_route"))
|
||||
or _optional_text(parent.prompt_snapshot.get("model_route")),
|
||||
即"本次覆盖 → 父轮次冻结路由",与前端 ["override", …] → ["round", …] 的顺序完全一致。前端 selectedWorkflowRoundFrozenRoute(App.vue:2202-2210)读的正是 detail.round.prompt_snapshot 的 model_route,就是后端这个 parent.prompt_snapshot。round 层是如实镜像,不是前端发明的。
|
||||
|
||||
【2. "少了 image_low 兜底" —— 是刻意设计,且 fail-safe,不会说谎】
|
||||
workflow-model-route.ts:28-31 的注释明写 "Mirrors the server-owned route chain without inventing a frontend default.",第 48 行返回 { route: "", source: "backend" }。这个空值不是被静默吞掉,而是被上游当作硬闸门:
|
||||
- App.vue:8492-8495:if (!persistentParent && !selectedWorkflowModelResolution.value.route) { workflowRoundError.value = "当前节点和后端默认均未提供生图路由…"; return false }
|
||||
- 模板 12929 / 12935-12936::model-status-message 与 :submit-disabled 都绑定 !selectedWorkflowModelResolution.route
|
||||
所以缺 image_low 的后果是"标签显示后端自动 + 禁止提交",而不是显示错误路由。硬编码 image_low 反而会让 UI 声称一个后端可能拒绝的路由(require_resolved_model_route 会抛 MODEL_CAPABILITY_UNCONFIRMED)。
|
||||
|
||||
【3. "快速角色标签说谎 / quick_avatar 查不到分配" —— 不可达,这是本条发现的致命硬伤】
|
||||
该标签链的输入全部来自 selectedWorkflowBackendNode ← activeWorkflowBackendNodes ← selectedQuickProfileLibraryItem.value?.workflowId(App.vue:1768-1775)。而 workflowId 字段只可能是 character_gradual,四处赋值全查过:
|
||||
- App.vue:4943-4954:const detailedWorkflow = availableWorkflows.find(w => w.workflow_type === CHARACTER_WORKFLOW_TYPE),然后 workflowId: detailedWorkflow?.workflow_id;快速工作流被单独放进 quickCharacterWorkflowId 字段。
|
||||
- App.vue:7410-7419:只有 if (workflowType === CHARACTER_WORKFLOW_TYPE) 才调 updateQuickProfileWorkflowLink(7524 写 workflowId);else 分支只写 quickCharacterWorkflowId。
|
||||
- App.vue:9455:workflowId: saved.workflow && isCharacterWorkflow(saved.workflow) ? … : undefined —— 该 saved.workflow 由 quick_profile_service.py:140 创建,workflow_type 为 "quick_profile",isCharacterWorkflow(7533-7535 只认 character_gradual / character_fast)返回 false,故为 undefined。
|
||||
- App.vue:9489:唯一调用点 4873 传入 characterWorkflow = undefined。
|
||||
CHARACTER_WORKFLOW_TYPE = "character_gradual"(App.vue:925)。结论:quick_avatar/quick_bust/quick_stand/quick_sheet 永远不会成为 selectedWorkflowBackendNode,这个 Composer 标签根本不为快速角色流渲染,"UI 显示本次覆盖而后端按 assigned_route 出图"的场景无法构造。
|
||||
|
||||
而且快速角色流有自己独立且正确的解析器 App.vue:6086-6098:
|
||||
return recordString(assignments, "quick_generation") || recordString(generation, "default_model") || selectedImageModelRoute()
|
||||
与后端 _assignment_key 把 quick_* 映射到 quick_generation 完全对齐;且 5813-5815 在其为空时直接 throw "未配置 quick_generation 统一生图路由…",连提交都进不去。
|
||||
|
||||
【4. 实际可达路径下前后端结论完全一致】
|
||||
gradual 工作流的生图节点键(engines/character_flow.py:51-105)只有 headshot / upper_body / lower_body / full_body / turnaround / design_sheet / style_lock,这七个在前端 76-84 与后端 2026-2033 的映射表里逐条相同(都→portrait_generation / halfbody_generation / fullbody_generation ×2 / sheet_generation ×2 / hires_fix)。非生图节点(profile_brief/prompt_plan/material_bind/profile_card)前端返回 ""、后端返回原 node_key 查不到分配,两边同样落到 profile→system,结果一致。后端多出的 questionnaire/preview/virtual_single_image/profile_draft/profile_preview 分支对应的节点类型在 gradual 工作流中不存在。
|
||||
|
||||
【5. 配置键耦合被夸大】
|
||||
App.vue:2234 读 generation.default_model,与后端 backend/routes/node_routes.py:377 的 default_model_route=str(generation_config.get("default_model") …) 是同一个键,当前并无失准。这属于"前端复刻了一份映射表、改键名需两边同改"的可维护性耦合,值得收敛(理想做法是后端在节点/轮次响应里下发 effective_model_route + source),但不是运行期缺陷。
|
||||
|
||||
综上:位置真实,但"优先级相反导致标签说谎"的场景被数据流隔离得不可达,缺 image_low 是刻意的 fail-safe,round 层是对 workflow_round_service.py:596-597 的正确镜像。P0/P1 严重度不成立,仅保留 P3 的重复实现/配置键耦合技术债。
|
||||
|
||||
### 推翻 #15
|
||||
- **定位**:`backend/services/integration_token_service.py:1(若保留,应收窄为“9 个模块零执行”,且必须删除 branch_lineage / workflow_progression 两项)`
|
||||
- **复核意见**:## 判定:误报(方法论无效,核心量化结论与最耸动的子论断均被实测推翻)
|
||||
|
||||
### 1. 该发现的取证方法是「在 tests/ 里 grep 模块文件名字符串」,这不是覆盖率
|
||||
我先复现了它的脚本,结果确实一致(68 个 service,23 个模块名在 tests/ 全文中零出现),类名同样为 0:
|
||||
`IntegrationTokenService 0 / ChatCommandGuardService 0 / DeletionSafetyService 0 / BranchLineageService 0 / WorkflowProgressionService 0 ...`
|
||||
|
||||
但这只证明「测试没有直接 import 这个文件名」,不能证明「零测试」。我随即安装 coverage 7.15.2,对全量套件做了真实行覆盖测量:
|
||||
`python -m coverage run --source=backend/services -m pytest tests/ -q` → **263 passed in 177.79s**。
|
||||
|
||||
### 2. 实测结果:23 个模块中有 8 个被实质性执行,其中 5 个覆盖率 74%~94%
|
||||
```
|
||||
branch_lineage_service stmts=172 covered=160 pct=93%
|
||||
workflow_progression_service stmts= 90 covered= 85 pct=94%
|
||||
prompt_plan_schema_service stmts=147 covered=123 pct=84%
|
||||
material_binding_schema_service stmts=140 covered=104 pct=74%
|
||||
node_injection_template_service stmts= 27 covered= 25 pct=93%
|
||||
model_provider_bootstrap stmts=126 covered= 41 pct=33%
|
||||
reference_binding_mapper stmts= 40 covered= 22 pct=55%
|
||||
chat_session_service stmts= 66 covered= 34 pct=52%
|
||||
```
|
||||
我进一步用 AST 剔除 import/def/class 头部行,只统计**函数体内真实执行的语句**,排除「仅 import 噪音」的可能:
|
||||
```
|
||||
branch_lineage_service body_executed=133
|
||||
prompt_plan_schema_service body_executed= 97
|
||||
material_binding_schema_service body_executed= 84
|
||||
workflow_progression_service body_executed= 67
|
||||
```
|
||||
这是货真价实的行为覆盖,不是导入副作用。
|
||||
|
||||
### 3. 最耸动的那句「同名测试不测同名 service,制造假象」——事实完全相反
|
||||
发现称 `test_workflow_branch_lineage.py`、`test_character_workflow_progression.py` 是「假象」。实测这两个模块恰恰是覆盖率最高的两个(93% / 94%)。原因是它们是**被再导出的 helper 模块**,测试通过前门 service 调用:
|
||||
```python
|
||||
# backend/services/workflow_service.py:10
|
||||
from backend.services.branch_lineage_service import (
|
||||
# backend/services/workflow_node_material_service.py:17
|
||||
from backend.services.branch_lineage_service import workflow_metadata_for_branch
|
||||
# backend/services/character_workflow_service.py:11
|
||||
from backend.services.workflow_progression_service import (
|
||||
# backend/services/image_service.py:11
|
||||
from backend.services.workflow_progression_service import ensure_character_gradual_node_access
|
||||
```
|
||||
而 `test_workflow_branch_lineage.py` 第 6-8 行正是 `from backend.services.character_workflow_service import CharacterWorkflowService` / `workflow_service import WorkflowService`。同名测试**正在**测同名 service,只是走的是调用方入口。把这称为「比明摆着没测试更危险的假象」是对代码的误读,且是本条发现中最不成立的部分。
|
||||
|
||||
### 4. 行数被夸大约一倍
|
||||
被声称的 4579 行中,实质有覆盖的 8 个模块合计约 **2279 行**(356+240+379+408+366+375+69+86),即约一半。真正零执行的只有 9 个模块(api_discovery 351、asset_import 406、contract 30、dashboard 117、deletion_safety 75、history 314、integration 171、integration_token 202、log 300 ≈ **1966 行**),不是 23 个 / 4579 行。
|
||||
|
||||
### 5. 残余的真实内核(但不足以支撑原发现,且非代码缺陷)
|
||||
公允地说,实测确认了三点中的两点:
|
||||
- `integration_token_service` executed=0(129 statements 全未执行)——属实;
|
||||
- `deletion_safety_service` executed=0——属实;
|
||||
- `chat_command_guard_service` 实际是 30%,但 body_executed 仅 4 行,`check_generation` 主体(21-39 行)与 `_daily_count`/`_daily_group_count` 全在 missing 中,行为层面确实未测——这一条方向上成立,但发现写的「零测试」与实测的 30% 不符。
|
||||
|
||||
不过这属于**测试覆盖缺口(过程问题)**,而非可触发的代码缺陷。我通读了 `integration_token_service.py` 全文,鉴权逻辑本身是正确的、无可指摘的:`verify()` 先做插件白名单校验(91-96 行 `if allowed_plugins and normalized_source not in allowed_plugins: raise ApiError(...INTEGRATION_TOKEN_INVALID)`),`_matches_hash` 用 `hmac.compare_digest(_hash_token(token, salt), digest)` 做常量时间比较(175 行),legacy 分支同样是 `hmac.compare_digest`(115 行),salt 用 `secrets.token_hex(16)`,`_previous_token_set` 带过期窗口校验(139-140 行),`_grace_seconds` 有 `min(max(seconds,0), MAX_GRACE_SECONDS)` 上下界钳制。没有任何硬编码比较、时序泄漏或绕过路径。路由层 `backend/routes/integration_routes.py:100/105-107` 也是正常注入。
|
||||
|
||||
### 结论
|
||||
发现的标题(23 个模块 / 4579 行零测试)在实测下**模块数虚高 2.5 倍、行数虚高约 1 倍**,且其重点强调的「同名测试假象」被证明是彻底反向的错误结论。取证手段(grep 模块名)对本仓库这种 helper-被再导出的架构系统性失效。按「不确定即误报」以及「一条发现里过半内容不成立即不成立」的标准,判 refuted=true。若要保留,必须重写为「9 个 service 零执行覆盖,其中 integration_token_service / deletion_safety_service 为安全相关」,严重度 P3(测试债,无已证实缺陷),并删除关于 branch_lineage_service 与 workflow_progression_service 的全部指控。
|
||||
|
||||
### 推翻 #16
|
||||
- **定位**:`backend/services/chat_workflow_service.py:903(唯一绕过 dispatcher 的直连调用,对应 main.py:1134 `/yp 审核`)`
|
||||
- **复核意见**:判定:误报(核心影响链不成立)。
|
||||
|
||||
一、机制本身属实,但只是"潜在"而非"已触发"
|
||||
backend/dto/common.py:29-33 的代码确实存在,行号完全对得上。我本机实测(Python 3.11.15)确认位置参数构造时 `BaseException.__new__` 会填充 args:
|
||||
POS str = "(<ErrorCode.VALIDATION_FAILED: 'VALIDATION_FAILED'>, '内容审核未通过', {'body_preview': 'secret'})"
|
||||
所以"str(exc) 返回元组 repr"这一点我不否认。但这只在 ApiError **作为异常对象本身**流到 f-string 时才有害。
|
||||
|
||||
二、决定性反证:main.py 里根本没有 ApiError
|
||||
`git ls-files "*.py" | xargs grep -ln ApiError` 的结果里**没有 main.py**;`grep -c ApiError main.py` = 0。main.py 那 40 处 `{exc}`(我逐条核对,515/669/1591 等行号确实存在)捕获到的不是 ApiError。
|
||||
|
||||
三、框架层已经消解了它——两道闸门
|
||||
闸门1,backend/routes/common.py:12-16:
|
||||
def handle_request(ctx, callback):
|
||||
try: return success_response(callback(), request_id=ctx.request_id)
|
||||
except Exception as exc: return response_from_exception(exc, request_id=ctx.request_id)
|
||||
`response_from_exception` 走 `exc.to_response()`,用的是 **self.message 字段**而非 str(exc),details 被装进 dict 的 "details" 键。
|
||||
我用脚本遍历了 `backend.route_registry.ROUTES` 全部 166 条路由 / 163 个 distinct handler:**0 个未被包裹**。初筛出的 8 个(start_workflow、archive_profile、get_error_logs 等)经查全部委托给 `_set_workflow_status` / `delete_profile` / `_read_logs`,这些内部都以 `return handle_request(ctx, action)` 收尾。
|
||||
|
||||
闸门2,backend/services/chat_workflow_service.py:1166-1170:
|
||||
@staticmethod
|
||||
def _data(response):
|
||||
if not response.get("ok"):
|
||||
raise ValueError(str(response.get("message") or response.get("error_code") or "ImageStudio 请求失败"))
|
||||
return response.get("data")
|
||||
即 details 在这里被**整体丢弃**,只取 message,且 ValueError 是单个位置参数 → str() 干净。
|
||||
|
||||
端到端实测(模拟含 provider_id/model_id/body_preview 的 ApiError):
|
||||
route response dict: {'ok': False, ..., 'details': {'provider_id':..., 'body_preview': '{"error":{"message":"sk-leak..."}}'}}
|
||||
type reaching main.py: ValueError
|
||||
main.py renders: 错误:生成失败:上游返回错误
|
||||
聊天用户拿到的是干净中文 message,无元组语法、无 details。所谓"中文提示被 Python 元组语法淹没"与"details 推送到群聊"两条影响均不成立。
|
||||
|
||||
四、证据片段有事实错误
|
||||
发现称 engines/image_provider.py:253,289,324 会把 body_preview 塞进 ApiError。实际读该文件:`grep -c ApiError engines/image_provider.py` = **0**。那三处抛的是 ImageProviderError,且 engines/image_provider.py:96-110 定义为:
|
||||
class ImageProviderError(RuntimeError):
|
||||
def __init__(self, message, *, provider_id, status_code=None, error_type="provider_error", details=None):
|
||||
super().__init__(message) # 单参数 → str(exc) 就是 message
|
||||
self.details = details or {}
|
||||
details 是普通属性,永远不进 str()。body_preview 泄漏链完全不存在。
|
||||
|
||||
五、异步推送路径也已加固
|
||||
worker_service.py:230 已经是 `message = _safe_error_message(exc)`,514-534 的实现只保留 message + code + reason/finish_reason/provider/model 白名单提示并截断 500 字。发现说"作者知道坑但聊天路径没复用"——实际是聊天路径用了另一套等效防护(_data 直接丢 details),不需要复用。
|
||||
|
||||
六、唯一残留(远低于所称严重度)
|
||||
chat_workflow_service.py:903 是全仓唯一绕过 dispatcher 的进程内直调:
|
||||
model_reviews = {node_id: self.cross_reviewer_factory().review_node(node_id) for node_id in node_ids}
|
||||
CrossReviewService.review_node 内部经 workflow_progression_service.py:168-172 可抛 ApiError,此时会以元组 repr 落到 main.py:1134 `❌ 审核失败:{exc}`。但:(1) 仅此 1 处,不是 40 处;(2) 该 details 内容为 workflow_id/node_id/node_key/branch_name/required_action/progression_version(见 workflow_progression_service.py:138-167),全是内部 ID,无 provider_id、无 model_id、无 body_preview、无凭据;(3) 同一命令的成功分支 main.py:1132 本来就 `json.dumps(result, ...)[:3000]` 把含 provider_id/model 的完整审核结果打给聊天,该命令设计上就是 verbose 的;(4) 该 ApiError 的 message 是英文 "character workflow node is locked by sequential progression",不存在"中文被淹没"。
|
||||
|
||||
综上:所称 P0/P1 级信息泄漏 + 40 处可用性崩坏为误报;实际残留是 1 处仅显示内部 ID 的观感问题,P3。
|
||||
正在加载…
添加表格
在新工单中引用