---

name: pw-image-generation
description: AI 图像生成和处理工作流。通过提示词生成图像，支持文生图、图生图、批量生成、图床管理、长图合并、PPT 打包。核心特性是逐张确认生成，避免浪费 API 额度。

---

Image-Generation - AI 图像生成工作流

核心理念: 分析风格 → 设计提示词 → 用户确认 → 生成图像，避免额度浪费

核心功能

图像生成:
- 文生图: 根据文本描述生成图像
- 图生图: 基于参考图片生成类似风格的图像
- 批量生成: 使用提示词模板批量生成多张图像
- 风格一致: 保持系列图像的视觉风格统一

图像处理:
- 长图合并: 将系列图片垂直拼接为一张长图
- PPT 打包: 将系列图片打包为 PPT 文件 (每张图片一页)
- 图床管理: 上传图片到图床并管理删除链接

使用时机

适用场景:
- 用户明确要求 "生成图像"、"创建配图"、"制作插画"
- 用户提供文本描述并需要视觉化呈现
- 用户提供参考图片并要求生成类似风格的图像
- 用户需要为文章、PPT、社交媒体制作配图
- 用户需要批量生成风格一致的系列图像
- 用户需要将多张图片合并为长图或 PPT

不适用场景:
- 用户只是询问如何生成图像 (提供建议即可)
- 用户需要编辑现有图片 (使用图片编辑工具)
- 用户需要图像识别或分析 (使用视觉分析工具)
- 用户需要截图或屏幕录制 (使用系统工具)

---

工作流程

分析风格 → 设计提示词 → 安装依赖 → 配置API → 确认生成 → 保存图像
    ↓          ↓           ↓         ↓         ↓         ↓
  风格文件    提示词文件   node-fetch  secrets.md  逐张确认  images/

---

脚本目录

所有脚本位于 ~/.claude/skills/pw-image-generation/scripts/ 目录中。

Agent 执行说明:
1. 确定此 SKILL.md 文件的目录路径为 SKILL_DIR
2. 脚本路径 = ${SKILL_DIR}/scripts/<script-name>.ts
3. 将本文档中的所有 ${SKILL_DIR} 替换为实际路径

可用脚本:
| 脚本 | 功能 | 参数 |
|------|------|------|
| generate-image.ts | 生成图像 (逐张确认) | [输出目录] |
| upload-image.ts | 上传图片到图床 | <图片路径> |
| delete-image.ts | 管理图床图片 | list\|delete <索引>\|delete-all |
| merge-to-long-image.ts | 合并为长图 | <图片目录> <输出文件> |
| merge-to-pptx.ts | 打包为 PPT | <图片目录> <输出文件> |
| analyze-image.ts | 分析图像风格 | <图像URL或路径> |

快速开始

Step 1: 创建项目目录

mkdir my-image-project && cd my-image-project

Step 2: 复制配置模板（可选）

cp -r ~/.claude/skills/pw-image-generation/config.example ./config
cp ~/.claude/skills/pw-image-generation/references/.gitignore.template ./.gitignore
# 编辑 config/secrets.md 自定义 API 密钥（可选）

Step 3: 创建提示词

mkdir -p prompts
cp ~/.claude/skills/pw-image-generation/references/prompt-templates/提示词模板.md ./prompts/我的提示词.md
vim ./prompts/我的提示词.md

参考 references/style-library.md 选择合适的风格。

Step 4: 生成图像

npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

脚本会逐张询问确认，避免浪费额度。

---

工具脚本详解

1. 生成图像

命令:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts [输出目录]

参数说明:
- [输出目录]: 可选，指定图像保存目录，默认为 ./images

工作流程:
1. 读取 prompts/ 目录下的所有提示词文件
2. 逐张显示提示词内容
3. 询问是否生成该图像 (y/n/q)
4. 生成图像并保存到输出目录
5. 支持中断和恢复

确认选项:
- y (yes): 生成当前图像
- n (no): 跳过当前图像，继续下一张
- q (quit): 退出生成流程

示例:

# 使用默认输出目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 指定输出目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts ./my-images

---

2. 上传图片到图床

命令:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts <图片路径>

参数说明:
- <图片路径>: 必需，要上传的本地图片文件路径

功能特性:
- 自动上传到 freeimage.host (永久存储)
- 返回可用的图片 URL
- 自动保存删除链接到 .upload-history.json
- 用于图生图的参考图上传

示例:

# 上传单张图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 上传后会返回:
# - 图片 URL (用于提示词中的 image_url)
# - 删除链接 (保存在历史记录中)

输出示例:

上传成功!
图片 URL: https://iili.io/xxx.png
删除链接已保存到 .upload-history.json

---

3. 管理图床图片

命令:

# 列出所有上传的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list

# 删除指定索引的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete <索引>

# 删除所有图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

参数说明:
- list: 列出所有上传记录
- delete <索引>: 删除指定索引的图片 (索引从 0 开始)
- delete-all: 删除所有图片

功能特性:
- 查看上传历史和删除链接
- 单个或批量删除图片
- 自动更新历史记录文件

示例:

# 查看上传历史
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list
# 输出:
# 0: 参考图.png - https://iili.io/xxx.png (2024-01-15)
# 1: 配图1.png - https://iili.io/yyy.png (2024-01-16)

# 删除索引为 0 的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete 0

# 删除所有图片 (会要求确认)
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

详细说明见 references/图床上传.md

---

4. 合并长图

命令:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts <图片目录> <输出文件>

参数说明:
- <图片目录>: 必需，包含要合并的图片的目录
- <输出文件>: 必需，输出的长图文件名

功能特性:
- 垂直拼接多张图片
- 自动识别 jpg/png/gif/webp 格式
- 按文件名数字排序
- 保持原图宽度，自动计算高度

依赖要求:
需要安装 ImageMagick:

brew install imagemagick

示例:

# 合并 images 目录下的所有图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./images 长图.png

# 指定其他目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./my-images 合集.jpg

使用场景:
- 制作小红书/微信公众号长图
- 合并系列教程截图
- 制作图片合集展示

---

5. 合并为 PPT

命令:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts <图片目录> <输出文件>

参数说明:
- <图片目录>: 必需，包含要打包的图片的目录
- <输出文件>: 必需，输出的 PPT 文件名

功能特性:
- 每张图片占一页
- 自动识别 jpg/png/gif/webp 格式
- 按文件名数字排序
- 16:9 比例，自动适应页面大小
- 图片居中显示

示例:

# 打包 images 目录下的图片为 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images 配图.pptx

# 指定其他目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./my-images 展示.pptx

使用场景:
- 快速制作图片演示 PPT
- 打包系列配图用于分享
- 将生成的图像整理成演示文档

---

6. 分析图像风格

命令:

# 从 URL 分析
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <图像URL>

# 从本地文件分析
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <本地路径>

参数说明:
- <图像URL或路径>: 必需，要分析的图像 URL 或本地文件路径

功能特性:
- 分析图像的视觉风格
- 生成适合的提示词建议
- 识别颜色、构图、艺术风格
- 保存分析结果到 analysis/ 目录

示例:

# 分析在线图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts https://example.com/image.jpg

# 分析本地图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts ./template/参考图.png

使用场景:
- 学习参考图片的风格特征
- 为图生图准备提示词
- 了解如何描述特定视觉风格

文件结构

项目目录结构

my-image-project/
├── config/
│   └── secrets.md           # API 配置（可选）
├── template/                # PDF 模板图片
├── prompts/                 # 提示词文件
├── analysis/                # 风格分析（可选）
├── images/                  # 生成的图像
└── .gitignore

Skill 目录结构

pw-image-generation/
├── SKILL.md                  # 本文件（核心文档）
├── config.example/           # 配置模板
│   ├── README.md             # 配置说明
│   └── secrets.md            # API 配置模板
├── references/               # 参考文档
│   ├── .gitignore.template   # Git 忽略文件模板
│   ├── 图床上传.md           # 图床上传指南
│   ├── style-library.md      # 风格库（9种预设风格）
│   └── prompt-templates/
│       └── 提示词模板.md     # 提示词模板
└── scripts/
    ├── analyze-image.ts      # 分析图像风格
    ├── generate-image.ts     # 生成图像（支持确认和跳过）
    ├── upload-image.ts       # 上传图片到图床
    ├── delete-image.ts       # 管理和删除图床图片
    ├── merge-to-long-image.ts       # 合并长图
    └── merge-to-pptx.ts        # 打包为 PPT

---

常见问题和错误处理

1. 生成图像失败

问题: 图像生成失败或返回错误

可能原因:
- API 密钥未配置或无效
- 提示词格式不正确
- 网络连接问题
- API 额度不足

解决方案:

# 检查配置文件
cat config/secrets.md

# 验证提示词格式
cat prompts/提示词.md

# 测试网络连接
curl -I https://api.openai.com

# 查看详细错误信息 (脚本会自动显示)

---

2. 图床上传失败

问题: 上传图片到图床失败

可能原因:
- 图片文件不存在或路径错误
- 图片格式不支持
- 图片文件过大 (超过 10MB)
- 网络连接问题

解决方案:

# 检查文件是否存在
ls -lh ./template/图片.png

# 检查文件大小
du -h ./template/图片.png

# 如果文件过大，压缩图片
# 使用 ImageMagick 压缩
convert ./template/图片.png -quality 85 -resize 2000x2000\> ./template/图片_compressed.png

---

3. 合并长图失败

问题: 合并长图时报错 "ImageMagick not found"

可能原因:
- 未安装 ImageMagick
- ImageMagick 未添加到 PATH

解决方案:

# macOS 安装
brew install imagemagick

# 验证安装
convert --version

# 如果仍然失败，检查 PATH
which convert

---

4. PPT 生成失败

问题: 生成 PPT 时报错或 PPT 无法打开

可能原因:
- 图片目录为空或不存在
- 图片格式不支持
- 输出文件路径无效

解决方案:

# 检查图片目录
ls -la ./images

# 检查图片格式 (支持 jpg/png/gif/webp)
file ./images/*.png

# 确保输出目录存在
mkdir -p ./output
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images ./output/配图.pptx

---

5. 提示词不生效

问题: 生成的图像与提示词描述不符

可能原因:
- 提示词描述不够具体
- 提示词语言混乱 (中英文混用)
- 提示词过长或过短
- 风格描述不明确

解决方案:

# 不好的提示词
一张图片

# 好的提示词
水彩风格，温馨的咖啡馆场景，柔和的光线，暖色调，手绘质感

# 使用风格库
参考 references/style-library.md 选择合适的风格描述

---

6. 批量生成中断

问题: 批量生成过程中意外中断

可能原因:
- 网络不稳定
- 用户手动中断 (Ctrl+C)
- API 限流

解决方案:
- 脚本会自动跳过已生成的图像
- 重新运行生成命令即可继续
- 已生成的图像不会重复生成
- 使用 n 选项跳过不需要的图像

---

7. 配置文件问题

问题: 配置文件不生效或找不到

可能原因:
- 配置文件路径错误
- 配置文件格式不正确
- 未复制配置模板

解决方案:

# 复制配置模板
cp -r ~/.claude/skills/pw-image-generation/config.example ./config

# 检查配置文件
cat config/secrets.md

# 配置文件格式示例
# API_BASE_URL=https://api.openai.com/v1
# API_KEY=sk-xxx

---

最佳实践

图像尺寸规范

根据不同使用场景选择合适的图像尺寸:

场景	比例	推荐像素	说明
文章配图	16:9	1920×1080	高清标准, 适配大屏阅读
公众号封面	2.35:1	900×383	微信官方推荐尺寸
小红书封面/配图	3:4	1242×1660	小红书推荐, 适配 iPhone 屏幕
X 文章封面	5:2	1500×600	X Articles 官方推荐
论文配图	16:9	1920×1080	高清标准

补充说明:
- 小红书也支持 1:1 (1080×1080) 和 4:3 (1440×1080)
- 公众号次图封面可用 200×200 (1:1)

使用建议:
- 在提示词中指定尺寸: size: 1920x1080 或 aspect_ratio: 16:9
- 优先使用推荐尺寸, 避免后期裁剪导致构图失衡
- 不同平台的尺寸要求不同, 生成前确认目标平台

---

提示词设计

基本原则:
- 具体明确: 详细描述场景、风格、颜色、构图
- 风格统一: 使用风格库中的预设风格描述
- 语言一致: 全英文或全中文，避免混用
- 长度适中: 50-200 字为宜，过短缺乏细节，过长容易混乱

推荐结构:

[风格] + [主体] + [场景] + [氛围] + [技术细节]

示例:
水彩风格，一只可爱的小猫，坐在窗台上，温暖的午后阳光，柔和的色彩，手绘质感

参考资源:
- references/style-library.md: 9 种预设风格
- references/prompt-templates/提示词模板.md: 提示词模板

---

图像生成流程

推荐步骤:
1. 先生成 1-2 张测试图像，验证提示词效果
2. 根据测试结果调整提示词
3. 确认效果满意后，批量生成剩余图像
4. 使用确认机制，避免浪费 API 额度
5. 定期备份生成的图像

避免浪费:
- 每次生成前仔细检查提示词
- 使用 n 选项跳过不需要的图像
- 使用 q 选项及时退出
- 不要盲目批量生成

---

图生图技巧

上传参考图:

# 1. 上传参考图到图床
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 2. 复制返回的 URL

# 3. 在提示词中使用
# image_url: https://iili.io/xxx.png
# prompt: 类似风格的场景，保持色调和构图

注意事项:
- 参考图尺寸建议 1024x1024 或更大
- 参考图清晰度要高
- 提示词要明确说明保留哪些特征
- 可以多次尝试不同的提示词组合

---

文件管理

目录结构建议:

my-image-project/
├── config/              # 配置文件 (不提交到 git)
├── template/            # 参考图片
├── prompts/             # 提示词文件
│   ├── 01-封面.md
│   ├── 02-内容1.md
│   └── 03-内容2.md
├── images/              # 生成的图像
│   ├── 01-封面.png
│   ├── 02-内容1.png
│   └── 03-内容2.png
└── output/              # 最终输出 (长图/PPT)

命名规范:
- 提示词文件: 使用数字前缀排序 (01-, 02-, 03-)
- 生成的图像: 自动使用提示词文件名
- 便于批量处理和排序

---

性能优化

提高生成速度:
- 使用较小的图像尺寸 (1024x1024 而非 2048x2048)
- 避免过于复杂的提示词
- 合理使用图生图 (比文生图更快)

节省 API 额度:
- 使用确认机制，不要跳过确认
- 先测试单张，再批量生成
- 保存好的提示词作为模板复用
- 定期清理图床上不需要的图片

---

质量控制

检查清单:
- [ ] 提示词描述清晰具体
- [ ] 风格描述统一一致
- [ ] 测试图像效果满意
- [ ] 图像尺寸和格式正确
- [ ] 文件命名规范有序
- [ ] 备份重要图像

常见问题:
- 图像风格不一致: 检查提示词中的风格描述
- 图像质量不佳: 增加技术细节描述 (如 "高清"、"细节丰富")
- 图像内容偏差: 提示词更具体，增加约束条件

---

重要提示

避免额度浪费

• 每次生成前都会询问确认
• 支持跳过已生成的图像
• 一张一张生成，避免批量消耗额度

配置管理

• 配置文件 config/secrets.md 是可选的
• 未配置时使用默认配置 (需要设置环境变量 API_KEY)
• 配置文件不会提交到版本控制 (已在 .gitignore 中)
• 支持自定义 API 端点和模型

运行环境

脚本使用 Bun 运行，无需本地安装依赖:

# 直接运行，Bun 会自动处理依赖
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

系统要求:
- Node.js 或 Bun 运行时
- macOS/Linux/Windows (WSL)
- 合并长图需要 ImageMagick

---

配置说明

查看 config.example/secrets.md 了解配置选项:

可配置项:
- API_BASE_URL: API 基础 URL (默认: OpenAI API)
- ANALYSIS_MODEL_ID: 图像分析模型 (默认: gpt-4-vision-preview)
- GENERATION_MODEL_ID: 图像生成模型 (默认: dall-e-3)
- API_KEY: API 密钥 (必需)

配置示例:

# config/secrets.md
API_BASE_URL=https://api.openai.com/v1
ANALYSIS_MODEL_ID=gpt-4-vision-preview
GENERATION_MODEL_ID=dall-e-3
API_KEY=sk-your-api-key-here

---

风格库

Skill 提供 9 种预设风格，保证图像风格一致性:

• 水彩风格 (watercolor) - 柔和温馨
• 扁平化设计 (flat-design) - 现代简洁
• 3D 渲染 (3d-render) - 立体真实
• 油画风格 (oil-painting) - 艺术经典
• 赛博朋克 (cyberpunk) - 科幻未来
• 像素艺术 (pixel-art) - 复古怀旧
• 手绘插画 (hand-drawn) - 温暖个性
• 照片写实 (photorealistic) - 高度真实
• 抽象艺术 (abstract) - 情感表达

查看 references/style-library.md 了解每种风格的详细说明和使用场景。

---

使用建议

Agent 使用指南

当用户请求生成图像时:

1. 确认需求: 询问用户图像用途、风格偏好、数量
2. 准备环境: 引导用户创建项目目录和配置
3. 设计提示词: 根据需求设计提示词，参考风格库
4. 生成测试: 先生成 1-2 张测试图像
5. 批量生成: 确认效果后批量生成
6. 后期处理: 根据需要合并长图或打包 PPT

典型工作流

场景 1: 文章配图

# 1. 创建项目
mkdir article-images && cd article-images

# 2. 准备提示词
mkdir prompts
# 创建 prompts/01-封面.md, 02-配图1.md 等

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 4. 合并长图 (可选)
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./images 长图.png

场景 2: PPT 配图

# 1. 创建项目
mkdir ppt-images && cd ppt-images

# 2. 准备提示词 (按页面顺序命名)
mkdir prompts
# 创建 prompts/01-标题页.md, 02-内容1.md 等

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 4. 打包为 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images 配图.pptx

场景 3: 图生图

# 1. 上传参考图
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 2. 在提示词中使用返回的 URL
# prompts/01-类似风格.md:
# image_url: https://iili.io/xxx.png
# prompt: 类似风格的场景，保持色调和构图

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

---

命令速查

# 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts [输出目录]

# 上传图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts <图片路径>

# 管理图床
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete <索引>
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

# 合并长图
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts <图片目录> <输出文件>

# 打包 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts <图片目录> <输出文件>

# 分析图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <图像URL或路径>