Gomoku against Laya-MLX: you play black, the model picks white's move from six candidates

# 一着 · Laya-MLX 五子棋

**中文** | [English](README.en.md)

一个在 Apple Silicon Mac 上运行的本地五子棋人机对战游戏。你执黑先手，Laya 执白；浏览器负责棋盘交互，Python 负责规则，MLX 在本机 GPU 上运行真实模型推理。

这个项目沿用 [laya-mlx Snake demo](https://github.com/mizorewww/laya-mlx/blob/main/docs/SNAKE_DEMO.md) 的思路：**程序提取局面特征 → 模型从候选动作中选择 → 战术规则检查 → 执行落子**。本项目没有对模型进行五子棋专项训练，也不把规则计算出的棋力归因给模型。

## 功能

- 15×15 自由五子棋：黑棋先行，横、竖、斜连续五颗或更多即胜；没有三三、四四、长连禁手。
- 每次 AI 落子真实调用一次 Laya `choice` 决策头，最多比较 6 个合法候选点。
- 展示候选点概率、模型首选、实际落点、推理耗时和战术规则介入。
- 支持悔棋一回合、重开、手数显示、最新落点与获胜连线标识。
- 鼠标、触摸及键盘操作；适配宽窄屏布局。目前游戏界面为中文，文档提供中英两种语言。
- 前端使用原生 HTML/CSS/Canvas，无需 Node.js、构建步骤或 CDN。
- 模型下载后离线游玩；不需要 API key、云端推理或付费模型服务。

## 环境要求

| 项目 | 要求 |
| --- | --- |
| 电脑 | Apple Silicon Mac（M 系列芯片） |
| 系统 | 上游声明 macOS 14+；实际支持还取决于当前 MLX wheel 与系统版本 |
| Python | 3.11 或更新版本；建议使用独立虚拟环境 |
| GPU | 本机可访问的 Metal GPU |
| 浏览器 | 较新的 Safari、Chrome、Edge 或其他现代浏览器 |
| 网络 | 首次安装依赖、下载模型时需要；之后可离线 |
| 磁盘 | 多语言 FP16 权重约 0.65 GB，另需依赖和缓存空间，建议预留数 GB |

本项目已在 M4 / 32 GB 内存、macOS 27.0、Python 3.14.7、MLX 0.32.2 上验证。这个记录不是最低内存要求，也不代表其他系统版本均已实测。当前启动路径不支持 Intel Mac、Windows 或 Linux。

## 安装：从零开始

### 1. 获取代码

```bash
git clone git@github.com:smile-magic/laya-mlx-wzq.git
cd laya-mlx-wzq
```

如果没有配置 SSH，也可以通过 HTTPS 克隆同一个仓库：

```bash
git clone https://github.com/smile-magic/laya-mlx-wzq.git
cd laya-mlx-wzq
```

仓库若为私有，需要先取得访问权限，并配置 GitHub SSH 密钥或 HTTPS 凭证。

### 2. 检查 Python 和芯片架构

```bash
uname -m
python3 --version
```

应分别看到 `arm64` 和 Python 3.11+。部分 Mac 的系统 `python3` 仍是 3.9；请换用已安装的新版 Python。若已安装 Homebrew，可用 `brew install python@3.12`，然后用 `python3.12` 替代后文创建环境时的 `python3`。不要使用 Rosetta 下的 x86_64 Python。

### 3. 创建环境并安装依赖

在仓库根目录执行：

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```

依赖文件固定 `laya-mlx==0.1.0`；MLX、tokenizers、NumPy、Hugg