Media Higgsfield Core

---
name: media-higgsfield-core
description: |
  Higgsfield MCP 이미지·영상 생성의 공유 코어. media-higgsfield-image / media-higgsfield-video가
  로드하는 SSOT(single source of truth)로, 호출 스키마·라이브 카탈로그 조회 프로토콜·공통 크래프트
  규칙(R1–R5)·인터뷰 슬롯·잡 수명주기를 정의합니다.
  다음과 같은 상황에서 로드됩니다:
  - media-higgsfield-image 또는 media-higgsfield-video가 호출 계약을 참조할 때
  - Higgsfield 모델의 파라미터를 하드코딩하지 않고 런타임 조회해야 할 때
  - namespace(mcp__higgsfield__ vs mcp__claude_ai_higgsfield__)를 런타임 해석해야 할 때
  이 스킬은 단독 실행 스킬이 아니라 두 소비 스킬이 참조하는 공유 코어입니다.
version: "1.2.0"
---

# Higgsfield 코어 (media-higgsfield-core)

> `moai-media` | 이미지·영상 스킬의 공유 SSOT (참조 전용 코어)

## 개요

이 스킬은 `media-higgsfield-image`와 `media-higgsfield-video`가 공통으로 참조하는 코어다. 두 소비 스킬은 호출 계약·조회 순서·공통 규칙을 여기서 가져온다. **핵심 설계 원칙: 파라미터(모델 id·enum·aspect·duration·media role·비용)는 절대 하드코딩하지 않고 런타임에 `models_explore`로 조회한다. 프롬프트 크래프트만 정적으로 큐레이션하고 출처를 단다.**

이 설계가 필요한 이유는 두 축이 서로 다른 진실원을 갖기 때문이다:

| 축 | 진실원 | 스킬이 얻는 방법 |
|---|---|---|
| 파라미터 | 라이브 MCP | `models_explore` / `show_marketing_studio` / `presets_show` / `get_cost` (호출 시점) |
| 프롬프트 크래프트 | 모델 벤더 공식 문서 | 계열별 `prompt-craft/*.md` (저술 시점 고정, 출처·Evidence tier 표기) |

## 코어 참조 파일

| 파일 | 역할 |
|---|---|
| `references/call-schema.md` | 중첩 `params{}` 형태 계약, `medias[].role/.value` 규칙, namespace 런타임 해석, 존재하지 않는 파라미터 안티패턴 |
| `references/catalog-protocol.md` | `models_explore` 등 라이브 조회 도구와 표준 순서(REQ-010), 범위 밖 모델 폴백 |
| `references/universal-rules.md` | R1–R5 벤더 교차 공통 규칙 |
| `references/interview-schema.md` | 크래프트 파일이 소비하는 수집 슬롯 |
| `references/job-lifecycle.md` | `get_cost` 프리플라이트, `credits` 규칙, `adjustments` 리드백, 폴링·오류 분류, 잔액 정지 |

## 오케스트레이션 계약 (REQ-010 흐름)

소비 스킬은 다음 순서를 따른다:

1. **의도 → 후보 좁히기** — 사용자 요청에서 계열 후보를 추린다(크래프트 노트 참조). 후보를 좁힐 뿐 파라미터를 단정하지 않는다.
2. **라이브 조회** — `models_explore(action:'get')`로 실제 제약을 가져온다. Marketing Studio 계열이면 `show_marketing_studio`.
3. **비용 프리플라이트** — `get_cost: true`로 `credits` 확인(크레딧 0). `adjustments` 확보.
4. **승인 게이트** — 크레딧이 나가기 전 마지막 정지선. 아래 §유료 생성 승인 게이트.
5. **생성** — 승인된 값으로만 호출.
6. **폴링·리드백** — `job_status`로 `completed`까지, `adjustments`를 사용자에게 보고.

## 유료 생성 승인 게이트

3단계에서 비용을 확인해놓고 곧바로 4단계로 넘어가면, 사용자는 **얼마가 나갔는지 청구된 뒤에 안다.** 프리플라이트는 비용을 *조회*할 뿐 승인을 받지 않는다. 이 게이트가 그 사이를 메운다.

- **[HARD] 크레딧이 소진되는 호출 전에는 반드시 승인을 받는다.** 프리플라이트(`get_cost: true`, 크레딧 0)와 조회 계열 도구는 게이트 대상이 아니다 — 돈이 나가는 호출만이다.
- **[HARD] 승인은 §승인 요청 계약의 경로로 받는다.** 이 스킬과 소비 스킬은 사용자에게 직접 묻지 않으므로(§인터뷰 경계), 게이트에 도달하면 blocker로 반환하고 **오케스트레이터가 대신 묻는다.** 슬롯 수집과 같은 경로다.
- **[HARD] 요약하지 말고 실제로 넘어가는 것을 그대로 보여준다:**

| 보여줄 것 | 왜 필요한가 |
|---|---|
| 프롬프트 **전문** | 사용자가 돈을 내는 대상이 이 문장이다 |
| 모델 id와 계열 | 같은 요청도 모델에 따라 비용·결과가 다르다 |
| 입력 미디어 (`media_id` / `job_id` 목록과 role) | 어떤 이미지가 재료로 들어가는지 |
| 조회로 확정된 옵션 (비율·해상도·길이 등) | 하드코딩이 아니라 조회값임을 확인 |
| 생성 개수 | 개수가 곧 배수 비용이다 |
| `adjustments` — 서버가 조용히 바꾼 값 | 사용자가 요청한 것과 실제 실행될 것의 차이 |
| `get_cost`가 돌려준 **견적 크레딧**과 현재 잔액 | 얼마가 나가고 얼마가 남는지 |

승인 선택지는 이렇게 구성한다:

| 선택지 | 뜻 |
|---|---|
| 이대로 생성 (권장) | 보여준 값 그대로 호출 |
| 고쳐서 다시 견적 | 프롬프트·모델·개수를 바꿔 3단계부터 다시 |
| 취소 | 호출하지 않고 종료. 크레딧 소진 없음 |

- **[HARD] `adjustments`는 승인 전에 보여준다.** 생성이 끝난 뒤 리드백으로 보고하는 것(6단계)은 그 자체로 옳지만, 서버가 요청을 바꿨다는 사실은 **돈이 나가기 전에** 알아야 취소할 수 있다. 6단계 보고가 있다고 해서 이 항목을 생략하지 않는다.
- **[HARD] 실패해도 새 잡을 만들지 않는다.** 생성 호출이 애매하게 실패하면(타임아웃·응답 없음) 재호출하지 않는다. 성공 신호가 없다는 것은 잡이 만들어지지 않았다는 증거가 아니며, 블라인드 재시도는 크레딧을 두 번 쓴다. 반환된 job/request ID가 있으면 `job_status`로 그 잡의 상태를 먼저 확인하고, ID조차 없으면 **생성 이력을 조회할 도구가 실제로 노출돼 있는지 먼저 확인한다** — 코어 `catalog-protocol.md`가 계약으로 두는 것은 `job_status`·`job_display`뿐이고, 이력 조회 도구는 그 목록에 없다. 노출돼 있으면 그것으로 확인하고, **없으면 사용자에게 Higgsfield 대시보드에서 직접 확인해 달라고 요청한다.** **재시도는 언제나 기존 잡 ID에 묶인다** — 없다는 것이 확인된 뒤에만 새로 만든다.
- **[HARD] 대량 배치는 배치 단위로 승인한다.** 한 요청이 여러 잡을 만들면(다중 변형·블록 조립 등) 잡마다 묻지 않고 **전체 계획 + 최대 총 크레딧**을 한 번에 승인받는다. 승인된 계획을 넘는 추가 생성은 새 승인을 받는다.

## namespace 런타임 해석

Higgsfield 도구의 namespace 접두사는 등록 방식에 따라 `mcp__higgsfield__` 또는 `mcp__claude_ai_higgsfield__`다. 스킬은 호출 직전 실제 노출된 namespace를 런타임에 확인하고 그 접두사를 쓴다. 어느 하나를 유일 정답으로 하드코딩하지 않는다. 상세는 `references/call-schema.md` §3.

## 인터뷰 경계

이 스킬(및 서브에이전트)은 사용자에게 직접 질문하지 않는다. 수집할 슬롯을 문서화할 뿐이며, 실제 질문은 오케스트레이터가 진행한다. 슬롯이 비면 구조화된 blocker 보고를 반환한다. 상세는 `references/interview-schema.md`.

## 승인 요청 계약 (런타임 중립)

[HARD] 이 스킬의 게이트는 **특정 도구 이름에 묶이지 않는다.** `AskUserQuestion`은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 **영구 blocker**가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.

승인은 아래 순서로 구한다. 위에서부터 **실제로 가능한 첫 번째**를 쓴다.

**승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것.** 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.

| 순위 | 경로 | 조건 |
|---|---|---|
| 1 | 런타임의 구조화 질문 도구 (`AskUserQuestion` 등) | 그 도구가 현재 세션에 노출돼 있을 때 |
| 2 | **일반 대화로 승인서를 제시하고 다음 턴에서 응답을 받는다** | 사용자와 직접 대화 중일 때. 도구가 없어도 이 경로는 언제나 열려 있다 |
| 3 | 구조화 blocker 반환 → 상위 오케스트레이터가 물어봄 | 서브에이전트로 실행 중일 때 |

**[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다.** 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.

**[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다.** 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 **대화도 blocker 반환도 불가능한 완전 무인 실행**에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.

**[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다.** 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:

- 승인받을 **행위** 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
- 게이트가 요구하는 **인자 전부** (요약하지 않은 값)
- **선택지 목록** — 상위가 그대로 사용자에게 제시할 수 있는 형태
- **재개 방법** — 어떤 답을 받으면 무엇을 이어서 실행하는지

**[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed).** 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 **대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못**이다. 2번 경로를 쓴다.

> 이 계약은 `CLAUDE.local.md` §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.

---

## 관련 스킬

| 스킬 | 관계 |
|---|---|
| `moai-media:media-higgsfield-image` | 소비: 이미지 생성 |
| `moai-media:media-higgsfield-video` | 소비: 영상 생성 |
| `moai-media:media-higgsfield-identity` | 소비: Soul·Element 일관성 참조 |
| `moai-media:media-higgsfield-assets` | 소비: 3D·오디오·영상 분석·후처리 |
| `moai-media:media-higgsfield-explainer` | 소비: 블록 조립형 설명 영상 |
| `moai-media:media-higgsfield-product` | 소비: 제품 촬영 10모드 |
| `moai-designer:design-brand-visual` | 소비(교차 플러그인): 브랜드 정합 비주얼 |
| `moai-story:story-*` | 소비(교차 플러그인): 작화·콘티·표지·캐릭터 |

## 출처

- [Higgsfield Skills (공식 agent 문서)](https://github.com/higgsfield-ai/skills)
- [Higgsfield MCP](https://higgsfield.ai/mcp)
- 라이브 카탈로그 스냅샷: `.moai/specs/SPEC-MOC-HIGGSFIELD-PROMPT-001/mcp-catalog-snapshot.md` (plan 단계 증거 기준선, 런타임 계약 아님)