codex-theme-submitter

向 CodexThemes 提交主题

将现有且已导出的 .codex-theme 包，或从 URL 提取的主题展示页（皮肤）链接，提交至 codexthemes.ai。此技能可独立使用：其 TypeScript 脚本负责 API 密钥存储和提交。它不会创建、编辑、验证或导出主题源文件——这些是 codex-theme-creator 的职责。本地只需安装 Node.js 20+ 和 npx。

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

根据用户分享的内容选择路径，而不是根据磁盘上已有的内容选择：

• 导出的 .codex-theme 包或本地主题 ID → 包提交，执行步骤 1–5。
• 主题展示页的 URL（仓库、图库、帖子）→ 链接提交，参见“从 URL 提交主题链接”。链接提交不需要包、导出文件或本地主题源文件——绝不要在 ~/.codexthemes/exports/ 中搜索匹配项，绝不要先要求用户导出包，也绝不要因包“缺失”而阻止提交。仅当用户明确表示希望发布可安装的包时，才对 URL 分享使用包提交路径。
• 没有具体内容（“提交我的主题”）→ 先在本地查找，再询问：
  1. 列出 ~/.codexthemes/exports/*.codex-theme。如果恰好有一个包，报出其名称（ID、版本、修改时间），并确认是否提交这个包。如果有多个，列出它们并询问要提交哪一个。
  2. 如果没有导出包，但 ~/.codexthemes/themes/ 中有主题源文件，告诉用户有哪些源文件，并提供两个选项：使用 codex-theme-creator 导出一个主题并提交该包，或分享主题页面的 URL 以提交链接。
  3. 如果本地什么都没有，询问要列出的主题 URL（链接提交），或告知用户先使用 codex-theme-creator 创建主题。 根据具体查找结果一次性询问；绝不要猜测用户指的是哪个主题，也绝不要在多个主题中擅自选择一个。

步骤 1：查找包

只提交可移植的 .codex-theme 包。托管导出位置为 ~/.codexthemes/exports/<theme-id>.codex-theme。

• 如果用户指定了包路径，使用该路径。
• 如果用户指定了主题 ID 或源目录，在 ~/.codexthemes/exports/ 中查找匹配文件。
• 如果不存在包，停止操作并告知用户先使用 codex-theme-creator（export-theme.ts）导出一个。绝不要手动拼装包 JSON，也不要提交原始主题源文件。
• 包中必须嵌入 preview——一张显示侧边栏的工作区截图；它会成为 codexthemes.ai 上的图库图片和详情图片。submit-theme.ts 拒绝提交缺少该内容的包（图库会显示原始背景图）。要修复此问题，可在主题的 previews/ 目录添加截图后，使用 codex-theme-creator 重新导出；也可以在提交时传入 --preview /absolute/screenshot.png，提供完整应用截图。绝不要将主题背景图作为 --preview 传入；--allow-art-preview 仅用于用户明确接受将背景图用作图库图片的情况。
• 仔细检查即将公开的确切预览图。真实的 Codex 截图通常会在侧边栏和工作区中显示账户显示名称、仓库名称、项目名称、任务标题、文件路径、源附件或对话文本。如果其中任何信息可能属于隐私内容，请在上传前停止，并提供经过脱敏的完整工作区截图，或已生成且使用通用内容的设计预览。向用户展示选定的图片并征得确认；成功的试运行无法检测图像像素中隐含的语义隐私泄露。

不要调查图稿的所有权，也不要因图稿所描绘的主体而阻止提交。提交页面和 API 会要求上传者确认其拥有分享权限；将此确认留给用户和服务器处理。

第 2 步：确保 API 密钥已配置

检查本地是否已配置 CodexThemes API 密钥：

npx tsx scripts/apikey.ts status

密钥优先从 CODEXTHEMES_API_KEY 环境变量读取，其次从 ~/.codexthemes/credentials.json 读取。

如果尚未配置密钥，请勿猜测或编造密钥。请引导用户前往以下地址创建 API 密钥：

https://codexthemes.ai/settings/apikeys

然后保存用户提供的密钥：

printf '%s' "<api-key>" | npx tsx scripts/apikey.ts set

优先使用 stdin 方式，以免密钥进入 shell 历史记录；也可以使用 apikey.ts set <key>。绝不要向用户完整显示密钥（脚本只会显示掩码形式），绝不要将密钥写入项目文件，也绝不要提交密钥。使用 npx tsx scripts/apikey.ts clear 删除已保存的密钥。

第 3 步：使用试运行进行预检

在不发起任何网络请求的情况下，验证软件包和配置：

npx tsx scripts/submit-theme.ts /absolute/path/<theme-id>.codex-theme --dry-run

试运行会确认软件包可解析为有效的 codex-theme 文档（格式、架构版本、清单 slug 和版本、非空 CSS、≤30 MB），报告解析出的端点和密钥是否已配置，并报告图库 preview 状态——present（来自软件包或 --preview 覆盖项），或者警告提交将回退到原始作品并被拒绝。提交前修复所有报告的问题；如果软件包本身无效，请让用户返回 codex-theme-creator 重新导出，不要手动编辑软件包。

第 4 步：提交

API 是 Agent 提交的唯一途径。绝不要在浏览器中打开 codexthemes.ai/submit、操作浏览器扩展或填写网页上传表单——该表单的文件选择器是供用户使用的，无法用于自动化操作（Chrome 会阻止扩展访问文件）。如果 submit-theme.ts 执行失败或未配置 API 密钥，请如实说明并引导用户解决问题；不要改用网站表单。

提交后，主题会立即发布到 codexthemes.ai——没有审核队列。重新提交已发布主题的 id 是常规更新方式（递增 manifest.version、重新导出，再次提交）。上传前，请展示最终 id、版本、作者、确切预览图，以及发布会立即生效这一事实。请用户确认发布和预览图选择，然后运行：

npx tsx scripts/submit-theme.ts /absolute/path/<theme-id>.codex-theme \
  [--preview /absolute/workspace-screenshot.png]

脚本会将软件包作为 UTF-8 JSON，通过 Authorization: Bearer <key> 向 POST https://codexthemes.ai/api/themes/submit 发送请求。上传前，--preview 会用指定的完整应用截图替换软件包内嵌的图库预览图。只有在用户明确指定其他环境（例如 staging）时，才使用 CODEXTHEMES_API_BASE 覆盖基础 URL。

第 5 步：报告结果

成功后，主题会立即上线，响应中包含其详情页 URL（url，例如 https://codexthemes.ai/themes/<theme-id>）。务必向用户提供该链接，以及从响应中获取的已发布 id 和版本——如果请求的 slug 已属于其他提交者或内置项目，服务器会在 slug 后添加随机后缀进行发布，而不是覆盖原项目，因此最终 id/url 可能与提交的内容不同。使用同一个 API 密钥重新提交自己的主题 id，会原地更新已发布主题——请先递增清单版本，以便更改生效。

失败时，请如实报告 HTTP 状态码和服务器消息，然后采取相应措施：

• 401/403：密钥无效或已撤销。请使用从 https://codexthemes.ai/settings/apikeys 获取的新密钥，引导用户重新执行第 2 步。
• 其他错误：参见 references/submit-api.md。

绝不要循环重试失败的提交；除非脚本报告 "status": "submitted"，否则绝不要声称主题已提交。

从 URL 提交关联主题

当用户分享主题展示页面的 URL（仓库、图库页面或帖子）时，将其作为关联目录条目（皮肤）发布。此流程本身完整：不需要 .codex-theme 包、导出文件或本地主题源文件，而且绝不能停下来等待这些内容——提取出的名称、作者、预览图和 URL 本身就是完整的提交内容。

1. 提取：获取页面并提取主题名称、作者和最佳预览图——截取已应用主题的工作区（包含侧边栏和内容的窗口），优先选择 og:image 或 README/截图图片。绝不要使用单独的壁纸或徽标作为预览图。作者只能是显示名称（页面作者、仓库所有者或署名）：去掉 @用户名和任何括号中的 ID——数字探索者 (@slimeXDX) → 数字探索者——用户仍可通过源 URL 找到该用户名，而且脚本会拒绝包含 (@handle) 的作者。
2. 生成 slug 和标签：根据主题名称生成简短的小写 ASCII slug——它将成为公开 URL https://codexthemes.ai/skins/<slug>。将非拉丁字符名称音译或翻译（功夫女足 → kungfu-womens-football）；绝不要退回到时间戳 ID，也不要使用不相关的词语。还要根据页面和预览图生成 2–5 个简短的小写英文标签，用于描述风格、氛围和主题（例如 editorial, dark, minimal）——务必提供标签；标签用于图库筛选。
3. 下载预览图到临时文件（PNG、JPEG 或 WebP，大小低于 10 MB）。不要将其保存到项目工作区。
4. 在上传前征求用户确认：展示提取出的名称、slug、作者、标签、源 URL，以及将用作预览图的图片。允许用户更正任何字段。
5. 提交（需要 API 密钥，与步骤 2 相同；同样禁止使用网页表单）：

npx tsx scripts/submit-skin.ts \
  --name "<theme name>" \
  --slug <ascii-slug> \
  --source-url "<the user's URL>" \
  --preview /absolute/preview.png \
  --tags "<tag1, tag2, tag3>" \
  [--author "<display name>"] [--description "<one-line description>"] [--mode light|dark|mixed] [--dry-run]

6. 反馈结果：成功时，响应中会包含公开条目 URL（https://codexthemes.ai/skins/<slug>）——务必将该链接提供给用户，并使用响应中的链接：如果 slug 已属于其他提交者，服务器会使用带随机后缀的 slug 发布，而不是覆盖现有条目。使用相同 API 密钥重新提交自己的 slug，会原地更新已发布的条目。

如果页面没有可用的工作区预览图，请停止并让用户提供一张，而不是用插图替代或生成模拟图。