feat: bootstrap NAS music deduper

2026-09-18 04:48:47 +08:00
commit 6154cd0752
17 changed files with 481 additions and 0 deletions
@@ -0,0 +1,39 @@
+# AM Music Deduper
+
+轻量级家庭 NAS 音乐库去重服务，面向 `AllMusic/{username}/` 场景。
+
+## 设计目标
+
+- 本地 SQLite 元数据库
+- L1 极速候选：文件大小 + 头/尾 64 KiB hash
+- Exact Duplicate 最终使用完整 SHA-256 确认
+- L2 使用 Chromaprint 做音频相似度候选
+- duration 预过滤，降低 CPU/I/O
+- 同一版本才允许自动择优
+- loser 进入 `.dedupe/trash/`，默认保留 30 天
+- 不使用软链接；物理去重使用 hard link
+- inotify 增量处理 + 低优先级全量 reconcile
+- 任何不确定或异常默认保留原文件
+
+## 当前阶段
+
+第一阶段先完成安全的扫描、SQLite 索引、L1/Exact 去重、trash/quarantine 和测试。
+L2 Chromaprint 比对与生产 NAS 监听在后续阶段接入。
+
+## 安全原则
+
+1. 不修改正在写入的文件。
+2. L1 命中必须再做完整 SHA-256 才能判定 exact duplicate。
+3. 不根据歌名/歌手/专辑单独判重。
+4. 不同格式或音频规格不会因为 metadata 相似而直接合并。
+5. 自动处理前保留可恢复路径；失败不删除原文件。
+6. 数据库只是索引，文件系统才是最终事实。
+
+## CLI 预期
+
+```bash
+am-deduper scan /music/AllMusic
+am-deduper dedupe /music/AllMusic
+am-deduper reconcile /music/AllMusic
+am-deduper trash-prune /music/AllMusic --days 30
+```