这是源码仓库。 项目主页在 https://doubak.com。

豆备（Doubak）的数据格式规范定义。从豆瓣（douban.com）备份的数据，均按本项目约定的格式规范进行存储与解析。

若将二者混淆为同一种格式去设计，是本项目早期最主要的经验教训。

• canonical/README.md —— 本树入口文档
• INGESTION.md —— 面对多个 bundle 归档，哪些可以读取、读取后可以得出哪些确定结论
• IDENTITY.md —— 如何识别与判定跨抓取批次的同一条记录
• FIELDS.md —— 定义可提取字段，以及哪些复合字段不应在解析阶段过早拆解
• JSON Schema：mark / subject / broadcast / longform / doulist / album / group_topic / group_join / common
• 一致性用例：17 组，重点约束**「解析器绝不得推导出的错误结论」**

cd canonical/v1 && python3 validate.py <canonical 目录>   # 零依赖
cd canonical/tests && python3 make-tests.py

基于真实用户归档 9279 行数据实测验证全部通过（标记 2940 · 作品 2940 · 广播 3394 · 长文 5）。

数据模型的演进刻意滞后于抓取——脱离历史页面去空想设计 schema，只会得到脆弱易损的数据结构。当前这四类格式，均已基于大量跨年份的历史真实页面完成了实测与对齐。

• bundle/README.md —— 本树入口文档
• bundle/v1/SPEC.md —— 规范性技术文本，建议优先阅读
• DESIGN.md —— 设计原则与技术取舍
• JSON Schema（2020-12）：manifest / index-entry / checkpoint / crawl-state-entry / coverage-entry / common
• 词表：intent / verdict / surface / capture-fidelity

cd bundle/v1
python3 validate.py examples/minimal-bundle   # 校验单个 bundle
python3 validate.py --tests                   # 运行全量用例
python3 validate.py --integrity-only <目录>   # 仅在底层字节损坏时报错

manifest.account 与七类用户记录的 account 支持可选的 nickname（字符串或 null）；旧归档可缺省。数字 user_id 仍是身份主键，昵称不参与内容修订。 合并规则见 canonical/FIELDS.md，字段契约可用 python3 tools/test_account_nickname.py 检查。

结构性检查无需任何第三方依赖；安装 jsonschema 与 referencing 后会额外运行 schema 层校验。 未安装依赖时，终端输出会显式明确说明：

通过（**只跑了结构层** —— 没装 jsonschema，schema 层没查）

此前最初的设计是在开头输出「提示: 未安装 jsonschema，跳过 schema 层校验」，末尾输出「通过」——用户往往只注意末尾的「通过」而忽略提示。这并非空穴来风：在开发 bundle/1.4 的 gap.url 期间，产出的归档曾有一段时间存在不合规字段（gap 设置了 additionalProperties: false，多出字段即违规），而本机校验器却一直报告「通过」，因为该违规仅能在 schema 校验层被捕获。此时保持退出码不变——未安装可选校验工具并不属于归档本身的损坏缺陷。

错误严格划分为完整性错误（数据损坏或哈希不匹配，退出码 2）与合规性错误（字节完整但结构声明不合规范，退出码 1）两类。详见 SPEC §12.1。

cd bundle/v1
python3 examples/make-minimal-bundle.py   # 偏移量与哈希摘要均严格依据文件内容动态计算
python3 tests/make-tests.py

账号头像归档与个人站点图标设计 新增开放 intent asset.image.account_avatar，使用已有 asset surface、assets 段与 parent capture 关系； 单纯扩展开放 intent 不要求升级 bundle 版本。Canonical 新增带修订及观测来源的 profile.ndjson， schema、验证器、摄取规则、示例与 conformance 已同步。旧八文件 canonical 仍可验证， 缺少 profile 文件表示没有结构化资料，不表示用户删除了头像。