Files
word-market/importer/docs/zpk-decrypted-content-analysis.md
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

5.0 KiB

ZPK 解密内容分析报告

1. 报告范围

本报告分析 output/zpk/decrypted/ 下的 ZPK 解密结果,分析对象为每个 ZPK 对应的独立 JSON 文件。

分析时间:2026-09-03

2. 产物概况

项目 结果
解密文件数量 139,296 个
文件总大小 2,380,901,642 字节,约 2.22 GiB
文件格式 UTF-8 JSON
文件组织 一个原始 .zpk 对应一个解密 .json
聚合情况 不使用 JSONL 或汇总文件

文件名保持基础名称一致,仅扩展名不同:

zpk/original/0_100001_35_1689360732.zpk
zpk/decrypted/0_100001_35_1689360732.json

3. 顶层字段

根据解密样本,JSON 顶层包含以下业务字段:

字段 类型 内容
meta object 词条元数据,如考试分类、数据版本
word string 英文单词或词组
us_pron string 美式音标
uk_pron string 英式音标
spell array 拼写或词形相关数据
confuse array 易混淆词列表
confuse_exps array 易混淆词对应的解释
interpret string 词条释义文本
phrase array 短语数据,包含短语、类型和序号信息
example string JSON 编码的例句数据
zpk string ZPK 文件标识

解密结果还保留了 raw 字段。该字段是解密得到的完整内层 JSON 对象副本,用于确保原始业务信息没有因结构化导出而丢失。

4. 重点数据结构

4.1 meta

典型结构如下:

{
  "book_exam": "",
  "data_version": "1.0"
}

meta 用于描述词条所属分类及数据版本。字段可能因词条版本不同而变化,读取程序不应假设所有字段都存在。

4.2 词形与发音

  • word 保存主词条。
  • us_pron 与 uk_pron 保存美式、英式发音标记。
  • spell 为数组,当前样本中可能为空数组。

这些字段应按原值保存,不应进行清洗、转写或字段删减。

4.3 释义

interpret 为包含词性的中文释义文本,可能包含换行符、多个词性以及特殊标点。例如一个词条可能同时包含名词、动词和形容词释义。

因此,导出或二次处理时不能按单行文本处理,也不能仅保留第一条释义。

4.4 易混淆词

confuse 与 confuse_exps 为两个相互关联的数组:

  • confuse:易混淆词。
  • confuse_exps:与易混淆词按位置对应的解释。

读取时应保留数组顺序;当两个数组长度不一致时,应保留原始数组,不应强行补齐或删除元素。

4.5 短语

phrase 是对象数组。对象可能包含:

字段 类型 含义
p array 短语内容
t number 短语类型
pseqs object 短语序号或关联信息

即使 p 为空,也应保留该对象,因为其类型和序号信息仍属于原始数据。

4.6 例句

example 在当前数据中是一个 JSON 字符串,而不是直接嵌套的 JSON 对象。其内部通常包含:

{
  "v": 1,
  "data": [
    {
      "type": "99",
      "i": {},
      "g": [
        {
          "eid": "例句标识",
          "e": "英文例句",
          "c": "中文翻译",
          "fid": "媒体或资源标识",
          "sid": "句子标识",
          "i": "图片资源路径",
          "b": "来源书名",
          "u": "音频资源路径",
          "s": 0
        }
      ]
    }
  ]
}

例句记录可能包含英文文本、中文翻译、图片路径、音频路径、来源书名及多个内部 ID。处理程序应先将 example 作为字符串保留;如需解析,应在副本上执行 JSON 解析。

5. 解密结果完整性要求

当前解密流程应遵循以下规则:

  1. 原始 .zpk 文件只读,不覆盖、不重写。
  2. 每个 .zpk 只生成一个对应的 .json 文件。
  3. 解密结果保留内层 JSON 的全部字段。
  4. 保留空数组、空对象、换行符、特殊字符和资源路径。
  5. 不将多个 ZPK 合并为 JSONL、CSV 或其他汇总文件。
  6. zpk、zpk_path、index_word、book_occurrences 等流程元信息如存在,应与原始业务字段并存,不得替换原始字段。

6. 数据使用建议

  • 读取 JSON 时使用 UTF-8 编码。
  • 对未知字段采用兼容读取方式,不因字段缺失而使整批任务失败。
  • 例句字段需要二次解析时,应捕获 JSON 解析异常,并保留原始字符串。
  • 不建议基于 definition_count 或 phrase_count 等派生统计字段替代原始数组内容。
  • 文件级处理应以 ZPK 文件名作为稳定主键。

7. 结论

ZPK 解密文件是以单词为中心的词典扩展数据,核心内容包括发音、释义、易混淆词、短语和例句资源。数据中存在嵌套 JSON 字符串、空数组和资源引用等情况,不能按扁平表格进行无损替代。

当前推荐的存储方式为原始 ZPK 与独立解密 JSON 一对一对应,并完整保留解密得到的全部业务字段。