astrbot_plugin_imagestudio/docs/ui-progress-2026-07-09.md

16 KiB

ImageStudio UI / Workflow Progress Handoff

日期:2026-07-09 范围:生成页、快速角色、角色工作流、阶段审查、锁定与分支、后端接口闭环

历史记录说明:本文保留当日开发与验证结果。当前 AstrBot 生产页面由 pages/imagestudio/index.html 自动发现;bridge 调用传相对 endpoint,兼容 v4.25 legacy /api/plug/astrbot_plugin_imagestudio/<endpoint> 与当前 /api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>。下文 /web URL 是 Vite 预览记录,不表示 AstrBot 注册了该生产入口。

当前总体状态

  • 生成页已经形成三条主入口:图片生成、快速角色、角色工作流。
  • 三条入口都已经有前端工作台,并已接入或预留对应后端接口:
    • 图片生成:走单图工作流与 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。
  • 本地 Vite dev server(仅历史预览路径,不是 AstrBot 生产入口):
    • 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/ 静态构建产物,避免把无关构建文件混入功能提交。