commit fcc72ba3d0f6eb11adce65d1c2a0b28139398cba Author: Codex Date: Mon Jul 20 22:13:04 2026 +0800 feat: add MoviePilot plugin skeleton diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2eb4b18 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +__pycache__/ +*.py[cod] +.pytest_cache/ +.venv/ +venv/ +.env + diff --git a/README.md b/README.md new file mode 100644 index 0000000..dd62581 --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# AstrBot MoviePilot 插件 + +在 AstrBot 内通过命令和 LLM 控制 MoviePilot。 + +## 当前状态 + +当前完成插件骨架和配置 schema。后续按 `docs/development-queue.md` 逐阶段实现。 + +## 安装开发版本 + +将本目录放到 AstrBot 的 `data/plugins/astrbot_plugin_moviepilot`,启动 AstrBot 后在插件管理页面重载。 + +## 配置 + +在 AstrBot WebUI 的插件配置中填写: + +- MoviePilot 地址和 API Token; +- 私聊用户白名单; +- 群聊及群内用户白名单; +- 固定推送群聊和个人账号; +- 通知轮询间隔。 + +API Token 仅用于访问 MoviePilot,不要粘贴到聊天消息或提交到日志中。 diff --git a/_conf_schema.json b/_conf_schema.json new file mode 100644 index 0000000..58e3a46 --- /dev/null +++ b/_conf_schema.json @@ -0,0 +1,75 @@ +{ + "moviepilot_url": { + "description": "MoviePilot 服务地址", + "type": "string", + "hint": "例如 http://192.168.1.10:3000,不要填写 /api/v1 后缀", + "obvious_hint": true, + "default": "" + }, + "moviepilot_api_token": { + "description": "MoviePilot API Token", + "type": "string", + "hint": "用于 X-API-KEY 请求头鉴权;请勿在聊天消息或日志中泄露", + "obvious_hint": true, + "default": "" + }, + "private_user_ids": { + "description": "允许操作的私聊用户", + "type": "list", + "hint": "填写 AstrBot / OneBot 11 使用的用户标识", + "default": [] + }, + "group_permissions": { + "description": "允许操作的群聊及群内用户", + "type": "template_list", + "hint": "群聊操作需要同时命中群标识和群内用户标识", + "templates": { + "group": { + "name": "群聊白名单", + "display_item": "group_id", + "items": { + "group_id": { + "description": "群聊标识", + "type": "string", + "default": "" + }, + "user_ids": { + "description": "群内用户标识", + "type": "list", + "default": [] + } + } + } + }, + "default": [] + }, + "push_group_id": { + "description": "通知推送群聊", + "type": "string", + "hint": "留空表示不推送到固定群聊", + "default": "" + }, + "push_private_user_id": { + "description": "通知推送个人账号", + "type": "string", + "hint": "留空表示不推送到固定个人账号", + "default": "" + }, + "notification_poll_interval": { + "description": "通知轮询间隔(秒)", + "type": "int", + "hint": "建议设置为 60~120 秒", + "default": 60 + }, + "search_cache_ttl": { + "description": "搜索结果缓存有效期(秒)", + "type": "int", + "hint": "超过有效期后,搜索结果编号不能继续用于订阅或下载", + "default": 600 + }, + "enable_notification_polling": { + "description": "启用 MoviePilot 通知轮询", + "type": "bool", + "default": true + } +} diff --git a/docs/development-queue.md b/docs/development-queue.md new file mode 100644 index 0000000..6a771c7 --- /dev/null +++ b/docs/development-queue.md @@ -0,0 +1,412 @@ +# 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 ` 执行操作。 +- `/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 +/mp download stop +/mp download delete +``` + +调用: + +- `/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 字段需要调整,也不会阻塞核心链路验证。 diff --git a/docs/research-2026-07-20.md b/docs/research-2026-07-20.md new file mode 100644 index 0000000..ae651f1 --- /dev/null +++ b/docs/research-2026-07-20.md @@ -0,0 +1,328 @@ +# AstrBot × MoviePilot 集成调研 + +> 调研日期:2026-07-20 +> +> 目标:先确认 AstrBot 插件能力和 MoviePilot 外置接口,再讨论插件边界与开发队列。本文件是第一版调研,不代表最终产品设计。 + +## 1. 本次阅读的源码版本 + +| 项目 | 本地参考路径 | 读取到的提交 | +|---|---|---| +| AstrBot | `C:\Users\Administrator\Documents\Codex\refs\AstrBot` | `fed29848ca0b3912ab6a8200a10cd0f2cb080f85`,4.26.7 版本提交 | +| MoviePilot | `C:\Users\Administrator\Documents\Codex\refs\MoviePilot` | `5c2b503a74eb85a3055b09e1e8d2c15deb08e0a1`,2026-07-20 拉取 | + +用户提供的上游仓库: + +- `https://github.com/AstrBotDevs/AstrBot` +- `https://github.com/jxxghp/MoviePilot` + +## 2. AstrBot 插件接口结论 + +### 2.1 插件基本结构 + +最小可用插件通常包含: + +```text +astrbot_plugin_moviepilot/ + metadata.yaml + main.py + requirements.txt # 只有需要额外依赖时添加 + _conf_schema.json # 需要 WebUI 配置时添加 +``` + +插件类继承 `Star`,初始化时接收 `Context`;入口文件需要是 `main.py`。插件持久化数据应放在 AstrBot 的 `data` 目录体系下,不应写回插件源码目录。 + +相关本地文档: + +- `C:\Users\Administrator\Documents\Codex\refs\AstrBot\docs\zh\dev\star\plugin-new.md` +- `C:\Users\Administrator\Documents\Codex\refs\AstrBot\docs\zh\dev\star\plugin.md` +- `C:\Users\Administrator\Documents\Codex\refs\AstrBot\docs\zh\dev\star\guides\plugin-pages.md` + +### 2.2 指令、事件和 LLM 工具 + +当前代码导出的主要接口位于 `astrbot.api` / `astrbot.api.event`: + +- `@filter.command("moviepilot")`:注册命令;可通过命令参数注解接收参数。 +- `@filter.command_group("moviepilot")`:适合组织 `search`、`subscribe`、`list`、`help` 等子命令。 +- `@filter.permission_type(...)`:可限制管理员或其他权限类型。 +- `@filter.event_message_type(...)`:按私聊/群聊等消息类型过滤。 +- `@filter.regex(...)`:需要兼容自然文本格式时使用。 +- `@llm_tool(...)`:将搜索、订阅查询等能力暴露给 LLM;工具 docstring 中必须提供符合 AstrBot 约定的 `Args:` 参数描述。 +- 生命周期:可实现 `terminate()`;插件重载/停止时调用。 + +消息事件 `AstrMessageEvent` 可获取: + +- `event.message_str`:纯文本消息。 +- `event.get_sender_id()`、`event.get_sender_name()`:用户身份。 +- `event.is_private_chat()`:私聊/群聊判断。 +- `event.unified_msg_origin`:用于标识消息来源和回复目标。 +- `yield event.plain_result(...)`:返回文本。 +- `yield event.image_result(...)`:返回图片或图片 URL。 +- `yield event.chain_result(...)`:返回消息链。 +- `await event.send(...)`:在事件处理过程中主动发送消息;不能用 `yield` 的场景使用它。 + +这意味着第一版可以做到“指令控制”和“按当前指令上下文回复”,不需要让 MoviePilot 直接知道 QQ/Telegram 等平台细节。 + +### 2.3 配置和插件 Web API + +当插件目录存在 `_conf_schema.json` 时,AstrBot 会生成并维护插件配置,实例化插件时将 `AstrBotConfig` 传入 `__init__`。建议配置项至少包括: + +- MoviePilot 地址,例如 `http://moviepilot:3000`。 +- MoviePilot API Token;应以密码/敏感字段形式展示,日志不得打印。 +- 默认搜索类型、默认搜索结果数。 +- 是否允许普通用户执行订阅/删除等写操作。 +- 可选的管理员用户或平台白名单。 + +插件还可以使用 `context.register_web_api(...)` 注册后端 API,路径需带插件名前缀。这个能力适合: + +1. 做“测试 MoviePilot 连接”的管理页面; +2. 展示订阅/下载状态; +3. 接收 MoviePilot Webhook 回调。 + +需要注意:插件 Web API 走 AstrBot 的扩展路由,实际公开路径由 AstrBot 的插件扩展入口统一转发,不应假设它等同于 MoviePilot 的 FastAPI 路由。 + +## 3. MoviePilot 外置接口结论 + +MoviePilot API 路由统一挂载在 `/api/v1` 下。当前源码中 API 路由入口是: + +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\api\apiv1.py` + +### 3.1 鉴权 + +外部集成最适合使用 API Token: + +```http +X-API-KEY: +``` + +MoviePilot 当前兼容两类外部凭据传递方式: + +- `X-API-KEY` 请求头或 `apikey` 查询参数; +- 部分 API_TOKEN 专用接口使用 `token` 查询参数。 + +源码依据: + +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\core\security.py` +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\docs\rules\09-external-response.md` + +插件实现应默认只使用 `X-API-KEY`,只有明确标注为 `token` 专用的接口才使用查询参数。API Token 不应进入用户可见回复、普通日志或异常堆栈。 + +### 3.2 第一阶段最有价值的接口 + +#### 媒体搜索和详情 + +| 功能 | 方法 | 路径 | 用途 | +|---|---|---|---| +| 搜索影视/人物 | GET | `/api/v1/media/search` | 根据标题搜索,支持 `title`、`type`、`page`、`count` | +| 查询媒体详情 | GET | `/api/v1/media/{mediaid}` | 根据 `tmdb:123` 等媒体 ID 获取详情 | +| 查询剧集季信息 | GET | `/api/v1/media/seasons` | 根据媒体 ID、标题、年份和季号查询季 | +| 精确搜索资源 | GET | `/api/v1/search/media/{mediaid}` | 针对媒体搜索站点资源 | +| 模糊搜索资源 | GET | `/api/v1/search/title` | 根据关键词搜索资源 | + +MoviePilot 的 `/media/search` 是“元数据/媒体搜索”,`/search/title` 和 `/search/media/{mediaid}` 是“下载资源搜索”,插件文案中必须区分两者。 + +#### 订阅管理 + +| 功能 | 方法 | 路径 | 用途 | +|---|---|---|---| +| 查询全部订阅 | GET | `/api/v1/subscribe/list` | API_TOKEN 认证的订阅列表,适合服务端桥接 | +| 新增订阅 | POST | `/api/v1/subscribe/` | Body 为 `schemas.Subscribe` | +| 更新订阅 | PUT | `/api/v1/subscribe/` | 更新订阅配置 | +| 更新状态 | PUT | `/api/v1/subscribe/status/{subid}` | 启用/暂停等状态变化 | +| 触发刷新 | GET | `/api/v1/subscribe/refresh` | 刷新订阅任务 | +| 搜索订阅 | GET | `/api/v1/subscribe/search` | 批量/后台搜索相关订阅 | +| 搜索单个订阅 | GET | `/api/v1/subscribe/search/{subscribe_id}` | 触发指定订阅搜索 | +| 按媒体查询订阅 | GET | `/api/v1/subscribe/media/{mediaid}` | 判断某媒体是否已订阅 | +| 按媒体删除订阅 | DELETE | `/api/v1/subscribe/media/{mediaid}` | 删除订阅 | +| 查询订阅历史 | GET | `/api/v1/subscribe/history/{mtype}` | 查看历史订阅 | + +订阅 Body 的关键字段包括:`name`、`year`、`type`、`tmdbid`、`mediaid`、`season`、`keyword`、`sites`、`downloader`、`save_path`、过滤规则和洗版选项等。当前源码还明确限制公共写入不能覆盖 `id`、运行状态、完成集数、用户名等系统字段;插件不应把查询结果原样回传为更新 Body。 + +源码依据: + +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\api\endpoints\subscribe.py` +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\schemas\subscribe.py` + +#### 下载和通知 + +| 功能 | 方法 | 路径 | 用途 | +|---|---|---|---| +| 查看正在下载 | GET | `/api/v1/download/` | 返回下载任务 | +| 添加下载 | POST | `/api/v1/download/` 或 `/api/v1/download/add` | 分别用于含媒体信息/不含媒体信息的下载 | +| 开始/暂停下载 | GET | `/api/v1/download/start/{hashString}` / `/stop/{hashString}` | 控制下载任务 | +| 删除下载 | DELETE | `/api/v1/download/{hashString}` | 删除下载任务 | +| 获取通知历史 | GET | `/api/v1/message/notification` | 读取 MoviePilot 已发送的通知历史 | +| 获取 Web 消息 | GET | `/api/v1/message/web` | 读取 Web 消息历史 | +| 清理通知历史 | DELETE | `/api/v1/message/notification` | 按范围清理通知记录 | + +MoviePilot 的“通知”主要是它内部向已配置渠道发送消息,并不是天然的“把消息推给 AstrBot”。如果目标是让 AstrBot 对用户推送,需要增加回流设计,见第 4 节。 + +#### Webhook + +MoviePilot 提供: + +```text +POST /api/v1/webhook/?token=&source=<来源> +GET /api/v1/webhook/?token=&source=<来源> +``` + +它接收外部媒体服务器/工具的报文,进入 MoviePilot 的 `WebhookChain`,不是 MoviePilot 主动向任意 URL 推送的通用订阅接口。因此不能直接把它当作“MoviePilot -> AstrBot 回调”使用。 + +源码依据: + +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\api\endpoints\webhook.py` +- `C:\Users\Administrator\Documents\Codex\refs\MoviePilot\app\chain\webhook.py` + +### 3.3 MCP 作为补充方案 + +MoviePilot 当前还提供 MCP: + +- Base path:`/api/v1/mcp` +- Transport:HTTP、JSON-RPC 2.0 +- 鉴权:`X-API-KEY` 或 `apikey` 查询参数 +- 方法:`initialize`、`notifications/initialized`、`tools/list`、`tools/call`、`ping` + +MCP 的优点是工具语义更完整,适合给 AstrBot 的 LLM Agent 调用;缺点是协议有会话/版本/工具 schema 处理,确定性命令仍然建议直接调用 REST。第一版可以采用“双通道”: + +- 命令处理器调用 REST,保证参数和权限可控; +- 可选 `@llm_tool` 调用 REST 封装,或后续接 MoviePilot MCP。 + +## 4. “推送消息”回流方案 + +当前确认有三种方向,优先级不同: + +| 方案 | 实现方式 | 优点 | 风险/缺口 | +|---|---|---|---| +| A. 指令查询 | 用户执行 `/mp notifications`,插件读取 `/message/notification` | 最简单、无需开放入站端口 | 不是真正实时推送 | +| B. 定时轮询 | 插件定时读取通知历史,保存最后已处理 ID/时间,再 `event.send()` 到绑定会话 | 不需要 MoviePilot 改造,能实现准实时 | 需要会话绑定、去重、轮询频率和多群路由 | +| C. MoviePilot 主动回调 | MoviePilot 的通知/事件发送到 AstrBot `context.register_web_api` 暴露的插件路由 | 实时、架构清晰 | 要确认部署网络、回调 payload、签名/鉴权;当前源码阅读尚未发现一个通用的 MoviePilot outbound webhook 配置可以直接复用 | + +因此第一版建议先做 A,随后做 B;C 作为需要实机联调或 MoviePilot 侧适配的增强项。若用户说的“推送消息”只是让 AstrBot 把操作结果回复出来,则不需要上述回流,直接使用 `yield event.plain_result(...)` 即可。 + +## 5. 建议的第一版交互模型 + +命令名可暂定为 `/mp`,但具体中文别名留到讨论时决定: + +```text +/mp help +/mp search 电影名 [movie|tv] +/mp detail tmdb:123 +/mp resources tmdb:123 +/mp subscribe <搜索结果编号> [season] +/mp subscriptions +/mp sub-search <订阅ID> +/mp unsubscribe <订阅ID或媒体ID> +/mp downloads +/mp notifications +/mp test +``` + +推荐搜索结果使用短期上下文缓存: + +1. `/mp search 沙丘` 返回编号、媒体 ID、类型、年份、海报。 +2. 用户执行 `/mp subscribe 2`。 +3. 插件从当前会话缓存中解析第 2 条,而不是让用户手工复制复杂 JSON。 + +订阅、删除、触发搜索、下载控制属于写操作,建议默认限制为管理员,或提供可配置白名单;普通用户默认只读搜索和查看。 + +## 6. 需要下一轮讨论确认的问题 + +1. **目标平台**:主要是 QQ(aiocqhttp)、Telegram,还是要保持所有 AstrBot 平台通用? +2. **订阅粒度**:第一版只支持“搜索结果编号订阅”,还是允许完整配置站点、下载器、质量、保存路径? +3. **权限**:哪些命令允许普通用户使用?订阅/删除/下载控制是否仅管理员? +4. **推送定义**:只需要操作结果回复,还是必须把 MoviePilot 的下载完成/订阅命中通知主动推送到群聊? +5. **MoviePilot 部署方式**:AstrBot 与 MoviePilot 是否同一 Docker 网络/同一局域网?是否有反向代理和 HTTPS? +6. **多用户映射**:MoviePilot 订阅的 `username` 是否需要映射到 AstrBot 用户,还是全部使用服务账号/超级用户? +7. **MCP 范围**:第一版是否要把能力提供给 LLM 自动调用,还是先只做显式命令? + +## 7. 当前判断 + +### 可以直接实现 + +- AstrBot 插件骨架、配置、异步 HTTP 客户端。 +- MoviePilot API Token 鉴权。 +- 媒体搜索、详情、资源搜索。 +- 订阅列表、新增/删除/触发搜索。 +- 下载列表和操作结果回复。 +- 可选的 LLM 工具封装。 + +### 需要实机联调 + +- 不同 MoviePilot 版本/部署下具体返回字段和错误文案。 +- 搜索返回的媒体 ID、类型和订阅 Body 的最佳映射。 +- AstrBot 插件 Web API 从 MoviePilot 网络侧是否可达。 +- 轮询通知的去重字段和目标会话绑定策略。 + +### 暂不应直接承诺 + +- 仅依赖 MoviePilot 当前 `/api/v1/webhook` 就实现 MoviePilot 主动推送到 AstrBot;该接口从源码看是入站 Webhook,不是通用 outbound webhook。 +- 把完整 MoviePilot 管理后台能力全部暴露给普通聊天用户;这会扩大误操作和权限风险。 + +## 8. 下一步 + +先围绕第 6 节问题确定第一版范围。确认后再把实现拆成正式开发队列,并据此创建插件骨架、API client、权限层、命令处理器、缓存/推送模块和测试计划。 + +## 9. 已确认的产品方向(讨论补充) + +根据当前讨论,产品方向调整为以下内容: + +- 主要适配 OneBot 11 / QQ,同时尽量保持 Telegram 兼容。 +- 白名单优先参考 AstrBot 对 OneBot 11 的平台身份和会话标识,不重新发明 QQ 号/群号格式;插件配置只保存允许操作的私聊用户和群聊成员。 +- 推送目标不是操作来源,而是在插件设置中填写固定推送群聊和/或固定推送个人账号。后续可以支持多个目标,但第一版可先支持一个群和一个个人目标。 +- 写操作支持二次确认,尤其是删除订阅、删除下载任务和其他不可逆动作;LLM 发起写操作也必须先展示拟执行内容,再等待用户确认。 +- MoviePilot 的下载器、站点、保存路径和质量策略以 MoviePilot 当前配置为准,插件不重复实现一套默认策略。 +- 搜索结果按会话缓存,支持使用编号继续操作;默认保留最近搜索结果并设置有效期。 +- 主链路以“先找媒体,再找资源,再决定订阅或立即下载”为核心,而不是让 `/mp search` 直接产生订阅。 +- 通知轮询允许 1~2 分钟一次,插件记录游标并去重;启动时默认不重放历史通知。 +- 目标功能包括命令控制和 LLM Tool,但 LLM 只能在白名单和确认机制通过后执行写操作。 + +### 9.1 建议的核心交互链路 + +#### 查询媒体 + +```text +/mp search 沙丘 +``` + +插件调用 `/api/v1/media/search`,返回媒体编号、标题、年份、类型、媒体 ID、简介和海报。 + +#### 搜索资源 + +```text +/mp resources 2 +``` + +插件使用当前会话中的第 2 条媒体结果,调用 `/api/v1/search/media/{mediaid}`,返回资源编号、标题、大小、质量、站点和可用性等摘要。 + +#### 立即下载 + +```text +/mp download 3 +``` + +插件使用当前会话中的第 3 条资源结果,先展示即将添加的资源信息并要求确认;确认后调用 MoviePilot 下载 API。下载链接只在插件内部传递给 MoviePilot,默认不直接发送到聊天窗口。 + +#### 订阅 + +```text +/mp subscribe 2 +``` + +插件以媒体结果为依据创建订阅。创建成功后可以继续触发一次订阅搜索;如果 MoviePilot 当前已经有可用资源,用户可以随后选择资源立即下载,否则由订阅机制等待后续资源。 + +#### 无资源结果 + +当 `/mp resources` 没有结果时,插件应明确提示: + +1. 当前搜索没有找到资源; +2. 可以直接订阅该媒体,等待后续搜索; +3. 可以修改关键词、媒体类型或搜索范围后重试。 + +这一步是主链路的重要分支,不能把“没有资源”当成 API 错误。 + +### 9.2 已确认的细节 + +1. 第一版同时支持一个指定推送群聊和一个指定推送个人账号;配置为空时不启用对应目标。 +2. 立即下载和删除操作都需要二次确认;查询、搜索和订阅可以直接执行。 +3. 订阅成功后自动触发一次订阅搜索;搜索失败不回滚已创建的订阅,只向用户报告失败原因。 +4. 资源搜索无结果时,回复中直接提示可使用 `/mp subscribe <媒体编号>` 订阅。 diff --git a/main.py b/main.py new file mode 100644 index 0000000..5202681 --- /dev/null +++ b/main.py @@ -0,0 +1,32 @@ +"""AstrBot MoviePilot integration plugin.""" + +from astrbot.api import logger, star +from astrbot.api.event import AstrMessageEvent, filter +from astrbot.api.star import AstrBotConfig + + +@star.register( + "astrbot_plugin_moviepilot", + "AstrBot MoviePilot Contributors", + "在 AstrBot 中通过命令和 LLM 控制 MoviePilot。", + "0.1.0", +) +class MoviePilotPlugin(star.Star): + """MoviePilot integration entrypoint.""" + + def __init__(self, context: star.Context, config: AstrBotConfig) -> None: + super().__init__(context) + self.config = config + logger.info("MoviePilot 插件已加载") + + @filter.command("mp") + async def moviepilot_help(self, event: AstrMessageEvent) -> None: + """显示 MoviePilot 插件命令入口。""" + yield event.plain_result( + "MoviePilot 插件已加载。当前开发中,后续将支持 /mp search、/mp resources、" + "/mp subscribe 和 /mp download。" + ) + + async def terminate(self) -> None: + """释放插件资源。""" + logger.info("MoviePilot 插件已停止") diff --git a/metadata.yaml b/metadata.yaml new file mode 100644 index 0000000..4eb602f --- /dev/null +++ b/metadata.yaml @@ -0,0 +1,11 @@ +name: astrbot_plugin_moviepilot +display_name: MoviePilot 控制 +description: 在 AstrBot 中通过命令和 LLM 控制 MoviePilot。 +short_desc: 搜索影视、订阅、下载和接收 MoviePilot 通知。 +version: 0.1.0 +author: AstrBot MoviePilot Contributors +repo: https://github.com/jxxghp/MoviePilot +astrbot_version: ">=4.16,<5" +support_platforms: + - aiocqhttp + - telegram diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..9feaed5 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +# AstrBot already provides the async HTTP stack used by this plugin. diff --git a/tests/test_plugin_metadata.py b/tests/test_plugin_metadata.py new file mode 100644 index 0000000..85fc27f --- /dev/null +++ b/tests/test_plugin_metadata.py @@ -0,0 +1,33 @@ +import json +from pathlib import Path + +import yaml + + +PROJECT_ROOT = Path(__file__).parents[1] + + +def test_metadata_contains_required_plugin_fields() -> None: + metadata = yaml.safe_load( + (PROJECT_ROOT / "metadata.yaml").read_text(encoding="utf-8") + ) + + assert metadata["name"] == "astrbot_plugin_moviepilot" + assert metadata["version"] == "0.1.0" + assert metadata["astrbot_version"] == ">=4.16,<5" + assert "aiocqhttp" in metadata["support_platforms"] + assert "telegram" in metadata["support_platforms"] + + +def test_config_schema_contains_connection_permissions_and_push_settings() -> None: + schema = json.loads( + (PROJECT_ROOT / "_conf_schema.json").read_text(encoding="utf-8") + ) + + assert schema["moviepilot_url"]["type"] == "string" + assert schema["moviepilot_api_token"]["type"] == "string" + assert schema["private_user_ids"]["type"] == "list" + assert schema["group_permissions"]["type"] == "template_list" + assert schema["push_group_id"]["type"] == "string" + assert schema["push_private_user_id"]["type"] == "string" + assert schema["notification_poll_interval"]["default"] == 60