# 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 <媒体编号>` 订阅。