astrbot_plugin_imagestudio/docs/ui-function-entry-index.md

20 KiB

ImageStudio UI 功能入口与接口索引

日期:2026-07-07 维护规则:每新增一个可点击的功能入口、浮层、工作台入口、页面入口或后端 API 占位,都必须更新本文档。

2026-07-08 已完成闭环总结

  • 快速角色:创建角色档案问卷已扩展为简单/复杂模式,复杂字段支持世界观、背景、身高/身材、身体特征、喜好、关系、故事钩子、画风和镜头偏好;字段可留空,不阻断生成档案。
  • 快速角色落库:生成档案会调用 profiles/quick-draft/save,保存角色档案并创建对应 quick_profile/角色工作流关联,前端不会在预览模式伪造落库成功。
  • 外部角色卡导入:工作流导入入口已提供粘贴导入弹窗,可识别外部人设文本并回填角色档案问卷。
  • 角色工作流:前期人设准备节点已接入后端角色工作流执行入口 workflows/:workflowId/execute-character,成功后进入 LLM 设定拆解节点。
  • LLM 设定拆解:中间大卡片固定为拆解工作台,身份性格、外观锚点、服装素材、约束负面项按组顺序排列,超出内容滚动展示;右侧详情显示 LLM 拆解摘要。
  • 节点对话注入:底部对话框会打包当前节点、角色档案、素材、拆解字段和用户原文,标记 source_language:auto、target_prompt_language:en、translation_mode:backend_llm 后提交 nodes/:nodeId/generate。
  • 工作流锁定与分支:后端将 completed/selected 节点作为锁定节点,禁止原链路继续修改、重跑、选图、归档或删除绑定图片;如需修改,前端提供“从此节点创建分支”,调用 workflows/:workflowId/branches 和 workflows/:workflowId/switch-branch,从选中节点切分支并保证旧链路干净。
  • 分支复制规则:从 base_node_id 创建分支时,切点之前的节点保留完成状态和选中图;切点及之后重置为 draft 并清空选中图,metadata 写入 copied_from_node_id 和分支切点信息。
  • 验证结果:后端锁定/分支/生成/图像/历史相关测试 39 条通过;前端 vue-tsc --noEmit 和 build:web 通过;浏览器预览工作流三栏布局无控制台错误。

维护方式

  • 入口名称 写用户在界面上能理解的名称。
  • 位置 写清楚入口在哪个页面、哪个卡片或哪个浮层。
  • 当前动作 写现在点击会发生什么。
  • 关联接口 写已规划或已接入的 endpoint;纯前端占位写 local/*。
  • 状态 使用:已接 UI、模拟数据、占位入口、待后端接入、已接后端。

前端入口总览

左侧导航

入口名称 位置 当前动作 关联模块 状态
概览 左侧星图导航 切换到概览页 overview 已接 UI
生成 左侧星图导航 切换到生成页 generate 已接 UI
队列 左侧星图导航 切换到队列模块 queue 已接 UI
性能 左侧星图导航 切换到性能详情页 performance 占位入口
图库 左侧星图导航 切换到图库模块 images 占位入口
角色 左侧星图导航 切换到角色模块 suggestions 占位入口
素材 左侧星图导航 切换到素材模块 images 占位入口
设置 左侧星图导航 切换到设置模块 settings 已接 UI
日志 左侧星图导航 切换到日志模块 logs 已接 UI

顶部工具区

入口名称 位置 当前动作 关联接口 状态
主题切换 顶部工具区 日间/夜间模式切换 local/preferences 已接 UI
消息中心 顶部工具区铃铛 打开消息浮层,外部点击关闭 local/notifications 模拟数据
日志浮层 顶部工具区文件图标 悬停或点击打开日志浮层 logs/generation, logs/errors 已接 UI
后端连接诊断 顶部工具区刷新按钮旁 显示插件桥/同源 API 连接状态,预览或异常时展开诊断横幅 ui/bootstrap 已接 UI
调色盘 顶部工具区调色盘 打开主题色选择浮层 local/preferences 已接 UI
搜索 顶部搜索框 搜索功能入口和模块 local/search-index 已接 UI

生成页入口

生成页模式切换

入口名称 位置 当前动作 关联接口 状态
图片生成 生成页顶部模式按钮 切换到图片生成工作台 nodes/:nodeId/generate 已接 UI / 后端落库
快速角色 生成页顶部模式按钮 切换到快速角色工作台 profiles/quick-draft, profiles/quick-draft/save 已接 UI / 后端落库
角色工作流 生成页顶部模式按钮 切换到角色工作流工作台 profiles/:profileId/workflows, workflows/:workflowId/nodes 已接 UI / 后端数据

图片生成工作台

入口名称 位置 当前动作 关联接口 状态
生图模型选择 图片生成底部输入框 选择当前生图模型 api-discovery/capabilities 模拟数据
自然语言输入框 图片生成底部 输入自然语言生图需求 local/prompt-composer 占位入口
提交生成 图片生成输入框按钮 自动准备单图工作流并提交后端生成,返回图片写入预览 profiles, profiles/:profileId/workflows, nodes/:nodeId/generate 已接 UI / 后端落库
最近请求 图片生成输入框内 点击填入历史请求 local/recent-prompts 模拟数据
图片队列 图片生成左侧队列 优先展示后端返回图片和最近图库结果,选择后在主图区放大显示 images/:imageId 已接 UI / 后端数据
图片主预览 图片生成中间主图 点击打开图片详情卡 images/:imageId 已接 UI
图片详情卡 图片预览浮层 滚轮缩放、双击缩放、拖拽查看 images/:imageId 已接 UI

快速角色入口

入口名称 位置 当前动作 关联接口 状态
全部角色档案列表 快速角色左侧 选择当前角色卡 profiles 模拟数据
添加档案 全部角色档案列表顶部 打开创建角色档案问卷,可在生成档案旁切换简单/复杂问卷 profiles/quick-draft 已接 UI
角色预览折角 角色预览卡右上角 打开角色设定详情大卡片 profiles/:profileId 已接 UI
角色设定详情大卡片 角色预览折角打开 查看当前角色基础、外观、风格、负面词 profiles/:profileId 模拟数据
半身像/头像图片 角色预览图 打开图片详情卡,可缩放拖拽 images/:imageId 已接 UI
角色图片类型卡 角色图片区域右侧 切换头像、半身、立绘、设定图 images/:imageId 模拟数据
参考素材卡 快速角色参考素材区 打开素材选择浮层 materials 已接 UI
不使用参考 素材选择浮层顶部 清空对应分类素材 local/material-selection 已接 UI
添加素材占位卡 素材选择浮层底部 记录添加意图,后续跳转素材库新增 materials/upload 占位入口
配饰细分类 配饰素材浮层 切换配饰子类并单列展示 material-categories 模拟数据
生成人设 快速角色功能按钮 打开问卷大卡片 profiles/quick-draft 已接 UI
保存角色 快速角色功能按钮 调用后端保存快速角色档案,并创建 quick_profile 工作流 profiles/quick-draft/save 已接 UI / 后端落库
整理素材集 快速角色功能按钮 后续整理角色专属素材包 materials 占位入口
衣橱匹配 快速角色功能按钮 后续按当前人设匹配服装与配饰 profiles/:profileId/wardrobe/match 占位入口
每日穿搭 快速角色功能按钮 后续生成长期穿搭方案 integrations/private-companion/daily-outfit 占位入口
进入工作流 快速角色功能按钮 切到角色工作流并使用当前人设继续细化 profiles/:profileId/workflows 已接 UI

角色工作流入口

节点流程

入口名称 位置 当前动作 关联接口 状态
大节点卡 角色工作流左侧节点流程 优先读取已选角色的后端角色工作流节点,缺数据时回退演示节点 workflows/:workflowId/nodes 已接 UI / 后端数据
小节点卡 大节点内部 选择具体节点并联动中间工作幕布 nodes/:nodeId 已接 UI / 后端数据
前期人设准备 大节点 展示人设导入、拆解、提示词和素材绑定节点 workflows/:workflowId/nodes 模拟数据
头像草稿 大节点 展示头像草稿多轮节点 nodes/:nodeId/images 模拟数据
全身与设定图 大节点 展示全身、手部、配饰和设定图拆分节点 nodes/:nodeId/images 模拟数据
审核修复并入库 大节点 展示审核、高清修复和归档节点 workflows/:workflowId/review 模拟数据

工作幕布联动

入口名称 位置 当前动作 关联接口 状态
导入粗略人设工作台 选中 导入粗略人设 节点时的中间幕布 显示新建人设和选择已有角色卡 profiles/quick-draft, profiles 已接 UI
新建粗略人设 导入粗略人设工作台左侧右下角 + 按钮 打开创建角色档案问卷,可选简单/复杂字段 profiles/quick-draft 已接 UI
选择已有角色卡 导入粗略人设工作台右侧 选择当前角色卡作为工作流输入 profiles/:profileId 模拟数据
当前导入摘要 导入粗略人设工作台底部 展示当前导入角色卡、风格、素材和状态 profiles/:profileId 模拟数据
节点草稿池 图片类节点下方 按当前后端节点图片显示候选图,缺数据时回退演示图 nodes/:nodeId/images 已接 UI / 后端数据
多选草稿 节点草稿池 多选后同步到主预览,并把当前采用图写回后端节点 nodes/:nodeId/select-image 已接 UI / 后端落库
平铺对比 主预览右上角 打开多图对比浮层 local/workflow-compare 已接 UI
工作流图片详情 主预览图片点击 打开图片详情卡,可缩放拖拽 images/:imageId 已接 UI
节点详情 右侧节点详情卡 展示后端节点阶段、状态、队列任务和产物摘要,缺字段时使用 UI 摘要 nodes/:nodeId 已接 UI / 后端数据

工作流操作按钮

入口名称 位置 当前动作 关联接口 状态
创建角色档案 前期人设准备 / 导入粗略人设 打开创建角色档案问卷,简单字段可直接生成,复杂字段作为可选结构传后端并自动选中角色卡 profiles/quick-draft/save 已接 UI / 后端落库
导入外部角色卡 前期人设准备 / 导入粗略人设 打开外部角色卡导入浮层,识别文本后填入创建角色档案问卷 local/profile-import-parser, profiles/quick-draft 已接 UI
导入当前角色卡 前期人设准备 / 导入粗略人设 选中已落库角色卡作为工作流输入,自动加载或创建角色工作流 profiles/:profileId, profiles/:profileId/workflows 已接 UI / 后端落库
进入设定拆解 前期人设准备 / 导入粗略人设 使用当前已落库角色卡调用后端工作流执行,成功后切到 LLM 拆解节点 workflows/:workflowId/nodes, workflows/:workflowId/execute-character 已接 UI / 后端已接
LLM 拆解设定工作台 前期人设准备 / LLM 拆解设定 展示身份性格、外观锚点、服装素材、约束负面项四组结构化字段,并显示字段完成度 workflows/:workflowId/nodes 已接 UI / 后端数据
重新拆解设定 前期人设准备 / LLM 拆解设定 用当前角色档案重新生成结构化字段,后端连通时写回当前节点 nodes/:nodeId/generate 已接 UI / 后端预留
确认字段 前期人设准备 / LLM 拆解设定 确认身份、外观、服装、配饰和禁用项,成功后进入提示词规划 nodes/:nodeId/complete 已接 UI / 后端已接
节点对话注入 角色工作流 / 底部对话框 自动识别当前节点、角色档案、素材和拆解字段,打包用户原文并标记后端 LLM 翻译为英文提示词后注入节点 nodes/:nodeId/generate 已接 UI / 后端注入预留
生成提示词矩阵 前期人设准备 / 提示词规划 后续生成头像、半身、全身和设定图提示词 nodes/:nodeId/generate 待后端接入
校验负面词 前期人设准备 / 提示词规划 后续检查负面词、权重和冲突项 review/policy/validate 待后端接入
绑定参考素材 前期人设准备 / 参考素材绑定 后续把素材写入节点参数 materials, nodes/:nodeId 待后端接入
打开素材库 前期人设准备 / 参考素材绑定 跳转素材模块补充素材 materials 已接 UI
生成头像草稿 头像草稿阶段 按当前后端节点生成头像和半身候选,结果写入节点图片 nodes/:nodeId/generate, nodes/:nodeId/images 已接 UI / 后端落库
对比候选 头像草稿阶段 打开已选草稿平铺对比 local/workflow-compare 已接 UI
再跑一轮 头像草稿阶段 将当前后端节点标记重试并再次生成候选 nodes/:nodeId/retry, nodes/:nodeId/generate 已接 UI / 后端落库
生成设定图 全身与设定图阶段 生成全身、手部、配饰或拆分设定图并写入节点图片 nodes/:nodeId/generate, nodes/:nodeId/images 已接 UI / 后端落库
细节补图 全身与设定图阶段 后续针对手部、鞋袜、配饰等局部补图 nodes/:nodeId/generate 待后端接入
重跑当前设定 全身与设定图阶段 后续保留人设锁定项重跑当前节点 nodes/:nodeId/retry 待后端接入
审核选图 审核修复并入库阶段 后续标记采用、备选或废弃版本 nodes/:nodeId/review 待后端接入
高清修复 审核修复并入库阶段 对当前后端节点发起高清修复生成,结果写入节点图片 nodes/:nodeId/generate, nodes/:nodeId/images 已接 UI / 后端落库
保存快照 各工作流阶段 保存当前流程快照、节点参数和选中角色卡摘要到 workflow_history POST workflows/:workflowId/history 已接 UI / 后端已接
从此节点创建分支 选中已完成/已采用节点时的右侧操作区 已完成节点锁定后,点击会以当前节点为切点复制工作流分支并切换到新分支;切点之前保持锁定,切点及之后重置为草稿 POST workflows/:workflowId/branches, POST workflows/:workflowId/switch-branch 已接 UI / 后端已接
归档图库 审核修复并入库阶段 后续把最终图放入角色图库 images/:imageId/archive 待后端接入

当前已定义 API endpoint

源码位置:frontend/shared/api/endpoints.ts

UI 与概览

  • ui/bootstrap
  • ui/actions
  • dashboard/summary

角色与快速角色

  • profiles
  • profiles/:profileId
  • profiles/:profileId/archive
  • profiles/quick-draft
  • profiles/quick-draft/save
  • profiles/:profileId/workflows

工作流

  • workflows/:workflowId
  • workflows/:workflowId/start
  • workflows/:workflowId/cancel
  • workflows/:workflowId/archive
  • workflows/:workflowId/execute-character
  • workflows/:workflowId/nodes
  • 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/mark-completed
  • nodes/:nodeId/select-image
  • nodes/:nodeId/adopt-image
  • nodes/:nodeId/review
  • nodes/:nodeId/images

图片

  • images/:imageId
  • images/:imageId/select
  • images/:imageId/unselect
  • images/:imageId/archive

队列

  • jobs
  • jobs/:taskId
  • jobs/:taskId/cancel
  • jobs/:taskId/retry
  • jobs/dead-letter/retry
  • jobs/dead-letter/move-failed

设置与存储

  • settings/schema
  • settings/current
  • settings/validate
  • settings/diff
  • settings/save
  • settings/reload
  • settings/export
  • settings/import
  • settings/snapshots
  • settings/snapshots/:snapshotId
  • settings/rollback
  • storage/status
  • storage/migrate

素材库

  • material-categories
  • material-categories/:categoryId
  • materials
  • materials/upload
  • materials/:materialId
  • materials/:materialId/recognize
  • materials/:materialId/re-recognize
  • materials/:materialId/confirm
  • assets/import-pack

衣橱与穿搭

  • profiles/:profileId/wardrobe
  • profiles/:profileId/wardrobe/import-material
  • profiles/:profileId/wardrobe/items
  • profiles/:profileId/wardrobe/items/:wardrobeItemId
  • profiles/:profileId/wardrobe/:wardrobeItemId
  • profiles/:profileId/wardrobe/match
  • integrations/private-companion/daily-outfit

模型发现与能力探测

  • api-discovery/dialects
  • api-discovery/probe-provider
  • api-discovery/probe-model
  • api-discovery/capabilities
  • api-discovery/manual-override
  • api-discovery/validate-render-plan

日志、事件与安全

  • logs/generation
  • logs/workflows
  • logs/errors
  • logs/integrations
  • integrations/logs
  • security/audit-logs
  • events/stream
  • web/manifest

浮层与弹出卡片

浮层名称 触发入口 当前内容 关闭方式 状态
消息中心 顶部铃铛 通知列表 外部点击 / 再点按钮 / ESC 已接 UI
日志浮层 顶部日志图标 生成日志、错误日志 外部点击 / ESC 已接 UI
调色盘 顶部调色盘 主题色选择 外部点击 / ESC 已接 UI
图片详情卡 图片生成/工作流/快速角色图片 大图缩放、双击、拖拽 外部点击 / 关闭按钮 / ESC 已接 UI
角色设定详情卡 快速角色折角 当前角色设定详情 外部点击 / 关闭按钮 / ESC 已接 UI
创建角色档案问卷 快速角色生成人设/添加档案/工作流新建人设 简单/复杂问卷切换;复杂问卷包含世界观、背景、身高身材、喜好、关系和生成偏好,字段可留空;保存时调用后端生成角色档案与 quick_profile 工作流 外部点击 / 关闭按钮 / ESC 已接 UI / 后端落库
外部角色卡导入 工作流导入粗略人设 / 粘贴导入 粘贴外部角色卡、人设文本或设定片段,并识别填入创建角色档案问卷 外部点击 / 取消 / 关闭按钮 / ESC 已接 UI
素材选择卡 快速角色参考素材 不使用、素材候选、添加素材 外部点击 / ESC 已接 UI
工作流多图对比 角色工作流平铺对比 多草稿大图对比 关闭按钮 / ESC 已接 UI

待补入口记录

新增功能时先写这里,再实现 UI 或接口。

待补入口 预期位置 预期接口 备注
素材库添加对应分类素材 素材选择浮层底部添加卡 materials/upload 需要带分类参数,如构图、服装、配饰子类
工作流草稿轮次自动创建 角色工作流节点流程 workflows/:workflowId/nodes 不满意重跑时自动创建草稿 02/03 等小节点
节点锁定元素写入 工作流多选草稿/节点详情 nodes/:nodeId/select-image 选中五官、发色、服装等锁定项
角色编辑界面 角色设定详情卡或角色模块 profiles/:profileId 当前只有详情卡和问卷占位
性能详情页 左侧性能入口 待定 当前只有入口和概览精简卡