딥시크 LLM을 뇌로, mineflayer를 몸으로. 실제로 걷고, 보고, 대화하고, 상황에 맞게 행동하는 실시간 AI 캐릭터 설계 문서.
Project Overview
마인크래프트 서버(포지/Forge)에서 사람처럼 행동하는 실시간 AI 캐릭터를 만든다. 강화학습 대신 경량 자기교정 루프로 행동을 점진적으로 개선한다.
가짜 플레이어로 접속하여 걷고, 점프하고, 바라보고, 블록과 상호작용한다.
플레이어 채팅에 맥락에 맞게 한국어로 반응한다.
딥시크 LLM이 상황을 판단해 대화+행동을 한 번에 결정한다.
성공/실패를 기억해 다음 행동을 더 똑똑하게 선택한다.
System Architecture
Forge 서버 모드가 아니라 별도 봇 클라이언트가 가짜 플레이어로 접속한다. 서버는 기존 포지/바닐라 서버 그대로 사용.
엔트리 · 봇 구동 + 루프 시작 + 종료 처리
deepseek.js (API 호출+파싱) · memory.js (자기교정 DB) · loop.js (판단 루프 심장)
mcBody.js (mineflayer 래퍼) · world.js (주변 상황 텍스트 요약)
Perceive → Decide → Act → Learn
매 사이클마다 4단계를 반복한다. 이게 봇의 "사람 같은 실시간 반응"의 핵심.
주변 플레이어·시간·좌표·채팅·체력을 수집해 "텍스트 상황 요약"으로 변환. (world.js)
[상황+대화+자기교정 힌트]를 딥시크에 전송 → JSON 응답 획득.
action을 게임 조작으로 변환. 이동·채팅·바라보기 실행. (mcBody)
행동 결과를 memory.js에 기록. 성공 가중치 ↑, 실패 ↓. 다음 결정에 반영.
// 딥시크가 매 사이클 반환하는 JSON { "speech": "안녕! 같이 놀래?", "action": "move_toward", "params": { "target": "player1" }, "thought": "플레이어가 가까이 와서 다가가 반기자" }
Action Catalog v1
딥시크가 고를 수 있는 9가지 행동. 각 행동은 지속시간 제한(timeout)이 있어 무한 루프를 방지한다.
가만히 있기
말만 하기
특정 플레이어에게 이동
특정 대상을 바라보기
대상을 피해 멀어지기
근처 랜덤 배회
주변 아이템 줍기
일정 거리 따라다니기
스폰 지점 복귀
DeepSeek Integration
대화 모드 — 플레이어가 채팅하면 자연스러운 답변+행동.
자율 행동 모드 — 아무도 안 말 걸면 스스로 상황 보고 행동 결정(배회·관찰).
두 경우 모두
{
"model": "deepseek-v4-flash",
"messages": [
{ "role": "system", "content": "너는 마인크래프트 서버에 사는 AI 캐릭터다... 반드시 JSON만 출력한다." },
{ "role": "user", "content": "상황: 밤, 플레이어 '철수'가 20블록 앞에 있음\n철수: \"같이 놀자\"" }
],
"temperature": 0.8
}
Self-Correction · 강화학습 대체
진짜 강화학습은 GPU 학습 팜이 필요해 비현실적. 대신 경량 자기교정(기억 강화)으로 대체한다. 같은 상황이 오면 이전에 잘 통했던 행동을 우선 선택.
// 성공: +0.1 (최대 1.0) / 실패: -0.2 (최소 0.0) action: "move_toward" // 야간+플레이어 근접 상황 success ×12 → confidence 0.92 ✅ fail ×3 → confidence 0.32 ⚠️
오래된 메모리는 confidence를 절반으로 감쇠시켜, 옛날 지식이 불필요하게 우세해지는 걸 막는다.
신뢰 기준: input_count ≥ 3 && confidence ≥ 0.6 → 이때만 메모리가 결정을 주도.
function decide(): if requested : return act(requested) if danger : return act('avoid') hit = bestMemory(context_key()) // confidence 최고치 + input_count≥3 if hit : return act(hit.action) else : return act(deepseekDecide()) // 탐험 function feedback(result): row = find(action, context_key()) row.confidence += (result.success ? +0.1 : -0.2) row.input_count += 1 decayOlderMemories() // 오래된 기억 confidence 절반화
SQLite Schema
자기교정 메모리. action + context_key + confidence + input_count
대화 컨텍스트. 봇과 플레이어 간 대화 보존
행동 실행 로그. 디버깅/통계용
CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, action TEXT NOT NULL, context_key TEXT NOT NULL, outcome TEXT NOT NULL, confidence REAL NOT NULL DEFAULT 0.5, input_count INTEGER NOT NULL DEFAULT 0, note TEXT, updated_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_mem_context ON memories(context_key);
.env Configuration
| 키 | 기본값 | 설명 |
|---|---|---|
| MC_HOST | 서버 주소 | |
| MC_PORT | 25565 | 서버 포트 |
| MC_USERNAME | 봇 닉네임 | |
| MC_AUTH | offline | offline | microsoft |
| DEEPSEEK_API_KEY | 딥시크 키 | |
| DEEPSEEK_MODEL | deepseek-v4-flash | 모델 |
| DEEPSEEK_BASE_URL | https://api.deepseek.com | 엔드포인트 |
| AI_TEMPERATURE | 0.8 | 창의성 |
| LOOP_INTERVAL_MS | 5000 | 판단 사이클 주기 |
| ACTION_TIMEOUT_MS | 30000 | 행동 최대 실행시간 |
| HUMAN_DELAY_MS | 600 | 사람 같은 딜레이 |
| DB_PATH | ./data/brain.db | SQLite 경로 |
| DB_BACKUP | 1 | 시작 시 백업 여부 |
| AUTO_RECONNECT | true | 연결 끊김 재시도 |
| MAX_DIALOG_HISTORY | 20 | 대화 최대 보존 개수 |
| BOT_FAMILIARITY | true | 봇 이름 부를 때만 응답할지 |
Error Recovery
| 오류 시나리오 | 처리 전략 |
|---|---|
| 딥시크 API 실패/타임아웃 | 재시도 3회(지수백오프) → 실패 시 기본 배회/idle 후 다음 사이클 |
| JSON 파싱 실패 | 응답에서 |
| action 미지원 | 로그 기록 후 idle 처리 |
| pathfinder 목적지 도달 실패 | 타임아웃 후 실패 피드백 |
| 서버 연결 끊김 | 대기 후 재연결(AUTO_RECONNECT), 연속 실패 시 종료 |
| 채팅 256자 초과 | 잘라서 분할 전송 또는 말 줄임 |
| 기타 예외 | 전역 try/catch → 이벤트 로그 + 안전한 idle |
Implementation Roadmap
아키텍처·프로토콜·자기교정 알고리즘·스키마 확정
의존성, 설정 로드, .env.example
딥시크 호출/JSON 파싱/재시도/fallback
SQLite 3개 테이블 + 자기교정 로직 + 단위테스트
mineflayer 접속/이동/채팅/인식
상황 요약 텍스트 생성
관찰→결정→행동→피드백 통합 루프
엔트리, 부팅 순서, 종료 처리
오프라인 서버로 접속·채팅·이동 검증