From d514bfc4982b462afbd87864c7e8addb167cdb87 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Sat, 4 Jul 2026 22:51:52 +0800 Subject: [PATCH] chore: initialize v3 plugin scaffold --- .gitignore | 45 + DEVELOPMENT.md | 71 + README.md | 71 + __init__.py | 1 + _conf_schema.json | 12 + adapters/__init__.py | 1 + adapters/astrbot_adapter.py | 1 + adapters/onebot11_adapter.py | 1 + adapters/webui_adapter.py | 1 + adapters/wechat_adapter.py | 1 + assets_builtin/.gitkeep | 1 + assets_builtin/placeholders/.gitkeep | 1 + backend/README.md | 13 + backend/__init__.py | 1 + backend/dto/__init__.py | 1 + backend/dto/common.py | 1 + backend/dto/image_dto.py | 1 + backend/dto/material_dto.py | 1 + backend/dto/profile_dto.py | 1 + backend/dto/wardrobe_dto.py | 1 + backend/dto/workflow_dto.py | 1 + backend/routes/.gitkeep | 1 + backend/services/.gitkeep | 1 + config.yaml | 26 + core/__init__.py | 1 + core/audit_service.py | 1 + core/config_service.py | 1 + core/event_bus.py | 1 + core/fsm.py | 1 + core/identity.py | 1 + core/interactions.py | 1 + core/interop.py | 1 + core/media_proxy.py | 1 + core/model_router.py | 1 + core/prompt_pipeline.py | 1 + core/queue_manager.py | 1 + core/secret_service.py | 1 + core/security.py | 1 + core/storage.py | 1 + core/webhook.py | 1 + data/archives/.gitkeep | 1 + data/db/.gitkeep | 1 + data/exports/.gitkeep | 1 + data/images/.gitkeep | 1 + data/materials/.gitkeep | 1 + data/styles/.gitkeep | 1 + data/temp/.gitkeep | 1 + data/thumbnails/.gitkeep | 1 + database/__init__.py | 1 + database/db_helper.py | 1 + database/migrations/.gitkeep | 1 + database/models.py | 1 + database/repositories/__init__.py | 1 + database/seed.py | 1 + engines/__init__.py | 1 + engines/character_flow.py | 1 + engines/fast_character_flow.py | 1 + engines/quick_profile_flow.py | 1 + engines/review_flow.py | 1 + engines/single_flow.py | 1 + frontend/README.md | 17 + frontend/env.d.ts | 18 + frontend/package.json | 24 + frontend/plugin-page/index.html | 2 + frontend/plugin-page/src/App.vue | 29 + frontend/plugin-page/src/main.ts | 4 + frontend/plugin-page/vite.config.ts | 12 + frontend/shared/api/endpoints.ts | 13 + frontend/shared/components/.gitkeep | 1 + frontend/shared/constants/.gitkeep | 1 + frontend/shared/schemas/.gitkeep | 1 + frontend/shared/stores/.gitkeep | 1 + frontend/shared/types/api.ts | 16 + frontend/shared/types/bootstrap.ts | 21 + frontend/shared/types/dashboard.ts | 19 + frontend/shared/utils/.gitkeep | 1 + frontend/standalone-web/index.html | 2 + frontend/standalone-web/src/App.vue | 67 + frontend/standalone-web/src/main.ts | 4 + frontend/standalone-web/vite.config.ts | 13 + frontend/tsconfig.json | 28 + imagestudio_api_contract_v3_ui_adjusted.md | 580 +++++++ imagestudio_codex_hermes_dev_flow_v3.md | 516 +++++++ ...udio_full_plugin_dev_doc_v3_ui_adjusted.md | 1337 +++++++++++++++++ main.py | 5 + metadata.yaml | 5 + pages/imagestudio/.gitkeep | 1 + web/.gitkeep | 1 + 88 files changed, 3031 insertions(+) create mode 100644 .gitignore create mode 100644 DEVELOPMENT.md create mode 100644 README.md create mode 100644 __init__.py create mode 100644 _conf_schema.json create mode 100644 adapters/__init__.py create mode 100644 adapters/astrbot_adapter.py create mode 100644 adapters/onebot11_adapter.py create mode 100644 adapters/webui_adapter.py create mode 100644 adapters/wechat_adapter.py create mode 100644 assets_builtin/.gitkeep create mode 100644 assets_builtin/placeholders/.gitkeep create mode 100644 backend/README.md create mode 100644 backend/__init__.py create mode 100644 backend/dto/__init__.py create mode 100644 backend/dto/common.py create mode 100644 backend/dto/image_dto.py create mode 100644 backend/dto/material_dto.py create mode 100644 backend/dto/profile_dto.py create mode 100644 backend/dto/wardrobe_dto.py create mode 100644 backend/dto/workflow_dto.py create mode 100644 backend/routes/.gitkeep create mode 100644 backend/services/.gitkeep create mode 100644 config.yaml create mode 100644 core/__init__.py create mode 100644 core/audit_service.py create mode 100644 core/config_service.py create mode 100644 core/event_bus.py create mode 100644 core/fsm.py create mode 100644 core/identity.py create mode 100644 core/interactions.py create mode 100644 core/interop.py create mode 100644 core/media_proxy.py create mode 100644 core/model_router.py create mode 100644 core/prompt_pipeline.py create mode 100644 core/queue_manager.py create mode 100644 core/secret_service.py create mode 100644 core/security.py create mode 100644 core/storage.py create mode 100644 core/webhook.py create mode 100644 data/archives/.gitkeep create mode 100644 data/db/.gitkeep create mode 100644 data/exports/.gitkeep create mode 100644 data/images/.gitkeep create mode 100644 data/materials/.gitkeep create mode 100644 data/styles/.gitkeep create mode 100644 data/temp/.gitkeep create mode 100644 data/thumbnails/.gitkeep create mode 100644 database/__init__.py create mode 100644 database/db_helper.py create mode 100644 database/migrations/.gitkeep create mode 100644 database/models.py create mode 100644 database/repositories/__init__.py create mode 100644 database/seed.py create mode 100644 engines/__init__.py create mode 100644 engines/character_flow.py create mode 100644 engines/fast_character_flow.py create mode 100644 engines/quick_profile_flow.py create mode 100644 engines/review_flow.py create mode 100644 engines/single_flow.py create mode 100644 frontend/README.md create mode 100644 frontend/env.d.ts create mode 100644 frontend/package.json create mode 100644 frontend/plugin-page/index.html create mode 100644 frontend/plugin-page/src/App.vue create mode 100644 frontend/plugin-page/src/main.ts create mode 100644 frontend/plugin-page/vite.config.ts create mode 100644 frontend/shared/api/endpoints.ts create mode 100644 frontend/shared/components/.gitkeep create mode 100644 frontend/shared/constants/.gitkeep create mode 100644 frontend/shared/schemas/.gitkeep create mode 100644 frontend/shared/stores/.gitkeep create mode 100644 frontend/shared/types/api.ts create mode 100644 frontend/shared/types/bootstrap.ts create mode 100644 frontend/shared/types/dashboard.ts create mode 100644 frontend/shared/utils/.gitkeep create mode 100644 frontend/standalone-web/index.html create mode 100644 frontend/standalone-web/src/App.vue create mode 100644 frontend/standalone-web/src/main.ts create mode 100644 frontend/standalone-web/vite.config.ts create mode 100644 frontend/tsconfig.json create mode 100644 imagestudio_api_contract_v3_ui_adjusted.md create mode 100644 imagestudio_codex_hermes_dev_flow_v3.md create mode 100644 imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md create mode 100644 main.py create mode 100644 metadata.yaml create mode 100644 pages/imagestudio/.gitkeep create mode 100644 web/.gitkeep diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5ab3dde --- /dev/null +++ b/.gitignore @@ -0,0 +1,45 @@ +# Python +__pycache__/ +*.py[cod] +.pytest_cache/ +.ruff_cache/ +.mypy_cache/ +.venv/ +venv/ + +# Node / frontend +node_modules/ +frontend/**/node_modules/ +frontend/**/dist/ +*.tsbuildinfo + +# AstrBot ImageStudio runtime data +data/db/* +data/images/* +data/thumbnails/* +data/materials/* +data/styles/* +data/archives/* +data/temp/* +data/exports/* +!data/db/.gitkeep +!data/images/.gitkeep +!data/thumbnails/.gitkeep +!data/materials/.gitkeep +!data/styles/.gitkeep +!data/archives/.gitkeep +!data/temp/.gitkeep +!data/exports/.gitkeep + +# Built static assets generated by frontend builds +pages/imagestudio/assets/ +web/assets/ + +# Local machine/editor noise +.env +.env.* +!.env.example +.DS_Store +Thumbs.db +.idea/ +.vscode/ diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..f6d4953 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,71 @@ +# Development Environment + +## Scope + +The repository is currently prepared for v3 `S0-1`. + +Prepared: + +- AstrBot plugin root files and v3 configuration placeholders. +- v3 top-level module layout: `adapters`, `core`, `engines`, `backend`, `database`, `assets_builtin`, `frontend`, `pages`, `web`, and `data`. +- Frontend source skeleton for Plugin Page UI and Standalone Web UI. +- Runtime data directories with `.gitkeep` files only. +- Generated data, local virtual environments, node modules, and build artifacts are ignored. + +Not implemented yet: + +- AstrBot adapter registration. +- Common response DTO and error handling. +- Request context, permission checks, and audit logger. +- Database migrations, repositories, and services. +- P0 API routes. +- Real UI screens beyond scaffold placeholders. + +## Local Tools + +On this machine, PowerShell blocks `npm.ps1`; use `npm.cmd` when needed. + +Codex bundled tools are also available: + +```text +C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe +C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\bin\pnpm.cmd +``` + +## First Tasks + +Follow `imagestudio_codex_hermes_dev_flow_v3.md` and continue with: + +```text +S0-2 实现 common response DTO +S0-3 实现 request_id / audit logger 基础工具 +S1-1 实现 character_profiles 表、Repository、Service +S1-2 实现 profile_workflows 和 workflow_nodes +S1-3 实现 generation_images +``` + +## P0 Frozen API Checklist + +P0 must implement these before expanding into advanced flows: + +```text +ui/bootstrap +dashboard/summary +profiles GET/POST/GET_ONE/PUT +profiles/quick-draft +profiles/{profile_id}/workflows GET/POST +workflows/{workflow_id} +workflows/{workflow_id}/nodes +nodes/{node_id}/generate +nodes/{node_id}/images +images/{image_id} +images/{image_id}/select +jobs +jobs/{task_id} +settings/schema +settings/current +storage/status +media/sign +``` + +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/README.md b/README.md new file mode 100644 index 0000000..b38d7ca --- /dev/null +++ b/README.md @@ -0,0 +1,71 @@ +# AstrBot ImageStudio + +AstrBot ImageStudio is an AstrBot role asset production and image-generation workspace plugin. + +It provides two UI surfaces: + +- AstrBot Plugin Page UI for lightweight status, queue, recent jobs, and quick entry points. +- Standalone Web UI mounted under AstrBot's plugin extension route for the full workspace. + +Both UIs share one backend API, database, queue model, VFS media layer, material library, wardrobe system, and audit trail. + +## Development Baseline + +Use the v3 documents as the source of truth: + +1. `imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md` +2. `imagestudio_api_contract_v3_ui_adjusted.md` +3. `imagestudio_codex_hermes_dev_flow_v3.md` + +Older v0.1 planning is superseded by v3. In v3, the central fact chain is: + +```text +character_profiles + -> profile_workflows + -> workflow_nodes + -> generation_tasks + -> generation_images +``` + +## Current Stage + +This repository is aligned to `S0-1`: v3 directory and configuration baseline. + +Next tasks: + +1. `S0-2` common response DTO. +2. `S0-3` request id and audit logger foundation. +3. `S1-1` `character_profiles` table, repository, and service. +4. `S1-2` `profile_workflows` and `workflow_nodes`. +5. `S1-3` `generation_images`. + +## Repository Layout + +```text +main.py +metadata.yaml +_conf_schema.json +config.yaml +adapters/ +core/ +engines/ +backend/ +database/ +assets_builtin/ +pages/imagestudio/ +web/ +frontend/ +data/ +``` + +The root directory is the plugin repository root. Do not introduce a second backend service or a standalone web port. + +## Non-Negotiable Rules + +- Standalone Web UI must be served by AstrBot plugin extension routes. +- Plugin Page UI and Standalone Web UI must call the same backend API. +- Frontend code must not read or construct real disk paths. +- API keys and tokens must not be returned to the frontend in plain text. +- Every write operation must record `audit_logs`. +- Generated images must have `generation_images` records. +- Media access must go through signed media APIs. diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..0868925 --- /dev/null +++ b/__init__.py @@ -0,0 +1 @@ +"""AstrBot ImageStudio plugin package.""" diff --git a/_conf_schema.json b/_conf_schema.json new file mode 100644 index 0000000..02e2994 --- /dev/null +++ b/_conf_schema.json @@ -0,0 +1,12 @@ +{ + "default_generation_model": { + "description": "Default model used for image generation.", + "type": "string", + "default": "" + }, + "enable_private_companion_integration": { + "description": "Allow integration calls from astrbot_plugin_private_companion.", + "type": "bool", + "default": false + } +} diff --git a/adapters/__init__.py b/adapters/__init__.py new file mode 100644 index 0000000..79e43e3 --- /dev/null +++ b/adapters/__init__.py @@ -0,0 +1 @@ +"""Runtime adapters for AstrBot, chat platforms, and Web UI integration.""" diff --git a/adapters/astrbot_adapter.py b/adapters/astrbot_adapter.py new file mode 100644 index 0000000..07ebc40 --- /dev/null +++ b/adapters/astrbot_adapter.py @@ -0,0 +1 @@ +"""AstrBot runtime adapter placeholder.""" diff --git a/adapters/onebot11_adapter.py b/adapters/onebot11_adapter.py new file mode 100644 index 0000000..15e1e1f --- /dev/null +++ b/adapters/onebot11_adapter.py @@ -0,0 +1 @@ +"""OneBot v11 adapter placeholder.""" diff --git a/adapters/webui_adapter.py b/adapters/webui_adapter.py new file mode 100644 index 0000000..9526c2b --- /dev/null +++ b/adapters/webui_adapter.py @@ -0,0 +1 @@ +"""AstrBot WebUI adapter placeholder.""" diff --git a/adapters/wechat_adapter.py b/adapters/wechat_adapter.py new file mode 100644 index 0000000..798f68d --- /dev/null +++ b/adapters/wechat_adapter.py @@ -0,0 +1 @@ +"""WeChat adapter placeholder.""" diff --git a/assets_builtin/.gitkeep b/assets_builtin/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/assets_builtin/.gitkeep @@ -0,0 +1 @@ + diff --git a/assets_builtin/placeholders/.gitkeep b/assets_builtin/placeholders/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/assets_builtin/placeholders/.gitkeep @@ -0,0 +1 @@ + diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..6408f69 --- /dev/null +++ b/backend/README.md @@ -0,0 +1,13 @@ +# Backend + +The backend exposes v3 P0 APIs through AstrBot plugin extension routes. + +Initial backend tasks: + +- 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. + +Do not start a separate web server. Register routes through AstrBot plugin extension APIs. diff --git a/backend/__init__.py b/backend/__init__.py new file mode 100644 index 0000000..78ace69 --- /dev/null +++ b/backend/__init__.py @@ -0,0 +1 @@ +"""Backend package for AstrBot ImageStudio.""" diff --git a/backend/dto/__init__.py b/backend/dto/__init__.py new file mode 100644 index 0000000..99ad22f --- /dev/null +++ b/backend/dto/__init__.py @@ -0,0 +1 @@ +"""Data transfer objects for ImageStudio backend APIs.""" diff --git a/backend/dto/common.py b/backend/dto/common.py new file mode 100644 index 0000000..cb8dcdb --- /dev/null +++ b/backend/dto/common.py @@ -0,0 +1 @@ +"""Common API DTO placeholder.""" diff --git a/backend/dto/image_dto.py b/backend/dto/image_dto.py new file mode 100644 index 0000000..f0bfb86 --- /dev/null +++ b/backend/dto/image_dto.py @@ -0,0 +1 @@ +"""Image DTO placeholder.""" diff --git a/backend/dto/material_dto.py b/backend/dto/material_dto.py new file mode 100644 index 0000000..0b06565 --- /dev/null +++ b/backend/dto/material_dto.py @@ -0,0 +1 @@ +"""Material DTO placeholder.""" diff --git a/backend/dto/profile_dto.py b/backend/dto/profile_dto.py new file mode 100644 index 0000000..cadedf5 --- /dev/null +++ b/backend/dto/profile_dto.py @@ -0,0 +1 @@ +"""Profile DTO placeholder.""" diff --git a/backend/dto/wardrobe_dto.py b/backend/dto/wardrobe_dto.py new file mode 100644 index 0000000..f15998a --- /dev/null +++ b/backend/dto/wardrobe_dto.py @@ -0,0 +1 @@ +"""Wardrobe DTO placeholder.""" diff --git a/backend/dto/workflow_dto.py b/backend/dto/workflow_dto.py new file mode 100644 index 0000000..0925957 --- /dev/null +++ b/backend/dto/workflow_dto.py @@ -0,0 +1 @@ +"""Workflow DTO placeholder.""" diff --git a/backend/routes/.gitkeep b/backend/routes/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/backend/routes/.gitkeep @@ -0,0 +1 @@ + diff --git a/backend/services/.gitkeep b/backend/services/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/backend/services/.gitkeep @@ -0,0 +1 @@ + diff --git a/config.yaml b/config.yaml new file mode 100644 index 0000000..4abc3a3 --- /dev/null +++ b/config.yaml @@ -0,0 +1,26 @@ +plugin: + name: astrbot_plugin_imagestudio + display_name: ImageStudio + version: 3.0.0 + +features: + quick_profile: true + workspace: true + material_library: true + wardrobe: true + api_discovery: true + private_companion_integration: false + +storage: + db_path: data/db/imagestudio.db + images_path: data/images + thumbnails_path: data/thumbnails + materials_path: data/materials + styles_path: data/styles + archives_path: data/archives + temp_path: data/temp + +security: + integration_token_set: false + allowed_integration_plugins: + - astrbot_plugin_private_companion diff --git a/core/__init__.py b/core/__init__.py new file mode 100644 index 0000000..4b7e716 --- /dev/null +++ b/core/__init__.py @@ -0,0 +1 @@ +"""Core services shared by ImageStudio engines and APIs.""" diff --git a/core/audit_service.py b/core/audit_service.py new file mode 100644 index 0000000..2bf1db5 --- /dev/null +++ b/core/audit_service.py @@ -0,0 +1 @@ +"""Audit logging service placeholder.""" diff --git a/core/config_service.py b/core/config_service.py new file mode 100644 index 0000000..98df480 --- /dev/null +++ b/core/config_service.py @@ -0,0 +1 @@ +"""Configuration service placeholder.""" diff --git a/core/event_bus.py b/core/event_bus.py new file mode 100644 index 0000000..2f3ccf8 --- /dev/null +++ b/core/event_bus.py @@ -0,0 +1 @@ +"""In-process event bus placeholder.""" diff --git a/core/fsm.py b/core/fsm.py new file mode 100644 index 0000000..cf02f12 --- /dev/null +++ b/core/fsm.py @@ -0,0 +1 @@ +"""Workflow finite-state-machine helpers placeholder.""" diff --git a/core/identity.py b/core/identity.py new file mode 100644 index 0000000..c79eb67 --- /dev/null +++ b/core/identity.py @@ -0,0 +1 @@ +"""Identity and request actor helpers placeholder.""" diff --git a/core/interactions.py b/core/interactions.py new file mode 100644 index 0000000..1ef734f --- /dev/null +++ b/core/interactions.py @@ -0,0 +1 @@ +"""Interaction menu and user action helpers placeholder.""" diff --git a/core/interop.py b/core/interop.py new file mode 100644 index 0000000..be0b694 --- /dev/null +++ b/core/interop.py @@ -0,0 +1 @@ +"""External plugin interoperability placeholder.""" diff --git a/core/media_proxy.py b/core/media_proxy.py new file mode 100644 index 0000000..d6b7dae --- /dev/null +++ b/core/media_proxy.py @@ -0,0 +1 @@ +"""Signed media URL helpers placeholder.""" diff --git a/core/model_router.py b/core/model_router.py new file mode 100644 index 0000000..6632eff --- /dev/null +++ b/core/model_router.py @@ -0,0 +1 @@ +"""Model route selection placeholder.""" diff --git a/core/prompt_pipeline.py b/core/prompt_pipeline.py new file mode 100644 index 0000000..341ff0b --- /dev/null +++ b/core/prompt_pipeline.py @@ -0,0 +1 @@ +"""Prompt composition pipeline placeholder.""" diff --git a/core/queue_manager.py b/core/queue_manager.py new file mode 100644 index 0000000..4272978 --- /dev/null +++ b/core/queue_manager.py @@ -0,0 +1 @@ +"""Generation queue manager placeholder.""" diff --git a/core/secret_service.py b/core/secret_service.py new file mode 100644 index 0000000..010c70e --- /dev/null +++ b/core/secret_service.py @@ -0,0 +1 @@ +"""Secret management placeholder.""" diff --git a/core/security.py b/core/security.py new file mode 100644 index 0000000..97e3754 --- /dev/null +++ b/core/security.py @@ -0,0 +1 @@ +"""Security and permission helpers placeholder.""" diff --git a/core/storage.py b/core/storage.py new file mode 100644 index 0000000..97b5313 --- /dev/null +++ b/core/storage.py @@ -0,0 +1 @@ +"""VFS storage helpers placeholder.""" diff --git a/core/webhook.py b/core/webhook.py new file mode 100644 index 0000000..2302afd --- /dev/null +++ b/core/webhook.py @@ -0,0 +1 @@ +"""Webhook dispatch placeholder.""" diff --git a/data/archives/.gitkeep b/data/archives/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/archives/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/db/.gitkeep b/data/db/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/db/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/exports/.gitkeep b/data/exports/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/exports/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/images/.gitkeep b/data/images/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/images/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/materials/.gitkeep b/data/materials/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/materials/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/styles/.gitkeep b/data/styles/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/styles/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/temp/.gitkeep b/data/temp/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/temp/.gitkeep @@ -0,0 +1 @@ + diff --git a/data/thumbnails/.gitkeep b/data/thumbnails/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/data/thumbnails/.gitkeep @@ -0,0 +1 @@ + diff --git a/database/__init__.py b/database/__init__.py new file mode 100644 index 0000000..fcfb97c --- /dev/null +++ b/database/__init__.py @@ -0,0 +1 @@ +"""Database models, helpers, migrations, and repositories.""" diff --git a/database/db_helper.py b/database/db_helper.py new file mode 100644 index 0000000..01538de --- /dev/null +++ b/database/db_helper.py @@ -0,0 +1 @@ +"""Database connection and migration helper placeholder.""" diff --git a/database/migrations/.gitkeep b/database/migrations/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/database/migrations/.gitkeep @@ -0,0 +1 @@ + diff --git a/database/models.py b/database/models.py new file mode 100644 index 0000000..f845b96 --- /dev/null +++ b/database/models.py @@ -0,0 +1 @@ +"""SQL model definitions placeholder.""" diff --git a/database/repositories/__init__.py b/database/repositories/__init__.py new file mode 100644 index 0000000..c55f87e --- /dev/null +++ b/database/repositories/__init__.py @@ -0,0 +1 @@ +"""Repository implementations for ImageStudio persistence.""" diff --git a/database/seed.py b/database/seed.py new file mode 100644 index 0000000..db29f95 --- /dev/null +++ b/database/seed.py @@ -0,0 +1 @@ +"""Seed data helpers placeholder.""" diff --git a/engines/__init__.py b/engines/__init__.py new file mode 100644 index 0000000..88eecfc --- /dev/null +++ b/engines/__init__.py @@ -0,0 +1 @@ +"""ImageStudio workflow engines.""" diff --git a/engines/character_flow.py b/engines/character_flow.py new file mode 100644 index 0000000..2bbdb29 --- /dev/null +++ b/engines/character_flow.py @@ -0,0 +1 @@ +"""Gradual character workflow engine placeholder.""" diff --git a/engines/fast_character_flow.py b/engines/fast_character_flow.py new file mode 100644 index 0000000..f49ee52 --- /dev/null +++ b/engines/fast_character_flow.py @@ -0,0 +1 @@ +"""Fast character package workflow engine placeholder.""" diff --git a/engines/quick_profile_flow.py b/engines/quick_profile_flow.py new file mode 100644 index 0000000..f22da23 --- /dev/null +++ b/engines/quick_profile_flow.py @@ -0,0 +1 @@ +"""Quick profile draft workflow placeholder.""" diff --git a/engines/review_flow.py b/engines/review_flow.py new file mode 100644 index 0000000..319db3a --- /dev/null +++ b/engines/review_flow.py @@ -0,0 +1 @@ +"""Review and stability-check workflow placeholder.""" diff --git a/engines/single_flow.py b/engines/single_flow.py new file mode 100644 index 0000000..2a15ef2 --- /dev/null +++ b/engines/single_flow.py @@ -0,0 +1 @@ +"""Single image workflow engine placeholder.""" diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..4306d1c --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,17 @@ +# Frontend + +The frontend contains two Vite applications: + +- `plugin-page/`: builds into `../pages/imagestudio`. +- `standalone-web/`: builds into `../web`. + +Shared API clients, types, stores, components, constants, schemas, and utilities live in `shared/`. + +Dependencies are declared in `package.json` but not installed yet. + +Both UIs must consume the same v3 API contract: + +- Plugin Page UI uses `window.AstrBotPluginPage`. +- 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 new file mode 100644 index 0000000..a821121 --- /dev/null +++ b/frontend/env.d.ts @@ -0,0 +1,18 @@ +/// + +declare module "*.vue" { + import type { DefineComponent } from "vue" + + const component: DefineComponent, Record, unknown> + export default component +} + +interface Window { + AstrBotPluginPage?: { + 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/package.json b/frontend/package.json new file mode 100644 index 0000000..a5a00a4 --- /dev/null +++ b/frontend/package.json @@ -0,0 +1,24 @@ +{ + "name": "astrbot-plugin-imagestudio-frontend", + "version": "3.0.0", + "private": true, + "type": "module", + "scripts": { + "dev:plugin": "vite --config plugin-page/vite.config.ts", + "dev:web": "vite --config standalone-web/vite.config.ts", + "build:plugin": "vite build --config plugin-page/vite.config.ts", + "build:web": "vite build --config standalone-web/vite.config.ts", + "build": "npm run build:plugin && npm run build:web", + "typecheck": "vue-tsc --noEmit" + }, + "dependencies": { + "@vitejs/plugin-vue": "^5.2.0", + "pinia": "^2.3.0", + "typescript": "^5.7.0", + "vite": "^6.0.0", + "vue": "^3.5.0", + "vue-router": "^4.5.0", + "vue-tsc": "^2.2.0" + }, + "devDependencies": {} +} diff --git a/frontend/plugin-page/index.html b/frontend/plugin-page/index.html new file mode 100644 index 0000000..fa207c8 --- /dev/null +++ b/frontend/plugin-page/index.html @@ -0,0 +1,2 @@ +
+ diff --git a/frontend/plugin-page/src/App.vue b/frontend/plugin-page/src/App.vue new file mode 100644 index 0000000..6855d06 --- /dev/null +++ b/frontend/plugin-page/src/App.vue @@ -0,0 +1,29 @@ + + + diff --git a/frontend/plugin-page/src/main.ts b/frontend/plugin-page/src/main.ts new file mode 100644 index 0000000..1d22108 --- /dev/null +++ b/frontend/plugin-page/src/main.ts @@ -0,0 +1,4 @@ +import { createApp } from "vue" +import App from "./App.vue" + +createApp(App).mount("#app") diff --git a/frontend/plugin-page/vite.config.ts b/frontend/plugin-page/vite.config.ts new file mode 100644 index 0000000..5774ee0 --- /dev/null +++ b/frontend/plugin-page/vite.config.ts @@ -0,0 +1,12 @@ +import { resolve } from "node:path" +import vue from "@vitejs/plugin-vue" +import { defineConfig } from "vite" + +export default defineConfig({ + plugins: [vue()], + root: __dirname, + build: { + outDir: resolve(__dirname, "../../pages/imagestudio"), + emptyOutDir: true, + }, +}) diff --git a/frontend/shared/api/endpoints.ts b/frontend/shared/api/endpoints.ts new file mode 100644 index 0000000..c07e7ea --- /dev/null +++ b/frontend/shared/api/endpoints.ts @@ -0,0 +1,13 @@ +export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio" + +export const endpoints = { + uiBootstrap: "ui/bootstrap", + dashboardSummary: "dashboard/summary", + profiles: "profiles", + quickProfileDraft: "profiles/quick-draft", + jobs: "jobs", + settingsSchema: "settings/schema", + settingsCurrent: "settings/current", + storageStatus: "storage/status", + mediaSign: "media/sign", +} as const diff --git a/frontend/shared/components/.gitkeep b/frontend/shared/components/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/frontend/shared/components/.gitkeep @@ -0,0 +1 @@ + diff --git a/frontend/shared/constants/.gitkeep b/frontend/shared/constants/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/frontend/shared/constants/.gitkeep @@ -0,0 +1 @@ + diff --git a/frontend/shared/schemas/.gitkeep b/frontend/shared/schemas/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/frontend/shared/schemas/.gitkeep @@ -0,0 +1 @@ + diff --git a/frontend/shared/stores/.gitkeep b/frontend/shared/stores/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/frontend/shared/stores/.gitkeep @@ -0,0 +1 @@ + diff --git a/frontend/shared/types/api.ts b/frontend/shared/types/api.ts new file mode 100644 index 0000000..594d9c2 --- /dev/null +++ b/frontend/shared/types/api.ts @@ -0,0 +1,16 @@ +export interface ApiSuccess { + ok: true + data: T + warnings: string[] + request_id?: string +} + +export interface ApiFailure { + ok: false + error_code: string + message: string + details?: Record + request_id?: string +} + +export type ApiResponse = ApiSuccess | ApiFailure diff --git a/frontend/shared/types/bootstrap.ts b/frontend/shared/types/bootstrap.ts new file mode 100644 index 0000000..2b552ac --- /dev/null +++ b/frontend/shared/types/bootstrap.ts @@ -0,0 +1,21 @@ +export interface UiBootstrap { + plugin_name: "astrbot_plugin_imagestudio" + display_name: string + plugin_version: string + dashboard_user: string | null + permissions: { + can_read: boolean + can_write: boolean + can_manage_config: boolean + can_manage_materials: boolean + can_retry_tasks: boolean + } + feature_flags: { + quick_profile: boolean + workspace: boolean + material_library: boolean + wardrobe: boolean + api_discovery: boolean + } + api_base: string +} diff --git a/frontend/shared/types/dashboard.ts b/frontend/shared/types/dashboard.ts new file mode 100644 index 0000000..f5f2c70 --- /dev/null +++ b/frontend/shared/types/dashboard.ts @@ -0,0 +1,19 @@ +export interface DashboardSummary { + plugin_status: "running" | "degraded" | "stopped" + today_generation_count: number + active_profiles: number + queue: { + pending: number + running: number + failed: number + dead_letter: number + } + storage: { + total_bytes: number + images_bytes: number + materials_bytes: number + temp_bytes: number + } + recent_jobs: unknown[] + recent_images: unknown[] +} diff --git a/frontend/shared/utils/.gitkeep b/frontend/shared/utils/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/frontend/shared/utils/.gitkeep @@ -0,0 +1 @@ + diff --git a/frontend/standalone-web/index.html b/frontend/standalone-web/index.html new file mode 100644 index 0000000..fa207c8 --- /dev/null +++ b/frontend/standalone-web/index.html @@ -0,0 +1,2 @@ +
+ diff --git a/frontend/standalone-web/src/App.vue b/frontend/standalone-web/src/App.vue new file mode 100644 index 0000000..e530a5d --- /dev/null +++ b/frontend/standalone-web/src/App.vue @@ -0,0 +1,67 @@ + + + diff --git a/frontend/standalone-web/src/main.ts b/frontend/standalone-web/src/main.ts new file mode 100644 index 0000000..1d22108 --- /dev/null +++ b/frontend/standalone-web/src/main.ts @@ -0,0 +1,4 @@ +import { createApp } from "vue" +import App from "./App.vue" + +createApp(App).mount("#app") diff --git a/frontend/standalone-web/vite.config.ts b/frontend/standalone-web/vite.config.ts new file mode 100644 index 0000000..02b1aac --- /dev/null +++ b/frontend/standalone-web/vite.config.ts @@ -0,0 +1,13 @@ +import { resolve } from "node:path" +import vue from "@vitejs/plugin-vue" +import { defineConfig } from "vite" + +export default defineConfig({ + plugins: [vue()], + root: __dirname, + base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/", + build: { + outDir: resolve(__dirname, "../../web"), + emptyOutDir: true, + }, +}) diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json new file mode 100644 index 0000000..9bf0e8e --- /dev/null +++ b/frontend/tsconfig.json @@ -0,0 +1,28 @@ +{ + "compilerOptions": { + "target": "ES2022", + "useDefineForClassFields": true, + "module": "ESNext", + "moduleResolution": "Bundler", + "strict": true, + "jsx": "preserve", + "resolveJsonModule": true, + "isolatedModules": true, + "esModuleInterop": true, + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "types": ["vite/client"], + "baseUrl": ".", + "paths": { + "@shared/*": ["shared/*"] + } + }, + "include": [ + "env.d.ts", + "plugin-page/src/**/*.ts", + "plugin-page/src/**/*.vue", + "standalone-web/src/**/*.ts", + "standalone-web/src/**/*.vue", + "shared/**/*.ts", + "shared/**/*.vue" + ] +} diff --git a/imagestudio_api_contract_v3_ui_adjusted.md b/imagestudio_api_contract_v3_ui_adjusted.md new file mode 100644 index 0000000..b620c9b --- /dev/null +++ b/imagestudio_api_contract_v3_ui_adjusted.md @@ -0,0 +1,580 @@ +# AstrBot ImageStudio API 契约与前后端对接文档 v3.0 + +> 生成日期:2026-07-04 +> 本文件给前端、后端、Codex、Hermes 共用。 +> 目标:冻结 P0-P2 的前后端接口,避免 UI 和后端各自跑偏。 + +--- + +## 1. 基础路径 + +Standalone Web 直接调用: + +```text +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/{endpoint} +``` + +Plugin Page 通过 Bridge 调用: + +```js +await window.AstrBotPluginPage.apiGet("{endpoint}") +await window.AstrBotPluginPage.apiPost("{endpoint}", payload) +``` + +--- + +## 2. 通用响应 + +### 成功 + +```json +{ + "ok": true, + "data": {}, + "warnings": [], + "request_id": "req_xxx" +} +``` + +### 失败 + +```json +{ + "ok": false, + "error_code": "ERROR_CODE", + "message": "用户可理解错误", + "details": {}, + "request_id": "req_xxx" +} +``` + +### 通用错误码 + +```text +UNAUTHORIZED +FORBIDDEN +VALIDATION_FAILED +RESOURCE_NOT_FOUND +CONFIG_REVISION_CONFLICT +TASK_NOT_RETRYABLE +TASK_NOT_CANCELABLE +MODEL_CAPABILITY_UNCONFIRMED +MODEL_CAPABILITY_UNSUPPORTED +STORAGE_WRITE_FAILED +MEDIA_NOT_FOUND +UPLOAD_TOO_LARGE +UNSUPPORTED_FILE_TYPE +INTEGRATION_TOKEN_INVALID +UNKNOWN_ERROR +``` + +--- + +## 3. UI Bootstrap + +```http +GET ui/bootstrap +``` + +响应: + +```json +{ + "plugin_name": "astrbot_plugin_imagestudio", + "display_name": "ImageStudio", + "plugin_version": "3.0.0", + "dashboard_user": "admin", + "permissions": { + "can_read": true, + "can_write": true, + "can_manage_config": true, + "can_manage_materials": true, + "can_retry_tasks": true + }, + "feature_flags": { + "quick_profile": true, + "workspace": true, + "material_library": true, + "wardrobe": true, + "api_discovery": true + }, + "api_base": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio" +} +``` + +--- + +## 4. Dashboard + +```http +GET dashboard/summary +``` + +响应 data: + +```json +{ + "plugin_status": "running", + "today_generation_count": 0, + "active_profiles": 0, + "queue": { + "pending": 0, + "running": 0, + "failed": 0, + "dead_letter": 0 + }, + "storage": { + "total_bytes": 0, + "images_bytes": 0, + "materials_bytes": 0, + "temp_bytes": 0 + }, + "recent_jobs": [], + "recent_images": [] +} +``` + +--- + +## 5. Profiles + +### List + +```http +GET profiles?keyword=&status=active&page=1&page_size=30 +``` + +### Create + +```http +POST profiles +``` + +请求: + +```json +{ + "name": "莉娅", + "description": "银白发少女", + "base_prompt": "", + "appearance_prompt": "", + "style_prompt": "", + "negative_prompt": "", + "default_model_route": "image_low" +} +``` + +### Quick Draft + +```http +POST profiles/quick-draft +``` + +请求: + +```json +{ + "questionnaire": { + "name": "莉娅", + "identity": "魔法学院学生", + "personality": ["温柔", "安静"], + "hair_color": "银白色", + "hairstyle": "长发", + "eye_color": "蓝色", + "style": "二次元厚涂", + "clothing_keywords": ["白色上衣", "蓝色短裙"] + } +} +``` + +响应 data: + +```json +{ + "draft_id": "draft_xxx", + "profile_preview": { + "name": "莉娅", + "base_prompt": "...", + "appearance_prompt": "...", + "style_prompt": "...", + "negative_prompt": "..." + } +} +``` + +### Detail / Update / Delete + +```http +GET profiles/{profile_id} +PUT profiles/{profile_id} +DELETE profiles/{profile_id} +``` + +--- + +## 6. Workflows + +### List by Profile + +```http +GET profiles/{profile_id}/workflows +``` + +### Create + +```http +POST profiles/{profile_id}/workflows +``` + +请求: + +```json +{ + "workflow_type": "single_image", + "display_name": "单图流 2026-07-04", + "mode": "quick" +} +``` + +### Detail + +```http +GET workflows/{workflow_id} +``` + +### Start / Cancel / Archive + +```http +POST workflows/{workflow_id}/start +POST workflows/{workflow_id}/cancel +POST workflows/{workflow_id}/archive +``` + +--- + +## 7. Nodes + +### List + +```http +GET workflows/{workflow_id}/nodes +``` + +### Generate + +```http +POST nodes/{node_id}/generate +``` + +请求: + +```json +{ + "prompt_patch": "衣服改成白色衬衫", + "material_ids": ["mat_001"], + "model_route": "image_low", + "count": 4, + "aspect_ratio": "3:4", + "quality": "low" +} +``` + +响应 data: + +```json +{ + "task_id": "task_xxx", + "node_status": "queued" +} +``` + +### Select Image + +```http +POST nodes/{node_id}/select-image +``` + +请求: + +```json +{ + "image_id": "img_001" +} +``` + +--- + +## 8. Images + +```http +GET nodes/{node_id}/images +GET images/{image_id} +POST images/{image_id}/select +POST images/{image_id}/unselect +POST images/{image_id}/archive +DELETE images/{image_id} +``` + +响应 data: + +```json +{ + "image_id": "img_001", + "thumbnail_url": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch?token=xxx", + "image_url": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch?token=yyy", + "positive_prompt": "...", + "negative_prompt": "...", + "model_used": "model_x", + "seed": 123, + "width": 1024, + "height": 1536, + "is_selected": true, + "created_at": "2026-07-04T22:00:00+09:00" +} +``` + +--- + +## 9. Material Categories + +```http +GET material-categories +POST material-categories +PUT material-categories/{category_id} +DELETE material-categories/{category_id} +``` + +系统分类 seed: + +```json +[ + {"name": "画风", "parent_id": null}, + {"name": "发色", "parent_id": null}, + {"name": "发型", "parent_id": null}, + {"name": "上衣", "parent_id": null}, + {"name": "下装", "parent_id": null}, + {"name": "连衣裙", "parent_id": null}, + {"name": "袜子", "parent_id": null}, + {"name": "鞋子", "parent_id": null}, + {"name": "配饰", "parent_id": null}, + {"name": "头饰", "parent_name": "配饰"}, + {"name": "胸饰", "parent_name": "配饰"}, + {"name": "腿饰", "parent_name": "配饰"} +] +``` + +--- + +## 10. Materials + +```http +GET materials?category_id=&keyword=&page=1&page_size=30 +POST materials +GET materials/{material_id} +PUT materials/{material_id} +DELETE materials/{material_id} +POST materials/upload +POST materials/{material_id}/recognize +POST materials/{material_id}/confirm +``` + +### Upload + +multipart form: + +```text +file= +category_id=cat_upper +``` + +响应 data: + +```json +{ + "material_id": "mat_001", + "status": "pending_recognition", + "image_url": "...", + "thumbnail_url": "..." +} +``` + +### Confirm + +```json +{ + "display_name": "白色短袖衬衫", + "prompt": "white short-sleeve blouse, clean collar", + "negative_prompt": "body, face, background", + "tags": ["上衣", "白色", "短袖"] +} +``` + +--- + +## 11. Wardrobe + +```http +GET profiles/{profile_id}/wardrobe +POST profiles/{profile_id}/wardrobe/import-material +DELETE profiles/{profile_id}/wardrobe/items/{wardrobe_item_id} +POST profiles/{profile_id}/wardrobe/match +``` + +### Import Material + +```json +{ + "material_id": "mat_001", + "wardrobe_category": "上衣", + "tags": ["夏季", "白色", "清爽"], + "season": "summer", + "style": "daily" +} +``` + +### Match + +```json +{ + "keywords": ["夏季", "白色"], + "scene": "daily", + "weather": "sunny" +} +``` + +--- + +## 12. private_companion Integration + +```http +POST integrations/private-companion/daily-outfit +``` + +Header: + +```text +X-ImageStudio-Integration-Token: *** +``` + +请求: + +```json +{ + "profile_id": "profile_001", + "character_name": "莉娅", + "scene": "daily", + "mood": "relaxed", + "weather": "sunny", + "keywords": ["夏季", "白色", "清爽"], + "request_source": "astrbot_plugin_private_companion" +} +``` + +响应: + +```json +{ + "matched": true, + "selected_materials": [], + "final_prompt": "...", + "job_id": "task_xxx" +} +``` + +--- + +## 13. Jobs + +```http +GET jobs?status=&workflow_id=&profile_id=&page=1&page_size=30 +GET jobs/{task_id} +POST jobs/{task_id}/cancel +POST jobs/{task_id}/retry +``` + +--- + +## 14. Logs + +```http +GET logs/generation +GET logs/workflows +GET logs/errors +GET logs/integrations +GET security/audit-logs +``` + +--- + +## 15. Settings + +```http +GET settings/schema +GET settings/current +POST settings/validate +POST settings/diff +POST settings/save +POST settings/reload +``` + +--- + +## 16. Media + +```http +GET media/sign?uri=storage://... +GET media/fetch?token=... +``` + +禁止前端直接传真实路径。 + +--- + +## 17. SSE + +```http +GET events/stream +``` + +事件样例: + +```text +event: image.created +data: {"image_id":"img_001","node_id":"node_001"} +``` + +--- + +## 18. P0 接口冻结清单 + +P0 必须先实现: + +```text +ui/bootstrap +dashboard/summary +profiles GET/POST/GET_ONE/PUT +profiles/quick-draft +profiles/{profile_id}/workflows GET/POST +workflows/{workflow_id} +workflows/{workflow_id}/nodes +nodes/{node_id}/generate +nodes/{node_id}/images +images/{image_id} +images/{image_id}/select +jobs +jobs/{task_id} +settings/schema +settings/current +storage/status +media/sign +``` + +P0 暂不强制实现: + +```text +api-discovery/probe-model +assets/import-pack +storage/migrate +advanced review policy editor +dead letter batch retry +``` diff --git a/imagestudio_codex_hermes_dev_flow_v3.md b/imagestudio_codex_hermes_dev_flow_v3.md new file mode 100644 index 0000000..630e525 --- /dev/null +++ b/imagestudio_codex_hermes_dev_flow_v3.md @@ -0,0 +1,516 @@ +# AstrBot ImageStudio Codex / Hermes 开发流程指南 v3.0 + +> 生成日期:2026-07-04 +> 目标:让 Codex / Hermes 能按正确顺序读懂并实现插件,不跑偏、不乱改、不单独起端口。 + +--- + +## 1. 代理分工 + +### Codex + +定位:主代码实现代理。 + +适合: + +```text +数据库模型 +Repository / Service / Route +接口实现 +队列逻辑 +单元测试 +前端组件实现 +Bug 修复 +``` + +### Hermes + +定位:需求整理和二次审查代理。 + +适合: + +```text +需求归纳 +开发任务拆解 +文档维护 +UI 与后端契约检查 +验收清单 +代码审查提示 +``` + +### 禁止 + +```text +禁止 Codex 和 Hermes 同时修改同一分支。 +禁止一次性要求代理“实现整个插件”。 +禁止把真实 API Key / Cookie / Token 发给代理。 +禁止让代理擅自启动独立 Web 端口。 +``` + +--- + +## 2. 推荐阅读顺序 + +交给 Codex 或 Hermes 前,按此顺序提供文档: + +```text +1. imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md +2. imagestudio_api_contract_v3_ui_adjusted.md +3. imagestudio_codex_hermes_dev_flow_v3.md +4. 原始后端 PRD v2:astrbot_imagestudio_prd_v2_engineering.md +5. UI 需求:生图插件的UI界面.md +``` + +如果上下文容量不足,优先给 1、2、3。 + +--- + +## 3. 分支策略 + +```text +main +├── feature/p0-db-models-codex +├── feature/p0-api-routes-codex +├── feature/p0-plugin-page-ui-codex +├── feature/p0-standalone-web-ui-codex +├── docs/ui-contract-hermes +└── review/p0-audit-hermes +``` + +规则: + +1. 一个任务一个分支。 +2. 一个代理一次只处理一个任务。 +3. 合并前必须人工看 diff。 +4. 合并前必须运行测试。 +5. 数据库迁移必须单独审查。 + +--- + +## 4. 开发阶段总览 + +### Stage 0:仓库初始化 + +目标: + +```text +建立目录结构 +建立配置文件 +建立测试框架 +建立基础 DB helper +建立通用响应格式 +``` + +交给 Codex 的任务: + +```text +任务 S0-1:创建项目目录结构和空模块。 +任务 S0-2:实现 common response DTO。 +任务 S0-3:实现 request_id / audit logger 基础工具。 +``` + +--- + +### Stage 1:数据库与 Repository + +目标: + +```text +实现 UI 必需事实表。 +``` + +优先表: + +```text +character_profiles +profile_workflows +workflow_nodes +generation_images +material_categories +materials +wardrobe_items +workflow_sessions +generation_tasks +media_files +audit_logs +``` + +Codex 任务示例: + +```text +任务 S1-1: +实现 character_profiles 表、Repository、Service。 +不得修改 UI。 +验收:能创建、查询、更新、软删除 profile。 + +任务 S1-2: +实现 profile_workflows 和 workflow_nodes。 +验收:一个 profile 下能创建 workflow,workflow 下能列出 nodes。 + +任务 S1-3: +实现 generation_images。 +验收:能按 node_id 查询图片卡片,支持 selected 状态。 +``` + +--- + +### Stage 2:Web API 注册 + +目标: + +```text +所有 P0 API 可被 Plugin Page Bridge 和 Standalone Web 调用。 +``` + +任务: + +```text +S2-1 ui/bootstrap +S2-2 dashboard/summary +S2-3 profiles CRUD +S2-4 workflows + nodes +S2-5 images +S2-6 jobs +S2-7 settings schema/current +S2-8 media sign/fetch +``` + +验收: + +```text +- 所有 API 返回统一 JSON。 +- 401/403/404/422/500 错误格式统一。 +- 写接口记录 audit_logs。 +``` + +--- + +### Stage 3:双 UI 挂载 + +目标: + +```text +Plugin Page UI 和 Standalone Web UI 都能打开。 +``` + +Codex 任务: + +```text +S3-1: +实现 pages/imagestudio/index.html 轻量 UI。 +只显示 dashboard summary、queue、recent jobs、打开完整工作台按钮。 + +S3-2: +实现 web/index.html 静态挂载。 +不单独起端口。 +路径为 /api/v1/plugins/extensions/astrbot_plugin_imagestudio/web。 + +S3-3: +实现 PluginPageClient 和 DirectWebClient。 +``` + +验收: + +```text +- AstrBot 插件页内可打开轻量 UI。 +- 浏览器可直接打开 /web。 +- 两个 UI 调用同一个 dashboard/summary。 +``` + +--- + +### Stage 4:单图流闭环 + +目标: + +```text +用户可以从 Web UI 创建单图流、提交生成、查看图片卡片。 +``` + +任务: + +```text +S4-1 single_flow engine +S4-2 nodes/{node_id}/generate +S4-3 queue_manager 基础队列 +S4-4 generation_tasks 状态迁移 +S4-5 image_service 保存 VFS + thumbnail +S4-6 selected image 状态 +``` + +验收: + +```text +- 至少支持 mock backend。 +- 任务状态 CREATED -> QUEUED -> RUNNING -> SUCCEEDED。 +- 图片卡片展示 prompt/model/seed。 +``` + +--- + +### Stage 5:角色工作流 + +目标: + +```text +角色档案驱动的标准角色流和专业角色流。 +``` + +任务: + +```text +S5-1 quick_profile_service +S5-2 character_flow 标准模式节点生成 +S5-3 professional 八阶段节点模板 +S5-4 workflow_history 采纳图写入 +S5-5 回溯 / 另开方案 +S5-6 review_flow 轻量稳定性检查 +``` + +验收: + +```text +- 快速人设问卷可生成 profile。 +- 角色流节点可显示和推进。 +- 已选择图有特殊状态。 +``` + +--- + +### Stage 6:素材区 + +目标: + +```text +素材分类、上传、识别、确认入库。 +``` + +任务: + +```text +S6-1 seed material_categories +S6-2 material list/detail +S6-3 upload material +S6-4 recognition mock / VLM adapter +S6-5 confirm material +S6-6 custom accessory categories +``` + +验收: + +```text +- 上传素材后进入 pending_confirm。 +- 用户确认后进入指定分类。 +- 卡片可查看素材 prompt。 +``` + +--- + +### Stage 7:角色衣橱与扩展 + +目标: + +```text +实现 wardrobe 和 private_companion 每日穿搭联动。 +``` + +任务: + +```text +S7-1 wardrobe_items +S7-2 从素材库加入衣橱 +S7-3 wardrobe match +S7-4 daily-outfit integration endpoint +S7-5 fallback random prompt +S7-6 integration logs +``` + +验收: + +```text +- 外部插件请求命中衣橱。 +- 未命中时走随机提示词。 +- 日志区能查看联动事件。 +``` + +--- + +### Stage 8:高级配置与 API Discovery + +目标: + +```text +完成模型配置、能力探测、RenderPlan 校验、Review 策略。 +``` + +任务: + +```text +S8-1 config_service +S8-2 secret_service +S8-3 models/providers +S8-4 api-discovery/probe-provider safe 模式 +S8-5 backend_capability_profiles +S8-6 validate-render-plan +S8-7 review/policies +``` + +验收: + +```text +- safe 探测不产生费用。 +- unknown 不等同于 false。 +- Secret 不回显。 +``` + +--- + +## 5. 交给 Codex 的标准任务模板 + +```text +当前任务编号:Sx-y + +任务目标: +<一句话描述> + +必须阅读: +- imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md 第 X 章 +- imagestudio_api_contract_v3_ui_adjusted.md 第 X 章 + +允许修改文件: +- path/to/file1.py +- path/to/file2.py + +禁止修改文件: +- config.yaml +- unrelated modules +- frontend/* (如果是纯后端任务) + +接口契约: +<复制相关 API 请求/响应> + +实现要求: +1. 使用统一响应格式。 +2. 写接口必须记录 audit_logs。 +3. 不得明文处理 Secret。 +4. 不得启动独立端口。 +5. 重复请求必须考虑幂等。 + +验收方式: +- pytest xxx +- 手动调用 endpoint xxx +- 检查数据库记录 xxx + +完成后输出: +1. 修改了哪些文件。 +2. 实现了哪些接口。 +3. 如何测试。 +4. 是否涉及数据库迁移。 +5. 已知限制。 +``` + +--- + +## 6. 代码审查清单 + +每个 PR 必查: + +```text +[ ] 是否单独起了新端口? +[ ] 是否绕过 AstrBot register_web_api? +[ ] 是否有真实 API Key / Token 泄露? +[ ] 是否有绝对磁盘路径进入数据库? +[ ] 是否有写接口未鉴权? +[ ] 是否有写接口未写 audit_logs? +[ ] 是否有删除操作绕过二阶段删除? +[ ] 是否有图片文件无 media_files 记录? +[ ] 是否有生成图片无 generation_images 记录? +[ ] 是否有任务无 generation_tasks 记录? +[ ] 是否破坏通用响应格式? +[ ] 是否新增 API 但没更新 API 契约? +[ ] 是否让 unknown capability 等同 false? +[ ] 是否让重复点击创建重复任务? +``` + +--- + +## 7. Hermes 审查提示词 + +```text +请作为需求审查代理,检查本次实现是否符合 ImageStudio v3 UI 调整版开发文档。 + +重点检查: +1. UI 需求是否都有后端事实表支撑。 +2. Profile / Workflow / Node / Image Card 是否闭环。 +3. 素材区上传识别确认是否闭环。 +4. 是否违反“不单独起端口”定案。 +5. 是否遗漏角色衣橱或 private_companion 联动。 +6. 是否存在 Secret / 权限 / 审计风险。 +7. 是否有未更新 API 契约的接口变化。 + +请输出: +- 通过项 +- 风险项 +- 必须修复项 +- 可延后项 +``` + +--- + +## 8. Codex 首轮推荐任务顺序 + +```text +1. S0-1 建立目录结构 +2. S1-1 character_profiles +3. S1-2 profile_workflows + workflow_nodes +4. S1-3 generation_images +5. S2-1 ui/bootstrap +6. S2-2 dashboard/summary +7. S3-1 Plugin Page UI +8. S3-2 Standalone Web UI 挂载 +9. S4-1 Single Image mock flow +10. S4-2 图片卡片 selected 状态 +``` + +做到第 10 步,插件已经具备 UI 原型闭环。 + +--- + +## 9. 严格禁止项 + +```text +禁止实现时另起端口。 +禁止把 Standalone Web UI 做成外部独立服务。 +禁止把 Plugin Page UI 和 Standalone Web UI 做成两套业务后端。 +禁止让 UI 直接读写本地文件。 +禁止在前端保存 API Key。 +禁止跳过任务表直接调用模型。 +禁止图片生成成功但不写 generation_images。 +禁止素材上传后直接入库而不确认。 +禁止删除真实文件前不写 delete_pending。 +禁止 Codex 自行扩大任务范围。 +``` + +--- + +## 10. 最小可运行验收 + +P0 最小验收命令或步骤: + +```text +1. 启动 AstrBot。 +2. 安装插件。 +3. 打开插件详情页 ImageStudio Plugin Page。 +4. 能看到仪表盘。 +5. 点击“打开完整工作台”。 +6. 浏览器打开 /web 页面。 +7. 新建角色档案。 +8. 创建单图流工作流。 +9. 创建一个节点。 +10. mock 生成一张图片卡片。 +11. 查看图片详情 prompt/model。 +12. 选择该图片,卡片边框状态变化。 +13. 查看 audit_logs 有对应记录。 +``` + +完成以上步骤后,再进入真实模型调用和高级能力。 diff --git a/imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md b/imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md new file mode 100644 index 0000000..87103bf --- /dev/null +++ b/imagestudio_full_plugin_dev_doc_v3_ui_adjusted.md @@ -0,0 +1,1337 @@ +# AstrBot ImageStudio 完整插件开发文档 v3.0(UI 需求调整版) + +> 生成日期:2026-07-04 +> 适用对象:AstrBot ImageStudio 生图插件本体、Plugin Page UI、Standalone Web UI、后端服务、Codex/Hermes 开发代理。 +> 来源合并: +> 1. 《AstrBot ImageStudio 三轨智能生图插件工程化研发规范 v2.0》 +> 2. 《生图插件的 UI 界面.md》 +> 3. 已定案架构:两套 UI,不单独起端口,均挂载在 AstrBot 服务下。 + +--- + +## 0. 本次审查结论 + +原 v2 后端文档的优势很明显: + +- 三轨工作流设计完整。 +- 任务生命周期、状态持久化、幂等、Webhook、安全、VFS、分支、Review、API Discovery 都已经工程化。 +- 已经具备中台插件的后端基础。 + +但根据 UI 需求重新审查后,必须调整的地方是: + +1. 原文档偏 **Session / Workflow Session 驱动**,而 UI 需要 **角色档案 Profile 驱动**。 +2. 原文档有 `workflow_history`,但 UI 需要显式的 **工作流节点 Node** 和 **图片卡片 Image Card**。 +3. 原文档有 `assets`,但 UI 需要 **分类树 + 素材卡片 + 上传识别确认入库**。 +4. 原文档有 `characters`,但 UI 需要先有可编辑的 **角色档案**,归档角色只是后续产物。 +5. 原文档有 Plugin Page 设置页,但当前定案是 **两套 UI**: + - AstrBot Plugin Page 内轻量 UI。 + - AstrBot 下挂载的完整 Standalone Web UI。 +6. 原文档有 Interop API,但 UI 需求明确需要和 `astrbot_plugin_private_companion` 的每日穿搭联动,所以必须补充 **角色衣橱 Wardrobe** 和 **每日穿搭请求协议**。 + +因此,v3.0 的后端必须从“任务中台”扩展为: + +```text +角色档案 Profile + -> 工作流 Workspace Workflow + -> 节点 Workflow Node + -> 生成任务 Generation Task + -> 图片卡片 Generation Image + -> 素材库 Material Library + -> 角色衣橱 Wardrobe + -> 日志审计 Audit / Logs + -> 双 UI 入口 +``` + +--- + +## 1. 产品定位 + +AstrBot ImageStudio 是一个面向 QQ / 微信 / Web UI / AstrBot Plugin Page 的 AI 生图中台插件。 + +它不是简单的聊天生图机器人,而是一个“角色资产生产与管理工作台”。 + +核心能力: + +1. 自由单图生成。 +2. 快速人设问卷生成角色档案。 +3. 渐进式角色人设工作流。 +4. 快速直出角色包。 +5. 素材库与画风库。 +6. 多节点工作流与图片卡片选择。 +7. 角色衣橱与每日穿搭插件联动。 +8. 队列、日志、存储、设置、模型能力探测。 +9. Plugin Page 轻量入口 + Standalone Web 完整工作台。 + +--- + +## 2. 双 UI 架构定案 + +### 2.1 UI 类型 + +本插件提供两套 UI。 + +```text +UI 1:AstrBot Plugin Page UI +- 集成在 AstrBot 插件详情页内。 +- 轻量管理面板。 +- 用于状态概览、队列、最近任务、基础设置、打开完整工作台。 + +UI 2:Standalone Web UI +- 不单独起端口。 +- 挂载在 AstrBot 插件 Web API 路径下。 +- 是完整 ImageStudio 工作台。 +``` + +### 2.2 不允许的实现方式 + +```text +禁止: +- 为 Standalone Web UI 单独启动 FastAPI / Flask / Uvicorn 端口。 +- 插件页 UI 和 Web UI 各自维护一套后端。 +- 前端直接读取 Dashboard Cookie、LocalStorage 或父页面 DOM。 +- 前端直接访问磁盘路径。 +- 前端明文展示或保存 API Key。 +``` + +### 2.3 推荐 URL + +实际外部访问路径由 AstrBot 插件 Web API 命名空间承载: + +```text +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/assets/* +``` + +Plugin Page 文件路径: + +```text +pages/imagestudio/index.html +``` + +Standalone Web 静态文件路径: + +```text +web/index.html +web/assets/* +``` + +--- + +## 3. 总体目录结构 + +```text +astrbot_plugin_imagestudio/ +├── __init__.py +├── main.py +├── metadata.yaml +├── _conf_schema.json +├── config.yaml +│ +├── pages/ +│ └── imagestudio/ +│ ├── index.html # Plugin Page 轻量 UI +│ ├── app.js +│ ├── style.css +│ └── assets/ +│ +├── web/ +│ ├── index.html # Standalone Web UI 构建产物 +│ ├── assets/ +│ └── favicon.ico +│ +├── frontend/ +│ ├── plugin-page/ # Plugin Page UI 源码 +│ ├── standalone-web/ # 完整 Web UI 源码 +│ └── shared/ +│ ├── api/ +│ │ ├── PluginPageClient.ts +│ │ ├── DirectWebClient.ts +│ │ └── types.ts +│ ├── components/ +│ └── schemas/ +│ +├── adapters/ +│ ├── astrbot_adapter.py +│ ├── onebot11_adapter.py +│ ├── wechat_adapter.py +│ └── webui_adapter.py +│ +├── core/ +│ ├── identity.py +│ ├── security.py +│ ├── fsm.py +│ ├── interactions.py +│ ├── queue_manager.py +│ ├── model_router.py +│ ├── prompt_pipeline.py +│ ├── storage.py +│ ├── media_proxy.py +│ ├── webhook.py +│ ├── config_service.py +│ ├── secret_service.py +│ ├── audit_service.py +│ ├── event_bus.py +│ └── interop.py +│ +├── engines/ +│ ├── single_flow.py +│ ├── character_flow.py +│ ├── fast_character_flow.py +│ ├── quick_profile_flow.py +│ └── review_flow.py +│ +├── backend/ +│ ├── routes/ +│ │ ├── web_routes.py +│ │ ├── ui_routes.py +│ │ ├── dashboard_routes.py +│ │ ├── profile_routes.py +│ │ ├── workflow_routes.py +│ │ ├── node_routes.py +│ │ ├── image_routes.py +│ │ ├── material_routes.py +│ │ ├── wardrobe_routes.py +│ │ ├── job_routes.py +│ │ ├── log_routes.py +│ │ ├── setting_routes.py +│ │ ├── discovery_routes.py +│ │ └── integration_routes.py +│ │ +│ ├── services/ +│ │ ├── dashboard_service.py +│ │ ├── profile_service.py +│ │ ├── quick_profile_service.py +│ │ ├── workflow_service.py +│ │ ├── node_service.py +│ │ ├── image_service.py +│ │ ├── material_service.py +│ │ ├── recognition_service.py +│ │ ├── wardrobe_service.py +│ │ ├── generation_service.py +│ │ ├── queue_service.py +│ │ ├── settings_service.py +│ │ └── integration_service.py +│ │ +│ └── dto/ +│ ├── common.py +│ ├── profile_dto.py +│ ├── workflow_dto.py +│ ├── image_dto.py +│ ├── material_dto.py +│ └── wardrobe_dto.py +│ +├── database/ +│ ├── models.py +│ ├── db_helper.py +│ ├── repositories/ +│ ├── migrations/ +│ └── seed.py +│ +├── assets_builtin/ +│ ├── missing.png +│ └── placeholders/ +│ +└── data/ + ├── db/ + ├── images/ + ├── thumbnails/ + ├── materials/ + ├── styles/ + ├── archives/ + └── temp/ +``` + +--- + +## 4. UI 与后端的核心映射 + +| UI 模块 | 后端必须提供 | +|---|---| +| 仪表盘 | dashboard summary、queue summary、storage status、recent jobs | +| 快速人设 | questionnaire schema、quick profile draft、profile save | +| 工作台左栏档案 | profile CRUD、profile search | +| 工作台中栏工作流/节点 | profile workflows、workflow nodes、node status | +| 工作台右栏节点详情 | node detail、node images、image metadata | +| 图片卡片 | image thumbnail、prompt、model、selected 状态 | +| 单图流 | single image workflow,可无 UI 节点,但后端需有 virtual node | +| 素材区分类树 | material categories CRUD | +| 素材卡片 | materials list/detail、prompt/tags、thumbnail | +| 上传识别入库 | upload、recognize、confirm、save | +| 日志区 | workflow logs、generation logs、queue logs、integration logs | +| 设置区 | settings schema、config current/save/validate/diff | +| 扩展区 | wardrobe、private_companion daily outfit integration | + +--- + +## 5. 数据模型调整 + +### 5.1 原 v2 模型保留 + +以下表继续保留: + +```text +workflow_sessions +generation_tasks +generation_batches +workflow_branches +workflow_history +prompt_versions +review_history +assets +asset_vectors +styles +characters +media_files +interaction_menus +quota_usage +backend_capability_profiles +backend_probe_runs +audit_logs +``` + +### 5.2 必须新增的 UI 支撑表 + +#### 5.2.1 character_profiles + +角色档案是 UI 工作台根对象。它不同于原 `characters` 表。 + +- `character_profiles`:编辑中的角色档案,可反复修改。 +- `characters`:归档后的角色资产,可作为最终发布产物。 + +```sql +CREATE TABLE character_profiles ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + profile_id VARCHAR(128) NOT NULL UNIQUE, + name VARCHAR(128) NOT NULL, + description TEXT DEFAULT NULL, + base_prompt TEXT DEFAULT NULL, + appearance_prompt TEXT DEFAULT NULL, + style_prompt TEXT DEFAULT NULL, + negative_prompt TEXT DEFAULT NULL, + default_model_route VARCHAR(128) DEFAULT NULL, + owner_platform VARCHAR(32) NOT NULL, + owner_context_id VARCHAR(128) DEFAULT NULL, + owner_user_id VARCHAR(128) NOT NULL, + owner_session_key VARCHAR(128) DEFAULT NULL, + avatar_image_uri VARCHAR(512) DEFAULT NULL, + status VARCHAR(32) DEFAULT 'active', + metadata_json TEXT DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +CREATE INDEX idx_profiles_owner ON character_profiles(owner_platform, owner_user_id); +CREATE INDEX idx_profiles_status ON character_profiles(status); +``` + +#### 5.2.2 profile_workflows + +UI 工作台内的工作流实例。 + +```sql +CREATE TABLE profile_workflows ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + workflow_id VARCHAR(128) NOT NULL UNIQUE, + profile_id VARCHAR(128) NOT NULL, + workflow_type VARCHAR(32) NOT NULL, + display_name VARCHAR(128) NOT NULL, + mode VARCHAR(32) DEFAULT NULL, + status VARCHAR(32) DEFAULT 'draft', + current_node_id VARCHAR(128) DEFAULT NULL, + current_branch VARCHAR(64) DEFAULT 'main', + session_key VARCHAR(128) DEFAULT NULL, + metadata_json TEXT DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(profile_id) REFERENCES character_profiles(profile_id) ON DELETE CASCADE +); +CREATE INDEX idx_profile_workflows_profile ON profile_workflows(profile_id, workflow_type, status); +``` + +#### 5.2.3 workflow_nodes + +UI 中栏可见节点。 + +```sql +CREATE TABLE workflow_nodes ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + node_id VARCHAR(128) NOT NULL UNIQUE, + workflow_id VARCHAR(128) NOT NULL, + node_key VARCHAR(64) NOT NULL, + title VARCHAR(128) NOT NULL, + description TEXT DEFAULT NULL, + step_name VARCHAR(64) DEFAULT NULL, + node_type VARCHAR(64) DEFAULT 'generation', + status VARCHAR(32) DEFAULT 'draft', + branch_name VARCHAR(64) DEFAULT 'main', + prompt TEXT DEFAULT NULL, + negative_prompt TEXT DEFAULT NULL, + model_route VARCHAR(128) DEFAULT NULL, + selected_image_id VARCHAR(128) DEFAULT NULL, + sort_order INTEGER DEFAULT 0, + metadata_json TEXT DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(workflow_id) REFERENCES profile_workflows(workflow_id) ON DELETE CASCADE +); +CREATE INDEX idx_nodes_workflow ON workflow_nodes(workflow_id, sort_order); +CREATE INDEX idx_nodes_status ON workflow_nodes(status); +``` + +#### 5.2.4 generation_images + +UI 图片卡片事实表。不得只依赖 `workflow_history`,因为未选中的候选图也要展示、删除、查看 prompt。 + +```sql +CREATE TABLE generation_images ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + image_id VARCHAR(128) NOT NULL UNIQUE, + profile_id VARCHAR(128) DEFAULT NULL, + workflow_id VARCHAR(128) DEFAULT NULL, + node_id VARCHAR(128) DEFAULT NULL, + task_id VARCHAR(128) DEFAULT NULL, + batch_id VARCHAR(128) DEFAULT NULL, + version_tag VARCHAR(64) DEFAULT NULL, + image_uri VARCHAR(512) NOT NULL, + thumbnail_uri VARCHAR(512) DEFAULT NULL, + positive_prompt TEXT DEFAULT NULL, + negative_prompt TEXT DEFAULT NULL, + model_used VARCHAR(128) DEFAULT NULL, + model_route VARCHAR(128) DEFAULT NULL, + seed BIGINT DEFAULT NULL, + width INTEGER DEFAULT NULL, + height INTEGER DEFAULT NULL, + is_selected BOOLEAN DEFAULT FALSE, + is_archived BOOLEAN DEFAULT FALSE, + metadata_json TEXT DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(profile_id) REFERENCES character_profiles(profile_id) ON DELETE SET NULL, + FOREIGN KEY(workflow_id) REFERENCES profile_workflows(workflow_id) ON DELETE SET NULL, + FOREIGN KEY(node_id) REFERENCES workflow_nodes(node_id) ON DELETE SET NULL +); +CREATE INDEX idx_images_node ON generation_images(node_id, created_at); +CREATE INDEX idx_images_profile ON generation_images(profile_id, created_at); +CREATE INDEX idx_images_selected ON generation_images(workflow_id, node_id, is_selected); +``` + +#### 5.2.5 material_categories + +素材区分类树。 + +```sql +CREATE TABLE material_categories ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + category_id VARCHAR(128) NOT NULL UNIQUE, + parent_id VARCHAR(128) DEFAULT NULL, + name VARCHAR(128) NOT NULL, + category_type VARCHAR(64) DEFAULT 'material', + is_system BOOLEAN DEFAULT FALSE, + sort_order INTEGER DEFAULT 0, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +CREATE INDEX idx_material_categories_parent ON material_categories(parent_id, sort_order); +``` + +系统内置分类: + +```text +画风 +发色 +发型 +上衣 +下装 +连衣裙 +袜子 +鞋子 +配饰 + - 头饰 + - 胸饰 + - 腿饰 +``` + +#### 5.2.6 materials + +UI 素材卡片表。它可以与原 `assets` 表合并,也可以作为 `assets` 的 UI 包装层。MVP 建议先建独立表,后续再做兼容映射。 + +```sql +CREATE TABLE materials ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + material_id VARCHAR(128) NOT NULL UNIQUE, + category_id VARCHAR(128) NOT NULL, + display_name VARCHAR(128) DEFAULT NULL, + image_uri VARCHAR(512) DEFAULT NULL, + thumbnail_uri VARCHAR(512) DEFAULT NULL, + prompt TEXT DEFAULT NULL, + negative_prompt TEXT DEFAULT NULL, + tags_json TEXT DEFAULT NULL, + source_type VARCHAR(32) DEFAULT 'upload', + recognition_status VARCHAR(32) DEFAULT 'confirmed', + linked_asset_namespace_id VARCHAR(128) DEFAULT NULL, + owner_session_key VARCHAR(128) DEFAULT NULL, + metadata_json TEXT DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(category_id) REFERENCES material_categories(category_id) +); +CREATE INDEX idx_materials_category ON materials(category_id, created_at); +CREATE INDEX idx_materials_status ON materials(recognition_status); +``` + +状态: + +```text +pending_upload +pending_recognition +pending_confirm +confirmed +archived +``` + +#### 5.2.7 wardrobe_items + +角色衣橱。 + +```sql +CREATE TABLE wardrobe_items ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + wardrobe_item_id VARCHAR(128) NOT NULL UNIQUE, + profile_id VARCHAR(128) NOT NULL, + material_id VARCHAR(128) NOT NULL, + wardrobe_category VARCHAR(64) NOT NULL, + tags_json TEXT DEFAULT NULL, + season VARCHAR(64) DEFAULT NULL, + style VARCHAR(64) DEFAULT NULL, + is_favorite BOOLEAN DEFAULT FALSE, + usage_count INTEGER DEFAULT 0, + last_used_at TIMESTAMP DEFAULT NULL, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY(profile_id) REFERENCES character_profiles(profile_id) ON DELETE CASCADE, + FOREIGN KEY(material_id) REFERENCES materials(material_id) ON DELETE CASCADE +); +CREATE INDEX idx_wardrobe_profile ON wardrobe_items(profile_id, wardrobe_category); +``` + +### 5.3 原表字段补充 + +为了让 UI 与任务系统关联,以下原表必须加字段: + +```sql +ALTER TABLE workflow_sessions ADD COLUMN profile_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE generation_tasks ADD COLUMN profile_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE generation_tasks ADD COLUMN ui_workflow_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE generation_tasks ADD COLUMN node_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE workflow_history ADD COLUMN profile_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE workflow_history ADD COLUMN ui_workflow_id VARCHAR(128) DEFAULT NULL; +ALTER TABLE workflow_history ADD COLUMN node_id VARCHAR(128) DEFAULT NULL; +``` + +--- + +## 6. 后端 Web API 规范 + +### 6.1 命名空间 + +所有业务接口挂在: + +```text +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/* +``` + +Plugin Page 内通过 Bridge 调用时使用相对 endpoint。 + +例如: + +```js +bridge.apiGet("dashboard/summary") +``` + +Standalone Web UI 使用直接 HTTP: + +```js +fetch("/api/v1/plugins/extensions/astrbot_plugin_imagestudio/dashboard/summary") +``` + +### 6.2 通用响应 + +```json +{ + "ok": true, + "data": {}, + "warnings": [], + "request_id": "req_xxx" +} +``` + +错误: + +```json +{ + "ok": false, + "error_code": "VALIDATION_FAILED", + "message": "用户可理解的错误信息", + "details": {}, + "request_id": "req_xxx" +} +``` + +--- + +## 7. UI Hosting 接口 + +```http +GET /web +GET /web/assets/{asset_path} +GET /ui/bootstrap +``` + +`/ui/bootstrap` 返回: + +```json +{ + "plugin_name": "astrbot_plugin_imagestudio", + "version": "3.0.0", + "ui_mode": "plugin_page | standalone", + "dashboard_user": "admin", + "permissions": { + "can_manage_config": true, + "can_manage_profiles": true, + "can_manage_materials": true, + "can_retry_tasks": true + }, + "feature_flags": { + "quick_profile": true, + "workspace": true, + "material_library": true, + "wardrobe": true, + "private_companion_integration": true + }, + "api_base": "/api/v1/plugins/extensions/astrbot_plugin_imagestudio" +} +``` + +--- + +## 8. Dashboard API + +```http +GET /dashboard/summary +``` + +返回: + +```json +{ + "plugin_status": "running", + "today_generation_count": 18, + "active_profiles": 5, + "queue": { + "pending": 3, + "running": 1, + "failed": 2, + "dead_letter": 0 + }, + "storage": { + "total_bytes": 1024000000, + "images_bytes": 800000000, + "materials_bytes": 180000000, + "temp_bytes": 44000000 + }, + "recent_jobs": [], + "recent_images": [] +} +``` + +--- + +## 9. Profile API + +```http +GET /profiles +POST /profiles +GET /profiles/{profile_id} +PUT /profiles/{profile_id} +DELETE /profiles/{profile_id} +POST /profiles/quick-draft +POST /profiles/{profile_id}/archive +``` + +快速人设草稿: + +```json +{ + "questionnaire": { + "name": "莉娅", + "hair_color": "银白色", + "style": "二次元厚涂", + "personality": ["安静", "温柔", "神秘"] + } +} +``` + +返回: + +```json +{ + "draft_id": "draft_001", + "profile_preview": { + "name": "莉娅", + "base_prompt": "...", + "appearance_prompt": "...", + "style_prompt": "...", + "negative_prompt": "..." + } +} +``` + +--- + +## 10. Workspace Workflow API + +```http +GET /profiles/{profile_id}/workflows +POST /profiles/{profile_id}/workflows +GET /workflows/{workflow_id} +PUT /workflows/{workflow_id} +POST /workflows/{workflow_id}/start +POST /workflows/{workflow_id}/cancel +POST /workflows/{workflow_id}/archive +``` + +支持工作流类型: + +```text +single_image +character_gradual +character_fast +quick_profile +``` + +角色流模式: + +```text +quick +standard +professional +``` + +--- + +## 11. Workflow Node API + +```http +GET /workflows/{workflow_id}/nodes +POST /workflows/{workflow_id}/nodes +GET /nodes/{node_id} +PUT /nodes/{node_id} +POST /nodes/{node_id}/generate +POST /nodes/{node_id}/retry +POST /nodes/{node_id}/select-image +POST /nodes/{node_id}/mark-completed +``` + +节点状态: + +```text +draft +queued +running +completed +selected +failed +skipped +discarded +``` + +--- + +## 12. Image Card API + +```http +GET /nodes/{node_id}/images +GET /images/{image_id} +POST /images/{image_id}/select +POST /images/{image_id}/unselect +POST /images/{image_id}/archive +DELETE /images/{image_id} +``` + +图片详情必须包含: + +```json +{ + "image_id": "img_001", + "image_url": "/media/sign?...", + "thumbnail_url": "/media/sign?...", + "prompt": "masterpiece, 1girl...", + "negative_prompt": "bad hands...", + "model_used": "xxx", + "seed": 123456, + "width": 1024, + "height": 1536, + "is_selected": true, + "created_at": "2026-07-04T22:00:00+09:00" +} +``` + +--- + +## 13. Material Library API + +### 13.1 分类 + +```http +GET /material-categories +POST /material-categories +PUT /material-categories/{category_id} +DELETE /material-categories/{category_id} +``` + +### 13.2 素材 + +```http +GET /materials?category_id=xxx&keyword=xxx +POST /materials +GET /materials/{material_id} +PUT /materials/{material_id} +DELETE /materials/{material_id} +``` + +### 13.3 上传识别确认入库 + +```http +POST /materials/upload +POST /materials/{material_id}/recognize +POST /materials/{material_id}/confirm +POST /materials/{material_id}/re-recognize +``` + +上传后的标准链路: + +```text +选择分类 + -> 上传图片 + -> 生成 media file + -> 创建 material pending_recognition + -> VLM 识别 + -> pending_confirm + -> UI 展示确认卡 + -> 用户确认或编辑 + -> confirmed 入库 +``` + +--- + +## 14. Wardrobe API 与 private_companion 联动 + +### 14.1 角色衣橱 + +```http +GET /profiles/{profile_id}/wardrobe +POST /profiles/{profile_id}/wardrobe/items +DELETE /profiles/{profile_id}/wardrobe/items/{wardrobe_item_id} +POST /profiles/{profile_id}/wardrobe/import-material +POST /profiles/{profile_id}/wardrobe/match +``` + +### 14.2 每日穿搭联动 + +```http +POST /integrations/private-companion/daily-outfit +``` + +请求: + +```json +{ + "profile_id": "profile_001", + "scene": "daily", + "mood": "relaxed", + "weather": "sunny", + "keywords": ["夏季", "清爽", "白色"] +} +``` + +返回命中衣橱: + +```json +{ + "matched": true, + "selected_materials": [ + { + "material_id": "mat_001", + "category": "上衣", + "prompt": "white blouse, short sleeves" + } + ], + "final_prompt": "1girl, white blouse, summer daily outfit...", + "job_id": "job_001" +} +``` + +未命中: + +```json +{ + "matched": false, + "fallback": "random_prompt_generation", + "final_prompt": "1girl, random summer outfit...", + "job_id": "job_002" +} +``` + +--- + +## 15. Jobs / Queue / SSE API + +```http +GET /jobs +GET /jobs/{task_id} +POST /jobs/{task_id}/cancel +POST /jobs/{task_id}/retry +GET /events/stream +``` + +SSE 事件: + +```text +task.created +task.queued +task.running +task.progress +task.completed +task.failed +image.created +node.updated +workflow.updated +material.confirmed +wardrobe.matched +config.changed +storage.warning +``` + +--- + +## 16. Logs / Audit API + +```http +GET /logs/generation +GET /logs/workflows +GET /logs/errors +GET /logs/integrations +GET /security/audit-logs +``` + +所有写操作必须写 `audit_logs`: + +```text +create_profile +update_profile +delete_profile +create_workflow +generate_node +select_image +upload_material +confirm_material +add_wardrobe_item +daily_outfit_request +save_config +delete_media +``` + +--- + +## 17. Settings / Config API + +保留 v2 配置系统,但 UI 按卡片分类展示。 + +```http +GET /settings/schema +GET /settings/current +POST /settings/validate +POST /settings/diff +POST /settings/save +POST /settings/reload +GET /settings/export +POST /settings/import +``` + +设置分组: + +```text +模型设置 +工作流设置 +队列设置 +素材库设置 +存储设置 +日志设置 +扩展设置 +安全设置 +API 探测 +Review / 稳定性检查 +``` + +开关用 switch,枚举用 select,路径用 path input,敏感项只显示掩码状态。 + +--- + +## 18. API Discovery 与 RenderPlan 校验 + +保留 v2 的能力探测系统: + +```http +GET /api-discovery/dialects +POST /api-discovery/probe-provider +POST /api-discovery/probe-model +GET /api-discovery/capabilities +POST /api-discovery/manual-override +POST /api-discovery/validate-render-plan +``` + +UI 展示时必须用户化: + +```text +确认支持 +确认不支持 +未确认 +``` + +不得把 `unknown` 当成不支持。 + +--- + +## 19. 前端设计 + +### 19.1 Plugin Page UI + +定位:轻量管理面板。 + +页面结构: + +```text +Plugin Page UI +├── 插件概览 +├── 当前队列 +├── 最近生成 +├── 存储空间 +├── 快速入口 +│ ├── 打开完整工作台 +│ ├── 快速人设 +│ ├── 上传素材 +│ └── 设置 +└── 基础设置 +``` + +调用方式: + +```ts +class PluginPageClient { + async get(endpoint: string, params?: object) { + return window.AstrBotPluginPage.apiGet(endpoint, params) + } + async post(endpoint: string, body?: object) { + return window.AstrBotPluginPage.apiPost(endpoint, body) + } +} +``` + +### 19.2 Standalone Web UI + +定位:完整工作台。 + +导航: + +```text +Standalone Web UI +├── 仪表盘 +├── 工作台 +│ ├── 快速人设 +│ ├── 单图流 +│ ├── 标准角色流 +│ └── 专业角色流 +├── 素材区 +├── 日志区 +├── 设置区 +└── 扩展区 +``` + +工作台采用三栏: + +```text +左栏:角色档案列表 +中栏:工作流与节点 +右栏:节点详情 + 图片卡片 +``` + +### 19.3 前端 API Client + +两套 UI 不共用入口,但共用类型和接口定义。 + +```text +frontend/shared/api/ +├── ApiClient.ts +├── PluginPageClient.ts +├── DirectWebClient.ts +└── endpoints.ts +``` + +Standalone Web: + +```ts +class DirectWebClient { + base = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio" + async get(endpoint: string) { + return fetch(`${this.base}/${endpoint}`) + } +} +``` + +--- + +## 20. 权限与安全 + +### 20.1 鉴权 + +1. Plugin Page UI 使用 AstrBot Dashboard 上下文。 +2. Standalone Web UI 挂载在 AstrBot 下,仍需检查 Dashboard 登录态或 request.username。 +3. 外部插件联动接口需要 internal token 或插件白名单。 +4. 所有写接口校验权限并写审计。 + +### 20.2 Secret + +1. API Key 不进入普通配置 JSON 明文。 +2. 前端只显示 `api_key_set` 和 `api_key_preview`。 +3. 日志不得输出明文 Secret。 +4. Codex/Hermes 任务中不得粘贴真实 Key。 + +### 20.3 媒体访问 + +1. 数据库只保存 VFS URI。 +2. 前端访问图片必须通过 `media/sign` 获取短期 URL。 +3. 文件丢失返回 `missing.png`。 +4. 禁止前端拼接真实文件路径。 + +--- + +## 21. 三轨工作流与 UI 对齐 + +### 21.1 Single Image + +UI: + +```text +档案可选 + -> 输入提示词 + -> 选择比例/模型/素材 + -> 生成 + -> 图片卡片 + -> 微调 / 高清 / 归档 +``` + +后端: + +```text +single_flow.py +profile_workflows.workflow_type = single_image +workflow_nodes 可使用 virtual node +generation_tasks 记录任务 +generation_images 记录全部候选图 +``` + +### 21.2 Character Gradual + +UI: + +```text +角色档案 + -> 创建标准/专业角色流 + -> 节点:头像、上身、下身、鞋袜、全身、三视图、设定稿、PV 海报 + -> 每节点生成候选图 + -> 选中图特殊边框 + -> 可回溯、另开方案、稳定性检查 +``` + +后端: + +```text +character_flow.py +workflow_nodes 对应阶段 +workflow_history 记录正式历史 +generation_images 保存候选图 +workflow_branches 管理分支 +review_history 记录稳定性检查 +``` + +### 21.3 Character Fast / Quick Profile + +快速人设: + +```text +问卷 + -> quick_profile_service + -> profile draft + -> 保存 character_profiles +``` + +快速直出角色包: + +```text +角色档案 + -> generation_batches + -> 头像 / 全身 / 三视图 / 设定稿 + -> 聚合返回图片卡片 +``` + +--- + +## 22. 开发分期 + +### P0:UI 能启动 + 后端基础 + +必须完成: + +1. Plugin Page UI 静态页。 +2. Standalone Web UI 挂载,不单独起端口。 +3. `ui/bootstrap`。 +4. `dashboard/summary`。 +5. `character_profiles` CRUD。 +6. `profile_workflows` CRUD。 +7. `workflow_nodes` 基础查询。 +8. `generation_images` 查询。 +9. `generation_tasks` 与队列状态。 +10. `settings/schema` 和 `settings/current`。 +11. Dashboard 鉴权和通用响应格式。 + +验收: + +```text +- 能在插件页打开轻量 UI。 +- 能直接打开 /web 完整 UI。 +- 能看到仪表盘。 +- 能新建角色档案。 +- 能创建一个单图工作流。 +- 能看到模拟或真实任务队列。 +``` + +### P1:单图流闭环 + +必须完成: + +1. Single Image Workflow。 +2. Prompt 扩写。 +3. 生图任务创建。 +4. 图片保存到 VFS。 +5. 缩略图生成。 +6. 图片卡片展示。 +7. 图片详情查看 prompt/model。 +8. 选择图片、取消选择。 +9. 任务失败重试。 + +验收: + +```text +- 单图流至少支持两轮微调。 +- 图片卡片能查看提示词和模型。 +- 已选图片有 selected 状态。 +``` + +### P2:角色工作流 + +必须完成: + +1. 标准角色流。 +2. 专业八阶段角色流。 +3. workflow_nodes 状态推进。 +4. workflow_history。 +5. 回溯与另开方案。 +6. Review / 稳定性检查轻量版。 +7. 归档角色。 + +验收: + +```text +- 标准角色流可完成头像、上身、全身、三视图、设定稿。 +- 专业角色流节点可展示。 +- 已选择图有特殊状态。 +``` + +### P3:素材区 + +必须完成: + +1. material_categories。 +2. materials。 +3. 分类树。 +4. 素材卡片。 +5. 上传图片。 +6. VLM 识别。 +7. 确认入库。 +8. 自定义配饰分类。 + +验收: + +```text +- 上传素材后进入 pending_confirm。 +- 确认后进入对应分类。 +- 卡片可查看 prompt。 +``` + +### P4:角色衣橱与联动 + +必须完成: + +1. wardrobe_items。 +2. 从素材库加入衣橱。 +3. 衣橱匹配。 +4. private_companion daily outfit API。 +5. 未命中 fallback 随机提示词。 +6. integration logs。 + +验收: + +```text +- 每日穿搭请求能命中衣橱素材。 +- 未命中时能生成随机穿搭 prompt。 +- 调用过程可在日志区查看。 +``` + +### P5:高级运维 + +必须完成: + +1. API Discovery。 +2. RenderPlan 校验。 +3. 模型池设置。 +4. Review 策略 UI。 +5. 死信任务管理。 +6. 配置 diff / rollback。 +7. 存储迁移计划。 +8. 成本统计。 + +--- + +## 23. 验收总表 + +| 阶段 | 关键验收 | +|---|---| +| P0 | 双 UI 均可打开,基础仪表盘可用 | +| P1 | 单图流闭环,图片卡片可查看 metadata | +| P2 | 角色流可推进节点,支持选择、回溯、归档 | +| P3 | 素材分类、上传、识别、确认入库可用 | +| P4 | 角色衣橱与 private_companion 联动可用 | +| P5 | API 探测、配置管理、运维面板可用 | + +--- + +## 24. 最终开发原则 + +1. UI 是需求入口,后端必须为 UI 状态提供事实表。 +2. 不允许只靠内存状态驱动工作台。 +3. 不允许前端直接推断任务状态。 +4. 不允许图片只存在文件夹而无数据库记录。 +5. 不允许素材入库跳过确认。 +6. 不允许 Standalone Web UI 单独起端口。 +7. 不允许两个 UI 各自拥有不同业务逻辑。 +8. 不允许 Secret 明文回显。 +9. 不允许重复点击造成重复生成。 +10. 不允许删除操作绕过二阶段删除和审计。 diff --git a/main.py b/main.py new file mode 100644 index 0000000..3812628 --- /dev/null +++ b/main.py @@ -0,0 +1,5 @@ +"""AstrBot ImageStudio plugin entrypoint. + +Milestone S0 keeps this file lightweight. AstrBot web API registration and +runtime adapters will be connected in later P0 tasks. +""" diff --git a/metadata.yaml b/metadata.yaml new file mode 100644 index 0000000..9607178 --- /dev/null +++ b/metadata.yaml @@ -0,0 +1,5 @@ +name: astrbot_plugin_imagestudio +desc: AstrBot ImageStudio role asset production and image-generation workspace. +version: 3.0.0 +author: YokiiroBW +repo: "http://192.168.31.210:18085/YokiiroBW/astrbot_plugin_imagestudio" diff --git a/pages/imagestudio/.gitkeep b/pages/imagestudio/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/pages/imagestudio/.gitkeep @@ -0,0 +1 @@ + diff --git a/web/.gitkeep b/web/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/web/.gitkeep @@ -0,0 +1 @@ +