Akagi机器人插件接口完全参考：mjai协议、manifest配置与meta HUD详解

Akagi机器人插件接口完全参考mjai协议、manifest配置与meta HUD详解【免费下载链接】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/AkagiAkagi 是一款支持雀魂、天鳳、麻雀一番街、天月麻將的实时麻将 AI 助手它的机器人插件接口允许你接入任意自定义 AI 模型在对局中实时分析并给出建议。本文将系统讲解 Akagi 机器人插件接口的三大核心基于mjai 协议的进程通信、manifest.toml的配置体系以及meta HUD的数据渲染机制帮助新手开发者快速上手编写自己的麻将 AI 机器人。上图是 Akagi 的完整对局分析界面右侧的「Bot 狀態」面板显示 AI 运行状态与积分「AI 推薦」区域给出每一步的推荐动作与概率这就是机器人通过 meta HUD 与前端交互的直观呈现。一、Akagi 机器人插件机制速览Akagi 的机器人是独立子进程Akagi 通过简单的行式 JSON 协议JSONL与它通信——把实时对局以 mjai 事件流喂给机器人机器人回复它想执行的动作并可选附带 HUD 展示数据。每个机器人占据mjai_bot/下的一个独立目录目录结构如下mjai_bot/name/ ├── bot.py # 入口文件 —— 负责与 Akagi 通信 ├── pyproject.toml # Python 依赖声明requires-python 3.12 ├── manifest.toml # 可选 —— UI 元数据 设置项模式 ├── settings.toml # 可选 —— 当前设置值运行时由 Akagi 写入 └── README.md # 机器人专属说明其中pyproject.toml有两条必须遵守的规则否则uv sync会失败[project] requires-python 3.12 # Akagi 内置 Python 3.12 [tool.uv] package false # 机器人是脚本而非可安装库完整的参考实现见 example/ 目录其 example/pyproject.toml 是经过验证的可直接照抄的模板。二、mjai 协议详解一行 JSON 的博弈Akagi 的机器人插件接口使用mjai 协议通信双方遵循严格的一问一答规则。2.1 I/O 协议stdin 进stdout 出Akagi 每局对局启动一次bot.py通过 stdin/stdout 通信每行一个 JSON 值stdin → 机器人一个 JSON数组一批 mjai 事件每次请求时一次性推入机器人 → stdout恰好一个JSON 反应对象例如{type:none}。stdin → [{type:tsumo,actor:2,pai:5p}] stdout ← {type:dahai,actor:2,pai:1m,tsumogiri:false}核心规则每行输入必须回复恰好一个反应多打或少打都会导致协议失步stdout 只能输出协议 JSON日志和诊断请写到 stderrAkagi 会以botname标签收录进应用日志{type:none}是轮不到我时的标准回复——机器人仍会看到所有事件以维护内部状态只是放弃行动收到end_game后回复一次并干净退出反应预算约 5 秒超时会被 Akagi 强制终止。一个最小可运行的循环只有十几行import json, sys def react(events: list[dict]) - dict: # 检查事件、更新状态、做出决策…… return {type: none} for line in sys.stdin: events json.loads(line.strip()) sys.stdout.write(json.dumps(react(events)) \n) sys.stdout.flush() if any(e.get(type) end_game for e in events): break2.2 座位信息三种获取方式机器人的座位actor_id0–3有三种传递途径推荐以start_game.id为准命令行参数python bot.py player_id兼容 mjai.app 约定未修改的 mjai.app 机器人可直接运行环境变量AKAGI_PLAYER_IDstart_game.id字段第一局事件上的id是权威来源。2.3 mjai 事件流完整事件速查表Akagi 遵循mjai 协议权威且最新的事件定义在 src/schema/mjai/mod.rs 的MjaiEvent枚举中。常用事件一览type关键字段说明start_gamenames、id你的座位、num_players、aka_flag首个事件start_kyokubakaze、kyoku、honba、oya、dora_marker、scores、tehais一局开始tehais[seat]为配牌tsumoactor、pai摸牌dahaiactor、pai、tsumogiri出牌chi/ponactor、target、pai、consumed[2]吃 / 碰daiminkanactor、target、pai、consumed[3]大明杠kakanactor、pai、consumed[3]加杠ankanactor、consumed[4]暗杠doradora_marker新宝牌指示牌reach/reach_acceptedactor立直宣言 / 立直成立horaactor、target、deltas?、ura_markers?和牌ryukyokudeltas?流局kitaactor、pai?三麻专用北end_kyoku/end_game—一局结束 / 整场结束退出牌串格式使用 mjai 记法1m~9m万、1p~9p筒、1s~9s索字牌ESWN风牌与PFC白发中赤五是后缀r如5mr未知牌为?。2.4 反应格式机器人如何回应反应就是一个 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} // 荣和 / 自摸三、manifest.toml 配置完整指南manifest.toml是机器人的设置说明书它声明机器人的元数据并定义用户在Bots标签页里可以调整的参数。一个完整的示例manifest_version 1 [bot] name my-bot # 应与文件夹名一致 display My Bot # 机器人选择器中的显示名 description 一句话描述。 version 0.1.0 supported_modes [4p, 3p] # 缺省为 [4p] [settings.temperature] type float # string | bool | int | float | enum label 采样温度 default 1.0 help 数值越高越随机。 min 0.1 max 2.0 step 0.1 [settings.api_key] type string label API 密钥 default secret true # 密码输入框日志中脱敏为 *** [settings.style] type enum label 打牌风格 default balanced choices [aggressive, balanced, defensive]3.1 设置类型速查type支持string、bool、int、float、enum五种int/float可配min、max、stepenum必须提供choices列表secret true前端渲染为密码输入框日志中脱敏为***注意值仍以明文存在settings.toml该文件已被 gitignore请视作凭据文件对待。3.2 机器人如何读取配置用户编辑设置后Akagi 把默认值 ⊕ 已保存值合并写入一个 JSON 文件并通过环境变量AKAGI_BOT_CONFIG指向它的绝对路径。机器人启动时读取即可import json, os cfg {} path os.environ.get(AKAGI_BOT_CONFIG) if path: with open(path) as f: cfg json.load(f) # {temperature: 1.0, style: balanced, ...}没有manifest.toml的机器人不会收到AKAGI_BOT_CONFIG也没有设置面板——适合无旋钮的简单机器人。设置变更不会重启正在运行的子进程新值在下一个start_game事件时生效。四、meta HUD 完全参考让 AI 的思考可见这是本篇文章的核心亮点。meta是反应对象上的可选附加字段Akagi 将其视为不透明数据原样转发给前端内容由机器人自行定义——用它来展示为什么选这张牌。4.1 meta 原始数据调试利器{type:dahai,actor:0,pai:9m,tsumogiri:false, meta:{q_values:[0.12,0.05,0.85],confidence:0.87}}任何放进meta的键都会作为原始数据显示在 HUD 的机器人响应视图中哪怕是临时字段也能用于调试。4.2 meta.show结构化 HUD 卡片要获得美观的渲染效果请填充meta.show。Akagi 的Bot ShowHUD 组件会把它渲染为一张带标题的行列表卡片候选出牌 Top-N、对手读牌、役种分析……语义由你决定{type:dahai,actor:0,pai:1m,tsumogiri:false, meta:{show:{ title:出牌候选, items:[ {label:打 1m,pais:[1m],value:85.42%,color:#00ff80,note:保持听牌}, {label:打 9p,pais:[9p],value:11.30%}, {label:立直,value:12000,color:#ffaa00} ] }}}4.3 meta.show 字段参考meta.show顶层字段类型含义titlestring?卡片标题缺省时用默认标题itemsarray每一行一条无label/tiles/pais的行会被跳过items中的每一项字段类型含义labelstring?行主文本paisstring[]?mjai 牌串数组渲染为牌图tilesstring?原始 mahgen DSL 字符串两者都设置时优先于paisvaluestring?右对齐文本任意格式如85.42%、12000colorstring?十六进制强调色如#00ff80—— 绘制为左侧色条 淡行底色notestring?label下方的小字副标题前端渲染端的实现可参考 frontend/src/components/BotShowList.tsx 与 frontend/src/lib/botShow.ts类型定义见 frontend/src/types.ts。4.4 进阶规则卡片何时更新内置机器人遵循一条黄金法则卡片只在机器人做出选择时变化其他时刻保持不变。大多数事件不是决策点对手的不可碰弃牌、不是你的摸牌此时回复{type:none}且不携带meta前端保持卡片不动避免整局闪烁放弃一次鸣牌也是一种选择在可碰可吃的窗口选择过牌时卡片必须刷新且过牌本身要作为一个候选行与 pon/chi/kan 一起排名如Pass 87% / Pon 13%——这正是屏幕上最有价值的信息。五、扩展能力toast 通知与注册流程5.1 前端 toast 通知机器人可以随时向前端推送toast 通知应用右下角弹出。它走 stderr 通道因此绝不会干扰 stdout 的协议。在 stderr 写一行如下格式即可AKAGI_NOTIFY {level:warn,title:牌山将尽,body:剩余不足8张——转攻为守。,sticky:false,id:...}字段说明levelinfo/success/warn/error必填、title必填、body可选、stickytrue 则常驻直到手动关闭、id稳定键相同 id 的新通知会替换旧通知。未带此前缀的 stderr 行照常作为诊断日志前缀后 JSON 解析失败会被丢弃并记警告。示例实现见 example/bot.py。5.2 注册机器人完整流程放入目录把机器人文件夹放到mjai_bot/name/下Akagi 在每次对局开始及打开/刷新 Bots 页时自动扫描无需重启构建环境带pyproject.toml的机器人需要点击「Install environment」执行一次uv sync可能较慢环境就绪前激活开关保持禁用避免对局中途触发慢同步激活分别开启 4 人 / 3 人模式的激活开关bot.active_4p/bot.active_3p两槽独立留空则该模式只分析不出手。机器人也可以从 GitHub Release 或本地.zip直接安装会自动构建环境详见 src/bot/README.md。结语Akagi 的机器人插件接口设计得非常克制而强大mjai 协议负责与任何语言编写的子进程通信manifest.toml把可配置项交给用户meta HUD则让 AI 的每一步决策都透明可见。无论你是想接入 Mortal 这样的深度强化学习模型还是写一个基于规则的小机器人mjai_bot/README.md 都是你最好的起点——对照 example/bot.py 这个经过验证的参考实现从零到一写出第一个 Akagi 麻将 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），仅供参考