Character Runtime MVP
상세 개발 계획

1개발 원칙

1.1 설계 원칙

1.2 기술 결정 가이드

2모노레포 구조

character-platform/
├─ apps/
│  ├─ api/                    # Fastify — Character Runtime API
│  ├─ web-player/             # React+Vite — Live2D Player
│  ├─ mcp-server/             # MCP TS SDK — Gateway
│  ├─ admin-console/          # 관리자 콘솔
│  └─ worker/                 # BullMQ 비동기 Worker
├─ packages/
│  ├─ character-schema/       # JSON Schema + TS 타입
│  ├─ character-package/      # Package 로더/검증
│  ├─ llm-adapter/            # LLM Provider Adapter
│  ├─ tts-adapter/            # TTS Provider Adapter
│  ├─ memory-engine/          # 기억 검색/저장/갱신
│  ├─ action-engine/          # ActionPlan → Live2D 이벤트
│  ├─ db/                     # Drizzle 스키마 + 마이그레이션
│  └─ observability/          # 로깅/메트릭
├─ characters/
│  └─ luna-v1/                # MVP 캐릭터 패키지
├─ tests/
│  ├─ fixtures/               # 평가셋 (기억 30개, 동작 20개)
│  ├─ e2e/
│  ├─ contract/               # MCP 계약 테스트
│  └─ security/
└─ infra/

초기 세팅 태스크

3Phase 0 — 기술 검증 스파이크

전체 MVP를 만들기 전에 가장 위험한 8개 연결을 최소한으로 검증한다. 완성도 있는 코드가 아니라 연결이 가능한지만 확인하는 throwaway prototype이다.

스파이크 통합 시나리오

1. 브라우저에서 Live2D 모델 로딩 (SP-1)
2. 텍스트 입력 → API → LLM → TurnPlan (SP-2)
3. Validator가 TurnPlan 검증 (SP-3)
4. WebSocket으로 Player에 이벤트 전달 (SP-5)
5. Player가 Expression + Motion 실행 (SP-1)
6. TTS 오디오 재생 + 립싱크 (SP-4)
7. 대화 내용에서 기억 저장 (SP-6)
8. 새 세션에서 기억 재호출 (SP-6)
9. MCP Inspector에서 같은 호출 (SP-7)
10. 다른 사용자로 같은 질문 → 기억 격리 (SP-8)

Go 판정: 10단계 중 10단계 모두 성공해야 Phase 1 진행.

스파이크 산출물 (Phase 1으로 이관)

• LLM 프롬프트 초안 (TurnPlan 생성용)
• TurnPlan / ActionPlan JSON Schema v0.1
• Capability Manifest v0.1 (MVP 캐릭터)
• WebSocket 이벤트 프로토콜 초안
• pgvector 임베딩 모델 선정
• 립싱크 볼륨 매핑 파라미터 초안
• MCP Tool Schema 초안

4Phase 1 — MVP 본개발

모듈 개요

M1. 기반 인프라

M2. Character Package & Schema

M3. Live2D Web Player

M4. Character Runtime API

M5. 대화 Orchestrator

M6. Memory Engine

기억 검색 SQL

WITH scored AS (
  SELECT m.*, me.embedding,
    1 - (me.embedding <=> $1::vector) AS semantic_sim,
    1.0 / (1.0 + EXTRACT(EPOCH FROM (NOW() - m.created_at)) / 86400) AS recency,
    CASE WHEN m.type = 'pinned' THEN 1.0 ELSE 0.0 END AS pin_score
  FROM memories m
  JOIN memory_embeddings me ON me.memory_id = m.id
  WHERE m.character_instance_id = $2 AND m.status = 'active'
)
SELECT *,
  (semantic_sim * 0.45 + recency * 0.15 + importance * 0.20
   + confidence * 0.10 + pin_score * 0.10) AS total_score
FROM scored ORDER BY total_score DESC LIMIT $3;

M7. Action Engine & Validator

M8. TTS & Lip-sync

M9. Realtime Event Gateway

이벤트 타입

turn.started    │ text.delta       │ emotion.changed
expression.play │ motion.play      │ parameter.overlay
audio.ready     │ audio.sync       │ state.updated
turn.completed  │ turn.failed

M10. MCP Server

M11. Admin Console

M12. Observability

5모듈 의존관계 & 권장 구현 순서

M2 (Schema/Package) ───────────────────────────────────┐
    │                                                    │
    ├── M3 (Live2D Player) ◄── M9 (Realtime Gateway)    │
    │         │                      │                   │
    │         └──────── M8 (TTS/Lipsync) ◄──┐           │
    │                                        │           │
M1 (인프라/DB) ──┬── M4 (API) ──── M5 (Orchestrator)    │
                 │       │              │   │   │        │
                 │       │              │   │   └─ M7 (Action Engine) ◄─ M2
                 │       │              │   │
                 │       │              │   └── M6 (Memory Engine) ◄── M1
                 │       │              │
                 │       │              └── M8 (TTS Worker)
                 │       │
                 │       ├── M10 (MCP Server)
                 │       └── M11 (Admin Console)
                 │
                 └── M12 (Observability)

권장 구현 순서

6DB 상세 설계

RLS (Row Level Security) — 기억 누출 방지

ALTER TABLE memories ENABLE ROW LEVEL SECURITY;

CREATE POLICY memories_instance_isolation ON memories
  USING (character_instance_id = current_setting('app.current_instance_id')::text);

-- 애플리케이션에서 매 요청마다:
-- SET LOCAL app.current_instance_id = 'ci_abc123';

인덱스 전략

-- 기억 검색
CREATE INDEX idx_memories_active ON memories (character_instance_id, status)
  WHERE status = 'active';

-- 벡터 검색 (HNSW)
CREATE INDEX idx_memory_embeddings_hnsw ON memory_embeddings
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

-- 최근 대화
CREATE INDEX idx_messages_conv ON messages (conversation_id, created_at DESC);

-- 상태 이벤트
CREATE INDEX idx_state_events ON state_events (character_instance_id, created_at DESC);

-- 감사 로그
CREATE INDEX idx_audit ON audit_logs (character_instance_id, created_at DESC);

7API 계약 상세

POST /v1/characters/{instanceId}/turns

Request

{
  "conversation_id": "conv_...",
  "message": "오늘 기분 어때?",
  "player_session_id": "player_...",
  "locale": "ko-KR",
  "response_mode": "text_audio_action",
  "idempotency_key": "idem_..."
}

Response (200)

{
  "turn_id": "turn_...",
  "text": "오늘은 네가 와서 꽤 좋아졌어.",
  "emotion": { "primary": "joy", "intensity": 0.7 },
  "action_plan": {
    "expression": { "id": "happy", "weight": 0.85, "fade_ms": 250 },
    "base_motion": { "id": "greet", "priority": 60 },
    "overlays": []
  },
  "state_revision": 143,
  "audio_pending": true
}

response_mode 옵션: text_only | text_action | text_audio_action

8MCP Tool/Resource 계약

character.turn

{
  "name": "character.turn",
  "description": "캐릭터에게 대화 메시지를 보내고 응답을 받는다.",
  "inputSchema": {
    "type": "object",
    "required": ["character_instance_id", "message"],
    "properties": {
      "character_instance_id": { "type": "string" },
      "conversation_id": { "type": "string" },
      "message": { "type": "string", "maxLength": 4000 },
      "player_session_id": { "type": "string" },
      "locale": { "type": "string", "default": "ko-KR" },
      "response_mode": { "enum": ["text_only","text_action","text_audio_action"] }
    }
  }
}

character.search_memory

{
  "name": "character.search_memory",
  "description": "캐릭터 인스턴스의 기억을 검색한다.",
  "inputSchema": {
    "type": "object",
    "required": ["character_instance_id", "query"],
    "properties": {
      "character_instance_id": { "type": "string" },
      "query": { "type": "string" },
      "limit": { "type": "integer", "default": 5, "maximum": 20 },
      "type_filter": { "enum": ["all","user_preference","episodic","semantic"] }
    }
  }
}

MCP Resources

character://instances/{id}/profile
character://instances/{id}/state
character://instances/{id}/relationship
character://instances/{id}/capabilities
character://instances/{id}/memory/index
character://instances/{id}/memory/{memory_id}
character://instances/{id}/motion-library
character://templates/{template_id}/lore/{page}

Auth Scopes

character:profile:read    character:state:read
character:chat            character:memory:read
character:memory:write    character:animation:control
character:instance:export character:admin

9Character Package v0.1

MVP Expressions (8종)

MVP Motions (10종)

Semantic Controls

10테스트 계획

기억 평가셋 (30개)

자연어 동작 평가셋 (20개, 발췌)

테스트 디렉터리 구성

tests/
├─ unit/                 # 순수 로직
├─ integration/          # DB/Redis 포함
├─ contract/             # MCP 계약
├─ e2e/                  # 브라우저 E2E
├─ eval/                 # LLM 평가 (비결정적)
└─ security/             # 인젝션, 격리

11배포 전략

12Go/No-Go 체크리스트

Phase 0 → Phase 1

• Live2D Web SDK — 모델 로딩 + Expression + Motion
• LLM → TurnPlan structured output 성공률 90%+
• ActionPlan Validator — 범위 초과 차단
• TTS + 볼륨 립싱크 동작
• WebSocket 이벤트 송수신
• pgvector 기억 저장/검색
• MCP Inspector — character.turn 동작
• 사용자 간 기억 격리 0건 누출

MVP 완료

• 로그인 후 대화 가능
• TTS + 립싱크 정상
• 8 표정 + 10 모션 동작
• 자연어 동작 20개 중 16개+ 정확 (80%+)
• 브라우저 재접속 후 핵심 기억 유지
• Recall@5 ≥ 85%, 사실 회상 ≥ 90%
• 사용자 간 기억 누출 0건
• 기억 확인·삭제 가능
• MCP 동일 Instance 호출 성공
• ActionPlan 통과율 ≥ 99%
• 무효 파라미터 실행 0건
• p95 첫 텍스트 ≤ 3초, 첫 음성 ≤ 5초
• 이벤트 유실 < 1%
• 기억 삭제 반영 ≤ 1분
• 데모 시나리오 11단계 전체 통과

13선행 과제 (비기술)