# 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 ` 执行操作。 - `/mp cancel` 取消当前待确认操作。 - 确认码只能由原会话、原白名单用户使用。 - 重复确认、过期确认、目标已变化时拒绝执行。 **验收:** 确认码无法跨群或跨用户使用;过期后不执行副作用操作。 ## 阶段 3:媒体查询主链路 ### 任务 2.1 实现 `/mp search` 调用: ```text GET /api/v1/media/search ``` 功能: - 支持关键词。 - 支持电影/电视剧类型筛选。 - 支持页码和结果数量。 - 格式化标题、年份、类型、媒体 ID、评分、简介和海报。 - 写入会话媒体结果缓存。 **验收:** 能从搜索结果稳定生成 `/mp resources <编号>` 和 `/mp subscribe <编号>` 所需的媒体引用。 ### 任务 2.2 实现媒体详情和季信息 命令: ```text /mp detail <媒体编号或媒体ID> /mp seasons <媒体编号或媒体ID> ``` 调用: - `/api/v1/media/{mediaid}`。 - `/api/v1/media/seasons`。 **验收:** 电视剧订阅前可以识别季号;电影不会错误要求季号。 ### 任务 2.3 实现 `/mp resources` 调用: ```text GET /api/v1/search/media/{mediaid} ``` 功能: - 使用会话媒体结果编号。 - 支持分页或按 MoviePilot 返回结果截断。 - 展示资源标题、大小、质量、分辨率、站点和做种信息等摘要。 - 写入会话资源结果缓存。 - 无结果时提示可订阅媒体。 **验收:** 资源编号可以安全映射到后续下载操作;不存在资源时不误报为网络错误。 ## 阶段 4:订阅和立即下载 ### 任务 3.1 实现 `/mp subscribe` 调用: ```text POST /api/v1/subscribe/ ``` 功能: - 从会话媒体缓存获取媒体信息。 - 使用 MoviePilot 当前配置的站点、下载器、保存路径和质量策略。 - 支持电影和电视剧;电视剧支持季号。 - 成功创建订阅后自动调用: ```text GET /api/v1/subscribe/search/{subscribe_id} ``` - 自动搜索失败不回滚订阅。 - 回复订阅创建结果和后续搜索结果。 **验收:** 创建成功、重复订阅、媒体不存在、季号错误、自动搜索失败都能给出明确结果。 ### 任务 3.2 实现订阅查询和控制 命令: ```text /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` 调用: ```text POST /api/v1/download/add ``` 功能: - 从会话资源缓存获取资源。 - 在确认消息中展示标题、站点、大小、质量和目标媒体。 - 用户确认后将资源提交给 MoviePilot。 - 下载链接不直接回传聊天窗口。 下载操作必须二次确认。 ### 任务 3.4 实现下载任务管理 命令: ```text /mp downloads /mp download start /mp download stop /mp download delete ``` 调用: - `/api/v1/download/`。 - `/api/v1/download/start/{hashString}`。 - `/api/v1/download/stop/{hashString}`。 - `/api/v1/download/{hashString}` DELETE。 删除下载任务必须二次确认。 ## 阶段 5:固定目标通知推送 ### 任务 4.1 实现通知轮询器 调用: ```text GET /api/v1/message/notification ``` 功能: - 默认 60~120 秒轮询。 - 记录最后处理通知的游标。 - 去重。 - 插件启动时不重放旧通知。 - MoviePilot 不可达时指数退避。 - 插件停止/重载时正确取消后台任务。 ### 任务 4.2 实现推送目标解析 支持两个独立目标: - 一个固定群聊。 - 一个固定个人账号。 通知发送使用 AstrBot 的平台消息能力,不直接调用 OneBot API;平台适配差异由 AstrBot 负责。 ### 任务 4.3 设计通知格式和过滤 至少支持: - 下载完成。 - 订阅命中资源。 - 下载失败。 - 订阅搜索失败。 - MoviePilot 错误通知。 通知格式应包含:标题、媒体类型、资源摘要、状态、时间和必要的 MoviePilot 跳转地址(如果返回)。Token、完整站点凭据和不必要的下载链接不得发送。 ## 阶段 6:命令组织和平台兼容 ### 任务 5.1 完善命令树 统一命令入口: ```text /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 字段需要调整,也不会阻塞核心链路验证。