本文档记录主题系统重构的实现状态。当前 Git 基线为 e43cde5；勾选项已在工作区实现，未勾选项继续作为后续兼容与增强工作。
- 将当前“作用区域：全屏 / 内容区 / 侧边栏”改为“配置模式：全屏统一 / 分区独立”。
- “全屏统一”模式只显示一套背景配置，同时作用于内容区和侧边栏。
- “分区独立”模式显示两套互不影响的配置：内容区域、侧边栏区域。
- 内容区和侧边栏均支持独立选择：无背景、纯色、线性渐变、径向渐变、本地图片。
- 每个区域独立保存图片、适应方式、透明度、渐变参数、模糊、饱和度和区域遮罩强度。
- 切换配置模式时保留当前编辑快照；点击“放弃”恢复切换前状态，点击“应用”才持久化。
- 背景图片选择、实时预览、导入导出、复制主题和 ZIP 主题包同步支持新模型。
建议主题结构升级为：
background.mode = fullscreen | per-region
background.fullscreen = BackgroundConfig
background.content = BackgroundConfig
background.sidebar = BackgroundConfig
兼容迁移规则：
- 旧主题
region = fullscreen迁移为mode = fullscreen。 - 旧主题
region = content迁移为mode = per-region，内容区沿用旧配置，侧边栏为none。 - 旧主题
region = sidebar迁移为mode = per-region，侧边栏沿用旧配置，内容区为none。 - 读取旧 schema 时自动迁移；保存后使用新 schema，不能丢失已有本地图片。
- 修复内容区背景覆盖原生图标、按钮、文字和交互控件的问题。
- 区域背景始终位于区域内容下方，不能依赖给所有直接子节点批量设置
z-index。 - 内容区和侧边栏分别建立稳定 stacking context，背景层使用负层级或等价的底层绘制方案。
- 不改变 Codex 原有
position: sticky/fixed/absolute、浮层、工具提示和菜单的层级关系。 - 页面切换、React 重建容器、target 重连和 watchdog 重注入后，背景仍挂载到正确区域。
- 未配置背景的区域保持完全不透明主题表面，不能透出另一区域的图片。
- 顶部标题栏根据主题
baseMode、背景色和前景色自动选择深色或浅色样式。 - 文件、编辑、视图、帮助以及窗口控制按钮在所有主题下保持清晰可读。
- 标题栏背景、底部分隔线、hover/active 状态与当前主题协调，不再固定为浅灰色。
- 背景图片默认不延伸到 Windows 原生标题栏，避免菜单文字落在复杂图片上。
- 当主题颜色对比不足时自动使用安全前景色，不直接覆盖用户保存的主题 token。
- 侧边栏背景、标题、正文、次要文字、图标、分隔线统一使用侧边栏语义 token。
- 修复浅色主题下侧边栏文字过淡、深色主题下图标与背景接近的问题。
- 默认、hover、active、selected、disabled、loading 状态均保持清晰层次。
- 当前任务高亮不能只依赖细微背景差异，应同时保证文字和图标对比度。
- 侧边栏独立图片背景开启时，自动应用可调遮罩，文字与图标不能直接落在高对比图片上。
- 侧边栏没有背景时，不受内容区图片、透明度或模糊设置影响。
- 背景页顶部使用“配置模式”下拉：
全屏统一、分区独立。 - 全屏统一模式显示一张“全屏背景”配置卡。
- 分区独立模式显示“内容区域”和“侧边栏区域”两张可折叠配置卡。
- 每张卡显示独立缩略图、文件名、加载状态、预览状态和清除背景操作。
- 清楚标记当前正在编辑的区域，避免把内容区图片误设到侧边栏。
- 主题卡片标记背景模式，例如“全屏背景”或“分区背景”。
参考图已经超出普通主题换色范围。它同时包含品牌标识、分区插画、图标替换、欢迎页 Hero、快捷功能卡片、装饰贴纸和 composer 皮肤。Theme Inject 应保留简单的“主题模式”，另提供显式启用的“高级皮肤模式”，避免普通用户面对大量配置。
| 层级 | 能力 | 预计新增配置 | 参考图还原度 |
|---|---|---|---|
| 基础主题 | 颜色、字体、圆角、阴影、分区背景 | 约 35–45 个标量 + 4–6 个资源槽 | 约 60%–70% |
| 高级皮肤 | 品牌区、组件表面、图标包、装饰层、欢迎页 | 约 65–85 个可视化选项 + 10–14 个资源槽 + 3 类结构化列表 | 约 80%–90% |
| 结构扩展 | 自定义欢迎页卡片、动作绑定、侧栏附加组件 | 不适合计为平铺字段，应使用数组配置 | 可接近参考图，但依赖 Codex DOM 适配 |
这里的“配置数量”指面板可见的用户选项，不包含终端 16 色等已有低层 token。最终 schema 应采用分组对象、共享预设和按需展开，不能做成 80 行连续表单。
appearance.mode = theme | skin
brand = BrandStyle
background = BackgroundLayout
surfaces = SurfaceCollection
typography = TypographyRoles
icons = IconTheme
decorations = Decoration[]
home = HomeSkin
layout = SkinLayout
accessibility = AccessibilityPolicy
- 应用字标或 Logo：对应参考图左上角
Miku Codex。 - 应用副标题：Logo 下方的一行说明文字。
- 侧边栏纹理或水印：必须位于导航内容下方。
- 主内容 Hero 图片：支持主题资源与响应式裁切。
- Hero 品牌徽章：对应右上角独立品牌贴片。
- 侧边栏头像和用户徽章。
- 右下角贴纸或角色小卡片。
- composer 装饰图片或纹理。
- 卡片图标资源使用主题包本地图片。
- 通用装饰资源目录，供星星、丝带、爱心等装饰层引用。
- 所有资源只允许主题包内本地文件，不加载远程 URL。
- 首版继续支持 PNG、JPEG、WebP；SVG 必须完成净化和安全审计后才能开放。
- 标题栏：背景、前景、次要前景、边框、hover、active。
- 侧边栏：品牌文字、导航图标、分组标题、分隔线、hover、selected、selected foreground。
- 主内容：Hero 遮罩、卡片背景、卡片前景、卡片边框、卡片图标底色。
- composer：背景、前景、占位文字、边框、操作图标、发送按钮。
- 装饰：主装饰色、次装饰色、发光色。
- 每一类 token 都要有自动对比度保护，但不能覆盖用户保存值。
为 titlebar、sidebar、content、hero、card、composer、popover 各保存一个 SurfaceStyle：
SurfaceStyle {
fill, opacity, blur, saturation,
borderColor, borderWidth, radius,
shadowColor, shadowBlur, shadowOpacity
}
- 表面样式支持颜色继承与独立覆盖。
- Hero、卡片和 composer 可引用同一命名预设，避免逐项重复设置。
- 透明表面自动使用文字对比保护。
- 参考图中的半透明白色卡片、青色描边和柔光阴影可由该模型表达。
- 品牌字体、正文字体、代码字体可分离配置。
- 标题字体独立于正文字体，并让 Hero 标题、Hero 副标题、导航和正文分别支持字号/字重比例。
- 支持文字描边或阴影作为可选可读性保护，不默认启用。
- 自定义字体首版只使用系统已安装字体；主题包字体文件需后续单独评估授权和安全。
- 侧边栏宽度和内容最大宽度。
- Hero 高度和卡片列数。
- 主内容内边距、Hero 独立焦点、卡片间距及更细的 composer 几何控制。
- 品牌区高度、侧边栏分组间距、导航行高。
- 提供紧凑、标准、宽松三个基础布局预设，再允许高级用户微调现有布局字段。
- 不修改 Windows 原生标题栏高度和窗口按钮几何，避免破坏命中区域。
- 模式：沿用原生、仅重着色、自定义图标包。
- 重着色模式分别覆盖 default、hover、active、disabled 四种可配置状态。
- 图标包按受限动作 ID 映射首批常用操作：新建任务、搜索、已安排、插件、拉取请求、设置、终端和发送。
- 找不到映射或 Codex 版本不兼容时自动回退原生图标，不能显示空白。
- 不通过脆弱的
nth-child替换图标；需要建立 Codex 版本适配器和选择器探测。
Decoration {
asset, region, anchor, offsetX, offsetY,
width, opacity, blendMode, layer, visibility
}
- 可挂载区域：标题栏、侧边栏、主内容、composer；Hero 装饰可通过主内容区域定位。
- 装饰只允许受限层级，默认
pointer-events: none，不能遮挡点击。 - 支持窗口宽度可见条件，窄窗口自动隐藏非必要装饰。
- 支持偏移、尺寸、透明度和受限层级，不允许任意脚本。
- 为装饰增加有限的混合模式与更细的页面状态可见条件。
- 参考图中的星星、虚线、爱心、角落贴纸由装饰列表表达，不硬编码进运行时。
- 仅在“新任务/空会话”状态显示自定义欢迎页；进入真实对话后恢复 Codex 正常内容。
- Hero 支持标题、副标题、徽章和主插画。
- 快捷卡片最多 4 个，每项包含标题、说明、图标和 Prompt 动作。
- 首版动作只允许将受限长度的 Prompt 模板填入 composer。
- 不能伪造运行结果、任务状态、项目列表或用户数据。
- 参考图左侧项目和任务内容继续来自 Codex 原数据；主题只负责视觉，不能把示例文字写死。
- 欢迎页结构注入必须单独设置开关，并按 Codex 版本维护适配器；失败时回退原生首页。
- 默认保留基础页：主题库、颜色、背景、字体、布局、效果与终端。
- 启用“高级皮肤”后按组显示品牌、表面、图标、装饰、欢迎页。
- 表面颜色提供“恢复继承值”，基础布局提供预设。
- 资源选择器显示推荐尺寸、当前裁切范围、体积和更完整的加载状态。
- 提供桌面宽屏、普通窗口和窄窗口三种实时预览状态。
- 高级皮肤不开放任意 JavaScript；行为只能使用 Rust/Binding allowlist。
- 限制 ZIP 资源大小、文件扩展名、路径、装饰数量、卡片数量和图标映射数量。
- 增加单图解码像素总量限制。
- 新增
skinCompatibility，记录适配的 Codex 版本和需要的运行时能力。 - watchdog 健康检查覆盖品牌层、区域宿主、图标回退和欢迎页挂载状态。
- Codex DOM 变化时优先降级为普通主题，不能阻止用户创建任务或输入消息。
- 可创建青色/粉色品牌皮肤，同时保持菜单、侧栏和 composer 文本达到可读对比度。
- Hero 插画、品牌徽章、四张快捷卡片、侧栏水印和角落贴纸均能由主题包资源配置。
- 高级皮肤配置及其 Logo、Hero、图标、装饰和卡片图标随 ZIP 完整导入导出，引用文件缺失时拒绝安装。
- 可通过 OpenAI 协议兼容的基础/视觉/生图模型，从文字或参考图生成可编辑的主题与皮肤资源。
- 所有装饰不遮挡搜索、窗口控制、导航、卡片、composer 和发送按钮。
- 原生项目、任务、对话和状态数据仍然真实可操作。
- 关闭高级皮肤后完整恢复 Codex 原结构，只保留普通主题能力。
- 在不支持的 Codex 版本上安全回退，不出现空白首页或消失的图标。
-
Neutral Light、Neutral Dark、Midnight Glass 的标题栏、侧边栏和内容区均可读。
-
全屏统一模式只需配置一次，内容区和侧边栏视觉连续且没有明显割裂。
-
分区独立模式可以为内容区设置图片、为侧边栏设置纯色，并同时正确显示。
-
分区独立模式可以只设置其中一个区域，另一区域保持原主题表面。
-
内容区图片不会覆盖文件夹、命令、审核、附件、composer 和窗口工具图标。
-
侧边栏图片不会覆盖搜索、新建任务、项目、设置和任务状态图标。
-
打开命令面板、菜单、弹窗、设置、终端和代码 diff 时，浮层始终位于背景上方。
-
刷新页面、切换任务、折叠侧边栏、重新注入和 watchdog 恢复后配置不丢失。
-
旧图片主题首次加载后外观与原配置一致，并能安全保存为新 schema。
- 优化主题生成：提升蓝图质量、资源生成稳定性、失败重试体验和生成结果一致性。