275 lines
6.5 KiB
Markdown
275 lines
6.5 KiB
Markdown
# macOS 编译、部署与运行指南
|
||
|
||
> Card Game Engine — YAML DSL 驱动的棋牌规则引擎
|
||
> 仓库：https://git.pwhealth100.com/xiaoou/card-game-engine
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
| 依赖 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| .NET SDK | **10.0** | 编译和运行 |
|
||
| YamlDotNet | 18.1.0 | NuGet 自动拉取，无需手动安装 |
|
||
| xUnit | 2.9.2 | 测试框架，NuGet 自动拉取 |
|
||
| Git | 任意 | 拉取代码 |
|
||
|
||
### 安装 .NET 9.0 SDK
|
||
|
||
```bash
|
||
# 方式一：官网下载安装
|
||
# https://dotnet.microsoft.com/zh-cn/download/dotnet/10.0
|
||
# 选 macOS Arm64 (Apple Silicon) 或 x64 (Intel)
|
||
|
||
# 方式二：Homebrew
|
||
brew install dotnet-sdk
|
||
|
||
# 验证安装
|
||
dotnet --version
|
||
# 应输出 9.0.x
|
||
```
|
||
|
||
---
|
||
|
||
## 获取代码
|
||
|
||
```bash
|
||
git clone http://git.pwhealth100.com/xiaoou/card-game-engine.git
|
||
cd card-game-engine
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构速览
|
||
|
||
```
|
||
card-game-engine/
|
||
├── CardGameEngine.sln # 解决方案文件
|
||
├── RuleEngine/ # 核心引擎库（类库）
|
||
│ └── RuleEngine.csproj # net9.0, 依赖 YamlDotNet
|
||
├── RuleEngine.Tests/ # 单元测试（xUnit）
|
||
│ └── RuleEngine.Tests.csproj # net9.0, 引用 RuleEngine
|
||
├── Demo/ # 控制台 Demo（可执行）
|
||
│ └── Demo.csproj # net9.0, 引用 RuleEngine
|
||
├── dsl-examples/ # 4 种麻将 DSL 配置
|
||
│ ├── xuezhandaodi.yaml # 四川血战到底 (108张)
|
||
│ ├── guangdong_jipinghu.yaml # 广东鸡平胡 (136张+花)
|
||
│ ├── guobiao.yaml # 国标麻将 (144张, 81番)
|
||
│ └── wuhan.yaml # 武汉麻将 (癞子+258将)
|
||
├── docs/ # 设计文档
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 编译
|
||
|
||
```bash
|
||
# 还原 NuGet 包 + 编译全部项目
|
||
dotnet build
|
||
|
||
# 仅编译 Release 版本
|
||
dotnet build -c Release
|
||
|
||
# 编译通过后输出：
|
||
# RuleEngine -> RuleEngine/bin/Debug/net10.0/RuleEngine.dll
|
||
# Demo -> Demo/bin/Debug/net10.0/Demo
|
||
# RuleEngine.Tests -> RuleEngine.Tests/bin/Debug/net10.0/RuleEngine.Tests.dll
|
||
```
|
||
|
||
编译产物在各自项目的 `bin/Debug/net10.0/` 下。Demo 的可执行文件是 `Demo/bin/Debug/net10.0/Demo`（macOS 原生二进制）。
|
||
|
||
---
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
# 运行全部测试（45 个）
|
||
dotnet test
|
||
|
||
# 详细输出
|
||
dotnet test --verbosity normal
|
||
|
||
# 按名称筛选
|
||
dotnet test --filter "FullyQualifiedName~鬼牌"
|
||
dotnet test --filter "FullyQualifiedName~全不靠"
|
||
dotnet test --filter "FullyQualifiedName~番型"
|
||
```
|
||
|
||
预期输出：
|
||
```
|
||
Total tests: 45
|
||
Passed: 45
|
||
Failed: 0
|
||
```
|
||
|
||
---
|
||
|
||
## 运行 Demo
|
||
|
||
所有命令均在项目根目录 `card-game-engine/` 下执行。
|
||
|
||
### 交互模式（默认）
|
||
|
||
逐局展示发牌和事件，推荐首次运行：
|
||
|
||
```bash
|
||
dotnet run --project Demo
|
||
|
||
# 等价于
|
||
dotnet run --project Demo -- --dsl xuezhandaodi
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
=== 麻将规则引擎 Demo — 四川麻将血战到底 === (交互模式)
|
||
|
||
[发牌]
|
||
AI-东(庄): 1万, 3万, 5万, ...
|
||
AI-南: ...
|
||
牌墙剩余: 64 张
|
||
|
||
[AI-东] 摸牌: 7万
|
||
[AI-东] 出牌: 9筒
|
||
→ AI-西: 碰！
|
||
...
|
||
```
|
||
|
||
### 切换玩法
|
||
|
||
```bash
|
||
# 武汉麻将（红中癞子 + 258将）
|
||
dotnet run --project Demo -- --dsl wuhan
|
||
|
||
# 国标麻将（144张，81番种，≥8番起胡）
|
||
dotnet run --project Demo -- --dsl guobiao
|
||
|
||
# 广东麻将鸡平胡（136张 + 花牌）
|
||
dotnet run --project Demo -- --dsl guangdong_jipinghu
|
||
```
|
||
|
||
### 压测模式
|
||
|
||
批量运行 N 局，输出统计：
|
||
|
||
```bash
|
||
# 100 局自动模式
|
||
dotnet run --project Demo -- --auto --count 100
|
||
|
||
# 1000 局压力测试
|
||
dotnet run --project Demo -- --auto --count 1000
|
||
|
||
# 指定玩法压测
|
||
dotnet run --project Demo -- --auto --count 500 --dsl wuhan
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
[局 100/100] ✅ 流局 | 总耗时 0.1s
|
||
|
||
========================================
|
||
统计: 总对局 100 | 胡牌率 0.0% | 出错 0 | 平均 2ms/局
|
||
```
|
||
|
||
> 胡牌率 ≈ 0% 是正常的——当前 AI 是随机出牌，只用于验证引擎逻辑正确性。后续 MCTS/LLM AI 上线后胡牌率会显著提升。
|
||
|
||
---
|
||
|
||
## 部署（独立可执行文件）
|
||
|
||
### 单文件发布
|
||
|
||
生成不依赖 .NET Runtime 的独立可执行文件：
|
||
|
||
```bash
|
||
# macOS Apple Silicon (M1/M2/M3)
|
||
dotnet publish Demo -c Release -r osx-arm64 --self-contained true -p:PublishSingleFile=true -o publish/osx-arm64
|
||
|
||
# macOS Intel (x64)
|
||
dotnet publish Demo -c Release -r osx-x64 --self-contained true -p:PublishSingleFile=true -o publish/osx-x64
|
||
```
|
||
|
||
产物：
|
||
```
|
||
publish/osx-arm64/
|
||
├── Demo # 单文件可执行 (~65MB)
|
||
├── Demo.pdb # 调试符号（可删除）
|
||
└── *.dll # 已内嵌到 Demo 中
|
||
```
|
||
|
||
运行：
|
||
```bash
|
||
# 注意：dsl-examples 目录需和可执行文件在同一目录或通过绝对路径指定
|
||
cd publish/osx-arm64
|
||
cp -r ../../dsl-examples .
|
||
|
||
./Demo
|
||
./Demo --dsl wuhan --auto --count 100
|
||
```
|
||
|
||
### 裁剪发布（减小体积）
|
||
|
||
```bash
|
||
dotnet publish Demo -c Release -r osx-arm64 \
|
||
--self-contained true \
|
||
-p:PublishSingleFile=true \
|
||
-p:PublishTrimmed=true \
|
||
-o publish/osx-arm64-trimmed
|
||
```
|
||
|
||
> 裁剪后会分析并移除未使用的代码，体积约减少 30-50%。如果出现运行时缺失类型，需要配置 TrimmerRootAssembly。
|
||
|
||
---
|
||
|
||
## CI/CD 示例（GitHub Actions / 本地脚本）
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# build-and-test.sh — 一键编译 + 测试 + 压测
|
||
|
||
set -e
|
||
|
||
echo "=== 还原依赖 ==="
|
||
dotnet restore
|
||
|
||
echo "=== 编译 ==="
|
||
dotnet build -c Release
|
||
|
||
echo "=== 单元测试 ==="
|
||
dotnet test -c Release --verbosity normal
|
||
|
||
echo "=== 压测 200 局 ==="
|
||
dotnet run --project Demo -c Release -- --auto --count 200 --dsl xuezhandaodi
|
||
dotnet run --project Demo -c Release -- --auto --count 200 --dsl wuhan
|
||
|
||
echo "=== 全部通过 ==="
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### `dotnet: command not found`
|
||
未安装 .NET SDK，或 `/usr/local/share/dotnet` 不在 PATH 中。确认安装后重启终端。
|
||
|
||
### `error NU1101: Unable to find package YamlDotNet`
|
||
NuGet 源不可达。检查网络，或配置国内镜像：
|
||
```bash
|
||
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
|
||
```
|
||
|
||
### macOS 安全提示"无法验证开发者"
|
||
首次运行 `dotnet run` 或单文件 `Demo` 时可能弹出。执行：
|
||
```bash
|
||
# 对单个文件
|
||
xattr -d com.apple.quarantine Demo
|
||
|
||
# 或全局允许（系统偏好设置 → 安全性与隐私 → 仍要打开）
|
||
```
|
||
|
||
### DSL 文件找不到
|
||
Demo 默认从 `dsl-examples/` 相对路径加载。确保执行目录是项目根，或通过绝对路径指定：
|
||
```bash
|
||
dotnet run --project Demo -- --dsl /absolute/path/to/dsl-examples/wuhan
|
||
```
|