diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e8a2dc8..fb2a18d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,77 +1,95 @@ -# Development Environment +# 开发约定 -## Scope +## AstrBot 运行契约 -The repository has completed the non-UI backend queue through `S120`. UI-only work remains separate. +ImageStudio 的生产宿主是 AstrBot `4.25.0` 及以上版本。 -Prepared: +- 插件入口是 `main.py` 中的 `Star` 子类。 +- AstrBot 调用 `initialize()` 和 `terminate()` 管理生命周期。 +- `initialize()` 通过 `context.register_web_api` 注册 API。 +- `pages/imagestudio/index.html` 由 AstrBot 自动发现为插件页面。 +- 插件页面 bridge 只接收 `ui/bootstrap` 这类相对 endpoint。 +- v4.25 legacy bridge 前缀为 `/api/plug/astrbot_plugin_imagestudio/`;当前直接 API 前缀为 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。 -- AstrBot plugin root files, runtime registration helpers, and v3 configuration placeholders. -- Backend API routes, route registry, permission matrix, contract export, and pure dispatch helpers. -- SQLite default database with optional PostgreSQL selection from `config.yaml`. -- `psycopg` and `psycopg2` PostgreSQL driver compatibility. -- Core repositories and services for profiles, workflows, nodes, jobs, images, materials, wardrobe, integrations, settings, review, costs, media, and model providers. -- Real image-provider path, VLM adapter interface, worker/retry/cancel infrastructure, budget guard, prompt expansion, token rotation, deletion safety, media indexing, and orphan scanning. -- Runtime data directories with `.gitkeep` files only. -- Generated data, local virtual environments, node modules, and build artifacts are ignored. +不要把内部辅助函数或自定义 web mount 当作 AstrBot 官方回调。也不要依赖 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web` 存在;`web/` 仅作为独立构建/兼容产物,生产插件页面以 `pages/imagestudio/` 为准。 -## Local Tools +## 目录职责 -On Windows, PowerShell may block `npm.ps1`; use `npm.cmd` when needed. +- `main.py`:AstrBot Star 生命周期与 Web API 接入。 +- `backend/routes/`:endpoint 适配层。 +- `backend/services/`:业务服务。 +- `database/`:数据库连接、仓储和迁移。 +- `frontend/plugin-page/`:AstrBot 插件页面源码,构建到 `pages/imagestudio/`。 +- `frontend/standalone-web/`:独立预览/兼容页面源码,构建到 `web/`。 +- `frontend/shared/`:两套前端共享的 API client、endpoint 和类型。 -Codex bundled tools are usually available under the local Codex runtime cache. The project itself does not require a standalone backend server for normal plugin use. +后端 endpoint 使用不带宿主前缀的形式维护,例如 `nodes/{node_id}/generate`。宿主适配层负责 legacy bridge 和当前 `/api/v1` 前缀的兼容,业务服务不应感知 URL 前缀。 -## Verification +## 持久化规则 -Run backend tests and non-UI smoke: +运行数据必须位于: ```text +data/plugin_data/astrbot_plugin_imagestudio/ +``` + +不要向插件源码目录写数据库、图片、日志或缓存。测试可使用临时目录,且不能把真实运行数据加入发布包。 + +`config.yaml` 保留 `data/db`、`data/images` 等逻辑路径;运行时路径解析层负责把前导 `data/` 替换为 AstrBot 插件数据根目录。本地开发则继续映射到仓库的 `data/`。不要在配置默认值中重复写完整 `data/plugin_data/astrbot_plugin_imagestudio/` 前缀。 + +## 本地前端开发 + +Windows 上若 PowerShell 阻止 `npm.ps1`,使用 `npm.cmd`: + +```powershell +cd frontend +npm.cmd install +npm.cmd run typecheck +npm.cmd run dev:plugin +``` + +`dev:plugin` 只用于本地开发。生产构建: + +```powershell +npm.cmd run build:plugin +``` + +它会更新 `pages/imagestudio/`。`dev:web` 与 `build:web` 只用于独立预览或兼容产物,不代表 AstrBot 注册了 `/web` 生产路由。 + +## 数据库后端 + +默认配置选择 SQLite。`backend: auto` 仅在 PostgreSQL 已启用且连接字段完整时切换到 PG;`backend: sqlite` 强制 SQLite;`backend: postgresql` 在驱动或配置缺失时快速失败。 + +PG 驱动是可选依赖,优先使用 `psycopg`,兼容回退到 `psycopg2`。不要在默认 `requirements.txt` 中启用 PG 驱动,以免 SQLite 用户被强制安装额外二进制依赖。 + +## 验证 + +```powershell python -m unittest discover -s tests python -m compileall adapters backend core database engines scripts tests main.py python scripts/imagestudio_non_ui_smoke.py python scripts/imagestudio_pg_smoke.py --dry-run + +cd frontend +npm.cmd run typecheck +npm.cmd run build:plugin +npm.cmd run build:web ``` -Set `IMAGESTUDIO_TEST_PG_DSN` before `python -m unittest tests.test_pg_smoke` to run a live PostgreSQL smoke. +设置 `IMAGESTUDIO_TEST_PG_DSN` 后,可运行 `python -m unittest tests.test_pg_smoke` 做真实 PG smoke。 -## API Contract +生产构建必须同时提交 `pages/imagestudio/` 的最新插件页面产物。`web/` 仅是独立预览兼容产物,但若仓库保留它,也应与同一份前端源码同步构建,避免两个产物行为漂移。 -The backend contract is available from: +## API 契约 + +契约 endpoint 为相对路径: ```text GET contract ``` -The exported contract includes `api_base`, routes, permissions, error codes, and the standard success/error response shape. - -## Database Backend - -Default behavior: +插件页面通过 bridge 调用时传 `contract`;直接请求时使用: ```text -database.backend = auto -postgresql.enabled = false -selected backend = sqlite +GET /api/v1/plugins/extensions/astrbot_plugin_imagestudio/contract ``` - -When PostgreSQL is configured: - -```yaml -database: - backend: auto - postgresql: - enabled: true - host: 127.0.0.1 - port: 5432 - database: imagestudio - user: imagestudio - password: "" -``` - -With `backend: auto`, enabling a complete PostgreSQL config makes PostgreSQL the selected backend. Use `backend: sqlite` to force SQLite even when PostgreSQL fields exist, or `backend: postgresql` to fail fast when PG config/driver is missing. - -PostgreSQL support is optional and imports `psycopg` first, then falls back to `psycopg2`. - -## Runtime Rule - -Do not start a separate FastAPI, Flask, or Vite production port for the plugin. Dev servers may only be used for local frontend development before build output is copied into AstrBot static paths. diff --git a/INSTALL.md b/INSTALL.md index 15ebf07..67f9e74 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,40 +1,164 @@ -# Installation and Packaging +# 安装与打包 -ImageStudio is an AstrBot plugin. Do not run it as a standalone FastAPI, Flask, or Vite production service. +ImageStudio 是 AstrBot 插件,不是独立 Web 服务。 -## Install Into AstrBot +## 兼容性 -1. Clone or copy this repository into AstrBot's plugin directory as `astrbot_plugin_imagestudio`. -2. Keep the repository root files in place: `metadata.yaml`, `main.py`, `config.yaml`, `_conf_schema.json`. -3. Restart or reload AstrBot so it can discover the plugin metadata. -4. AstrBot should call `main.get_plugin_manifest()` or `main.register_plugin(runtime)` to discover extension routes and the web mount. +- AstrBot `>= 4.25.0`。 +- Windows、Linux、macOS 与 Docker(以 AstrBot 本身支持的平台为准)。 +- Python 版本跟随对应 AstrBot 发行版。 +- SQLite 默认可用;PostgreSQL 需要额外安装驱动。 -The backend API is mounted under: +## 安装到 AstrBot + +推荐通过 AstrBot 插件管理器安装。手工安装时,将仓库完整复制到 AstrBot 配置的插件目录,目录名保持为 `astrbot_plugin_imagestudio`;常见安装位置为: ```text -/api/v1/plugins/extensions/astrbot_plugin_imagestudio +data/plugins/astrbot_plugin_imagestudio/ ``` -The standalone web entry is mounted under: +至少保留以下运行文件和目录: ```text -/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web +main.py +metadata.yaml +_conf_schema.json +config.yaml +pages/imagestudio/index.html +adapters/ +backend/ +core/ +database/ +engines/ ``` -## Database +重启或在 AstrBot 中重载插件。AstrBot 会发现 `Star` 插件类,调用其 `initialize()`;停用或重载时调用 `terminate()`。插件在 `initialize()` 中使用 `context.register_web_api` 注册 API。 -SQLite is the default and requires no extra service: +## 插件页面与 API + +AstrBot 自动发现 `pages/imagestudio/index.html`。请从 AstrBot 插件管理界面打开页面,不要把未注册的 `/web` 静态目录当作生产入口。 + +页面 bridge 使用相对 endpoint: + +```text +ui/bootstrap +jobs +settings/current +``` + +兼容路由如下: + +```text +# AstrBot v4.25 legacy bridge +/api/plug/astrbot_plugin_imagestudio/ + +# 当前直接 API +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/ +``` + +`window.AstrBotPluginPage.apiGet("ui/bootstrap")` 这类 bridge 调用只传相对 endpoint;直接请求才拼接当前 `/api/v1/plugins/extensions/...` 前缀。 + +## 配置图片生成 Provider + +ImageStudio 不内置可直接用于生产的云端模型。首次生图前,请在 AstrBot 的插件配置页填写: + +```text +default_generation_model: image-main +generation_provider_id: imagestudio_default +generation_provider_base_url: https://provider.example.com +generation_provider_image_endpoint: /v1/images/generations +generation_provider_model: provider-model-id +generation_provider_route: image-main +generation_provider_api_key_env_var: IMAGESTUDIO_PROVIDER_API_KEY +generation_provider_timeout_seconds: 180 +``` + +并在启动 AstrBot 的进程环境中提供密钥,例如: + +```powershell +$env:IMAGESTUDIO_PROVIDER_API_KEY = "replace-with-secret" +``` + +对应的 `config.yaml` 结构为: + +```yaml +generation: + default_model: image-main + provider: + provider_id: imagestudio_default + base_url: https://provider.example.com + image_endpoint: /v1/images/generations + model_id: provider-model-id + route_name: image-main + api_key_env_var: IMAGESTUDIO_PROVIDER_API_KEY + timeout_seconds: 180 +``` + +`route_name` 是 ImageStudio 使用的逻辑路由名,`model_id` 是 Provider 接收的真实模型名。无鉴权的本地 Provider 可以留空 `api_key_env_var`;除此之外不要把 API Key 直接写入仓库或 `config.yaml`。配置不完整时,生图接口会返回 `MODEL_CAPABILITY_UNCONFIRMED`;Provider 请求失败时任务和节点会进入失败状态,不会使用 mock 结果冒充生产成功。 + +## 配置素材视觉识别 Provider + +素材识别需要一个支持图片输入的 OpenAI 兼容多模态模型。在 AstrBot 插件配置页至少填写模型和路由;连接字段留空时会复用上面的生图 Provider。若 Vision 地址、密钥或超时不同而 ID 留空,插件会自动派生独立 Provider ID,避免覆盖生图配置: + +```text +vision_provider_model: vision-model-id +vision_provider_route: material_vlm +vision_provider_endpoint: /v1/chat/completions +``` + +如需使用独立的视觉服务,可再填写: + +```text +vision_provider_id: vision_provider +vision_provider_base_url: https://vision-provider.example.com +vision_provider_api_key_env_var: IMAGESTUDIO_VISION_API_KEY +vision_provider_timeout_seconds: 180 +vision_provider_enabled: true +``` + +等价的 `config.yaml` 配置如下。`provider_id`、`base_url`、`api_key_env_var` 和超时留空时均复用 `generation.provider`,但 `model_id` 必须显式配置: + +```yaml +vision: + default_route: material_vlm + provider: + provider_id: "" + base_url: "" + vision_endpoint: /v1/chat/completions + model_id: vision-model-id + route_name: material_vlm + api_key_env_var: "" + timeout_seconds: 180 + enabled: true +``` + +识别时 ImageStudio 会从插件 VFS 读取 `storage://` 素材文件,校验实际大小、扩展名和 PNG/JPEG/GIF/WebP 文件签名,再编码为 `data:image/...;base64` 发送给视觉 Provider。未配置有效路由或密钥时接口返回 `MODEL_CAPABILITY_UNCONFIRMED`;Provider 调用失败时素材保持 `pending_recognition`,只记录脱敏后的失败类型,不会生成或允许确认 mock 提示词与标签。 + +## 运行数据 + +AstrBot 插件的持久化数据根目录为: + +```text +data/plugin_data/astrbot_plugin_imagestudio/ +``` + +默认 SQLite 配置: ```yaml database: backend: auto sqlite: + # 逻辑路径;AstrBot 运行时映射到插件数据目录 path: data/db/imagestudio.db postgresql: enabled: false ``` -PostgreSQL is selected when `backend: postgresql`, or when `backend: auto` and `postgresql.enabled` plus connection fields are configured. +配置中的 `data/...` 是可移植的逻辑路径,AstrBot 运行时会把它映射到上述插件数据根目录;不要在配置里再次手工拼接 `data/plugin_data/astrbot_plugin_imagestudio`,否则可能产生重复目录。图片、素材、缩略图、归档和临时文件也位于同一个插件数据根目录。升级插件源码时不要删除该目录;备份时应单独备份它。 + +## 可选 PostgreSQL + +选择 `backend: postgresql`,或在 `backend: auto` 下启用并完整配置 PostgreSQL 后,ImageStudio 会使用 PG: ```yaml database: @@ -48,59 +172,50 @@ database: password: "" ``` -The plugin supports either `psycopg` or `psycopg2` when PostgreSQL is selected. +默认 SQLite 不需要第三方数据库驱动。为避免给所有安装者强制安装 PG 驱动,`requirements.txt` 中不启用 PostgreSQL 依赖;需要 PG 时任选其一安装: -## Secrets +```powershell +python -m pip install "psycopg[binary]>=3.1" +# 或兼容驱动 +python -m pip install "psycopg2-binary>=2.9" +``` -Do not commit `.env*`, API keys, DSNs, or integration tokens. Runtime tokens are rotated through: +## 密钥 + +不要提交 `.env*`、API Key、DSN、数据库密码或集成 token。私伴集成 token 的轮换 endpoint 为: ```text POST integrations/private-companion/token/rotate ``` -The rotate response returns the new token once. Config stores only salt and hash. +返回的新 token 只展示一次,配置仅保存 salt 与 hash。 -## Smoke Checks - -Run the non-UI backend smoke: +## 验证 ```powershell python scripts/imagestudio_non_ui_smoke.py -``` - -Run the PostgreSQL plan without connecting: - -```powershell python scripts/imagestudio_pg_smoke.py --dry-run -``` - -Run full tests: - -```powershell python -m unittest discover -s tests python -m compileall adapters backend core database engines scripts tests main.py ``` -Optional live PostgreSQL smoke: +可选的真实 PostgreSQL smoke: ```powershell $env:IMAGESTUDIO_TEST_PG_DSN = "postgresql://user:password@127.0.0.1:5432/imagestudio_test" python -m unittest tests.test_pg_smoke ``` -## Package +## 打包 -Use Git so ignored local data and secrets are excluded: +使用 Git 归档可自动排除未跟踪的本地数据和多数开发产物: ```powershell git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD ``` -The package should include source modules, migrations, built/static assets, config templates, and docs. It should not include: +发布包应包含源码、迁移、`pages/imagestudio/` 构建产物、配置模板和文档;不应包含: -- `.git/` -- `.env*` -- `data/*` runtime contents -- `node_modules/` -- `__pycache__/` -- local test databases or generated media +- `.git/`、`.env*`、`node_modules/`、`__pycache__/`。 +- `data/plugin_data/astrbot_plugin_imagestudio/` 中的任何运行数据。 +- 本地测试数据库、生成图片、日志、缓存或密钥。 diff --git a/README.md b/README.md index 01b12a5..33cab53 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,87 @@ # AstrBot ImageStudio -ImageStudio 是一个给 AstrBot 使用的角色资产与生图工作台插件。它把角色档案、工作流、素材库、衣橱、队列、日志和模型能力探测放在同一个插件里,方便后续为角色持续生成、筛选和管理图片。 +ImageStudio 是运行在 AstrBot 内的角色资产与生图工作台插件,提供角色档案、工作流、素材库、衣橱、任务队列、日志和模型能力档案等功能。 -## 现在能用什么 +## 兼容范围 -- 查看插件运行概览、队列状态、最近任务和最近图片。 -- 创建角色档案,维护基础设定、外观提示词、风格提示词和默认模型路由。 -- 创建角色工作流,按节点生成、重试、采纳、选择或归档图片。 -- 管理素材库、素材分类、衣橱条目,并做每日穿搭匹配。 -- 查看任务队列、失败任务、死信队列、生成日志、错误日志和审计日志。 -- 探测 OpenAI 兼容生图接口的能力,保存模型/路线能力档案。 -- 默认使用 SQLite;在配置 PostgreSQL 后可以切换到 PG 数据库。 -- 提供 AstrBot 插件卡片概览页,也提供独立的星图导航工作台入口。 +- AstrBot:`4.25.0` 及以上。 +- 运行平台:AstrBot 支持的 Windows、Linux、macOS 和 Docker 环境。 +- 数据库:默认 SQLite;PostgreSQL 为可选后端。 +- 生产运行方式:由 AstrBot 加载插件,不启动独立 FastAPI、Flask 或 Vite 服务。 -## 怎么打开 +## AstrBot 加载方式 -在 AstrBot 插件页面打开 ImageStudio 时,默认看到的是轻量星图概览页:它用于确认插件状态、队列、最近图片和快捷入口。 +AstrBot 通过 `main.py` 中的 `Star` 插件类自动发现 ImageStudio,并管理其生命周期: -完整工作台在概览页的“工作台”入口里,路径由 AstrBot 挂载到: +- `initialize()`:读取 AstrBot 配置、初始化持久化数据,并通过 `context.register_web_api` 注册插件 API。 +- `terminate()`:插件停用或重载时释放运行资源。 +- `pages/imagestudio/index.html`:由 AstrBot 自动发现为插件页面,无需手工注册静态 `/web` 入口。 + +## 打开界面 + +安装并重载插件后,从 AstrBot 的插件管理界面打开 ImageStudio。生产页面来自: ```text -/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web +pages/imagestudio/index.html ``` -## 当前 UI 状态 +仓库中的 `web/` 是独立前端构建/兼容产物。除非宿主显式注册对应静态路由,否则 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web` 不是 AstrBot 保证提供的生产入口。 -插件卡片页目前是轻量入口,这是有意保留的 AstrBot 内嵌页面,不代表后端功能只有这一页。 +## API 兼容模式 -独立工作台已经切换为星图导航页:左侧图标导航用于切换概览、生成、队列、图库、角色、素材、设置和日志;顶部提供功能搜索、日夜主题、通知和调色盘;主区域聚合当前队列、最近图片、智能工作建议和右侧性能监控。 +插件页面优先使用 `window.AstrBotPluginPage` bridge。传给 `apiGet`、`apiPost`、`apiPut` 或 `apiDelete` 的值必须是相对 endpoint,例如: -当前导航页已接入 `dashboard/summary`、`jobs`、`logs/generation` 和 `logs/errors` 等真实接口,并为接口失败、空队列、无图片和日志为空的情况提供可读状态。后续详情页会继续沿用这套导航入口接入更完整的生成、图库、角色和设置操作流。 +```text +ui/bootstrap +dashboard/summary +nodes//generate +``` -## 配置说明 +ImageStudio 同时兼容两套路由前缀: -AstrBot 小齿轮设置用于安装后最常改的项目:默认模型、私伴插件集成、SQLite/PG 数据库配置。 +- 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` 前缀。 -安装、打包、数据库和 smoke 测试命令见 [INSTALL.md](INSTALL.md)。 +## 运行与权限边界 + +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)。 diff --git a/_conf_schema.json b/_conf_schema.json index c3ef70d..d4a8128 100644 --- a/_conf_schema.json +++ b/_conf_schema.json @@ -1,9 +1,84 @@ { "default_generation_model": { - "description": "默认生图模型或模型路由名。留空时由工作流或能力探测结果选择。", + "description": "默认生图路由名。generation_provider_route 留空时也使用此值。", "type": "string", "default": "" }, + "generation_provider_id": { + "description": "OpenAI 兼容生图提供方 ID。", + "type": "string", + "default": "imagestudio_default" + }, + "generation_provider_base_url": { + "description": "OpenAI 兼容生图 API 根地址,例如 https://api.openai.com。", + "type": "string", + "default": "" + }, + "generation_provider_image_endpoint": { + "description": "生图 endpoint。", + "type": "string", + "default": "/v1/images/generations" + }, + "generation_provider_model": { + "description": "提供方实际模型 ID;留空时复用默认生图路由名。", + "type": "string", + "default": "" + }, + "generation_provider_route": { + "description": "ImageStudio 模型路由名;留空时复用 default_generation_model。", + "type": "string", + "default": "" + }, + "generation_provider_api_key_env_var": { + "description": "保存 API Key 的环境变量名。无鉴权的本地提供方可留空。", + "type": "string", + "default": "" + }, + "generation_provider_timeout_seconds": { + "description": "生图请求超时秒数。", + "type": "string", + "default": "180" + }, + "vision_provider_id": { + "description": "素材视觉识别提供方 ID;连接配置与生图 Provider 一致时留空可复用,否则会自动派生独立 ID。", + "type": "string", + "default": "" + }, + "vision_provider_base_url": { + "description": "素材视觉识别 API 根地址;留空时复用生图提供方地址。", + "type": "string", + "default": "" + }, + "vision_provider_endpoint": { + "description": "OpenAI 兼容视觉识别 endpoint。", + "type": "string", + "default": "/v1/chat/completions" + }, + "vision_provider_model": { + "description": "素材视觉识别使用的真实多模态模型 ID。该字段必须显式配置。", + "type": "string", + "default": "" + }, + "vision_provider_route": { + "description": "ImageStudio 素材视觉识别逻辑路由名。", + "type": "string", + "default": "material_vlm" + }, + "vision_provider_api_key_env_var": { + "description": "视觉识别 API Key 的环境变量名;留空时复用生图提供方配置。", + "type": "string", + "default": "" + }, + "vision_provider_timeout_seconds": { + "description": "素材视觉识别请求超时秒数。", + "type": "string", + "default": "180" + }, + "vision_provider_enabled": { + "description": "是否启用素材视觉识别路由。", + "type": "bool", + "default": true + }, "enable_private_companion_integration": { "description": "允许 astrbot_plugin_private_companion 调用 ImageStudio 的穿搭和素材集成接口。", "type": "bool", @@ -15,7 +90,7 @@ "default": "auto" }, "sqlite_path": { - "description": "SQLite 数据库文件路径。默认放在插件目录的 data/db/imagestudio.db。", + "description": "SQLite 逻辑路径。AstrBot 运行时会把 data/... 映射到 data/plugin_data/astrbot_plugin_imagestudio/...;默认物理落点为该插件数据目录下的 db/imagestudio.db。", "type": "string", "default": "data/db/imagestudio.db" }, diff --git a/adapters/astrbot_adapter.py b/adapters/astrbot_adapter.py index e1808f6..1f35b42 100644 --- a/adapters/astrbot_adapter.py +++ b/adapters/astrbot_adapter.py @@ -44,9 +44,12 @@ def normalize_extension_path(path: str) -> str: def resolve_route(method: str, path: str) -> RouteMatch | None: normalized_method = str(method or "").strip().upper() endpoint = normalize_extension_path(path) - for route in ROUTES: - if route.method != normalized_method: - continue + candidates = sorted( + (route for route in ROUTES if route.method == normalized_method), + key=_route_specificity, + reverse=True, + ) + for route in candidates: params = _match_endpoint(route.endpoint, endpoint) if params is None: continue @@ -61,6 +64,21 @@ def resolve_route(method: str, path: str) -> RouteMatch | None: return None +def _route_specificity(route: RouteSpec) -> tuple[int, int, int]: + """Prefer concrete routes over parameterized routes. + + Route manifests are maintained by feature area, so relying on declaration + order makes a generic route such as ``jobs/{task_id}/retry`` shadow + ``jobs/dead-letter/retry``. Literal segment count is the primary signal; + total segment count and fewer parameters break ties deterministically. + """ + + segments = [segment for segment in route.endpoint.split("/") if segment] + parameter_count = sum(1 for segment in segments if segment.startswith("{") and segment.endswith("}")) + literal_count = len(segments) - parameter_count + return literal_count, len(segments), -parameter_count + + def runtime_route_table() -> list[dict[str, Any]]: return [ { diff --git a/backend/README.md b/backend/README.md index 6408f69..7bc3511 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,13 +1,16 @@ # Backend -The backend exposes v3 P0 APIs through AstrBot plugin extension routes. +后端由 AstrBot 插件生命周期托管,不启动独立 Web 服务。 -Initial backend tasks: +- `main.py` 中的 `Star` 子类在 `initialize()` 阶段调用 `context.register_web_api`。 +- `terminate()` 用于插件停用或重载时清理资源。 +- route registry 和业务层只维护 `ui/bootstrap`、`profiles`、`nodes/{node_id}/generate` 等相对 endpoint。 +- AstrBot v4.25 插件页面 bridge 兼容 `/api/plug/astrbot_plugin_imagestudio/`。 +- 当前直接调用兼容 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。 +- 前端 bridge 必须传相对 endpoint,不能传完整宿主 URL。 -- Common response DTO and error code handling. -- Request context, permission checks, and request id creation. -- Audit logging foundation. -- Database helper and migration runner. -- Route modules for `ui/bootstrap`, `dashboard/summary`, profiles, workflows, nodes, images, jobs, settings, storage, media, and web hosting. +插件 UI 由 `pages/imagestudio/index.html` 自动发现。未注册的 `/web` 目录不是生产入口。 -Do not start a separate web server. Register routes through AstrBot plugin extension APIs. +SQLite、媒体、日志和缓存等运行数据应写入 `data/plugin_data/astrbot_plugin_imagestudio/`,不要写入插件源码目录。 + +当前 API 的产品边界是可信 AstrBot WebUI 管理员工作台。角色档案已按调用身份过滤,但其他资源尚未完成统一祖先链 owner 授权;在补齐该授权与跨用户回归测试前,不应把本插件作为互不信任用户共享的多租户服务发布。 diff --git a/backend/dto/common.py b/backend/dto/common.py index d602f4a..2ddc536 100644 --- a/backend/dto/common.py +++ b/backend/dto/common.py @@ -17,6 +17,7 @@ class ErrorCode(StrEnum): TASK_NOT_CANCELABLE = "TASK_NOT_CANCELABLE" MODEL_CAPABILITY_UNCONFIRMED = "MODEL_CAPABILITY_UNCONFIRMED" MODEL_CAPABILITY_UNSUPPORTED = "MODEL_CAPABILITY_UNSUPPORTED" + GENERATION_FAILED = "GENERATION_FAILED" STORAGE_WRITE_FAILED = "STORAGE_WRITE_FAILED" MEDIA_NOT_FOUND = "MEDIA_NOT_FOUND" UPLOAD_TOO_LARGE = "UPLOAD_TOO_LARGE" diff --git a/backend/dto/image_dto.py b/backend/dto/image_dto.py index 7759995..dc7242a 100644 --- a/backend/dto/image_dto.py +++ b/backend/dto/image_dto.py @@ -52,3 +52,19 @@ class GenerationImage: "metadata": self.metadata, "created_at": self.created_at, } + + +@dataclass(frozen=True) +class ImageListResult: + items: list[GenerationImage] + total: int + page: int + page_size: int + + def to_dict(self) -> dict[str, Any]: + return { + "items": [item.to_dict() for item in self.items], + "total": self.total, + "page": self.page, + "page_size": self.page_size, + } diff --git a/backend/dto/profile_dto.py b/backend/dto/profile_dto.py index 62a2409..ae3f347 100644 --- a/backend/dto/profile_dto.py +++ b/backend/dto/profile_dto.py @@ -25,6 +25,7 @@ class CharacterProfile: metadata: dict[str, Any] created_at: str updated_at: str + generation_kind: str = "ungenerated" def to_dict(self) -> dict[str, Any]: return { @@ -45,6 +46,7 @@ class CharacterProfile: "metadata": self.metadata, "created_at": self.created_at, "updated_at": self.updated_at, + "generation_kind": self.generation_kind, } diff --git a/backend/route_registry.py b/backend/route_registry.py index 5a9f406..5a14209 100644 --- a/backend/route_registry.py +++ b/backend/route_registry.py @@ -19,6 +19,12 @@ PERMISSION_MATRIX: dict[str, dict[str, Any]] = { "required_permission": "can_manage_materials", "description": "material library management", }, + "retry": { + "auth_required": True, + "required_permission": "can_retry_tasks", + "required_permissions": ["can_write", "can_retry_tasks"], + "description": "task retry management (write + retry capabilities)", + }, "public_token": {"auth_required": False, "required_permission": None, "description": "signed public token"}, } @@ -39,6 +45,10 @@ class RouteSpec: "permission": self.permission, "auth_required": matrix["auth_required"], "required_permission": matrix["required_permission"], + "required_permissions": list( + matrix.get("required_permissions") + or ([matrix["required_permission"]] if matrix["required_permission"] else []) + ), } @@ -74,7 +84,7 @@ ROUTES: tuple[RouteSpec, ...] = ( RouteSpec("GET", "nodes/{node_id}/dependency-context", "backend.routes.node_routes.get_node_dependency_context", "read"), RouteSpec("PUT", "nodes/{node_id}", "backend.routes.node_routes.update_node", "write"), RouteSpec("POST", "nodes/{node_id}/generate", "backend.routes.node_routes.generate_node", "write"), - RouteSpec("POST", "nodes/{node_id}/retry", "backend.routes.node_routes.retry_node", "write"), + RouteSpec("POST", "nodes/{node_id}/retry", "backend.routes.node_routes.retry_node", "retry"), RouteSpec("POST", "nodes/{node_id}/complete", "backend.routes.node_routes.mark_node_completed", "write"), RouteSpec("POST", "nodes/{node_id}/mark-completed", "backend.routes.node_routes.mark_node_completed", "write"), RouteSpec("POST", "nodes/{node_id}/select-image", "backend.routes.node_routes.select_node_image", "write"), @@ -86,6 +96,7 @@ ROUTES: tuple[RouteSpec, ...] = ( RouteSpec("GET", "nodes/{node_id}/review", "backend.routes.review_routes.review_node", "read"), RouteSpec("GET", "nodes/{node_id}/images", "backend.routes.image_routes.list_node_images", "read"), RouteSpec("GET", "workflows/{workflow_id}/review", "backend.routes.review_routes.review_workflow", "read"), + RouteSpec("GET", "images", "backend.routes.image_routes.list_images", "read"), RouteSpec("GET", "images/{image_id}", "backend.routes.image_routes.get_image", "read"), RouteSpec("POST", "images/{image_id}/select", "backend.routes.image_routes.select_image", "write"), RouteSpec("POST", "images/{image_id}/unselect", "backend.routes.image_routes.unselect_image", "write"), @@ -95,9 +106,9 @@ ROUTES: tuple[RouteSpec, ...] = ( RouteSpec("GET", "jobs", "backend.routes.job_routes.list_jobs", "read"), RouteSpec("GET", "jobs/{task_id}", "backend.routes.job_routes.get_job", "read"), RouteSpec("POST", "jobs/{task_id}/cancel", "backend.routes.job_routes.cancel_job", "write"), - RouteSpec("POST", "jobs/{task_id}/retry", "backend.routes.job_routes.retry_job", "write"), - RouteSpec("POST", "jobs/dead-letter/retry", "backend.routes.job_routes.retry_dead_letter_jobs", "write"), - RouteSpec("POST", "jobs/dead-letter/move-failed", "backend.routes.job_routes.move_failed_jobs_to_dead_letter", "write"), + RouteSpec("POST", "jobs/{task_id}/retry", "backend.routes.job_routes.retry_job", "retry"), + RouteSpec("POST", "jobs/dead-letter/retry", "backend.routes.job_routes.retry_dead_letter_jobs", "retry"), + RouteSpec("POST", "jobs/dead-letter/move-failed", "backend.routes.job_routes.move_failed_jobs_to_dead_letter", "retry"), RouteSpec("GET", "costs/usage", "backend.routes.cost_routes.get_cost_usage", "read"), RouteSpec("POST", "costs/guard", "backend.routes.cost_routes.check_cost_guard", "read"), RouteSpec("GET", "settings/schema", "backend.routes.settings_routes.get_settings_schema", "read"), diff --git a/backend/routes/asset_routes.py b/backend/routes/asset_routes.py index 28976cb..3aa3dc9 100644 --- a/backend/routes/asset_routes.py +++ b/backend/routes/asset_routes.py @@ -6,6 +6,7 @@ from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.routes.common import handle_request +from backend.routes.params import as_bool from backend.services.asset_import_service import AssetImportService from backend.services.material_service import MaterialService from core.audit_service import AuditService @@ -29,7 +30,7 @@ def import_asset_pack( raise ApiError(ErrorCode.VALIDATION_FAILED, "package_uri is required", {"field": "package_uri"}) return asset_service.plan_import_pack( package_uri, - dry_run=_as_bool(payload.get("dry_run"), default=True), + dry_run=as_bool(payload.get("dry_run"), default=True), ctx=ctx, ) @@ -44,11 +45,3 @@ def _create_asset_import_service() -> AssetImportService: audit_service=AuditService(database), ) ) - - -def _as_bool(value: Any, *, default: bool = False) -> bool: - if value is None: - return default - if isinstance(value, bool): - return value - return str(value).strip().lower() in {"1", "true", "yes", "on"} diff --git a/backend/routes/cost_routes.py b/backend/routes/cost_routes.py index 542e5d3..edec24f 100644 --- a/backend/routes/cost_routes.py +++ b/backend/routes/cost_routes.py @@ -6,6 +6,7 @@ import json from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_float, optional_int, optional_str from backend.services.cost_guard_service import CostGuardService from backend.services.cost_service import CostService from core.identity import RequestContext @@ -24,11 +25,11 @@ def get_cost_usage( def action() -> dict[str, Any]: require_authenticated(ctx) return cost_service.usage_summary( - profile_id=_optional_str(params.get("profile_id")), - workflow_id=_optional_str(params.get("workflow_id")), - node_id=_optional_str(params.get("node_id")), - provider_id=_optional_str(params.get("provider_id")), - days=_optional_int(params.get("days")), + profile_id=optional_str(params.get("profile_id")), + workflow_id=optional_str(params.get("workflow_id")), + node_id=optional_str(params.get("node_id")), + provider_id=optional_str(params.get("provider_id")), + days=optional_int(params.get("days")), unit_prices=_unit_prices(params.get("unit_prices")), ) @@ -46,16 +47,16 @@ def check_cost_guard( def action() -> dict[str, Any]: require_authenticated(ctx) return guard_service.check_generation_budget( - provider_id=_optional_str(params.get("provider_id")), - provider_model=_optional_str(params.get("provider_model")), - model_route=_optional_str(params.get("model_route")), - planned_task_count=_int_or_default(params.get("planned_task_count"), 1), - planned_image_count=_int_or_default(params.get("planned_image_count"), 1), - planned_total_tokens=_int_or_default(params.get("planned_total_tokens"), 0), - max_task_count=_optional_int(params.get("max_task_count")), - max_image_count=_optional_int(params.get("max_image_count")), - max_estimated_cost=_optional_float(params.get("max_estimated_cost")), - days=_optional_int(params.get("days")), + provider_id=optional_str(params.get("provider_id")), + provider_model=optional_str(params.get("provider_model")), + model_route=optional_str(params.get("model_route")), + planned_task_count=int_or_default(params.get("planned_task_count"), 1), + planned_image_count=int_or_default(params.get("planned_image_count"), 1), + planned_total_tokens=int_or_default(params.get("planned_total_tokens"), 0), + max_task_count=optional_int(params.get("max_task_count")), + max_image_count=optional_int(params.get("max_image_count")), + max_estimated_cost=optional_float(params.get("max_estimated_cost")), + days=optional_int(params.get("days")), unit_prices=_unit_prices(params.get("unit_prices")), ) @@ -77,35 +78,3 @@ def _unit_prices(value: Any) -> dict[str, Any]: return {} return parsed if isinstance(parsed, dict) else {} return {} - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _optional_int(value: Any) -> int | None: - if value is None or value == "": - return None - try: - return int(value) - except (TypeError, ValueError): - return None - - -def _optional_float(value: Any) -> float | None: - if value is None or value == "": - return None - try: - return float(value) - except (TypeError, ValueError): - return None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/event_routes.py b/backend/routes/event_routes.py index e9ad1d6..f66caeb 100644 --- a/backend/routes/event_routes.py +++ b/backend/routes/event_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.event_stream_service import EventStreamService from core.identity import RequestContext from core.security import require_authenticated @@ -21,22 +22,8 @@ def get_event_stream( def action() -> dict[str, Any]: require_authenticated(ctx) return event_service.recent_events( - event_type=_optional_str(params.get("event_type")), - limit=_int_or_default(params.get("limit"), 50), + event_type=optional_str(params.get("event_type")), + limit=int_or_default(params.get("limit"), 50), ) return handle_request(ctx, action) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/history_routes.py b/backend/routes/history_routes.py index c0a2bf1..7929159 100644 --- a/backend/routes/history_routes.py +++ b/backend/routes/history_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import optional_str from backend.services.history_service import HistoryService from backend.services.image_service import ImageService from backend.services.workflow_service import WorkflowService @@ -43,7 +44,7 @@ def list_workflow_history( def action() -> list[dict[str, Any]]: require_authenticated(ctx) - node_id = _optional_str(params.get("node_id")) + node_id = optional_str(params.get("node_id")) return [entry.to_dict() for entry in history_service.list_workflow_history(workflow_id, node_id=node_id)] return handle_request(ctx, action) @@ -84,10 +85,3 @@ def _create_history_service() -> HistoryService: image_service=image_service, audit_service=audit_service, ) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None diff --git a/backend/routes/image_routes.py b/backend/routes/image_routes.py index 9071dfe..9f47a8b 100644 --- a/backend/routes/image_routes.py +++ b/backend/routes/image_routes.py @@ -5,8 +5,9 @@ from __future__ import annotations from typing import Any from backend.dto.common import ApiError -from backend.dto.image_dto import GenerationImage +from backend.dto.image_dto import GenerationImage, ImageListResult from backend.routes.common import handle_request +from backend.routes.params import as_bool, int_or_default, optional_str from backend.services.deletion_safety_service import DeletionSafetyService from backend.services.image_service import ImageService from backend.services.media_service import MediaService @@ -18,6 +19,30 @@ from database.repositories.image_repository import ImageRepository from database.repositories.workflow_repository import WorkflowRepository +def list_images( + ctx: RequestContext, + query: dict[str, Any] | None = None, + service: ImageService | None = None, + media_service: MediaService | None = None, +) -> dict: + image_service = service or _create_image_service() + signer = media_service or MediaService() + params = query or {} + + def action() -> dict[str, Any]: + require_authenticated(ctx) + result = image_service.list_images( + profile_id=optional_str(params.get("profile_id")), + workflow_id=optional_str(params.get("workflow_id")), + include_archived=as_bool(params.get("include_archived"), default=True, non_string_truthiness=True), + page=int_or_default(params.get("page"), 1), + page_size=int_or_default(params.get("page_size"), 60), + ) + return _serialize_image_list(result, signer) + + return handle_request(ctx, action) + + def list_node_images( ctx: RequestContext, node_id: str, @@ -31,7 +56,7 @@ def list_node_images( def action() -> list[dict[str, Any]]: require_authenticated(ctx) - include_archived = _as_bool(params.get("include_archived")) + include_archived = as_bool(params.get("include_archived"), non_string_truthiness=True) return [_serialize_image(image, signer) for image in image_service.list_by_node(node_id, include_archived)] return handle_request(ctx, action) @@ -135,8 +160,8 @@ def safe_delete_image( return deletion_service.delete_image( image_id, ctx, - dry_run=_as_bool(params.get("dry_run", True)), - delete_files=_as_bool(params.get("delete_files")), + dry_run=as_bool(params.get("dry_run", True), non_string_truthiness=True), + delete_files=as_bool(params.get("delete_files"), non_string_truthiness=True), ) return handle_request(ctx, action) @@ -151,14 +176,6 @@ def _create_image_service() -> ImageService: ) -def _as_bool(value: Any) -> bool: - if isinstance(value, bool): - return value - if isinstance(value, str): - return value.strip().lower() in {"1", "true", "yes", "on"} - return bool(value) - - def _serialize_image(image: GenerationImage, media_service: MediaService) -> dict[str, Any]: payload = image.to_dict() payload["image_url"] = _signed_url(media_service, image.image_uri) @@ -166,6 +183,12 @@ def _serialize_image(image: GenerationImage, media_service: MediaService) -> dic return payload +def _serialize_image_list(result: ImageListResult, media_service: MediaService) -> dict[str, Any]: + payload = result.to_dict() + payload["items"] = [_serialize_image(image, media_service) for image in result.items] + return payload + + def _signed_url(media_service: MediaService, uri: str | None) -> str | None: if not uri: return None diff --git a/backend/routes/integration_routes.py b/backend/routes/integration_routes.py index 03338b7..4cb57a4 100644 --- a/backend/routes/integration_routes.py +++ b/backend/routes/integration_routes.py @@ -81,6 +81,7 @@ def rotate_private_companion_token( def _create_integration_service() -> IntegrationService: database = Database(load_database_settings()) audit_service = AuditService(database) + config_service = ConfigService() wardrobe_service = WardrobeService( wardrobe_repository=WardrobeRepository(database), profile_repository=ProfileRepository(database), @@ -90,7 +91,8 @@ def _create_integration_service() -> IntegrationService: return IntegrationService( wardrobe_service=wardrobe_service, integration_repository=IntegrationRepository(database), - token_service=IntegrationTokenService(audit_service=audit_service), + token_service=IntegrationTokenService(config_service, audit_service=audit_service), + enabled=config_service.load().feature_flags().get("private_companion_integration", False), ) diff --git a/backend/routes/job_routes.py b/backend/routes/job_routes.py index 041ab76..3dc7c38 100644 --- a/backend/routes/job_routes.py +++ b/backend/routes/job_routes.py @@ -5,11 +5,13 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.event_stream_service import get_default_event_bus +from backend.services.generation_job_retry_service import GenerationJobRetryService from backend.services.queue_service import QueueService from core.audit_service import AuditService from core.identity import RequestContext -from core.security import require_authenticated, require_write +from core.security import require_authenticated, require_task_retry, require_write from database.db_helper import Database, load_database_settings from database.repositories.job_repository import JobRepository @@ -25,11 +27,11 @@ def list_jobs( def action() -> dict[str, Any]: require_authenticated(ctx) return queue_service.list_jobs( - status=_optional_str(params.get("status")), - workflow_id=_optional_str(params.get("workflow_id")), - profile_id=_optional_str(params.get("profile_id")), - page=_int_or_default(params.get("page"), 1), - page_size=_int_or_default(params.get("page_size"), 30), + status=optional_str(params.get("status")), + workflow_id=optional_str(params.get("workflow_id")), + profile_id=optional_str(params.get("profile_id")), + page=int_or_default(params.get("page"), 1), + page_size=int_or_default(params.get("page_size"), 30), ).to_dict() return handle_request(ctx, action) @@ -66,13 +68,14 @@ def cancel_job( def retry_job( ctx: RequestContext, task_id: str, - service: QueueService | None = None, + payload: dict[str, Any] | None = None, + service: GenerationJobRetryService | None = None, ) -> dict: - queue_service = service or _create_queue_service() + retry_service = service or _create_generation_job_retry_service() def action() -> dict[str, Any]: - require_write(ctx) - return queue_service.retry_job(task_id, ctx).to_dict() + require_task_retry(ctx) + return retry_service.retry_job(task_id, ctx, overrides=payload or {}).to_dict() return handle_request(ctx, action) @@ -80,14 +83,14 @@ def retry_job( def retry_dead_letter_jobs( ctx: RequestContext, payload: dict[str, Any] | None = None, - service: QueueService | None = None, + service: GenerationJobRetryService | None = None, ) -> dict: - queue_service = service or _create_queue_service() + retry_service = service or _create_generation_job_retry_service() params = payload or {} def action() -> dict[str, Any]: - require_write(ctx) - return queue_service.retry_dead_letters(ctx, limit=_int_or_default(params.get("limit"), 50)) + require_task_retry(ctx) + return retry_service.retry_dead_letters(ctx, limit=int_or_default(params.get("limit"), 5)) return handle_request(ctx, action) @@ -101,8 +104,8 @@ def move_failed_jobs_to_dead_letter( params = payload or {} def action() -> dict[str, Any]: - require_write(ctx) - return queue_service.move_failed_to_dead_letter(ctx, limit=_int_or_default(params.get("limit"), 50)) + require_task_retry(ctx) + return queue_service.move_failed_to_dead_letter(ctx, limit=int_or_default(params.get("limit"), 50)) return handle_request(ctx, action) @@ -116,15 +119,12 @@ def _create_queue_service() -> QueueService: ) -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None +def _create_generation_job_retry_service() -> GenerationJobRetryService: + # Import lazily so route discovery does not construct provider runtimes. + from backend.routes.node_routes import _create_generation_service - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default + generation_service = _create_generation_service() + return GenerationJobRetryService( + queue_service=generation_service.queue_service, + generation_service=generation_service, + ) diff --git a/backend/routes/log_routes.py b/backend/routes/log_routes.py index 77ae3a8..71f82e7 100644 --- a/backend/routes/log_routes.py +++ b/backend/routes/log_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.log_service import LogService from core.identity import RequestContext from core.security import require_authenticated, require_config_manager @@ -17,10 +18,10 @@ def get_generation_logs(ctx: RequestContext, query: dict[str, Any] | None = None def action(log_service: LogService, limit: int) -> list[dict[str, Any]]: return log_service.generation_logs( limit, - status=_optional_str(params.get("status")), - workflow_id=_optional_str(params.get("workflow_id")), - profile_id=_optional_str(params.get("profile_id")), - node_id=_optional_str(params.get("node_id")), + status=optional_str(params.get("status")), + workflow_id=optional_str(params.get("workflow_id")), + profile_id=optional_str(params.get("profile_id")), + node_id=optional_str(params.get("node_id")), ) return _read_logs(ctx, query, service, action) @@ -31,11 +32,11 @@ def get_workflow_logs(ctx: RequestContext, query: dict[str, Any] | None = None, def action(log_service: LogService, limit: int) -> list[dict[str, Any]]: return log_service.workflow_logs( - _optional_str(params.get("workflow_id")), + optional_str(params.get("workflow_id")), limit, - action=_optional_str(params.get("action")), - node_id=_optional_str(params.get("node_id")), - branch_name=_optional_str(params.get("branch_name")), + action=optional_str(params.get("action")), + node_id=optional_str(params.get("node_id")), + branch_name=optional_str(params.get("branch_name")), ) return _read_logs(ctx, query, service, action) @@ -47,8 +48,8 @@ def get_error_logs(ctx: RequestContext, query: dict[str, Any] | None = None, ser def action(log_service: LogService, limit: int) -> list[dict[str, Any]]: return log_service.error_logs( limit, - source=_optional_str(params.get("source")), - status=_optional_str(params.get("status")), + source=optional_str(params.get("source")), + status=optional_str(params.get("status")), ) return _read_logs(ctx, query, service, action) @@ -59,10 +60,10 @@ def get_integration_logs(ctx: RequestContext, query: dict[str, Any] | None = Non def action(log_service: LogService, limit: int) -> list[dict[str, Any]]: return log_service.integration_logs( - _optional_str(params.get("integration_name")), + optional_str(params.get("integration_name")), limit, - action=_optional_str(params.get("action")), - status=_optional_str(params.get("status")), + action=optional_str(params.get("action")), + status=optional_str(params.get("status")), ) return _read_logs(ctx, query, service, action) @@ -75,10 +76,10 @@ def get_audit_logs(ctx: RequestContext, query: dict[str, Any] | None = None, ser def action() -> list[dict[str, Any]]: require_config_manager(ctx) return log_service.audit_logs( - _int_or_default(params.get("limit"), 50), - action=_optional_str(params.get("action")), - target_type=_optional_str(params.get("target_type")), - actor_id=_optional_str(params.get("actor_id")), + int_or_default(params.get("limit"), 50), + action=optional_str(params.get("action")), + target_type=optional_str(params.get("target_type")), + actor_id=optional_str(params.get("actor_id")), ) return handle_request(ctx, action) @@ -95,20 +96,6 @@ def _read_logs( def action() -> list[dict[str, Any]]: require_authenticated(ctx) - return reader(log_service, _int_or_default(params.get("limit"), 50)) + return reader(log_service, int_or_default(params.get("limit"), 50)) return handle_request(ctx, action) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/material_routes.py b/backend/routes/material_routes.py index 760914b..7e47ff3 100644 --- a/backend/routes/material_routes.py +++ b/backend/routes/material_routes.py @@ -7,14 +7,16 @@ from typing import Any from backend.dto.common import ApiError from backend.dto.material_dto import Material, MaterialListResult from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.material_service import MaterialService from backend.services.media_service import MediaService +from backend.services.model_provider_bootstrap import sync_vision_provider_from_config from backend.services.model_provider_runtime import ModelProviderRuntime from backend.services.model_provider_service import ModelProviderService from core.audit_service import AuditService from core.identity import RequestContext from core.security import require_authenticated, require_permission -from database.db_helper import Database, load_database_settings +from database.db_helper import Database, load_config_payload, load_database_settings from database.repositories.material_repository import MaterialRepository from database.repositories.model_provider_repository import ModelProviderRepository @@ -88,10 +90,10 @@ def list_materials( def action() -> dict[str, Any]: require_authenticated(ctx) result = material_service.list_materials( - category_id=_optional_str(params.get("category_id")), - keyword=_optional_str(params.get("keyword")), - page=_int_or_default(params.get("page"), 1), - page_size=_int_or_default(params.get("page_size"), 30), + category_id=optional_str(params.get("category_id")), + keyword=optional_str(params.get("keyword")), + page=int_or_default(params.get("page"), 1), + page_size=int_or_default(params.get("page_size"), 30), ) return _serialize_material_list(result, signer) @@ -232,10 +234,16 @@ def _create_material_service() -> MaterialService: database = Database(load_database_settings()) model_provider_service = ModelProviderService(ModelProviderRepository(database)) model_provider_runtime = ModelProviderRuntime(model_provider_service) + config = load_config_payload() + sync_vision_provider_from_config(model_provider_service, config) + vision = config.get("vision") if isinstance(config.get("vision"), dict) else {} + provider = vision.get("provider") if isinstance(vision.get("provider"), dict) else {} + default_route = str(provider.get("route_name") or vision.get("default_route") or "material_vlm").strip() return MaterialService( repository=MaterialRepository(database), audit_service=AuditService(database), vision_provider_factory=model_provider_runtime.vision_provider_for_route, + default_recognition_route=default_route, ) @@ -259,17 +267,3 @@ def _signed_url(media_service: MediaService, uri: str | None) -> str | None: return media_service.sign_media(uri)["url"] except ApiError: return None - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/media_routes.py b/backend/routes/media_routes.py index c1090d6..23d6f86 100644 --- a/backend/routes/media_routes.py +++ b/backend/routes/media_routes.py @@ -6,6 +6,7 @@ from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.media_index_service import MediaIndexService from backend.services.media_service import MediaService from backend.services.orphan_media_service import OrphanMediaService @@ -58,8 +59,8 @@ def index_media( def action() -> dict[str, Any]: require_authenticated(ctx) return index_service.index_files( - root=_optional_str(params.get("root")), - limit=_int_or_default(params.get("limit"), 500), + root=optional_str(params.get("root")), + limit=int_or_default(params.get("limit"), 500), ) return handle_request(ctx, action) @@ -79,22 +80,8 @@ def scan_orphan_media( def action() -> dict[str, Any]: require_authenticated(ctx) return orphan_service.scan( - root=_optional_str(params.get("root")), - limit=_int_or_default(params.get("limit"), 500), + root=optional_str(params.get("root")), + limit=int_or_default(params.get("limit"), 500), ) return handle_request(ctx, action) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/node_routes.py b/backend/routes/node_routes.py index 4abded5..4781071 100644 --- a/backend/routes/node_routes.py +++ b/backend/routes/node_routes.py @@ -8,19 +8,29 @@ from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from backend.routes.common import handle_request from backend.services.event_stream_service import get_default_event_bus +from backend.services.cost_guard_service import CostGuardService +from backend.services.cost_service import CostService from backend.services.generation_service import GenerationService from backend.services.image_service import ImageService from backend.services.model_provider_runtime import ModelProviderRuntime +from backend.services.model_provider_bootstrap import sync_generation_provider_from_config from backend.services.model_provider_service import ModelProviderService from backend.services.node_dependency_context_service import NodeDependencyContextService +from backend.services.prompt_expansion_service import PromptExpansionService from backend.services.queue_service import QueueService -from backend.services.workflow_service import WorkflowService +from backend.services.workflow_service import ( + LOCKED_NODE_STATUSES, + WorkflowService, + is_repeatable_single_image_node, + locked_node_edit_error, +) from core.audit_service import AuditService from core.identity import RequestContext -from core.security import require_authenticated, require_write -from database.db_helper import Database, load_database_settings +from core.security import require_authenticated, require_task_retry, require_write +from database.db_helper import Database, load_config_payload, load_database_settings from database.repositories.image_repository import ImageRepository from database.repositories.job_repository import JobRepository +from database.repositories.material_repository import MaterialRepository from database.repositories.model_provider_repository import ModelProviderRepository from database.repositories.profile_repository import ProfileRepository from database.repositories.workflow_repository import WorkflowRepository @@ -145,14 +155,57 @@ def generate_node( def retry_node( ctx: RequestContext, node_id: str, + payload: dict[str, Any] | None = None, service: WorkflowService | None = None, + generation_service: GenerationService | None = None, ) -> dict: - workflow_service = service or _create_workflow_service() + resolved_generation_service = generation_service + if resolved_generation_service is None and service is None: + resolved_generation_service = _create_generation_service() + workflow_service = ( + service + or getattr(resolved_generation_service, "workflow_service", None) + or _create_workflow_service() + ) + request_overrides = payload or {} def action() -> dict[str, Any]: - require_write(ctx) - node = workflow_service.update_node(node_id, {"status": "queued"}, ctx) - return {"node_id": node.node_id, "node_status": node.status, "queue_placeholder": True} + require_task_retry(ctx) + node = workflow_service.get_node(node_id) + if node.status in LOCKED_NODE_STATUSES and not is_repeatable_single_image_node(node): + raise locked_node_edit_error(node) + if node.status not in _RETRYABLE_NODE_STATUSES and not ( + node.status in LOCKED_NODE_STATUSES and is_repeatable_single_image_node(node) + ): + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "node cannot be retried from its current status", + { + "node_id": node.node_id, + "status": node.status, + "allowed_statuses": sorted(_RETRYABLE_NODE_STATUSES), + }, + ) + metadata = node.metadata if isinstance(node.metadata, dict) else {} + last_request = metadata.get("last_generate_request") + if not isinstance(last_request, dict) or not last_request: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "node has no previous generation request to retry", + { + "node_id": node.node_id, + "status": node.status, + "field": "metadata.last_generate_request", + }, + ) + if resolved_generation_service is None: + raise ApiError( + ErrorCode.UNKNOWN_ERROR, + "generation service is unavailable for node retry", + {"node_id": node.node_id}, + ) + retry_request = _build_retry_generation_request(node.node_id, last_request, request_overrides) + return resolved_generation_service.generate_node(node.node_id, retry_request, ctx) return handle_request(ctx, action) @@ -238,6 +291,9 @@ def _create_generation_service() -> GenerationService: event_bus = get_default_event_bus() model_provider_service = ModelProviderService(ModelProviderRepository(database)) model_provider_runtime = ModelProviderRuntime(model_provider_service) + config_payload = load_config_payload() + sync_generation_provider_from_config(model_provider_service, config_payload) + generation_config = config_payload.get("generation") if isinstance(config_payload.get("generation"), dict) else {} return GenerationService( workflow_service=WorkflowService( workflow_repository=workflow_repository, @@ -255,9 +311,17 @@ def _create_generation_service() -> GenerationService: workflow_repository=workflow_repository, audit_service=audit_service, ), - single_flow_engine=SingleFlowEngine(image_provider_factory=model_provider_runtime.image_provider_for_route), + single_flow_engine=SingleFlowEngine( + image_provider_factory=model_provider_runtime.image_provider_for_route, + allow_mock_fallback=False, + ), model_provider_service=model_provider_service, + cost_guard_service=CostGuardService(CostService(database)), + prompt_expansion_service=PromptExpansionService(), event_bus=event_bus, + default_model_route=str(generation_config.get("default_model") or "").strip() or None, + require_resolved_model_route=True, + material_resolver=MaterialRepository(database), ) @@ -265,3 +329,91 @@ def _bool(value: Any) -> bool: if isinstance(value, str): return value.strip().lower() in {"1", "true", "yes", "on"} return bool(value) + + +_RETRYABLE_NODE_STATUSES = frozenset({"failed", "cancelled", "skipped"}) +_RETRY_DERIVED_REQUEST_FIELDS = frozenset( + { + "cost_guard", + "expanded_negative_prompt", + "expanded_prompt", + "prompt_expansion", + "reference_persistence", + "resolved_model_route", + } +) + + +def _build_retry_generation_request( + node_id: str, + last_request: dict[str, Any], + overrides: dict[str, Any], +) -> dict[str, Any]: + omitted_references = _ephemeral_reference_count(last_request) + if omitted_references and not _has_reference_override(overrides): + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "the previous generation used inline reference images; provide replacement references before retrying", + { + "node_id": node_id, + "ephemeral_data_urls_omitted": omitted_references, + "required_fields": ["input_images", "image", "selected_draft_image_ids", "stage_inputs"], + }, + ) + request = { + key: value + for key, value in last_request.items() + if key not in _RETRY_DERIVED_REQUEST_FIELDS and key != "idempotency_key" + } + for key, value in overrides.items(): + if key not in _RETRY_DERIVED_REQUEST_FIELDS and key != "idempotency_key": + request[key] = value + + previous_metadata = last_request.get("metadata") + override_metadata = overrides.get("metadata") + if isinstance(previous_metadata, dict) or isinstance(override_metadata, dict): + request["metadata"] = { + **(previous_metadata if isinstance(previous_metadata, dict) else {}), + **(override_metadata if isinstance(override_metadata, dict) else {}), + } + request["idempotency_key"] = f"node-retry-{node_id}-{uuid4().hex}" + return request + + +def _ephemeral_reference_count(request: dict[str, Any]) -> int: + persistence = request.get("reference_persistence") + if not isinstance(persistence, dict): + return 0 + try: + return max(int(persistence.get("ephemeral_data_urls_omitted") or 0), 0) + except (TypeError, ValueError): + return 0 + + +def _has_reference_override(payload: dict[str, Any]) -> bool: + for key in ("input_images", "image", "selected_draft_image_ids", "stage_inputs"): + if _has_nonempty_value(payload.get(key)): + return True + metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {} + dependency = payload.get("dependency_context") if isinstance(payload.get("dependency_context"), dict) else {} + return any( + _has_nonempty_value(value) + for value in ( + metadata.get("selected_draft_image_ids"), + metadata.get("stage_inputs"), + dependency.get("selected_image_ids"), + dependency.get("selected_draft_image_ids"), + dependency.get("stage_inputs"), + dependency.get("material_bindings"), + ) + ) + + +def _has_nonempty_value(value: Any) -> bool: + if value is None: + return False + if isinstance(value, str): + return bool(value.strip()) + if isinstance(value, (list, tuple, dict, set)): + return bool(value) + return True diff --git a/backend/routes/params.py b/backend/routes/params.py new file mode 100644 index 0000000..a375c6f --- /dev/null +++ b/backend/routes/params.py @@ -0,0 +1,82 @@ +"""Side-effect-free coercion helpers shared by route handlers.""" + +from __future__ import annotations + +from typing import Any + + +_TRUE_TEXT_VALUES = frozenset({"1", "true", "yes", "on"}) + + +def optional_str(value: Any) -> str | None: + """Return a stripped string, or ``None`` for missing/blank values.""" + + if value is None: + return None + text = str(value).strip() + return text or None + + +# Both names are used for this coercion across the backend. Keep the alias so +# route and service code can use the vocabulary that best fits the field. +optional_text = optional_str + + +def optional_int(value: Any) -> int | None: + """Return an integer when coercion succeeds, otherwise ``None``.""" + + if value is None or value == "": + return None + try: + return int(value) + except (TypeError, ValueError): + return None + + +def optional_float(value: Any) -> float | None: + """Return a float when coercion succeeds, otherwise ``None``.""" + + if value is None or value == "": + return None + try: + return float(value) + except (TypeError, ValueError): + return None + + +def int_or_default(value: Any, default: int) -> int: + """Return an integer when coercion succeeds, otherwise ``default``. + + Range normalization intentionally remains the responsibility of the + receiving service; route parsing only handles type coercion. + """ + + try: + return int(value) + except (TypeError, ValueError): + return default + + +def as_bool( + value: Any, + *, + default: bool = False, + non_string_truthiness: bool = False, +) -> bool: + """Coerce a route parameter to bool while preserving legacy semantics. + + Strings accept the route-level true tokens ``1``, ``true``, ``yes`` and + ``on``. Some existing routes historically applied Python truthiness to + non-string values; they opt into that behavior with + ``non_string_truthiness=True``. + """ + + if value is None: + return default + if isinstance(value, bool): + return value + if isinstance(value, str): + return value.strip().lower() in _TRUE_TEXT_VALUES + if non_string_truthiness: + return bool(value) + return str(value).strip().lower() in _TRUE_TEXT_VALUES diff --git a/backend/routes/profile_routes.py b/backend/routes/profile_routes.py index e554e5a..aae6669 100644 --- a/backend/routes/profile_routes.py +++ b/backend/routes/profile_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default, optional_str from backend.services.event_stream_service import get_default_event_bus from backend.services.profile_service import ProfileService from backend.services.quick_profile_service import QuickProfileService @@ -29,10 +30,10 @@ def list_profiles( require_authenticated(ctx) result = profile_service.list_profiles( ctx=ctx, - keyword=_optional_str(params.get("keyword")), - status=_optional_str(params.get("status")) or "active", - page=_int_or_default(params.get("page"), 1), - page_size=_int_or_default(params.get("page_size"), 30), + keyword=optional_str(params.get("keyword")), + status=optional_str(params.get("status")) or "active", + page=int_or_default(params.get("page"), 1), + page_size=int_or_default(params.get("page_size"), 30), ) return result.to_dict() @@ -62,7 +63,7 @@ def get_profile( def action() -> dict: require_authenticated(ctx) - return profile_service.get_profile(profile_id).to_dict() + return profile_service.get_profile(profile_id, ctx).to_dict() return handle_request(ctx, action) @@ -154,17 +155,3 @@ def _create_workflow_service(database: Database | None = None) -> WorkflowServic audit_service=AuditService(database), event_bus=get_default_event_bus(), ) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/settings_routes.py b/backend/routes/settings_routes.py index e7e3a3d..1574ed3 100644 --- a/backend/routes/settings_routes.py +++ b/backend/routes/settings_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import int_or_default from backend.services.settings_service import SettingsService from core.audit_service import AuditService from core.identity import RequestContext @@ -130,7 +131,7 @@ def list_settings_snapshots( def action() -> list[dict[str, Any]]: require_config_manager(ctx) - return settings_service.list_snapshots(_int_or_default(params.get("limit"), 20)) + return settings_service.list_snapshots(int_or_default(params.get("limit"), 20)) return handle_request(ctx, action) @@ -166,10 +167,3 @@ def rollback_settings( def _create_settings_service() -> SettingsService: database = Database(load_database_settings()) return SettingsService(audit_service=AuditService(database)) - - -def _int_or_default(value: Any, default: int) -> int: - try: - return int(value) - except (TypeError, ValueError): - return default diff --git a/backend/routes/storage_routes.py b/backend/routes/storage_routes.py index 0ff3e6a..bbce4c1 100644 --- a/backend/routes/storage_routes.py +++ b/backend/routes/storage_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import as_bool from backend.services.media_service import MediaService from backend.dto.common import ApiError, ErrorCode from core.identity import RequestContext @@ -42,15 +43,7 @@ def migrate_storage( return media_service.plan_storage_migration( source_uri, target_uri, - dry_run=_as_bool(payload.get("dry_run"), default=True), + dry_run=as_bool(payload.get("dry_run"), default=True), ) return handle_request(ctx, action) - - -def _as_bool(value: Any, *, default: bool = False) -> bool: - if value is None: - return default - if isinstance(value, bool): - return value - return str(value).strip().lower() in {"1", "true", "yes", "on"} diff --git a/backend/routes/wardrobe_routes.py b/backend/routes/wardrobe_routes.py index 3c43eb9..d47e38e 100644 --- a/backend/routes/wardrobe_routes.py +++ b/backend/routes/wardrobe_routes.py @@ -5,6 +5,7 @@ from __future__ import annotations from typing import Any from backend.routes.common import handle_request +from backend.routes.params import optional_str from backend.services.wardrobe_service import WardrobeService from core.audit_service import AuditService from core.identity import RequestContext @@ -28,7 +29,11 @@ def list_wardrobe_items( require_authenticated(ctx) return [ item.to_dict() - for item in wardrobe_service.list_items(profile_id, _optional_str(params.get("wardrobe_category"))) + for item in wardrobe_service.list_items( + profile_id, + optional_str(params.get("wardrobe_category")), + ctx, + ) ] return handle_request(ctx, action) @@ -87,10 +92,3 @@ def _create_wardrobe_service() -> WardrobeService: material_repository=MaterialRepository(database), audit_service=AuditService(database), ) - - -def _optional_str(value: Any) -> str | None: - if value is None: - return None - text = str(value).strip() - return text or None diff --git a/backend/routes/workflow_routes.py b/backend/routes/workflow_routes.py index 1c5cebb..8379f33 100644 --- a/backend/routes/workflow_routes.py +++ b/backend/routes/workflow_routes.py @@ -7,11 +7,13 @@ from typing import Any from backend.routes.common import handle_request from backend.services.character_workflow_service import CharacterWorkflowService from backend.services.event_stream_service import get_default_event_bus +from backend.services.queue_service import QueueService from backend.services.workflow_service import WorkflowService from core.audit_service import AuditService from core.identity import RequestContext from core.security import require_authenticated, require_write from database.db_helper import Database, load_database_settings +from database.repositories.job_repository import JobRepository from database.repositories.profile_repository import ProfileRepository from database.repositories.workflow_repository import WorkflowRepository @@ -87,7 +89,18 @@ def cancel_workflow( workflow_id: str, service: WorkflowService | None = None, ) -> dict: - return _set_workflow_status(ctx, workflow_id, "cancelled", service) + workflow_service = service or _create_workflow_service() + queue_service = QueueService( + JobRepository(workflow_service.workflow_repository.database), + workflow_service.audit_service, + workflow_service.event_bus, + ) + + def action() -> dict[str, Any]: + require_write(ctx) + return workflow_service.cancel_workflow(workflow_id, ctx, queue_service).to_dict() + + return handle_request(ctx, action) def archive_workflow( diff --git a/backend/services/api_discovery_service.py b/backend/services/api_discovery_service.py index e4cd0ec..7f2f066 100644 --- a/backend/services/api_discovery_service.py +++ b/backend/services/api_discovery_service.py @@ -2,6 +2,10 @@ from __future__ import annotations +import json +import os +import urllib.error +import urllib.request from typing import Any from uuid import uuid4 @@ -44,18 +48,25 @@ class ApiDiscoveryService: if not model_id: raise ApiError(ErrorCode.VALIDATION_FAILED, "model_id is required", {"field": "model_id"}) dialect = str(payload.get("dialect") or "unknown") + live_result = _live_probe(payload) if payload.get("live_probe") else { + "mode": "safe", + "message": "safe probe recorded metadata only; no external API call was made", + } + capabilities = dict(payload.get("capabilities") or {}) + if live_result.get("models"): + capabilities["discovered_models"] = live_result["models"] + if live_result.get("supported_sizes"): + capabilities["supported_sizes"] = live_result["supported_sizes"] + capabilities["max_tested_size"] = live_result["supported_sizes"][-1] profile = self.repository.upsert_profile( { "capability_profile_id": payload.get("capability_profile_id") or new_capability_profile_id(), "provider_id": provider_id, "model_id": model_id, "dialect": dialect, - "status": "unconfirmed", - "capabilities": payload.get("capabilities") or {}, - "probe_result": { - "mode": "safe", - "message": "safe probe recorded metadata only; no external API call was made", - }, + "status": "confirmed_supported" if live_result.get("connected") else "unconfirmed", + "capabilities": capabilities, + "probe_result": live_result, } ) return profile @@ -163,3 +174,48 @@ class ApiDiscoveryService: def new_capability_profile_id() -> str: return f"cap_{uuid4().hex}" + + +def _live_probe(payload: dict[str, Any]) -> dict[str, Any]: + base_url = str(payload.get("base_url") or "").strip().rstrip("/") + if not base_url.startswith(("http://", "https://")): + raise ApiError(ErrorCode.VALIDATION_FAILED, "valid base_url is required", {"field": "base_url"}) + timeout = min(max(int(payload.get("timeout_seconds") or 20), 3), 60) + env_name = str(payload.get("api_key_env_var") or "").strip() + api_key = os.getenv(env_name, "") if env_name else "" + headers = {"Accept": "application/json", **({"Authorization": f"Bearer {api_key}"} if api_key else {})} + result: dict[str, Any] = {"mode": "live", "connected": False, "models": [], "supported_sizes": [], "warnings": []} + api_prefix = base_url if base_url.lower().endswith("/v1") else f"{base_url}/v1" + models_url = f"{api_prefix}/models" + result["resolved_api_base"] = api_prefix + result["image_endpoint"] = "/images/generations" if base_url.lower().endswith("/v1") else "/v1/images/generations" + try: + request = urllib.request.Request(models_url, headers=headers, method="GET") + with urllib.request.urlopen(request, timeout=timeout) as response: + body = response.read(2 * 1024 * 1024).decode("utf-8-sig") + parsed = json.loads(body) + items = parsed.get("data", []) if isinstance(parsed, dict) else [] + result["models"] = [str(item.get("id")) for item in items if isinstance(item, dict) and item.get("id")][:200] + result["connected"] = True + result["http_status"] = response.status + except urllib.error.HTTPError as exc: + result.update({"http_status": exc.code, "error": f"models endpoint returned HTTP {exc.code}"}) + except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, UnicodeDecodeError) as exc: + result["error"] = str(exc) + + if payload.get("allow_lightweight_test") and result["connected"]: + endpoint = str(payload.get("image_endpoint") or result["image_endpoint"]) + if base_url.lower().endswith("/v1") and endpoint.lower().startswith("/v1/"): + endpoint = endpoint[3:] + endpoint_url = f"{base_url}{endpoint if endpoint.startswith('/') else '/' + endpoint}" + model_id = str(payload.get("model_id") or "").strip() + for size in ("1920x1080", "2560x1440", "3840x2160"): + data = json.dumps({"model": model_id, "prompt": "A plain gray circle on white background, capability test", "size": size, "n": 1, "response_format": "b64_json"}).encode("utf-8") + request = urllib.request.Request(endpoint_url, data=data, headers={**headers, "Content-Type": "application/json"}, method="POST") + try: + with urllib.request.urlopen(request, timeout=timeout) as response: + response.read(1024) + result["supported_sizes"].append(size) + except Exception as exc: # Provider dialects expose inconsistent errors; retain a short diagnostic only. + result["warnings"].append({"size": size, "message": str(exc)[:180]}) + return result diff --git a/backend/services/asset_import_service.py b/backend/services/asset_import_service.py index bfa1b67..0e08644 100644 --- a/backend/services/asset_import_service.py +++ b/backend/services/asset_import_service.py @@ -47,12 +47,27 @@ class AssetImportService: manifest_candidates = _manifest_candidates(root, relative, package_path) manifest_summary = _manifest_summary(package_path, manifest_candidates) applied = {"materials": 0, "styles": 0, "material_ids": [], "created": 0, "updated": 0} + unsupported_features = [] + if manifest_summary["styles"]: + unsupported_features.append( + { + "code": "STYLE_IMPORT_UNSUPPORTED", + "message": "style entries are not imported by the current asset-pack service", + "count": manifest_summary["styles"], + } + ) if not dry_run and not manifest_summary["valid"]: raise ApiError( ErrorCode.VALIDATION_FAILED, "asset pack manifest is invalid", {"field": "manifest", "errors": manifest_summary["errors"]}, ) + if not dry_run and unsupported_features: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "asset pack contains unsupported entries", + {"field": "styles", "unsupported_features": unsupported_features}, + ) if not dry_run: if self.material_service is None or ctx is None: raise ApiError( @@ -69,8 +84,9 @@ class AssetImportService: "bytes": total_bytes, "manifest_candidates": [item["uri"] for item in manifest_candidates], "manifest": manifest_summary, - "import_enabled": manifest_summary["valid"], - "execution_enabled": True, + "import_enabled": manifest_summary["valid"] and not unsupported_features, + "execution_enabled": manifest_summary["valid"] and not unsupported_features, + "unsupported_features": unsupported_features, "applied": applied, } @@ -84,10 +100,18 @@ class AssetImportService: ctx: RequestContext, ) -> dict[str, Any]: payload = _load_manifest_payload(manifest["path"]) + if _list_count(payload.get("styles")): + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "style entries are not supported by asset pack import", + {"field": "styles"}, + ) material_ids: list[str] = [] created_count = 0 updated_count = 0 base_relative = relative if package_path.is_dir() else relative.parent + planned_materials: list[tuple[dict[str, Any], bool]] = [] + planned_material_ids: set[str] = set() for index, item in enumerate(payload.get("materials") or []): if not isinstance(item, dict): raise ApiError( @@ -103,11 +127,25 @@ class AssetImportService: manifest_uri=manifest["uri"], index=index, ) + material_id = str(material_payload["material_id"]) + if material_id in planned_material_ids: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "asset pack contains duplicate material IDs", + {"field": f"materials[{index}].material_id", "material_id": material_id}, + ) + planned_material_ids.add(material_id) self.storage.ensure_file(material_payload["image_uri"]) if material_payload.get("thumbnail_uri"): self.storage.ensure_file(material_payload["thumbnail_uri"]) existing = self.material_service.repository.get_material(material_payload["material_id"]) - if existing is None: + if existing is not None: + self.material_service.get_material(material_payload["material_id"]) + self.material_service.validate_material_payload(material_payload, creating=existing is None) + planned_materials.append((material_payload, existing is None)) + + for material_payload, creating in planned_materials: + if creating: material = self.material_service.create_material(material_payload, ctx) created_count += 1 else: @@ -116,7 +154,7 @@ class AssetImportService: material_ids.append(material.material_id) return { "materials": len(material_ids), - "styles": _list_count(payload.get("styles")), + "styles": 0, "material_ids": material_ids, "created": created_count, "updated": updated_count, diff --git a/backend/services/character_workflow_service.py b/backend/services/character_workflow_service.py index fd039d4..5f28825 100644 --- a/backend/services/character_workflow_service.py +++ b/backend/services/character_workflow_service.py @@ -12,6 +12,8 @@ from core.identity import RequestContext CHARACTER_WORKFLOW_TYPES = {"character_fast", "character_gradual", "quick_profile"} +GENERATION_NODE_TYPES = {"generation", "single_image"} +EDITABLE_PREPARATION_NODE_TYPES = {"planning", "reference_binding"} class CharacterWorkflowService: @@ -37,18 +39,52 @@ class CharacterWorkflowService: ] if not active_nodes: raise ApiError(ErrorCode.VALIDATION_FAILED, "workflow has no executable nodes", {"workflow_id": workflow_id}) + if workflow.status == "completed": + return { + "workflow": workflow.to_dict(), + "nodes": [node.to_dict() for node in active_nodes], + "completed_node_ids": [ + node.node_id for node in active_nodes if node.status in {"completed", "selected"} + ], + "queued_node_ids": [node.node_id for node in active_nodes if node.status == "queued"], + "prepared_node_ids": [], + "idempotent_replay": True, + } + previous_execution = workflow.metadata.get("character_execution") + if workflow.status == "running" and isinstance(previous_execution, dict): + completed_node_ids = [node.node_id for node in active_nodes if node.status == "completed"] + queued_node_ids = [node.node_id for node in active_nodes if node.status == "queued"] + prepared_node_ids = [ + node.node_id + for node in active_nodes + if node.node_type in EDITABLE_PREPARATION_NODE_TYPES and node.status == "draft" + ] + return { + "workflow": workflow.to_dict(), + "nodes": [node.to_dict() for node in active_nodes], + "completed_node_ids": completed_node_ids, + "queued_node_ids": queued_node_ids, + "prepared_node_ids": prepared_node_ids, + "idempotent_replay": True, + } running_workflow = workflow if workflow.status not in {"running", "completed"}: running_workflow = self.workflow_service.update_workflow(workflow_id, {"status": "running"}, ctx) - completed_nodes: list[WorkflowNode] = [] + prepared_nodes: list[WorkflowNode] = [] prompt_context: list[str] = [] for node in active_nodes: prompt = _node_prompt(profile, node, running_workflow, prompt_context) negative_prompt = _negative_prompt(profile, node) - completed = self.workflow_service.update_node( + if node.node_type in GENERATION_NODE_TYPES: + target_status = "queued" + elif node.node_type in EDITABLE_PREPARATION_NODE_TYPES: + target_status = node.status + else: + target_status = "completed" + prepared = self.workflow_service.update_node( node.node_id, { - "status": "completed", + "status": target_status, "prompt": prompt, "negative_prompt": negative_prompt, "metadata": { @@ -57,33 +93,46 @@ class CharacterWorkflowService: "executor": "character_workflow", "workflow_type": workflow.workflow_type, "context_prompts": len(prompt_context), + "prepared_only": target_status in {"queued", "draft"}, }, }, }, ctx, ) - completed_nodes.append(completed) + prepared_nodes.append(prepared) prompt_context.append(prompt) - completed_workflow = self.workflow_service.update_workflow( + queued_nodes = [node for node in prepared_nodes if node.status == "queued"] + completed_nodes = [node for node in prepared_nodes if node.status == "completed"] + editable_nodes = [ + node + for node in prepared_nodes + if node.node_type in EDITABLE_PREPARATION_NODE_TYPES and node.status == "draft" + ] + workflow_status = "running" if queued_nodes or editable_nodes else "completed" + updated_workflow = self.workflow_service.update_workflow( workflow_id, { - "status": "completed", - "current_node_id": completed_nodes[-1].node_id, + "status": workflow_status, + "current_node_id": (queued_nodes[0] if queued_nodes else prepared_nodes[-1]).node_id, "metadata": { **running_workflow.metadata, "character_execution": { "executor": "character_workflow", "workflow_type": workflow.workflow_type, "completed_node_ids": [node.node_id for node in completed_nodes], + "queued_node_ids": [node.node_id for node in queued_nodes], + "prepared_node_ids": [node.node_id for node in editable_nodes], }, }, }, ctx, ) return { - "workflow": completed_workflow.to_dict(), - "nodes": [node.to_dict() for node in completed_nodes], + "workflow": updated_workflow.to_dict(), + "nodes": [node.to_dict() for node in prepared_nodes], "completed_node_ids": [node.node_id for node in completed_nodes], + "queued_node_ids": [node.node_id for node in queued_nodes], + "prepared_node_ids": [node.node_id for node in editable_nodes], } diff --git a/backend/services/cost_service.py b/backend/services/cost_service.py index e3249b4..8675b3b 100644 --- a/backend/services/cost_service.py +++ b/backend/services/cost_service.py @@ -51,10 +51,28 @@ class CostService: key = (provider, provider_model, model_route) group = groups.setdefault(key, _new_group(provider, provider_model, model_route)) group["image_count"] += 1 - group["_task_ids"].add(str(row["task_id"] or row["image_id"])) - group["total_tokens"] += _usage_number(usage, "total_tokens", "total") - group["input_tokens"] += _usage_number(usage, "input_tokens", "prompt_tokens") - group["output_tokens"] += _usage_number(usage, "output_tokens", "completion_tokens") + task_key = str(row["task_id"] or row["image_id"]) + group["_task_ids"].add(task_key) + # Image providers report usage for the whole request, while one + # request may persist several image rows. Keep the largest value + # observed for each task so the same request is not charged once + # per output image. + task_usage = group["_usage_by_task"].setdefault( + task_key, + {"total_tokens": 0, "input_tokens": 0, "output_tokens": 0}, + ) + task_usage["total_tokens"] = max( + task_usage["total_tokens"], + _usage_number(usage, "total_tokens", "total"), + ) + task_usage["input_tokens"] = max( + task_usage["input_tokens"], + _usage_number(usage, "input_tokens", "prompt_tokens"), + ) + task_usage["output_tokens"] = max( + task_usage["output_tokens"], + _usage_number(usage, "output_tokens", "completion_tokens"), + ) finalized = [_finalize_group(group, prices) for group in groups.values()] totals = { "image_count": sum(group["image_count"] for group in finalized), @@ -153,12 +171,17 @@ def _new_group(provider_id: str, provider_model: str, model_route: str) -> dict[ "output_tokens": 0, "estimated_cost": 0.0, "_task_ids": set(), + "_usage_by_task": {}, } def _finalize_group(group: dict[str, Any], prices: dict[str, PriceSpec]) -> dict[str, Any]: group = dict(group) group["task_count"] = len(group.pop("_task_ids")) + usage_by_task = group.pop("_usage_by_task") + group["total_tokens"] = sum(item["total_tokens"] for item in usage_by_task.values()) + group["input_tokens"] = sum(item["input_tokens"] for item in usage_by_task.values()) + group["output_tokens"] = sum(item["output_tokens"] for item in usage_by_task.values()) group["estimated_cost"] = round(_estimate_cost(group, prices), 6) return group @@ -195,7 +218,7 @@ def _price_spec(group: dict[str, Any], prices: dict[str, PriceSpec]) -> PriceSpe def _provider_id(metadata: dict[str, Any]) -> str: provider_error = metadata.get("provider_error") if isinstance(metadata.get("provider_error"), dict) else {} - return str(metadata.get("provider_id") or provider_error.get("provider_id") or "mock") + return str(metadata.get("provider_id") or provider_error.get("provider_id") or "unknown") def _provider_model(metadata: dict[str, Any]) -> str: diff --git a/backend/services/dashboard_service.py b/backend/services/dashboard_service.py index bdbb3e7..9d869be 100644 --- a/backend/services/dashboard_service.py +++ b/backend/services/dashboard_service.py @@ -7,7 +7,8 @@ from typing import Any from backend.dto.common import ApiError from core.config_service import ConfigService, ImageStudioConfig -from database.db_helper import Database, REPO_ROOT +from core.runtime_paths import resolve_data_path +from database.db_helper import Database from database.repositories.job_repository import JobRepository from backend.services.media_service import MediaService @@ -51,7 +52,7 @@ class DashboardService: counts = queue_repository.count_by_status() return { "pending": counts.get("created", 0) + counts.get("queued", 0), - "running": counts.get("running", 0), + "running": counts.get("running", 0) + counts.get("retrying", 0), "failed": counts.get("failed", 0), "dead_letter": counts.get("dead_letter", 0), } @@ -94,10 +95,10 @@ class DashboardService: return None def _storage_summary(self, config: ImageStudioConfig) -> dict[str, int]: - images_bytes = _directory_size(_resolve_data_path(config.storage.images_path)) - thumbnails_bytes = _directory_size(_resolve_data_path(config.storage.thumbnails_path)) - materials_bytes = _directory_size(_resolve_data_path(config.storage.materials_path)) - temp_bytes = _directory_size(_resolve_data_path(config.storage.temp_path)) + images_bytes = _directory_size(resolve_data_path(config.storage.images_path)) + thumbnails_bytes = _directory_size(resolve_data_path(config.storage.thumbnails_path)) + materials_bytes = _directory_size(resolve_data_path(config.storage.materials_path)) + temp_bytes = _directory_size(resolve_data_path(config.storage.temp_path)) return { "total_bytes": images_bytes + thumbnails_bytes + materials_bytes + temp_bytes, "images_bytes": images_bytes + thumbnails_bytes, @@ -106,13 +107,6 @@ class DashboardService: } -def _resolve_data_path(path: str) -> Path: - resolved = Path(path) - if not resolved.is_absolute(): - resolved = REPO_ROOT / resolved - return resolved - - def _directory_size(path: Path) -> int: if not path.exists(): return 0 diff --git a/backend/services/generation_job_retry_service.py b/backend/services/generation_job_retry_service.py new file mode 100644 index 0000000..c8ec3af --- /dev/null +++ b/backend/services/generation_job_retry_service.py @@ -0,0 +1,433 @@ +"""Synchronous, lineage-preserving retries for persisted generation jobs.""" + +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Any +from uuid import uuid4 + +from backend.dto.common import ApiError, ErrorCode +from backend.dto.job_dto import GenerationTask +from backend.services.generation_service import GenerationService +from backend.services.queue_service import QueueService +from core.identity import RequestContext + + +MAX_SYNCHRONOUS_DEAD_LETTER_RETRIES = 5 + + +class GenerationJobRetryService: + """Create and execute a replacement task from a persisted task request. + + ImageStudio intentionally does not start QueueWorker in the AstrBot plugin + process: no production worker handler or lifecycle owner exists yet. A web + retry therefore has to execute through GenerationService instead of merely + changing the old row back to ``queued``. + """ + + def __init__(self, queue_service: QueueService, generation_service: GenerationService): + self.queue_service = queue_service + self.generation_service = generation_service + + def retry_job( + self, + task_id: str, + ctx: RequestContext, + *, + overrides: dict[str, Any] | None = None, + ) -> GenerationTask: + original = self.queue_service.get_job(task_id) + self._validate_executable(original) + request_overrides = overrides or {} + self._validate_ephemeral_references(original, request_overrides) + operation_id = f"retry_{uuid4().hex}" + retry_key = f"{operation_id}:{original.task_id}" + claimed = self.queue_service.begin_retry(task_id, ctx, operation_id=operation_id) + previous_status = str(claimed.metadata["retry_execution"]["previous_status"]) + request = self._replacement_request( + claimed, + operation_id=operation_id, + retry_key=retry_key, + overrides=request_overrides, + ) + prepared_node = None + + try: + prepared_node = self._prepare_node(claimed, ctx) + response = self.generation_service.generate_node(str(claimed.node_id), request, ctx) + replacement = self.queue_service.get_job(str(response["task_id"])) + except Exception as exc: + replacement = self.queue_service.get_job_by_idempotency_key(retry_key) + node_status_restored = replacement is not None + if replacement is None: + try: + node_status_restored = self._restore_prepared_node(prepared_node, claimed.task_id, ctx) + except Exception: + node_status_restored = False + self._restore_original(claimed, previous_status=previous_status, exc=exc, ctx=ctx) + else: + replacement = self._finalize_lineage(claimed, replacement, operation_id=operation_id, ctx=ctx) + raise self._retry_error( + exc, + original=claimed, + replacement=replacement, + operation_id=operation_id, + original_status_restored=replacement is None, + node_status_restored=node_status_restored, + ) from exc + + return self._finalize_lineage(claimed, replacement, operation_id=operation_id, ctx=ctx) + + def retry_dead_letters(self, ctx: RequestContext, *, limit: int = 5) -> dict[str, Any]: + applied_limit = _synchronous_batch_limit(limit) + jobs = self.queue_service.list_jobs( + status="dead_letter", + page=1, + page_size=applied_limit, + ).items + retried: list[dict[str, Any]] = [] + errors: list[dict[str, Any]] = [] + for job in jobs: + try: + retried.append(self.retry_job(job.task_id, ctx).to_dict()) + except ApiError as exc: + details = dict(exc.details or {}) + errors.append( + { + "task_id": job.task_id, + "error_code": exc.error_code.value, + "message": exc.message, + "replacement_task_id": details.get("replacement_task_id"), + "retry_lineage": details.get("retry_lineage"), + } + ) + return { + "execution_mode": "synchronous", + "requested_limit": _int_or_default(limit, 5), + "applied_limit": applied_limit, + "max_limit": MAX_SYNCHRONOUS_DEAD_LETTER_RETRIES, + "retried": retried, + "errors": errors, + "total": len(retried), + "processed": len(retried) + len(errors), + "remaining": self.queue_service.queue_summary()["dead_letter"], + } + + def _validate_executable(self, task: GenerationTask) -> None: + if task.task_type != "generation" or not task.node_id or not isinstance(task.request, dict): + raise ApiError( + ErrorCode.TASK_NOT_RETRYABLE, + "task has no executable generation request", + { + "task_id": task.task_id, + "task_type": task.task_type, + "node_id": task.node_id, + "request_type": type(task.request).__name__, + }, + ) + + def _validate_ephemeral_references(self, task: GenerationTask, overrides: dict[str, Any]) -> None: + omitted = _ephemeral_reference_count(task.request) + if omitted and not _has_reference_override(overrides): + raise ApiError( + ErrorCode.TASK_NOT_RETRYABLE, + "task used inline reference images that were not persisted; provide replacement references", + { + "task_id": task.task_id, + "ephemeral_data_urls_omitted": omitted, + "required_fields": ["input_images", "image", "selected_draft_image_ids", "stage_inputs"], + }, + ) + + def _prepare_node(self, task: GenerationTask, ctx: RequestContext) -> Any | None: + node = self.generation_service.workflow_service.get_node(str(task.node_id)) + if node.status not in {"queued", "running"}: + return None + last_task_id = _optional_text(node.metadata.get("last_task_id")) + if last_task_id != task.task_id: + raise ApiError( + ErrorCode.TASK_NOT_RETRYABLE, + "node is already owned by another active generation task", + { + "task_id": task.task_id, + "node_id": node.node_id, + "active_task_id": last_task_id, + "node_status": node.status, + }, + ) + self.generation_service.workflow_service.update_node( + node.node_id, + { + "status": "failed", + "metadata": { + **node.metadata, + "retry_preparation": { + "task_id": task.task_id, + "prepared_at": _now(), + "previous_status": node.status, + }, + }, + }, + ctx, + ) + return node + + def _restore_prepared_node(self, original_node: Any | None, task_id: str, ctx: RequestContext) -> bool: + if original_node is None: + return True + workflow_service = self.generation_service.workflow_service + current = workflow_service.get_node(original_node.node_id) + preparation = current.metadata.get("retry_preparation") if isinstance(current.metadata, dict) else None + if ( + current.status != "failed" + or not isinstance(preparation, dict) + or _optional_text(preparation.get("task_id")) != task_id + ): + return False + after = workflow_service.workflow_repository.update_node( + original_node.node_id, + {"status": original_node.status, "metadata": original_node.metadata}, + ) + if after is None: + return False + workflow_service.audit_service.record( + ctx=ctx, + action="rollback_retry_preparation", + target_type="workflow_node", + target_id=original_node.node_id, + before_snapshot=current.to_dict(), + after_snapshot=after.to_dict(), + metadata={"task_id": task_id}, + ) + workflow_service._publish( + "workflow.node_status_changed", + { + "workflow_id": after.workflow_id, + "node_id": after.node_id, + "before_status": current.status, + "after_status": after.status, + }, + ) + workflow_service._publish( + "workflow.node_updated", + {"workflow_id": after.workflow_id, "node_id": after.node_id}, + ) + return True + + def _replacement_request( + self, + task: GenerationTask, + *, + operation_id: str, + retry_key: str, + overrides: dict[str, Any], + ) -> dict[str, Any]: + request = { + key: value + for key, value in dict(task.request or {}).items() + if key not in _DERIVED_REQUEST_FIELDS and key != "idempotency_key" + } + for key, value in overrides.items(): + if key not in _DERIVED_REQUEST_FIELDS and key != "idempotency_key": + request[key] = value + request.update( + { + "idempotency_key": retry_key, + "retry_of_task_id": task.task_id, + "retry_operation_id": operation_id, + } + ) + if task.model_route and not _optional_text(request.get("model_route")): + request["model_route"] = task.model_route + return request + + def _finalize_lineage( + self, + original: GenerationTask, + replacement: GenerationTask, + *, + operation_id: str, + ctx: RequestContext, + ) -> GenerationTask: + previous_lineage = original.metadata.get("retry_lineage") + root_task_id = ( + _optional_text(previous_lineage.get("root_task_id")) + if isinstance(previous_lineage, dict) + else None + ) or original.task_id + lineage = { + "operation_id": operation_id, + "retry_of_task_id": original.task_id, + "root_task_id": root_task_id, + "original_status": original.metadata["retry_execution"]["previous_status"], + "replacement_task_id": replacement.task_id, + "replacement_status": replacement.status, + "completed_at": _now(), + } + updated_replacement = self.queue_service.update_task( + replacement.task_id, + {"metadata": {**replacement.metadata, "retry_lineage": lineage}}, + ctx, + ) + latest_original = self.queue_service.get_job(original.task_id) + retry_execution = dict(latest_original.metadata.get("retry_execution") or {}) + self.queue_service.update_task( + original.task_id, + { + "status": "superseded", + "progress": 100, + "result": { + **latest_original.result, + "replacement_task_id": updated_replacement.task_id, + }, + "metadata": { + **latest_original.metadata, + "retry_execution": { + **retry_execution, + "status": "completed", + "completed_at": lineage["completed_at"], + "replacement_task_id": updated_replacement.task_id, + "replacement_status": updated_replacement.status, + }, + }, + }, + ctx, + ) + return updated_replacement + + def _restore_original( + self, + original: GenerationTask, + *, + previous_status: str, + exc: Exception, + ctx: RequestContext, + ) -> None: + latest = self.queue_service.get_job(original.task_id) + if latest.status != "retrying": + return + retry_execution = dict(latest.metadata.get("retry_execution") or {}) + self.queue_service.update_task( + original.task_id, + { + "status": previous_status, + "metadata": { + **latest.metadata, + "retry_execution": { + **retry_execution, + "status": "rejected", + "rejected_at": _now(), + "error_type": type(exc).__name__, + "error_message": _safe_error_message(exc), + }, + }, + }, + ctx, + ) + + def _retry_error( + self, + exc: Exception, + *, + original: GenerationTask, + replacement: GenerationTask | None, + operation_id: str, + original_status_restored: bool, + node_status_restored: bool, + ) -> ApiError: + replacement_task_id = replacement.task_id if replacement else None + lineage = { + "operation_id": operation_id, + "retry_of_task_id": original.task_id, + "replacement_task_id": replacement_task_id, + "replacement_status": replacement.status if replacement else None, + } + details = { + **(dict(exc.details or {}) if isinstance(exc, ApiError) else {}), + "retry_of_task_id": original.task_id, + "replacement_task_id": replacement_task_id, + "original_status_restored": original_status_restored, + "node_status_restored": node_status_restored, + "retry_lineage": lineage, + } + if isinstance(exc, ApiError): + return ApiError(exc.error_code, exc.message, details) + return ApiError(ErrorCode.GENERATION_FAILED, "task retry execution failed", details) + + +def _synchronous_batch_limit(value: Any) -> int: + return min(max(_int_or_default(value, 5), 1), MAX_SYNCHRONOUS_DEAD_LETTER_RETRIES) + + +def _int_or_default(value: Any, default: int) -> int: + try: + return int(value) + except (TypeError, ValueError): + return default + + +def _optional_text(value: Any) -> str | None: + if value is None: + return None + text = str(value).strip() + return text or None + + +def _safe_error_message(exc: Exception) -> str: + text = " ".join(str(exc or type(exc).__name__).split()) + return text[:500] if text else type(exc).__name__ + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat() + + +_DERIVED_REQUEST_FIELDS = frozenset( + { + "cost_guard", + "expanded_negative_prompt", + "expanded_prompt", + "prompt_expansion", + "reference_persistence", + "resolved_model_route", + } +) + + +def _ephemeral_reference_count(request: dict[str, Any]) -> int: + persistence = request.get("reference_persistence") + if not isinstance(persistence, dict): + return 0 + try: + return max(int(persistence.get("ephemeral_data_urls_omitted") or 0), 0) + except (TypeError, ValueError): + return 0 + + +def _has_reference_override(payload: dict[str, Any]) -> bool: + for key in ("input_images", "image", "selected_draft_image_ids", "stage_inputs"): + if _has_nonempty_value(payload.get(key)): + return True + metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {} + dependency = payload.get("dependency_context") if isinstance(payload.get("dependency_context"), dict) else {} + return any( + _has_nonempty_value(value) + for value in ( + metadata.get("selected_draft_image_ids"), + metadata.get("stage_inputs"), + dependency.get("selected_image_ids"), + dependency.get("selected_draft_image_ids"), + dependency.get("stage_inputs"), + dependency.get("material_bindings"), + ) + ) + + +def _has_nonempty_value(value: Any) -> bool: + if value is None: + return False + if isinstance(value, str): + return bool(value.strip()) + if isinstance(value, (list, tuple, dict, set)): + return bool(value) + return True diff --git a/backend/services/generation_reference_service.py b/backend/services/generation_reference_service.py new file mode 100644 index 0000000..adb3c1c --- /dev/null +++ b/backend/services/generation_reference_service.py @@ -0,0 +1,470 @@ +"""Resolve generation reference images into provider-ready inputs.""" + +from __future__ import annotations + +import base64 +import binascii +import re +from typing import Any, Protocol +from urllib.parse import urlsplit + +from backend.dto.common import ApiError, ErrorCode +from backend.services.image_service import ImageService +from core.storage import VfsStorage + + +MAX_REFERENCE_IMAGE_BYTES = 25 * 1024 * 1024 +MAX_REFERENCE_IMAGE_TOTAL_BYTES = 50 * 1024 * 1024 +MAX_REFERENCE_IMAGES = 16 +_SUPPORTED_IMAGE_MIMES = {"image/png", "image/jpeg", "image/gif", "image/webp"} +_DATA_IMAGE_RE = re.compile(r"^data:([^;,]+)(?:;[^,]*)?;base64,(.*)$", re.IGNORECASE | re.DOTALL) + + +class MaterialResolver(Protocol): + def get_material(self, material_id: str) -> Any | None: ... + + +class GenerationReferenceService: + def __init__( + self, + image_service: ImageService, + storage: VfsStorage, + material_resolver: MaterialResolver | None = None, + ): + self.image_service = image_service + self.storage = storage + self.material_resolver = material_resolver + + def resolve(self, workflow_id: str, payload: dict[str, Any]) -> tuple[str, ...]: + resolved: list[str] = [] + seen: set[str] = set() + image_cache: dict[str, Any] = {} + storage_cache: dict[str, tuple[str, int]] = {} + total_bytes = 0 + for value, source, force_image_id in _reference_candidates(payload): + prepared, canonical_key, byte_count = self._resolve_candidate( + workflow_id, + value, + source=source, + force_image_id=force_image_id, + image_cache=image_cache, + storage_cache=storage_cache, + ) + total_bytes = _append_reference( + resolved, + seen, + prepared, + canonical_key, + byte_count, + total_bytes, + source, + ) + if self.material_resolver is not None: + for material_id, source in _material_reference_candidates(payload): + prepared, canonical_key, byte_count = self._resolve_material( + material_id, + source=source, + storage_cache=storage_cache, + ) + total_bytes = _append_reference( + resolved, + seen, + prepared, + canonical_key, + byte_count, + total_bytes, + source, + ) + return tuple(resolved) + + def _resolve_material( + self, + material_id: str, + *, + source: str, + storage_cache: dict[str, tuple[str, int]], + ) -> tuple[str, str, int]: + material = self.material_resolver.get_material(material_id) if self.material_resolver else None + if material is None: + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "reference material does not exist", + {"material_id": material_id, "source": source}, + ) + if str(material.recognition_status or "").strip() != "confirmed": + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference material is not confirmed", + { + "material_id": material_id, + "recognition_status": material.recognition_status, + "source": source, + }, + ) + image_uri = _optional_text(material.image_uri) + if not image_uri: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "confirmed reference material has no image", + {"material_id": material_id, "source": source}, + ) + return self._prepare_uri(image_uri, source=source, storage_cache=storage_cache) + + def _resolve_candidate( + self, + workflow_id: str, + value: Any, + *, + source: str, + force_image_id: bool, + image_cache: dict[str, Any], + storage_cache: dict[str, tuple[str, int]], + ) -> tuple[str, str, int]: + if isinstance(value, dict): + image_id = _optional_text(value.get("image_id")) + if image_id: + return self._resolve_image_id( + workflow_id, + image_id, + source=source, + image_cache=image_cache, + storage_cache=storage_cache, + ) + for key in ("image_uri", "url", "data_url", "input_image"): + reference = _optional_text(value.get(key)) + if reference: + return self._prepare_uri(reference, source=source, storage_cache=storage_cache) + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference image object must include image_id or image_uri", + {"source": source}, + ) + + reference = _optional_text(value) + if not reference: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference image cannot be empty", + {"source": source}, + ) + if force_image_id or not _is_reference_uri(reference): + return self._resolve_image_id( + workflow_id, + reference, + source=source, + image_cache=image_cache, + storage_cache=storage_cache, + ) + return self._prepare_uri(reference, source=source, storage_cache=storage_cache) + + def _resolve_image_id( + self, + workflow_id: str, + image_id: str, + *, + source: str, + image_cache: dict[str, Any], + storage_cache: dict[str, tuple[str, int]], + ) -> tuple[str, str, int]: + image = image_cache.get(image_id) + if image is None: + try: + image = self.image_service.get_image(image_id) + except ApiError as exc: + if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND: + raise + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "reference image does not exist", + {"image_id": image_id, "source": source}, + ) from exc + image_cache[image_id] = image + if image.workflow_id != workflow_id: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference image does not belong to this workflow", + { + "image_id": image_id, + "workflow_id": workflow_id, + "image_workflow_id": image.workflow_id, + "source": source, + }, + ) + return self._prepare_uri(image.image_uri, source=source, storage_cache=storage_cache) + + def _prepare_uri( + self, + reference: str, + *, + source: str, + storage_cache: dict[str, tuple[str, int]], + ) -> tuple[str, str, int]: + if reference.startswith("storage://"): + cached = storage_cache.get(reference) + if cached is None: + try: + path = self.storage.ensure_file(reference) + size = path.stat().st_size + if size > MAX_REFERENCE_IMAGE_BYTES: + raise _image_too_large(reference, size, source) + body = path.read_bytes() + except ApiError as exc: + if exc.error_code != ErrorCode.MEDIA_NOT_FOUND: + raise + raise ApiError( + ErrorCode.MEDIA_NOT_FOUND, + "reference image file does not exist", + {"uri": reference, "source": source}, + ) from exc + except OSError as exc: + raise ApiError( + ErrorCode.MEDIA_NOT_FOUND, + "reference image file could not be read", + {"uri": reference, "source": source}, + ) from exc + if len(body) > MAX_REFERENCE_IMAGE_BYTES: + raise _image_too_large(reference, len(body), source) + mime = _detect_image_mime(body) + if mime is None: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "reference image is not a supported PNG, JPEG, GIF, or WebP image", + {"uri": reference, "source": source}, + ) + cached = (f"data:{mime};base64,{base64.b64encode(body).decode('ascii')}", len(body)) + storage_cache[reference] = cached + return cached[0], f"storage:{reference}", cached[1] + + if reference.lower().startswith("data:"): + byte_count = _validate_data_image_url(reference, source=source) + return reference, f"data:{reference}", byte_count + + parsed = urlsplit(reference) + if parsed.scheme.lower() in {"http", "https"} and parsed.hostname: + return reference, f"url:{reference}", 0 + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference image must be an image ID, storage URI, HTTP(S) URL, or image data URL", + {"reference": reference, "source": source}, + ) + + +def _reference_candidates(payload: dict[str, Any]) -> list[tuple[Any, str, bool]]: + candidates: list[tuple[Any, str, bool]] = [] + for key in ("input_images", "image"): + for index, value in enumerate(_ordered_values(payload.get(key))): + candidates.append((value, f"{key}[{index}]", False)) + + dependency_context = payload.get("dependency_context") + if not isinstance(dependency_context, dict): + dependency_context = {} + for index, value in enumerate(_ordered_values(dependency_context.get("selected_image_ids"))): + candidates.append((value, f"dependency_context.selected_image_ids[{index}]", True)) + + metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {} + for prefix, value in ( + ("selected_draft_image_ids", payload.get("selected_draft_image_ids")), + ("metadata.selected_draft_image_ids", metadata.get("selected_draft_image_ids")), + ("dependency_context.selected_draft_image_ids", dependency_context.get("selected_draft_image_ids")), + ): + for index, image_id in enumerate(_ordered_values(value)): + candidates.append((image_id, f"{prefix}[{index}]", True)) + + injection_template = ( + dependency_context.get("injection_template") + if isinstance(dependency_context.get("injection_template"), dict) + else {} + ) + for index, image_id in enumerate(_ordered_values(injection_template.get("selected_draft_image_ids"))): + candidates.append( + ( + image_id, + f"dependency_context.injection_template.selected_draft_image_ids[{index}]", + True, + ) + ) + + for prefix, value in ( + ("stage_inputs", payload.get("stage_inputs")), + ("metadata.stage_inputs", metadata.get("stage_inputs")), + ("dependency_context.stage_inputs", dependency_context.get("stage_inputs")), + ("dependency_context.injection_template.stage_inputs", injection_template.get("stage_inputs")), + ): + for index, reference in enumerate(_stage_input_references(value)): + candidates.append((reference, f"{prefix}[{index}]", False)) + return candidates + + +def _material_reference_candidates(payload: dict[str, Any]) -> list[tuple[str, str]]: + dependency_context = payload.get("dependency_context") + if not isinstance(dependency_context, dict): + return [] + bindings = dependency_context.get("material_bindings") + if not isinstance(bindings, dict): + return [] + + candidates: list[tuple[str, str]] = [] + generation_params = bindings.get("generation_params") + if isinstance(generation_params, dict): + for index, material_id in enumerate(_ordered_values(generation_params.get("reference_material_ids"))): + text = _optional_text(material_id) + if text: + candidates.append( + (text, f"dependency_context.material_bindings.generation_params.reference_material_ids[{index}]") + ) + active_bindings = bindings.get("active_bindings") + if isinstance(active_bindings, list): + for index, binding in enumerate(active_bindings): + if not isinstance(binding, dict): + continue + material = binding.get("material") if isinstance(binding.get("material"), dict) else {} + material_id = _optional_text(material.get("material_id") or binding.get("material_id")) + if material_id: + candidates.append( + (material_id, f"dependency_context.material_bindings.active_bindings[{index}].material_id") + ) + + result: list[tuple[str, str]] = [] + seen: set[str] = set() + for material_id, source in candidates: + if material_id not in seen: + result.append((material_id, source)) + seen.add(material_id) + return result + + +def _append_reference( + resolved: list[str], + seen: set[str], + prepared: str, + canonical_key: str, + byte_count: int, + total_bytes: int, + source: str, +) -> int: + if canonical_key in seen: + return total_bytes + if len(resolved) >= MAX_REFERENCE_IMAGES: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "too many reference images", + {"max_reference_images": MAX_REFERENCE_IMAGES, "source": source}, + ) + if total_bytes + byte_count > MAX_REFERENCE_IMAGE_TOTAL_BYTES: + raise ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "reference images exceed the total size limit", + {"max_total_bytes": MAX_REFERENCE_IMAGE_TOTAL_BYTES, "source": source}, + ) + resolved.append(prepared) + seen.add(canonical_key) + return total_bytes + byte_count + + +def _ordered_values(value: Any) -> list[Any]: + values = list(value) if isinstance(value, (list, tuple)) else ([] if value is None else [value]) + return [item for item in values if not isinstance(item, str) or item.strip()] + + +def _stage_input_references(value: Any) -> list[Any]: + if value is None: + return [] + if isinstance(value, str): + return [value] if value.strip() else [] + if isinstance(value, (list, tuple)): + return [reference for item in value for reference in _stage_input_references(item)] + if not isinstance(value, dict): + return [] + if any(_optional_text(value.get(key)) for key in ("image_id", "image_uri", "url", "data_url")): + return [value] + return [ + reference + for item in value.values() + if isinstance(item, (dict, list, tuple)) + for reference in _stage_input_references(item) + ] + + +def _validate_data_image_url(value: str, *, source: str) -> int: + match = _DATA_IMAGE_RE.fullmatch(value) + if match is None: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference data URL must contain a base64-encoded image", + {"source": source}, + ) + declared_mime = match.group(1).strip().lower() + if declared_mime == "image/jpg": + declared_mime = "image/jpeg" + if declared_mime not in _SUPPORTED_IMAGE_MIMES: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "reference data URL uses an unsupported image type", + {"mime": declared_mime, "source": source}, + ) + encoded = re.sub(r"\s+", "", match.group(2)) + if len(encoded) > ((MAX_REFERENCE_IMAGE_BYTES + 2) // 3) * 4: + raise ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "reference data URL exceeds the size limit", + {"max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, + ) + try: + body = base64.b64decode(encoded, validate=True) + except (binascii.Error, ValueError) as exc: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference data URL contains invalid base64", + {"source": source}, + ) from exc + if len(body) > MAX_REFERENCE_IMAGE_BYTES: + raise ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "reference data URL exceeds the size limit", + {"bytes": len(body), "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, + ) + detected_mime = _detect_image_mime(body) + if detected_mime is None: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "reference data URL does not contain a supported image", + {"source": source}, + ) + if detected_mime != declared_mime: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "reference data URL MIME type does not match its image payload", + {"declared_mime": declared_mime, "detected_mime": detected_mime, "source": source}, + ) + return len(body) + + +def _detect_image_mime(body: bytes) -> str | None: + if body.startswith(b"\x89PNG\r\n\x1a\n"): + return "image/png" + if body.startswith(b"\xff\xd8\xff"): + return "image/jpeg" + if body.startswith((b"GIF87a", b"GIF89a")): + return "image/gif" + if len(body) >= 12 and body.startswith(b"RIFF") and body[8:12] == b"WEBP": + return "image/webp" + return None + + +def _image_too_large(uri: str, size: int, source: str) -> ApiError: + return ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "reference image exceeds the size limit", + {"uri": uri, "bytes": size, "max_bytes": MAX_REFERENCE_IMAGE_BYTES, "source": source}, + ) + + +def _is_reference_uri(value: str) -> bool: + return value.lower().startswith(("storage://", "data:", "http://", "https://")) + + +def _optional_text(value: Any) -> str | None: + if value is None: + return None + text = str(value).strip() + return text or None diff --git a/backend/services/generation_service.py b/backend/services/generation_service.py index 783e528..a3af309 100644 --- a/backend/services/generation_service.py +++ b/backend/services/generation_service.py @@ -2,11 +2,13 @@ from __future__ import annotations +import threading from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.dto.job_dto import GenerationTask from backend.services.cost_guard_service import CostGuardService +from backend.services.generation_reference_service import GenerationReferenceService, MaterialResolver from backend.services.image_service import ImageService from backend.services.model_provider_service import ModelProviderService from backend.services.node_dependency_context_service import NodeDependencyContextService @@ -15,13 +17,26 @@ from backend.services.queue_service import QueueService from backend.services.workflow_service import ( LOCKED_NODE_STATUSES, WorkflowService, + is_repeatable_single_image_node, locked_node_edit_error, ) from core.event_bus import EventBus +from core.generation_errors import provider_failure_attribution from core.identity import RequestContext +from engines.image_provider import ImageProviderError from engines.single_flow import SingleFlowEngine +_NODE_GENERATION_LOCKS_GUARD = threading.Lock() +_NODE_GENERATION_LOCKS: dict[str, "_NodeGenerationLock"] = {} + + +class _NodeGenerationLock: + def __init__(self): + self.lock = threading.RLock() + self.users = 0 + + class GenerationService: def __init__( self, @@ -33,17 +48,36 @@ class GenerationService: cost_guard_service: CostGuardService | None = None, prompt_expansion_service: PromptExpansionService | None = None, event_bus: EventBus | None = None, + default_model_route: str | None = None, + require_resolved_model_route: bool = False, + material_resolver: MaterialResolver | None = None, ): self.workflow_service = workflow_service self.queue_service = queue_service self.image_service = image_service self.single_flow_engine = single_flow_engine or SingleFlowEngine() + self.reference_service = GenerationReferenceService( + image_service, + self.single_flow_engine.storage, + material_resolver, + ) self.model_provider_service = model_provider_service self.cost_guard_service = cost_guard_service self.prompt_expansion_service = prompt_expansion_service self.event_bus = event_bus + self.default_model_route = _optional_text(default_model_route) + self.require_resolved_model_route = require_resolved_model_route def generate_node(self, node_id: str, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: + lock_entry = _retain_node_generation_lock(node_id) + lock_entry.lock.acquire() + try: + return self._generate_node_locked(node_id, payload, ctx) + finally: + lock_entry.lock.release() + _release_node_generation_lock(node_id, lock_entry) + + def _generate_node_locked(self, node_id: str, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: node = self.workflow_service.get_node(node_id) idempotency_key = _optional_text(payload.get("idempotency_key")) if idempotency_key: @@ -60,14 +94,48 @@ class GenerationService: }, ) return self._existing_generation_response(existing_task, node_id) - if node.status in LOCKED_NODE_STATUSES: + active_task = self._active_generation_task(node) + if node.status in {"queued", "running"} and active_task is not None: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "generation is already in progress for this node", + { + "node_id": node_id, + "status": node.status, + "last_task_id": active_task.task_id, + "task_status": active_task.status, + }, + ) + if node.status in LOCKED_NODE_STATUSES and not is_repeatable_single_image_node(node): raise locked_node_edit_error(node) workflow = self.workflow_service.get_workflow(node.workflow_id).workflow - model_route = str(payload.get("model_route") or node.model_route or "image_low") + if workflow.status == "cancelled": + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "generation cannot start for a cancelled workflow", + {"workflow_id": workflow.workflow_id, "status": workflow.status}, + ) + profile = self.workflow_service.profile_repository.get(workflow.profile_id) + profile_model_route = _optional_text(getattr(profile, "default_model_route", None)) + model_route = str( + payload.get("model_route") + or node.model_route + or profile_model_route + or self.default_model_route + or "image_low" + ) route_resolution = self._resolve_model_route(model_route) + if self.require_resolved_model_route and route_resolution.get("status") != "resolved": + raise ApiError( + ErrorCode.MODEL_CAPABILITY_UNCONFIRMED, + "未找到可用的生图模型路由,请先在模型配置中完成提供商与路由设置", + {"model_route": model_route, "resolution": route_resolution}, + ) cost_guard = self._check_cost_budget(payload, model_route, route_resolution) - prompt_expansion = self._expand_prompt(workflow.profile_id, node, payload) - generation_request = { + enriched_payload = self._enrich_generation_payload(node.node_id, payload) + prompt_expansion = self._expand_prompt(workflow.profile_id, node, enriched_payload) + reference_images = self.reference_service.resolve(workflow.workflow_id, enriched_payload) + runtime_generation_request = { **payload, "model_route": model_route, "resolved_model_route": route_resolution, @@ -82,6 +150,11 @@ class GenerationService: else {} ), } + generation_request, ephemeral_reference_count = _strip_ephemeral_image_data_urls(runtime_generation_request) + if ephemeral_reference_count: + generation_request["reference_persistence"] = { + "ephemeral_data_urls_omitted": ephemeral_reference_count, + } task = self.queue_service.create_task( { "profile_id": workflow.profile_id, @@ -102,48 +175,165 @@ class GenerationService: "generation.node_queued", {"workflow_id": workflow.workflow_id, "node_id": node_id, "task_id": task.task_id}, ) - self.workflow_service.update_node( - node_id, - { - "status": "queued", - "model_route": model_route, - "metadata": { - **node.metadata, - "last_task_id": task.task_id, - "last_generate_request": generation_request, - }, - }, + queued_metadata = { + **node.metadata, + "last_task_id": task.task_id, + "last_generate_request": generation_request, + } + execution_metadata = queued_metadata.get("execution") + if isinstance(execution_metadata, dict) and execution_metadata.get("prepared_only") is True: + queued_metadata["execution"] = { + **execution_metadata, + "prepared_only": False, + "task_id": task.task_id, + } + queued_node_payload = { + "status": "queued", + "model_route": model_route, + "metadata": queued_metadata, + } + try: + self._queue_generation_node(node, queued_node_payload, ctx) + except Exception: + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=[], + images=[], + ctx=ctx, + ) + try: + self.queue_service.update_task_if_status( + task.task_id, + {"queued"}, + { + "status": "failed", + "progress": 100, + "error_message": "node could not enter the generation queue", + }, + ctx, + ) + except Exception: + pass + raise + running_task = self.queue_service.update_task_if_status( + task.task_id, + {"queued"}, + {"status": "running", "progress": 20}, ctx, + require_workflow_not_cancelled=True, ) - self.queue_service.update_task(task.task_id, {"status": "running", "progress": 20}, ctx) + if running_task is None: + current_task = self.queue_service.get_job(task.task_id) + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=[], + images=[], + ctx=ctx, + ) + raise ApiError( + ErrorCode.GENERATION_FAILED, + "generation task changed before provider execution", + {"task_id": task.task_id, "status": current_task.status}, + ) + task = running_task running_node = self.workflow_service.update_node(node_id, {"status": "running"}, ctx) self._publish( "generation.node_running", {"workflow_id": workflow.workflow_id, "node_id": node_id, "task_id": task.task_id}, ) - assets = self.single_flow_engine.generate(running_node, task, generation_request) - images = [ - self.image_service.create_image( - { - "profile_id": workflow.profile_id, - "workflow_id": workflow.workflow_id, - "node_id": node_id, - "task_id": task.task_id, - "image_uri": asset.image_uri, - "thumbnail_uri": asset.thumbnail_uri, - "positive_prompt": asset.positive_prompt, - "negative_prompt": asset.negative_prompt, - "model_route": asset.model_route, - "seed": asset.seed, - "width": asset.width, - "height": asset.height, - "is_selected": index == 0, - "metadata": asset.metadata, - }, - ctx, + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=[], + images=[], + ctx=ctx, ) - for index, asset in enumerate(assets) - ] + assets: list[Any] = [] + images: list[Any] = [] + try: + runtime_generation_request = { + **runtime_generation_request, + "input_images": reference_images, + } + runtime_generation_request.pop("image", None) + assets = self.single_flow_engine.generate(running_node, task, runtime_generation_request) + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=assets, + images=images, + ctx=ctx, + ) + for asset in assets: + images.append( + self.image_service.create_image( + { + "profile_id": workflow.profile_id, + "workflow_id": workflow.workflow_id, + "node_id": node_id, + "task_id": task.task_id, + "image_uri": asset.image_uri, + "thumbnail_uri": asset.thumbnail_uri, + "positive_prompt": asset.positive_prompt, + "negative_prompt": asset.negative_prompt, + "model_route": asset.model_route, + "seed": asset.seed, + "width": asset.width, + "height": asset.height, + # Keep records unselected until the task completion CAS + # wins. A concurrent cancellation can then roll them + # back without disturbing an older selected image. + "is_selected": False, + "metadata": asset.metadata, + }, + ctx, + ) + ) + except Exception as exc: + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=assets, + images=images, + ctx=ctx, + ) + self._cleanup_generation_outputs(assets=assets, images=images) + failure = self._record_generation_failure( + task=task, + node_id=node_id, + workflow_id=workflow.workflow_id, + route_resolution=route_resolution, + exc=exc, + ctx=ctx, + ) + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=assets, + images=images, + ctx=ctx, + ) + if isinstance(exc, ApiError): + raise + raise ApiError( + ErrorCode.GENERATION_FAILED, + "图像生成失败", + failure, + ) from exc provider_failure = _provider_failure_from_assets([asset.metadata for asset in assets]) result: dict[str, Any] = {"image_ids": [image.image_id for image in images]} update_payload: dict[str, Any] = { @@ -154,11 +344,32 @@ class GenerationService: if provider_failure: result["provider_failure"] = provider_failure update_payload["metadata"] = {**task.metadata, "provider_failure": provider_failure} - completed_task = self.queue_service.update_task( + completed_task = self.queue_service.update_task_if_status( task.task_id, + {"running"}, update_payload, ctx, + require_workflow_not_cancelled=True, ) + if completed_task is None: + current_task = self.queue_service.get_job(task.task_id) + if self._cancel_generation_if_requested(task.task_id, workflow.workflow_id, ctx): + return self._finalize_cancelled_generation( + task_id=task.task_id, + node_id=node_id, + workflow_id=workflow.workflow_id, + assets=assets, + images=images, + ctx=ctx, + ) + self._cleanup_generation_outputs(assets=assets, images=images) + raise ApiError( + ErrorCode.GENERATION_FAILED, + "generation task changed before completion", + {"task_id": task.task_id, "status": current_task.status}, + ) + if images: + images[0] = self.image_service.select_image(images[0].image_id, ctx) completed_node = self.workflow_service.update_node(node_id, {"status": "completed"}, ctx) self._publish( "generation.node_completed", @@ -193,6 +404,21 @@ class GenerationService: "idempotent_replay": True, } + def _active_generation_task(self, node: Any) -> GenerationTask | None: + metadata = node.metadata if isinstance(node.metadata, dict) else {} + task_id = _optional_text(metadata.get("last_task_id")) + if not task_id: + return None + try: + task = self.queue_service.get_job(task_id) + except ApiError as exc: + if exc.error_code == ErrorCode.RESOURCE_NOT_FOUND: + return None + raise + if task.node_id == node.node_id and task.status in {"queued", "running"}: + return task + return None + def _resolve_model_route(self, route_name: str) -> dict[str, Any]: if not self.model_provider_service: return {"route_name": route_name, "status": "unresolved"} @@ -237,6 +463,56 @@ class GenerationService: raise ApiError(ErrorCode.VALIDATION_FAILED, "generation budget exceeded", guard) return guard + def _queue_generation_node( + self, + original_node: Any, + payload: dict[str, Any], + ctx: RequestContext, + ) -> Any: + current = self.workflow_service.get_node(original_node.node_id) + if current.status not in LOCKED_NODE_STATUSES: + return self.workflow_service.update_node(current.node_id, payload, ctx) + if not is_repeatable_single_image_node(current): + raise locked_node_edit_error(current) + + repeat_payload = dict(payload) + repeat_metadata = repeat_payload.get("metadata") if isinstance(repeat_payload.get("metadata"), dict) else {} + repeat_payload["metadata"] = { + **repeat_metadata, + "repeat_generation": { + "previous_status": current.status, + "previous_selected_image_id": current.selected_image_id, + "task_id": repeat_metadata.get("last_task_id"), + }, + } + after = self.workflow_service.workflow_repository.update_node(current.node_id, repeat_payload) + if after is None: + raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "node not found", {"node_id": current.node_id}) + self.workflow_service.audit_service.record( + ctx=ctx, + action="update_node", + target_type="workflow_node", + target_id=current.node_id, + before_snapshot=current.to_dict(), + after_snapshot=after.to_dict(), + metadata={"source": "generation.repeatable_single_image"}, + ) + if self.workflow_service.event_bus: + self.workflow_service.event_bus.publish( + "workflow.node_status_changed", + { + "workflow_id": after.workflow_id, + "node_id": after.node_id, + "before_status": current.status, + "after_status": after.status, + }, + ) + self.workflow_service.event_bus.publish( + "workflow.node_updated", + {"workflow_id": after.workflow_id, "node_id": after.node_id}, + ) + return after + def _expand_prompt( self, profile_id: str, @@ -248,18 +524,230 @@ class GenerationService: profile = self.workflow_service.profile_repository.get(profile_id) if profile is None: return None + return self.prompt_expansion_service.expand_for_node(profile, node, payload) + + def _enrich_generation_payload(self, node_id: str, payload: dict[str, Any]) -> dict[str, Any]: enriched_payload = dict(payload) - if "dependency_context" not in enriched_payload: + if not isinstance(enriched_payload.get("dependency_context"), dict): enriched_payload["dependency_context"] = NodeDependencyContextService( self.workflow_service, self.image_service, - ).get_context(node.node_id) - return self.prompt_expansion_service.expand_for_node(profile, node, enriched_payload) + ).get_context(node_id) + return enriched_payload def _publish(self, event_type: str, payload: dict[str, Any]) -> None: if self.event_bus: self.event_bus.publish(event_type, payload) + def _cancel_generation_if_requested( + self, + task_id: str, + workflow_id: str, + ctx: RequestContext, + ) -> bool: + task = self.queue_service.get_job(task_id) + if task.status == "cancelled": + return True + workflow = self.workflow_service.get_workflow(workflow_id).workflow + if workflow.status != "cancelled" or task.status not in {"queued", "running"}: + return False + try: + task = self.queue_service.cancel_job( + task_id, + ctx, + reason="owning workflow was cancelled", + ) + except ApiError: + task = self.queue_service.get_job(task_id) + return task.status == "cancelled" + + def _finalize_cancelled_generation( + self, + *, + task_id: str, + node_id: str, + workflow_id: str, + assets: list[Any], + images: list[Any], + ctx: RequestContext, + ) -> dict[str, Any]: + cleanup = self._cleanup_generation_outputs(assets=assets, images=images) + task = self.queue_service.get_job(task_id) + node = self.workflow_service.get_node(node_id) + node_metadata = node.metadata if isinstance(node.metadata, dict) else {} + node_task_id = _optional_text(node_metadata.get("last_task_id")) + if node_task_id == task_id and node.status in {"queued", "running", "cancelled"}: + cancellation = task.metadata.get("cancellation") if isinstance(task.metadata, dict) else None + cancellation_reason = ( + _optional_text(cancellation.get("reason")) + if isinstance(cancellation, dict) + else None + ) + node_update: dict[str, Any] = { + "metadata": { + **node_metadata, + "generation_cancellation": { + "task_id": task_id, + "reason": cancellation_reason or "cancelled", + "cleanup": cleanup, + }, + }, + } + if node.status in {"queued", "running"}: + node_update["status"] = "cancelled" + node = self.workflow_service.update_node( + node_id, + node_update, + ctx, + ) + self._publish( + "generation.node_cancelled", + { + "workflow_id": workflow_id, + "node_id": node_id, + "task_id": task_id, + "node_status": node.status, + "cleanup": cleanup, + }, + ) + return { + "task_id": task.task_id, + "task_status": task.status, + "node_status": node.status, + "images": [], + "cancelled": True, + } + + def _cleanup_generation_outputs(self, *, assets: list[Any], images: list[Any]) -> dict[str, Any]: + removed_image_ids: list[str] = [] + removed_uris: list[str] = [] + errors: list[dict[str, str]] = [] + for image in reversed(images): + image_id = _optional_text(getattr(image, "image_id", None)) + if not image_id: + continue + try: + removed = self.image_service.image_repository.delete_metadata(image_id) + if removed is not None: + removed_image_ids.append(image_id) + except Exception as exc: + errors.append( + { + "target": image_id, + "error_type": exc.__class__.__name__, + "message": str(exc), + } + ) + + seen_uris: set[str] = set() + for asset in assets: + for field in ("image_uri", "thumbnail_uri"): + uri = _optional_text(getattr(asset, field, None)) + if not uri or uri in seen_uris: + continue + seen_uris.add(uri) + try: + path = self.single_flow_engine.storage.resolve_uri(uri) + if path.exists() and path.is_file(): + path.unlink() + removed_uris.append(uri) + except Exception as exc: + errors.append( + { + "target": uri, + "error_type": exc.__class__.__name__, + "message": str(exc), + } + ) + return { + "image_records_removed": removed_image_ids, + "files_removed": removed_uris, + "errors": errors, + } + + def _record_generation_failure( + self, + *, + task: GenerationTask, + node_id: str, + workflow_id: str, + route_resolution: dict[str, Any], + exc: Exception, + ctx: RequestContext, + ) -> dict[str, Any]: + if isinstance(exc, ImageProviderError): + failure = provider_failure_attribution(exc, route_context=route_resolution, fallback_used=False) + else: + failure = { + "source": "generation_pipeline", + "category": "internal_error", + "error_type": exc.__class__.__name__, + "message": "generation pipeline failed", + "retryable": False, + "fallback_used": False, + } + failed_task = None + try: + failed_task = self.queue_service.update_task_if_status( + task.task_id, + {"queued", "running"}, + { + "status": "failed", + "progress": 100, + "error_message": str(failure.get("message") or "generation failed"), + "metadata": {**task.metadata, "generation_failure": failure}, + }, + ctx, + ) + except Exception: + pass + if failed_task is not None: + try: + node = self.workflow_service.get_node(node_id) + node_metadata = node.metadata if isinstance(node.metadata, dict) else {} + if ( + _optional_text(node_metadata.get("last_task_id")) == task.task_id + and node.status in {"queued", "running"} + ): + self.workflow_service.update_node( + node_id, + { + "status": "failed", + "metadata": { + **node_metadata, + "generation_failure": failure, + "last_task_id": task.task_id, + }, + }, + ctx, + ) + except Exception: + pass + self._publish( + "generation.node_failed", + {"workflow_id": workflow_id, "node_id": node_id, "task_id": task.task_id, "failure": failure}, + ) + return failure + + +def _retain_node_generation_lock(node_id: str) -> _NodeGenerationLock: + key = str(node_id) + with _NODE_GENERATION_LOCKS_GUARD: + entry = _NODE_GENERATION_LOCKS.get(key) + if entry is None: + entry = _NodeGenerationLock() + _NODE_GENERATION_LOCKS[key] = entry + entry.users += 1 + return entry + + +def _release_node_generation_lock(node_id: str, entry: _NodeGenerationLock) -> None: + key = str(node_id) + with _NODE_GENERATION_LOCKS_GUARD: + entry.users -= 1 + if entry.users == 0 and _NODE_GENERATION_LOCKS.get(key) is entry: + _NODE_GENERATION_LOCKS.pop(key, None) + def _optional_text(value: Any) -> str | None: if value is None: @@ -268,6 +756,37 @@ def _optional_text(value: Any) -> str | None: return text or None +_OMITTED_EPHEMERAL_REFERENCE = object() + + +def _strip_ephemeral_image_data_urls(value: Any) -> tuple[Any, int]: + """Remove inline image payloads before writing a generation request to storage.""" + + if isinstance(value, str): + if value.lstrip().lower().startswith("data:image/"): + return _OMITTED_EPHEMERAL_REFERENCE, 1 + return value, 0 + if isinstance(value, dict): + cleaned: dict[Any, Any] = {} + omitted = 0 + for key, item in value.items(): + prepared, item_omitted = _strip_ephemeral_image_data_urls(item) + omitted += item_omitted + if prepared is not _OMITTED_EPHEMERAL_REFERENCE: + cleaned[key] = prepared + return cleaned, omitted + if isinstance(value, (list, tuple)): + cleaned_items: list[Any] = [] + omitted = 0 + for item in value: + prepared, item_omitted = _strip_ephemeral_image_data_urls(item) + omitted += item_omitted + if prepared is not _OMITTED_EPHEMERAL_REFERENCE: + cleaned_items.append(prepared) + return cleaned_items, omitted + return value, 0 + + def _provider_failure_from_assets(metadata_items: list[dict[str, Any]]) -> dict[str, Any] | None: for metadata in metadata_items: failure = metadata.get("provider_error") diff --git a/backend/services/history_service.py b/backend/services/history_service.py index 88fad09..f837944 100644 --- a/backend/services/history_service.py +++ b/backend/services/history_service.py @@ -227,13 +227,45 @@ class HistoryService: "node does not belong to this workflow", {"workflow_id": workflow_id, "node_id": node_id}, ) + image_id = _optional_text(payload.get("image_id")) + if image_id: + image = self.image_service.get_image(image_id) + if image.workflow_id != workflow_id: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "image does not belong to this workflow", + { + "workflow_id": workflow_id, + "image_id": image_id, + "image_workflow_id": image.workflow_id, + }, + ) + if image.node_id: + image_node = self.workflow_service.get_node(image.node_id) + if image_node.workflow_id != workflow_id: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "image node does not belong to this workflow", + { + "workflow_id": workflow_id, + "image_id": image_id, + "image_node_id": image.node_id, + "image_node_workflow_id": image_node.workflow_id, + }, + ) + if node_id and image.node_id != node_id: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "image does not belong to this node", + {"workflow_id": workflow_id, "node_id": node_id, "image_id": image_id}, + ) history = self.workflow_repository.create_history( { "history_id": payload.get("history_id") or new_history_id(), "profile_id": workflow.profile_id, "workflow_id": workflow.workflow_id, "node_id": node_id, - "image_id": payload.get("image_id"), + "image_id": image_id, "branch_name": payload.get("branch_name") or workflow.current_branch or "main", "action": payload.get("action") or "save_version", "title": payload.get("title") or workflow.display_name, diff --git a/backend/services/image_service.py b/backend/services/image_service.py index ecdf8e5..93184d3 100644 --- a/backend/services/image_service.py +++ b/backend/services/image_service.py @@ -6,7 +6,7 @@ from typing import Any from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode -from backend.dto.image_dto import GenerationImage +from backend.dto.image_dto import GenerationImage, ImageListResult from backend.services.workflow_service import LOCKED_NODE_STATUSES, locked_node_edit_error from core.audit_service import AuditService from core.identity import RequestContext @@ -80,6 +80,31 @@ class ImageService: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "节点不存在", {"node_id": node_id}) return self.image_repository.list_by_node(node_id, include_archived=include_archived) + def list_images( + self, + *, + profile_id: str | None = None, + workflow_id: str | None = None, + include_archived: bool = True, + page: int = 1, + page_size: int = 60, + ) -> ImageListResult: + normalized_page = max(page, 1) + normalized_page_size = min(max(page_size, 1), 100) + items, total = self.image_repository.list_images( + profile_id=profile_id, + workflow_id=workflow_id, + include_archived=include_archived, + page=normalized_page, + page_size=normalized_page_size, + ) + return ImageListResult( + items=items, + total=total, + page=normalized_page, + page_size=normalized_page_size, + ) + def get_image(self, image_id: str) -> GenerationImage: image = self.image_repository.get(image_id) if image is None: @@ -176,7 +201,12 @@ class ImageService: if not image.node_id: return node = self.workflow_repository.get_node(image.node_id) - if node and node.status in LOCKED_NODE_STATUSES: + # ``completed`` means generation finished and its candidates are ready + # for curation. Prompt/node edits stay locked in WorkflowService, but + # users must still be able to change the tentative selection or + # archive rejected candidates until an image is formally adopted and + # the node enters ``selected``. + if node and node.status in LOCKED_NODE_STATUSES and node.status != "completed": raise locked_node_edit_error(node) diff --git a/backend/services/integration_service.py b/backend/services/integration_service.py index a3521a4..01b49ac 100644 --- a/backend/services/integration_service.py +++ b/backend/services/integration_service.py @@ -22,13 +22,24 @@ class IntegrationService: wardrobe_service: WardrobeService, integration_repository: IntegrationRepository, token_service: IntegrationTokenService | None = None, + *, + enabled: bool = True, ): self.wardrobe_service = wardrobe_service self.integration_repository = integration_repository self.token_service = token_service + self.enabled = enabled def daily_outfit(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: source = str(payload.get("request_source") or PRIVATE_COMPANION) + if not self.enabled: + error = ApiError( + ErrorCode.FORBIDDEN, + "private companion integration is disabled", + {"request_source": source, "feature": "private_companion_integration"}, + ) + self._record_failure(source, payload, error) + raise error if source != PRIVATE_COMPANION: error = ApiError( ErrorCode.INTEGRATION_TOKEN_INVALID, diff --git a/backend/services/integration_token_service.py b/backend/services/integration_token_service.py index e09d333..a40ae32 100644 --- a/backend/services/integration_token_service.py +++ b/backend/services/integration_token_service.py @@ -6,13 +6,12 @@ import hashlib import hmac import secrets from datetime import datetime, timedelta, timezone -from pathlib import Path from typing import Any from backend.dto.common import ApiError, ErrorCode -from backend.services.settings_service import _dump_yaml from core.audit_service import AuditService from core.config_service import ConfigService +from core.config_writer import config_file_lock, dump_yaml, write_text_atomic from core.identity import RequestContext from core.interop import PRIVATE_COMPANION from database.db_helper import _load_yaml_subset @@ -45,27 +44,30 @@ class IntegrationTokenService: def rotate(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: token = _token_or_generate(payload.get("token")) grace_seconds = _grace_seconds(payload.get("grace_seconds")) - config = self._load_config() - security = dict(config.get("security") or {}) - now = _now() - current_hash = str(security.get("integration_token_hash") or "").strip() - current_salt = str(security.get("integration_token_salt") or "").strip() - if current_hash and current_salt: - security["previous_integration_token_hash"] = current_hash - security["previous_integration_token_salt"] = current_salt - security["previous_integration_token_expires_at"] = _format_time(now + timedelta(seconds=grace_seconds)) - else: - security.pop("previous_integration_token_hash", None) - security.pop("previous_integration_token_salt", None) - security.pop("previous_integration_token_expires_at", None) - salt = secrets.token_hex(16) - security["integration_token_hash"] = _hash_token(token, salt) - security["integration_token_salt"] = salt - security["integration_token_rotated_at"] = _format_time(now) - security["integration_token_set"] = True - security.pop("integration_token", None) - config["security"] = security - self._write_config(config) + with config_file_lock(self.config_service.config_path): + config = self._load_config() + security = dict(config.get("security") or {}) + now = _now() + current_hash = str(security.get("integration_token_hash") or "").strip() + current_salt = str(security.get("integration_token_salt") or "").strip() + if current_hash and current_salt: + security["previous_integration_token_hash"] = current_hash + security["previous_integration_token_salt"] = current_salt + security["previous_integration_token_expires_at"] = _format_time( + now + timedelta(seconds=grace_seconds) + ) + else: + security.pop("previous_integration_token_hash", None) + security.pop("previous_integration_token_salt", None) + security.pop("previous_integration_token_expires_at", None) + salt = secrets.token_hex(16) + security["integration_token_hash"] = _hash_token(token, salt) + security["integration_token_salt"] = salt + security["integration_token_rotated_at"] = _format_time(now) + security["integration_token_set"] = True + security.pop("integration_token", None) + config["security"] = security + self._write_config(config) public_status = self.status() if self.audit_service: self.audit_service.record( @@ -93,7 +95,11 @@ class IntegrationTokenService: {"request_source": normalized_source}, ) if not _current_token_set(security): - return {"valid": True, "required": False, "token_slot": "not_configured"} + raise ApiError( + ErrorCode.INTEGRATION_TOKEN_INVALID, + "integration token has not been configured", + {"request_source": normalized_source, "token_configured": False}, + ) candidate = str(token or "").strip() if not candidate: raise ApiError(ErrorCode.INTEGRATION_TOKEN_INVALID, "integration token is required", {}) @@ -120,9 +126,7 @@ class IntegrationTokenService: return _load_yaml_subset(path.read_text(encoding="utf-8")) def _write_config(self, config: dict[str, Any]) -> None: - path: Path = self.config_service.config_path - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(_dump_yaml(config), encoding="utf-8") + write_text_atomic(self.config_service.config_path, dump_yaml(config)) def _current_token_set(security: dict[str, Any]) -> bool: diff --git a/backend/services/material_service.py b/backend/services/material_service.py index 6a01570..0cdb3b2 100644 --- a/backend/services/material_service.py +++ b/backend/services/material_service.py @@ -2,6 +2,7 @@ from __future__ import annotations +import base64 from pathlib import PurePosixPath from typing import Any, Callable from uuid import uuid4 @@ -9,10 +10,15 @@ from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from backend.dto.material_dto import Material, MaterialCategory, MaterialListResult from core.audit_service import AuditService +from core.image_formats import ( + IMAGE_EXTENSIONS_BY_MIME, + SUPPORTED_IMAGE_EXTENSIONS, + detect_image_format, +) from core.identity import RequestContext +from core.storage import VfsStorage from database.repositories.material_repository import MaterialRepository from engines.vision_provider import ( - MockVisionProvider, VisionProvider, VisionProviderError, VisionRecognitionRequest, @@ -23,11 +29,9 @@ from engines.vision_provider import ( MATERIAL_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm", "confirmed", "archived"} MAX_UPLOAD_BYTES = 20 * 1024 * 1024 UPLOAD_SIZE_FIELDS = ("size_bytes", "content_length", "file_size", "size") -UPLOAD_ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"} +UPLOAD_ALLOWED_EXTENSIONS = set(SUPPORTED_IMAGE_EXTENSIONS) UPLOAD_ALLOWED_CONTENT_TYPES = { - "image/jpeg": {".jpg", ".jpeg"}, - "image/png": {".png"}, - "image/webp": {".webp"}, + mime_type: set(extensions) for mime_type, extensions in IMAGE_EXTENSIONS_BY_MIME.items() } @@ -39,11 +43,13 @@ class MaterialService: *, vision_provider_factory: Callable[[dict[str, Any]], VisionProvider | None] | None = None, default_recognition_route: str = "material_vlm", + storage: VfsStorage | None = None, ): self.repository = repository self.audit_service = audit_service self.vision_provider_factory = vision_provider_factory self.default_recognition_route = default_recognition_route + self.storage = storage or VfsStorage() def create_category(self, payload: dict[str, Any], ctx: RequestContext) -> MaterialCategory: name = str(payload.get("name") or "").strip() @@ -117,14 +123,9 @@ class MaterialService: return category def create_material(self, payload: dict[str, Any], ctx: RequestContext) -> Material: + self.validate_material_payload(payload, creating=True) display_name = str(payload.get("display_name") or "").strip() - if not display_name: - raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"}) - self._validate_category(payload.get("category_id")) - self._validate_storage_uri(payload.get("image_uri"), "image_uri") - self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri") status = payload.get("recognition_status", "pending_upload") - self._validate_status(status) material = self.repository.create_material( { "material_id": payload.get("material_id") or new_material_id(), @@ -174,19 +175,10 @@ class MaterialService: def update_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material: before = self.get_material(material_id) - if "category_id" in payload: - self._validate_category(payload.get("category_id")) - if "image_uri" in payload: - self._validate_storage_uri(payload.get("image_uri"), "image_uri") - if "thumbnail_uri" in payload: - self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri") - if "recognition_status" in payload: - self._validate_status(payload["recognition_status"]) + self.validate_material_payload(payload, creating=False) update_payload = dict(payload) if "display_name" in update_payload: update_payload["display_name"] = str(update_payload["display_name"]).strip() - if not update_payload["display_name"]: - raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"}) after = self.repository.update_material(material_id, update_payload) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "material not found", {"material_id": material_id}) @@ -200,6 +192,19 @@ class MaterialService: ) return after + def validate_material_payload(self, payload: dict[str, Any], *, creating: bool) -> None: + if creating or "display_name" in payload: + if not str(payload.get("display_name") or "").strip(): + raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"}) + if creating or "category_id" in payload: + self._validate_category(payload.get("category_id")) + if creating or "image_uri" in payload: + self._validate_storage_uri(payload.get("image_uri"), "image_uri") + if creating or "thumbnail_uri" in payload: + self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri") + if creating or "recognition_status" in payload: + self._validate_status(payload.get("recognition_status", "pending_upload")) + def delete_material(self, material_id: str, ctx: RequestContext) -> Material: return self.update_material(material_id, {"recognition_status": "archived"}, ctx) @@ -232,7 +237,7 @@ class MaterialService: "extension": extension, "size_bytes": declared_size, "max_size_bytes": MAX_UPLOAD_BYTES, - "mock": True, + "storage_reference_only": True, } }, }, @@ -250,23 +255,49 @@ class MaterialService: return self._recognize_material(material, ctx) def _recognize_material(self, material: Material, ctx: RequestContext) -> Material: - recognition, provider_error, fallback_used, route_name = self._recognize_with_adapter(material) + route_name = _recognition_route(material.metadata, self.default_recognition_route) + provider = self._vision_provider(material, route_name) + if provider is None: + raise ApiError( + ErrorCode.MODEL_CAPABILITY_UNCONFIRMED, + "material vision route is not configured or its credentials are unavailable", + { + "material_id": material.material_id, + "route_name": route_name, + "modality": "vision_recognition", + }, + ) + + request = _vision_request(material, self.storage) + try: + recognition = provider.recognize_material(request) + except VisionProviderError as exc: + failure = _vision_provider_error(exc) + self._record_recognition_failure(material, route_name, failure, ctx) + raise _vision_api_error(material.material_id, route_name, failure) from None + except Exception as exc: + failure = _unexpected_vision_provider_error(provider, exc) + self._record_recognition_failure(material, route_name, failure, ctx) + raise _vision_api_error(material.material_id, route_name, failure) from None + generated_tags = recognition.tags - prompt = material.prompt or recognition.prompt or _mock_prompt(material) + metadata = { + key: value + for key, value in material.metadata.items() + if key not in {"confirmed", "recognition", "recognition_failure"} + } after = self.update_material( material.material_id, { - "prompt": prompt, - "negative_prompt": material.negative_prompt or recognition.negative_prompt or "body, face, background, watermark", + "prompt": material.prompt or recognition.prompt, + "negative_prompt": material.negative_prompt or recognition.negative_prompt, "tags": sorted(set(material.tags + generated_tags)), "recognition_status": "pending_confirm", "metadata": { - **material.metadata, + **metadata, "recognition": _recognition_metadata( recognition, route_name=route_name, - fallback_used=fallback_used, - provider_error=provider_error, ), }, }, @@ -282,32 +313,65 @@ class MaterialService: ) return after - def _recognize_with_adapter( + def _vision_provider(self, material: Material, route_name: str) -> VisionProvider | None: + if self.vision_provider_factory is None: + return None + return self.vision_provider_factory( + { + "route_name": route_name, + "modality": "vision_recognition", + "material_id": material.material_id, + "image_uri": material.image_uri, + "thumbnail_uri": material.thumbnail_uri, + } + ) + + def _record_recognition_failure( self, material: Material, - ) -> tuple[VisionRecognitionResult, dict[str, Any] | None, bool, str]: - route_name = _recognition_route(material.metadata, self.default_recognition_route) - request = _vision_request(material) - provider = None - if self.vision_provider_factory: - provider = self.vision_provider_factory( - { - "route_name": route_name, - "modality": "vision_recognition", - "material_id": material.material_id, - "image_uri": material.image_uri, - "thumbnail_uri": material.thumbnail_uri, - } - ) - if provider is None: - return _mock_vision_recognition(material), None, False, route_name - try: - return provider.recognize_material(request), None, False, route_name - except VisionProviderError as exc: - return _mock_vision_recognition(material), _vision_provider_error(exc), True, route_name + route_name: str, + failure: dict[str, Any], + ctx: RequestContext, + ) -> Material: + metadata = { + key: value + for key, value in material.metadata.items() + if key not in {"confirmed", "recognition", "recognition_failure"} + } + after = self.update_material( + material.material_id, + { + "recognition_status": "pending_recognition", + "metadata": { + **metadata, + "recognition_failure": {**failure, "route_name": route_name}, + }, + }, + ctx, + ) + self.audit_service.record( + ctx=ctx, + action="recognize_material_failed", + target_type="material", + target_id=material.material_id, + before_snapshot=material.to_dict(), + after_snapshot=after.to_dict(), + metadata={"route_name": route_name, "error_type": failure.get("error_type")}, + ) + return after def confirm_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material: material = self.get_material(material_id) + if material.recognition_status not in {"pending_confirm", "confirmed"}: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "material must have a successful recognition result before confirmation", + { + "material_id": material_id, + "recognition_status": material.recognition_status, + "required_status": "pending_confirm", + }, + ) update_payload = { "recognition_status": "confirmed", "display_name": payload.get("display_name", material.display_name), @@ -354,34 +418,97 @@ def new_material_id() -> str: return f"mat_{uuid4().hex}" -def _mock_prompt(material: Material) -> str: - base = material.display_name.strip().lower().replace("_", " ") - return f"{base}, clean product reference, transparent background" - - -def _mock_tags(material: Material) -> list[str]: - text = f"{material.display_name} {material.prompt or ''}".lower() - tags = ["material"] - for keyword in ("white", "blue", "black", "red", "ribbon", "shirt", "blouse", "dress", "skirt", "shoe"): - if keyword in text: - tags.append(keyword) - return tags - - -def _vision_request(material: Material) -> VisionRecognitionRequest: +def _vision_request(material: Material, storage: VfsStorage) -> VisionRecognitionRequest: + image_data_url, content_type, size_bytes = _storage_image_data_url( + str(material.image_uri or ""), + material.metadata, + storage, + ) return VisionRecognitionRequest( display_name=material.display_name, - image_uri=str(material.image_uri or ""), - thumbnail_uri=material.thumbnail_uri, + image_uri=image_data_url, + thumbnail_uri=None, prompt=material.prompt, negative_prompt=material.negative_prompt, tags=tuple(material.tags), - metadata=material.metadata, + metadata={ + **material.metadata, + "vision_input": { + "source_uri": material.image_uri, + "content_type": content_type, + "size_bytes": size_bytes, + }, + }, ) -def _mock_vision_recognition(material: Material) -> VisionRecognitionResult: - return MockVisionProvider().recognize_material(_vision_request(material)) +def _storage_image_data_url( + image_uri: str, + metadata: dict[str, Any], + storage: VfsStorage, +) -> tuple[str, str, int]: + if not image_uri: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "material image_uri is required for recognition", + {"field": "image_uri"}, + ) + path = storage.ensure_file(image_uri) + try: + reported_size = path.stat().st_size + except OSError: + raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "material image could not be inspected", {"uri": image_uri}) from None + if reported_size > MAX_UPLOAD_BYTES: + raise ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "material image exceeds the recognition size limit", + {"uri": image_uri, "size_bytes": reported_size, "max_size_bytes": MAX_UPLOAD_BYTES}, + ) + try: + with path.open("rb") as handle: + content = handle.read(MAX_UPLOAD_BYTES + 1) + except OSError: + raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "material image could not be read", {"uri": image_uri}) from None + if len(content) > MAX_UPLOAD_BYTES: + raise ApiError( + ErrorCode.UPLOAD_TOO_LARGE, + "material image exceeds the recognition size limit", + {"uri": image_uri, "size_bytes": len(content), "max_size_bytes": MAX_UPLOAD_BYTES}, + ) + content_type = _image_content_type(content) + if content_type is None: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "material image bytes do not match a supported image format", + {"uri": image_uri, "allowed": sorted(UPLOAD_ALLOWED_CONTENT_TYPES)}, + ) + + extension = _suffix(image_uri) + if extension and extension not in UPLOAD_ALLOWED_CONTENT_TYPES[content_type]: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "material image extension does not match its file signature", + {"uri": image_uri, "extension": extension, "detected_content_type": content_type}, + ) + upload = metadata.get("upload") if isinstance(metadata.get("upload"), dict) else {} + declared_content_type = _optional_text(upload.get("content_type")) + if declared_content_type and declared_content_type != content_type: + raise ApiError( + ErrorCode.UNSUPPORTED_FILE_TYPE, + "material image content type does not match its file signature", + { + "uri": image_uri, + "declared_content_type": declared_content_type, + "detected_content_type": content_type, + }, + ) + encoded = base64.b64encode(content).decode("ascii") + return f"data:{content_type};base64,{encoded}", content_type, len(content) + + +def _image_content_type(content: bytes) -> str | None: + image_format = detect_image_format(content) + return image_format.mime_type if image_format is not None else None def _recognition_route(metadata: dict[str, Any], default_route: str) -> str: @@ -398,8 +525,6 @@ def _recognition_metadata( recognition: VisionRecognitionResult, *, route_name: str, - fallback_used: bool, - provider_error: dict[str, Any] | None, ) -> dict[str, Any]: metadata = { "engine": "mock_vlm" if recognition.provider_id == "mock" else "vlm_adapter", @@ -407,26 +532,52 @@ def _recognition_metadata( "model": recognition.model, "confidence": recognition.confidence, "route_name": route_name, - "fallback_used": fallback_used, + "fallback_used": False, "description": recognition.description, "raw_metadata": recognition.raw_metadata, } - if provider_error: - metadata["provider_error"] = provider_error return metadata def _vision_provider_error(exc: VisionProviderError) -> dict[str, Any]: + failure = { + "source": "vision_provider", + "provider_id": _optional_text(exc.provider_id) or "unknown", + "status_code": exc.status_code, + "error_type": _optional_text(exc.error_type) or "provider_error", + } + if isinstance(exc.details.get("retryable"), bool): + failure["retryable"] = exc.details["retryable"] + return failure + + +def _unexpected_vision_provider_error(provider: VisionProvider, exc: Exception) -> dict[str, Any]: return { "source": "vision_provider", - "provider_id": exc.provider_id, - "status_code": exc.status_code, - "error_type": exc.error_type, - "message": str(exc), - "details": exc.details, + "provider_id": _optional_text(getattr(provider, "provider_id", None)) or "unknown", + "status_code": None, + "error_type": "unexpected_provider_error", + "exception_type": exc.__class__.__name__, } +def _vision_api_error(material_id: str, route_name: str, failure: dict[str, Any]) -> ApiError: + details = { + "material_id": material_id, + "route_name": route_name, + "provider_id": failure.get("provider_id"), + "status_code": failure.get("status_code"), + "error_type": failure.get("error_type"), + } + if "retryable" in failure: + details["retryable"] = failure["retryable"] + return ApiError( + ErrorCode.GENERATION_FAILED, + "material vision provider request failed", + details, + ) + + def _normalize_upload_filename(value: Any) -> str | None: if value is None: return None diff --git a/backend/services/model_provider_bootstrap.py b/backend/services/model_provider_bootstrap.py new file mode 100644 index 0000000..5116e4b --- /dev/null +++ b/backend/services/model_provider_bootstrap.py @@ -0,0 +1,292 @@ +"""Bootstrap image-generation and material-vision routes from configuration.""" + +from __future__ import annotations + +from collections.abc import Mapping +import re +from typing import Any + +from backend.services.model_provider_service import ModelProviderService + + +def sync_generation_provider_from_config( + service: ModelProviderService, + config: Mapping[str, Any], +) -> dict[str, Any]: + generation = _mapping(config.get("generation")) + provider = _mapping(generation.get("provider")) + default_route = _text(generation.get("default_model")) + route_name = _text(provider.get("route_name")) or default_route + model_id = _text(provider.get("model_id")) or default_route + base_url = _text(provider.get("base_url")) + if not any((default_route, route_name, model_id, base_url)): + _disable_config_routes(service, "image_generation") + return {"configured": False, "status": "not_configured"} + + missing = [ + field + for field, value in ( + ("generation.default_model", route_name), + ("generation.provider.model_id", model_id), + ("generation.provider.base_url", base_url), + ) + if not value + ] + if missing: + _disable_config_routes(service, "image_generation") + return {"configured": False, "status": "incomplete", "missing_fields": missing} + + provider_id = _text(provider.get("provider_id")) or "imagestudio_default" + provider_payload: dict[str, Any] = { + "provider_id": provider_id, + "display_name": _text(provider.get("display_name")) or "ImageStudio default provider", + "provider_type": "openai_compatible", + "base_url": base_url, + "image_endpoint": _text(provider.get("image_endpoint")) or "/v1/images/generations", + "timeout_seconds": _positive_int(provider.get("timeout_seconds"), 180), + "enabled": _bool(provider.get("enabled", True)), + "metadata": {"source": "config_bootstrap"}, + } + api_key_env_var = _text(provider.get("api_key_env_var")) + api_key_secret_ref = _text(provider.get("api_key_secret_ref")) + if api_key_env_var: + provider_payload["api_key_env_var"] = api_key_env_var + if api_key_secret_ref: + provider_payload["api_key_secret_ref"] = api_key_secret_ref + service.upsert_provider(provider_payload) + route = _upsert_config_route( + service, + { + "route_name": route_name, + "provider_id": provider_id, + "model_id": model_id, + "modality": "image_generation", + "priority": _int(provider.get("priority"), 10), + "enabled": _bool(provider.get("enabled", True)), + "metadata": {"source": "config_bootstrap"}, + } + ) + return { + "configured": True, + "status": "ready", + "provider_id": provider_id, + "route_name": route["route_name"], + "model_id": route["model_id"], + "api_key_source": "env" if api_key_env_var else "secret_ref" if api_key_secret_ref else "none", + } + + +def sync_vision_provider_from_config( + service: ModelProviderService, + config: Mapping[str, Any], +) -> dict[str, Any]: + """Persist the configured material-recognition route. + + Vision settings may omit provider connection fields. In that case they + inherit the generation provider's ID, base URL, key reference, timeout and + compatible image endpoint. The vision model remains explicit because an + image-generation model is not necessarily multimodal. + """ + + generation = _mapping(config.get("generation")) + generation_provider = _mapping(generation.get("provider")) + vision = _mapping(config.get("vision")) + vision_provider = _mapping(vision.get("provider")) + + default_route = _text(vision.get("default_route")) + route_name = _text(vision_provider.get("route_name")) or default_route + model_id = _text(vision_provider.get("model_id")) + base_url = _text(vision_provider.get("base_url")) or _text(generation_provider.get("base_url")) + vision_endpoint = _text(vision_provider.get("vision_endpoint")) or "/v1/chat/completions" + + configured_values = ( + model_id, + _text(vision_provider.get("base_url")), + _text(vision_provider.get("provider_id")), + _text(vision_provider.get("api_key_env_var")), + _text(vision_provider.get("api_key_secret_ref")), + ) + if not any(configured_values): + _disable_config_routes(service, "vision_recognition") + return { + "configured": False, + "status": "not_configured", + "route_name": route_name or None, + } + + missing = [ + field + for field, value in ( + ("vision.default_route", route_name), + ("vision.provider.model_id", model_id), + ("vision.provider.base_url", base_url), + ) + if not value + ] + if missing: + _disable_config_routes(service, "vision_recognition") + return { + "configured": False, + "status": "incomplete", + "route_name": route_name or None, + "missing_fields": missing, + } + + generation_provider_id = _text(generation_provider.get("provider_id")) or "imagestudio_default" + requested_provider_id = _text(vision_provider.get("provider_id")) + generation_api_key_env_var = _text(generation_provider.get("api_key_env_var")) + generation_api_key_secret_ref = _text(generation_provider.get("api_key_secret_ref")) + api_key_env_var = _text(vision_provider.get("api_key_env_var")) or generation_api_key_env_var + api_key_secret_ref = _text(vision_provider.get("api_key_secret_ref")) or generation_api_key_secret_ref + generation_timeout = _positive_int(generation_provider.get("timeout_seconds"), 180) + vision_timeout = _positive_int( + vision_provider.get("timeout_seconds", generation_provider.get("timeout_seconds")), + 180, + ) + connection_differs = any( + ( + requested_provider_id and requested_provider_id != generation_provider_id, + _text(vision_provider.get("base_url")) + and _text(vision_provider.get("base_url")) != _text(generation_provider.get("base_url")), + _text(vision_provider.get("api_key_env_var")) + and api_key_env_var != generation_api_key_env_var, + _text(vision_provider.get("api_key_secret_ref")) + and api_key_secret_ref != generation_api_key_secret_ref, + _text(vision_provider.get("provider_type")) + and _text(vision_provider.get("provider_type")) + != (_text(generation_provider.get("provider_type")) or "openai_compatible"), + _text(vision_provider.get("display_name")) + and _text(vision_provider.get("display_name")) != _text(generation_provider.get("display_name")), + vision_timeout != generation_timeout, + ) + ) + reuses_generation_provider = not connection_differs + provider_id = ( + generation_provider_id + if reuses_generation_provider + else requested_provider_id or f"{generation_provider_id}_vision" + ) + route_enabled = _bool(vision_provider.get("enabled", True)) + provider_enabled = ( + _bool(generation_provider.get("enabled", True)) + if reuses_generation_provider + else route_enabled + ) + provider_payload: dict[str, Any] = { + "provider_id": provider_id, + "display_name": ( + _text(vision_provider.get("display_name")) + or _text(generation_provider.get("display_name")) + or "ImageStudio vision provider" + ), + "provider_type": ( + _text(vision_provider.get("provider_type")) + or _text(generation_provider.get("provider_type")) + or "openai_compatible" + ), + "base_url": base_url, + "image_endpoint": _text(generation_provider.get("image_endpoint")) or "/v1/images/generations", + "timeout_seconds": vision_timeout if not reuses_generation_provider else generation_timeout, + "enabled": provider_enabled, + "metadata": {"source": "config_bootstrap", "vision_enabled": True}, + } + if api_key_env_var: + provider_payload["api_key_env_var"] = api_key_env_var + if api_key_secret_ref: + provider_payload["api_key_secret_ref"] = api_key_secret_ref + service.upsert_provider(provider_payload) + route = _upsert_config_route( + service, + { + "route_name": route_name, + "provider_id": provider_id, + "model_id": model_id, + "modality": "vision_recognition", + "priority": _int(vision_provider.get("priority"), 10), + "enabled": route_enabled, + "settings": {"vision_endpoint": vision_endpoint}, + "metadata": { + "source": "config_bootstrap", + "reuses_generation_provider": reuses_generation_provider, + }, + } + ) + return { + "configured": True, + "status": "ready", + "provider_id": provider_id, + "route_name": route["route_name"], + "model_id": route["model_id"], + "vision_endpoint": vision_endpoint, + "reuses_generation_provider": reuses_generation_provider, + "provider_id_auto_derived": bool(not reuses_generation_provider and not requested_provider_id), + "api_key_source": "env" if api_key_env_var else "secret_ref" if api_key_secret_ref else "none", + } + + +def _upsert_config_route(service: ModelProviderService, payload: dict[str, Any]) -> dict[str, Any]: + """Keep a single active config-owned route across provider/model changes.""" + + route_name = _text(payload.get("route_name")) + modality = _text(payload.get("modality")) or "image_generation" + stable_route_id = _config_route_id(route_name, modality) + route = service.upsert_route({**payload, "route_id": stable_route_id}) + _disable_config_routes(service, modality, except_route_id=stable_route_id) + return route + + +def _disable_config_routes( + service: ModelProviderService, + modality: str, + *, + except_route_id: str | None = None, +) -> None: + for existing in service.list_routes(): + metadata = _mapping(existing.get("metadata")) + if ( + existing.get("route_id") == except_route_id + or existing.get("modality") != modality + or metadata.get("source") != "config_bootstrap" + or not existing.get("enabled") + ): + continue + service.upsert_route( + { + **existing, + "enabled": False, + "metadata": { + **metadata, + **({"superseded_by": except_route_id} if except_route_id else {"disabled_by": "config"}), + }, + } + ) + + +def _config_route_id(route_name: str, modality: str) -> str: + stem = re.sub(r"[^A-Za-z0-9_]+", "_", f"{modality}_{route_name}").strip("_").lower() + return f"route_config_{stem or 'model'}" + + +def _mapping(value: Any) -> dict[str, Any]: + return dict(value) if isinstance(value, Mapping) else {} + + +def _text(value: Any) -> str: + return str(value or "").strip() + + +def _bool(value: Any) -> bool: + if isinstance(value, str): + return value.strip().lower() in {"1", "true", "yes", "on", "enabled"} + return bool(value) + + +def _int(value: Any, default: int) -> int: + try: + return int(value) + except (TypeError, ValueError): + return default + + +def _positive_int(value: Any, default: int) -> int: + return max(_int(value, default), 1) diff --git a/backend/services/model_provider_runtime.py b/backend/services/model_provider_runtime.py index f22d3de..4d37330 100644 --- a/backend/services/model_provider_runtime.py +++ b/backend/services/model_provider_runtime.py @@ -3,6 +3,7 @@ from __future__ import annotations from typing import Any +from urllib.parse import urlsplit from backend.services.model_provider_service import ModelProviderService from core.secret_service import SecretStore, resolve_secret_value @@ -35,18 +36,28 @@ class ModelProviderRuntime: secret_ref=provider.get("api_key_secret_ref"), secret_store=self.secret_store, ) - if not secret.value: + secret_configured = bool(provider.get("api_key_env_var") or provider.get("api_key_secret_ref")) + if secret_configured and not secret.value: return None + settings = dict(resolved.get("settings") or {}) + capabilities = dict(provider.get("capabilities") or {}) + base_url = str(provider.get("base_url") or "") return OpenAIImageProvider( ImageProviderConfig( provider_id=str(resolved["provider_id"]), - base_url=str(provider.get("base_url") or ""), - api_key=secret.value, + base_url=base_url, + api_key=secret.value or "", image_model=str(resolved["model_id"]), image_endpoint=str(provider.get("image_endpoint") or "/v1/images/generations"), provider_type=str(provider.get("provider_type") or "openai_compatible"), timeout_seconds=int(provider.get("timeout_seconds") or 180), extra_headers=dict(provider.get("extra_headers") or {}), + supports_negative_prompt=_configured_bool( + settings.get("supports_negative_prompt"), + capabilities.get("supports_negative_prompt"), + capabilities.get("negative_prompt"), + default=_default_negative_prompt_support(base_url), + ), ) ) @@ -65,15 +76,19 @@ class ModelProviderRuntime: secret_ref=provider.get("api_key_secret_ref"), secret_store=self.secret_store, ) - if not secret.value: + secret_configured = bool(provider.get("api_key_env_var") or provider.get("api_key_secret_ref")) + if secret_configured and not secret.value: + return None + base_url = str(provider.get("base_url") or "").strip() + if not base_url: return None settings = dict(resolved.get("settings") or {}) capabilities = dict(provider.get("capabilities") or {}) return OpenAIVisionProvider( VisionProviderConfig( provider_id=str(resolved["provider_id"]), - base_url=str(provider.get("base_url") or ""), - api_key=secret.value, + base_url=base_url, + api_key=secret.value or "", vision_model=str(resolved["model_id"]), vision_endpoint=str( settings.get("vision_endpoint") @@ -85,3 +100,25 @@ class ModelProviderRuntime: extra_headers=dict(provider.get("extra_headers") or {}), ) ) + + +def _configured_bool(*values: Any, default: bool) -> bool: + for value in values: + if value is None: + continue + if isinstance(value, str): + normalized = value.strip().lower() + if normalized in {"1", "true", "yes", "on", "enabled"}: + return True + if normalized in {"0", "false", "no", "off", "disabled"}: + return False + return bool(value) + return default + + +def _default_negative_prompt_support(base_url: str) -> bool: + try: + hostname = str(urlsplit(base_url).hostname or "").lower() + except ValueError: + return True + return not (hostname == "api.openai.com" or hostname.endswith(".openai.azure.com")) diff --git a/backend/services/profile_service.py b/backend/services/profile_service.py index f29f4a9..2fe3c7a 100644 --- a/backend/services/profile_service.py +++ b/backend/services/profile_service.py @@ -23,7 +23,9 @@ class ProfileService: def create_profile(self, payload: dict[str, Any], ctx: RequestContext) -> CharacterProfile: self._validate_create_payload(payload) - owner_user_id = payload.get("owner_user_id") or ctx.actor_id + # Ownership comes from the authenticated caller. Accepting an + # arbitrary owner_user_id would allow cross-tenant profile creation. + owner_user_id = ctx.actor_id if not owner_user_id: raise ApiError( ErrorCode.VALIDATION_FAILED, @@ -57,7 +59,7 @@ class ProfileService: ) return profile - def get_profile(self, profile_id: str) -> CharacterProfile: + def get_profile(self, profile_id: str, ctx: RequestContext | None = None) -> CharacterProfile: profile = self.repository.get(profile_id) if profile is None or profile.status == "deleted": raise ApiError( @@ -65,6 +67,8 @@ class ProfileService: "角色档案不存在", {"profile_id": profile_id}, ) + if ctx is not None: + self._require_owner(profile, ctx) return profile def list_profiles( @@ -90,7 +94,7 @@ class ProfileService: payload: dict[str, Any], ctx: RequestContext, ) -> CharacterProfile: - before = self.get_profile(profile_id) + before = self.get_profile(profile_id, ctx) if "name" in payload and not str(payload["name"]).strip(): raise ApiError(ErrorCode.VALIDATION_FAILED, "角色名称不能为空", {"field": "name"}) update_payload = dict(payload) @@ -114,7 +118,7 @@ class ProfileService: return after def delete_profile(self, profile_id: str, ctx: RequestContext) -> CharacterProfile: - before = self.get_profile(profile_id) + before = self.get_profile(profile_id, ctx) after = self.repository.soft_delete(profile_id) if after is None: raise ApiError( @@ -137,6 +141,17 @@ class ProfileService: if not name: raise ApiError(ErrorCode.VALIDATION_FAILED, "角色名称不能为空", {"field": "name"}) + def _require_owner(self, profile: CharacterProfile, ctx: RequestContext) -> None: + if ctx.actor_id and ctx.actor_id == profile.owner_user_id: + return + # Use not-found semantics so guessed resource IDs cannot enumerate + # another user's profiles. + raise ApiError( + ErrorCode.RESOURCE_NOT_FOUND, + "角色档案不存在", + {"profile_id": profile.profile_id}, + ) + def new_profile_id() -> str: return f"profile_{uuid4().hex}" diff --git a/backend/services/prompt_expansion_service.py b/backend/services/prompt_expansion_service.py index 271bfe7..2cffaf3 100644 --- a/backend/services/prompt_expansion_service.py +++ b/backend/services/prompt_expansion_service.py @@ -41,6 +41,36 @@ class PromptExpansionService: **(profile.metadata.get("prompt_variables") if isinstance(profile.metadata.get("prompt_variables"), dict) else {}), **(payload.get("variables") if isinstance(payload.get("variables"), dict) else {}), } + injection_payload = injection_payload_from_generation_request(payload) + dependency_injection = ( + dependency_context.get("injection_template") + if isinstance(dependency_context.get("injection_template"), dict) + else {} + ) + material_bindings = ( + injection_payload["material_bindings"] + or dependency_context.get("material_bindings") + or dependency_injection.get("material_bindings") + or [] + ) + stage_inputs = ( + injection_payload["stage_inputs"] + or dependency_context.get("stage_inputs") + or dependency_injection.get("stage_inputs") + or {} + ) + selected_draft_image_ids = ( + injection_payload["selected_draft_image_ids"] + or dependency_context.get("selected_draft_image_ids") + or dependency_injection.get("selected_draft_image_ids") + or [] + ) + context_prompt_parts = _unique_prompt_parts( + [ + *_prompt_values(dependency_context.get("prompt_context")), + *_material_prompt_parts(material_bindings), + ] + ) result = merge_prompt_sections( { "parts": [profile.base_prompt, profile.appearance_prompt, profile.style_prompt], @@ -57,24 +87,16 @@ class PromptExpansionService: "negative_parts": _as_list(prompt_plan_generation.get("negative_patch")), "variables": variables, }, + { + "parts": context_prompt_parts, + "variables": variables, + }, { "parts": _payload_parts(payload), "negative_parts": _payload_negative_parts(payload), "variables": variables, }, ) - injection_payload = injection_payload_from_generation_request(payload) - dependency_injection = ( - dependency_context.get("injection_template") - if isinstance(dependency_context.get("injection_template"), dict) - else {} - ) - material_bindings = ( - injection_payload["material_bindings"] - or dependency_context.get("material_bindings") - or dependency_injection.get("material_bindings") - or [] - ) node_injection = build_node_injection_contract( node, requested_kind=injection_payload["requested_kind"], @@ -82,8 +104,8 @@ class PromptExpansionService: dependency_context=dependency_context, material_bindings=material_bindings, prompt_plan=prompt_plan or dependency_injection.get("prompt_plan") or {}, - stage_inputs=injection_payload["stage_inputs"], - selected_draft_image_ids=injection_payload["selected_draft_image_ids"], + stage_inputs=stage_inputs, + selected_draft_image_ids=_string_list(selected_draft_image_ids), ui_context=injection_payload["ui_context"], ) return { @@ -121,3 +143,117 @@ def _as_list(value: Any) -> list[Any]: if isinstance(value, list): return value return [value] + + +def _material_prompt_parts(material_bindings: Any) -> list[str]: + if not isinstance(material_bindings, (dict, list, tuple)): + return [] + + structured: list[str] = [] + contexts: list[str] = [] + if isinstance(material_bindings, dict): + structured.extend(_prompt_values(material_bindings.get("material_prompts"))) + structured.extend(_prompt_values(material_bindings.get("reference_prompts"))) + generation_params = material_bindings.get("generation_params") + if isinstance(generation_params, dict): + structured.extend(_prompt_values(generation_params.get("reference_prompts"))) + structured.extend(_raw_material_prompt_values(material_bindings.get("active_bindings"))) + structured.extend(_raw_material_prompt_values(material_bindings.get("rules"))) + contexts.extend(_prompt_values(material_bindings.get("prompt_context"))) + else: + structured.extend(_raw_material_prompt_values(material_bindings)) + + return _unique_prompt_parts([*structured, *contexts]) + + +def _raw_material_prompt_values(value: Any) -> list[str]: + if not isinstance(value, (list, tuple)): + return [] + result: list[str] = [] + for item in value: + if not isinstance(item, dict): + continue + result.extend(_prompt_values(item.get("material_prompt"))) + material = item.get("material") + if isinstance(material, dict): + result.extend(_prompt_values(material.get("prompt"))) + return result + + +def _prompt_values(value: Any) -> list[str]: + if value is None: + return [] + if isinstance(value, str): + text = value.strip() + return _split_prompt_text(text) if text else [] + if isinstance(value, (list, tuple)): + result: list[str] = [] + for item in value: + result.extend(_prompt_values(item)) + return result + if isinstance(value, dict): + for key in ("prompt", "text"): + if key in value: + return _prompt_values(value.get(key)) + return [] + + +def _unique_prompt_parts(values: list[str]) -> list[str]: + result: list[str] = [] + seen: set[str] = set() + for value in values: + text = str(value or "").strip() + key = text.casefold() + if text and key not in seen: + result.append(text) + seen.add(key) + return result + + +def _string_list(value: Any) -> list[str]: + if isinstance(value, str): + return [value] if value.strip() else [] + if not isinstance(value, (list, tuple)): + return [] + return _unique_prompt_parts([str(item) for item in value if str(item or "").strip()]) + + +def _split_prompt_text(text: str) -> list[str]: + parts: list[str] = [] + current: list[str] = [] + depth = 0 + quote: str | None = None + escaped = False + for character in text: + if escaped: + current.append(character) + escaped = False + continue + if character == "\\": + current.append(character) + escaped = True + continue + if quote: + current.append(character) + if character == quote: + quote = None + continue + if character in {'"', "'"}: + current.append(character) + quote = character + continue + if character in "([{": + depth += 1 + elif character in ")]}": + depth = max(depth - 1, 0) + if character == "," and depth == 0: + part = "".join(current).strip() + if part: + parts.append(part) + current = [] + continue + current.append(character) + part = "".join(current).strip() + if part: + parts.append(part) + return parts diff --git a/backend/services/queue_service.py b/backend/services/queue_service.py index 7bc4d39..a600d89 100644 --- a/backend/services/queue_service.py +++ b/backend/services/queue_service.py @@ -24,8 +24,12 @@ TASK_STATUSES = { "failed", "cancelled", "dead_letter", + "retrying", + "superseded", } +RETRYABLE_TASK_STATUSES = {"failed", "dead_letter", "cancelled"} + class QueueService: def __init__(self, repository: JobRepository, audit_service: AuditService, event_bus: EventBus | None = None): @@ -125,34 +129,44 @@ class QueueService: return self.repository.get_by_idempotency_key(normalized_key) def cancel_job(self, task_id: str, ctx: RequestContext, *, reason: str | None = None) -> GenerationTask: - before = self.get_job(task_id) - if before.status == "cancelled": - return before - if before.status in {"completed", "succeeded"}: - raise ApiError( - ErrorCode.TASK_NOT_CANCELABLE, - "task cannot be cancelled from current status", - {"task_id": task_id, "status": before.status}, - ) - self._validate_task_status_transition(before.status, "cancelled") - after = self.repository.update( - task_id, - { - "status": "cancelled", - "error_message": _optional_text(reason) or before.error_message, - "metadata": { - **before.metadata, - "cancellation": { - "requested_by": ctx.actor_id or "system", - "requested_at": _now(), - "reason": _optional_text(reason) or "cancelled", - "previous_status": before.status, + while True: + before = self.get_job(task_id) + if before.status == "cancelled": + return before + if before.status == "retrying": + raise ApiError( + ErrorCode.TASK_NOT_CANCELABLE, + "task retry execution is already in progress", + {"task_id": task_id, "status": before.status}, + ) + if before.status in {"completed", "succeeded", "superseded"}: + raise ApiError( + ErrorCode.TASK_NOT_CANCELABLE, + "task cannot be cancelled from current status", + {"task_id": task_id, "status": before.status}, + ) + self._validate_task_status_transition(before.status, "cancelled") + after = self.repository.update_if_status( + task_id, + {before.status}, + { + "status": "cancelled", + "error_message": _optional_text(reason) or before.error_message, + "metadata": { + **before.metadata, + "cancellation": { + "requested_by": ctx.actor_id or "system", + "requested_at": _now(), + "reason": _optional_text(reason) or "cancelled", + "previous_status": before.status, + }, }, }, - }, - ) - if after is None: - raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "task not found", {"task_id": task_id}) + ) + if after is not None: + break + # The task changed after it was read. Re-evaluate the current + # state instead of applying cancellation from a stale snapshot. self.audit_service.record( ctx=ctx, action="cancel_task", @@ -164,12 +178,155 @@ class QueueService: self._publish_status_change(before, after) return after + def update_task_if_status( + self, + task_id: str, + expected_statuses: set[str] | tuple[str, ...] | list[str], + payload: dict[str, Any], + ctx: RequestContext, + *, + require_workflow_not_cancelled: bool = False, + ) -> GenerationTask | None: + """Update a task only if the status observed by this caller still owns it.""" + + normalized_statuses = { + str(status).strip() + for status in expected_statuses + if str(status).strip() + } + before = self.get_job(task_id) + if before.status not in normalized_statuses: + return None + status = payload.get("status") + if status is not None: + self._validate_task_status_transition(before.status, str(status)) + if require_workflow_not_cancelled: + after = self.repository.update_if_status_unless_workflow_cancelled( + task_id, + {before.status}, + payload, + ) + else: + after = self.repository.update_if_status(task_id, {before.status}, payload) + if after is None: + return None + self.audit_service.record( + ctx=ctx, + action="update_task", + target_type="generation_task", + target_id=task_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + metadata={"compare_and_set": True}, + ) + if before.status != after.status: + self._publish_status_change(before, after) + self._publish("generation.task_updated", {"task_id": task_id, "status": after.status}) + return after + + def cancel_workflow_jobs( + self, + workflow_id: str, + ctx: RequestContext, + *, + reason: str = "workflow cancelled", + ) -> dict[str, Any]: + """CAS-cancel every queued/running task currently owned by a workflow.""" + + cancelled_ids: list[str] = [] + skipped: list[dict[str, str]] = [] + for status in ("queued", "running"): + while True: + candidates, _ = self.repository.list( + status=status, + workflow_id=workflow_id, + page=1, + page_size=100, + ) + if not candidates: + break + changed = 0 + for candidate in candidates: + try: + cancelled = self.cancel_job(candidate.task_id, ctx, reason=reason) + if cancelled.status == "cancelled": + cancelled_ids.append(cancelled.task_id) + except ApiError as exc: + current = self.get_job(candidate.task_id) + skipped.append( + { + "task_id": candidate.task_id, + "status": current.status, + "error_code": exc.error_code.value, + } + ) + current = self.get_job(candidate.task_id) + if current.status != status: + changed += 1 + if changed == 0: + break + return { + "workflow_id": workflow_id, + "cancelled_task_ids": cancelled_ids, + "skipped": skipped, + } + def is_cancelled(self, task_id: str) -> bool: return self.get_job(task_id).status == "cancelled" - def retry_job(self, task_id: str, ctx: RequestContext) -> GenerationTask: + def claim_queued_task( + self, + task_id: str, + ctx: RequestContext, + *, + worker_id: str, + ) -> GenerationTask | None: + """Atomically claim one queued task for a worker.""" + before = self.get_job(task_id) - if before.status not in {"failed", "dead_letter", "cancelled"}: + if before.status != "queued": + return None + self._validate_task_status_transition(before.status, "running") + attempt = _int_or_default(before.metadata.get("worker_attempt"), 0) + 1 + after = self.repository.update_if_status( + task_id, + {"queued"}, + { + "status": "running", + "progress": max(before.progress, 1), + "metadata": { + **before.metadata, + "worker_attempt": attempt, + "worker": { + "worker_id": worker_id, + "status": "running", + "claimed_at": _now(), + }, + }, + }, + ) + if after is None: + return None + self.audit_service.record( + ctx=ctx, + action="claim_task", + target_type="generation_task", + target_id=task_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + self._publish_status_change(before, after) + return after + + def requeue_job(self, task_id: str, ctx: RequestContext) -> GenerationTask: + """Requeue a task for an explicitly managed QueueWorker. + + Web retry routes use GenerationJobRetryService instead because the + AstrBot plugin does not start a persistent QueueWorker by default. + """ + + before = self.get_job(task_id) + if before.status not in RETRYABLE_TASK_STATUSES: raise ApiError( ErrorCode.TASK_NOT_RETRYABLE, "task cannot be retried from current status", @@ -182,14 +339,59 @@ class QueueService: "status": "queued", "progress": 0, "error_message": None, - "metadata": {**before.metadata, "retry_requested": True}, + "metadata": {**before.metadata, "requeue_requested": True}, }, ) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "task not found", {"task_id": task_id}) self.audit_service.record( ctx=ctx, - action="retry_task", + action="requeue_task", + target_type="generation_task", + target_id=task_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + self._publish_status_change(before, after) + return after + + def begin_retry(self, task_id: str, ctx: RequestContext, *, operation_id: str) -> GenerationTask: + """Atomically reserve a failed task for synchronous retry execution.""" + + before = self.get_job(task_id) + if before.status not in RETRYABLE_TASK_STATUSES: + raise ApiError( + ErrorCode.TASK_NOT_RETRYABLE, + "task cannot be retried from current status", + {"task_id": task_id, "status": before.status}, + ) + self._validate_task_status_transition(before.status, "retrying") + retry_metadata = { + "operation_id": operation_id, + "status": "running", + "requested_by": ctx.actor_id or "system", + "requested_at": _now(), + "previous_status": before.status, + } + after = self.repository.update_if_status( + task_id, + {before.status}, + { + "status": "retrying", + "progress": 0, + "metadata": {**before.metadata, "retry_execution": retry_metadata}, + }, + ) + if after is None: + current = self.get_job(task_id) + raise ApiError( + ErrorCode.TASK_NOT_RETRYABLE, + "task retry was already claimed or its status changed", + {"task_id": task_id, "status": current.status}, + ) + self.audit_service.record( + ctx=ctx, + action="begin_retry_task", target_type="generation_task", target_id=task_id, before_snapshot=before.to_dict(), @@ -223,7 +425,7 @@ class QueueService: counts = self.repository.count_by_status() return { "pending": counts.get("created", 0) + counts.get("queued", 0), - "running": counts.get("running", 0), + "running": counts.get("running", 0) + counts.get("retrying", 0), "failed": counts.get("failed", 0), "dead_letter": counts.get("dead_letter", 0), } @@ -231,16 +433,16 @@ class QueueService: def recent_jobs(self, limit: int = 10) -> list[dict[str, Any]]: return [task.to_dict() for task in self.repository.recent(limit=limit)] - def retry_dead_letters(self, ctx: RequestContext, *, limit: int = 50) -> dict[str, Any]: + def requeue_dead_letters(self, ctx: RequestContext, *, limit: int = 50) -> dict[str, Any]: jobs = self.list_jobs(status="dead_letter", page=1, page_size=_batch_limit(limit)).items - retried = [] + requeued = [] errors = [] for job in jobs: try: - retried.append(self.retry_job(job.task_id, ctx).to_dict()) + requeued.append(self.requeue_job(job.task_id, ctx).to_dict()) except ApiError as exc: errors.append({"task_id": job.task_id, "error_code": exc.error_code.value, "message": exc.message}) - return {"retried": retried, "errors": errors, "total": len(retried)} + return {"requeued": requeued, "errors": errors, "total": len(requeued)} def move_failed_to_dead_letter(self, ctx: RequestContext, *, limit: int = 50) -> dict[str, Any]: jobs = self.list_jobs(status="failed", page=1, page_size=_batch_limit(limit)).items @@ -311,3 +513,10 @@ def _batch_limit(value: int) -> int: except (TypeError, ValueError): limit = 50 return min(max(limit, 1), 100) + + +def _int_or_default(value: Any, default: int) -> int: + try: + return int(value) + except (TypeError, ValueError): + return default diff --git a/backend/services/review_service.py b/backend/services/review_service.py index 51846be..b91bfdc 100644 --- a/backend/services/review_service.py +++ b/backend/services/review_service.py @@ -6,8 +6,8 @@ from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.services.workflow_service import WorkflowService -from backend.services.settings_service import _dump_yaml from core.config_service import ConfigService +from core.config_writer import config_file_lock, dump_yaml, write_text_atomic from database.db_helper import _load_yaml_subset from database.repositories.image_repository import ImageRepository from engines.review_flow import ReviewFlowEngine, ReviewPolicy @@ -36,10 +36,10 @@ class ReviewService: validation = self.validate_policy(payload) if not validation["valid"]: raise ApiError(ErrorCode.VALIDATION_FAILED, "review policy validation failed", validation) - config = self._load_config_mapping() - config["review_policy"] = validation["policy"] - self.config_service.config_path.parent.mkdir(parents=True, exist_ok=True) - self.config_service.config_path.write_text(_dump_yaml(config), encoding="utf-8") + with config_file_lock(self.config_service.config_path): + config = self._load_config_mapping() + config["review_policy"] = validation["policy"] + write_text_atomic(self.config_service.config_path, dump_yaml(config)) self.review_engine = ReviewFlowEngine(ReviewPolicy.from_mapping(validation["policy"])[0]) return {"saved": True, "policy": self.get_policy()} diff --git a/backend/services/settings_service.py b/backend/services/settings_service.py index 470f25a..ca4d2cd 100644 --- a/backend/services/settings_service.py +++ b/backend/services/settings_service.py @@ -9,9 +9,17 @@ from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from core.config_service import ConfigService +from core.config_writer import config_file_lock, dump_yaml, write_text_atomic from core.audit_service import AuditService from core.identity import RequestContext -from database.db_helper import REPO_ROOT, _load_yaml_subset +from core.runtime_paths import is_default_config_path, resolve_plugin_path +from database.db_helper import ( + Database, + DatabaseSettings, + get_runtime_config_overrides, + load_config_file_payload, + load_config_payload, +) SENSITIVE_KEY_PARTS = ("password", "token", "secret", "api_key", "apikey", "key", "dsn") @@ -55,6 +63,39 @@ class SettingsService: _field("private_companion_integration", "bool", label="私伴插件集成"), ], }, + { + "key": "generation", + "title": "生图提供方", + "fields": [ + _field("default_model", "string", label="默认路由名"), + _field("provider.provider_id", "string", label="提供方 ID"), + _field("provider.base_url", "string", label="API 根地址"), + _field("provider.image_endpoint", "string", label="生图 endpoint"), + _field("provider.model_id", "string", label="模型 ID"), + _field("provider.route_name", "string", label="路由名"), + _field("provider.api_key_env_var", "string", label="API Key 环境变量"), + _field("provider.timeout_seconds", "number", label="超时秒数"), + ], + }, + { + "key": "vision", + "title": "素材视觉识别", + "fields": [ + _field("default_route", "string", label="默认 Vision 路由名"), + _field("provider.provider_id", "string", label="Vision 提供方 ID(留空复用生图)"), + _field("provider.base_url", "string", label="Vision API 根地址(留空复用生图)"), + _field("provider.vision_endpoint", "string", label="Vision endpoint"), + _field("provider.model_id", "string", label="Vision 模型 ID"), + _field("provider.route_name", "string", label="Vision 路由名"), + _field( + "provider.api_key_env_var", + "string", + label="Vision API Key 环境变量(留空复用生图)", + ), + _field("provider.timeout_seconds", "number", label="Vision 超时秒数"), + _field("provider.enabled", "bool", label="启用 Vision 路由"), + ], + }, { "key": "storage", "title": "存储", @@ -106,6 +147,48 @@ class SettingsService: raise ApiError(ErrorCode.VALIDATION_FAILED, "config must be an object", {"field": "config"}) errors: list[dict[str, Any]] = [] warnings: list[dict[str, Any]] = [] + generation = config.get("generation", {}) + generation_provider: Mapping[str, Any] = {} + if isinstance(generation, Mapping): + provider = generation.get("provider", {}) + provider = provider if isinstance(provider, Mapping) else {} + generation_provider = provider + route_name = str(provider.get("route_name") or generation.get("default_model") or "").strip() + model_id = str(provider.get("model_id") or generation.get("default_model") or "").strip() + base_url = str(provider.get("base_url") or "").strip() + if any((route_name, model_id, base_url)): + for field, value in ( + ("generation.default_model", route_name), + ("generation.provider.model_id", model_id), + ("generation.provider.base_url", base_url), + ): + if not value: + errors.append({"field": field, "message": "configured generation provider field is required"}) + vision = config.get("vision", {}) + if isinstance(vision, Mapping): + provider = vision.get("provider", {}) + provider = provider if isinstance(provider, Mapping) else {} + route_name = str(provider.get("route_name") or vision.get("default_route") or "").strip() + model_id = str(provider.get("model_id") or "").strip() + base_url = str(provider.get("base_url") or generation_provider.get("base_url") or "").strip() + explicitly_configured = any( + str(provider.get(key) or "").strip() + for key in ( + "provider_id", + "base_url", + "model_id", + "api_key_env_var", + "api_key_secret_ref", + ) + ) + if explicitly_configured: + for field, value in ( + ("vision.default_route", route_name), + ("vision.provider.model_id", model_id), + ("vision.provider.base_url", base_url), + ): + if not value: + errors.append({"field": field, "message": "configured vision provider field is required"}) database = config.get("database", {}) if isinstance(database, Mapping): backend = str(database.get("backend", "auto")).lower() @@ -136,7 +219,7 @@ class SettingsService: if not isinstance(incoming, Mapping): raise ApiError(ErrorCode.VALIDATION_FAILED, "config must be an object", {"field": "config"}) before = _flatten(current) - after = _flatten(dict(incoming)) + after = _flatten(_merge_masked(current, incoming)) keys = sorted(set(before) | set(after)) changes = [] for key in keys: @@ -177,15 +260,29 @@ class SettingsService: validation = self.validate(candidate) if not validation["valid"]: raise ApiError(ErrorCode.VALIDATION_FAILED, "config validation failed", validation) - before = self._load_current_mapping() - self._record_snapshot(before, ctx, "before_save") incoming = candidate.get("config", candidate) if not isinstance(incoming, Mapping): raise ApiError(ErrorCode.VALIDATION_FAILED, "config must be an object", {"field": "config"}) - merged = _merge_masked(before, incoming) - self.config_service.config_path.parent.mkdir(parents=True, exist_ok=True) - self.config_service.config_path.write_text(_dump_yaml(merged), encoding="utf-8") - after = self._load_current_mapping() + with config_file_lock(self.config_service.config_path): + before = self._load_current_mapping() + before_file = load_config_file_payload(self.config_service.config_path) + merged_effective = _merge_masked(before, incoming) + conflicts = _runtime_override_conflicts(merged_effective, self.config_service.config_path) + if conflicts: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "these settings are managed by AstrBot; update them in the AstrBot plugin settings", + {"runtime_managed_fields": conflicts}, + ) + merged = _restore_runtime_managed_fields( + merged_effective, + before_file, + get_runtime_config_overrides() if is_default_config_path(self.config_service.config_path) else {}, + ) + _initialize_database_if_changed(before_file, merged) + self._record_snapshot(before_file, ctx, "before_save") + write_text_atomic(self.config_service.config_path, dump_yaml(merged)) + after = self._load_current_mapping() if self.audit_service: self.audit_service.record( ctx=ctx, @@ -279,11 +376,25 @@ class SettingsService: validation = self.validate({"config": config}) if not validation["valid"]: raise ApiError(ErrorCode.VALIDATION_FAILED, "snapshot config validation failed", validation) - before = self._load_current_mapping() - self._record_snapshot(before, ctx, "before_rollback") - self.config_service.config_path.parent.mkdir(parents=True, exist_ok=True) - self.config_service.config_path.write_text(_dump_yaml(config), encoding="utf-8") - after = self._load_current_mapping() + with config_file_lock(self.config_service.config_path): + before = self._load_current_mapping() + before_file = load_config_file_payload(self.config_service.config_path) + conflicts = _runtime_override_conflicts(config, self.config_service.config_path) + if conflicts: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "snapshot changes settings managed by AstrBot", + {"runtime_managed_fields": conflicts}, + ) + rollback_config = _restore_runtime_managed_fields( + config, + before_file, + get_runtime_config_overrides() if is_default_config_path(self.config_service.config_path) else {}, + ) + _initialize_database_if_changed(before_file, rollback_config) + self._record_snapshot(before_file, ctx, "before_rollback") + write_text_atomic(self.config_service.config_path, dump_yaml(rollback_config)) + after = self._load_current_mapping() self.audit_service.record( ctx=ctx, action="rollback_settings", @@ -318,10 +429,7 @@ class SettingsService: return json.loads(self.schema_path.read_text(encoding="utf-8")) def _load_current_mapping(self) -> dict[str, Any]: - path = self.config_service.config_path - if not path.exists(): - return {} - return _load_yaml_subset(path.read_text(encoding="utf-8")) + return load_config_payload(self.config_service.config_path) def _record_snapshot(self, config: Mapping[str, Any], ctx: RequestContext, reason: str) -> str | None: if not self.audit_service: @@ -427,10 +535,7 @@ def _mask_path_value(value: Any) -> Any: def _resolve_path(path: str | Path) -> Path: - resolved = Path(path) - if not resolved.is_absolute(): - resolved = REPO_ROOT / resolved - return resolved + return resolve_plugin_path(path) def _merge_masked(current: Mapping[str, Any], incoming: Mapping[str, Any]) -> dict[str, Any]: @@ -445,30 +550,86 @@ def _merge_masked(current: Mapping[str, Any], incoming: Mapping[str, Any]) -> di return result -def _dump_yaml(value: Mapping[str, Any], indent: int = 0) -> str: - lines: list[str] = [] - prefix = " " * indent +def _runtime_override_conflicts(incoming: Mapping[str, Any], config_path: Path) -> list[str]: + if not is_default_config_path(config_path): + return [] + overrides = _flatten(get_runtime_config_overrides()) + if not overrides: + return [] + candidate = _flatten(incoming) + return sorted(path for path, value in overrides.items() if path in candidate and candidate[path] != value) + + +def _restore_runtime_managed_fields( + candidate: Mapping[str, Any], + file_config: Mapping[str, Any], + runtime_overrides: Mapping[str, Any], +) -> dict[str, Any]: + result = _copy_mapping(candidate) + file_values = _flatten(file_config) + for path in _flatten(runtime_overrides): + if path in file_values: + _set_nested_value(result, path.split("."), file_values[path]) + else: + _delete_nested_value(result, path.split(".")) + return result + + +def _copy_mapping(value: Mapping[str, Any]) -> dict[str, Any]: + copied: dict[str, Any] = {} for key, child in value.items(): if isinstance(child, Mapping): - lines.append(f"{prefix}{key}:") - lines.append(_dump_yaml(child, indent + 2).rstrip()) + copied[str(key)] = _copy_mapping(child) elif isinstance(child, list): - lines.append(f"{prefix}{key}:") - for item in child: - lines.append(f"{prefix} - {_format_scalar(item)}") + copied[str(key)] = [ + _copy_mapping(item) if isinstance(item, Mapping) else item + for item in child + ] else: - lines.append(f"{prefix}{key}: {_format_scalar(child)}") - return "\n".join(lines) + "\n" + copied[str(key)] = child + return copied -def _format_scalar(value: Any) -> str: - if isinstance(value, bool): - return "true" if value else "false" - if value is None: - return "null" - if isinstance(value, (int, float)): - return str(value) - text = str(value) - if text == "" or any(char in text for char in [":", "#", "{", "}", "[", "]", ","]) or text.strip() != text: - return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"' - return text +def _set_nested_value(target: dict[str, Any], parts: list[str], value: Any) -> None: + cursor = target + for part in parts[:-1]: + child = cursor.get(part) + if not isinstance(child, dict): + child = {} + cursor[part] = child + cursor = child + if parts: + cursor[parts[-1]] = value + + +def _delete_nested_value(target: dict[str, Any], parts: list[str]) -> None: + if not parts: + return + cursor: dict[str, Any] = target + parents: list[tuple[dict[str, Any], str]] = [] + for part in parts[:-1]: + child = cursor.get(part) + if not isinstance(child, dict): + return + parents.append((cursor, part)) + cursor = child + cursor.pop(parts[-1], None) + for parent, key in reversed(parents): + child = parent.get(key) + if isinstance(child, dict) and not child: + parent.pop(key, None) + else: + break + + +def _initialize_database_if_changed(before: Mapping[str, Any], after: Mapping[str, Any]) -> None: + before_database = before.get("database") if isinstance(before.get("database"), Mapping) else {} + after_database = after.get("database") if isinstance(after.get("database"), Mapping) else {} + if dict(before_database) == dict(after_database): + return + Database(DatabaseSettings.from_mapping(after)).initialize() + + +# Compatibility alias for existing tests and services that imported the +# previous private serializer. New code should import core.config_writer. +_dump_yaml = dump_yaml diff --git a/backend/services/wardrobe_service.py b/backend/services/wardrobe_service.py index 11347f7..7533116 100644 --- a/backend/services/wardrobe_service.py +++ b/backend/services/wardrobe_service.py @@ -2,6 +2,7 @@ from __future__ import annotations +import sqlite3 from typing import Any from uuid import uuid4 @@ -31,7 +32,7 @@ class WardrobeService: self.audit_service = audit_service def import_material(self, profile_id: str, payload: dict[str, Any], ctx: RequestContext) -> WardrobeItem: - self._ensure_profile(profile_id) + self._ensure_profile(profile_id, ctx) material_id = str(payload.get("material_id") or "").strip() wardrobe_category = str(payload.get("wardrobe_category") or "").strip() if not material_id: @@ -45,18 +46,33 @@ class WardrobeService: material = self.material_repository.get_material(material_id) if material is None or material.recognition_status != "confirmed": raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "confirmed material not found", {"material_id": material_id}) - item = self.wardrobe_repository.create( - { - "wardrobe_item_id": payload.get("wardrobe_item_id") or new_wardrobe_item_id(), - "profile_id": profile_id, - "material_id": material_id, - "wardrobe_category": wardrobe_category, - "tags": payload.get("tags") or material.tags, - "season": payload.get("season"), - "style": payload.get("style"), - "is_favorite": payload.get("is_favorite", False), - } + duplicate = next( + ( + existing + for existing in self.wardrobe_repository.list_by_profile(profile_id, wardrobe_category) + if existing.material_id == material_id + ), + None, ) + if duplicate is not None: + raise _duplicate_wardrobe_item_error(profile_id, material_id, wardrobe_category, duplicate.wardrobe_item_id) + try: + item = self.wardrobe_repository.create( + { + "wardrobe_item_id": payload.get("wardrobe_item_id") or new_wardrobe_item_id(), + "profile_id": profile_id, + "material_id": material_id, + "wardrobe_category": wardrobe_category, + "tags": payload.get("tags") or material.tags, + "season": payload.get("season"), + "style": payload.get("style"), + "is_favorite": payload.get("is_favorite", False), + } + ) + except Exception as exc: + if not _is_unique_constraint_error(exc): + raise + raise _duplicate_wardrobe_item_error(profile_id, material_id, wardrobe_category) from None self.audit_service.record( ctx=ctx, action="add_wardrobe_item", @@ -66,12 +82,17 @@ class WardrobeService: ) return item - def list_items(self, profile_id: str, wardrobe_category: str | None = None) -> list[WardrobeItem]: - self._ensure_profile(profile_id) + def list_items( + self, + profile_id: str, + wardrobe_category: str | None, + ctx: RequestContext, + ) -> list[WardrobeItem]: + self._ensure_profile(profile_id, ctx) return self.wardrobe_repository.list_by_profile(profile_id, wardrobe_category) def delete_item(self, profile_id: str, wardrobe_item_id: str, ctx: RequestContext) -> WardrobeItem: - self._ensure_profile(profile_id) + self._ensure_profile(profile_id, ctx) before = self.wardrobe_repository.get(wardrobe_item_id) if before is None or before.profile_id != profile_id: raise ApiError( @@ -91,7 +112,7 @@ class WardrobeService: return deleted def match(self, profile_id: str, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: - self._ensure_profile(profile_id) + self._ensure_profile(profile_id, ctx) categories = _normalize_categories(payload.get("categories")) if not categories: categories = list(DEFAULT_WARDROBE_CATEGORIES) @@ -107,7 +128,7 @@ class WardrobeService: scored_candidates = [] for index, item in enumerate(candidates): material = self.material_repository.get_material(item.material_id) - if material is None: + if material is None or material.recognition_status != "confirmed": continue score, breakdown = _score_candidate(item, material, context) scored_candidates.append((score, -index, item, material, breakdown)) @@ -166,9 +187,9 @@ class WardrobeService: ) return result - def _ensure_profile(self, profile_id: str) -> None: + def _ensure_profile(self, profile_id: str, ctx: RequestContext) -> None: profile = self.profile_repository.get(profile_id) - if profile is None or profile.status == "deleted": + if profile is None or profile.status == "deleted" or profile.owner_user_id != ctx.actor_id: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "profile not found", {"profile_id": profile_id}) @@ -176,6 +197,28 @@ def new_wardrobe_item_id() -> str: return f"wardrobe_{uuid4().hex}" +def _duplicate_wardrobe_item_error( + profile_id: str, + material_id: str, + wardrobe_category: str, + wardrobe_item_id: str | None = None, +) -> ApiError: + details: dict[str, Any] = { + "profile_id": profile_id, + "material_id": material_id, + "wardrobe_category": wardrobe_category, + } + if wardrobe_item_id: + details["wardrobe_item_id"] = wardrobe_item_id + return ApiError(ErrorCode.VALIDATION_FAILED, "material already exists in wardrobe category", details) + + +def _is_unique_constraint_error(exc: Exception) -> bool: + if isinstance(exc, sqlite3.IntegrityError): + return True + return getattr(exc, "sqlstate", None) == "23505" or getattr(exc, "pgcode", None) == "23505" + + def _normalize_categories(value: Any) -> list[str]: if not isinstance(value, list): return [] diff --git a/backend/services/worker_service.py b/backend/services/worker_service.py index ad77943..fe11af8 100644 --- a/backend/services/worker_service.py +++ b/backend/services/worker_service.py @@ -8,7 +8,6 @@ from dataclasses import dataclass, field from datetime import datetime, timedelta, timezone from typing import Any -from backend.dto.common import ApiError from backend.dto.job_dto import GenerationTask from backend.services.queue_service import QueueService from core.identity import RequestContext @@ -186,27 +185,13 @@ class QueueWorker: for candidate in queued: if _retry_deferred(candidate): continue - try: - attempt = _int(candidate.metadata.get("worker_attempt"), 0) + 1 - return self.queue_service.update_task( - candidate.task_id, - { - "status": "running", - "progress": max(candidate.progress, 1), - "metadata": { - **candidate.metadata, - "worker_attempt": attempt, - "worker": { - "worker_id": self.worker_id, - "status": "running", - "claimed_at": _now(), - }, - }, - }, - ctx, - ) - except ApiError: - continue + claimed = self.queue_service.claim_queued_task( + candidate.task_id, + ctx, + worker_id=self.worker_id, + ) + if claimed is not None: + return claimed return None def _handle_failure(self, task: GenerationTask, exc: Exception, ctx: RequestContext) -> WorkerRunResult: diff --git a/backend/services/workflow_service.py b/backend/services/workflow_service.py index 6a73323..fefb65e 100644 --- a/backend/services/workflow_service.py +++ b/backend/services/workflow_service.py @@ -15,6 +15,7 @@ from backend.services.prompt_plan_schema_service import ( PROMPT_PLAN_SCHEMA_VERSION, normalize_prompt_plan, ) +from backend.services.queue_service import QueueService from core.audit_service import AuditService from core.event_bus import EventBus from core.fsm import node_transition, workflow_transition @@ -36,6 +37,7 @@ NODE_STATUSES = { "completed", "selected", "failed", + "cancelled", "skipped", "discarded", } @@ -76,26 +78,25 @@ class WorkflowService: "workflow display_name is required", {"field": "display_name"}, ) - workflow = self.workflow_repository.create_workflow( + status = payload.get("status", "draft") + self._validate_workflow_status(status) + workflow_id = payload.get("workflow_id") or new_workflow_id() + node_payloads = self._initial_node_payloads(workflow_id, workflow_type, payload) + workflow, nodes = self.workflow_repository.create_workflow_with_nodes( { - "workflow_id": payload.get("workflow_id") or new_workflow_id(), + "workflow_id": workflow_id, "profile_id": profile_id, "workflow_type": workflow_type, "display_name": display_name, "mode": payload.get("mode"), - "status": payload.get("status", "draft"), + "status": status, + "current_node_id": node_payloads[0]["node_id"] if node_payloads else None, "current_branch": payload.get("current_branch", "main"), "session_key": payload.get("session_key") or ctx.session_key, "metadata": payload.get("metadata") or {}, - } + }, + node_payloads, ) - nodes = self._create_initial_nodes(workflow, payload, ctx) - if nodes: - self.workflow_repository.update_workflow( - workflow.workflow_id, - {"current_node_id": nodes[0].node_id}, - ) - workflow = self.workflow_repository.get_workflow(workflow.workflow_id) or workflow self.audit_service.record( ctx=ctx, action="create_workflow", @@ -175,6 +176,101 @@ class WorkflowService: self._publish("workflow.updated", {"workflow_id": workflow_id, "profile_id": after.profile_id}) return after + def cancel_workflow( + self, + workflow_id: str, + ctx: RequestContext, + queue_service: QueueService, + ) -> ProfileWorkflow: + """Cancel a workflow and CAS-cancel its active tasks and nodes.""" + + while True: + before = self.get_workflow(workflow_id).workflow + if before.status == "cancelled": + after = before + break + self._validate_workflow_status_transition(before.status, "cancelled") + after = self.workflow_repository.update_workflow_if_status( + workflow_id, + {before.status}, + {"status": "cancelled"}, + ) + if after is not None: + self.audit_service.record( + ctx=ctx, + action="cancel_workflow", + target_type="profile_workflow", + target_id=workflow_id, + before_snapshot=before.to_dict(), + after_snapshot=after.to_dict(), + ) + self._publish( + "workflow.status_changed", + { + "workflow_id": workflow_id, + "profile_id": after.profile_id, + "before_status": before.status, + "after_status": after.status, + }, + ) + self._publish("workflow.updated", {"workflow_id": workflow_id, "profile_id": after.profile_id}) + break + + queue_service.cancel_workflow_jobs(workflow_id, ctx, reason="workflow cancelled") + for node in self.workflow_repository.list_nodes(workflow_id): + if node.status not in {"queued", "running"}: + continue + node_metadata = node.metadata if isinstance(node.metadata, dict) else {} + last_task_id = str(node_metadata.get("last_task_id") or "").strip() + if last_task_id: + try: + last_task = queue_service.get_job(last_task_id) + except ApiError as exc: + if exc.error_code != ErrorCode.RESOURCE_NOT_FOUND: + raise + else: + # A task that committed before workflow cancellation owns + # its terminal node update. Tasks still active were CAS- + # cancelled above and their nodes are cancelled here. + if last_task.status in {"completed", "succeeded"}: + continue + cancelled_node = self.workflow_repository.update_node_if_status( + node.node_id, + {node.status}, + { + "status": "cancelled", + "metadata": { + **node_metadata, + "workflow_cancellation": { + "workflow_id": workflow_id, + "requested_by": ctx.actor_id or "system", + }, + }, + }, + ) + if cancelled_node is None: + continue + self.audit_service.record( + ctx=ctx, + action="cancel_node", + target_type="workflow_node", + target_id=node.node_id, + before_snapshot=node.to_dict(), + after_snapshot=cancelled_node.to_dict(), + metadata={"source": "workflow.cancel"}, + ) + self._publish( + "workflow.node_status_changed", + { + "workflow_id": workflow_id, + "node_id": node.node_id, + "before_status": node.status, + "after_status": cancelled_node.status, + }, + ) + self._publish("workflow.node_updated", {"workflow_id": workflow_id, "node_id": node.node_id}) + return after + def create_branch( self, workflow_id: str, @@ -383,23 +479,41 @@ class WorkflowService: self._publish("workflow.node_updated", {"workflow_id": after.workflow_id, "node_id": node_id}) return after - def _create_initial_nodes( + def _initial_node_payloads( self, - workflow: ProfileWorkflow, + workflow_id: str, + workflow_type: str, payload: dict[str, Any], - ctx: RequestContext, - ) -> list[WorkflowNode]: + ) -> list[dict[str, Any]]: if payload.get("auto_create_nodes", True) is False: return [] - return [ - self.create_node( - workflow.workflow_id, - template, - ctx, - audit=False, + nodes: list[dict[str, Any]] = [] + for template in _initial_node_templates(workflow_type): + node_key = str(template.get("node_key") or "").strip() + title = str(template.get("title") or "").strip() + status = str(template.get("status") or "draft") + if not node_key or not title or status not in NODE_STATUSES: + raise RuntimeError(f"invalid initial node template for {workflow_type}") + nodes.append( + { + "node_id": template.get("node_id") or new_node_id(), + "workflow_id": workflow_id, + "node_key": node_key, + "title": title, + "description": template.get("description"), + "step_name": template.get("step_name"), + "node_type": template.get("node_type", "generation"), + "status": status, + "branch_name": template.get("branch_name", "main"), + "prompt": template.get("prompt"), + "negative_prompt": template.get("negative_prompt"), + "model_route": template.get("model_route"), + "selected_image_id": template.get("selected_image_id"), + "sort_order": template.get("sort_order", 0), + "metadata": template.get("metadata") or {}, + } ) - for template in _initial_node_templates(workflow.workflow_type) - ] + return nodes def _copy_branch_nodes( self, @@ -474,12 +588,7 @@ class WorkflowService: return workflow def _validate_workflow_status_transition(self, current: str, target: str) -> None: - if target not in WORKFLOW_STATUSES: - raise ApiError( - ErrorCode.VALIDATION_FAILED, - "unsupported workflow status", - {"field": "status", "allowed": sorted(WORKFLOW_STATUSES)}, - ) + self._validate_workflow_status(target) transition = workflow_transition(current, target) if not transition.allowed: raise ApiError( @@ -488,6 +597,14 @@ class WorkflowService: {"current": current, "target": target, "reason": transition.reason}, ) + def _validate_workflow_status(self, status: Any) -> None: + if not isinstance(status, str) or status not in WORKFLOW_STATUSES: + raise ApiError( + ErrorCode.VALIDATION_FAILED, + "unsupported workflow status", + {"field": "status", "allowed": sorted(WORKFLOW_STATUSES)}, + ) + def _validate_node_status_transition(self, current: str, target: str) -> None: if target not in NODE_STATUSES: raise ApiError( @@ -603,6 +720,14 @@ def locked_node_edit_error(node: WorkflowNode) -> ApiError: ) +def is_repeatable_single_image_node(node: WorkflowNode) -> bool: + return bool( + node.node_key == "virtual_single_image" + or node.node_type == "virtual_single_image" + or (isinstance(node.metadata, dict) and node.metadata.get("virtual") is True) + ) + + def _node_payload_changes(node: WorkflowNode, payload: dict[str, Any]) -> bool: comparable = { "title": node.title, diff --git a/config.yaml b/config.yaml index 1bc664c..798a507 100644 --- a/config.yaml +++ b/config.yaml @@ -11,7 +11,41 @@ features: api_discovery: true private_companion_integration: false +generation: + # default_model 是 ImageStudio 路由名;route_name 留空时复用它。 + default_model: "" + provider: + provider_id: imagestudio_default + display_name: ImageStudio default provider + base_url: "" + image_endpoint: /v1/images/generations + model_id: "" + route_name: "" + api_key_env_var: "" + timeout_seconds: 180 + priority: 10 + enabled: true + +vision: + # 素材识别路由;provider 中留空的连接字段会复用 generation.provider。 + # 若地址、密钥或超时不同且 provider_id 留空,会自动派生独立 Vision provider ID,避免覆盖生图配置。 + # Vision 模型必须单独填写,不能假定生图模型具备视觉理解能力。 + default_route: material_vlm + provider: + provider_id: "" + display_name: "" + base_url: "" + vision_endpoint: /v1/chat/completions + model_id: "" + route_name: material_vlm + api_key_env_var: "" + timeout_seconds: 180 + priority: 10 + enabled: true + storage: + # 这里使用逻辑 data/... 路径;AstrBot 运行时映射到 + # data/plugin_data/astrbot_plugin_imagestudio/...,本地开发仍映射到仓库 data/。 db_path: data/db/imagestudio.db images_path: data/images thumbnails_path: data/thumbnails diff --git a/core/config_service.py b/core/config_service.py index d030c36..6d4217f 100644 --- a/core/config_service.py +++ b/core/config_service.py @@ -6,7 +6,8 @@ from dataclasses import dataclass from pathlib import Path from typing import Any -from database.db_helper import REPO_ROOT, load_config_payload +from core.runtime_paths import resolve_config_path +from database.db_helper import load_config_payload @dataclass(frozen=True) @@ -75,7 +76,4 @@ class ConfigService: def _resolve_path(path: str | Path) -> Path: - resolved = Path(path) - if not resolved.is_absolute(): - resolved = REPO_ROOT / resolved - return resolved + return resolve_config_path(path) diff --git a/core/config_writer.py b/core/config_writer.py new file mode 100644 index 0000000..cd73659 --- /dev/null +++ b/core/config_writer.py @@ -0,0 +1,79 @@ +"""Shared serialization and atomic-write helpers for the runtime config.""" + +from __future__ import annotations + +import json +import threading +from collections.abc import Mapping +from pathlib import Path +from typing import Any +from uuid import uuid4 + + +_LOCKS_GUARD = threading.Lock() +_PATH_LOCKS: dict[str, threading.RLock] = {} + + +def config_file_lock(path: str | Path) -> threading.RLock: + """Serialize read-modify-write operations for one config path.""" + + # Return the native lock context manager directly. A generator-based + # contextmanager mutates an escaping exception's ``__traceback__``; + # ImageStudio's frozen ApiError intentionally rejects that mutation. + return _lock_for_path(Path(path)) + + +def write_text_atomic(path: str | Path, content: str) -> None: + """Replace a UTF-8 text file atomically in its destination directory.""" + + destination = Path(path) + with config_file_lock(destination): + destination.parent.mkdir(parents=True, exist_ok=True) + temporary = destination.with_name(f".{destination.name}.{uuid4().hex}.tmp") + try: + temporary.write_text(content, encoding="utf-8") + temporary.replace(destination) + finally: + if temporary.exists(): + temporary.unlink() + + +def dump_yaml(value: Mapping[str, Any], indent: int = 0) -> str: + """Serialize the simple mapping/list/scalar YAML subset used by ImageStudio.""" + + lines: list[str] = [] + prefix = " " * indent + for key, child in value.items(): + if isinstance(child, Mapping): + lines.append(f"{prefix}{key}:") + lines.append(dump_yaml(child, indent + 2).rstrip()) + elif isinstance(child, list): + lines.append(f"{prefix}{key}:") + for item in child: + lines.append(f"{prefix} - {_format_scalar(item)}") + else: + lines.append(f"{prefix}{key}: {_format_scalar(child)}") + return "\n".join(lines) + "\n" + + +def _lock_for_path(path: Path) -> threading.RLock: + try: + key = str(path.resolve()) + except OSError: + key = str(path.absolute()) + with _LOCKS_GUARD: + lock = _PATH_LOCKS.get(key) + if lock is None: + lock = threading.RLock() + _PATH_LOCKS[key] = lock + return lock + + +def _format_scalar(value: Any) -> str: + if isinstance(value, bool): + return "true" if value else "false" + if value is None: + return "null" + if isinstance(value, (int, float)): + return str(value) + return json.dumps(str(value), ensure_ascii=False) diff --git a/core/fsm.py b/core/fsm.py index 7fce626..0eb6bc5 100644 --- a/core/fsm.py +++ b/core/fsm.py @@ -34,9 +34,11 @@ TASK_TRANSITIONS: dict[str, set[str]] = { "running": {"completed", "succeeded", "failed", "cancelled"}, "completed": set(), "succeeded": set(), - "failed": {"queued", "cancelled", "dead_letter"}, - "cancelled": {"queued"}, - "dead_letter": {"queued"}, + "failed": {"queued", "cancelled", "dead_letter", "retrying"}, + "cancelled": {"queued", "retrying"}, + "dead_letter": {"queued", "retrying"}, + "retrying": {"failed", "cancelled", "dead_letter", "superseded"}, + "superseded": set(), } diff --git a/core/generation_errors.py b/core/generation_errors.py index 9d29844..72ce014 100644 --- a/core/generation_errors.py +++ b/core/generation_errors.py @@ -2,6 +2,7 @@ from __future__ import annotations +import re from typing import Any from engines.image_provider import ImageProviderError @@ -83,6 +84,13 @@ def _safe_details(details: dict[str, Any]) -> dict[str, Any]: def _safe_message(value: str, *, limit: int = 240) -> str: text = " ".join(str(value or "").split()) + text = re.sub(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+", "Bearer [REDACTED]", text) + text = re.sub( + r'''(?ix)(["']?(?:api[_-]?key|apikey|authorization|token|password|secret)["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^"'\s,;}]+''', + r"\1[REDACTED]", + text, + ) + text = re.sub(r"\bsk-[A-Za-z0-9_-]{8,}\b", "[REDACTED]", text) return text[:limit] if text else "image provider failed" diff --git a/core/image_formats.py b/core/image_formats.py new file mode 100644 index 0000000..05349a3 --- /dev/null +++ b/core/image_formats.py @@ -0,0 +1,52 @@ +"""Supported raster image signature, MIME, and extension mappings.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + + +@dataclass(frozen=True) +class ImageFormat: + mime_type: str + extension: str + accepted_extensions: frozenset[str] + + +PNG = ImageFormat("image/png", ".png", frozenset({".png"})) +JPEG = ImageFormat("image/jpeg", ".jpg", frozenset({".jpg", ".jpeg"})) +GIF = ImageFormat("image/gif", ".gif", frozenset({".gif"})) +WEBP = ImageFormat("image/webp", ".webp", frozenset({".webp"})) + +SUPPORTED_IMAGE_FORMATS = (PNG, JPEG, GIF, WEBP) +SUPPORTED_IMAGE_MIME_TYPES = frozenset(item.mime_type for item in SUPPORTED_IMAGE_FORMATS) +SUPPORTED_IMAGE_EXTENSIONS = frozenset( + extension for item in SUPPORTED_IMAGE_FORMATS for extension in item.accepted_extensions +) +IMAGE_EXTENSIONS_BY_MIME = { + item.mime_type: item.accepted_extensions for item in SUPPORTED_IMAGE_FORMATS +} + + +def detect_image_format(content: bytes) -> ImageFormat | None: + """Return the supported image format identified by its file signature.""" + + if content.startswith(b"\x89PNG\r\n\x1a\n"): + return PNG + if content.startswith(b"\xff\xd8\xff"): + return JPEG + if content.startswith((b"GIF87a", b"GIF89a")): + return GIF + if len(content) >= 12 and content.startswith(b"RIFF") and content[8:12] == b"WEBP": + return WEBP + return None + + +def detect_file_image_format(path: Path) -> ImageFormat | None: + """Inspect only the bytes required to identify a supported image file.""" + + try: + with path.open("rb") as handle: + return detect_image_format(handle.read(12)) + except OSError: + return None diff --git a/core/media_proxy.py b/core/media_proxy.py index 6da15b6..9c5eb0a 100644 --- a/core/media_proxy.py +++ b/core/media_proxy.py @@ -9,16 +9,19 @@ import hmac import json import mimetypes import os +import secrets import time from pathlib import Path from typing import Any from backend.dto.common import ApiError, ErrorCode +from core.image_formats import detect_file_image_format from core.storage import VfsStorage DEFAULT_MEDIA_TTL_SECONDS = 300 -MEDIA_FETCH_PATH = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch" +MEDIA_FETCH_PATH = "/api/plug/astrbot_plugin_imagestudio/media/fetch" +_PROCESS_MEDIA_SIGNING_SECRET = os.environ.get("IMAGESTUDIO_MEDIA_SIGNING_SECRET") or secrets.token_urlsafe(48) class MediaProxy: @@ -30,10 +33,10 @@ class MediaProxy: ttl_seconds: int = DEFAULT_MEDIA_TTL_SECONDS, ): self.storage = storage or VfsStorage() - self.signing_secret = signing_secret or os.environ.get( - "IMAGESTUDIO_MEDIA_SIGNING_SECRET", - "imagestudio-dev-media-signing-secret", - ) + # A process-local random key is safer than a public source-code default. + # Operators can set IMAGESTUDIO_MEDIA_SIGNING_SECRET when tokens must + # remain valid across AstrBot process restarts. + self.signing_secret = signing_secret or _PROCESS_MEDIA_SIGNING_SECRET self.ttl_seconds = ttl_seconds def sign(self, uri: str) -> dict[str, Any]: @@ -63,6 +66,11 @@ class MediaProxy: "body_base64": _b64encode(path.read_bytes()), } + def resolve_file(self, token: str) -> tuple[Path, dict[str, Any]]: + """Resolve a signed token for host-native streaming/file responses.""" + + return self._resolve_token(token) + def _resolve_token(self, token: str) -> tuple[Path, dict[str, Any]]: payload = self._decode(token) uri = str(payload.get("uri") or "") @@ -110,6 +118,9 @@ class MediaProxy: def _guess_content_type(path: Path) -> str: + image_format = detect_file_image_format(path) + if image_format is not None: + return image_format.mime_type return mimetypes.guess_type(path.name)[0] or "application/octet-stream" diff --git a/core/remote_fetch.py b/core/remote_fetch.py new file mode 100644 index 0000000..51f4b84 --- /dev/null +++ b/core/remote_fetch.py @@ -0,0 +1,179 @@ +"""Bounded HTTP helpers for provider-controlled remote responses.""" + +from __future__ import annotations + +import ipaddress +import socket +import urllib.request +from collections.abc import Iterable +from typing import Any +from urllib.parse import urlsplit + + +class RemoteFetchError(ValueError): + """Raised when a remote URL or response violates the fetch policy.""" + + +def read_http_response_limited( + request: str | urllib.request.Request, + *, + timeout_seconds: int, + max_bytes: int, + allow_private: bool = False, + allowed_private_hosts: Iterable[str] = (), + same_origin_redirects_only: bool = False, +) -> bytes: + """Fetch an HTTP(S) response while validating redirects and size.""" + + if max_bytes <= 0: + raise ValueError("max_bytes must be positive") + url = request.full_url if isinstance(request, urllib.request.Request) else str(request) + allowed_hosts = frozenset(_normalize_host(host) for host in allowed_private_hosts if _normalize_host(host)) + validate_http_url(url, allow_private=allow_private, allowed_private_hosts=allowed_hosts) + opener = urllib.request.build_opener( + _ValidatedRedirectHandler( + allow_private=allow_private, + allowed_private_hosts=allowed_hosts, + same_origin_only=same_origin_redirects_only, + ) + ) + with opener.open(request, timeout=timeout_seconds) as response: + declared_size = _content_length(response) + if declared_size is not None and declared_size > max_bytes: + raise RemoteFetchError(f"remote response exceeds {max_bytes} bytes") + body = response.read(max_bytes + 1) + if len(body) > max_bytes: + raise RemoteFetchError(f"remote response exceeds {max_bytes} bytes") + return body + + +def validate_http_url( + url: str, + *, + allow_private: bool = False, + allowed_private_hosts: Iterable[str] = (), +) -> None: + """Reject non-HTTP, credential-bearing and unsafe private-network URLs.""" + + try: + parsed = urlsplit(str(url or "").strip()) + host = _normalize_host(parsed.hostname) + port = parsed.port or (443 if parsed.scheme.lower() == "https" else 80) + except ValueError as exc: + raise RemoteFetchError("remote URL is malformed") from exc + if parsed.scheme.lower() not in {"http", "https"}: + raise RemoteFetchError("remote URL must use http or https") + if parsed.username is not None or parsed.password is not None: + raise RemoteFetchError("remote URL must not include credentials") + if not host: + raise RemoteFetchError("remote URL must include a hostname") + allowed_hosts = {_normalize_host(item) for item in allowed_private_hosts} + if allow_private or host in allowed_hosts: + return + for address in _resolve_addresses(host, port): + if _is_unsafe_address(address): + raise RemoteFetchError("remote URL resolves to a private or local network address") + + +def url_hostname(url: str | None) -> str | None: + """Return a normalized hostname from an HTTP(S) URL when present.""" + + try: + parsed = urlsplit(str(url or "").strip()) + except ValueError: + return None + if parsed.scheme.lower() not in {"http", "https"}: + return None + return _normalize_host(parsed.hostname) or None + + +class _ValidatedRedirectHandler(urllib.request.HTTPRedirectHandler): + def __init__( + self, + *, + allow_private: bool, + allowed_private_hosts: frozenset[str], + same_origin_only: bool, + ): + super().__init__() + self.allow_private = allow_private + self.allowed_private_hosts = allowed_private_hosts + self.same_origin_only = same_origin_only + + def redirect_request( + self, + req: urllib.request.Request, + fp: Any, + code: int, + msg: str, + headers: Any, + newurl: str, + ) -> urllib.request.Request | None: + validate_http_url( + newurl, + allow_private=self.allow_private, + allowed_private_hosts=self.allowed_private_hosts, + ) + old_origin = _origin(req.full_url) + new_origin = _origin(newurl) + if old_origin[0] == "https" and new_origin[0] != "https": + raise RemoteFetchError("HTTPS redirects must not downgrade to HTTP") + if self.same_origin_only and old_origin != new_origin: + raise RemoteFetchError("provider endpoint redirected to a different origin") + redirected = super().redirect_request(req, fp, code, msg, headers, newurl) + if redirected is not None and old_origin != new_origin: + redirected.remove_header("Authorization") + return redirected + + +def _resolve_addresses(host: str, port: int) -> set[ipaddress.IPv4Address | ipaddress.IPv6Address]: + try: + literal = ipaddress.ip_address(host) + except ValueError: + literal = None + if literal is not None: + return {literal} + try: + rows = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM) + except OSError as exc: + raise RemoteFetchError("remote hostname could not be resolved") from exc + addresses: set[ipaddress.IPv4Address | ipaddress.IPv6Address] = set() + for row in rows: + try: + addresses.add(ipaddress.ip_address(row[4][0].split("%", 1)[0])) + except (ValueError, IndexError): + continue + if not addresses: + raise RemoteFetchError("remote hostname did not resolve to an IP address") + return addresses + + +def _is_unsafe_address(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool: + # is_global also excludes shared/CGNAT (100.64.0.0/10), documentation, + # loopback, link-local, reserved and unspecified ranges. + return not address.is_global or address.is_multicast + + +def _content_length(response: Any) -> int | None: + value = response.headers.get("Content-Length") if getattr(response, "headers", None) else None + if value in (None, ""): + return None + try: + return int(value) + except (TypeError, ValueError): + return None + + +def _normalize_host(value: str | None) -> str: + return str(value or "").strip().rstrip(".").lower() + + +def _origin(url: str) -> tuple[str, str, int]: + try: + parsed = urlsplit(url) + scheme = parsed.scheme.lower() + host = _normalize_host(parsed.hostname) + port = parsed.port or (443 if scheme == "https" else 80) + except ValueError as exc: + raise RemoteFetchError("redirect URL is malformed") from exc + return scheme, host, port diff --git a/core/runtime_paths.py b/core/runtime_paths.py new file mode 100644 index 0000000..c106fbc --- /dev/null +++ b/core/runtime_paths.py @@ -0,0 +1,112 @@ +"""Resolve writable ImageStudio paths for local and AstrBot runtimes.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Callable + + +PLUGIN_NAME = "astrbot_plugin_imagestudio" +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def get_astrbot_runtime_data_root() -> Path | None: + """Return this plugin's AstrBot-managed data directory when available.""" + + getter = _astrbot_plugin_data_path_getter() + if getter is None: + return None + try: + root = getter() + except Exception: + return None + if root is None or not str(root).strip(): + return None + return Path(root).expanduser() / PLUGIN_NAME + + +def get_runtime_data_root() -> Path: + """Return the root used for mutable data in the current runtime.""" + + return get_astrbot_runtime_data_root() or (REPO_ROOT / "data") + + +def resolve_data_path(path: str | Path) -> Path: + """Resolve a configured mutable-data path without changing absolute paths. + + The repository configuration historically uses ``data/...``. Under + AstrBot, the leading ``data`` component is replaced by AstrBot's + plugin-specific writable directory. Local development keeps the existing + ``REPO_ROOT/data/...`` layout. + """ + + resolved = Path(path).expanduser() + if resolved.is_absolute(): + return resolved + + astrbot_root = get_astrbot_runtime_data_root() + if astrbot_root is None: + return REPO_ROOT / resolved + + parts = resolved.parts + if parts and parts[0].lower() == "data": + resolved = Path(*parts[1:]) if len(parts) > 1 else Path() + return astrbot_root / resolved + + +def get_default_config_path() -> Path: + """Return the writable default configuration path for this runtime.""" + + astrbot_root = get_astrbot_runtime_data_root() + if astrbot_root is not None: + return astrbot_root / "config.yaml" + return REPO_ROOT / "config.yaml" + + +def resolve_config_path(path: str | Path = "config.yaml") -> Path: + """Resolve default config to writable storage while preserving explicit paths.""" + + resolved = Path(path).expanduser() + if resolved.is_absolute(): + return resolved + if _is_default_config_reference(resolved): + return get_default_config_path() + return REPO_ROOT / resolved + + +def is_default_config_path(path: str | Path) -> bool: + """Whether a resolved path is the runtime's default writable config.""" + + return _same_path(Path(path), get_default_config_path()) + + +def get_packaged_config_path() -> Path: + """Return the read-only configuration defaults shipped with the plugin.""" + + return REPO_ROOT / "config.yaml" + + +def resolve_plugin_path(path: str | Path) -> Path: + """Resolve a plugin resource path relative to the installed package.""" + + resolved = Path(path).expanduser() + return resolved if resolved.is_absolute() else REPO_ROOT / resolved + + +def _astrbot_plugin_data_path_getter() -> Callable[[], str | Path] | None: + try: + from astrbot.core.utils.astrbot_path import get_astrbot_plugin_data_path + except Exception: + return None + return get_astrbot_plugin_data_path + + +def _is_default_config_reference(path: Path) -> bool: + return path == Path("config.yaml") + + +def _same_path(left: Path, right: Path) -> bool: + try: + return left.resolve() == right.resolve() + except OSError: + return left.absolute() == right.absolute() diff --git a/core/security.py b/core/security.py index 3e67984..4750dbd 100644 --- a/core/security.py +++ b/core/security.py @@ -28,5 +28,10 @@ def require_write(ctx: RequestContext) -> None: require_permission(ctx, "can_write") +def require_task_retry(ctx: RequestContext) -> None: + require_write(ctx) + require_permission(ctx, "can_retry_tasks") + + def require_config_manager(ctx: RequestContext) -> None: require_permission(ctx, "can_manage_config") diff --git a/core/storage.py b/core/storage.py index 0381f90..bbd91a0 100644 --- a/core/storage.py +++ b/core/storage.py @@ -10,7 +10,7 @@ from typing import Any from backend.dto.common import ApiError, ErrorCode from core.config_service import ConfigService, ImageStudioConfig -from database.db_helper import REPO_ROOT +from core.runtime_paths import resolve_data_path @dataclass(frozen=True) @@ -71,7 +71,7 @@ class VfsStorage: items: list[dict[str, Any]] = [] total = 0 for root_name in selected_roots: - root_path = _resolve_data_path(roots[root_name]).resolve() + root_path = resolve_data_path(roots[root_name]).resolve() if not root_path.exists(): continue for path in sorted(root_path.rglob("*")): @@ -102,7 +102,7 @@ class VfsStorage: root_path = self._root_paths().get(root) if root_path is None: raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"uri": uri, "root": root}) - resolved_root = _resolve_data_path(root_path).resolve() + resolved_root = resolve_data_path(root_path).resolve() resolved_path = (resolved_root / relative).resolve() if resolved_path != resolved_root and resolved_root not in resolved_path.parents: raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri}) @@ -129,7 +129,7 @@ class VfsStorage: return root, relative_path def _entry(self, root: str, path: str) -> VfsEntry: - resolved = _resolve_data_path(path) + resolved = resolve_data_path(path) return VfsEntry( root=root, uri_prefix=f"storage://{root}/", @@ -154,13 +154,6 @@ def _storage_roots(config: ImageStudioConfig) -> dict[str, str]: } -def _resolve_data_path(path: str) -> Path: - resolved = Path(path) - if not resolved.is_absolute(): - resolved = REPO_ROOT / resolved - return resolved - - def _directory_size(path: Path) -> int: if not path.exists(): return 0 diff --git a/database/db_helper.py b/database/db_helper.py index 9b67a1f..22099d7 100644 --- a/database/db_helper.py +++ b/database/db_helper.py @@ -6,14 +6,21 @@ configuration explicitly enables it, or when `backend: postgresql` is set. from __future__ import annotations +import json import os import sqlite3 from dataclasses import dataclass from pathlib import Path from typing import Any, Iterable, Mapping +from core.runtime_paths import ( + REPO_ROOT, + get_packaged_config_path, + is_default_config_path, + resolve_config_path, + resolve_data_path, +) -REPO_ROOT = Path(__file__).resolve().parents[1] _RUNTIME_CONFIG_OVERRIDES: dict[str, Any] = {} @@ -28,15 +35,27 @@ def get_runtime_config_overrides() -> dict[str, Any]: def load_config_payload(config_path: str | Path = "config.yaml") -> dict[str, Any]: - path = Path(config_path) - if not path.is_absolute(): - path = REPO_ROOT / path - payload = _load_yaml_subset(path.read_text(encoding="utf-8")) if path.exists() else {} + path = resolve_config_path(config_path) + payload = load_config_file_payload(path) if _should_apply_runtime_overrides(path): return _merge_mappings(payload, _RUNTIME_CONFIG_OVERRIDES) return payload +def load_config_file_payload(config_path: str | Path = "config.yaml") -> dict[str, Any]: + """Load packaged and writable YAML without applying in-process overrides.""" + + path = resolve_config_path(config_path) + payload: dict[str, Any] = {} + if _should_apply_runtime_overrides(path): + packaged_path = get_packaged_config_path() + if not _same_path(path, packaged_path) and packaged_path.exists(): + payload = _load_yaml_subset(packaged_path.read_text(encoding="utf-8")) + if path.exists(): + payload = _merge_mappings(payload, _load_yaml_subset(path.read_text(encoding="utf-8"))) + return payload + + @dataclass(frozen=True) class SqliteSettings: path: str = "data/db/imagestudio.db" @@ -116,6 +135,7 @@ class Database: db_path.parent.mkdir(parents=True, exist_ok=True) conn = sqlite3.connect(db_path) conn.row_factory = sqlite3.Row + conn.execute("PRAGMA foreign_keys = ON") return conn return self._connect_postgresql() @@ -137,10 +157,7 @@ class Database: conn.close() def _resolve_sqlite_path(self) -> Path: - db_path = Path(self.settings.sqlite.path) - if not db_path.is_absolute(): - db_path = REPO_ROOT / db_path - return db_path + return resolve_data_path(self.settings.sqlite.path) def _connect_postgresql(self): try: @@ -255,10 +272,14 @@ def _as_bool(value: Any) -> bool: def _should_apply_runtime_overrides(path: Path) -> bool: + return is_default_config_path(path) + + +def _same_path(left: Path, right: Path) -> bool: try: - return path.resolve() == (REPO_ROOT / "config.yaml").resolve() + return left.resolve() == right.resolve() except OSError: - return path.absolute() == (REPO_ROOT / "config.yaml").absolute() + return left.absolute() == right.absolute() def _copy_plain_mapping(value: Mapping[str, Any]) -> dict[str, Any]: @@ -300,7 +321,7 @@ def _load_yaml_subset(text: str) -> dict[str, Any]: last_key_by_indent: dict[int, str] = {} for raw_line in text.splitlines(): - line = raw_line.split("#", 1)[0].rstrip() + line = _strip_yaml_comment(raw_line).rstrip() if not line.strip(): continue indent = len(line) - len(line.lstrip(" ")) @@ -337,8 +358,13 @@ def _load_yaml_subset(text: str) -> dict[str, Any]: def _parse_scalar(value: str) -> Any: - if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}: - return value[1:-1] + if len(value) >= 2 and value[0] == value[-1] == '"': + try: + return json.loads(value) + except json.JSONDecodeError: + return value[1:-1] + if len(value) >= 2 and value[0] == value[-1] == "'": + return value[1:-1].replace("''", "'") lowered = value.lower() if lowered == "true": return True @@ -350,3 +376,30 @@ def _parse_scalar(value: str) -> Any: return int(value) except ValueError: return os.path.expandvars(value) + + +def _strip_yaml_comment(line: str) -> str: + quote: str | None = None + escaped = False + index = 0 + while index < len(line): + char = line[index] + if quote == '"': + if escaped: + escaped = False + elif char == "\\": + escaped = True + elif char == quote: + quote = None + elif quote == "'": + if char == quote: + if index + 1 < len(line) and line[index + 1] == quote: + index += 1 + else: + quote = None + elif char in {"'", '"'}: + quote = char + elif char == "#" and (index == 0 or line[index - 1].isspace()): + return line[:index] + index += 1 + return line diff --git a/database/repositories/image_repository.py b/database/repositories/image_repository.py index 2fcf631..374eda8 100644 --- a/database/repositories/image_repository.py +++ b/database/repositories/image_repository.py @@ -138,6 +138,50 @@ class ImageRepository: conn.close() return [_row_to_image(row) for row in rows] + def list_images( + self, + *, + profile_id: str | None = None, + workflow_id: str | None = None, + include_archived: bool = True, + page: int = 1, + page_size: int = 60, + ) -> tuple[list[GenerationImage], int]: + placeholder = self.placeholder + clauses: list[str] = [] + params: list[Any] = [] + if profile_id: + clauses.append(f"profile_id = {placeholder}") + params.append(profile_id) + if workflow_id: + clauses.append(f"workflow_id = {placeholder}") + params.append(workflow_id) + if not include_archived: + clauses.append("is_archived = 0") + where_clause = f"WHERE {' AND '.join(clauses)}" if clauses else "" + normalized_page = max(page, 1) + normalized_page_size = min(max(page_size, 1), 100) + offset = (normalized_page - 1) * normalized_page_size + conn = self.database.connect() + try: + total_row = conn.execute( + f"SELECT COUNT(*) AS total FROM generation_images {where_clause}", + tuple(params), + ).fetchone() + rows = conn.execute( + f""" + SELECT {IMAGE_COLUMNS} + FROM generation_images + {where_clause} + ORDER BY created_at DESC, image_id DESC + LIMIT {placeholder} OFFSET {placeholder} + """, + tuple(params + [normalized_page_size, offset]), + ).fetchall() + finally: + conn.close() + return [_row_to_image(row) for row in rows], int(total_row["total"] if total_row else 0) + def update(self, image_id: str, payload: dict[str, Any]) -> GenerationImage | None: allowed = { "thumbnail_uri", diff --git a/database/repositories/job_repository.py b/database/repositories/job_repository.py index 0b1495f..83c6d20 100644 --- a/database/repositories/job_repository.py +++ b/database/repositories/job_repository.py @@ -157,36 +157,8 @@ class JobRepository: return [_row_to_task(row) for row in rows], int(total_row["total"] if total_row else 0) def update(self, task_id: str, payload: dict[str, Any]) -> GenerationTask | None: - allowed = { - "status", - "model_route", - "progress", - "request", - "result", - "error_message", - "metadata", - } - assignments: list[str] = [] - params: list[Any] = [] placeholder = self.placeholder - for key in allowed: - if key not in payload: - continue - column = key - value = payload[key] - if key == "request": - column = "request_json" - value = _json_or_none(value) - elif key == "result": - column = "result_json" - value = _json_or_none(value) - elif key == "metadata": - column = "metadata_json" - value = _json_or_none(value) - elif key == "progress": - value = int(value) - assignments.append(f"{column} = {placeholder}") - params.append(value) + assignments, params = _update_assignments(payload, placeholder) if not assignments: return self.get(task_id) assignments.append("updated_at = CURRENT_TIMESTAMP") @@ -206,6 +178,109 @@ class JobRepository: conn.close() return self.get(task_id) + def update_if_status( + self, + task_id: str, + expected_statuses: set[str] | tuple[str, ...] | list[str], + payload: dict[str, Any], + ) -> GenerationTask | None: + """Update a task only while it is still in an expected state. + + The status predicate and mutation run in one SQL statement. This is the + compare-and-set primitive used by retry orchestration and queue workers + to prevent two callers from claiming the same task. + """ + + normalized_statuses = tuple( + sorted({str(status).strip() for status in expected_statuses if str(status).strip()}) + ) + if not normalized_statuses: + return None + placeholder = self.placeholder + assignments, params = _update_assignments(payload, placeholder) + if not assignments: + task = self.get(task_id) + return task if task and task.status in normalized_statuses else None + assignments.append("updated_at = CURRENT_TIMESTAMP") + status_placeholders = ", ".join(placeholder for _ in normalized_statuses) + params.extend([task_id, *normalized_statuses]) + conn = self.database.connect() + try: + cursor = conn.execute( + f""" + UPDATE generation_tasks + SET {", ".join(assignments)} + WHERE task_id = {placeholder} + AND status IN ({status_placeholders}) + """, + tuple(params), + ) + changed = int(cursor.rowcount or 0) > 0 + conn.commit() + finally: + conn.close() + return self.get(task_id) if changed else None + + def update_if_status_unless_workflow_cancelled( + self, + task_id: str, + expected_statuses: set[str] | tuple[str, ...] | list[str], + payload: dict[str, Any], + ) -> GenerationTask | None: + """CAS-update a task while its owning workflow is not cancelled.""" + + normalized_statuses = tuple( + sorted({str(status).strip() for status in expected_statuses if str(status).strip()}) + ) + if not normalized_statuses: + return None + placeholder = self.placeholder + assignments, params = _update_assignments(payload, placeholder) + if not assignments: + task = self.get(task_id) + if task is None or task.status not in normalized_statuses: + return None + if task.workflow_id: + conn = self.database.connect() + try: + row = conn.execute( + f"SELECT status FROM profile_workflows WHERE workflow_id = {placeholder}", + (task.workflow_id,), + ).fetchone() + finally: + conn.close() + if row is None or str(row["status"]) == "cancelled": + return None + return task + assignments.append("updated_at = CURRENT_TIMESTAMP") + status_placeholders = ", ".join(placeholder for _ in normalized_statuses) + params.extend([task_id, *normalized_statuses, "cancelled"]) + conn = self.database.connect() + try: + cursor = conn.execute( + f""" + UPDATE generation_tasks + SET {", ".join(assignments)} + WHERE task_id = {placeholder} + AND status IN ({status_placeholders}) + AND ( + workflow_id IS NULL + OR EXISTS ( + SELECT 1 + FROM profile_workflows + WHERE profile_workflows.workflow_id = generation_tasks.workflow_id + AND profile_workflows.status <> {placeholder} + ) + ) + """, + tuple(params), + ) + changed = int(cursor.rowcount or 0) > 0 + conn.commit() + finally: + conn.close() + return self.get(task_id) if changed else None + def count_by_status(self) -> dict[str, int]: conn = self.database.connect() try: @@ -264,6 +339,39 @@ def _json_or_none(value: Any | None) -> str | None: return json.dumps(value, ensure_ascii=False, sort_keys=True) +def _update_assignments(payload: dict[str, Any], placeholder: str) -> tuple[list[str], list[Any]]: + allowed = { + "status", + "model_route", + "progress", + "request", + "result", + "error_message", + "metadata", + } + assignments: list[str] = [] + params: list[Any] = [] + for key in allowed: + if key not in payload: + continue + column = key + value = payload[key] + if key == "request": + column = "request_json" + value = _json_or_none(value) + elif key == "result": + column = "result_json" + value = _json_or_none(value) + elif key == "metadata": + column = "metadata_json" + value = _json_or_none(value) + elif key == "progress": + value = int(value) + assignments.append(f"{column} = {placeholder}") + params.append(value) + return assignments, params + + def _limit(value: int) -> int: try: limit = int(value) diff --git a/database/repositories/profile_repository.py b/database/repositories/profile_repository.py index 5650250..d1fdfeb 100644 --- a/database/repositories/profile_repository.py +++ b/database/repositories/profile_repository.py @@ -29,6 +29,26 @@ PROFILE_COLUMNS = """ updated_at """ +PROFILE_GENERATION_KIND_COLUMN = """ + CASE + WHEN EXISTS ( + SELECT 1 + FROM profile_workflows AS detailed_workflow + WHERE detailed_workflow.profile_id = character_profiles.profile_id + AND detailed_workflow.workflow_type = 'character_gradual' + AND LOWER(COALESCE(detailed_workflow.status, '')) <> 'cancelled' + ) THEN 'detailed' + WHEN EXISTS ( + SELECT 1 + FROM profile_workflows AS quick_workflow + WHERE quick_workflow.profile_id = character_profiles.profile_id + AND quick_workflow.workflow_type = 'character_fast' + AND LOWER(COALESCE(quick_workflow.status, '')) <> 'cancelled' + ) THEN 'quick' + ELSE 'ungenerated' + END AS generation_kind +""" + class ProfileRepository: def __init__(self, database: Database): @@ -97,7 +117,11 @@ class ProfileRepository: conn = self.database.connect() try: row = conn.execute( - f"SELECT {PROFILE_COLUMNS} FROM character_profiles WHERE profile_id = {placeholder}", + f""" + SELECT {PROFILE_COLUMNS}, {PROFILE_GENERATION_KIND_COLUMN} + FROM character_profiles + WHERE profile_id = {placeholder} + """, (profile_id,), ).fetchone() finally: @@ -129,7 +153,7 @@ class ProfileRepository: ).fetchone() rows = conn.execute( f""" - SELECT {PROFILE_COLUMNS} + SELECT {PROFILE_COLUMNS}, {PROFILE_GENERATION_KIND_COLUMN} FROM character_profiles {where} ORDER BY updated_at DESC, created_at DESC @@ -242,6 +266,7 @@ def _row_to_profile(row) -> CharacterProfile: metadata=metadata, created_at=str(row["created_at"]), updated_at=str(row["updated_at"]), + generation_kind=str(row["generation_kind"] or "ungenerated"), ) diff --git a/database/repositories/workflow_repository.py b/database/repositories/workflow_repository.py index cbdd092..e33ec04 100644 --- a/database/repositories/workflow_repository.py +++ b/database/repositories/workflow_repository.py @@ -80,48 +80,30 @@ class WorkflowRepository: return self.database._placeholder def create_workflow(self, payload: dict[str, Any]) -> ProfileWorkflow: + workflow, _ = self.create_workflow_with_nodes(payload, []) + return workflow + + def create_workflow_with_nodes( + self, + payload: dict[str, Any], + node_payloads: list[dict[str, Any]], + ) -> tuple[ProfileWorkflow, list[WorkflowNode]]: placeholder = self.placeholder conn = self.database.connect() try: - conn.execute( - f""" - INSERT INTO profile_workflows ( - workflow_id, - profile_id, - workflow_type, - display_name, - mode, - status, - current_node_id, - current_branch, - session_key, - metadata_json - ) VALUES ( - {placeholder}, {placeholder}, {placeholder}, {placeholder}, - {placeholder}, {placeholder}, {placeholder}, {placeholder}, - {placeholder}, {placeholder} - ) - """, - ( - payload["workflow_id"], - payload["profile_id"], - payload["workflow_type"], - payload["display_name"], - payload.get("mode"), - payload.get("status", "draft"), - payload.get("current_node_id"), - payload.get("current_branch", "main"), - payload.get("session_key"), - _json_or_none(payload.get("metadata")), - ), - ) + _insert_workflow(conn, placeholder, payload) + for node_payload in node_payloads: + _insert_node(conn, placeholder, node_payload) conn.commit() + except Exception: + conn.rollback() + raise finally: conn.close() workflow = self.get_workflow(payload["workflow_id"]) if workflow is None: raise RuntimeError("workflow was inserted but could not be read back") - return workflow + return workflow, self.list_nodes(workflow.workflow_id) def get_workflow(self, workflow_id: str) -> ProfileWorkflow | None: placeholder = self.placeholder @@ -195,53 +177,64 @@ class WorkflowRepository: conn.close() return self.get_workflow(workflow_id) + def update_workflow_if_status( + self, + workflow_id: str, + expected_statuses: set[str] | tuple[str, ...] | list[str], + payload: dict[str, Any], + ) -> ProfileWorkflow | None: + normalized_statuses = tuple( + sorted({str(status).strip() for status in expected_statuses if str(status).strip()}) + ) + if not normalized_statuses: + return None + allowed = { + "display_name", + "mode", + "status", + "current_node_id", + "current_branch", + "session_key", + "metadata", + } + assignments: list[str] = [] + params: list[Any] = [] + placeholder = self.placeholder + for key in allowed: + if key not in payload: + continue + column = "metadata_json" if key == "metadata" else key + value = _json_or_none(payload[key]) if key == "metadata" else payload[key] + assignments.append(f"{column} = {placeholder}") + params.append(value) + if not assignments: + workflow = self.get_workflow(workflow_id) + return workflow if workflow and workflow.status in normalized_statuses else None + assignments.append("updated_at = CURRENT_TIMESTAMP") + status_placeholders = ", ".join(placeholder for _ in normalized_statuses) + params.extend([workflow_id, *normalized_statuses]) + conn = self.database.connect() + try: + cursor = conn.execute( + f""" + UPDATE profile_workflows + SET {", ".join(assignments)} + WHERE workflow_id = {placeholder} + AND status IN ({status_placeholders}) + """, + tuple(params), + ) + changed = int(cursor.rowcount or 0) > 0 + conn.commit() + finally: + conn.close() + return self.get_workflow(workflow_id) if changed else None + def create_node(self, payload: dict[str, Any]) -> WorkflowNode: placeholder = self.placeholder conn = self.database.connect() try: - conn.execute( - f""" - INSERT INTO workflow_nodes ( - node_id, - workflow_id, - node_key, - title, - description, - step_name, - node_type, - status, - branch_name, - prompt, - negative_prompt, - model_route, - selected_image_id, - sort_order, - metadata_json - ) VALUES ( - {placeholder}, {placeholder}, {placeholder}, {placeholder}, - {placeholder}, {placeholder}, {placeholder}, {placeholder}, - {placeholder}, {placeholder}, {placeholder}, {placeholder}, - {placeholder}, {placeholder}, {placeholder} - ) - """, - ( - payload["node_id"], - payload["workflow_id"], - payload["node_key"], - payload["title"], - payload.get("description"), - payload.get("step_name"), - payload.get("node_type", "generation"), - payload.get("status", "draft"), - payload.get("branch_name", "main"), - payload.get("prompt"), - payload.get("negative_prompt"), - payload.get("model_route"), - payload.get("selected_image_id"), - int(payload.get("sort_order", 0)), - _json_or_none(payload.get("metadata")), - ), - ) + _insert_node(conn, placeholder, payload) conn.commit() finally: conn.close() @@ -328,6 +321,64 @@ class WorkflowRepository: conn.close() return self.get_node(node_id) + def update_node_if_status( + self, + node_id: str, + expected_statuses: set[str] | tuple[str, ...] | list[str], + payload: dict[str, Any], + ) -> WorkflowNode | None: + normalized_statuses = tuple( + sorted({str(status).strip() for status in expected_statuses if str(status).strip()}) + ) + if not normalized_statuses: + return None + allowed = { + "title", + "description", + "step_name", + "node_type", + "status", + "branch_name", + "prompt", + "negative_prompt", + "model_route", + "selected_image_id", + "sort_order", + "metadata", + } + assignments: list[str] = [] + params: list[Any] = [] + placeholder = self.placeholder + for key in allowed: + if key not in payload: + continue + column = "metadata_json" if key == "metadata" else key + value = _json_or_none(payload[key]) if key == "metadata" else payload[key] + assignments.append(f"{column} = {placeholder}") + params.append(value) + if not assignments: + node = self.get_node(node_id) + return node if node and node.status in normalized_statuses else None + assignments.append("updated_at = CURRENT_TIMESTAMP") + status_placeholders = ", ".join(placeholder for _ in normalized_statuses) + params.extend([node_id, *normalized_statuses]) + conn = self.database.connect() + try: + cursor = conn.execute( + f""" + UPDATE workflow_nodes + SET {", ".join(assignments)} + WHERE node_id = {placeholder} + AND status IN ({status_placeholders}) + """, + tuple(params), + ) + changed = int(cursor.rowcount or 0) > 0 + conn.commit() + finally: + conn.close() + return self.get_node(node_id) if changed else None + def create_history(self, payload: dict[str, Any]) -> WorkflowHistoryEntry: placeholder = self.placeholder conn = self.database.connect() @@ -477,6 +528,87 @@ class WorkflowRepository: return [_row_to_branch(row) for row in rows] +def _insert_workflow(conn, placeholder: str, payload: dict[str, Any]) -> None: + conn.execute( + f""" + INSERT INTO profile_workflows ( + workflow_id, + profile_id, + workflow_type, + display_name, + mode, + status, + current_node_id, + current_branch, + session_key, + metadata_json + ) VALUES ( + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder} + ) + """, + ( + payload["workflow_id"], + payload["profile_id"], + payload["workflow_type"], + payload["display_name"], + payload.get("mode"), + payload.get("status", "draft"), + payload.get("current_node_id"), + payload.get("current_branch", "main"), + payload.get("session_key"), + _json_or_none(payload.get("metadata")), + ), + ) + + +def _insert_node(conn, placeholder: str, payload: dict[str, Any]) -> None: + conn.execute( + f""" + INSERT INTO workflow_nodes ( + node_id, + workflow_id, + node_key, + title, + description, + step_name, + node_type, + status, + branch_name, + prompt, + negative_prompt, + model_route, + selected_image_id, + sort_order, + metadata_json + ) VALUES ( + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder} + ) + """, + ( + payload["node_id"], + payload["workflow_id"], + payload["node_key"], + payload["title"], + payload.get("description"), + payload.get("step_name"), + payload.get("node_type", "generation"), + payload.get("status", "draft"), + payload.get("branch_name", "main"), + payload.get("prompt"), + payload.get("negative_prompt"), + payload.get("model_route"), + payload.get("selected_image_id"), + int(payload.get("sort_order", 0)), + _json_or_none(payload.get("metadata")), + ), + ) + + def _row_to_workflow(row) -> ProfileWorkflow: return ProfileWorkflow( workflow_id=row["workflow_id"], diff --git a/docs/code-audit-2026-07-10.md b/docs/code-audit-2026-07-10.md new file mode 100644 index 0000000..7f8d957 --- /dev/null +++ b/docs/code-audit-2026-07-10.md @@ -0,0 +1,149 @@ +# 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 unittest discover -s tests +python -m compileall -q adapters backend core database engines scripts tests main.py +python scripts/imagestudio_non_ui_smoke.py +python scripts/imagestudio_pg_smoke.py --dry-run + +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 产物已由构建流程移除。 diff --git a/docs/frontend-integration-queue.md b/docs/frontend-integration-queue.md new file mode 100644 index 0000000..e5d3db5 --- /dev/null +++ b/docs/frontend-integration-queue.md @@ -0,0 +1,114 @@ +# ImageStudio 前端接入队列 + +更新时间:2026-07-11 + +本文记录后端已经具备、但前端尚未完整接入的功能,以及当前前后端仍需闭环的能力。实施时按优先级从上到下推进。 + +## P0:核心功能闭环 + +### 1. 多适配器真实路由 + +- 后端加载并管理全部生成适配器,而非只使用 `generation.provider`。 +- 支持默认适配器切换、任务指定适配器和禁用状态。 +- 支持故障切换、路由优先级和不可用适配器跳过。 +- 将模型能力档案绑定到具体适配器与模型。 +- 删除适配器前检查是否仍被任务、路由或配置引用。 + +### 2. 配置快照管理 + +- 展示快照列表、详情、操作人、时间和变更原因。 +- 调用 `settings/diff` 展示当前配置与快照的差异。 +- 接入 `settings/snapshots/{snapshot_id}` 和 `settings/rollback`。 +- 回滚前展示影响范围并要求二次确认。 + +### 3. 存储维护 + +- 接入 `storage/status`,展示目录可写性、空间与存储状态。 +- 接入 `storage/migrate`,展示迁移计划、进度和结果。 +- 接入 `media/index`,支持媒体索引重建。 +- 接入 `media/orphans`,支持孤儿文件扫描和安全处理。 + +### 4. 图库完整管理 + +- 接入选中、取消选中、归档和批量操作。 +- 接入安全删除与永久删除,并提供二次确认。 +- 展示批量操作进度、失败项和可恢复状态。 + +## P1:工作流与模型能力 + +### 5. 工作流生命周期管理 + +- 接入启动、取消和归档工作流。 +- 增加工作流状态操作栏。 +- 展示节点依赖上下文。 +- 接入工作流整体审查与历史版本恢复。 + +### 6. 审查策略页面 + +- 接入审查策略读取、校验和保存。 +- 配置角色一致性、候选图规则、错误与警告阈值。 +- 展示规则校验错误及影响范围。 + +### 7. 模型能力档案 + +- 展示已探测的适配器、模型和能力档案。 +- 区分生图、文本和视觉模型。 +- 支持重新探测、手动修正和能力状态管理。 +- 接入渲染计划兼容性校验。 + +### 8. 实时事件流 + +- 接入 `events/stream`。 +- 实时更新生成进度、队列状态和日志。 +- 支持断线重连,并保留轮询降级方案。 + +## P2:系统管理能力 + +### 9. 私伴插件集成管理 + +- 展示集成 Token 状态。 +- 支持 Token 轮换、集成启停和最近调用记录。 +- 提供每日穿搭联调测试入口。 + +### 10. 成本保护 + +- 接入 `costs/guard`。 +- 配置单次、每日和每月预算。 +- 支持超限警告或阻止策略。 +- 按适配器和模型展示费用异常。 + +### 11. 完整数据备份 + +- 当前页面仅支持脱敏配置导入导出。 +- 后续增加 SQLite 数据库备份和恢复。 +- 设计 PostgreSQL 导出、恢复和版本兼容方案。 +- 支持图片、素材与清单文件打包,并生成校验值。 + +### 12. 系统诊断页面 + +- 展示 API 合同、前后端版本、Web Manifest 和健康状态。 +- 展示已挂载路由及当前用户权限矩阵。 +- 提供诊断信息复制与脱敏导出。 + +## P3:补充与体验优化 + +### 13. 提示词扩写 + +- 接入 `prompts/expand`。 +- 支持扩写前后对比、一键采用和历史记录。 + +### 14. 素材包导入 + +- 完善导入预检、内容清单和冲突处理。 +- 展示导入进度、失败项和最终报告。 + +### 15. 页面权限统一 + +- 根据后端权限隐藏或禁用操作。 +- 统一展示无权限原因和只读状态。 +- 权限变化后自动刷新页面能力。 + +## 推荐实施顺序 + +`多适配器真实路由 → 配置快照 → 存储维护 → 图库管理 → 工作流生命周期 → 审查策略 → 能力档案 → 实时事件流 → 系统管理能力` + diff --git a/docs/ui-function-entry-index.md b/docs/ui-function-entry-index.md index 40a2f48..5a86d9e 100644 --- a/docs/ui-function-entry-index.md +++ b/docs/ui-function-entry-index.md @@ -3,6 +3,8 @@ 日期: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/` 与当前 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。文中独立 `web/` 或 Vite 地址只代表开发预览,不是 AstrBot 保证注册的生产入口。 + ## 2026-07-08 已完成闭环总结 - 快速角色:创建角色档案问卷已扩展为简单/复杂模式,复杂字段支持世界观、背景、身高/身材、身体特征、喜好、关系、故事钩子、画风和镜头偏好;字段可留空,不阻断生成档案。 @@ -246,7 +248,9 @@ - `profiles/:profileId/wardrobe/match` - `integrations/private-companion/daily-outfit` -### 模型发现与能力探测 +### 模型能力档案与安全元数据检查 + +`probe-provider` 和 `probe-model` 当前只登记/检查元数据,不会主动向填写的地址发起网络请求;真实 Provider 可用性由配置后的生成调用验证。 - `api-discovery/dialects` - `api-discovery/probe-provider` diff --git a/docs/ui-progress-2026-07-07.md b/docs/ui-progress-2026-07-07.md index 36037e0..ec43d29 100644 --- a/docs/ui-progress-2026-07-07.md +++ b/docs/ui-progress-2026-07-07.md @@ -4,6 +4,8 @@ 分支:`codex/ui-navigation-s130-s145` 口令:星图导航-S130 +> 历史记录说明:本文保留当日 UI 开发状态。当前 AstrBot 生产入口以自动发现的 `pages/imagestudio/index.html` 为准;API 在 `initialize()` 中通过 `context.register_web_api` 注册,bridge 传相对 endpoint。独立 `web/` 或 Vite 路径仅用于开发预览。 + ## 已完成进度 ### 导航与概览页 diff --git a/docs/ui-progress-2026-07-09.md b/docs/ui-progress-2026-07-09.md index ca3c426..1dd95f2 100644 --- a/docs/ui-progress-2026-07-09.md +++ b/docs/ui-progress-2026-07-09.md @@ -3,6 +3,8 @@ 日期:2026-07-09 范围:生成页、快速角色、角色工作流、阶段审查、锁定与分支、后端接口闭环 +> 历史记录说明:本文保留当日开发与验证结果。当前 AstrBot 生产页面由 `pages/imagestudio/index.html` 自动发现;bridge 调用传相对 endpoint,兼容 v4.25 legacy `/api/plug/astrbot_plugin_imagestudio/` 与当前 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。下文 `/web` URL 是 Vite 预览记录,不表示 AstrBot 注册了该生产入口。 + ## 当前总体状态 - 生成页已经形成三条主入口:`图片生成`、`快速角色`、`角色工作流`。 @@ -253,7 +255,7 @@ - 结果:通过。 - 使用 Codex bundled Python 运行 `python -m unittest tests.test_prompt_plan_schema_service tests.test_material_binding_schema_service tests.test_review_service tests.test_quick_profile_service tests.test_workflow_service tests.test_node_dependency_context_service tests.test_prompt_expansion_service tests.test_history_service` - 结果:44 tests OK。 -- 本地 dev server: +- 本地 Vite dev server(仅历史预览路径,不是 AstrBot 生产入口): - `http://127.0.0.1:5173/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/?view=generate` - HTTP 返回 200。 diff --git a/docs/ui-progress-2026-07-10.md b/docs/ui-progress-2026-07-10.md index 7323206..8530f07 100644 --- a/docs/ui-progress-2026-07-10.md +++ b/docs/ui-progress-2026-07-10.md @@ -4,6 +4,21 @@ 分支:`codex/ui-navigation-s130-s145` 范围:未提交变更检查、功能验证、静态构建、推送前总结。 +> 历史记录说明:本文保留当日开发与构建状态。当前 AstrBot 生产页面由 `pages/imagestudio/index.html` 自动发现;插件通过 `context.register_web_api` 提供 API,页面 bridge 传相对 endpoint。下文 `/web` URL 是 Vite 预览记录,不表示 AstrBot 注册了该生产入口。 + +## 后续前端重构更新 + +本文件后续章节保留当时的阶段记录,当前前端状态以 [前端拆分与体验优化报告](ui-refactor-2026-07-10.md) 为准。本轮已拆出导航、指标/状态原语、图片预览、素材弹窗、外部角色卡解析和共享工具,并完成桌面与 390×844 移动端浏览器回归。 + +当前构建产物: + +- `pages/imagestudio/assets/index-CF6dVfCE.js` +- `pages/imagestudio/assets/index-D4NekmM3.css` +- `web/assets/index-djgvYVE7.js` +- `web/assets/index-VBJk7aNa.css` + +当前前端定向验证:`typecheck`、Plugin Page/Web 生产构建、18 项前端契约测试及 7 项文档打包测试均通过。 + ## 推送前状态 - 已执行 `git fetch origin`。 @@ -76,7 +91,7 @@ - 结果:81 tests OK。 - `npm.cmd run build:web` - 结果:通过,生成最新 `web/` 静态产物。 -- 内置浏览器打开: +- 内置浏览器打开本地 Vite 预览(不是 AstrBot 生产入口): - `http://127.0.0.1:5173/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/?view=materials` - 结果:素材页标题、预览模式提示、示例素材卡、素材操作卡正常渲染。 - 控制台:未发现 error/warn。 diff --git a/docs/ui-refactor-2026-07-10.md b/docs/ui-refactor-2026-07-10.md new file mode 100644 index 0000000..a0333bf --- /dev/null +++ b/docs/ui-refactor-2026-07-10.md @@ -0,0 +1,67 @@ +# ImageStudio 前端拆分与体验优化(2026-07-10) + +## 本轮目标 + +在不改变后端 API 契约的前提下,拆分大型 Workbench、合并重复代码,并修复真实数据与预览数据边界、键盘操作、移动端导航和弹窗体验问题。 + +## 已完成拆分 + +- `AppNavigationRail.vue`:导航渲染、活动页语义和固定/自动收起控制。 +- `MetricCardGrid.vue`:素材、队列、首页和性能页统一指标卡渲染。 +- `StateCard.vue`:统一成功、错误、警告状态反馈及 `aria-live`。 +- `EmptyState.vue`:统一空态和可选操作入口。 +- `ImagePreviewDialog.vue`:统一图片预览、0.5–4 倍缩放、双击缩放、拖拽和 Escape/遮罩关闭。 +- `MaterialOperationDialog.vue`:素材 URI、素材包和衣橱操作;补齐焦点管理、焦点循环和移动端布局。 +- `MaterialCategoryCreateDialog.vue`:素材分类创建表单与焦点管理。 +- `MaterialDetailDialog.vue`:素材详情展示与键盘关闭。 +- `features/quick-profile/profile-import.ts`:外部角色卡解析、默认问卷和空问卷纯函数。 +- `types/navigation.ts`:导航与模块契约。 + +## 已合并的重复代码 + +- `shared/utils/presentation.ts`:状态标准化、状态文案/颜色、时间、容量、成本、任务等待时间和短 ID。 +- `shared/utils/storage-uri.ts`:`storage://` 校验、文件名提取和 PNG/JPEG/GIF/WebP 素材 URI 校验。 +- `shared/utils/collections.ts`:`uniqueBy` 与字符串去重。 +- `shared/types/ui.ts`:通用指标卡、详情行和动作卡类型。 +- 图片预览重复模板、素材分类/详情弹层以及四处指标卡模板已合并为组件。 + +## UI/UX 修复 + +- 桌面导航增加固定/自动收起开关;队列和性能入口重新进入主导航。 +- 390px 移动端底部导航显示文字标签,不再只依赖抽象符号和 hover 提示。 +- 全局搜索升级为标准 combobox/listbox:支持 Ctrl/Cmd+K、`/`、上下方向键和 Enter。 +- 生成与工作流输入支持 Ctrl/Cmd+Enter 提交。 +- 原“生成设置”“工作流设置”“附加素材”假按钮已接入真实设置/素材导航。 +- 首页队列“查看详情”“重试”按钮已连接真实队列选择与重试动作,并按权限/状态禁用。 +- 真实后端已连接但未配置模型时不再伪装成示例/本地模型;提交会被禁用并引导到设置。 +- 真实后端空素材库不再自动展示示例素材;预览/错误模式才显示明确标记的样例。 +- 素材 URI 前端校验与后端一致,支持 GIF。 +- 弹窗补齐遮罩关闭、Escape、自动聚焦、busy 防误关、焦点循环、`100dvh` 与 safe-area。 +- 队列 tab、通知筛选和素材分类筛选补齐 `aria-selected`/`aria-pressed`。 +- 状态卡统一使用 `role="alert"` 或 `role="status"`,错误不再挤在模型选择器的小区域中。 + +## 验证 + +- `npm.cmd run typecheck`:通过。 +- `python -m unittest tests.test_frontend_api_contract tests.test_docs_packaging`:25 项通过。 +- 全量 `python -m unittest discover -s tests`:359 项 OK,其中 1 项按环境条件跳过。 +- `npm.cmd run build:plugin`:通过。 +- `npm.cmd run build:web`:通过。 +- 浏览器桌面与 390×844 移动端回归:通过。 + - 导航固定、移动标签、明暗主题正常。 + - Ctrl/Cmd+K 搜索、方向键和 Enter 跳转正常。 + - 队列筛选具备 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` + +## 剩余边界 + +- `App.vue` 已拆出组件、纯函数、共享类型和工具,但仍约 18,138 行,主要体积来自生成/角色工作流状态编排和集中样式;后续应继续拆 `useWorkflowStore`、`useWorkflowActions`、通知和异步资源 composable。 +- 浏览器回归运行在 Vite 预览模式,未连接真实 AstrBot 后端;真实数据库写入、素材 Vision 与 Provider 调用仍由后端测试和 AstrBot 环境验收覆盖。 diff --git a/engines/image_provider.py b/engines/image_provider.py index 9d2c47d..da996b6 100644 --- a/engines/image_provider.py +++ b/engines/image_provider.py @@ -13,9 +13,20 @@ import urllib.request from dataclasses import dataclass, field from typing import Any, Callable, Protocol +from core.remote_fetch import RemoteFetchError, read_http_response_limited, validate_http_url + JsonDict = dict[str, Any] HttpTransport = Callable[[str, JsonDict, dict[str, str], int], JsonDict] +MAX_PROVIDER_IMAGE_BYTES = 25 * 1024 * 1024 +MAX_PROVIDER_IMAGE_COUNT = 8 +MAX_PROVIDER_JSON_BASE_OVERHEAD_BYTES = 1024 * 1024 +MAX_PROVIDER_JSON_PER_IMAGE_OVERHEAD_BYTES = 128 * 1024 +# Decoding JSON temporarily retains the response bytes, decoded text, and +# parsed base64 strings. Keep the aggregate response bounded even when eight +# images are requested; individual images still receive their full 25 MiB cap. +MAX_PROVIDER_JSON_HARD_BYTES = 128 * 1024 * 1024 +MAX_PROVIDER_ERROR_BYTES = 64 * 1024 class ImageProvider(Protocol): @@ -35,6 +46,7 @@ class ImageProviderConfig: provider_type: str = "openai_compatible" timeout_seconds: int = 180 extra_headers: dict[str, str] = field(default_factory=dict) + supports_negative_prompt: bool = True def endpoint_url(self) -> str: base = self.base_url.rstrip("/") @@ -45,6 +57,7 @@ class ImageProviderConfig: @dataclass(frozen=True) class ImageGenerationRequest: prompt: str + negative_prompt: str | None = None model: str | None = None size: str = "1024x1024" count: int = 1 @@ -113,12 +126,15 @@ class OpenAIImageProvider: "prompt": request.prompt, "size": request.size, "n": _bounded_count(request.count), + "response_format": "b64_json", } if request.input_images: payload["image"] = list(request.input_images) + if self.config.supports_negative_prompt and (negative_prompt := _optional_text(request.negative_prompt)): + payload["negative_prompt"] = negative_prompt headers = { - "Authorization": f"Bearer {self.config.api_key}", "Content-Type": "application/json", + **({"Authorization": f"Bearer {self.config.api_key}"} if self.config.api_key else {}), **self.config.extra_headers, } try: @@ -133,7 +149,12 @@ class OpenAIImageProvider: error_type=exc.error_type, details=exc.details, ) from exc - return _parse_image_response(self.provider_id, model, response) + return _parse_image_response( + self.provider_id, + model, + response, + provider_base_url=self.config.base_url, + ) class MockImageProvider: @@ -155,19 +176,33 @@ class MockImageProvider: def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_seconds: int) -> JsonDict: + try: + validate_http_url(url, allow_private=True) + except RemoteFetchError as exc: + raise ImageProviderError( + "image provider endpoint is invalid", + provider_id="unknown", + error_type="configuration_error", + details={"reason": str(exc)}, + ) from exc data = json.dumps(payload, ensure_ascii=False).encode("utf-8") request = urllib.request.Request(url, data=data, headers=headers, method="POST") try: - with urllib.request.urlopen(request, timeout=timeout_seconds) as response: - body = response.read().decode("utf-8-sig") + body = read_http_response_limited( + request, + timeout_seconds=timeout_seconds, + max_bytes=_provider_json_limit(payload.get("n", 1)), + allow_private=True, + same_origin_redirects_only=True, + ).decode("utf-8-sig") except urllib.error.HTTPError as exc: - body = exc.read().decode("utf-8", errors="replace") + body = exc.read(MAX_PROVIDER_ERROR_BYTES + 1).decode("utf-8", errors="replace") raise ImageProviderError( "image provider returned an HTTP error", provider_id="unknown", status_code=exc.code, error_type="http_error", - details={"body_preview": body[:500]}, + details={"body_preview": body[:500], "body_truncated": len(body) > MAX_PROVIDER_ERROR_BYTES}, ) from exc except urllib.error.URLError as exc: raise ImageProviderError( @@ -176,6 +211,13 @@ def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_sec error_type="network_error", details={"reason": str(exc.reason)}, ) from exc + except (RemoteFetchError, UnicodeDecodeError) as exc: + raise ImageProviderError( + "image provider response exceeded safety limits", + provider_id="unknown", + error_type="invalid_response", + details={"reason": str(exc)}, + ) from exc try: parsed = json.loads(body) except json.JSONDecodeError as exc: @@ -190,7 +232,13 @@ def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_sec return parsed -def _parse_image_response(provider_id: str, model: str, response: JsonDict) -> ImageGenerationResult: +def _parse_image_response( + provider_id: str, + model: str, + response: JsonDict, + *, + provider_base_url: str | None = None, +) -> ImageGenerationResult: data = response.get("data", []) if not isinstance(data, list): raise ImageProviderError( @@ -207,6 +255,7 @@ def _parse_image_response(provider_id: str, model: str, response: JsonDict) -> I raw_metadata={ "created": response.get("created"), "response_keys": sorted(str(key) for key in response.keys()), + "provider_base_url": provider_base_url, }, ) @@ -225,7 +274,19 @@ def _bounded_count(value: int) -> int: count = int(value) except (TypeError, ValueError): count = 1 - return min(max(count, 1), 8) + return min(max(count, 1), MAX_PROVIDER_IMAGE_COUNT) + + +def _provider_json_limit(requested_count: Any) -> int: + """Bound a base64 JSON response according to the requested image count.""" + + count = _bounded_count(requested_count) + base64_bytes_per_image = ((MAX_PROVIDER_IMAGE_BYTES + 2) // 3) * 4 + calculated = ( + MAX_PROVIDER_JSON_BASE_OVERHEAD_BYTES + + count * (base64_bytes_per_image + MAX_PROVIDER_JSON_PER_IMAGE_OVERHEAD_BYTES) + ) + return min(calculated, MAX_PROVIDER_JSON_HARD_BYTES) def _optional_text(value: Any) -> str | None: diff --git a/engines/review_flow.py b/engines/review_flow.py index 91d8a17..d3b63ae 100644 --- a/engines/review_flow.py +++ b/engines/review_flow.py @@ -24,6 +24,8 @@ _KNOWN_NODE_STATUSES = { "discarded", } +_GENERATION_NODE_TYPES = {"generation", "single_image", "virtual_single_image"} + @dataclass(frozen=True) class ReviewPolicy: @@ -120,7 +122,11 @@ class ReviewFlowEngine: selected_image = next((image for image in images if image.image_id == node.selected_image_id), None) if self.policy.warn_without_images and not images: warnings.append({"code": "NO_IMAGES", "message": "node has no generated images"}) - if node.status in self.policy.require_selected_image_for_statuses and not node.selected_image_id: + if ( + node.node_type in _GENERATION_NODE_TYPES + and node.status in self.policy.require_selected_image_for_statuses + and not node.selected_image_id + ): errors.append({"code": "MISSING_SELECTED_IMAGE", "message": "completed node has no selected image"}) if ( self.policy.fail_on_selected_image_not_found @@ -185,6 +191,20 @@ class ReviewFlowEngine: "node_ids": incomplete, } ) + incomplete_generation = [ + node.node_id + for node in nodes + if node.node_type in _GENERATION_NODE_TYPES + and node.status not in self.policy.workflow_terminal_statuses + ] + if incomplete_generation: + errors.append( + { + "code": "INCOMPLETE_GENERATION_NODES", + "message": "workflow has unfinished generation nodes", + "node_ids": incomplete_generation, + } + ) selected_model_routes = sorted( { str(result["summary"].get("selected_image_model_route")) diff --git a/engines/single_flow.py b/engines/single_flow.py index 7061244..13244f6 100644 --- a/engines/single_flow.py +++ b/engines/single_flow.py @@ -1,10 +1,10 @@ -"""Single image workflow mock engine.""" +"""Single-image workflow engine with an explicit development mock mode.""" from __future__ import annotations import base64 +import binascii import re -import urllib.request from dataclasses import dataclass from pathlib import Path from typing import Any, Callable @@ -12,8 +12,15 @@ from typing import Any, Callable from backend.dto.job_dto import GenerationTask from backend.dto.workflow_dto import WorkflowNode from core.generation_errors import provider_failure_attribution +from core.image_formats import ImageFormat, detect_image_format +from core.remote_fetch import RemoteFetchError, read_http_response_limited, url_hostname from core.storage import VfsStorage -from engines.image_provider import ImageGenerationRequest, ImageProvider, ImageProviderError +from engines.image_provider import ( + MAX_PROVIDER_IMAGE_BYTES, + ImageGenerationRequest, + ImageProvider, + ImageProviderError, +) ONE_PIXEL_PNG = base64.b64decode( @@ -39,9 +46,12 @@ class SingleFlowEngine: self, storage: VfsStorage | None = None, image_provider_factory: Callable[[dict[str, Any]], ImageProvider | None] | None = None, + *, + allow_mock_fallback: bool = False, ): self.storage = storage or VfsStorage() self.image_provider_factory = image_provider_factory + self.allow_mock_fallback = allow_mock_fallback def generate(self, node: WorkflowNode, task: GenerationTask, request: dict[str, Any]) -> list[MockGeneratedAsset]: count = _bounded_count(request.get("count", 1)) @@ -64,6 +74,8 @@ class SingleFlowEngine: count, ) except ImageProviderError as exc: + if not self.allow_mock_fallback: + raise route = request.get("resolved_model_route") if isinstance(request.get("resolved_model_route"), dict) else {} return self._generate_mock( task, @@ -76,7 +88,15 @@ class SingleFlowEngine: count, provider_error=provider_failure_attribution(exc, route_context=route, fallback_used=True), ) - return self._generate_mock(task, request, prompt, negative_prompt, model_route, width, height, count) + if self.allow_mock_fallback: + return self._generate_mock(task, request, prompt, negative_prompt, model_route, width, height, count) + route = request.get("resolved_model_route") if isinstance(request.get("resolved_model_route"), dict) else {} + raise ImageProviderError( + "no usable image provider is configured for this model route", + provider_id=str(route.get("provider_id") or "unresolved"), + error_type="configuration_error", + details={"model_route": model_route}, + ) def _generate_mock( self, @@ -135,10 +155,11 @@ class SingleFlowEngine: result = provider.generate_image( ImageGenerationRequest( prompt=prompt, + negative_prompt=negative_prompt, model=str(route.get("model_id") or model_route), size=f"{width}x{height}", count=count, - input_images=tuple(str(item) for item in request.get("input_images") or request.get("image") or []), + input_images=_normalize_input_images(request.get("input_images") or request.get("image")), metadata={"task_id": task.task_id, "model_route": model_route}, ) ) @@ -147,11 +168,17 @@ class SingleFlowEngine: for index, image in enumerate(result.images): if not image.has_image_data: continue - image_bytes = _image_bytes(image.b64_json, image.url, provider_id=result.provider_id) - image_uri = f"storage://images/single/{task_stem}_{index + 1}.png" - thumbnail_uri = f"storage://thumbnails/single/{task_stem}_{index + 1}.png" - self._write_png(image_uri, image_bytes) - self._write_png(thumbnail_uri, image_bytes) + image_bytes = _image_bytes( + image.b64_json, + image.url, + provider_id=result.provider_id, + provider_base_url=str(result.raw_metadata.get("provider_base_url") or ""), + ) + image_format = _require_image_format(image_bytes, provider_id=result.provider_id) + image_uri = f"storage://images/single/{task_stem}_{index + 1}{image_format.extension}" + thumbnail_uri = f"storage://thumbnails/single/{task_stem}_{index + 1}{image_format.extension}" + self._write_image(image_uri, image_bytes) + self._write_image(thumbnail_uri, image_bytes) assets.append( MockGeneratedAsset( image_uri=image_uri, @@ -169,6 +196,8 @@ class SingleFlowEngine: "provider_model": result.model, "usage": result.usage, "source_url": image.url, + "content_type": image_format.mime_type, + "file_extension": image_format.extension, }, ) ) @@ -181,6 +210,9 @@ class SingleFlowEngine: return assets def _write_png(self, uri: str, content: bytes = ONE_PIXEL_PNG) -> None: + self._write_image(uri, content) + + def _write_image(self, uri: str, content: bytes) -> None: path = self.storage.resolve_uri(uri) Path(path).parent.mkdir(parents=True, exist_ok=True) Path(path).write_bytes(content) @@ -229,14 +261,53 @@ def _safe_file_stem(value: str) -> str: return stem or "task" -def _image_bytes(b64_json: str | None, url: str | None, *, provider_id: str = "unknown") -> bytes: +def _normalize_input_images(value: Any) -> tuple[str, ...]: + if value is None: + return () + if isinstance(value, str): + text = value.strip() + return (text,) if text else () + if isinstance(value, (list, tuple, set)): + return tuple(text for item in value if (text := str(item).strip())) + text = str(value).strip() + return (text,) if text else () + + +def _image_bytes( + b64_json: str | None, + url: str | None, + *, + provider_id: str = "unknown", + provider_base_url: str | None = None, +) -> bytes: if b64_json: - return base64.b64decode(re.sub(r"\s+", "", b64_json)) - if url: + encoded = re.sub(r"\s+", "", b64_json) + if len(encoded) > ((MAX_PROVIDER_IMAGE_BYTES + 2) // 3) * 4: + raise ImageProviderError( + "image provider base64 payload exceeds the size limit", + provider_id=provider_id, + error_type="invalid_response", + ) try: - with urllib.request.urlopen(url, timeout=120) as response: - return response.read() - except Exception as exc: + body = base64.b64decode(encoded, validate=True) + except (binascii.Error, ValueError) as exc: + raise ImageProviderError( + "image provider returned invalid base64 image data", + provider_id=provider_id, + error_type="invalid_response", + ) from exc + return _validate_image_bytes(body, provider_id=provider_id) + if url: + provider_host = url_hostname(provider_base_url) + try: + body = read_http_response_limited( + url, + timeout_seconds=120, + max_bytes=MAX_PROVIDER_IMAGE_BYTES, + allowed_private_hosts=(provider_host,) if provider_host else (), + ) + return _validate_image_bytes(body, provider_id=provider_id) + except (OSError, RemoteFetchError) as exc: raise ImageProviderError( "image provider image URL could not be downloaded", provider_id=provider_id, @@ -244,3 +315,27 @@ def _image_bytes(b64_json: str | None, url: str | None, *, provider_id: str = "u details={"reason": str(exc)}, ) from exc raise ImageProviderError("image payload is empty", provider_id=provider_id, error_type="invalid_response") + + +def _validate_image_bytes(body: bytes, *, provider_id: str) -> bytes: + if not body: + raise ImageProviderError("image payload is empty", provider_id=provider_id, error_type="invalid_response") + if len(body) > MAX_PROVIDER_IMAGE_BYTES: + raise ImageProviderError( + "image provider payload exceeds the size limit", + provider_id=provider_id, + error_type="invalid_response", + ) + _require_image_format(body, provider_id=provider_id) + return body + + +def _require_image_format(body: bytes, *, provider_id: str) -> ImageFormat: + image_format = detect_image_format(body) + if image_format is None: + raise ImageProviderError( + "image provider payload is not a supported image", + provider_id=provider_id, + error_type="invalid_response", + ) + return image_format diff --git a/engines/vision_provider.py b/engines/vision_provider.py index c2c2df7..b4f05de 100644 --- a/engines/vision_provider.py +++ b/engines/vision_provider.py @@ -8,9 +8,13 @@ import urllib.request from dataclasses import dataclass, field from typing import Any, Callable, Protocol +from core.remote_fetch import RemoteFetchError, read_http_response_limited, validate_http_url + JsonDict = dict[str, Any] HttpTransport = Callable[[str, JsonDict, dict[str, str], int], JsonDict] +MAX_PROVIDER_JSON_BYTES = 4 * 1024 * 1024 +MAX_PROVIDER_ERROR_BYTES = 64 * 1024 class VisionProvider(Protocol): @@ -92,6 +96,12 @@ class OpenAIVisionProvider: provider_id=self.provider_id, error_type="configuration_error", ) + if not (_remote_image_url(request.image_uri) or _remote_image_url(request.thumbnail_uri)): + raise VisionProviderError( + "vision image must be supplied as an HTTP(S) URL or data:image URL", + provider_id=self.provider_id, + error_type="invalid_request", + ) payload = { "model": model, "messages": [ @@ -108,8 +118,8 @@ class OpenAIVisionProvider: "response_format": {"type": "json_object"}, } headers = { - "Authorization": f"Bearer {self.config.api_key}", "Content-Type": "application/json", + **({"Authorization": f"Bearer {self.config.api_key}"} if self.config.api_key else {}), **self.config.extra_headers, } try: @@ -160,11 +170,9 @@ def _user_content(request: VisionRecognitionRequest) -> list[dict[str, Any]]: ), } ] - image_url = _remote_image_url(request.thumbnail_uri) or _remote_image_url(request.image_uri) + image_url = _remote_image_url(request.image_uri) or _remote_image_url(request.thumbnail_uri) if image_url: content.append({"type": "image_url", "image_url": {"url": image_url}}) - else: - content[0]["text"] += f"\nStorage image URI: {request.image_uri}" return content @@ -176,19 +184,33 @@ def _remote_image_url(value: str | None) -> str | None: def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_seconds: int) -> JsonDict: + try: + validate_http_url(url, allow_private=True) + except RemoteFetchError as exc: + raise VisionProviderError( + "vision provider endpoint is invalid", + provider_id="unknown", + error_type="configuration_error", + details={"reason": str(exc)}, + ) from exc data = json.dumps(payload, ensure_ascii=False).encode("utf-8") request = urllib.request.Request(url, data=data, headers=headers, method="POST") try: - with urllib.request.urlopen(request, timeout=timeout_seconds) as response: - body = response.read().decode("utf-8-sig") + body = read_http_response_limited( + request, + timeout_seconds=timeout_seconds, + max_bytes=MAX_PROVIDER_JSON_BYTES, + allow_private=True, + same_origin_redirects_only=True, + ).decode("utf-8-sig") except urllib.error.HTTPError as exc: - body = exc.read().decode("utf-8", errors="replace") + body = exc.read(MAX_PROVIDER_ERROR_BYTES + 1).decode("utf-8", errors="replace") raise VisionProviderError( "vision provider returned an HTTP error", provider_id="unknown", status_code=exc.code, error_type="http_error", - details={"body_preview": body[:500]}, + details={"body_preview": body[:500], "body_truncated": len(body) > MAX_PROVIDER_ERROR_BYTES}, ) from exc except urllib.error.URLError as exc: raise VisionProviderError( @@ -197,6 +219,13 @@ def _post_json(url: str, payload: JsonDict, headers: dict[str, str], timeout_sec error_type="network_error", details={"reason": str(exc.reason)}, ) from exc + except (RemoteFetchError, UnicodeDecodeError) as exc: + raise VisionProviderError( + "vision provider response exceeded safety limits", + provider_id="unknown", + error_type="invalid_response", + details={"reason": str(exc)}, + ) from exc try: parsed = json.loads(body) except json.JSONDecodeError as exc: diff --git a/frontend/README.md b/frontend/README.md index 4306d1c..f6d14a8 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -7,11 +7,21 @@ The frontend contains two Vite applications: Shared API clients, types, stores, components, constants, schemas, and utilities live in `shared/`. -Dependencies are declared in `package.json` but not installed yet. +The Workbench is split by responsibility: -Both UIs must consume the same v3 API contract: +- `standalone-web/src/App.vue` owns page orchestration, backend state, and cross-feature coordination. +- `standalone-web/src/components/` contains reusable navigation, metric, state, empty-state, image-preview, and material-dialog components. +- `standalone-web/src/features/` contains feature-level pure logic such as external character-profile parsing. +- `standalone-web/src/types/` contains shell/navigation contracts shared by the Workbench components. +- `shared/utils/` contains presentation and `storage://` helpers reused by both the Workbench and dialogs. -- Plugin Page UI uses `window.AstrBotPluginPage`. +Keep new modal, status-card, metric-card, parsing, and formatting logic out of `App.vue` when an existing component or utility can own it. The Workbench stylesheet is intentionally app-global inside the standalone page/plugin iframe so extracted components can reuse the same design tokens and class primitives. + +Install dependencies with `npm.cmd install` on Windows or `npm install` on other platforms. Validate with `npm.cmd run typecheck`, then build both targets with `npm.cmd run build`. + +Both targets render the same Workbench implementation and consume the same v3 API contract: + +- Plugin Page UI prefers `window.AstrBotPluginPage`; the shared client unwraps AstrBot and ImageStudio response envelopes and provides a POST method-override envelope for legacy bridges that only expose GET/POST. - Standalone Web UI uses `/api/v1/plugins/extensions/astrbot_plugin_imagestudio`. Do not store API keys, media paths, or selected image state in frontend-only storage. diff --git a/frontend/env.d.ts b/frontend/env.d.ts index 7d9c55e..5a7d699 100644 --- a/frontend/env.d.ts +++ b/frontend/env.d.ts @@ -10,10 +10,10 @@ declare module "*.vue" { interface Window { AstrBotPluginPage?: { ready?(): Promise - apiGet(path: string, params?: Record): Promise - apiPost(path: string, body?: unknown): Promise - apiPut(path: string, body?: unknown): Promise - apiPatch(path: string, body?: unknown): Promise - apiDelete(path: string): Promise + apiGet?(path: string, params?: Record): Promise + apiPost?(path: string, body?: unknown): Promise + apiPut?(path: string, body?: unknown): Promise + apiPatch?(path: string, body?: unknown): Promise + apiDelete?(path: string): Promise } } diff --git a/frontend/plugin-page/index.html b/frontend/plugin-page/index.html index fa207c8..870ea73 100644 --- a/frontend/plugin-page/index.html +++ b/frontend/plugin-page/index.html @@ -1,2 +1,12 @@ -
- + + + + + + AstrBot ImageStudio + + +
+ + + diff --git a/frontend/plugin-page/src/App.vue b/frontend/plugin-page/src/App.vue index ce16d8a..1f66b66 100644 --- a/frontend/plugin-page/src/App.vue +++ b/frontend/plugin-page/src/App.vue @@ -1,478 +1,7 @@ - - diff --git a/frontend/plugin-page/vite.config.ts b/frontend/plugin-page/vite.config.ts index 3a0e328..257aa0f 100644 --- a/frontend/plugin-page/vite.config.ts +++ b/frontend/plugin-page/vite.config.ts @@ -1,13 +1,16 @@ import { resolve } from "node:path" +import { fileURLToPath } from "node:url" import vue from "@vitejs/plugin-vue" import { defineConfig } from "vite" +const rootDir = fileURLToPath(new URL(".", import.meta.url)) + export default defineConfig({ plugins: [vue()], - root: __dirname, + root: rootDir, base: "./", build: { - outDir: resolve(__dirname, "../../pages/imagestudio"), + outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true, }, }) diff --git a/frontend/shared/api/client.ts b/frontend/shared/api/client.ts index bfd5c07..276b3fa 100644 --- a/frontend/shared/api/client.ts +++ b/frontend/shared/api/client.ts @@ -1,7 +1,11 @@ import { API_BASE } from "./endpoints" -import type { ApiResponse } from "../types/api" +import type { ApiResponse, AstrBotApiResponse } from "../types/api" export type ApiTransport = "plugin-bridge" | "direct-fetch" +export type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" + +const METHOD_OVERRIDE_KEY = "__imagestudio_method" +const METHOD_OVERRIDE_BODY_KEY = "__imagestudio_body" export class ApiClientError extends Error { readonly code: string @@ -27,6 +31,14 @@ export async function putJson(endpoint: string, body?: unknown) { return request(endpoint, { method: "PUT", body }) } +export async function patchJson(endpoint: string, body?: unknown) { + return request(endpoint, { method: "PATCH", body }) +} + +export async function deleteJson(endpoint: string, body?: unknown) { + return request(endpoint, { method: "DELETE", body }) +} + export function getApiTransport(): ApiTransport { const bridge = typeof window === "undefined" ? undefined : window.AstrBotPluginPage return bridge && (typeof bridge.apiGet === "function" || typeof bridge.apiPost === "function") @@ -37,13 +49,21 @@ export function getApiTransport(): ApiTransport { export async function request( endpoint: string, options: { - method?: "GET" | "POST" | "PUT" | "DELETE" + method?: ApiMethod query?: Record body?: unknown } = {}, ): Promise { + const hasPluginBridge = typeof window !== "undefined" && Boolean(window.AstrBotPluginPage) const bridgePayload = await requestViaPluginBridge(endpoint, options) - if (bridgePayload !== undefined) { + if (hasPluginBridge) { + if (bridgePayload === undefined) { + throw new ApiClientError("invalid_api_response", "AstrBot Plugin Page bridge returned no response", { + endpoint, + method: options.method ?? "GET", + transport: "plugin-bridge", + }) + } return unwrapApiResponse(bridgePayload) } @@ -65,7 +85,7 @@ export async function request( } const payload = await parseResponsePayload(response, endpoint, url) - if (!response.ok && !isApiResponse(payload)) { + if (!response.ok && !isApiResponse(payload) && !isAstrBotApiResponse(payload)) { throw new ApiClientError("http_error", `接口请求失败(HTTP ${response.status})`, { endpoint, transport: "direct-fetch", @@ -80,11 +100,11 @@ export async function request( async function requestViaPluginBridge( endpoint: string, options: { - method?: "GET" | "POST" | "PUT" | "DELETE" + method?: ApiMethod query?: Record body?: unknown }, -): Promise | undefined> { +): Promise | AstrBotApiResponse | undefined> { const bridge = window.AstrBotPluginPage if (!bridge) { return undefined @@ -94,31 +114,68 @@ async function requestViaPluginBridge( await bridge.ready() } if (method === "GET" && typeof bridge.apiGet === "function") { - return bridge.apiGet>(endpoint, compactQuery(options.query)) + return bridge.apiGet | AstrBotApiResponse>(endpoint, compactQuery(options.query)) } if (method === "POST" && typeof bridge.apiPost === "function") { - return bridge.apiPost>(endpoint, options.body) + return bridge.apiPost | AstrBotApiResponse>(endpoint, options.body) } if (method === "PUT" && typeof bridge.apiPut === "function") { - return bridge.apiPut>(endpoint, options.body) + return bridge.apiPut | AstrBotApiResponse>(endpoint, options.body) + } + if (method === "PATCH" && typeof bridge.apiPatch === "function") { + return bridge.apiPatch | AstrBotApiResponse>(endpoint, options.body) } if (method === "DELETE" && typeof bridge.apiDelete === "function") { - return bridge.apiDelete>(endpoint) + return bridge.apiDelete | AstrBotApiResponse>(endpoint) } - return undefined + if (["PUT", "PATCH", "DELETE"].includes(method) && typeof bridge.apiPost === "function") { + return bridge.apiPost | AstrBotApiResponse>(endpoint, { + [METHOD_OVERRIDE_KEY]: method, + [METHOD_OVERRIDE_BODY_KEY]: method === "DELETE" ? {} : options.body === undefined ? {} : options.body, + }) + } + throw new ApiClientError("bridge_method_unavailable", `AstrBot Plugin Page bridge does not support ${method}`, { + endpoint, + method, + transport: "plugin-bridge", + }) } -function unwrapApiResponse(payload: T | ApiResponse): T { - if (!isApiResponse(payload)) { - return payload +function unwrapApiResponse(payload: T | ApiResponse | AstrBotApiResponse): T { + let current: unknown = payload + for (let depth = 0; depth < 4; depth += 1) { + if (isApiResponse(current)) { + if (!current.ok) { + throw new ApiClientError(current.error_code, current.message, current.details ?? {}) + } + current = current.data + continue + } + if (isAstrBotApiResponse(current)) { + if (current.status === "error") { + if (isApiResponse(current.data)) { + current = current.data + continue + } + throw new ApiClientError( + current.error_code || "astrbot_bridge_error", + current.message || current.error || "AstrBot Plugin Page bridge request failed", + current.details ?? bridgeErrorDetails(current.data), + ) + } + current = current.data + continue + } + return current as T } - if (!payload.ok) { - throw new ApiClientError(payload.error_code, payload.message, payload.details) - } - return payload.data + throw new ApiClientError("invalid_api_response", "API response wrapper nesting is too deep") } -async function parseResponsePayload(response: Response, endpoint: string, url: string): Promise> { +async function parseResponsePayload( + response: Response, + endpoint: string, + url: string, +): Promise | AstrBotApiResponse> { const contentType = response.headers.get("content-type") ?? "" const isJson = contentType.includes("application/json") || contentType.includes("+json") if (!isJson) { @@ -134,7 +191,7 @@ async function parseResponsePayload(response: Response, endpoint: string, url }) } try { - return (await response.json()) as T | ApiResponse + return (await response.json()) as T | ApiResponse | AstrBotApiResponse } catch (err) { throw new ApiClientError("invalid_api_response", "接口返回格式不正确", { endpoint, @@ -148,8 +205,22 @@ async function parseResponsePayload(response: Response, endpoint: string, url } } -function isApiResponse(payload: T | ApiResponse): payload is ApiResponse { - return Boolean(payload && typeof payload === "object" && "ok" in payload) +function isApiResponse(payload: unknown): payload is ApiResponse { + if (!payload || typeof payload !== "object" || !("ok" in payload) || typeof payload.ok !== "boolean") { + return false + } + return payload.ok ? "data" in payload : "error_code" in payload && "message" in payload +} + +function isAstrBotApiResponse(payload: unknown): payload is AstrBotApiResponse { + if (!payload || typeof payload !== "object" || !("status" in payload)) { + return false + } + return payload.status === "error" || (payload.status === "ok" && "data" in payload) +} + +function bridgeErrorDetails(data: unknown): Record { + return data && typeof data === "object" ? { bridge_data: data } : {} } function compactQuery(query?: Record): Record | undefined { diff --git a/frontend/shared/api/endpoints.ts b/frontend/shared/api/endpoints.ts index 9cfaefa..bc0f944 100644 --- a/frontend/shared/api/endpoints.ts +++ b/frontend/shared/api/endpoints.ts @@ -32,6 +32,7 @@ export const endpoints = { nodeReview: (nodeId: string) => `nodes/${nodeId}/review`, nodeImages: (nodeId: string) => `nodes/${nodeId}/images`, workflowReview: (workflowId: string) => `workflows/${workflowId}/review`, + images: "images", image: (imageId: string) => `images/${imageId}`, imageSelect: (imageId: string) => `images/${imageId}/select`, imageUnselect: (imageId: string) => `images/${imageId}/unselect`, @@ -42,6 +43,7 @@ export const endpoints = { jobRetry: (taskId: string) => `jobs/${taskId}/retry`, jobDeadLetterRetry: "jobs/dead-letter/retry", jobDeadLetterMoveFailed: "jobs/dead-letter/move-failed", + costUsage: "costs/usage", settingsSchema: "settings/schema", settingsCurrent: "settings/current", settingsValidate: "settings/validate", diff --git a/frontend/shared/types/api.ts b/frontend/shared/types/api.ts index 594d9c2..0f98869 100644 --- a/frontend/shared/types/api.ts +++ b/frontend/shared/types/api.ts @@ -14,3 +14,20 @@ export interface ApiFailure { } export type ApiResponse = ApiSuccess | ApiFailure + +export interface AstrBotApiSuccess { + status: "ok" + data: T + message?: string +} + +export interface AstrBotApiFailure { + status: "error" + data?: unknown + error?: string + error_code?: string + message?: string + details?: Record +} + +export type AstrBotApiResponse = AstrBotApiSuccess | AstrBotApiFailure diff --git a/frontend/shared/types/assets.ts b/frontend/shared/types/assets.ts index 5289aaa..460e9dd 100644 --- a/frontend/shared/types/assets.ts +++ b/frontend/shared/types/assets.ts @@ -23,6 +23,12 @@ export interface AssetImportPlan { manifest: AssetManifestSummary import_enabled: boolean execution_enabled: boolean + unsupported_features?: Array<{ + code: string + message: string + count?: number + [key: string]: unknown + }> applied: { materials: number styles: number diff --git a/frontend/shared/types/cost.ts b/frontend/shared/types/cost.ts new file mode 100644 index 0000000..bc45431 --- /dev/null +++ b/frontend/shared/types/cost.ts @@ -0,0 +1,27 @@ +export interface CostUsageTotals { + image_count: number + task_count: number + total_tokens: number + input_tokens: number + output_tokens: number + estimated_cost: number +} + +export interface CostUsageGroup extends CostUsageTotals { + provider_id: string + provider_model: string + model_route: string +} + +export interface CostUsageSummary { + currency: string + filters: { + profile_id?: string | null + workflow_id?: string | null + node_id?: string | null + provider_id?: string | null + days?: number | null + } + totals: CostUsageTotals + groups: CostUsageGroup[] +} diff --git a/frontend/shared/types/image.ts b/frontend/shared/types/image.ts index 8865235..1e0cbb8 100644 --- a/frontend/shared/types/image.ts +++ b/frontend/shared/types/image.ts @@ -23,6 +23,13 @@ export interface GenerationImage { created_at: string } +export interface ImageListResult { + items: GenerationImage[] + total: number + page: number + page_size: number +} + export interface NodeGenerateResult { task_id?: string | null request_id?: string | null diff --git a/frontend/shared/types/material-operations.ts b/frontend/shared/types/material-operations.ts new file mode 100644 index 0000000..5ef2174 --- /dev/null +++ b/frontend/shared/types/material-operations.ts @@ -0,0 +1,16 @@ +export type MaterialOperationMode = "register-uri" | "asset-pack" | "wardrobe" + +export interface MaterialRegistrationRequest { + image_uri: string + display_name: string + category_id: string + filename: string +} + +export interface AssetPackRequest { + package_uri: string +} + +export interface WardrobeImportRequest { + wardrobe_category: string +} diff --git a/frontend/shared/types/profile.ts b/frontend/shared/types/profile.ts index 1df1f5e..a302bad 100644 --- a/frontend/shared/types/profile.ts +++ b/frontend/shared/types/profile.ts @@ -14,6 +14,7 @@ export interface CharacterProfile { metadata?: Record created_at: string updated_at: string + generation_kind?: "ungenerated" | "quick" | "detailed" } export interface ProfileListResult { diff --git a/frontend/shared/types/ui.ts b/frontend/shared/types/ui.ts index bd47ded..f9bc91d 100644 --- a/frontend/shared/types/ui.ts +++ b/frontend/shared/types/ui.ts @@ -6,3 +6,26 @@ export interface UiAction { requires_permission: string enabled: boolean } + +export interface UiMetricCard { + label: string + value: string + hint: string + state: TState +} + +export interface UiDetailRow { + label: string + value: string +} + +export interface UiActionCard { + id: TId + title: string + detail: string + badge: string + endpoint?: string + action: string + tone: TTone + enabled: boolean +} diff --git a/frontend/shared/types/wardrobe.ts b/frontend/shared/types/wardrobe.ts index 9c5ba5a..360887d 100644 --- a/frontend/shared/types/wardrobe.ts +++ b/frontend/shared/types/wardrobe.ts @@ -14,9 +14,39 @@ export interface WardrobeItem { } export interface WardrobeMatchResult { - profile_id?: string - items?: WardrobeItem[] - matched_items?: WardrobeItem[] - selected?: WardrobeItem | null - [key: string]: unknown + profile_id: string + selected_materials: Array<{ + wardrobe_item_id: string + material_id: string + wardrobe_category: string + display_name: string + prompt?: string | null + tags: string[] + season?: string | null + style?: string | null + is_favorite: boolean + usage_count: number + score: number + score_breakdown: Record + }> + outfit_prompt: string + fallback_used: boolean + fallback_supplement_used: boolean + fallback_reason: "missing_categories" | "no_matching_materials" | null + fallback_prompt?: string | null + fallback_strategy: { + name?: string | null + reason?: string | null + missing_categories: string[] + prompt: string + } + match_details: { + requested_categories: string[] + missing_categories: string[] + matched_count: number + keywords: string[] + requested_tags: string[] + season?: string | null + style?: string | null + } } diff --git a/frontend/shared/utils/collections.ts b/frontend/shared/utils/collections.ts new file mode 100644 index 0000000..d050921 --- /dev/null +++ b/frontend/shared/utils/collections.ts @@ -0,0 +1,13 @@ +export function uniqueBy(items: readonly T[], keyOf: (item: T) => K): T[] { + const seen = new Set() + return items.filter((item) => { + const key = keyOf(item) + if (seen.has(key)) return false + seen.add(key) + return true + }) +} + +export function uniqueStrings(items: readonly string[]): string[] { + return uniqueBy(items, (item) => item) +} diff --git a/frontend/shared/utils/presentation.ts b/frontend/shared/utils/presentation.ts new file mode 100644 index 0000000..5cebbb6 --- /dev/null +++ b/frontend/shared/utils/presentation.ts @@ -0,0 +1,93 @@ +import type { CostUsageSummary } from "../types/cost" +import type { GenerationJob } from "../types/job" + +export function normalizeStatus(status: string): string { + return String(status || "").trim().toLowerCase() +} + +export function statusLabel(status: string): string { + const labels: Record = { + running: "运行中", + degraded: "降级", + stopped: "已停止", + loading: "加载中", + created: "已创建", + pending: "等待中", + queued: "排队中", + completed: "已完成", + succeeded: "已成功", + failed: "失败", + cancelled: "已取消", + dead_letter: "死信", + retrying: "重试执行中", + superseded: "已被重试替代", + } + return labels[normalizeStatus(status)] ?? status +} + +export function statusClass(status: string): "is-bad" | "is-warn" | "is-good" | "is-idle" { + const normalized = normalizeStatus(status) + if (["failed", "dead_letter", "cancelled"].includes(normalized)) return "is-bad" + if (["running", "queued", "created", "pending", "retrying"].includes(normalized)) return "is-warn" + if (["completed", "succeeded"].includes(normalized)) return "is-good" + return "is-idle" +} + +export function formatBytes(value: number): string { + const bytes = Number.isFinite(value) && value > 0 ? value : 0 + if (bytes < 1024) return `${bytes} B` + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB` + if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB` + return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB` +} + +export function formatCostEstimate(summary: CostUsageSummary): string { + const amount = Number(summary.totals.estimated_cost) + const currency = summary.currency || "USD" + try { + return `${new Intl.NumberFormat("zh-CN", { + style: "currency", + currency, + minimumFractionDigits: amount < 1 ? 4 : 2, + maximumFractionDigits: amount < 1 ? 6 : 2, + }).format(amount)} 估算` + } catch { + return `${currency} ${amount.toFixed(amount < 1 ? 6 : 2)} 估算` + } +} + +export function formatTime(value?: string): string { + if (!value) return "-" + const date = new Date(value) + if (Number.isNaN(date.getTime())) return value + return new Intl.DateTimeFormat("zh-CN", { + month: "2-digit", + day: "2-digit", + hour: "2-digit", + minute: "2-digit", + }).format(date) +} + +export function timestamp(value: string): number { + const parsed = Date.parse(value) + return Number.isFinite(parsed) ? parsed : 0 +} + +export function waitTime(job: GenerationJob): string { + const start = timestamp(job.created_at) + if (!start) return "-" + const minutes = Math.max(0, Math.round((Date.now() - start) / 60000)) + if (minutes < 1) return "刚刚" + if (minutes < 60) return `${minutes} 分钟` + return `${Math.round(minutes / 60)} 小时` +} + +export function shortId(value: string): string { + return value.length > 10 ? `${value.slice(0, 6)}...${value.slice(-4)}` : value +} + +export function progressValue(job: GenerationJob): number { + const value = Number(job.progress) + if (!Number.isFinite(value)) return 0 + return Math.max(0, Math.min(100, value)) +} diff --git a/frontend/shared/utils/storage-uri.ts b/frontend/shared/utils/storage-uri.ts new file mode 100644 index 0000000..aefb3dc --- /dev/null +++ b/frontend/shared/utils/storage-uri.ts @@ -0,0 +1,12 @@ +export function isStorageUri(value: string): boolean { + return /^storage:\/\/[a-z0-9_-]+(?:\/[^?#]*)?$/i.test(value.trim()) +} + +export function storageFilename(value: string): string { + const normalized = value.trim().split(/[?#]/, 1)[0].replace(/\/+$/, "") + return normalized.split("/").pop() ?? "" +} + +export function isSupportedImageStorageUri(value: string): boolean { + return isStorageUri(value) && /\.(png|jpe?g|gif|webp)$/i.test(storageFilename(value)) +} diff --git a/frontend/standalone-web/index.html b/frontend/standalone-web/index.html index fa207c8..870ea73 100644 --- a/frontend/standalone-web/index.html +++ b/frontend/standalone-web/index.html @@ -1,2 +1,12 @@ -
- + + + + + + AstrBot ImageStudio + + +
+ + + diff --git a/frontend/standalone-web/src/App.vue b/frontend/standalone-web/src/App.vue index 49e859f..02ba38a 100644 --- a/frontend/standalone-web/src/App.vue +++ b/frontend/standalone-web/src/App.vue @@ -1,20 +1,65 @@ + + diff --git a/frontend/standalone-web/src/components/EmptyState.vue b/frontend/standalone-web/src/components/EmptyState.vue new file mode 100644 index 0000000..0e35bc3 --- /dev/null +++ b/frontend/standalone-web/src/components/EmptyState.vue @@ -0,0 +1,60 @@ + + + + + diff --git a/frontend/standalone-web/src/components/ImagePreviewDialog.vue b/frontend/standalone-web/src/components/ImagePreviewDialog.vue new file mode 100644 index 0000000..2e8c5a8 --- /dev/null +++ b/frontend/standalone-web/src/components/ImagePreviewDialog.vue @@ -0,0 +1,286 @@ + + + + + diff --git a/frontend/standalone-web/src/components/MaterialCategoryCreateDialog.vue b/frontend/standalone-web/src/components/MaterialCategoryCreateDialog.vue new file mode 100644 index 0000000..82c9728 --- /dev/null +++ b/frontend/standalone-web/src/components/MaterialCategoryCreateDialog.vue @@ -0,0 +1,133 @@ + + +