Peach 0.52.0 · 功能缺口报告：SMB/NAS 媒体库 + 外部刮削结果复用

[jackalgao-bot]

0. 一句话

在「Windows 本机 + NAS 共享盘（Z: 映射，1785 个平铺文件）+ 另一个刮削器负责产出 NFO/封面」的组合下，Peach 目前 无法完成首次扫描 （20 秒硬超时），也 无法把媒体文件交给本机外部播放器并同时命中同目录字幕 （SMB 来源只给 URL），且 已登记的媒体根不能更换传输方式 （本地→SMB 必须删根重建）。

1. 环境与现状

• Peach：0.52.0 ，commitc91779d7258301bcddba5cc6be6f9304df730748 ，便携版（Windows 11，10.0.26200，AMD64）
• 机器：Ryzen 9 7945HX（16C/32T），32 GB 内存
• 数据目录：E:\datel\Peach\peach-data （已迁出系统盘）
• 媒体：NAS（极空间 Z4Pro+）外接 NTFS 盘，SMB 共享外部设备-SATA2 ，Windows 映射为Z: ，Peach 中登记为 本地磁盘Z:\media
• 目录形态： 完全平铺，无子目录
  • 条目 1785 = 视频 1508 （avi 516 / mp4 490 / wmv 480 / mkv 22）+ 字幕 276 （srt 251 / ssa 15 / ass 10）+.javdex-root 1（0 字节）
  • 总大小约 2.79 TB；字幕与视频同主名（如k1188.srt ）
• 另一个工具（Javdex） 只读 扫同一目录并负责刮削；Peach 侧不需要任何写媒体目录的能力（不使用"整理"）
• 现状配置：媒体库「我的媒体库」，来源「本地磁盘」，读取策略「正常读取」，处理方式「仅使用本地资料」，预览关闭

2. 需求（按优先级）

1. 只读共用 ：同一媒体目录，另一个程序负责刮削，Peach 只浏览/播放，不写媒体目录。
2. 少复制 ：Javdex 导出的 NFO 与封面按需被 Peach 读取；最好支持"一个番号一份封面"被该番号的多分卷共用，避免每文件一份拷贝。
3. 自动区分分卷 ：xxx-1 / -2 / -3 应被识别为同一作品的多个分卷（一个作品卡、多资产）。
4. 外部播放器 + 字幕 ：从 Peach 点"用 PotPlayer 打开"时， 必须传本机可访问的真实文件路径 （如Z:\media\k1188.wmv ），让播放器按同目录同名规则自动命中k1188.srt 。
5. 预览九宫格可按条手动生成，默认关闭（此项目前工作正常）。

3. 阻塞项与证据

B1（阻塞级）映射盘上的首次扫描必然 20 秒超时

• 现象：扫描失败，files=0 ；issue：[Errno 10060] 读取媒体目录或配套文件超时，已跳过，可重试: 'Z:\\media'

• 状态文件：state\library-processing.json →scan_checkpoints["local:z:\\media"] = {"files": 0, "seconds": 20.13, ...}

• 源码：src/peach/media_io.py:15``TIMEOUT_SECONDS = 20.0 （硬编码、无配置）；media_io.py:116-140 的directory 读取在 Windows 本地盘分支里对 每个条目entry.stat() ，并且value == 'identity' 时再os.stat(entry.path) 补读一次

• 实测（同一时刻、同一台机器、资源管理器/PowerShell 正常）：

  • 目录枚举 1785 条： 1.75 s
  • 单文件 stat： 11.1 ms
  • 1508 个视频逐个 stat： 16.7 s
  • → 清单 + 第二层身份补读必然越过 20 s 上限，files=0 是必然结果，不是偶发抖动

• 说明：测试连接（/api/configuration/smb/test ）能通过，说明账户与共享本身没问题
  期望 ：

• a) 该超时可配置，或按条目数量分级（例如 ≥N 条目时放大到 120 s）；至少允许单一 request 超过 20 s 时"部分成功"而不是整目录判失败；

• b) 对网络映射盘（UNC/映射盘） 避免逐文件二次 stat ：Windows 的QueryDirectory 已返回属性，可用一次查询；st_ino 缺失时不要在读取请求里补，改为"身份缺失 → 记为未知"而不是失败；

• c) 可选：对映射盘提供"按网络路径处理"的标记，走与 SMB 传输相同的低往返路径。

B2（阻塞级）同一真实目录无法以两种传输并存，且既有根不能改传输方式

• 现象：已有Z:\media 根时，再加smb://192.168.18.86/外部设备-SATA2/media → 输入框变红 + "无法保存配置"；而"测试连接"显示"共享目录可读取"

• 源码：media_configuration.py:192-198 （declared /path 重复或互含即报"媒体目录与另一行重复或互相包含"）；media_identity.py:169 （"已有根目录的来源和账本路径不可更换；请添加另一目录"）

• 影响：想在两种传输之间试跑，必须先删根、重扫，且丢失根 ID
  期望 ：

• a) 允许 修改既有根的transport （filesystem ↔ smb）并保留root_id 、账本前缀与资产 ID （明确的重定位语义，与 ADR-0115 一致）；

• b) 或允许同一真实目录登记两条传输，但只允许其中一条启用扫描/读取。

B3（需求级）SMB 来源下"外部播放器"拿不到本地路径

• 现象：SMB 根下点"系统默认播放器/PotPlayer 打开"，播放器收到的是smb://... 字符串
• 源码：src/peach/local_playback.py:63 （subprocess.Popen([chosen[1], str(path)]) ；SMB 资源__str__ 即 smb URL）
• 后果：即使 PotPlayer 能打开 URL， 同目录.srt/.ass 不会自动配对 （URL 流无同目录概念），这正是本需求的核心目标
  期望 ：为 SMB 根提供"本机路径映射"配置（例如把smb://host/share/media 映射为Z:\media 或 UNC），local-playback 时优先使用该映射路径打开；映射缺失时再退回网络地址。

B4（需求级）平铺目录的 NFO/封面命名过于严格

• 源码：src/peach/library_nfo.py:66-84

  • NFO：<视频主名>.nfo → 否则按番号唯一匹配 → 否则movie.nfo （仅单视频目录或同番号）
  • 封面：<视频主名>-poster.jpg →<视频主名>.jpg →poster/folder/cover.* （ 仅单视频目录 ）

• 影响：1785 个文件平铺时，poster.jpg 类目录级封面无效；多分卷需要 每文件一份封面 ，与"少复制"目标冲突
  期望 ：

• a) 封面增加"按番号匹配"回退（同 B 的 NFO 逻辑）：<番号>-poster.jpg /<番号>.jpg 可被该番号所有分卷共用；

• b) 或允许目录级封面（poster.jpg /folder.jpg ）在多视频目录内按番号配对生效。

4. 已确认工作正常的部分（不需要改）

• 番号识别是通用规则（catalog_rules.py 的^(?:\d{3})?[A-Za-z]{2,8}[-_. ]?\d{2,5}$ 与^(?:n|k)(\d{3,5}) 分支），jup0019 / gedo0043 / kb1547 这类前缀不需要白名单
• 预览/时间轴产物、转码分片、字幕 WebVTT 都写数据目录， 媒体目录零写入 （library_processing.py:2269 、timeline_sheets.py 、config.py:142 ）
• 预览开关独立于刮削；按库custom 只勾 probe+preview 即可"永不联网刮削"
• SMB 传输本身可用（测试连接通过；smb_transport.scandir 一次查询带属性）

5. 复现步骤（最短路径）

1. 便携版 0.52.0，数据目录指向非系统盘
2. 添加媒体目录：Windows 映射网络盘Z: ，指向 SMB 共享下 1785 个平铺文件
3. 来源"本地磁盘"，读取策略"正常读取"，处理方式"仅使用本地资料"，预览关闭
4. 点扫描 → 约 20.1 s 后失败：[Errno 10060] 读取媒体目录或配套文件超时… ，files=0
5. 在已有Z: 根的情况下再添加同一共享的smb://... 路径 → 保存报"重复或互相包含"，无法保存

[longmeidao]

新版本应该已经修复了；如果仍能复现可以开一个 issue 提供诊断日志，我来排错。