CLI 워크플로

문서 저작과 배치 제출 순서입니다.

문서 저작 흐름

만들고, 읽고, 시험 적용하고, 제안하는 순서입니다. 각 명령의 옵션은 명령 참조에 있습니다.
만들기, 읽기, 모의 실행, 제안 — bash
pnpm --filter @mellowz-studio/cli start -- doc create --title "히나" --key hina-create-001 --execute
pnpm --filter @mellowz-studio/cli start -- doc read <문서 id> --section identity
pnpm --filter @mellowz-studio/cli start -- doc simulate <문서 id> --operations ops.json
pnpm --filter @mellowz-studio/cli start -- doc propose <문서 id> --operations ops.json --execute
  1. doc create를 --execute 없이 먼저 실행해 같은 이름의 문서가 있는지 봅니다.
  2. --execute를 붙여 문서를 만듭니다. 같은 --key로 다시 보내도 문서는 하나입니다.
  3. doc simulate로 연산이 통하는지 서버 사본에서 확인합니다. 실패하면 종료 코드 2입니다.
  4. doc propose를 --execute 없이 실행해 결과만 보고, 괜찮으면 --execute로 올립니다.
  5. 제안은 승인 대기로 들어갑니다. 적용 여부는 앱에서 사용자가 결정합니다. proposals list로 상태를 봅니다.
제안 상태 보기 — bash
pnpm --filter @mellowz-studio/cli start -- proposals list <문서 id> --status pending
연산 파일은 연산 1~20개가 든 JSON입니다. 연산 형식은 캐릭터챗 MCP의 가이드 도구(get_character_chat_guide)가 알려 줍니다.

가져오기 미리보기

외부 플랫폼 덤프를 가져오기 전에 정규화 결과만 봅니다. 아무것도 저장하지 않습니다.
덤프 정규화 미리보기 — bash
pnpm --filter @mellowz-studio/cli start -- import normalize --platform zeta --source dump.json

배치 제출 흐름

캐릭터 브리프 여러 건을 한 번에 문서로 만듭니다. 제출은 체리를 씁니다.
items.json 한 항목의 모양 — json
[
  {
    "id": "item-001",
    "brief": {
      "name": "히나",
      "oneLiner": "수줍은 도서관 사서",
      "tags": ["일상", "로맨스"],
      "description": "조용한 마을 도서관에서 일하는 사서입니다.",
      "genre": "로맨스",
      "audienceBias": "neutral"
    },
    "maxAttempts": 3,
    "maximumCherry": 5
  }
]
audienceBias는 male, female, neutral 중 하나입니다. 태그는 10개까지, 설명은 4,000자까지입니다. maxAttempts는 1~20의 정수이고 maximumCherry는 0 이상의 정수입니다.
모의 실행, 제출, 상태 보기 — bash
pnpm --filter @mellowz-studio/cli start -- batch create --batch-id hina-batch-001 --items items.json
pnpm --filter @mellowz-studio/cli start -- batch create --batch-id hina-batch-001 --items items.json --execute
pnpm --filter @mellowz-studio/cli start -- batch get hina-batch-001
  1. --execute 없이 실행해 estimatedCherry와 기존 배치를 확인합니다.
  2. --execute를 붙여 제출합니다. 같은 --batch-id로 다시 보내면 같은 요청입니다.
  3. batch get으로 상태와 항목별 진행, 만들어진 문서를 봅니다.
  4. 일부 항목이 실패했으면 batch retry를 먼저 모의 실행으로 보고, --execute로 재시도합니다. 재시도도 체리를 씁니다.
  5. 중간에 멈추려면 batch cancel --execute입니다. 쓰지 않은 예약은 돌려받습니다.
주의
토큰이 개인 키 지출 한도나 잔액을 넘으면 서버가 거절하고 종료 코드 5로 끝납니다.

스크립트에서 쓰기

--json을 붙이면 종료 코드와 함께 결과를 기계가 읽을 수 있습니다. 쓰기 명령을 자동화할 때는 모의 실행의 dryRun과 data를 확인한 뒤에만 --execute를 붙이세요. 자세한 원칙은 안전한 자동화에 있습니다.

관련