Image Variations(Skill 01)
唯一のエントリポイント。 オーケストレーションはここに記述。12 方向の全文、プロンプトテンプレート、Provider 互換マトリックス、エラーコード、 閾値はここにはありません。すべて凍結ベースライン内で必要に応じて読み取ります。2 つの漂流する真実を避けるためです。
- ビジネスルール:
Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md - 方向レジストリ:
.../references/directions/registry.json - プロンプトテンプレート:
.../references/grid-prompt.md、.../references/sequence-prompt.md - Provider 互換性とセキュリティ:
.../references/provider-compat.md - エラーコード:
.../references/error-registry.json - パッケージングルール:
.../references/packaging.md - 契約:
.../contracts/{image-artifact,job-state,delivery-package}.schema.json
ベースラインは読み取り専用:ハッシュマニフェストは shared/baseline.manifest.json にあり、shared/check_baseline.py は常にグリーンである必要があります。
仕様変更が必要な場合は、まず理由を説明し確認を得てください。実装内で密かにベースラインを「修正」しないでください。
一、5 つの不可侵ルール
- 暗黙のダウングレード禁止。能力不足、予算不足、検証不合格の場合は、常に明示的に
references/error-registry.jsonのエラーコードを返します。「より小さいサイズ/低いグレード/少ない枚数に静かに切り替える」ことは許可されず、失敗を成功と偽ることも許可されません。 - 閾値は設定からのみ読み取る。
config/iv.config.jsonが唯一の情報源です(単一タイルエッジ長の warn/hard、シームの pass/risk、 拡大倍率、リトライと予算)。これらはまだ実際のモデルでキャリブレーションされていません。変更する前にデータを提供してください。コード内にマジックナンバーを記述しないでください。 - 単一の真実の情報源。方向、プロンプト、エラーコード、契約はすべてベースラインから実行時に読み取られます。本 Skill にコピーしないでください。
- 秘密鍵は参照のみ。
secret://…またはenv:…のみを受け入れます。秘密鍵、元画像、ユーザーテキストはログ、 マニフェスト、エラーメッセージ、ZIP に含めてはなりません。 - 成果物は検証可能でなければならない。各納品には
manifest.json(image-artifact1.1)とdelivery-package.jsonが含まれます。マニフェスト内の各エントリは実際に存在し、ハッシュが一致している必要があります。
二、使用方法
# 1) 事前チェック:計画のみ計算、モデル呼び出しやディスク書き込みは行わない
python scripts/run_task.py --input task.json --preflight-only
# 2) 正式実行(秘密鍵がない場合は mock_synthetic で全パスをテスト)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty
# 3) 一部のフレームのみが失敗した場合、元のインデックスで追加生成(rev2 を生成、parent は rev1 を指す)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1
タスク記述(JSON、フィールドは references/provider-compat.md のプロダクトパラメーターと一致):
{
"task_id": "cup_light_001",
"output_mode": "grid", // grid | sequence
"grid_size": 3, // grid 必須:2 | 3 | 4
"direction": "light", // 12 方向のいずれか、registry.json 参照
"input_type": "text_only", // text_only | image_only | image_plus_text
"subject": "淡いグレーの陶器カップ", // 被写体の説明、主体アンカーに入る
"reference_path": "img/ref.png", // 画像入力がある場合必須、workspace からの相対パス
"aspect_ratio": "3:4",
"resolution_tier": "1K", // 1K | 2K | 4K;デフォルトは単一タイルの最小エッジ長から逆算
"provider": {"type": "mock_synthetic"},
"pack_zip": true
}
sequence の場合、さらに branch(方向がサポートする 3 つのブランチのいずれか)と image_count(4–16)が必要です。
実際の Provider:
"provider": {
"type": "openai_image_compatible", // または gemini_image_compatible
"base_url": "https://api.example.com/v1",
"model_id": "gpt-image-1",
"api_key_secret_ref": "secret://IMAGE_API_KEY",
"capability": { "...": "provider-compat.md §1 能力宣言を参照" }
}
capability がデフォルトの場合は、基準を満たしていないと見なされ MODEL_CAPABILITY_UNSUPPORTED が報告されます。これは「最低限のリスト」であり、
デフォルト値で密かに補完されることはありません。組み込みアダプターが注入されていない場合は BUILTIN_UNAVAILABLE が報告され、自動的に外部ネットワークに切り替わることはありません。
三、フロー(分岐ルール)
入力解析 → 事前チェック(能力/アスペクト比/グレード/枚数/予算)
├─ 不合格 → エラーコードを報告、終了(モデル呼び出しなし、ディスク書き込みなし)
└─ 合格 ─┬─ Grid:一度にボード生成 → 検証(N×N / シームレス / 分割可能 / アスペクト比)→ 限定ボード全体リトライ
│ → 正規化 → 行優先でタイル分割 → 各タイルエッジ長判定(ok / risk / too_low)
└─ Sequence:まず N フレームの計画を生成(フレーム数、各フレームの変化点、保持項目、プロンプト)
→ フレームごとに生成(フレーム 1 はベース、フレーム 2–N は常にフレーム 1 を参照;元画像がある場合は各フレームに元画像を含める)
→ 単一フレーム失敗はスロットを保持して続行;フレーム 1 失敗は即座に SEQUENCE_ANCHOR_FAILED
→ 類似重複検出(リトライを使い果たした後もスロットを保持し注釈を付ける)
→ ディスク書き込み(manifest + delivery-package + オプション ZIP)→ JSON 結果を返す
主要な判定:
| 状況 | 処理 |
|---|---|
grid_size が 2/3/4 以外、シーケンスが 4–16 以外 | INVALID_MODE_OR_COUNT |
| 単一タイルエッジ長が hard 閾値を下回る | TILE_RESOLUTION_TOO_LOW、納品パッケージなし |
| 単一タイルエッジ長が warn 閾値を下回る | 納品するが TILE_RESOLUTION_RISK 警告を記録(tile_edge_ok=false) |
| シーム < risk 閾値 | GRID_VALIDATION_FAILED、ボード全体をリトライ;タイル分割画像は外部に送信しない |
| シームが risk–pass の間 | 納品し GRID_SEAM_RISK を記録 |
| ボードの N×N 構造/アスペクト比が基準未満 | GRID_VALIDATION_FAILED |
| フレーム 1 失敗 | SEQUENCE_ANCHOR_FAILED、予算を消費し続けない |
| i 番目のフレーム失敗 | 元のインデックススロットを保持し、後続のフレームを続行、最終的に partial_failed |
| 予算超過見込み | BUDGET_EXCEEDED(分割提案を添付可、ただし自動的には分割しない) |
四、成果物
workspace/iv_<task_id>_<revision>/
├── manifest.json # image-artifact 1.1(スタイル/サイズ/シーム/実行/警告/エラー)
├── delivery-package.json # 本パッケージのマニフェスト(ファイルごとの sha256)
├── board.png # Grid のみ:kind=board, index=0
└── images/NN.png # Grid=タイル分割画像 tile(行優先);Sequence=フレーム frame(インデックスは前方に移動しない)
同じディレクトリ内に iv_<task_id>_<revision>.zip がオプションのパッケージ成果物として含まれます。ZIP 内には delivery-package.json
自身は含まれません。archive ハッシュは delivery-package.json に書き戻されます。
部分失敗時:実際に存在する画像のみ登録(失敗フレームは images[] に含まれない)、失敗情報は
errors[].asset_id + validation.failed_indices に記録、status=partial_failed。
再実行により新しいリビジョンが生成され(parent_artifact_revision は前のバージョンを指す)、成功したフレームはバイト単位で変更されません。
五、境界
- 画像バリエーションの生成のみ。コピーライティング、プラットフォーム公開、カバーレイアウトは Skill 02(
image-content-publishing) に属し、本 Skill はその範囲を超えません。 - ユーザーが明示的に複数の方向を要求した場合、1 つだけを選択して理由を説明するか、
MULTIPLE_DIRECTIONSを報告します。混在は行いません。 - 「他人の作品へのスタイル転送」などのグレーゾーンリクエストは行いません。実在の人物/ブランドが関与する場合は
provider-compat.md §4のセキュリティ要件に従って処理します。 - 自己テスト用の
mock_synthetic成果物には、常にprovider_type=mock_syntheticのラベルが付けられます。外部に納品してはいけません。
六、開発と検証
.venv/bin/python skills/image-variations/tests/run_all.py # 9 スイート(ベースライン 24/24 と契約 48/48 を含む)
.venv/bin/python shared/check_baseline.py # ベースライン読み取り専用検証
エビデンスと既知の逸脱は docs/PHASE_EVIDENCE.md に記録されています。