Community影像github.com

主體一致的圖像變體

把一句需求或一張參考圖變成一組主體不變的圖片。網格模式一次畫成 2×2、3×3 或 4×4 的整板再切開;序列模式生成 4 到 16 張,用來表現光線、角度、場景或敘事的變化。兩種模式都交出帶清單、可以核驗的壓縮包。

主體一致的圖像變體 是什麼?

可重複使用的成組靜幀技能。它在接觸印樣式的整板和短序列之間選擇,穩住主體,並交付帶 manifest 的壓縮包,而不是一堆無法核驗的散圖。

相容平台~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/Chans-gh/AI-Image-Variation/tree/HEAD/skills/image-variations

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Image Variations(Skill 01)

唯一入口。 編排寫在這裡;12 個方向的全文、Prompt 模板、Provider 相容矩陣、錯誤碼、 閾值不在這裡,一律在凍結基線內按需讀取,避免出現兩份互相飄移的真相。

  • 業務規則:Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md
  • 方向註冊表:.../references/directions/registry.json
  • Prompt 模板:.../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 必須常綠。 需要改規範請先說明理由並取得確認,不要在實現裡悄悄「修正」基線。

一、五條不可違反的規則

  1. 不靜默降級。能力不足、預算不足、校驗不通過,一律顯式返回 references/error-registry.json 裡的錯誤碼;不允許「悄悄換個更小的尺寸/更低的檔位/更少的張數」 繼續跑,也不允許把失敗說成通過。
  2. 閾值只從配置讀。config/iv.config.json 是唯一來源(單格邊長 warn/hard、接縫 pass/risk、 放大倍數、重試與預算)。它們尚未經真實模型校準,改之前先給數據。程式碼裡不得出現魔法數字。
  3. 單一事實來源。方向、Prompt、錯誤碼、契約都從基線執行時讀取,不複製進本 Skill。
  4. 金鑰只走引用。只接受 secret://… 或 env:…;金鑰、原圖、使用者文字不得進入日誌、 manifest、錯誤訊息或 ZIP。
  5. 產物必須可驗證。每次交付都帶 manifest.json(image-artifact 1.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 條幀計劃(幀數、每幀變化點、保持項、Prompt)
                  → 逐幀生成(圖 1 打底,圖 2–N 一律引用圖 1;有原圖則每幀都帶原圖)
                  → 單幀失敗保留槽繼續;圖 1 失敗立即 SEQUENCE_ANCHOR_FAILED
                  → 近似重複檢測(重試耗盡後保留槽位並標註)
 → 落盤(manifest + delivery-package + 可選 ZIP)→ 返回 JSON 結果

關鍵判定:

情況處理
grid_size 非 2/3/4、序列不在 4–16INVALID_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=幀(索引不前移)

同目錄下 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 不越界。
  • 使用者顯式要求多個方向時只挑一個並說明理由,或報 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。

相關技能