412 行
11 KiB
Markdown
412 行
11 KiB
Markdown
# AstrBot × MoviePilot 开发队列
|
||
|
||
> 状态:方案确认后生成
|
||
>
|
||
> 目标:在 AstrBot 内提供 MoviePilot 的命令控制、LLM 调用和固定目标通知能力。
|
||
|
||
## 总体原则
|
||
|
||
- 先做确定性的 REST API 桥接,再做 LLM Tool。
|
||
- 先完成“搜索媒体 → 搜索资源 → 订阅/下载”的主链路,再扩展后台管理能力。
|
||
- 所有网络调用使用异步 HTTP 客户端,不使用 `requests`。
|
||
- API Token 只存在于 AstrBot 配置和内存请求头中,不写入日志和用户回复。
|
||
- 命令和 LLM 共用同一套 MoviePilot Client、权限校验、会话缓存和确认服务。
|
||
- 破坏性或有副作用的操作必须经过确认。
|
||
|
||
## 阶段 0:插件骨架与配置
|
||
|
||
### 任务 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 字段敏感显示;配置修改后不会要求手工编辑文件。
|
||
|
||
## 阶段 1:公共基础层
|
||
|
||
### 任务 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` 取消当前待确认操作。
|
||
- 确认码只能由原会话、原白名单用户使用。
|
||
- 重复确认、过期确认、目标已变化时拒绝执行。
|
||
|
||
**验收:** 确认码无法跨群或跨用户使用;过期后不执行副作用操作。
|
||
|
||
## 阶段 2:媒体查询主链路
|
||
|
||
### 任务 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 返回结果截断。
|
||
- 展示资源标题、大小、质量、分辨率、站点和做种信息等摘要。
|
||
- 写入会话资源结果缓存。
|
||
- 无结果时提示可订阅媒体。
|
||
|
||
**验收:** 资源编号可以安全映射到后续下载操作;不存在资源时不误报为网络错误。
|
||
|
||
## 阶段 3:订阅和立即下载
|
||
|
||
### 任务 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。
|
||
|
||
删除下载任务必须二次确认。
|
||
|
||
## 阶段 4:固定目标通知推送
|
||
|
||
### 任务 4.1 实现通知轮询器
|
||
|
||
调用:
|
||
|
||
```text
|
||
GET /api/v1/message/notification
|
||
```
|
||
|
||
功能:
|
||
|
||
- 默认 60~120 秒轮询。
|
||
- 记录最后处理通知的游标。
|
||
- 去重。
|
||
- 插件启动时不重放旧通知。
|
||
- MoviePilot 不可达时指数退避。
|
||
- 插件停止/重载时正确取消后台任务。
|
||
|
||
### 任务 4.2 实现推送目标解析
|
||
|
||
支持两个独立目标:
|
||
|
||
- 一个固定群聊。
|
||
- 一个固定个人账号。
|
||
|
||
通知发送使用 AstrBot 的平台消息能力,不直接调用 OneBot API;平台适配差异由 AstrBot 负责。
|
||
|
||
### 任务 4.3 设计通知格式和过滤
|
||
|
||
至少支持:
|
||
|
||
- 下载完成。
|
||
- 订阅命中资源。
|
||
- 下载失败。
|
||
- 订阅搜索失败。
|
||
- MoviePilot 错误通知。
|
||
|
||
通知格式应包含:标题、媒体类型、资源摘要、状态、时间和必要的 MoviePilot 跳转地址(如果返回)。Token、完整站点凭据和不必要的下载链接不得发送。
|
||
|
||
## 阶段 5:命令组织和平台兼容
|
||
|
||
### 任务 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 后续验证命令格式和目标消息发送能力。
|
||
|
||
## 阶段 6:LLM Tool 和确认工作流
|
||
|
||
### 任务 6.1 添加只读 LLM Tools
|
||
|
||
- 搜索媒体。
|
||
- 获取媒体详情。
|
||
- 搜索资源。
|
||
- 查询订阅。
|
||
- 查询下载任务。
|
||
- 查询通知。
|
||
|
||
工具输出使用结构化、短结果,避免把大量资源列表塞进上下文。
|
||
|
||
### 任务 6.2 添加写操作 LLM Tools
|
||
|
||
- 创建订阅。
|
||
- 立即下载资源。
|
||
- 触发订阅搜索。
|
||
- 开始/暂停下载。
|
||
- 删除订阅。
|
||
- 删除下载任务。
|
||
|
||
所有写操作统一进入确认服务;LLM 只能创建待确认操作,不能绕过 `/mp confirm`。
|
||
|
||
### 任务 6.3 添加自然语言链路
|
||
|
||
支持类似:
|
||
|
||
> 搜索《沙丘 2》,看看有没有 4K 资源;如果有,告诉我选哪个。
|
||
|
||
以及:
|
||
|
||
> 把刚才第 2 个资源下载下来。
|
||
|
||
LLM 必须在执行前明确展示媒体、资源、站点、大小和操作类型。
|
||
|
||
## 阶段 7:测试、联调和文档
|
||
|
||
### 任务 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 字段需要调整,也不会阻塞核心链路验证。
|