Akagi麻将AI助手：Rust技术栈实现的实时分析与自定义AI集成指南
Akagi麻将AI助手：Rust技术栈实现的实时分析与自定义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技术栈开发的日麻AI辅助工具，专为雀魂、天鳳等主流麻将平台设计。该项目采用单二进制架构，结合Tauri框架构建跨平台桌面应用，能够实时分析麻将对局并提供专业建议。通过模块化设计和清晰的协议接口，Akagi不仅内置了先进的麻将分析引擎，还支持用户自定义AI模型集成，为麻将爱好者和技术开发者提供了一个强大的学习和开发平台。
技术架构与核心设计理念
Akagi采用现代化的Rust技术栈构建，其核心设计遵循事件驱动架构和模块化分离原则。整个系统围绕事件总线（Event Bus）构建，各子系统通过明确定义的通道进行通信，确保高内聚低耦合的设计目标。
Akagi采用Rust+Tauri技术栈，实现高性能的麻将分析系统
系统的核心模块包括：
- 游戏数据捕获层- 支持MITM代理和Chromium DevTools Protocol两种模式
- 协议桥接层- 将平台特定的协议转换为标准的mjai事件流
- 游戏状态跟踪器- 基于riichienv-core构建的麻将状态管理
- 分析引擎- 移植自mahjong-helper的Go实现，提供向听数、和牌率、放铳风险等核心计算
- AI机器人运行时- 独立的Python子进程管理，支持mjai协议兼容的AI模型
技术栈的完整配置位于 src/analysis/ 目录，其中包含麻将分析引擎的所有算法实现。分析模块采用Rust重新实现了EndlessCheng的mahjong-helper工具，在保持算法准确性的同时获得了显著的性能提升。
实时分析引擎的技术实现
Akagi的分析引擎是其核心价值所在，它能够在毫秒级别完成复杂的麻将计算。引擎的实现位于src/analysis/目录，主要包含以下几个关键组件：
向听数与手牌效率分析
基于riichienv-core库，Akagi能够精确计算手牌的当前向听数，并评估每张牌的打牌效率。算法考虑牌型组合、宝牌影响、场况因素等多维度信息，为玩家提供科学的打牌建议。
和牌率与听牌率计算
通过内置的概率模型，系统能够实时计算各种听牌形式的和牌概率。这些计算考虑了剩余牌张、对手行为模式、场况风险等多个因素，为攻防决策提供数据支持。
放铳风险评估系统
Akagi的风险评估模型是技术上的亮点之一。系统不仅计算基础放铳概率，还考虑了以下修正因素：
- 筋牌理论（Suji）分析
- 对手打牌习惯识别
- 场况与点数差影响
- 剩余巡目风险评估
系统能够精确分析各种和牌场景，提供专业的决策支持
弃牌搜索算法
当玩家需要弃牌时，分析引擎会遍历所有可能的弃牌选择，综合考虑手牌效率改善、安全度评估、打点潜力等多个目标函数，最终推荐最优的弃牌选择。
多平台支持与协议适配
Akagi的技术优势之一在于其灵活的平台适配能力。目前支持的主要平台包括：
雀魂（Mahjong Soul）支持
通过深度解析雀魂的WebSocket通信协议，Akagi能够实时捕获游戏状态。协议解析代码位于src/bridge/majsoul/目录，实现了完整的五层协议栈解析：
- WebSocket二进制帧处理
- 类型字节识别
- 包装层解包
- 内部消息解析
- Protobuf反序列化
天鳳（Tenhou）支持
天鳳平台采用JSON标签流协议，Akagi实现了观察模式下的完整解析。虽然当前版本仅支持观察模式，但架构设计为未来的自动对局支持预留了接口。
捕获模式技术实现
Akagi提供两种捕获模式，满足不同用户需求：
MITM代理模式：使用hudsucker库实现中间人代理，需要用户信任自签名的CA证书。这种模式支持系统范围的流量拦截，适合高级用户。
Chromium CDP模式：通过Chrome DevTools Protocol直接控制浏览器实例，无需CA证书信任。Akagi会启动一个隔离的浏览器配置文件，自动登录游戏并捕获通信。
自定义AI模型集成框架
Akagi最强大的特性之一是其开放的AI集成框架。通过标准化的mjai协议，用户可以轻松集成自定义的麻将AI模型。
mjai协议规范
AI机器人通过简单的JSONL协议与Akagi通信，每个决策点Akagi向机器人发送一批mjai事件，机器人回复一个动作响应。协议设计简洁高效，支持以下核心事件类型：
{ "type": "start_game", "names": ["玩家1", "玩家2", "玩家3", "玩家4"], "id": 0, "num_players": 4 }机器人开发指南
要开发自定义AI机器人，只需在mjai_bot/目录下创建机器人文件夹，包含以下文件：
- bot.py- 主程序入口，实现mjai协议处理
- pyproject.toml- Python依赖声明
- manifest.toml- 机器人元数据和配置模式
- settings.toml- 运行时配置（由Akagi管理）
详细的开发文档位于 mjai_bot/README.md，其中包含了完整的协议规范、开发示例和最佳实践。
内置Mortal AI示例
Akagi内置了Mortal AI作为示例机器人，展示了完整的AI集成流程。用户可以通过一键安装功能快速部署Mortal，也可以参考其实现开发自己的AI模型。
安装与配置流程
快速启动指南
Akagi采用便携式打包设计，每个平台一个独立的压缩包。安装过程极为简单：
- 从发布页面下载对应平台的ZIP文件
- 解压到任意有写入权限的目录
- 运行可执行文件
首次启动时会自动运行设置向导，引导用户完成语言选择、平台配置、捕获模式设置和机器人安装等步骤。
配置文件结构
所有配置存储在config.toml文件中，采用TOML格式，结构清晰易读：
[general] language = "zh-CN" [platform] kind = "Majsoul" [capture] mode = "chromium" [bot] enabled = true active_4p = "mortal" active_3p = "mortal3p"运行时环境管理
Akagi内置了独立的Python运行时环境（python-build-standalone 3.12 + uv），确保机器人能够在没有系统Python的环境中正常运行。这种设计避免了环境依赖冲突，提高了部署的可靠性。
历史记录与统计分析系统
Akagi内置了完整的历史记录系统，所有完整结束的对局都会自动保存到本地。历史数据存储在<config_root>/history/目录下，采用JSONL格式，便于后续分析和处理。
数据存储格式
历史记录采用两级存储结构：
index.jsonl- 游戏索引，每行一个GameRecordgames/<ulid>.mjai.jsonl- 完整的mjai事件流副本
统计可视化功能
前端的历史标签页提供了丰富的统计功能：
- 排名分布饼图- 直观展示玩家的排名分布
- 累计PT折线图- 支持多种计分规则切换
- 详细统计数据- 包括和牌率、放铳率、立直率、副露率等关键指标
系统帮助玩家理解何时应该宣告立直，这是日本麻将中的重要策略
可扩展的计分规则
系统支持多种计分规则，包括雀魂段位系统、天鳳段位系统和自定义规则。用户可以根据自己的需求灵活配置，所有选择都会持久化到本地存储。
开发与扩展指南
项目结构概览
Akagi采用清晰的模块化结构，便于开发者理解和扩展：
src/ ├── analysis/ # 麻将分析引擎 ├── bot/ # AI机器人运行时管理 ├── bridge/ # 平台协议适配 ├── capture/ # 数据捕获后端 ├── game_state/ # 游戏状态跟踪 ├── history/ # 历史记录系统 └── ipc/ # 前后端通信接口自定义分析算法扩展
开发者可以通过以下步骤扩展分析功能：
- 在
result::AnalysisResult中添加新字段 - 在相应模块中实现计算逻辑
- 通过
analyze()函数集成到分析流水线
新平台适配指南
要支持新的麻将平台，需要实现以下组件：
- 协议解析器 - 将平台特定的协议转换为mjai事件
- 游戏状态适配器 - 将平台状态映射到标准麻将状态
- 捕获后端 - 实现数据获取机制
详细的开发指南位于各模块的README文件中，为开发者提供了完整的技术文档。
学习路径设计建议
初学者入门阶段
对于麻将新手，建议从观察模式开始：
- 安装Akagi但不启用AI建议
- 观察系统提供的实时分析数据
- 重点关注向听数和手牌效率分析
- 逐步理解安全牌识别逻辑
中级玩家提升阶段
当熟悉基本分析后，可以启用Mortal AI：
- 安装Mortal AI机器人
- 对比AI建议与自己的决策
- 分析AI的决策逻辑和风险评估
- 学习攻防平衡策略
高级玩家自定义阶段
对于有经验的玩家和开发者：
- 开发自定义AI机器人
- 调整分析参数和风险偏好
- 集成外部AI模型
- 贡献代码或改进算法
Akagi帮助玩家掌握自摸的时机判断，这是提升胜率的关键技能
开源社区与贡献指南
Akagi采用Apache 2.0开源协议，鼓励社区参与和贡献。项目在GitHub上保持活跃开发，主要贡献途径包括：
问题报告与功能建议
通过GitHub Issues提交问题报告或功能建议，提供详细的复现步骤和环境信息。
代码贡献流程
- Fork项目仓库
- 创建功能分支
- 实现功能并添加测试
- 提交Pull Request
- 通过CI测试和代码审查
文档改进
项目文档位于各模块的README文件中，欢迎改进文档质量、添加示例或翻译。
AI模型贡献
社区成员可以贡献改进的AI模型或权重文件，通过Discord社区分享和交流。
技术优势与未来展望
Akagi的技术架构具有多个显著优势：
性能优势
基于Rust实现的分析引擎提供了极致的性能表现，能够在毫秒级别完成复杂的麻将计算，确保实时分析的流畅性。
可扩展性设计
模块化的架构设计使得系统易于扩展，无论是添加新的麻将平台还是集成新的AI模型，都只需要实现相应的接口即可。
跨平台兼容性
通过Tauri框架，Akagi能够在Windows、macOS和Linux系统上提供一致的用户体验，同时保持原生应用的性能表现。
开源生态建设
项目的开源特性促进了社区协作，用户和开发者可以共同改进系统，分享AI模型，推动麻将AI技术的发展。
未来，Akagi团队计划继续扩展平台支持（包括Riichi City和Amatsuki），改进前端用户体验，并优化AI集成框架。项目的持续发展依赖于活跃的社区参与，欢迎所有对麻将AI技术感兴趣的开发者加入贡献。
通过Akagi，麻将爱好者不仅可以获得专业的实时分析指导，还可以深入了解麻将AI的技术实现，甚至参与到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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考