# 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/branches` - `POST workflows/:workflowId/switch-branch` - 分支规则: - 切点之前的节点保留完成状态和选中图。 - 切点及之后重置为 `draft` 并清空选中图。 - metadata 记录 `copied_from_node_id`、切点和分支继承信息。 - 为审查确认补充了后端受控例外: - 允许 `completed -> selected` 的采用收敛。 - 已经 `selected` 后切换到另一张图仍会拒绝,继续要求新建分支。 ## 后端接口状态 ### 已接入或已使用 - `profiles` - `profiles/quick-draft` - `profiles/quick-draft/save` - `profiles/:profileId/workflows` - `workflows/:workflowId` - `workflows/:workflowId/nodes` - `workflows/:workflowId/execute-character` - `workflows/:workflowId/branches` - `workflows/:workflowId/switch-branch` - `workflows/:workflowId/history` - `workflows/:workflowId/review` - `nodes/:nodeId` - `nodes/:nodeId/generate` - `nodes/:nodeId/retry` - `nodes/:nodeId/complete` - `nodes/:nodeId/select-image` - `nodes/:nodeId/adopt-image` - `nodes/:nodeId/review` - `nodes/:nodeId/images` - `images/: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.py` - `tests/test_review_service.py` - `tests/test_prompt_plan_schema_service.py` - `tests/test_material_binding_schema_service.py` - `tests/test_prompt_expansion_service.py` - `tests/test_node_dependency_context_service.py` - `tests/test_workflow_service.py` - `tests/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 运行 `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。 - 后端素材绑定 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 运行 `python -m unittest tests.test_single_flow_generation tests.test_character_workflow_service` - 结果:15 tests OK。 - 后端提示词规划 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 运行 `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。 - 审查确认采用前端闭环补充验证: - `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。 ## 建议下一步 1. 完成最终入库节点:保存角色版本、图片、提示词、素材引用、审查记录和分支信息。 2. 做一次完整浏览器手动回归:头像确认、半身确认、设定图确认、进入高清修复、锁定后创建分支。 3. 视提交策略决定是否纳入当前 `web/` 静态构建产物,避免把无关构建文件混入功能提交。