Agent 接入与控制 Bot

文档首页 · 使用指南 · 常见问题

除了管理台，还可以用两种方式操作 Reelay：

• Telegram 控制 Bot：在手机上收审批卡片、点按钮，或者直接用一句话查询和操作；
• MCP：让 Claude 等 AI Agent 查询待审批、媒体库与缺集，并批量批准、忽略、重试或订阅。

Bot 的自然语言助手与 MCP 共用管理工具（定义在 reelay/agent_tools.py），但整个控制 Bot 还有独立的卡片与按钮能力。自然语言写操作会先生成计划，你点「执行」后才执行；MCP 的读写工具可以直接执行，是否再次向你确认取决于 Agent 客户端，Reelay 不在每次调用前另行确认。首次接入建议先用只读令牌。

控制 Bot

在「设置 → Telegram」填好控制 Bot 的 Token 与你的 Telegram 数字 ID，先在 Telegram 打开自己的 Bot 并发送 /start，再重启主进程。控制 Bot 只回应这个 ID；它与用于监听来源的个人 Telegram 账号不同。

卡片与按钮（不需要 AI）：

• 需要你确认的资源会推送一张审批卡片：转存、忽略、换目录、追剧、不再接收；卡片保留原内容并在末尾写明结果。
• 识别错了点「✏️ 修正」，再发一句要改的内容，如「片名 繁花」「第 2 季 E01-E05」「繁花 2023 剧集 S01E03」，没写的项不变；也可以点「重新识别」。待审批的改完会重新核对 TMDB 并发回新卡片。
• 转存或整理停下来时推送「需要处理」的提醒，按情况给出核验转存、按已到的继续、重新整理、删除转存文件 / 覆盖保存、重试、忽略和修正。
• 审批汇总、停机补拉的通知带「查看待审批」按钮；追更提醒每部剧带「🔕」按钮，可以把现在缺的集标为不用等，或不再提醒这部（可撤销）；订阅自动结束时可以一键继续订阅。
• 入库通知与故障告警也推送到这里。

直接说话（需要配置 AI 服务）：

• 「待审批里有什么」「哪些任务失败了，为什么」
• 「我有哪些 4K 的日本动画」「《X》第二季缺哪几集」
• 「把《X》这几集都批了，存到剧集」「订阅《X》第一季」「不追《X》了」「把这条的片名改成《Y》」

查询直接回答；自然语言提出的批准、忽略、重试、订阅、取消订阅、修正识别等写操作会先列出来，点「执行」后才执行，十分钟内不点就作废。这种计划确认不代表普通卡片按钮和直接命令都要经过同一流程。模型被要求把资源正文和片名当作数据，但这不是对提示注入的绝对保证，执行前仍应核对对象与动作。

命令（命令入口本身不依赖 AI，常用项会显示在 / 菜单；/retry 可直接输入但不在菜单里。/subs 片名 会查询 TMDB，并可使用已配置的 AI 辅助解析）：

命令	作用
/pending	待审批与待人工，每条一个按钮点开卡片处理；可以一键全部批准或全部忽略（先确认）
/failed	失败任务，点开可以修正、重试或忽略
/subs	追剧订阅：已入库多少、缺哪几集；/subs 片名（可加季号，如 /subs 嫁金钗 第二季）在 TMDB 找剧，点选一季订阅，待审批里已有这部剧时可以一并转存；可以取消订阅；已播完、自动结束的不列出（播完时的通知上可以继续订阅）；还列出订阅建议，可以订阅或点「不用了」
/ignored	「不再接收」的作品，可以恢复接收
/status · /retry <任务 ID> · /help	状态计数、重试、帮助

115 登录失效后的重新扫码仍在管理台完成。

MCP

接入方式

HTTP：Docker 部署，或 Agent 不在 Reelay 所在的机器上时使用。在管理台「设置 → 运行与安全 → Agent 接入」生成访问令牌（读写、只读各一个），然后：

claude mcp add --transport http reelay http://127.0.0.1:28080/mcp \
  --header "Authorization: Bearer <令牌>"

• /mcp 由 Web 进程提供，只认 MCP 访问令牌，与管理台登录密码互不相关；两个令牌都没设置时 /mcp 关闭。
• 只读令牌看不到写操作工具。令牌至少 24 个字符，管理台可以随机生成。
• Agent 在其他机器上时，要像管理台一样把端口开放出去，或经反向代理访问；反向代理需要放行 Authorization 请求头。

stdio：Agent 与 Reelay 在同一台机器上、直接读写 data/ 时使用：

pip install -e ".[agent]"
claude mcp add reelay -- /path/to/reelay/.venv/bin/reelay-mcp

设置环境变量 REELAY_MCP_READONLY=1 只提供查询工具（HTTP 的读写令牌也降为只读）。

工具

工具	作用	读写
status	运行概况：各状态任务数、运行模式、Worker / 消息源 / 115 健康状态	只读
list_pending	待审批（附建议动作与理由、推荐版本、等待天数）与待人工处理的任务	只读
list_tasks / get_task	按状态或关键字检索任务；任务详情与最近的处理轨迹	只读
list_save_dirs	保存目录别名，批准时可以改投到其中之一	只读
search_library	按片名、类型、最低清晰度、地区或 TMDB 类型检索已入库作品与各季的集	只读
missing_episodes	缺集巡检结果：缺哪几集、哪些已播出多天仍未入库	只读
list_subscriptions / find_show	已订阅的剧（含是否已自动结束）与订阅建议；把剧名对应到 TMDB 条目与季	只读
list_ignored	「不再接收」的作品	只读
approve	批准待审批任务，可改投目录	写 · 真实转存
reject	忽略待审批任务	写
retry	按检查点重试失败任务	写 · 可能真实转存
subscribe	订阅一部剧的某一季，返回这一季正在待审批的任务	写
unsubscribe / resume_subscription	取消订阅；已自动结束的订阅继续订阅	写
unignore	恢复接收一部作品	写
correct	修正待审批、待人工或失败任务的识别结果（片名、年份、类型、季、集、分辨率）	写
reparse	重新识别（不用缓存），已有转存检查点的任务不行	写

approve、reject、retry、reparse 接收任务 ID 数组（每次 1–100 个），逐条返回结果，期间已被处理的任务会标出来。批准和重试只改任务状态，真实的 115 转存与整理由正在运行的主进程执行，无法从 MCP 撤销。会产生真实转存的工具带 destructiveHint 标注，客户端可以据此逐次确认，但标注本身不会强制客户端询问。

只读表示不提供这些写操作，不等于零外部请求：作品查询等仍可能访问 TMDB 或调用已配置的 AI。当前 MCP 工具也不覆盖管理台的全部功能，例如重新扫码、修改设置、核验转存、按部分继续、重新整理和冲突覆盖仍需在管理台或相应 Bot 按钮中处理。