返回 BookField

BookField package format

wbpkg

wbpkg 是 BookField 为 local-first reading、离线搜索、学习计划和结构化引用而导入的 installable content package format。

Version snapshot

workbook.toml
schema_version = 4
.wbpkg/manifest.json
schemaVersion = 5
reader_manifest.json
schemaVersion = 3
reader.rdoc
schemaVersion = 3
Reader SQLite schema
db_schema_version = 17

概要

BookField 可以验证、安装和阅读的 package

一个 wbpkg package 包含一个 work 和一个 edition。它把 metadata、reader asset、navigation、可选 schedule 和 locator index 放在一起，供 BookField 在设备上验证并安装。

Installable container

一个 work 和一个 edition 的单一 installable boundary。

Manifest v5

manifest.json 定义 identity、work、edition、assets、navigation 和可选 entries。

ReaderDoc v3

ReaderDoc content 已为导入准备好，因此 Reader 运行时不解析 EPUB、HTML 或 CSS。

Navigation tree

navigationTree 决定 entry point 和 package level 的目录。

Locator indexes

locator index 和 bindings 让匹配 package 已安装时可以离线解析引用。

Study plans

只有包含学习计划 metadata 的 package 才会在 manifest.json 中包含 authored studyPlans。

Package layout

wbpkg 中的 canonical files

package path 统一为 package-root-relative POSIX path。Text package 在 reader/ 下包含 ReaderDoc files；没有 text asset 的 image、audio 或 video only package 可以省略 reader/。

.wbpkg
manifest.json
reader/{assetId}/reader_manifest.json
reader/{assetId}/reader.rdoc
images/{assetId}.{ext}
images/{assetId}-thumb.{ext}
media/{assetId}.{ext}
locator/{profileId}.json

Manifest contract

Manifest v5 定义 install contract

manifest.json 是 BookField 在 import 前读取的公开 contract。legacy packageKind 和 presentation fields 不属于当前 package shape。

packageId / packageVersion

定义用于安装和替换判断的 package identity 与 package version。

work / edition

标识 package 中包含的 work 和 edition。

assets

列出 text、image、audio、video assets 以及各自的 local path。

navigationTree

定义 Reader 可离线打开的 entry point 和 package navigation。

studyPlans

只有 package 包含学习计划 metadata 时才添加 authored schedules。

bindings

连接 authored references 和 locator index，实现 offline resolution。

Package creation

说明公开 package 边界，而不是内部制作方式

  1. 1

    准备 source content

    准备 source content、metadata、media，以及可选的 authored schedules 或 references。

  2. 2

    生成 wbpkg

    生成包含 manifest metadata、ReaderDoc content、media、navigation 和 locator files 的 installable package。

  3. 3

    分发前验证

    分发前确认 package structure 和 schema compatibility。

Reader import

BookField 在设备本地读取 installed package

  1. 1

    Validate

    BookField 检查 package shape，并拒绝不支持或 malformed package。

  2. 2

    Unpack

    受支持的 package asset 会展开到 app-owned local storage。

  3. 3

    导入 SQLite

    ReaderDoc payload、navigation、locator index、search record 和 schedule 会注册为离线可用。

Compatibility

让 package 保持可预测的规则

  • 拒绝 legacy packageKind values。
  • 拒绝 legacy presentation fields。
  • 拒绝 non-canonical package paths。
  • 拒绝 malformed structured references。
  • installable wbpkg 不包含 source EPUB files。

Canonical references

Update policy

此公开页面是面向实现评估的概要，并不是规范正本。正本文档和 schema 文件由 BookField 源资料管理。

正本文档和 schema 文件

  • 00-spec-index.md

    此页面概述的 version policy、shared manifest shape、package layout、path rules、study-plan storage 和 locator policy 的正本。

  • 04-manifest-json-schema.md

    manifest v5 contract、必需的 navigationTree、package-root-relative paths、semantic validation boundary 和 rejection rules 的正本。

  • 08-reader-app-design.md

    定义 BookField 如何验证、展开、把 ReaderDoc data 导入 SQLite，并在设备本地读取 installed packages。

  • schemas/manifest-v5.schema.json / readerdoc-v3.schema.json

    提供 validation tooling 使用的 manifest.json 与 ReaderDoc payload structural schemas。

canonical docs 或 schema files 变更时，先更新 source，再刷新此公开 snapshot 和说明。

规划面向 BookField 的 package 分发

返回 BookField 概要，或咨询 wbpkg distribution flow 是否适合你的内容模型。

返回 BookField 咨询内容分发方案