organize-files v3A

Immutable. This exact content is served forever at /api/v1/blob/3a1b5200a4ebc061.

---
name: organize-files
version: 3
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:

```text
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 and `media_source` + `media_id` pair.
4. For TV season confusion, use `query_media_detail(media_source="themoviedb", media_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:

```text
transfer_file(
  file_path="<source path>",
  storage="local",
  media_type="movie|tv",
  media_source="<source>",
  media_id="<native_id>",
  season=<season_number_if_tv>
)
```

For one recording:

```text
transfer_file(file_path="<audio file>", media_type="music", music_type="recording", media_source="musicbrainz", media_id="<recording_id>")
```

For a complete album, transfer the album directory once:

```text
transfer_file(file_path="<album directory>/", media_type="music", music_type="album", media_source="musicbrainz", media_id="<album_id>")
```

Rules:

- For directories, pass a trailing slash in `file_path` so the tool treats it as a directory.
- Prefer leaving `target_path`, `target_storage`, and `transfer_type` empty so configured directory rules apply.
- Set `target_path` or `transfer_type` only when the user explicitly asks or the default directory configuration cannot handle the file.
- For a single movie or a single TV season folder, transfer the folder once with the shared identity.
- For mixed folders, split by media and transfer each file/subfolder separately.
- For episode packs, identify the media once, then reuse the exact `media_source` + `media_id`, `media_type="tv"`, and the confirmed `season` for each item.
- For one recording, transfer only that audio file with the recording ID.
- For one album, verify the directory belongs to the selected album, then transfer the directory once with the album ID. Do not submit every track as an unrelated recording.
- Never transfer an artist search result. Select a recording or album first.
- When the user asks to refresh music tags, cover, or lyrics after transfer, call `scrape_metadata(media_type="music", ...)`; album scraping may use the album ID and reports actual lyrics counts.

### 6. Report Clearly

After each transfer batch, report:

- source path(s) processed;
- recognized media title, type, `media_source` + `media_id`, season/episode range when relevant;
- success/failure count;
- any failed message exactly enough for the user to act, such as missing media library directory, unsupported storage, existing history, or no media recognized.

If the result creates failed history records, tell the user they can retry with the history ID or let the agent continue with `transfer-failed-retry`.

## Common Cases

### User Gives A Single File

1. `recognize_media(path=...)`
2. If needed, `search_media(...)` and confirm the result.
3. `transfer_file(file_path=..., media_type=..., media_source=..., media_id=..., season=...)`

### User Gives A Season Folder

1. `list_directory(path=...)`
2. Pick a representative episode and run `recognize_media(path=...)`.
3. Confirm `media_source`, `media_id`, `media_type="tv"`, and season.
4. `transfer_file(file_path="<folder>/", media_type="tv", media_source="<source>", media_id="<native_id>", season=<season>)`

### User Gives One Music Track

1. `recognize_media(path=..., media_type="music")`
2. Confirm the artist and recording title; use `search_media(..., music_type="recording")` when ambiguous.
3. Check the exact recording with `query_library_exists` when duplicate risk matters.
4. Transfer the audio file once with the recording `media_source` + `media_id`.

### User Gives An Album Folder

1. `list_directory(path=...)` and confirm the files form one album rather than a mixed folder.
2. Recognize a representative track, then search/select the album entity and query album detail.
3. Compare the folder's supported audio-file count with album `total_tracks`; ask before proceeding when the folder appears incomplete or mixed.
4. Check album library existence, then transfer the directory once with `media_type="music"`, `music_type="album"`, and the album identity.
5. If requested, scrape the album directory for configured tags, cover, and lyrics; do not claim every lyric was found unless the tool reports it.

### User Gives A Messy Mixed Folder

1. `list_directory(path=...)`
2. Group candidates by likely title/year/season.
3. Confirm groups before writing if there is more than one media.
4. Transfer each group separately; do not run one directory transfer over unrelated media.

### Transfer Says The File Was Already Organized

1. `query_transfer_history(title="<title or source path keyword>", status="all")`
2. Find the exact record with matching `src`.
3. Ask the user to confirm deletion if the record is stale or failed.
4. `delete_transfer_history(history_id=<id>)`
5. Retry `transfer_file(...)`.

## Guardrails

- Do not use shell commands, raw database edits, or manual filesystem moves for organization.
- Do not delete transfer history without an exact matching source path and user confirmation.
- Do not use broad download roots as transfer targets unless the user explicitly confirms the scope.
- Do not process unrelated media in one directory transfer.
- Do not confuse a same-name recording, album, and artist; preserve `music_type` and source-native IDs.
- Do not report a partial album as complete or present in the library.
- Do not override target directories or transfer modes unless necessary.
- Prefer asking one focused question over guessing media identity, season mapping, or destructive cleanup.