Codex Skin 如何工作

Codex Skin 会把一套已发布主题的六位 ID，转换成当前 Codex 窗口中经过验证的外观。网站、公开插件、签名本地 Helper、data-only 主题包与官方 Codex adapter 分担不同职责。任何一层都不能自行授予访问权、执行主题代码，或把中间状态当作成功。

本页只说明公开系统边界，不会公开私有 selector、签名私钥、Production 存储路径、客户数据和管理配置。

一次主题请求经过哪些环节

用户在 Codex 任务中发出请求
  -> Skill + 固定 wrapper
  -> 网站/API 完成授权和主题交付
  -> 经过验证的 Bootstrap/Helper
  -> 签名 data-only 主题包
  -> 通过短时 loopback 控制官方 Codex
  -> 可见验证
     -> 提交成功，或回滚

用户先从图库取得真实 ID，Skill 会把该 ID 作为独立参数。网站核对设备，并在 Pro 主题请求中核对当前访问期。Helper 只有在发布产物和主题包内容都通过校验后才会继续。它随后操作一个身份明确的官方 Codex 实例，检查最终可见结果，只在结果与请求一致时记录成功，然后退出。

浏览器授权与 Pricing 都是同一事务中的条件分支。callback 页面、本地文件、缓存包和可编辑客户端状态都不能自己授予 Pro access，付款与访问权来自经过验证的服务端事实。

组件与职责

组件	负责	不负责
网站与 API	主题目录、网页 session、设备批准、访问判断、短时交付	本地渲染、任意 Helper 命令
插件、Skills 与 wrapper	受支持意图、六位 ID、提醒与确认、结构化结果	开放式 Shell 执行、服务端权益
Bootstrap 与 Helper	已验证本地二进制、授权 client、包校验、有限事务、Restore	后台重复应用、主题自带代码
主题包	manifest、白名单设计数据、声明的本地图片	CSS、JavaScript、selector、Shell、可执行文件
Adapter	官方身份、loopback 目标、能力探测、固定 renderer 映射	未知进程、浏览器或未验证区域

网站与 API

网站发布主题目录与公开预览。需要交付受保护主题包时，网站负责 browser session、设备批准、服务端访问判断和短时主题响应。Free 与 Pro 主题包都只会交付给经过授权的插件设备。

Pro 状态由经过验证的支付与 access 记录决定。签名支付商事件创建或改变访问期，浏览器成功页不能做到这一点。API 可以判断当前请求能否下载主题包，但不能向 Helper 下发任意 CSS、selector 或本地命令。

插件、Skills 与 wrapper

公开插件把自然语言请求收敛到少量固定操作：version、按六位 ID 应用或切换、本地 status 与离线 Restore。Skill 会显示 20–60 秒窗口勿动提醒，解释浏览器批准，在确实需要时请求明确的重启确认，并报告稳定结果。

wrapper 只用固定参数调用固定外部 Helper。用户文字、网页内容与主题数据不会被插入通用 Shell 命令。自定义 API origin、包路径、下载 URL、selector、CSS、JavaScript 和 Shell 片段都不属于支持面。

Bootstrap 与 Helper

插件钉住 release-tagged Bootstrap launcher 与对应平台 SHA-256。launcher 只从固定公开 GitHub Releases 路径获取预期文件，随后核对签名 descriptor、平台、大小、digest 与 Helper 自检，全部通过后才激活候选。

Helper 是自包含产物，用户无需安装 Node 或 Go。它处理设备授权、主题下载验证、事务状态、原生外观备份、Apply、可见验证、回滚、本地状态与 Restore。状态与恢复引擎位于可替换插件缓存之外。

每次应用、切换或 Restore 都是一笔有限的按需 Helper 操作，不是 daemon、托盘应用、登录项或后台 controller。

主题包

主题包包含带版本的 manifest，以及声明的本地 PNG、JPEG 或 WebP 资产。签名 descriptor 会绑定六位 ID、主题版本、包或 manifest digest、大小、schema 与验证 key 信息。引擎还会检查路径、MIME、hash、声明文件和数据字段。

主题包不能提供可执行渲染逻辑。CSS、JavaScript、Shell、PowerShell、selector、远程执行 URL、路径穿越、符号链接和未声明文件都会被拒绝。

Adapter 与官方 Codex

危险操作前，adapter 会核对官方 Codex 应用、进程、用户 profile、renderer marker 与 loopback CDP endpoint。它不会连接任意浏览器或未知进程。身份或所需能力无法确认时，操作会 fail closed。

adapter 会把 Helper 持有的固定模板与白名单设计数据映射到受支持 Codex 区域。对话专用原图和颜色只作用于经过验证的 Home、对话与输入表面，原生工具页面继续使用匹配的官方浅色或深色 palette。

设备授权与凭据

网页登录与本地插件授权有关联，但不是同一个凭据边界。浏览器批准页会显示要授权的电脑与平台。用户批准后，原插件事务继续。

插件 Access Token 只保留在内存中，轮换的 Refresh Token 存入 macOS Keychain 或 Windows Credential Manager。公开 Helper 不会把凭据内容写入普通状态文件、命令参数、环境变量或日志。

本地状态可能显示 deviceLinked: true，它只说明本机存在设备引用，不能证明当前网页 session 已登录、服务器仍接受该设备或 Pro access 有效。这些检查会在下一次受保护主题操作中重新进行。

应用事务

validate -> stage -> backup -> apply -> verify -> commit
                 \                         /
                  -------- rollback ------

Validate

Helper 会核对设备与访问判断、包签名与内容、官方 Codex 身份、loopback endpoint 和所需界面能力。这里失败不会触碰当前外观。

Stage

通过验证的主题包会下载并解包到受限 staging 区域，不会被当成可执行输入。

Backup

第一次发生视觉变更前，Codex Skin 会保存首次 Apply 前准确的原生外观选择：system、light 或 dark，以及相关原生 code-theme 设置。恢复点位于插件缓存之外，一直保留到 Restore。

Apply

深色皮肤会让 Codex 原生外观匹配 dark，浅色皮肤匹配 light。如果原生模式已经一致，Helper 不会重写或重启；受信任窗口中的同模式主题替换可以直接完成。

macOS 深浅切换会优先使用经过验证的应用内 Appearance 路径。若在变更前发现该合同不存在，可以退回一次明确确认的受控重启。Windows 当前在跨模式时继续使用确认重启路径。主题自身不能控制其中任何一种方式。

Verify 与 commit

Helper 会在当前官方 renderer 中核对请求的 public ID、版本和必要视觉 marker。只有这些结果通过，事务才提交成功。Apply 或验证失败时，会恢复上一个已验证状态或已保存官方外观，不留下半应用状态。

为什么必须以可见验证作为成功边界

很多有效中间事件都不能证明用户已经看到请求的主题。API 返回 200、主题包下载完成、样式层插入成功或重启已获同意，都不是最终结果。

直接操作的成功结果需要同时包含 ok: true、请求的 themePublicId、themeVersion 和 operationId。受控重启路径必须让 status 到达 completed，并且 ID 与版本一致。desired、downloaded、pending_confirmation、restart_approved 和 running 都不是成功。

本地历史也有同样限制。appliedThemePublicId 表示上一笔有限事务曾经通过可见验证并提交，不能证明完全退出或 renderer reload 后新建的 renderer 仍带主题。

失败、回滚与 Restore

失败后的结果取决于事务停在哪里：

在变更前发生下载、descriptor、签名、hash、内容、身份或能力错误，不会触碰当前外观
发生变更后失败，会使用事务备份恢复上一个已验证状态或官方外观
无法确认进程、renderer 或归属时，会停止新 Apply，而不是继续猜测
稳定错误码只给一个下一步，不会暴露 Token、存储 key、stack trace 或敏感本地路径

离线 Restore会移除皮肤，并恢复首次应用前保存的准确原生外观。它不依赖网络、登录、有效 Pro、Node 或插件缓存。Apply 失败、访问到期、退款确认或插件被移除后，这条本地恢复路径仍然存在。

会话边界与本地状态

当前 Paid Alpha 使用 one-shot 事务。Apply、切换或 Restore 结束后，Helper 会退出，不存在标记为 active 的 runtime、heartbeat keeper、Guardian 或静默重新注入主题的 service。

完全退出 Codex、重启电脑或后续 renderer reload 会结束当前可见保证。用户可以再次让插件应用主题。最后一次验证状态与缓存外恢复点仍是有用的本地事实，但不能保证当前 renderer 仍然带主题。

架构刻意排除的做法

Codex Skin 不接受任意主题代码、远程命令、自定义 origin 或用户提供的 selector。为了让主题长期驻留，它也不会安装常驻 MCP、系统 service、daemon、托盘/菜单栏应用、登录项或开机注入器。

系统不会修改官方 Codex 应用包、app.asar、代码签名、WindowsApps 文件或受保护系统目录。

默认情况下，产品与 Helper 记录不包含提示词、对话、源码、项目文件、本地绝对路径、Token、Cookie 和截图。交付与支持所需的有限记录使用标识符、版本、时间戳、字节数、结果和稳定错误，不读取工作区内容。