# Agent影视助手

`Agent影视助手` 是这个仓库的主线插件，重点解决一件事：

把 `飞书命令入口`、`外部智能体`、`盘搜`、`影巢`、`115`、`夸克`、`MoviePilot 原生搜索 / PT 下载` 收进同一套稳定工作流。

当前版本：`0.2.71`

当前 helper 版本：`0.1.51`

当前 Release：https://github.com/liuyuexi1987/MoviePilot-Plugins/releases/tag/v0.2.71

如果你是第一次用这个仓库，先把这个插件跑通就够了。

---

## 适合谁

- 你想把飞书当成类似 `TG / 企业微信` 的资源命令入口。
- 你想让 `OpenClaw`、`Hermes`、`WorkBuddy` 这类外部智能体稳定控制 MoviePilot。
- 你想统一处理“找资源 -> 选资源 -> 转存到 115 / 夸克”的流程。
- 你也想把 MoviePilot 原生 `MP搜索 / PT搜索 / 下载 / 订阅 / 更新检查` 放进同一套命令入口。
- 你希望智能体不要自己乱拼影巢、盘搜、115、夸克接口，而是统一交给插件执行。

---

## 两种主要用法

### 1. 不使用外部智能体，只用飞书命令入口

如果你不想接外部智能体，只想要一个命令窗口，可以只配置飞书。

配好后，直接在飞书里发：

```text
盘搜搜索 片名
影巢搜索 片名
转存 片名
夸克转存 片名
下载 片名
更新检查 片名
115登录
影巢签到
```

这种用法更像 TG / 企业微信机器人入口：飞书负责收消息，插件负责执行。

### 2. 使用外部智能体

如果你要接 `OpenClaw`、`Hermes`、`WorkBuddy`，建议安装 `agent-resource-officer skill / helper`。

外部智能体负责理解用户需求和展示结果；资源搜索、转存、下载、签到、Cookie 修复都交给插件。

重点文档：

- [外部智能体接入](../docs/AGENT_RESOURCE_OFFICER_EXTERNAL_AGENTS.md)
- [跨机器部署](../docs/AGENT_RESOURCE_OFFICER_REMOTE_DEPLOY.md)
- 全部命令：`docs/ALL_COMMANDS.md`

### MCP 和 Skill 怎么分工

如果你的智能体客户端支持 MoviePilot 官方 MCP，可以一起接。

- MCP 更适合查 MoviePilot 管理信息，比如插件列表、下载器状态、站点状态、历史记录、工作流。
- `agent-resource-officer skill / helper` 更适合资源流，比如盘搜、影巢、115/夸克转存、PT 编号下载、翻页、盘搜/影巢详情和 Cookie 修复。
- `MP搜索 / PT搜索 / 下载 / 更新检查` 这类片名资源流，也建议优先交给 `agent-resource-officer`，避免智能体绕过插件规则。

MCP 地址通常是：

```text
http://你的MP地址:3000/api/v1/mcp
X-API-KEY=你的 MoviePilot API_TOKEN
```

---

## 核心命令

### 搜索

| 命令 | 作用 |
|---|---|
| `搜索 <片名>` | 默认优先走 MP/PT；如果 MP/PT 已关闭，再按当前启用源回退 |
| `盘搜搜索 <片名>` | 先查盘搜；盘搜没结果时按开关补查影巢 |
| `影巢搜索 <片名>` | 先查影巢；影巢没结果时按开关补查盘搜 |
| `MP搜索 <片名>` / `PT搜索 <片名>` | 走 MoviePilot 原生搜索 / PT 搜索 |
| `盘搜更新检查 <片名>` | 只看盘搜侧更新资源 |
| `影巢更新检查 <片名>` | 只看影巢侧更新资源 |

补充：

- `搜索 第 3 集`、`搜索 E03` 这类带集数线索的写法，会直接按 MP/PT 搜索，不再回退到云盘。
- `检查 大君夫人`、`检查大君夫人` 这类写法，会按更新检查处理；但 `检查115登录` 仍然保留为 115 登录检查。
- `更新检查 xx 剧` / `检查 xx 剧` 这类带剧集意图的写法，会按 MP/PT 搜索；云盘侧更新检查请显式使用 `盘搜更新检查` 或 `影巢更新检查`。

### 转存 / 下载

| 命令 | 作用 |
|---|---|
| `转存 <片名>` | 默认等同 `115转存 <片名>` |
| `115转存 <片名>` | 搜索后优先转存到 115 |
| `夸克转存 <片名>` | 搜索后优先转存到夸克 |
| `下载 <片名>` | 走 MoviePilot 原生 PT 下载链，先找片并列出 PT 候选 |

注意：

- `转存 <片名>` 默认是 115，不会自动改成夸克。
- 只有明确说 `夸克转存 <片名>` 才走夸克。
- `下载 <片名>` 是 PT 下载，不是云盘转存。
- PT 搜索结果里直接回编号会立即下载。
- `下载1` 是给当前 PT 结果生成下载计划，不是确认旧计划。
- 云盘/影巢结果才有详情卡；想看详情用 `选择 1 详情` 或 `详情 1`。

### 选择 / 翻页

```text
1
下载1
选择 1 详情
n
```

- `1`：PT 结果里直接下载；云盘结果里继续转存/解锁。
- `下载1`：给第 1 条 PT 结果生成下载计划。
- `选择 1 详情` / `详情 1`：只用于云盘/影巢详情。
- `n`：下一页。

完整命令见：`docs/ALL_COMMANDS.md`

---

## 主要能力

### 云盘资源

- 盘搜搜索
- 影巢搜索 / 解锁
- `云盘搜索` 已废弃，收到后只会提示改用 `盘搜搜索` / `影巢搜索`
- 115 转存
- 夸克转存
- 更新检查
- 编号选择、详情、翻页
- 智能建议与候选推荐

### MoviePilot 原生能力

- MP / PT 搜索
- PT 下载计划
- 订阅
- 下载任务
- 下载历史
- 入库历史
- 站点状态 / 下载器状态
- 热门探索 / 推荐

### 账号与修复

- 115 扫码登录 / 状态检查
- 影巢签到 / 签到日志
- 影巢 Cookie 修复
- 夸克 Cookie 修复

`115登录` / `115转存` 现在不再强依赖 `P115StrmHelper`；有它时更适合做 115 整理、STRM 和旧登录态复用，没有它也可以直接扫码后完成 115 转存。

Cookie 修复会用到本机浏览器登录态。如果 MoviePilot 在 NAS、智能体在电脑上，修复命令读取的是智能体电脑上的浏览器 Cookie，再写回 NAS 上的 MoviePilot。

---

## 和旧插件的关系

`Agent影视助手` 是把旧的分散能力收成一条主线。

| 旧插件 | 主要用途 | 现在建议 |
|---|---|---|
| `FeishuCommandBridgeLong` | 旧飞书入口 | 新环境优先用 Agent影视助手内置飞书入口 |
| `HdhiveOpenApi` | 影巢独立能力 | 主能力已收进 Agent影视助手 |
| `QuarkShareSaver` | 夸克独立转存 | 主能力已收进 Agent影视助手 |
| `HDHiveDailySign` | 旧影巢签到兜底 | 新环境优先走 Agent影视助手修复链 |

旧组合仍然能用，但更适合兼容老环境；新装建议优先用 `Agent影视助手`。

---

## 新手最容易踩的坑

### 外部智能体乱改命令

常见错误：

- 把 `盘搜搜索`、`影巢搜索`、`MP搜索` 这些明确命令改写成别的入口
- 把 `下载` 当成云盘转存
- 把云盘详情当成直接选择，或把 PT 编号下载当成详情
- 重排插件返回的编号

解决方式：让智能体安装并读取 `agent-resource-officer skill`。长线程跑偏时，直接对智能体说：

```text
校准影视技能
```

外部智能体收到这句时，应先检查并拉取 `MoviePilot-Plugins` 仓库最新版，再重新加载影视技能规则；如果工作区有本地改动，就跳过自动拉取并说明原因。

### 跨机器地址填错

如果 MoviePilot 在 NAS，智能体在电脑上，`ARO_BASE_URL` 要填 NAS 地址：

```text
ARO_BASE_URL=http://你的NAS地址:3000
```

不要填 `127.0.0.1`，那只代表智能体自己这台机器。

### 夸克失败不一定是 Cookie 失效

分享受限、分享者封禁、`41031` 不一定是 Cookie 问题。只有明确提示登录态失效时，才优先走夸克 Cookie 修复。

---

## 进一步阅读

- [插件安装说明](../docs/PLUGIN_INSTALL.md)
- [外部智能体接入](../docs/AGENT_RESOURCE_OFFICER_EXTERNAL_AGENTS.md)
- [跨机器部署](../docs/AGENT_RESOURCE_OFFICER_REMOTE_DEPLOY.md)
- 全部命令：`docs/ALL_COMMANDS.md`