命令行 ab-plugin

ab-plugin 随 autobangumi-sdk 轮子安装，只依赖 ab_sdk，不需要安装 AutoBangumi。

uv tool install ./autobangumi_sdk-0.6.0-py3-none-any.whl
# 或在项目里：uv add ./autobangumi_sdk-0.6.0-py3-none-any.whl

轮子在 4.0 beta / 正式版的 GitHub Release 附件中，不发布到 PyPI，见 获取 SDK。契约测试需要 pytest：new 生成的 pyproject.toml 已在 dev 依赖组里带上 pytest；自己建的项目用 uv add --dev pytest（或安装 autobangumi-sdk[test]）。

new

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

ab-plugin validate [path]

校验清单字段、sdk 版本范围是否包含当前 SDK、入口模块是否存在、前端入口文件是否存在，并拒绝含原生扩展（.so / .pyd / .dylib / .dll）的目录。有问题时退出码为 1。

pack

ab-plugin pack [path] [-o dist]

先校验，再打成 dist/<id>-<版本>.zip。zip 内容在 zip 根（与签名目录的包布局一致）。排除 tests/、pyproject.toml、uv.lock、dist/、.venv、.git、node_modules、各类缓存和 .pyc。文件顺序与时间戳固定：同样的内容得到同样的 sha256。

dev

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 包，也不会发现新出现的插件目录（等下一次配置变更或重启）。

开发循环

ab-plugin new my-notify --kind notifier
cd my-notify
uv add ../autobangumi_sdk-0.6.0-py3-none-any.whl   # 只需一次
uv run pytest            # 契约测试
ab-plugin dev . --config-dir /path/to/autobangumi/config   # 链接并开启热重载，重启 AB 一次
# 改代码 → AB 自动重载 → 在 WebUI 里验证
ab-plugin pack .