赤木麻将 - 日麻 AI 实时分析工具（雀魂/天凤）

项目说明

<!-- markdownlint-disable MD033 MD041 -->

<br/>

<p align="center">
<picture>
<源码 media="(prefers-color-scheme: dark)" srcset="assets/logo/akagi-logo-dark.png">
<img alt="Akagi" src="assets/logo/akagi-logo-light.png" width="55%">
</picture>
</p>

<p align="center">
<i>「死ねば助かるのに………」 - 赤木しげる</i>
<br/><br/>
Real-time 麻将 AI assistant for <b>麻将 Soul</b>, <b>Tenhou</b>, and more.<br/>
Akagi V3: A single-binary Rust + Tauri rewrite of
<a href=" and
<a href="
<br/><br/>
<a href=" anything on Discord</a>
·
<a href=" Bug</a>
·
<a href=" Feature</a>
·
<a href="
</p>

<p align="center">
<a href=" src=" alt="GitHub stars" /></a>
<a href=" src=" alt="Latest release" /></a>
<a href=" src=" alt="Open issues" /></a>
<a href="./LICENSE.txt"><img src=" alt="License: Apache-2.0" /></a>
<a href=" src=" alt="Build status" /></a>
<a href=" src=" alt="Discord" /></a>
<a href=" src=" alt="Ask DeepWiki" /></a>
</p>

<p align="center">
Other branches:
</p>

<p align="center">
<a href=" src=")-blue?logo=github" alt="v2 branch" /></a>
<a href=" src=")-blue?logo=github" alt="NG branch" /></a>
</p>

<p align="center">
<b>English</b>
·
<a href="./README.zh-TW.md">繁體中文</a>
·
<a href="./README.zh-CN.md">简体中文</a>
</p>

---

About

> The purpose of this project is to provide a con way to understand
> your performance in 麻将 matches in real time and to learn from it.
> This project is intended for educational purposes only. The author is
> not responsible for any actions taken by users. 游戏 de and
> publishers reserve the right to act against users who their
> terms of service; any consequences (account suspension, etc.) are the
> user's responsibility.

Akagi watches your 麻将 Soul / Tenhou 游戏 over a local proxy or a
built-in browser, mirrors the 游戏 state, and shows shanten, waits,
agari rate, tenpai rate, per-opponent deal-in risk, and a
recommended discard in a draggable HUD. A built-in AI model ships inside
the app — nothing to install — and its suggestion appears each turn; point
it at the cloud inference API when you want a stronger, hosted model.

Screenshots

<img width="2559" height="1439" alt="image" src=" />

---

Table of Contents

For users

Features

Supported Platforms

Quick Start

Bots

Game History

Logs &amp; Diagnostics

Troubleshooting

Roadmap

For de

Architecture

Tech Stack

Project Layout

mjai Bots (plugin interface)

Build From Source

Testing

Releases &amp; CI

Reference Materials

License &amp; Attribution

Acknowledgements

---

Features

Live HUD — shanten, waits, agari rate, tenpai rate, per-opponent

deal-in risk, suggested attack/defence discard. Draggable, resizable
UI layout.

Two capture modes

- MITM proxy (default) — system-wide; needs a one-time CA trust.
- Chromium — Akagi launches a controlled Chromium-family browser
and intercepts WebSocket frames via the Chrome De 协议.
Zero proxy/CA setup; just play in the launched window.

Two bot backends

- Built-in bot (default) — a pure-Rust neural net embedded in the
binary. No Python, no download, no setup; it just plays, in both
4-player and 3-player.
- Cloud inference (optional) — hand each decision to a
hosted, stronger model. The built-in model stays loaded as an
automatic fallback, so an unreachable ser stalls a live
游戏. Keys are bought or redeemed from inside the app.

Per-mode routing throughout: bot.active_4p and bot.active_3p swap
automatically based on the table's player count.

Game history — every completed match is auto-recorded. The

History tab shows a rank pie chart, a cumulative PT line chart with
selectable scoring rules (麻将 Soul tiers / Tenhou ranks /
Custom uma), and detailed stats (win rate, deal-in rate, riichi rate,
fuuro rate, ryukyoku rate, a winning / deal-in points, a
winning turn, yakuman / nagashi-mangan counts).

Simple first-run setup — language → platform → capture mode →

CA trust / Chromium pick → bot settings → done.

Internationalization — English, 日本語, 繁體中文, 简体中文.

Li from Setup or Settings.

Sanma (3-player) — fully supported: AI analysis, per-mode bot

routing, history stats, 3p uma tables.

In-app updates — checks for new releases on launch and on demand

from *Settings → Updates*; one click downloads the update, applies it
in place, and restarts. Read-only installs (e.g. AppImage) fall back
to the release page.

Supported Platforms

| Platform | 4-Player | 3-Player | AutoPlay |
|---|:---:|:---:|:---:|
| Mahjong Soul (Majsoul) | &check; | &check; | &check; |
| Tenhou | &check; | &check; | &check; |
| Riichi City | &check; | &check; | &check; |
| Amatsuki | (planned) | (planned) | &cross; |

---

Quick Start

A. Install a release

Akagi ships as a portable zip — one self-contained folder per platform.
Download the file for your OS from
Releases, unzip anywhere
you ha permission (e.g. ~/Apps/, Desktop), and run akagi
inside. Configuration, logs, history, the CA cert, and bots are all
created right next to it, so moving / backing up / uninstalling is just
moving / copying / deleting the folder.

| OS | File | Notes |
|---|---|---|
| Windows | akagi-<>-windows-x64.zip | x86_64. Requires WebView2 (preinstalled on Win10 1803+ / Win11). SmartScreen will warn — *More info → Run anyway*. |
| macOS | akagi-<>-macos-arm64.zip | Apple Silicon. Unsigned: run xattr -cr <unzipped folder> once, or right-click → *Open* the first time. |
| Linux | akagi-<>-linux-x64.zip | Built on ubuntu-22.04 (glibc 2.35+). Requires WebKit2GTK 4.1 (apt install libwebkit2gtk-4.1-0 / dnf install webkit2gtk4.1 / pacman -S webkit2gtk-4.1). |

On first launch the Setup wizard walks you through language,
platform, capture mode, bot settings, and CA trust (only if you choose
MITM mode). There is no bot to install — the built-in one is already there.

B. Chromium mode (no CA trust needed)

The simplest path. After Setup, Akagi finds Chrome / Edge / Brave /
Chromium automatically and launches it with its own separate profile;
log in to Mahjong Soul and play.

Frames are intercepted via the Chrome De 协议 — no system
proxy, no certificate.

C. MITM mode

System-wide proxy with a self-signed root CA at ./ca/:

1. Trust the certificate ./ca/akagi-ca.crt (or .cer / .pem /
.der).
2. Route the game client through 127.0.0.1:23410.
Health probe: GET /ping → pong.
3. On Windows, Proxifier is the usual
way to redirect a specific application to the proxy.
4. Exclude loopback from that redirection. Send localhost,
127.0.0.1 and ::1 direct, ne Akagi.

> [!IMPORTANT]
> Step 4 is not optional. Games talk to themselves o for
> internal bookkeeping, and a redirector rule that matches the 游戏 for
> *any* target host will sweep those sockets into Akagi too. Akagi refuses
> them (you will see a refusing CONNECT to loopback warning in the log),
> but the game may still misbehave — so exclude loopback at the source.
>
> In Proxifier: Profile → Proxification Rules, enable the built-in
> Localhost rule (Action: *Direct*) and drag it above your game
> rule. Order matters — Proxifier takes the first rule that matches, so a
> Localhost rule sitting below the 游戏 rule ne.

---

Bots

Built-in bot (no install)

Akagi ships a built-in, pure-Rust bot. It's the default for both modes
(bot.active_4p = "akagi-native", bot.active_3p = "akagi-native3p") and
appears at the top of the Bots tab, always "ready".

It's a small neural net trained by behavior cloning (weights are embedded
in the binary), so its strength is modest by design — a sensible default,
not a top-tier engine.

Cloud inference (built-in bot)

The built-in bot can optionally hand its decisions to a **remote inference
服务端** instead of running its embedded model — a stronger, hosted model
reached over the 网络. The embedded local model stays loaded as an automatic
fallback: if the 服务端 is unreachable, rate-limited, or the key is invalid,
the bot plays the local model's move so a live 游戏 ne.

#### Getting a cloud-inference key

Three ways:

Buy key — an in-app purchase.

Redeem code — turn a prepaid 代码 into a key, or add time to the key you

already hold.

Ask in the Discord server.

#### Request timeout

Each move is fetched from the 服务端 with a request timeout (default
3000 ms, adjustable in the cloud-inference settings, bounded to 500–10000 ms).
If a response doesn't arrive in time, that turn falls back to the offline local
model. Raise it to tolerate a slower 服务端 or connection; lower it to give up
sooner. Note that a riichi costs two requests (declare, then discard) within one
turn, so very high risk o the 游戏's turn timer.

Per-mode bots

bot.active_4p and bot.active_3p are independent. Akagi picks the
right one when the 游戏 starts, based on the table's player count.

Beyond these two backends, Akagi can also run external mjai bots as
subprocesses. That's an extension point for de rather than a step
anyone needs — see mjai Bots (plugin interface).

---

Game History

Every cleanly-ended match (one that produced an end_game mjai event)
is persisted under <config_root>/history/:

Mid-游戏 disconnects leave an unfinalised buffer and are silently
dropped — only complete games make it to disk.

The frontend's History tab shows:

Rank pie chart — 1st / 2nd / 3rd / 4th distribution

(3 slices for sanma).

Cumulative PT line chart — selectable scoring rule:

- Mahjong Soul: pick 場次 (銅 / 銀 / 金 / 玉 / 王座) and
段位 (初心 1 星 → 魂天).
- Tenhou: pick 段位 (新人 → 天鳳位 across 21 ranks).
- Custom: edit the uma + dan-bonus arrays directly.
Switching rule / dan re-renders immediately — no backend round-trip.

Detailed stats — win rate, deal-in rate, riichi rate, fuuro rate,

ryukyoku rate, a winning / deal-in points, a winning
turn, yakuman / nagashi-mangan counts.

Game list — filterable by platform / players / east-or-south /

date. Click a row for final standings + per-游戏 stats; the trash
icon deletes both the index entry and the per-游戏 .mjai.jsonl.

PT-rule and filter selections persist to localStorage. Records load
from the backend on bridge boot and stay current via the
history-recorded Tauri event.

See src/history/README.md for the math,
the storage schema, and how to add a new platform / stat field /
filter dimension.

---

Logs & Diagnostics

Per-session logs land under <log_dir>/<YYYYMMDD-HHMMSS>/:

The frontend's Logs route has two tabs:

Diagnostic

Filterable application log. Filter by level (trace / debug / info /
warn / error) and by module. Li or browse past sessions; click
a row to see 源码 location + raw structured fields. An **Open
Folder** button reveals the session directory in the OS file manager.

Inspector

Protocol-le . Three entry types:

WS Frame — raw binary (base64-truncated) plus the bridge's

first-pass parse.

MjaiEvent — decoded events flowing to the bot.

BotReaction — bot responses with the meta field

(confidence / q- / whatever the bot emits).

Frame counts show how many mjai events each WS frame produced.
Useful when debugging a bot or a bridge issue.

---

Troubleshooting

> [!TIP]
> Reproduce the problem, then save the session folder under
> <log_dir>/<session>/ — it has e (app log, raw frames,
> mjai events, bot meta) needed to file a useful bug report.

Capture not working in MITM mode. Make sure the CA at

./ca/akagi-ca.crt is trusted in your OS store. the proxy is
running: curl should reply pong.
Check your proxy redirector (Proxifier / system proxy) is sending
the game client to the right host:port.

游戏 hangs on the loading screen in MITM mode. Your redirector is

probably proxying the 游戏's loopback traffic. Look for
refusing CONNECT to loopback in the log, then exclude localhost,
127.0.0.1 and ::1 — see step 4 of the MITM setup above.

Capture not working in Chromium mode. Detect did not find your

browser. Set capture.chromium.executable manually in Settings or
config.toml. If the launched browser starts but no frames flow,
check that --remote-debugging-port was not blocked by another
extension.

Reopening Akagi with the Chromium window still open. Akagi closes

the still-running browser and relaunches a single fresh window (it
cannot attach a second instance to the same profile). Login is
preserved, so 麻将 Soul reconnects to an in-progress match on
reload. If a lefto refuses to close — capture stops with
"couldn't terminate the browser already using profile …" — close it
manually and click Restart. Running two Akagi instances against the
same profile is unsupported.

Tenhou reconnected in the middle of a hand. Tenhou's rejoin message

is a snapshot of the table, not a replay, so Akagi cannot rebuild the
hand in progress. It shows a "rejoined mid-hand" toast and pauses
analysis and autoplay until the next hand starts; from there on the
游戏 is tracked normally. A 游戏 rejoined this way is not saved to
History, since Akagi never saw the hands before the drop and a partial
record would skew the statistics.

Bot crashed mid-game. The Inspector tab shows the last frame the

bot saw before dying; attach it to the bug report.

Wrong bot picked for a 3-player game. Check bot.active_3p in

Settings → Bot — it is independent of bot.active_4p.

Where do I get help? Discord

for chat, GitHub Issues
for tracked bugs and feature requests.

---

Roadmap

Done in alpha.8:

[x] 3-player mahjong (sanma) — full pipeline

[x] Tenhou bridge (obser)

[x] Riichi City bridge (MITM only — nati; obser)

[x] 游戏 history persistence + History tab (rank pie / PT chart / stats)

[x] Logs (Diagnostic + Inspector tabs)

[x] i18n: en / ja / zh-TW / zh-CN, with Setup-wizard language picker

[x] Bot install from a GitHub release or a local ZIP file

[x] Chromium capture mode (no CA trust needed)

[x] Custom themes (frontend theming hooks)

[x] AutoPlay (麻将 Soul and Tenhou; the bot drives the table

autonomously)

Planned:

[ ] Amatsuki platform support

[ ] Refine Frontend — tile layout, animations, accessibility

Detailed bug tracking lives in
GitHub Issues.

---
---

Architecture

Single Rust binary. Subsystems own only their bus handles, never each
other. src/e.rs is the single source of
truth for channel types.

src/lib.rs wires the buses on boot. The frontend
talks to the backend over push events (mjai-event, bot-response,
bot-status, …) and a set of pull commands, both documented in
src/ipc/README.md. With AutoPlay on, the
autoplay manager consumes the bot's decisions and performs them
through the Chromium capture backend (CDP) — clicking the table on
麻将 Soul, or sending the action over the 游戏's own connection on
Tenhou, whose 客户端 协议 is plain enough to speak directly.

Tech Stack

| Layer | Tech |
|---|---|
| Shell | Tauri 2 |
| Backend | Rust (edition 2021), tokio, tracing, clap |
| MITM | hudsucker 0.24 (rcgen-ca, rustls-client) |
| CDP capture | chromiumoxide 0.9 |
| Mahjong engine | riichien 0.4 |
| Built-in bot | candle 0.9 (pure-Rust NN inference; weights embedded) |
| Cloud inference | reqwest 0.13 (rustls) |
| Protobuf | prost 0.14 + prost-reflect 0.16 |
| Frontend | React 19, TypeScript, Vite 8 |
| Styling | Tailwind CSS v4, shadcn/ui (Radix No) |
| State | Zustand |
| Charts | Recharts |
| Tile rendering | <mah-gen> Web Component |
| i18n | react-i18next |
| mjai bot runtime | python-build-standalone 3.12 + uv (bundled per platform; plugin bots only — the built-in bot needs none of it) |

Project Layout

Per-module de guides live in each src/*/README.md.

mjai Bots (plugin interface)

> Optional, and aimed at de. The built-in bot
> is the default and needs none of this — you only come here to run a *different*
> engine under Akagi.

Besides its own bot, Akagi can drive any 引擎 that speaks the mjai
协议. Such a bot is a standalone subprocess talking JSONL o/stdout:
Akagi feeds it the 游戏 as mjai events, and it replies with an action plus
optional HUD data.

Write one

The full guide lives in mjai_bot/README.md: the
I/O 协议, the mjai event stream, the reaction and meta HUD format, toast
notifications, and manifest.toml settings.
mjai_bot/example/ is a working rule-based bot you can
copy.

For local de, drop your bot folder under mjai_bot/<name>/ and click
Install en on its row in the Bots tab to build its venv — no
need to repackage and reinstall on every change. The acti toggle stays
disabled until the en is ready.

Install one

The Bots tab installs a bot from a GitHub release or a local ZIP.

The IPC command install_bot_from_github(repo, asset_glob?, name?) fetches the
latest release zip, extracts it under mjai_bot/<name>/, bot.py,
and runs uv sync once. Subsequent launches are fast — the sync is gated by a
stamp at mjai_bot/<name>/.akagi/synced.stamp.

Install from ZIP is the offline equi: click Browse… to pick a
.zip (or paste its path). It runs the exact same extract / /
uv sync pipeline; your source .zip is left untouched.

AGPL boundary

Bots run as a separate OS subprocess spawned by Akagi. Communication is
strictly JSONL o / stdout — no in-process linking, no shared address
space, no FFI. This is an intentional license boundary: an AGPL-licensed bot
(e.g. Mortal, which links libriichi) stays inside its own process, so dropping
it under mjai_bot/<name>/ does not make Akagi a derived work of the bot.

Build From Source

Prerequisites

Rust (latest stable, 1.80+)

Node.js 20+ and npm

Tauri 2 system deps:

- Linux: libwebkit2gtk-4.1-dev, libgtk-3-dev,
libayatana-appindicator3-dev, librs,
protobuf-compiler
- macOS: Xcode Command Line Tools
- Windows: WebView2 (preinstalled on Windows 11)

Run / build

Bundled runtime

scripts/fetch-runtime.sh <target-triple> downloads
python-build-standalone 3.12 + uv for the target and stages them
under runtime/. scripts/package-zip.sh then copies that tree next
to the binary inside the zip; src/bot/runtime.rs finds it
exe-adjacent at runtime, so the shipped app works without a system
Python install.

Testing

Integration tests live in tests/:

| File | Covers |
|---|---|
| analysis_pipeline.rs | End-to-end analysis (events → shanten → discard recommendation) |
| analysis_bench.rs | Hot-path performance |
| bot_lifecycle.rs | Install → sync → spawn → roundtrip |
| example_bot.rs | Rule-based reference bot driving a synthetic 游戏 |
| mortal_zip_layout.rs | the Mortal release-zip layout |

Releases & CI

GitHub Actions release.yml builds
on tag push (v3.*) or manual dispatch. One portable zip per target:

| OS runner | Target | Artifact |
|---|---|---|
| ubuntu-22.04 (glibc 2.35) | x86_64-unknown-linux-gnu | akagi-<>-linux-x64.zip |
| macos-14 | aarch64-apple-darwin | akagi-<>-macos-arm64.zip |
| windows-latest | x86_64-pc-windows-msvc | akagi-<>-windows-x64.zip |

Repository admins can build the current head commit of an open PR by posting
an exact /build-artifacts comment on that PR. The
pr-build.yml workflow replies with links
to the three portable artifacts when the build finishes; artifacts are retained
for 14 days. Comments from users without repository admin permission are
ignored.

Each zip ships python-build-standalone 3.12 + uv next to the
binary, so bots run without a system Python install.

Tags must be on the v3 branch.

Reference Materials

| Source | Used in | What for |
|---|---|---|
| mjai JSONL spec (Gimite) | src/schema/mjai/ | MjaiEvent enum + bot wire contract — 15 event types, tile-string format, state-machine rules. |
| EndlessCheng/mahjong-helper (Go analysis CLI) | src/analysis/ | Direct Rust port of util/ — shanten, waits, agari-rate, tenpai-rate, risk model, discard search. |
| Xerxes-2/MajsoulMax-rs (Rust MITM proxy, GPL-3.0) | src/proxy/handler.rs, src/bridge/majsoul/parser.rs, src/bridge/majsoul/proto/liqi.proto | Reference for the 5-layer 麻将 Soul WS wire format (type byte → Wrapper → inner message → action protobuf). Format only — no code copied. |
| smly/RiichiEnv (Rust RL env w/ Python bindings) | Cargo.toml (riichien dep), src/analysis/, src/game_state/ | Tile / hand / shanten / yaku / score primitives + 游戏-state model. The analysis 引擎 and 游戏 tracker are built on this. |
| eric200203/mahgen (mahjong-tile rendering DSL) | src/game_state/mahgen_view.rs, frontend <mah-gen> | DSL syntax for pre-encoding hand / meld / ri backend-side. |
| smly/mjai.app (mahjong AI competition platform) | mjai_bot/, src/bot/ | Bot subprocess con — JSONL stdin/stdout, argv python bot.py <player_id>, AKAGI_PLAYER_ID en flush points. |
| shinkuan/Akagi | Architecture / behaviour parity | The original feature set we are reproducing: MITM proxy, mjai bridge, pluggable bots, recommendation HUD. |

License & Attribution

Akagi v3 is licensed under the Apache License 2.0.
Copyright 2026 Shinkuan. Third-party attributions live in
NOTICE — read it alongside the license. Per
Apache-2.0 §4(d), redistributions must include both files.

Bundled / linked sources

mahjong-helper (MIT) — src/analysis/ is a Rust port of util/.

riichien / RiichiEn.0) — Cargo dependency.

mahgen (MIT) — DSL + <mah-gen> custom element.

Reference-only (no code copied; listed in NOTICE for credit)

MajsoulMax-rs (GPL-3.0) — 麻将 Soul WS wire format reference only.

mjai spec (Gimite) — bot wire contract.

mjai.app — bot subprocess con.

Acknowledgements

Akagi (Python, v2) and

AkagiNG (Electron + Python) —
the predecessors this v3 is built on.

mjai.app and the mjai

specification by Gimite — the protocol that makes pluggable bots
possible.

The community on Discord for bug

reports, model contributions, and feedback.

技术栈

开发语言：Rust

项目类型：日麻 AI 实时分析工具（雀魂/天凤）

Star 数：1076

功能特点

这是一套日麻 AI 实时分析工具（雀魂/天凤），代码结构清晰，适合开发者学习游戏的客户端渲染、服务端逻辑、场景管理与资源加载。项目涵盖了游戏的核心玩法、界面交互、地图与角色系统等模块，对理解游戏开发的完整流程具有较高的参考价值。

从技术实现角度看，游戏项目的难点在于：游戏循环与状态管理、资源加载与渲染优化、客户端与服务端的协议同步、以及多平台适配。本项目在这些方面提供了可运行的实现，开发者可以在此基础上进行二次开发或学习研究。

部署说明

1. 下载源码压缩包，解压到本地开发环境。

2. 根据项目类型准备对应的运行环境（Node.js / Go / C# / Unity / Godot 等）。

3. 按照 README 中的步骤配置依赖、数据库和配置文件。

4. 先启动服务端，再运行客户端，即可进入游戏进行测试。

注意：本项目仅供学习研究使用，请勿用于商业或非法用途。

学习价值

对于想进入游戏开发领域的开发者来说，这套源码是一个很好的入门参考。通过阅读代码，可以学习到游戏的核心玩法实现、场景与资源管理、网络协议设计、以及渲染优化等关键技术点。

同时，项目中的代码组织方式和模块划分，也展示了游戏项目在工程化方面的实践经验，值得开发者深入研究和借鉴。理解一个完整游戏项目的架构，对后续开发其他类型游戏也很有帮助。

免责声明

本资源来源于开源社区，仅供学习研究和技术交流使用，请勿用于任何商业或违法违规用途。使用本项目产生的一切后果由使用者自行承担。若涉及第三方权益，请联系删除。