chore: initialize v3 plugin scaffold
这个提交存在于:
当前提交
d514bfc498
共有 88 个文件被更改,包括 3031 次插入 和 0 次删除
45
.gitignore
Vendored
普通文件
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
普通文件
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
普通文件
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
普通文件
1
__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""AstrBot ImageStudio plugin package."""
|
||||
12
_conf_schema.json
普通文件
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
普通文件
1
adapters/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Runtime adapters for AstrBot, chat platforms, and Web UI integration."""
|
||||
1
adapters/astrbot_adapter.py
普通文件
1
adapters/astrbot_adapter.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""AstrBot runtime adapter placeholder."""
|
||||
1
adapters/onebot11_adapter.py
普通文件
1
adapters/onebot11_adapter.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""OneBot v11 adapter placeholder."""
|
||||
1
adapters/webui_adapter.py
普通文件
1
adapters/webui_adapter.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""AstrBot WebUI adapter placeholder."""
|
||||
1
adapters/wechat_adapter.py
普通文件
1
adapters/wechat_adapter.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""WeChat adapter placeholder."""
|
||||
1
assets_builtin/.gitkeep
普通文件
1
assets_builtin/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
|
|
@ -0,0 +1 @@
|
|||
|
||||
13
backend/README.md
普通文件
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
普通文件
1
backend/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Backend package for AstrBot ImageStudio."""
|
||||
1
backend/dto/__init__.py
普通文件
1
backend/dto/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Data transfer objects for ImageStudio backend APIs."""
|
||||
1
backend/dto/common.py
普通文件
1
backend/dto/common.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Common API DTO placeholder."""
|
||||
1
backend/dto/image_dto.py
普通文件
1
backend/dto/image_dto.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Image DTO placeholder."""
|
||||
1
backend/dto/material_dto.py
普通文件
1
backend/dto/material_dto.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Material DTO placeholder."""
|
||||
1
backend/dto/profile_dto.py
普通文件
1
backend/dto/profile_dto.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Profile DTO placeholder."""
|
||||
1
backend/dto/wardrobe_dto.py
普通文件
1
backend/dto/wardrobe_dto.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Wardrobe DTO placeholder."""
|
||||
1
backend/dto/workflow_dto.py
普通文件
1
backend/dto/workflow_dto.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Workflow DTO placeholder."""
|
||||
1
backend/routes/.gitkeep
普通文件
1
backend/routes/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
backend/services/.gitkeep
普通文件
1
backend/services/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
26
config.yaml
普通文件
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
普通文件
1
core/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Core services shared by ImageStudio engines and APIs."""
|
||||
1
core/audit_service.py
普通文件
1
core/audit_service.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Audit logging service placeholder."""
|
||||
1
core/config_service.py
普通文件
1
core/config_service.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Configuration service placeholder."""
|
||||
1
core/event_bus.py
普通文件
1
core/event_bus.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""In-process event bus placeholder."""
|
||||
1
core/fsm.py
普通文件
1
core/fsm.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Workflow finite-state-machine helpers placeholder."""
|
||||
1
core/identity.py
普通文件
1
core/identity.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Identity and request actor helpers placeholder."""
|
||||
1
core/interactions.py
普通文件
1
core/interactions.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Interaction menu and user action helpers placeholder."""
|
||||
1
core/interop.py
普通文件
1
core/interop.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""External plugin interoperability placeholder."""
|
||||
1
core/media_proxy.py
普通文件
1
core/media_proxy.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Signed media URL helpers placeholder."""
|
||||
1
core/model_router.py
普通文件
1
core/model_router.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Model route selection placeholder."""
|
||||
1
core/prompt_pipeline.py
普通文件
1
core/prompt_pipeline.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Prompt composition pipeline placeholder."""
|
||||
1
core/queue_manager.py
普通文件
1
core/queue_manager.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Generation queue manager placeholder."""
|
||||
1
core/secret_service.py
普通文件
1
core/secret_service.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Secret management placeholder."""
|
||||
1
core/security.py
普通文件
1
core/security.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Security and permission helpers placeholder."""
|
||||
1
core/storage.py
普通文件
1
core/storage.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""VFS storage helpers placeholder."""
|
||||
1
core/webhook.py
普通文件
1
core/webhook.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Webhook dispatch placeholder."""
|
||||
1
data/archives/.gitkeep
普通文件
1
data/archives/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/db/.gitkeep
普通文件
1
data/db/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/exports/.gitkeep
普通文件
1
data/exports/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/images/.gitkeep
普通文件
1
data/images/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/materials/.gitkeep
普通文件
1
data/materials/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/styles/.gitkeep
普通文件
1
data/styles/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/temp/.gitkeep
普通文件
1
data/temp/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
data/thumbnails/.gitkeep
普通文件
1
data/thumbnails/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
database/__init__.py
普通文件
1
database/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Database models, helpers, migrations, and repositories."""
|
||||
1
database/db_helper.py
普通文件
1
database/db_helper.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Database connection and migration helper placeholder."""
|
||||
1
database/migrations/.gitkeep
普通文件
1
database/migrations/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
database/models.py
普通文件
1
database/models.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""SQL model definitions placeholder."""
|
||||
|
|
@ -0,0 +1 @@
|
|||
"""Repository implementations for ImageStudio persistence."""
|
||||
1
database/seed.py
普通文件
1
database/seed.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Seed data helpers placeholder."""
|
||||
1
engines/__init__.py
普通文件
1
engines/__init__.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""ImageStudio workflow engines."""
|
||||
1
engines/character_flow.py
普通文件
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
普通文件
1
engines/review_flow.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Review and stability-check workflow placeholder."""
|
||||
1
engines/single_flow.py
普通文件
1
engines/single_flow.py
普通文件
|
|
@ -0,0 +1 @@
|
|||
"""Single image workflow engine placeholder."""
|
||||
17
frontend/README.md
普通文件
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
普通文件
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
普通文件
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>
|
||||
29
frontend/plugin-page/src/App.vue
普通文件
29
frontend/plugin-page/src/App.vue
普通文件
|
|
@ -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,
|
||||
},
|
||||
})
|
||||
13
frontend/shared/api/endpoints.ts
普通文件
13
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
|
||||
|
|
@ -0,0 +1 @@
|
|||
|
||||
|
|
@ -0,0 +1 @@
|
|||
|
||||
|
|
@ -0,0 +1 @@
|
|||
|
||||
|
|
@ -0,0 +1 @@
|
|||
|
||||
16
frontend/shared/types/api.ts
普通文件
16
frontend/shared/types/api.ts
普通文件
|
|
@ -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
普通文件
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
普通文件
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
普通文件
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"
|
||||
1
pages/imagestudio/.gitkeep
普通文件
1
pages/imagestudio/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
1
web/.gitkeep
普通文件
1
web/.gitkeep
普通文件
|
|
@ -0,0 +1 @@
|
|||
|
||||
正在加载…
添加表格
在新工单中引用