S120 打包安装文档
这个提交存在于:
父节点
94b7fc5b69
当前提交
4bff71d80b
共有 4 个文件被更改,包括 170 次插入 和 70 次删除
|
|
@ -2,75 +2,47 @@
|
||||||
|
|
||||||
## Scope
|
## 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:
|
Prepared:
|
||||||
|
|
||||||
- AstrBot plugin root files and v3 configuration placeholders.
|
- AstrBot plugin root files, runtime registration helpers, and v3 configuration placeholders.
|
||||||
- v3 top-level module layout: `adapters`, `core`, `engines`, `backend`, `database`, `assets_builtin`, `frontend`, `pages`, `web`, and `data`.
|
- Backend API routes, route registry, permission matrix, contract export, and pure dispatch helpers.
|
||||||
- Database helper foundation with SQLite default and optional PostgreSQL selection from `config.yaml`.
|
- SQLite default database with optional PostgreSQL selection from `config.yaml`.
|
||||||
- `character_profiles` persistence and service layer with audit logging.
|
- `psycopg` and `psycopg2` PostgreSQL driver compatibility.
|
||||||
- `profile_workflows` and `workflow_nodes` persistence and service layer with audit logging.
|
- Core repositories and services for profiles, workflows, nodes, jobs, images, materials, wardrobe, integrations, settings, review, costs, media, and model providers.
|
||||||
- `generation_images` persistence and service layer with selected image exclusivity and audit logging.
|
- Real image-provider path, VLM adapter interface, worker/retry/cancel infrastructure, budget guard, prompt expansion, token rotation, deletion safety, media indexing, and orphan scanning.
|
||||||
- `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.
|
|
||||||
- Runtime data directories with `.gitkeep` files only.
|
- Runtime data directories with `.gitkeep` files only.
|
||||||
- Generated data, local virtual environments, node modules, and build artifacts are ignored.
|
- 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
|
## 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
|
```text
|
||||||
C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe
|
python -m unittest discover -s tests
|
||||||
C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\bin\pnpm.cmd
|
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
|
```text
|
||||||
S2-4 实现 workflows / nodes / images routes
|
GET contract
|
||||||
S2-5 实现 jobs / settings placeholders
|
|
||||||
S2-6 实现 storage status / media sign placeholders
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## P0 Frozen API Checklist
|
The exported contract includes `api_base`, routes, permissions, error codes, and the standard success/error response shape.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Database Backend
|
## 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.
|
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
普通文件
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
|
||||||
34
README.md
34
README.md
|
|
@ -29,28 +29,26 @@ character_profiles
|
||||||
|
|
||||||
## Current Stage
|
## 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.
|
- AstrBot runtime registration manifest and pure dispatch helpers.
|
||||||
- Common API response helpers matching the v3 contract.
|
- v3 response helpers, request context, permission guards, and permission matrix export.
|
||||||
- Request context and permission guard helpers.
|
- SQLite default database with optional PostgreSQL via `psycopg` or `psycopg2`.
|
||||||
- Database helper with SQLite default and optional PostgreSQL selection.
|
- Migrations, repositories, audit logging, config snapshots, route registry, and contract export.
|
||||||
- Initial `audit_logs` migration and audit recording service.
|
- Profiles, workflows, nodes, queues, images, media signing, material library, wardrobe, integrations, costs, review policy, model provider routing, and worker infrastructure.
|
||||||
- `character_profiles` migration, repository, service, and audit-backed create/update/delete.
|
- 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.
|
||||||
- `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.
|
|
||||||
|
|
||||||
Next tasks:
|
Useful entry points:
|
||||||
|
|
||||||
1. `S2-4` workflows, nodes, and images routes.
|
- `main.get_plugin_manifest()`
|
||||||
2. `S2-5` jobs placeholders and settings current/schema.
|
- `main.register_plugin(runtime)`
|
||||||
3. `S2-6` storage status and media sign placeholders.
|
- `main.dispatch_web_request(...)`
|
||||||
4. `S3` mount Plugin Page UI and Standalone Web UI through AstrBot.
|
- `scripts/imagestudio_non_ui_smoke.py`
|
||||||
5. `S4` single image mock flow and generation task lifecycle.
|
- `scripts/imagestudio_pg_smoke.py`
|
||||||
|
|
||||||
|
For installation, packaging, smoke checks, and PG setup, see [INSTALL.md](INSTALL.md).
|
||||||
|
|
||||||
## Repository Layout
|
## Repository Layout
|
||||||
|
|
||||||
|
|
|
||||||
20
tests/test_docs_packaging.py
普通文件
20
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()
|
||||||
正在加载…
添加表格
在新工单中引用