麻将 Copilot / Mahjong Copilot

麻将 AI 助手，基于 mjai (Mortal模型) 实现的机器人。会对游戏对局的每一步进行指导。现支持雀魂三人、四人麻将。

加入QQ群：1031865144
点击加入Discord

Mahjong AI Assistant for Majsoul，基于mjai（Mortal模型）机器人实现。当你在Majsoul游戏中时，AI会为你提供逐步指导。目前支持Majsoul三麻和四麻模式。

下载、帮助和更多信息请访问网站 请查看网站获取下载、帮助及其他信息
帮助信息 Help Info | https://mjcopilot.com

---

特性：

• 对局每一步 AI 指导，可在游戏中覆盖显示
• 自动打牌，自动加入游戏
• 多语言支持
• 支持本地 Mortal 模型和在线模型，支持三麻和四麻

Features:

• Step-by-step AI guidance for the game，with optional in-game overlay.
• Auto play & auto joining next game
• Multi-language support
• Supports Mortal local models and online models，3p and 4p mahjong modes.

使用方法 / Instructions

开发

1. 克隆 repo
2. 安装 Python 虚拟环境。Python 版本推荐 3.11.
3. 安装 requirements.txt 中的依赖。
4. 安装 Playwright + Chromium
5. 主程序入口: main.py

To Develope

1. Clone the repo
2. Install Python virtual environment. Python version 3.11 recommended.
3. Install dependencies from requirements.txt
4. Install Playwright + Chromium
5. Main entry: main.py

示例脚本 Sample script：

git clone https://github.com/latorc/MahjongCopilot.git
cd MahjongCopilot
python -m venv venv
CALL venv\Scripts\activate.bat
pip install -r requirements.txt
set PLAYWRIGHT_BROWSERS_PATH=0
playwright install chromium
python main.py

配置模型

本程序支持几种模型来源。其中，本地模型（Local）是基于 Akagi 兼容的 Mortal 模型。要获取 Akagi 的模型，请参见 Akagi Github 的说明。

Model Configuration

This program supports different types of AI models. The 'Local' Model type uses Mortal models compatible with Akagi. To acquire Akagi's models, please refer to Akagi Github .

截图 / Screenshots

界面 / GUI

游戏中覆盖显示 (HUD）/ In-game Overlay (HUD)

设计 / Design

目录说明 Description for folders：

• gui: tkinter GUI 相关类 / tkinter GUI related classes
• game: 雀魂游戏相关类 / classes related to Majsoul game
• bot: AI 模型和机器人实现 / implementations for AI models and bots
• common: 共同使用的支持代码 commonly used supporting code
• libriichi & libriichi3p: 编译完成的 libriichi 库文件 / For compiled libriichi libraries

鸣谢 / Credit

• 基于 Mortal 模型和 MJAI 协议 Based on Mortal Model an MJAI protocol

  Mortal: https://github.com/Equim-chan/Mortal

• 设计和功能实现基于 Akagi Design and implementation based on Akagi

  Akagi: https://github.com/shinkuan/Akagi

• 参考 Reference Mahjong Soul API: https://github.com/MahjongRepository/mahjong_soul_api

• MJAI协议参考 / MJAI Protocol Reference

  MJAI: https://mjai.app

许可 / License

本项目使用 GNU GPL v3 许可协议。
协议全文请见 LICENSE

MahjongCopilot 快速上手指南

MahjongCopilot 是一款基于 Mortal 模型（mjai 协议）的麻将 AI 助手，专为雀魂（Majsoul）设计。它支持三人及四人麻将模式，提供实时对局指导、自动打牌及游戏内覆盖显示（HUD）功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows / Linux / macOS
• Python 版本：推荐 Python 3.11
• 前置依赖：
  • Git（用于克隆代码库）
  • Playwright 及 Chromium 浏览器内核（用于自动化控制浏览器）

国内加速建议：

• 安装 Python 依赖时，建议使用清华或阿里镜像源以提升下载速度。
• 安装 Playwright 浏览器内核时，若官方源连接缓慢，可配置国内镜像环境变量。

安装步骤

请按照以下步骤在本地部署项目：

1. 克隆项目仓库

   git clone https://github.com/latorc/MahjongCopilot.git
   cd MahjongCopilot
   

2. 创建并激活虚拟环境

   python -m venv venv
   # Windows 系统
   CALL venv\Scripts\activate.bat
   # Linux/macOS 系统
   source venv/bin/activate
   

3. 安装 Python 依赖 （推荐使用国内镜像源）

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

4. 安装 Playwright 及 Chromium

   # 设置浏览器下载路径为当前目录（可选，避免默认路径权限问题）
   set PLAYWRIGHT_BROWSERS_PATH=0
   # 安装 Chromium 内核
   playwright install chromium
   

   注：若 playwright install 下载失败，请尝试配置 PLAYWRIGHT_DOWNLOAD_HOST 环境变量指向国内镜像。

基本使用

1. 启动程序

在激活虚拟环境的终端中运行主程序：

python main.py

2. 配置 AI 模型

程序启动后，需在图形界面或配置文件中选择模型来源：

• 在线模型：直接调用云端服务，无需额外下载。
• 本地模型：基于 Akagi 兼容的 Mortal 模型。
  • 如需使用本地模型，请访问 Akagi Github 下载对应的模型文件，并按说明放置到指定目录。

3. 开始对局

• 登录雀魂网页版。
• 程序将自动识别游戏窗口，并提供实时出牌建议（可在游戏中以 HUD 形式覆盖显示）。
• 开启“自动打牌”或“自动加入下一局”功能后，AI 将接管操作。

---

更多详细设置、多语言切换及高级功能，请访问官网：https://mjcopilot.com/help