astrbot_plugin_imagestudio/DEVELOPMENT.md

3.8 KiB

开发约定

AstrBot 运行契约

ImageStudio 的生产宿主是 AstrBot 4.25.0 及以上版本。

  • 插件入口是 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/。

不要把内部辅助函数或自定义 web mount 当作 AstrBot 官方回调。也不要依赖 /api/v1/plugins/extensions/astrbot_plugin_imagestudio/web 存在;web/ 仅作为独立构建/兼容产物,生产插件页面以 pages/imagestudio/ 为准。

目录职责

  • 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 和类型。

后端 endpoint 使用不带宿主前缀的形式维护,例如 nodes/{node_id}/generate。宿主适配层负责 legacy bridge 和当前 /api/v1 前缀的兼容,业务服务不应感知 URL 前缀。

持久化规则

运行数据必须位于:

data/plugin_data/astrbot_plugin_imagestudio/

不要向插件源码目录写数据库、图片、日志或缓存。测试可使用临时目录,且不能把真实运行数据加入发布包。

config.yaml 保留 data/db、data/images 等逻辑路径;运行时路径解析层负责把前导 data/ 替换为 AstrBot 插件数据根目录。本地开发则继续映射到仓库的 data/。不要在配置默认值中重复写完整 data/plugin_data/astrbot_plugin_imagestudio/ 前缀。

本地前端开发

Windows 上若 PowerShell 阻止 npm.ps1,使用 npm.cmd:

cd frontend
npm.cmd install
npm.cmd run typecheck
npm.cmd run dev:plugin

dev:plugin 只用于本地开发。生产构建:

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 用户被强制安装额外二进制依赖。

验证

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 契约

契约 endpoint 为相对路径:

GET contract

插件页面通过 bridge 调用时传 contract;直接请求时使用:

GET /api/v1/plugins/extensions/astrbot_plugin_imagestudio/contract