从 C++ 控制台程序到五平台安装包:一个开源五子棋 AI 的工程复盘
文章目录
引言
前前后后做了十八个月的五子棋 AI。十九路棋盘,五档难度,PyQt5 界面,纯 CPU 离线运行; 同一套搜索算法写了两份实现(Python 作为算法基准,C++17 作为性能路径,走本地 TCP 跟界面通信)。
工程上真正花时间的是四次我以为自己想明白了、结果被数据打脸的经历。 这篇文章把这四次复盘一遍。项目开源在 GitHub 上,链接放在最后。
先说个反直觉的起点:这个项目最早是 C++ 写的,而且是个控制台程序,因为我当时在学信奥,C++更加顺手。 Python 反而是最后才出现的版本。很多人默认"先 Python 原型、再 C++ 提速", 我这里正好是反过来的。
一、起点
2025 年 2 月,我发了第一版控制台程序;2 月 22 日把启发式遍历积分换成了 Alpha-Beta 剪枝 + 极大极小;4 月加了 1–4 级难度,7 月加了悔棋;10 月用 Python + Pygame 把整个东西重写了一遍,打包成 exe 发了出去。
到这里为止,Python 是最后才出现的那个版本。
二、中间那一段:2026 年 5 月,我重新开了一个仓库
2026 年 5 月 29 日,我把它彻底重开成一个正经仓库: https://github.com/iamlinxuhan/GomokuAI-Py —— PyQt5 界面 + Alpha-Beta 剪枝。 第一次有了成体系的界面、难度分级和发布流程。
9 月 19 日的 v2.0.0 是一次彻底重写:评估层和搜索层整层换掉,界面重做成一套统一的 设计系统,旧版的"分层 TSS 威胁响应""多线防守""搏命模式"全部删除。今天还在用的 位棋盘 + 全增量评估 + Negamax/PVS + 置换表 + 静止搜索 + VCF,就是在那一次定下来的。
这个仓库还有两个身份:它的引擎是纯 Python,不依赖平台相关的二进制,所以它成了
唯一支持 macOS 的版本(arm64 和 Intel 各出了 .dmg / .pkg);2026 年 10 月 2 日的
v2.1.0 是它最后一版,我在 README 里写明此后停止维护。因为python引擎计算实在太慢了,于是我们又回到了我们的起点语言:C++。
9 月 23 日,那个 Python 版还在往前跑的时候,我另开了一个仓库:把同一套算法用 C++17 再写一遍,通过本地 TCP 接进界面,也就是现在的 https://github.com/iamlinxuhan/GomokuAI 。两个仓库并行了大半个月,直到 Python 那边 发出最后一版。
三、2026 年:引擎被静默换掉了
新版是双引擎的:首选 C++,C++ 起不来时自动退回本地 Python。这个设计本身没问题。
问题出在一次用户反馈:Windows 版"不知名原因"变慢变弱,界面上显示Python引擎(本地)。 可是我当时为了防止回退引擎,做了很多工作,比如做了一个端口池逐个通信尝试,如果全部失败就让系统拉起一个空闲端口通信。可是即使如此竟然还会退回Python引擎。
排查过程暴露了我自己设计上的一个问题:
- 日志里有一列
reason,没用 —— 两个引擎写进去的字一模一样 - 还有一行
engine:,也没用 —— 只说明文件被找到了,不代表跑起来了
真正能区分的是搜索结果本身:
| 引擎 | 分值 | 实际搜到的深度 |
|---|---|---|
| C++ 档位 1(时限 0.5 秒 / 深度上限 2) | -610 | 2 |
| 本地 Python 档位 1(时限 3 秒 / 深度上限 4) | -540 | 4 |
用户发来的日志里写的是 val=-540 / dep=4,和本地 Python 引擎逐字相符;
而且 dep=4 物理上越过了 C++ 那一档的深度上限 2,不可能是 C++ 输出的。
根因落在打包和构建的接缝上——算法本身没有问题。
打包产物根目录里有 VCRUNTIME140.dll 那一组,但缺了 MSVCP140.dll;
而 C++ 引擎默认用"动态链接运行库",启动时必须加载它。
于是:装了 VC++ 运行库的机器一切正常,没装的机器引擎一启动就退出。 这就是"有人中招、有人不中招"的来源。修法是改成静态链接运行库,让引擎自带一切。
刺人的地方在于:程序没有报错,界面没有任何变化,用户看到的只是"这台电脑上的 AI 好像有点笨"。 一次加载失败,被完整地包装成了"它就是这么弱"。
还有个后续值得说:这条回归是静默的,改回去不会有任何报错。 所以在 CI 里加了一条 —— Windows 构建完之后直接扫描生成的 exe, 发现里面还带着那个 DLL 名字就判失败。让流水线当场变红,而不是等用户来报。
四、另外三条被数据打脸的结论
1. 我删掉了 130 行"聪明"的代码
回到第二节那次 v2.0.0 重写。
被删掉的旧版里,搜索之前有一层约 130 行的启发式威胁判断,用来抢答"现在该走哪"。 它最典型的一条判据:
if opp_win >= 2 or opp_live4 >= 2:
# 对手有双杀,赶紧防
而实战里最常见的双杀形态是 opp_win == 1 且 opp_live4 >= 1 ——
一个冲四加一个活四,恰好落在这条判据之外。
规则永远补不完,根子上的问题是:我用有限条规则,去近似一个可以精确判定的问题。 现在换成两个能给出确定性结论的机制去算:静止搜索数"成五点"的个数, VCF 专找"每一步都在冲四"的强制序列 —— 而且 VCF 是三态返回,能明确区分 "没有杀"和"我没算完"。
当一个问题存在精确解时,用规则近似它,代价会落在 "你不知道自己什么时候不准"上。
(有点讽刺:2025 年我就已经把启发式算法换成正经搜索了,一年半之后差点又用启发式去补搜索的洞。)
2. 我把"更进取"量成了"更弱"
我想让低难度别那么被动,加了一条根节点进攻偏置:分值在最优手 3000 以内的手,
改按 1.5 × 己方棋型 − 0.5 × 对手威胁 重排。
一分不牺牲,怎么可能变弱?同难度自我对弈:
| 难度 | 加了偏置那一方的胜率 |
|---|---|
| 初级 | 25 – 35% |
| 中级 | 0%(0 胜 8 负) |
中级是 0。而它只在分值完全相同的手之间重排,一分都没牺牲。 真因是这个判据和搜索的判断方向相反 —— 低深度下"造一个对手随手就能应住的冲四" 看起来进取,但方向是反的。
"更进取"和"更弱"是两件事,得分开量了才知道是不是同一件事。这次是同一件事。
3. 我在错误的预算上做了 A/B 测试
验证一个搜索优化时,我用"每手 1.5 秒"的预算,测出来两边胜率各 50%, 看着像"这个优化没用"。
但真正的问题是测错了地方:这个优化在浅层搜索里根本不生效, 而 1.5 秒只够搜到 4–6 层 —— 两边下的根本是同一手棋,胜率当然只能是 50%。
换到 6 秒重测,30 局配对,优化那一侧 21 胜 9 负(70%)。
不过也不能把 70% 说成"正式难度下也赢 70%",因为正式难度是每手 15–20 秒。 知道自己测出来的东西能推广到哪一步,比测出那个数字本身更重要。
五、附录:如果你也想做一个类似的
按我自己踩坑的顺序列,仅供参考(同时我的项目已经以GPL3协议开源,可以作文参考,链接在文章结尾):
- 先把规则写对,包括胜负判定和悔棋。这步没什么技巧,但错了后面全白搭
- 别一开始就上神经网络。 我中间试过 ResNet18 + MCTS,它本身是好东西, 但它要求的(模型分发、加载时间、CPU 推理延迟)和我给这个程序定的目标 (打开就能用、离线、纯 CPU)不一致。先想清楚目标再选工具
- 评估函数必须是"零和"的 —— 从黑方看和从白方看,分值正好相反,
evaluate(局面, 黑) == -evaluate(局面, 白)。不对称的评估不会报错, 只会让搜索悄悄变弱。另外make/unmake要严格对称并支持乱序撤销, 这样写测试才有意义 - 胜负判定要能给出确定结论,别用规则去猜(见第四节第 1 条)
- 难度分级应该切"搜索深度上限",而不是关掉某个功能模块。 我一开始在低难度关掉了"连续冲四取胜"这个能力,结果低难度既看不见自己的杀棋、 也看不见对手的 —— 那是"瞎"。触发这件事的是一盘真实败局: 对手用一条 11 手的连续冲四链取胜,而低难度全程没有任何机制能看见它
- 快慢两份实现,用进程边界而不是扩展模块。 C++ 那份崩了、没编译、端口被占, 界面全部翻译成"这次用本地引擎",棋局继续 —— 这比绑成扩展模块省心得多。 代价是要设计一个好协议:我用了一个 15 格的端口池,每格都先过一遍握手校验 (校验棋盘尺寸、胜利分、分值刻度),因为"连得上"不等于"是我们的引擎"
- 测试用离屏渲染,不需要显示器,这样才能放进 CI
结语
回到开头那个假 loading 的故事:2025 年那版我写过一个假的加载动画,
循环打印 loading . . .,转几下才进游戏 —— 其实没有任何东西在加载。
2026 年的加载界面,原则变成了:如实显示这一屏还要停留多久(约 0.9 秒), 不演一个和真实成本差 43 倍的假进度条。
同一件事,隔了一年半,态度完全反过来了。这个项目里我最喜欢的变化就是这个 —— 我不再想骗那个正在用我程序的人。
项目开源在 GitHub:GomokuAI
(GPL-3.0,Windows / Linux 五个平台的安装包都在 Releases 里,
也可以用 uv sync && uv run python main.py 从源码跑。)
纯 Python 的前身 —— 也是唯一支持 macOS 的版本 —— 在
GomokuAI-Py 。该仓库已于近日归档,不再进行支持和维护。
如果这篇文章里有哪条结论你觉得站不住,欢迎在评论区指出来。

评论
登录后参与技术讨论,分享你的经验与见解。
登录 / 注册暂无评论