/xhs-cover-skill

name: xhs-cover
description: >
  Generate Xiaohongshu (XHS / RedNote) cover images using GPT Image 2 / Codex image generation first, with the legacy Gemini CLI as fallback.
  Triggers for cover generation: "生成封面", "小红书封面", "xhs封面", "制作封面",
  "帮我做张图", "XHS cover", "RedNote cover".
  Triggers for cover editing: "修改封面", "改一下封面", "上一张图基础上",
  "基于这张图调整", "不要重新做", "edit this cover".
  Triggers for style learning: "学习这个风格", "提取风格", "我想自定义风格",
  "这张图的风格", "learn this style", "extract style".
  Always trigger this skill when user mentions 小红书/XHS/RedNote together
  with 封面/cover/图片, OR when user uploads a reference image and asks
  about creating a similar style.
metadata:
  openclaw:
    requires:
      bins:
        - node
    primaryEnv: OPENAI_API_KEY
    emoji: "🎨"

小红书封面生成器

直接生成或修改小红书封面，优先使用 GPT Image 2 / Codex 图片生成能力。

• **官网**：https://xhscover.vivi.wiki（可在线预览所有风格效果图）
• **作者**：Vivi
• **支持风格**：18种预设风格 + 用户自定义风格
• **技术原理**：优先用 GPT Image 2 / Codex 图片生成或编辑，将你的人像照片/上一版封面 + 文字要求合成为封面图；Gemini 命令行脚本仅作为备用方案。

---

路径约定

本 Skill 的脚本位于 SKILL.md 所在目录。执行任何命令前，先确定 `SKILL_DIR`：

• **Codex（推荐）**：`~/.codex/skills/xhs-cover-skill`
• **Claude Code**：`~/.claude/skills/xhs-cover`
• **OpenClaw**：`~/.openclaw/skills/xhs-cover`

后续所有 `${SKILL_DIR}` 均指此路径，不要硬编码。

---

工作流入口

触发后，先判断用户意图：

• **生成封面**（默认）：用户想用已有风格生成封面 → 进入下方「执行流程」
• **修改封面**：用户对已生成封面提出排版、文案、比例、人物大小、颜色或局部风格修改 → 必须以上一张封面图作为输入图进行编辑，保留原图主体风格和构图，只改用户点名的部分；不要从零重新创造一张封面。
• **学习/提取风格**：用户上传了参考图，或说了「学习/提取/自定义风格」→ 跳到「风格学习工作流」
• **使用自定义风格**：用户说「用 XX 风格生成」且 XX 不在内置列表中 → 检查 `styles/` 目录是否有对应 JSON；有则使用，无则建议先运行风格学习工作流

---

执行流程

Step 0：优先使用 GPT Image 2

在 Codex 中，如果可以使用图片生成/编辑能力，默认使用 GPT Image 2 生成或编辑封面，不再优先调用 Gemini CLI。

输入要素：

• 人物照片：用户上传的图片，或给出的本地绝对路径。
• 上一版封面：当用户要求“修改/调整/在上一张基础上改”时，必须使用最近一次生成或用户明确指定的封面图作为编辑输入。
• 主标题：封面最大字。
• 副标题/小字：辅助说明，可拆成 1-3 行。
• 风格：映射到内置风格语义，例如 `hand-drawn-border` = 手绘边框/综艺活力感。
• 比例：默认小红书 3:4。

生成提示词模板：

使用用户提供的人物照片生成一张小红书 3:4 竖版封面。保持人物脸部身份和五官特征真实自然，不改变发型、妆容和服装主体。

风格：{风格中文描述}。
主标题：{主标题}
副标题/小字：{副标题}

排版要求：主标题最大、最醒目；副标题作为小字分行排版；文字清晰可读，适合手机信息流；不要添加除主标题和副标题之外的任何文字。

封面修改提示词模板：

基于用户指定或最近一次生成的小红书封面图进行局部修改，不要重新设计一张新图。保留原图的主体风格、构图、人物身份、边框、纹理、色彩气质和封面层次，只修改用户明确点名的内容。

本次修改要求：{用户修改要求}

如果涉及文字，必须严格使用用户给出的文案，中文准确、无错别字、无乱码；不要添加未要求的新文字。保持 3:4 竖版小红书封面比例，文字适合手机信息流阅读。

如果用户明确要求“xhs cover skill + GPT Image 2”，直接按本步骤生成。

以下 Gemini CLI 流程仅在 GPT Image 2 不可用、或用户明确要求命令行/API 生成时使用。

Step 1：检查配置（首次使用 Onboarding）

cat ~/.config/xhs-cover/config.json 2>/dev/null

**如果文件存在且有 `apiKey` 字段 → 跳到 Step 2。**

否则进入 Onboarding：

1a. 介绍 Skill

向用户展示以下介绍（用 markdown 格式输出，清晰美观）：

🎨 欢迎使用小红书封面生成器！

这个工具让你直接在命令行生成小红书封面，无需打开网站。
你只需要：一张人物照片 + 标题文字 → 即可生成封面。

📖 官网：https://xhscover.vivi.wiki
   （可在线预览18种风格的效果示例，帮你选择合适的风格）

👩‍💻 作者：Vivi

首次使用需要配置一次 API Key，之后每次直接生成。

1b. 选择 API 类型

> 💡 **OpenClaw 用户**：可跳过 Onboarding，直接在 OpenClaw 配置文件中设置环境变量： > ```yaml > skills: > entries: > xhs-cover: > env: > XHS_COVER_API_KEY: "你的 API Key" > XHS_COVER_BASE_URL: "https://generativelanguage.googleapis.com/v1beta/openai" > XHS_COVER_MODEL: "gemini-2.0-flash-exp-image-generation" > ``` > 设置后重启 OpenClaw 即可，无需走以下步骤。

用 AskUserQuestion 询问（**必须先问这个，再问 key**）：

**问题**："请选择 API 来源"

| 选项 | 说明 | |------|------| | Google AI Studio（官方） | 使用谷歌官方 API，有免费层级（无需绑卡），但图片生成是否免费请以官方定价页为准，需要科学上网 | | 第三方 API 代理 | 使用兼容 OpenAI 格式的第三方代理服务，无需科学上网，需提供 Base URL、API Key 和模型名称 |

1c. 根据选择收集 API 信息

**如果选择 Google AI Studio**：

向用户说明如何获取 API Key：

📝 获取 Google AI Studio API Key 步骤：
1. 访问 https://aistudio.google.com/apikey
2. 登录 Google 账号
3. 点击「Create API key」
4. 复制生成的 Key（以 AIza 开头）

注意：Gemini API 有免费层级，但图片生成功能是否免费以 https://ai.google.dev/gemini-api/docs/pricing 为准（Google 定价会随版本更新调整）。

用 AskUserQuestion 询问：

• **API Key**（必填，以 AIza 开头）

然后自动设定：

• `baseUrl` = `https://generativelanguage.googleapis.com/v1beta/openai`
• `model` = 当前支持图片生成的模型名（Google 会随版本迭代更新，可在 https://ai.google.dev/gemini-api/docs/models 查询最新名称）

**如果选择第三方 API**：

用 AskUserQuestion 一次性询问以下三项：

• **API Base URL**（必填，例如 `https://api.your-provider.com`）
• **API Key**（必填，由服务商提供）
• **模型名称**（必填，可向服务商确认支持的模型，推荐填写 `gemini-3-pro-image-preview`）

1d. 询问输出目录

用 AskUserQuestion 询问（可跳过用默认值）：

• **封面保存目录**（默认：`~/Desktop/XHS封面`）

1e. 保存配置

先运行：

mkdir -p ~/.config/xhs-cover

再用 Write 工具写入 `~/.config/xhs-cover/config.json`：

{
  "apiType": "google 或 third-party",
  "apiKey": "用户输入的key",
  "baseUrl": "对应的URL",
  "model": "对应的模型名",
  "outputDir": "用户输入或默认值",
  "defaultAspectRatio": "3:4"
}

写入后立即执行（保护 API Key 安全）：

chmod 600 ~/.config/xhs-cover/config.json

1f. 测试 API 连通性

node ${SKILL_DIR}/scripts/generate.mjs --test

• ✅ 成功 → 告知用户 Onboarding 完成，直接进入 Step 2
• ❌ 失败 → 告知错误原因，询问是否重新配置（Google 用户提示检查科学上网；第三方用户提示检查 URL 和 Key）

---

Step 2：收集生成参数

读取当前配置：

cat ~/.config/xhs-cover/config.json

用 **一次** AskUserQuestion 收集所有必要参数（已在命令中提供的跳过）：

必问项

**① 封面图片路径**（必填）

• 支持直接拖拽文件到终端，或粘贴绝对路径
• 提示：`支持 JPG/PNG，手机照片会自动修正方向`

**② 主标题**（必填）

• 封面最显眼的大字，例如：`如何用3个月学会Python`

选问项（用一个 AskUserQuestion，多选/可选）

**③ 副标题**（可选）

• 补充说明文字，例如：`零基础入门+项目实战`

**④ 其他备注**（可选）

• 对风格、构图的额外要求，例如：`人物占比大，标签加上：进阶虾、学习虾`

**⑤ 比例**（单选，默认 3:4） | 选项 | 说明 | |------|------| | 3:4（默认） | 小红书标准竖版，最常用 | | 1:1 | 正方形，适合头像或九宫格 | | 9:16 | 全屏竖版，适合视频封面 | | 4:3 | 横版，适合横构图人像 |

**⑥ 生成张数**（默认 1，最多 5）

---

Step 3：风格选择

用 AskUserQuestion 询问风格选择方式：

**选项 A：自动匹配**（推荐，根据你的标题内容自动选择最合适的风格）

**选项 B：从列表选择**（展示18种风格说明）

**选项 C：打开官网预览**（用户可先访问 https://xhscover.vivi.wiki 查看视觉效果，再回来输入风格ID）

---

如果选 A（自动匹配）：

根据主标题和副标题内容，按以下规则推荐 **1-2种** 最合适的风格，并简要说明理由，然后 AskUserQuestion 让用户确认：

| 内容类型 | 推荐风格 | |---------|---------| | 职场/职业/工作/汇报/升职/面试 | `professional-clean`、`workplace-big-text`、`professional-woman` | | 教程/干货/攻略/方法/步骤/指南 | `background-big-text`、`sticker-energy`、`multi-layer-layout` | | 居家/生活/日常/厨房/家务 | `cozy-home`、`home-motivation`、`yellow-pink-banner` | | 励志/正能量/突破/坚持/成长 | `dark-glow`、`home-motivation`、`dashed-decoration` | | 旅行/户外/自由/清新 |