v2.5.0 · 开源 · Python

天青 · 中国象棋

楚河汉界 · 运筹帷幄

一款基于 Python + pygame 的中国象棋人机对战程序。 内置 Alpha-Beta 剪枝搜索 + 置换表 + 历史启发 的智能 AI， 支持悔棋、将军/将死/困毙判定与 chessai 棋局分析面板， 配以木纹棋盘风格的精致 UI。

Python 3.8+ pygame Alpha-Beta AI chessai 可选集成 44 项单元测试
楚 河汉 界

功能特性

规则严谨、AI 智能、界面精美，兼顾教学演示与娱乐。

🧠

智能 AI 对战

玩家执红（下方），电脑执黑；AI 采用 negamax + Alpha-Beta 剪枝、置换表与历史启发，默认 2 秒思考预算，界面不冻结。

📜

完整象棋规则

七种棋子走法、蹩马腿、塞象眼、炮架、过河兵、九宫、飞将、不送将过滤，规则层纯逻辑可单测。

🏁

真正的胜负判定

将军 / 将死 / 困毙（和棋）完整判定，显式状态机 PLAYING → AI_THINKING → GAME_OVER。

⏪

悔棋

「悔棋」按钮或 U 键撤销最近一个完整回合，支持吃子恢复；无历史时按钮自动禁用。

🔬

棋局分析面板

按 H / F1 打开：FEN、chessai 将军/将死/飞将状态、AI 推荐走法（自研 AI 计算 + chessai 交叉校验）。

🎨

木纹棋盘 UI

程序化木纹棋盘、河界描边艺术字、棋子缩放适配、最近一步标记、将军红环警报、俘虏区、终局横幅。

🔌

引擎接口抽象

Engine.get_best_move() 协议，可替换自研 AI 或接外部 UCI 引擎，游戏逻辑零改动。

⚡

性能优化

快速将军检测、make/unmake 就地走子、迭代加深 + 时间预算、AI 后台线程、渲染缓存；深度 3 提速约 7 倍。

🧪

测试与工程化

44 项单元测试 + 无头冒烟脚本；pyproject.toml 规范打包（pip install -e . / chinese-chess 命令）。

技术栈

  • 语言 / 环境：Python 3.8+，Windows / Linux / macOS
  • 图形界面：pygame 2.x（棋盘、棋子、字体渲染）
  • AI 搜索：negamax + Alpha-Beta 剪枝 + 置换表（Zobrist）+ 历史启发 + 迭代加深
  • 可选依赖：chessai-python（分析面板规则交叉校验，未安装时优雅降级）
  • 工程：pyproject.toml / requirements 双清单 / git 版本管理 / unittest

快速开始

安装依赖（核心只需 pygame）：

pip install -r requirements.txt

运行游戏：

python main.py

规范安装后也可直接用命令启动（可选）：

pip install -e .
# 之后可用命令： chinese-chess

可选：安装分析面板增强（会引入 opencv/fastapi 等重依赖，可跳过）：

pip install -r requirements-optional.txt

操作说明

  1. 点击己方棋子选中（金色高亮），可走位置显示绿色圆点
  2. 点击可走位置落子；点击己方其他棋子可改选
  3. 电脑思考时状态栏提示，被将军时显示红色警报与将子红环
  4. 按 U 或点「悔棋」撤销最近一个完整回合（吃子恢复）
  5. 按 H / F1 开关棋局分析面板（FEN、状态、AI 推荐）
  6. 终局弹出横幅，点「重新开始」再来一局

目录结构

Python_chinese_chess/
├── main.py                   # 程序入口
├── pyproject.toml            # 项目元数据 / 命令入口 / 可选依赖
├── requirements.txt          # 核心依赖（pygame）
├── requirements-optional.txt # 可选依赖（chessai 分析面板）
├── README.md / index.html    # 说明文档与介绍页
├── chinese_chess/            # 主包
│   ├── constants.py          # 常量与资源管理
│   ├── fonts.py              # 中文字体管理（候选字体 + 文件兜底）
│   ├── pieces.py             # 走法规则 + Board 局面（纯逻辑）
│   ├── board.py              # 棋盘 / 棋子渲染
│   ├── button.py             # 三态按钮控件
│   ├── ai.py                 # Alpha-Beta AI + 评估 + 终局判定
│   ├── zobrist.py            # Zobrist 哈希（置换表键）
│   ├── engine.py             # 引擎接口抽象
│   ├── chessai_bridge.py     # chessai 集成（优雅降级）
│   └── game.py               # 游戏主循环（状态机 + AI 线程）
├── assets/s2/                # 14 张棋子图片
├── scripts/smoke_ui.py       # 无头冒烟脚本
├── docs/DEVELOPMENT.md       # 开发建议与性能优化记录
└── tests/                    # 44 项单元测试（不依赖 pygame）

版本历史

  • 2.5.0

    P2 信息与动效：俘虏区（双方被吃棋子小图）、回合数显示、AI 思考动态省略号、终局居中半透明横幅 + 大字。

  • 2.4.0

    UI 优化：信息栏布局分区（消除重叠）、窗口 900×720、木纹棋盘 + 河界艺术字、棋子缩放与描边、最近一步标记、将军警报、按钮三态；修复 GIF 8-bit 缩放崩溃。

  • 2.3.1

    工程规范化：pyproject.toml、可选依赖拆分、版本号统一、README 更新。

  • 2.3.0

    状态机化、悔棋（按钮/U 键）、引擎接口抽象、AI 置换表 + 历史启发、将帅位置缓存、git 版本管理。

  • 2.2.0

    集成 chessai-python：分析面板（H/F1）、FEN / 将军 / 将死交叉校验、桥接层优雅降级。

  • 2.1.0

    AI 搜索 4× 加速、迭代加深 + 时间预算、AI 线程化不冻结、渲染缓存。

  • 2.0.0

    重构为标准包结构；修复走法 / 胜负 bug；AI 重写为 Alpha-Beta；新增将军 / 将死 / 困毙与单元测试。

  • 1.0.0

    原平铺版脚本，可运行但电脑无智能。