# Gomoku AI · 五子棋人工智能博弈系统

原生 HTML5 / CSS3 / JavaScript、本地计算、无服务器、无数据库、无第三方运行依赖。课程实践版本，包含实际搜索与可复现验证，不保证比赛胜率或专业棋力。

## 立即运行

**直接双击 `index.html`**。页面包含全部样式、引擎、界面和 Blob Worker 源码，无需联网。允许 Worker 的浏览器会在独立线程搜索；Worker 被阻止时，自动切换到 ≤100ms 预算的主线程基础搜索（仍可能短暂阻塞）。

推荐静态 HTTP 运行，需 Node.js 18+：

```sh
cd /Users/leoknox/data/Code/CLion/gomoku-ai
npm run serve
```

打开 http://127.0.0.1:8080 。可用 `PORT=8090 npm run serve` 更换端口；Ctrl+C 关闭服务。不需要 `npm install`。

也可以 `python3 -m http.server 8080 --bind 127.0.0.1`；Nginx 将整个目录作为静态目录即可。只部署 `index.html` 也可以下棋，但文档链接需要同时部署 Markdown 文件。严格 CSP 需要允许 inline script/style 和 `worker-src blob:`；否则应单独调整打包/部署策略。

## 操作

- 默认人类执黑 vs AI-A。设置模式、执棋、规则后点击“开始新对局”。设置变化会暂停当前局；继续可沿用原有棋局配置。
- 人人模式每次悔一步。人机模式退回到人类的决策回合，包含交换和候选等阶段。AI 对战先暂停再悔棋。
- AI-A / AI-B 的难度、单步时间、对局间隔可以实时调整；正在进行的搜索沿用启动时参数。
- 点击交叉点落子；键盘聚焦棋盘后用方向键选择、Enter/空格落子。最末一手有彩色方形标记。
- 棋谱按钮、滑块、前后按钮进入回放并暂停；“返回对局”回到实况，再点击“继续”恢复 AI。
- 导出 JSON 包含实际落子时间、当时玩家、规则、交换/提案事件、结果、耗时、实际搜索指标和最多 100 局已完成评测棋谱。
- “启动多局评测”会开始新的 AI 对局批次，交替 AI-A/AI-B 的初始颜色，每对使用相同第二手，后续对使用不同可复现第二手。停止按钮保留当前棋局。

## 规则与课堂开局

棋盘内部 `i=y*15+x`，左上为 A15，右下为 P1，H8 为 112。列为 `ABCDEFGHJKLMNOP`，四周显示坐标。黑白交替，终局后不可继续。

自由模式：双方 ≥5 连即胜。允许白先，但这是课堂练习，不是标准竞赛。

连珠禁手模式：黑棋长连、双四、真双三拒绝落子；黑棋恰好五连胜，白棋 ≥5 连胜。禁手点在本应用中**拦截并重下**，不直接判负。无合法落点判平局，亦属本任务指定的应用规则。

规则定义参考 [RIF 国际连珠规则，第 3、9 节](https://www.renju.net/rifrules/)。本程序默认依照用户需求，让长连优先于交叉方向的恰好五连；这与该文第 9.2 节“同时成五”的优先级有差异。可通过 `fiveOverridesOverline: true` 改成恰好五连优先。恰好五连默认优先于三三、四四。程序没有实现 RIF 文档中的申诉、停钟、放弃落子等全部现场程序。

特殊开局默认全部关闭，启用时按以下课堂需求配置，而不是完整 RIF 指定开局体系：

1. 指定：黑1 H8；白2任意合法点；黑3中心5×5（F6–K10）。
2. 交换：默认第4手前，原执白玩家决定是否交换**玩家身份**；棋子与棋盘不变。源码 `swapAfter` 可配置决策手数。
3. 第五手 N 打：整局4手后，黑方提出 N 个合法且不同的点，白方选定一个正式黑5；N 默认2，可调2–8。第五手区域半径可调2–7（7表示全盘）。候选不做对称等价去重；课堂若要求“非同型候选”需另行明确。
4. 同时启用三项时严格依次处理交换、白4、黑方提案、白方选点、白6。

`js/core.js` 的 `DEFAULT_RULES` 集中管理禁手开关、优先级、开局、先手、悔棋与积分。第五手提案不计入正式棋谱手数；它们记录为独立事件，可分别撤销。

## AI 实现

四方向棋型评估、双方攻防、局部控制；全盘立即成五检查、必要防守；邻域候选排序；Negamax 形式 Minimax / Alpha-Beta；迭代加深；双32位 Zobrist 置换表；有界 VCF。没有远程模型调用，也没有用随机概率代替搜索。交换决策使用静态局面评估，尚未做交换博弈树优化。

| 难度 | 最大深度 | 内部普通候选上限 | 置换表 | VCF |
|---|---:|---:|---|---|
| 简单 | 1 | 8 | 关 | 关 |
| 普通 | 2 | 10 | 关 | 关 |
| 困难 | 4 | 14 | 开 | 关 |
| 专家 | 7 | 18 | 开 | 开 |

深度是上限，不是承诺；时间预算不足时保留最后完整层，若一层也未完成，返回已验证合法的排序回退点。根候选至少24个，强制成五点不受普通截断限制。实际完成深度、节点、耗时、分数和主变化在页面显示。

详见 [AI_ALGORITHM.md](AI_ALGORITHM.md) 和 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 开发、测试

```sh
npm run build    # 修改 js/、style.css、page.html 后重建单文件入口
npm test         # Node 内建测试，无外部依赖
npm run bench    # 12组性能用例 + 4局实际自对弈
```

`GOMOKU_BENCH_MS=100 GOMOKU_GAMES=8 npm run bench` 可增加预算与局数；计时搜索结果受硬件/JIT/系统负载影响。固定棋型测试可复现，计时比赛不保证逐手相同。

可选浏览器测试需另备 Playwright 和浏览器，游戏运行不需要它们：

```sh
npm install --no-save --package-lock=false playwright
npx playwright install chromium
node tests/browser.cjs
```

也可设置 `PLAYWRIGHT_MODULE` 为现有 Playwright 包绝对路径，`CHROME_PATH` 为已有 Chrome 可执行文件路径。`GOMOKU_URL` 指向运行中的 HTTP 服务。截图和 JSON 导出保存在 `tests/browser-artifacts/`。

## 完成状态与边界

已实现棋盘、三种模式、自由/禁手规则、递归真活三、独立课堂开局、撤销、回放、JSON导出、真实本地搜索、Worker取消/异常回退、自对弈统计、测试与性能记录。

尚未实现：VCT、开局库、专业棋谱库对照认证、完整 RIF 26 种指定开局/对称提案限制、全局交换/N打联合博弈树、浏览器界面的 JSON 导入、自动权重训练、全局长时间赛钟。源码有校验事件一致性的 `Game.fromRecord` 重放入口。

候选剪枝与启发式评分是选择性搜索，不保证最优；禁手虽然覆盖递归判断和多种固定边界，未穷举全部15×15局面。正式比赛前仍应拿到课堂 PPT/裁判样例验证配置。小样本自对弈仅验证稳定性，不构成棋力或胜率证明。

Chrome 已实际进行浏览器验证；Edge、Safari 的真实浏览器/设备尚未测试，不将标准 API 兼容设计当作实测结论。完整证据见 [TEST_REPORT.md](TEST_REPORT.md)。