Emby 电视剧媒体库整理助手

概述

接收用户提供的电视剧文件夹路径，扫描文件结构，按照 Emby 标准命名规范分析并生成整理方案。 严格遵守"先预览、后执行"原则：在用户确认前，不执行任何实际的重命名或移动操作。

标准目录结构

电视剧名称 (年份)/
  Season 01/
    电视剧名称 (年份) - S01E01.ext
    电视剧名称 (年份) - S01E01 - 集名称.ext          ← 原文件含集名称时保留
    电视剧名称 (年份) - S01E01.zh-CN.srt
    电视剧名称 (年份) - S01E01 - 集名称.zh-CN.srt    ← 字幕同步保留集名称
  Season 02/
    电视剧名称 (年份) - S02E01.ext
  Season 00/
    特别篇原文件名.ext（文件名不变）
    SP原文件名.ext（文件名不变）

集名称保留规则

当原文件名中包含集名称/话名（即集号之后的标题性文字）时，应在重命名后的文件名中保留，格式为：

电视剧名称 (年份) - S01E01 - 集名称.ext

识别集名称的方法：

1. 提取集号标识（第1话、E01、EP01等）之后、画质/编码/发布组等噪音标签之前的文字
2. 集名称通常出现在集号后，以空格、下划线或横线分隔

典型示例：

噪音排除规则（以下内容不属于集名称，应剥离）：

• 画质：1080P、1080p、720P、4K、2160p
• 编码：x264、x265、HEVC、H.264、H.265
• 来源：WEB-DL、WEBRip、BluRay、BDRip、HDTV
• 音频：AAC、DDP5.1、DTS
• 色彩：HDR、DV、10bit
• 发布组/网站标识：用 [] 或 【】 包围的内容
• 后缀噪音：_高清、+、- 结尾的无意义字符
• 文件扩展名：.mkv、.mp4 等

完整工作流程

阶段一：扫描分析（不修改任何文件）

1. 扫描输入路径，列出所有文件（含子目录），包括视频、字幕、NFO、图片等。
2. 识别剧名：从文件夹名中去除分类标签、季数说明、画质信息等干扰字符（见下方清理规则）。
3. 识别年份：优先从文件夹名或 NFO 文件读取；无法确认时标注「需要人工确认」。
4. 识别季号集号：按集数识别规则逐文件解析（见下方规则）。
5. 判断特别篇：按特别篇识别关键词分类（见下方规则）。

阶段二：输出整理方案（必须完整输出以下五部分）

一、识别结果摘要

- 输入文件夹路径：（用户提供的原始路径）
- 识别电视剧名称：（从路径/文件名提取的原始名称）
- 建议电视剧名称：（清理后的标准名称）
- 年份：（识别到的年份，或"需要人工确认"）
- 识别到的季：（如：第1季、第2季、第3季）
- 是否包含特别篇：是/否
- 是否存在需要人工确认的文件：是/否
- 建议整理后的根目录：（如：/vol3/1000/Movies/TVPlay/布鲁伊 (2018)）

二、建议目录结构

用树形结构展示整理后的完整目录。

三、重命名前后对照表

四、需要人工确认的问题

列出所有无法自动判断的条目，如：

• 年份无法确认
• 季号无法判断
• 集号无法判断
• 特别篇编号/类型无法确认
• 字幕无法匹配对应视频

五、Excel 对照表信息

Excel 文件名：电视剧名称_yyyyMMdd_HHmmss.xlsx
Excel 保存路径：\x3C用户指定路径>/电视剧名称_yyyyMMdd_HHmmss.xlsx

保存路径规则：

1. 如果用户在本次请求中明确指定了保存路径（如「保存到 /vol3/backup」），则使用用户指定的路径。
2. 如果用户未指定路径，使用默认路径：/vol2/1000/SyncFile/OpenClawSync。
3. 在输出整理方案时，需向用户确认 Excel 保存路径，例如： 「Excel 将保存到：/vol2/1000/SyncFile/OpenClawSync（默认），如需保存到其他位置请告知。」

阶段三：等待用户确认

输出整理方案后，必须停止并等待用户明确确认，不得自动继续执行。

阶段四：执行整理（用户确认后）

1. 按对照表逐文件执行移动和重命名。
2. 如果目标文件已存在，不覆盖，标记为「冲突」。
3. 所有操作完成后，生成 Excel 对照表并保存。

阶段五：生成 Excel 对照表

⚠️ 关键：必须通过运行 Python 脚本生成 Excel，严禁手动写入 .xlsx 文件内容！

.xlsx 文件是 ZIP 压缩的 XML 格式，手动写入会生成损坏的文件。必须使用 generate_excel.py 脚本通过 openpyxl 库正确生成。

生成步骤（严格按顺序执行）：

1. 构造 JSON 数据：将整理结果组装为如下结构的 JSON：

   {
     "show_name": "电视剧名称",
     "output_dir": "/vol2/1000/SyncFile/OpenClawSync",
     "records": [
       {
         "序号": 1,
         "电视剧名称": "刀剑神域",
         "年份": "2012",
         "原始路径": "/vol3/1000/Movies/TVPlay/[动漫]刀剑神域/01_《刀剑神域》第1话 剑的世界_高清 1080P+.mp4",
         "原始文件名": "01_《刀剑神域》第1话 剑的世界_高清 1080P+.mp4",
         "新路径": "/vol3/1000/Movies/TVPlay/刀剑神域 (2012)/Season 01/刀剑神域 (2012) - S01E01 - 剑的世界.mp4",
         "新文件名": "刀剑神域 (2012) - S01E01 - 剑的世界.mp4",
         "季号": "S01",
         "集号": "E01",
         "集名称": "剑的世界",
         "文件类型": "普通剧集",
         "是否重命名": "是",
         "是否移动": "是",
         "处理状态": "待确认",
         "说明": "保留集名称"
       }
     ]
   }
   

2. 写入临时 JSON 文件：将 JSON 数据保存到临时文件，例如 /tmp/emby_data_\x3Ctimestamp>.json：

   Write tool → file_path: /tmp/emby_data_\x3Ctimestamp>.json, content: \x3C上述JSON>
   

3. 通过 Bash 运行脚本：使用 Bash 工具执行 Python 命令：

   python "C:/Users/Admin/.workbuddy/skills/emby-tv-organizer/scripts/generate_excel.py" --data /tmp/emby_data_\x3Ctimestamp>.json --output \x3C保存目录>
   

4. 确认输出：脚本成功后会打印 [OK] Excel 已生成：\x3C完整路径>，将此路径报告给用户。

脚本路径：C:/Users/Admin/.workbuddy/skills/emby-tv-organizer/scripts/generate_excel.py

保存目录规则：

• 优先使用用户本次指定的路径
• 用户未指定时使用默认路径 /vol2/1000/SyncFile/OpenClawSync

文件名格式：电视剧名称_yyyyMMdd_HHmmss.xlsx（非法文件名字符自动替换为下划线）

输出效果：列宽适配长路径（路径列 75 字符宽），首行+首列冻结，自动筛选，状态颜色标记，统计 Sheet 含边框样式

❌ 错误做法：直接用 Write 工具将内容写入 .xlsx 文件（会产生 XML 原文而非有效 Excel） ✅ 正确做法：写 JSON → Bash 运行 Python 脚本 → openpyxl 生成有效 .xlsx

路径清理规则（识别剧名时移除以下内容）

示例：[动漫]布鲁伊 1-3季 → 剧名：布鲁伊

集数识别规则

以下格式均应被识别并统一转换为 SxxExx：

季号判断优先级：

1. 文件名中含明确季号（S01、第一季等）→ 直接使用。
2. 文件位于明确季文件夹（Season 02、第二季）→ 使用该季号。
3. 上级路径含 1-3季 等范围说明，但单文件无法判断 → 标注「需要人工确认」。
4. 无任何季信息 → 默认为第 1 季（S01）。

多集合并：多集文件命名为 电视剧名称 (年份) - S01E01-E02.ext。

特别篇识别关键词

以下关键词命中时，归入 Season 00，文件名保持原样不变：

特别篇、SP、Special、OVA、OAD、番外、花絮、幕后、Making Of
预告、Trailer、PV、OP、ED、NCOP、NCED、采访、访谈

文件类型分类

字幕命名规则：普通剧集字幕与视频同名，保留语言标签，集名称同步保留：

布鲁伊 (2018) - S01E01.mkv
布鲁伊 (2018) - S01E01 - 玩游戏.mkv              ← 含集名称的视频
布鲁伊 (2018) - S01E01.zh-CN.srt
布鲁伊 (2018) - S01E01 - 玩游戏.zh-CN.srt        ← 字幕同步保留集名称
布鲁伊 (2018) - S01E01.en.srt

Season 00 中的特别篇字幕，保持原文件名风格，不强制改名。

Excel 字段规范

调用 scripts/generate_excel.py 时，Excel 需包含以下字段：

安全约束（铁律）

• 绝不在用户确认前执行任何文件操作。
• 目标文件已存在时，不覆盖，标记为「冲突」并记录在 Excel 的「说明」列。
• 任何步骤失败时，在 Excel 中记录失败原因，继续处理其他文件。
• 对于无法确认的信息，标注「需要人工确认」，不强行猜测。

参考资源

• 详细的 Excel 生成脚本：scripts/generate_excel.py
• 集数识别正则表达式参考：references/episode_patterns.md