mirror of
https://github.com/LHY0125/Gobang-Game.git
synced 2026-06-29 00:45:55 +08:00
docs: 重写 README 并更新 .gitignore 适配 v2.0 架构
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
+14
-3
@@ -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/
|
||||
|
||||
@@ -1,45 +1,218 @@
|
||||
# Gobang (五子棋) v2.0
|
||||
<p align="center">
|
||||
<h1>Gobang</h1>
|
||||
<p>五子棋桌面应用 — Rust + Tauri + React 构建</p>
|
||||
</p>
|
||||
|
||||
Rust + Tauri 2.x + React 19 构建的五子棋桌面应用。
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/badge/version-2.0.0-blue" alt="version">
|
||||
<img src="https://img.shields.io/badge/tauri-2.x-ffa03a" alt="tauri">
|
||||
<img src="https://img.shields.io/badge/react-19-61dafb" alt="react">
|
||||
<img src="https://img.shields.io/badge/rust-1.95-000000" alt="rust">
|
||||
<img src="https://img.shields.io/badge/typescript-strict-blue" alt="typescript">
|
||||
<img src="https://img.shields.io/badge/license-MIT-green" alt="license">
|
||||
<img src="https://img.shields.io/badge/tests-26%20passed-brightgreen" alt="tests">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## 简介
|
||||
|
||||
Gobang 是一款五子棋桌面应用，支持本地双人、人机对战、网络联机和棋谱回放。
|
||||
|
||||
v2.0 使用 **Tauri 2.x + React 19 + TypeScript + Rust** 完全重写，替代了原有的 C + IUP GUI。
|
||||
|
||||
## 架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph 前端["React 前端"]
|
||||
UI[UI 组件层<br/>MainMenu / BoardCanvas / GameView / ReplayView]
|
||||
Store[状态管理<br/>Zustand Store]
|
||||
Core[纯逻辑层<br/>board-renderer / 坐标转换 / 类型定义]
|
||||
UI --> Store
|
||||
UI --> Core
|
||||
end
|
||||
|
||||
subgraph IPC["Tauri IPC 桥接"]
|
||||
invoke[invoke]
|
||||
end
|
||||
|
||||
subgraph 后端["Rust core 库"]
|
||||
Board[棋盘引擎<br/>落子 / 胜负 / 悔棋 / 候选位]
|
||||
Rules[禁手规则<br/>长连 / 双三 / 双四]
|
||||
AI[AI 引擎<br/>Alpha-Beta 搜索 / 棋形评分]
|
||||
LLM[LLM AI<br/>OpenAI 兼容 API]
|
||||
Network[网络对战<br/>renet P2P]
|
||||
Record[棋谱记录<br/>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) — 河南理工大学人工智能协会
|
||||
|
||||
Reference in New Issue
Block a user