S120 打包安装文档
这个提交存在于:
父节点
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
普通文件
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
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
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()
|
||||
正在加载…
添加表格
在新工单中引用