Files
word-market/importer/README.md
T
voidandClaude Sonnet 4.6 131c2b6353 docs(importer): 补充导出流程、数据模型与 ZPK 内容分析
- README:三步流程、接口与下载地址、破解参数、日常命令与性能说明
- DATA-MODEL:词书/词条及关联数据的实体关系
- zpk-decrypted-content-analysis:ZPK 解密后的字段结构分析

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-08 21:16:04 +08:00

296 lines
9.8 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.
# Lexis Export Toolkit
> 本目录是 `word-market` monorepo 的 `importer` 子项目。以下命令均在 `importer/` 目录下执行。
这个目录是“不背单词 / Lexis”离线导出工具包。整个流程三步,每步产出都是可读明文:
1. 下载词书目录(游客态接口,产出可读 JSON)
2. 逐个下载所有词书,解密并导出单词(产出可读 SQLite / CSV)
3. 逐个下载所有词书所有单词的 ZPK,并解密为 JSONL(产出可读 JSONL)
解密逻辑抽成独立工具(`decrypt-sqlcipher2-db.py`、`decrypt-zpk-aes.py`),可单独调用,也被步骤 2/3 复用。
## 环境
- Windows + PowerShell
- Python 3.10+
- Python 依赖:`pycryptodome`
- 不依赖 `adb`:主流程已完全走游客态 HTTP 接口与静态 CDN,不再从设备拉取数据
- 可选:`bin\jadx-1.5.6`,只在复核 APK / `libcommon.so` 常量时需要
安装依赖:
```powershell
pip install pycryptodome
```
## 目录
```text
README.md
run.py # 一键逐个执行三步流程
src\
fetch-book-catalog.py # 步骤1:从服务端拉取词书目录(游客态接口)
download-wordbooks.py # 步骤2:逐个下载词书、解密并导出单词与 zpk 字段
download-zpk.py # 步骤3:从词表去重后逐个下载所有 ZPK 并解密为 JSONL
decrypt-sqlcipher2-db.py # 独立工具:离线解密单个 SQLCipher2 词书 DB(可单独调用)
decrypt-zpk-aes.py # 独立工具:离线解密 ZPK 为 JSONL(可单独调用)
archive\ # 已归档:旧版分步工具(download-all-wordbooks.py、download-all-zpk.py、export-wordbook-words.py、export-word-zpk-index.py 等)
output\ # 统一输出目录(三步流程的所有产物)
book-catalog.json # 步骤1 产出(可读)
book-catalog-full.json # 步骤1 产出(可读)
databases\ # 步骤2 原始加密 DB(中间缓存,非最终产出)
decrypted-databases\ # 步骤2 解密后 DB(可读)
wordbook-words\ # 步骤2 每本词书单词 CSV(可读)
all-wordbook-words.csv # 步骤2 全量词表(可读,步骤3 输入)
unique-zpk-index.csv # 步骤3 去重 ZPK 索引(可读)
zpk-cache\0\ # 步骤3 加密 ZPK(中间缓存,非最终产出)
zpk-jsonl\ # 步骤3 解密后 JSONL(可读)
wordbook-download-report.csv # 步骤2 下载报告
wordbook-word-summary.csv # 步骤2 导出报告
zpk-download-report.csv # 步骤3 下载/解密报告
bin\
is_cool_lexis_5_11_1_1787132405511.apk
jadx-1.5.6\
```
## 关键路径
- 原始 APK:`bin\is_cool_lexis_5_11_1_1787132405511.apk`
- 词书目录:`output\book-catalog.json`(精简字段,可读)
- 词书目录全量:`output\book-catalog-full.json`(接口原始 tabs/books)
- 原始词书 DB:`output\databases\LangEasyLexisV3_<CODE>.db`(中间缓存)
- 解密后词书 DB:`output\decrypted-databases\LangEasyLexisV3_<CODE>.sqlite`(可读)
- 全量词表:`output\all-wordbook-words.csv`(可读)
- 唯一 ZPK 索引:`output\unique-zpk-index.csv`(可读)
- ZPK 缓存:`output\zpk-cache\0\*.zpk`(中间缓存)
- ZPK 解密输出:`output\zpk-jsonl\zpk-decrypted.jsonl`(可读)
- 下载报告:`output\wordbook-download-report.csv`、`output\zpk-download-report.csv`
## 完整流程
整个流程三步:下载词书目录 -> 逐个下载所有词书 -> 逐个下载所有词书所有单词的 ZPK。
一键顺序执行三步(任一步失败即停):
```powershell
python run.py
```
也可单独执行每一步(以下是三个步骤的命令):
步骤1:拉取词书目录(游客接口,无需登录/设备):
```powershell
python src\fetch-book-catalog.py
```
步骤2:逐个下载所有词书(下载 zip -> 校验 MD5 -> 解包 -> 解密 DB -> 导出单词与 zpk 字段):
```powershell
python src\download-wordbooks.py --workers 16
```
步骤3:从全量词表去重后逐个下载所有 ZPK,并解密为 JSONL(断点续传):
```powershell
python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000
```
离线解密已下载的 ZPK(独立工具,可单独调用,非必要):
```powershell
python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl
```
## 词书列表接口
词书目录不再依赖设备偏好文件,直接走游客态接口拉取:
```text
GET https://api.beingfine.cn/v3/3/bb/wordbooks/for-guest/{timestamp}
```
请求参数(query):
```text
type=3/bb/wordbooks/for-guest
app_id=600000001
udid=<任意,可为空>
umid=<任意,可为空>
version=5.11.1
user_id=0
channel=isCool
timestamp={当前毫秒时间戳}
timezone=480
pad=0
token=tk85bf4d7d70a4d5028187ba6dfb3649
```
请求头:
```text
Referer: https://app.bbdc.cn
User-Agent: LangEasyLexis/5.11.1
```
响应为明文 JSON,`result_code=200`,`data_body` 是字符串形式的 JSON,
包含 `tabs`(分类)、`books`(全部词书,约 1000 本)、`last_update_time`。
该接口不校验 `sign`、`udid`、`umid`,无需逆向签名算法。
实现位置:`src\fetch-book-catalog.py`。
## 词书 DB 破解信息
词书 DB 是 SQLCipher2 风格分页加密:
- key:`arsenal iscool`
- page size:`1024`
- reserve:`48`
- KDF:`PBKDF2-HMAC-SHA1`
- iterations:`4000`
- 每页 IV:页面尾部 reserve 区前 16 字节
实现位置:`src\decrypt-sqlcipher2-db.py`(独立工具,`download-wordbooks.py` 会导入复用)。
`src\archive\derive-lexis-db-keys.py`(已归档,日常流程不需要)用来复核 `libcommon.so` 中 `getDBKey()` 的常量派生。它默认读取 APK 反编译资源里的:
```text
jadx-out\resources\lib\x86\libcommon.so
```
如果以后要复核 key 派生,先用 `bin\jadx-1.5.6` 重新反编译 `bin\is_cool_lexis_5_11_1_1787132405511.apk` 生成 `jadx-out`。
## 词书下载
词书 DB zip 走静态 CDN:
```text
{cdn_base}/dicts/v3/{code}/{version}/LangEasyLexisV3_{code}.db.zip
```
可用 CDN:
```text
http://static.beingfine.cn
https://hwstatic.beingfine.cn
https://ccastatic.beingfine.cn
```
请求头:
```text
Referer: https://app.bbdc.cn
User-Agent: LangEasyLexis/5.11.1
```
下载工具会校验 `Content-MD5`,并自动 fallback 到下一个 CDN。
## ZPK 下载
ZPK 文件走静态 CDN:
```text
{cdn_base}/r/{zpkName}.zpk
```
`zpkName` 来自词书数据库的 `zpk` 字段,格式:
```text
{bid}_{word_id}_{version}_{updated_unix}
```
下载工具同样支持断点续传、`Content-MD5` 校验和 CDN fallback。
## ZPK 解密算法
`.zpk` 是 protobuf field 1 包住的 AES 密文:
```text
.zpk
-> protobuf field 1 bytes: AES-256-CBC ciphertext
-> key = md5(word).hexdigest().encode("ascii")
-> iv = b"IscoolInitVector"
-> PKCS7/PKCS5 unpad
-> protobuf field 1 bytes: UTF-8 JSON
```
Python 等价实现:
```python
import hashlib
from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad
key = hashlib.md5(word.encode("utf-8")).hexdigest().encode("ascii")
iv = b"IscoolInitVector"
plaintext = AES.new(key, AES.MODE_CBC, iv).decrypt(ciphertext)
plaintext = unpad(plaintext, 16)
```
实现位置:`src\decrypt-zpk-aes.py`。
## 日常命令
继续下载缺失 ZPK(已下载的自动跳过,已解密的自动跳过下载与解密):
```powershell
python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000
```
重新离线解密已下载的 ZPK(覆盖写):
```powershell
python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl
```
重新导出词表(下载已存在则跳过,只重跑解密与导出):
```powershell
python src\download-wordbooks.py --workers 16
```
单独解密一个词书 DB(独立工具):
```powershell
python src\decrypt-sqlcipher2-db.py output\databases\LangEasyLexisV3_<CODE>.db output\decrypted-databases\LangEasyLexisV3_<CODE>.sqlite
```
`download-zpk.py` 每次运行都会从 `all-wordbook-words.csv` 重建 `unique-zpk-index.csv`,无需单独生成索引。
## 当前状态
- 三步流程输出统一到 `output\`,每步产出都是可读明文;加密产物(`databases\`、`zpk-cache\0\`)仅作为断点续传的中间缓存。
- 完整跑完:`output\unique-zpk-index.csv` 约 115104 个唯一 ZPK 名,`output\zpk-jsonl\zpk-decrypted.jsonl` 是最终可读解密产物。
- 旧的动态调试、native trace、内存采样脚本已清理;当前 ZPK 正文算法不依赖真机调试。
## 下载性能与中断
`src\download-zpk.py` 已改成长连接 worker 池:
- 默认并发:`64`
- 推荐并发:`64` 到 `96`;如果本机网络和 CDN 都稳,可以试 `128`
- 推荐请求超时:`--timeout 6`
- 每个 worker 会复用到 CDN 的 HTTP keep-alive 连接,避免每个小 ZPK 都重新握手
- 默认 `--cdn-mode primary` 会优先使用 HTTP 主 CDN;如果主 CDN 被限速,可以试 `--cdn-mode spread`
- 任务队列只保留少量待下载项,内存占用稳定,`Ctrl+C` 后不会等待海量 Future 收尾
- 按 `Ctrl+C` 会停止继续投递任务,写出部分报告,并以退出码 `130` 结束
如果 `Ctrl+C` 后仍短暂卡住,是正在执行的少量 HTTP 请求还在等待 socket 超时;把 `--timeout` 降到 `3` 到 `5` 可以更快退出:
```powershell
python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000
```
如果主 CDN 明显限速,可以分散到 3 个 CDN 试一次:
```powershell
python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000 --cdn-mode spread
```
冒烟测试不要覆盖正式报告时可以单独指定报告路径:
```powershell
python src\download-zpk.py --limit 20 --out-dir output\zpk-cache-test\0 --jsonl output\zpk-jsonl-test\zpk-decrypted.jsonl --report output\zpk-download-smoke-report.csv
```