# 围棋 · 在线对战
两个人用各自的电脑 / 平板打开网页就能下围棋。**Rust 后端 + 纯静态 HTML 前端**,服务端权威校验落子(提子、禁自杀、打劫、数子全在服务端算),不装 App、不注册账号、前端零构建。
```
浏览器 A ──┐ ┌── 规则引擎(提子 / 禁自杀 / 全局同形 / 数子 / 计时)
├── WebSocket ────┤
浏览器 B ──┘ └── 房间状态(棋盘 + 棋盘时钟 + 观战者 + 语音)
└── 观战者
Rust(axum + tokio) public/ 里的 html/css/js 由同一个进程托管
```

## 跑起来
需要 Rust 工具链(`cargo` 1.75+)。
```bash
cargo run --release # 或 cargo run 走 debug,编译更快
```
然后打开 (默认端口 3100,避开象棋项目的 3000;要改就 `PORT=3200 cargo run`)。
首次编译约 2~4 分钟(拉依赖 + 编 axum/tokio),之后增量编译几秒。
## 两个人怎么玩
**同一个 Wi-Fi(最简单)**
1. 你在电脑上打开 `http://localhost:3100`,选好棋盘大小(9 / 13 / 19 路)和每方时间,点「创建房间」,屏幕上会出现 4 位房号。
2. 终端启动服务时会顺便打印局域网地址,比如 `http://192.168.1.8:3100`。
3. 对方在平板 / 另一台电脑上打开这个地址,输入房号,点「加入」。
4. 黑先白后,白方看到的棋盘会自动旋转 180°,1 路始终在自己这边。
**看别人下棋**
输入房号点「只看」,就进入观战;两个座位都有人时,点「加入」也会自动变成观战。观战者能看到实时棋局、手数和双方剩余时间,但动不了棋盘。
**不在同一个 Wi-Fi**
把编译出的单文件二进制丢到有公网 IP 的服务器上(见下一节),`PORT=3100 ./cngo`。用 Nginx/Caddy 反代时记得放行 WebSocket 的 `Upgrade` 头:
```nginx
location / {
proxy_pass http://127.0.0.1:3100;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
```
## 编译成单文件程序
```bash
cargo build --release
```
产物:`target/release/cngo`(自带 HTTP/WS 服务 + 内嵌前端资源,不依赖任何运行时)。
`build.rs` 会把 `public/` 整个目录编译进二进制,所以拷到没装任何东西的电脑 / NAS / 树莓派上直接跑;
`/health` 里能看到 `"engine":"rust"`、`"game":"go"`、`"mode":"embedded"`。
- 默认只编「当前系统 + 当前架构」。要给 Linux x86_64 用,就在 Linux 上 `cargo build --release`,
或用 `cargo zigbuild` / 交叉工具链。
- 前端资源已内嵌,但**程序同目录若存在 `public/`,会优先用磁盘上的版本**,方便临时改页面。
## 改前端不用编译
`public/` 里的 `index.html`、`style.css`、`js/**/*.js` 就是最终产物,浏览器直接加载 ES module:
```
public/
index.html 页面骨架
style.css 样式(深色 + 木色棋盘)
js/shared/rules.js 规则引擎的浏览器副本(本地双人模式、落点校验)
js/client/board.js Canvas 棋盘绘制:木板木纹、星位、坐标、棋子高光、落点预览
js/client/main.js 界面状态、联机逻辑、计时、断线重连、终局数子展示、语音界面
js/client/sound.js WebAudio 现场合成的落子声(噪声脉冲,无音频文件)
js/client/voice.js 按住说话的录音(MediaRecorder)、base64 编解码、播放
```
改完存盘刷新即可(服务端对静态资源发 `Cache-Control: no-cache`)。
注意 `js/shared/rules.js` 是 `src/rules.rs` 的 JS 镜像:**改规则要两边一起改**,
服务端才是权威,前端那份只负责「点下去之前先告诉你能不能下」。
## 代码结构
```
src/rules.rs 规则引擎:气与棋块、提子、禁自杀、全局同形(超级劫)、数子、坐标记法
src/protocol.rs WebSocket 消息类型(serde 序列化,与 public/js 里的 JSON 契约一致)
src/server.rs 房间管理 + 权威校验 + 棋盘时钟 + 观战席 + 静态文件服务
src/main.rs 启动、端口/绑定地址、局域网地址打印
build.rs 把 public/ 压成资源表编进二进制
tests/e2e.rs 双客户端联机流程(含提子、观战、停一手数子、认输、再来一局、静态资源、语音)
```
## 测试
```bash
cargo test
```
- `rules::tests` —— 15 组规则断言(提单子/整块、禁自杀、提子优先于自杀、角上提子、超级劫、
数子与贴目、坐标记法跳过 I、编码往返、气数计算)
- `tests/e2e.rs` —— 5 组联机断言(建房→加入→落子→抢手被拒→重复落点被拒→观战禁下→停两手数子→再来一局;
角上提子与认输;未知房号;`/health` 与静态资源;语音收发/历史取回/观战禁发/超长拒绝)
单跑某一组:`cargo test superko` / `cargo test --test e2e`。
## 规则口径
按**中国规则(数子 / 面积计算)**实现,够两个人下棋用,不做裁判级抠细节:
| 事情 | 怎么判 |
| --- | --- |
| 提子 | 落子后对方某块棋气为 0,整块提掉,被提的子计入本方「提子数」 |
| 禁着点 | 落子后自己这块没气、又提不到对方子 → 不合法(自杀禁止) |
| 打劫 | 全局同形禁止(超级劫):任何让局面与之前完全相同的着法都不合法,提示「先到别处应一手」 |
| 停一手 | 右侧「停一手」或按 `P`;双方各停一手即终局 |
| 终局 | 数子:本方活子数 + 只被本方围住的空点;白贴 7.5 目(3 又 3/4 子) |
| 超时 | 时间归零判负;有一方掉线时计时自动暂停,不算他输 |
| 重开 | 双方都点「再来一局」才重开(对手已离开时直接重开) |
| 认输 | 右侧「认输」 |
| 掉线 | 重新打开邀请链接,会回到原来坐的那一边 |
**数子的简化**:双活(seki)里的空点按「双方都能进」记为中性,不给任何一方;
死子不会自动识别为死子 —— 所以终局前请自己把死子提干净,或者干脆下到没有争议再双方停手。
真要精确判定死活,得接一个死活判定引擎,见「还没做的」。
## 玩法细节
| 做的事情 | 怎么操作 |
| --- | --- |
| 落子 | 点交叉点就落;鼠标悬停会先显示一颗半透明的子,点偏了也算最近的交叉点 |
| 提子 | 目标点周围对方棋块没气时自动提,落子声会变成连响,右侧「提 N」会加 |
| 停一手 | 右侧「停一手」或键盘 `P` |
| 计时 | 建房时选 10 / 20 / 40 分钟或不限时;每方各自扣时,落子或停手后换对方 |
| 手数 | 棋谱按手数两列排,带 `提N` 标记;坐标用围棋习惯记法(跳过字母 I) |
| 上一手 | 棋盘上用红点标出最后一手的位置 |
| 观战 | 右侧显示观战人数;观战者不能落子、不能发语音 |
## 语音互动
棋盘右侧面板下方就是语音区,不用切换页面:
- **按住「按住说话」**(鼠标 / 手指都行)开始录,**松手自动发**;最长 30 秒,到点自动停并发出。
- 对方收到立刻播放,同时进「互动记录」列表;发的人自己不回放。
- 点列表里任意一条就放那条,再点一次停。列表带发送方(黑/白)、时长和时刻。
- 观战者能听、能点历史,但不能发(按钮会提示「观战中只能听」);本地双人模式没有语音。
实现上:浏览器 `MediaRecorder` 录成 **webm/opus**(Safari 落到 `audio/mp4`),base64 后走同一条 WebSocket。
服务端把每条语音的**元信息**放进房间状态,音频本体只在发的那一刻广播一次、点历史时用 `voiceGet` 单独取。
房间内保留最近 **40 条**、总量约 12MB(base64 后),超出丢最旧的;每局「再来一局」会清空语音记录。
> 跨内核播放:Chrome/Firefox 录的是 webm/opus,Safari 播不了 webm,Safari 录的 mp4 反过来 Chrome 能播。
> 所以跨平台对局可能遇到「对方发的听不见」——需要服务端转码才能彻底解决,目前没做。
## 还没做的
- 死活判定与死子自动标记(现在的数子只做「子 + 空」的静态统计)
- 让子局 / 贴目自定义(现在固定 7.5 目,黑先)
- 悔棋、棋谱回放、SGF 导入导出
- 读秒(现在只有一次性包干时间)
- 语音转码(webm ↔ mp4)与语音落盘:目前只在内存里,重启即清
- 棋局持久化:服务端所有棋局都在内存里,重启就清空(空房 10 分钟回收,有人的房 4 小时)
- 多进程 / 多机部署(房间在进程内存里,要横向扩得先接 Redis 之类的外置状态)
## 依赖下载 / 编译加速(本机已配,遵循 dev-cache-layout)
- 依赖走 **USTC sparse 镜像**,包缓存实体集中在 `~/.cache/cargo/registry`(`~/.cargo/registry` 是软链指向它)。
- 编译包了一层 **sccache**(`rustc-wrapper`,实体 `~/.cache/sccache`),冷启动 / 清 target 重建能省三分之一时间。
- `jobs = 3`:本机 2 核 4 线程 8G 内存的安全上限,别调 4。
- 配置都在 `~/.cargo/config.toml`,仓库里**不需要**再放 `.cargo/config.toml`。
- **`target/` 留在项目目录**(增量编译 + 复查用),已在 `.gitignore`;不要挪到 `~/Library/Caches` 再软链回来
—— 软链不被 `.gitignore` 的目录型规则匹配,`git status` 会冒 `??`,而且缓存脱离项目生命周期。
- 前端零构建(原生 ES module),**没有 npm / node_modules / 打包缓存**,不需要给这个项目单独配包缓存。