linkfox-aigc-imagegen-brand-gene-extract

ブランド遺伝子スタイル抽出（Brand Gene Extract）

商品画像とユーザーのブランド遺伝子パラメーターに基づいて、統一されたブランドビジュアル言語（Brand DNA）を抽出し、下流のアトミックスキルが利用できる構造化 JSON を出力します。

---

適用シーン

シーン	説明
セット画像の構成での呼び出し	linkfox-aigc-imagegen-cloth / linkfox-aigc-imagegen-product（セット画像の構成パス）からステップ三で呼び出され、セット全体の統一されたビジュアル遺伝子を定義します
ブランド遺伝子の変更	ユーザーがメインカラー／フォント／プラットフォーム／地域を変更した後に再抽出します
初回のブランド定義	コンテキストにブランド遺伝子の結果がまだ存在しない場合に、初回抽出を行います

不適用

• 完全な brandGeneJson がすでにあり、変更する必要がない場合（直接再利用し、この skill を再度呼び出しません）
• 背景の置き換え／切り抜き／合成など、純粋な画像編集操作
• ビジュアル以外のブランドストーリーのコピー

---

入力パラメーター

パラメーター	型	デフォルト	説明
images	list[image]	—	ユーザーがアップロードした商品画像のリスト（1 枚以上）。商品の色彩と雰囲気の分析に使用します
brandKey	object	—	ユーザーが入力したブランド遺伝子情報（下記のフィールド説明を参照）

brandKey フィールドの説明

フィールド	型	デフォルト	説明
brandColor	string	""	ブランドのメインカラー（HEX 値）。空でない場合はそのまま使用し、空の場合は自動抽出します
fontStyle	string	""	フォントスタイル。空でない場合はそのまま使用し、空の場合は自動抽出します
brandName	string	""	ブランド名。ブランドの組み込み戦略に使用します
language	string	"英文"	ターゲット市場の言語
platform	string	"亚马逊"	公開プラットフォーム（Amazon/TikTok/Shopee など）
salesRegion	string	"美国"	販売地域／国

---

パイプラインの手順

ステップ 1：パラメーターの解析とルーティングの決定

• 入力：brandKey、images
• 操作：
  1. brandKey 内の各フィールド値を解析します
  2. メインカラーの決定：brandColor が空でない → そのまま採用；空 → 「自動抽出」としてマークします
  3. フォントの決定：fontStyle が空でない → そのまま採用；空 → 「自動抽出」としてマークします
  4. デフォルト値の補完：language が空なら「英文」をデフォルトにします；platform が空なら「亚马逊」をデフォルトにします；salesRegion が空なら「美国」をデフォルトにします
  5. images をアクセス可能な URL のリスト（imageUrlList）に変換し、ステップ 3 で textgen に渡します
• 出力：決定ルーティング表（ユーザーが指定したフィールドと自動抽出が必要なフィールド）+ imageUrlList
• 用途：ステップ 2 の prompt の組み立てをガイドします

ステップ 2：ブランドビジュアル遺伝子抽出 prompt の組み立て

• 入力：ステップ 1 の決定ルーティング表、brandKey の全フィールド

• 操作：以下のブランドビジュアル遺伝子抽出指示と brandKey パラメーターを組み合わせて完全な prompt を作成し、ステップ 3 に渡します：

  役割：あなたは一流のブランドビジュアル専門家兼クリエイティブディレクターです。商品画像とパラメーターに基づいて統一されたビジュアル言語を構築し、さまざまなシーンでブランドの一貫性を高く保ちます。

  A. 統一ビジュアルテーマ（UNIFIED_VISUAL_THEME）

  1. Brand Color（ブランドのメインカラー）：

     • 単なるカラーパレットではなく、「世界観」を持つ中心色を定義します
     • 独自性：プロジェクト全体で定義できる中心となる HEX 色値は 1 つだけです
     • 出典：商品の色そのものを考慮し、非常に高い美的センスを備えている必要があります
     • ⚠️ 白黒グレーのプロトコル（CRITICAL）：商品そのものが白黒グレーでない限り、白黒グレーをメインカラーとして使用することは禁止です。具体的な色値（例：#EAF86C）を必ず出力してください

  2. 背景戦略（Background Strategy）：以下の 4 つのサブフィールドをすべて出力する必要があります。1 つでも欠けてはいけません。それぞれ具体的な内容を記述してください（空欄にしたり、フィールド名だけを記述したりしてはいけません）：

     • 背景戦略-スタイルの定義：salesRegion に基づいて文化的にローカライズした全体的な環境スタイルを設定します。写真のようにリアルな環境を追求し、背景レイヤーを重ねた印象を厳禁とします。ライフスタイルと感情的な共感を重視します。 例："モダンな北欧風のミニマルな住空間、無垢材と暖白色のトーン、床まで届く窓からの自然光、アメリカの中間所得層の美意識に合う"
     • 背景戦略-シーンのキーワード：具体的なシーン／小道具のキーワードを、コンマで区切って記述します。 例："無垢材の長テーブル, リネンのテーブルクロス, 観葉植物, 陶器, 朝の光"
     • 背景戦略-光と影：光の方向、色温度、雰囲気を明確に指定します（必須フィールドです。最も漏れやすいため、必ず出力してください）。 例："柔らかな自然光のサイドライト、暖色系の色温度 4000K、朝のゆったりとした雰囲気を演出し、わずかに長い影を落として立体感を高める"
     • Brand Injection（ブランドの組み込み）：ブランドのメインカラー／Logo／識別要素をシーンに自然に溶け込ませる方法を記述します（必須フィールドです。最も漏れやすいため、必ず出力してください）。 例："ブランドのメインカラーをクッションやタグのアクセントカラーとして使用し、Logo は小道具に低彩度の型押しで配置して、主張しすぎないようにする"

  B. フォントの完全固定（LOCKED_TYPOGRAPHY）

  1. フォントスタイル：以下のライブラリからスタイルを 1 つだけ選んで固定します：

     • 幾何学的なサンセリフ体：Jost, League Spartan, Montserrat, Manrope, Outfit
     • 力強いサンセリフ体：Bebas Neue, Oswald, Barlow Condensed, Anton, Fjalla One
     • クラシックで優雅なセリフ体：Bodoni Moda, Playfair Display, Prata, Cormorant Garamond, DM Serif Display
     • 丸みのある遊び心のあるフォント：Nunito, Quicksand, Varela Round, Fredoka, Baloo 2
     • ポップな手書き風：Pacifico, Permanent Marker, Amatic SC, Caveat, Luckiest Guy

  2. 色の戦略：

     • 見出し色（Heading Color）：ブランドのメインカラーまたは反転色を必ず使用します。見出しの背景色がブランドのメインカラーまたは同系色の場合は、「柔軟な反転色」を自動的に適用します。次に、ブランドのメインカラーと同系色の色を検討します（黒に近い色は禁止。色が濃くなりすぎないようにしてください）
     • 本文色（Body Color）：見出し色と区別し、読みやすさを確保します
     • ⚠️ 出力形式に関する注意：色の戦略は ["Heading Color"：色値] と ["Body color"：色値] の形式で出力します。これは色の定義であり、テキスト内容ではありません

  3. 柔軟な反転色の使用許可：暗い背景またはブランドカラーの単色ブロックを使用する場合は、テキストをマットホワイト（#FFFFFF）に切り替えることを許可します

  4. 組版の制限：すべて斜体ではない書体（Non-italic）に統一し、行間は標準（standard leading）にします

  出力要件：下記の「出力形式」に厳密に従って完全な JSON を出力してください。説明文やコードブロックのマーカーは一切出力しないでください。

• 出力：完全な textgen prompt 文字列

• 用途：ステップ 3 の prompt 入力として使用します

步骤 3：调用 linkfox-aigc-textgen 执行视觉推理

• 输入：步骤 2 的 prompt、步骤 1 的 imageUrlList
• 操作：按 linkfox-aigc-textgen SKILL.md 的调用方式调用 textgen 执行视觉推理。本步骤产出的内容要回读进上下文做字段提取（步骤 4），不链式拼进下游出图，因此用 textgen 的默认模式（不是 --content-only）：把下列字段写成 JSON 参数文件，经 --stdin 传入运行，再解析 stdout。<textgen根目录> 通过 skill:linkfox-aigc-textgen 解析其 SKILL.md 所在目录的绝对路径取得；<本skill根目录> = 本 SKILL.md 所在目录的绝对路径。

  ⚠️ 中间参数文件落到会话 data/ 目录。先取目录：

  DATADIR=$(python <本skill根目录>/scripts/save_brand_gene.py --datadir)
  

  ⚠️ 构造 brand_gene_params.json 必须用 Write 工具写到 $DATADIR/brand_gene_params.json（prompt 含引号、反斜杠等特殊字符，shell heredoc 内嵌 JSON 易解析失败）。若走命令行生成，只用 python -c 配合 json.dumps，不要手拼 JSON 字符串。

  python <textgen根目录>/scripts/aigc_textgen.py --stdin < "$DATADIR/brand_gene_params.json"
  

  JSON 参数文件包含以下字段：
  • prompt：步骤 2 组装的品牌视觉基因提取指令（含「输出格式」要求）
  • imageUrls：步骤 1 输出的 imageUrlList
  • model：GEM_3_1_PRO（需要视觉理解与复杂推理能力）
  • thinkingLevel：high
• 输出：解析 textgen stdout 得到 content（解析方式按 linkfox-aigc-textgen SKILL.md 的「输出契约」）。
• 用途：作为步骤 4 的组装原料

步骤 4：组装 brandGeneJson

• 输入：步骤 3 解析出的 content（换行可能为 ⏎ 占位符，提取前先还原为换行符）
• 操作：从该 content 中提取品牌视觉基因各字段，严格按照下方「输出格式」自行组装为 brandGeneJson
• 缺失字段兜底（强制）：组装后必须逐一核对「输出格式」中的全部字段是否齐全。若模型输出遗漏了某字段（实测最易漏 背景策略-光影 与 Brand Injection（品牌植入）），不得直接交付残缺 JSON，须按以下顺序兜底补齐：
  1. 优先从 content 其余文字中归纳推断该字段的合理值；
  2. 无可推断内容时，结合已确定的主色 / 风格定义生成一句与整体调性一致的兜底描述（如光影按"自然柔和侧光、暖色温、增强立体感"，品牌植入按"主色作点缀、Logo 低调融入道具"）。 最终 brandGeneJson 必须字段齐全，禁止出现缺字段或字段值为空串。
• 输出：brandGeneJson（长度为 1 的 JSON 列表，字段齐全）
• 落盘（强制）：组装完成后必须写入会话目录并保留路径供下游复用：
  1. 用 Write 工具将 brandGeneJson 写到 $DATADIR/brand_gene_assembled.json（DATADIR 同步骤 3）；或
  2. 运行落盘脚本（推荐，自动注册 _meta.json）：

     python <本skill根目录>/scripts/save_brand_gene.py "$DATADIR/brand_gene_assembled.json"
     

     stdout 会打印 Saved full response: <绝对路径> (<N> bytes)——将该绝对路径记入上下文，后续 S3 套图编排通过 --brand-gene-file <绝对路径> 或 manifest 的 brand_gene_json 消费。
• 用途：透传给下游出图链路（linkfox-aigc-imagegen-cloth 的种草图/卖点图/A+图 等类型 / linkfox-aigc-imagegen-product 等）作为 brandGeneJson 参数

---

产物落盘

产物	目录	说明
brand_gene_params.json	<session>/data/	textgen 入参（步骤 3 中间文件）
brandGeneJson 最终结果	<session>/data/linkfox-aigc-imagegen-brand-gene-extract-<ts>.json	经 save_brand_gene.py 落盘，供套图 S3 与单张 --brand-gene-file 复用

路径协议：<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/（<session> 取自 SESSION_ID），与仓库 CLAUDE.md「输出文件位置」一致。

---

核心规则

A. 主色和字体逻辑

• 如果 brandColor 有值 → 输出 JSON 中 "brandColor (品牌主色)" 直接用该值
• 如果 fontStyle 有值 → 输出 JSON 中 "字体风格" 直接用该值
• 如果哪个值为空 → 该值用核心变量里的规则来自动提取

B. 其他值逻辑

"背景策略-风格定义"、"颜色策略-Heading" 等字段，默认都用核心变量的规则来获取，不受 brandKey 中 brandColor/fontStyle 的透传影响。

---

输出格式

严格按照以下 JSON 格式输出，输出为长度为 1 的列表：

[
  {
    "brandColor": {
      "brandColor (品牌主色)": "颜色名称与HEX值",
      "背景策略-风格定义": "基于 salesRegion 的风格描述",
      "背景策略-场景关键词": "关键词1, 关键词2, ...",
      "背景策略-光影": "光影氛围描述",
      "Brand Injection（品牌植入）": "品牌元素如何植入场景"
    },
    "fontStyle": {
      "字体策略": "选定的字体家族名称",
      "字体风格": "选定的具体字体名称",
      "颜色策略-Heading": "[\"Heading Color\"：颜色值/反白逻辑]",
      "颜色策略-Body/Sub": "[\"Body color\"：颜色值]",
      "灵活反白": "You are authorized to switch to Matte White (#FFFFFF) text whenever using a dark background or a solid brand-color panel.",
      "排版": "Non-italic, standard leading"
    }
  }
]

---

错误处理

情况	处理
images 为空	停止执行，提示用户上传至少 1 张商品图片
brandKey 完全为空	所有字段按默认值填充（salesRegion=美国、language=英文、platform=亚马逊），主色与字体走自动提取
商品为纯黑白灰且无法提取彩色主色	允许使用黑白灰作为主色（黑白灰协议的唯一豁免条件）

---

调用方式

本 skill 由套图编排层在步骤三中调用，调用时机：

1. 首次调用：上下文中没有进行过品牌基因样式提取时
2. 重新调用：用户明确要求修改品牌基因（场景 G）时

复用规则：同一上下文中提取结果可复用，无需重复调用。

---

解决认证和算力问题

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

异常情况

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

已知局限

• 品牌主色提取基于 GEM_3_1_PRO 对商品图片的视觉理解，可能与专业设计师判断有偏差
• 字体风格限定在预设的 5 类 25 款字体中，无法选择库外字体
• 背景策略的文化本土化依赖 salesRegion 的语义理解，非结构化地域数据库
• 品牌基因 JSON 必须经 save_brand_gene.py 落盘到会话 data/，不可仅存于对话上下文
• 依赖 linkfox-aigc-textgen skill 可用；若 textgen 调用失败，品牌基因提取无法完成