Files
cngo/README.md
T
rong cb28bbb49e feat: 围棋在线对战(Rust 服务端 + 零构建前端)
- 规则引擎:提子、禁自杀、全局同形(超级劫)、中国规则数子(白贴 7.5 目)、停一手终局
- 服务端:axum + tokio,房间/观战/包干计时/断线重连/语音中继,前端资源内嵌单文件
- 前端:Canvas 木纹棋盘(9/13/19 路、星位、四边坐标、翻转视角)、WebAudio 合成落子声、
  本机双人模式、终局数子面板
- 测试:16 组规则断言 + 5 组 e2e(提子/劫/数子/观战/语音/静态资源)
- 构建缓存遵循 dev-cache-layout:target/ 留项目内并忽略,前端零构建不产生包缓存
2026-10-23 10:12:55 +08:00

186 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 围棋 · 在线对战
两个人用各自的电脑 / 平板打开网页就能下围棋。**Rust 后端 + 纯静态 HTML 前端**,服务端权威校验落子(提子、禁自杀、打劫、数子全在服务端算),不装 App、不注册账号、前端零构建。
```
浏览器 A ──┐ ┌── 规则引擎(提子 / 禁自杀 / 全局同形 / 数子 / 计时)
├── WebSocket ────┤
浏览器 B ──┘ └── 房间状态(棋盘 + 棋盘时钟 + 观战者 + 语音)
└── 观战者
Rust(axum + tokio) public/ 里的 html/css/js 由同一个进程托管
```
![桌面版对局](docs/shot-desktop.jpg)
<p>
<img src="docs/shot-room.jpg" width="32%" alt="建房" />
<img src="docs/shot-score.jpg" width="32%" alt="数子终局" />
<img src="docs/shot-mobile.jpg" width="17%" alt="手机竖屏" />
</p>
## 跑起来
需要 Rust 工具链(`cargo` 1.75+)。
```bash
cargo run --release # 或 cargo run 走 debug,编译更快
```
然后打开 <http://localhost:3100>(默认端口 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 / 打包缓存**,不需要给这个项目单独配包缓存。