3步精通Akagi：雀魂智能辅助系统从部署到实战的全流程指南

一、价值主张：重新定义麻将AI辅助体验

Akagi作为一款开源雀魂智能客户端，通过深度整合实时游戏分析与AI决策引擎，为麻将爱好者提供从牌局数据采集到策略推荐的全流程辅助解决方案。其核心技术优势体现在三个方面：

• 毫秒级响应的模型推理（AI对牌局数据的实时计算过程）能力，确保在复杂牌局中提供即时决策支持
• 轻量化架构设计，支持Windows与macOS多平台部署，资源占用率低于同类工具40%
• 高度可定制的策略系统，允许用户通过配置文件调整AI风险偏好、分析频率等核心参数

该工具既能满足新手玩家的基础辅助需求（如牌型分析、胡牌提示），也能为进阶玩家提供专业级数据分析支持（如对手行为模式识别、概率分布计算），实现"千人千面"的个性化辅助体验。

二、场景化部署：三步完成环境搭建

2.1 环境检测与代码获取

🔧 第一步：克隆项目仓库

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

✅ 验证方法：执行完成后，通过以下命令检查核心目录结构：

ls -l | grep -E "mjai|mahjong_soul_api|mhm"

应显示mjai/、mahjong_soul_api/和mhm/三个核心目录

2.2 系统专属安装流程

Windows平台部署

🔧 管理员PowerShell执行安装脚本

scripts\install_akagi.ps1

⚠️ 注意事项：

• 安装过程中出现"用户账户控制"提示时，需选择"是"授予权限
• 脚本会自动安装Python环境、依赖库及系统证书
• 全过程需保持网络畅通，下载依赖包约需5-10分钟

macOS平台部署

🔧 终端执行自动化安装

bash scripts/install_akagi.command

✅ 验证方法：脚本执行完成后，终端应显示"Akagi环境配置成功"提示，同时生成配置文件[config.json]

2.3 核心资源配置与验证

🔧 AI模型部署

1. 将下载的模型文件放置于[mjai/bot/]目录
2. 重命名模型文件为"mortal.pth"
3. 执行权限检查命令：

ls -l mjai/bot/mortal.pth

确保文件权限显示为"-rw-r--r--"或类似可读权限

💡 配置验证：启动基础检查脚本验证环境完整性

python -m mhm --check

成功输出应包含"模型加载成功"和"协议连接正常"等验证信息

三、功能解析：五大核心模块技术原理

3.1 智能决策引擎

核心原理：基于深度强化学习训练的麻将策略模型，通过分析当前手牌组合、剩余牌池、对手行为历史等多维数据，生成最优操作建议。

技术实现：

• 模型架构：采用ResNet+LSTM混合网络结构，处理序列型牌局数据
• 决策流程：通过蒙特卡洛树搜索（MCTS）生成候选操作，结合价值网络评估选择最优解
• 配置接口：可通过[config.json]中的"risk_level"参数（1-5）调整策略保守程度

应用示例：在东一局南家听牌场景中，系统会自动计算不同舍牌的胡牌概率与点炮风险，当"risk_level"设为3（中等风险）时，会优先选择胡牌概率≥40%且点炮风险<15%的舍牌方案。

3.2 实时数据采集系统

核心原理：通过协议解析技术捕获游戏内数据，构建完整的牌局数据库，为AI决策提供数据支持。

技术实现：

• 数据捕获：基于[liqi_proto/liqi.proto]定义的协议规范，解析游戏通信数据
• 存储结构：采用JSON格式实时记录打牌顺序、杠碰吃操作与分数变化
• 扩展接口：可通过修改[mahjong_soul_api/ms/rpc.py]中的回调函数自定义数据采集粒度

应用示例：开发人员可通过实现on_game_data回调函数，将每局数据实时同步至本地数据库，用于后续牌谱分析与策略优化。

3.3 个性化配置中心

核心原理：通过配置文件实现工具行为的精细化调整，满足不同用户的使用习惯与需求场景。

关键配置文件：

• [config.json]：核心参数配置，包括AI分析频率（默认200ms/次）、界面显示风格等
• [settings.json]：高级设置，包含反检测功能开关、操作延迟范围等安全相关参数
• [mhm/config.py]：应用程序配置，可调整日志级别、模块加载策略等

配置示例：调整AI分析频率与操作延迟

// config.json 片段
{
  "ai_analysis_interval": 250,  // 分析间隔（毫秒）
  "display_mode": "professional",  // 显示模式：minimal/professional/teaching
  "operation_delay": {
    "min": 300,
    "max": 800  // 随机操作延迟范围（毫秒）
  }
}

3.4 多模式交互界面

核心原理：提供三种显示模式适应不同使用场景，平衡信息密度与决策效率。

模式特点：

• 极简模式：仅显示核心决策建议，适合低干扰需求场景
• 专业模式：展示完整概率分析图表，包括待牌概率、危险牌评估等数据
• 教学模式：附带策略解释与牌理说明，帮助新手理解决策依据

切换方法：通过快捷键Ctrl+M（Windows）或Cmd+M（macOS）循环切换模式，当前模式会在界面右下角显示。

3.5 协议解析与适配模块

核心原理：通过定义标准化的协议接口，确保工具在游戏版本更新后仍能保持功能完整性。

技术实现：

• 协议定义：[liqi_proto/liqi.proto]文件定义通信接口规范
• 版本适配：通过协议版本协商机制自动适配游戏服务端更新
• 扩展能力：支持通过[liqi.json]配置文件添加自定义协议解析规则

维护策略：项目会定期更新协议定义文件，用户可通过git pull获取最新协议支持，无需重新安装整个系统。

四、实战技巧：安全高效使用指南

4.1 安全使用策略

⚠️ 账号保护措施

• 启用[settings.json]中的"anti_detection"功能：

{
  "security": {
    "anti_detection": true,
    "randomize_click_position": true
  }
}

• 设置合理的操作延迟（推荐300-800ms），模拟真实玩家操作节奏
• 避免连续使用超过2小时，降低账号风险

💡 使用建议：配合[my_logger.py]中的日志功能，定期检查操作记录是否符合自然行为模式。

4.2 效率提升方法

性能优化：

• 调整[config.json]中的"analysis_quality"参数平衡性能与精度
• 关闭不使用的功能模块（如教学提示）减少资源占用
• 对于低配置电脑，可降低AI模型推理精度：

python -m mhm --low-precision

工作流优化：

• 使用快捷键Ctrl+D（Windows）或Cmd+D（macOS）快速隐藏/显示界面
• 通过[config.json]配置常用操作的一键执行功能
• 导出牌局数据进行离线分析：

python -m mjai.export --path ./replays --format json

五、问题排查：常见故障解决方案

5.1 启动时证书错误

现象：程序启动后提示"SSL certificate verify failed"

排查路径：

1. 检查系统证书库是否包含项目证书
2. 确认安装脚本已正确执行证书导入步骤
3. 验证Python证书配置：

python -m certifi

解决方案：

# 重新安装证书
python -m certifi --install
# 验证证书路径配置
export SSL_CERT_FILE=$(python -m certifi)

5.2 AI分析无响应

现象：游戏中未显示决策建议，界面提示"AI分析中"但长时间无结果

排查路径：

1. 检查[mjai/bot/]目录是否存在mortal.pth文件
2. 查看终端输出是否有"model loaded successfully"提示
3. 检查系统资源占用情况，确认是否存在资源不足

解决方案：

# 检查模型文件完整性
md5sum mjai/bot/mortal.pth
# 重新安装依赖
pip install -r requirement.txt --upgrade
# 以调试模式启动，查看详细日志
python -m mhm --debug

5.3 网络连接失败

现象：提示"无法连接到游戏服务器"或"协议握手失败"

排查路径：

1. 检查[config.json]中的网络设置：

{
  "network": {
    "proxy_enabled": false,
    "server_address": "https://majsoul.union-game.com"
  }
}

2. 测试网络连通性：

curl -I https://majsoul.union-game.com

解决方案：

# 重置网络配置
python -m mhm --reset-network
# 检查防火墙设置
sudo ufw allow 8080/tcp  # 开放工具所需端口

通过本指南的系统部署与功能解析，您已掌握Akagi雀魂助手的核心使用方法。请记住，工具的价值在于辅助提升游戏理解能力，合理使用才能真正享受麻将竞技的乐趣与成长。建议定期通过git pull获取项目更新，以获得最新功能与安全补丁。