mcpField
C
codex-theme-finder

codex-theme-finder

github.com/codexthemes设计与 UI7222 次安装15 周前更新
代码仓库

关于 codex-theme-finder

codex-theme-finder 是用于搜索 CodexThemes 已发布主题库的技能，可展示候选主题、预览和后续操作。它会区分可安装包、需手动下载的归档和设计参考。

主要功能

  1. 01搜索已发布的主题库
  2. 02在免费额度内免 API 密钥搜索
  3. 03展示主题详情与预览
  4. 04区分安装包、归档和皮肤
  5. 05引导安装主题或重建外观

适用场景

  1. 01按风格、主题或氛围查找主题
  2. 02比较图库结果后再选择
  3. 03寻找可供重建的视觉参考

安装

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

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

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

包含的文件

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

agents/
openai.yaml
references/
search-api.md
scripts/
apikey.ts
find-themes.ts
paths.ts
self-test.ts

详细介绍

在 CodexThemes 上查找 Codex 主题

搜索 codexthemes.ai 上已发布的主题画廊。此技能独立运行：其 TypeScript 脚本负责搜索请求和 API 密钥存储。它不会创建、安装或提交主题——这些工作由 codex-theme-creator、codex-theme-installer 和 codex-theme-submitter 负责。所需的本地工具只有 Node.js 20+ 和 npx。

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

第 1 步：搜索

将用户的请求转化为简短的搜索词（风格、主题、氛围——例如 dark anime、pastel floral light），然后运行：

npx tsx scripts/find-themes.ts <terms...> [--limit <1-50>] [--page <n>] [--sort <popular|newest|name>]

在免费匿名配额内，无需 API 密钥即可搜索，因此不要一开始就要求提供密钥。如果已配置密钥（CODEXTHEMES_API_KEY 环境变量或 ~/.codexthemes/credentials.json），脚本会自动发送密钥以获取更高的限额；输出中的 auth 字段会显示使用了哪种模式。

如果第一组结果不多，请使用不同的搜索词进行多次搜索，但绝不要重复相同的查询。

第 2 步：展示结果

展示最匹配的结果——如果画廊中有多个候选项，就展示几个（最多 5 个），而不只是第一个结果；在得出只有一个匹配项的结论前，先进行一两次更宽泛的搜索。对于每个推荐主题，请展示：id、名称、作者、简短描述、公开的 url（即其 codexthemes.ai 详情页——务必包含，方便用户在浏览器中查看主题），以及预览图片。每个结果都带有一个 image URL：请将图片下载到临时文件，并向用户展示该本地图片——不要在聊天 Markdown 中直接引用远程 URL，它经常无法正常显示。如果结果没有图片，请写明“无预览”，不要显示损坏的嵌入内容。请让主题 id 保持可见——codex-theme-installer 需要它。

结果分为三类——请检查 kind 和 installable（每个条目的 guidance 字段也会说明后续步骤）：

  • installable: true — .codex-theme 包；codex-theme-installer 可以一键安装。
  • kind: "theme"、installable: false — 归档包（zip）。无法由 Agent 安装：请引导用户前往 url 登录、下载归档并手动安装。
  • kind: "skin" — 不含主题包的设计参考。分享 url，并提出可以用 codex-theme-creator 重新创建此风格。

如果没有结果，请如实告知，并建议使用更宽泛的搜索词，或提出用 codex-theme-creator 创建自定义主题。

第 3 步：提供安装选项——绝不要只列出结果就结束

找到主题并非终点；请根据每个结果的类型，提供相应的后续操作：

  • 有多个可安装候选项 → 询问用户想安装哪一个，例如：“回复一个主题 id（例如 shaolin-kickoff），我就会安装并应用它。”
  • 恰好有一个合适的可安装结果 → 直接向用户提供安装选项：“回复 install，我就会安装并应用 <id>。”
  • 只有归档主题（installable: false）→ 提供其 url，并说明用户可以在那里登录以下载归档并手动安装。
  • 皮肤（kind: "skin"）→ 提供其 url，并提出：“我可以用 codex-theme-creator 将这种风格重新创建为可安装主题——需要我这么做吗？”

用户作出选择后，将任务交给 codex-theme-installer（如果尚未安装，请像本技能最初安装时那样引导安装：npx skills add codexthemes/skills --skill codex-theme-installer -g -a codex）；随后，安装程序会继续通过 codex-theme-switcher 激活主题。绝不要只给出结果列表，却不提供安装方式就结束对话。

第 4 步：处理配额和速率限制

遇到 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 时，表示配置的密钥无效或已撤销——引导用户以相同方式创建新密钥。

评论

支持 Markdown