> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 동반자 시스템

> 15종, 감성인식, 성장진행을 갖춘 게임화된 AI 동반자.

# AI 동반자 시스템

동반자 시스템은 에이전트를 개성, 감성 인식 및 게임화된 성장 시스템을 갖춘 가상 동반자로 변화시킵니다.

## 특징

<CardGroup cols={2}>
  <Card title="15종 + 모자 9개" icon="paw">
    15종의 반려종과 9종의 모자 중에서 선택하세요. 각 종은 희귀도 기반 발광 효과를 갖춘 맞춤형 SVG 아이콘으로 렌더링됩니다.
  </Card>

  <Card title="에이전트 외모 동기화" icon="shuffle">
    동반자는 에이전트를 전환할 때 자동으로 종과 모자를 변경합니다. 개발자는 로봇, 연구원은 올빼미, 작가는 여우입니다. 이모티콘 아바타가 포함된 맞춤형 에이전트가 자동으로 매핑됩니다.
  </Card>

  <Card title="Hermes 7-State Petdex 엔진" icon="wand-magic-sparkles">
    스프라이트 오버레이는 **7개의 Petdex 정렬 상태**(유휴/실행/검토/점프/웨이브/실패/**대기**)를 사용합니다. HITL 차단된 신호(승인, 명확화, 데스크톱/브라우저 인계)는 **대기**를 유도합니다. 거짓 물결이 아닙니다. SSE 워크플로 이벤트는 하트비트 자동 복구와 함께 임시/고정/릴리스 모드를 사용합니다.
  </Card>

  <Card title="데스크탑 애완동물 오버레이" icon="desktop">
    Tauri 데스크탑에서 스프라이트는 기본적으로 **기본 창에 내장**되어 렌더링됩니다. **데스크톱 팝업**(컨텍스트 메뉴) 또는 **Shift+클릭**을 사용하여 앱이 최소화된 동안 계속 표시되는 투명한 항상 상단 퍼펫 창(`/pet-overlay`)을 엽니다. 튀어나온 애완동물은 드래그, 상태 말풍선, 미니 작성기(한 번 클릭), 두 번 클릭하여 기본 창 전환, Shift+클릭하여 다시 팝업, 알파 클릭 연결 및 자리를 비운 동안 차례가 완료되면 메일 아이콘을 지원합니다. WebUI/SaaS에서 스프라이트는 페이지 내 드래그 가능한 오버레이로 렌더링됩니다(OS 팝아웃 없음).
  </Card>

  <Card title="성장과 진화" icon="arrow-up">
    능력치 진화, XP 진행, 일일 간식 상호 작용 및 생일 감지 기능을 갖춘 5단계 희귀도 시스템(일반 → 전설).
  </Card>

  <Card title="HITL UX 대기 중" icon="shield-heart">
    상담원이 귀하의 승인이나 설명을 필요로 할 때 데스크톱 애완동물은 **대기** 애니메이션(Hermes 정렬)을 표시합니다. 일상적인 오류는 조난 루프가 아닌 간단한 검토/실패한 일시적인 오류를 사용합니다.
  </Card>

  <Card title="커뮤니티 Petdex 갤러리" icon="store">
    Canvas 썸네일, 지연 로딩, 검색 및 원클릭 설치 기능이 포함된 내장 갤러리를 통해 petdex.dev에서 수백 개의 커뮤니티 생성 SpriteSheet를 찾아보고 설치하세요. 수동 URL 입력이 필요하지 않습니다.
  </Card>

  <Card title="동적 스프라이트 호환성" icon="puzzle-piece">
    `resolvePetSheetRow()` 엔진은 별칭 기반 매핑을 사용하여 Codex 9행, 레거시 8행 및 사용자 정의 스프라이트 시트 형식을 자동으로 조정합니다. 모든 커뮤니티 스프라이트는 수동 구성 없이 "그냥 작동"합니다.
  </Card>

  <Card title="장치 간 구성 동기화" icon="cloud">
    선택한 스프라이트를 포함한 컴패니언 기본 설정은 `/companion/config` API을 통해 서버 측에 유지됩니다. 개인화를 유지하면서 장치나 브라우저를 전환하세요.
  </Card>

  <Card title="세션 /pet 명령" icon="terminal">
    애완동물 팔레트를 즉시 열려면 채팅에 `/pet`을 입력하세요. 제출 차단은 **제로 LLM 토큰**을 사용하여 로컬에서 슬래시를 처리합니다. 에이전트 왕복이 필요하지 않습니다.
  </Card>

  <Card title="설치된 애완동물 관리" icon="trash">
    설치된 펫은 갤러리 위에 칩으로 나타납니다. 확인을 통해 칩 메뉴를 사용하여 애완동물을 제거하세요. 활성 스프라이트를 제거하면 선택 항목이 지워지고 서버 구성이 자동으로 동기화됩니다.
  </Card>

  <Card title="오프라인 페일오픈" icon="wifi-slash">
    petdex.dev 카탈로그를 사용할 수 없을 때 이미 설치된 애완동물은 계속 사용할 수 있습니다. 매니페스트 복구를 기다리지 않고 스프라이트를 전환합니다.
  </Card>

  <Card title="Atlas 품질 사전 확인" icon="magnifying-glass">
    설치 시 스프라이트 시트는 Codex 8×9 및 Legacy 8×8 그리드에 대해 검증됩니다. 잘못된 치수는 설치 전에 거부되어 깨지거나 픽셀화된 스프라이트가 컬렉션에 들어가는 것을 방지합니다.
  </Card>

  <Card title="GUI 건강검진 의사" icon="stethoscope">
    기능 게이트, 구성, 디스크 존재, 아틀라스 형식, SHA 무결성 및 로컬 제공 등 6가지 검사를 포괄하는 원클릭 진단입니다. 결과는 이중 언어(EN/ZH)로 제공되며 갤러리에서 액세스할 수 있거나 스프라이트 로드에 실패하면 자동으로 트리거됩니다.
  </Card>

  <Card title="제로 구성 테마 동기화" icon="palette">
    동반 강조 색상(희귀성 글로우, 링 섀도우, 상태 풍선 테두리)은 CSS 변수 토큰 파생을 통해 작업공간 테마 프로필을 자동으로 따릅니다. 모양 설정에서 테마를 변경하세요. 컴패니언은 즉시 업데이트되며 별도의 구성이 필요하지 않습니다. Tauri 팝아웃 오버레이(`/pet-overlay`)는 가벼운 상태를 유지합니다. 창 간 악센트 토큰을 계속 동기화하는 동안 배경화면/ArtLayer 로드를 건너뜁니다.
  </Card>
</CardGroup>

## 구성

1. **설정 > 컴패니언**으로 이동합니다. 컴패니언 시스템은 기본적으로 활성화되어 있습니다.
2. 15+9가지 옵션 중 종족과 모자를 선택하세요
3. **갤러리** 탭으로 전환하여 petdex.dev에서 커뮤니티 SpriteSheets를 찾아보세요. 한 번의 클릭으로 검색, 미리보기 및 설치가 가능합니다.
4. 칩 행에서 설치된 애완동물을 관리합니다. 활성 스프라이트를 전환하거나 확인 후 제거합니다.
5. LLM 토큰을 소모하지 않고 애완동물 팔레트를 열려면 언제든지 채팅에 `/pet`을 입력하세요.
6. 선택한 스프라이트와 구성은 API 서버를 통해 여러 기기에 자동으로 동기화됩니다.
7. 컴패니언은 활성 에이전트의 아바타와 자동으로 동기화됩니다.

## 작동 방식

컴패니언 시스템은 두 가지 시각적 계층에서 작동합니다.

* **SVG 레이어**(기본값): 채팅 입력 근처에 포함된 경량 아이콘 기반 렌더링입니다. 종과 모자 변경을 통해 활성 물질의 정체성을 자동으로 반영합니다.
* **스프라이트 레이어**(선택 사항): Codex 8×9 표준 SpriteSheets(1536×1872px)를 지원하는 전체 캔버스 2D 애니메이션 엔진. 데스크톱 Tauri에서는 기본 창이나 튀어나온 투명 OS 창에 내장된 렌더링이 제공됩니다(PSUA — 기본 창은 상태를 소유하고 이벤트를 통해 꼭두각시 미러링). WebUI에서는 드래그 가능한 인페이지 오버레이로 렌더링됩니다. `resolvePetSheetRow()`은 Codex(9행)와 레거시(8행) 레이아웃을 자동으로 감지하고 **7가지 Petdex 상태**(Hermes 정렬)(유휴, 실행, 검토, 점프, 웨이브, 실패 및 **대기**)를 매핑합니다. 상태 말풍선은 **팝아웃된 데스크톱 창에만** 나타납니다.

스프라이트 상태 시스템은 SSE 워크플로 이벤트를 GUI 사용자 차단 신호와 결합합니다.

* **워크플로 SSE**(`stepKeyToPetEvent` 경유): 계획 → 검토(고정), 실행 → 실행(고정), 실패 → 실패(일시적), 마일스톤 → 점프/검토(일시적)
* **HITL 차단됨**(승인/명확화/데스크톱/브라우저 스토어의 `deriveBlockedOnUser`을 통해): **대기** — 조치를 취해야 하는 동안 실행/웨이브를 재정의합니다. Codex 행 6에 매핑됩니다(레거시 시트는 유휴 상태로 돌아갑니다).
* **스트림 활성**: 사용 중 → 검토; 턴 종료 → 웨이브(막혀있지 않은 경우)

모든 상태는 localStorage 지속성을 갖춘 Zustand를 통해 관리됩니다. 컴패니언 기본 설정은 `/companion/config` API을 통해 서버에 동기화됩니다.

## 검증된 품질

컴패니언 시스템은 **291개의 테스트를 모두 통과했습니다**(2026-08-02 인증)를 통해 지원됩니다.

* **백엔드 pytest: 57/57 통과** — pet\_store (7) + 컴패니언 API (10) + 기능 게이트 (23) + 컴패니언 구성 (17)
* **프런트엔드 vitest: 234/234 통과** — 동반 서비스(28: petInstall/petSpritesheet/formatLabel/doctorI18n/slashCommand/companionTheme) + 구성 요소(147: 갤러리/Sprite/Icons/snack/generator/manifest/assets) + 스프라이트(65: 엔진/StateMachine/stateMapping/surfaceBridge/statusBubble/blockedOnUser/awayCompletion)

주요 적용 범위:

* PetStateMachine: **100%** 라인 적용 범위
* CompanionSprite: **91.83%** 라인 커버리지
* petSurfaceBridge: **100%** 라인 커버리지
  -companionGenerator: **99.13%** 라인 커버리지
* Atlas 품질 사전 확인: Codex/Legacy/비표준/무효 모두 검증됨
* GUI 의사: 이중 언어 i18n이 포함된 6개 항목 진단 체인

**#12 컴패니언 ← 테마 프로필 SSOT** (2026-08-02):

* 게이트 스크립트 `scripts/dev/e2e-companion-theme-ssot-gate.sh`: **15/15 vitest** (companionTheme에는 인라인 스타일 변형 + 마케팅 경로 + ThemeProfileProvider pet-overlay가 포함됨)
* Chrome MCP 연기: `/settings/preferences` 테마 견본 + 컴패니언 설정「작업 공간 테마 따르기」읽기 전용 링크
* 선택 사항: `COMPANION_THEME_SSOT_CHROME=1`는 라이브 스택에 대해 pytest chrome\_e2e를 실행합니다.
* 정직한 경계: 캔버스 스프라이트 픽셀에는 테마 색조가 적용되지 않습니다(악센트 UI만 해당).