astrbot_plugin_imagestudio/README.md

114 行
5.8 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# AstrBot ImageStudio
ImageStudio 是运行在 AstrBot 内的角色资产与生图工作台插件,提供角色档案、工作流、素材库、衣橱、任务队列、日志和模型能力档案等功能。
## 兼容范围
- AstrBot:`4.25.0` 及以上。
- 运行平台:AstrBot 支持的 Windows、Linux、macOS 和 Docker 环境。
- 数据库:默认 SQLite;PostgreSQL 为可选后端。
- 生产运行方式:由 AstrBot 加载插件,不启动独立 FastAPI、Flask 或 Vite 服务。
## AstrBot 加载方式
AstrBot 通过 `main.py` 中的 `Star` 插件类自动发现 ImageStudio,并管理其生命周期:
- `initialize()`:读取 AstrBot 配置、初始化持久化数据,并通过 `context.register_web_api` 注册插件 API。
- `terminate()`:插件停用或重载时释放运行资源。
- `pages/imagestudio/index.html`:由 AstrBot 自动发现为插件页面,无需手工注册静态 `/web` 入口。
## 打开界面
安装并重载插件后,从 AstrBot 的插件管理界面打开 ImageStudio。生产页面来自:
```text
pages/imagestudio/index.html
```
仓库中的 `web/` 是独立前端构建/兼容产物。除非宿主显式注册对应静态路由,否则 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web` 不是 AstrBot 保证提供的生产入口。
## API 兼容模式
插件页面优先使用 `window.AstrBotPluginPage` bridge。传给 `apiGet`、`apiPost`、`apiPut` 或 `apiDelete` 的值必须是相对 endpoint,例如:
```text
ui/bootstrap
dashboard/summary
nodes/<node_id>/generate
```
ImageStudio 同时兼容两套路由前缀:
- AstrBot v4.25 legacy bridge:`/api/plug/astrbot_plugin_imagestudio/<endpoint>`。
- 当前扩展 API:`/api/v1/plugins/extensions/astrbot_plugin_imagestudio/<endpoint>`。
bridge 会处理宿主前缀;前端不应把完整 `/api/plug/...` 或 `/api/v1/...` 地址传给 bridge。直接 `fetch` 时才使用当前 `/api/v1` 前缀。
## 运行与权限边界
ImageStudio 当前定位为 AstrBot WebUI 内的管理工作台。Bridge 只接受 AstrBot 已认证请求,并为插件页面授予显式的写入、配置、素材和任务重试能力;不会信任浏览器自行提交的用户名、用户 ID 或转发 IP 请求头。
角色档案列表和档案读写已按 AstrBot 登录身份隔离,但工作流、图片、任务、衣橱、Dashboard 和媒体索引尚未形成完整的跨资源多租户授权链。因此当前版本应仅暴露给可信 AstrBot 管理员,不应作为面向多个互不信任用户的公共工作台部署。
## 配置生图 Provider
生产生图需要一个 OpenAI 兼容的图片生成接口。请在 AstrBot 插件配置中填写至少以下字段:
```text
default_generation_model = image-main
generation_provider_base_url = https://provider.example.com
generation_provider_model = provider-model-id
generation_provider_route = image-main
generation_provider_api_key_env_var = IMAGESTUDIO_PROVIDER_API_KEY
```
然后在 AstrBot 进程环境中设置对应 API Key。无鉴权的本地 Provider 可以把 `generation_provider_api_key_env_var` 留空。Provider 未配置完整或调用失败时,生产模式会返回明确错误并把任务/节点标记为失败,不会把 mock 图片伪装成成功结果。完整示例见 [INSTALL.md](INSTALL.md)。
素材识别还需配置 `vision_provider_model`、`vision_provider_route` 和 `vision_provider_endpoint`。Vision 的 Provider ID、根地址、API Key 环境变量和超时可留空以复用生图 Provider;如果连接或超时不同但 ID 留空,插件会自动派生独立 Vision Provider ID,避免覆盖生图配置。识别模型必须显式填写。识别链会读取并校验真实 `storage://` 图片后发送 data URL,无有效路由或 Provider 失败时不会回退到 mock 结果。完整配置见 [INSTALL.md](INSTALL.md)。
## 主要功能
- 查看运行概览、队列、最近任务、最近图片和日志。
- 创建角色档案及角色工作流,按节点生成、重试、审查、采纳和归档图片。
- 管理素材分类、素材库、衣橱与穿搭匹配。
- 登记、确认和校验 OpenAI 兼容模型能力档案;当前 discovery endpoint 是安全的元数据检查,不会主动向任意地址发起探测请求。
- 使用 SQLite 零配置运行,或按需切换 PostgreSQL。
## 聊天命令
插件提供 `/影棚` 和短别名 `/yp`,两套命令行为一致。聊天权限在设置页“聊天权限”中配置。
```text
/yp 帮助
/yp 状态
/yp 单图 <提示词> [--角色 名称] [--模型 路由] [--尺寸 1K|2K|4K] [--数量 1-4]
/yp 快速角色 <角色名和描述>
/yp 确认
/yp 工作流 <角色名或ID>
/yp 节点 <workflow_id>
/yp 生成 <node_id>
/yp 下一步 <workflow_id>
/yp 候选图 <node_id>
/yp 选择 <序号>
/yp 审核 <node_id|workflow_id>
/yp 高清 <image_id> 2K|4K
/yp 素材导入 <分类名称或ID> (命令消息需附带图片)
/yp 加入衣橱 <material_id> <角色名或ID> <衣橱分类>
/yp 任务 [task_id]
/yp 取消 <task_id>
/yp 重试 <task_id>
```
快速角色和详细角色工作流要求群聊、用户白名单同时命中;单图允许任意一个白名单命中。聊天生成还受用户/群聊并发、每日额度和 2K/4K 开关约束。单图在后台线程执行,命令会立即返回请求 ID,完成后通过 AstrBot 统一消息来源主动发送图片。
## 持久化数据
运行数据统一放在 AstrBot 数据目录中:
```text
data/plugin_data/astrbot_plugin_imagestudio/
```
数据库、图片、缩略图、素材、归档和临时文件都应位于该目录下,不能依赖插件源码目录可写。安装、升级和打包细节见 [INSTALL.md](INSTALL.md),开发约定见 [DEVELOPMENT.md](DEVELOPMENT.md)。
本轮 AstrBot 兼容、后端、前端、功能闭环与安全审计记录见 [docs/code-audit-2026-07-10.md](docs/code-audit-2026-07-10.md)。