chore: initialize v3 plugin scaffold

这个提交存在于:
YokiiroBW 2026-07-04 22:51:52 +08:00
当前提交 d514bfc498
共有 88 个文件被更改,包括 3031 次插入 和 0 次删除

45
.gitignore Vendored 普通文件
查看文件

@ -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/

71
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.

71
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.

1
__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""AstrBot ImageStudio plugin package."""

12
_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
}
}

1
adapters/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""Runtime adapters for AstrBot, chat platforms, and Web UI integration."""

查看文件

@ -0,0 +1 @@
"""AstrBot runtime adapter placeholder."""

查看文件

@ -0,0 +1 @@
"""OneBot v11 adapter placeholder."""

1
adapters/webui_adapter.py 普通文件
查看文件

@ -0,0 +1 @@
"""AstrBot WebUI adapter placeholder."""

查看文件

@ -0,0 +1 @@
"""WeChat adapter placeholder."""

1
assets_builtin/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1 @@

13
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.

1
backend/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""Backend package for AstrBot ImageStudio."""

1
backend/dto/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""Data transfer objects for ImageStudio backend APIs."""

1
backend/dto/common.py 普通文件
查看文件

@ -0,0 +1 @@
"""Common API DTO placeholder."""

1
backend/dto/image_dto.py 普通文件
查看文件

@ -0,0 +1 @@
"""Image DTO placeholder."""

查看文件

@ -0,0 +1 @@
"""Material DTO placeholder."""

查看文件

@ -0,0 +1 @@
"""Profile DTO placeholder."""

查看文件

@ -0,0 +1 @@
"""Wardrobe DTO placeholder."""

查看文件

@ -0,0 +1 @@
"""Workflow DTO placeholder."""

1
backend/routes/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
backend/services/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

26
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

1
core/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""Core services shared by ImageStudio engines and APIs."""

1
core/audit_service.py 普通文件
查看文件

@ -0,0 +1 @@
"""Audit logging service placeholder."""

1
core/config_service.py 普通文件
查看文件

@ -0,0 +1 @@
"""Configuration service placeholder."""

1
core/event_bus.py 普通文件
查看文件

@ -0,0 +1 @@
"""In-process event bus placeholder."""

1
core/fsm.py 普通文件
查看文件

@ -0,0 +1 @@
"""Workflow finite-state-machine helpers placeholder."""

1
core/identity.py 普通文件
查看文件

@ -0,0 +1 @@
"""Identity and request actor helpers placeholder."""

1
core/interactions.py 普通文件
查看文件

@ -0,0 +1 @@
"""Interaction menu and user action helpers placeholder."""

1
core/interop.py 普通文件
查看文件

@ -0,0 +1 @@
"""External plugin interoperability placeholder."""

1
core/media_proxy.py 普通文件
查看文件

@ -0,0 +1 @@
"""Signed media URL helpers placeholder."""

1
core/model_router.py 普通文件
查看文件

@ -0,0 +1 @@
"""Model route selection placeholder."""

1
core/prompt_pipeline.py 普通文件
查看文件

@ -0,0 +1 @@
"""Prompt composition pipeline placeholder."""

1
core/queue_manager.py 普通文件
查看文件

@ -0,0 +1 @@
"""Generation queue manager placeholder."""

1
core/secret_service.py 普通文件
查看文件

@ -0,0 +1 @@
"""Secret management placeholder."""

1
core/security.py 普通文件
查看文件

@ -0,0 +1 @@
"""Security and permission helpers placeholder."""

1
core/storage.py 普通文件
查看文件

@ -0,0 +1 @@
"""VFS storage helpers placeholder."""

1
core/webhook.py 普通文件
查看文件

@ -0,0 +1 @@
"""Webhook dispatch placeholder."""

1
data/archives/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/db/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/exports/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/images/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/materials/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/styles/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/temp/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
data/thumbnails/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@

1
database/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""Database models, helpers, migrations, and repositories."""

1
database/db_helper.py 普通文件
查看文件

@ -0,0 +1 @@
"""Database connection and migration helper placeholder."""

查看文件

@ -0,0 +1 @@

1
database/models.py 普通文件
查看文件

@ -0,0 +1 @@
"""SQL model definitions placeholder."""

查看文件

@ -0,0 +1 @@
"""Repository implementations for ImageStudio persistence."""

1
database/seed.py 普通文件
查看文件

@ -0,0 +1 @@
"""Seed data helpers placeholder."""

1
engines/__init__.py 普通文件
查看文件

@ -0,0 +1 @@
"""ImageStudio workflow engines."""

1
engines/character_flow.py 普通文件
查看文件

@ -0,0 +1 @@
"""Gradual character workflow engine placeholder."""

查看文件

@ -0,0 +1 @@
"""Fast character package workflow engine placeholder."""

查看文件

@ -0,0 +1 @@
"""Quick profile draft workflow placeholder."""

1
engines/review_flow.py 普通文件
查看文件

@ -0,0 +1 @@
"""Review and stability-check workflow placeholder."""

1
engines/single_flow.py 普通文件
查看文件

@ -0,0 +1 @@
"""Single image workflow engine placeholder."""

17
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.

18
frontend/env.d.ts Vendored 普通文件
查看文件

@ -0,0 +1,18 @@
/// <reference types="vite/client" />
declare module "*.vue" {
import type { DefineComponent } from "vue"
const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
export default component
}
interface Window {
AstrBotPluginPage?: {
apiGet<T>(path: string, params?: Record<string, unknown>): Promise<T>
apiPost<T>(path: string, body?: unknown): Promise<T>
apiPut<T>(path: string, body?: unknown): Promise<T>
apiPatch<T>(path: string, body?: unknown): Promise<T>
apiDelete<T>(path: string): Promise<T>
}
}

24
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": {}
}

查看文件

@ -0,0 +1,2 @@
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>

查看文件

@ -0,0 +1,29 @@
<template>
<main class="plugin-page-shell">
<h1>ImageStudio</h1>
<p>Plugin Page UI scaffold is ready.</p>
</main>
</template>
<style scoped>
.plugin-page-shell {
box-sizing: border-box;
min-height: 100vh;
padding: 24px;
color: #1f2937;
background: #f8fafc;
font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}
h1 {
margin: 0 0 8px;
font-size: 24px;
font-weight: 700;
}
p {
margin: 0;
color: #64748b;
}
</style>

查看文件

@ -0,0 +1,4 @@
import { createApp } from "vue"
import App from "./App.vue"
createApp(App).mount("#app")

查看文件

@ -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,
},
})

查看文件

@ -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

查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1,16 @@
export interface ApiSuccess<T> {
ok: true
data: T
warnings: string[]
request_id?: string
}
export interface ApiFailure {
ok: false
error_code: string
message: string
details?: Record<string, unknown>
request_id?: string
}
export type ApiResponse<T> = ApiSuccess<T> | ApiFailure

查看文件

@ -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
}

查看文件

@ -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[]
}

查看文件

@ -0,0 +1 @@

查看文件

@ -0,0 +1,2 @@
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>

查看文件

@ -0,0 +1,67 @@
<template>
<main class="web-shell">
<aside class="sidebar">
<strong>ImageStudio</strong>
<span>Standalone Web UI</span>
</aside>
<section class="workspace">
<h1>Workspace Scaffold</h1>
<p>The full AstrBot-mounted workbench starts here.</p>
</section>
</main>
</template>
<style scoped>
.web-shell {
box-sizing: border-box;
display: grid;
grid-template-columns: 240px minmax(0, 1fr);
min-height: 100vh;
color: #172033;
background: #f6f7f9;
font-family:
Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}
.sidebar {
display: flex;
flex-direction: column;
gap: 8px;
padding: 24px;
border-right: 1px solid #d7dde6;
background: #ffffff;
}
.sidebar strong {
font-size: 18px;
}
.sidebar span,
.workspace p {
color: #607086;
}
.workspace {
padding: 32px;
}
h1 {
margin: 0 0 8px;
font-size: 28px;
}
p {
margin: 0;
}
@media (max-width: 760px) {
.web-shell {
grid-template-columns: 1fr;
}
.sidebar {
border-right: 0;
border-bottom: 1px solid #d7dde6;
}
}
</style>

查看文件

@ -0,0 +1,4 @@
import { createApp } from "vue"
import App from "./App.vue"
createApp(App).mount("#app")

查看文件

@ -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,
},
})

28
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"
]
}

查看文件

@ -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=<image>
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
```

查看文件

@ -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 有对应记录。
```
完成以上步骤后,再进入真实模型调用和高级能力。

文件差异内容过多而无法显示 加载差异

5
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.
"""

5
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"

查看文件

@ -0,0 +1 @@

1
web/.gitkeep 普通文件
查看文件

@ -0,0 +1 @@