Files
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

9.8 KiB
Raw Permalink Blame History

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 常量时需要

安装依赖:

pip install pycryptodome

目录

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。

一键顺序执行三步(任一步失败即停):

python run.py

也可单独执行每一步(以下是三个步骤的命令):

步骤1:拉取词书目录(游客接口,无需登录/设备):

python src\fetch-book-catalog.py

步骤2:逐个下载所有词书(下载 zip -> 校验 MD5 -> 解包 -> 解密 DB -> 导出单词与 zpk 字段):

python src\download-wordbooks.py --workers 16

步骤3:从全量词表去重后逐个下载所有 ZPK,并解密为 JSONL(断点续传):

python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000

离线解密已下载的 ZPK(独立工具,可单独调用,非必要):

python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl

词书列表接口

词书目录不再依赖设备偏好文件,直接走游客态接口拉取:

GET https://api.beingfine.cn/v3/3/bb/wordbooks/for-guest/{timestamp}

请求参数(query):

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

请求头:

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 反编译资源里的:

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:

{cdn_base}/dicts/v3/{code}/{version}/LangEasyLexisV3_{code}.db.zip

可用 CDN:

http://static.beingfine.cn
https://hwstatic.beingfine.cn
https://ccastatic.beingfine.cn

请求头:

Referer: https://app.bbdc.cn
User-Agent: LangEasyLexis/5.11.1

下载工具会校验 Content-MD5,并自动 fallback 到下一个 CDN。

ZPK 下载

ZPK 文件走静态 CDN:

{cdn_base}/r/{zpkName}.zpk

zpkName 来自词书数据库的 zpk 字段,格式:

{bid}_{word_id}_{version}_{updated_unix}

下载工具同样支持断点续传、Content-MD5 校验和 CDN fallback。

ZPK 解密算法

.zpk 是 protobuf field 1 包住的 AES 密文:

.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 等价实现:

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(已下载的自动跳过,已解密的自动跳过下载与解密):

python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000

重新离线解密已下载的 ZPK(覆盖写):

python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl

重新导出词表(下载已存在则跳过,只重跑解密与导出):

python src\download-wordbooks.py --workers 16

单独解密一个词书 DB(独立工具):

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 可以更快退出:

python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000

如果主 CDN 明显限速,可以分散到 3 个 CDN 试一次:

python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000 --cdn-mode spread

冒烟测试不要覆盖正式报告时可以单独指定报告路径:

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