astrbot_plugin_moviepilot/docs/integration.md

98 行
3.5 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 安装与联调说明
## 安装
将插件目录放到 AstrBot:
```text
AstrBot/data/plugins/astrbot_plugin_moviepilot/
```
目录至少需要包含:
```text
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 的稳定性和轮询分页行为。
## ?????
- `moviepilot_timeout`???????????? 20?
- `moviepilot_retries`??????HTTP 429 ? 5xx ???????? 2?
- `moviepilot_retry_backoff`?????????? 0.5 ??
????????????????? API Token?`/mp test` ??????????????????????
## ?????
????? AstrBot ?????? `sessions.json` ? `notification_cursor.json`??????????? `/mp test`????????????????????????
## Telegram ??
Telegram ?????? AstrBot ?????????????????????? `/mp test`??? QQ ?????? `/mp search`?`/mp resources`?`/mp subscribe`?`/mp confirm`??? Telegram ???????????????????????????????????????