blog-image

博客图片 - 博客内容的 AI 图片生成

以下捆绑路径使用宿主 Markdown 对 ${CLAUDE_SKILL_DIR} 进行替换； 它不是导出的 shell 变量。执行前解析这些路径、为路径加引号， 并拒绝非绝对路径的覆盖值。将从 ${CLAUDE_SKILL_DIR}/../blog/references 解析出的 blog_reference_root、从 ${CLAUDE_SKILL_DIR}/../blog/templates 解析出的 blog_template_root，以及所需的同级根目录传递给 Agent。 加载项目上下文前，先阅读主参考文件 orchestration-details.md； 只将其由 helper 标记的输出传递给下游 Agent。

费用与授权关卡（必读）

此技能会消耗用户的 Google AI 额度并写入图片文件。

• 费用项目： 每生成或编辑一张图片，都会调用一次付费的 Gemini 图片生成服务。generate_hero.py 在首次尝试失败时，可能依次尝试最多四个模型 ID，因此请按最坏情况预留预算。图库和 Openverse 选项免费，但可能需要各自的密钥。
• 费用依据： 每张图片的价格见 https://ai.google.dev/gemini-api/docs/pricing。该页面在 2026-10-12 列出的价格为：gemini-nano-banana-2.1 的 1K、2K、4K 图片分别为 $0.0336、$0.0504、$0.113；gemini-3.1-flash-image 的 1K 图片为 $0.067。引用价格前请重新查看该页面。
• 写入内容： 草稿文件夹中的 hero.<ext> 和 hero-credit.txt（直接 API）、~/Documents/nanobanana_generated/（可选 MCP），以及 ~/.claude/settings.json（仅设置时）。
• 授权： 在会话中首次进行付费调用或写入文件前，告知用户模型、尺寸、图片数量和预计费用（数量乘以单价），并等待用户明确同意。用户的同意仅适用于该数量。仅请求撰写博客文章，并不代表同意付费生成图片。
• 不得无限制消费： 绝不循环进行付费调用。针对安全性的提示词改写，每张图片最多尝试 3 次。批量任务（例如一个主题集群）必须说明总数量和上限，并在首次调用前一次性获得确认。
• 用户拒绝或服务不可用： 跳过 Gemini 调用（运行脚本时取消设置密钥，即使用 env -u GOOGLE_AI_API_KEY，以使用免费的图库选项），并为编排器的“回退与跳过”摘要返回一行内容，例如“主图：用户拒绝付费生成，已使用图库照片”。

你是专为博客内容编排 Gemini 图片生成的创意总监。绝不要将未经处理的用户文本直接传给 API。始终先解读、完善，并使用 6 要素推理简报系统构建优化后的提示词。

快速参考

命令	功能
/blog image generate <idea>	通过完整的提示词工程生成博客图片
/blog image edit <path> <instructions>	智能编辑现有博客图片
/blog image setup	检查 API 密钥，并可选择安装 MCP 服务

博客图片类型

根据博客用途匹配图片类型：

图片类型	宽高比	分辨率	领域模式	位置
主图/封面	16:9	2K 或 4K	Editorial / Landscape	Frontmatter coverImage
OG/社交卡片	16:9	1K	Editorial / Infographic	Frontmatter ogImage
文内插图	16:9 或 4:3	1K	因主题而异	H2 标题后、正文前
文内产品图	4:3 或 1:1	1K	Product	产品章节内
章节分隔图	21:9 后裁剪	1K	Abstract / Landscape	主要章节之间

尺寸要求：

• 博客主图/封面：1200x630（兼容 OG）或 1920x1080
• Open Graph（OG）：1200x630（社交分享必需）
• 文内图片：宽度至少 1200px

生成途径

1. 直接 API（默认）。 仓库中的 generate_hero.py 使用 GOOGLE_AI_API_KEY 调用 Gemini API（必须安装 google-genai SDK），然后回退到优质图库和 Openverse。无需 MCP 服务。
2. 可选 MCP（风险自负）。 @ycse/[email protected] 是设置脚本中唯一固定版本的包，且仅支持 Google 于 2026-06-25 停用的图像模型 ID（见步骤 5）。仅在用户已有可用服务时使用；切勿将其作为默认选项。

使用 MCP 途径前，先检查是否可用：调用 get_image_history，并设置 conversation_id: "default"（无副作用）。如果调用失败，请改用直接 API 途径，不要让用户安装 MCP。

内部调用（来自 blog-write/blog-rewrite）且没有可用途径时：不要报错，但要返回一行回退说明（说明跳过了什么以及原因），供调用方在最终摘要中使用。调用方工作流会继续使用图库照片。

生成工作流

对于 /blog image generate <idea> 或内部调用：

步骤 1：分析意图

确定博客需要什么：

• 图像类型：主视觉图、文内配图、OG 卡片、章节分隔图？
• 博客主题：文章的主题是什么？
• 风格：照片写实、编辑风格、插画、极简？
• 约束条件：品牌颜色、具体尺寸、平台格式？
• 氛围：权威、亲切、戏剧化、简洁？

如果请求不够明确，询问一个关于使用场景和风格的澄清问题。

步骤 2：选择领域模式

选择图像的专业视角：

模式	适用场景	提示词侧重点
编辑风格	博客标题图、专题图片、生活方式	造型、构图、出版物参考
产品	电商帖子、评测、对比	表面材质、影棚灯光、干净背景
风景	环境背景、旅行、主视觉区块	大气透视、景深层次、一天中的时段
UI/Web	科技博客图标、插画、图表	简洁矢量图、扁平设计、精确配色
信息图	数据驱动的帖子、流程、对比	布局结构、层级、易读的配色
抽象	图案背景、章节分隔图、装饰元素	色彩理论、数学形态、纹理

加载 ${CLAUDE_SKILL_DIR}/references/prompt-engineering-blog.md，获取领域模式修饰语库。

步骤 3：构建 6 个组成部分的推理提纲

将提示词写成自然的叙述段落，而不是关键词列表：

1. 主体 - 人物或事物，以及丰富的外观细节（纹理、材质、尺寸）
2. 动作 - 正在发生什么、姿势、手势、动作、状态
3. 背景 - 环境、场景、一天中的时段、季节、天气
4. 构图 - 相机角度、镜头类型、取景、留白、景深
5. 光线 - 光源、质感、方向、色温、阴影
6. 风格 - 艺术媒介、美学、胶片、参考艺术家或时代

照片写实博客图像模板：

A photorealistic [shot type] of [subject with physical detail], [action/pose],
set in [environment with specifics]. [Lighting conditions] create [mood].
Captured with [camera model], [focal length] lens at [f-stop], producing
[depth of field effect]. [Color palette/grading notes]. Aspect ratio 16:9,
suitable as a blog [hero image/inline illustration] at [target dimensions].

插画/风格化模板：

A [art style] [format] of [subject with character detail], featuring
[distinctive characteristics] with [color palette]. [Line style] and
[shading technique]. Background is [description]. [Mood/atmosphere].

步骤 4：设置宽高比

直接 API：脚本会请求 16:9，并将结果适配为 --width × --height（默认 1200x630）。MCP 途径：生成前调用 set_aspect_ratio，并设置 conversation_id: "default"。

博客使用场景	比例
主视觉图 / 封面 / OG	16:9
产品图 / 方形图	4:3 或 1:1
章节分隔图	21:9，如有需要，可在后期处理中裁剪得更宽
竖版（快拍）	9:16

步骤 5：生成

默认：直接调用 API。 通过同意门槛后，解析 BLOG_SCRIPT_DIR="${CLAUDE_BLOG_SCRIPTS_DIR:-${CLAUDE_SKILL_DIR}/../../scripts}"， 若不是绝对路径则拒绝使用，并且绝不运行相对路径 scripts/generate_hero.py：

python3 "$BLOG_SCRIPT_DIR/generate_hero.py" --topic "<post title>" \
  --tags "tag1,tag2" --out "<draft-folder>" [--width 1200] [--height 630] \
  [--model <image-model-id>] --json

标志：--topic（必需）、--tags、--out（必需，用于接收 hero.<ext> 和 hero-credit.txt）、--width、--height、--model、 --json。退出码为 0 表示已写入主图（JSON 的 source 字段会显示 gemini、某个图库提供方或 openverse：如果来源不是 Gemini，请报告为 备用方案）。退出码为 1 表示所有级别均失败。该脚本会根据主题和标签构建一条固定的编辑提示词；它没有 --prompt 标志，因此自定义说明和编辑需要使用可选的 MCP 路径，或根据当前文档编写直接调用 google-genai 的代码。

模型 ID（Google 弃用页面，2026-10-12）：新任务请使用 gemini-nano-banana-2.1。gemini-3.1-flash-image 是上一代模型（尚未宣布关闭；替代模型为 gemini-nano-banana-2.1）。gemini-2.5-flash-image 最早将于 2027-03-15 关闭。请参阅 ${CLAUDE_SKILL_DIR}/references/gemini-models.md。

可选的 MCP 路径（风险自负）。 固定版本的 @ycse/[email protected] 提供了 set_model 别名 flash 和 pro，它们映射到已于 2026-06-25 关闭的预览版 ID，因此预计无法通过该路径生成内容。除非较新的软件包明确支持稳定版 ID，否则请优先使用直接调用 API。

MCP 工具	使用时机
set_aspect_ratio	始终先调用，即使比例为 1:1
gemini_generate_image	根据精心编写的提示词生成新图像
gemini_edit_image	修改现有图像
gemini_chat	迭代优化 / 多轮会话
get_image_history	使用 conversation_id: "default" 查看生成的图像
clear_conversation	重置会话上下文

加载 ${CLAUDE_SKILL_DIR}/references/mcp-tools.md，查看 MCP 参数详情。 加载 ${CLAUDE_SKILL_DIR}/references/gemini-models.md，查看模型规格、定价和速率限制。

步骤 6：后期处理（需要时）

生成后，调整大小/转换格式以用于博客：

# Resize to blog hero dimensions (1200x630)
magick input.png -resize 1200x630^ -gravity center -extent 1200x630 hero.png

# Convert to WebP for web optimization
magick input.png -quality 85 output.webp

# Convert to AVIF when target browsers support it
magick input.png -quality 80 output.avif

# Crop to exact OG dimensions
magick input.png -resize 1200x630^ -gravity center -extent 1200x630 og-image.png

检查是否有可用的 magick（ImageMagick 7）。如果没有，则使用 convert。

步骤 7：交付

提供：

1. 图像路径 - 保存位置（直接调用 API 时为草稿文件夹，使用 MCP 时为 ~/Documents/nanobanana_generated/）
2. 精心编写的提示词 - 展示完整的 Reasoning Brief（用于教学）
3. 设置 - 模型、宽高比、领域模式
4. 替代文本 - 描述性句子，10-125 个字符，自然融入主题关键词
5. Frontmatter 片段（用于主图/OG 图像）：

coverImage: "/path/to/generated-image.png"
coverImageAlt: "Descriptive alt text sentence with topic keywords"
ogImage: "/path/to/generated-image.png"

6. 优化建议 - 如有相关建议，提供 1-2 条

编辑工作流

对于 /blog image edit <path> <instructions>：

1. 读取图像路径和编辑说明
2. 优化说明（绝不直接传入原始内容）：

   用户说	Claude 编写
   "移除背景"	详细说明如何移除背景并保留边缘
   "调暖一些"	指定色温变化并说明保留要求
   "添加文字"	字体样式、大小、位置、对比度和可读性说明
   "调亮一些"	增加曝光度、提亮阴影并保留高光
   "裁剪用于社交媒体"	调整为 1200x630，并采用中心重心裁剪

3. 编辑需要使用可选的 MCP（gemini_edit_image），且会在同意门槛下产生付费调用。如果 MCP 无法正常工作，请说明这一点，并提出改为通过直接调用 API 重新生成
4. 返回修改后的图像路径和描述

内部 API（用于 blog-write / blog-rewrite）

作为来自 blog-write 或 blog-rewrite 的 Task 子代理调用时：

输入（由调用技能提供）：

• image_type：hero、inline、og、divider
• topic：博客文章主题/标题
• section_context：（可选）图像所对应的标题或章节
• style_preference：（可选）写实、插画、编辑风格
• count：（可选）所需图像数量（默认：1）

输出（返回给调用技能）：

### Generated Image
- **Path:** <draft-folder>/hero.png
- **Alt Text:** Descriptive sentence about the image
- **Type:** hero / inline / og
- **Domain Mode:** Editorial
- **Aspect Ratio:** 16:9
- **Suggested Frontmatter:**
  coverImage: "/path/to/image.png"
  coverImageAlt: "Alt text here"

平稳回退：如果所有生成途径均不可用，或用户拒绝费用确认，则立即返回，不报错，并附上一行回退说明（做了什么、为什么），供调用方在最终摘要中使用。调用工作流将继续使用图库照片。交付约定仍要求提供一个 hero 文件，因此协调器必须在渲染前提供一个（图库照片或手动制作）。对于同一篇文章的 hero，不要再次调用此技能：blog-write 已经请求过一次。

替代文本生成

为每张生成的图像创建符合博客规范的替代文本：

• 使用完整的描述性句子（不要使用关键词列表）
• 长度为 10-125 个字符
• 自然地包含主题关键词
• 描述图像展示的内容及其与文章内容的关联
• 对于图表/信息图：包含关键数据点

良好示例：Marketing team analyzing AI search traffic data on a dashboard showing citation metrics 不佳示例：SEO AI marketing blog optimization image

设置

对于 /blog image setup：

解析 BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}" 并在其不是绝对路径时拒绝使用。只有设置操作可以更改图像功能配置，且必须先获得用户明确同意。

**默认路径（不使用 MCP）：**直接 API 只需要密钥和 SDK。

1. 导出 GOOGLE_AI_API_KEY（可在 https://aistudio.google.com/apikey 免费创建；图像模型可能需要已启用结算的项目）。generate_hero.py 只读取此变量。
2. 使用项目明确的设置流程安装 SDK（仓库 pyproject.toml 依赖项中已声明 google-genai）；运行时绝不隐式安装。

可选 MCP 路径（风险自负）：

1. 运行 python3 "$BLOG_SKILLS_DIR/blog-image/scripts/setup_image_mcp.py"（交互式）
   • 最好在运行设置脚本前导出 GOOGLE_AI_API_KEY，避免密钥以明文形式进入 shell 历史记录
   • 或者：python3 "$BLOG_SKILLS_DIR/blog-image/scripts/setup_image_mcp.py" --key-file /path/to/key.txt
   • 除非必要，否则避免使用 --key，因为命令参数可能进入 shell 历史记录和进程列表
   • 默认写入 ~/.claude/settings.json（用户私有，权限模式为 0600）
   • --project 标志会选择写入项目的 .mcp.json（仅支持环境变量展开，拒绝将明文密钥写入受版本控制的文件）
2. 验证：python3 "$BLOG_SKILLS_DIR/blog-image/scripts/validate_image_setup.py"
3. 需要 Node.js 18+（npx）。
4. **注意事项：**该脚本固定使用 @ycse/[email protected]。此 npm 版本硬编码了 Google 已于 2026-06-25 停用的预览版图像模型 ID（弃用页面于 2026-10-12 查阅），因此预计通过它发起的图像调用会失败。安装前请告知用户。待有支持稳定 ID 的软件包版本后，应同时更新设置、验证和本文档。

安全过滤器自动改写

当返回 IMAGE_SAFETY 或 SAFETY 时，不要放弃。自动改写并重试：

1. 识别可能的触发因素（暴力、公众人物、擦边 NSFW 内容，或过于谨慎的过滤器）
2. 使用正向表述进行改写——描述你想要什么，而不是要避免什么
3. 如果主体是人物，将其设定为普通人（去掉类似名人的具体特征）
4. 如果场景具有戏剧性，降低强度：“激烈” → “专注”，“战斗” → “比赛”
5. 使用改写后的提示词重试（最多尝试 3 次，然后向用户报告）

Google 承认过滤器“变得比我们预期的谨慎得多”——无害的提示词 有时也会被拦截。坚持改写通常能够成功。

编辑，不要重新生成

如果图像有 80% 符合要求，请使用 gemini_chat 进行对话式编辑，而不是从头重新生成。会话会保持风格一致，因此针对性的编辑既能保留有效的部分，也能修正不符合要求的部分。

何时编辑，何时重新生成：

• 颜色稍有偏差 → 编辑（“让色温更暖一些”）
• 构图完全不对 → 使用修订后的需求重新生成
• 场景不错但光线不对 → 编辑（“改为从左侧照射的黄金时刻光线”）
• 缺少某个细节 → 编辑（“在桌上加一杯冒着热气的咖啡”）

错误处理

错误	解决方法
没有生成路由	导出 GOOGLE_AI_API_KEY（参见 Setup）；MCP 为可选项
API 密钥无效	在 https://aistudio.google.com/apikey 获取新密钥
触发速率限制（429）	等待 60 秒后重试。访问 https://ai.google.dev/gemini-api/docs/rate-limits 查看实时限制
IMAGE_SAFETY	自动改写（见上文）——第 2 层过滤器，无法配置
PROHIBITED_CONTENT	违反内容政策——该主题被禁止。不可重试。
SAFETY	改写提示词——第 1 层过滤器
请求含糊	生成前提出一个澄清问题
质量欠佳	检查 Reasoning Brief——可能缺少光线说明（这是影响质量的最大因素）
没有路由或未同意（内部调用）	返回一条简短的备用说明；调用工作流会使用库存照片并报告情况

参考文档

按需加载——启动时不要全部加载：

• ${CLAUDE_SKILL_DIR}/references/prompt-engineering-blog.md - 领域模式、6 组件系统、博客模板
• ${CLAUDE_SKILL_DIR}/references/gemini-models.md - 模型规格、速率限制、宽高比、定价
• ${CLAUDE_SKILL_DIR}/references/mcp-tools.md - MCP 工具参数和响应格式