shinkuan/Akagi

支持雀魂、天鳳、麻雀一番街、天月麻將，能夠使用自定義的AI模型實時分析對局並給出建議，內建Mortal AI作為示例。 Supports Majsoul, Tenhou, Riichi City, Amatsuki, with the ability to use custom AI models to analyze games in real time and provide suggestions. Comes with Mortal AI as a built-in example.

Akagi 는 무엇인가요?

Akagi는 온라인 리치 마작(마작 soul, Tenhou, Riichi City 등)을 플레이하는 동안 실시간 분석을 제공하는 데스크톱 보조 도구입니다. 플레이 중에는 다음과 같은 유용한 수치를 표시하는 작은 오버레이(HUD)가 나타납니다:

선텐(Shanten) – 완성된 손까지 얼마나 멀었는지
대기(Waits) – 손을 완성시키는 데 필요한 패
아가리 / 텐파이 확률(Agari / Tenpai rates) – 승리하거나 텐파이 상태가 될 확률
각 상대의 딜 인 리스크(Deal-in risk per opponent) – 각 상대의 버린 패의 위험도
추천 버림(Suggested discard) – 내장된 AI가 버릴 만한 최적의 패

오버레이는 이동 및 크기 조절이 가능하며, 모든 완료된 게임은 로컬에 저장되어 나중에 통계, 랭크 분포, PT 추세선, 각 수의 세부 데이터를 확인할 수 있습니다.

어떻게 작동하나요?

게임 데이터 캡처 – Akagi는 다음 중 하나로 작동합니다:
- 게임의 WebSocket 트래픽을 가로채는 MITM 프록시를 실행 (한 번만 자체 서명된 CA 설치)
- Chromium 기반 브라우저를 실행하고 Chrome DevTools Protocol을 통해 WebSocket 프레임을 스니핑 (인증서 필요 없음)
원시 프레임을 표준 mjai 이벤트 스트림으로 변환 – Mahjong Soul, Tenhou 등 플랫폼별 브리지로 공통 JSON 형식의 일본 리치 마작 이벤트 스트림으로 변환됩니다.
이벤트를 봇에 공급 – 두 가지 백엔드가 사용 가능:
- 내장 봇 – HuggingFace의 candle 라이브러리를 사용해 Rust 바이너리에 컴파일된 작은 신경망. 로컬에서 작동하며 다운로드 필요 없음. 4인용 및 3인용(산마) 게임 모두 지원.
- 클라우드 추론 – 선택적 원격 모델로 더 강력한 성능 기대 가능. 로컬 모델은 항상 백업으로 로드되므로 서버가 느리거나 사용 불가능해도 게임이 멈추지 않음.
분석 표시 – HUD는 위의 수치를 표시하고, 히스토리 탭은 누적된 통계를 시각화합니다.
옵션 AutoPlay – 활성화 시 봇이 실제로 수를 대신 수행할 수 있음 (Chromium 창에서 패 클릭 또는 Tenhou에 직접 액션 전송).

모든 구성 요소는 단일 Rust 바이너리 내의 가벼운 이벤트 버스를 통해 통신하며, UI는 Tauri 2, React 19, Tailwind CSS로 구축됩니다.

누구에게 유용할까요?

결정 순간에 즉각적인 피드백을 원하고, "좋은 버림"이 어떤 모습인지 배우고 싶은 일반 플레이어
플레이 중에 선텐, 대기 목록, 리스크 지표를 빠르게 확인하고 싶은 마작 이론 학습자
실시간 게임 상태 캡처, Rust 기반 신경망 추론 파이프라인, 웹 게임과 데스크톱 UI 간의 브리지에 관심 있는 개발자/연구자

시작하기

릴리스 다운로드 – Releases 페이지에서 Windows, macOS (Apple Silicon), Linux용 zip 파일을 다운로드. 원하는 위치에 압축 해제하고 akagi 실행 파일을 실행.
설치 마법사 실행 – 언어, 플레이할 플랫폼, 캡처 모드(MITM 또는 Chromium), 클라우드 추론 키 사용 여부를 설정.
게임 플레이 – Akagi에서 내장된 Chromium 브라우저를 실행하거나 기존 클라이언트를 로컬 프록시(127.0.0.1:23410)로 설정. HUD가 자동으로 표시됩니다.
몇 게임 후 History 탭 탐색 – 승률 차트, PT 추세, 각 수 통계를 확인 가능.

제한 및 주의사항

내장된 신경망은 의도적으로 보수적입니다. 타당한 조언은 제공하지만 최상위 엔진은 아님.
MITM 프록시 사용 시 자체 서명된 CA 설치와 Windows에서는 Proxifier 같은 제3자 리디렉터 필요. 루프백 트래픽을 제외하지 않으면 게임이 제대로 작동하지 않을 수 있음.
클라우드 추론은 구매 또는 사용 가능한 키 필요. 없으면 로컬 모델로 백업.
완전한 게임만 저장됨. 중간에 연결 끊기 시 부분 데이터는 삭제됨.
소프트웨어는 교육 목적만 사용 가능. 게임 이용 약관 위반 가능하며, 계정 벌금은 사용자 책임.

빠른 참조

기능	세부 사항
지원 게임	Mahjong Soul, Tenhou, Riichi City (향후: Amatsuki)
캡처 모드	MITM 프록시(시스템 완전) 또는 Chromium CDP(인증서 없음)
봇	내장된 Rust NN, 선택적 클라우드 호스팅 모델, 외부 mjai 플러그인
플랫폼	Windows x64, macOS ARM64, Linux x64 (glibc 2.35+)
UI 기술	Tauri 2 + React 19 + TypeScript + Tailwind
라이선스	Apache 2.0

Akagi는 단일 포터블 바이너리로 패키징된 실시간 AI 지원 분석 도구이며, 선택적 클라우드 기반 추론을 제공합니다.