sn-image-imitate

sn-image-imitate

画像スタイル模倣シーンスキル（ティア 1）。ティア 0 の sn-image-base が提供する sn-image-recognize、sn-text-optimize、sn-image-generate ツールに依存します。

特徴：

• 参照画像から忠実度の高い長文キャプションを抽出します
• スタイルとレイアウトを維持しながら、ユーザーが指定した内容の変更に応じてキャプションを書き換えます
• キャプションの書き換え中にレイアウトロック制約を適用します
• 生成後にレイアウトの一貫性を確認し、回数を制限して再試行します
• デバッグと再現性のための構造化された処理成果物を返します

対象外

• 内容を変更しない純粋なニューラルスタイル転送（専用のスタイル転送ツールを使用してください）
• 参照画像の特定領域のローカル編集／インペインティング
• 動画やアニメーションの入力処理（単一の静止画像のみサポートします）
• 1 回の呼び出しで複数の参照画像から一括生成すること
• 参照画像とのピクセル単位の忠実度の保証。このスキルが目指すのはレイアウトとスタイルの一貫性であり、完全な再現ではありません

入力仕様

• reference_image（string、必須）：スタイル参照画像のローカルパスまたは URL
• target_content（string、必須）：生成画像に追加したい新しい内容
• output_mode（string、デフォルトは friendly）：出力モード。friendly または verbose
• aspect_ratio（string、デフォルトは 16:9）：生成する画像のアスペクト比
• image_size（string、デフォルトは 2k）：出力画像サイズのプリセット
• max_attempts（int、デフォルトは 3）：レイアウトの一貫性を満たすための最大生成試行回数
• layout_threshold（float、デフォルトは 0.75）：結果を採用するためのレイアウト類似度の最小スコア

環境変数

依存関係のインストールと API キーの設定については、sn-image-base スキルを参照してください。

SenseNova Token Plan を利用して sn-image-base スキルを実行する場合に設定する最低限の環境変数：

SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="your-api-key"

フォールバックの優先順位は、専用変数 > ドメイン共有変数 > グローバル変数です。テキスト呼び出しでは SN_TEXT_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY、画像認識呼び出しでは SN_VISION_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY、画像生成では SN_IMAGE_GEN_API_KEY -> SN_API_KEY の順に使用します。

追加の設定については、sn-image-generate_en.md の Python dependencies and API keys セクションを参照してください。

API 設定

このスキルのすべての API 呼び出しは、sn-image-base スキルの sn_agent_runner.py を通じて実行されます。 詳細については、sn-image-base スキルの README.md を参照してください。

• VLM 呼び出し：sn-image-recognize（ステップ 1 と 3）
• LLM 呼び出し：sn-text-optimize（ステップ 2）
• 画像生成呼び出し：sn-image-generate（ステップ 3）

MissingApiKeyError が発生した場合、またはモデルを明示的に指定する場合：CLI 引数でモデルと認証パラメーターを明示的に渡してください。$SN_IMAGE_BASE/references/api_spec.md を参照してください。

$SN_IMAGE_BASE パスの説明：$SN_IMAGE_BASE は sn-image-base スキルのインストールディレクトリです（SKILL.md が存在します）。エージェントはスキル名 sn-image-base を使ってこのパスを特定できます。

アーキテクチャ：メインエージェント + ワーカーエージェント

このスキルでは、2 層のエージェントアーキテクチャを使用します。

• メインエージェント：ユーザーのリクエストを受け取り、パラメーターを正規化して事前チェックを送り、ワーカーエージェントを呼び出し、最終的なテキスト／画像をユーザーに送信します
• ワーカーエージェント：固定の 3 ステップのパイプラインを実行し、構造化された JSON を返します

責任の分担：

• ワーカーエージェントは、ユーザーに直接表示されるメッセージを送信しません
• ユーザー向けの応答はすべてメインエージェントが送信します
• ワーカーエージェントの最後のメッセージは、Return Contract で定義された JSON 文字列のみでなければなりません
• ワーカーエージェントは VLM／LLM／画像生成の呼び出しを直接実行します。これらの低レベルの呼び出しに、ネストされたサブエージェントは使用しません

ワークフロー

メインエージェントのワークフロー

1. reference_image、target_content、output_mode（デフォルトは friendly）、aspect_ratio（デフォルトは 16:9）、image_size（デフォルトは 2k）、max_attempts（デフォルトは 3）、layout_threshold（デフォルトは 0.75）を抽出します
2. 必須入力を検証します：
   • reference_image が指定され、解決可能であること
   • target_content が空でないこと
3. 事前確認メッセージを送信します："sn-image-imitate skillを使用してスタイルに一貫性のある画像を生成しています。しばらくお待ちください..."
4. 正規化したすべてのパラメーターと作業ディレクトリを指定して、ワーカーエージェントを開始します
5. ワーカーの結果に応じて処理します：
   • status=ok：最終的な概要と生成された画像を送信します
   • status=error：実際のエラーを報告します

ワーカーエージェントのワークフロー

ワーカーエージェントは、reference_image、target_content、output_mode、aspect_ratio、image_size、max_attempts、layout_threshold、およびこのスキルの作業ディレクトリ（$SKILL_DIR）を受け取ります。

エラー処理方針：

すべての sn_agent_runner.py 呼び出しで、同じエラー処理ルールを適用します：

• サブプロセスがゼロ以外のコードで終了した場合、クラッシュした場合、またはタイムアウトした場合：フォールバックせず、標準エラー出力の実際のエラーメッセージまたはシステムエラー文字列を含めて status=error を返します
• サブプロセスが無効な JSON を返した場合、または JSON に想定される result フィールドがない場合：空の値やデフォルト値で黙って続行せず、status=error を返します
• ステップ 3 で VLM レビューの呼び出しに失敗した場合、その試行は未完了として扱います：スコアを記録せず、残りの試行回数に応じてレビューを一度再試行するか、次の試行に進みます

ステップ 0 — 初期化

1. YYYYMMDD_HHMMSS 形式で task_id を生成します
2. 一時ディレクトリ /tmp/openclaw/sn-image-imitate/<task_id>/ を TEMP_DIR として作成します
3. REFERENCE_IMAGE を解決して正規化します
4. ユーザーリクエストを保存します：

echo "$TARGET_CONTENT" > "$TEMP_DIR/target-content.txt"

ステップ 1 — 画像の注釈（長いキャプション＋レイアウトの設計図）

prompts/image_annotate.md をシステムプロンプトとして使用し、参照画像に対して sn-image-recognize を呼び出します。

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-recognize \
  --system-prompt-path "$SKILL_DIR/prompts/image_annotate.md" \
  --user-prompt "Please annotate this reference image and follow the required output format." \
  --images "$REFERENCE_IMAGE" \
  --output-format json

JSON の result を解析し、次の 3 つのブロックを解析します：

• SHORT_CAPTION: ...
• LONG_CAPTION: ...
• LAYOUT_BLUEPRINT_JSON: { ... }

解析に失敗した場合、LONG_CAPTION が空の場合、または LAYOUT_BLUEPRINT_JSON が無効な JSON の場合は、status=error を返します。

出力を保存します：

echo "$SHORT_CAPTION" > "$TEMP_DIR/reference-short-caption.txt"
echo "$LONG_CAPTION" > "$TEMP_DIR/reference-long-caption.txt"
echo "$LAYOUT_BLUEPRINT_JSON" > "$TEMP_DIR/layout-blueprint.json"

ステップ 2 — 新しい長いキャプションの生成（レイアウトを維持したコンテンツの書き換え）

目標：参照画像の長いキャプションからスタイル、レイアウト、視覚表現を維持しながら、主要なコンテンツを target_content に置き換えます。

維持する厳格な要件（layout-blueprint.json を参考にします）：

• 視覚的な階層（タイトル／サブタイトル／本文の強調順）
• 領域のトポロジー（主要ブロックの数と相対的な位置）
• 読み進める方向（左から右／上から下／放射状／タイムラインの方向）
• グラフの種類とデータの表現形式（存在する場合）
• 余白のリズムと配置パターン
• ブループリントに示された主要領域の境界ボックスとトポロジー上の関係

推奨するシステムプロンプト：prompts/caption_rewrite.md（追加を推奨）。 存在しない場合は、次のインラインの代替システムプロンプトを使用します：

スタイルとレイアウトの制約を維持しながら、ユーザーの指定に従って意味的なコンテンツを書き換えて、長いキャプションを作成してください。ブロックのトポロジー、読み進める順序、視覚的な階層は変更しないでください。キャプションは詳細に記述し、画像生成にそのまま使用できるものにしてください。

sn-text-optimize を呼び出します：

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-text-optimize \
  --system-prompt-path "$SKILL_DIR/prompts/caption_rewrite.md" \
  --user-prompt "Reference long caption:\n$LONG_CAPTION\n\nLayout blueprint JSON:\n$LAYOUT_BLUEPRINT_JSON\n\nTarget content:\n$TARGET_CONTENT\n\nReturn only the rewritten long caption." \
  --output-format json

JSON の result を NEW_LONG_CAPTION として解析します。空の場合は、status=error を返します。

出力を保存します：

echo "$NEW_LONG_CAPTION" > "$TEMP_DIR/new-long-caption.txt"

ステップ 3 — 画像生成とレイアウトのレビューループ

attempt を 1 から max_attempts まで順番に実行します。

画像生成（sn-image-base の sn-image-generate ツールを使用）：

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-generate \
  --prompt "$CURRENT_PROMPT" \
  --aspect-ratio "$ASPECT_RATIO" \
  --image-size "$IMAGE_SIZE" \
  --save-path "$TEMP_DIR/attempt_<N>.png" \
  --output-format json

VLM の設定要件：

• max_attempts > 1 の場合、各試行で VLM によるレビューが必要です
• 画像認識のパラメーターとして、OpenClaw の設定から VLM モデルを選択します
• OpenClaw の設定に適切な VLM モデルがない場合：
  • 現在のパラメーターの組み合わせでは実行できないことをユーザーに通知します
  • VLM の設定を追加するか、レビューをスキップするため max_attempts を 1 に設定するよう提案します
• VLM 呼び出しがタイムアウトまたは失敗した場合：フォールバックせず、実際のエラーをそのまま報告します

レイアウトの一貫性レビュー（max_attempts > 1 の場合のみ実行）：

ブループリントを構造上の基準として、prompts/layout_review.md を使用して候補画像と参照画像を比較します。

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-recognize \
  --system-prompt-path "$SKILL_DIR/prompts/layout_review.md" \
  --user-prompt "Reference is image[0], candidate is image[1]. Layout blueprint JSON:\n$LAYOUT_BLUEPRINT_JSON\n\nEvaluate layout similarity and return JSON only." \
  --images "$REFERENCE_IMAGE" "$TEMP_DIR/attempt_<N>.png" \
  --output-format json

想定されるレビュー JSON（result 内）：

{
  "layout_similarity_score": 0.0,
  "style_similarity_score": 0.0,
  "pass": false,
  "major_deviations": [],
  "fix_hints": []
}

試行結果の保存：

{
  "attempt": 1,
  "image": "$TEMP_DIR/attempt_1.png",
  "layout_similarity_score": 0.0,
  "style_similarity_score": 0.0,
  "pass": false,
  "major_deviations": [],
  "timing": {
    "image_generation": { "elapsed_seconds": 12.34, "model": "sn_image_model" },
    "vlm_review": { "elapsed_seconds": 5.67, "model": "sensenova-122b" }
  }
}

注：elapsed_seconds は各 CLI 呼び出しの --output-format json の戻り値から読み取ります。image_generation.model はハードコードされたプレースホルダー "sn_image_model" に固定されています（sn-image-generate はモデルフィールドを返しません）。vlm_review.model は sn-image-recognize の JSON 戻り値から読み取ります。max_attempts=1 の場合、timing.vlm_review は省略されます。

早期終了の確認（max_attempts > 1 の場合のみ実行）：

合格基準：

• layout_similarity_score >= layout_threshold

• pass = true

• 合格した場合：ループを直ちに終了し、生成を続けません

• 不合格で、残りの試行がある場合は、修正のヒントをプロンプトに追加します：

Layout correction requirements:
- <fix_hint_1>
- <fix_hint_2>
...

• すべての試行でしきい値に達しなかった場合、最もスコアの高い候補を返し、layout_passed=false に設定します

戻り値の仕様

Worker Agent の最終応答は、余分なテキストやコードフェンスを含まない JSON のみである必要があります。

通常フロー

{
  "status": "ok",
  "need_main_agent_send": true,
  "output_mode": "friendly|verbose",
  "result": {
    "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_2.png",
    "reference_image": "<resolved_reference_image>",
    "reference_short_caption": "<short caption from step 1>",
    "reference_long_caption": "<long caption from step 1>",
    "layout_blueprint": { "...": "..." },
    "new_long_caption": "<rewritten long caption from step 2>",
    "layout_passed": true,
    "selected_attempt": 2
  },
  "attempts": [
    {
      "attempt": 1,
      "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_1.png",
      "layout_similarity_score": 0.62,
      "style_similarity_score": 0.79,
      "pass": false,
      "major_deviations": ["center panel too narrow", "title block moved to top-right"]
    },
    {
      "attempt": 2,
      "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_2.png",
      "layout_similarity_score": 0.81,
      "style_similarity_score": 0.84,
      "pass": true,
      "major_deviations": []
    }
  ],
  "review": {
    "threshold": 0.75
  },
  "timing": {
    "total_elapsed_seconds": 24.56,
    "annotate": { "elapsed_seconds": 3.21, "model": "sensenova-122b" },
    "rewrite": { "elapsed_seconds": 2.45, "model": "sensenova-122b" },
    "generation_total": { "elapsed_seconds": 11.90, "model": "sn_image_model" },
    "review_total": { "elapsed_seconds": 7.00, "model": "sensenova-122b" }
  }
}

エラーフロー

{
  "status": "error",
  "error": "<actual_error_message>"
}

ルール：

• status=ok には need_main_agent_send: true を含める必要があります
• result.image は、生成済み画像の既存パスである必要があります
• timing.total_elapsed_seconds は Worker の実行全体を対象とします
• ステップ 1 の形式の解析に失敗した場合（無効なブループリント JSON を含む）、status=error を返します（黙って処理を続行しないでください）
• attempts には、生成とレビューを行った各試行を記録する必要があります
• しきい値に合格する試行がなかった場合、最もスコアの高い候補を返し、result.layout_passed=false に設定します

出力形式

friendly モード（デフォルト）

• 参照スタイルに沿い、リクエストされた内容に更新した画像を生成したことを示す簡潔な一文
• レイアウトの一貫性がしきい値を満たしたかどうかと試行回数に言及します
• 画像を 1 枚送信します：result.image

verbose モード

Style imitation result
---
Reference short caption: <reference_short_caption>
---
Style/layout cues:
<brief extraction from reference_long_caption + layout_blueprint>
---
New long caption:
<new_long_caption>
---
#1 attempt=<n> layout_score=<0.00> style_score=<0.00> pass=<true|false> [selected]
  deviations: <major_deviations or none>
#2 attempt=<n> layout_score=<0.00> style_score=<0.00> pass=<true|false>
  deviations: <major_deviations or none>
...
---
Layout threshold: <0.75> | Passed: <true|false> | Selected: attempt <n>
Time statistics: Total <total>s | Annotation <t>s | Rewrite <t>s | Generation <t>s×<n> attempts | Review <t>s×<n> attempts
---
Images (selected image)

呼び出し関係

• 最下層の依存関係：sn-image-base → sn-image-recognize、sn-text-optimize、sn-image-generate

参考資料

• prompts/image_annotate.md - 画像アノテーションとレイアウトブループリントのシステムプロンプト（ステップ 1、必須）
• prompts/caption_rewrite.md - レイアウト固定の制約を含むキャプション書き換えのシステムプロンプト（ステップ 2、必須）
• prompts/layout_review.md - 候補画像と参照画像のレイアウト／スタイルレビュー用プロンプト（ステップ 3、必須）
• ../sn-image-base/SKILL.md - ベースツールの動作とパラメーターのデフォルト値