S120 打包安装文档

这个提交存在于:
YokiiroBW 2026-07-06 04:33:14 +08:00
父节点 94b7fc5b69
当前提交 4bff71d80b
共有 4 个文件被更改,包括 170 次插入 和 70 次删除

查看文件

@ -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.

106
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

查看文件

@ -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

查看文件

@ -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()