pumasi-image

# /pumasi-image — Codex 이미지 생성 > Codex의 네이티브 이미지 생성/편집 도구(`image_gen`, gpt-image-2)로 이미지를 만든다. > 코드 병렬 외주(pumasi)와 완전히 분리된 독립 스킬. > **이미지 요청은 사용자가 "코덱스로"라고 말해도 전부 이 스킬이 담당한다** — pumasi로 넘기지 않는다. ## 먼저 읽을 것 - `references/clarification-matrix.md` — 모드별 의도 파악 질문 매트릭스 - `references/keyword-mapping.md` — 비율·퀄리티 키워드 자동 매핑 + 자연어 힌트 변환표 - `references/image-studio-prompt.md` — 모드 분류 + Output Template 시스템 프롬프트 (영문 프롬프트 작성 직전에만 Read) --- ## 핵심 원칙 1. **백엔드는 2종 — Codex 네이티브 이미지 도구(기본)·Grok `image_gen`(선택)** — nanobanana 등 다른 백엔드 사용 안 함. 백엔드는 Step 3에서 사용자가 고른다(입력에 지명이 있으면 스킵). Grok을 쓸 때는 반드시 `scripts/imagen.sh`(`--backend grok`)를 경유한다(비율 강제·확장자 정합·실패 사유 표면화가 그 안에 있다). `grok`을 직접 부르지 말 것. 2. **API 키를 꺼내 직접 호출하지 않는다** — 볼트·환경변수·설정 파일에서 OpenAI(또는 xAI) API 키를 읽어 `api.openai.com` 등 이미지 API 엔드포인트를 직접 부르는 행동은 **금지**. 이미지는 오직 (a) Codex 네이티브 이미지 도구 또는 (b) `scripts/`의 codex/grok 백엔드로만 만든다. 구독 세션이 인증을 담당하며, 이 스킬은 어떤 키도 만들거나 복사하지 않는다. 3. **image-studio 시스템 프롬프트 내면화** — 모드 분류 + Output Template 작성 4. **후처리 절대 금지** — sips/ImageMagick/재인코딩 금지, 생성 원본 그대로 저장(SHA1 유지) 5. **저장 경로 고정** — `{BASE_DIR}/images/{YYYY-MM-DD}/{slug}-{seq}.png` 6. **최대 5개 질문** — 기술 2개 + 의도 3개, 조건부 스킵 7. **텍스트는 이미지 도구가 직접 렌더링한다** — 썸네일·포스터·로고의 한글/영문 카피는 프롬프트의 Text Integration 섹션에 따옴표로 묶어 그대로 명시. **HTML/CSS 분리·후합성·텍스트 레이어 분할 절대 금지.** 구세대 diffusion(SD/Midjourney) 가정으로 "텍스트 못 그림"이라고 회피하지 말 것 — 다음 §의 capability snapshot 참조. --- ## gpt-image-2 capability snapshot (as of 2026-05) > 목적: 구세대 diffusion 직감으로 회피 행동(HTML/CSS 분리, 텍스트 빼고 합성, 재시도 회피)을 하지 못하게 capability를 명시적으로 박는다. 모델 업데이트 시 `as of` 날짜 기준으로 갱신. ### CAN (자신 있게 시도) - **한글/영문 헤드라인 텍스트** — 16pt 이상 굵은 sans-serif/serif, 정확한 자모/획 - **다국어 혼용** — 한+영 동시 노출(예: "광안대교 BEST 5 / Best Spots") - **로고 타이포그래피** — 워드마크, 레터마크, 한자/한글 디자인 타이포 - **숫자/날짜 단순 표기** — "2026", "BEST 5", "Vol.3" 정도는 안정적 - **복잡한 레이아웃** — 헤드라인 + 서브카피 + 가격표 + CTA 버튼 한 컷에 - **표·UI 목업·차트** — 행/열 정렬, 라벨, 범례, 막대그래프 텍스트 - **손/얼굴/포즈 디테일** — 손가락 개수, 표정, 시선 방향 정확 - **사진 사실성** — DSLR 룩, 조명 일관성, 그림자/반사 물리 ### WEAK (조심해서 시도, 결과 보고 판단) - **매우 작은 글씨** — 8pt 이하 본문은 깨질 확률 높음 → 헤드라인 위주로 설계 - **긴 본문 단락** — 한 블록 50자 이상은 중간에 자모 흔들림 가능 - **정확성이 중요한 숫자** — 가격/날짜/전화번호는 1-2글자 변형 위험 (생성 후 검수 필수) - **손글씨/캘리그래피 한글** — 자모 결합 흔들림 잦음, 정자체 폰트가 안전 ### CAN'T 가정 금지 (구세대 diffusion 직감 차단) - ❌ "한글은 어차피 깨지니까 영문으로만 만들자" — gpt-image-2는 한글 OK - ❌ "텍스트는 빼고 만든 후 HTML/CSS로 합성하자" — 1차 직접 렌더 금지 사유 아님 - ❌ "썸네일이니까 텍스트 부분만 따로 디자인하자" — 한 컷에 통합 렌더가 정석 - ❌ "로고에 한자/한글 들어가면 안 됨" — 워드마크 직접 렌더 가능 ### Grok image_gen 차이 (선택 백엔드) - 비율은 **9:16 / 16:9 / 1:1만** 지원 — 그 외를 주면 스크립트가 1:1로 강제하고 경고한다 - 퀄리티 파라미터 없음 (퀄리티 질문 스킵) - 산출물이 보통 **JPEG** — 스크립트가 타깃 확장자를 소스에 맞춰 자동 조정하고 최종 경로를 `path:`로 보고한다 - 텍스트 렌더 품질은 gpt-image-2 대비 미검증. SuperGrok 구독이면 한계비용 0 ### 운영 룰 1. **1차는 무조건 이미지 도구로 직접 렌더** — 텍스트 포함 여부 무관 2. **결과 검수** — 이미지 표시 후 텍스트 정확도 사용자 확인 (Step 7 모드 참조) 3. **재시도 우선** — 첫 결과가 깨졌으면 프롬프트 보강(폰트 명시, 크기 명시)해서 1-2회 재생성 4. **합성 옵션은 사용자 명시 거부 후** — "직접 렌더 결과 마음에 안 들어, 합성으로 가자"는 사용자 발화가 있을 때만 후합성 워크플로우 제안 --- ## 워크플로우 ### Step 0: feature flag 확인 (scripts 경로를 쓸 때만) 네이티브 도구를 직접 쓰면 이 단계는 없다. `scripts/imagen.sh` 위임 경로를 쓸 때는 스크립트가 `codex features list`로 `image_generation` 플래그를 확인하고 꺼져 있으면 `codex features enable image_generation`으로 켠다 — 사용자에게는 조용히 수행한다고만 짧게 알린다. ### Step 1: 모드 자동 감지 사용자 요청에서 7가지 모드 중 하나를 결정한다: | 모드 | 감지 키워드 | |------|-----------| | MODE_A_PORTRAIT | "프로필", "인물", "얼굴", "초상" | | MODE_B_LANDSCAPE | "풍경", "배경", "자연", "도시", "바다", "산" | | MODE_C_OBJECT | "제품", "물건", "아이템", "상품" | | MODE_D_ILLUSTRATION | "일러스트", "그림", "아트", "드로잉" | | MODE_E_THUMBNAIL | "썸네일", "커버", "대표이미지", "유튜브" | | MODE_F_LOGO | "로고", "브랜드", "심볼", "아이콘" | | MODE_G_CONCEPTUAL | "컨셉트", "추상", "아이디어", "상징" | 모드 판단 불확실 시 Step 3의 질문에 "모드 선택" 1개를 추가한다. ### Step 2: 키워드 자동 매핑 → 파라미터 추출 `references/keyword-mapping.md`를 Read하여 비율·퀄리티 자연어 힌트를 추출한다. - 비율 키워드가 입력에 있으면 → 비율 질문 스킵 - 퀄리티 키워드가 입력에 있으면 → 퀄리티 질문 스킵 ### Step 3: 사용자 질문 (§A 번호형 블록, 최대 5개) Codex CLI에는 객관식 카드형 질문 UI가 **없다.** 결정이 꼭 필요하면 `$PLUGIN_ROOT/shared/questioning-policy.md §A`의 **채팅 번호형 선택지 블록**으로 묻는다. `references/clarification-matrix.md`를 Read하여 모드별 의도 파악 카테고리 3개를 확정한다. **질문 순서** (한 턴 최대 4문항 — 초과분은 우선순위 낮은 의도 질문부터 잘라낸다): 0. **백엔드** (입력에 "그록으로"/"grok"/"코덱스로"/"codex" 지명이 있으면 스킵) ```text 질문: 어떤 백엔드로 생성할까요? 1. Codex gpt-image-2 (권장) — 임의 비율, 한글/영문 텍스트 렌더 강함 2. Grok image_gen — SuperGrok 구독 시 한계비용 0. 단 비율 9:16/16:9/1:1만, 텍스트 렌더 미검증 3. 문장으로 직접 알려주기 ``` 1. 비율 (Step 2에서 확정됐으면 스킵. **Grok 선택 시 선택지를 9:16/16:9/1:1로 제한**) 2. 퀄리티 (Step 2에서 확정됐으면 스킵. Grok에는 퀄리티 파라미터가 없으므로 Grok 선택 시 스킵) 3~5. 의도 파악 3개 (모드 매트릭스 기반) **질문 원칙**: - §1 + §2c: 이미 입력에서 확정된 차원은 **묻지 않는다**. 요청이 구체적이면 질문 없이 바로 생성한다(과잉 질문 = 마찰 실패). - 물을 때는 §A 번호형 블록으로 — 각 슬롯당 5개 이상 선택지, 그중 1~2개는 창의적 대안(★), 마지막은 "문장으로 직접 알려주기"(Other 대체). - "자동 추천(AI 판단)" 안전망 선택지를 항상 포함하고, "모르면 1번(자동 추천)으로 진행하겠습니다"로 안내한다. - 여러 슬롯을 한 번에 물을 때는 각 질문 블록을 이어서 출력하고 "여러 개면 1,3처럼 적어주세요"로 안내. 카드 UI를 흉내내지 말 것. §A 블록 예시 (단일 슬롯): ```text 질문: 어떤 분위기로 갈까요? 1. 자동 추천 — 내용에 맞게 판단. 결정 피로 없이 진행 2. 다크 시네마틱 — 영화적, 깊은 그림자 3. 따뜻함 — 친근, 햇살, 파스텔 4. 조용한 위로감 (★) — 잔잔함, 여운 5. 문장으로 직접 알려주기 ``` ### Step 4: image-studio 내면화 + Output Template 작성 `references/image-studio-prompt.md`를 Read하여 시스템 프롬프트를 내면화한다. 내면화 후: 1. Normalization JSON 내부적으로 작성 (노출하지 않음) 2. 선택된 모드의 Output Template을 200~500 단어 영문 프롬프트로 작성 3. 사용자 선택 값(비율·퀄리티·의도 3개)을 Technical Specifications / Anti-Patterns 섹션에 반영 4. 비율·퀄리티 자연어 힌트를 Technical Specifications에 삽입 (keyword-mapping.md 참조) 5. **Format / Medium Guard** — 단일 심볼 컨셉(돋보기·로켓·방패 등)을 사용자가 로고/아이콘을 요청하지 않았는데 앱아이콘·글래스 배지로 만들지 않는다. hero/배너/커버/씬은 프레임을 가득 채우는 full-bleed 장면으로 번역한다 (image-studio-prompt.md의 가드 참조) 프롬프트를 다음 경로에 저장 (없으면 `mkdir -p`): ``` {BASE_DIR}/.imagen/prompt-{timestamp}.md ``` ### Step 4-bis (선택, feature flag 뒤): 영문 프롬프트 작성을 codex 워커에 위임 환경변수 `PUMASI_IMAGE_DELEGATE_PROMPT=1` 설정 시: 1. Step 4의 image-studio-prompt.md Read + 영문 프롬프트 작성 단계 **스킵** 2. Step 6에서 `scripts/imagen-full.sh` 호출 — 의도 한 줄 + mode + aspect + quality + 타깃 경로(+ 선택 ref 이미지)만 전달 3. 영문 프롬프트 작성은 codex 워커 측에서 수행하고 prompt.md + manifest.json + codex.log를 `{타깃디렉토리}/.imagen-full/`에 저장 (refine 복구용) 4. **자동 fallback**: imagen-full.sh가 exit ≠ 0이면 즉시 Step 4(직접 작성) + 기본 경로로 폴백. 사용자에게는 "위임 경로 실패 → 직접 작성 경로로 전환" 한 줄 안내. codex 백엔드 전용(Grok에는 없음). ### Step 5: 저장 경로 계산 **기준 디렉토리 (하드코딩 금지, 동적 계산)**: ```bash BASE_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd) DATE=$(date +%Y-%m-%d) TARGET_DIR="${BASE_DIR}/images/${DATE}" mkdir -p "$TARGET_DIR" SLUG="busan-gwangan-bridge-night" # 요청에서 계산 (핵심 명사 1~2개 → 영문 kebab-case) SEQ=1 TARGET_PATH="${TARGET_DIR}/${SLUG}-$(printf '%02d' $SEQ).png" while [[ -e "$TARGET_PATH" ]]; do SEQ=$((SEQ + 1)) TARGET_PATH="${TARGET_DIR}/${SLUG}-$(printf '%02d' $SEQ).png" done echo "$TARGET_PATH" ``` **왜 git root 기준인가**: 세션의 cwd가 항상 프로젝트 루트는 아니다. 단순 상대경로는 엉뚱한 곳에 저장될 위험이 있어, 프로젝트 루트의 `images/` 하위를 기본값으로 둔다. git 저장소 밖이면 `pwd` 기준. slug 예: "부산 광안대교 야경" → `busan-gwangan-bridge-night`, "AI 마켓플레이스 로고" → `ai-marketplace-logo`. 확장자는 `.png`. Grok 백엔드는 산출물이 보통 JPEG라 스크립트가 확장자를 맞춰 조정하므로 **결과 보고는 스크립트 출력의 `path:`를 기준**으로 한다. ### Step 6: 이미지 생성 호출 **기본 경로 — Codex 네이티브 이미지 도구를 직접 호출한다.** - 백그라운드 CLI 세션을 띄우지 않는다. - Step 4의 영문 프롬프트 + Step 5의 타깃 경로를 도구에 전달한다. - 프롬프트 끝에 후처리 금지 가드(원본 유지, 재인코딩 금지)를 명시한다. - 텍스트가 깨졌으면 합성하지 말고 프롬프트를 보강해 1~2회 재생성한다(운영 룰 3). - 도구가 돌려준 이미지를 **이번 호출 산출물만** Step 5의 타깃 경로에 저장한다. 생성이 0장이면 거짓 성공을 보고하지 말고 실패로 처리한다. **스타일 앵커(레퍼런스)**: 여러 장을 같은 스타일로 뽑을 때는 1장을 먼저 생성·승인받고, 나머지를 전부 그 파일을 레퍼런스로 물려 편집 도구로 생성한다(앵커 우선 패턴). 레퍼런스가 있으면 프롬프트에서 스타일 서술을 걷어내고 "첨부 이미지의 스타일·조명·색감 유지" + 피사체·구도 델타만 쓴다 — 레퍼런스가 이미 묶은 것을 긴 산문으로 재서술하면 둘이 싸운다. 스타일 일관성 수단 서열(1차 출처 리서치 2026-08-22): 레퍼런스 이미지 ≫ 텍스트 재사용 ≫ seed(어느 벤더도 프롬프트가 달라진 뒤의 재현을 보장하지 않음). #### 위임 경로 (선택) — scripts 사용 별도 `codex exec` 워커에 생성을 위임하거나(호스트 컨텍스트 절약), **Grok 백엔드**를 쓰거나, 영문 프롬프트 작성까지 위임하려면 `scripts/`의 결정적 래퍼를 쓴다: ```bash # 영문 프롬프트는 호스트가 작성, 생성만 위임 (3번째 인자 비율은 실측 비교 경고용, --ref 반복 가능) bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen.sh \ "{prompt_file_path}" "{target_image_path}" "{aspect e.g. 16:9 — 생략 가능}" \ --backend "{codex|grok — Step 3 선택 결과, 생략 시 codex}" \ --ref "{anchor_image_path — 생략 가능}" # 영문 프롬프트 작성까지 codex 워커에 위임 (PUMASI_IMAGE_DELEGATE_PROMPT 경로) bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen-full.sh \ "{intent}" "{mode}" "{aspect}" "{quality}" "{target_image_path}" "{ref_image — 생략 가능}" # 여러 장 일괄 (partial success + per-item retry manifest; 항목에 "ref" 키로 앵커 지정 가능) bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen-batch.sh "{batch_json_path}" ``` `--backend grok`: `grok` 헤드리스 `image_gen`으로 생성한다(`--ref`를 주면 `image_edit`). 사전 조건: grok CLI 설치(`$HOME/.grok/bin/grok`) + `grok login`. 미설치/미로그인이면 스크립트가 exit 3으로 실패하니 사용자에게 알리고 codex 재생성 여부를 §A 블록으로 확인한다. 래퍼 내부 동작(codex 백엔드): 1. `codex features list`로 image_generation feature flag 재확인 (안전망) 2. `codex exec --json … < /dev/null` 호출 — codex가 이미지 도구로 1장 생성. `< /dev/null`은 exec가 stdin EOF를 무한 대기(헤드리스 행)하는 것을 막는다. 레퍼런스는 `--image=<path>`(파일당 1개)로 전달 — `-i FILE...`은 가변 인자라 뒤따르는 프롬프트를 이미지 경로로 삼켜 "No prompt provided" 실패를 만든다(실측 2026-08-22). 3. **회수 계약 (codex-cli 0.147+ 실측)**: `codex exec`는 이미지를 `~/.codex/generated_images/<thread_id>/exec-*.png`로 **저장**하고 stdout JSONL에는 base64를 싣지 않는다. 래퍼는 stdout의 `thread.started.thread_id`(디렉토리명과 1:1)로 **이 세션 산출물만** 집어 타깃에 복사한다(동시 실행과 경합 없음, 스테일 오집음 없음). 구버전 codex 호환용으로 stdout(JSONL)·세션 rollout의 base64 디코딩 폴백(`extract_image.py`)을 유지한다. 생성 0장이면 거짓 성공 없이 exit 5. 4. 실측 해상도(`sips`) + 요청 비율과 15%↑ 괴리 시 경고. 후처리는 절대 하지 않음. 5. **프록시 우회** — 로컬 프록시(`HTTP_PROXY`/`HTTPS_PROXY`)가 환경에 상속돼 있으면 codex 호출에서만 벗긴다. 프록시를 경유하면 이미지 엔드포인트 요청이 ~153초 뒤 `network error`로 죽는다(2026-07-23 실측: 경유 89/89 실패, 우회 시 동일 프롬프트 44초 성공). 해제는 `PUMASI_IMAGE_KEEP_PROXY=1`. 6. **실패 사유 표면화** — codex가 남긴 `image generation failed: …` 원문을 `REASON:`으로 출력하고, network error면 프록시 힌트를 덧붙인다. 네트워크 실패와 정책 거부를 구분해 보고한다. > ⚠️ **샌드박스/승인 우회 경계 (opt-in).** 래퍼는 `codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox`로 > 비대화형 실행한다 — 동작은 대상 이미지 경로 1개 쓰기로 한정된다. **신뢰하는 본인 프로젝트에서만** 사용한다. ### Step 7: 결과 확인 + 표시 (모드별) 생성 모드를 판정한 후 그에 맞게 동작한다. (PNG 1장 표시 = 약 1,400~3,000 비전 토큰이 cached prefix에 박히므로 기본값은 표시 안 함.) #### 모드 판정 규칙 - **fast/no-show** (기본값): 검수/audit 키워드 없고, 모드가 텍스트 의존(E_THUMBNAIL/F_LOGO)도 아니고, 의도에 한글/영문 카피가 없을 때 - **review/show-one**: 모드가 `MODE_E_THUMBNAIL` / `MODE_F_LOGO` / 의도에 직접 인용된 카피(따옴표)가 있을 때 — 마지막 1장만 표시 - **audit/show-all**: 사용자가 "검수해줘", "전부 보여줘", "꼼꼼히 확인", "review all" 명시할 때 — 전체 표시 #### 동작 1. 파일 존재 확인 + `file {target_image_path}`로 해상도/포맷/sha1 확인 (스크립트 경로면 출력의 `path:` 기준) 2. 모드별 분기: - **fast**: 경로만 안내 (`✅ 생성 완료: {path} ({해상도} {포맷}, sha1: {prefix})` + "깨졌으면 '이미지 보여줘'라고 말씀해주세요"). 이미지 표시 안 함. - **review**: 위 안내 + 마지막 1장만 표시 (텍스트 렌더링 검수). 안내에 "[review 모드]" 추가. - **audit**: 위 안내 + 모든 이미지 표시. 안내에 "[audit 모드]" 추가. ### Step 8: MODE_REFINE 루프 (state 유지 + Step 4 재로드 금지) 생성 직후 다음을 대화 컨텍스트(skill state)로 유지: - `last_prompt_path`: 마지막 영문 프롬프트 파일 경로 (Step 4 산출물) - `last_image_path`: 마지막 이미지 경로 (앵커 후보) - `last_manifest_path`: 마지막 manifest.json 경로 (imagen-full.sh 사용 시) - 선택 파라미터 (backend / mode / aspect / quality / 의도 답변 3개) **리파인 판정**: - **동일 이미지 리파인** ("색감 좀 바꿔줘", "더 밝게"): - Step 4 재로드 **금지** — `last_prompt_path` Read + 사용자 델타만 patch - 시각 컨텍스트 필요 시 `last_image_path` 표시 (자동 review 모드)