Theme Manifest

主题清单

theme.json 是主题的元数据文件，必须位于主题 ZIP 的根目录。文件缺失或 JSON 解析失败都会导致安装被拒绝。

完整示例

{
  "id": "my-theme",
  "name": "我的主题",
  "version": "1.0.0",
  "description": "一个自定义主题",
  "author": "StackPanel",
  "supportsDarkMode": true
}

字段说明

字段	必填	类型	说明
id	是	string	主题唯一标识，/^[a-z0-9_-]{1,64}$/
name	是	string	主题显示名称
version	是	string	semver 版本号
description	否	string	主题描述
author	否	string	作者
supportsDarkMode	否	boolean	声明支持暗色。当前仅作能力标记，暗色切换由前端主题驱动
locales	否	string[]	随包提供的界面语言（BCP 47，如 zh-CN）
assets	否	object	品牌资源相对路径：{ logo?, favicon? }，经 /themes/:id/assets/* 提供

id 规则

• 格式为 /^[a-z0-9_-]{1,64}$/，即小写字母、数字、下划线和短横线。
• default 是保留 ID，第三方主题不可使用。
• 通过 /admin/themes 直接上传 ZIP 时，ID 已存在会返回 409，不允许覆盖安装；升级走市场安装通道 POST /admin/market/themes/:id/install。

版本管理

version 遵循 semver 规范。安装时该值从清单写入数据库 themes 表的 version 列，管理后台显示此值。