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

298 行
20 KiB
Markdown

# ImageStudio UI 功能入口与接口索引
日期:2026-07-07
维护规则:每新增一个可点击的功能入口、浮层、工作台入口、页面入口或后端 API 占位,都必须更新本文档。
> AstrBot 运行约定(2026-07-10 校正):生产 UI 由 `pages/imagestudio/index.html` 自动发现;插件在 `initialize()` 中通过 `context.register_web_api` 注册接口。`window.AstrBotPluginPage` 只传 `ui/bootstrap` 这类相对 endpoint,并兼容 v4.25 legacy `/api/plug/astrbot_plugin_imagestudio/<endpoint>` 与当前 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>`。文中独立 `web/` 或 Vite 地址只代表开发预览,不是 AstrBot 保证注册的生产入口。
## 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`
### 模型能力档案与安全元数据检查
`probe-provider` 和 `probe-model` 当前只登记/检查元数据,不会主动向填写的地址发起网络请求;真实 Provider 可用性由配置后的生成调用验证。
- `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` | 当前只有详情卡和问卷占位 |
| 性能详情页 | 左侧性能入口 | 待定 | 当前只有入口和概览精简卡 |