diff --git a/docs/macos-build-deploy.md b/docs/macos-build-deploy.md
new file mode 100644
index 0000000..de4d04b
--- /dev/null
+++ b/docs/macos-build-deploy.md
@@ -0,0 +1,274 @@
+# macOS 编译、部署与运行指南
+
+> Card Game Engine — YAML DSL 驱动的棋牌规则引擎  
+> 仓库：https://git.pwhealth100.com/xiaoou/card-game-engine
+
+---
+
+## 环境要求
+
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| .NET SDK | **9.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/9.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/net9.0/RuleEngine.dll
+#   Demo -> Demo/bin/Debug/net9.0/Demo
+#   RuleEngine.Tests -> RuleEngine.Tests/bin/Debug/net9.0/RuleEngine.Tests.dll
+```
+
+编译产物在各自项目的 `bin/Debug/net9.0/` 下。Demo 的可执行文件是 `Demo/bin/Debug/net9.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
+```