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