/organize-files

name: organize-files
version: 2
description: >-
  Use this skill when the user asks the MoviePilot agent to identify and organize downloaded/local video or music files that automatic transfer cannot handle. Typical triggers include manually organizing a file or folder, a TV season pack, one music recording, or a complete album directory. If the user gives failed transfer history IDs, prefer transfer-failed-retry instead.
allowed-tools: list_directory query_directory_settings query_download_tasks query_transfer_history delete_transfer_history recognize_media search_media query_media_detail query_library_exists transfer_file scrape_metadata ask_user_choice send_message

Organize Files (智能整理文件)

Use this skill to help the user identify media files that MoviePilot could not organize automatically, then call the normal transfer pipeline through `transfer_file`. Do not rename, move, or copy files manually; let MoviePilot's directory, transfer mode, rename template, overwrite, scrape, and notification settings handle the actual organization.

MoviePilot Transfer Flow

MoviePilot's normal flow is:

1. `DownloadChain.download_single` adds a downloader task, records `DownloadHistory` and `DownloadFiles`, runs downloader-specific `download_added`, then sends `DownloadAdded`. 2. `TransferChain.process` scans completed downloader tasks in monitored download directories. If a `DownloadHistory` exists for the hash, it reuses the recorded media IDs; otherwise it falls back to path recognition. 3. Agent/manual organization calls `transfer_file`, which enters `TransferFileTool` -> `TransferChain.manual_transfer` -> `TransferChain.do_transfer`. 4. `do_transfer` recursively collects eligible video/subtitle/audio files, ignores recycle/hidden paths and configured exclude words, and reuses download history when possible. Video uses `MetaInfoPath`; music uses audio tags plus `MetaMusic`/`MusicInfo` and keeps the selected recording or album identity. 5. `TransferChain.__handle_transfer` chooses the target directory through `DirectoryHelper`, delegates file operations to the file manager module, and lets `TransHandler` build the final target path and name. 6. The callback writes `TransferHistory` success/failure records, emits transfer events, sends notifications, and may trigger `transfer-failed-retry` for failed history records.

Important implication: an existing `TransferHistory` for the same source path can make a later transfer skip. Delete only stale or failed history records, and only after the user has confirmed the record is safe to remove.

Workflow

1. Classify The Request

• If the user provides one or more failed transfer history IDs, stop and use `transfer-failed-retry`.
• If the user provides a path, start from that path.
• If the user describes a download task, use `query_download_tasks` to find its save path or hash, then continue with the path.
• If the user only says "整理一下下载目录", use `query_directory_settings(directory_type="download")` first, then ask which directory or subdirectory to process if more than one candidate exists.

2. Inspect Candidate Files

Use `list_directory` for any directory the user provides. Prefer `sort_by="time"` for "recent" or "刚下载的" requests.

For directories with more than 20 items, ask the user to narrow the folder or choose the relevant child directory before running transfers. Avoid organizing a broad shared download root unless the user explicitly confirms the scope.

Treat these as transfer candidates:

• main media files and Blu-ray folders;
• matching subtitle and external audio files in the same media folder;
• episode packs where files share the same title/season pattern.
• individual supported audio files and album folders containing multiple tracks.

Skip obvious samples, trailers, screenshots, hidden folders, recycle folders, and files that are not media/subtitle/audio.

3. Identify The Media

For the best sample file, call:

recognize_media(path="<source file path>")

If recognition fails or looks wrong:

1. Extract likely title, year, media type, season/episode range, or music artist/track/album from filenames and audio tags. 2. For video, call `search_media(title="...", year="...", media_type="movie|tv")`. For music, call `search_media(title="<artist> - <title>", media_type="music", music_type="recording|album")`. 3. If several results are plausible, use `ask_user_choice` when available, or ask the user directly to choose the correct title/TMDB ID. 4. For TV season confusion, use `query_media_detail(tmdb_id=<id>, media_type="tv")` before deciding the season number. For an album, use `query_media_detail(media_type="music", music_type="album", media_source="musicbrainz", media_id="<album_id>")` and verify `total_tracks` before treating the directory as complete.

Never invent an ID. Preserve the exact source-native entity returned by search: a recording is one track, an album is a multi-track collection, and an artist is browse-only and cannot be organized.

4. Check Existing State

Before writing:

• Use `query_library_exists` when a precise video or music identity is known and duplicate risk matters. For albums, an exists result is only true after complete track coverage is confirmed.
• Use `query_transfer_history(title="<title or path keyword>", status="all")` if the file may already have a success or failure record.
• If `transfer_file` later returns "已整理过", query transfer history, identify the matching source path, and ask before deleting the stale record.

Only call `delete_transfer_history(history_id=<id>)` for the exact stale/failed record that blocks the requested source path. Do not delete unrelated successful history.

5. Transfer Through MoviePilot

Use `transfer_file` with explicit identity whenever possible:

transfer_file(
  file_path="<source path>",
  storage="local",
  media_type="movie|tv",
  tmdbid=<tmdb_id>,
  season=<season_number_if_tv>
)

For one recording:

tra