moviepilot-cli

MoviePilot CLI

所有脚本路径均相对于此技能文件。

使用本地 moviepilot tool ... 命令与 MoviePilot MCP 工具交互。 该命令会读取本地 MoviePilot 配置；正常本地使用时，无需向用户索要 API_TOKEN、数据库密码或后端 DSN。

范围与边界

此技能适用于通过 MCP 工具提供的常规 MoviePilot 产品操作。 如果其他技能更为匹配，请优先选择：

请求	首选技能
斜杠命令或插件／系统命令分发	command-dispatch
手动整理文件	organize-files
重试失败的传输历史记录	transfer-failed-retry
MCP 工具未提供的直接 REST 端点	moviepilot-api
直接执行 SQL 查询或数据库更新	database-operation
重启、检查版本或升级	moviepilot-update
仅限浏览器的状态、站点登录页面、屏幕截图、Cookie	browser-use

只有在 moviepilot tool list 和 moviepilot tool show <command> 确认没有 MCP 工具可执行所需操作后，才使用 moviepilot-api。只有在任务明确要求检查或修改 SQL，或产品工具／API 无法回答数据问题时，才使用 database-operation。

发现命令

列出所有可用命令：moviepilot tool list

显示特定命令的参数和用法：moviepilot tool show <command>

工具列表包含已启用插件声明的工具。启用、禁用、重新加载或重新配置插件后，请重新运行 tool list 和 tool show，以便命令选择使用刷新的运行时注册表。

调用命令前务必先运行 show <command>——无法推断参数名称，请勿猜测。

命令组

类别	命令
媒体搜索	search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits
种子	search_torrents, get_search_results
下载	add_download_tasks, query_download_tasks, update_download_tasks, delete_download_tasks, query_downloaders
订阅	add_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares
媒体库	query_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history
文件	list_directory, query_directory_settings
站点	query_sites, query_site_userdata, test_site, update_site, update_site_cookie
系统	query_schedulers, run_scheduler, create_agent_task, query_agent_tasks, update_agent_task, run_agent_task, delete_agent_task, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message

工作流

发送消息

发送消息前运行 moviepilot tool show send_message。对于结构化 Telegram 回复，优先使用可选的 rich_message 参数，并在其中填写完整的 GitHub 风格 Markdown 正文。标题、列表、表格、引用块、代码块和链接会转换为 Telegram 富文本消息内容。不要在 message、title 或 image_url 中重复相同内容；不需要富文本消息时，再使用这些普通字段。其他已配置频道会将富文本 Markdown 源作为纯文本备用内容接收。

搜索和下载

1. 搜索 TMDB

按标题搜索电影或电视剧： moviepilot tool run search_media title="..." media_type="movie"

如果用户指定了电视剧季数，请先执行季数验证步骤——用户提供的季数可能与 TMDB 不一致。

2. 搜索种子

重复使用 search_media 返回的确切 media_source 和 media_id。不要用辅助 TMDB、Douban、Bangumi 或 AniList 映射 ID 替换选定的主身份。

省略 sites= 时使用用户的默认站点。如果用户指定了站点，请先获取站点 ID： moviepilot tool run query_sites

使用默认站点搜索种子： moviepilot tool run search_torrents media_source="themoviedb" media_id=791373 media_type="movie"

使用用户指定的站点搜索种子（传入 query_sites 返回的站点 ID）： moviepilot tool run search_torrents media_source="themoviedb" media_id=791373 media_type="movie" sites='1,3'

当 search_torrents 返回结果时：

1. 停止 — 暂时不要调用 get_search_results。
2. 将所有 filter_options 字段及每个字段中的所有值原样呈现给用户。
3. 不要预先选择、概括或省略任何字段或值。
4. 等待用户选择筛选条件，或确认不需要筛选条件，然后再进行下一步。

3. 获取筛选后的结果（仅在用户回应 filter_options 后）

运行 moviepilot tool show get_search_results，查看可用参数。筛选逻辑：同一字段内为 OR，不同字段间为 AND。

筛选值必须来自 search_torrents 返回的 filter_options — 不要编造、翻译、规范化，也不要使用任何其他来源的值。注意：filter_options 的键采用驼峰命名法（例如 freeState），而 get_search_results 的参数采用蛇形命名法（例如 free_state）。

使用选定的筛选条件获取结果： moviepilot tool run get_search_results resolution='1080p,2160p' free_state='免费,50%'

若要筛选可能出现在标题之外的字幕、音频、DIY、翻译或发行说明，请使用 content_pattern。它会匹配种子标题、描述和标签，而 title_pattern 仅匹配标题。如果需要描述来说明结果匹配的原因，请设置 include_description=true；如果需要返回标签，请设置 include_labels=true： moviepilot tool run get_search_results content_pattern='特效字幕|国语|DIY' include_description=true include_labels=true

如果没有结果，请告知用户应放宽哪个筛选条件，并在重试前征求用户同意。

4. 以编号列表呈现结果

展示所有结果，不要预先选择。每行包含：索引、标题、大小、做种数、分辨率、发布组、volume_factor、freedate_diff。

volume_factor	含义
免费	免费下载
50%	下载量减半
2X	上传量翻倍
2X免费	上传量翻倍 + 免费
普通	无优惠

freedate_diff：剩余免费时长（例如 2天3小时）。

5. 下载前检查

用户选择种子后：运行检查媒体库和订阅步骤。

如果媒体已存在于媒体库中或已订阅，停止并向用户报告检查结果。

6. 添加下载

下载一个或多个种子（torrent_url 来自 get_search_results 的输出）： moviepilot tool run add_download_tasks torrent_url="abc1234:1,def5678:2"

错误处理

步骤	操作
search_media 无结果	使用其他标题（英文/原文）重试，然后询问用户标题或确切的 media_source + media_id。
search_torrents 无结果	告知用户，并询问是否使用其他站点重试。
get_search_results 无结果	不要悄悄放宽筛选条件。建议放宽哪个筛选条件，并在重试前征求用户同意。
add_download_tasks 失败	运行 query_downloaders + query_download_tasks 进行诊断，然后向用户报告。

添加订阅

1. 运行 search_media，并保存返回的 media_source 和 media_id。
2. 运行 检查媒体库和订阅 步骤；如果媒体已存在或已订阅，则停止并向用户报告。
3. 如果用户指定了电视剧季数，先运行季数验证步骤。

订阅电影或电视剧： moviepilot tool run add_subscribe title="..." year="2011" media_type="tv" media_source="themoviedb" media_id=42009

订阅指定季数： moviepilot tool run add_subscribe title="..." year="2011" media_type="tv" media_source="themoviedb" media_id=42009 season=4

从指定集数开始订阅： moviepilot tool run add_subscribe title="..." year="2024" media_type="tv" media_source="themoviedb" media_id=12345 season=1 start_episode=13

订阅完整的无损专辑，并持续提升其音质： moviepilot tool run add_subscribe title="..." media_type="music" music_type="album" media_source="musicbrainz" media_id="<release-group-id>" audio_quality="hires|lossless" audio_format="DSD|FLAC|ALAC" min_bit_depth=24 best_version=1

音频比特率和采样率的单位分别为 bps 和 Hz。例如，传入 min_bitrate=320000 和 min_sample_rate=96000。

管理下载

列出下载任务并获取后续操作所需的哈希值： moviepilot tool run query_download_tasks status=downloading

对于下载器中既未下载也未暂停的任务，使用 status=completed；使用 status=all 可包含所有带有 MoviePilot 标签的下载器任务。诊断不带 MoviePilot 内置标签的任务时，添加 include_all_tags=true。需要跟踪器 URL 时，添加 include_trackers=true 或按 hash 查询。

更新下载任务（支持启动/停止、标签、速度限制、跟踪器、保存路径、分类、分享率，以及下载器支持时的做种时间）： moviepilot tool run update_download_tasks hash=<hash> action=stop upload_limit=512 download_limit=2048

向下载任务添加跟踪器： moviepilot tool run update_download_tasks hash=<hash> trackers='https://tracker.example/announce,udp://tracker.example:80/announce'

删除下载任务（先向用户确认——此操作不可撤销）： moviepilot tool run delete_download_tasks hash=<hash>

删除下载任务并同时移除其文件（先向用户确认——此操作不可撤销）： moviepilot tool run delete_download_tasks hash=<hash> delete_files=true

管理订阅

列出有效订阅： moviepilot tool run query_subscribes status=R

更新订阅筛选条件： moviepilot tool run update_subscribe subscribe_id=123 resolution="1080p"

仅为电视剧最佳版本订阅下载整季合集： moviepilot tool run update_subscribe subscribe_id=123 best_version=1 best_version_full=1

触发搜索缺失剧集（先向用户确认）： moviepilot tool run search_subscribe subscribe_id=123

删除订阅（先向用户确认）： moviepilot tool run delete_subscribe subscribe_id=123

管理自主 Agent 任务

仅在用户明确要求延迟执行、定期执行、提醒或监控行为时，使用自主任务。应直接执行即时工作。使用 MoviePilot 的 TZ 设置处理当地时间。

计划运行会复用原始 Agent 会话上下文，但面向用户的消息会通过 MoviePilot 配置的通知渠道广播，而不会绑定到创建任务的渠道。如果 Agent 在执行期间通过消息工具发送完整结果，任务运行结束时就不会再次发送相同的最终回复。

自主任务工具使用 query_agent_tasks 返回的整数 task_id。query_schedulers 和 run_scheduler 仅用于 MoviePilot 系统、插件和工作流运行时服务，并使用字符串 job_id 值；切勿混用这些 ID，也不要将这些工具用于自主任务。

对于相对时间的一次性请求，使用 date 和 delay_minutes；MoviePilot 会计算并保存确切的运行时间： moviepilot tool run create_agent_task name="检查电影资源" content="搜索电影《示例电影》是否有资源并报告，不要自动下载。" trigger_type=date delay_minutes=30

对于在固定时间执行的一次性任务，使用 date 和 ISO 8601 格式的 trigger： moviepilot tool run create_agent_task name="今晚检查资源" content="检查目标电影是否有资源并报告。" trigger_type=date trigger="2026-07-19 20:30:00"

对于定期工作，使用标准的五字段 cron 表达式。此示例会在每天 20:30 运行： moviepilot tool run create_agent_task name="每日资源检查" content="检查目标电影是否有资源并报告。" trigger_type=cron trigger="30 20 * * *"

列出任务并查看 next_run_at 和最新结果： moviepilot tool run query_agent_tasks

暂停或恢复任务： moviepilot tool run update_agent_task task_id=1 enabled=false

将已启用的任务加入队列以立即执行，而不必等待当前 Agent 轮次结束： moviepilot tool run run_agent_task task_id=1

仅在与用户确认永久删除后，才删除任务： moviepilot tool run delete_agent_task task_id=1

检查媒体库和订阅

在下载或订阅前运行，以避免重复。

检查媒体是否已存在于媒体库中： moviepilot tool run query_library_exists media_source="themoviedb" media_id=123456 media_type="movie"

检查媒体是否已订阅： moviepilot tool run query_subscribes media_source="themoviedb" media_id=123456

季验证

用户指定季数时必须执行验证。作品有时会将一部剧集分成多个部分，并归入 TMDB 的同一季；在线社区和种子站点可能会将每个部分标记为单独的“季”。

1. 验证季是否存在

获取媒体详情以检查可用季数： moviepilot tool run query_media_detail media_source="themoviedb" media_id=<id> media_type="tv"

将 season_info 与用户指定的季数进行比较：

1. 如果 season_info 中存在该季 → 直接使用该季数，并返回调用工作流。
2. 如果该季不存在 → 用户所说的“季”可能对应现有 TMDB 季中的后续剧集范围。记下 season_info 中最新（编号最高）的季，然后继续下一步。

2. 确定正确的剧集范围

获取 season_info 中最新一季的播出安排。这是仅限 TMDB 使用的工具，因此其原生 tmdb_id 参数是有意使用的： moviepilot tool run query_episode_schedule tmdb_id=<id> season=<latest_season_number>

使用 air_date 查找近期播出的剧集区间，该区间可能对应用户所说的缺失季。留意剧集之间 air_date 的间隔；间隔表示部分内容之间存在断档，间隔之后的剧集可能就是用户所说的下一“季”。例如，如果 TMDB 第 1 季有第 1–24 集，且第 12 集和第 13 集之间相隔数月，那么第 13–24 集对应用户所说的“第 2 季”。如果不存在此类间隔，请告知用户内容不可用。否则，请与用户确认剧集范围。

错误处理

缺少配置或身份验证失败：运行 moviepilot doctor，检查本地 MoviePilot 安装和设置。仅限插件的日志发现仍会显示，但不会因此降低整体 Doctor 状态。 对于本地 CLI 用法，不要让用户将 API 密钥粘贴到提示词中。