astrbot_plugin_moviepilot/docs/development-queue.md

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:媒体查询主链路

调用:

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:

  1. 阶段 0 全部。
  2. 阶段 1 的 Client、权限、缓存、确认服务。
  3. 阶段 2 的媒体搜索、详情、资源搜索。
  4. 阶段 3 的订阅和立即下载。
  5. 阶段 4 的通知轮询和固定推送。
  6. 命令树中的 help、test、search、resources、subscribe、download、confirm。

MVP 完成后再实现订阅管理、下载任务控制、Telegram 兼容和 LLM Tool。这样即使后续复杂 API 字段需要调整,也不会阻塞核心链路验证。