Akagi雀魂智能助手：AI驱动的麻将辅助系统全流程指南

1. 价值主张：重新定义麻将辅助工具的核心能力

1.1 核心价值定位

Akagi雀魂智能助手作为一款开源麻将辅助系统，通过深度整合AI决策引擎与实时游戏分析技术，为玩家提供从牌局数据采集到策略推荐的全流程解决方案。该工具采用轻量化架构设计，支持多平台部署，既能满足新手玩家的基础辅助需求，也能为进阶玩家提供专业级数据分析支持。

1.2 技术优势解析

• 毫秒级响应的模型推理：AI对牌局数据的实时计算过程可在200ms内完成，确保不影响游戏体验
• 高度可定制的策略系统：用户可通过配置文件调整AI决策风格，适应不同游戏场景
• 跨平台兼容性：支持Windows、macOS等主流操作系统，实现一致的用户体验
• 模块化架构设计：各功能模块独立封装，便于扩展与维护

1.3 用户收益矩阵

• 新手玩家：降低学习门槛，快速掌握基本策略与牌局分析方法
• 进阶玩家：提供专业数据支持，优化决策过程，提升竞技水平
• 开发者：开放的API接口与模块化设计，便于二次开发与功能扩展

2. 实施路径：从环境搭建到功能验证的完整流程

2.1 环境准备阶段

2.1.1 代码仓库获取

🔧 操作：执行以下命令克隆项目代码

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

✅ 验证：成功执行后，当前目录应包含mjai/、mahjong_soul_api/等核心文件夹

2.1.2 系统环境检查

🔧 操作：检查Python环境与必要依赖

python --version
pip --version

⚠️ 注意：确保Python版本不低于3.7，pip版本不低于20.0.0

2.2 安装执行阶段

2.2.1 Windows平台部署

🔧 操作：在管理员PowerShell中执行安装脚本

scripts\install_akagi.ps1

⚠️ 注意：若出现权限提示请选择"是"，安装过程需保持网络畅通

2.2.2 macOS平台部署

🔧 操作：在终端执行自动化安装

bash scripts/install_akagi.command

✅ 验证：脚本执行完成后应显示"环境配置成功"提示

2.3 资源配置与验证

2.3.1 AI模型部署

🔧 操作：

1. 将下载的AI模型文件放置于mjai/bot/目录
2. 重命名模型文件为"mortal.pth"
3. 检查文件权限确保可读

✅ 验证：执行以下命令检查模型文件

ls -l mjai/bot/mortal.pth

💡 提示：模型文件建议通过官方渠道获取，第三方模型可能存在兼容性问题

2.3.2 基础功能测试

🔧 操作：运行基础测试命令

python simple_client.py

✅ 验证：程序应正常启动并显示"客户端初始化成功"信息

3. 场景应用：五大核心功能的实战价值

3.1 智能决策引擎

3.1.1 功能描述

系统自动捕获当前手牌、剩余牌池与对手行为数据，通过内置算法生成最优操作建议。AI决策过程综合考虑场况风险与胡牌概率，提供符合当前局势的策略推荐。

3.1.2 适用场景

• 竞技匹配中的关键决策点
• 复杂牌型的听牌选择
• 逆风局的风险控制策略

3.1.3 配置建议

通过修改config.json中的"risk_level"参数调整策略保守程度：

• 低风险（1-3）：适合分数领先时保持优势
• 中风险（4-6）：平衡进攻与防守的常规模式
• 高风险（7-10）：适合逆风局追分或比赛关键时刻

3.1.4 新手适配建议

初学者建议将"risk_level"设为3-4，优先学习基础策略，随着经验积累逐步提高风险等级。

最佳实践：定期分析AI推荐与实际决策的差异，建立个人策略库，逐步减少对AI的依赖。

3.2 实时数据采集系统

3.2.1 功能描述

工具通过协议解析技术记录每局的打牌顺序、杠碰吃操作与分数变化，数据以JSON格式实时存储，为后续分析提供基础。

3.2.2 适用场景

• 个人打牌风格分析
• 对手行为模式研究
• 牌局复盘与战术优化

3.2.3 配置建议

修改mahjong_soul_api/ms/rpc.py中的回调函数，可自定义：

• 数据采集频率（建议设为200ms/次）
• 存储字段与格式
• 异常情况处理机制

3.2.4 新手适配建议

新手可先使用默认配置，熟悉数据采集流程后，逐步增加采集字段，深入了解牌局数据背后的战术意义。

最佳实践：每周至少复盘3-5局关键比赛，结合采集数据进行战术分析与总结。

3.3 个性化配置中心

3.3.1 功能描述

通过编辑项目根目录的config.json文件，用户可灵活调整系统各项参数，打造个性化辅助体验。

3.3.2 适用场景

• 界面显示风格定制
• 功能模块开关控制
• 性能与体验平衡调整

3.3.3 核心配置项说明

• "account_bind"：雀魂账号绑定参数
• "analysis_frequency"：AI分析频率（建议200-500ms/次）
• "ui_style"：界面显示风格（simple/professional/teaching）
• "notification_method"：提示方式（sound/visual/both）

3.3.4 参数调整影响

• 提高分析频率会增加系统资源占用，但决策响应更及时
• 专业模式界面提供更多数据，但可能分散注意力
• 教学模式适合新手，但会增加屏幕信息量

最佳实践：根据设备性能与个人习惯，建立2-3套配置方案，针对不同场景快速切换。

3.4 多模式交互界面

3.4.1 功能描述

提供三种操作模式满足不同场景需求，适应从新手到专业玩家的全阶段使用需求。

3.4.2 模式对比与适用场景

• 极简模式：仅显示核心决策建议，适合比赛或专注游戏时使用
• 专业模式：展示完整概率分析图表，适合学习研究与技术提升
• 教学模式：附带策略解释与牌理说明，适合新手入门学习

3.4.3 模式切换方法

通过快捷键Ctrl+M（Windows）或Cmd+M（macOS）快速切换界面模式，或在settings.json中设置默认启动模式。

3.4.4 新手适配建议

新手建议从教学模式开始，逐步熟悉各项指标含义后过渡到专业模式，比赛时可使用极简模式保持专注。

最佳实践：根据游戏阶段灵活切换模式，如起手阶段使用专业模式分析牌型，中局阶段切换至极简模式保持专注。

3.5 协议解析与适配模块

3.5.1 功能描述

自动适配雀魂游戏的协议更新，通过liqi_proto/liqi.proto定义的接口规范，确保在游戏版本更新后仍能保持功能完整性。

3.5.2 技术原理

系统通过定期检查协议版本，自动下载更新proto文件并重新生成解析代码，确保与游戏服务器保持通信兼容。

3.5.3 配置建议

在settings.json中设置协议自动更新频率：

• "protocol_update_check": true（启用自动检查）
• "update_interval": 86400（每日检查一次，单位：秒）

3.5.4 新手适配建议

建议保持默认自动更新配置，避免因协议版本不匹配导致功能异常。

最佳实践：游戏大版本更新后，主动执行一次手动更新检查，确保协议解析模块正常工作。

4. 问题解决：系统故障的诊断与排除

4.1 启动时证书错误

4.1.1 现象描述

程序启动后提示"SSL certificate verify failed"，无法建立安全连接。

4.1.2 原因链分析

1. 系统证书库中缺少必要的根证书
2. 安装脚本未正确执行证书导入步骤
3. 网络环境限制导致证书更新失败

4.1.3 前置检查项

• 确认网络连接正常
• 检查系统日期时间是否准确
• 验证安装脚本是否完整执行

4.1.4 解决方案

🔧 操作：重新安装证书

python -m certifi

💡 提示：若问题持续，可手动导入项目目录中的证书文件：

# Windows
certutil -addstore -f "Root" common/cert.pem

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain common/cert.pem

4.2 AI分析无响应

4.2.1 现象描述

游戏中未显示决策建议，AI分析模块无输出。

4.2.2 原因链分析

1. AI模型文件不存在或损坏
2. 模型加载路径配置错误
3. 系统资源不足导致模型加载失败
4. 依赖库版本不兼容

4.2.3 前置检查项

• 检查mjai/bot/目录是否存在mortal.pth文件
• 查看终端输出是否有"model loaded"提示
• 确认系统内存是否充足（建议至少8GB）

4.2.4 解决方案

🔧 操作：执行以下步骤修复

# 检查模型文件
ls -l mjai/bot/mortal.pth

# 修复依赖
pip install -r requirement.txt --upgrade

# 验证模型加载
python -c "from mjai.bot.model import load_model; load_model('mjai/bot/mortal.pth')"

⚠️ 注意：若提示模型文件损坏，需重新下载模型并确保文件完整性

4.3 网络连接失败

4.3.1 现象描述

提示"无法连接到游戏服务器"，无法正常登录或同步数据。

4.3.2 原因链分析

1. 网络连接问题或防火墙限制
2. 代理设置配置错误
3. 游戏服务器维护或临时故障
4. 协议版本不匹配

4.3.3 前置检查项

• 检查网络连接是否正常
• 确认防火墙是否允许程序访问网络
• 测试游戏官方客户端是否能正常连接

4.3.4 解决方案

🔧 操作：测试网络连通性并检查配置

# 测试网络连通性
curl -I https://majsoul.union-game.com

# 检查配置文件
cat config.json | grep -A 5 "network"

💡 提示：若使用代理，确保config.json中的"proxy"配置正确，格式为"http://ip:port"

4.4 环境隔离建议

4.4.1 安全使用基础

为确保账号安全与系统稳定性，建议采取以下环境隔离措施：

4.4.2 虚拟环境配置

🔧 操作：创建并使用Python虚拟环境

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install -r requirement.txt

4.4.3 防检测配置

在settings.json中启用安全保护功能：

• "anti_detection": true（启用反检测机制）
• "random_delay": true（启用随机操作延迟）
• "delay_range": [300, 800]（设置300-800ms随机延迟）

4.4.4 使用时间管理

• 避免连续使用超过2小时
• 定期重启程序，清除运行痕迹
• 不同账号使用不同配置文件，避免交叉影响

最佳实践：建立独立的游戏辅助环境，与日常工作环境隔离，降低安全风险。