最终图像资源
<skill-dir> 是包含此 SKILL.md 的文件夹,<plugin-root> 是其上两层的文件夹。在命令中将它们替换为实际路径。(在 Claude Code 中,它们分别是 ${CLAUDE_SKILL_DIR} 和 ${CLAUDE_PLUGIN_ROOT}。)
输入:一个资源或列表,例如“连击冻结图标”或“每日任务 GDD 中的 6 个奖励图标”。输出:PNG 文件,位于游戏的资源路径下,每条记录包含其提示词和模型。
首先阅读 <plugin-root>/shared/conventions.md 和仓库配置(Art 部分)。
GI="<skill-dir>/scripts/gen_image.py" # 仅 Python 3;绝不打印密钥
python3 "$GI" check # 检查将使用的密钥和模型,无成本(从游戏仓库目录运行)
python3 "$GI" generate --prompt "…" --out <file.png> [--size WxH] [--background transparent] [--ref <art.png> …] [--log <log.jsonl>]
0. 该项目是否启用了图像生成?
读取 config: Image generation:
on:前往步骤 1。off:不生成图像。使用现有美术或仓库的占位符模式,并在报告中列出仍需要的资源(名称、尺寸、用途)。不要再次询问。not set或缺失:这是该项目的第一个图像。运行check,然后使用问题工具询问:- 如果未找到密钥,问题将说明最终资源默认为 OpenAI 的 GPT 图像(最新版本,2 或更高),并且需要 API 密钥。选项包括:
- 立即设置密钥(推荐): 显示以下设置步骤,等待用户告知已完成。然后再次运行
check。一切就绪后,写入on。 - 不用于此项目: 写入
off (opted out <YYYY-MM-DD>),并在没有生成美术的情况下继续。 - 现在不设置: 本次跳过图像,保持字段为
not set,并在下次再次询问。
- 立即设置密钥(推荐): 显示以下设置步骤,等待用户告知已完成。然后再次运行
- 如果找到了密钥(在仓库的
.env、环境变量或为其他项目设置的位置),问题将说明密钥的位置以及check选择的模型。如果check显示.env文件被 git 跟踪,请警告密钥已被提交,应轮换,并建议将其移出 git。选项包括:用于此项目(推荐,然后写入on)、不用于此项目(off)以及现在不设置。
- 如果未找到密钥,问题将说明最终资源默认为 OpenAI 的 GPT 图像(最新版本,2 或更高),并且需要 API 密钥。选项包括:
API 密钥设置(向用户展示)
- 前往 platform.openai.com → API keys → Create new secret key。项目范围的密钥最佳。
- 确保 Billing 有余额。GPT 图像模型还可能要求你验证组织(Settings → Organization → General)。验证后,访问权限可能需要几分钟才能生效。
- 将密钥保存在本机。切勿将其粘贴到聊天中。
- macOS(推荐): 在终端中运行此命令。它会在不显示密钥的情况下要求输入,并将其存储在钥匙串中:
security add-generic-password -U -a "$USER" -s gd-toolkit-openai -w - 仅限此项目: 将
OPENAI_API_KEY=…添加到仓库的.env或.env.local。首先检查该文件是否已包含在.gitignore中。 - 任何位置: 将
export OPENAI_API_KEY=…添加到你的 shell 配置文件,例如~/.zshrc,然后打开一个新终端。 - 或者 使用仅你可读的文件:
~/.config/gd-toolkit/openai_api_key(chmod 600)。
- macOS(推荐): 在终端中运行此命令。它会在不显示密钥的情况下要求输入,并将其存储在钥匙串中:
- 完成后告诉我,我会检查它。该检查不产生费用。
钥匙串、shell 或配置文件中的密钥适用于每个项目;.env 密钥适用于其仓库,并优先于钥匙串。on/off 选择是每个项目独立进行的。
1. 规划资源
- 风格: 读取 config: Art style 并查看其列出的参考美术。将最相近的 1-4 个现有资源作为
--ref传入,以便新美术与游戏匹配。在每个提示词中使用相同的词语描述风格:调色板、线条粗细、着色方式、相机角度和材质。 - 规格: 对于每个资源,其最终尺寸、格式、是否需要透明度、文件名及其路径(config: Assets dir,加上仓库的命名模式)。
- 显示列表,包括总数和模型,并在用户确认后生成。一次确认覆盖整个批次。
2. 生成
- 模型:
--model auto(默认)使用密钥可用的最新 gpt-image 模型(版本 2 或更高),对于最终美术,优先选择详细变体。--fast(作为--prefer fast传入)仅用于草稿。如果 config: Image model 指定了模型,则使用--model传入。 - 尺寸: 以模型支持的最大正方形或最接近的宽高比生成,然后缩小到最终尺寸(macOS 上使用
sips -Z <px>)。绝不放大。 - 透明度: 图标、物品和精灵需要
--background transparent。如果输出提示模型拒绝,则图像变为不透明:使用提示词中命名的纯色背景颜色重新生成,然后移除该颜色,并在报告中说明。 - 提示词: 描述主题,然后是风格块,最后是构图(居中、留白、除非要求否则不包含文本)。要求不包含文字、徽标或水印,除非资源需要文本。
- 将每次生成记录到 config: Art log(
--log)。切勿将元数据文件放在已交付的资源旁边。
3. 检查每张图像
在保留每张图像之前,先使用小尺寸副本检查以节省上下文。如果图像与风格参考不匹配、包含多余文字或伪影、裁剪不当或在其游戏内最小尺寸下不可读,则最多重新生成 3 次。如果仍然失败,保留最佳的一张并标记。
4. 报告
列出每个资源及其路径、尺寸、模型以及任何标记。同时列出仍需要的资源(如果生成为 off 或跳过),以及日志路径。说明图像由 AI 生成,以便所有者决定需要在哪里披露这一情况,例如在商店列表上。