From 605e01803faf6fa19d4cdc35aaf527ea3b0df1f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Sun, 31 May 2026 12:57:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=20=E5=B9=B6?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20.gitignore=20=E9=80=82=E9=85=8D=20v2.0=20?= =?UTF-8?q?=E6=9E=B6=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- .gitignore | 17 +++- README.md | 227 ++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 214 insertions(+), 30 deletions(-) diff --git a/.gitignore b/.gitignore index cd2db96..a82ca51 100644 --- a/.gitignore +++ b/.gitignore @@ -3,15 +3,26 @@ dist dist-ssr *.local target/ + +# Editor .vscode/* !.vscode/extensions.json .idea .DS_Store *.suo *.sw? + +# Claude .claude/ .codegraph/ CLAUDE.md -build/ -bin/gobang_config.ini -*.png + +# Env & logs +.env +*.log + +# OS +Thumbs.db + +# Tauri +gui/gen/ diff --git a/README.md b/README.md index 1fd8514..bda2768 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,218 @@ -# Gobang (五子棋) v2.0 +

+

Gobang

+

五子棋桌面应用 — Rust + Tauri + React 构建

+

-Rust + Tauri 2.x + React 19 构建的五子棋桌面应用。 +

+ version + tauri + react + rust + typescript + license + tests +

+ +--- + +## 简介 + +Gobang 是一款五子棋桌面应用，支持本地双人、人机对战、网络联机和棋谱回放。 + +v2.0 使用 **Tauri 2.x + React 19 + TypeScript + Rust** 完全重写，替代了原有的 C + IUP GUI。 + +## 架构 + +```mermaid +graph TB + subgraph 前端["React 前端"] + UI[UI 组件层
MainMenu / BoardCanvas / GameView / ReplayView] + Store[状态管理
Zustand Store] + Core[纯逻辑层
board-renderer / 坐标转换 / 类型定义] + UI --> Store + UI --> Core + end + + subgraph IPC["Tauri IPC 桥接"] + invoke[invoke] + end + + subgraph 后端["Rust core 库"] + Board[棋盘引擎
落子 / 胜负 / 悔棋 / 候选位] + Rules[禁手规则
长连 / 双三 / 双四] + AI[AI 引擎
Alpha-Beta 搜索 / 棋形评分] + LLM[LLM AI
OpenAI 兼容 API] + Network[网络对战
renet P2P] + Record[棋谱记录
JSON 序列化] + end + + UI --> invoke + invoke --> Board + invoke --> AI + invoke --> Network + invoke --> Record + invoke --> Rules + LLM --> AI + AI --> Board + AI --> Rules +``` + +### 数据流 + +```mermaid +sequenceDiagram + actor U as 用户 + participant UI as React UI + participant Z as Zustand Store + participant IPC as Tauri IPC + participant R as Rust 后端 + + U->>UI: 点击棋盘 + UI->>Z: placePiece(x, y) + Z->>IPC: invoke('place_piece', {x, y}) + IPC->>R: commands::place_piece() + R->>R: Board::place() + check_win() + is_forbidden() + IPC-->>Z: MoveResult + Z->>UI: 更新棋盘渲染 + + alt 人机模式 + Z->>IPC: invoke('ai_move') + IPC->>R: AiEngine::best_move() + R-->>Z: Position + Z->>IPC: invoke('place_piece', pos) + end +``` ## 功能 -- 本地双人对战 -- 人机对战 (Alpha-Beta 剪枝 AI, 5 级难度) -- 网络对战 (renet P2P) -- LLM 大模型 AI -- 棋谱记录与回放 (JSON) -- 禁手规则 (长连/双三/双四) -- 中/英双语 +### 游戏模式 + +- **本地双人** — 同机两人轮流落子 +- **人机对战** — Alpha-Beta 剪枝 AI，5 级难度可调 +- **网络对战** — renet P2P 联机（纯 Rust ENet 协议） +- **LLM AI** — 大模型 API 接入对战（OpenAI 兼容接口） + +### 游戏规则 + +- 标准五子棋规则，黑方先手 +- **禁手规则**（可开关）：长连禁手、双三禁手、双四禁手 +- 悔棋功能 + +### 棋谱 + +- JSON 格式棋谱记录与回放 +- 步进滑块逐帧复盘 +- 自动播放模式 + +### 界面 + +- Canvas 木纹风格棋盘渲染 +- 棋子径向渐变 + 最后一手红圈高亮 +- 中 / English 界面切换 +- 计时器（可选） + +## 安装 + +从 [Releases](https://github.com/LHY0125/Gobang-Game/releases) 下载最新版安装包。 + +或从源码构建： + +```bash +npm install +npx tauri build +``` + +> **要求**：Windows 10+（自带 WebView2）。 ## 开发 -### 环境要求 +```bash +# 开发模式 GUI（热更新） +npx tauri dev + +# 仅前端 +npm run dev + +# 前端测试 +npm test + +# Rust 检查 +cargo check +cargo clippy -- -D warnings + +# Rust 测试 +cargo test + +# 完整构建 +npx tauri build +``` + +### 技术栈 + +| 层 | 技术 | +|---|---| +| 前端框架 | React 19 + TypeScript (strict) | +| 状态管理 | Zustand | +| 国际化 | i18next | +| 桌面框架 | Tauri 2.x | +| 核心库 | Rust workspace (core + gui) | +| 网络 | renet | +| 棋谱 | serde_json | +| Rust 测试 | cargo test (26 个测试) | +| 构建 | Vite + Cargo | + +### 项目结构 + +``` +core/ # Rust 核心库（零 Tauri 依赖） +├── types.rs # 类型定义 (Position, Color, Board, GameConfig) +├── board.rs # 棋盘引擎 (落子/胜负/悔棋/候选位) +├── rules.rs # 禁手规则 (长连/双三/双四) +├── ai/ +│ ├── evaluate.rs # 棋形评分 (连五/活四/冲四/活三) +│ └── search.rs # Alpha-Beta 搜索 + Negamax +├── record.rs # JSON 棋谱记录与复盘 +├── network.rs # renet 网络对战协议 +└── llm.rs # LLM AI (OpenAI 兼容 API) +gui/ # Tauri 桌面应用 +└── src/ + ├── lib.rs # Tauri Builder + 状态管理 + ├── commands.rs # IPC 命令 (薄层调用 core) + └── main.rs # 入口 +src/ # React 前端 +├── core/ # 纯逻辑 (types, constants) +├── store/ # Zustand 状态管理 +├── components/ +│ ├── board/ # BoardCanvas + board-renderer +│ ├── menu/ # MainMenu / LocalGame / AiGame / Online / Replay +│ ├── game/ # GameView / GameInfo / TimerDisplay / GameControls +│ └── replay/ # ReplayView / StepSlider / ReplayControls +├── hooks/ # 通用 hooks +└── i18n/ # zh-CN / en +docs/ # 设计文档与实施计划 +``` + +## 贡献 + +欢迎提交 Issue 和 Pull Request。大改动前建议先开 Issue 讨论。 + +### 本地开发环境 - Node.js 22+ - Rust 1.95+ (stable-x86_64-pc-windows-gnu) - MinGW-w64 - Windows 10+ -### 命令 +### 代码规范 -```bash -npm install # 安装前端依赖 -npx tauri dev # 开发模式 -npx tauri build # 生产构建 -cargo test # Rust 测试 -cargo clippy -- -D warnings # Lint -npm test # 前端测试 -``` +- TypeScript `strict: true`，零编译错误 +- Rust `cargo clippy -- -D warnings` 零警告 +- AI 引擎通过 `AiEngine` trait 抽象，可替换 -## 架构 +## 许可证 -``` -core/ # Rust 游戏核心库 (零 Tauri 依赖) -gui/ # Tauri 桌面应用 (薄命令层) -src/ # React 前端 (TypeScript strict) -``` +MIT License -## 许可 +## 作者 -MIT +[刘航宇](https://github.com/LHY0125) — 河南理工大学人工智能协会