Music Library Organizer / 音乐库整理

Other

音乐库整理工作流：扫描→规划→主人确认→软删除→验证→清理。强调安全流程。Safe-by-default music library organizer with soft-delete + mandatory owner confirmation.

Install

openclaw skills install @thinkcodee/music-library-organizer

音乐库整理 Skill (Music Library Organizer)

整理 /volume4/media2/音乐 下的所有音乐和歌词文件，按歌手字母 A-Z 归类 + 重命名 + 去重。 核心安全原则：永不立即删除，整理后必须主人确认才能彻底删除。

A safe-by-default music library organizer with 6-stage workflow: scan → plan → owner confirms → soft-delete → verify → cleanup. Hard deletes require explicit owner confirmation and 5-second delay.

适用场景 / Use Cases

首次整理一个新下载的乱序音乐库 / First-time organization of a new music library
重新整理已有的字母目录 / Reorganizing existing A-Z folders
合并多个来源（备份、低音质备份、新下载） / Merging multiple sources (backups, low-quality backups, new downloads)
修正之前整理时的错误（歌手/歌名反了、命名格式不统一） / Fixing previous organization errors (artist/song swapped, inconsistent naming)

核心原则（铁律）

🚨 安全铁律（不可违反）

永不立即删除文件
- 默认所有"删除"都是软删除（移到 _已删除_时间戳/ 目录）
- 只有**主人明确说"真删/硬删/永久删除/rm -rf"**才能物理删除
- 删除前必须二次确认（报大小+文件数+不可恢复）
- 不可逆操作必须延迟 5 秒执行
整理后必须验证
- 每个阶段完成后跑验证脚本
- 对比整理前后的差异
- 主人确认无误后才能继续下一步
必须分阶段
- 每个阶段独立可回滚
- 失败立即停止，不进入下一阶段

整理方法论（6 阶段工作流）

阶段 0：调研（必做）

在动文件之前，先调研：

目录大小（du -sh）
文件数量（find -type f | wc -l）
顶层结构（ls -la）
命名格式（抽样看 20-30 个文件）
绝不能假设之前整理过/没整理过，每次必须实际看

阶段 1：扫描 + 分类

扫描所有文件，按 4 类分类：

分类	特征	处理方式
正常	父目录=歌手，文件名=`歌手 - 歌名.ext`	跳过
反了	父目录=歌名，文件名=`歌名 - 歌手.ext`	修正
命名不一致	文件名用 `-` 不是 `-`（无空格）	改名
孤儿	无分隔符、无法识别	标记给主人看

关键工具：

父目录 = 歌手（最权威）
文件名解析：先 -（带空格），后 -（不带空格）
ID3 标签作为补充（mutagen）

阶段 2：生成计划（dry-run）

不修改任何文件，生成：

移动清单（从 A 移到 B）
改名清单（X.ext → Y.ext）
冲突清单（目标位置已存在）
预计影响（文件数、大小、磁盘释放）

输出为 CSV 或 JSON，让人工审阅。

阶段 3：用户确认

向主人报告：

总操作数
涉及歌手/字母
冲突案例（如果有）
风险点

**等待主人明确说"执行"**才能继续。

阶段 4：执行（软删除默认）

按顺序执行：

移动文件到新位置
改名
清理空目录

绝不删除任何文件——只移动和重命名。

阶段 5：验证

执行后立即验证：

文件总数是否一致
抽样几个文件确认位置/名称
反了的、命名不一致的统计应该都是 0
生成验证报告

阶段 6：主人确认后清理

只有主人说"清理"/"删除 X"时：

报告待删内容（大小+文件数）
二次确认
5 秒延迟
执行 rm -rf
验证目录已消失
记录到日志

目标目录结构

/volume4/media2/音乐/
├── A/
│   ├── A1 TRIP/
│   │   ├── A1 TRIP - 放空.flac
│   │   └── A1 TRIP - 放空.lrc
│   └── ...
├── B/
│   ├── Beyond/
│   │   ├── Beyond - 海阔天空.flac
│   │   └── Beyond - 海阔天空.lrc
│   └── ...
├── Z/
│   ├── 周杰伦/
│   │   ├── 周杰伦 - 晴天.flac
│   │   └── 周杰伦 - 晴天.lrc
│   └── ...
├── 其他/                          # 数字开头/无法识别的
└── _低音质备份/                    # 替换掉的低质版本（保留）

命名规则

音乐文件

单歌手：歌手 - 歌名.格式 （如 周杰伦 - 晴天.flac）
多歌手：统一用 & 连接（如 Alan Walker & K-391 - Different World.flac）
缺歌手：仅 歌曲名.格式，归入 其他/

歌词文件

与音乐文件主名一致：歌手 - 歌名.lrc
找不到匹配时保留原位

文件名格式铁律

分隔符必须用 -（带空格）
不用 -（不带空格）、不用 _

去重规则（音质优先级）

无损 (FLAC/APE/WAV)         → 100/95/90
320k MP3                    → 70
高码率 MP3 (≥256k)          → 60
普通 MP3                    → 50
M4A / AAC                   → 40/35
OGG / OPUS                  → 30
WMA                         → 20
其他                        → 10

被替换的低音质文件 → 目标根目录/_低音质备份/原路径（保留，不删除）

中文歌手名首字母

使用 pypinyin 库转拼音首字母
数字开头或无法识别 → 其他/

脚本	用途
`scripts/organize_music.py`	主整理脚本（dry-run + apply）
`scripts/dedup_music.py`	按音质优先级去重
`scripts/rematch_lyrics.py`	重新匹配歌词到音乐
`scripts/clean_orphan_lyrics.py`	清理孤立歌词（软删除）
`scripts/restore_orphan_lyrics.py`	从软删除目录恢复歌词
`scripts/cleanup_empty_dirs_v2.py`	清理空目录（软删除，v2 修正版）

完整工作流示例

场景 A：首次整理（无整理历史）

# 1. 调研
ls -la /volume4/media2/音乐/  # 看顶层
du -sh /volume4/media2/音乐/
find /volume4/media2/音乐/ -type f | wc -l

# 2. 干跑
python3 /root/.openclaw/workspace/scripts/organize_music.py --no-tag
# 输出: 整理报告_dryrun_时间戳.csv

# 3. 给主人看报告
# 报告: 影响 X 文件, Y GB, 涉及 Z 个歌手

# 4. 主人确认
# "执行"

# 5. 真执行
python3 /root/.openclaw/workspace/scripts/organize_music.py --apply

# 6. 验证
ls /volume4/media2/音乐/A/ | head -10
ls /volume4/media2/音乐/Z/ | head -10

# 7. 生成清单（可选）
python3 /root/.openclaw/workspace/scripts/generate_music_xlsx.py

场景 B：整理备份目录（如 `_低音质备份/`）

# 1. 扫描备份
du -sh /volume4/media2/音乐/_低音质备份/
find /volume4/media2/音乐/_低音质备份/ -type f | wc -l

# 2. 检查冲突
# 找备份里文件 vs 主目录同名文件 → 报告冲突

# 3. 给主人看 dry-run
# "X 个文件将移动到主目录, Y 个冲突（主目录更优，跳过）"

# 4. 主人确认

# 5. 执行
# - 移动非冲突文件
# - 删除冲突的备份文件（**不删主目录版本**）
# - 删除空目录

# 6. 验证 + 生成清单

场景 C：修正歌手/歌名反了的文件

# 1. 扫描所有"反了"的文件
# 规则：父目录=歌名（looks_like_song_title），文件名=歌手

# 2. 报告
# "X 个文件需要：改名 + 移动到正确歌手目录"
# "Y 个是父目录=歌名但其实是多歌手"

# 3. 主人确认

# 4. 执行：重命名 + mv + 删空目录

安全检查清单

每次执行前：

已调研（du, find, ls）
已生成 dry-run 报告
已给主人看报告（影响范围）
主人明确说"执行"
5 秒延迟后执行（针对删除）
验证完成（文件数一致、抽样确认）
记录到 memory

每次删除前：

主人明确说"硬删/真删/rm -rf/永久删除"
报告：大小、文件数、不可恢复
二次确认（"确认真删除"）
5 秒延迟
删除后验证目录已消失
记录到 memory

错误处理

错误	处理
权限拒绝	`chmod -R a+rX` 后重试
磁盘满	立即停止，报告
目标位置冲突	报告给主人，不要自动覆盖
ID3 标签解析失败	回退到文件名解析
父目录=歌名	报告给主人，让主人决定
无法识别的格式	移到 `其他/`

关键教训（来自历史任务）

2026-06-19 教训

误删了 26 个 .lrc 歌词（脚本 bug + 没二次确认）
教训：所有删除必须软删除 + 二次确认
修正：MEMORY.md 加了"数据安全规则"

2026-06-21 教训

误判 /音乐/ 已清空（实际 46,000+ 项目还在）
教训：删之前必须 ls -la 实际验证
修正：MEMORY.md 加了"重要目录区别"

2026-06-21 经验

organize_music.py 设计良好（dry-run 报告 + 软删除 + ID3 标签）
重命名 55 个文件：用 -（带空格）统一格式
81 个反了文件：要重命名 + 移动到正确目录

Music Library Organizer / 音乐库整理

Install

音乐库整理 Skill (Music Library Organizer)

适用场景 / Use Cases

核心原则（铁律）

🚨 安全铁律（不可违反）

整理方法论（6 阶段工作流）

阶段 0：调研（必做）

阶段 1：扫描 + 分类

阶段 2：生成计划（dry-run）

阶段 3：用户确认

阶段 4：执行（软删除默认）

阶段 5：验证

阶段 6：主人确认后清理

目标目录结构

命名规则

音乐文件

歌词文件

文件名格式铁律

去重规则（音质优先级）

中文歌手名首字母

推荐脚本

现有脚本（已验证可用，全部打包在 `scripts/` 子目录中）

完整工作流示例

场景 A：首次整理（无整理历史）

场景 B：整理备份目录（如 `_低音质备份/`）

场景 C：修正歌手/歌名反了的文件

安全检查清单

错误处理

关键教训（来自历史任务）

2026-06-19 教训

2026-06-21 教训

2026-06-21 经验

相关文件

Music Library Organizer / 音乐库整理

Install

音乐库整理 Skill (Music Library Organizer)

适用场景 / Use Cases

核心原则（铁律）

🚨 安全铁律（不可违反）

整理方法论（6 阶段工作流）

阶段 0：调研（必做）

阶段 1：扫描 + 分类

阶段 2：生成计划（dry-run）

阶段 3：用户确认

阶段 4：执行（软删除默认）

阶段 5：验证

阶段 6：主人确认后清理

目标目录结构

命名规则

音乐文件

歌词文件

文件名格式铁律

去重规则（音质优先级）

中文歌手名首字母

推荐脚本

现有脚本（已验证可用，全部打包在 scripts/ 子目录中）

完整工作流示例

场景 A：首次整理（无整理历史）

场景 B：整理备份目录（如 _低音质备份/）

场景 C：修正歌手/歌名反了的文件

安全检查清单

错误处理

关键教训（来自历史任务）

2026-06-19 教训

2026-06-21 教训

2026-06-21 经验

相关文件

现有脚本（已验证可用，全部打包在 `scripts/` 子目录中）

场景 B：整理备份目录（如 `_低音质备份/`）