astrbot_plugin_moviepilot/docs/development-queue.md

430 行
12 KiB
Markdown

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

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

# 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`
调用:
```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 <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 实现通知轮询器
调用:
```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 字段需要调整,也不会阻塞核心链路验证。