结构调整

workspace-storage/jellyfin/jellyfin-dedup-howto.md

@@ -0,0 +1,94 @@
+# Jellyfin 重复电影检测操作指南
+
+> Jellyfin 服务器配置见 `jellyfin-config.md`
+
+## 概述
+
+通过 Jellyfin API 检测库中的重复电影，支持两种检测方式：
+- **相同名称+年份**：同一部电影被多次导入到不同文件夹
+- **相同文件大小+时长**：同一个文件被不同文件夹引用导致重复扫描入库（允许1%误差）
+
+## 文件位置
+
+```
+bt-docs/jellyfin-dedup.py         # 检测脚本
+bt-docs/jellyfin-dedup-howto.md   # 本文档
+bt-docs/jellyfin-config.md        # Jellyfin 配置信息
+```
+
+## 前置条件
+
+1. Jellyfin 服务已在 Windows 上运行（端口 8096）
+2. WSL 可通过网关 IP 访问 Windows 主机
+
+## 使用方法
+
+### 运行检测
+
+```bash
+python3 /mnt/f/docs/jellyfin-dedup.py
+```
+
+> ⚠ 如果脚本在 WSL 中运行，注意 WSL 内访问 Windows 端口需要填写网关 IP。脚本内默认使用 `172.25.208.1:8096`，可直接修改脚本头部的 `SERVER_URL`。
+
+### 输出说明
+
+```
+============================================================
+Jellyfin 重复电影检测
+============================================================
+
+📦 获取所有电影...
+  已获取 100/753 部电影...
+  共获取 753 部电影
+
+🔍 开始检测重复...
+
+⚠️  发现 14 组重复
+============================================================
+
+[1] 相同名称+年份
+  原因: 电影名 'IPZZ-740 ...' (2025) 存在 2 个版本
+    [1] 番号名称
+        ID:   e6955cab611255a7518af51492c15c15
+        年份: 2025
+        路径: E:\01_automated\日本电影\...
+        大小: 5.12 GB
+        简介: ...
+    [2] 番号名称（破解版）
+        ID:   224ead2dfa59084b0d9f9080b188f297
+        年份: 2025
+        路径: E:\01_automated\日本电影\...
+        大小: 4.82 GB
+```
+
+### 检测结果解读
+
+| 检测类型 | 含义 | 处理建议 |
+|---------|------|---------|
+| **相同名称+年份** | 同一部电影在两个不同文件夹中 | 保留画质较好的版本，删除另一个 |
+| **相同文件大小+时长** | 同一个文件被多次扫描入库 | 删除 Jellyfin 中重复条目即可，无需删除文件 |
+
+## 常见问题
+
+### 连接失败怎么办？
+A: 检查 Jellyfin 是否在运行，确认网关 IP 是否正确：
+```bash
+ip r | grep default  # 查看默认网关
+```
+
+### 为什么有些重复没检测到？
+A: 目前检测逻辑：
+- 相同番号不同文件名 → 能检测到
+- 同一文件软链接/硬链接 → 能检测到（文件大小相同时）
+- 不同画质版本（4K vs 1080p）→ 不会被标记（大小不同）
+
+### 如何手动删除重复项？
+A: 在 Jellyfin Web UI 中找到重复电影 → 删除 → 在「文件和元数据」选项中勾选「删除文件」即可（注意别误删）。
+
+## 相关文档
+
+- API 配置: `jellyfin-config.md`
+- 搜索 API: `jellyfin-search-api.md`
+- 检测脚本: `jellyfin-dedup.py`
+- 演员统计: `../bt-scripts/jellyfin_actor_stats.py`