texas-holdem-dsh-plugin

Readme

# DSH Desktop Texas Hold'em

一个运行在 DSH Desktop Web Profile 中的德州扑克插件，支持本地规则 AI 对战和同一局域网内的 2–6 人联机牌局。

插件采用 Host + Client 架构：Host 负责洗牌、发牌、行动校验、回合推进和结算；Client 只负责展示牌局状态并提交玩家操作。牌桌通过侧边栏入口打开，嵌入 DSH Desktop 中间工作区，并随侧边栏、详情栏和窗口尺寸自动调整布局。

## 运行效果

### 游戏开始页

![Texas Hold'em 游戏开始页](docs/media/holdem-home.png)

### 牌局界面

![Texas Hold'em 单机牌局](docs/media/holdem-game.png)

### 演示视频

[▶ 播放 14 秒运行演示（MP4）](docs/media/holdem-demo.mp4)

视频展示了单机牌局操作，以及侧边栏展开、收起时牌桌根据可用空间自动调整布局的效果。

## 功能

- 标准 52 张牌的 Texas Hold'em No-Limit 简化规则。
- 支持 Fold、Check、Call、Raise 和 All-in。
- 支持 Preflop、Flop、Turn、River、Showdown 和结算完整流程。
- 支持皇家同花顺至高牌的全部标准牌型比较。
- 支持平局、主池、边池和全押结算。
- 单机模式：1 名玩家对战本地规则 AI，不调用模型 API。
- 局域网模式：2–6 名真人玩家，通过房主 IPv4、临时端口和 6 位房间码加入。
- 房主 Host 维护唯一权威状态，并校验玩家身份、行动序号和状态版本。
- 对手底牌在摊牌前会被过滤，不发送给无权查看的客户端。
- 牌桌嵌入 DSH Desktop 中间区域，不覆盖侧边栏和详情栏。
- 窗口缩小时，牌局界面会根据可用宽高等比缩放，保持牌桌、座位和操作栏完整可见。
- 插件停止时会释放 UI 注册、定时器、牌局状态和局域网监听。

## 游戏规则

| 配置 | 默认值 |
| --- | ---: |
| 初始筹码 | 1,000 |
| 小盲注 | 10 |
| 大盲注 | 20 |
| 最小加注 | 20 |
| 局域网人数 | 2–6 人 |

筹码只用于游戏内计分，不具有现实货币价值。

## 安装

### 1. 克隆仓库

```bash
git clone https://github.com/tycket033-tech/dsh-holdem.git
cd dsh-holdem
```

### 2. 添加到 DSH Web Profile

编辑 DSH Web Profile 的 `package.json`。Windows 默认位置为：

```text
%USERPROFILE%\.dsh\profiles\web\package.json
```

将插件目录加入 `dependencies`，并将插件名称加入 `dsh.profile.bundles`。请保留文件中原有的其他依赖和 Bundle：

```json
{
  "dependencies": {
    "texas-holdem-dsh-plugin": "link:D:/path/to/dsh-holdem"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "texas-holdem-dsh-plugin"
      ]
    }
  }
}
```

在该 Profile 目录安装依赖，然后重启 DSH Desktop：

```bash
pnpm install
```

启动完成后，侧边栏底部会出现 `♠ Texas Hold'em` 入口。

## 如何游戏

### 单机模式

1. 点击侧边栏的 `Texas Hold'em`。
2. 输入昵称。
3. 点击“开始单机对战”。
4. 使用 Fold、Check、Call、Raise 或 All-in 完成牌局。
5. 结算后可以开始下一局或退出牌桌。

### 局域网模式

房主：

1. 点击“创建局域网房间”。
2. 将页面显示的 IPv4 地址、端口和房间码发给同一可信局域网内的玩家。
3. 至少两名玩家进入房间后点击“开始牌局”。

其他玩家：

1. 在加入房间区域输入房主地址，例如 `http://192.168.1.10:3080`。
2. 输入 6 位房间码和昵称。
3. 点击“加入房间”，等待房主开始。

局域网模式不提供公网中继、自动端口映射、NAT 穿透或房主迁移。

## 开发与测试

项目不需要构建步骤，Host 和 Client 均为原生 ES Module。运行测试：

```bash
npm test
```

监听模式：

```bash
npm run test:watch
```

当前测试覆盖：

- 标准牌型排序与七选五最佳牌型。
- 盲注、合法行动和完整街道推进。
- 过期状态拒绝与行动幂等标识。
- 全押、主池和边池结算。
- 对手底牌权限过滤。
- 本地规则 AI 完整牌局。
- 局域网房间人数、状态过滤和监听生命周期。

## 项目结构

```text
.
├── client.js            # DSH Client UI、侧边栏入口和自适应牌桌
├── index.js             # Host 插件入口和生命周期注册
├── cordis.patch.yml     # DSH Bundle 声明
├── src/
│   ├── ai.js            # 本地规则 AI
│   ├── cards.js         # 牌组、牌面与洗牌
│   ├── controller.js    # Host API 调度
│   ├── engine.js        # 权威牌局状态机
│   ├── errors.js        # 规则错误
│   ├── evaluator.js     # 牌型计算与比较
│   ├── network.js       # HTTP API 和临时局域网监听
│   └── room.js          # 局域网房间与玩家管理
└── test/
    └── holdem.test.js   # 规则、控制器和网络测试
```

## Host API

HTTP 前缀为 `/texas-holdem`。支持的方法包括：

```text
new-game
get-state
player-action
reset-game
create-room
join-room
start-room
room-state
room-action
reset-room
leave-room
```

DSH Host 也会在可用时通过 Harness 注册同名调用。所有参数和返回值都是可序列化 JSON。

## 安全说明

- 只建议在可信局域网内使用联机功能。
- 不要将临时端口、房间码或玩家 Token 暴露到公网。
- DSH Desktop 主 Web Server 无需改为 `0.0.0.0`。
- 首次创建局域网房间时，插件会在检测到的本机局域网 IPv4 上启动临时监听。
- 最后一个房间关闭或插件停止后，临时监听会自动释放。
- Client 不负责洗牌、判定胜负或直接修改筹码；关键操作始终由 Host 校验。

## 当前限制

- 不支持断线后的完整牌局恢复。
- 不支持自动发现局域网房间。
- 不支持公网联机、云端中继和房主迁移。
- 不保存跨重启战绩或筹码。
- AI 为本地规则 AI，不使用 DeepSeek 或其他模型服务。

## License

MIT