# chinese_chess

**Repository Path**: bltzmnn/chinese_chess

## Basic Information

- **Project Name**: chinese_chess
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 安卓, Linux, TUI

## README

# 中国象棋引擎环境

基于 Pikafish 的中国象棋对弈与分析环境，覆盖 **PC（GUI / 命令行）** 和 **安卓手机** 两个平台。

## 环境信息

| 组件 | 说明 |
|---|---|
| PC 引擎 | Pikafish 2026-09-06（官方 universal 版，bench 1,399,715 NPS） |
| PC GUI | tchess V1.9（跨平台，支持 UCI/UCCI） |
| PC 交互式 TUI | play_tui.py（键盘选子走子，6 档难度可调，自包含） |
| 安卓 App | 象棋鱼 v2.3（已升级内置引擎至 2026-09-06） |
| 本机 | AMD Ryzen 7 8845H / 16 线程 / AVX-512 / Radeon 780M |
| 编译环境 | ~/android-sdk（platform 34 + NDK 25.1.8937393）、~/jdk17 |

## 目录结构

```
chinese_chess/
├── linux/                        ← PC 端（Linux）
│   ├── bin/
│   │   ├── pikafish              ← 引擎（2026-09-06 官方 universal 版）
│   │   └── pikafish.nnue         ← NNUE 权重（50.7MB，2026-09-06 配套）
│   ├── tchess_V1.9/              ← GUI 界面（官方分发包，非 submodule；上游见"相关资源"）
│   ├── play_tui.py               ← 交互式 TUI 对弈（键盘操作，难度可调，自包含）
│   └── test_play_tui.py          ← TUI 冒烟测试（pyte 虚拟终端）
├── android/                      ← 安卓端
│   ├── ChessFish_*.apk           ← 编译好的 APK（可直接 adb install）
│   ├── chinese-chess-fish-android/  ← 象棋鱼源码（已替换引擎，可重新编译）
│   │   └── app/src/main/pikafish/arm64-v8a/  ← 内置引擎（2026-09-06）
│   ├── pikafish-replacement/     ← 引擎替换文件（引擎×2 + 权重 + ini）
│   └── 象棋鱼换引擎编译指南.md     ← 换引擎 + 编译完整步骤
├── 实现方案.md                    ← 技术选型文档
└── README.md
```

## 快速开始

### PC：GUI 对弈

```bash
cd chinese_chess/linux/tchess_V1.9
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.KQOGV3 ./tchess.sh
```

> Wayland 环境下需要设置 `DISPLAY` 和 `XAUTHORITY`，X11 环境直接 `./tchess.sh` 即可。

> **关于 tchess_V1.9/**：这是 tchess 官方预编译分发包（含内置 JRE、app.jar、棋盘皮肤等约 214MB），
> 直接解压即用，未作为 git submodule 引入。上游源码与新版发布见"相关资源"中的 tchess 项目链接；
> 若需更新版本，下载官方 release 包替换本目录即可。

启动后在 tchess 中加载引擎：

1. **引擎 → 引擎管理 → 添加引擎**，选择 `chinese_chess/linux/bin/pikafish`
2. 配置线程数（16）和哈希表大小（2048 MB）
3. 如需中规：引擎配置中将 `Repetition Rule` 设为 `ChineseRule`
4. 点击工具栏 **引擎执红/引擎执黑** 开始对弈

### PC：交互式 TUI（推荐，键盘操作）

```bash
cd chinese_chess/linux
python3 play_tui.py
```

- **方向键**移动光标，**回车/空格**选中己方棋子，再移动光标到目标格回车落子
- 非法走法会被引擎校验并拦截提示
- `u` 悔棋（人机各撤一步）、`f` 翻转视角、`q` 认输
- 红子红字、黑子青字，光标反色高亮；需支持颜色与方向键的真实终端（TERM=dumb 会拒绝启动）

**思考强度可调**：启动时选择难度，对局中随时按 `1~6` 实时切换（下一手生效）：

| 档位 | 名称 | 搜索深度 | 参考耗时/步 |
|---|---|---|---|
| 1 | 新手 | depth 1 | 0.5s |
| 2 | 入门 | depth 2 | 0.8s |
| 3 | 业余 | depth 4 | 1s |
| 4 | 大师（默认） | depth 8 | 2s |
| 5 | 特级大师 | depth 12 | 3s |
| 6 | 满血 | 不限（movetime 控制） | 3s |

Pikafish 早在 2023 年 4 月就移除了 `UCI_LimitStrength`/`UCI_Elo` 限棋选项，官方当时的提交即建议改用限制搜索深度或节点数来降棋力——难度因此改用 `go depth` 深度阶梯实现：深度越浅棋力越弱、响应越快。档位名为大致棋力感受，非精确 Elo 对应。状态栏实时显示当前档位。

### 安卓：安装象棋鱼

```bash
adb install android/ChessFish_20260910_508_armv8-dotprod-Debug.apk
```

> 若手机已装官方版象棋鱼，签名不同会安装失败，先卸载旧版。
> dotprod 版闪退的老手机需换 armv8 flavor 重编（见编译指南）。

App 内置皮卡鱼 2026-09-06（Threads=8 / Hash=512MB / MultiPV=5），无需额外配置即可对弈、分析、打谱。

## 安卓端编译（象棋鱼源码）

环境一次性装好后，重编译只需一条命令：

```bash
cd android/chinese-chess-fish-android
JAVA_HOME=~/jdk17 ./gradlew assembleArmV8-dotprod-Debug
# 产物: app/build/outputs/apk/armv8-dotprod-/debug/*.apk
```

完整步骤（环境安装、引擎替换、签名、常见问题）见 [象棋鱼换引擎编译指南.md](./android/象棋鱼换引擎编译指南.md)。

要点：

| 项 | 值 |
|---|---|
| JDK | ~/jdk17（Temurin 17，系统 JRE 21 无 javac） |
| Android SDK | ~/android-sdk（NDK 版本锁定 25.1.8937393） |
| 引擎/权重 | app/src/main/pikafish/arm64-v8a/ 下 4 个文件，与权重必须同版本 |
| 镜像 | settings.gradle.kts 阿里云 Maven + 腾讯 Gradle 分发包 |
| 磁盘 | ⚠️ 编译需 ~5GB 空间（SDK + Gradle 缓存） |

## 引擎版本选择

官方提供多个指令集版本，优先级：vnni512 > avx512 > avx512f > avxvnni > bmi2 > avx2 > sse41-popcnt。

PC 端现使用官方 universal 版（2026-09-06，bench 1,399,715 NPS）；旧版 avx512/bmi2/avx2 实测数据（2026.01.31）：

| 版本 | NPS | 说明 |
|---|---|---|
| avx512 | 1,194,197 | 旧版本机最快 |
| bmi2 | 1,115,413 | |
| avx2 | 1,067,239 | |

可通过 `bench` 命令测速：`./pikafish bench`

安卓端对应 ARM 指令集：`pikafish-armv8-dotprod`（近几年手机） / `pikafish-armv8`（老设备）。

## 引擎参数说明

| 参数 | 说明 | PC 推荐值 | 手机推荐值 |
|---|---|---|---|
| Hash | 局面缓存（MB） | 2048 | 64~512 |
| Threads | 并行搜索线程数 | 16 | ≤ CPU 核心数 |
| MultiPV | 显示候选着法数 | 1（对弈）/ 3~5（分析） | 同左 |
| Repetition Rule | 棋规 | AsianRule / ChineseRule | 同左 |

> 注：Pikafish 2023-04 起已移除 `UCI_LimitStrength`/`UCI_Elo` 参数，限棋改由 play_tui.py 的深度阶梯实现。

## 相关资源

- [Pikafish 官网](https://www.pikafish.com/) — 引擎下载、Wiki、QQ 群
- [tchess 项目](https://github.com/sojourners/public-Xiangqi) — PC GUI
- [象棋鱼项目](https://github.com/zfdang/chinese-chess-fish-android) — 安卓 App 源码
- [皮卡鱼论坛](https://bbs.pikafish.org/) — 技术讨论
- [皮卡鱼网页版](https://xiangqiai.com/) — 在线体验
- [实现方案.md](./实现方案.md) — 技术选型与扩展方案

## 许可

本项目以 [GPL v3](./LICENSE) 发布。

> 注意：内置引擎 Pikafish 上游同为 GPL v3；tchess 分发包的许可以其官方仓库为准；
> Pikafish 官方 NNUE 权重为非商业免费，商用需单独授权。