当前主题协议 V4

当前协议为 V4。 新作品统一使用 V4，应用外观、启动图、配色、阅读主题和字体可独立选择；旧 V1/V2/V3 包继续兼容。导入先保存，应用由用户确认。当前清单 · 历史 V1。

统一模块目录

V1、V2、V3、V4 使用相同分类、名称与顺序。版本只扩展支持范围；模块固定展示，分别标明“已提供”“作者未提供”“此协议版本不支持”，只有已提供的模块可选。

分类	模块	键名	最低协议
应用外观	应用配色	`palette`	V1
应用外观	界面图标	`icons`	V1
应用外观	页面背景	`pageBackground`	V1
应用外观	导航装饰	`navigation`	V1
应用外观	启动图	`launchScreen`	V4
阅读外观	阅读纸张	`readerPaper`	V2
阅读外观	段评装饰	`paragraphReview`	V2
阅读外观	加载动画	`openingIndicator`	V2
阅读外观	信息栏样式	`informationBars`	V2
阅读外观	评论卡片	`commentCard`	V3
字体	字体	`fonts`	V2

“评论卡片”统一包含本章说与神评论的底色、边框、圆角、内边距和徽章；与“阅读纸张”“段评装饰”（段评按钮素材）分开选择，组合下载互不夹带。不改变评论内容或启用功能。字体仍是一个模块，内含 ui/body/header/footer 角色。skin、palette、reader、fonts 是四个存储容器，不是另一套用户模块分类；一个容器可以承载多个独立可选模块。

机器协议的 moduleCatalog 提供相同目录。catalogVersion: 3 增加 V4 启动图模块；新主题包使用 schemaVersion: 4。作者作品的 version 是另一套独立递增的发布序号。

当前 V4 套装清单

V4 使用整数 schemaVersion: 4 和 format: "origo.theme-suite"。components 可声明 skin、palette、reader、fonts；省略某组件表示应用时保留接收者现有选择，显式系统选择则恢复相应内置能力。竖屏启动图 skin.artwork.launchScreen 和可选横屏图 launchScreenLandscape 都使用必填 asset 和可选 darkAsset，只接受静态 PNG/WebP，单文件不超过 2 MiB、最长边不超过 2048 像素。未提供横屏图时 App 以 contain 居中回退竖屏图；首页准备好后立即退出，不强制停留。下面的有效示例不需要预览图或额外素材：

{
  "schemaVersion": 4,
  "format": "origo.theme-suite",
  "id": "my-shared-theme",
  "version": 1,
  "name": "My shared theme",
  "author": "Your Name",
  "license": "Your actual license",
  "components": {
    "skin": {
      "base": "original"
    },
    "palette": {
      "light": {
        "seed": "#456789"
      },
      "dark": {
        "seed": "#345678"
      }
    },
    "reader": {
      "light": {
        "background": "#FFFDF7",
        "text": "#202020",
        "controlBar": "#FFFDF7"
      }
    },
    "fonts": {
      "resources": [],
      "roles": {
        "ui": {
          "builtin": "system"
        },
        "body": {
          "builtin": "system"
        },
        "header": {
          "builtin": "system"
        },
        "footer": {
          "builtin": "system"
        }
      }
    }
  }
}

配色与字体

每种配色外观选择单个 seed，或齐全的 primary、secondary、tertiary，两种形式互斥；均可带 topBar。纯系统字体可用 resources: []，各 role 可为 { "builtin": "system" }。自定义字体 role 引用 resources 中的 ID，资源须声明 family、asset、license、licenseAsset；字体文件与许可文本都要随包提供。

阅读资源与交付

V3 的 reader 协议支持浅深纸张、背景变体、段评图标、信息栏样式、评论卡片及受限 WebP 开书动画；这些是格式能力，不代表「分享当前搭配」会捕获所有可选设置。当前捕获的确切范围见使用与分享。完整分享包不能带组件交付用的 distribution。

信息栏样式的范围

reader.informationBars 可提供 style、contentPreset，或两者同时提供。style.header 与 style.footer 可调整字体角色、字号（8–24）、字重（100–900，步长 100）、语义颜色（text、muted、accent）、透明度（0.2–1）和密度（compact、regular、relaxed）；也可按信息类型覆写字体角色、字重、颜色和透明度。字体角色引用 components.fonts.roles，组合下载只附带实际引用的字体与许可。

contentPreset 只允许页首和页尾，每侧最多两行；每行左、中、右三组各最多三个项目。可用类型固定为时间、电量、书名、章名、章节页数、剩余页数、章节数、剩余章节数、章节进度、全书进度、本次阅读时长、今日阅读时长和本书阅读时长。格式同样受限，例如时间仅 auto/12h/24h，电量仅 auto/icon/percent/both，进度仅 auto/percent/bar/both。它不是任意文字、脚本或远程数据入口。

应用时，信息栏样式默认不勾选。用户明确选择后才套用作者声明的样式或有限内容预设；未声明的一侧保持原样，设备位置与边距等本机布局也保留。它不控制状态栏、正文排版、阅读进度来源或实时统计计算。

下载创作工具中的 references/protocol.json 从真实模型生成，references/suites.md 说明字段与资源约束。检查器按实际协议分派到同源验证器，支持 original 皮肤、单 seed 与空资源系统字体，不要求伪造资源。V4 本地校验压缩/展开上限为 128/192 MiB，另有资源角色预算；临时分享前后均限 32 MiB。--complete 对 V2/V3/V4 只审计四个存储容器是否存在，对 V1 仍审计素材全覆盖；默认允许合法部分包。

下载当前机器协议。作者上传一个完整 ZIP。可选 media.images 使用图片 ID 与包内路径，media.cover 引用图片 ID。组合下载保留所选资源和许可，省略宣传图片。V1/V2/V3 仍可读取；新作品使用 V4。

版本标识

schemaVersion: 4 表示主题包协议 V4。catalogVersion: 3 增加启动图模块。versionName: "4.0" 是作者展示版本，也支持 1.1、2.2；version 是递增整数交付序号，用于精确下载和更新识别。旧包未声明 versionName 时，整数 1 显示为 1.0。

V3 的可选 reader.commentCard 定义本章说和神评论卡片的浅深底色、边框、圆角和徽章；正文文字跟随阅读文字颜色。阅读设置可独立选择卡片皮肤，组合下载时作为“评论卡片”独立选择。