astrbot_plugin_imagestudio/DEVELOPMENT.md

77 行
2.7 KiB
Markdown

# 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:
```text
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:
```text
GET contract
```
The exported contract includes `api_base`, routes, permissions, error codes, and the standard success/error response shape.
## Database Backend
Default behavior:
```text
database.backend = auto
postgresql.enabled = false
selected backend = sqlite
```
When PostgreSQL is configured:
```yaml
database:
backend: auto
postgresql:
enabled: true
host: 127.0.0.1
port: 5432
database: imagestudio
user: imagestudio
password: ""
```
With `backend: auto`, enabling a complete PostgreSQL config makes PostgreSQL the selected backend. Use `backend: sqlite` to force SQLite even when PostgreSQL fields exist, or `backend: postgresql` to fail fast when PG config/driver is missing.
PostgreSQL support is optional and imports `psycopg` first, then falls back to `psycopg2`.
## Runtime Rule
Do not start a separate FastAPI, Flask, or Vite production port for the plugin. Dev servers may only be used for local frontend development before build output is copied into AstrBot static paths.