Community이미지github.com

주체를 맞춘 이미지 변형

한 문장의 요청이나 참고 이미지를 주체가 같은 한 묶음으로 바꿉니다. 그리드는 2×2, 3×3, 4×4 한 장을 그린 뒤 잘라 냅니다. 시퀀스는 4장에서 16장으로 빛, 각도, 장소, 이야기의 변화를 만듭니다. 둘 다 매니페스트가 있는 검증 가능한 패키지를 넘깁니다.

주체를 맞춘 이미지 변형란 무엇인가요?

맞춰진 정지 이미지 세트를 위한 재사용 스킬입니다. 콘택트 시트나 짧은 연속 중 하나를 고르고 주체를 안정시키며, 검토할 수 없는 파일 더미 대신 매니페스트가 있는 zip을 줍니다.

지원 대상~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에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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–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에 기록됨.

관련 스킬