16 KiB
16 KiB
ImageStudio UI / Workflow Progress Handoff
日期:2026-07-09 范围:生成页、快速角色、角色工作流、阶段审查、锁定与分支、后端接口闭环
当前总体状态
- 生成页已经形成三条主入口:
图片生成、快速角色、角色工作流。 - 三条入口都已经有前端工作台,并已接入或预留对应后端接口:
- 图片生成:走单图工作流与
nodes/:nodeId/generate。 - 快速角色:走
profiles/quick-draft/save保存档案并创建工作流关联。 - 角色工作流:走
profiles/:profileId/workflows、workflows/:workflowId/nodes和节点级生成/审查/历史接口。
- 图片生成:走单图工作流与
- 当前重点已经从纯 UI 进入“角色工作流闭环”:档案导入、设定拆解、提示词规划、素材绑定、头像/半身/设定图、审查、高清修复、入库。
已完成内容
快速角色与角色档案
- 创建角色档案问卷已支持简单/复杂模式。
- 复杂问卷字段包含世界观、背景、身高/身材、身体特征、喜好、关系、故事钩子、生成风格、镜头偏好等。
- 问卷字段可留空,不要求全部填写,避免破坏创建体验。
- 生成档案按钮语义已从“生成预览”改为“生成档案”。
- 生成档案后会在右侧角色卡区域生成/选中新角色卡。
- 外部角色卡导入已提供弹窗入口,可粘贴外部人设文本并回填问卷字段。
- 快速角色参考素材选择沿用分类素材卡,默认生产语义应为“不使用参考”,避免无意引入参考图。
前期人设准备
前期人设准备页面布局已调整:导入入口放到侧面,上方主卡片下移,侧边空间更有效。- 该阶段包含:
- 导入粗略人设
- LLM 设定拆解
- 提示词规划
- 参考素材绑定
- LLM 设定拆解卡片按组展示身份性格、外观锚点、服装素材、约束负面项。
- 大卡片尺寸保持稳定,内部小项目按顺序排列,内容超出时滚动。
- 底部对话框会根据当前节点注入上下文,包括角色档案、节点信息、素材、拆解字段和用户原文,并标记后端 LLM 翻译为英文提示词。
提示词规划
- 提示词规划页面已搭建矩阵化展示。
- 支持头像、半身、全身、设定图等目标节点的提示词条目。
- 已加入继承字段、权重依据、负面词和冲突项校验区域。
- 修复过卡片重叠、内容被遮挡、胶囊超出卡片下沿等布局问题。
- 提示词规划 LLM 输出结构已补齐后端 schema,版本为
2026-07-09.prompt-plan-schema.v1。 - 后端提示词规划 schema 包含:
matrix:头像、半身、全身、设定图等目标提示词矩阵。weight_suggestions:权重建议、数值和依据。inheritance_fields/inheritance_changes:继承字段与变更建议。guardrails:负面提示词、语言策略和检查项。conflicts:按目标节点归属的冲突项。by_target/by_node_key/by_node_id:按目标、后端节点类型和真实节点索引。
- 保存
prompt_plan节点 metadata 或 workflow metadata 时,后端会自动规范化为正式 prompt plan schema。 - 节点依赖上下文会按当前目标节点过滤提示词规划,例如头像节点只拿头像 prompt patch,全身节点只拿全身 prompt patch。
PromptExpansionService会从 dependency context 自动继承 prompt plan 的 positive/negative patch,并注入生成链路与node_injection.prompt_plan。
参考素材绑定
- 参考素材绑定页面已建立。
- 绑定节点已翻译为中文,并改为直接绑定大节点,不再绑定后期生成才会出现的小节点。
- 已按“快速角色参考素材”的交互方式提供素材选择。
- 参考素材选择弹窗已改为悬浮在上方,而不是向下撑开布局。
- 默认生产语义应为“不使用参考”,只有用户显式选择后才注入素材。
- 素材绑定规则已接入后端 metadata 写入与 workflow 级规范化落库。
- 后端素材绑定 schema 版本为
2026-07-09.material-binding-schema.v1。 - 保存
material_bind节点时,后端会自动生成:rules:完整规则,包含未选择素材的“不使用参考”分类。active_rules:用户显式选择素材后才启用的规则。by_stage:按前端大阶段索引。by_node_key:按后端节点类型索引。by_node_id/node_parameters:按真实 workflow node 索引。
- 后端默认参考策略为
explicit_only,default_use_reference=false,空素材分类不会进入生成参考。 - 节点依赖上下文会按当前目标节点过滤素材,例如头像只拿头像阶段绑定,半身只拿半身阶段绑定。
PromptExpansionService会从 dependency context 自动继承规范化素材绑定,供后端 LLM 和生成链路注入。
角色工作流大节点
- 前端大节点已对齐后端设计,当前角色工作流大节点包括:
- 前期人设准备
- 头像
- 半身像
- 全身与设定图
- 高清修复并入库
- 已补齐半身像节点。
- 前期人设准备暂时不再调整,后续重点转入生成链路与审查链路。
头像 / 半身 / 设定图生成逻辑
- 头像节点:
- 第一个节点按钮为“生成头像”。
- 后续轮次按钮为“再跑一轮”。
- 原“再跑一轮”语义下的确认按钮已改为“确认使用”。
- 半身像和全身/设定图已按同样逻辑整理。
- 选中候选后可进入对应阶段审查节点。
- 下方对话框已按当前节点分别注入节点上下文。
阶段审查节点
- 已加入 UI 层阶段审查节点:
portrait-review:头像审查halfbody-review:半身像审查body-sheet-review:设定图审查
- 阶段审查映射到真实后端节点:
- 头像审查映射到
headshot - 半身像审查映射到
half_body - 设定图审查映射到
expression_sheet/ 设定图相关节点
- 头像审查映射到
- 审查阶段按钮已调整为:
选中的图片重新生成对比候选确认
选中的图片重新生成用于同提示词不同模型复跑,解决某个模型偶尔异常的问题。确认用于通过审查并推进到下一阶段。
审查确认闭环
- 审查阶段点击
确认已接入真实闭环:- 调用
nodes/:nodeId/adopt-image。 - 将选中图片写入后端采用历史。
- 将上一真实生成节点状态收敛为
selected。 - 上一节点进入锁定状态,后续修改需要从该点创建分支。
- 推进
workflow.current_node_id到下一真实节点。 - 在 workflow metadata 的
stage_inputs中记录阶段输入交接。
- 调用
- 设定图审查确认后,选中的成品稿会放入
高清修复输入桶。 - 前端维护
workflowInputImagesByNodeId,用于展示“下一节点输入图”,不伪造图片真实归属。 - 如果下一节点已经锁定,前端不会再尝试修改下一节点 metadata,只记录 workflow 级交接信息。
- 后端
adopt_node_image已消费前端传入的next_backend_node_id、handoff_bucket、handoff_role等 metadata。 - 后端会将阶段交接正式写入
workflow.metadata.stage_inputs,schema 版本为2026-07-09.stage-input-bucket.v1。 - 后端会同步推进
workflow.current_node_id到下一真实节点,并保留最近阶段审查交接日志stage_review_handoffs。 - 前端已补齐
workflowReviewAdopt操作:- 头像/半身/设定图阶段显示
确认采用。 - 高清修复阶段显示
确认修复结果。 - 采用前要求选中的图片是真实后端图片,且必须属于当前后端节点。
completed节点允许本地切换候选图并执行一次确认采用,但不允许重新生成、重跑或修改提示词。selected节点视为最终锁定,只显示创建分支和保存快照。- 头像/半身采用后优先按后端
sort_order推进到下一真实节点。 - 设定图采用后固定交接到
高清修复与统一风格。 - 高清修复采用后交接到
入库。 - 采用成功后前端会刷新 workflow、nodes 和 node images,并跳转到下一 UI 节点。
- 头像/半身/设定图阶段显示
后端注入与审查结构
- 已新增
backend/services/node_injection_template_service.py,统一定义每个节点的对话注入契约。 - 注入契约包含用户原文、节点上下文、上游选图、素材绑定、阶段输入、语言翻译策略和预期 JSON 返回结构。
- 已补齐
stage_review与candidate_review注入模板,支持审查节点下方对话框按节点独立注入。 prompt_plan注入模板已补入正式提示词规划 schema、权重建议、继承字段、负面词和冲突返回结构。material_bind注入模板已补入正式素材绑定 schema、默认参考策略和目标后端节点字段。NodeDependencyContextService已返回injection_template,供前端或后续 LLM 编排读取。PromptExpansionService已返回node_injection,生成链路可以把节点注入契约一并传给后端 LLM。ReviewFlowEngine.review_node已返回正式stage_review结构,schema 版本为2026-07-09.stage-review-result.v1。- 阶段审查结果结构包含:
- 同提示词多模型候选
candidates - 候选评分
score - 画面缺陷与警告
defects/warnings - 选中候选
selected_candidate - 重生成记录
regeneration_records - 人工确认动作
manual_confirmation - 下一阶段输入桶预期结构
handoff
- 同提示词多模型候选
锁定与分支
- 后端锁定状态包括
completed和selected。 - 普通编辑、重跑、选图、归档或删除锁定节点绑定图片会被阻止。
- 前端在锁定节点显示“从此节点创建分支”入口。
- 创建分支调用:
POST workflows/:workflowId/branchesPOST workflows/:workflowId/switch-branch
- 分支规则:
- 切点之前的节点保留完成状态和选中图。
- 切点及之后重置为
draft并清空选中图。 - metadata 记录
copied_from_node_id、切点和分支继承信息。
- 为审查确认补充了后端受控例外:
- 允许
completed -> selected的采用收敛。 - 已经
selected后切换到另一张图仍会拒绝,继续要求新建分支。
- 允许
后端接口状态
已接入或已使用
profilesprofiles/quick-draftprofiles/quick-draft/saveprofiles/:profileId/workflowsworkflows/:workflowIdworkflows/:workflowId/nodesworkflows/:workflowId/execute-characterworkflows/:workflowId/branchesworkflows/:workflowId/switch-branchworkflows/:workflowId/historyworkflows/:workflowId/reviewnodes/:nodeIdnodes/:nodeId/generatenodes/:nodeId/retrynodes/:nodeId/completenodes/:nodeId/select-imagenodes/:nodeId/adopt-imagenodes/:nodeId/reviewnodes/:nodeId/imagesimages/:imageId
已预留但仍需后端深化
- 最终角色版本入库 schema。
- 角色图库与素材库联动。
关键代码位置
- 前端主页面:
frontend/standalone-web/src/App.vue - 前端接口定义:
frontend/shared/api/endpoints.ts - 后端 workflow 服务:
backend/services/workflow_service.py - 后端 history/adopt 服务:
backend/services/history_service.py - 后端提示词规划 schema:
backend/services/prompt_plan_schema_service.py - 后端素材绑定 schema:
backend/services/material_binding_schema_service.py - 后端节点注入模板:
backend/services/node_injection_template_service.py - 后端节点依赖上下文:
backend/services/node_dependency_context_service.py - 后端审查引擎:
engines/review_flow.py - 后端角色工作流服务:
backend/services/character_workflow_service.py - 角色工作流节点模板:
engines/character_flow.py - 相关测试:
tests/test_history_service.pytests/test_review_service.pytests/test_prompt_plan_schema_service.pytests/test_material_binding_schema_service.pytests/test_prompt_expansion_service.pytests/test_node_dependency_context_service.pytests/test_workflow_service.pytests/test_character_workflow_service.py
已验证
- 前端类型检查:
npm.cmd run typecheck- 结果:通过。
- 后端 history 测试:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_history_service - 结果:4 tests OK。
- 使用 Codex bundled Python 运行
- 后端审查/历史/节点注入/单图生成相关测试:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_review_service tests.test_history_service tests.test_prompt_expansion_service tests.test_node_dependency_context_service tests.test_single_flow_generation - 结果:28 tests OK。
- 使用 Codex bundled Python 运行
- 后端素材绑定 schema / workflow 同步 / 上下文注入测试:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_material_binding_schema_service tests.test_workflow_service tests.test_node_dependency_context_service tests.test_prompt_expansion_service tests.test_review_service tests.test_history_service - 结果:37 tests OK。
- 使用 Codex bundled Python 运行
- 后端生成链路补充测试:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_single_flow_generation tests.test_character_workflow_service - 结果:15 tests OK。
- 使用 Codex bundled Python 运行
- 后端提示词规划 schema / workflow 同步 / 上下文注入测试:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_prompt_plan_schema_service tests.test_workflow_service tests.test_node_dependency_context_service tests.test_prompt_expansion_service - 结果:26 tests OK。
- 使用 Codex bundled Python 运行
- 后端角色工作流核心回归:
- 使用 Codex bundled Python 运行
python -m unittest tests.test_prompt_plan_schema_service tests.test_material_binding_schema_service tests.test_workflow_service tests.test_node_dependency_context_service tests.test_prompt_expansion_service tests.test_review_service tests.test_history_service tests.test_single_flow_generation tests.test_character_workflow_service - 结果:57 tests OK。
- 使用 Codex bundled Python 运行
- 审查确认采用前端闭环补充验证:
npm.cmd run typecheck- 结果:通过。
- 使用 Codex bundled Python 运行
python -m unittest tests.test_prompt_plan_schema_service tests.test_material_binding_schema_service tests.test_review_service tests.test_quick_profile_service tests.test_workflow_service tests.test_node_dependency_context_service tests.test_prompt_expansion_service tests.test_history_service - 结果:44 tests OK。
- 本地 dev server:
http://127.0.0.1:5173/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/?view=generate- HTTP 返回 200。
当前限制与风险
- 浏览器插件在一次 reload 验证时超时重置,因此没有执行页面内真实点击确认验证,避免误改本地工作流数据。
web/静态产物当前有旧资产删除和新资产生成,属于之前构建结果,提交前需要统一确认是否纳入。- 工作区存在多处既有改动,提交前需要按功能拆分检查,不要把无关改动混进同一版。
- 阶段审查与高清修复输入桶已有后端结构,但还没有做完整页面点击回归。
- 最终入库节点仍需补齐角色版本、图片、提示词、素材引用、审查记录和分支信息的正式 schema。
建议下一步
- 完成最终入库节点:保存角色版本、图片、提示词、素材引用、审查记录和分支信息。
- 做一次完整浏览器手动回归:头像确认、半身确认、设定图确认、进入高清修复、锁定后创建分支。
- 视提交策略决定是否纳入当前
web/静态构建产物,避免把无关构建文件混入功能提交。