Serendipity/Gobang-Game
1
1
Fork 0
mirror of https://github.com/LHY0125/Gobang-Game.git synced 2026-06-28 16:35:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 开源文件 — LICENSE/CHANGELOG/CODE_OF_CONDUCT/CONTRIBUTING/SECURITY/README

Browse Source 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
刘航宇
2026-05-31 00:29:00 +08:00
parent e395ea424b
commit 4126b9f74c
6 changed files with 211 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+20
View File
@@ -0,0 +1,20 @@
# Changelog
## 2.0.0 (2026-05-31)
### Added
- Rust + Tauri 2.x + React 19 + TypeScript strict 全重写
- Cargo workspace 两 crate 架构 (core + gui)
- Canvas 木纹风格棋盘渲染
- 中英双语界面 (i18next)
- Alpha-Beta 剪枝 AI 引擎 (5 级难度)
- LLM 大模型 AI (OpenAI 兼容 API)
- renet 网络对战 (纯 Rust ENet 协议)
- JSON 棋谱记录与回放
- Zustand 状态管理
### Changed
- 从 C + IUP + CMake 迁移到 Rust + Tauri + Vite
- 棋谱格式从二进制改为 JSON
- 网络协议从 ENet C 库改为 renet 纯 Rust 实现
- AI 从评分制升级为 Alpha-Beta 搜索
CODE_OF_CONDUCT.md
+36
View File
@@ -0,0 +1,36 @@
# 贡献者行为准则
## 我们的承诺
为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺：无论年龄、体型、残障、种族、性别认同和表达、经验水平、国籍、个人外貌、宗教、性取向或身份，参与本项目不会受到骚扰。
## 我们的标准
有助于创造积极环境的行为包括：
- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心
不可接受的行为包括：
- 使用性暗示语言或图像以及不受欢迎的性关注
- 侮辱/贬损性评论以及人身攻击或政治攻击
- 公开或私下的骚扰
- 未经明确许可发布他人的私人信息
## 我们的责任
项目维护者有责任澄清可接受行为的标准，并应对任何不可接受的行为采取适当和公平的纠正措施。
## 范围
本行为准则适用于项目空间和代表项目的公共空间。
## 执行
可通过 GitHub Issues 或直接联系维护者报告辱骂、骚扰或其他不可接受的行为。所有投诉将被审查和调查，并将产生被认为必要且适合情况的回应。
本项目改编自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版。
CONTRIBUTING.md
+73
View File
@@ -0,0 +1,73 @@
# 贡献指南
## 本地开发环境
- **Node.js** 22+
- **Rust** 1.95+ (stable-x86_64-pc-windows-gnu)
- **MinGW-w64** (GCC 15.x 需 `-lmcfgthread` 链接标志)
- **Windows 10+** (自带 WebView2)
## 开发流程
1. Fork 本仓库
2. `git clone <你的 fork>`
3. `git checkout -b feature/xxx`
4. 开发 + 测试
5. `git commit` (遵循约定式提交格式)
6. `git push`
7. 提交 Pull Request
## 运行测试
```bash
# 前端单元测试
npm test
# Rust 测试
cargo test
# E2E 测试 (需要先 npx tauri dev)
npx playwright test
# Clippy 检查
cargo clippy -- -D warnings
```
## 代码规范
### TypeScript
- `strict: true`，零编译错误
- 核心逻辑在 `src/core/`，纯函数，零框架依赖
- 不可变操作优先
### Rust
- 所有 `pub fn` 必须有 `///` 文档注释
- 所有 `unsafe` 块必须有 `// SAFETY:` 注释
- `cargo clippy -- -D warnings` 零警告
- `cargo fmt` 统一格式
## 提交格式
```
<类型>: <描述>
```
类型：`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`
## 项目结构
```
core/ # Rust 游戏核心库（零 Tauri 依赖）
gui/ # Tauri 桌面应用
src/ # React 前端
tests/ # 前端单元测试
e2e/ # Playwright E2E 测试
```
## 开始贡献前
- 大改动建议先开 Issue 讨论
- 新功能需要对应的测试
- 不要引入新的 clippy 警告
LICENSE
+21
View File
@@ -0,0 +1,21 @@
# MIT License
Copyright (c) 2026 LHY
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+30 -142
View File
@@ -1,157 +1,45 @@
# C语言五子棋系统
# Gobang (五子棋) v2.0
![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-v9.0-blue)
![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)
Rust + Tauri 2.x + React 19 构建的五子棋桌面应用。
> 🎯 **最新版本 v9.0** - 全面集成 ENet 网络联机功能，重构 GUI 代码架构，纯图形化交互体验。
## 功能
## 📋 大版本更新
- 本地双人对战
- 人机对战 (Alpha-Beta 剪枝 AI, 5 级难度)
- 网络对战 (renet P2P)
- LLM 大模型 AI
- 棋谱记录与回放 (JSON)
- 禁手规则 (长连/双三/双四)
- 中/英双语
### v9.0 (2026-03-17) - 局域网联机与 GUI 架构重构
## 开发
- 🌐 **局域网对战** - 引入 ENet 库，支持稳定、无粘包的局域网多人对战（创建房间/加入房间）。
- 🎨 **GUI 深度重构** - 拆分臃肿的 GUI 代码，模块化为 `gui_core`, `gui_game`, `gui_menu`, `gui_draw`, `gui_replay`，大幅提升可维护性。
- 📦 **精简安装包** - 优化 Inno Setup 打包脚本，实现极简核心依赖打包。
- � **全面摒弃控制台** - 专注于基于 IUP 的原生图形化交互体验。
### 环境要求
---
- Node.js 22+
- Rust 1.95+ (stable-x86_64-pc-windows-gnu)
- MinGW-w64
- Windows 10+
## 目录
- [C语言五子棋系统](#c语言五子棋系统)
- [📋 大版本更新](#-大版本更新)
- [v9.0 (2026-03-17) - 局域网联机与 GUI 架构重构](#v90-2026-03-17---局域网联机与-gui-架构重构)
- [目录](#目录)
- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [🎮 游戏模式](#-游戏模式)
- [⚙️ 核心功能](#️-核心功能)
- [快速开始](#快速开始)
- [编译项目](#编译项目)
- [打包安装程序](#打包安装程序)
- [游戏玩法](#游戏玩法)
- [技术架构](#技术架构)
- [AI 算法](#ai-算法)
- [网络通信](#网络通信)
- [图形界面](#图形界面)
- [项目结构](#项目结构)
- [许可证](#许可证)
---
## 项目简介
这是一个使用纯 C 语言编写的现代化五子棋系统。采用轻量级的 IUP 库构建原生风格的图形化用户界面。系统不仅支持基于 Minimax 算法（带 Alpha-Beta 剪枝）的高级人机对战，还完美支持基于 ENet 的局域网多人实时联机对弈。
## 功能特性
### 🎮 游戏模式
- **人机对战 (PvE)** - 挑战 1-5 级难度的智能 AI。
- **局域网联机 (Network)** - 建立主机或作为客机加入，与朋友在局域网内实时对战。
- **复盘模式 (Replay)** - 载入自动保存的对局记录（CSV），逐步回放并分析对局。
### ⚙️ 核心功能
- **实时对局控制** - 支持悔棋（PvE）、断线重连检测、胜负判定。
- **自动游戏记录** - 每局游戏结束后自动保存至 `bin/records/` 目录。
- **模块化构建** - 提供高度配置化的 Makefile，一键源码编译包含 ENet 和主程序的二进制文件。
---
## 快速开始
### 编译项目
项目使用 Makefile 进行构建，依赖 MinGW-w64 工具链。
在项目根目录下打开 PowerShell 或 CMD，运行：
### 命令
```bash
# 清理旧文件
mingw32-make clean
# 编译生成 GUI 可执行文件
mingw32-make gui
npm install # 安装前端依赖
npx tauri dev # 开发模式
npx tauri build # 生产构建
cargo test # Rust 测试
cargo clippy -- -D warnings # Lint
npm test # 前端测试
```
生成的可执行文件 `gobang_gui.exe` 和所需的动态链接库 `iup.dll` 会输出到 `bin/` 目录下。
## 架构
**运行游戏：**
```bash
.\bin\gobang_gui.exe
```
core/ # Rust 游戏核心库 (零 Tauri 依赖)
gui/ # Tauri 桌面应用 (薄命令层)
src/ # React 前端 (TypeScript strict)
```
### 打包安装程序
## 许可
如果你需要将游戏打包成 Windows 安装程序，项目提供了 Inno Setup 脚本。
确保你已安装 [Inno Setup 6](https://jrsoftware.org/isinfo.php)，然后运行：
```powershell
& "D:\Program Files (x86)\Inno Setup 6\iscc.exe" installer\installer.iss
```
生成的安装包 `Gobang_Inno_Setup.exe` 将存放在 `installer\dist\` 目录下。
---
## 游戏玩法
1. 运行 `gobang_gui.exe` 启动游戏主菜单。
2. 选择你要进行的游戏模式：
- **人机对战**：直接进入游戏，玩家执黑先行，点击棋盘空白处落子。
- **局域网联机**：
- **作为房主**：点击“局域网联机” -> “创建房间”，等待好友加入（默认端口8888）。
- **作为玩家**：点击“局域网联机” -> 输入房主的 IP 地址和端口 -> “加入房间”。
- **复盘模式**：选择历史对局记录，使用“上一步/下一步”按钮进行回放。
---
## 技术架构
### AI 算法
- **Minimax 博弈树**：遍历所有可能的落子情况。
- **Alpha-Beta 剪枝**：极大提升搜索效率，AI 默认思考深度为 3 层。
- **启发式评估函数**：基于连五、活四、冲四、活三等经典五子棋棋型进行棋局评分。
### 网络通信
- **底层库**：[ENet](http://enet.bespin.org/) (基于 UDP 的可靠网络传输协议)。
- **机制**：游戏采用非阻塞轮询机制处理网络事件，完美解决传统 TCP 粘包问题，确保落子坐标、断开连接等指令 100% 可靠送达。
### 图形界面
- **底层库**：[IUP](https://www.tecgraf.puc-rio.br/iup/) (轻量级、跨平台的 C 语言原生 GUI 库)。
- **机制**：事件驱动架构，通过回调函数响应用户的鼠标点击、按钮触发和窗口切换。
---
## 项目结构
```text
Gobang/
├── bin/ # 编译输出目录 (包含 exe, dll 和 records)
├── include/ # 头文件目录
├── libs/ # 第三方库源码及预编译库 (ENet, IUP)
├── src/ # 核心源代码
│ ├── main.c # 程序入口
│ ├── gobang.c # 五子棋核心规则与逻辑
│ ├── ai.c # 智能 AI 算法
│ ├── network.c # ENet 网络通信封装
│ ├── record.c # 棋谱记录与解析
│ ├── gui_core.c # GUI 初始化与核心循环
│ ├── gui_game.c # 游戏主界面与交互逻辑
│ ├── gui_menu.c # 游戏主菜单界面
│ ├── gui_draw.c # 棋盘与棋子渲染
│ └── gui_replay.c # 复盘模式交互逻辑
├── installer/ # Inno Setup 安装包打包脚本及输出
├── Makefile # 自动化构建脚本
└── README.md # 项目说明文档
```
## 许可证
本项目采用 [MIT 许可证](https://opensource.org/licenses/MIT)授权。欢迎自由修改和分发！
MIT
SECURITY.md
+31
View File
@@ -0,0 +1,31 @@
# 安全策略
## 报告漏洞
如果你发现安全漏洞，请**不要**在公开 Issue 中报告。请通过以下方式私下报告：
- GitHub: 在 [Security Advisories](https://github.com/LHY0125/Gobang/security/advisories) 页面提交
- 邮件: 联系项目维护者
我们会在 **48 小时内**确认收到报告，并在 7 天内提供初步评估和修复计划。
## 安全最佳实践
### 作为用户
- 仅从 [Releases](https://github.com/LHY0125/Gobang/releases) 页面下载安装包
- 网络对战时确保在可信网络环境中进行
### 作为开发者
- 永远不要在源代码中硬编码密钥或凭据
- 所有 `unsafe` 块必须有 `// SAFETY:` 注释
- 输入验证在系统边界执行
## 支持版本
| 版本 | 支持状态 |
|------|----------|
| v2.x | 活跃支持 |
| v1.x | 仅安全修复 |
| < v1.0 | 不再支持 |