calc_cli 使用文档

概述

calc_cli 是本项目中用于国标麻将（GB Mahjong）算番和向听数计算的核心命令行工具。它集成了听牌分析（Shanten Calculator）和番数计算（Fan Calculator）功能。无论是分析一手牌的进张情况，还是计算和牌后的具体番型和分数，都可以通过此工具完成。

./calc_cli [选项] <手牌字符串>

calc_cli 使用一套特定的字符串格式来描述麻将手牌、副露（吃碰杠）以及比赛时的状态信息。

格式结构为：[手牌/副露] | [状态标志] | [花牌]

麻将牌使用数字或字母加上特定的后缀来表示。

类别	标记	示例	说明
数牌	`m`	`123m`	万子 (Man)，数字 1-9。
数牌	`s`	`456s`	索子 (Sou)，数字 1-9。
数牌	`p`	`789p`	筒子 (Pin)，数字 1-9。
字牌	`E`、`S`、`W`、`N`	`EEESS`	东风 (East)、西风 (West)、南风 (South)、北风 (North)。
字牌	`C`、`F`、`B`/`P`	`CCFFPP`	中 (Chung / Center)、发 (Fa)、白 (Bai/Pai)。

副露使用方括号 [] 包裹，格式为 [牌型, 供牌来源]。牌型如 345m (吃), 333s (碰), CCCC (杠)。供牌来源用数字表示：

这是可选部分，用 | 分隔。通常由 5-6 个字符组成 (如 EE1000)，每个位置代表一种状态：

花牌直接使用字符序列表示（如 abcdefgh 对应春夏秋冬梅兰竹菊）。

示例	含义
`[123m,1][123p,1]123m12p44s3p\|EE1000\|c`	吃 123m (上家)，吃 123p (上家)，立牌 123m 12p 44s，和牌张 3p。状态为东圈东风，自摸和牌，花牌为秋。

如果输入的手牌未和牌，工具会输出详细的向听数分析。

输出项	说明
各牌型向听数	计算一般高、七对子、十三幺、全不靠、组合龙等所有牌型的最小向听数。
进张建议	详细列出“打哪张牌，可以待哪张牌”，包括有效进张数。
好型率	若为一向听，会额外分析进张后的好型（两面、三面等）概率。

示例片段：

一般型:  1 向听
打 1s 待 4s 7s
打 2m 待 4m

如果输入的是合法和牌，工具会输出番数计算结果。

示例片段：

Total Fan: 88
Fan Details:
  1. 十三幺 (88 fan)

calc 模块包含完善的单元测试。建议在修改算法后运行测试进行回归验证。

测试文件	覆盖内容
`test/unit/fan_calculator_test.cpp`	各种番种计算、边界条件测试。
`test/unit/shanten_test.cpp`	向听数计算、听牌分析、进张数计算。
`test/unit/starting_hand_test.cpp`	起手配牌捕获逻辑测试。
`test/unit/player_stats_test.cpp`	起手向听分布统计、玩家数据统计集成测试。

运行命令:

# 在 build 目录下
./test/unit/fan_calculator_test
# 或
ctest -R fan_calculator_test