272 行
16 KiB
Markdown
272 行
16 KiB
Markdown
# 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/` 静态构建产物,避免把无关构建文件混入功能提交。
|