Emby 电视剧媒体库整理助手#

概述#

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

---

标准目录结构#

text

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

集名称保留规则#

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

text

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

识别集名称的方法：

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

典型示例：

原始文件名提取的集号提取的集名称重命名结果01_《刀剑神域》第1话 剑的世界_高清 1080P+.mp4S01E01剑的世界刀剑神域 (2012) - S01E01 - 剑的世界.mp4``第2话 灰色之剑.mkvS01E02灰色之剑刀剑神域 (2012) - S01E02 - 灰色之剑.mkv``[ANi] 芙莉莲 - 05 [1080P].mkvS01E05（无）葬送的芙莉莲 (2023) - S01E05.mkv``布鲁伊.S01E01.mkvS01E01（无）布鲁伊 (2018) - S01E01.mkv

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

• 画质： 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. 判断特别篇：按特别篇识别关键词分类（见下方规则）。

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

一、识别结果摘要

text

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

二、建议目录结构

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

三、重命名前后对照表

序号原始路径/文件名建议路径/文件名文件类型识别信息说明

四、需要人工确认的问题

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

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

五、Excel 对照表信息

text

Excel 文件名：电视剧名称_yyyyMMdd_HHmmss.xlsx
Excel 保存路径：<用户指定路径>/电视剧名称_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： 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_<timestamp>.json： text

   Write tool → file_path: /tmp/emby_data_<timestamp>.json, content: <上述JSON>
   
   

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

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

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

脚本路径： 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季 第一季 第二季 全集 完结画质信息1080p 2160p 4K 720p编码信息x264 x265 HEVC AVC WEB-DL WEBRip BluRay BDRip HDTV音频信息AAC DDP5.1 DD+5.1 Atmos DTS H.264 H.265色彩信息HDR DV Dolby Vision 10bit 8bit其他发布组名称、网站广告、无意义中括号内容、多余空格/点号/横线

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

---

集数识别规则#

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

原始格式示例转换结果S01E01 / s01e01S01E01S01E01S1E1S1E1S01E011x011x01S01E01EP01 / Ep.01 / E01EP01E01（季号需另行判断）第01集 / 第1集第1集E0101话 / 第01话第01话E01Episode 01Episode 01E01纯数字 0101E01（季号需另行判断）

季号判断优先级：

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

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

---

特别篇识别关键词#

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

text

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

---

文件类型分类#

文件类型扩展名视频（普通剧集）.mkv .mp4 .avi .ts .m2ts字幕.srt .ass .ssa .sub .idxNFO.nfo图片.jpg .jpeg .png .webp .tbn其他以上之外的所有文件

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

text

布鲁伊 (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 需包含以下字段：

字段说明序号从 1 开始递增电视剧名称整理后的标准剧名年份首播年份，未知填「需要人工确认」原始路径文件整理前的完整路径原始文件名文件整理前的文件名新路径文件整理后的完整路径新文件名文件整理后的文件名季号如 S01、S02、S00集号如 E01、E02；特别篇可填「特别篇」或留空集名称原文件中的集标题/话名，如「剑的世界」；无则留空文件类型普通剧集/特别篇/SP/OVA/番外/花絮/字幕/NFO/图片/其他是否重命名是/否是否移动是/否处理状态已整理/待确认/跳过/失败说明如「特别篇放入 Season 00，名称不变」「保留集名称：剑的世界」

---

安全约束（铁律）#

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

---

参考资源#

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