diff --git a/.gitignore b/.gitignore index 056ad96..b6161ee 100644 --- a/.gitignore +++ b/.gitignore @@ -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* diff --git a/CHANGELOG.md b/CHANGELOG.md index db0ec87..ace3e34 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/docs/final-release-audit-2026-07-22.md b/docs/final-release-audit-2026-07-22.md new file mode 100644 index 0000000..dfc8067 --- /dev/null +++ b/docs/final-release-audit-2026-07-22.md @@ -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 项后端测试,前端类型/契约/构建通过,但其模型成本权限仍需收紧。 diff --git a/docs/release-readiness-2026-07-27.md b/docs/release-readiness-2026-07-27.md new file mode 100644 index 0000000..b5f6339 --- /dev/null +++ b/docs/release-readiness-2026-07-27.md @@ -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 的冒烟检查。 diff --git a/docs/错题本.md b/docs/错题本.md index 80d5a14..2ec3752 100644 --- a/docs/错题本.md +++ b/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 检查。 diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 01370e4..358d77c 100644 --- a/frontend/package-lock.json +++ b/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", diff --git a/frontend/package.json b/frontend/package.json index 2f904fa..eb2ede3 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "astrbot-plugin-imagestudio-frontend", - "version": "1.0.66", + "version": "1.0.73", "private": true, "type": "module", "scripts": { diff --git a/metadata.yaml b/metadata.yaml index 6899df3..08079b5 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -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" diff --git a/scripts/package_plugin.sh b/scripts/package_plugin.sh new file mode 100644 index 0000000..9dd1355 --- /dev/null +++ b/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" diff --git a/审计/01-总览与架构.md b/审计/01-总览与架构.md new file mode 100644 index 0000000..2f25cdf --- /dev/null +++ b/审计/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 行): + +| 区段 | 行号 | 行数 | 占比 | +|---|---|---:|---:| +| ` + + ``` + 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 = { + 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 塞进
+  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 选项跟着轮次类型走。
diff --git a/审计/findings/B2-后端内部耦合.md b/审计/findings/B2-后端内部耦合.md
new file mode 100644
index 0000000..f8582b9
--- /dev/null
+++ b/审计/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..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
组合根(位置错误)"] + GS["generation_service
2432行/21参数"] + WS["workflow_service
扇入15 扇出14"] + WRS["workflow_round_service
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 个大文件 | diff --git a/审计/findings/C0-测试实跑结果.md b/审计/findings/C0-测试实跑结果.md new file mode 100644 index 0000000..e9d0af6 --- /dev/null +++ b/审计/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)。 diff --git a/审计/findings/C1-后端精简空间.md b/审计/findings/C1-后端精简空间.md new file mode 100644 index 0000000..4906052 --- /dev/null +++ b/审计/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 路由装饰器。 diff --git a/审计/findings/C2-前端精简空间.md b/审计/findings/C2-前端精简空间.md new file mode 100644 index 0000000..1288bdb --- /dev/null +++ b/审计/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 `` 派生类、动态 `: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 查看器直接复用 ``(模板 `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 处)、一句文案 `取消这个素材参考` → `默认不注入这个参考`、多一条 ``。其余包括分组 tab、`TransitionGroup`、"不使用"选项、缩略图渲染全部一致。 +- **代码**(App.vue:12021-12042 与 12672-12693 完全同构): + ```html +
+
+ {{ material.category }}参考 + 选择素材 +
+ {{ activeQuickProfileMaterialPickerCountLabel }} +
+
+ +
+ ``` +- **影响**:约 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( + 'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])', + ) ?? [], + ) + } + ``` + ```ts + // ConfirmDialog.vue + function focusableElements() { + return Array.from( + dialogRef.value?.querySelectorAll( + '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, opts: { + dialogRef: Ref + 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 +
+
↕...
+
...
+ ``` +- **影响**:约 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`(**整个文件没有 `