mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-07-12 16:02:35 +08:00
feat: 优化query_library_exists和query_subscribes工具输出，优化SKILL.md
fix(add_download): 更新torrent_url和description字段的描述，移除错误的添加直链的功能
This commit is contained in:
PKC278
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: moviepilot-cli
|
||||
description: Use this skill when the user wants to find, download, or subscribe to a movie or TV show (including anime); asks about download or subscription status; needs to check or organize the media library; or mentions MoviePilot directly. Covers the full media acquisition workflow via MoviePilot — searching TMDB, filtering and downloading torrents from PT indexer sites, managing subscriptions for automatic episode tracking, and handling library organization, site accounts, filter rules, and schedulers.
|
||||
description: Use this skill when the user wants to find, download, or subscribe to a movie or TV show (including anime); asks about download or subscription status; needs to check or organize the media library; or mentions MoviePilot directly. Covers the full media acquisition workflow via MoviePilot — searching TMDB, filtering and downloading torrents from indexer sites, managing subscriptions for automatic episode tracking, and handling library organization, site accounts, filter rules, and schedulers.
|
||||
---
|
||||
|
||||
# MoviePilot CLI
|
||||
@@ -16,30 +16,18 @@ node scripts/mp-cli.js list # list all available commands
|
||||
node scripts/mp-cli.js show <command> # show parameters, required fields, and usage
|
||||
```
|
||||
|
||||
Always run `show <command>` before calling a command. Do not guess parameter names or argument formats.
|
||||
Always run `show <command>` before calling a command. Parameter names vary per command and are not inferable — do not guess.
|
||||
|
||||
## Command Groups
|
||||
|
||||
| Category | Commands |
|
||||
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Media Search | search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits |
|
||||
| Torrent | search_torrents, get_search_results |
|
||||
| Download | add_download, query_download_tasks, delete_download, query_downloaders |
|
||||
| Subscription | add_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares |
|
||||
| Library | query_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history |
|
||||
| Files | list_directory, query_directory_settings |
|
||||
| Sites | query_sites, query_site_userdata, test_site, update_site, update_site_cookie |
|
||||
| System | query_schedulers, run_scheduler, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message |
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Don't guess command parameters.** Parameter names vary per command and are not inferrable. Always run `show <command>` first.
|
||||
- **`search_torrents` results are cached server-side.** `get_search_results` reads from that cache — always run `search_torrents` first in the same session before filtering.
|
||||
- **Omitting `sites` uses the user's configured default sites**, not all available sites. Only call `query_sites` and pass `sites=` when the user explicitly asks for a specific site.
|
||||
- **TMDB season numbers don't always match fan-labeled seasons.** Anime and long-running shows often split one TMDB season into parts. Always validate with `query_media_detail` when the user mentions a specific season.
|
||||
- **`add_download` is irreversible without manual cleanup.** Always present torrent details and wait for explicit confirmation before calling it.
|
||||
- **`get_search_results` filter params are ANDed.** Combining multiple fields can silently exclude valid results. If results come back empty, drop the most restrictive filter and retry before reporting failure.
|
||||
- **`volume_factor` and `freedate_diff` indicate promotional status.** `volume_factor` describes the discount type (e.g. `免费` = free download, `2X` = double upload only, `2X免费` = free download + double upload, `普通` = no discount). `freedate_diff` is the remaining free window (e.g. `2天3小时`); empty means no active promotion. Always include both fields when presenting results — they are critical for the user to pick the best-value torrent.
|
||||
**Media Search:** search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits
|
||||
**Torrent:** search_torrents, get_search_results
|
||||
**Download:** add_download, query_download_tasks, delete_download, query_downloaders
|
||||
**Subscription:** add_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares
|
||||
**Library:** query_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history
|
||||
**Files:** list_directory, query_directory_settings
|
||||
**Sites:** query_sites, query_site_userdata, test_site, update_site, update_site_cookie
|
||||
**System:** query_schedulers, run_scheduler, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message
|
||||
|
||||
## Common Workflows
|
||||
|
||||
@@ -49,41 +37,43 @@ Always run `show <command>` before calling a command. Do not guess parameter nam
|
||||
# 1. Search TMDB to get tmdb_id
|
||||
node scripts/mp-cli.js search_media title="流浪地球2" media_type="movie"
|
||||
|
||||
# [TV only, only if user specified a season] Validate season — see "Season Validation" section below
|
||||
# [TV only, only if user specified a season] the user's season may not match TMDB; validate first, see "Season Validation" section below
|
||||
node scripts/mp-cli.js query_media_detail tmdb_id=... media_type="tv"
|
||||
|
||||
# 2. Search torrents using tmdb_id — results are cached server-side
|
||||
# Response includes available filter options (resolution, release group, etc.)
|
||||
# [Optional] If the user specifies sites, first run query_sites to get IDs, then pass them via sites param
|
||||
node scripts/mp-cli.js query_sites # get site IDs
|
||||
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" # use user's default sites
|
||||
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" sites='1,3' # override with specific sites
|
||||
# 2. Search torrents — results are cached server-side; get_search_results reads from this cache
|
||||
# Omitting sites= uses the user's configured default sites; only pass it when explicitly requested
|
||||
node scripts/mp-cli.js query_sites # get site IDs (only if needed)
|
||||
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" # default sites
|
||||
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" sites='1,3' # specific sites
|
||||
|
||||
# 3. Present ALL available filter_options to the user and ask which ones to apply
|
||||
# 3. Present the filter_options from step 2's response to the user and ask which ones to apply
|
||||
# Show every field and its values — do not pre-select or omit any
|
||||
# e.g. "分辨率: 1080p, 2160p；字幕组: CMCT, PTer；请问需要筛选哪些条件？"
|
||||
|
||||
# 4. Filter cached results based on user preferences and your own judgment
|
||||
# Filter params are ANDed — if results come back empty, drop the most restrictive field and retry
|
||||
node scripts/mp-cli.js get_search_results resolution='1080p'
|
||||
|
||||
# [Optional] Re-check available filter options from cached results (same shape as search_torrents; returns filter options only)
|
||||
# [Optional] If you need to review the available filter_options again without re-running search_torrents
|
||||
node scripts/mp-cli.js get_search_results show_filter_options=true
|
||||
|
||||
# 4. Filter cached results based on user preferences and your own judgment
|
||||
# Each param is an array (OR within a field, AND across fields): resolution='1080p,2160p' free_state='免费,50%'
|
||||
# IMPORTANT: filter_options keys are camelCase (freeState) but params are snake_case (free_state)
|
||||
# If results come back empty, drop the most restrictive field and retry
|
||||
node scripts/mp-cli.js get_search_results resolution='2160p'
|
||||
node scripts/mp-cli.js get_search_results resolution='1080p,2160p' free_state='免费,50%'
|
||||
|
||||
# 5. Present ALL filtered results as a numbered list — do not pre-select or discard any
|
||||
# Show for each: index, title, size, seeders, resolution, release group, volume_factor, freedate_diff
|
||||
# volume_factor: 免费=free download, 50%=download counted at 50% size, 2X=double upload, 2X免费=both, 普通=no discount
|
||||
# freedate_diff: remaining free window (e.g. "2天3小时"); empty = no active promotion
|
||||
# Let the user pick by number; only then proceed to step 6
|
||||
|
||||
# 6. After user confirms selection, check library and subscriptions before downloading
|
||||
node scripts/mp-cli.js query_library_exists tmdb_id=123456 media_type="movie"
|
||||
node scripts/mp-cli.js query_library_exists tmdb_id=123456 media_type="movie" # or "tv"
|
||||
node scripts/mp-cli.js query_subscribes tmdb_id=123456
|
||||
# If already in library or subscribed, warn the user and ask for confirmation to proceed
|
||||
|
||||
# 7. Add download
|
||||
# Single item:
|
||||
node scripts/mp-cli.js add_download torrent_url="abc1234:1"
|
||||
# Multiple items:
|
||||
node scripts/mp-cli.js add_download torrent_url="abc1234:1,def5678:2"
|
||||
# 7. Add download — this is irreversible without manual cleanup, always confirm with user first
|
||||
node scripts/mp-cli.js add_download torrent_url="abc1234:1" # single
|
||||
node scripts/mp-cli.js add_download torrent_url="abc1234:1,def5678:2" # multiple
|
||||
```
|
||||
|
||||
### Add Subscription
|
||||
@@ -92,8 +82,15 @@ node scripts/mp-cli.js add_download torrent_url="abc1234:1,def5678:2"
|
||||
# 1. Search to get tmdb_id (required for accurate identification)
|
||||
node scripts/mp-cli.js search_media title="黑镜" media_type="tv"
|
||||
|
||||
# 2. Subscribe — the system will auto-download new episodes
|
||||
# 2. Check library and existing subscriptions (same as Search and Download step 6)
|
||||
|
||||
# 3. Subscribe — the system will auto-download new episodes
|
||||
# If the user specified a season, run Season Validation first to get the correct season + start_episode
|
||||
# Pass start_episode= when the user's requested season maps to a mid-season episode range on TMDB
|
||||
# (e.g. fans call it "Season 2" but TMDB only has Season 1, episodes starting from ep 13)
|
||||
node scripts/mp-cli.js add_subscribe title="黑镜" year="2011" media_type="tv" tmdb_id=42009
|
||||
node scripts/mp-cli.js add_subscribe title="黑镜" year="2011" media_type="tv" tmdb_id=42009 season=4 # specific season
|
||||
node scripts/mp-cli.js add_subscribe title="某动漫" year="2024" media_type="tv" tmdb_id=12345 season=1 start_episode=13 # mid-season start
|
||||
```
|
||||
|
||||
### Manage Subscriptions
|
||||
@@ -107,7 +104,7 @@ node scripts/mp-cli.js delete_subscribe subscribe_id=123
|
||||
|
||||
## Season Validation (only when user specifies a season)
|
||||
|
||||
Skip this section if the user did not mention a specific season.
|
||||
Productions sometimes release a show in multiple cours under one season; online communities and torrent sites may label each cour as a separate season.
|
||||
|
||||
**Step 1 — Verify the season exists:**
|
||||
|
||||
@@ -118,7 +115,7 @@ node scripts/mp-cli.js query_media_detail tmdb_id=<id> media_type="tv"
|
||||
Check `season_info` against the season the user requested:
|
||||
|
||||
- **Season exists:** use that season number directly, then proceed to torrent search.
|
||||
- **Season does not exist:** anime and long-running shows often split one TMDB season into multiple parts that fans call separate seasons. Use the latest available season number and continue to Step 2.
|
||||
- **Season does not exist:** use the latest available season number and continue to Step 2.
|
||||
|
||||
**Step 2 — Identify the correct episode range:**
|
||||
|
||||
@@ -126,12 +123,12 @@ Check `season_info` against the season the user requested:
|
||||
node scripts/mp-cli.js query_episode_schedule tmdb_id=<id> season=<latest_season>
|
||||
```
|
||||
|
||||
Use `air_date` to find a block of recently-aired episodes that likely corresponds to what the user calls the missing season. If no such block exists, tell the user the content is unavailable. Otherwise, confirm the episode range with the user before proceeding to torrent search.
|
||||
Use `air_date` to find a block of recently-aired episodes that likely corresponds to what the user calls the missing season. If no such block exists, tell the user the content is unavailable. Otherwise, confirm the episode range with the user, then use the `season=` filter in `get_search_results` to narrow torrent results to that range (e.g. `season='S01 E13,S01 E14'`).
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| No search results | Retry with an alternative title (e.g. English title). If still empty, ask the user to confirm the title or provide the TMDB ID directly. |
|
||||
| Download failure | Run `query_downloaders` to check downloader health, then `query_download_tasks` to check if the task already exists (duplicate tasks are rejected). If both are normal, report findings to the user, suggest checking storage space, and mention it may be a network error — suggest retrying later. |
|
||||
| Missing configuration | Ask the user for the backend host and API key. Once provided, run `node scripts/mp-cli.js -h <HOST> -k <KEY>` (no command) to save the config persistently — subsequent commands will use it automatically. |
|
||||
**No search results:** Retry with an alternative title (e.g. English title). If still empty, ask the user to confirm the title or provide the TMDB ID directly.
|
||||
|
||||
**Download failure:** Run `query_downloaders` to check downloader health, then `query_download_tasks` to check if the task already exists (duplicate tasks are rejected). If both are normal, report findings to the user and mention it may be a network error — suggest retrying later.
|
||||
|
||||
**Missing configuration:** Ask the user for the backend host and API key. Once provided, run `node scripts/mp-cli.js -h <HOST> -k <KEY>` (no command) to save the config persistently — subsequent commands will use it automatically.
|
||||
|
||||
Reference in New Issue
Block a user