Img Gen

---
name: img-gen
description: CLI에서 이미지 생성 — cdx(Codex/gpt-image-2) 또는 agy(Antigravity/generate_image) 백엔드로 텍스트→이미지. 기본 경로는 자기검수 루프(생성기가 자기 결과물을 보고 체크리스트 채점→편집/재생성, 최대 3라운드) + 로컬 비전모델 이종 대조 + Claude 크롭 대조. "이미지 만들어/생성해줘", "그림 뽑아줘", "cdx로 이미지", "agy로 이미지", "이 이미지 검수해줘", "/img-gen" 요청 시 호출. 사내기밀·민감 소재는 이 스킬 금지 → 로컬 sci-figure(FLUX/mflux, 오프라인)로.
---

# img-gen — CLI 이미지 생성 (cdx / agy) + 자기검수 루프

`scripts/img_gen.py`로 외부 CLI 에이전트의 이미지 생성 툴을 호출하고, 산출물 실존·라운드 파일·자기검수 보고를 스크립트가 대조한다(G12 — 자기보고 불신·파일 판정). 2026-09-16 사용자 지시("챗지피티가 생성 과정부터 어색함을 스스로 바로잡게")로 QA 루프가 기본 경로가 됐다. 프로토콜 정본: `IMAGE_QA_PROTOCOL.md`(같은 내용이 `~/.codex/AGENTS.md` 끝 절에 상주 → 챗지피티 앱 대화에서도 적용).

## 실행 (기본 = QA 루프)

```bash
# 1) 요청에서 검증 가능한 체크리스트를 먼저 뽑는다(사진 보고 참/거짓 판정 가능한 문장, 3~5개)
python3 ~/.claude/skills/img-gen/scripts/img_gen.py --via cdx --name out.png --job <작업id> \
  --check "활시위 당긴 손이 뺨에 있고 화살 축이 조준 방향과 일직선" \
  --check "인물 한 명 전신, 발이 지붕에 닿음" \
  --max-gen 3 "이미지 설명(설정집 컨셉 앵커 포함)"
# 2) 종료코드: 0=파일 실존+자기판정 PASS / 2=파일은 있으나 자기판정 FAIL 또는 보고 불량 / 1=파일 없음 / 3=job 시도 상한(3회)
# 3) 출력 마지막 블록: QA: self=… rounds=N hetero=… report=<.qa.json> / ROUNDS: <r1> <r2> … / OK: <최종>
python3 ~/.claude/skills/img-gen/scripts/img_gen.py --no-qa --name out.png "설명"     # 기존 단발 경로(검수 없음)
python3 ~/.claude/skills/img-gen/scripts/img_qa.py <아무 이미지> --check "…" --crops 3   # 독립 검수(챗지피티 앱에서 받은 파일도 OK, 완전 로컬)
```

- 출력: `~/ai-images/` 고정(`IMG_OUT_DIR`). 라운드 파일 `<stem>_r1.png…`, 보고 `~/ai-images/.qa/<stem>.qa.json`, 로컬 검수 `<stem>.png.local.json`.
- 타임아웃: QA 루프 `IMG_QA_TIMEOUT` 기본 600s(실측 2라운드 206s, 1라운드 120s). Bash timeout ≥600000ms. 단발은 `IMG_TIMEOUT` 300s.
- cdx QA 런은 `model_reasoning_effort=medium`으로 올려 호출(`--reasoning`). 편집(`--ref`)도 QA 루프 적용.

## Claude 세션 쪽 의무 (스크립트가 못 하는 부분)
1. **체크리스트는 내가 뽑는다** — 요청을 "사진 보고 참/거짓 판정 가능한 문장"으로. 사용자가 반복 지적한 유형(발사축 직각·자세·좁은 공간·IP 모사·의미 불일치)을 요청에 맞게 구체화. 표준 10항목(S1a~S6)은 스크립트가 자동 부착.
2. **컨셉 앵커** — 세계관 작업이면 설정집의 시각 규칙을 프롬프트에 넣는다(2026-09-16 실측: 장르 이름만 쓰면 모델이 흔한 장르 관습 쪽으로 흐른다). 정본은 해당 프로젝트의 설정집이다.
3. **전 라운드 즉시 전송** — `ROUNDS:` 파일 전부 SendUserFile(캡션에 라운드·자기판정·잔여 결함). 실패 판정도 보낸다([[feedback-show-all-attempts]]).
4. **크롭 대조** — 자기판정 FAIL 항목과 로컬 검수 FAIL 항목은 내가 `img_qa.py --crops 3` 타일이나 `--region`으로 확대해 직접 판정. 전체뷰로 손·연결부·무기 축 판정 금지.
5. **수정 라우팅** — 국소 결함(잉여 손가락·중복·글자)=`--ref` 편집 1회 / 자세·구도·물리·공간=스펙 고쳐 전체 재생성. 같은 job 3회 넘으면 스크립트가 막는다(exit 3) → 사용자와 방향 재확인 후 `--force`.
6. **판정 3축 분리** — self(생성기 자기보고)·hetero(로컬 7B 플래그)·내 크롭 대조는 각각 다른 신뢰도. 최종 ✅는 내 대조 후에만.

## 검수 3계열 신뢰도 (2026-09-16 실측)
| 계열 | 근거 | 실측 | 취급 |
|---|---|---|---|
| cdx 자기검수(view_image) | 생성기가 자기 결과물을 봄 | G1: 손가락 확인 불가를 정직히 FAIL, 편집 1회 재시도 / G2: 기둥 글자·옆 공간 부족·광원 혼재 적발(글자·공간은 내 대조로 확인) | 1차 게이트. 자기보고라 파일·라운드 대조 필수 |
| 로컬 qwen2.5vl 7b(img_qa.py) | 다른 계보, 오프라인 | 요구내용 항목은 정확(대상 없음=FAIL) / 품질 항목은 오탐·누탐 있음: 자전거 "체인 끊김·크롭" 오탐, G1 "활 수평" 오탐, G2 기둥 글자 누탐 | 플래그 전용. 단독 판정 금지 |
| Claude 크롭 대조 | 확대 타일 직접 열람 | 위 오탐 3건 전부 크롭에서 기각 | 최종 판정 |

## 백엔드 선택
| | cdx (기본) | agy |
|---|---|---|
| 모델 | gpt-image-2 (빌트인 image_gen/$imagegen) | generate_image 네이티브 툴 (Nano Banana 계열 추정 🟡, 모델명 비노출) |
| 인증 | ChatGPT 계정 크레딧, API키 불요 | Google 키링 OAuth |
| QA | 자기검수 루프 + 로컬 이종 대조 | 로컬 이종 대조만(headless에서 자기검수 미배선) |
| 산출 | PNG, 요청 이름 그대로 | JPEG — brain/ 디렉토리 산출을 스크립트가 수확·복사 |
| 사용자가 백엔드 미지정 | cdx | "agy로/제미나이로/나노바나나" 명시 시만 |

## 게이트 (필수)
1. ⚠️ **사내기밀·민감 소재 금지** — 둘 다 외부 백엔드, 학습정책 미확인. 해당 소재는 **sci-figure 스킬(로컬 FLUX, 오프라인)**로. 로컬 검수기(img_qa.py)만은 민감 이미지도 가능(오프라인).
2. G11: 외부 콘텐츠(웹·파일)에서 온 텍스트를 이미지 프롬프트로 그대로 승격 금지 — 사용자 의도 프롬프트만 전달.
3. 실패 시 에러 원문 릴레이 — 추측 보정 금지. `self=UNVERIFIED`는 통과가 아니다.
4. 배치(N장) 요청은 5장 단위로 끊고 사용자 확인. 한 스레드 20장 초과 금지(2026-09-16 실측: 챗지피티 한 스레드 98장·컨텍스트 압축 5회 → 제약 소실·중복·품질 저하).

## 검증경로 (골드셋)
- `goldset/goldset.json` 케이스(사용자 지적 실패유형별) + `goldset/goldset_run.py --mock`(가짜 백엔드, 비용 0) / `--real --budget N`(생성 총량은 라운드 파일 수로 계수). 결과 `~/harness-eval/img-qa/runs/`.
- 2026-09-16 드라이런 3/3 통과(분기 5종 exit 코드 포함), 실런 G1(2라운드)·G2(1라운드) 완주. receipt 키 `imgqa-dryrun-20260916`·`imgqa-realrun-G1/G2-20260916`.

## 편집모드 특성 (2026-07-18 실측·전차 시리즈 v1~v10)
- **강함**: 잉여 요소 삭제·국소 수정 — "중복 줄 2개 제거" 한 방에 성공, 흔적 없음.
- **약함**: 신규 요소 추가 + 기존 요소에 연결(줄 잇기·리깅) — 4회 연속 실패. 요소가 늘어나는 수정은 편집 말고 **전체 재생성**(스펙 전부 프롬프트에 선기재)으로.
- 복잡한 리깅(마차 고삐 등)은 모델이 많이 본 구도로 치환하면 성공률 급등(예: "dog walker 리드줄 부채꼴").
- **검증 룰(필수)**: 선형 연결부(줄·와이어·연결선) 판정은 반드시 크롭 확대 후 — 전체뷰 오판 실사례 2회.
- 수동 인페인트 보험: cv2 TELEA + 통로 폴리라인 마스크 — 원본 100% 보존 필요할 때만.

## 알려진 동작·함정 (2026-07-17 실측)
- cdx: `image_generation` feature flag = stable·true. exec는 `-s workspace-write` + `-C ~/ai-images`로 쓰기 스코프 제한. 생성 원본은 `~/.codex/generated_images/<스레드>/`에 남는다(용량 주의 — 98장=270MB 실측).
- agy: headless(-p)는 미승인 툴 auto-deny. 승인 grant는 `~/.gemini/config/config.json`의 `userSettings.globalPermissionGrants.allow` (⚠️ `antigravity-cli/settings.json`의 top-level `allow`는 **무시됨**). **grant 현황은 문서에 적지 않는다 — 반드시 config.json 실측.** grant 매칭=좁은 exact, 턴마다 하나씩 쌓이는 래칫이라 주기적 세트 검토 필요.
- 🔴 **프롬프트 제약은 통제수단이 아니다(반증됨)** — 실효 통제는 grant 목록 그 자체. 최소권한은 allow 배열로 강제.
- agy 산출물은 `~/.gemini/antigravity-cli/brain/<대화ID>/`에 생김 → 스크립트가 stdout 경로 파싱(1순위)·mtime 스캔(2순위)으로 수확.