astrbot_plugin_moviepilot/docs/integration.md

3 KiB

安装与联调说明

安装

将插件目录放到 AstrBot:

AstrBot/data/plugins/astrbot_plugin_moviepilot/

目录至少需要包含:

metadata.yaml
_conf_schema.json
main.py
moviepilot_client.py

启动 AstrBot 后,在插件管理页面重载插件,并在插件配置页面填写 MoviePilot 地址和 API Token。

配置建议

MoviePilot

  • 地址填写 MoviePilot 的服务根地址,例如 http://192.168.1.20:3000。
  • 不要把 /api/v1 拼到配置地址末尾。
  • 使用 MoviePilot 的 API Token。
  • AstrBot 和 MoviePilot 在同一局域网时,填写 AstrBot 容器能够访问的地址;不能只填写 MoviePilot 容器内部的 localhost。

OneBot 11 / QQ

  • allowed_platforms 保留 aiocqhttp。
  • private_user_ids 填允许操作的用户标识。
  • group_permissions 中填写群标识和群内用户标识。
  • 群聊操作必须同时匹配群和用户。
  • push_platform_id 使用发送通知的 AstrBot 平台实例 ID。

Telegram

  • allowed_platforms 增加 telegram。
  • 根据 AstrBot 实际事件使用的用户/会话标识填写白名单。
  • push_platform_id 设置为 telegram。
  • Telegram 的群聊/私聊主动发送能力需要由当前 AstrBot 适配器和 Bot 权限支持。

实机联调顺序

  1. 先在 AstrBot WebUI 保存配置并重载插件。
  2. 使用白名单私聊执行 /mp test,验证插件加载、MoviePilot 地址和 API Token。
  3. 执行 /mp search 测试影片,确认返回媒体编号。
  4. 执行 /mp resources 1,确认返回资源编号和摘要。
  5. 先用测试资源执行 /mp download 1,确认收到确认码;再执行 /mp cancel 验证取消流程。
  6. 再次执行下载并使用 /mp confirm <确认码>,确认 MoviePilot 出现下载任务。
  7. 执行 /mp subscribe 1,确认订阅创建并触发一次搜索。
  8. 验证 /mp downloads、/mp subscriptions 和任务控制命令。
  9. 配置固定群聊/个人账号,等待一个轮询周期验证通知推送和去重。
  10. 最后测试 LLM 的搜索、资源查询、订阅确认和下载确认链路。

常见问题

401/403

检查 MoviePilot API Token,以及请求是否确实到达目标 MoviePilot 实例。

连接超时

检查容器网络、局域网防火墙、反向代理和 MoviePilot 监听地址;AstrBot 容器内的 localhost 指向 AstrBot 容器自身。

编号无效或过期

搜索结果按会话保存并受 TTL 限制。重新执行对应的 /mp search 或 /mp resources 即可。

没有推送

检查轮询是否启用、推送平台 ID 是否正确、目标群/用户是否可由 AstrBot 主动发送,以及 MoviePilot 通知历史中是否出现了新记录。

尚需实机确认

  • 当前 MoviePilot 版本返回的资源字段是否都能被 /api/v1/download/add 接受。
  • 不同下载器、站点和保存策略下的订阅 Body 行为。
  • OneBot 11 和 Telegram 部署中的实际平台实例 ID。
  • MoviePilot 通知历史 ID 的稳定性和轮询分页行为。