8.5 KiB
AstrBot ImageStudio
ImageStudio 是运行在 AstrBot 内的角色资产与生图工作台插件。它把角色档案、详细角色工作流、快速角色、素材库、衣橱、生成队列、模型路由、日志和聊天命令放在同一套持久化链路中。
运行形态与兼容范围
- AstrBot:
>= 4.25.0,<5。 - 平台:以 AstrBot 支持的 Windows、Linux、macOS 和 Docker 环境为准。
- 数据库:默认 SQLite;PostgreSQL 是可选后端。
- 生产运行:由 AstrBot 加载
main.py中的Star插件类,不启动独立 FastAPI、Flask 或 Vite 服务。 - 插件页面:生产入口是
pages/imagestudio/index.html;web/仅作为兼容构建产物保留。
initialize() 会先应用 AstrBot 配置、执行数据库迁移和默认分类初始化,再注册 Web API 并启动持久化候选任务 Worker;terminate() 会停止 Worker 并释放运行资源。
详细角色工作流
详细角色继续使用现有的 character_gradual 主线,没有另建平行流程。规范工作流包含 11 个顺序节点:
| 顺序 | 节点 | 用途 |
|---|---|---|
| 1 | 人设导入与拆解 profile_brief |
接收粗略人设,拆解身份、性格、外观、服装和一致性锚点 |
| 2 | 提示词规划 prompt_plan |
规划各图像阶段的正向、负向提示词和继承规则 |
| 3 | 素材预选 material_bind |
绑定风格、构图、服装、鞋袜、配饰和临时参考 |
| 4 | 头像 headshot |
确认五官、发型、眼睛、表情和身份锚点 |
| 5 | 上半身像 upper_body |
确认上身服装、姿态和轮廓 |
| 6 | 下半身像 lower_body |
确认腰胯、腿部比例、鞋袜和下身细节 |
| 7 | 全身像 full_body |
确认完整服装、身体比例和整体剪影 |
| 8 | 三视图 turnaround |
生成正面、侧面和背面的一致视图 |
| 9 | 设定图 design_sheet |
汇总表情、姿势、手部、配饰和设计细节 |
| 10 | 高清修复 style_lock |
完成高清修复、身份统一和风格锁定 |
| 11 | 档案卡 profile_card |
校验必填资产并原子封存角色档案卡 |
节点按顺序解锁。锁定节点仍可查看,但不能生成、改素材或写入结果;已完成节点只能从已完成切点创建分支后继续修改。旧工作流仍通过惰性映射读取:half_body → upper_body、expression_sheet → turnaround、pose_sheet → design_sheet、final_pack → profile_card,不会替换旧 node_id 或搬动旧图片。
轮次、候选与反馈
- 每个详细生图轮次生成 4 或 5 个候选;每个候选是一条独立的持久任务、独立超时和隔离输出目录。
- 一轮只规划一次提示词、治理、素材快照、模型路由和预算。单个候选失败不会抹掉其他成功结果,界面会显示部分成功和失败摘要。
- UUID 是内部主键;
TX-15-03这类稳定显示码用于界面和聊天反馈。 - “聚焦”“比较”“喜欢/拒绝/严格拒绝”和“最终定稿”是不同状态。最终采用必须明确选择恰好一个成功候选,不会自动采用第一张。
- 自然语言反馈支持“1、2 喜欢,3 严格拒绝”等写法。服务端会重新校验编号;没有可用文本 LLM 时使用确定性的本地编号解析,不接受越界或幻觉编号。
- 下一轮保存父轮次、用户原文、反馈摘要和正负提示词补丁;重启后可恢复轮次与未完成任务。
素材、审查、分支与档案卡
素材闭环
任意尚未封存的图像节点都可以打开素材抽屉,复用素材库的上传、粘贴、识别、确认和绑定能力。异步任务只持久化 material_id,不会持久化 data URL。创建轮次时会冻结素材/参考快照,因此后续编辑素材不会改变历史轮次;重新进入角色或切换分支时会从后端恢复绑定和来源。
两类审查
- 视觉质检:使用视觉模型检查画面质量、身份一致性和结构问题。
- 生成式交叉审查:保留主候选为 01,并让不同的图片生成模型产生复审候选;可只重做选中的复审项,也可在确认后跳过。视觉审核模型与交叉生图模型分别配置。
两条路径都会写入历史记录。交叉审查通过后才把采用结果交给高清修复阶段;没有配置不同的可用生图路由时,会返回可操作的配置错误,不会伪造复审结果。
分支
main 分支常驻。新分支必须从已完成节点创建,服务端校验父分支、切点、自引用和环。提示词、素材绑定、阶段输入、轮次和审查状态按分支隔离;界面同时展示父链、继承来源分支和来源节点。
档案卡
档案卡不是普通角色记录的别名。封存会在单个幂等事务中校验头像、人设图/文档、立绘、PV 图等必填资产,建立资产 manifest、写入历史并归档工作流。缺少资产或任一步失败时不会留下半张档案卡。封存后工作流只读;旧 final_archive_* 数据仍可只读查看。
模型配置与无模型行为
在 ImageStudio 设置页添加适配器并配置模型分工。图片生成、提示词规划/扩写、素材视觉识别、视觉质检、生成式交叉审查、高清修复等用途可以选择不同路由;详细工作流默认使用当前阶段的实际路由,只有用户显式覆盖时才发送新的 model_route。
ImageStudio 不内置可冒充生产结果的云端模型或 mock 图片。未配置真实 Provider 时:
- 页面、角色档案、素材元数据、分支、历史、队列查询和已有图片仍可使用;
- 需要文本/视觉/生图模型的动作会返回明确的缺失能力或 Provider 错误;
- 已创建的异步任务会进入可诊断的失败状态,不会显示为成功;
- 可跳过的生成式交叉审查仍需用户明确确认,系统不会静默替用户通过。
Provider 和安装配置示例见 INSTALL.md。
AstrBot 插件页面与 API
从 AstrBot 插件管理界面打开 ImageStudio。页面优先使用 window.AstrBotPluginPage bridge,并只向 apiGet、apiPost、apiPut、apiDelete 传相对 endpoint,例如:
ui/bootstrap
workflows/<workflow_id>/branches
nodes/<node_id>/rounds
rounds/<round_id>/feedback
插件兼容两套路由前缀:
- AstrBot v4.25 legacy bridge:
/api/plug/astrbot_plugin_imagestudio/<endpoint>。 - 当前扩展 API:
/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>。
直接 fetch 时才拼完整扩展 API;bridge 调用不能重复拼宿主前缀。当前产品定位是已认证 AstrBot 管理界面,不应把插件 API 直接暴露为面向互不信任用户的公共服务。工作流、轮次、图片、素材和任务的聊天/Web 操作会沿资源 owner 链校验,不能仅凭已知 ID 操作其他用户资源。
聊天命令
/影棚 与短别名 /yp 完全等价。常用命令如下;完整语法以 /yp 帮助 返回为准。
/yp 帮助
/yp 状态
/yp 快速角色 <角色名> <角色描述>
/yp 工作流 <角色名或角色 ID>
/yp 单图 <提示词>
/yp 轮次 <node_id> [4|5] [可选提示词]
/yp 轮次状态 <round_id>
/yp 候选 <round_id>
/yp 反馈 <round_id> <自然语言反馈>
/yp 下一轮 <round_id> [4|5]
/yp 定稿 <round_id> <候选编号>
/yp 审查 <round_id> <候选编号> [审核|跳过]
/yp 审查重做 <round_id> <候选编号,候选编号> [提示词修订]
/yp 审查通过 <round_id> <候选编号>
/yp 素材 <node_id> [material_id,material_id]
/yp 分支 <workflow_id>
/yp 新建分支 <workflow_id> <已完成切点node_id> <新分支名>
/yp 切换分支 <workflow_id> <分支名>
/yp 档案卡 <workflow_id> [可选人设文档]
/yp 任务 [task_id]
/yp 取消 <task_id>
/yp 重试 <task_id>
快速角色和详细角色工作流要求群聊白名单与用户白名单同时命中;单图允许任意一个白名单命中。长任务会立即返回已入队信息,完成或失败后通过原消息来源主动回传,重载后也可恢复尚未发送的终态通知。
持久化数据
运行数据统一位于 AstrBot 数据目录:
data/plugin_data/astrbot_plugin_imagestudio/
数据库、图片、缩略图、素材、归档和临时文件不能依赖插件源码目录可写。升级前应单独备份该目录,覆盖插件源码时不得删除它。安装、升级、迁移、Docker/NAS 手工覆盖和发布包边界见 INSTALL.md。
开发约定见 DEVELOPMENT.md,本轮详细工作流审计见 docs/workflow-secondary-audit-2026-07-15.md。