transfer-failed-retry

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Transfer Failed Retry (整理失败重试)

传输失败重试（整理失败重试）

This skill handles retrying failed file transfers/organizations. When file transfers fail, you can use this skill to analyze the failures, remove stale history records, and attempt to re-identify and re-organize the files. It supports both single-file and batch retry scenarios.

本Skill用于处理失败的文件传输/整理操作的重试。当文件传输失败时，你可以使用此Skill分析失败原因、清除过期历史记录，并尝试重新识别和整理文件。它支持单文件和批量重试两种场景。

Prerequisites

前置条件

You need the following tools:

```
query_transfer_history
```
- Query transfer history records
```
delete_transfer_history
```
- Delete a transfer history record
```
recognize_media
```
- Recognize media info from file path or title
```
transfer_file
```
- Transfer/organize files to the media library
```
search_media
```
- Search TMDB for media information

你需要以下工具：

```
query_transfer_history
```
- 查询传输历史记录
```
delete_transfer_history
```
- 删除传输历史记录
```
recognize_media
```
- 从文件路径或标题识别媒体信息
```
transfer_file
```
- 将文件传输/整理至媒体库
```
search_media
```
- 在TMDB中搜索媒体信息

Workflow

工作流程

Step 1: Query the Failed Transfer History

步骤1：查询失败的传输历史

Use

query_transfer_history

to get details about the failed record(s). Filter by status

failed

to find the specific records.

If you are given a specific history record ID (or multiple IDs), query with those IDs to understand the failure context:

query_transfer_history(status="failed")

From each record, extract the following key information:

id: The history record ID
src: Source file path
title: The recognized title (may be incorrect)
errmsg: The error message explaining why the transfer failed
type: Media type (movie/tv)
tmdbid: TMDB ID (if available)
seasons/episodes: Season/episode info (if TV show)
downloader: Which downloader was used
download_hash: The torrent hash

使用

query_transfer_history

获取失败记录的详情。通过状态

failed

筛选出特定记录。

如果给定了具体的历史记录ID（或多个ID），使用这些ID进行查询以了解失败背景：

query_transfer_history(status="failed")

从每条记录中提取以下关键信息：

id: 历史记录ID
src: 源文件路径
title: 已识别的标题（可能不正确）
errmsg: 解释传输失败原因的错误信息
type: 媒体类型（电影/电视剧）
tmdbid: TMDB ID（若有）
seasons/episodes: 季/集信息（若为电视剧）
downloader: 使用的下载工具
download_hash: 种子哈希值

Step 2: Analyze the Failure Reason

步骤2：分析失败原因

Common failure reasons and how to handle them:

Error Message	Cause	Solution
未识别到媒体信息	File name couldn't be matched to any media	Use `search_media` to find the correct TMDB ID, then use `transfer_file` with explicit `tmdbid`
源目录不存在	Source file was moved or deleted	Cannot retry - skip this record
目标路径不存在	Target directory issue	Retry transfer - the directory config may have been fixed
文件已存在	Target file already exists	May need to use `force` mode or skip
未找到有效的集数信息	Episode number not recognized	Use `recognize_media` with the file path to get better metadata, or specify season/episode in `transfer_file`
未获取到转移目录设置	No transfer directory configured for this media type	Cannot auto-fix - notify user about directory configuration

常见失败原因及处理方式：

错误信息	原因	解决方案
未识别到媒体信息	文件名无法匹配到任何媒体资源	使用 `search_media` 查找正确的TMDB ID，然后在 `transfer_file` 中指定该 `tmdbid` 进行传输
源目录不存在	源文件已被移动或删除	无法重试 - 跳过该记录
目标路径不存在	目标目录存在问题	重试传输 - 目录配置可能已修复
文件已存在	目标文件已存在	可能需要使用 `force` 模式或跳过
未找到有效的集数信息	集数未被识别	使用 `recognize_media` 结合文件路径获取更准确的元数据，或在 `transfer_file` 中指定季/集信息
未获取到转移目录设置	未为此媒体类型配置传输目录	无法自动修复 - 通知用户进行目录配置

Step 3: Delete the Failed History Record(s)

步骤3：删除失败的历史记录

Before retrying, you must delete the old failed history record(s). The system skips files that already have a transfer history entry (even failed ones).

delete_transfer_history(history_id=<record_id>)

在重试之前，必须删除旧的失败历史记录。系统会跳过已有传输历史条目（即使是失败的）的文件。

delete_transfer_history(history_id=<record_id>)

Step 4: Re-identify and Re-organize

步骤4：重新识别与整理

Based on the failure analysis in Step 2:

基于步骤2的失败分析：

Case A: Unrecognized Media (未识别到媒体信息)

场景A：媒体未识别（未识别到媒体信息）

Try recognizing the media from file path:

recognize_media(path="<source_file_path>")

If recognition fails, try searching TMDB with keywords extracted from the filename:
```
search_media(title="<extracted_title>", media_type="movie" or "tv")
```

Once you have the correct TMDB ID, re-transfer with explicit identification:

transfer_file(file_path="<source_path>", tmdbid=<tmdb_id>, media_type="movie" or "tv")

尝试从文件路径识别媒体：

recognize_media(path="<source_file_path>")

如果识别失败，尝试使用从文件名提取的关键词在TMDB中搜索：
```
search_media(title="<extracted_title>", media_type="movie" or "tv")
```

获取到正确的TMDB ID后，通过明确识别信息重新传输：

transfer_file(file_path="<source_path>", tmdbid=<tmdb_id>, media_type="movie" or "tv")

Case B: Transfer Error (file operation failed)

场景B：传输错误（文件操作失败）

Simply retry the transfer:

transfer_file(file_path="<source_path>")

直接重试传输：

transfer_file(file_path="<source_path>")

Case C: Episode Recognition Issue

场景C：剧集识别问题

For TV shows where episode info couldn't be determined:

Use
```
recognize_media
```
to get better metadata

Re-transfer with explicit season info:

transfer_file(file_path="<source_path>", tmdbid=<tmdb_id>, media_type="tv", season=<season_number>)

对于无法确定集数信息的电视剧：

使用
```
recognize_media
```
获取更准确的元数据

指定季信息重新传输：

transfer_file(file_path="<source_path>", tmdbid=<tmdb_id>, media_type="tv", season=<season_number>)

Step 5: Report Result

步骤5：报告结果

After the retry attempt, report the result:

If successful: Confirm the file(s) have been organized correctly
If failed again: Report the new error and suggest manual intervention
For batch operations: Report a summary (e.g., "成功 8/10，失败 2/10")

重试尝试完成后，报告结果：

若成功：确认文件已正确整理
若再次失败：报告新的错误并建议手动干预
批量操作：报告汇总结果（例如："成功 8/10，失败 2/10"）

Batch Processing (批量处理)

批量处理

When multiple files from the same source fail simultaneously (e.g., 10 episodes of the same TV show all fail with the same error), the system groups them and triggers a single batch retry.

当同一来源的多个文件同时传输失败时（例如，同一部电视剧的10集均因相同错误失败），系统会将它们分组并触发单次批量重试。

Key Optimization Rules for Batch Processing:

批量处理关键优化规则：

Identify media ONCE, apply to ALL files: Since batch files typically belong to the same media, perform media recognition (
```
recognize_media
```
) or search (
```
search_media
```
) only ONCE using the first file, then reuse the result (tmdbid, media_type) for all subsequent files.
Process each file individually for delete + transfer: Even though the media identity is shared, you must still:
- Delete each failed history record individually
- Transfer each file individually (they have different source paths)
Stop early if root cause is unfixable: If the first file fails due to an unfixable issue (e.g., missing directory configuration), skip all remaining files with the same error rather than retrying each one.
Process in order: Handle files sequentially to avoid race conditions.

仅识别一次媒体，应用于所有文件：由于批量文件通常属于同一媒体，只需使用第一个文件执行一次媒体识别（
```
recognize_media
```
）或搜索（
```
search_media
```
），然后将结果（tmdbid、media_type）复用至所有后续文件。
逐个文件执行删除+传输：即使媒体信息共享，仍必须：
- 逐个删除每条失败历史记录
- 逐个传输每个文件（它们的源路径不同）
若根因无法修复则提前终止：如果第一个文件因无法修复的问题失败（例如，缺少目录配置），跳过所有具有相同错误的剩余文件，而非逐个重试。
按顺序处理：按顺序处理文件以避免竞争条件。

Batch Example Flow:

批量处理示例流程：

undefined

undefined

Given failed records: IDs = [42, 43, 44, 45] (4 episodes of the same show)

给定失败记录：IDs = [42, 43, 44, 45]（同一部剧的4集）

All have errmsg="未识别到媒体信息"

所有记录的errmsg均为"未识别到媒体信息"

1. Query all failed records

1. 查询所有失败记录

query_transfer_history(status="failed")

2. Identify media ONCE using the first file

2. 使用第一个文件仅识别一次媒体

recognize_media(path="/downloads/Show.Name.S01E01.1080p.mkv")

Found: tmdb_id=789, media_type="tv"

结果：tmdb_id=789, media_type="tv"

3. For each record: delete history, then re-transfer

3. 对每条记录：删除历史，然后重新传输

delete_transfer_history(history_id=42) transfer_file(file_path="/downloads/Show.Name.S01E01.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=43) transfer_file(file_path="/downloads/Show.Name.S01E02.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=44) transfer_file(file_path="/downloads/Show.Name.S01E03.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=45) transfer_file(file_path="/downloads/Show.Name.S01E04.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=42) transfer_file(file_path="/downloads/Show.Name.S01E01.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=43) transfer_file(file_path="/downloads/Show.Name.S01E02.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=44) transfer_file(file_path="/downloads/Show.Name.S01E03.1080p.mkv", tmdbid=789, media_type="tv")

delete_transfer_history(history_id=45) transfer_file(file_path="/downloads/Show.Name.S01E04.1080p.mkv", tmdbid=789, media_type="tv")

4. Report summary: "重试完成：4/4 成功"

4. 报告汇总结果："重试完成：4/4 成功"

undefined

undefined

Important Notes

重要注意事项

Always delete the old history record first before retrying. The system will skip files with existing history.
Do not retry if the source file no longer exists (源目录不存在).
Do not retry if the error is about missing directory configuration - this requires user intervention.
For unrecognized media, always try
```
recognize_media
```
with the file path first before falling back to
```
search_media
```
.
Be cautious with TV shows - ensure the correct season and episode information is used.
For batch processing, always reuse media identification results across all files to save time and resources.
When this skill is triggered automatically by the system, it provides the
```
history_id
```
(s) directly. Start from Step 1 with those specific IDs.

重试前务必先删除旧历史记录：系统会跳过已有历史记录的文件。
源文件不存在时（源目录不存在）请勿重试。
错误为缺少目录配置时请勿重试 - 这需要用户干预。
对于未识别的媒体，始终先尝试使用
```
recognize_media
```
结合文件路径进行识别，再 fallback 到
```
search_media
```
。
处理电视剧时需谨慎 - 确保使用正确的季和集信息。
批量处理时，务必在所有文件中复用媒体识别结果以节省时间和资源。
当系统自动触发此Skill时，会直接提供
```
history_id
```
(s)。请从步骤1开始，使用这些特定ID进行操作。

Example: Single File Retry Flow

示例：单文件重试流程

undefined

undefined

1. Query the failed record

1. 查询失败记录

query_transfer_history(status="failed", page=1)

Found: id=42, src="/downloads/Movie.Name.2024.1080p.mkv", errmsg="未识别到媒体信息"

结果：id=42, src="/downloads/Movie.Name.2024.1080p.mkv", errmsg="未识别到媒体信息"

2. Try to recognize the media from path

2. 尝试从路径识别媒体

recognize_media(path="/downloads/Movie.Name.2024.1080p.mkv")

Recognition failed

识别失败

3. Search TMDB

3. 在TMDB中搜索

search_media(title="Movie Name", year="2024", media_type="movie")

Found: tmdb_id=123456

结果：tmdb_id=123456

4. Delete old history record

4. 删除旧历史记录

delete_transfer_history(history_id=42)

5. Re-transfer with correct identification

5. 使用正确的识别信息重新传输

transfer_file(file_path="/downloads/Movie.Name.2024.1080p.mkv", tmdbid=123456, media_type="movie")

Success!

成功！

undefined

undefined