/ecom-details-image

name: ecom-details-image
description: Create visual concepts, image-generation prompts, and optional AI-generated images for product hero images, marketing creatives, social posts, ads, ecommerce PDP visuals, and general visual design tasks. Use when the user asks for visual strategy, image prompt writing, product/marketing image direction, or direct text-to-image generation. In Codex environments use the built-in imagegen tool; elsewhere use the bundled script backed by the apiz CLI.

ecom-details-image Skill

当用户需要视觉策略、图片 Prompt、商品主图、营销图、社媒图、广告图、电商 PDP 视觉，或要求直接 AI 生图时，使用这个 Skill。

这个 Skill 有两种模式：

1. **Brief / Prompt 模式**：只输出视觉简报和可执行图片 Prompt。 2. **Generate 模式**：当用户明确要求“生图、生成图片、出图、render image”时，先输出最终 Prompt，再按下方**生图通道判断**选择生成方式。

不要暴露、索要、写入、提交或回显真实 API key。使用者必须通过自己的环境变量配置 API。

---

生图通道判断（Generate 模式必读）

直接生图前必须先判断当前运行环境，选择对应通道：

通道 A：Codex 环境 → agent 内置 imagegen

**判断方法**：检查你自己（agent）当前会话中是否具备内置的 `imagegen` 工具。有，说明你在 Codex 环境。

执行方式：

1. 不要调用 `scripts/generate_image.py`，直接调用内置 `imagegen` 工具。 2. 把最终 Prompt（含 Campaign Style Lock）作为 `prompt` 传入；工具如支持比例/尺寸参数，传入对应比例。 3. 如果用户提供了参考产品图，按 imagegen 工具的参考图/编辑参数传入。 4. 把返回的图片文件记录为 Generated Files；建议将文件移动或复制到 `generated-images/<产品slug>/` 目录，与本 Skill 的输出习惯保持一致。 5. imagegen 不可用或调用失败时，回退到通道 B。

通道 B：非 Codex 环境 → apiz CLI 脚本

claude code / OpenClaw 等其他环境使用 `scripts/generate_image.py`，脚本内部调用 **apiz CLI**（https://apiz.ai）提交生成任务并下载结果，不再直连任何 HTTP API。

前置条件（本机通常已就绪）：

1. 已安装 apiz CLI（`apiz --version` 可执行）。 2. 已登录：`apiz auth login` 保存过 API key，或设置了 `APIZ_API_KEY` 环境变量。认证完全由 CLI 处理，脚本不接触密钥。

可选配置（通过 `.env` 或环境变量，全部可省略）：

APIZ_IMAGE_MODEL=apiz/gpt-image-2.5-flare
# APIZ_API_KEY=sk-xxx        # 仅未使用 apiz auth login 时需要
# APIZ_BASE_URL=https://api.apiz.ai
# APIZ_BIN=C:\path\to\apiz.exe

• `APIZ_IMAGE_MODEL`：apiz 图片模型 id，默认 `apiz/gpt-image-2.5-flare`（GPT Image 2.5，支持参考图编辑、10 种比例、1K/2K/4K）。兼容旧别名 `IMG_MODEL`、`OPENAI_IMAGE_MODEL`、`OPENAI_MODEL`。
• 其他可用模型用 `apiz models list` 查看（category=image），如 `fal-ai/nano-banana-pro`、`apiz/gpt-image-2.5-sunburst`。
• 旧变量 `IMG_API_KEY`、`IMG_BASE_URL` 仍被兼容读取。

生图脚本：

python3 scripts/generate_image.py --prompt "clean product hero image..." --size 1:1
python3 scripts/generate_image.py --prompt-file prompt.txt --output-dir outputs
python3 scripts/generate_image.py --env-file .env --prompt-file prompt.txt

**参考图片**：如果用户提供了本地产品照片路径，使用 `--image` 参数传入；脚本会先 `apiz upload` 上传到 apiz CDN 换取公网 URL，再走图生图，这对保证产品外观准确非常有效。已有公网 URL 时用 `--image-url` 直接传入。

**注意**：生图会消耗 apiz 账户积分（`apiz account balance` 查看）。批量出图前先把 Image Pack Plan 报给用户确认。

如果 apiz CLI 未安装或未登录，不要阻塞：返回完整 Prompt 包，并给出安装/登录指引（`apiz auth login`），方便用户稍后自行运行。

---

核心流程

1. 判断视觉任务类型和场景（见下方**场景模板系统**）。 2. 从 `references/templates/` 匹配对应模板，读取 `prompt_template`、`variants`、`category_tips` 作为 Prompt 基础结构。 3. 只收集会实质影响图片结果的缺失信息。 4. 构建视觉简报。 5. 如果任务包含多张图，先建立 **Campaign Style Lock**，锁定整套图的色板、冷暖调、字体、背景、光线、布局和图标风格。 6. 写出可执行图片 Prompt（**保持简洁**，见下方 Prompt 精简原则）；多图任务必须把同一段 Campaign Style Lock 原样放进每张 Prompt。 7. 如果任务是商品图、详情页图或营销图，先做转化驱动力诊断。 8. 如果用户要求电商详情页、PDP、主图堆栈或整套商品图，默认输出 **5 张主图 + 7-9 张详情页图片** 的图片包。 9. 如果用户要求直接出图，按**生图通道判断**执行：Codex 环境用内置 imagegen；其他环境调用 `scripts/generate_image.py`（apiz CLI）。用户提供了参考产品图时，Codex 传给 imagegen，脚本通道传 `--image`。 10. 返回 Prompt、生成文件路径和关键假设。

---

最小输入

任何视觉任务都优先确认这些信息：

• 目标：图片要达成什么效果。
• 用途：商品主图、广告图、社媒图、Banner、PDP 模块、缩略图、概念图等。
• 主体：产品、人物、场景、物体或抽象概念。
• 受众和使用语境。
• 风格：真实摄影、编辑部风格、高级棚拍、UGC、3D 渲染、插画等。
• 构图、比例、平台尺寸。
• 是否需要图片内文字。
• 负面约束：避免 logo、避免文字、避免杂乱、避免医疗承诺等。

如果缺少非关键字段，明确假设后继续，不要无谓阻塞。

---

通用图片 Prompt 结构

默认用英文写 Prompt，除非用户要求其他语言。

Prompt 按这个结构组织：

1. Campaign Style Lock，多图任务必填且每张图完全一致。 2. 主体和场景。 3. 图片目的和情绪意图。 4. 构图、镜头和取景。 5. 光线、颜色、材质和纹理。 6. 风格和真实感等级。 7. 平台限制和画幅比例。 8. 图片内文字处理。 9. 负面约束。

Prompt 要足够具体，可以直接执行；也不要过度规定无关细节，避免和用户目标冲突。

---

GPT-Image-2 Prompt 铁律（必须遵守）

以下规则来自大量实战验证，每条 Prompt 都必须逐条检查。

1. 颜色用 hex 码，不用形容词

"白底"出来是淡灰，"金色"出来有 8 种金。必须写 hex：

• 白底 → `#FFFFFF`
• 深灰文字 → `#2D2D2D`
• 金色强调 → `#D4AF37`
• 浅米色背景 → `#F5F1E8`
• 深绿背景 → `#1A3A2E`

2. 产品占比必须数字化

不同图型的产品占比黄金区间：

| 图型 | 产品占比 | 说明 | |---|---|---| | 白底主图 | 35-40% | 太小显廉价，太大显拥挤 | | 卖点副图 | 25-30% | 左图右文布局，产品在左 | | 场景氛围图 | 20-25% | 场景图不是产品图，氛围才是主角 | | 信息流广告 | 40% | 环境干扰多，产品要更突出 | | 搜索广告 | 45% | 搜索图比信息流再大一点 | | SKU 多规格卡 | 60-70%（整体） | 多个产品横排 |

3. 留白必须显式声明

不写留白，AI 一定把画面填满。每张图必须写：

• 白底主图 / 卖点副图 / 广告图：`留白至少 45%`
• 场景氛围图：`留白至少 50%`
• 详情页长图：`留白 50%+`

4. 否定清单不能省

每条 Prompt 结尾必须加负面约束，写具体禁止项而不是笼统的"不要多余的"：

不要添加：道具、手、水印、假 logo、额外文字、装饰元素、渐变背景

5. 平台预留空间

国内电商主图必须预留：

• `顶部中央 200×100 区域留空（平台价格叠加区）` — 不写产品会把整个画面填满
• `左上角 200×100 像素区域完全留白` — logo 区域（如需要）

6. 3 层信息架构

电商图内文字必须遵循：

• 核心承诺 ≤15 字（主标题）
• 关键证据 2-3 个（图标 + 短标签）
• 行动指令 ≤8 字（CTA 按钮）

7. 批量出图优于反复调参

一次批量出图，让 CTR 数据选风格，不要凭审美反复调参。

---

Prompt 精简原则

**GPT-Image-2 在结构清晰、信息具体的 Prompt 下表现最佳。**

• 只包含核心信息，去除冗余约束和重复描述。
• 自然语言优于关键词堆砌。
• 明确描述材质纹理（磨砂玻璃、拉丝金属、哑光饰面、丝绸光泽）。
• 始终包含光线方向和质量，场景图指定色温（如 `色温 5500K`）。
• 不要在一个 Prompt 里塞入太多场景、风格、情绪要求。
• 如果用户提供了参考产品图，传入 `--image` 比文字描述更有效。
• 中文字用「」中文引号包裹，渲染准确率明显高于英文引号或无引号。
• 复杂笔画的中文字（赢、鬱、餮等）尽量换成简单同义字，95% 准确率不是 100%。

---

场景模板系统

`references/templates/` 目录包含 25 个场景模板，每个模板提供 `prompt_template`、`variants`（风格变体）、`category_tips`（品类建议）、`examples` 和 `anti_ai_tips`。

模板匹配表

| 触发词 | 模板文件 | |---|---| | 白底图, 主图, hero image, packshot | `01-hero-image.json` | | 场景图, 生活图, lifestyle | `02-lifestyle-scene.json` | | 平铺图, flat lay, 俯拍 | `03-flat-lay.json` | | 细节图, 微距, macro, 特写 | `04-detail-macro.json` | | 海报, poster, banner, 促销 | `05-poster-banner.json` | | 社交媒体, 小红书, Instagram, TikTok | `06-social-media.json` | | UGC, 买家秀, GRWM | `07-ugc-style.json` | | 模特, model, 人物展示 | `08-model-showcase.json` | | 对比, before after, 前后 | `09-before-after.json` | | 包装, packaging, 礼盒 | `10-packaging.json` | | 信息图, A+, 详情页 | `11-infographic.json` | | 创意, 概念, creative | `12-creative-concept.json` | | 尺寸, 规格, 使用步骤 | `13-size-spec.json` | | 套装, 组合, bundle | `14-multi-product.json` | | 直播, livestream | `15-livestream.json` | | 试穿, 融入, try on | `16-try-on-virtual.json` | | 拆解图, 爆炸图, exploded view