Akagi麻将AI助手：实时分析引擎的架构解析与部署指南

【免费下载链接】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.项目地址: https://gitcode.com/gh_mirrors/ak/Akagi

Akagi是一款采用Rust+Tauri技术栈重构的实时麻将AI助手，为雀魂、天凤、麻雀一番街、天月麻将等主流平台提供专业级智能分析服务。该项目通过先进的深度学习模型和实时数据处理架构，为玩家提供向听数计算、听牌概率评估、放铳风险分析等核心功能，成为麻将爱好者的智能决策辅助工具。

技术架构深度解析

事件驱动架构设计

Akagi采用基于事件总线的模块化架构，各子系统通过广播通道解耦，确保高内聚低耦合的设计原则。核心事件总线位于src/event_bus.rs，定义了系统内部通信的所有通道类型。

系统工作流程遵循清晰的管道处理模式：

游戏客户端 → 数据捕获层 → 协议转换层 → AI分析引擎 → 可视化界面

数据捕获子系统

系统提供两种数据捕获模式，满足不同使用场景：

MITM代理模式：基于hudsucker库实现中间人代理，支持系统级网络流量拦截。该模式需要一次性CA证书信任配置，位于./ca/目录下的自签名根证书。

Chromium模式：通过Chrome DevTools Protocol直接控制浏览器实例，无需证书配置。Akagi启动独立的Chromium家族浏览器，创建隔离的用户数据目录<config_root>/chrome-profile，实现零代理设置的实时数据监控。

麻将分析引擎

分析引擎位于src/analysis/目录，移植自EndlessCheng/mahjong-helper的Go实现，基于riichienv-core库构建完整的麻将规则引擎。

核心分析模块包括：

• 向听数计算：shanten.rs模块提供精确的向听数评估
• 听牌概率：tenpai_rate.rs实现开放手牌听牌率估算
• 和牌概率：agari_rate.rs计算每种听牌的和牌概率
• 放铳风险：risk/目录实现对手放铳风险评估模型

AI模型集成架构

Akagi采用进程隔离的AI模型集成方案，通过JSONL标准协议与外部AI进程通信。这种设计实现了AGPL许可证边界，确保商业友好性。

AI模型管理位于src/bot/目录，支持以下特性：

• 双模式切换：独立配置4人麻将和3人麻将的AI模型
• 环境隔离：每个AI运行在独立的Python虚拟环境中
• 热更新支持：运行时模型切换无需重启应用

部署与配置指南

系统环境要求

最小硬件配置：

• 内存：4GB RAM
• 存储：2GB可用空间
• 网络：稳定互联网连接

软件依赖：

• Windows：WebView2运行时（Windows 10 1803+内置）
• Linux：WebKit2GTK 4.1（libwebkit2gtk-4.1-0）
• macOS：Xcode命令行工具

快速部署步骤

步骤1：获取可执行文件

git clone https://gitcode.com/gh_mirrors/ak/Akagi cd Akagi

步骤2：运行初始化向导首次启动时，系统将引导完成以下配置：

1. 语言选择（支持英文、日文、简体中文、繁体中文）
2. 游戏平台选择（雀魂、天凤、麻雀一番街）
3. 捕获模式配置（MITM代理或Chromium模式）
4. AI模型安装（可选Mortal AI示例）

步骤3：配置文件定制主配置文件config.toml支持热重载，主要配置项：

[bot] enabled = true active_4p = "mortal" # 四人麻将AI模型 active_3p = "mortal3p" # 三人麻将AI模型 [capture] mode = "chromium" # 或 "mitm" [proxy] enabled = true addr = "127.0.0.1:23410" # 代理监听地址

AI模型配置详解

Mortal AI模型集成：

1. 获取Mortal权重文件mortal.pth
2. 放置到mjai_bot/mortal/目录
3. 系统自动检测并配置Python环境

自定义AI模型开发： 创建mjai_bot/<name>/目录结构：

mjai_bot/<name>/ ├── bot.py # JSONL标准接口 ├── pyproject.toml # Python依赖声明 ├── manifest.toml # 模型元数据（可选） └── settings.toml # 用户配置（可选）

实战应用场景分析

实时对局分析

Akagi在游戏过程中提供以下实时分析功能：

手牌效率评估：

• 向听数精确计算
• 有效牌识别与排序
• 鸣牌时机建议

风险评估系统：

• 对手听牌范围分析
• 放铳概率计算
• 安全牌推荐算法

AI决策支持：

• 深度学习模型推荐
• 置信度评分显示
• 多策略对比分析

历史数据统计

系统自动记录完整对局历史，提供以下分析维度：

战绩统计分析：

• 胜率、平均顺位、平均得点
• 各局面决策成功率
• 特定牌型处理效果

技术能力评估：

• 防守能力评分系统
• 进攻时机把握度分析
• 鸣牌效率统计

开发调试支持

内置诊断工具支持深度调试：

日志系统：

• 按模块过滤的应用程序日志
• 原始WebSocket帧记录
• 实时日志流监控

协议分析器：

• WebSocket帧到mjai事件转换
• AI响应元数据检查
• 帧计数统计分析

性能优化建议

系统资源管理

内存优化策略：

• 启用AI模型时预留2GB内存空间
• 定期清理历史会话日志
• 配置合理的日志轮转策略

CPU使用优化：

• 调整分析引擎计算频率
• 启用AI模型缓存机制
• 配置合适的线程池大小

网络配置优化

代理模式优化：

[proxy] max_connections = 100 # 最大并发连接数 buffer_size = 8192 # 缓冲区大小 timeout = 30 # 超时设置（秒）

Chromium模式优化：

[capture.chromium] extra_args = [ "--disable-gpu", "--disable-software-rasterizer", "--disable-dev-shm-usage" ]

AI模型性能调优

模型加载优化：

• 预加载常用AI模型权重
• 实现模型权重缓存机制
• 支持模型热切换

推理延迟优化：

• 批处理推理请求
• GPU加速支持（如可用）
• 量化模型权重

故障排查手册

常见问题诊断

数据捕获失败：

1. 检查代理端口占用：netstat -an | grep 23410
2. 验证CA证书信任状态
3. 确认游戏客户端代理设置

AI模型加载失败：

1. 验证Python环境完整性
2. 检查模型权重文件路径
3. 查看mjai_bot/<name>/.akagi/日志

性能问题排查：

1. 监控系统资源使用率
2. 检查网络延迟和丢包率
3. 分析AI推理延迟统计

日志分析指南

系统日志位于<log_dir>/<YYYYMMDD-HHMMSS>/目录：

日志目录结构： ├── all.log # 综合跟踪输出 ├── proxy.binlog # 原始WebSocket帧 ├── majsoul/<flow_id>.log # 平台特定协议日志 └── inspector.jsonl # 协议分析器输出

调试工具使用

诊断视图：

• 按级别（trace/debug/info/warn/error）过滤日志
• 按模块分类查看详细输出
• 实时日志流监控

检查器视图：

• WebSocket帧原始数据查看
• mjai事件流解码显示
• AI响应元数据分析

扩展开发指南

自定义AI模型集成

开发符合mjai协议的AI模型需实现以下接口：

输入协议：

[ {"type": "start_game", "id": 0}, {"type": "tsumo", "actor": 0, "pai": "1m"} ]

输出协议：

{ "type": "dahai", "actor": 0, "pai": "5p", "tsumogiri": false }

平台协议扩展

添加新游戏平台支持需要实现以下组件：

1. 协议解析器：位于src/bridge/目录
2. 状态跟踪器：继承GameStateTracker接口
3. 事件转换器：实现MjaiEvent转换逻辑

前端界面定制

前端基于React + TypeScript + Tailwind CSS构建：

组件架构：

• 路由组件：frontend/src/routes/
• 仪表板磁贴：frontend/src/tiles/
• 状态管理：frontend/src/stores/

国际化支持： 系统支持多语言界面，翻译文件位于frontend/src/i18n/目录。

未来技术路线

近期开发计划

平台扩展：

• 天月麻将完整支持
• 更多麻将平台协议适配

功能增强：

• 自定义主题系统
• 前端界面动画优化
• 无障碍访问支持

技术架构演进

性能优化方向：

• WebAssembly分析引擎
• GPU加速推理支持
• 分布式AI模型服务

用户体验改进：

• 移动端适配优化
• 离线模式支持
• 社区功能集成

生态系统建设

开发者工具：

• 协议分析调试工具
• AI模型训练框架
• 性能基准测试套件

社区贡献：

• 插件化架构支持
• 第三方AI模型市场
• 数据分析API服务

总结

Akagi麻将AI助手通过现代化的技术架构，为麻将爱好者提供了专业级的实时分析工具。其模块化设计、灵活的AI集成方案和丰富的功能特性，使其成为麻将技能提升的理想辅助工具。无论是初学者学习基础规则，还是进阶玩家优化决策策略，Akagi都能提供有价值的分析支持。

项目采用Apache 2.0开源协议，确保了商业友好性，同时通过进程隔离设计避免了AGPL许可证的传染性风险。随着社区的持续贡献和技术的不断演进，Akagi将继续为麻将AI分析领域带来创新和改进。

【免费下载链接】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.项目地址: https://gitcode.com/gh_mirrors/ak/Akagi