astrbot_plugin_imagestudio/DEVELOPMENT.md

96 行
3.8 KiB
Markdown

# 开发约定
2026-07-04 22:51:52 +08:00
## AstrBot 运行契约
2026-07-04 22:51:52 +08:00
ImageStudio 的生产宿主是 AstrBot `4.25.0` 及以上版本。
2026-07-04 22:51:52 +08:00
- 插件入口是 `main.py` 中的 `Star` 子类。
- AstrBot 调用 `initialize()` 和 `terminate()` 管理生命周期。
- `initialize()` 通过 `context.register_web_api` 注册 API。
- `pages/imagestudio/index.html` 由 AstrBot 自动发现为插件页面。
- 插件页面 bridge 只接收 `ui/bootstrap` 这类相对 endpoint。
- v4.25 legacy bridge 前缀为 `/api/plug/astrbot_plugin_imagestudio/`;当前直接 API 前缀为 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/`。
2026-07-04 22:51:52 +08:00
不要把内部辅助函数或自定义 web mount 当作 AstrBot 官方回调。也不要依赖 `/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web` 存在;`web/` 仅作为独立构建/兼容产物,生产插件页面以 `pages/imagestudio/` 为准。
2026-07-04 22:51:52 +08:00
## 目录职责
2026-07-04 22:51:52 +08:00
- `main.py`:AstrBot Star 生命周期与 Web API 接入。
- `backend/routes/`:endpoint 适配层。
- `backend/services/`:业务服务。
- `database/`:数据库连接、仓储和迁移。
- `frontend/plugin-page/`:AstrBot 插件页面源码,构建到 `pages/imagestudio/`。
- `frontend/standalone-web/`:独立预览/兼容页面源码,构建到 `web/`。
- `frontend/shared/`:两套前端共享的 API client、endpoint 和类型。
2026-07-04 22:51:52 +08:00
后端 endpoint 使用不带宿主前缀的形式维护,例如 `nodes/{node_id}/generate`。宿主适配层负责 legacy bridge 和当前 `/api/v1` 前缀的兼容,业务服务不应感知 URL 前缀。
2026-07-04 22:51:52 +08:00
## 持久化规则
2026-07-04 22:51:52 +08:00
运行数据必须位于:
2026-07-04 22:51:52 +08:00
```text
data/plugin_data/astrbot_plugin_imagestudio/
2026-07-04 22:51:52 +08:00
```
不要向插件源码目录写数据库、图片、日志或缓存。测试可使用临时目录,且不能把真实运行数据加入发布包。
2026-07-04 22:51:52 +08:00
`config.yaml` 保留 `data/db`、`data/images` 等逻辑路径;运行时路径解析层负责把前导 `data/` 替换为 AstrBot 插件数据根目录。本地开发则继续映射到仓库的 `data/`。不要在配置默认值中重复写完整 `data/plugin_data/astrbot_plugin_imagestudio/` 前缀。
2026-07-06 04:33:14 +08:00
## 本地前端开发
2026-07-04 22:51:52 +08:00
Windows 上若 PowerShell 阻止 `npm.ps1`,使用 `npm.cmd`:
```powershell
cd frontend
npm.cmd install
npm.cmd run typecheck
npm.cmd run dev:plugin
2026-07-04 22:51:52 +08:00
```
`dev:plugin` 只用于本地开发。生产构建:
```powershell
npm.cmd run build:plugin
```
它会更新 `pages/imagestudio/`。`dev:web` 与 `build:web` 只用于独立预览或兼容产物,不代表 AstrBot 注册了 `/web` 生产路由。
## 数据库后端
默认配置选择 SQLite。`backend: auto` 仅在 PostgreSQL 已启用且连接字段完整时切换到 PG;`backend: sqlite` 强制 SQLite;`backend: postgresql` 在驱动或配置缺失时快速失败。
PG 驱动是可选依赖,优先使用 `psycopg`,兼容回退到 `psycopg2`。不要在默认 `requirements.txt` 中启用 PG 驱动,以免 SQLite 用户被强制安装额外二进制依赖。
## 验证
```powershell
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
cd frontend
npm.cmd run typecheck
npm.cmd run build:plugin
npm.cmd run build:web
```
设置 `IMAGESTUDIO_TEST_PG_DSN` 后,可运行 `python -m unittest tests.test_pg_smoke` 做真实 PG smoke。
生产构建必须同时提交 `pages/imagestudio/` 的最新插件页面产物。`web/` 仅是独立预览兼容产物,但若仓库保留它,也应与同一份前端源码同步构建,避免两个产物行为漂移。
## API 契约
2026-07-06 04:33:14 +08:00
契约 endpoint 为相对路径:
2026-07-06 04:33:14 +08:00
```text
GET contract
```
插件页面通过 bridge 调用时传 `contract`;直接请求时使用:
```text
GET /api/v1/plugins/extensions/astrbot_plugin_imagestudio/contract
```