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=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은 범위를 벗어나지 않음. - 사용자가 명시적으로 여러 방향을 요청하면 하나만 선택하고 이유를 설명하거나
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에 기록됨.