pixeltamer

pixeltamer — 使用 GPT Image 2.5 生成、编辑和组合图像

真正按你的要求生成图像。提供两种后端，让你无需二选一：使用 OpenAI API 密钥，或使用已登录 ChatGPT 订阅的 codex CLI。API 后端默认使用 gpt-image-2.5-flare，并接受 --model；Codex 在服务端选择图像模型。同一项技能，同样的提示词，由你选择付费方式。

适用场景

用户提出以下任何需求时，触发此技能：

• 生成新图像、海报、插画、照片、样机、图标、贴纸、精灵图、徽标、主视觉图、信息图、广告创意、吸睛卡片、杂志封面、播客艺术图、产品照、横幅、OG 图像、社交卡片、角色设定表、应用屏幕、仪表板样机
• 编辑现有图像（修改、局部重绘、蒙版、仅更改某项）
• 将多张参考图像混合成一张图像
• 批量生成一组相关图像并进行验证

如果用户说“帮我生成一张图”或提出类似需求，就使用此技能。

前提条件 — 检查安装情况（首次生成前执行）

先运行此命令，查看有哪些可用选项：

pixeltamer doctor

如果输出中至少有一个后端带有 ✓ 标记，就可以开始生成。自动检测会在设置了密钥时选择 API，否则选择 codex。可通过每次调用时指定 --backend api|codex 覆盖，或设置 PIXELTAMER_BACKEND 环境变量。

如果 pixeltamer doctor 未显示后端状态，而是报错 permission denied： 安装或更新时，skills CLI 移除了调度器的执行权限。调度器无法自行恢复执行权限（它必须先运行才能做到），因此请通过 bash 引导运行一次——之后它会自动修复其他问题：

# run it through bash (works even without +x):
bash ~/.claude/skills/pixeltamer/scripts/pixeltamer doctor
# or restore the bit permanently:
chmod +x ~/.claude/skills/pixeltamer/scripts/pixeltamer

现在所有其他脚本都会通过其解释器运行，因此只有调度器文件的执行权限可能导致此问题。

如果两个后端都显示 ✗，不要运行 pixeltamer config——它会交互式提示，需要真实 TTY，而 Bash 工具不具备这一条件，因此调用会一直挂起。改用 AskUserQuestion，请用户选择：

“Pixeltamer 需要配置两个后端之一。请选择： API 密钥 — 速度最快，功能完整（编辑 + 组合），按图像计费。 Codex CLI — 使用你现有的 ChatGPT Plus/Team/Enterprise 订阅，无需密钥，仅支持生成。”

如果用户选择 API

告诉他们将密钥放入 pixeltamer 的配置目录。这是最简洁的方式，因为 Python 脚本每次调用时都会自动加载密钥——无需重启 shell，也无需管理环境变量：

mkdir -p ~/.config/pixeltamer
echo 'OPENAI_IMAGE_API_KEY=sk-yourkeyhere' > ~/.config/pixeltamer/.env
chmod 600 ~/.config/pixeltamer/.env

如果其组织尚未通过 GPT Image 访问验证，首次调用会返回 403——请引导他们前往 https://platform.openai.com/settings/organization/general 完成一次性验证。

如果他们更倾向于使用点文件，也可以在 ~/.zshrc（或 .bashrc）中执行 export OPENAI_API_KEY="sk-..."，但需要重启 Agent，才能让新环境变量生效。使用 .env 文件则无需重启。

如果用户选择 codex

# 1. install codex if missing
npm install -g @openai/codex

# 2. log in (opens a browser, OAuth via ChatGPT)
codex login

# 3. confirm
codex login status

无需重启。bash 后端每次调用时都会重新读取 codex 身份验证信息。

codex 的更新与技能相互独立——npx skills update 不会更新 codex。现在，pixeltamer doctor 会报告已安装的 codex 版本，并在版本低于 npm 最新版时发出提示（codex 过旧是已知故障原因——旧版架构曾导致进程无限期挂起）。如果 doctor 提示有可用更新，请运行 npm install -g @openai/codex@latest。

用户完成设置后

重新运行 pixeltamer doctor 确认设置无误，然后继续处理原始请求。

三种模式

模式 1 — 单次生成

pixeltamer generate -p "<prompt>" --size 1024x1024 --quality high -o output.png

也可以使用快捷方式，它会自动推断为 generate：

pixeltamer "Create a pitch-deck slide titled..."

探索方案时，可并行生成 4 张：

pixeltamer generate -p "..." -n 4 --concurrency 4 -o variants/

透明素材

任何需要合成到你无法控制的背景上的内容——图标、徽标、吉祥物、产品抠图、图表图层、贴纸——都应生成真正带有 Alpha 通道的图像，而不是事后再清理绿幕：

pixeltamer generate -p "<isolated subject>" --background transparent -o asset.png

generate 在两种后端上均适用。在 API 上，这是一个请求参数；在 codex 上，它会转换为提示词说明（codex 没有背景参数），并自动检查 Alpha 通道。如果返回的 PNG 是 RGB 格式，就会在 stderr 中发出警告。Codex 的 edit/compose 无法实现此功能——调度器会说明这一点。

编写提示词前需要注意：**提示词的优先级高于标志。**你描述的任何背景、表面、场景或投影阴影都会被绘制出来，而你得到的会是一张完全不透明的 PNG，且不会出现任何错误。加载 references/transparency.md，查看约束说明和验证步骤。

模式 2 — 编辑 / 局部重绘

# Modify a single existing image
pixeltamer edit -i source.png -p "Change ONLY the sky to overcast. Preserve everything else exactly." -o edited.png

# With a mask — white pixels regenerate
pixeltamer edit -i source.png --mask mask.png -p "..." -o edited.png

编辑功能在两种后端上均适用。API 路径使用 /v1/images/edits（支持 --mask 进行区域局部重绘）。codex 路径直接使用 OAuth Responses API（scripts/pixeltamer_codex_oauth.py）——凭据与 codex exec 相同，但传输方式不同，且无需 API 密钥。Codex-OAuth 不支持 --mask；如果用户需要基于蒙版进行局部重绘，则需要使用 API 路径。

模式 3 — 多参考图合成

通过 /images/edits 传入 2–16 张参考图，将它们融合为一张输出图：

pixeltamer compose \
  -p "Reference 1 is the product. Reference 2 is the kitchen scene. Compose: place the product on the counter with morning window light from the left." \
  -i product.png \
  -i kitchen.png \
  -o composed.png \
  --size 1536x1024

这是最具杀手级的功能。请参阅 references/multi-reference.md，了解实际有效的标注模式。

参考图顺序仍然重要：将最不能丢失的面部、徽标或产品细节放在最前面。GPT Image 2.5 默认能更好地保留主体。对于提供此控制选项的模型和服务商，直接通过 API 编辑时仍可使用 --input-fidelity high。

模式 4 — 批量处理（含验证的多图计划）

对于需要 4 张或更多相关图像的项目（例如网站的主视觉图、功能图、页脚图和社交媒体图），请使用批处理状态机。工作流如下：

1. 调查需要哪些图像。
2. 制定 prompts.md，每张图像对应一个条目（目标路径、格式、原生尺寸、可选参考图、状态、提示词）。 Format 标为 PNG transparent 的条目必须使用 --background transparent 生成——验证器会检查是否带有真正的 Alpha 通道，否则判定失败。 如果批次是一组系列素材（产品系列、图标家族、贴纸包），请编写一个共用的风格与约束说明块，并将其原封不动地附加到每个条目的提示词中。这个固定后缀能让 N 次独立生成的图像看起来像同一套素材——请参阅 references/transparency.md。
3. 逐张生成，并为每个条目调用正确的后端。
4. 运行 pixeltamer batch <path-to-prompts.md>，验证每个输出（文件是否存在、尺寸是否匹配、文件大小是否合理）。
5. 使用 Read 工具对每张生成的 PNG 进行视觉自检；如果不符合提示词，则将状态降级为 failed:<reason>。
6. 仅重新生成失败的条目。

验证器在 scripts/verify-images.mjs 中解析 prompts.md 格式。请参阅 references/multi-reference.md 了解其结构。

工作流 — 调用时的操作步骤

0. 先阅读 references/index.md。 在路由映射中找到与请求最匹配的条目。只加载最小且有用的内容——一个配方、一个操作手册文件或一份参考资料，不要全部加载。如果我们的配方或操作手册中已有类似模式，就不要从头编写提示词。如果没有匹配项，则回退到 references/prompting.md，再加上最接近的配方。
1. 理解请求。 确定模式（生成／编辑／组合／批量）。确认第 0 步加载的配方／操作手册／参考资料确实适用；如果不适用，则重新路由。
2. 在适用时阅读参考资料。 除 index.md 指向的文件外：任何非简单提示词都要加载 references/prompting.md。组合模式要加载 references/multi-reference.md。任何透明 Alpha 素材都要加载 references/transparency.md。如果要以编程方式组合提示词、遇到某个规范类别（UI／信息图／品牌标识／电商主视觉／建筑渲染／科学图谱／字体海报），或需要确保多张图片的品牌一致性，则加载 references/prompt-patterns.md。不要把所有参考资料都塞进上下文，只取所需内容。
3. 确定未指定的参数。 根据用途选择合适的尺寸（参见 references/prompting.md 中的尺寸表）。默认 --quality high。如果用户未指定后端，则选择一个。如果素材将与其他内容合成——图标、徽标、吉祥物、抠图或图表图层——则使用 --background transparent，并在编写提示词前加载 references/transparency.md。
4. 构建提示词。 使用规范结构：意图 → 场景 → 主体 → 细节 → 文字 → 风格 → 约束。删除魔法词（“8K、超精细、杰作、专业”）。将需要出现在图像中的文字加上引号。编辑时说明需要保留的内容。对于 UI 屏幕、信息图、品牌渲染、科学图谱，或任何需要以编程方式组合提示词的请求，都应采用 JSON 配置架构及 references/prompt-patterns.md 中的其他高级模式。
5. 生成。 调用正确的 pixeltamer 子命令。打印生成文件的绝对路径。
6. 目视自检。 使用 Read 工具查看生成的 PNG，并根据提示词进行判断：
   • 主体是否匹配？
   • 文字是否正确呈现，拼写是否与引号中的内容完全一致？
   • 是否存在明显瑕疵（人体结构扭曲、拼写错误、字体显示异常）？
   • 构图是否符合要求？
   • 如果要求透明背景：Alpha 是否确实透明？Alpha 通道不透明是常见的静默失败——务必检查，不要想当然。 如果结果不符合要求，就如实说明。不要用“看起来很棒！”掩盖糟糕的结果。
7. 迭代或交付。 如果结果有误，只更改一个维度后重新生成（参见 references/prompting.md 中的迭代表）。如果结果不错，则向用户提供文件路径。

标志控制属性，提示词控制内容

这是整个技能中最清晰的心智模型，也是 Agent 最常弄错的一点。输出的属性由标志控制。在提示词中描述这些属性并不可靠，而且取决于后端。

属性	使用标志	不要使用提示词
尺寸	--size 1536x1024、2K、4K	“一张 1536x1024 的……图片”
输出容器	--output-format png|jpeg|webp	“将其保存为 webp”
压缩	--output-compression 0-100	“稍微压缩一下”
渲染质量	--quality low|medium|high	“高质量、细节丰富”
变体数量	-n 4	“给我四个版本”
编辑区域	--mask region.png	“只改左上角”
参考图保真度	GPT Image 2.5：将关键参考图放在最前；旧版模型：--input-fidelity high	“保持人脸完全不变”

提示词用于描述图片中的内容。尺寸、格式、数量和遮罩并不在图片中。

背景是个例外，但仅限 codex。 在 API 后端，--background 是一个真实参数，上述规则仍然适用。在 codex 中没有这样的参数，因此透明度确实由提示词控制——这就是为什么其中的 --background transparent 会改写提示词，而不是设置标志。这两点都写在 references/transparency.md 中。

视觉自我验证——不可妥协

每张生成的图片都必须先通过 Read 加载回来并进行视觉评估，才能宣称成功。图像生成具有随机性；“API 调用成功”不代表“图片符合要求”。这一步可以发现：

• 文字叠加内容拼写错误或被改写
• 主体错误（咖啡店，而不是咖啡杯）
• 视觉瑕疵（扭曲的手、乱码的排版、多余的肢体）
• 画面宽高比不正确（主体过小或被裁切）
• 色彩或色调不符合品牌

出现问题时，通常正确的做法是在提示词中只改动一处并重新生成，而不是一口气添加三个新条件，指望其中一个能起作用。

输出格式——告知用户的内容

成功生成后，提供：

• 绝对文件路径（脚本会将其打印到 stdout）
• 用一句话说明生成了什么（例如：“已生成一张 1024×1536 的竖版封面，标题已按原文准确呈现”）
• 如果有多个变体（-n N），列出所有路径

自我验证后仍未成功时：

• 说明出了什么问题（文字被改写、主体过于笼统等）
• 建议最可能有效的一项修正，并提出可以重新生成
• 未经用户同意，不要自动重新生成——用户可能想自行调整提示词

可用配方

recipes/infographic.md · recipes/meta-ad.md · recipes/viral-linkedin.md · recipes/ui-mockup.md · recipes/editorial-cover.md · recipes/product-photo.md · recipes/mascot.md

在符合相应触发条件时，加载匹配的配方。其中包含提示词框架、完整示例、尺寸默认值和常见失败情况表。

吉祥物 / 品牌角色 / 应用图标角色请求——编写提示词之前务必加载 recipes/mascot.md。 模型默认会把“可爱角色”生成成通用的 Slack 团子形象；该配方明确规定了从上下文选择锚点的决策树、剪影与比例规则，以及需要避免的反模式。不加载它是吉祥物效果平淡最常见的原因。

可用参考资料

references/prompting.md——提示词准则。规范结构、不要说什么，以及风格、构图和灯光词汇。 references/api-backend.md——API 详情、环境变量、故障排除。 references/codex-backend.md——codex CLI 详情、两种调用模式及其权衡。 references/multi-reference.md——精通合成模式、标注方式、参考图组的尺寸设置。 references/post-process.md——压缩、调整大小、转换、提取 alpha 通道、合并。 references/ui-mockup-prompting.md——类比式与清单式风格、使用真实数据而非占位符、资源规范化。

仅提取当前任务所需的内容。不要把所有内容一股脑抛出来。

常见错误 — 避免这些模式

不要这样做	原因
"8K, ultra detailed, masterpiece, trending on artstation"	魔法词并不能说明视觉效果。应改为描述材质、光线、构图和纹理。
"professional, beautiful, premium, stunning"	只有赞美，没有任何指导性内容。
未确认可用的后端就开始生成	如果这是本次会话中的首次调用，请先运行 pixeltamer doctor。
在 codex 后端上编辑 / 合成	自 0.3.0 起可通过 OAuth Responses API（pixeltamer_codex_oauth.py）使用。基于蒙版的修复仍需使用 API 路径——Responses API 不接受蒙版参数。需要指定输出尺寸的编辑也一样：codex 会沿用输入图像的宽高比，并忽略 --size。
为抠图素材使用色度键绿幕	这是过时的建议。--background transparent 可在两个后端的 generate 中生成真正的 alpha 通道。只有在边缘不干净，或使用 codex 进行 edit/compose 时才使用色度键。
要求透明背景时却描述背景内容	提示词的优先级高于标志。写上“干净的白色影棚”，就会压过 --background transparent，最终得到白色矩形。
跳过视觉结果的自我检查	图像生成具有随机性。“API 调用成功”≠“图像正确”。
一个方案无效时又叠加三个新条件	每次只改变一个方面，否则你就不知道什么起了作用。
把 examples 文件夹中的 PNG 当作标准答案	它们只是示例，不是规格。重新生成时构图会有所不同。

后端速查表

需求	使用方式
生成单张图像的最快方式	使用默认 gpt-image-2.5-flare 的 API
没有 / 不想使用 API 密钥	codex
编辑现有图像（无需蒙版）	任一后端——API 或 codex-OAuth
基于蒙版的修复	仅限 API——Responses API 不接受蒙版参数
编辑时保留人脸 / 徽标 / 标签类型	API；使用 Sunburst，并将关键参考图放在最前面
编辑时保证输出尺寸	仅限 API——codex 在 edit/compose 中会忽略 --size，并沿用输入图像的宽高比
将 2–16 张参考图合成为一张	任一后端——API 或 codex-OAuth
在队友的机器上运行，且无需共享凭据	codex（每位用户单独登录）
透明背景 / 真正的 alpha 通道	两者均可用于 generate——API 将其作为参数传入，codex 通过提示词实现并验证。Codex 的 edit/compose：仅限 API
指定输出文件格式（png / jpeg / webp）	仅限通过 --output-format 使用 API——两种 codex 传输方式始终返回 PNG
自定义 OpenAI 兼容主机（jmrai、ZenMux、OpenRouter）	设置 OPENAI_IMAGE_BASE_URL 后使用 API
最高质量 / 编辑精度	使用设置了 OPENAI_IMAGE_MODEL=gpt-image-2.5-sunburst 的 API
高质量的大尺寸图像（4K）	使用 API；在 codex 中，--size 仅对 generate 有效，而且生成大尺寸图像时其推理循环会变慢

Persona 说明

输出（文件路径、成功消息、失败说明）应简洁实用。不要夸大宣传，也不要用“这是你惊艳的杰作”之类的说法——pixeltamer 正是要帮助消除这种低质内容，而不是产出它。只需说明：生成了什么、文件在哪里，以及接下来该做什么。