# ImageStudio 代码与功能审计(2026-07-10) ## 审计范围 本轮审计覆盖仓库中的 Python、TypeScript、Vue、HTML、YAML、JSON、SQL 迁移、脚本、测试和全部 Markdown 文档,重点核对: - AstrBot 插件生命周期、Plugin Page、Web API、Bridge 与持久化目录兼容性。 - 后端路由、服务、数据库外键、配置写入、Provider 调用、任务状态机和错误传播。 - 前端功能入口、API 契约、真实数据与示例数据边界、按钮行为和生产构建产物。 - 重复代码、可复用解析逻辑、生产 mock/fallback、SSRF、身份伪造和 owner 边界。 ## AstrBot 官方运行模式核对 官方资料: - [插件开发指南](https://docs.astrbot.app/dev/star/plugin-new.html) - [插件 Pages](https://docs.astrbot.app/dev/star/guides/plugin-pages.html) - [插件配置](https://docs.astrbot.app/dev/star/guides/plugin-config.html) - [插件存储](https://docs.astrbot.app/dev/star/guides/storage.html) - [AstrBot 官方仓库](https://github.com/AstrBotDevs/AstrBot) 核对结论: 1. 插件继承 `Star`;AstrBot 在启用时调用 `initialize()`,在停用或重载时调用 `terminate()`。 2. `pages//index.html` 会被自动发现,并在受限 iframe 中运行;页面通过 `window.AstrBotPluginPage` 调用后端。 3. 后端使用 `context.register_web_api(route, handler, methods, desc)` 注册,动态路径语法为 `` 和 ``。ImageStudio 的 `//` catch-all 与官方语法一致。 4. Page 端传相对 endpoint;Dashboard 转发到 `/api/v1/plugins/extensions//`。v4.25 legacy 前缀仍兼容 `/api/plug//`。 5. 当前官方 Bridge 的 JSON 操作以 GET/POST 为主;ImageStudio 对旧 Bridge 的 PUT/PATCH/DELETE 使用 POST method-override 信封兼容。 6. 官方 `PluginRequest` 提供 `username`、`client_host`、`query`、`json()` 和 `path_params` 等字段,不提供可用于细粒度角色授权的完整用户角色模型。 7. `get_astrbot_plugin_data_path()` 返回 AstrBot 的 `data/plugin_data` 根目录,插件仍需追加自己的插件名。因此运行数据正确位置是 `data/plugin_data/astrbot_plugin_imagestudio/`。 ## 已修复问题 ### AstrBot 接入与安全 - Bridge 不再信任 `x-username`、`x-user-id` 或 `x-forwarded-for` 作为身份来源。 - 用显式能力替代 wildcard 权限;任务重试同时要求 `can_write` 与 `can_retry_tasks`。 - Bridge 同步业务分发移到工作线程,长时间 Provider 请求不再阻塞 AstrBot 事件循环。 - Bridge 路由按方法只注册一个 catch-all,兼容官方 GET/POST 调用、POST method-override 信封和旧版 Quart 请求。 - 媒体下载优先使用 AstrBot `file_response`,避免生产请求整文件 base64 复制。 - Provider 限制 HTTP(S)、响应大小、图片魔数和同源重定向,并拒绝非显式允许的私网目标。 - Provider 错误正文中的 Bearer token、API key 与常见密钥字段会在记录和返回前脱敏。 ### 持久化与配置 - 运行数据库、媒体和可写配置映射到 AstrBot 插件数据目录。 - SQLite 强制启用外键。 - 配置、审查策略和集成 token 使用同目录临时文件、原子替换和进程内路径锁。 - YAML 标量解析修复引号内 `#` 和字符串类型漂移。 - 数据库配置切换会先初始化并验证目标数据库,验证失败时不会切换运行连接。 - AstrBot runtime override 管理的 DSN、数据库密码与 Provider API key 不会因设置保存、回滚或快照操作写入 YAML;掩码后的 diff 也不会误报变化。 - 生图和 Vision Provider 配置均可从 AstrBot 配置自动 bootstrap 到运行数据库,fresh install 不再缺少模型路由。 - 配置路由使用稳定 ID;模型变化或配置清空会停用旧路由,Vision 配置也不会覆盖生图 Provider。 ### Provider、媒体与生成上下文 - Provider 未配置或调用失败时,任务和节点进入失败状态;生产模式不再把 mock 图片当成功结果。 - 默认模型、档案默认模型、Prompt Expansion 和 Cost Guard 已接入生成请求。 - 上游节点图片、草稿参考图、stage input、显式参考图以及已确认素材都会真正传入 Provider,不再只保留 URI 元数据。 - `storage://` 图片会校验归属、数量、单图/总大小和文件魔数,再转换为带正确 MIME 的 data URL。 - 大型 inline data URL 不再持久化到任务数据库;若旧任务使用 inline 参考图,重试时必须提供替代参考图,不能静默丢失生成条件。 - `negative_prompt` 已贯通到兼容 Provider。官方 OpenAI/Azure OpenAI 默认关闭该未知字段,其他路由可通过 capabilities/settings 显式开关。 - PNG、JPEG、GIF 与 WebP 按真实魔数保存,并保持文件后缀、元数据 MIME、媒体响应与实际字节一致。 - Provider JSON 响应上限按请求图片数量和 Base64 开销动态计算,总硬上限为 128 MiB。 ### 任务、重试、取消与工作流 - 工作流初始状态执行枚举校验;非法状态不会落库。 - 未完成的生成节点会让工作流审查失败。 - 历史快照在写入前校验图片、工作流和节点归属,避免外键异常泄漏为未知错误。 - 虚拟单图节点允许连续发起生成,不会在第一次完成后永久锁死。 - node retry 与 job retry 都会执行真实、受控的同步重试,并生成新的幂等键、lineage、替代任务记录与有上限的 DLQ 记录。 - job retry 预检失败会恢复原任务和节点状态;并发重试使用 CAS,只有一个请求能取得执行权。 - task 运行、成功、失败和取消均使用比较并交换更新,陈旧请求不能覆盖终态。 - workflow 取消会级联取消其活跃 task/node;若 Provider 已在远程执行,返回结果会被拒绝提交,暂存图片元数据、原图和缩略图会清理。 - 同一 Provider 请求生成多张图时,usage 按 task 聚合,不再按每张输出图重复累计。 ### 素材、素材包与 Vision - Vision 识别会读取真实 `storage://` 图片,并校验文件大小、扩展名、MIME 和魔数后再发送给 Provider。 - Vision 未配置、调用失败或返回无效时不会回退 mock;素材保持 `pending_recognition`,且未成功识别的素材不能 confirm。 - 素材包在首条记录写入前对清单、文件、类型、重复 material ID 和所有条目执行确定性预检。 - 素材包 `styles` 当前明确报告为不支持,不再假报成功导入。 - confirmed 素材可由前端导入角色衣橱;未确认素材会被后端拒绝。 ### 前端与代码精简 - Plugin Page 删除重复轻量导航,直接复用完整 Workbench。 - API client 统一解包 AstrBot 与 ImageStudio 响应,并兼容旧 Bridge method override。 - 修复工作流详情解构、角色工作流后端 ID 同步、并发创建去重和素材选择假 ID。 - mock、provider error、fallback 和 degraded 图片不能被采纳、归档或作为后续参考图。 - 快速角色素材选择只提交真实、已确认的后端素材;示例素材只在预览/错误模式显示。 - completed 节点可以持久化切换候选图,selected 节点仍保持锁定;成本面板使用真实 Provider usage。 - 新增 `MaterialOperationDialog.vue`,提供已有 `storage://` 素材登记、素材包 dry-run/apply 和 confirmed 素材导入衣橱入口。 - 导航、指标卡、状态卡、空态、图片预览、素材分类和素材详情已拆为独立组件;外部角色卡解析已拆为纯函数 feature 模块。 - 状态、时间、容量、成本、集合去重和 `storage://` 校验已迁入共享工具,素材/队列/性能页的重复指标模板已合并。 - 搜索支持 Ctrl/Cmd+K、方向键和 Enter;移动导航显示标签,弹窗补齐焦点管理、Escape、safe-area 与 `100dvh`。 - 真实后端无模型或空素材库时不再伪装成示例数据;示例模型/素材只在明确的预览或错误模式显示。 - node retry 前端只发送一次请求;模型 discovery 文案明确为 metadata-only。 - 13 个 route 文件的重复字符串、数字和布尔参数解析已合并到 `backend/routes/params.py`。 - 生成参考图收集、任务重试、Provider bootstrap、配置安全写入、图片格式识别与远程抓取分别拆入独立服务/核心模块,减少路由与主流程中的重复实现。 ## 当前发布边界与延期项 以下项目不应被误解为已完成: 1. **完整多租户 owner 链**:角色档案已按身份隔离,但 workflow、node、image、job、wardrobe、Dashboard 和媒体仍未完成统一祖先链授权。当前产品边界是可信 AstrBot WebUI 管理员工作台。 2. **可信成本上限**:成本接口可以聚合 Provider usage,但服务端尚无可信价格表;调用方提供的 `unit_prices` 只能用于估算,不能作为强财务控制。 3. **持久后台 Worker**:生产重试采用受控同步重试闭环;尚未引入跨进程持久 worker、租约和原子 claim 调度器。进程被强制终止时,极端情况下可能遗留 `retrying` 状态,需要恢复任务或后续巡检。 4. **Provider 物理中止**:远程 HTTP 请求一旦发出无法可靠撤回;取消操作保证结果不提交并清理本地暂存结果,但不能保证上游 Provider 停止计费或计算。 5. **前端进一步拆分**:已抽出导航、指标/状态原语、图片预览、素材弹窗、角色卡解析及共享工具,但完整 `App.vue` Workbench 仍有约 18,138 行,后续应继续拆分工作流 store/actions、通知和异步资源 composable。 6. **模型 discovery 语义**:`api-discovery/probe-*` 当前只登记并校验能力元数据,不执行外部网络探测。真实可用性由配置后的 Provider 请求验证;UI 和文档不得把 metadata-only 操作描述为在线探测成功。 7. **素材包事务边界**:导入前已有完整、确定性的全包预检,但多条素材记录仍不是单一数据库事务;若底层数据库在写入阶段发生异常,可能需要人工处理已写入的前缀记录。 ## 最终验证 最终交付前已执行: ```powershell python -m compileall -q adapters backend core database engines scripts tests main.py cd frontend npm.cmd run typecheck npm.cmd run build:plugin npm.cmd run build:web ``` 结果: - 全量 Python:共 359 项,结果 OK,其中 1 项按环境条件跳过。 - 高风险组合回归:170 项全部通过。 - `compileall`:通过。 - 非 UI smoke:通过,111 条路由/handler 注册及调用健康。 - PostgreSQL smoke `--dry-run`:通过。 - `git diff --check`:通过;仅报告工作区 LF 将转 CRLF 的提示,无空白错误。 - 前端 `typecheck`、`build:plugin`、`build:web`:全部通过。 - 浏览器 UI smoke:桌面与 390×844 移动端渲染正常;导航固定、移动标签、Ctrl/Cmd+K 搜索、队列 tab、明暗主题和图片缩放弹窗通过,控制台无应用 error/warn。 最终构建产物: - `pages/imagestudio/assets/index-CF6dVfCE.js` - `pages/imagestudio/assets/index-D4NekmM3.css` - `web/assets/index-djgvYVE7.js` - `web/assets/index-VBJk7aNa.css` 旧 hash 产物已由构建流程移除。