2026-07-04 22:51:52 +08:00
# Development Environment
## Scope
2026-07-06 04:33:14 +08:00
The repository has completed the non-UI backend queue through `S120` . UI-only work remains separate.
2026-07-04 22:51:52 +08:00
Prepared:
2026-07-06 04:33:14 +08:00
- 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.
2026-07-04 22:51:52 +08:00
- Runtime data directories with `.gitkeep` files only.
- Generated data, local virtual environments, node modules, and build artifacts are ignored.
## Local Tools
2026-07-06 04:33:14 +08:00
On Windows, PowerShell may block `npm.ps1` ; use `npm.cmd` when needed.
2026-07-04 22:51:52 +08:00
2026-07-06 04:33:14 +08:00
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.
2026-07-04 22:51:52 +08:00
2026-07-06 04:33:14 +08:00
## Verification
2026-07-04 22:51:52 +08:00
2026-07-06 04:33:14 +08:00
Run backend tests and non-UI smoke:
2026-07-04 22:51:52 +08:00
```text
2026-07-06 04:33:14 +08:00
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
2026-07-04 22:51:52 +08:00
```
2026-07-06 04:33:14 +08:00
Set `IMAGESTUDIO_TEST_PG_DSN` before `python -m unittest tests.test_pg_smoke` to run a live PostgreSQL smoke.
2026-07-04 22:51:52 +08:00
2026-07-06 04:33:14 +08:00
## API Contract
The backend contract is available from:
2026-07-04 22:51:52 +08:00
```text
2026-07-06 04:33:14 +08:00
GET contract
2026-07-04 22:51:52 +08:00
```
2026-07-06 04:33:14 +08:00
The exported contract includes `api_base` , routes, permissions, error codes, and the standard success/error response shape.
2026-07-04 23:08:05 +08:00
## 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.
2026-07-06 04:33:14 +08:00
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.