川麻AI出牌助手：基于向听数与安全度评估的实战策略解析

1. 项目概述：一个为川麻玩家设计的AI出牌助手

如果你是一位四川麻将（川麻，血战到底）的爱好者，肯定有过这样的纠结时刻：手里捏着一把牌，感觉听牌遥遥无期，或者好不容易听牌了，却不知道打哪张最安全、听口最宽。更头疼的是，面对对手打出的牌，总在犹豫要不要碰、要不要杠，生怕一个错误的决定就点了“大炮”。现在，一个名为sceneun1ty/mahjong-ai的开源项目，试图用人工智能来解决这些痛点。它本质上是一个川麻AI出牌助手，核心功能非常简单直接：你拍一张手牌的照片，它在一秒内就能给你最优的出牌建议。

这个项目不仅仅是一个简单的规则计算器。它融合了计算机视觉（识别麻将牌）、麻将理论算法（向听数计算、听牌分析）以及实战策略（安全度评估、对手预测），旨在成为你口袋里的“军师”。无论是刚入门的新手，想快速理解牌效和防守；还是有一定基础的玩家，希望在复杂局面下获得数据支持，这个工具都能提供实实在在的帮助。它的运行不依赖于复杂的服务器或高昂的硬件，你可以通过命令行直接使用其分析引擎，也可以将其作为技能集成到像OpenClaw这样的AI助手平台中，通过聊天软件随时随地调用。

接下来，我将从一个开发者和麻将爱好者的双重角度，为你深度拆解这个项目的设计思路、核心算法、使用方式以及背后的麻将理论。你会发现，将AI应用于传统棋牌游戏，远不止是“算得快”那么简单，其中涉及大量对游戏本质的理解和策略建模。

1.1 核心需求与设计目标解析

为什么是四川麻将？川麻（血战到底）以其节奏快、番型多样、策略独特而深受欢迎，但其规则也带来了特有的决策复杂度。项目作者精准地抓住了川麻玩家的几个核心痛点：

第一，效率与安全的平衡。川麻没有“吃”，只能“碰”和“杠”，这导致牌型组合的灵活性相对日麻较低，更容易出现“卡死”的情况。因此，如何快速向听牌推进（效率），同时避免打出危险牌点炮（安全），是每巡决策的关键。AI需要能够量化这两者。

第二，血战到底规则下的特殊策略。一人胡牌后游戏继续，直到三人胡牌或牌墙摸完。这意味着即使你暂时无法胡牌，也要极力避免放炮，尤其是点给尚未胡牌的玩家。AI的“安全评分”功能正是为此而生。

第三，开局阶段的独特决策。“定缺”是川麻的标志性规则，开局必须宣告一门不要的花色。选择定缺哪一门，以及定缺后“换三张”时换哪三张牌，极大地影响了整局牌的走向。这些开局策略往往是经验性很强的，AI可以通过概率计算提供数据参考。

基于这些痛点，项目的设计目标非常明确：

1. 极速响应：分析必须在秒级完成，以适应牌桌实时决策。
2. 高准确度：牌面识别、向听数计算、听牌分析必须绝对可靠。
3. 策略全面：覆盖从定缺、换三张、中盘攻防到终盘防守的全流程。
4. 易于接入：既可作为独立工具使用，也能轻松集成到日常使用的通讯软件中。

项目通过分层架构实现了这些目标：底层是麻将规则引擎，负责所有逻辑计算；中间层是策略评估器，结合效率与安全给出综合建议；上层是交互接口，支持文本输入和未来的视觉识别。这种设计使得核心算法保持纯净，而交互方式可以灵活扩展。

2. 核心算法与麻将理论深度拆解

这个AI的“大脑”是其分析引擎（mahjong_analyze.py）。要理解它的建议为何可信，我们需要深入其算法核心。这不仅仅是编程，更是对麻将数学模型的深刻应用。

2.1 向听数计算：衡量手牌进度的标尺

“向听数”是麻将AI最基础也是最核心的概念。它表示当前手牌距离听牌（再进一张有效牌即可胡牌的状态）还差几步。川麻标准手牌是13张，胡牌时需要14张构成特定的组合（如顺子、刻子、将牌）。向听数就是从13张到听牌状态所需要替换的牌的最小张数。

项目的算法实现，通常基于“标准型”分解法。它会遍历手牌所有可能的分解方式（将牌、顺子、刻子、搭子的组合），寻找使得未完成部分（搭子、单张）数量最少的分解。向听数就等于这些未完成部分的数量减1。例如，一手牌分解后，有一个完整的顺子（3张），一个完整的刻子（3张），一个将牌对子（2张），还剩下一个两面搭子（2张，如4万5万）和一个单张。那么未完成部分就是1个搭子和1个单张，共2个部分，向听数就是1（即再进1张有效牌就能听牌）。

注意：向听数计算是NP难问题，但得益于川麻只有108张牌（万、筒、条各36张），且无字牌，搜索空间相对较小。项目采用了高效的动态规划或回溯算法，才能在毫秒内完成计算。在实际代码中，你会看到它预先计算了所有可能的牌型组合与向听数的映射表，通过查表加速，这是工程上的常见优化。

2.2 听牌分析与待牌数计算：量化胡牌概率

知道向听数后，下一步就是分析如果打掉某张牌，手牌会进入怎样的听牌状态，以及这个状态的“好坏”。这就是听牌分析模块的工作。

1. 枚举有效进张：对于打掉候选牌A后的新牌型，算法会模拟摸入剩下的所有牌（约108-已出牌-手牌），判断哪些牌能使手牌向听数减少。这些牌就是“有效进张”。

2. 计算待牌种类与剩余枚数：确定听牌后，算法会进一步计算具体“听”哪些牌。例如，听5、8筒两面。然后，它需要去检查牌墙和已出牌中，这些待牌还剩下多少张。这是关键！听5、8筒虽然有两门，但如果河里已经见了3张5筒和2张8筒，实际剩余枚数可能只有1-2张，胡牌概率大打折扣。

3. 评估听牌宽度与质量：项目输出的“听5张最多”，就是综合了待牌种类数和剩余枚数后的直观体现。它不仅告诉你听几张牌，还隐含了这些牌在牌墙中的存量。一个听3门但每门剩4张的牌（共12张），远比听6门但每门只剩1张的牌（共6张）更容易胡。

2.3 安全度评估模型：从“读牌”到数据化

防放炮是川麻的精髓。AI的安全评估模型，可以看作是将高手的“读牌”经验数据化、概率化。

1. 基于牌河的危险度推断：这是基础模型。如果对手打过一张7万，那么他手牌中包含6万、7万、8万、9万顺子的可能性就大大降低，因此这些牌的安全度会相对提高。尤其是“现物”（对方打过的牌的同牌）是绝对安全的。算法会遍历所有对手的牌河，为每一张未出现的牌赋予一个基础危险分数。

2. 基于牌效的进阶预测：更高级的模型会尝试推测对手的手牌构成。例如，对手连续打出中张牌（4、5、6万），而早期打出边张（1、9万），这可能意味着他在做“断幺”或手牌结构偏向某一花色。AI的“对手预测”模式就在做这件事：通过分析对手的舍牌序列，结合麻将牌效理论，模拟出对手可能的手牌组合，从而预测他可能不要什么牌（安全），急需什么牌（危险）。

3. 安全与效率的权衡算法：AI给出的最终推荐，是“效率分”和“安全分”加权综合的结果。例如，打A牌能听一个宽口（效率分90），但属于中度危险牌（安全分40）；打B牌只能听一个窄口（效率分60），但是绝对安全牌（安全分100）。最终的推荐排序，就取决于权重如何设置。项目示例中的🟢🟡🔴标签，正是这种综合评分的可视化体现。一个注重进攻的玩家可以调高效率权重，一个保守的玩家则可以调高安全权重。

3. 从安装到实战：完整使用指南与避坑要点

了解了原理，我们来看看如何真正用起来。项目提供了两种主要使用方式：作为独立的Python脚本运行，或者作为OpenClaw技能在聊天软件中使用。这里我们重点讲解更通用、更透明的独立脚本方式。

3.1 环境准备与独立脚本运行

首先，你需要一个Python环境（建议3.8以上）。由于项目核心是纯逻辑计算，不涉及复杂的深度学习框架，依赖非常轻量，通常只需要标准库。

# 1. 克隆项目代码 git clone https://github.com/sceneun1ty/mahjong-ai.git cd mahjong-ai # 2. 查看脚本帮助，了解所有参数 python3 scripts/mahjong_analyze.py --help

运行分析的核心命令格式如下：

python3 scripts/mahjong_analyze.py --hand “你的手牌” --discard “已出牌河”

这里的关键是牌的张数和编码格式。

关于手牌张数的重要规则：

• 当你需要出牌建议时，--hand参数应提供14张牌。因为这模拟了你摸进一张牌后，需要打出一张牌的状态。AI会分析打掉14张中的哪一张最好。
• 当你需要定缺建议或换三张建议时，--hand参数应提供13张牌。因为这是开局抓完牌后，尚未摸第一张牌的状态。

编码格式详解：项目使用一套简洁的编码系统，你必须严格遵守：

• 1m代表一万（m来自“万”的拼音“wan”的声母？更常见的记忆法是“m”像“万”字的下半部分？实际上，这是国际麻将通用编码“man”的缩写）。
• 5p代表五筒（p来自“筒”的拼音“tong”的声母？不对，这是“pin”的缩写，源自日语“ピンズ”）。
• 9s代表九条（s来自“条”的拼音“tiao”的声母？不对，这是“sou”的缩写，源自日语“ソウズ”）。

实操心得：这套编码（m/p/s）最初源于日本麻将记谱方式，因其简洁而在国际麻将社区和编程中被广泛采用。对于中国玩家，一个快速的记忆法是：m（万）、p（筒，想象成圆点“Point”）、s（条，想象成竹子“Stick”）。输入时，牌与牌之间用英文逗号分隔，不要有空格。

让我们运行一个完整的例子。假设你手上有14张牌：一万、二万、三万、五万、五万、三筒、四筒、七筒、八筒、九筒、二条、三条、四条、六条。牌河里已经出现过1筒、2筒、5筒、5筒、9条、9条。

对应的命令就是：

python3 scripts/mahjong_analyze.py \ --hand “1m,2m,3m,5m,5m,3p,4p,7p,8p,9p,2s,3s,4s,6s” \ --discard “1p,2p,5p,5p,9s,9s”

3.2 解读AI的输出报告

运行上述命令后，你会得到类似示例的输出。我们来逐行解读：

🀄 手牌（14张）：[万] 1万 2万 3万 5万 5万 [筒] 3筒 4筒 7筒 8筒 9筒 [条] 2条 3条 4条 6条

AI首先将你杂乱输入的手牌按花色整理并翻译成中文，非常直观。这步验证了输入是否正确。

🗑️ 场上已出（6张）

确认了它识别到的已出牌。

🎯 出牌建议： ========================================================= ⭐ 打 6条 🟡40 → 听 2筒(3) 5筒(2) (5张) 打 5万 🟡55 → 听 5筒(3) (3张) 打 1万 🟢60 → 1向听

这是核心建议部分。

• ⭐ 打 6条：这是AI的首选推荐。🟡40是一个综合评分（可能是效率与安全的加权分，40分意味着有一定风险但效率尚可）。→ 听 2筒(3) 5筒(2) (5张)是打掉6条后的结果：你将听2筒和5筒，其中2筒还剩3张，5筒还剩2张，总计有效待牌5张。这是一个“两面听”的宽口。
• 打 5万：次选方案。评分🟡55稍高，但听牌结果听 5筒(3) (3张)显示只听一门5筒（单调将），且只剩3张，待牌数仅3张，效率低于方案一。
• 打 1万：第三方案。评分🟢60最高（绿色表示安全），但结果1向听意味着打掉1万后并未听牌，只是向听数减少为1。这是一个纯粹的防守型打法。

结论：AI认为当前局面下，打6条进攻性最强（听5张），虽然有一定风险（黄灯），但综合收益最高。如果你判断场上有人可能听牌，且6条是危险张，那么可以选择更安全的打1万（放弃听牌，确保不放炮）。

3.3 开局策略：定缺与换三张的AI思路

川麻开局阶段的决策影响深远。项目提供了专门的分析模式。

定缺分析 (--mode dingque)：输入开局13张手牌。

python3 scripts/mahjong_analyze.py --hand “1m,3m,5m,2p,3p,4p,5p,7p,8p,1s,2s,9s,9s” --mode dingque

AI会分析你手牌中万、筒、条三门的牌型结构。它的建议逻辑通常是：

1. 数量最少的花色：这是最直观的，缺一门意味着你要打掉该花色所有牌，数量越少成本越低。
2. 结构最差的花色：如果两门数量接近，则看哪一门的牌更“散”，更难以形成搭子。例如，一门是1、5、9万，另一门是3、4、5筒，显然前者更差。
3. 避免定缺“有对子”的花色：对子是宝贵的资源，用于做将或杠。定缺有对子的花色意味着你必须拆对，损失较大。

换三张策略 (--mode swap3)：定缺后，你需要与其余三家各交换一张牌（共换出三张，换入三张）。AI在此模式下的目标是：换出你定缺花色中价值最低的牌，并期望换入能优化你保留花色结构的牌。虽然换入什么是随机的，但换出什么是可控的。AI会建议换出哪三张，通常是定缺花色中孤张、边张、无法与你保留花色形成有效关联的牌。

4. 项目架构、扩展性与实战问题排查

4.1 项目工程结构解读

项目的目录结构清晰，体现了良好的模块化思想：

mahjong-ai/ ├── SKILL.md # OpenClaw技能定义文件 ├── DEVLOG.md # 中文开发日志（非常有价值！） ├── scripts/ │ └── mahjong_analyze.py # 核心分析引擎（约460行） ├── references/ # 理论参考资料 │ ├── mahjong_theory.md # 川麻理论与策略 │ └── tile_visual_guide.md # 麻将牌视觉识别指南 └── README.md # 项目总览

• mahjong_analyze.py是心脏，所有算法逻辑集中于此。阅读这个文件，你可以学到如何用代码实现向听数计算、听牌枚举等核心功能。
• references/目录是项目的“知识库”。mahjong_theory.md很可能包含了项目所依据的牌效理论、安全评估公式，是理解AI决策依据的钥匙。tile_visual_guide.md则为未来扩展拍照识别功能提供了数据基础（每张牌的标准图像特征）。
• DEVLOG.md记录了开发过程中的思考、尝试和遇到的坑，对于想自己动手实现类似项目的人来说，是极佳的学习材料。

4.2 如何集成到OpenClaw与未来扩展

项目作为OpenClaw Skill的设计，大大提升了其实用性。OpenClaw是一个允许你为AI助手（如Claude）创建自定义技能的平台。集成后，你可以在WhatsApp、Telegram等软件中，直接向助手发送麻将桌照片，并收到分析结果。这个过程涉及：

1. 图像上传：用户发送照片。
2. 视觉识别：OpenClaw调用项目的视觉识别模块（待开发或集成第三方服务）将图片转换为牌面编码字符串。
3. 调用分析引擎：将编码字符串传入mahjong_analyze.py的核心函数。
4. 格式化返回：将分析结果转换成易读的文本或图片，返回给用户。

从Roadmap看，作者雄心勃勃，计划支持日麻、港麻、国标等多种规则。这需要重构核心引擎，因为不同规则的胡牌牌型、番种计算、甚至向听数定义都不同。一个可行的架构是设计一个“规则抽象层”，将通用逻辑（如手牌表示、基本组合判断）与特定规则（番种、役种、特殊规则）解耦。

4.3 常见问题与排查技巧实录

在实际使用中，你可能会遇到一些问题。以下是我在测试和类似项目中总结的经验：

问题1：运行脚本时报编码错误或牌面无法识别。

• 排查：首先检查你的命令行环境是否支持UTF-8编码（输出中的麻将符号和中文需要）。其次，严格检查输入格式：是否用了中文逗号？牌与牌之间是否有空格？花色编码m/p/s是否用小写？例如，“1m, 2m”（逗号后有空格）可能导致解析失败。
• 解决：确保输入是纯英文逗号分隔的无空格字符串。在终端中，使用引号包裹整个字符串参数。

问题2：AI的建议与我的直觉或另一位高手的判断不符。

• 排查：这通常有几个原因。第一，已出牌 (--discard) 信息不完整。AI的安全评估极度依赖牌河信息。如果你只输入了部分已出牌，它的危险判断会失准。第二，AI的权重偏好。项目可能内置了一套固定的效率/安全权重。你的策略可能更激进或更保守。第三，特殊场况未考虑。例如，你是“庄家”或已有人“下雨”（杠），AI的通用模型可能未加权这些因素。
• 解决：尽可能输入完整的已出牌信息。理解AI的建议是“基于当前输入数据的数学最优解”，而人的直觉包含了更多场外信息（对手风格、牌局阶段、点数差）。将AI建议作为重要的数据参考，而非绝对命令。

问题3：定缺或换三张的建议看起来“很奇怪”。

• 排查：定缺建议基于纯数学期望，它追求的是“使剩下两门牌的平均向听数最优”。但有时，保留一门虽然张数多但结构极差的牌，不如保留张数少但结构好（如已有搭子、对子）的牌。AI的算法可能过于看重数量。
• 解决：不要盲目跟随定缺建议。结合你的打牌风格：如果你擅长做“清一色”，即使某门牌少但有两三个对子，也可能值得保留。AI提供的是一个基线，最终决策需要融入你的战略意图。

问题4：想修改AI的进攻/防守倾向。

• 深入：这需要你阅读源代码，找到评估函数。通常有一个类似calculate_score(efficiency, safety)的函数，其中efficiency和safety是两个0-100的分数。最终的排序得分可能是efficiency * alpha + safety * beta。你可以尝试调整alpha和beta的系数（例如，alpha=0.7, beta=0.3更进攻；alpha=0.3, beta=0.7更防守），然后重新测试。

这个项目最宝贵的价值在于，它把一个依赖大量经验的游戏决策过程，拆解成了可量化、可分析的数学模型。无论你是否完全采纳它的建议，通过观察和分析它的计算过程，你都能极大地深化自己对麻将牌效、形状和风险管理的理解。它就像一位不知疲倦、绝对理性的陪练，帮助你从“凭感觉打牌”向“用数据辅助决策”迈进。