xiaoou/card-game-engine

Fork 0

Files

xiaoou 504189a918 build: 升级 net9.0 → net10.0 (服务端 SDK 已升级至 10.0.109)

2026-07-04 10:58:12 +08:00

6.5 KiB

Raw Permalink Blame History

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

# 方式一：官网下载安装
# 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

获取代码

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

编译

# 还原 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 原生二进制）。

运行测试

# 运行全部测试（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/ 下执行。

交互模式（默认）

逐局展示发牌和事件，推荐首次运行：

dotnet run --project Demo

# 等价于
dotnet run --project Demo -- --dsl xuezhandaodi

输出示例：

=== 麻将规则引擎 Demo — 四川麻将血战到底 === (交互模式)

[发牌]
  AI-东(庄): 1万, 3万, 5万, ...
  AI-南: ...
  牌墙剩余: 64 张

[AI-东] 摸牌: 7万
[AI-东] 出牌: 9筒
→ AI-西: 碰！
...

切换玩法

# 武汉麻将（红中癞子 + 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 局，输出统计：

# 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 的独立可执行文件：

# 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 中

运行：

# 注意：dsl-examples 目录需和可执行文件在同一目录或通过绝对路径指定
cd publish/osx-arm64
cp -r ../../dsl-examples .

./Demo
./Demo --dsl wuhan --auto --count 100

裁剪发布（减小体积）

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 / 本地脚本）

#!/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 源不可达。检查网络，或配置国内镜像：

dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

macOS 安全提示"无法验证开发者"

首次运行 dotnet run 或单文件 Demo 时可能弹出。执行：

# 对单个文件
xattr -d com.apple.quarantine Demo

# 或全局允许（系统偏好设置 → 安全性与隐私 → 仍要打开）

DSL 文件找不到

Demo 默认从 dsl-examples/ 相对路径加载。确保执行目录是项目根，或通过绝对路径指定：

dotnet run --project Demo -- --dsl /absolute/path/to/dsl-examples/wuhan

6.5 KiB Raw Permalink Blame History Unescape Escape