docs: finalize integration and test report
这个提交存在于:
父节点
e48e325cfc
当前提交
5f9a5ae35a
共有 8 个文件被更改,包括 230 次插入 和 12 次删除
62
README.md
62
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`。
|
||||
|
|
|
|||
|
|
@ -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
普通文件
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
普通文件
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
普通文件
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
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"]
|
||||
|
|
|
|||
正在加载…
添加表格
在新工单中引用