From 4bff71d80bed68a4d1f62f2fd7b48899897a96ff Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Mon, 6 Jul 2026 04:33:14 +0800 Subject: [PATCH] =?UTF-8?q?S120=20=E6=89=93=E5=8C=85=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEVELOPMENT.md | 80 +++++++++----------------- INSTALL.md | 106 +++++++++++++++++++++++++++++++++++ README.md | 34 ++++++----- tests/test_docs_packaging.py | 20 +++++++ 4 files changed, 170 insertions(+), 70 deletions(-) create mode 100644 INSTALL.md create mode 100644 tests/test_docs_packaging.py diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index cd97a76..e8a2dc8 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,75 +2,47 @@ ## Scope -The repository is currently prepared for v3 `S0-1`. +The repository has completed the non-UI backend queue through `S120`. UI-only work remains separate. 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`. -- Database helper foundation with SQLite default and optional PostgreSQL selection from `config.yaml`. -- `character_profiles` persistence and service layer with audit logging. -- `profile_workflows` and `workflow_nodes` persistence and service layer with audit logging. -- `generation_images` persistence and service layer with selected image exclusivity and audit logging. -- `ui/bootstrap` and `dashboard/summary` pure route handlers ready for AstrBot mounting. -- Profile CRUD and quick profile draft pure route handlers ready for AstrBot mounting. -- Frontend source skeleton for Plugin Page UI and Standalone Web UI. +- 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. -Not implemented yet: - -- AstrBot adapter registration. -- Repositories and business services. -- P0 API routes. -- Real UI screens beyond scaffold placeholders. - ## Local Tools -On this machine, PowerShell blocks `npm.ps1`; use `npm.cmd` when needed. +On Windows, PowerShell may block `npm.ps1`; use `npm.cmd` when needed. -Codex bundled tools are also available: +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 -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 +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 ``` -## First Tasks +Set `IMAGESTUDIO_TEST_PG_DSN` before `python -m unittest tests.test_pg_smoke` to run a live PostgreSQL smoke. -Follow `imagestudio_codex_hermes_dev_flow_v3.md` and continue with: +## API Contract + +The backend contract is available from: ```text -S2-4 实现 workflows / nodes / images routes -S2-5 实现 jobs / settings placeholders -S2-6 实现 storage status / media sign placeholders +GET contract ``` -## 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. +The exported contract includes `api_base`, routes, permissions, error codes, and the standard success/error response shape. ## Database Backend @@ -98,4 +70,8 @@ database: 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 only imports `psycopg` when the PG backend is selected. +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. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..15ebf07 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,106 @@ +# Installation and Packaging + +ImageStudio is an AstrBot plugin. Do not run it as a standalone FastAPI, Flask, or Vite production service. + +## Install Into AstrBot + +1. Clone or copy this repository into AstrBot's plugin directory as `astrbot_plugin_imagestudio`. +2. Keep the repository root files in place: `metadata.yaml`, `main.py`, `config.yaml`, `_conf_schema.json`. +3. Restart or reload AstrBot so it can discover the plugin metadata. +4. AstrBot should call `main.get_plugin_manifest()` or `main.register_plugin(runtime)` to discover extension routes and the web mount. + +The backend API is mounted under: + +```text +/api/v1/plugins/extensions/astrbot_plugin_imagestudio +``` + +The standalone web entry is mounted under: + +```text +/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web +``` + +## Database + +SQLite is the default and requires no extra service: + +```yaml +database: + backend: auto + sqlite: + path: data/db/imagestudio.db + postgresql: + enabled: false +``` + +PostgreSQL is selected when `backend: postgresql`, or when `backend: auto` and `postgresql.enabled` plus connection fields are configured. + +```yaml +database: + backend: auto + postgresql: + enabled: true + host: 127.0.0.1 + port: 5432 + database: imagestudio + user: imagestudio + password: "" +``` + +The plugin supports either `psycopg` or `psycopg2` when PostgreSQL is selected. + +## Secrets + +Do not commit `.env*`, API keys, DSNs, or integration tokens. Runtime tokens are rotated through: + +```text +POST integrations/private-companion/token/rotate +``` + +The rotate response returns the new token once. Config stores only salt and hash. + +## Smoke Checks + +Run the non-UI backend smoke: + +```powershell +python scripts/imagestudio_non_ui_smoke.py +``` + +Run the PostgreSQL plan without connecting: + +```powershell +python scripts/imagestudio_pg_smoke.py --dry-run +``` + +Run full tests: + +```powershell +python -m unittest discover -s tests +python -m compileall adapters backend core database engines scripts tests main.py +``` + +Optional live PostgreSQL smoke: + +```powershell +$env:IMAGESTUDIO_TEST_PG_DSN = "postgresql://user:password@127.0.0.1:5432/imagestudio_test" +python -m unittest tests.test_pg_smoke +``` + +## Package + +Use Git so ignored local data and secrets are excluded: + +```powershell +git archive --format=zip --output astrbot_plugin_imagestudio.zip HEAD +``` + +The package should include source modules, migrations, built/static assets, config templates, and docs. It should not include: + +- `.git/` +- `.env*` +- `data/*` runtime contents +- `node_modules/` +- `__pycache__/` +- local test databases or generated media diff --git a/README.md b/README.md index cc3d37c..28a9a05 100644 --- a/README.md +++ b/README.md @@ -29,28 +29,26 @@ character_profiles ## Current Stage -This repository has completed `S0-1` and started the S0 backend foundation. +The non-UI backend queue through `S120` is implemented. UI-only stages remain separate. -Implemented foundation: +Implemented backend foundation and operations: -- v3 directory and configuration baseline. -- Common API response helpers matching the v3 contract. -- Request context and permission guard helpers. -- Database helper with SQLite default and optional PostgreSQL selection. -- Initial `audit_logs` migration and audit recording service. -- `character_profiles` migration, repository, service, and audit-backed create/update/delete. -- `profile_workflows` and `workflow_nodes` migrations, repositories, services, and audit-backed create/update. -- `generation_images` migration, repository, service, selected-state exclusivity, archive/delete metadata semantics, and audit logging. -- `ui/bootstrap` and `dashboard/summary` service/route handlers with v3 response wrapping. -- Profile CRUD and quick profile draft route handlers. +- AstrBot runtime registration manifest and pure dispatch helpers. +- v3 response helpers, request context, permission guards, and permission matrix export. +- SQLite default database with optional PostgreSQL via `psycopg` or `psycopg2`. +- Migrations, repositories, audit logging, config snapshots, route registry, and contract export. +- Profiles, workflows, nodes, queues, images, media signing, material library, wardrobe, integrations, costs, review policy, model provider routing, and worker infrastructure. +- Real image-provider adapter path, VLM adapter interface, prompt expansion, budget guard, token rotation, safe deletion, media index, orphan scanning, PG smoke, and non-UI smoke scripts. -Next tasks: +Useful entry points: -1. `S2-4` workflows, nodes, and images routes. -2. `S2-5` jobs placeholders and settings current/schema. -3. `S2-6` storage status and media sign placeholders. -4. `S3` mount Plugin Page UI and Standalone Web UI through AstrBot. -5. `S4` single image mock flow and generation task lifecycle. +- `main.get_plugin_manifest()` +- `main.register_plugin(runtime)` +- `main.dispatch_web_request(...)` +- `scripts/imagestudio_non_ui_smoke.py` +- `scripts/imagestudio_pg_smoke.py` + +For installation, packaging, smoke checks, and PG setup, see [INSTALL.md](INSTALL.md). ## Repository Layout diff --git a/tests/test_docs_packaging.py b/tests/test_docs_packaging.py new file mode 100644 index 0000000..d43772c --- /dev/null +++ b/tests/test_docs_packaging.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +import unittest +from pathlib import Path + + +class PackagingDocsTests(unittest.TestCase): + def test_install_docs_cover_smoke_pg_and_archive_commands(self): + install = Path("INSTALL.md").read_text(encoding="utf-8") + readme = Path("README.md").read_text(encoding="utf-8") + + self.assertIn("python scripts/imagestudio_non_ui_smoke.py", install) + self.assertIn("python scripts/imagestudio_pg_smoke.py --dry-run", install) + self.assertIn("git archive --format=zip", install) + self.assertIn("psycopg2", install) + self.assertIn("[INSTALL.md](INSTALL.md)", readme) + + +if __name__ == "__main__": + unittest.main()