# PdkBot 架构设计

## 概述

PdkBot 是 hjha-server 跑得快游戏的自动出牌机器人系统。采用**外挂式**设计——不修改核心游戏逻辑，通过 `IPdkBot` 接口注入，模拟真人玩家参与牌局。

## 设计原则

### 1. 外挂式架构（非侵入）

```
PdkGameMain.WaitWanJiaShuRu()
  ├─ BotMode == false → Console.ReadLine()（人工输入）
  └─ BotMode == true  → bot.DecidePlay()
```

机器人只在 `WaitWanJiaShuRu()` 的 case 4（打牌）和 case 3（包庄）节点介入，完全不修改游戏状态机、规则引擎或结算逻辑。

### 2. 信息隔离（模拟真人视角）

机器人**只能看到**：
| 信息 | 来源字段 | 说明 |
|------|---------|------|
| 自己手牌 | `CardPack.Cards[myPos-1]` (GameState==1) | 16 张起 |
| 桌面最后出牌 | `Info.MaxPlayCard` | 谁出的什么牌型，GameNum==0 表示新一轮 |
| 各家剩余张数 | `Info.ShenYuCard[]` | 跑得快中这是公开信息 |
| 各家已出炸弹数 | `Info.ZhaDans[]` | 公开统计 |
| 游戏规则 | `Rule` | 关牌/经典/15 张、必压、AAA 炸弹等 |
| 游戏阶段 | `Info.GameZT` | 3=包庄 4=打牌 |

**不能看到**：其他玩家的具体手牌内容 (`CardPack.Cards[other].CardInfos`)。

### 3. 策略可插拔

```
IPdkBot (接口)
  ├─ PdkBot          ← 5 维启发式评分（当前默认）
  ├─ IsmctsBot       ← 蒙特卡洛树搜索（推荐）
  └─ CustomBot       ← 自定义策略只需实现接口
```

切换策略只需改 `PdkGameMain.InitBots()` 中的一行代码。

## 核心组件

### PdkBotView：可见信息快照

```csharp
public class PdkBotView
{
    TCardInfoPdkF[] MyHand;      // 我的手牌
    PlayOutCardPdkF MaxPlayCard; // 桌面最后一手
    int WhoPlay;                 // 当前轮到谁
    int MyPos;                   // 我的位置
    byte[] ShenYuCard;           // 各家剩余牌数
    int[] ZhaDans;               // 各家炸弹数
    PdkRule Rule;                // 游戏规则
    int GameZT;                  // 游戏阶段
}
```

由 `PdkGameMain.BuildBotView(pos)` 从完整游戏状态中**裁剪**生成，确保不泄漏。

### IPdkBot：策略接口

```csharp
public interface IPdkBot
{
    bool DecideBaoZhuang(PdkBotView view);
    PlayOutCardPdkF DecidePlay(PdkBotView view);
}
```

### GameBaoZhuang 状态机

包庄是逐人推进的：

```
BaoZhuang[] 值含义：
  0 → 尚未选择
  1 → 包庄
  2 → 不包庄

流程：
  GameFaPai → WhoPlay = FistPlay（黑桃3持有者）
  GameBaoZhuang()
    ├─ FistPlay 已选 1 → 直接打牌
    └─ 从 i=0 逐人轮询
        ├─ BaoZhuang[i]==0 → WhoPlay=i+1 → SendPack → bot/人回答
        ├─ BaoZhuang[i]==1 → 记录, bcount++
        └─ BaoZhuang[i]==2 → 跳过
  ↓
  bcount==1 → 唯一包庄
  bcount>1  → 庄家包则庄家, 否则下家
  bcount==0 → 无人包庄
  ↓
  GameZT=4 → 打牌
```

## 文件清单

| 文件 | 职责 |
|------|------|
| `PdkFriendServer/Logic/PdkBot.cs` | IPdkBot 接口、PdkBotView、PdkBot 启发式实现、IsmctsBot |
| `PdkFriendServer/Logic/PdkGameMain.cs` | BotMode 开关、BuildBotView、InitBots、WaitWanJiaShuRu 集成点 |
| `hjha-console/Program.cs` | `main.BotMode = true` 启动入口 |
| `docs/bot-architecture.md` | 本文档 |
| `docs/bot-algorithms.md` | 算法路径分析 |
| `docs/ismcts-design.md` | ISMCTS 实现设计 |

## 运行

```bash
cd ~/projects/hjha-server
dotnet run --project hjha-console
# 输出：bot-包庄 → bot出牌日志 → 结算输赢 → test over
```