캐릭터 카드 V2 와 V3: 무엇이 바뀌었고 어떻게 마이그레이션하는가.캐릭터 카드 V2 와 V3:
무엇이 바뀌었고 어떻게 옮기는가.

어떤 클라이언트에서 카드를 내보내고 다른 클라이언트로 가져왔더니 절반의 필드가 사라진 경험 —— 인사말이 잘리고, lorebook 이 사라지고, 커스텀 프롬프트가 조용히 떨어져 나간 경험이 있다면, 그것이 바로 V1 / V2 / V3 문제다. Tavern 카드 포맷은 커뮤니티의 유산이다. 단일 위원회도, 버전화된 schema 레지스트리도, 모든 키를 같은 방식으로 구현하는 호스트도 없다.

대부분의 크리에이터에게는 사실 큰 문제가 아니다 —— 라이브러리가 Chub.ai, RisuAI, 그리고 친구가 직접 호스팅하는 SillyTavern 위에 동시에 살아남아야 하기 전까지는. 잘못된 버전을 보내면 몇 시간을 들여 쓴 결과물이 날아간다. 이 글에서는 각 버전이 무엇을 더했는지, 어디서 V3 를 안심하고 써도 되는지, 그리고 무엇도 깨뜨리지 않고 옮기는 방법을 차근차근 살핀다.

V1 카드는 최초의 Tavern 포맷이었다: 단일 JSON 페이로드를 PNG 의 tEXt 청크(키워드는 chara)에 넣고 JSON 자체는 Base64 로 인코딩한다. 스키마는 평평하고 최소한이었다 —— 본질적으로 name, description, personality, scenario, first_mes, 그리고 몇 개의 형제 필드뿐이었다. 이것만으로 커뮤니티를 수년간 지탱했고, 대부분의 호스트는 지금도 이를 폴백으로 받아들인다.

하지만 V1 에는 lorebook, 대체 인사말, 작성자나 튜닝 대상 모델에 관한 구조화된 메타데이터가 들어갈 자리가 없었다. 기본 이상을 담으려면 description 산문에 끼워 넣는 수밖에 없었다. 바로 그 틈을 V2 가 메우려 했다.

V2 는 PNG tEXt 전달 방식을 그대로 유지하되, 페이로드를 최상위 봉투로 감싼다:

{
  "spec": "chara_card_v2",
  "spec_version": "2.0",
  "data": {
    "name": "...",
    "description": "...",
    /* every real field lives under data */
  }
}

이 중첩이 핵심 변경이다 —— 평평한 형태만 읽는 옛 클라이언트는 쓸 만한 것을 아무것도 보지 못하므로, V2 카드는 거의 항상 V1 스타일 최상위 사본을 호환 심(shim)으로 함께 담는다.

data 아래에서 V2 는 크리에이터들이 의지하게 된 일련의 필드를 도입했다:

• character_book —— 카드 안에 직접 내장된 lorebook. 자체 엔트리, 키, 트리거 순서, 삽입 깊이를 가진다.
• alternate_greetings —— 추가 오프닝 메시지 배열. 무작위로 또는 사용자가 선택한다.
• tags, creator, character_version —— 갤러리와 출처를 위한 구조화된 메타데이터.
• system_prompt 과 post_history_instructions —— system 메시지와 jailbreak 류 후행 지시사항을 위한 명시적 슬롯. 옛날처럼 description 에 욱여넣는 관행을 대체한다.
• V1 에서 가져오되 의미를 정돈한 필드들: personality, scenario, mes_example, first_mes.
• extensions —— 어떤 호스트든 자신의 사적 설정을 둘 수 있는 자유 형식 오브젝트. V3 가 이후 확장의 발판으로 삼는 비상구이기도 하다.

호스트 측면에서, 2026 년 현재 V2 는 여전히 안전한 기본값이다. SillyTavern 은 정전으로 취급하고, Chub.ai 는 V2 를 저장·배포하며, RisuAI 도 대부분의 V2 영역을 지원한다(일부 필드는 자체 UI 관습으로 해석). 오늘 크로스 플랫폼 배포용으로 단 하나만 골라야 한다면 답은 여전히 V2 다.

V3 ( spec: "chara_card_v3" 로 식별)는 재작성이 아닌 다듬기로 이해하는 편이 옳다. V2 봉투 위에 소량의 새 기능을 얹고, 이전에는 흐릿했던 규칙을 단단히 조인다. 대부분의 크리에이터가 마주칠 새 표면:

• assets —— 표정, 대체 일러스트, 오디오 같은 추가 미디어를 카드와 함께 선언하는 방법. 호스트 고유의 사이드카 파일에 의존하지 않아도 된다.
• group_only_greetings —— 캐릭터가 그룹 채팅에 로드되었을 때만 등장하는 오프닝 라인. 1:1 에서는 나오지 않는다.
• nickname —— 정식 캐릭터명과 별개로 채팅 안에서 표시될 짧은 이름.
• creator_notes_multilingual —— 로케일을 키로 하는 작성자 노트 맵. 같은 카드에서 EN, JA, ZH 작성자 코멘트를 함께 제공할 수 있어 하나만 골라 나머지를 숨길 필요가 없다.
• source —— 파생 또는 리믹스 원본을 가리키는 명시적 출처 URL(또는 URL 배열).
• 스키마 전반의 타이핑이 살짝 엄격해짐 —— 배열은 배열, 선택은 명시, V2 의 string-or-array 모호함도 몇 군데 못 박혔다.

솔직히 말하면 V3 는 아직 자리를 잡는 중이다. 호스트마다 구현 부분 집합이 다르고, 스펙 자체도 공개적으로 계속 진화한다. V3 커버리지는 SillyTavern 이 앞서고, 다른 호스트는 부분 지원에 머무르며 인식 못 하는 키는 조용히 V2 의미로 후퇴한다. 그래서 어떤 키가 어떤 호스트에서 살아남는지 아는 linter 가 유용하다 —— 그리고 그 자리에 tavernai.cards 를 세우고 있다.

대부분의 V2 → V3 마이그레이션은 기계적이다: spec 올리고, 새 선택 키 추가하고, 내보낸다. 실패하는 지점은 예측 가능하다:

1. extensions 아래 커스텀 키. V2 에서는 어떤 호스트든 여기에 무엇이든 쓸 수 있다. V3 로 옮기면 일부 커스텀 키에는 일급 대응 필드(예: asset 참조)가 생기고, 나머지에는 없다. 단순 병합은 같은 데이터를 두 군데에 남기고, 호스트는 둘 중 어느 쪽을 우선할지 예측 불가능해진다.
2. 다국어 필드. creator_notes_multilingual 은 V3 추가다. 이를 모르는 호스트는 평이한 creator_notes 문자열로 후퇴한다. 다국어 맵만 채우고 평이 필드를 비우면 구 클라이언트에서는 아무것도 표시되지 않는다.
3. PNG tEXt 인코딩. 역사적 관습은 UTF-8 JSON 을 Base64 로 인코딩해 chara 키워드에 넣는 것이다. 의외로 많은 버그가 Base64 없이 원시 UTF-8 을 쓰거나, 임베드 전 비-ASCII 문자를 제거하는 도구에서 비롯된다. 한 호스트에서는 깔끔히 열리는 카드가 다른 호스트에서는 조용히 깨진다면 보통 여기가 원인이다.
4. 내장 vs 외부 lorebook. character_book 은 카드와 함께 이동한다 —— 휴대성에는 좋지만 공유 세계관에는 아프다. 카드 셋이 lorebook 을 공유하면서 인라인으로 유지하면 동기화할 사본이 셋이 된다. 결국 많은 팀이 정전인 외부 lorebook 과 폴백용 얇은 내장 사본을 함께 두는 쪽으로 정착한다.
5. assets 의 상대 경로. V3 의 asset 참조는 상대도 절대도 가능하지만, 스펙이 해석 기준을 완전히 못 박지는 않는다. 호스트마다 가정이 다르다. 카드가 여기저기 옮겨 다닌다면 절대 URL(또는 콘텐츠 해시)이 더 안전하다.

tavernai.cards 는 정확히 이 워크플로를 위해 만들어지고 있다: 로스터의 단일 진실 원본을 유지하고, V2 와 V3 스펙 모두에 대해 lint 하며, 각 호스트가 실제로 이해하는 형태로 내보낸다.

• Lint —— 공개 전 인사말 누락, 낡은 참조, 호스트 비호환 필드를 잡아낸다.
• 자동 마이그레이션 —— V1 에서 V2, V2 에서 V3 로. 블랙박스 덮어쓰기가 아닌 검토 가능한 diff 와 함께.
• 멀티 플랫폼 동기화 —— 같은 카드를 Chub, RisuAI, SillyTavern 각각의 방언으로 내보낸다.
• V2 / V3 양방향 내보내기 —— 같은 소스에서 V3 카드와 V2 호환 빌드를 동시에 만든다.