Files
Thing/MUSIC_DECRYPT_PLAN.md
T
2026-09-28 00:21:12 +08:00

50 KiB
Raw Blame History

音乐模块 · 本地音乐解密规划(Music Decrypt Plan)

状态:P0 + P1a + P1c 已实施并完成真机端到端验证(2026-09-27:网易云解密 + QQ音乐离线解密 + 文件夹批量 + musicex 在线取密钥,用真实 192kHz/24bit .mflac 样本跑通全链路;Rust 单测 204 项全库通过) 定位:音乐模块的「本地解密」子能力,不是独立模块——挂靠 music 模块新增「解密」页签,Rust 侧新增 music/decrypt/ 子模块;ncm 与 qmc 均为纯 Rust 离线引擎,QQ 按「内嵌 ekey 离线 → musicex 在线取密钥」分层(Frida 降为 P2 兜底) 日期:2026-09-27(同日修订:QQ 分层重排、ncm 算法细节补全) 关联文档:AI_DEV_GUIDE.md(模块注册 / IPC 范式——注意 specta 绑定见 lib.rs 的 export_bindings())、MUSIC_REMOTE_PLAN.md(规划文档范式) 参考项目与许可分档:


0. 结论先行

  1. 范围收敛到两平台(本轮显式指定):网易云 .ncm + QQ音乐 QMC 系列。酷狗/酷我明确出栈,不进任何分期。
  2. 两条技术路线,全部纯 Rust,零新增运行时依赖:
    • ncm → Rust 原生(aes 0.8 / cbc 0.1 / base64 0.22 已在依赖;ecb crate 不在依赖树,ECB 手写 16 字节块循环,零新增 crate)。
    • QQ → Rust 原生三层路由(详见 §3.2):① 尾部内嵌 ekey 的文件纯离线可解;② musicex 文件读本机凭据调 GetEVkey API;③ 前两层都不成立才用 Frida 注入兜底。
    • 本节原有的「Frida 主链」判断已作废:它把「需要客户端在跑」与「需要 Frida 注入」绑成了一件事。实际只有第③层需要注入,而前两层覆盖绝大多数真实文件。改分层后不再需要便携 Python、不再需要 pip install frida、不再受杀软与 mangled 符号版本漂移影响。
  3. UI 是音乐模块第 4 个页签「解密」:useModuleTabs 加一项 + DecryptPanel.vue + 独立轻量 store,命令与事件挂进现有 music 命令族,完全照抄下载任务的「先回 taskId、进度走事件」范式。
  4. 许可边界分三档:ncmdump 是 MIT,可逐行对照;QKKDecrypt 与 qmc-decoder 是 GPLv3 + FFmpeg GPL,只沉淀格式/协议知识与坑清单,实现逐行重写。
  5. 工作量:P0(网易云 + 页签全链路)约 2 个工作日;P1a(QQ 离线 + API,纯 Rust)约 2~3 个工作日;P1b(Frida 兜底,按需)另计。
flowchart LR
  subgraph FE["前端 · 解密页签"]
    A["DecryptPanel.vue<br/>文件选择 / 任务列表 / 状态卡"]
    S["decryptStore.ts<br/>任务状态 + 事件监听"]
  end
  subgraph R["Rust · music/decrypt/"]
    C["commands.rs<br/>run / cancel"]
    N["ncm.rs<br/>网易云离线引擎"]
    Q["qq.rs<br/>QMC 三层路由(P1)"]
  end
  subgraph QQS["QQ 三层(P1)"]
    L1["① 尾部内嵌 ekey<br/>纯离线"]
    L2["② musicex → 本机凭据<br/>GetEVkey API"]
    L3["③ Frida 兜底<br/>(P1b,按需)"]
  end
  O["savedir/decrypted/"]
  A --> S --> C
  C --> N --> O
  C --> Q --> L1 --> O
  Q --> L2 --> O
  Q -.-> L3 -.-> O
  Q -.->|"music-decrypt-event"| S
  N -.-> S

1. 需求解构

用户原话 解构 落点
在音乐模块添加解密 Tabs 音乐模块第 4 个页签 §5.2
解密各平台的加密格式 收敛为 QQ音乐 + 网易云(本轮显式指定) §3
最小路径实现 砍掉:转码、元数据回填、封面提取、拖拽、酷狗酷我、并发调优、历史持久化 §7 P2 清单
可参考 QKKDecrypt 对齐思路与坑,不搬 GPLv3 代码 §3.3

2. 现状勘察(2026-09-27 从仓库实际读取)

2.1 已具备的基建(直接复用)

能力 现有实现 复用方式
Tab 体系 useModuleTabs(MusicModule.vue:78,alwaysVisible 模式,标题栏浮动切换器自动接管) 加 { value: 'decrypt', label: '解密' } 一项
任务 + 事件范式 music_download / music-download-event(commands.rs:187、constants.rs:107) 解密照抄:先回 taskId,进度推事件
便携 Python + pip 镜像 runtime.rs(清华源 PIP_INDEX_URL,mod.rs:77) QQ sidecar 的 frida 安装、Python 就绪检查
加密依赖 Cargo.toml 已有 aes = "0.8"、cbc = "0.1"、base64 = "0.22" ncm 的 AES-128-ECB 手写循环,零新增依赖
specta 绑定 lib.rs export_bindings() 两处 collect_commands! 新命令两处同步登记(lib.rs:300 注释明确要求)
文件选择对话框 @tauri-apps/plugin-dialog(MusicModule.vue:4 已 import) 页签内直接用,不加 Rust 命令
输出目录 默认 savedir(设置页「本地下载目录」) 解密默认输出 savedir/decrypted/
播放引擎 symphonia(Cargo.toml:115) 解出的 flac/mp3/ogg 可直接进曲库试听

2.2 关键缺口(需新增)

缺口 说明
ncm 解密实现 纯算法,约 200 行 + 单测
QQ 运行期 sidecar Frida 注入 + EncAndDesMediaFile 调用序列,按参考思路重写
解密任务 store 下载任务在 musicStore;解密需独立轻量 store(页签切换会卸载组件,监听器必须挂 store)
frida 依赖安装 pip install frida(wheel 带原生扩展,走现有镜像),需一条安装命令 + 进度事件

3. 技术选型

3.1 网易云 .ncm:Rust 原生离线

为什么不进 Python:

  • ncm 是纯文件级算法,不需要任何进程配合;塞进 Python 等于把 200 行算法绑上「必须先装运行时」的前置。
  • 便携 Python 是按需安装(musicdl 才触发),解密不应被它卡住——Rust 路线开箱即用。
  • Rust 侧可直接 cargo test,对照样本文件做回归。

算法要点(对照 MIT 协议的 ncmdump(src/ncmcrypt.cpp)逐条独立重写。下面每一条都是会写错的地方,不是梗概):

① 容器结构

0x00  magic     8B   "CTENFDAM"(即 43 54 45 4E 46 44 41 4D)
0x08  2B        0x02 0x00  → 跳过
0x0A  key_len   4B   LE
0x0E  key_data  key_len B      (XOR 0x64 → AES-128-ECB → 得 RC4 密钥盒种子)
...   meta_len  4B   LE
...   meta_data meta_len B     (XOR 0x63 → 去 22B 前缀 → base64 → AES-128-ECB → 去 6B 前缀 → JSON)
...   5B        跳过(CRC32 4B + 图片版本 1B)
...   cover_len 4B   LE
...   img_len   4B   LE
...   img_data  img_len B      (内嵌封面:PNG 或 JPEG)
...   跳 cover_len - img_len
...   audio     剩余全部        (改性 RC4)

② 两个 XOR 常量不同(原文档误合并成一个 0x64)

段 XOR 常量 加密方式 解密后处理
key 段 0x64 AES-128-ECB 跳过前 17 字节(neteasecloudmusic),其余即 RC4 密钥盒种子
meta 段 0x63 AES-128-ECB(先 base64 解码) 跳过前 6 字节(music:),其余为 JSON

③ AES-128-ECB 解密:key 段与 meta 段用两个不同的 16 字节密钥——sCoreKey = ASCII neteasecloudmusi(即 17 字节前缀 neteasecloudmusic\0 的前 16 字节)、sModifyKey = ASCII #14ljk_!\]&0U<'(。收尾不是"去前缀",而是 PKCS#7 风格 padding:逐 16 字节块解密,最后一字节即 padding 长度(> 16 时视作 0),去掉 padding 后再手动跳前缀。

易错点:「AES 密钥」与「要剥掉的前缀」是两个东西。neteasecloudmusic 既是被剥的 17 字节前缀(含结尾 NUL),其前 16 字节又是 key 段的 AES 密钥;meta 段则两者都不同。混用不报错、只会全解错(实现里分别命名为 CORE_KEY / CORE_AES_KEY / MODIFY_KEY)。

④ meta 段的两层前缀:原始数据前 22 字节是字面量 163 key(Don't modify):,先剥掉它,再对余下部分 base64 解码,才喂给 AES。

⑤ 音频段是「改性 RC4」

  • 密钥盒用参考实现的 KSA:swap = keybox[i];c = (swap + last_byte + key[key_offset]) & 0xff,key_offset 触 keyLen 归零循环取 key,keybox[i] = keybox[c]、keybox[c] = swap、last_byte = c。照抄即可,但注意 last_byte 在模 256 下是恒等变形(结果与标准 RC4 逐字节相同),它既不是"关键差异",也不能作为验证手段——见 §6.25。
  • 明文按 0x8000 字节一块循环,块内 j = (i + 1) & 0xff,plain[i] = cipher[i] ^ keybox[(keybox[(keybox[j] + j) & 0xff] + keybox[j]) & 0xff]。块之间不重置密钥盒、也不额外跳字节——i 是块内下标。
  • 块边界必须由"读满一块"确定(read_full),不能用 Read::read 的短读结果,否则相位错位、中途变噪声(§6.24)。
  • 不存在"每 0x8000 字节后跳过 5 字节间隔"(原文档此条有误)。0x8000 是块大小,5 是 §① 里跳过的 CRC32 + 图片版本。

⑥ 输出扩展名由音频首帧魔数决定,不是 meta 的 format 字段(原文档此条说反了):首个解密块以 ID3(0x49 0x44 0x33)开头 → .mp3,否则 → .flac。meta 的 format 只用于另一件事——判断该不该回填标签/封面时的格式分支。

⑦ 顺手可得的元数据:meta JSON 含 musicName / artist(二维数组,取每项第 0 个元素并用 / 连接)/ album / bitrate / duration,且封面字节已在上面的 img_data 里读出。P0 已实现封面单独落盘(<歌名>.cover.png|jpg,按魔数定扩展名);写进音频标签仍留 P2——那需要 lofty 且要按 mp3/flac/m4a 分派容器,属于「增强」而非「能播」。

⑧ 失败处理:魔数不符 / key_len <= 0 / 块不足 16 字节 → 返回可读错误(Err(String)),per-file 失败不 panic、不中断整批。

3.2 QQ音乐:Rust 原生三层路由(本节已重写)

原判断作废的理由:原文把「需要 QQ 客户端在跑」与「需要 Frida 注入」绑成了一件事。二者其实独立——ekey(解密密钥)有三种存储形态,只有第三种才需要注入。前两层覆盖真实曲库的绝大多数文件,且都是纯 Rust。

QMC 加密本体(与 ncm 同构:字节流密码 + 可选密钥):

方案 密钥来源 适用
QMC1 固定种子,无需密钥 旧版 .qmc0 / .qmc3 / .qmcflac / .qmcogg
QMC2 ekey(base64 + TC-TEA 加密),密钥 ≤300B 走 Map XOR,>300B 走改性 RC4 .mgg / .mflac 全系

ekey 的三种存储形态 → 三层路由:

层 形态 需要客户端? 实现方式
① 尾部内嵌 ekey:QTag 格式(ekey + 歌曲 ID + QTag 魔术)或 V1 格式(文件末尾 4 字节为 key 长度,key 在其前) ❌ 不需要 纯 Rust 离线,从文件尾直接提取
② musicex 尾部(QQ 客户端 ≥ 19.57 / Win 22.x):尾部 192B 只存 song_id + media_mid + filename,ekey 不落盘 ✅ 需运行且已登录 纯 Rust:读凭据 → 调 API 取 ekey
③ 客户端内部导出(方案原文所选) ✅ Python sidecar + Frida attach QQMusicCommon.dll

第②层的完整链路(全部可在 Rust 内完成,windows-sys 只差一个 feature):

  1. 尾部检测:读末 8 字节,为 "musicex\0" 即 musicex;再向前读 footer_size + 8 解析完整 footer(0x00 song_id u32LE、0x0C media_mid UTF-16LE 60B、0x48 filename UTF-16LE 68B、0xC0 footer_size、0xC8 magic)。
  2. 取 uin:读 %APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini 的 [Account] Uin(明文 INI)。
  3. 取 authst:authst 在 Windows 上不落盘,仅在运行中的 QQMusic.exe 进程内存里。用 CreateToolhelp32Snapshot + Process32FirstW/NextW 定位进程 → OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ) → VirtualQueryEx 遍历可读区(只需 MEM_COMMIT,跳过 MEM_MAPPED)→ ReadProcessMemory 按 1MB 分块 → 搜 "authst":" 取其后 Base64URL 串。实测约 0.5 秒。
  4. 调 API:POST https://u.y.qq.com/cgi-bin/musicu.fcg,req_1.module = "music.vkey.GetEVkey"、method = "CgiGetEVkey";param.filename 必须带 .mgg/.mflac 后缀、param.songtype 必须为 1(否则返回 104005)、param.platform = "27"(Windows)。响应取 req_1.data.midurlinfo[0].ekey。

三处易错点:MEMORY_BASIC_INFORMATION 在 Win10 1803+ 有 2 字节 PartitionId 插在 AllocationProtect 与 RegionSize 之间,漏掉会导致 state 读成 protect、所有内存区被跳过;filename 不带扩展名返回空 ekey;authst 有效期约 22.3 小时会过期。

前置检查与降级出口(UI 状态卡据此渲染):QQ 未运行或未登录 → 提示"请启动并登录 QQ 音乐后重试";层①②均失败的文件才落到③;Frida 不可用时报可读错误并给排除指引,不自动拉起 QQ 客户端。

③(P1b,按需)的形态若将来要做:qq_decrypt.py 走 include_str! 内置(与 bridge.rs:17 的 BRIDGE_SCRIPT 同范式),一次进程 attach 一批文件,stdout JSON-Lines 回报进度;导出符号是 mangled name(?Open@EncAndDesMediaFile@@…),按子串 EncAndDesMediaFile 模糊匹配,严禁硬编码地址或 RVA。

输出扩展名(不能按输入扩展名机械映射):.qmc0→.mp3、.qmc3→.mp3、.qmc2→.ogg、.qmcogg→.ogg、.qmcflac→.flac、.mgg/.mgg0/.mgg1/.mggl→.ogg、.mflac/.mflac0/.mflach→.flac(均以首帧魔数兜底校验)。.mmp4 的产物容器(m4a 还是 mp4)尚未独立证实,实施 P1 时必须用真机样本确认后再定。

3.3 许可边界(必须遵守,三档口径)

  • MIT(可逐行对照):taurusxin/ncmdump(网易云 ncm 算法本体)。可直接对照 src/ncmcrypt.cpp 实现,仅需保留版权声明。
  • GPLv3(只读文档与行为,严禁抄代码):QQKWKG-TriMusicDecrypt(+ FFmpeg GPL)、ownlight6/qmc-decoder。整段搬代码 = 给本仓库引入 GPL 传染。 允许的是:阅读其调用序列、常量、格式与协议说明后独立重写——本文档 §3.1 / §3.2 沉淀的正是这类非代码知识。
  • 合规口径(UI 底部放一行):仅处理用户本人拥有合法访问权限的本地文件,不用于批量分发或规避付费授权。

4. 接口契约

4.1 Tauri 命令

// 任务
music_decrypt_run(task_id, files?, folder?, root?, out_dir?, in_place?) -> Result<(), String>
music_decrypt_cancel(task_id: String) -> Result<bool, String>
// 预览与状态
music_decrypt_scan(folder: String, root: Option<String>) -> Result<ScanSummary, String>
music_decrypt_qq_status() -> Result<QqOnlineStatus, String>   // 只读本机,不发网络请求

QqOnlineStatus 字段:{ running, loggedIn, uin, ready, message, steps }。 authst 不下发到前端——它只活在后端内存里用于调接口。

  • 注册是 3 处,不是 2 处(实测仓库现状):
    1. music/mod.rs 的 pub use commands::{...} re-export(约 mod.rs:48);
    2. lib.rs 的 collect_commands![](export_bindings() 内,lib.rs:205);
    3. lib.rs 的 generate_handler![](run() 内,lib.rs:348)。 漏第 2 处 = 运行时能调但 bindings.ts 缺类型;漏第 1、3 处 = 编译失败或调用失败。
  • 前端沿用本模块既有范式(musicStore.ts 全用原生 invoke + 手写类型,不用 commands),故解密 store 同样用 invoke。

4.2 事件 music-decrypt-event(登记进 constants.rs 音乐分组)

type MusicDecryptEvent =   // 注意:只有 tag 是 kebab-case,**字段名仍是 snake_case**
  | { type: 'start';    task_id: string; total: number }
  | { type: 'file';     task_id: string; index: number; name: string;
      status: 'ok' | 'error' | 'unsupported';
      message: string | null;   // 失败原因,或成功时的备注(平台 / 密钥形态 / 元数据摘要)
      output: string | null;    // 主产物
      cover: string | null }    // 单独落盘的封面(网易云带内嵌封面时才有)
  | { type: 'progress'; task_id: string; done: number; total: number;
      bytes_done: number; bytes_total: number; name: string }
  | { type: 'finished'; task_id: string; ok: number; failed: number; cancelled: number }

字段名是 snake_case 而非 camelCase:DecryptEvent 上只有 #[serde(tag = "type", rename_all = "kebab-case")] 作用在 tag 上,变体字段名原样输出。前端 decryptStore.ts 的 RawEvent 必须照此声明 ——两边不一致时不会编译报错,只会表现为「任务建好了但进度永不动」。 Rust 侧有 event_json_contract 单测把形状钉死(§6.23)。

结果态没有 already:P0 不做「已解密过则跳过」(同一文件重解会产出 _1 后缀的新文件), 语义比"猜哪份产物属于哪次输入"更可预测。

原先的 deps-install 事件随 music_decrypt_install_deps 一起取消——三层路由后不再需要 pip install frida。 注意前端 musicStore.ts:419 是硬编码事件名字符串、并未引用前端常量表,故解密 store 同样硬编码,仅 Rust 侧登记常量。

4.3 文件识别(用户不选平台)

按扩展名路由,魔数校验兜底:

扩展名 路线
.ncm 网易云离线引擎(按内容魔数识别,不依赖后缀)
.mgg / .mgg0 / .mgg1 / .mggl / .mflac / .mflac0 / .mflach / .mmp4 / .qmc0 / .qmc2 / .qmc3 / .qmcflac / .qmcogg QQ 引擎(按尾部形态决定是否联网)
其他 散选时保留为 unsupported;文件夹扫描时直接跳过

后缀矩阵原文档只列了 3 个,会静默漏掉用户曲库里的常见文件,故过滤列表与路由表一次写全。 实际判定以内容为准(§4.5),后缀只用于文件对话框的过滤器。

4.3.1 QQ 音乐:是否需要登录?

这是使用者最常问的一点,所以结论放在前面:

文件来源 扩展名 需要 QQ 音乐登录?
QQ 客户端 ≤ 19.51 下载 .qmc0 .qmc3 .qmcflac .qmcogg 不需要
QQ 客户端较旧版本下载(QTag / V1 尾部) .mgg .mflac 不需要
QQ 客户端 ≥ 19.57 下载(musicex 尾部) .mgg .mflac .mmp4 需要:客户端运行 + 已登录
网易云(任何版本) .ncm 不需要

为什么新版必须登录:从 19.57 起,QQ 音乐不再把解密密钥(ekey)写进文件, 只在文件末尾留 192 字节元数据;客户端自己也是在播放/下载时拿本机登录态 (uin + authst)向服务器实时换取密钥。第三方要解开同一个文件,只能复刻这一步。

这里的实现方式:只读本机凭据(INI 里的 uin + 运行中 QQMusic.exe 内存里的 authst), 再调官方 music.vkey.GetEVkey 接口取密钥——不注入进程、不改写文件、不做任何反检测。

操作步骤(与 UI 状态卡里的文案一致):

  1. 在电脑上启动 QQ 音乐客户端(Windows 版)。
  2. 用它登录你的账号,并保持客户端开着(authst 只存在于运行期内存)。
  3. 回到「解密」页点「重新检测」,状态变为「已就绪」即可解密 musicex 文件。
  4. 若提示未取到登录令牌:先在客户端里播放任意一首歌触发一次网络请求,再重新检测。
  5. 仍失败则试过以管理员身份运行本应用(读其他进程内存可能需要更高权限)。
  6. 登录令牌约 22.3 小时过期;过期后重新检测即可,无需重装。

UI 呈现:状态卡显示三态(未运行 / 未登录 / 已就绪)+ QQ 号 + 「重新检测」按钮; 未就绪时折叠区里就是上面这 6 条步骤。上方那句"旧版文件与 .ncm 本来就不需要登录" 也会一并显示,避免用户误以为自己必须登录才能用这个功能。

4.4 输出路径规则

  • 就地模式(in_place = true,文件夹批量的默认):产物与源文件同目录同名, 仅按格式改扩展名(Pop/a.mflac → Pop/a.flac)。符合"就地解出来"的直觉, 也天然不会与其他目录的同名文件冲突。此时 out_dir 不参与写盘。
  • 指定输出目录(in_place = false):默认根目录 savedir/decrypted/, 并按 root 还原相对目录结构(Pop/2026/b.ncm → out/Pop/2026/b.flac)。 散选文件没有相对目录,平铺到根目录。
  • 同名去重:即使还原了目录结构,同一目录内仍可能撞名(如 .mgg 与 .mgg1 同基名)。 规则:优先用原名,已存在(磁盘上或本批内已占位)则追加 _1 / _2…
  • 输入输出相交保护:非就地模式下,若某输入文件已位于输出目录内则剔除, 避免"解出来再解"无限膨胀;全被剔除时报错并提示可改用「就地解密」。
  • 扩展名以音频首帧魔数决定(ncm 见 §3.1⑥,QMC 见 §3.2 末),不信任输入扩展名; 魔数认不出时才回退到输入后缀映射。

4.5 文件夹批量

命令参数的关系:

参数 含义
folder 文件夹批量入口:Rust 侧递归扫描该目录
root 计算相对路径的基准(决定输出目录里还原哪几层)
files 散选文件列表(folder 为空时使用)
in_place 就地解密(默认 true,见 §4.4)
music_decrypt_scan 只扫描不解密,返回 { total, ncm, qmc } 供 UI 预览

平台判定按内容,不按后缀(scan::route):

  1. 读 8 字节魔数,命中 CTENFDAM → 网易云;
  2. 否则读尾部判 QMC 形态:后缀在 QMC 家族里 → QQ音乐;
  3. 后缀不认识时,只有明确的尾部形态(QTag / V1 / musicex)才认领—— 否则任何末尾凑巧不是 QTag 的文件都会被判成"QMC1",噪声太大。

理由:同一曲库里 .ncm / .mflac / .qmcflac / .mgg 混放是常态,且 QQ 还有 .mgg0 / .mflac0 等变体,靠后缀枚举必然漏。代价是认不出的文件会被跳过, 所以扫描数可能少于用户预期——因此 UI 先调 music_decrypt_scan 显示 "找到 N 个 · 网易云 x · QQ音乐 y",让用户在开跑前就能判断是否符合预期。


5. 架构与模块设计

5.1 Rust 侧 src-tauri/src/music/decrypt/(已实施的实际结构)

decrypt/
  mod.rs             // 任务表(Mutex<HashMap<taskId, 取消标志>>)、工作线程 + 节流事件转发、事件契约
  common.rs          // 两引擎公共件:DecryptError、魔数定格式、同名去重、读满一块
  ncm.rs             // 网易云离线引擎(AES-ECB + RC4 变体 + meta/封面)
  qmc.rs             // QQ:QMC1 静态密钥 / QMC2 Map / QMC2 RC4 / tc_tea / 尾部形态 + 流密码
  qq_footer.rs       // musicex 尾部解析(纯,可单测)
  qq_credentials.rs  // 凭据:INI 解析(纯)+ 进程内存取 authst(平台胶水)
  qq_memscan.rs      // Windows 专用:ToolHelp 枚举进程 + VirtualQueryEx/ReadProcessMemory(只读)
  qq_ekey.rs         // GetEVkey 请求组装与响应解析(纯,可单测)
  qq_online.rs       // 编排:musicex → 凭据 → 取密钥 → 解密;probe_status()
  scan.rs            // 文件夹递归扫描 + 内容优先的平台路由
  commands.rs        // run / cancel / scan / qq_status(四条命令)

平台判定与密钥来源的分工:scan.rs 只决定"这文件归哪个引擎"; qmc.rs 决定"密钥从哪来"(内嵌 / 静态);只有尾部是 musicex 时, 调度层才把 KeyRequired 交给 qq_online.rs 转在线路径——这样离线路径保持零网络依赖。

mod.rs 挂到 music/mod.rs 的子模块列表;事件常量加进 constants.rs 音乐分组。

5.2 前端

src/modules/music/components/DecryptPanel.vue   // 页签内容
src/stores/decryptStore.ts                      // 任务列表 + 事件监听(照 musicUploadStore 范式)
MusicModule.vue                                 // tabs 加一项 + <TabsContent value="decrypt">
index.ts                                        // searchItems 加「音乐解密」(tab: 'decrypt')

P0 / P1a / P1c UI 形态(已实施):

  • 顶部操作行:选择文件夹 | 选择文件(dialog 多选,按 §4.3 全后缀过滤)| 就地解密开关 | 取消 / 清空记录
  • QQ 音乐在线解密状态卡:状态点(三态)+ 一句话状态 + QQ 号 + 重新检测 + 折叠的操作步骤; 未就绪时折叠区里就是 §4.3.1 那 6 条,并附一句"旧版文件与 .ncm 本来就不需要登录"
  • 输出目录行:就地模式下置灰并显示"与源文件同目录"
  • 文件夹扫描预览条:显示"找到 N 个 · 网易云 x · QQ音乐 y" + 开始解密按钮
  • 中部任务表:任务头(文件夹路径 / 进度条 / bytes_done/bytes_total / 打开产物目录)| 文件行(文件名 | 平台徽标 | 状态徽章 | 打开产物目录 | 打开封面 | 备注或失败原因)
  • 空态用 StateBlock variant="empty";进度条结构恒定(完成后保留满格,不整块消失)
  • 底部一行合规说明

5.3 数据流

与下载链路同构:前端 → music_decrypt_run → Rust 建 taskId 即回 → 后台执行 → music-decrypt-event → decryptStore 更新 → 列表刷新。页签切换组件卸载不影响任务(监听在 store)。


6. 关键实现细节与已知的坑

ncm(编号对应 §3.1 的条目号)

  1. aes 0.8 只有块原语、ecb crate 不在依赖树:ECB 手写 16 字节块循环(cipher::BlockDecrypt::decrypt_block)。不要为此引入 ecb crate。
  2. 两段 XOR 常量不同(0x64 key / 0x63 meta)。照抄成同一个常量 = 必然失败。
  3. PKCS#7 风格 padding:AES-ECB 收尾取最后一字节为 padding 长度(> 16 视作 0),不是“去前缀”。
  4. 改性 RC4 KSA 的 last_byte 累加(照抄参考实现即可,但别误解它): 式子 c = (swap + last_byte + key[key_offset]) & 0xff 在模 256 下恰好化简为标准 RC4, 实测两者密钥盒逐字节相同(256/256)。因此它不是"与标准 RC4 的关键差异", 也不能靠与标准 RC4 比对来验证实现——验证只能靠固定向量(见 §6.25)。 key_offset 触 keyLen 归零循环取 key 这一点照抄。
  5. 音频块之间不跳字节,0x8000 只是块大小;i 是块内下标。原文档的"每 0x8000 跳过 5 字节"是错的(那 5 字节在 §① 的头部里,且已单独处理)。但块边界必须由"读满一块"确定,不能用 Read::read 的短读结果(见 §6.24)。
  6. 输出扩展名看音频首帧魔数(ID3 → .mp3,否则 .flac),不看 meta 的 format。 实现比这条更宽一点:还识别 fLaC / OggS / RIFF..WAVE / ftyp / wvpk, 给 P1 的 QQ 产物复用(ncmdump 的兜底同为 flac)。
  7. meta 段是两层前缀:先剥 22 字节 163 key(Don't modify):,再 base64,再 AES,再剥 6 字节 music:。
  8. 流式处理:0x8000 块逐块读→解→写,禁止整文件读入内存(.mmp4 可能很大)。大文件下需按已处理字节数推 progress。
  9. 单测不依赖真实样本:真实 FLAC 最小样本进不了仓库。改为对中间产物断言——AES-ECB 往返、KSA 密钥盒已知值、padding 剥离、魔数→扩展名判定、以及"自造一个合法 ncm 容器(用同一套算法正向构造)再解回来"的往返测试。真机样本走手动自测。
  10. 魔数/解析失败走 per-file Err,不 panic、不中断整批。

QQ(P1)

  1. 第①层(QTag / V1)完全离线,不要因为"QQ 文件"就先去连客户端——先用尾部分支判形态再决定要不要读凭据。
  2. 第②层的 authst 只在 QQMusic.exe 运行期内存里,不落盘;uin 在 QQMusicServiceConfig.ini 可明文读。MEMORY_BASIC_INFORMATION 的 2 字节 PartitionId(Win10 1803+)必须包含,否则 state 会读成 protect、所有内存区被跳过。
  3. API 三处必须:filename 带 .mgg/.mflac 后缀、songtype = 1、module = music.vkey.GetEVkey(不是 GetVkey)。否则 104005 或 ekey 为空。
  4. authst 约 22.3 小时过期:失败文案要给"重新登录 QQ 音乐"的出口,而不是只报网络错误。
  5. 第③层(Frida):必须先启动 QQ 音乐再 attach,QQMusicCommon.dll 打开主界面即加载;导出符号是 mangled name,按子串 EncAndDesMediaFile 模糊匹配,严禁硬编码地址或 RVA;被杀软拦截只给排除指引,不做反检测动作;批量时客户端 UI 可能短暂卡顿,属预期。
  6. path_sensitive_mflac 变体(同名文件不同目录内容不同)P1 不处理:报错带全路径,遇到再迭代。
  7. .mmp4 产物容器未证实,P1 先用真机样本确认再定(见 §3.2 末)。

工程

  1. 新命令登记 3 处:music/mod.rs re-export、lib.rs 的 collect_commands![]、lib.rs 的 generate_handler![](见 §4.1)。
  2. music-decrypt-event 常量进 constants.rs 音乐分组;前端沿用硬编码字符串(与 musicStore.ts:419 一致)。
  3. 解密 store 必须独立于组件生命周期:Tabs 非 active 会卸载内容,事件监听挂 store 不挂组件。
  4. 输出同名去重 + 输入输出相交保护(见 §4.4)——原文档缺失,不做会静默覆盖用户文件。
  5. 三层路由后不再需要便携 Python 与 frida,music_decrypt_install_deps 命令取消;QQ 未登录的错误出口走状态卡提示。

实施中新增确认的坑(2026-09-27 实测)

  1. 事件字段名是 snake_case(不是 camelCase)。#[serde(tag = ..., rename_all = "kebab-case")] 只作用于 tag,变体字段名原样输出。前后端不一致时不报错,只表现为进度不动。 Rust 侧 event_json_contract 单测钉死 JSON 形状。
  2. 音频块边界必须用"读满一块"而非 Read::read 的返回值。BufReader::read 会短读, 块边界一漂移,解密式里的「块内偏移 i」就与加密侧错位,表现为文件从中间某处起全是噪声 (实测首个坏字节落在 32418,仍在第一大块内),前半段却完全正常,极难排查。 已加 read_full() 专门处理。
  3. last_byte 累加在模 256 下是恒等变形:c = swap + last_byte + key 与标准 RC4 的 j += s[i] + key 结果逐字节相同(已实测 256/256 一致)。所以:
    • 不能靠"与标准 RC4 比对"来验证密钥盒实现;
    • 也不要以为它是"改性 RC4 的关键差异"而据此改写(本计划早期的 §6.4 表述即由此误导)。 真正的验证手段是固定向量(key_box_matches_reference_vectors / keystream_matches_reference_vector)。
  4. MODIFY_KEY 是 16 字节而非 17(aes::Aes128 的密钥长度就是 16); CORE_KEY 的 17 字节是解密后要剥掉的前缀,与 AES 密钥不是同一个东西 (AES 密钥是它的前 16 字节)。两者混用不会编译报错,只会全解错。
  5. 合成容器单测的 key 段必须带 neteasecloudmusic 前缀——否则解密端剥前缀后拿到错种子。 这个坑一度被"单循环 KSA"的错误实现掩盖(两边同时错、往返仍然自洽)。

P1a(QQ 离线)实施中新增确认的坑

  1. QMC2 Map 密码的 scramble 必须用 wrapping_shl/shr(对移位量取模), 不能写成 u8::rotate_left/rotate_right——后者会在内部再取一次模,结果不同。 被 Apache 参考实现的原向量抓到(若不比对向量,会产出"能跑但全错"的解密)。
  2. tc_tea 不是 TEA-ECB,而是 TEA 变体 + 自定义 CBC:块与密钥字都是大端、 16 轮(非 32)、单轮是 ((v<<4)+k1) ^ (sum+v) ^ ((v>>5)+k2), 且明文前置 1+pad+2 字节头、尾部 7 字节 0 自校验。照 TEA-ECB 写会解出部分可读的乱码 (表现极具迷惑性:能看到明文碎片)。尾部 0 校验正是"密钥对不对"的权威判据。
  3. V1 尾部判定不能只看长度:任意加密数据末尾都可能凑出 0<n<=0x400, 只按长度判会把普通 QMC1 文件误判成 V1 并砍掉一大截音频(实测 32871 字节 → 4096)。 必须追加"前面那一段像不像 base64 ekey"的校验。
  4. sniff_tail 的 audio_len 必须换算成绝对长度:它只读了尾部 probe, detect_tail 给出的是相对 probe 起点的偏移;QMC1(无尾部)必须回落到整个文件大小。 另外不要在两个地方各写一遍尾部探测——当初 decrypt_file 自己复制了一遍, 修了 sniff_tail 却没修它,症状是"探测结果对、实际产物只有 4KB"。
  5. QMC1 的掩码分支是 pos > 0x7FFF(严格大于),不是 >=;写成 >= 会在回绕点差一字节。

P1c(musicex 在线)实施中新增确认的点

  1. MEMORY_BASIC_INFORMATION 的 PartitionId(Win10 1803+):直接沿用 windows-sys 的结构体即可,但自己手写 #[repr(C)] 时千万别漏——漏了会让 RegionSize/State/Protect 全部读错偏移,VirtualQueryEx 返回的 State 读成 Protect(如 0x04 而非 0x1000),于是所有内存区被跳过、永远扫不到 token。
  2. getEVkey 的三个"必须":filename 带扩展名、songtype=1、 module=music.vkey.GetEVkey(不是 GetVkey)。任一写错都只是"拿不到 ekey", 不会报错——所以请求体用纯函数组装并单测锁死(qq_ekey::build_evkey_request)。
  3. authst 会过期(约 22.3 小时):失败文案必须给"重新登录 / 重新检测"的出口, 否则用户会以为是网络问题。响应里的 expiration 已带进产物备注。
  4. 单元测试不要真的发网络请求:本机一旦登录成功,测试就会去连 QQ 服务器, 导致测试变慢变脆。改为验证"请求体能正确构造"+"#!Qk 头守卫"+"尾部能被解析出 media_mid/filename"三段——真实响应留给真机端到端。
  5. musicex 音频段要校验 #!Qk 头:尾部像 musicex 不代表内容真是 QMC2 密文; 没有这道守卫会把任意文件"解"成垃圾却报告成功。

真机端到端验证后修正(2026-09-27)

  1. #!Qk 不是 QMC2 密文的通用魔术(推翻第 37 条的做法):真机 musicex 样本 (Avicii - Heaven,197MB .mflac)的密文头是 51 74 03 75,按"必须以 #!Qk 开头"写的守卫会把完全合法的文件误拒。 正确做法是用解密结果判定密钥是否正确:用取到的密钥解出前 16 字节, 看是否是已知音频魔术(fLaC / OggS / ID3 / ftyp…)——密钥错时它是随机噪声, 几乎不可能凑巧命中;命中即说明密钥对、文件也对。 这也是"内容优先"原则的又一次应用:不要用猜测的密文特征做判据,要用能验证的结果。
  2. 文档给的 musicex 字段偏移在真样本上是对的:0x0C media_mid(60B UTF-16LE)、 0x48 filename(68B UTF-16LE)、0xC0 footer_size、0xC8 magic 全部命中, 尾部实测 192 字节、padding 区有 13 个非零字节(所以不能假设 padding 全 0)。
  3. 真机样本的规模提醒:.mflac 可达 197MB / 192kHz / 24bit。 qq_online 目前把音频段整段读入内存再解密(探针与生产路径都是), 在这个量级下可用,但如果将来遇到多 G 的文件,应改成分块解密 + 流式写盘 (qmc 的流密码本身已支持任意偏移)。

7. 分阶段计划

P0 — 网易云 + 解密页签全链路(约 2 天)✅ 已实施(2026-09-27)

  • useModuleTabs + TabsContent 接「解密」页签;index.ts 搜索条目
  • decrypt/ncm.rs:§3.1 全部要点 + 单测(18 项通过)
  • decrypt/mod.rs + commands.rs:run / cancel + 事件发射;三处登记;constants.rs 事件常量
  • decryptStore.ts + DecryptPanel.vue:选文件 → 批量任务 → 进度 → 打开输出目录
  • 输出同名去重 + 输入输出相交保护(§4.4)
  • 封面单独落盘(<歌名>.cover.png|jpg)——标签回填仍留 P2(lofty 需按容器分派)
  • 自测:真实 .ncm 样本解出(需人工用真机样本验证;仓库内样本有版权且体积大,故算法靠 §6.9 的中间产物单测 + 合成容器往返覆盖)
  • 验收:页签选 10 个 ncm 全部解出、失败有原因、切页签不丢任务、播放器直接可播

已交付文件:

文件 内容
src-tauri/src/music/decrypt/ncm.rs 网易云离线引擎(容器解析 / AES-ECB / 密钥盒 / 流式解密 / 魔数定格式 / 封面 / 同名去重)+ 单测
src-tauri/src/music/decrypt/mod.rs 任务表、工作线程 + 节流事件转发、DecryptEvent 契约(含 JSON 形状单测)
src-tauri/src/music/decrypt/commands.rs music_decrypt_run / music_decrypt_cancel + 输出目录解析与相交保护
src/stores/decryptStore.ts 任务状态 + 事件监听(挂 store,不随组件卸载)
src/modules/music/components/DecryptPanel.vue 页签 UI
music/mod.rs · lib.rs · constants.rs 子模块挂载、MusicManager.decrypt 字段、三处命令登记、事件常量

P1a — QQ 离线解密 + 文件夹批量(✅ 已实施,纯 Rust,无 Python/frida)

  • decrypt/qmc.rs:QMC1 静态密钥表 / QMC2 Map 密码 / QMC2 RC4 变体 / tc_tea(TEA 变体 + 自定义 CBC)
  • 第①层:QTag 与 V1 尾部 ekey 提取 → 离线解密
  • decrypt/scan.rs:递归扫描 + 内容优先的平台路由 + 保留相对目录结构
  • 文件夹批量:folder / root / in_place 三个参数 + music_decrypt_scan 预览命令
  • decrypt/common.rs:两引擎统一的错误类型、魔数定格式、同名去重、读满一块
  • 单测 56 项(模块合计 174 项全库通过),含参考实现的原始测试向量
  • 第②层 musicex + GetEVkey API(未实施,见 P1c)
  • 真实 .mflac/.mgg/.qmcflac 样本自测(需人工;仓库内不放版权样本)

已交付文件(P1a 增量):

文件 内容
src-tauri/src/music/decrypt/qmc.rs QMC 全套离线算法 + 尾部形态判定
src-tauri/src/music/decrypt/scan.rs 文件夹递归扫描与平台路由
src-tauri/src/music/decrypt/common.rs 两引擎公共件

算法来源(全部宽松许可,均有原始向量锁行为):

部分 来源 许可
QMC1 静态密钥表 + 掩码规则 jixunmoe/qmc-decode MIT
QMC2 密钥派生 / Map / RC4 / 尾部形态 bczhc/qmc-dec(qmc2-crypto) Apache-2.0
tc_tea tc_tea crate MIT/Apache-2.0

P1b — Frida 兜底(按需,不计入本轮)

  • qq_decrypt.py(include_str!):attach → EncAndDesMediaFile 调用序列 → 批量 → JSON-Lines 进度
  • decrypt/qq_frida.rs:前置检查、spawn、逐行读转发事件
  • 触发条件:仅当 §3.2 的第③层文件在真实用户场景中被确认存在且前两层无法覆盖时才做

P1c — musicex 联网取 ekey(✅ 已实施)

  • qq_footer.rs:musicex 尾部解析(song_id / media_mid / filename)
  • qq_credentials.rs:读 %APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini 的 uin + 扫进程内存取 authst
  • qq_memscan.rs(Windows):CreateToolhelp32Snapshot + OpenProcess + VirtualQueryEx + ReadProcessMemory(只读)
  • qq_ekey.rs:GetEVkey 请求组装与响应解析(filename 带扩展名 / songtype=1 / platform="27")
  • qq_online.rs:编排 + probe_status() 在线能力探测
  • music_decrypt_qq_status 命令 + UI 状态卡(含逐步操作说明)
  • windows-sys 增开 Win32_System_Diagnostics_ToolHelp 与 ..._Debug
  • 本机实测:probe_status() 返回 running=true logged_in=true uin=1154027699 ready=true —— 内存扫描确实取到了 authst
  • 端到端已用真机样本跑通(2026-09-27,见下)

真机端到端验证记录(首个 musicex 样本)

样本:C:\Users\Administrator\Music\Heaven - Avicii_EM.mflac(197,104,516 字节, 尾部 musicex\0,song_id=233102682,media_mid=003iTvi44A6RMs, filename=AIM0002ELI6a1wXJDo.mflac)

环节 实测结果
尾部解析 song_id / quality1=2 / quality2=11 / media_mid / filename 全部正确
凭据 返回 running=true logged_in=true uin=1154027699 ready=true
GetEVkey 成功,拿到 704 字符 ekey;expiration=80400(22.3 小时,与文档一致)
ekey → 密钥 解密出 512 字节原始密钥 → 命中 RC4 变体(>300 字节)分支
音频段 197,104,324 字节(= 文件大小 − 192 字节尾部,完全吻合)
解密结果 首帧 66 4c 61 43 = fLaC ✅
产物校验(lofty) 277.261 秒 · 192000 Hz · 24 bit · 2 声道 · 5686 kbps —— 192kHz/24bit Hi-Res 无损

验证方式:examples/decrypt_musicex_probe.rs 走真实链路(读内存凭据 → 真实 HTTP 请求 → 解密),再用 examples/verify_audio.rs 交给项目同款解析器确认产物合法。 两个 example 都保留,供后续 QQ 改协议时快速定位。

这次验证推翻了一个错误假设:样本的密文头是 51 74 03 75,不是文档里提到的 #!Qk。原先按"密文必须以 #!Qk 开头"写的守卫会把完全合法的文件误拒——已改为 用解密结果判定(解出的前 16 字节是否为已知音频魔术),见 §6.38。

凭据可用性已知限制:

维度 情况
uin 来源 INI 明文,稳定
authst 来源 仅运行期内存;QQ 音乐必须开着且已登录
有效期 约 22.3 小时(响应 expiration 字段,已带进产物备注)
权限 读他人进程内存可能需管理员;失败文案已提示
是否注入 否,纯只读——这是它与 Frida 兜底的本质区别

P2 — 按需增强(不进本轮)

  • ID3 / FLAC / MP4 标签回填(用 lofty,按容器分派;meta JSON 已在解密时解析出来)
  • 解密完成 →「加入本地曲库」/ 上传飞牛(复用 musicUploadStore)
  • 拖拽文件进页签、解密历史持久化
  • 酷狗 / 酷我(除非再次明确要求)
  • QQ 变体适配(path_sensitive_mflac)

变更:原计划把「封面提取 / ID3 标签回填」一起从 P2 提前到 P0。实际只提前了封面提取—— 封面字节在解析容器时顺手就读出来了,落盘是十几行,且不做就"能播但难用"。 标签回填仍留 P2:它需要 lofty 且要按 mp3/flac/m4a 分派容器,属于增强而非可用性门槛。


8. 风险与开放问题

风险 影响 对策
QQ 改 musicex 尾部/API 协议 第②层失效 协议字段集中在 qq_footer / qq_ekey 两处;错误文案带原始响应码;关注 qmc-decoder issue
authst 提取被安全软件拦截 第②层失效 只读内存、不注入;失败给"以管理员身份运行"出口
musicex 端到端 真实响应字段可能与文档不符 已验证通过(真机 197MB 样本,产物为合法 192kHz/24bit FLAC) 保留 examples/decrypt_musicex_probe.rs + verify_audio.rs,QQ 改协议时可快速定位
authst 过期(22.3h) 第②层短期失效 错误文案给"重新登录/重新检测"出口;有效期带进产物备注
QQ 版本升级改 mangled 导出符号 仅第③层(Frida)失效 子串模糊匹配;第③层不在实施范围,影响面已缩小
真实样本不足导致算法细节偏差 解出错文件 已用参考实现的原始测试向量交叉验证(QMC1 掩码 / Map / RC4 / tc_tea / ekey 端到端)
GPLv3 边界被无意破坏 许可风险 三档口径见 §3.3;QMC 只取 MIT / Apache-2.0 两份来源的代码与数据
网易云改 ncm 格式 个别文件失败 per-file error 不中断整批
同名文件落盘互相覆盖 用户文件丢失 §4.4 同名去重 + 相交保护
文件夹扫描漏文件(内容认不出) 用户以为解完了 UI 先出 music_decrypt_scan 预览数量

开放问题:

  1. 解密输出默认就地(文件夹批量)或 savedir/decrypted/(散选);独立设置项留 P2。
  2. QQ 未运行时是否自动拉起?离线层与 .ncm 完全不需要客户端;只有 musicex 需要, 当前选择"只提示、不自动拉"(客户端要登录,自动拉起也解决不了登录态)。
  3. .mmp4 的产物容器(m4a / mp4)待真机样本确认——当前靠首帧 ftyp 魔数判定,认不出时按后缀落 m4a。 (.mflac 已实测确认:产物为 192kHz/24bit 的 .flac。)
  4. musicex 端到端未验证 已解决(2026-09-27,真机样本跑通,见 P1c 的验证记录)。
  5. .mflac0 / .mgg1 等变体按 QMC2 处理,但未用真实样本验证过其尾部形态与 .mflac / .mgg 一致。
  6. 微信登录的 QQ 音乐 (tmeLoginType=3):实现上 authst 与 QQ 登录通用, 但 login_type 目前固定发 1(QQ 登录实测可用)——若真机发现微信登录取不到 ekey,需按凭据来源推断。
  7. 大文件内存占用:qq_online 目前整段读入内存解密;197MB 实测可用, 但 .mflac 可以更大。若遇到多 G 文件,应改流式(qmc 的流密码已支持任意偏移)。

附录 A:参考项目对照(只取思路)

A.1 QKKDecrypt 实测结论(2026-09-27 深读 main@938b22d,来自其源码而非猜测)

最重要的一条:该项目 QQ 路径完全不解析 QMC 加密格式——它把原始加密文件整包交给 QQ 自己的 DLL 解密,因此不受 static/map cipher 变体影响。代价是强依赖四项:QQ 客户端运行 + QQMusicCommon.dll 已加载 + 管理员权限(cli.py::_require_admin(),非管理员直接 return 2 并打印"已禁止继续使用")+ mangled 名/编译器版本不变。这四项与它的"回退"一起,正是我们改走 §3.2 分层路由的原因。

QKKDecrypt 文件 可借鉴 不可借鉴
platforms/qq/adapter.py SUPPORTED_SUFFIXES 仅 .mflac/.mgg/.mmp4;前置检查项;ASCII 暂存
qq/runtime/qqmusic_decrypt.py EncAndDesMediaFile 的 3 组候选 mangled 名、NativeFunction 全 thiscall 签名、调用序(Memory.alloc(0x28) → ctor → allocUtf16String → Open(..,1,0) → GetSize → Read → dtor) 硬编码;整文件读入内存;未校验 Open/Read 返回值
qq/runtime/frida_decrypt_gateway.py 进程查找用子串匹配 "qqmusic";每批次只 attach 一次并缓存 session 无 session 重连(QQ 中途重启即失效)
qq/variant_adapter.py "路径敏感型 mflac"→解密前先复制到纯 ASCII 路径(pick_safe_tmp_dir:盘根 _qqmusic_tmp → 项目根 → tempfile.gettempdir()) 只实装了这一个变体
qq/internal_direct.py / qq/export_fallback.py — 存在但未接入主流程 = 死代码,不可当作可用的回退能力承诺
platforms/netease/adapter.py 输出扩展白名单法 它没有自研 ncm 算法——直接 from ncmdump import NeteaseCloudMusicFile 委托 PyPI 的 ncmdump-py;且 predicted_extension() 会多解密一遍(性能坑)
Application/decrypt_service.py 事件粒度 = 逐文件 index/total;file_finished.result ∈ success/failed/already_decrypted 事件种类过多(20+)
cover_art_service.py "本地同名图 → 缓存 → 联网"的 local-first 顺序 给网易云产物做封面兜底时查的是 QQ 音乐 API
THIRD_PARTY_LICENSES.md 合规口径与风险表述 内置 FFmpeg 为 --enable-gpl --enable-version3 构建 → 传染面比"仓库 GPLv3"更大

对本文档的两处直接修正:

  1. "输出扩展名看音频首帧魔数"得到双重印证——QKKDecrypt 的最终扩展名同样不取映射表,而是 detect_audio_container() 从实际字节判定(fLaC/OggS/RIFF..WAVE/ID3/0xFF 0xFB|0xF3|0xF2/偏移 4 处 ftyp)。故 §3.2 的输出扩展名表仅作声明/预期用,实际以魔数为准。
  2. .mgg 解出后它强制归一为 .m4a(normalize_target_format 把 ogg→m4a)。本项目不跟这个行为——Cargo.toml:112 已确认 symphonia 默认特性含 ogg/vorbis,直接落 .ogg 即可播,保持"所见即所得"(§3.1 原口径)。
  3. QKKDecrypt 不支持 .mflac0/.mgg1/.mflac1/.qmc*——我们的扩展面比它宽(§4.3),但格式知识来源是 qmc-decoder 的文档(GPLv3,不抄代码)。

A.2 借鉴到 P0 的一条设计(最终未采用,附理由)

QKKDecrypt 的 file_finished.result 含 already_decrypted 与 stopped_by_user 两个态。 stopped_by_user 已采纳(取消后 finished.cancelled > 0,任务落为"已取消")。 already_decrypted 决定不做:它要判断"某份已存在的产物是否就是本次输入的产物", 在扁平输出目录里只能靠文件名猜,猜错就静默跳过用户的文件——代价大于收益。 P0 改为永不跳过:目标名被占用就写 <名>_1.<ext>,宁可多一份产物也不丢工作。 (ncm::unique_output 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)