astrbot_plugin_imagestudio/docs/workflow-secondary-audit-development-queue.md

15 KiB

ImageStudio 现有角色工作流二次审计与修复队列

需求来源:对工作流的二次审计.md 基线:1.0.8 目标:在现有 character_gradual 工作流上增量修复,不创建平行工作流。 部署规则:1.0.9–1.0.19 只开发和本地验证;全部完成后由 1.0.20 统一部署 NAS。

审计结论

全仓 268 个源码、配置和 Markdown 文件已经完成覆盖审计。现有项目应保留的主线是:

workflow_nodes → generation_tasks / generation_images → workflow_history → workflow_progression

项目已经具备逐节点解锁、节点锁、素材绑定、候选图片池、比较界面、图片采用、阶段交接、分支复制、视觉质检、队列重试和 AstrBot 命令骨架。此次工作不是重写,而是修复下列真实断点:

  • 详细工作流的 4 张图仍是一条任务/一次 provider 请求/一个超时。
  • 候选会被前端或后端自动选中,多选比较和最终单选混用。
  • 没有稳定轮次、候选编号和喜欢/拒绝/严格拒绝状态。
  • 对话输入没有候选编号解释链路。
  • 当前“交叉审核”是 VLM 视觉质检,不是不同生图模型复审。
  • 工作流素材可选择,但没有按轮次冻结快照和返回当前阶段的闭环。
  • 当前阶段模板缺下半身、三视图、档案卡等目标节点。
  • 分支是一次性复制,缺父链校验、祖先解析和分支级状态隔离。
  • 最终入库当前参数组合会被后端拒绝,且不是原子档案卡封存。
  • AstrBot 命令的选图、下一步、快速角色和长任务仍有接线错误。
  • App.vue 含大量不可达 mock 代码、两套比较弹窗和多处历史 UI 回归风险。

全程质量约束

  • 不回滚已有工作树,不破坏现有单图、快速角色、素材、设置和图库能力。
  • 旧工作流/旧节点 key/旧图片可读;升级采用惰性兼容或增量补节点。
  • 详细角色仍使用现有 character_gradual workflow 和真实 backend node。
  • 稳定 UUID 是主键;TX-15-03 仅作为持久化显示码。
  • 单图、快速角色、详细工作流、分支、轮次和候选的任务/图片/目录严格隔离。
  • 锁定节点可查看但不可写;已完成节点只能创建分支。
  • 最终采用必须由用户明确单选,禁止默认选择第一张。
  • 弹窗仅在完整外部单击时关闭;选字/拖动越界不关闭。
  • 深夜模式只使用主题 token,不新增白底浮层。
  • 所有删除、清理、重试、保存和长任务都返回明确状态或失败原因。
  • 不进行真实付费生图;本地与 NAS 验收使用 mock、只读探测或用户提供的安全测试方式。

小版本修复队列

1.0.9 — 在现有节点上补轮次/候选聚合层

状态:completed

  • 继续复用 generation_tasks、generation_images、workflow_history,新增最小 round/candidate/pool 结构。
  • 为旧节点图片建立只读 legacy round 适配,不搬文件、不改 image_id。
  • 增加 canonical stage mapper 和旧 key 映射,集中替代前后端散落映射。
  • 增加稳定 round/candidate display code、模型来源和失败摘要。
  • SingleFlowEngine 按 workflow/branch/node/round/candidate 生成隔离路径。
  • 修复 database/models.py 对现有表声明不完整的问题。

验收:全新/1.0.8 升级/重复迁移通过;旧工作流仍可打开;显示码刷新后不变化。

1.0.10 — 接通现有 QueueWorker,拆分独立候选任务

状态:completed

  • 将现有 GenerationService 拆为 prepare 与 execute;旧 generate_node() 保持兼容包装。
  • 仅详细工作流生图阶段使用 round API;一张候选一条 count=1 任务和独立超时。
  • 启用现有 QueueWorker,AstrBot initialize 启动、terminate 停止,重启恢复 stale task。
  • 一轮提示词/翻译/审核/素材只规划一次,候选共享服务端快照。
  • 轮次聚合部分成功、全部失败、取消、重试;单候选失败不得把整个节点直接标失败。
  • Provider/route 级并发限制,SQLite 写入竞争保护。

验收:4/5 条独立任务并发;一条超时不影响其他候选;接口先返回已入队;重启可恢复。

1.0.11 — 修复候选选择语义并原子确认

状态:completed

  • 移除后端成功后自动选择第一张图的详细工作流行为。
  • 前端拆分聚焦、比较、多候选反馈、最终单选四种状态,初始全部为空。
  • 喜欢、拒绝、严格拒绝复用 round pool + history 持久化。
  • 多选比较不再调用 nodeSelectImage;最终确认必须恰好单选一张成功候选。
  • 服务端原子完成:候选确认、图片独占选择、history、stage input、progression 解锁。
  • 图片采用的下一节点由服务端推导,不再信任客户端传入越级 node_id。

验收:刷新不丢选择/反馈;未选或多选不能确认;确认失败事务完整回滚。

1.0.12 — 对话编号解释与下一轮提示词

状态:completed

  • 在现有工作流对话框增加候选反馈解释,不再把“1、2 喜欢”直接当普通生图 prompt。
  • 解析稳定显示码、当前轮次序号、喜欢/拒绝/严格拒绝和素材意图。
  • LLM 只返回结构化 display code 动作;服务端重新映射并拒绝幻觉/越界编号。
  • 无 LLM 时提供确定性的本地中文编号解析,按钮与对话走同一服务。
  • 下一轮记录父轮次、用户原文、反馈摘要、positive/negative patch。

验收:中文顿号/逗号/完整编号均可解析;失败不污染上一轮;严格拒绝进入负向约束。

1.0.13 — 复用现有素材库完成中途素材闭环

状态:completed

  • 工作流任意未封存图像阶段可打开现有素材上传/粘贴/识别能力。
  • 推荐“进入素材库识别后绑定”;临时引用明确标记且不得把 data URL 持久化到异步任务。
  • 每轮冻结 material/reference snapshot,后续素材编辑不改变历史轮次。
  • 从素材库返回时恢复 workflow、branch、node、round 上下文。
  • 重新打开角色时从后端恢复全部 material bindings,而非只恢复单个 materialId。
  • 把会被卡片 overflow 裁剪的素材 popover 改为现有工作台内安全抽屉/对话框。

验收:添加素材后回到原轮次;刷新绑定不丢;历史快照不漂移;跨工作流不串图。

1.0.14 — 保留视觉质检,增加生成式交叉审查

状态:completed

  • 现有 CrossReviewService 保留并明确命名为视觉质检。
  • 新增“审查 / 跳过”确认弹窗;两条路径都写 history。
  • 生成式交叉审查复用 round/candidate 服务,路由必须是不同的 image_generation 模型。
  • 审查池 01 保留主候选,02 起标注适配器/模型;多轮只重生成被选项,其他候选保留。
  • 审查通过后原子交接至 restoration round,再解锁下一阶段。
  • 设置中的视觉审核模型和交叉生图模型分开显示与保存。

验收:模型来源准确;缺模型给出可操作错误;第二轮审查不丢未重生成候选;跳过审查可正常推进。

1.0.15 — 就地升级现有阶段模板与旧数据兼容

状态:completed

  • 新工作流阶段改为:确认人设、拆解设定、预选素材、头像、上半身、下半身、全身、三视图、设定图、高清修复、档案卡。
  • 保留现有四大组/十一小节点的可见与逐步解锁体验,节点 catalog 集中维护。
  • 旧 key 惰性映射:half_body → upper_body、expression_sheet → turnaround、pose_sheet → design_sheet、final_pack → profile_card。
  • 旧工作流缺少下半身时只增量补节点,不重建工作流、不替换 node_id。
  • 提示词规划、素材绑定、模型分工、依赖上下文同步使用 canonical stage。
  • 所有图像阶段复用相同 round/candidate/review UI 和服务。

验收:新旧工作流均可推进;只解锁直接后继;旧最终图片和 history 保留。

1.0.16 — 修复现有分支并增加祖先解析

状态:completed

  • 继续使用 workflow_branches.base_branch_name/base_node_id 和物理节点副本。
  • main 始终出现在分支列表;校验父分支、状态、自父、环、切点和“仅已完成节点可分支”。
  • 分支创建与节点复制改为单事务,失败不留半分支。
  • 增加 BranchLineageResolver,按当前分支 → 父分支 → main 解析有效节点数据。
  • prompt plan、material bindings、stage inputs 和审查交接按 branch 隔离。
  • dependency context 标注 inherited/source_branch/source_node_id。
  • 前端在现有工作流增加分支选择、父链、切点和来源展示。

验收:多级分支切点前后读取正确;错误父链被拒绝;分支数据不串;封存 workflow 全部写操作拒绝。

1.0.17 — 修复最终入库并建立独立档案卡

状态:completed

  • 修复当前 final_pack node + hires image 导致 history 校验失败的问题。
  • 新增独立 profile card 与资产 manifest,不把它等同于 character profile。
  • 单个幂等事务完成必填资产校验、档案卡、头像、人设文档/人设图、立绘、PV 图、history 和 workflow archive。
  • 兼容旧 final_archive_* 数据的只读 legacy card 视图。
  • Profile 分类改为未生成/快速角色/档案卡;详细工作流进行中单独展示,不提前算档案卡。
  • 角色页增加三种边框、筛选和封存只读状态。

验收:缺必填资产不封存;失败全部回滚;重复请求不重复建卡;刷新分类稳定。

1.0.18 — 修复并补齐现有 AstrBot/QQ 命令接线

状态:completed

  • 保留 /影棚 和 /yp,统一委托 Web 共用的 progression/round/candidate/feedback/adoption/branch/card 服务。
  • 修复聊天“选图”只 select 不 adopt、任意阶段覆盖头像、下一步跨分支、无图 generation 可直接 complete。
  • 修复快速角色确认后仍走 quick_profile 规划流的问题,接入现有 character_fast 四图流。
  • 增加轮次、反馈、确认候选、审查、素材、分支和档案卡命令。
  • 长命令立即返回已入队,持久化 reply target,完成/失败主动回传且可在重载后恢复。
  • 增加资源 owner 链校验;知道 ID 也不能操作他人工作流/图片/任务。
  • 帮助/状态卡展示分支、当前轮次和下一动作,卡片写入运行时数据目录。

验收:/影棚 与 /yp 同义;白名单规则不回退;聊天和 Web 推进结果一致;长任务不阻塞。

1.0.19 — 前端增量拆分与历史 UX 回归

状态:completed

  • 保持现有三栏工作流布局,将 catalog、候选板、比较弹窗、确认弹窗、素材抽屉和分支面板就近拆出组件。
  • 删除 workflowRunNodes return 后不可达 mock 工作流、未使用 computed 和重复比较弹窗。
  • 只保留一个 WorkflowCompareDialog;图片预览直接接收工作流图片,不借单图缓存。
  • 统一安全 backdrop helper,修复 ImagePreview、Wardrobe、设置和比较弹窗的拖动越界关闭。
  • 工作流模型默认展示阶段实际路由,只有显式覆盖才发送 model_route;同时显示生图模型与文本 LLM。
  • 头像可 cover;全身/三视图/设定图使用 contain。
  • 轮次懒加载、候选分页/折叠、事件增量刷新,避免节点/分支增加后的 N+1。
  • 深夜模式、窄屏、按钮堆叠、空状态、部分成功、错误和重试提示回归。

验收:typecheck/build 通过;4/5 候选、移动端、深夜模式和全部历史交互坑完成测试。

1.0.20 — 全量回归、打包、统一部署 NAS

状态:completed

  • Python compileall、pytest、前端 typecheck、production build 全通过。
  • 验证全新安装、1.0.8 升级、重复迁移、卸载重装和 stale task 恢复。
  • 清理死代码、缓存、测试资源和打包排除项;.env*、真实数据、密钥绝不进入 ZIP。
  • 更新 metadata、前端 package version、README、INSTALL、CHANGELOG。
  • 生成 AstrBot 可直接安装 ZIP;代码与安装包准备提交 Forgejo。
  • 最后才覆盖 NAS 插件目录、重启 astrbot-ops-pro、检查日志并在浏览器验收。

验收:AstrBot 无导入/迁移错误;页面自动连接;工作流按目标节点推进;不触发真实付费生图。

执行记录

版本 状态 日期 说明
1.0.8 baseline 2026-07-15 现有渐进工作流、UI 与 AstrBot 适配基线
1.0.9 completed 2026-07-15 新增稳定 round/candidate/pool、旧图片只读适配、隔离输出路径;63 项 Python 测试、前端 typecheck 与 133 条 AstrBot 路由导入检查通过。
1.0.10 completed 2026-07-15 一轮一次规划、候选独立任务、5 Worker 并发、partial/all-failed 聚合、stale 恢复与敏感路由快照收口;97 项测试通过。
1.0.11 completed 2026-07-15 候选聚焦/比较/反馈/定稿语义分离,最多 3 个喜欢、严格单候选确认及原子 progression 交接完成;Python 102 项、前端 typecheck 与 138 条 AstrBot 路由导入检查通过。
1.0.12 completed 2026-07-15 自然语言候选反馈、display code 白名单解释、草稿定稿恢复、父轮次提示词补丁与 1–3 个喜欢候选的下一轮闭环完成;补齐 round 所有权链和并发反馈版本校验。专项 44 项、前端 typecheck、Python 编译与 141 条路由导入检查通过。
1.0.13 completed 2026-07-15 任意未封存图像节点接入素材抽屉、上传/粘贴/识别/确认和 material_id 绑定;刷新恢复、owner/只读保护、导航上下文与不可漂移轮次快照闭环完成。专项 10 项与前端 typecheck 通过。
1.0.14 completed 2026-07-15 视觉质检与生成式交叉审核分离;跨模型候选、主候选保留、增量重生、审核/跳过历史及 XF 高清修复原子交接完成。专项 16 项、前端 typecheck、Python 编译与 144 条路由导入通过。
1.0.15 completed 2026-07-15 现有 character_gradual 就地升级为 11 个规范节点;旧 key 惰性兼容并只补缺失下半身节点,专项测试通过。
1.0.16 completed 2026-07-15 分支/节点原子创建、父链与祖先解析、branch_state 隔离及三栏分支面板完成;后端专项与前端构建通过。
1.0.17 completed 2026-07-15 档案卡单事务封存、旧 final_archive 只读兼容、角色分类/边框/筛选完成;1.0.15–1.0.17 联合回归 22 项通过。
1.0.18 completed 2026-07-15 /影棚 与 /yp 完全等价并复用 Web 服务;快速角色四图并行、详细流 round/feedback/confirm、素材/分支/档案卡及持久终态回传闭环完成。命令/权限/旧聊天 11 项、通知重载与 round runtime 回归通过,144 条路由可导入。
1.0.19 completed 2026-07-15 抽出工作流 Composer 并保留三栏;后端路由继承/显式覆盖、模型与文本 LLM 展示、completed/selected 锁语义、历史折叠与增量刷新、图片 fit 和暗色/窄屏回归完成。契约 5 项、typecheck、plugin/web build 通过。
1.0.20 completed 2026-07-15 全量 Python 149 项、前端契约 9 项、typecheck、双端 production build、compileall 与 144 条路由导入通过;生产 mock/示例资源清零。NAS 由 1.0.8 原位升级至 1.0.20,AstrBot 成功加载插件,15 条迁移及关键新表通过实库检查,页面自动连接并显示 1.0.20;未触发真实付费生图。