3.5 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 compileall adapters backend core database engines scripts tests main.py
cd frontend
npm.cmd run typecheck
npm.cmd run build:plugin
npm.cmd run build:web
生产构建必须同时提交 pages/imagestudio/ 的最新插件页面产物。web/ 仅是独立预览兼容产物,但若仓库保留它,也应与同一份前端源码同步构建,避免两个产物行为漂移。
API 契约
契约 endpoint 为相对路径:
GET contract
插件页面通过 bridge 调用时传 contract;直接请求时使用:
GET /api/v1/plugins/extensions/astrbot_plugin_imagestudio/contract