mirror of
https://github.com/EstrellaXD/Auto_Bangumi.git
synced 2026-10-29 11:46:17 +08:00
776abfa896
- API 参考按实际路由重写，修正认证方式、请求方法与设置向导端点 - 数据库指南改为异步 Database 与 MIGRATIONS - E2E 指南改为指向 e2e/README.md - 插件快速上手补上安装 SDK 轮子的步骤，ab-plugin dev 加 --config-dir - 发布流程改为手动推送标签触发
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 命令行 ab-plugin
|
||
|
||
`ab-plugin` 随 `autobangumi-sdk` 轮子安装，只依赖 `ab_sdk`，不需要安装 AutoBangumi。
|
||
|
||
```bash
|
||
uv tool install ./autobangumi_sdk-0.5.0-py3-none-any.whl
|
||
# 或在项目里：uv add ./autobangumi_sdk-0.5.0-py3-none-any.whl
|
||
```
|
||
|
||
轮子在 4.0 beta / 正式版的 GitHub Release 附件中，不发布到 PyPI，见 [获取 SDK](/dev/plugins/sdk)。契约测试需要 pytest：`new` 生成的 `pyproject.toml` 已在 `dev` 依赖组里带上 pytest；自己建的项目用 `uv add --dev pytest`（或安装 `autobangumi-sdk[test]`）。
|
||
|
||
## new
|
||
|
||
```bash
|
||
ab-plugin new <id> [--kind rename|notifier|search] [--dir .]
|
||
```
|
||
|
||
生成 `<id>/` 目录：
|
||
|
||
```
|
||
<id>/
|
||
├── plugin.toml
|
||
├── <id 的下划线形式>/__init__.py # 插件代码
|
||
├── tests/test_contract.py # 继承 ab_sdk.testing 的契约套件
|
||
├── pyproject.toml # 仅用于开发，不会被打包
|
||
└── README.md
|
||
```
|
||
|
||
`id` 只能由小写字母、数字和连字符组成。目录已存在时拒绝执行。没有下载器骨架：下载器要连接真实后端，一个能直接通过契约的骨架没有意义。
|
||
|
||
生成的 `pyproject.toml` 依赖 `autobangumi-sdk`。这个包不在 PyPI 上，运行 `uv run pytest` 前先在插件目录里执行一次 `uv add <轮子路径>`，uv 会把依赖指向本地轮子。
|
||
|
||
## validate
|
||
|
||
```bash
|
||
ab-plugin validate [path]
|
||
```
|
||
|
||
校验清单字段、`sdk` 版本范围是否包含当前 SDK、入口模块是否存在、前端入口文件是否存在，并拒绝含原生扩展（`.so` / `.pyd` / `.dylib` / `.dll`）的目录。有问题时退出码为 1。
|
||
|
||
## pack
|
||
|
||
```bash
|
||
ab-plugin pack [path] [-o dist]
|
||
```
|
||
|
||
先校验，再打成 `dist/<id>-<版本>.zip`。zip 内容在 zip 根（与签名目录的包布局一致）。排除 `tests/`、`pyproject.toml`、`uv.lock`、`dist/`、`.venv`、`.git`、`node_modules`、各类缓存和 `.pyc`。文件顺序与时间戳固定：同样的内容得到同样的 sha256。
|
||
|
||
## dev
|
||
|
||
```bash
|
||
ab-plugin dev [path] [--config-dir config]
|
||
```
|
||
|
||
- 先校验，再把插件目录软链到 `<config-dir>/plugins/local/<id>`。
|
||
- `--config-dir` 默认是当前目录下的 `config`。在插件目录里运行时，请指向 AB 的配置目录（源码运行时为 `backend/src/config`）。
|
||
- 软链接指向插件目录的绝对路径，AB 必须能用同一路径访问它（例如源码运行的 AB）。AB 在 Docker 中运行时，请把插件目录复制或挂载到容器的 `config/plugins/local/<id>/`，再在 设置 → 插件 中开启「允许未签名插件」并启用它。
|
||
- 在宿主配置文件（先找 `config_dev.json`，再找 `config.json`）里写入 `plugins.dev_mode`、`plugins.allow_unsigned` 和 `plugins.enabled.<id>`。
|
||
- 配置文件不存在时拒绝执行：请先启动一次 AutoBangumi。
|
||
- 运行中的 AB 不会重读配置文件，需要重启一次。之后，`dev_mode` 每秒检查一次本地插件目录，文件变化后自动重载该插件。上次加载失败的插件也被监听，修好源码后自动恢复。
|
||
- `dev_mode` 只监听本地目录，不监听 pip 包，也不会发现新出现的插件目录（等下一次配置变更或重启）。
|
||
|
||
## 开发循环
|
||
|
||
```bash
|
||
ab-plugin new my-notify --kind notifier
|
||
cd my-notify
|
||
uv add ../autobangumi_sdk-0.5.0-py3-none-any.whl # 只需一次
|
||
uv run pytest # 契约测试
|
||
ab-plugin dev . --config-dir /path/to/autobangumi/config # 链接并开启热重载，重启 AB 一次
|
||
# 改代码 → AB 自动重载 → 在 WebUI 里验证
|
||
ab-plugin pack .
|
||
```
|