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 必須常綠。
需要改規範請先說明理由並取得確認,不要在實現裡悄悄「修正」基線。
一、五條不可違反的規則
- 不靜默降級。能力不足、預算不足、校驗不通過,一律顯式返回
references/error-registry.json裡的錯誤碼;不允許「悄悄換個更小的尺寸/更低的檔位/更少的張數」 繼續跑,也不允許把失敗說成通過。 - 閾值只從配置讀。
config/iv.config.json是唯一來源(單格邊長 warn/hard、接縫 pass/risk、 放大倍數、重試與預算)。它們尚未經真實模型校準,改之前先給數據。程式碼裡不得出現魔法數字。 - 單一事實來源。方向、Prompt、錯誤碼、契約都從基線執行時讀取,不複製進本 Skill。
- 金鑰只走引用。只接受
secret://…或env:…;金鑰、原圖、使用者文字不得進入日誌、 manifest、錯誤訊息或 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 條幀計劃(幀數、每幀變化點、保持項、Prompt)
→ 逐幀生成(圖 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=幀(索引不前移)
同目錄下 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。