docs: finalize integration and test report

这个提交存在于:
Codex 2026-07-20 22:34:05 +08:00
父节点 e48e325cfc
当前提交 5f9a5ae35a
共有 8 个文件被更改,包括 230 次插入 和 12 次删除

查看文件

@ -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`。

查看文件

@ -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 单元测试

82
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 的稳定性和轮询分页行为。

32
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、分页和轮询去重。

15
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 | 测试、联调说明和使用文档 |

13
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:
"""搜索影视信息。"""

查看文件

@ -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"

查看文件

@ -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"]