Files
Thing/doc/MUSIC_DECRYPT_PLAN.md
T

668 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 音乐模块 · 本地音乐解密规划(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`(<https://github.com/taurusxin/ncmdump>,**MIT**)——§3.1 全部算法细节的对照物,**可逐行对照**。
> - `QQKWKG-TriMusicDecrypt`(QKKDecrypt,<https://github.com/Acooldog/QQKWKG-TriMusicDecrypt>,**GPLv3**)——只取平台矩阵与坑清单。
> - `ownlight6/qmc-decoder`(<https://github.com/ownlight6/qmc-decoder>,**GPLv3**)——只取 QMC/musicex/ekey 的**格式与协议知识**(<https://github.com/ownlight6/qmc-decoder/blob/main/MGG_DECRYPTION_FLOW.md>)。
> - 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<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 命令
```rust
// 任务
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` 音乐分组)
```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<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)**
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<n<=0x400`,
只按长度判会把普通 QMC1 文件误判成 V1 并砍掉一大截音频(实测 32871 字节 → 4096)。
必须追加"前面那一段像不像 base64 ekey"的校验。
31. **`sniff_tail` 的 `audio_len` 必须换算成绝对长度**:它只读了尾部 probe,
`detect_tail` 给出的是**相对 probe 起点**的偏移;QMC1(无尾部)必须回落到**整个文件大小**。
另外**不要在两个地方各写一遍尾部探测**——当初 `decrypt_file` 自己复制了一遍,
修了 `sniff_tail` 却没修它,症状是"探测结果对、实际产物只有 4KB"。
32. **QMC1 的掩码分支是 `pos > 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.<ext>`,宁可多一份产物也不丢工作。
(`ncm::unique_output` 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)