曲库整理

曲库整理只由人触发，后台不会自动移动文件。所有移动、删除和空目录清理都先预览，执行后可以撤销。

命名规则

默认结构：

艺人 / 专辑 / 音轨号 - 曲名.ext

具体要求：

• 多艺人用 ; 连接。
• 专辑目录优先使用专辑艺人；合辑不会被拆散。
• 缺少专辑时，放进艺人的 Unknown Album 目录。
• 多碟专辑自动加碟号前缀。
• 缺少音轨号时直接用曲名。
• 文件名中的 /、\、: 等非法字符会被替换。
• 路径总长度受文件系统限制，超长时会截断并提示。

.lrc 与音频同名，跟随改名。封面和其他 sidecar 不会被移动。

范围与排除

• 受管根：一次整理一个根。
• 整理目录：可以多选子目录；不选表示整个曲库。
• 排除目录：可以多选，排除项优先于包含项。
• 包含和排除都使用相对路径，不能越出受管根。

排除项适合放过「正在整理」「临时下载」「不想动」的目录。每次预览都会显示本次实际范围和排除数量。

预览

预览会列出：

• 旧相对路径和新相对路径；
• 状态：移动、已正确、目标冲突、无法生成路径；
• 原因：缺标签、非法字符、目标已存在、跨卷等；
• .lrc 的旧名和新名；
• 移动后可能变空的目录。

状态为「已正确」的文件不会移动。目标冲突的文件不会覆盖，需要先手动处理。

预览计划保存在数据库中，有效期 6 小时，只能执行一次。修改范围、排除项或文件系统后，需要重新生成预览。

执行

点击「执行」后：

1. 再次校验计划仍然有效。
2. 按同一卷 rename 移动；跨卷时拒绝，而不是静默复制。
3. 同名目标存在时拒绝覆盖。
4. .lrc 跟随移动。
5. 记录旧路径、新路径、批次和时间。
6. 可选清理移动后为空的目录。

任何一步失败都会记录原因，不会把失败伪装成成功。

撤销

整理日志按批次显示移动、删除和空目录清理。可以单条撤销，也可以多选批量撤销。

• 撤销移动时，如果原路径已被占用，会跳过并提示。
• 撤销删除时，从回收站还原到原相对路径。
• 撤销按时间倒序执行，避免父子目录顺序冲突。

重复音频

重复检测在后台每 24 小时运行一次，只读，不会删除任何文件。也可以手动「立即检查」。

分类

分类	证据	是否可直接删除
音频完全一致	去掉标签后的音频哈希相同	通常可以
同一录音	MusicBrainz 录音 ID 或 AcoustID 指纹相同	需要试听，可能是不同压缩或版本
标题/艺人/时长相近	标题、艺人相同，整组时长跨度不超过 2 秒	必须试听

分类是互斥的：

1. 先建立精确副本组。
2. 同一录音组只收尚未进入精确组的文件；已进入精确组的文件作为受保护参照。
3. 相似组只收剩下的文件；精确组和录音组的保留项作为参照。
4. 相似组之间不再互相参照，避免 1 秒、3 秒、5 秒被传递串成一组。

每个可删除文件最多属于一个分类。参照项标为「其他分类保留」，不参与删除。

保留建议

每组按质量排序，优先保留：

• 有损格式中码率更高、标签更完整的；
• 有无损格式时优先无损；
• 已属于其他分类的参照项；
• 路径更规范、已有歌词或封面的。

保留理由显示在保留项卡片上，不会挂到待删除副本上。

选择与删除

• 默认不勾选任何项。
• 「全选当前分类」只勾选当前分类中建议删除的副本。
• 「一键删除此分类」由服务端按分类重新取数，只处理该分类的建议删除项。
• 「删除所选」处理手动勾选的副本。
• 参照项、建议保留项和其他分类的文件不会被连带删除。

删除前会校验所有选中组：

• 路径必须属于该组；
• 必须是建议删除项；
• 不能是参照项或保留项；
• 每组至少保留一份。

任意一组校验失败，整批不执行。旧版本产生的混合分类数据会被拒绝，并提示重新检测。

删除后文件进入 data/trash/，同时写入整理日志。可以在日志页批量撤销。

空目录

空目录清理只处理真正为空的目录。以下情况不会被清理：

• 目录里有刚移入的文件；
• 目录里有隐藏文件或 sidecar；
• 目录是受管根本身；
• 目录位于排除范围。

预览会列出目录和原因，默认勾选可以安全清理的项。

只读与安全

• policy.write_enabled = false 或 roots.read_only = true 时，执行接口拒绝运行。
• 所有路径都经过受管根校验，拒绝绝对路径、.. 和符号链接逃逸。
• 移动和删除都记录批次，支持撤销。
• 不会自动删除重复音频，也不会在后台自动整理目录。