# 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//generate ``` ImageStudio 同时兼容两套路由前缀: - AstrBot v4.25 legacy bridge:`/api/plug/astrbot_plugin_imagestudio/`。 - 当前扩展 API:`/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。 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。 ## 持久化数据 运行数据统一放在 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)。