手把手开发麻将AI为Akagi编写mjai插件机器人的完整教程【免费下载链接】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吗本教程将手把手教你为Akagi编写一个mjai插件机器人——一个独立运行的麻将AI子进程能实时读取对局、自主决策并给出建议。Akagi 是一款支持雀魂、天鳳、麻雀一番街、天月麻将的实时麻将分析工具内置 Mortal AI 作为示例而通过mjai 插件接口你完全可以开发自己的自定义 AI 模型参与分析。什么是mjai插件机器人先搞懂运行原理Akagi 的插件机器人本质是一个独立子进程Akagi 通过标准的 stdin/stdout 管道用一行一个 JSON 的JSONL 协议与它对话——把实时对局以 mjai 事件流喂给机器人机器人则回复一个动作打牌、碰、杠、立直、荣和等以及可选的 HUD 展示数据。这个设计非常巧妙机器人崩溃不影响 Akagi 主程序AI 模型可以热替换AGPL 许可的机器人也能安全接入。完整的通信协议见官方文档mjai_bot/README.md。第一步搭建机器人目录结构每个机器人独占一个文件夹放在项目根目录的mjai_bot/下mjai_bot/你的机器人名/ ├── bot.py # 入口程序负责JSONL通信 ├── pyproject.toml # 依赖声明requires-python 3.12 ├── manifest.toml # 可选——UI元数据与配置项 └── README.md # 机器人说明pyproject.toml中必须包含[tool.uv] package false否则uv sync会尝试把你的机器人构建成包而失败。可参考现成示例example/pyproject.toml。Akagi 自带 Python 3.12 运行时和 uv即使系统没有装 Python 也能运行你的机器人。第二步理解核心I/O协议最关键的一步Akagi 每局会启动一次bot.py通信规则非常简洁stdin → 机器人每行一个 JSON 数组一批 mjai 事件机器人 → stdout每行恰好一个 JSON 动作对象无动作时回复{type:none}一个最小可运行的通信循环长这样参考 example/bot.pyimport json, sys def react(events): # 分析事件、更新状态、做出决策 return {type: none} for line in sys.stdin: line line.strip() if not line: continue events json.loads(line) sys.stdout.write(json.dumps(react(events)) \n) sys.stdout.flush() if any(e.get(type) end_game for e in events): break记住三条铁律每行必须恰好回复一个动作、stdout 只输出协议 JSON日志走 stderr、看到end_game事件后回复一次并优雅退出。另外单次决策时间预算约 5 秒超时会被 Akagi 中止。第三步认识mjai事件流——机器人的感官Akagi 讲的是mjai 协议事件类型及其字段形状以 src/schema/mjai/mod.rs 中的MjaiEvent枚举为权威标准。最常用的事件有事件类型含义关键字段start_game对局开始id你的座位、names、num_playersstart_kyoku一局开始tehais配牌、dora_marker、scorestsumo摸牌actor、paidahai打牌actor、pai、tsumogirichi/pon/daiminkan吃/碰/大明杠actor、target、consumedreach立直宣言actorhora和牌actor、target、deltasend_kyoku/end_game局/场结束—牌型使用 mjai 记号1m~9m是万子5p是筒子ESWN是风牌红宝牌带r后缀如5mr未知牌是?。第四步输出动作与HUD数据——机器人的手脚机器人的回复就是一个 mjai 动作对象常见的有{type:none} // 过 {type:dahai,actor:2,pai:1m,tsumogiri:false} // 打牌 {type:reach,actor:2} // 立直 {type:pon,actor:2,target:0,pai:1m,consumed:[1m,1m]} {type:hora,actor:2,target:0,pai:5p} // 荣和/自摸除了动作你还可以附带meta字段把为什么这么选展示到 HUD 上。其中meta.show能渲染成结构化卡片例如显示候选打牌的概率排行{type:dahai,actor:0,pai:1m,tsumogiri:false, meta:{show:{ title:Discard candidates, items:[ {label:Discard 1m,pais:[1m],value:85.42%,note:keeps tenpai}, {label:Riichi,value:12000,color:#ffaa00} ] }}}这些数据会呈现在 Akagi 的 Bot Show 面板中让玩家一眼看懂 AI 的思路。第五步用manifest.toml给机器人加配置面板想让用户在Bots标签页调整参数如温度、API Key、风格加一个manifest.toml即可manifest_version 1 [bot] name my-bot display My Bot description One-line description. version 0.1.0 supported_modes [4p, 3p] [settings.temperature] type float label Sampling temperature default 1.0 min 0.1 max 2.0支持的类型有string、bool、int、float、enumsecret true的字段会渲染为密码输入并在日志中打码。运行时Akagi 会把合并后的配置写入 JSON 文件并通过环境变量AKAGI_BOT_CONFIG指向它机器人启动时读取即可。第六步注册并运行你的麻将AI机器人放置文件夹把机器人目录放进mjai_bot/name/Akagi 在每次开局或刷新 Bots 标签页时自动扫描无需重启。安装环境若有pyproject.toml点击机器人行上的安装环境按钮执行一次uv sync可能较慢仅首次。环境就绪前启用开关保持禁用确保对局中不会临时同步。激活机器人为四麻和三麻分别选择启用的机器人active_4p/active_3p两个槽位独立。留空则只做分析不驱动对局。示例机器人 mjai_bot/example/bot.py 是一个完整的、可复制的规则型向听优化器实现了自摸和牌、暗杠、立直、最小向听数打牌等策略并演示了向 Akagi 前端发送 toast 通知stderr 中输出AKAGI_NOTIFY {...}前缀行。它是你入门的最佳参照。进阶让机器人说话——前端通知机器人还能随时向 Akagi 界面右下角弹出 toast 通知走 stderr 通道完全不影响 stdout 协议sys.stderr.write(AKAGI_NOTIFY {level:warn,title:Low wall,body:Fewer than 8 tiles left}\n)level支持info、success、warn、error非常适合提示模型加载失败、牌局告急等场景。总结从协议理解到实际部署为 Akagi 编写mjai 插件机器人的路径已经清晰搭建目录 → 理解 JSONL 通信 → 解析事件流 → 输出动作与 HUD 数据 → 配置化 → 注册运行。这套设计让任何语言实现的麻将AI都能无缝接入也让你的自定义AI模型能实时参与雀魂、天鳳等平台的牌局分析。现在就打开 mjai_bot/README.md 和示例代码开始你的第一个麻将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），仅供参考