diff --git a/README.md b/README.md index dd62581..d0c925d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## 当前状态 -当前完成插件骨架和配置 schema。后续按 `docs/development-queue.md` 逐阶段实现。 +核心功能已按开发队列完成到 `v0.11.0`,包括媒体/资源搜索、订阅、立即下载、下载任务控制、固定目标通知和 LLM Tool。 ## 安装开发版本 @@ -21,3 +21,63 @@ - 通知轮询间隔。 API Token 仅用于访问 MoviePilot,不要粘贴到聊天消息或提交到日志中。 + +## 命令 + +```text +/mp help +/mp search <关键词> +/mp detail <媒体编号或媒体ID> +/mp seasons <媒体编号或媒体ID> +/mp resources <媒体编号> +/mp subscribe <媒体编号> +/mp download <资源编号> +/mp downloads +/mp download start <任务ID> +/mp download stop <任务ID> +/mp download delete <任务ID> +/mp subscriptions +/mp confirm <确认码> +/mp cancel +``` + +推荐使用链路: + +```text +/mp search 沙丘 +/mp resources 2 +/mp download 1 +/mp confirm abc123 +``` + +如果没有资源,可以直接: + +```text +/mp subscribe 2 +``` + +订阅创建后插件会自动触发一次 MoviePilot 订阅搜索。 + +## 推送 + +通知轮询读取 MoviePilot 的 `/api/v1/message/notification`,默认首次启动不重放历史通知,后续按通知 ID 去重。推送目标由配置决定: + +- `push_group_id`:固定群聊。 +- `push_private_user_id`:固定个人账号。 +- `push_platform_id`:目标平台实例,默认 `aiocqhttp`,Telegram 可填写 `telegram`。 + +## 安全 + +- 所有命令和 LLM Tool 都先经过平台、私聊用户、群聊和群内用户白名单检查。 +- 下载、删除订阅、删除下载任务等副作用操作需要确认。 +- 资源下载链接只传给 MoviePilot,默认不直接发送到聊天窗口。 +- Token 保存在 AstrBot 配置中,不应写入日志、截图或聊天记录。 + +## 开发与测试 + +```bash +python -m pytest tests -q +python -m py_compile main.py access_policy.py confirmation.py download_service.py media_service.py moviepilot_client.py notification_service.py platform_compat.py session_context.py subscription_service.py +``` + +完整设计和分阶段任务见 `docs/research-2026-07-20.md` 与 `docs/development-queue.md`。 diff --git a/docs/development-queue.md b/docs/development-queue.md index 6a771c7..9fed51c 100644 --- a/docs/development-queue.md +++ b/docs/development-queue.md @@ -4,6 +4,24 @@ > > 目标:在 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。 @@ -13,7 +31,7 @@ - 命令和 LLM 共用同一套 MoviePilot Client、权限校验、会话缓存和确认服务。 - 破坏性或有副作用的操作必须经过确认。 -## 阶段 0:插件骨架与配置 +## 阶段 1:插件骨架与配置 ### 任务 0.1 创建插件目录结构 @@ -41,7 +59,7 @@ **验收:** 配置可以通过 AstrBot WebUI 修改;Token 字段敏感显示;配置修改后不会要求手工编辑文件。 -## 阶段 1:公共基础层 +## 阶段 2:公共基础层 ### 任务 1.1 实现 MoviePilot REST Client @@ -94,7 +112,7 @@ **验收:** 确认码无法跨群或跨用户使用;过期后不执行副作用操作。 -## 阶段 2:媒体查询主链路 +## 阶段 3:媒体查询主链路 ### 任务 2.1 实现 `/mp search` @@ -148,7 +166,7 @@ GET /api/v1/search/media/{mediaid} **验收:** 资源编号可以安全映射到后续下载操作;不存在资源时不误报为网络错误。 -## 阶段 3:订阅和立即下载 +## 阶段 4:订阅和立即下载 ### 任务 3.1 实现 `/mp subscribe` @@ -232,7 +250,7 @@ POST /api/v1/download/add 删除下载任务必须二次确认。 -## 阶段 4:固定目标通知推送 +## 阶段 5:固定目标通知推送 ### 任务 4.1 实现通知轮询器 @@ -272,7 +290,7 @@ GET /api/v1/message/notification 通知格式应包含:标题、媒体类型、资源摘要、状态、时间和必要的 MoviePilot 跳转地址(如果返回)。Token、完整站点凭据和不必要的下载链接不得发送。 -## 阶段 5:命令组织和平台兼容 +## 阶段 6:命令组织和平台兼容 ### 任务 5.1 完善命令树 @@ -305,7 +323,7 @@ GET /api/v1/message/notification - 统一纯文本和图片回复。 - QQ 先行测试,Telegram 后续验证命令格式和目标消息发送能力。 -## 阶段 6:LLM Tool 和确认工作流 +## 阶段 7:LLM Tool 和确认工作流 ### 任务 6.1 添加只读 LLM Tools @@ -341,7 +359,7 @@ GET /api/v1/message/notification LLM 必须在执行前明确展示媒体、资源、站点、大小和操作类型。 -## 阶段 7:测试、联调和文档 +## 阶段 8:测试、联调和文档 ### 任务 7.1 单元测试 diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..8bef5fd --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,82 @@ +# 安装与联调说明 + +## 安装 + +将插件目录放到 AstrBot: + +```text +AstrBot/data/plugins/astrbot_plugin_moviepilot/ +``` + +目录至少需要包含: + +```text +metadata.yaml +_conf_schema.json +main.py +moviepilot_client.py +``` + +启动 AstrBot 后,在插件管理页面重载插件,并在插件配置页面填写 MoviePilot 地址和 API Token。 + +## 配置建议 + +### MoviePilot + +- 地址填写 MoviePilot 的服务根地址,例如 `http://192.168.1.20:3000`。 +- 不要把 `/api/v1` 拼到配置地址末尾。 +- 使用 MoviePilot 的 API Token。 +- AstrBot 和 MoviePilot 在同一局域网时,填写 AstrBot 容器能够访问的地址;不能只填写 MoviePilot 容器内部的 `localhost`。 + +### OneBot 11 / QQ + +- `allowed_platforms` 保留 `aiocqhttp`。 +- `private_user_ids` 填允许操作的用户标识。 +- `group_permissions` 中填写群标识和群内用户标识。 +- 群聊操作必须同时匹配群和用户。 +- `push_platform_id` 使用发送通知的 AstrBot 平台实例 ID。 + +### Telegram + +- `allowed_platforms` 增加 `telegram`。 +- 根据 AstrBot 实际事件使用的用户/会话标识填写白名单。 +- `push_platform_id` 设置为 `telegram`。 +- Telegram 的群聊/私聊主动发送能力需要由当前 AstrBot 适配器和 Bot 权限支持。 + +## 实机联调顺序 + +1. 先在 AstrBot WebUI 保存配置并重载插件。 +2. 使用白名单私聊执行 `/mp test`,验证插件加载、MoviePilot 地址和 API Token。 +3. 执行 `/mp search 测试影片`,确认返回媒体编号。 +4. 执行 `/mp resources 1`,确认返回资源编号和摘要。 +5. 先用测试资源执行 `/mp download 1`,确认收到确认码;再执行 `/mp cancel` 验证取消流程。 +6. 再次执行下载并使用 `/mp confirm <确认码>`,确认 MoviePilot 出现下载任务。 +7. 执行 `/mp subscribe 1`,确认订阅创建并触发一次搜索。 +8. 验证 `/mp downloads`、`/mp subscriptions` 和任务控制命令。 +9. 配置固定群聊/个人账号,等待一个轮询周期验证通知推送和去重。 +10. 最后测试 LLM 的搜索、资源查询、订阅确认和下载确认链路。 + +## 常见问题 + +### 401/403 + +检查 MoviePilot API Token,以及请求是否确实到达目标 MoviePilot 实例。 + +### 连接超时 + +检查容器网络、局域网防火墙、反向代理和 MoviePilot 监听地址;AstrBot 容器内的 `localhost` 指向 AstrBot 容器自身。 + +### 编号无效或过期 + +搜索结果按会话保存并受 TTL 限制。重新执行对应的 `/mp search` 或 `/mp resources` 即可。 + +### 没有推送 + +检查轮询是否启用、推送平台 ID 是否正确、目标群/用户是否可由 AstrBot 主动发送,以及 MoviePilot 通知历史中是否出现了新记录。 + +## 尚需实机确认 + +- 当前 MoviePilot 版本返回的资源字段是否都能被 `/api/v1/download/add` 接受。 +- 不同下载器、站点和保存策略下的订阅 Body 行为。 +- OneBot 11 和 Telegram 部署中的实际平台实例 ID。 +- MoviePilot 通知历史 ID 的稳定性和轮询分页行为。 diff --git a/docs/test-report.md b/docs/test-report.md new file mode 100644 index 0000000..4f768d0 --- /dev/null +++ b/docs/test-report.md @@ -0,0 +1,32 @@ +# 阶段 11 测试报告 + +## 已通过 + +- `python -m pytest tests -q` + - 34 个测试通过。 +- 所有插件业务模块通过 `python -m py_compile`。 +- metadata 和 `_conf_schema.json` 可解析。 +- MoviePilot REST Client、白名单、缓存、确认、媒体搜索、订阅、下载、通知、平台目标和 LLM 注册均有测试覆盖。 + +## 当前环境限制 + +尝试将本插件放到本地 AstrBot 参考源码路径进行导入检查时,环境缺少 AstrBot 运行依赖: + +```text +ModuleNotFoundError: No module named 'deprecated' +``` + +这属于本机 AstrBot 参考环境未安装完整依赖,不能替代真实 AstrBot 实例联调。应在实际 AstrBot 虚拟环境或容器中安装 AstrBot requirements 后再执行: + +```bash +python -c "import main; print('astrbot_import: PASS')" +``` + +## 实机联调剩余项 + +- 使用真实 MoviePilot API Token 验证 `/mp test`。 +- 验证媒体搜索结果字段和资源下载 Body。 +- 验证订阅策略继承和自动搜索。 +- 验证 QQ 固定群聊/私聊主动推送。 +- 验证 Telegram 平台实例 ID 和主动推送权限。 +- 验证 MoviePilot 通知历史 ID、分页和轮询去重。 diff --git a/docs/version-history.md b/docs/version-history.md new file mode 100644 index 0000000..94ac577 --- /dev/null +++ b/docs/version-history.md @@ -0,0 +1,15 @@ +# 版本记录 + +| 版本 | 阶段 | 内容 | +|---|---|---| +| `v0.1.0` | 1 | 插件骨架、元数据、WebUI 配置 schema | +| `v0.2.0` | 2 | 异步 MoviePilot REST Client | +| `v0.3.0` | 3 | QQ/Telegram 白名单权限服务 | +| `v0.4.0` | 4 | 会话缓存、TTL 和二次确认 | +| `v0.5.0` | 5 | 媒体、详情、季信息和资源搜索 | +| `v0.6.0` | 6 | 订阅、自动触发搜索和立即下载 | +| `v0.7.0` | 7 | 下载任务列表、开始、暂停、删除 | +| `v0.8.0` | 8 | 通知轮询、游标去重和固定目标推送 | +| `v0.9.0` | 9 | QQ/Telegram 平台目标抽象 | +| `v0.10.0` | 10 | LLM 查询工具和确认型写操作工具 | +| `v0.11.0` | 11 | 测试、联调说明和使用文档 | diff --git a/main.py b/main.py index ec9b88b..278f5a3 100644 --- a/main.py +++ b/main.py @@ -17,7 +17,7 @@ from astrbot.api.event import MessageChain "astrbot_plugin_moviepilot", "AstrBot MoviePilot Contributors", "在 AstrBot 中通过命令和 LLM 控制 MoviePilot。", - "0.1.0", + "0.11.0", ) class MoviePilotPlugin(star.Star): """MoviePilot integration entrypoint.""" @@ -59,6 +59,17 @@ class MoviePilotPlugin(star.Star): "/mp subscribe、/mp download。" ) + @moviepilot.command("test", alias={"测试"}) + async def test_connection(self, event: AstrMessageEvent) -> None: + """测试 MoviePilot 连接和 API Token。""" + if not self.access_policy.is_allowed(event): + return + try: + await self.media_service._get_client().test_connection() + yield event.plain_result("MoviePilot 连接成功,API Token 有效。") + except Exception as exc: + yield event.plain_result(f"MoviePilot 连接失败:{exc}") + @moviepilot.command("search", alias={"搜索"}) async def search_media(self, event: AstrMessageEvent, title: str) -> None: """搜索影视信息。""" diff --git a/metadata.yaml b/metadata.yaml index 4eb602f..7e37a89 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -2,7 +2,7 @@ name: astrbot_plugin_moviepilot display_name: MoviePilot 控制 description: 在 AstrBot 中通过命令和 LLM 控制 MoviePilot。 short_desc: 搜索影视、订阅、下载和接收 MoviePilot 通知。 -version: 0.1.0 +version: 0.11.0 author: AstrBot MoviePilot Contributors repo: https://github.com/jxxghp/MoviePilot astrbot_version: ">=4.16,<5" diff --git a/tests/test_plugin_metadata.py b/tests/test_plugin_metadata.py index 85fc27f..581f29b 100644 --- a/tests/test_plugin_metadata.py +++ b/tests/test_plugin_metadata.py @@ -13,7 +13,7 @@ def test_metadata_contains_required_plugin_fields() -> None: ) assert metadata["name"] == "astrbot_plugin_moviepilot" - assert metadata["version"] == "0.1.0" + assert metadata["version"] == "0.11.0" assert metadata["astrbot_version"] == ">=4.16,<5" assert "aiocqhttp" in metadata["support_platforms"] assert "telegram" in metadata["support_platforms"]