12 KiB
AstrBot × MoviePilot 开发队列
状态:方案确认后生成
目标:在 AstrBot 内提供 MoviePilot 的命令控制、LLM 调用和固定目标通知能力。
执行映射
本文件的详细内容按实现依赖分组;实际版本推送按以下 11 项执行,每项对应一个版本标签:
| 项目 | 实现内容 | 版本 |
|---|---|---|
| 1 | 插件骨架与 WebUI 配置 | v0.1.0 |
| 2 | MoviePilot REST Client | v0.2.0 |
| 3 | 平台白名单权限服务 | v0.3.0 |
| 4 | 会话缓存和确认机制 | v0.4.0 |
| 5 | 媒体与资源搜索 | v0.5.0 |
| 6 | 订阅与立即下载 | v0.6.0 |
| 7 | 下载任务控制 | v0.7.0 |
| 8 | 固定目标通知推送 | v0.8.0 |
| 9 | QQ / Telegram 平台兼容 | v0.9.0 |
| 10 | LLM Tool 和确认工作流 | v0.10.0 |
| 11 | 测试、联调和文档 | v0.11.0 |
总体原则
- 先做确定性的 REST API 桥接,再做 LLM Tool。
- 先完成“搜索媒体 → 搜索资源 → 订阅/下载”的主链路,再扩展后台管理能力。
- 所有网络调用使用异步 HTTP 客户端,不使用
requests。 - API Token 只存在于 AstrBot 配置和内存请求头中,不写入日志和用户回复。
- 命令和 LLM 共用同一套 MoviePilot Client、权限校验、会话缓存和确认服务。
- 破坏性或有副作用的操作必须经过确认。
阶段 1:插件骨架与配置
任务 0.1 创建插件目录结构
- 创建
metadata.yaml。 - 创建
main.py。 - 创建
_conf_schema.json。 - 创建
requirements.txt,优先使用 AstrBot 已有的异步 HTTP 依赖,只有缺少时才新增依赖。 - 建立
tests/和基础测试夹具。
验收: AstrBot 能发现、加载、卸载和重载插件;插件缺少配置或 MoviePilot 不可达时不会导致 AstrBot 崩溃。
任务 0.2 设计 WebUI 配置
配置项:
- MoviePilot Base URL。
- MoviePilot API Token。
- OneBot 11 私聊用户白名单。
- OneBot 11 群聊及群内用户白名单。
- 固定推送群聊目标。
- 固定推送个人账号目标。
- 通知轮询间隔,默认 60~120 秒可配置。
- 搜索结果缓存有效期。
- 是否启用通知轮询。
验收: 配置可以通过 AstrBot WebUI 修改;Token 字段敏感显示;配置修改后不会要求手工编辑文件。
阶段 2:公共基础层
任务 1.1 实现 MoviePilot REST Client
实现统一的异步请求封装:
- Base URL 规范化。
X-API-KEY鉴权。- GET/POST/PUT/DELETE。
- JSON 编解码。
- 连接超时和读取超时。
- HTTP 错误、MoviePilot
success/message/data响应解析。 - 脱敏日志。
- 可识别的异常类型:配置错误、连接失败、鉴权失败、API 错误、响应格式错误。
验收: 通过 mock HTTP 服务覆盖成功、401、403、404、超时、无效 JSON 和 MoviePilot 失败响应。
任务 1.2 实现权限服务
- 判断当前事件是否来自允许平台。
- 读取 AstrBot/OneBot 11 的群号和用户号。
- 私聊用户白名单判断。
- 群聊群白名单 + 群内用户白名单判断。
- Telegram 预留统一的
PlatformIdentity抽象。 - 未授权请求统一处理,不泄露 MoviePilot 地址和 Token 信息。
验收: 覆盖允许私聊、拒绝私聊、允许群成员、拒绝群成员、拒绝非白名单群、缺失平台身份等情况。
任务 1.3 实现会话上下文缓存
为每个 AstrBot 会话保存:
- 最近媒体搜索结果。
- 最近资源搜索结果。
- 操作编号与 MoviePilot ID 的映射。
- 创建时间和过期时间。
- 待确认操作。
建议使用 event.unified_msg_origin 作为会话主键,并把缓存数据存放到 AstrBot data 目录体系中。
验收: 不同群聊/私聊之间编号不串线;过期编号会得到明确提示;插件重载后数据行为符合配置预期。
任务 1.4 实现确认服务
- 为下载、删除订阅、删除下载任务等操作生成短确认码。
- 绑定确认码、会话、用户、目标对象和过期时间。
/mp confirm <code>执行操作。/mp cancel取消当前待确认操作。- 确认码只能由原会话、原白名单用户使用。
- 重复确认、过期确认、目标已变化时拒绝执行。
验收: 确认码无法跨群或跨用户使用;过期后不执行副作用操作。
阶段 3:媒体查询主链路
任务 2.1 实现 /mp search
调用:
GET /api/v1/media/search
功能:
- 支持关键词。
- 支持电影/电视剧类型筛选。
- 支持页码和结果数量。
- 格式化标题、年份、类型、媒体 ID、评分、简介和海报。
- 写入会话媒体结果缓存。
验收: 能从搜索结果稳定生成 /mp resources <编号> 和 /mp subscribe <编号> 所需的媒体引用。
任务 2.2 实现媒体详情和季信息
命令:
/mp detail <媒体编号或媒体ID>
/mp seasons <媒体编号或媒体ID>
调用:
/api/v1/media/{mediaid}。/api/v1/media/seasons。
验收: 电视剧订阅前可以识别季号;电影不会错误要求季号。
任务 2.3 实现 /mp resources
调用:
GET /api/v1/search/media/{mediaid}
功能:
- 使用会话媒体结果编号。
- 支持分页或按 MoviePilot 返回结果截断。
- 展示资源标题、大小、质量、分辨率、站点和做种信息等摘要。
- 写入会话资源结果缓存。
- 无结果时提示可订阅媒体。
验收: 资源编号可以安全映射到后续下载操作;不存在资源时不误报为网络错误。
阶段 4:订阅和立即下载
任务 3.1 实现 /mp subscribe
调用:
POST /api/v1/subscribe/
功能:
-
从会话媒体缓存获取媒体信息。
-
使用 MoviePilot 当前配置的站点、下载器、保存路径和质量策略。
-
支持电影和电视剧;电视剧支持季号。
-
成功创建订阅后自动调用:
GET /api/v1/subscribe/search/{subscribe_id} -
自动搜索失败不回滚订阅。
-
回复订阅创建结果和后续搜索结果。
验收: 创建成功、重复订阅、媒体不存在、季号错误、自动搜索失败都能给出明确结果。
任务 3.2 实现订阅查询和控制
命令:
/mp subscriptions
/mp sub-search <订阅ID>
/mp unsubscribe <订阅ID或媒体编号>
/mp refresh
调用:
/api/v1/subscribe/list。/api/v1/subscribe/search/{subscribe_id}。/api/v1/subscribe/media/{mediaid}。/api/v1/subscribe/media/{mediaid}DELETE。/api/v1/subscribe/refresh。
删除订阅必须进入确认流程。
任务 3.3 实现 /mp download
调用:
POST /api/v1/download/add
功能:
- 从会话资源缓存获取资源。
- 在确认消息中展示标题、站点、大小、质量和目标媒体。
- 用户确认后将资源提交给 MoviePilot。
- 下载链接不直接回传聊天窗口。
下载操作必须二次确认。
任务 3.4 实现下载任务管理
命令:
/mp downloads
/mp download start <hash>
/mp download stop <hash>
/mp download delete <hash>
调用:
/api/v1/download/。/api/v1/download/start/{hashString}。/api/v1/download/stop/{hashString}。/api/v1/download/{hashString}DELETE。
删除下载任务必须二次确认。
阶段 5:固定目标通知推送
任务 4.1 实现通知轮询器
调用:
GET /api/v1/message/notification
功能:
- 默认 60~120 秒轮询。
- 记录最后处理通知的游标。
- 去重。
- 插件启动时不重放旧通知。
- MoviePilot 不可达时指数退避。
- 插件停止/重载时正确取消后台任务。
任务 4.2 实现推送目标解析
支持两个独立目标:
- 一个固定群聊。
- 一个固定个人账号。
通知发送使用 AstrBot 的平台消息能力,不直接调用 OneBot API;平台适配差异由 AstrBot 负责。
任务 4.3 设计通知格式和过滤
至少支持:
- 下载完成。
- 订阅命中资源。
- 下载失败。
- 订阅搜索失败。
- MoviePilot 错误通知。
通知格式应包含:标题、媒体类型、资源摘要、状态、时间和必要的 MoviePilot 跳转地址(如果返回)。Token、完整站点凭据和不必要的下载链接不得发送。
阶段 6:命令组织和平台兼容
任务 5.1 完善命令树
统一命令入口:
/mp help
/mp test
/mp search <关键词>
/mp detail <编号>
/mp resources <编号>
/mp subscribe <编号>
/mp download <编号>
/mp subscriptions
/mp sub-search <订阅ID>
/mp unsubscribe <订阅ID或媒体ID>
/mp downloads
/mp notifications
/mp confirm <确认码>
/mp cancel
命令处理器只负责解析参数、检查权限和组织回复;业务调用集中在服务层。
任务 5.2 QQ / Telegram 兼容
- 抽象平台身份读取。
- 抽象固定群聊/个人目标构造。
- 统一会话缓存主键。
- 统一纯文本和图片回复。
- QQ 先行测试,Telegram 后续验证命令格式和目标消息发送能力。
阶段 7:LLM Tool 和确认工作流
任务 6.1 添加只读 LLM Tools
- 搜索媒体。
- 获取媒体详情。
- 搜索资源。
- 查询订阅。
- 查询下载任务。
- 查询通知。
工具输出使用结构化、短结果,避免把大量资源列表塞进上下文。
任务 6.2 添加写操作 LLM Tools
- 创建订阅。
- 立即下载资源。
- 触发订阅搜索。
- 开始/暂停下载。
- 删除订阅。
- 删除下载任务。
所有写操作统一进入确认服务;LLM 只能创建待确认操作,不能绕过 /mp confirm。
任务 6.3 添加自然语言链路
支持类似:
搜索《沙丘 2》,看看有没有 4K 资源;如果有,告诉我选哪个。
以及:
把刚才第 2 个资源下载下来。
LLM 必须在执行前明确展示媒体、资源、站点、大小和操作类型。
阶段 8:测试、联调和文档
任务 7.1 单元测试
- MoviePilot Client。
- API Token 脱敏。
- MoviePilot 错误转换。
- 权限白名单。
- 会话缓存隔离和过期。
- 确认码隔离和过期。
- 订阅 Body 构造。
- 资源到下载请求的字段映射。
- 通知游标和去重。
任务 7.2 Mock API 集成测试
使用 mock MoviePilot 服务覆盖:
- 媒体搜索。
- 资源搜索。
- 创建订阅。
- 自动触发订阅搜索。
- 立即下载。
- 查询通知。
- API Token 错误。
- 网络超时。
任务 7.3 实机联调
需要准备:
- 可访问的 MoviePilot Base URL。
- API Token 通过 AstrBot 配置注入。
- 至少一个可用媒体搜索源。
- 至少一个可用资源站点。
- 一个测试 QQ 群和测试用户。
- 一个测试推送群聊或个人账号。
实机重点确认:
- 媒体 ID 和媒体类型映射。
- 资源结果中可提交下载的字段。
- 订阅创建字段和默认策略继承。
- 通知历史的稳定游标字段。
- AstrBot 到固定 QQ/Telegram 目标的发送行为。
任务 7.4 使用文档
- 安装方式。
- 配置示例。
- OneBot 11 白名单填写说明。
- 命令帮助。
- LLM 使用示例。
- 推送说明。
- 常见错误排查。
- Token 和网络安全建议。
建议的首个可交付版本
第一轮不要一次完成全部队列,建议以以下范围作为 MVP:
- 阶段 0 全部。
- 阶段 1 的 Client、权限、缓存、确认服务。
- 阶段 2 的媒体搜索、详情、资源搜索。
- 阶段 3 的订阅和立即下载。
- 阶段 4 的通知轮询和固定推送。
- 命令树中的
help、test、search、resources、subscribe、download、confirm。
MVP 完成后再实现订阅管理、下载任务控制、Telegram 兼容和 LLM Tool。这样即使后续复杂 API 字段需要调整,也不会阻塞核心链路验证。