mcpField
C
codex-theme-installer

codex-theme-installer

github.com/codexthemes设计与 UI71.7k 次安装14 周前更新
代码仓库

关于 codex-theme-installer

codex-theme-installer 用于下载并安装 CodexThemes 上发布的 Codex 主题。它会先验证主题包再写入本地，并通过 codex-theme-switcher 继续激活。

主要功能

  1. 01下载已发布的主题
  2. 02验证包格式与内容
  3. 03在本地安装主题文件
  4. 04管理 API 密钥与配额
  5. 05继续激活主题

适用场景

  1. 01安装指定的 CodexThemes 主题
  2. 02更新已安装的主题
  3. 03处理下载配额或密钥错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/codexthemes/skills --skill codex-theme-installer

安装后在 Claude Code 中输入/codex-theme-installer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
download-api.md
scripts/
apikey.ts
install-theme.ts
paths.ts
self-test.ts

详细介绍

从 CodexThemes 安装主题

从 codexthemes.ai 下载已发布主题的便携包，并将其源文件解压到 ~/.codexthemes/themes/<theme-id>/。此技能独立运行：其 TypeScript 脚本负责下载、验证和本地安装。它不会搜索图库（codex-theme-finder）、创建主题（codex-theme-creator）或提交主题（codex-theme-submitter）。应用主题由 codex-theme-switcher 负责，但安装成功后会直接衔接该步骤（步骤 4）；只安装文件后就停止，不算完成任务。所需的本地工具只有 Node.js 20+ 和 npx。

在诊断意外的 API 响应或更改端点行为前，请先阅读 references/download-api.md。所有命令都从已安装的技能目录中运行。

步骤 1：确定主题

将要安装的主题解析为主题 ID——即 codex-theme-finder 结果中的小写 slug，或 https://codexthemes.ai/themes/<theme-id> URL 中的 ID。脚本接受这两种形式。如果用户只描述了风格，没有指定主题，请先使用 codex-theme-finder 查找候选主题，不要猜测 ID。

步骤 2：安装

npx tsx scripts/install-theme.ts <theme-id | codexthemes.ai theme URL> [--force]

在免费匿名配额内，无需 API 密钥即可下载，因此不要一开始就要求用户提供密钥。如果已配置密钥（CODEXTHEMES_API_KEY 环境变量或 ~/.codexthemes/credentials.json），脚本会自动发送该密钥，以获得更高的限额。

脚本会先验证下载的包（格式、架构版本、主题 ID 是否匹配、安全的相对文件名、≤30 MB），然后才写入任何内容；接着将 theme.json、样式表、插图和 readme 解压到 ~/.codexthemes/themes/<theme-id>/。如果目标主题目录已存在且非空，脚本会拒绝覆盖；只有在用户确认要替换本地副本后才能传入 --force——该目录中可能包含用户自己的修改。

更新已安装的主题：已发布的主题会在 codexthemes.ai 上原地更新，因此当用户要求更新、升级或重新下载已安装的主题时，请使用 --force 重新安装——更新请求本身即表示确认，除非本地副本包含用户所做的修改（此时应先提醒用户）。文件写入后，继续执行步骤 4，让正在运行的应用实际切换到新版本；对同一主题 ID 进行热切换会重新注入更新后的 CSS。

步骤 3：处理配额和速率限制

遇到 HTTP 429 或 402 时，表示免费配额已用尽；脚本的错误消息会包含任何 Retry-After 值。不要循环重试。告知用户免费下载配额已用完，并指导其配置个人 API 密钥：

  1. 在 https://codexthemes.ai/settings/apikeys 创建密钥。
  2. 存储密钥：printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set（通过 stdin 输入可避免将密钥写入 shell 历史记录；也可以使用 apikey.ts set <key>）。
  3. 重新运行安装。

使用 npx tsx scripts/apikey.ts status 检查当前密钥状态；使用 npx tsx scripts/apikey.ts clear 删除已存储的密钥。绝不要输出完整密钥（脚本只会显示掩码形式），绝不要将其写入项目文件，也绝不要提交它。

遇到 401/403 时，表示已配置的密钥无效或已撤销——请指导用户以相同方式创建新密钥。遇到 404 时，表示该主题 ID 不存在；请使用 codex-theme-finder 重新检查 ID。

第 4 步：激活主题，或告知用户下一步该如何回复

用户提出安装请求，意味着他们想在 Codex 中看到主题，而不只是保存主题文件。报告已安装路径（~/.codexthemes/themes/<theme-id>/）、主题版本和写入的文件，然后直接使用 codex-theme-switcher 继续激活。如果尚未安装 codex-theme-switcher，请用与引导此技能相同的方式安装（npx skills add codexthemes/skills --skill codex-theme-switcher -g -a codex）。

  • 如果 Codex 已开放调试端点，立即使用切换器的 switch-theme.ts apply <theme-id> 热切换，并通过 switch-theme.ts status 验证——热切换可撤销，除了安装请求本身，无需额外确认。
  • 如果激活需要重启 Codex，请勿悄悄重启，也不要只说“已安装”就结束。结束时应告知用户继续操作所需的确切回复，例如：“回复 apply，我将重启 Codex 以激活 <theme-id>。”用户回复后，按照切换器的 --launch 流程操作。

绝不要只以“文件已安装，但未应用”结束对话，却不给出可执行的下一步；也绝不要在切换器的 status 报告 active 之前声称主题已激活。

评论

支持 Markdown