astrbot_plugin_imagestudio/DEVELOPMENT.md

2.7 KiB

Development Environment

Scope

The repository has completed the non-UI backend queue through S120. UI-only work remains separate.

Prepared:

  • AstrBot plugin root files, runtime registration helpers, and v3 configuration placeholders.
  • Backend API routes, route registry, permission matrix, contract export, and pure dispatch helpers.
  • SQLite default database with optional PostgreSQL selection from config.yaml.
  • psycopg and psycopg2 PostgreSQL driver compatibility.
  • Core repositories and services for profiles, workflows, nodes, jobs, images, materials, wardrobe, integrations, settings, review, costs, media, and model providers.
  • Real image-provider path, VLM adapter interface, worker/retry/cancel infrastructure, budget guard, prompt expansion, token rotation, deletion safety, media indexing, and orphan scanning.
  • Runtime data directories with .gitkeep files only.
  • Generated data, local virtual environments, node modules, and build artifacts are ignored.

Local Tools

On Windows, PowerShell may block npm.ps1; use npm.cmd when needed.

Codex bundled tools are usually available under the local Codex runtime cache. The project itself does not require a standalone backend server for normal plugin use.

Verification

Run backend tests and non-UI smoke:

python -m unittest discover -s tests
python -m compileall adapters backend core database engines scripts tests main.py
python scripts/imagestudio_non_ui_smoke.py
python scripts/imagestudio_pg_smoke.py --dry-run

Set IMAGESTUDIO_TEST_PG_DSN before python -m unittest tests.test_pg_smoke to run a live PostgreSQL smoke.

API Contract

The backend contract is available from:

GET contract

The exported contract includes api_base, routes, permissions, error codes, and the standard success/error response shape.

Database Backend

Default behavior:

database.backend = auto
postgresql.enabled = false
selected backend = sqlite

When PostgreSQL is configured:

database:
  backend: auto
  postgresql:
    enabled: true
    host: 127.0.0.1
    port: 5432
    database: imagestudio
    user: imagestudio
    password: ""

With backend: auto, enabling a complete PostgreSQL config makes PostgreSQL the selected backend. Use backend: sqlite to force SQLite even when PostgreSQL fields exist, or backend: postgresql to fail fast when PG config/driver is missing.

PostgreSQL support is optional and imports psycopg first, then falls back to psycopg2.

Runtime Rule

Do not start a separate FastAPI, Flask, or Vite production port for the plugin. Dev servers may only be used for local frontend development before build output is copied into AstrBot static paths.