| 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 with their own OpenAI-compatible API. |
ecom-details-image Skill
当用户需要视觉策略、图片 Prompt、商品主图、营销图、社媒图、广告图、电商 PDP 视觉，或要求直接 AI 生图时，使用这个 Skill。
这个 Skill 有两种模式：
- Brief / Prompt 模式：只输出视觉简报和可执行图片 Prompt。
- Generate 模式：当用户明确要求“生图、生成图片、出图、render image”时，先输出最终 Prompt，再调用
scripts/generate_image.py。
不要暴露、索要、写入、提交或回显真实 API key。使用者必须通过自己的环境变量配置 API。
生图配置
直接生图使用 apimart.ai 图像生成接口（GPT-Image-2，异步轮询模式）。优先在 .claude/skills/ecom-details-image/ 放 .env，不要把真实 API key 写进仓库：
IMG_BASE_URL=https://api.apimart.ai/v1
IMG_MODEL=gpt-image-2
IMG_API_KEY=your-api-key
脚本也兼容常见别名：OPENAI_BASE_URL、OPENAI_API_BASE、OPENAI_IMAGE_MODEL、OPENAI_MODEL、OPENAI_API_KEY。
生图脚本：
python3 scripts/generate_image.py --prompt "clean product hero image..." --size 1:1 --resolution 2k
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 参数传入。这是提升产品外观一致性的最关键手段，忽略参考图会导致生成结果与真实产品差异巨大。
如果缺少任何生图配置，说明需要在 .env 里配置什么，并把最终 Prompt 交给用户，方便用户稍后自行运行。
核心流程
- 判断视觉任务类型和场景（见下方场景模板系统）。
- 从
references/templates/ 匹配对应模板，读取 prompt_template、variants、category_tips 作为 Prompt 基础结构。
- 只收集会实质影响图片结果的缺失信息。
- 构建视觉简报。
- 如果任务包含多张图，先建立 Campaign Style Lock，锁定整套图的色板、冷暖调、字体、背景、光线、布局和图标风格。
- 写出可执行图片 Prompt（保持简洁，见下方 Prompt 精简原则）；多图任务必须把同一段 Campaign Style Lock 原样放进每张 Prompt。
- 如果任务是商品图、详情页图或营销图，先做转化驱动力诊断。
- 如果用户要求电商详情页、PDP、主图堆栈或整套商品图，默认输出 5 张主图 + 7-9 张详情页图片 的图片包。
- 【必须】如果用户要求直接出图，必须调用
scripts/generate_image.py；如果用户提供了参考产品图，必须传入 --image 参数。
- 返回 Prompt、生成文件路径和关键假设。
最小输入
任何视觉任务都优先确认这些信息：
- 目标：图片要达成什么效果。
- 用途：商品主图、广告图、社媒图、Banner、PDP 模块、缩略图、概念图等。
- 主体：产品、人物、场景、物体或抽象概念。
- 【关键】参考图：用户是否提供了参考产品图？如果有，生成时必须使用
--image 参数。
- 受众和使用语境。
- 风格：真实摄影、编辑部风格、高级棚拍、UGC、3D 渲染、插画等。
- 构图、比例、平台尺寸。
- 是否需要图片内文字。
- 负面约束：避免 logo、避免文字、避免杂乱、避免医疗承诺等。
如果缺少非关键字段，明确假设后继续，不要无谓阻塞。
通用图片 Prompt 结构
默认用英文写 Prompt，除非用户要求其他语言。
Prompt 按这个结构组织：
- Campaign Style Lock，多图任务必填且每张图完全一致。
- 主体和场景。
- 图片目的和情绪意图。
- 构图、镜头和取景。
- 光线、颜色、材质和纹理。
- 风格和真实感等级。
- 平台限制和画幅比例。
- 图片内文字处理。
- 负面约束。
Prompt 要足够具体，可以直接执行；也不要过度规定无关细节，避免和用户目标冲突。
Prompt 精简原则（关键）
图片生成模型在简洁聚焦的 Prompt 下表现最佳，而非冗长复杂的描述。 这是最影响生成质量的环节。
- 只包含核心信息，去除冗余约束和重复描述。
- 自然语言优于关键词堆砌。
- 明确描述材质纹理（磨砂玻璃、拉丝金属、哑光饰面、丝绸光泽）。
- 始终包含光线方向和质量。
- 不要在一个 Prompt 里塞入太多场景、风格、情绪要求。
- **【关键】如果用户提供了参考产品图，传入
--image 参数比文字描述更有效。
场景模板系统
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 | 17-exploded-view.json |
| 隐形模特, ghost mannequin, 3D服装 | 18-ghost-mannequin.json |
| 多角度, 网格, grid, 多色展示 | 19-multi-angle-grid.json |
| 杂志, 封面, editorial, magazine | 20-magazine-editorial.json |
| 季节, 四季, campaign, 春夏秋冬 | 21-seasonal-campaign.json |
| 奢华, 氛围, 烟雾, luxury, atmospheric | 22-luxury-atmospherics.json |
| 设备模型, 界面, mockup, SaaS, APP | 23-device-mockup.json |
| 店铺, 门面, 空间, storefront, 实体店 | |
无匹配 → 默认 01-hero-image.json。只读取匹配到的模板文件，不要一次性加载全部。
模板使用方式
- 取
prompt_template 作为 Prompt 基础结构。
- 用用户产品信息替换
{variables}。
- 用户指定风格变体 → 应用
variants.<name>.overrides。
- 已知产品品类 → 应用
category_tips.<category>。
- 简化：只保留有值的字段，输出简洁的自然语言 Prompt。
风格变体速查
每个模板通常包含 3-4 个风格变体，常用变体类型：
- luxury — 高端奢华（Rembrandt 光线、金色点缀、深色渐变）
- minimal — 极简现代（纯白/浅色、干净线条、大留白）
- fresh — 清新自然（明亮自然光、柔和粉彩、通透感）
- tech — 科技感（戏剧性侧光、深色背景、金属质感）
Anti-AI 技巧（UGC / 直播 / 社媒场景）
生成 UGC、直播或社媒内容时，必须遵循以下规则让图片看起来真实：
- 指定具体手机型号：
iPhone 14 Pro、iPhone 15 Pro。
- 添加可见瑕疵：毛孔、轻微噪点、暖色偏移、不完美构图。
- 使用真实感语言：
NOT professional photography、NOT AI-generated look。
- 展示真实环境：略微凌乱、真实物品、水渍、用过的毛巾。
- 参考胶片色调：
Kodak Portra 400 color feel。
- 明确声明：
NOT retouched, NOT smoothed。
- 避免典型 AI 词汇：不用
perfect、flawless、stunning、hyper-realistic。
- 各模板中如有
anti_ai_tips 字段，生成对应场景时必须遵循。
整套图片风格一致性规则
当生成主图 + 详情页、PDP 图片包、广告组图、社媒组图或任何多张图片时，必须先定义一个 Campaign Style Lock。这是整套图的视觉合同，不是灵感描述。
Campaign Style Lock 必填字段
- 视觉方向：例如 premium tech ecommerce、clean household care、warm gift editorial。
- 固定色板：限制为 2-3 个主色 + 1 个强调色；写清楚背景色、文字色、强调色，不要每张图重新配色。
- 冷暖调：明确 warm / cool / neutral，并要求全套一致。
- 字体系统：统一为一种字体风格，例如 modern geometric sans-serif；禁止混用衬线、手写、复古、卡通字体。
- 背景系统：统一背景材质、空间和深浅，例如 clean light gray studio background 或 deep navy premium tech background。
- 光线系统：统一光源方向、阴影强度、反光质感和氛围。
- 布局系统：统一留白、圆角、分栏、标签、编号和信息图组件风格。
- 图标 / 插画系统：如果用图标，统一线宽、形状、颜色和复杂度。
- 产品呈现规则：产品角度、大小比例、材质表现和是否居中必须稳定。
- 禁止漂移项：明确禁止 changing color palette, mixed fonts, inconsistent lighting, random backgrounds, mismatched icon styles。
默认 Style Lock 模板
如果用户没有给品牌规范，使用保守统一的电商视觉系统：
Campaign Style Lock: consistent premium ecommerce visual system across the entire image set; fixed palette of clean off-white background, deep charcoal text, one product-matched accent color, and one soft secondary accent; neutral-cool studio lighting; modern geometric sans-serif headline placeholders only; consistent rounded rectangular info labels; consistent thin-line icon style; clean high-end product photography mixed with minimal infographic elements; stable product scale and placement; generous whitespace; no color palette changes, no mixed fonts, no random backgrounds, no inconsistent lighting, no mismatched icon styles.
多图 Prompt 强制规则
- 每张图 Prompt 的第一段必须是同一段 Campaign Style Lock，不能改写、缩短或换同义词。
- 单张图只能改变：画面目的、主体动作、局部构图和短文案。
- 单张图不能改变：色板、冷暖调、字体风格、背景系统、光线系统、图标风格和信息标签样式。
- 如果用户要求重生其中一张图，必须复用原来的 Campaign Style Lock。
- 如果已生成图片风格不一致，优先重写 Prompt 包，而不是逐张随意补描述。
商品和营销转化流程
商品主图、电商图片、广告图和 PDP 视觉不要从固定模板开始，要先判断转化驱动力。
选择一个主要驱动力：
A. 视觉驱动型
适用于购买决策依赖外观、风格匹配、光洁度、质感、前后对比或礼品属性的产品。
重点：
- 一眼抓住产品吸引力。
- 质感、细节、工艺和质量信号。
- 使用场景和视觉层级。
- 简短利益点。
B. 痛点驱动型
适用于买家有明确摩擦、风险、时间损失、不适或反复烦恼的产品。
强制顺序：
- 痛点挖掘 / 风险触发。
- 利益 / 解决方案。
- 信任和证明。
- 优惠 + CTA。
重点是具体问题、缓解机制、证据和风险逆转。
C. 情感价值驱动型
适用于购买和身份、信心、归属、地位、关怀、快乐、新奇或冲动相关的产品。
重点：
- 情绪钩子。
- 身份或向往。
- 产品作为实现方式。
- 社交证明和低摩擦行动。
商品图序列模板
当用户提到“详情页、PDP、Amazon A+、Shopify 商品页、主图堆栈、整套商品图、商品详情图片”时，不要只停留在 5 张主图。必须追加详情页图片序列，并把每一屏都写成可单独生图的 Prompt。
视觉驱动主图序列
- 一眼可懂的视觉主张。
- 核心功能或质感特写。
- 使用场景匹配。
- 普通方案 vs 升级方案对比。
- 优惠、物流、保障或 CTA 画面。
痛点驱动主图序列
- 问题快照。
- 解决机制。
- 利益证明。
- 信任画面。
- 优惠 + 紧迫 CTA。
情感价值主图序列
- 情绪场景钩子。
- 身份 / 价值表达。
- 产品作为实现方式。
- 归属、地位或社交信号。
- 带情绪强化的优惠 + CTA。
详情页图片序列模板
详情页图片用于移动端纵向浏览，默认每张图独立成屏，尺寸优先使用 2:3 或平台指定竖版比例。除非用户明确只要文案，否则每个模块都要输出对应图片 Prompt。
通用 PDP 详情页图片序列
- 首屏承接：延续主图卖点，说明产品为谁解决什么问题。
- 痛点放大：展示用户当前的不便、损失、风险或反复烦恼。
- 机制解释：用视觉化结构说明产品如何发挥作用，避免虚构无法证明的数据。
- 核心利益：把 2-4 个主要利益做成易扫读的信息图。
- 使用步骤：用 3-4 步说明怎么用，降低理解成本。
- 场景覆盖：展示典型使用场景、适用对象或使用前后状态。
- 对比选择：普通方案 vs 本产品，突出可观察差异和体验差异。
- 信任背书：展示材料、包装、质检、保障、真实评价等已有证据；没有证据就写“proof placeholder”，不要编造认证。
- FAQ / 风险逆转 / CTA：处理残留、适用范围、售后、组合优惠等临门疑虑。
驱动力适配
- 视觉驱动型：增加质感细节、尺寸比例、使用场景和礼品感。
- 痛点驱动型：严格按“问题严重性 → 解决机制 → 利益证明 → 信任 → CTA”推进。
- 情感价值驱动型：增加生活方式、身份表达、社交场景和情绪回报。
图片内文字规则
- 详情页图片可以有短文案，但必须短、清楚、适合移动端。
- 每屏主标题建议 3-7 个英文词或 6-12 个中文字。
- 说明性文字用 2-4 个短标签，不要生成大段小字。
- 如果模型容易生成乱码，Prompt 中明确要求 “clean layout with short readable headline placeholders, no dense body text”。
多图生成执行规则
当用户要求直接生成整套电商图片：
- 先建立 Campaign Style Lock，并写入图片包计划。
- 再为每张图建立编号、用途、画幅、图片内短文案和独立 Prompt。
- 主图默认
1:1（2K）；详情页图片默认 2:3（2K）。
- 每张图使用独立 Prompt 文件，避免一次 Prompt 生成多屏拼图。
- 每张独立 Prompt 必须以同一段 Campaign Style Lock 开头。
- 输出目录用产品英文 slug，例如
generated-images/laundry-detergent-pods-pdp/。
- 如果 API 或模型不支持某个尺寸，改用最接近的支持尺寸，并在结果中说明。
- 如果缺少
.env 或生图配置，只输出完整 Prompt 包，不调用脚本。
- 不要虚构认证、实验数据、评分、销量、真实评价或品牌授权。
直接生图规则
当用户要求生成图片：
- 先输出最终 Prompt。
- 短 Prompt 用
--prompt，长 Prompt 用 --prompt-file。
- 根据平台选择
--size（比例格式），没有要求时默认 1:1。
--resolution 默认 2k，4K 仅限 6 个宽幅比例。- 只有用户指定目录时才使用
--output-dir，否则使用 generated-images/。
- 如果缺少
IMG_API_KEY 等配置，不要调用脚本；返回 Prompt 和配置命令示例。
命令形状：
python3 scripts/generate_image.py --prompt "..." --size 1:1 --resolution 2k
脚本支持：
--prompt--prompt-file--output-dir--size：比例格式（1:1、16:9、2:3、4:5 等 14 种）--resolution：1k / 2k / 4k，默认 2k--image【必须】：参考产品图片路径，当用户提供参考图时必须使用此参数--poll-interval：轮询间隔秒数，默认 5--timeout：轮询超时秒数，默认 180--format：保存格式（仅影响扩展名），默认 png
QA 检查
最终输出前确认：
- Prompt 符合用户真实目标。
- 已匹配正确的场景模板，Prompt 基于模板的
prompt_template 组装。
- Prompt 保持简洁，只包含核心信息，没有冗余约束。
- 主体、构图、风格和用途明确。
- 商品 / 营销任务包含转化驱动力诊断。
- 证据缺失时不虚构效果、认证或数据。
- 图片内文字短且必要。
- UGC / 直播 / 社媒场景已应用 anti-AI 技巧（模板中的
anti_ai_tips 字段）。
- 【必须检查】如有用户参考图片，必须传入
--image 参数。
- 负面约束覆盖常见失败点。
- 输出和文件里没有 API key 或私密凭据。
输出格式
Brief / Prompt 模式返回：
- 匹配模板：使用的模板文件名和场景类型
- Visual Brief
- Final Image Prompt
- Negative Constraints
- Assumptions
商品或营销任务追加：
- Conversion Driver Diagnosis
- Campaign Style Lock，当任务包含多张图片
- Hero Image Sequence（标注每张图对应的模板文件）
- PDP Detail Image Sequence，当请求涉及详情页、PDP 或整套商品图
- Copy Lines，如果图片需要文字
- Test Priorities
Generate 模式返回：
- 匹配模板：使用的模板文件名和场景类型
- Final Image Prompt
- Campaign Style Lock，多图任务必须返回
- Image Pack Plan，包含每张图的编号、用途、尺寸、对应模板和短文案
- Generated Files
- Assumptions / Notes
