Python五子棋3.0重构全记录：模块解耦与AI算法实现-代码聚汇网

Python五子棋3.0重构全记录：模块解耦与AI算法实现

沃克森·2026-09-09·阅读 21 GEO检测（免费）

Python五子棋AI算法

|难度：普通|阅读约 30 分钟

1. 从零手写五子棋3.0：为什么这次要重写而不是继续打补丁

五子棋这个项目，我从1.0到2.0一路踩坑走过来，最初只是几百行控制台程序，后来加了图形界面、双人对战、简单AI，代码越滚越大，直到某天整理项目时发现，原本应该清晰的棋局逻辑被界面代码、AI逻辑、输入事件全部纠缠在一起。

坦白说，2.0版本能跑，但每次加新功能都像在叠积木的底层抽走一根——改一行落子逻辑，界面就出Bug；调整AI权重，棋盘绘制就闪烁。所以我决定做一次彻底的重构，做成“五子棋3.0”，目标很明确：逻辑层与渲染层彻底分离，AI从“能赢”变成“像人”，并且让整个项目具备可扩展性。这篇文章会把这次重构的思路、核心设计、实现细节、踩坑过程全部记录一遍，适合对游戏逻辑感兴趣、想用Python从零实现一个完整小项目的初学者，也适合想改进自己业余项目的开发者参考。

项目本身不复杂，核心就几个点：棋盘数据模型、落子规则判定、胜负检测、AI决策、界面渲染与交互。但恰恰是这些看似基础的部分，组合起来后有很多细节值得琢磨。如果能耐心跟着走一遍，你会对“怎么写一个结构清晰、还能持续迭代的小型项目”有很具体的体感。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 整体架构与关键设计取舍

2.1 模块边界划分：数据、规则、AI与界面彻底解耦

3.0版本的核心改动，不是把某个算法换掉，而是把整个项目从结构上拆开。我把代码分成了四个独立模块：

board.py：棋盘数据结构与胜负检测，只维护一个二维数组，不关心界面怎么画。
rules.py：落子合法性、禁手规则、歧义处理，负责“能不能下”的判断。
ai.py：电脑玩家策略，输入棋盘状态，输出最佳落子位置。
gui.py：界面渲染与鼠标交互，只负责把棋盘画出来，把用户操作转成坐标。

这种拆分最大的好处是：AI和规则可以脱离图形界面做单元测试，棋盘逻辑可以单独用命令行验证正确性。对我这种喜欢边写边跑的人来说，这个改动直接把调试成本砍掉了一大半。

很多业余项目最后变成一团乱麻，根子就在于“职责不分”。比如2.0版本里，绘制棋盘那次要清空画布重画，顺便还在里面做了一步AI计算——你说它错吧，功能能跑；说它对，AI算起来慢的时候界面卡死，根本没法优化。所以3.0下定决心：界面只做界面的事，AI只管给坐标。

2.2 棋盘数据模型与坐标体系设计

棋盘我用的标准15x15，这在五子棋里是最常见的规格，国际比赛、休闲对战都默认这个尺寸。数据结构上我没有用什么高深的技巧，直接用二维列表，每个位置存储一个整数：0表示空，1表示黑子，2表示白子。

坐标体系上有个细节值得提一下：我用的是“行、列”而不是“x、y”。因为棋盘在屏幕上从左到右是y方向，从上到下是x方向，如果用传统的(x, y)，很容易在循环遍历时搞混行列。统一成board[row][col]之后，写检测函数的时候思路会顺很多。

python复制EMPTY, BLACK, WHITE = 0, 1, 2
BOARD_SIZE = 15

def create_board():
    return [[EMPTY] * BOARD_SIZE for _ in range(BOARD_SIZE)]

这里一个容易被新手忽略的技巧：列表生成式比[[EMPTY] * BOARD_SIZE] * BOARD_SIZE要安全得多。后者看起来一样，实际上是同一行的引用反复复制，改一个位置整列都变——我在2.0版本里被这个Bug坑了整整一个晚上。

2.3 渲染层的选择：tkinter还是pygame

界面方案我当时纠结了一段时间。tkinter是Python自带的，不需要额外安装，写起来也简单，做五子棋这种低频交互的棋盘完全够用；而pygame功能更强，动画、音效、复杂控件都好做，但引入依赖、增加学习成本，而且对4个核心很简单的功能来说属于杀鸡用牛刀。

最终选了tkinter。五子棋的交互就三种：显示棋盘、响应落子、重新开局，用Canvas绘制棋盘格和棋子再绑定鼠标事件，二十来行代码就能搞定。如果不是要做华丽的特效，tkinter反而是最优解——少一个依赖，程序在任何装了Python的机器上都能直接跑。

3. 胜负判定与规则实现的核心细节

3.1 落子合法性检查：边界、空格与禁手逻辑

落子合法性是每局游戏最先触发的一环。每次鼠标点击棋盘，先要把屏幕坐标转换成棋盘坐标，然后做三个检查：

坐标是否在0到14之间。
该位置是否为空。
如果是人机对战且开启禁手规则，还要判断当前落子是否构成三三禁手、四四禁手或长连禁手。

前两个检查是基础，第三个是进阶。普通休闲模式可以跳过禁手，但如果要做正规一点的对弈，黑棋的限制必须考虑进去。禁手规则的核心是：黑棋先手优势太大，所以禁止用“双三”“双四”或六颗以上连成一线获胜。

判断禁手稍微有点绕，思路是这样：在临时棋盘上把黑子放在待检测位置，然后分别扫描这个位置在横、竖、两条斜线四个方向上的棋型，统计是否同时形成两个活三或两个冲四。如果满足，就禁止落子。这个逻辑只在人机模式且黑棋是玩家时启用，AI自己下的话不受此限制（或者可以反过来限制AI，取决于你想做的难度）。

3.2 八方向扫描与五子连线检测

五子棋的胜负判断其实非常简单粗暴：每次落子后，从落子点出发，沿着四个方向（横向、纵向、两条对角线）各向外扫一遍，数连续相同棋子的数量，只要能数到5就判胜。

实现上有个细节：四个方向本质上就是八个方向的配对，水平方向是左右组合，垂直方向是上下组合，两个斜向同理。所以可以定义一组方向向量：

python复制DIRECTIONS = [
    ((0, -1), (0, 1)),   # 水平
    ((-1, 0), (1, 0)),   # 垂直
    ((-1, -1), (1, 1)),  # 主对角线
    ((-1, 1), (1, -1)),  # 副对角线
]

def count_in_direction(board, row, col, dr, dc):
    count = 0
    r, c = row + dr, col + dc
    while 0 <= r < BOARD_SIZE and 0 <= c < BOARD_SIZE and board[r][c] == board[row][col]:
        count += 1
        r += dr
        c += dc
    return count

def check_win(board, row, col):
    player = board[row][col]
    if player == EMPTY:
        return False
    for dir1, dir2 in DIRECTIONS:
        total = 1 + count_in_direction(board, row, col, *dir1) + count_in_direction(board, row, col, *dir2)
        if total >= 5:
            return True
    return False

这里有个选择：>= 5还是== 5。如果开启禁手规则，黑棋长连（6颗以上）不算赢；但普通对局中，长连也应该判定为胜利，所以直接用>=5反而简单，也不会妨碍禁手逻辑单独判断。

3.3 胜负提示与终局状态流转

检测到胜负后，项目会进入“终局状态”。这个状态很关键，因为如果不做限制，玩家在已经结束的棋盘上继续点击落子，会破坏对局数据，甚至导致AI在已死的棋盘上继续计算。

我在GameState里加了一个状态字段：

python复制class GameState:
    def __init__(self):
        self.board = create_board()
        self.current_player = BLACK
        self.winner = None
        self.game_over = False
        self.move_count = 0

每一轮落子前先判断game_over，为真就直接忽略输入。同时，每次落子后把move_count加1，当它等于BOARD_SIZE * BOARD_SIZE时还没有胜者，棋局以平局收场。这种细节在文档驱动型项目里容易被忽略，但真人对局时一定会遇到。

4. AI决策算法：从随机落子到启发式评估

4.1 两种AI方案：极小化极大与贪心选择

AI是五子棋3.0里最有意思的部分。2.0版本里我写了个初级AI，思路就是遍历空位、计算每个位置周围已有棋子的密度，选密度最大的位置下，效果嘛……连我自己都经常被它“菜”到无语。3.0版本我决定认真做一个“不蠢”的AI。

网上很多人一提到五子棋AI就说用极小化极大+Alpha-Beta剪枝，这个方向确实对，但对于一个15x15的五子棋来说，搜索树太深，不剪枝根本跑不动。我做了个折中：深度限制在4层，每层只搜索评分最高的前N个候选点，这样既保留了一些前瞻能力，又不会慢到让玩家等得不耐烦。

不过在写复杂AI之前，我强烈建议先把“贪心评分AI”做明白。贪心AI的价值不在于强，而在于能用最少的代码验证整个逻辑链路是否通畅：棋子能正确落下、胜负能正确判定、界面能正确刷新。3.0版本里我保留了两种AI模式，默认用贪心，用户可以在配置里切换为深度AI，两相对比更能理解搜索类AI为何更强。

4.2 棋型评估与打分权重体系

无论是贪心AI还是深度AI，核心都是“给每个位置打分”。打分的基础是棋型识别：连续同色棋子构成的形状，以及两端是否被堵住。

我把棋型分成几个等级：

五连：100000分，直接赢。
活四：50000分，对手无论怎么堵都拦不住。
冲四：10000分，只有一个位置能堵，但这一手必须应对。
活三：5000分，再下一手可以变活四，对手需要警惕。
眠三：1000分，有发展潜力，但暂时不急。
活二：500分，早期布局用。
眠二：50分，聊胜于无。

打分时不能只看落子位置本身的棋子形状，还要考虑对对手的威胁。所以我给分数设计了“攻击分”和“防守分”：计算己方在这个位置下子后的得分，再计算如果这位置被对手占了对自己的威胁有多大，最终得分是两者的加权和。

python复制def evaluate_position(board, row, col, player):
    if board[row][col] != EMPTY:
        return -float('inf')
    attack_score = score_point(board, row, col, player)
    defend_score = score_point(board, row, col, 3 - player)
    return attack_score * 1.1 + defend_score * 0.9

attack_score权重略高于defend_score，因为五子棋先手优势极大，该进攻时如果不果断，很容易从优势变成被动防守。

4.3 候选点生成与搜索深度控制

深度AI每层都遍历整个棋盘是不可能的，256个空位，展开4层，那就是256的4次方，直接爆炸。所以必须在每一层提前砍掉大量无效节点。

我采用的方法是候选点裁剪：先扫描所有空位，每层只保留评分最高的前10个位置作为下一层的分支。这样一来，搜索规模变成10×10×10×10=10000次评估，实际运行时间在几百毫秒内，完全能接受。

Alpha-Beta剪枝在这种结构下意义不大，因为候选点已经很少了，但加上也无妨，能让搜索树少走一半以上的路径。核心实现思路是维护一个“当前最优”的上下界，如果某条分支显然比已知结果差，直接剪掉，不再深入。

4.4 AI难度调节与随机因子

3.0版本里给AI加了三个难度挡位：简单、中等、困难。难度的差异不是“搜索深度”，而是在评分后对结果做不同程度的随机扰动。

简易模式下，最终得分会乘以一个0.8到1.2之间的随机数，这样AI有时候会自己放弃最佳落子，去下一些看似合理的废棋，新手玩起来不会觉得压力太大。困难模式则把随机因子去掉，AI永远选择评估分最高的位置。

这个设计比单纯改搜索深度要实用得多。搜索深度4层和5层，对玩家感知来说区别极小——除非是专业棋手。但随机扰动的那一点点“不确定性”，反而让AI显得像一个有情绪的人类棋手，而不是一台冷冰冰的机器。

5. 界面交互与关键渲染实现

5.1 Canvas绘制棋盘与坐标转换公式

界面部分用的tkinter.Canvas。棋盘画起来不复杂：一个15×15的网格，线宽1像素，外加九个星位点缀，然后把棋子画成实心圆。

坐标转换是界面和逻辑之间的桥梁。鼠标点击得到的是屏幕像素坐标，需要转换成棋盘坐标。我设定每格大小为40像素，棋盘左上角起点在(40, 40)，这样留出边距给棋谱坐标编号。

python复制GRID_SIZE = 40
MARGIN = 40

def pixel_to_board(x, y):
    row = round((y - MARGIN) / GRID_SIZE)
    col = round((x - MARGIN) / GRID_SIZE)
    return row, col

def board_to_pixel(row, col):
    y = MARGIN + row * GRID_SIZE
    x = MARGIN + col * GRID_SIZE
    return x, y

这里有个小坑：round取整时如果点击非常靠近格线，可能会造成误判。我加了个容差逻辑，如果像素坐标距离最近交点的距离超过半个格子，就判定为无效点击，不让玩家在下棋时产生“明明点这里为什么落在隔壁”的困扰。

5.2 鼠标事件绑定与落子反馈

落子流程是这样的：鼠标左键点击棋盘区域，触发on_click事件，先把像素坐标转换成棋盘坐标，再调用规则模块检查合法性，合法就落子、更新界面、切换玩家、检查胜负，非法则弹一个状态栏提示。

界面上的反馈很关键。我给棋子画了一层很小的阴影，模拟立体感；落子后会在最后一颗子旁边画一个红色小方框标记，提示下一手轮到谁、刚才是哪边下的。这些细节看似无关紧要，但极大提升了使用体验——我见过很多业余项目，功能齐全但玩家完全不知道当前棋盘状态，就是因为缺了这点“状态反馈”。

另外还要处理一个细节：AI思考需要时间，如果是深度AI那几百毫秒CPU占用还不明显，但为了不阻塞界面，我把AI调用放进了after延迟任务里，让界面先在状态栏显示“电脑思考中...”，然后等计算完成再落子重绘。这样界面不会卡死，也让玩家感觉电脑是真的在“思考”。

5.3 悔棋、重开与棋局记录功能

3.0版本把2.0里没有的“悔棋”功能补上了。实现很简单：在GameState里维护一个栈，每次落子入栈，点击悔棋按钮时如果当前是玩家回合，就连续弹出两步（玩家一步、AI一步），恢复棋盘后重绘。

重开功能就更容易了，重新初始化GameState、清空画布即可。但这里有个小陷阱：如果之前启用了禁手规则，重开时必须把禁手配置一起恢复，否则会出现第一局黑棋不能双三、第二局又能下双三的诡异局面。我把配置封装成一个Config对象，每次重开时从Config读取，而不是从全局变量读，这样就不会有状态残留。

棋局记录功能我用了简单的列表存储，每次落子记录(row, col, player)，既可以在界面画出序号，也方便后期导出成PGN格式（当然五子棋没有标准PGN，但可以自定义格式）。这算是个锦上添花的功能，但做起来成本很低，对复盘很有帮助。

6. 人机对战下的AI细节问题与处理

6.1 禁手规则的实现坑点与临时落子法

禁手规则是我这次重构时反复调试最多的部分。常见误区是直接在原棋盘上模拟落子去判断，结果把真实棋盘状态改了，还会在判断失败时“忘记”恢复，导致后面所有逻辑全部乱套。

我的做法是：判断禁手时，复制一份棋盘，在副本上落子，再扫描棋型。

python复制import copy

def is_forbidden_move(board, row, col):
    temp_board = copy.deepcopy(board)
    temp_board[row][col] = BLACK
    # 然后在 temp_board 上判断是否形成多活三、多冲四或长连

用deepcopy开销不大，因为15x15总共才225个元素，而且禁手判断只在落子瞬间触发，频率很低，性能完全不是问题。重要的是思路清晰：永远不要在真实棋盘上“试下”。

6.2 黑棋先手优势与白棋应对策略

五子棋是典型的先手优势游戏，如果没有任何限制，黑棋开局必胜。为了让对战更有趣，我给人机模式设定了两个可选规则：禁手规则和交换规则。

禁手规则前面已经提过，专门限制黑棋。交换规则则是经典的五手两打变种：黑棋先下五手（前三手之后，白棋可以选择交换或继续），然后白棋下第五手。这个规则我不打算在3.0里完整实现，但架构上保留了扩展点：rules.py里所有判断都只依赖“当前玩家是谁”，将来如果要加交换规则，只需在落子流程中插入一个“是否交换”的判断即可。

白棋应对黑棋先手的思路也很直接：AI评估时不仅要抓自己的进攻机会，还要监控对手的威胁。我实现了一个威胁度检测函数，定期扫描全盘，统计双方最能形成五连的位置，如果对手有多个冲四点，必须优先堵，哪怕牺牲一点自己的进攻阵型。

6.3 AI自对弈与终局胜率统计

深度AI写完之后，我做了一个自对弈测试：让AI黑棋跟AI白棋互下100局，比赛结束后统计胜率分布。结果黑棋胜率大约58%，白棋42%，这个比例虽然还有差距，但比2.0版本的黑棋90%胜率好太多了——禁手规则和防守权重的加入确实让人机对战更平衡了。

自对弈测试也能发现一些隐蔽Bug。比如有一轮测试里，AI在棋盘某一个区域反复落子，最后走出了四连但不堵对手的三连，输掉比赛。查代码发现是评分函数中防守分计算时，对手棋子颜色参数写错了，总是把对手当成自己。这类问题光靠手玩很难发现，自对弈批量跑几十局立刻暴露。

7. 常见问题与排查技巧实录

7.1 落子错位问题：像素坐标换算出的行列不对

这是最常遇到的问题，新手尤其容易碰见。症状是：鼠标明明点在棋盘交叉点上，落子却落在斜对角的位置上，或者干脆落在格子内部。

排查思路是这样的：先在on_click里加一行打印语句，输出像素坐标和换算后的棋盘坐标，然后用鼠标点几个已知位置，比如棋盘正中央，看看坐标对不对。如果输出的是(MARGIN偏移前的值)，那就是board_to_pixel和pixel_to_board的换算关系里少了MARGIN；如果行列对调了，说明x和y的映射写反了。

打个比方：坐标换算就像地图上的经纬度，在地图上看到的是标尺刻度，但你得先知道原点在哪。如果原点设错了，测出来的每一步都是偏差的，而且偏差会随着棋盘尺寸增大而变大。

7.2 棋子重叠：重复绘制同一位置的棋子

这个Bug在2.0版本里出现过，症状是同一位置会出现多个深浅不一的棋子，像叠了好多层。

根因在于落子后刷新界面时，没有判断目标位置是否已经有子。只要在某处先写上子，然后另一段绘制代码遍历棋盘时，发现这个位置非空，又画了一遍。3.0里我在绘制前加了过滤：只对待绘制棋盘上非空的位置画子，并且在逻辑层落子前也做一次占用检查，双重保障。

7.3 AI计算卡死界面：阻塞调用的坑

深度AI在4层搜索时大约需要几百毫秒，如果直接用同步调用，界面会在这几百毫秒里完全冻结，鼠标点击没有反应，窗口标题栏还会变成“未响应”。玩家体验极差。

解决办法就是前面提过的用after延迟调用。核心思路是：不要把AI计算放在主线程里同步跑，而是安排它在事件循环的下一轮执行。如果AI计算时间真的非常长，还可以考虑放到独立线程里，但Python的GIL限制意味着纯计算型任务多线程并不能加速，所以这里用after实际上是为了把耗时的计算移出GUI事件处理流程，而不是真正意义上的并行。

7.4 悔棋后AI重新计算导致状态错乱

悔棋功能做出来后，我又遇到了一个逻辑Bug：玩家悔棋后，AI居然也“跟着悔棋”了，而且AI重新计算时会基于已空掉的棋盘进行，导致后续落子和记录完全错乱。

排查后发现，是因为悔棋后我调用AI时没有更新move_count，AI内部计算时根据move_count判断该谁下，结果拿到的是过期值，就误以为是AI回合。解决方案很简单：悔棋后同步更新move_count，并且在AI计算前再校验一次当前玩家ID。

7.5 常遇问题速查表

症状	可能原因	解决办法
落子位置偏移一个格子	坐标换算缺少MARGIN偏移	检查`board_to_pixel`中的原点偏移
棋盘上出现重复棋子	绘制前未检查目标位置状态	落子前先判断目标位置为空
AI思考时窗口无法响应	同步阻塞调用	改用`after`延迟调用，或放到工作线程
悔棋后AI乱走	悔棋未更新move_count与当前玩家	悔棋后同步刷新状态字段
黑棋总是长连获胜	禁手规则未生效	检查是否在副本棋盘上判断禁手
界面棋子颜色与状态不一致	绘制顺序错乱	先画棋盘网格，再画棋子，最后画标记

8. 项目扩展方向与个人经验总结

3.0版本做到这个程度，核心需求基本都满足了：双人对战、人机对战、禁手规则、悔棋、重开、棋局记录，代码结构也算清爽。但这个项目如果就此打住，总觉得有点可惜，几个可以继续扩展的方向我简单聊聊。

网络对战是目前提升最大的方向，把本地棋盘数据封装成消息，通过TCP或WebSocket传输“落子坐标”，服务器只做转发，逻辑层不需要大改。局域网对战一个人用很简单，加个IP和端口输入框就行。

AI进一步升级的路线，一个是把搜索树换成蒙特卡洛树搜索（MCTS），这是AlphaGo之前比较强的五子棋算法，特点是可以在不依赖复杂棋型评估的情况下，靠大量随机模拟得出较好落子，15x15棋盘完全能跑；另一个是引入深度学习模型，但考虑到训练数据获取难度和推理性能，对个人小项目来说性价比不高。

最后再分享一点我自己的体会：这个项目从1.0到3.0，最大的收获不是五子棋本身，而是明白了“写一个功能能跑的代码容易，写一个能持续迭代的代码很难”。当你把逻辑、界面、AI彻底分开之后，每一次改动都变得更加从容。如果你也手头有一个小项目越写越乱，我建议你不要继续打补丁，像我一样选一个点重写一版，带来的清爽感，远超你的预期。