历史协议 V1（旧包兼容）

以下为历史 V1 字段与限制，仅供读取旧包和迁移，不是当前创作规范。新作品请使用 V2。旧包不能仅把版本号 1 改成 2。

包的目录结构

manifest.json
LICENSE.txt
README.md
assets/
  preview.png
  background.jpg
  background-dark.jpg
  icons/
    home.png
    home-dark.png
    home-selected.png
    home-selected-dark.png

这是一份部分主题的目录示意，完整包还需要其他图标。说明文件可选且须使用 UTF-8；图片只能放在 assets/ 下。安全文件名只使用 ASCII 字母、数字、点、下划线和连字符，每一段以字母或数字开头。

最小的配色主题

下面是可通过清单校验的配色主题示例；还须提供真实的 assets/preview.png 图片才能打包。它有意不替换图标或背景。

{
  "schemaVersion": 1,
  "id": "quiet-garden",
  "version": 1,
  "name": "Quiet Garden",
  "description": "安静的花园配色",
  "author": "Your Name",
  "license": "CC-BY-4.0",
  "preview": "assets/preview.png",
  "palette": {
    "primary": "#426B52",
    "secondary": "#A16B4F",
    "tertiary": "#617788"
  }
}

授权示例不自动赋予素材许可；换成你实际拥有的许可与署名。

清单字段

字段	要求
schemaVersion	固定为整数 1
id	最长 48 字符，小写字母开头，仅小写字母、数字、单个分隔连字符；不能用内置 ID
version	正整数，更新同一主题时递增
name / author	必填，各最多 60 个 UTF-16 单位
description	可省略或为空，最多 300 个 UTF-16 单位
license	必填，最多 120 个 UTF-16 单位
preview	固定路径 assets/preview.png
palette	可选，提供时必须同时有 primary、secondary、tertiary；颜色为 #RRGGBB
palette.name	可选，配套配色的名称，最多 60 个 UTF-16 单位；省略时使用主题 name
palette.topBar	可选，为书库、发现（含第二行）和搜索页的共用横排选择按钮单独配色；至少提供下述一项
iconScale	可选数值 0.75～1.2，作者推荐的贴图大小；省略为 1.0（100%），不改变按钮、文字或背景
icons	可选，只接受素材清单中的 80 个键
artwork	可选，只接受 pageBackground 与 navigation

文本不允许首尾空白、换行或控制字符；emoji 等字符可能占两个 UTF-16 单位。内置 ID original、tidal、botanical、celestial 保留使用。主题必须至少提供配色、图标或背景之一；不接受未知字段。

命名沿用协议的 camelCase 与稳定动作语义，例如 topBar、selectedBackground、darkAsset、readAloud。书库、发现和搜索共用 topBar，不另造页面专属别名。新增能力保持可选；已有作品只补本次需要的字段，不需要补齐后续新增槽位，也不因新增可选字段提升 schemaVersion。

可选项按需省略：缺图标槽使用 App 原系统图标；缺 selected 使用 normal，缺 darkAsset 使用该状态的 asset。页面底图缺失时保留原渐变／底色；导航装饰缺失时不叠图。没有 palette 则应用素材时保留用户当前配色；palette.name 缺省使用作品名。topBar 整块或单个角色缺省使用现有 ColorScheme／材质颜色规则，调用方显式覆盖优先。iconScale 缺省为 1.0，已保存的用户覆盖优先。身份、版本、作者、许可、预览及至少一种配色／图标／背景内容仍必需；声明了 palette 时三个基础色必须齐全。合法省略与坏声明不同：引用不存在或损坏的文件仍须报错，不能当成可选项忽略。

横排按钮的普通和选中配色

在 palette 中加入 topBar，即可为书库分组、发现分类及来源、搜索过滤等共用横排选择按钮设置颜色：

"topBar": {
  "background": "#E6EDF2",
  "foreground": "#234A73",
  "selectedBackground": "#234A73",
  "selectedForeground": "#FFFFFF"
}

background / foreground 是普通状态的底色及文字／图标色；selectedBackground / selectedForeground 是选中状态的底色及文字／图标色。四项均可省略，但对象至少有一项，颜色严格使用 #RRGGBB。未提供的字段保留 App 的默认计算，不接受空对象、未知字段或 null。它控制按钮本身；页面顶栏、布局和玻璃／实底偏好继续由 App 管理。请检查两种材质、浅深外观下的文字与图标对比度。

旧版 App 会严格拒绝 topBar；需要兼容旧版时省略此字段。V1 的同一组颜色用于浅深外观；公开模板和投稿仍为 V1。

图标与背景的写法

配色可按需提供；声明 palette 时仍需三个基础色。导入后，App 的配色列表会新增配套配色，默认与 贴图主题同名；例如 name 是“静岸”，配套配色也叫“静岸”。如需不同名称，在 palette 中增加 "name": "静岸暮色"，并保留三个颜色字段。 选择贴图主题会默认选中它的配套配色；之后可以单独换成其他配色，重新选择贴图时 再次恢复配套配色。旧的无配色部分包保持当前颜色。旧版 App 尚不接受 palette.name， 自定义名称需要本次或更新的 App；默认同名包不需要增加字段。

把下面两个字段合入你的清单；这个片段只展示一个图标，不是完整主题。

{
  "icons": {
    "home": {
      "normal": {
        "asset": "assets/icons/home.png",
        "darkAsset": "assets/icons/home-dark.png"
      },
      "selected": {
        "asset": "assets/icons/home-selected.png",
        "darkAsset": "assets/icons/home-selected-dark.png"
      }
    }
  },
  "artwork": {
    "pageBackground": {
      "asset": "assets/background.jpg",
      "darkAsset": "assets/background-dark.jpg"
    },
    "navigation": {
      "asset": "assets/background.jpg",
      "darkAsset": "assets/background-dark.jpg"
    }
  }
}

槽位有 normal 才有效；selected 与 darkAsset 都是可选的。精确回退顺序为：先选择 selected（缺失则 normal），再选择这个状态的 darkAsset（缺失则该状态的 asset）。缺少整个槽位则显示 App 原有图标。注意：选中状态缺深色图，不会转去用普通状态的深色图。

图片与 ZIP 限制

项目	上限或要求
ZIP 压缩大小 / 展开大小	10 MiB / 20 MiB
ZIP 条目	512 个，目录也计数
manifest.json	64 KiB
全部被引用图片	总计 2400 万解码像素，共用同一路径只计算一次
图标	正方形，最大 512×512，必须包含透明通道
背景	每边最大 2048
预览	PNG，每边最大 1600
图片格式	静态 PNG、JPEG、WebP，真实格式必须匹配扩展名

不允许 SVG、GIF、字体、脚本、远程 URL、加密 ZIP、符号链接、重复或大小写冲突路径、路径穿越和未被引用的图片。SVG 原稿需要先导出透明 PNG 或 WebP。说明文件不要另造未支持的文件名。

机器可读参考

下载 V1 字段 Schema 与槽位表。它与公开 Skill 从服务端实际校验模型生成；完整模板始终是这一份。schemaVersion 是协议，version 是主题的升级序号，两者不可混用。

图标大小与本地测试

可在清单根部写 "iconScale": 0.9 推荐 90% 大小。它是相对 App 默认贴图尺寸的绝对比例，不与用户设置相乘。用户可在「外观设置」中调整 75%～120%，按主题分别记忆；「恢复作者推荐」清除用户覆盖值。只含配色、没有图标的包不受缩放影响。旧版 App 严格拒绝这个新可选字段；需要兼容旧 App 时省略，使用默认大小。

从本地测试到市场上架始终沿用同一主题 id，发布新正式版本时递增 version。新版 App 的「我的主题」按 ID 显示一张卡片，版本页可保留同版本的不同内容：本地测试稿和市场正式版分别标注。完全相同的包复用；安装正式版不会覆盖不同的测试稿。名称相同但 ID 不同不会自动合并。安装来源由客户端校验与收据记录，不可在清单中伪造。