症状 · 核对 · 恢复
Codex 主题排障：背景不显示、导入失败、更新失效与恢复
安全排查 Codex 或 WorkBuddy 主题不显示、不动、无法导入或更新后失效，按照停止、核对和恢复步骤定位问题。
核验日期
主题或背景完全不显示
确认主题包面向你正在打开的应用：Codex 与 WorkBuddy 主题包不能混用。再确认 macOS 与准确客户端版本，并检查匹配适配器是否标记为已验证。
- 在 Studio 重新打开主题包确认目标
- 先检查静态兜底图片
- 不要靠重命名或跳过目标检查强制使用未知版本
混淆了原生主题与 .cctheme
Codex 原生主题与 CC Theme 主题包使用不同加载路径。.cctheme 不会出现在原生外观下拉框，原生分享字符串也不是高级本地媒体主题包。
- 原生配色与字体使用 Codex 外观设置
- 用 Studio 检查 .cctheme 主题包
- 只使用正式 Release 指定的目标适配器
- 不要靠重命名伪装成另一种格式
视频、水波或方向背景保持静止
系统开启减少动态效果时，水波会停止，方向图集会固定到 idle 帧。视频则需要确认素材是限制内的 MP4，并且目标主题包确实包含该文件。
- 检查系统减少动态效果设置
- 水波模式必须有一张有效本地兜底图
- 方向模式必须使用静态 WebP，且列数 × 行数等于 8、16 或 32
导入提示主题包不安全或已损坏
导入器遇到不一致会明确拒绝，不会静默忽略。请用当前 Studio 重新导出，并让 manifest.json、theme.json、声明目标文件和哈希保持完整。
- 导出后不要手动往压缩包加文件
- 核对扩展名和真实媒体签名
- 拒绝远程 URL、脚本、原始 CSS、HTML、SVG 与路径穿越
- 只用于 manifest 记录的应用和版本
客户端更新后主题失效
即使产品仍能启动，更新也可能改变内部界面结构。新构建应先保持待验证，直到代表性页面、回退与恢复流程全部通过。
- 停止旧适配器
- 恢复原生外观
- 记录准确新版本与失败页面
- 等待兼容记录，不修改已签名应用包
排障常见问题
为什么 Codex 更新后背景消失？
适配器是针对准确客户端界面验证的；新构建可能改变结构，因此应停止旧适配器，等待新版本完成验证。
为什么导入 .cctheme 后没有出现在 Codex 主题菜单？
因为 .cctheme 不是 Codex 原生分享格式，它属于 CC Theme Studio 与匹配本地适配器的工作流。
为什么水波只显示静态图片？
系统可能开启了减少动态效果，或者没有附加有效兜底图片。减少动态效果下保持静态是预期行为。
为什么方向图集显示了错误帧？
检查方向数、列、行、首方向角度、idle 帧和原点；列数乘行数必须等于选择的帧数。
为什么 WebP 图集被拒绝？
它必须是静态 WebP，且不超过 32 MiB、3200 万像素或单边 16384 像素，网格单元还必须能整除。
为什么我修改 ZIP 后 .cctheme 无法导入？
每个声明文件都有完整性哈希；导出后增加、删除或修改文件而不重建 manifest，会导致主题包不一致。
恢复操作会删除聊天吗？
不会。恢复只移除 CC Theme 外观和连接状态，不会删除或找回产品数据。