codex-theme-creator

创建 Codex 主题

创建可逆的装饰性主题，不修改 app.asar、已签名的应用包、WindowsApps、用户任务或身份验证数据。除非所选布局模式明确允许有界的构图调整，否则保留原生布局和交互行为。

权限边界

将此技能作为新 Codex 主题唯一的设计和 QA 权威。除非用户明确指定该来源，否则不要读取、复制或混合其他已安装的主题技能、已完成的主题清单、已完成的主题 CSS 或本地主题集合。不要将此工作流描述为与“本地主题惯例”结合使用。请从此技能匹配的骨架以及用户的需求说明或参考图开始。

此技能独立运行。其 TypeScript 脚本负责搭建、验证、可逆的会话应用和恢复。除非用户明确要求使用，否则切勿检测、调用、读取 CodeDrobe、Dream/Fiona 或其他主题注入器的配置，也不要声称依赖这些工具。不要复用它们的标记名称或运行时数据。唯一必需的本地工具是 Node.js、npx 和官方 Codex 桌面应用。

托管存储

除非用户明确要求其他位置，否则将所有生成的主题文件保存在托管库 ~/.codexthemes 中：

• 可编辑的源文件和美术素材：~/.codexthemes/themes/<theme-id>/
• 预览：~/.codexthemes/themes/<theme-id>/previews/
• 可分享的程序包：~/.codexthemes/exports/
• 运行时状态：~/.codexthemes/state/

切勿在当前工作区中或其附近创建主题文件的暂存、副本或临时副本（例如 .codexthemes-stage 目录）。如果沙盒或权限模式阻止写入 ~/.codexthemes，请先请求用户批准写入该目录，而不是先写到其他位置再移动文件。

阅读必需的参考资料

创建主题或进行重大重新设计之前，请完整阅读以下文件：

• references/design-playbook.md：布局模式、语义调色板、选择器和表面覆盖范围。
• references/qa-checklist.md：真实应用验收矩阵和严重故障项。
• references/theme-schema.md：清单和可移植程序包规范。
• references/asset-rights.md：用户素材处理和提交交接。

在写明下方的设计规范之前，不要开始制作美术素材或 CSS。

Gate 1：编写设计契约

记录：

• layoutMode
• backgroundScope
• decorDensity
• 浅色或深色模式及原因
• 插画焦点和文字安全区域
• 语义调色板
• 允许更改的界面表面
• 必须保持不变的原生几何结构和状态
• 目标桌面视口和窄屏视口

按以下顺序选择布局模式：

1. 当用户提供参考图像或指定视觉世界（游戏、电影、动漫、品牌、季节或其他鲜明的艺术指导）时，默认使用 native-immersive：保留原生布局，并提供协调统一的侧边栏、卡片、菜单、编辑器、设置、差异和终端样式材料，以及 references/design-playbook.md 中的装饰菜单。
2. 仅当用户明确要求主题只更改背景时，才使用 native-background。
3. 仅当参考图明确要求采用不同首页构图，且包含边界清晰的竖版、产品或营销主视觉时，才使用 editorial-showcase。
4. 无需主导性插画时，使用 palette-only。

将 decorDensity 记录为 minimal、balanced 或 rich。参考图具有鲜明艺术指导时，默认使用 rich，否则默认使用 balanced；只有用户明确要求仅更换背景或打造安静主题时，才使用 minimal。设计手册规定了每种密度所需覆盖的元素。仅提供一张背景图和一层遮罩的主题，不符合 balanced 或 rich 的要求。

backgroundScope 决定主导性背景插画的显示位置。这不是运行时开关，而是固化在 CSS 选择器中的设置，因此之后更改意味着需要重新构建主题。由于大多数用户不知道有此选项，应明确询问，而不是悄悄替用户决定：

• 用户未说明偏好时，在开始构建前用简单语言询问一次，例如：“背景插画应该只显示在首页（推荐——这样对话文字和代码最清晰），还是也显示在对话页面？”为确保可读性，推荐将 home 作为默认值。
• 只有用户选择 workspace 或明确要求在任务／对话页面显示插画时，才选择 workspace。

在反馈给用户的设计契约中说明所选范围，让用户清楚最终效果。切勿仅因页面不是首页，就推断它是对话页面；设置和系统页面不得继承任务插画。使用 workspace 时，应在对话文字后方加上更强的遮罩，确保长篇内容和代码清晰可读。

不要默认使用深色模式。根据用户的明确要求或参考图的亮度选择模式。风格不明确的编辑、花卉、肖像、文具、生活方式、效率和柔和粉彩主题，默认使用浅色模式。

Gate 2：记录原生契约

在相同视口下检查未经修改的运行中应用，并记录以下内容的证据：

• 首页标题、原生建议卡片、项目选择器和编辑器
• 已填充内容的对话和活动行
• 设置和个人资料页面
• 个人菜单、下拉菜单、对话框和工具提示
• 附件、文件卡片、已更改文件／差异和输出面板
• xterm 挂载前后的终端
• 侧边栏的闲置、悬停、选中、项目悬停、长标题和行操作状态
• 窄屏和宽屏下的页眉操作

除非设计契约明确允许更改，否则应将几何结构、可见性、点击目标、键盘焦点和仅悬停时显示的操作视为不可变项。

Gate 3：搭建正确的骨架

从已安装的技能目录运行：

npx tsx scripts/scaffold-theme.ts \
  --id <safe-slug> \
  --name "<display name>" \
  --layout-mode <native-background|native-immersive|editorial-showcase|palette-only> \
  --background-scope <home|workspace> \
  [--art /absolute/artwork.png]

默认源位置为 ~/.codexthemes/themes/<safe-slug>/。始终使用此受管理的主题库，除非用户明确要求其他位置；只有在这种情况下才传入 --output /absolute/theme-parent。切勿仅因当前工作区可写就使用它。

切勿以复制使用其他布局模式的完整主题作为起点。

Gate 4：分层、可控地实现

按以下顺序构建 CSS：

1. 语义令牌
2. 外壳表面
3. 精确限定路由范围的背景
4. 原生组件根节点
5. 交互状态
6. 非交互装饰
7. 响应式和减少动态效果规则

克制适用于几何和交互，而非覆盖范围：实现契约所要求的每种表面材质和装饰元素（参见 playbook 的装饰菜单）。在 balanced 或 rich 密度下，仅替换背景，却不处理原生卡片、编辑区、侧边栏、页眉、排版和滚动条的主题，都是未完成的。使用稳定的角色、测试 ID、已验证的组件类，以及范围严格的 :has(...)。存在结构钩子时，避免使用局部化文本选择器。

绝不要对 aside *、main *、通用 svg 或宽泛的后代元素组应用宽泛的 opacity、display、visibility、position、overflow 或 color 覆盖。绝不要使用后代元素上的 opacity: 1 来修复对比度；这会显示隐藏的行操作。

为每条分隔线、轮廓、侧边栏边缘、卡片边界和页眉边界指定唯一的所有者。使用纯色且易读的页眉表面；渐变和图案应置于内容后方，而非低对比度的工具栏控件后方。所有装饰都应位于原生控件下方，并设置 pointer-events: none。

对于浅色主题，除非契约有意定义对比面板，否则设置、菜单、对话框、输出／差异面板、代码表面和终端宿主都应采用相同的浅色语义系统。终端宿主、xterm 视口和 xterm 屏幕应一起设置主题。

更改表面的背景并不会改变其文本样式。原生应用（尤其是在深色模式下）会为许多后代显式设置浅色文本颜色，而 main、aside 或 header 上继承的 color 永远无法覆盖显式设置的后代颜色。每当背景的亮度反转时（浅色主题应用于原生深色模式，或反之），都要覆盖这些后代元素上的文本令牌，包括消息正文、Markdown 内容、列表项、按钮和标签，而不只是容器。这是主题发布后无法阅读的最常见原因。

应在异步解码大型图案前安装样式表，避免冷启动时先闪现原生页面，再跳转到不同布局。

每次可见更改后都要递增清单版本。

Gate 5：应用前验证

运行：

npx tsx scripts/validate-theme.ts /absolute/theme-directory

修复所有错误。警告在根据设计契约检查之前都应视为未解决。静态验证不能替代视觉验证。

在 1440x900 和窄视口下生成自包含预览。将预览保存到 ~/.codexthemes/themes/<theme-id>/previews/（脚手架已创建此目录）；绝不要写入工作区或暂存目录。每张预览都应标注为设计预览，绝不能标注为已验证的 Codex 截图。

每张预览都必须在同一画面中展示完整的主题工作区，包括侧边栏、页眉和主页内容；绝不能只展示背景图案。将主要桌面预览保存为栅格文件（PNG、JPEG 或 WebP；例如 previews/home-1440x900.png）：它将成为 codexthemes.ai 上的主题图库图片和详情图片。完成 Gate 6 验证后，用应用主题的真实截图替换它。

Gate 6：应用并验证真实应用

应用主题或重启 Codex 前，先征得明确许可。使用此技能自带的可逆 TypeScript 运行时；不要查找或优先使用外部主题程序。

如果 Codex 已公开本地调试端点，则无需重启即可应用：

npx tsx scripts/apply-theme.ts apply /absolute/theme-directory

如果不存在端点，则明确征求重启 Codex 的许可，然后使用独立启动器：

npx tsx scripts/apply-theme.ts apply /absolute/theme-directory --launch

当没有端点处于运行状态时，--launch 会打印 {"status": "scheduled"}，并将退出 → 重新启动 → 注入这一流程交给一个脱离进程的辅助程序，该程序会在重启后继续运行。这是必需的，因为托管在 Codex 内的 Agent 会随 Codex 一同退出；当前工具调用（也可能包括会话）可能会被重启中断。切勿自行绕过重启：不要编写 shell 封装脚本、launchd 或计划任务、脚本副本，或任何其他重新启动机制——--launch 辅助程序已经能够在重启后继续运行。

启动器支持 macOS 和 Windows（在 Windows 上，它会定位 Codex/ChatGPT 可执行文件，使用 taskkill 优雅地关闭它——绝不使用 /F——并使用调试标志重新启动；如果检测失败，请通过 --app 传入完整的 .exe 路径）。如果 Windows 重新启动后端点始终没有出现，说明该安装版本（例如 Microsoft Store 软件包）丢弃了调试标志——请如实说明这一限制，并继续完成源码、预览、验证和打包；切勿修改 WindowsApps 下的文件。

"scheduled" 不代表成功。Codex 恢复运行后，报告任何内容之前都要先验证：

npx tsx scripts/apply-theme.ts status

status 会探测每个正在运行的 Codex 页面，只有在样式元素确实位于 DOM 中时，才会报告 "active" 以及注入的主题 ID。如果报告 "inactive"，请读取 ~/.codexthemes/state/launch.log，查看辅助程序的结果和错误。

如果成功应用后旧主题仍不断重新出现（先前任务的过期会话仍在重新注入该主题），请先征得用户同意重启，再通过 apply ... --launch --relaunch 强制干净地重新启动——绝不要要求用户手动退出应用，也不要自行设计重启机制。

如需日后通过一条命令在已完成的主题之间切换，请交由 codex-theme-switcher skill 处理；此 skill 的应用运行时用于创建过程中的 QA。

启动器会将调试绑定到 127.0.0.1，只注入自有的 <style> 元素和 CodexThemes 页面标记，不会修改已签名的应用程序包，并会在当前应用会话中保持主题生效，即使遇到 SPA 路由切换和渲染器重新加载也不例外。完全退出应用后，需要重新应用主题（同样使用 --launch）。随时可以通过以下方式还原：

npx tsx scripts/apply-theme.ts restore

如果当前平台无法独立应用主题，请完成源码、预览、验证和打包。如实说明应用方面的限制；切勿悄悄改用其他已安装的注入器。

每次应用后（无论是热切换还是重启后应用），都要立即运行自动化可读性门槛检查，且在此之前不要做任何其他操作：

npx tsx scripts/qa-contrast.ts

如果可见文本无法辨读，该检查会硬性失败（退出码为 1），并使用两种独立的测量方法：针对已验证不透明背景的计算样式组合，以及真实截图像素（pixelFailures）；后者也会评估位于图像内容和透明图层上的文本。fail 表示主题当前不可读：在进行其他操作之前，修复文本令牌或图像遮罩（或切换回之前的主题），绝不要让未通过检查的主题保持启用，也绝不要报告它已成功应用。pass 是必要条件，但并不足够；请继续完成完整的矩阵测试：

qa-contrast.ts 特意按路由进行局部检查：它只会采样运行时已挂载且可见的内容。主页上的通过结果不能说明设置页面或尚未挂载的终端也通过了检查。对于会改变组件的主题，请导航并在主页、包含代表性内容的一条对话、卡片/选择控件可见的设置页面，以及 xterm 挂载后的终端上重新运行该检查。分别记录每条路由的结果；绝不要将某条路由的通过结果当作整个矩阵的依据。 当根令牌看起来正确，但某个组件仍使用原生调色板时，请检查组件根元素的内联 style 和本地声明的自定义属性。当前 Codex 构建会为设置控件和终端创建本地令牌孤岛；组件自身的声明优先于继承的根令牌。请修正已确认的组件根元素（例如 [data-codex-terminal="true"]）以及任何颜色由内联样式指定的视口，并使用范围严格限定的 !important，然后重新测试现有的已挂载实例和新挂载的实例。

分别验证：

• 结构：原生侧边栏、卡片、项目选择器、编辑器、任务内容、设置和终端均正常工作
• 范围：首页和对话插画仅出现在约定的位置
• 调色板：所有更改后的界面区域都属于同一套语义系统
• 模式独立性：完整的原生 --color-token-* 扫描结果均已包含，因此无论用户的 Codex 以原生浅色模式还是深色模式启动，主题的呈现效果都一致（参见操作手册中的原生令牌扫描）
• 状态：空闲、悬停、选中、禁用、焦点可见、加载中、运行中、已展开和打开
• 几何：无裁切、溢出、重复边框、文本与图标重叠或侧边栏操作冲突
• 生命周期：冷启动、路由切换、渲染器重新加载、主题切换、恢复和重新应用

捕获真实截图，并记录计算样式和几何信息作为证据。构建成功、注入标记、静态模型图或一张首页截图都不代表任务完成。P0 检查失败时，请修正选择器或令牌归属，并重新运行完整测试矩阵，而不是添加紧急覆盖规则。

Gate 7：通过签核后再打包

仅打包已验证的本地文件。.codex-theme 包必须是 UTF-8 JSON，不得包含绝对路径、外部 CSS 资源、脚本、跟踪代码、机密或私有引用，且大小不得超过 30 MB。请遵循 references/theme-schema.md。

使用以下命令导出可分享的包：

npx tsx scripts/export-theme.ts ~/.codexthemes/themes/<theme-id>

默认输出路径为 ~/.codexthemes/exports/<theme-id>.codex-theme。请勿将导出包放在项目工作区或可编辑的主题源文件中。仅在用户明确要求使用其他导出目录时才使用 --output。

导出包会嵌入工作区预览图（manifest 中的 preview，或 previews/ 中效果最佳的栅格图像），codexthemes.ai 会将其用作图库和详情页图片。导出前，请确认该图片展示的是应用主题后的工作区（包含侧边栏），而非原始插画；若替换为已验证的截图，请重新导出。

请使用用户提供的素材来创建、应用、验证和导出主题。不要调查素材的所有权、要求更换插画，也不要因为主题涉及游戏、电影、动漫、公众人物、品牌或其他第三方作品而阻止本地打包。不要作出法律结论，也不要声称用户拥有这些素材。

导出后，向用户提供以下两种提交方式：

1. 手动提交：将 .codex-theme 包和清晰的预览图提交至 https://codexthemes.ai/submit。
2. Agent 辅助提交：告知用户可以回复类似 Use $codex-theme-submitter to submit ~/.codexthemes/exports/<theme-id>.codex-theme to codexthemes.ai 的提示词；如果未安装 $codex-theme-submitter，可以运行 npx skills add codexthemes/skills --skill codex-theme-submitter -g -a codex 添加。

说明提交流程会要求上传者确认其有权分享这些素材；将此确认留给用户和提交流程处理。除非用户提出要求，否则不要代为提交。

完成标准

拒绝几近完成的主题。首页再精致，也无法弥补对话、设置、菜单、终端、侧边栏状态、窄窗口或冷启动中的问题。请分别报告已设计、已静态验证、已应用、已通过视觉验证和已打包的内容。务必报告规范源文件路径和导出路径。