开放格式 · 文件清单 · 准确目标
.cctheme 格式：面向 Codex 与 WorkBuddy 的可检查主题包
了解 .cctheme 压缩包包含什么、目标版本与 SHA-256 如何工作、允许哪些媒体，以及为什么安装器必须保持独立。
规范核验日期
必需文件
每个主题包都从 manifest.json 与 theme.json 开始。manifest 记录 kind、目标身份、适配器、声明文件、大小、媒体类型与 SHA-256；theme.json 保存可编辑文档，不会把二进制媒体复制成 Base64。
编译后的目标配置与媒体位于目标目录。Codex 使用 targets/macos/，WorkBuddy 使用 targets/macos-workbuddy/。包内目标才是权威信息，不能只看文件名决定应用位置。
- manifest.json — 主题包、目标、文件清单与完整性
- theme.json — 可编辑本地主题文档
- targets/macos/theme.json — Codex 编译配置
- targets/macos-workbuddy/theme.json — WorkBuddy 编译配置
允许的本地媒体
当前适配器属于媒体皮肤。目标目录包含必需的 PNG、JPEG 或 WebP 背景，也可以使用生成的纯色兜底图；还可以加入不超过 256 MiB 的 background.mp4。Codex v2 包可选加入不可拆分的宠物 manifest 与 WebP 精灵图；WorkBuddy 会拒绝宠物数据。
完整压缩包的压缩与解压大小上限均为 550 MiB，文件条目不超过 20 个。导入时会检查媒体类型、文件签名、尺寸或结构、展开大小与清单哈希。
- PNG、JPEG 或 WebP 静态背景
- 不超过 256 MiB 的可选 MP4
- 仅 Codex 可选 v2 宠物文件对
- 不允许嵌入播放器、远程 URL 或可执行媒体处理器
会被拒绝的内容
所有路径必须是相对、规范且已声明的。导入会拒绝路径穿越、绝对路径、重复或未声明条目，以及不支持的 schema kind。仅把任意文件改成允许的扩展名也无法通过，因为还会检查媒体签名。
主题包禁止脚本、原始 CSS、HTML 与 SVG。客户端选择器和版本补丁属于固定本地适配器，不能由用户分发的主题携带。
- JavaScript、Shell 或 PowerShell 主题载荷
- 原始 CSS、HTML 与 SVG
- 远程媒体 URL 或网页播放器
- 路径穿越、绝对、重复或未声明路径
完整性不等于身份
除 manifest.json 外，每个文件都会在 manifest.integrity.files 中保存 SHA-256。导入器在读取主题文档或媒体之前重新计算哈希，用于发现相对清单的损坏或替换。
哈希不是数字签名，也不能证明作者身份。安装器 Release 上线后，应另外对照同一 Release 发布的校验值，并检查源码与发行说明。
- 哈希不匹配会拒绝主题包
- 目标不匹配会拒绝主题包
- 未知适配器或客户端版本不能默认兼容
- 安装器信任与主题包完整性分开评估
.cctheme 格式常见问题
.cctheme 只是改名的 ZIP 吗？
它使用 ZIP 容器，但导入还要求 .cctheme 扩展名、支持的 kind、准确 manifest、已声明路径、目标身份与通过验证的哈希。
没有安装适配器也能检查主题吗？
可以。压缩包可在 CC Theme Studio 中打开，JSON 与声明素材可以独立于本地适配器检查。
一个主题包能同时面向 Codex 与 WorkBuddy 吗？
不能。当前用户主题包只标识一个应用、平台与客户端版本，独立主题包可以避免误应用到另一个客户端。
主题包会修改 Codex 原生颜色或字体吗？
不会。当前 macOS 主题包只控制本地媒体、媒体位置、结构层模糊或饱和度与系统外观模式；原生颜色、字体、圆角和布局保持锁定。
为什么安装器不能放进主题包？
把主题数据与固定适配器代码分开，可以避免主题作者在外观包中携带可执行客户端控制逻辑。
规范与合同
仓库规范是事实来源。主题包限制与目标版本只能通过经过审查的合同更新改变。