# 音乐模块 · 本地音乐解密规划(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`(规划文档范式) > 参考项目与**许可分档**: > - `taurusxin/ncmdump`(,**MIT**)——§3.1 全部算法细节的对照物,**可逐行对照**。 > - `QQKWKG-TriMusicDecrypt`(QKKDecrypt,,**GPLv3**)——只取平台矩阵与坑清单。 > - `ownlight6/qmc-decoder`(,**GPLv3**)——只取 QMC/musicex/ekey 的**格式与协议知识**()。 > - GPLv3 两仓:**只读文档与行为,严禁抄代码**。 --- ## 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 兜底,按需)另计。 ```mermaid flowchart LR subgraph FE["前端 · 解密页签"] A["DecryptPanel.vue
文件选择 / 任务列表 / 状态卡"] S["decryptStore.ts
任务状态 + 事件监听"] end subgraph R["Rust · music/decrypt/"] C["commands.rs
run / cancel"] N["ncm.rs
网易云离线引擎"] Q["qq.rs
QMC 三层路由(P1)"] end subgraph QQS["QQ 三层(P1)"] L1["① 尾部内嵌 ekey
纯离线"] L2["② musicex → 本机凭据
GetEVkey API"] L3["③ Frida 兜底
(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 命令 ```rust // 任务 music_decrypt_run(task_id, files?, folder?, root?, out_dir?, in_place?) -> Result<(), String> music_decrypt_cancel(task_id: String) -> Result // 预览与状态 music_decrypt_scan(folder: String, root: Option) -> Result music_decrypt_qq_status() -> Result // 只读本机,不发网络请求 ``` `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` 音乐分组) ```typescript 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>)、工作线程 + 节流事件转发、事件契约 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 加一项 + 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)** 11. 第①层(QTag / V1)**完全离线**,不要因为"QQ 文件"就先去连客户端——先用尾部分支判形态再决定要不要读凭据。 12. 第②层的 `authst` **只在 `QQMusic.exe` 运行期内存里**,不落盘;`uin` 在 `QQMusicServiceConfig.ini` 可明文读。`MEMORY_BASIC_INFORMATION` 的 2 字节 `PartitionId`(Win10 1803+)**必须包含**,否则 `state` 会读成 `protect`、所有内存区被跳过。 13. API 三处必须:`filename` 带 `.mgg`/`.mflac` 后缀、`songtype = 1`、`module = music.vkey.GetEVkey`(不是 `GetVkey`)。否则 `104005` 或 ekey 为空。 14. `authst` 约 22.3 小时过期:失败文案要给"重新登录 QQ 音乐"的出口,而不是只报网络错误。 15. 第③层(Frida):必须**先启动 QQ 音乐**再 attach,`QQMusicCommon.dll` 打开主界面即加载;导出符号是 mangled name,**按子串 `EncAndDesMediaFile` 模糊匹配,严禁硬编码地址或 RVA**;被杀软拦截只给排除指引,**不做反检测动作**;批量时客户端 UI 可能短暂卡顿,属预期。 16. `path_sensitive_mflac` 变体(同名文件不同目录内容不同)P1 不处理:报错带全路径,遇到再迭代。 17. `.mmp4` 产物容器未证实,P1 先用真机样本确认再定(见 §3.2 末)。 **工程** 18. 新命令登记 **3 处**:`music/mod.rs` re-export、`lib.rs` 的 `collect_commands![]`、`lib.rs` 的 `generate_handler![]`(见 §4.1)。 19. `music-decrypt-event` 常量进 `constants.rs` 音乐分组;前端沿用硬编码字符串(与 `musicStore.ts:419` 一致)。 20. 解密 store 必须独立于组件生命周期:Tabs 非 active 会卸载内容,事件监听挂 store 不挂组件。 21. **输出同名去重 + 输入输出相交保护**(见 §4.4)——原文档缺失,不做会静默覆盖用户文件。 22. 三层路由后**不再需要便携 Python 与 frida**,`music_decrypt_install_deps` 命令取消;QQ 未登录的错误出口走状态卡提示。 **实施中新增确认的坑(2026-09-27 实测)** 23. **事件字段名是 snake_case**(不是 camelCase)。`#[serde(tag = ..., rename_all = "kebab-case")]` 只作用于 tag,变体字段名原样输出。前后端不一致时**不报错**,只表现为进度不动。 Rust 侧 `event_json_contract` 单测钉死 JSON 形状。 24. **音频块边界必须用"读满一块"而非 `Read::read` 的返回值**。`BufReader::read` 会短读, 块边界一漂移,解密式里的「块内偏移 `i`」就与加密侧错位,表现为**文件从中间某处起全是噪声** (实测首个坏字节落在 32418,仍在第一大块内),前半段却完全正常,极难排查。 已加 `read_full()` 专门处理。 25. **`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`)。 26. **`MODIFY_KEY` 是 16 字节而非 17**(`aes::Aes128` 的密钥长度就是 16); `CORE_KEY` 的 17 字节是**解密后要剥掉的前缀**,与 AES 密钥不是同一个东西 (AES 密钥是它的前 16 字节)。两者混用不会编译报错,只会全解错。 27. **合成容器单测的 key 段必须带 `neteasecloudmusic` 前缀**——否则解密端剥前缀后拿到错种子。 这个坑一度被"单循环 KSA"的错误实现掩盖(两边同时错、往返仍然自洽)。 **P1a(QQ 离线)实施中新增确认的坑** 28. **QMC2 Map 密码的 `scramble` 必须用 `wrapping_shl/shr`**(对移位量取模), 不能写成 `u8::rotate_left/rotate_right`——后者会在内部再取一次模,结果**不同**。 被 Apache 参考实现的原向量抓到(若不比对向量,会产出"能跑但全错"的解密)。 29. **tc_tea 不是 TEA-ECB,而是 TEA 变体 + 自定义 CBC**:块与密钥字都是**大端**、 16 轮(非 32)、单轮是 `((v<<4)+k1) ^ (sum+v) ^ ((v>>5)+k2)`, 且明文前置 `1+pad+2` 字节头、尾部 7 字节 0 自校验。照 TEA-ECB 写会解出**部分可读的乱码** (表现极具迷惑性:能看到明文碎片)。尾部 0 校验正是"密钥对不对"的权威判据。 30. **V1 尾部判定不能只看长度**:任意加密数据末尾都可能凑出 `0 0x7FFF`(严格大于)**,不是 `>=`;写成 `>=` 会在回绕点差一字节。 **P1c(musicex 在线)实施中新增确认的点** 33. **`MEMORY_BASIC_INFORMATION` 的 `PartitionId`(Win10 1803+)**:直接沿用 `windows-sys` 的结构体即可,但**自己手写 `#[repr(C)]` 时千万别漏**——漏了会让 `RegionSize`/`State`/`Protect` 全部读错偏移,`VirtualQueryEx` 返回的 `State` 读成 `Protect`(如 `0x04` 而非 `0x1000`),于是所有内存区被跳过、永远扫不到 token。 34. **`getEVkey` 的三个"必须"**:`filename` 带扩展名、`songtype=1`、 `module=music.vkey.GetEVkey`(不是 `GetVkey`)。任一写错都只是"拿不到 ekey", 不会报错——所以请求体用纯函数组装并单测锁死(`qq_ekey::build_evkey_request`)。 35. **`authst` 会过期(约 22.3 小时)**:失败文案必须给"重新登录 / 重新检测"的出口, 否则用户会以为是网络问题。响应里的 `expiration` 已带进产物备注。 36. **单元测试不要真的发网络请求**:本机一旦登录成功,测试就会去连 QQ 服务器, 导致测试变慢变脆。改为验证"请求体能正确构造"+"`#!Qk` 头守卫"+"尾部能被解析出 `media_mid`/`filename`"三段——真实响应留给真机端到端。 37. **musicex 音频段要校验 `#!Qk` 头**:尾部像 musicex 不代表内容真是 QMC2 密文; 没有这道守卫会把任意文件"解"成垃圾却报告成功。 **真机端到端验证后修正(2026-09-27)** 38. **`#!Qk` 不是 QMC2 密文的通用魔术**(推翻第 37 条的做法):真机 musicex 样本 (Avicii - Heaven,197MB `.mflac`)的密文头是 **`51 74 03 75`**,按"必须以 `#!Qk` 开头"写的守卫会把**完全合法的文件误拒**。 正确做法是**用解密结果判定密钥是否正确**:用取到的密钥解出前 16 字节, 看是否是已知音频魔术(`fLaC` / `OggS` / `ID3` / `ftyp`…)——密钥错时它是随机噪声, 几乎不可能凑巧命中;命中即说明密钥对、文件也对。 这也是"内容优先"原则的又一次应用:**不要用猜测的密文特征做判据,要用能验证的结果。** 39. **文档给的 musicex 字段偏移在真样本上是对的**:`0x0C` media_mid(60B UTF-16LE)、 `0x48` filename(68B UTF-16LE)、`0xC0` footer_size、`0xC8` magic 全部命中, 尾部实测 192 字节、padding 区有 13 个非零字节(所以不能假设 padding 全 0)。 40. **真机样本的规模提醒**:`.mflac` 可达 197MB / 192kHz / 24bit。 `qq_online` 目前把音频段整段读入内存再解密(探针与生产路径都是), 在这个量级下可用,但如果将来遇到多 G 的文件,应改成分块解密 + 流式写盘 (`qmc` 的流密码本身已支持任意偏移)。 --- ## 7. 分阶段计划 ### P0 — 网易云 + 解密页签全链路(约 2 天)**✅ 已实施(2026-09-27)** - [x] `useModuleTabs` + `TabsContent` 接「解密」页签;`index.ts` 搜索条目 - [x] `decrypt/ncm.rs`:§3.1 全部要点 + 单测(**18 项通过**) - [x] `decrypt/mod.rs` + `commands.rs`:run / cancel + 事件发射;**三处**登记;`constants.rs` 事件常量 - [x] `decryptStore.ts` + `DecryptPanel.vue`:选文件 → 批量任务 → 进度 → 打开输出目录 - [x] 输出同名去重 + 输入输出相交保护(§4.4) - [x] 封面单独落盘(`<歌名>.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**) - [x] `decrypt/qmc.rs`:QMC1 静态密钥表 / QMC2 Map 密码 / QMC2 RC4 变体 / tc_tea(TEA 变体 + 自定义 CBC) - [x] 第①层:QTag 与 V1 尾部 ekey 提取 → **离线解密** - [x] `decrypt/scan.rs`:递归扫描 + 内容优先的平台路由 + 保留相对目录结构 - [x] **文件夹批量**:`folder` / `root` / `in_place` 三个参数 + `music_decrypt_scan` 预览命令 - [x] `decrypt/common.rs`:两引擎统一的错误类型、魔数定格式、同名去重、读满一块 - [x] 单测 **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(**✅ 已实施**) - [x] `qq_footer.rs`:musicex 尾部解析(song_id / media_mid / filename) - [x] `qq_credentials.rs`:读 `%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini` 的 `uin` + 扫进程内存取 `authst` - [x] `qq_memscan.rs`(Windows):`CreateToolhelp32Snapshot` + `OpenProcess` + `VirtualQueryEx` + `ReadProcessMemory`(**只读**) - [x] `qq_ekey.rs`:`GetEVkey` 请求组装与响应解析(`filename` 带扩展名 / `songtype=1` / `platform="27"`) - [x] `qq_online.rs`:编排 + `probe_status()` 在线能力探测 - [x] `music_decrypt_qq_status` 命令 + UI 状态卡(含**逐步操作说明**) - [x] `windows-sys` 增开 `Win32_System_Diagnostics_ToolHelp` 与 `..._Debug` - [x] **本机实测**:`probe_status()` 返回 `running=true logged_in=true uin=1154027699 ready=true` —— 内存扫描确实取到了 `authst` - [x] **端到端已用真机样本跑通**(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.`,宁可多一份产物也不丢工作。 (`ncm::unique_output` 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)