diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..eb94aa5 --- /dev/null +++ b/CHANGELOG.md @@ -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 搜索 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..14d1247 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,36 @@ +# 贡献者行为准则 + +## 我们的承诺 + +为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺：无论年龄、体型、残障、种族、性别认同和表达、经验水平、国籍、个人外貌、宗教、性取向或身份，参与本项目不会受到骚扰。 + +## 我们的标准 + +有助于创造积极环境的行为包括： + +- 使用友好和包容的语言 +- 尊重不同的观点和经验 +- 优雅地接受建设性批评 +- 关注对社区最有利的事情 +- 对其他社区成员表示同理心 + +不可接受的行为包括： + +- 使用性暗示语言或图像以及不受欢迎的性关注 +- 侮辱/贬损性评论以及人身攻击或政治攻击 +- 公开或私下的骚扰 +- 未经明确许可发布他人的私人信息 + +## 我们的责任 + +项目维护者有责任澄清可接受行为的标准，并应对任何不可接受的行为采取适当和公平的纠正措施。 + +## 范围 + +本行为准则适用于项目空间和代表项目的公共空间。 + +## 执行 + +可通过 GitHub Issues 或直接联系维护者报告辱骂、骚扰或其他不可接受的行为。所有投诉将被审查和调查，并将产生被认为必要且适合情况的回应。 + +本项目改编自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ee66580 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 警告 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..36db005 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md index 7602558..1fd8514 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..744971a --- /dev/null +++ b/SECURITY.md @@ -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 | 不再支持 |