# Linkfox Aigc Imagegen Product

> 商品图生成（非服饰类）。支持单张或套图：白底主图、场景图、特写图、卖点版式图、A+详情页图。单张单类型直接出图；多张多类型自动编排规划。用户说"做套图""做白底图""做场景图""做卖点图""做A…

商品图生成（非服饰类）。支持单张或套图：白底主图、场景图、特写图、卖点版式图、A+详情页图。单张单类型直接出图；多张多类型自动编排规划。用户说"做套图""做白底图""做场景图""做卖点图""做A+图""做特写图"时触发。纯图片编辑操作走 linkfox-aigc-imagegen。

- Page: https://ss33.ai/skills/linkfox-ai/linkfox-aigc-imagegen-product-79442044044
- Publisher: linkfox-ai
- Category: [Business](https://ss33.ai/skills/category/business-y1h0vy) › [Branding & design](https://ss33.ai/skills/category/business-y1h0vy/branding-and-design-e25ohe)
- License: MIT
- Source: https://github.com/linkfox-ai/linkfox-skills/blob/ea5581c8c727f259a4fa5ea3df00e7cec77bf5ce/skills/linkfox-aigc-imagegen-product/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/linkfox-ai/linkfox-aigc-imagegen-product-79442044044

# 商品图生成

统一入口：非服饰类商品（美妆、数码、家居、食品等）的全类型电商出图能力。单张直出 & 套图编排都从这一个 skill 进入。

## 动态模型配置（动态完整列表）

本 skill 是普通图片生成场景，**不设置专用模型白名单**。商品套图、服装套图、人台换模特均从图片 bizType=201 的动态完整列表选择模型，不能因旧文档曾列出五个、六个或七个模型而拒绝其它模型。

在介绍、推荐或确认模型前，按下游文档调用查询模式（实际使用绝对路径）：

```bash
python <linkfox-aigc-imagegen根目录>/scripts/aigc_imagegen.py --list-models --inline
```

- 查询和生成都不注入 `--allowed-models`；编排脚本原样透传所选模型，不新增提交前校验或参数重写。
- 返回 `name` 用于展示，`requestValue` 用于构造内部请求。未命中旧模型表但存在于当前列表的模型，正常接受。
- 只按实际任务能力筛选：参考图数量、支持比例、分辨率和质量档位等。例如不支持参考图的模型不能用于本场景，但不是因历史白名单而排除。
- 仅配置查询失败时使用底层返回的静态兜底列表；下方旧表只是历史请求值参考，不作为本 skill 的可选模型上限。成功但缺失/维护中不恢复旧选项，不自动换模型。
- 原默认模型、缺参确认方式和业务流水线保持不变；默认参数不再合法时提示补充或重选，不跟随后台 `isDefault` 自动替换。

## 入口路由

| 条件 | 路径 | 操作 |
|------|------|------|
| 只要一张特定类型的图（如"做一张白底图"） | **单张直出** | 确定 type → **Read** 对应 `references/types/<type>.md` → 执行共享流水线 |
| 要多张 / 多类型 / 套图（如"做一套图""出5张图"） | **套图编排** | Read `references/runtime/00-index.md` → 按步 Read `01-plan` / `02-confirm` → 调 `scripts/run_collection_pipeline.py` **三阶段**（plan / dispatch / summary，agent 顺序发 3 个 Bash；dispatch 在 skill 层用 `ThreadPoolExecutor` 并发跑 `scripts/run_one_task.py`，agent 自己**不**并发；**禁止** Read `maintainer/collection/` 或套图阶段 Read `types/*.md`） |

## 类型路由表

| type | 名称 | 与卖点关联 | 是否有画面描述 | 默认比例 | 详情 reference |
|------|------|-----------|-------------|---------|----------------|
| WHITE_BG | 白底图 | 否 | 否 | 1:1 | `references/types/white-bg.md` |
| SCENE | 场景图 | 是 | 是 | 1:1 | `references/types/scene.md` |
| CLOSE_UP | 特写图 | 是 | 是 | 1:1 | `references/types/close-up.md` |
| SELLING_POINT | 卖点图 | 是 | 是 | 1:1 | `references/types/selling-point.md` |
| PREMIUM_APLUS | 高级A+图 | 是 | 是 | 1464:600 | `references/types/aplus.md` |
| STANDARD_APLUS | 普通A+图 | 是 | 是 | 970:600 | `references/types/aplus.md` |
| PHONE_APLUS | 手机A+图 | 是 | 是 | 600:450 | `references/types/aplus.md` |

确定 type 后，**必须 Read** 对应的 type reference 文件获取该类型的步骤 2 差异逻辑和提示词模板，**禁止跳过**。

## 不适用

- 服饰 / 模特类图片（上装/下装/连衣裙/外套/鞋帽等）→ 走 `linkfox-aigc-imagegen-cloth` 系列。
- 纯图片编辑操作（换背景、去水印、换角度等已有明确创意方向的操作）→ 走 `linkfox-aigc-imagegen`。
- 纯文字生成 → `linkfox-aigc-textgen`。
- 视频生成 → `linkfox-aigc-videogen`。

## 共享流水线

所有类型都走同一条 3 步流水线，差异部分由各 type reference 定义。

### 步骤 1：校验图片 URL 可访问性（所有类型通用）

- **输入**：`imageUrls`
- **空数组护栏（强制）**：若 `imageUrls` 为空数组 / 缺失 / 全部无效，**立即停止**，不得带空图调下游。优先从上下文（用户本轮/历史上传的原始图片路径）补齐；仍无法补齐时如实向用户报错并请求重新上传，**禁止**带空 `imageUrls` 继续执行。
- **操作**：逐项检查 `imageUrls` 中的值（保持原顺序）：已是公开 URL（http/https 开头）→ 直接透传；本地文件路径（非 http/https）→ 读取并按本 skill 内置的 [references/file-upload.md](references/file-upload.md) 执行上传，获得公开 URL 后替换；无需安装额外上传 skill。
- **输出**：`imageUrls`（全部为公开可访问的 HTTPS URL）

### 步骤 2：构造最终 prompt（差异部分见各 type reference）

各类型的步骤 2 逻辑不同（是否调 textgen、用哪个模型、是否做敏感词规避等），详见已 Read 的 `references/types/<type>.md`。

> **白底图静态直出约束（WHITE_BG）**：用 `scripts/build_imagegen_prompt.py --type WHITE_BG` 构建 imagegen 参数文件，脚本会自动从 `references/types/white-bg.md` 的 ```text``` 代码块提取白底图静态正文作为最终 prompt。正文较长，一律交脚本读取，**不要手动复制或经 shell 变量传递**。
>
> **textgen 链式调用约束（适用于除白底图外的所有类型）**：凡需调 `linkfox-aigc-textgen` 的类型，必须使用本 skill 的 `build_textgen_params.py` 辅助脚本构建 textgen 参数文件（脚本自动完成模板读取、占位符填充、模型/thinkingLevel 设置、敏感词规避指令追加），然后按 textgen SKILL.md 的**链式调用方式**执行。
>
> **套图强制走 pipeline 三阶段**：套图路径用 `scripts/run_collection_pipeline.py` 跑 plan / dispatch / summary 三阶段，agent 按顺序发 3 个 Bash；并发由 skill 层 dispatch 用 `ThreadPoolExecutor` 完成，**agent 自己不并发**：
>
> 1. `--phase plan` 写 `image-plan.json` / `collection-state.json`，stdout 直接打 markdown 表格 + 1 行 status JSON（含 `specs[]` / `run_one_task_script` / `state_file` / `total`）
> 2. 用户确认后，agent 只发 1 个 dispatch Bash：`python <本skill根>/scripts/run_collection_pipeline.py --phase dispatch --state <state_file>`；dispatch 内部用 `ThreadPoolExecutor` 并发跑 `run_one_task.py --index 1..N`，每个子任务落 `task-result-<id>.json` 片段；dispatch 自身 stdout **不** emit `Saved full response`，仅末尾 1 行 `{"status":"dispatch_complete",...}` 供 agent 内部解析（这条 Bash 不渲染图，是正常的）
> 3. `--phase summary --state <state_file>` 读片段 → stdout 打末尾 markdown 明细（**每张成功图自带 `![label](abs_path)` 内联引用**，前端 markdown 渲染器据此渲染整组图）+ 1 行 status JSON；同时合并写 `collection-asset-manifest.json`
>
> **禁止** Agent 手工 S1 或 Read S0~S3 全文；**禁止**用户确认后自己拆 N 个 Bash 跑 `run_one_task.py`（旧协议；现在并发已在 skill 层完成，自己并发只会重复出图）；**禁止**转发 summary markdown 时把 `![]()` 行剥掉（整组图就靠这些行渲染）；**禁止**在 summary 之外另贴 `Saved full response: [...]`（与 markdown `![]()` 双重渲染）。下方 bash 单步链路**仅适用于单张直出**。
>
> **路径铁律**：本链路横跨两个 skill 目录（构参脚本属本 skill，生文与注参脚本属 `linkfox-aigc-textgen`），当前工作目录不固定，**所有脚本一律用绝对路径调用，不要用裸 `scripts/...` 相对路径**（相对路径会指向错误目录导致执行失败）。其中 `<本skill根目录>` = 本 SKILL.md 所在目录的绝对路径；`<textgen根目录>` 通过 `skill:linkfox-aigc-textgen` 解析其 SKILL.md 所在目录的绝对路径取得。
>
> 1. 构参（本 skill）：`python <本skill根目录>/scripts/build_textgen_params.py --type <TYPE> ... --out <textgen_params.json>`
> 2. 生文（textgen skill）：`PROMPT=$(python <textgen根目录>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>)` —— `--content-only` 输出单行 content 捕获进变量（换行压平为 `⏎`、下游自动还原的机制见 textgen SKILL.md）。
> 3. 注参（步骤 3，用 `jq` 内联）：用 `jq` 把 `$PROMPT` 内联拼进下游 imagegen 参数 JSON，再交 `linkfox-aigc-imagegen` 出图。
>    ```bash
>    PROMPT=$(python <textgen根目录>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>)
>    PARAMS=$(jq -nc --arg p "$PROMPT" --argjson imgs '<步骤1的URL JSON数组>' \
>      '{prompt:$p, imageUrls:$imgs, provider:"<provider>", outputNum:1, aspectRatio:"<ratio>", resolution:"<resolution>"}')
>    # 然后按 linkfox-aigc-imagegen SKILL.md 的调用方式把 $PARAMS 传入出图
>    ```
>
> **禁止**手动用 Write 工具构造 textgen 参数文件（必须经 `build_textgen_params.py`）、用 `jq -r` 抽取原始 content（会重新引入真实换行符破坏拼接）、或直接写 Python 调 API 绕过此链路。

### 步骤 3：调 `linkfox-aigc-imagegen` 出图（所有类型通用）

- **输入**：步骤 2 的 `prompt`、步骤 1 的 `imageUrls`、`ratio`、`resolution`、`provider`
- **操作**：**Read `skill:linkfox-aigc-imagegen` 的 SKILL.md，按其调用方式执行出图脚本**。传入参数：
  - `prompt`：步骤 2 产出的最终 prompt
  - `imageUrls`：步骤 1 的全部图片 URL
  - `provider`：入参指定的模型（默认 `BANANA_PRO`）
  - `aspectRatio`：`ratio` 原样透传
  - `resolution`：原样透传
  - `outputNum`：`1`
- **输出**：图片（`Saved full response:` 后的本地路径）
- **单张直出交付（按类型）**：本 skill 单张直出场景按 `references/runtime/03-deliver.md` §3.1 走，agent 在 imagegen Bash 完成后必须：
  1. 解析 stdout 的 `Saved full response: ["..."]` 取本地路径（成功时 1 张）
  2. 在对话回复正文里**追加** markdown 内联块：

     ```markdown
     - 第 1 张 · <类型中文名>
       ![<类型中文名>](<abs_path>)
     ```

  3. **类型中文名对照**：SCENE→场景图 / CLOSE_UP→特写图 / SELLING_POINT→卖点图 / WHITE_BG→白底图 / PREMIUM_APLUS→高级A+图 / STANDARD_APLUS→普通A+图 / PHONE_APLUS→手机A+图
  4. **禁止**把 `Saved full response: [...]` / `Saved full response: <json路径>` 协议原文复述进对话回复——它是 skill ↔ bridge 内部协议行，复述会让用户看到裸露的 JSON 数组路径（即"协议行裸露"故障）；只读它取路径，不抄字面
  5. **禁止**自行 echo 一遍 `Saved full response:` 字面让 bridge 再渲染——bridge 路径 A 的「任务产出」资源卡是 imagegen Bash stdout 自动触发的，agent 不要手动复制
  6. **双重渲染**（markdown 内联图 + bridge「任务产出」资源卡同时呈现）是当前协议下的预期行为，不算故障
  7. 失败情形（stdout 是 `Saved full response: <data 路径>.json` 单文件）按本 SKILL.md「错误处理与失败护栏」如实告知，不追加内联图

### 中间产物落盘（强制）

所有要跨步骤复用或交付的文件一律落到会话目录 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/{data|media}/`（协议见仓库 `CLAUDE.md`「输出文件位置」）。

| 产物类型 | 目录 | 获取方式 |
|---------|------|---------|
| 品牌基因 JSON | `data/` | `linkfox-aigc-imagegen-brand-gene-extract` 的 `save_brand_gene.py` |
| 套图规划 image-plan.json | `data/` | S2 确认后 `scripts/save_image_plan.py` 逐条追加落盘 |
| imageUrls 数组 | `data/` | 步骤 1 校验后 Write 到 `$DATADIR/image-urls.json`（通常很小） |
| task-result-*.json | `data/` | 每个 `run_one_task.py` 完成后落盘的任务结果片段，summary phase 读后汇总末尾 markdown + asset manifest |
| collection-asset-manifest.json | `data/` | summary phase 自动从 task-result 片段中合并 `assets[]` 写出，记录每张结果图的 `src`、`slot`、`type`、`label`，供 Listing HTML 合并重渲染 |
| 单张构参 JSON（textgen/imagegen 入参） | `data/` | `build_textgen_params.py` / `build_imagegen_prompt.py` 的 `--out`（仅单张直出场景） |
| 结果图 | `media/` | `linkfox-aigc-imagegen` 脚本自动落盘 |

`DATADIR=$(python <brand-gene根目录>/scripts/save_brand_gene.py --datadir)`；下游 `--brand-gene-file` 指向 S1 落盘的品牌基因绝对路径。

## 下游 skill 调用约定

本 skill 依赖下表两个下游 skill，**按文档化方式调用**：先 Read 对方 SKILL.md 了解其调用方式，单张直出按步骤 2/3 的链式命令、套图按 `scripts/run_collection_pipeline.py` + `scripts/run_one_task.py` 编排——两者都按文档以**绝对路径**调用下游官方脚本（这是允许的）。本 skill 自带的 `build_textgen_params.py` / `build_imagegen_prompt.py` / `run_collection_pipeline.py` / `run_one_task.py` 等是参数构建与编排辅助脚本，可直接运行。脱离上述文档化链路自行拼调用、或直连下游 HTTP API 才是不允许的。

| 下游 skill | 用途 | 调用时机 |
|------------|------|---------|
| `linkfox-aigc-imagegen` | AI 生图 | 步骤 3（所有类型） |
| `linkfox-aigc-textgen` | 提示词改写 | 步骤 2（除白底图外的所有类型） |

调用方式：Read `skill:<skill-name>` 的 SKILL.md，按其中的调用方式章节执行。

## 共享输入参数

以下参数为所有类型通用（类型特有参数见各 type reference）：

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `imageUrls` | string[] | 必填 | 商品参考图 URL。步骤 1 会校验可访问性 |
| `ratio` | string | 随类型 | 图片比例，原样透传给 imagegen 的 `aspectRatio` |
| `resolution` | string | 2K | 按所选模型当前支持的分辨率选择；默认2K不变，旧2K/4K不是完整选项目录 |
| `provider` | string | — | 从图片 bizType=201 动态完整列表中选择能力匹配的模型，内部使用 requestValue；未指定时沿用原确认/默认策略，不以历史模型表作枚举限制 |

## 错误处理与失败护栏

> `linkfox-aigc-imagegen` skill 对**业务失败也返回 exit 0**（不是非零退出），所以**不能靠命令退出码判断成败，必须解析 stdout**。

**1. 怎么判一次调用成败**
- **成功**：stdout 含 `Saved full response: ["xxx.png", ...]`（JSON 数组路径）→ 图片已落盘 media/，取路径展示。
- **失败**：stdout 含 `Saved full response: xxx.json`（单个 JSON 文件路径，非数组）→ 无图片产物，需读该 JSON 查看错误详情（`errcode`/`errmsg`/`error`）。

**2. 失败怎么处理（按类型分流）**
| 失败类型 | 判断依据 | 处理 |
|----------|----------|------|
| 参数非法 | `errmsg`/`errorMsg` 指向 `provider`、`aspectRatio`、`resolution`、`quality` 等入参不被接受 | 用 `AskUserQuestion` 让用户重选对应参数 |
| 认证失败 | `errcode==401` 或提示 API Key | 停止并提示用户配置 `LINKFOX_AGENT_API_KEY`，不重试 |
| 瞬时错误 | `error` 为网络/超时/连接失败（`Connection failed`、timeout 等） | **最多自动重试 1 次**；再失败转「其它错误」 |
| 其它错误 | 配额、内容被拒、服务端 5xx、未知 errcode 等 | **不重试**，如实告知用户失败原因 |

**3. 硬性护栏（违反即视为故障）**
- ❌ **禁止因生图失败改调任何其它 skill**——本 skill 的生图路径唯一（`linkfox-aigc-imagegen`），失败就按上表处理或上报，绝不"换一个 skill 试试"。
- ❌ **禁止无上限重试**：除"瞬时错误最多 1 次"外，同一类失败不得反复重试。
- ❌ **禁止把失败的返回体当成功**继续往下走（展示空图、告诉用户"已生成"）。

## 全局规则

### 动态模型选择与历史请求值参考

本 skill 不限定模型枚举。当前可选模型以底层动态完整列表及任务能力为准；下表仅记录旧请求值，供兼容历史调用，不能用于拒绝新增模型。未传模型时仍沿用原确认方式。

| 模型名称 | 内部代码 |
|---------|---------|
| LFBanana Pro | `BANANA_PRO` |
| Img2 | `GPT_2_IMAGE` |
| Img2.5 sunburst | `GPT_2_5_IMAGE` |
| Img 2.5 flare | `GPT_2_5_F_IMAGE` |
| LFBanana2 | `BANANA_2` |
| Linkfox-Image-1 | `AIDRAW_EDIT` |
| Wan 2.7 | `WAN2_7` |

**模型确认**：未传 `provider` 时，沿用原确认方式，让用户从当前可用列表选择；已指定且存在于当前列表、能力满足任务时直接下发对应请求值，即使不在旧表内也正常接受。确实不在当前列表或能力不匹配时再提示重选，不用旧模型表作校验。

### 分辨率规则

**分辨率仍是步骤 3 的必传参数**。选项读取所选模型当前支持的分辨率；旧2K/4K目录不构成选项上限，原默认策略不变。

1. agent 层透传了 `resolution`：沿用原参数透传方式，不以旧2K/4K目录额外拒绝当前模型支持的值
2. agent 层未透传：使用 `AskUserQuestion` 让用户从所选模型当前支持的分辨率中选择

### 任务独立性声明

套图中的每张图片都是**独立任务**，各任务之间互不依赖。单个类型出图失败不影响其余任务继续执行。

### 执行期约束

1. **上传边界**：出图流水线接收 `imageUrls`，不自动上传。本地输入图或需公开的产物由调用方按本 skill 内置的 [references/file-upload.md](references/file-upload.md) 执行上传后传入；无需查找或安装额外上传 skill。
2. **计划管理工具使用规范**：单张直出时不使用计划工具。套图并发出图前须为 N 张图创建任务计划（见 `references/runtime/02-confirm.md`）。
3. **套图落盘**：plan / summary 由 `run_collection_pipeline.py` 写盘；**禁止** Agent 凭记忆 Write 整份 manifest / image-plan。
4. **Listing 报告回写资产清单（强制）**：套图 summary 完成后保留 `$DATADIR/collection-asset-manifest.json`。Listing HTML 合并只用 `agent-listing-result-html-skill/scripts/merge-listing-assets.mjs`。如果 manifest 中仍是本地 `media/` 路径，由调用方先按本 skill 内置的 [references/file-upload.md](references/file-upload.md) 执行上传，换成公开 OSS URL 并更新 manifest，再执行 merge；出图流水线不自动上传，但不得暗示本地路径可直接写入 HTML。

## 套图编排流程（runtime，渐进 Read）

**仅套图路径触发**；单张直出不要 Read 本节。

| 步骤 | Read | 操作 |
|------|------|------|
| 入口 | `references/runtime/00-index.md` | S0 场景判定 |
| plan | `references/runtime/01-plan.md` | 写 job.json → `--phase plan`，stdout markdown 表格原样转发 + AskUserQuestion |
| 确认 → dispatch → summary | `references/runtime/02-confirm.md` | 用户确认 → agent 发 1 个 `--phase dispatch` Bash（skill 层并发跑全部 `run_one_task.py`，不渲染图）→ 紧接 1 个 `--phase summary` Bash 写 manifest + 打含 `![]()` 的 markdown 明细 |

维护细则见 `references/maintainer/collection/`，**运行时禁止 Read**。

## 已知局限

- 白底图模板为静态指令，无品类识别与结构判定，全品类统一按"去背 + 精修 + 居中放大"处理；异形 / 透明 / 反光类产品的边缘处理可能不及预期。
- 场景图/特写图强依赖 `linkfox-aigc-textgen`（`GEM_3_FLASH`）对品类与结构的判定，判定错误会直接传导到构图。
- 卖点图/A+ 共用字典模板，靠 `{layoutInfo}` 区分；意图填错会导致版式串型。
- 模板正文以服装品类口吻写就（"面料质感 / 版型优势"），用于非服饰商品时由模型自适应。
- 多张参考图时由模型自行判断主体，复杂组合下可能误判。
- 不做敏感词改写（场景图/特写图/白底图）：若卖点/场景含违禁内容，本链路不拦截，由上游或人工把关。卖点图/A+ 图在 textgen 环节含敏感词规避。

## 解决认证和算力问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

### 异常情况
- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。
- **响应401或402状态码**
- **响应提示算力或余额不足**：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。