EJClaw 8782df2111 v1.10.0 릴리스 기록 · README 링크
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:07:00 +09:00
2026-11-20 22:40:45 +09:00

겜녹이 (Game Voice Recorder, GVR)

디스코드 음성채널에 봇이 들어가 참가자 각자의 목소리를 따로 녹음하고, 게임 PC의 NVIDIA GPU로 한국어 텍스트(STT)로 바꾼 뒤, 발로란트·리그 오브 레전드 경기 데이터(킬·라운드·오브젝트·인게임 채팅)와 같은 타임라인에 묶어 https://gvr.tkrmagid.kr 에서 보고 듣는 프로그램입니다.

  • 게임 PC: 포터블 GameVoiceRecorder.exe 하나로 디스코드 봇, STT 엔진, 기록 저장소, 설정 화면이 돈다
  • 사이트 서버: 디스코드 로그인(서버 멤버만), 게임 PC 연결 확인·잠금 화면, 기록 중계 (기록은 게임 PC 에만 있음)
  • 설계·계획: docs/gemnoki-project-plan.pdf, 개발 구조·인터페이스: docs/dev/ARCHITECTURE.md
  • 범인찾기 · 리플레이 동기화 계획서 v1.2 (결정 반영): docs/culprit-finder-plan.pdf · 원본 · 비용 계산 · 프롬프트 초안: docs/report/culprit/ (실제로 쓰는 프롬프트는 site/server/prompt/)
  • 제작 완료 보고서 (M0~M8): docs/gemnoki-final-report.pdf · 단계별 테스트 기록: docs/dev/test-results.md
  • Windows 실행 파일: Gitea 릴리스 v1.10.0 (GameVoiceRecorder-1.10.0-win-x64.zip 권장, 단일 파일 GameVoiceRecorder-1.10.0-portable.exe) · 바뀐 점 보고서 docs/gemnoki-v1.3.7-report.pdf · 처음 버전 v1.0.0

로그인 · 관리자 (v1.2.0~)

  • exe 는 등록된 디스코드 계정으로 로그인해야 열린다. 로그인 버튼 → 브라우저에서 디스코드 로그인 → 사이트 서버(gvr.tkrmagid.kr)가 등록 명단을 확인한다. 등록되지 않은 아이디면 "등록되지 않은 아이디입니다"와 디스코드 아이디를 보여 주고 앱을 열지 않는다.
  • 역할: 최고 관리자(293719842274541579, 1352267557213573160, 서버에 고정) · 관리자 · 유저. 유저 등록 · 역할 변경 · 등록 해제는 최고 관리자만, 등록 명단 보기와 관리자 전용 설정은 관리자도 할 수 있다.
  • 설정 창 🛡️ 관리자 탭(관리자에게만 보임): 유저 등록(디스코드 아이디 + 역할), 등록 계정 목록(역할 · 마지막 접속 · 앱 버전 · 등록한 사람), 관리자 전용 기능 목록.
  • 관리자 전용 (일반 유저 화면에서는 🔒 잠김, 메인 프로세스에서도 막음): 다른 봇으로 바꾸기 · 봇 토큰, 녹음 안내(TTS) 끄기 · 문구, 음성 보관 기간, 사이트 서버 주소 · PC 이름 · 등록/해제, 학습 데이터 삭제, 파인튜닝.
  • 앱은 시작할 때와 10분마다 등록 여부를 다시 확인한다. 등록이 해제되면 바로 잠그고 봇 · 녹음 · 사이트 연결을 멈춘다. 사이트 서버에 못 붙으면 마지막 확인 뒤 3일까지는 그대로 쓴다.
  • 서버 쪽: site/server/src/app-auth.ts (/auth/app/*, /app/me, /app/admin/users), 앱 쪽: app/src/core/auth.ts, 권한 목록: app/src/core/roles.ts. 로그인 E2E: app/scripts/login-e2e.mts.

v1.6.0 바뀐 점

  • 내 정보 (사이트 오른쪽 위 내 이름 누르기, site/web/src/components/UserEdit.tsx): 표시 이름 바꾸기 · 되돌리기(디스코드 서버 별명으로), 내 색, 라이엇 ID, 녹음 제외, 내 기록 보기 · 관리 페이지 · 로그아웃
    • 표시 이름은 사이트 서버에 저장하고(PUT /site/profile/name, 1~32자 · 보이지 않는 글자 금지 · 다른 사람 표시 이름과 겹치면 거절 · 10분에 10번) 게임 PC 앱에 바로 보낸다(PUT /api/internal/names, 예전 앱은 10분마다 받아 감)
    • 색 · 라이엇 ID · 녹음 제외는 게임 PC 앱 기록에 저장 (PATCH /api/users/:id, 본인 또는 관리자. 다른 사람에게 연결된 라이엇 ID 는 본인이 가져갈 수 없음)
  • 관리 페이지 /admin (관리자 · 최고 관리자, site/web/src/pages/AdminPage.tsx): 게임 PC 연결 · 앱 버전 · 새 버전 안내(Gitea 최신 릴리스), 녹음된 사람 + 앱 등록 유저 목록에서 표시 이름 · 색 · 라이엇 ID · 녹음 제외 바꾸기, 앱 등록 · 역할 · 해제(최고 관리자). 서버 /site/admin/* 는 앱 관리자 탭 /app/admin/* 와 같은 코드 (site/server/src/app-auth.ts). 표시 이름은 사이트에서는 관리자도 바꿀 수 있다

v1.5.0 바뀐 점

  • 3D 리플레이: 발로란트 경력 탭에서 경기 리플레이를 내려받아 두면, 사이트 경기 화면 "3D 리플레이"를 열 때 게임 PC 앱이 %LOCALAPPDATA%\VALORANT\Saved 아래 <경기 ID>.vrf 를 찾아 변환해 보낸다 (처음 한 번 10초 안팎, 그 뒤로는 GVR-Data/replays/<경기 ID>.json.gz 보관본). 선수 10명이 3D 맵 위에서 움직이고 그때 대화가 같이 재생된다
    • 변환기 resources/replay/gvr-replay.exe (tools/replay-extract, .NET 단일 파일). 한 번에 하나 · 낮은 우선순위로 돌린다. 실패하면 이유를 사이트에 보여 주고, 같은 파일은 다시 내려받을 때까지 다시 하지 않는다
    • 앱 app/src/core/replays.ts, API GET /api/matches/:id/replay (gzip JSON, 변환 중 202) · GET /api/replays (찾은 리플레이 목록)

v1.4.3 바뀐 점

  • 상대 닉네임을 말로 적던 문제 (예: 말소리가 "QQQWWWQ"로 나옴): 그 경기 선수 이름을 모두 핫워드로 넣어서, 말을 못 알아들으면 Whisper 가 닉네임을 그대로 적었다. 이제
    • 선수 이름은 한글이 들어간 것만 핫워드로 넣는다 (영문 · 숫자 닉네임은 한국어 말로 나올 일이 거의 없음)
    • 결과가 선수 이름(또는 그 조각)뿐이면 워커가 선수 이름을 빼고 한 번 더 변환한다 (worker/gvr_worker/stt.py is_name_echo, 앱이 player_names 로 넘김)
    • 한 번만: 예전에 이렇게 적힌 발화를 정밀 모델로 다시 변환한다 (음성 파일이 지워졌으면 숨김, 사람이 고친 발화는 그대로). app/src/core/stt/pipeline.ts recheckNameEchoes

v1.4.2 바뀐 점

  • 녹음 중에 음성채널에 들어온 사람이 사이트에서 "알 수 없음"으로 뜨던 문제: 앱이 그 사람을 유저로 저장만 하고 users.updated 를 보내지 않았다. 이제 들어올 때 보낸다 (app/src/core/discord/bot.ts onVoiceState)
  • 사이트도 실시간 발화 · 녹음 상태에 처음 보는 사람 아이디가 오면 유저 목록을 한 번 다시 받아 온다 (v1.4.1 이하 앱에서도 이름이 뜸)

v1.4.1 바뀐 점

  • 잡음으로 배운 문장 비교: v1.4.0 은 편집 거리로 비교해서, 배운 문장 뒤에 짧은 실제 말("네", "가자", "아니")이 붙은 발화까지 잡음으로 지웠다. 이제 글자 수가 같고 15% 안 글자만 바뀐 것(인식이 한두 글자 다르게 나온 것)만 같은 문장으로 본다

v1.4.0 바뀐 점

  • 사이트 발화 우클릭 → 삭제…: 확인 창에서 "잡음이라 삭제" 또는 "그냥 삭제". 관리자나 말한 사람만 지울 수 있고, 글 · 음성 파일 · 교정 학습 데이터를 게임 PC 에서 지운다 (POST /api/utterances/:id/delete)
  • "잡음이라 삭제"는 인식된 문장을 noise_phrases 에 배운다. 다음에 같은 문장(띄어쓰기 · 문장부호 무시, 8글자 이상이면 글자 수가 같고 15% 안 글자만 바뀐 것까지. 앞뒤에 말이 붙으면 그대로)이 인식되면 잡음(noise_reason='learned')으로 숨기고 파일을 지운다. 배운 문장은 단어사전 화면에서 보고 지운다 (GET/DELETE /api/noise-phrases)
  • 사이트 효과음: "새 발화 알림" · "재생 시작"을 기본으로 끈다 (예전에 저장한 설정도 한 번 꺼 줌, 그 뒤 다시 켜면 그대로)

v1.3.9 바뀐 점

  • 기록 zip 받아오기: 표시 이름에 .. 이 있으면(예: 하늘..별) 그 이름이 들어간 녹음 파일을 "음성 파일 이름이 잘못되었습니다"로 거절해, 내보낸 zip 을 다시 넣지 못했다. zip 안 이름은 꺼낼 때 찾는 열쇠로만 쓰고 이 PC 에 쓸 경로는 발화 ID 로 만들므로, 폴더 구분자(/, \)만 막는다

v1.3.8 바뀐 점

  • 녹음 파일 이름: 날짜_시각_말한사람_게임_모드_맵_라운드_발화ID.ogg (예: 2026-10-16_04-03-16_사금향_발로란트_경쟁전_어센트_R7_0mv9….ogg, 롤은 라운드 대신 게임 시간 12분30초, 경기 밖은 …_사금향_경기밖_….ogg). 시각은 게임 PC 시각, Windows 에서 못 쓰는 글자는 뺀다. app/src/core/audio-names.ts
    • 녹음이 끝나면 바로 이 이름으로 저장하고(경기 중에는 지금 라운드), 경기가 끝나 경기 상세(정확한 라운드)가 오거나 표시 이름이 바뀌면 다시 맞춘다. 예전 파일도 처음 켤 때 바꾼다
    • 음성 인식이 그 파일을 읽는 중이거나 대기열에 있으면 바꾸지 않고, 변환이 끝난 뒤 바꾼다. 다른 프로그램이 파일을 열고 있으면 다음에 다시 한다
    • 기록 zip 안 audio/ 도 같은 이름, 사이트 ogg 다운로드 · 자세한 정보도 같은 이름 (v1.3.7 zip 의 audio/<발화ID>.ogg 도 그대로 받는다)

v1.3.7 바뀐 점

  • 기록 관리 (사이트 "기록" 탭, site/web/src/pages/RecordsPage.tsx): 기록을 경기 하나 = 묶음 하나로 보고, 경기 밖 대화는 녹음 세션 안에서 경기 사이마다 묶는다. 다음 경기가 30분 안에 시작하면 "경기 전 대화", 지난 경기가 30분 안에 끝났으면 "경기 후 대화", 아니면 "게임 밖 대화". 묶음을 골라 한 번에 zip 내려받기 · 지우기(관리자) · zip 받아오기(관리자). 앱 app/src/core/bundles.ts, API GET /api/bundles · GET /api/bundles/export?ids= · POST /api/bundles/delete · POST /api/bundles/import
  • zip 형식 gvr-bundle v1: manifest.json(형식 · 묶음 · 개수), data.json(유저 · 세션 · 경기 · 라운드 · 이벤트 · 범인 분석 · 발화), audio/<발화ID>.ogg, 대화.txt. 받아오기는 형식 · 버전 · 발화 ID · 말한 사람 · 시각 · 경기 연결 · 음성 파일(ogg 머리) · 개수를 모두 확인하고 하나라도 빠지면 아무것도 넣지 않고 "받아오기 실패: (이유)"로 끝낸다. 이미 있는 발화는 건너뛴다. 받아온 녹음의 보관 기간은 받아온 날부터 센다 (utterance_imports)
  • 사이트 ↔ 게임 PC 중계: 큰 zip 을 1MB 조각으로 주고받는다 (사이트 서버 → 앱 요청 본문, 앱 → 사이트 서버 응답 모두)

v1.3.6 바뀐 점

  • 목소리 깨짐: 녹음기가 디스코드 패킷이 "도착한 간격"으로 말 사이 쉼을 채웠다. 게임 중(CPU 부하)에는 패킷이 2~3개씩 몰려 와서 말 중간에 20ms 무음이 계속 끼었다 (사용자 파일: 실제 7.0초 발화가 8.5초, 패킷 3개 중 1개가 무음). 이제 RTP 타임스탬프로 패킷 자리를 정한다 (recorder.ts tapRtp · Utterance.place). 예전 녹음은 처음 켤 때 한 번 끼운 무음을 빼고 다시 변환한다 (ogg.ts removeInsertedSilence)
  • 말한 사람 "알 수 없음": 앱이 users.updated 를 빈 목록으로 보내 사이트가 유저 목록을 비웠다. 이제 실제 목록을 보낸다 (사이트도 빈 목록이면 다시 받아 옴)
  • 잡음: 목소리 없음 · 잡음에서 지어낸 문장 · 같은 말 반복은 사이트에 보이지 않고 ogg 도 지운다 (경기 중 실시간 판정은 경기 뒤 정밀 모델이 다시 본 다음). 로그에 "잡음 발화 … 숨김 · 음성 파일 삭제 (이유, 인식 문장)" 로 남는다. 목소리가 0.15초라도 있으면 Whisper 로 넘기고, 반복 고리는 한 번으로 줄여 남은 말을 보여 준다
  • 시작 창: 포터블 exe 를 푸는 동안 작은 그림 창(assets/app/splash.bmp), 앱이 켜지는 동안 "켜는 중" 창
  • 녹음 안내 말 속도 0.12.0 (Edge TTS 는 0.52.0, 그보다 느리면 워커 tempo 가 atempo 로 늘림)
  • 사이트: 재생 음량 0~200% · 발화 우클릭(재생 · 자세한 정보(원본 ogg 이름 · 게임 PC 경로 · 크기 · 인식 정보) · ogg 다운로드 · 내용 복사, 앱 GET /api/utterances/:id/info)
  • 사이트 로그: 사이트 서버가 data/logs/site-날짜.log 로 남긴다 (게임 PC 연결 · 끊김 · 기록 요청 결과 · 봇 중계 · 범인찾기 · 브라우저 오류). 관리자는 https://gvr.tkrmagid.kr/logs 에서 게임 PC 가 꺼져 있어도 보고 내려받는다 (잠금 화면 · 설정 메뉴에 링크). 14일 보관
  • 지금 게임: 앱 게임 연동 탭 · 사이트(머리글 · 타임라인 오른쪽)에 연결된 게임 · 상태(메뉴 · 대기열 · 요원/챔피언 선택 · 경기 중) · 모드 · 맵 · 라운드 · 점수 · 내 요원/챔피언 · KDA · 게임 시간
  • 발로란트 데스매치 · 팀 데스매치 · 에스컬레이션: 킬 점수를 라운드로 착각해 "R63 승리" 같은 가짜 라운드와 에이스를 만들던 것 고침. 경기 상세에 선수 이름이 비어 오면 이름 서비스로 채운다 ("주인 계정 자동 연결: #" 고침)

v1.3.5 바뀐 점

  • 표시 이름 빈틈: 표시 이름을 정하기 전에 시작한 범인 분석이 정한 뒤에 저장되면 결과 본문에 예전 이름이 남을 수 있었다 (이미 이름이 바뀐 유저는 다시 훑지 않았음). 이제 가린 예전 이름을 기억해 두고(meta.hidden_names), 분석을 저장할 때마다 · 이름을 다시 받을 때마다 모든 분석에서 바꾼다
  • 상태 메시지 실제 확인: site/server/scripts/presence-e2e.mts (사이트 서버 코드로 봇을 빈 음성채널에 넣었다 빼며 확인)

v1.3.4 바뀐 점

  • 슬래시 명령 응답: 그 디스코드 서버를 지켜보는 겜녹이 앱이 없으면 사이트 서버가 명령을 무시해서 디스코드에 "애플리케이션이 응답하지 않았어요"만 떴다 (봇 토큰을 직접 쓰는 옛 v1.1.0 PC 와 겹치지 않게 넣은 동작). 이제 1.5초 기다렸다가 아무도 받지 않았으면 이유를 답한다: 앱이 꺼져 있음 / 내 앱이 다른 서버를 녹음 대상으로 정해 둠 / 아직 연결 중. 앱은 서버가 권한을 다시 확인하다 지켜보기를 끊으면 1분 뒤 다시 요청한다
  • 봇 상태 메시지: 녹음 중(봇이 어느 서버에서든 음성채널에 있음)이면 빨간 상태(다른 용무 중) + "🔴 녹음 중", 아니면 "🎙️ 대기 중 · /녹음시작". 겜녹이 봇은 사이트 서버가, 다른 봇 모드는 앱이 바꾼다. 봇 하나가 여러 서버에 들어가 있어서 채널 이름은 넣지 않는다

v1.3.3 바뀐 점

  • 따라갈 사람 목록: 녹음할 서버의 멤버가 모두 나온다. 내 계정이 맨 위, 그다음 관리자(최고 관리자 포함), 나머지는 이름순. 예전에는 봇이 서버를 지켜보기 전에 목록을 요청하면 사이트 서버가 거절했고 앱이 그 오류를 숨겨 "선택 안 함"만 보였다. 이제 가입한 서버면 바로 받고, 실패하면 오류와 다시 불러오기 버튼을 보여 준다. 녹음할 서버를 바꾸면 봇이 새 서버를 바로 지켜본다. 서버: GET /app/admins
  • 롤 채팅은 API 로만: 화면 글자 인식(OCR)을 앱 · 워커 · 빌드에서 모두 뺐다 (pywinrt · mss · Pillow 의존성 제거). 롤 클라이언트(LCU) API 로 챔피언 선택 · 게임 후 채팅을 받는다. 롤은 게임 중 전체 · 팀 채팅을 주는 API 가 없다 (LCU · 게임 클라이언트 API 모두, 비공식 포함). 게임 로그 파일(r3dlog)에 채팅이 남아 있으면 경기 뒤에 붙인다
  • 표시 이름 (실명 숨기기): 디스코드 아이디마다 보일 이름을 정하면 사이트(로그인 이름 · 대화 기록 · 유저 목록), 앱, 범인 분석에 그 이름만 쓰고 이미 저장된 이름도 바꾼다. 앱 🛡️ 관리자 탭에서 최고 관리자가 정한다. 서버: GET /app/names, PUT /app/admin/names, node dist/cli.js name <아이디> [이름]
  • 저장소의 시연 · 테스트 데이터, 화면 캡처, 계획서 PDF 에서 실제 이름을 빼고 가짜 이름(하늘)으로 바꿨다

디스코드 봇

  • 기본은 겜녹이 봇으로 진행: 토큰을 넣지 않아도 로그인만 하면 바로 연결된다. 봇은 사이트 서버가 디스코드에 연결하고, 앱은 로그인 토큰으로 서버 중계(/app/bot/ws)를 받는다.
  • 다른 봇으로 진행하기(관리자만)를 고르면 직접 만든 봇 토큰을 넣는다 (암호화 저장). v1.0.0 에서 토큰을 넣어 쓰던 설치는 다른 봇 모드로 그대로 이어진다.
  • v1.2.1 부터 겜녹이 봇 토큰은 사이트 서버 밖으로 나가지 않는다 (v1.1.0 은 exe 에 감춰 넣었고, v1.2.0 은 로그인한 유저에게 내려줬다). 등록된 유저의 PC 에도 토큰이 없어서 PC 를 뒤지거나 통신을 가로채도 꺼낼 수 없다. 음성채널에 들어갈 때 서버가 디스코드에서 받은 일회용 음성 접속 정보만 그 PC 에 넘기고, 음성은 PC ↔ 디스코드로 바로 간다. 사이트 서버가 꺼져 있으면 겜녹이 봇은 쓸 수 없다 (다른 봇 모드는 상관없음). 구조: docs/dev/ARCHITECTURE.md 8장
  • 빌드에 비밀값이 필요 없어 공개 릴리스에 올려도 된다. 등록되지 않은 사람은 exe 를 받아도 겜녹이 봇을 쓸 수 없다.

통신 · 데이터 보안 (v1.2.2~)

  • 앱 ↔ 사이트 서버(로그인 토큰 · 기기 키 · 기록 중계 · 봇 중계)는 https/wss 만 쓴다. 사이트 서버 주소를 http 로 바꾸면 거절하고 아무것도 보내지 않는다 (이 PC 안 127.0.0.1 · localhost 만 예외, 개발용). app/src/core/util/secure-url.ts
  • 사이트 서버 인증서는 앱에 들어 있는 Mozilla 루트 인증서로만 검증하고 검증을 끌 수 없다. NODE_TLS_REJECT_UNAUTHORIZED=0, Windows 인증서 저장소에 깐 가짜 루트 인증서(감시 · 프록시 프로그램)로는 통신을 엿볼 수 없다. 검증 끄기 변수는 시작할 때 지워서 사이트 밖 통신도 검증한다. app/src/core/util/secure-http.ts
  • 겜녹이 봇 중계 권한: 앱 유저가 가입한 디스코드 서버, 그 유저가 볼 수 있는 채널만 보이고, 그 유저가 들어갈 수 있는 음성채널에만 봇을 부를 수 있다.
  • 게임 연동(Riot 로컬 API)의 자체 서명 인증서 예외는 이 PC 안 주소에만 쓴다. Riot 원격 API 등 바깥 주소는 항상 인증서를 검증한다.
  • exe(Electron) 잠금: NODE_OPTIONS · NODE_EXTRA_CA_CERTS(가짜 인증서를 끼워 통신을 엿보는 데 쓰임) · ELECTRON_RUN_AS_NODE · --inspect 를 무시하고 app.asar 만 읽는다 (Electron fuses). 설정 창은 앱 화면만 띄우고 바깥 주소는 브라우저로 연다. 권한 요청(마이크 · 카메라 등)은 거절한다.
  • 사이트 서버: 보안 정책(CSP)으로 이 사이트 스크립트와 이 사이트로의 접속만 허용, 실시간 WebSocket 은 이 사이트에서 온 연결만, 로그인 세션 · 앱 토큰 · 기기 키는 해시로만 저장, 로그에서 로그인 code · state · 검색어를 지운다. 등록 코드 대입 · 로그인 요청 폭주는 IP 별로 막는다. HSTS · http→https 이동 · TLS 1.2 미만 차단은 앞단 프록시(NPMplus)가 한다.
  • 디스코드 음성은 디스코드 자체 암호화(DAVE 종단간 암호화)로 간다.

🔍 범인찾기 (v1.3.2~)

끝난 경기를 고르고 "범인 분석"을 누르면 AI(Claude)가 그 경기의 음성 대화 · 킬 · 라운드/오브젝트 · 경제 · 채팅 · 10명 스탯을 읽고 10명 평점 · 태그 · 한 줄 평과 팀별 범인 1명(이유 + 근거)을 만든다. 근거를 누르면 그 순간의 음성 · 타임라인으로 간다. 계획서: docs/culprit-finder-plan.pdf

  • 정한 것 (2026-10-15): 범인 = 가장 못함 + 가장 발목 + 결과의 원인을 종합해 팀마다 1명 · 분석 버튼은 등록된 앱 유저 이상(다시 분석은 관리자) · Claude Opus 5.5(생각 high) · 말투 중간맛 · 녹음 안내(TTS)에 "녹음된 대화는 AI 경기 분석에 쓰일 수 있어요" 추가
  • 전적 사이트 계산법 참고: 평점과 범인은 기록 점수에서 출발해 승부처 · 역할 · 경제 · 음성 소통으로 더하고 뺀다 (지시문 v1.2). 분석할 때 외부 전적 사이트에는 접속하지 않고, 앱이 경기 기록으로 직접 계산한다
    • 기록 점수 (0~10, 모든 경기): OP.GG OP스코어 계산법을 따라 우리 기록으로 계산한 점수 + 경기/팀 순위 + MVP · ACE + 점수를 올리고 깎은 지표. 발로란트는 OP.GG 가 밝힌 입력(라운드 승률 · KAST · ACS · 피해 격차), 롤은 킬 관여 · 데스 · 딜/받은 피해/골드 비중 · CS · 레벨 · CC · 와드. OP.GG 는 가중치를 공개하지 않아서, 계수는 개발할 때 한 번 OP.GG 공식 MCP 로 받은 실제 경기 점수에 맞춰 정했다 (교차 검증: 발로란트 상관 0.97 · 평균 오차 0.49점, 롤 상관 0.94 · 0.60점 · 팀 최하위 일치 85%). packages/shared/src/rating.ts, 맞추는 도구 tools/opscore-fit/
    • LOL.PS 라인전: LOL.PS 라인전 점수의 입력과 같은 10 · 15분 맞라이너 CS · 골드 · 경험치 차 (LOL.PS 점수 모델은 공개되지 않아 차이 값만). 참고한 원문 · 구현 대응: tools/opscore-fit/README.md
  • 실제 E2E (2026-10-15, v1.3.2, app/scripts/culprit-real-e2e.mts): 실제 Claude Opus 5.5(생각 high), 외부 사이트 접속 없음. 발로란트 시연 경기 33초 · $0.138, 롤 시연 경기 36초 · $0.123. 기록 · docs/dev/test-results.md
  • 리플레이 동기화: 공식 · 비공식 API 로 리플레이 시간을 읽을 수 있을 때만 넣는다 (화면 글자 인식(OCR) · 게임 설정 파일 고치기는 하지 않음). Windows 실기 확인 전이라 v1.3.x 에는 없다
  • 앱: 경기 상세에서 추가 지표 저장(발로란트 피해량 · 받은 피해 · KAST · 첫킬 · 설치/해체 · 라운드별 장비, 롤 포지션 · 딜량 · 시야 · 10/15분 CS), "분석할 수 있는 경기" 판정(경기 결과 · 녹음 공백 1분 · 음성 변환), 근거 번호가 달린 AI 자료 만들기, 결과 저장(culprit_analyses). app/src/core/culprit.ts
  • 사이트 서버: Claude API 키는 서버 환경 변수 ANTHROPIC_API_KEY 에만 (deploy/site/set-anthropic-key.sh). 권한 · 월 $100 · 하루 20회 · 중복 잠금, 구조화 출력, 근거 번호 확인, 비용 장부(토큰 · 비용만, 대화 내용 없음). site/server/src/culprit.ts, 지시문 · 지식 묶음 site/server/prompt/ (지식 묶음의 요원 · 챔피언 목록은 공식 데이터로 하루 한 번 갱신)
  • 화면: 사이트 🔍 범인찾기 탭 (site/web/src/pages/CulpritPage.tsx), 경기 화면의 "🔍 범인 보기". 화면 확인: node --import tsx app/scripts/culprit-shots.mts

진행 현황

단계 내용 상태
M0 기술 검증 DAVE 음성 연결, faster-whisper STT·음량·잡음·사전, 게임 로컬 API 처리, 게임 PC 진단 기능 ✅ 완료 (결과)
M1 녹음 + STT 기본 따라가기·명령 참여, TTS 안내, 유저별 녹음, 대기열 STT, /녹음제외·참여 ✅ 완료 (실음성 테스트)
M2 사이트 서버 · 사이트 v1 디스코드 로그인, 연결 확인·잠금, 타임라인·따라 읽기·필터·검색·실시간 ✅ 완료 · https://gvr.tkrmagid.kr 배포
M3 발로란트 연동 경기 감지, 킬·라운드·채팅, 라운드 시간 + 경기 경과 시간, 경기 상세 ✅ 완료 (전체 스택 테스트)
M4 롤 연동 · 채팅 OCR 게임 API 이벤트, LCU 결과·타임라인, 채팅 OCR·로그, 롤 경기 상세 ✅ 완료 (Windows 실기 확인: 기록) · v1.3.3 에서 OCR 은 빼고 LCU API · 로그 파일만 씀
M5 exe · 설정 · 모델 포터블 exe, 첫 실행 마법사, GPU 감지·모델 다운로드, 암호화 저장, 7일 삭제 ✅ 완료 (Windows 빌드·실행 확인)
M6 단어사전 · UI/UX 핫워드·교정 사전, 사이트 교정 반영, 테마·애니메이션·효과음 ✅ 완료 (사전 효과)
M7 실사용 테스트 통합 테스트, 성능·안정화 ✅ 완료 (GPU 실음성: CER 3.6%, 지연 1.05초 · 기록)
M8 파인튜닝 교정 데이터 + 합성 음성 LoRA 학습, 오류율 비교 후 교체 ✅ 완료 (GPU 시험 학습: CER 4.8% → 1.8%)
범인찾기 (v1.3.x) AI(Claude Opus 5.5 high) 10명 평점 · 팀별 범인 · 근거, 기록 점수(OP.GG OP스코어 계산법) · 10/15분 라인전(LOL.PS 정의) ✅ 완료 (실제 Claude E2E, 사이트 배포, v1.3.5 · 리플레이 동기화는 Windows 실기 확인 뒤)

저장소 구조

app/              게임 PC 앱 (Electron + Node.js 코어, TypeScript)
worker/           STT 워커 (Python, faster-whisper, 롤 로그 채팅, 모델 관리, 파인튜닝)
site/server/      사이트 서버 (Fastify, Discord OAuth2, 기기 중계)
site/web/         사이트 화면 (React + Vite)
packages/shared/  앱·사이트 공통 타입
deploy/           사이트 서버 배포 (.5 Docker, gvr.tkrmagid.kr)
tools/            사전 생성기 등
docs/             설명서·계획서, 개발 문서, 브랜드
assets/           앱·사이트 아이콘·배너

개발

# STT 워커
cd worker && uv venv --python 3.11 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt
.venv/bin/python -m pytest -q

# 사이트 (가짜 데이터로 화면 개발: http://127.0.0.1:5173)
cd site/web && npm install && npm run dev
cd site/server && npm install && npm test
deploy/site/deploy.sh             # .5 배포 (deploy/README.md)

# 앱 코어 (헤드리스)
cd app && npm install && npm test
npm run core -- --diagnose        # 게임 PC 진단 (GPU·STT 속도·Riot API·롤 로그 채팅)
Description
No description provided
Readme 92 MiB
v1.12.1 Latest
2026-11-21 12:22:47 +09:00
Languages
TypeScript 68.5%
C# 12.6%
Python 7.5%
CSS 4.8%
JavaScript 3.6%
Other 2.9%