雀魂AI助手：从入门到定制的全栈开发指南

产品定位：重新定义麻将辅助工具的技术边界

雀魂AI助手（Akagi）并非传统意义上的游戏辅助程序，而是一个构建在MITM（中间人技术）架构上的实时数据处理平台。它通过协议解析、AI决策引擎和可视化界面的有机结合，为麻将策略研究提供了完整的技术栈支持。

与同类工具相比，本项目的独特价值在于：

• 模块化设计：从网络数据捕获到策略输出的全流程可定制
• AI模型接口：预留自定义算法集成通道，支持模型热替换
• 协议兼容性：持续更新的协议解析模块确保与游戏版本同步

这个开源项目特别适合三类用户：希望优化游戏体验的玩家、研究麻将AI的算法工程师、以及对网络协议分析感兴趣的开发者。

场景矩阵：针对不同技术水平的应用图谱

快速部署场景：零基础用户的15分钟启动方案

适用场景：首次接触工具的玩家，需要快速验证核心功能
操作要点：

1. 克隆项目仓库：git clone https://gitcode.com/gh_mirrors/ak/Akagi
2. 执行对应系统的安装脚本：
   • Windows用户：运行scripts/install_akagi.ps1
   • macOS/Linux用户：执行scripts/install_akagi.command
3. 启动主程序：python main.py并按照引导完成初始配置

预期效果：程序自动启动并进入监控状态，当检测到雀魂游戏进程时自动开始数据捕获，默认界面显示基础牌局信息。

协议分析场景：开发者的网络数据解码实践

适用场景：需要理解游戏数据结构的高级用户
操作要点：

1. 启用详细日志模式：修改config.json中log_level为DEBUG
2. 启动MITM代理：运行python mitm.py --port 8080
3. 配置系统代理指向本地8080端口
4. 使用liqi.py解析捕获的协议数据：python liqi.py --file capture.log

预期效果：获得结构化的游戏数据输出，包含牌局状态、玩家行为和系统消息的完整解码结果。

AI模型集成场景：算法工程师的策略定制方案

适用场景：希望接入自定义AI模型的研究人员
操作要点：

1. 将训练好的模型文件放置于mjai/bot/目录（需符合mortal.pth格式）
2. 修改mjai/bot/model.py中的模型加载接口
3. 调整策略参数：在config.json中配置ai_thinking_depth和risk_preference
4. 启动带AI功能的客户端：python client.py --enable-ai

预期效果：自定义模型成功加载并对实时牌局做出决策，策略建议延迟控制在200ms以内。

个性化方案：基于用户角色的配置体系

核心配置框架

配置文件结构：

• 主配置：config.json（全局参数）
• 界面配置：settings.json（UI布局和显示选项）
• AI参数：mjai/bot/config.json（算法相关参数）

配置原则：

• 所有配置项支持运行时动态调整
• 通过config.py提供类型检查和默认值填充
• 支持配置文件热加载（修改后无需重启程序）

玩家配置方案

需求：平衡性能与分析精度，获得流畅的游戏体验
方案：

1. 基础设置：

   {
     "analysis_depth": 3,
     "show_probability": true,
     "interface_density": "medium"
   }
   

2. 视觉优化：在settings.json中启用深色主题
3. 性能调优：关闭background_sync选项减少网络请求

验证方法：连续进行3局游戏，确保界面响应延迟<100ms，AI建议生成时间<500ms。

开发者配置方案

需求：完整日志记录与协议分析能力
方案：

1. 开发模式启用：

   {
     "developer_mode": true,
     "log_level": "DEBUG",
     "protocol_dump": true
   }
   

2. 启动协议分析工具：python liqi.py --live
3. 配置VSCode调试环境：使用.vscode/launch.json中的预设配置

验证方法：检查logs/目录下是否生成完整的协议日志，确保每个网络包都能被正确解析。

进阶路径：从使用者到贡献者的成长体系

技术栈解析

核心模块架构：

• 网络层：基于mitmproxy的协议拦截与解析（mitm.py）
• 数据处理层：Protocol Buffers协议实现（liqi_proto/目录）
• AI引擎：PyTorch模型推理框架（mjai/bot/目录）
• UI层：Tkinter构建的桌面界面（gui.py和client.tcss）

关键技术点：

• MITM技术：通过动态证书生成实现HTTPS流量拦截
• 协议逆向：基于protobuf的二进制协议解析
• 实时推理：优化的模型结构实现低延迟决策生成

问题诊断方法论

常见问题排查流程：

1. 连接失败

   • 症状：程序启动后状态栏显示"未连接"
   • 排查步骤：
     1. 检查系统代理设置是否指向127.0.0.1:8080
     2. 验证证书信任状态：certmgr.msc（Windows）或钥匙串访问（macOS）
     3. 查看端口占用：netstat -ano | findstr 8080（Windows）或lsof -i:8080（Linux/macOS）
   • 根本原因：通常是系统安全软件阻止了代理设置或证书安装

2. 模型加载错误

   • 症状：启动时提示ModelNotFoundError
   • 排查步骤：
     1. 确认模型文件mortal.pth存在于mjai/bot/目录
     2. 检查文件权限：ls -l mjai/bot/mortal.pth
     3. 验证模型版本兼容性：查看requirements.txt中的PyTorch版本要求
   • 根本原因：模型文件缺失、权限不足或版本不兼容

贡献者成长路线

初级贡献者（1-3个月）：

• 技能目标：掌握项目基本架构和配置方法
• 实践任务：
  1. 修复文档中的错误或补充说明
  2. 提交bug报告并提供复现步骤
  3. 参与简单功能的代码审查

中级贡献者（3-6个月）：

• 技能目标：熟悉核心模块代码和协议结构
• 实践任务：
  1. 实现小型功能模块（如自定义界面组件）
  2. 优化现有算法的性能
  3. 参与协议更新适配工作

高级贡献者（6个月以上）：

• 技能目标：能够设计和实现新功能模块
• 实践任务：
  1. 开发新的AI模型集成接口
  2. 设计并实现插件系统
  3. 指导新贡献者并参与架构决策

通过这个进阶路径，你不仅能深入掌握实时数据处理和AI应用开发的核心技术，还能为开源社区贡献价值，与全球开发者共同完善这个雀魂辅助平台。记住，真正的技术提升来自于实际参与和持续迭代。