Raybbish/dsh-poker-plugin

dsh-poker — DSH 的扑克插件

一个社区构建的 游戏中心，用于 DSH Web UI（dsh web）：一个本地、
多人 德州扑克 MVP，可在同一台机器的多个浏览器窗口中游玩。仅使用游戏
代币——无钱包、无真钱、无公共网络。

非官方社区插件。 本项目与 DeepSeek 无关联、未获其赞助或认可。它使用
自己的名称和视觉标识。不支持充值、奖品、提现、兑现或真钱投注。

该架构借鉴了
leeclouddragon/dsh-all-in 的若干经验——一个
极简的 DSH 插槽接缝、纯粹且可注入的游戏规则、明确的投注状态、
不变量驱动的模拟以及产物级构建门禁——同时有意
保留本项目服务器权威的多人游戏、WebSocket、账本、
身份注册表以及可选的 AI 提供方模型。参见
架构 → 采纳的原则与有意的差异。

┌──────────────────────────────────────────────────────────────┐
│ dsh web (127.0.0.1:3080)                                     │
│  侧边栏页脚：  ♠ Poker   ← 游戏中心入口                        │
│  覆盖层：        大厅 → 深色扑克牌桌                            │
│                                                              │
│  主机（同一进程）                                             │
│   dsh-poker（cordis 插件）                                    │
│    ├─ TableService   权威状态、命令、计时器                    │
│    ├─ PokerEngine    纯德州扑克状态机                          │
│    ├─ Ledger         游戏代币账本（不可变，整数）               │
│    ├─ storage-domain poker 单元  ($DSH_HOME/storages/poker.json) │
│    └─ /poker/ws      WebSocket 网关（实时）                    │
└──────────────────────────────────────────────────────────────┘

功能（MVP）

- 大厅 — 创建牌桌（2–10 个座位），通过列表或房间 ID（复制
按钮）加入，昵称 + 买入，钱包显示。
- 中文 / 英文模式 — 从房间
栏、大厅和操作到结果、错误和牌局历史，切换整个界面。浏览器
会记住所选语言。
- 富有表现力的牌桌 UI — 侧边栏和牌桌会展示主机 Agent 的
思考 / 空闲状态；AI 座位具有稳定的视觉角色和本地化的
思考台词，涵盖空闲、观察、思考、行动和反应状态。
发牌、筹码移向底池、弃牌、底池变化、回合和赢家
派彩均有动画，同时仍遵循 prefers-reduced-motion。
- 完整的加注额度 — 选择最小、半底池、四分之三底池、
底池或最大，拖动合法范围滑块，或输入精确的加注至
金额。每个值都会根据服务器提供的合法边界进行归一化；在
移动端，控件会变为适合触控的底部面板。
- 可选 AI 玩家 — 在游戏前或游戏期间添加一个或多个服务器端机器人
一个游戏。每个机器人仅携带其私有玩家视图调用用户配置的 API；每个
响应在应用前都会根据引擎的合法动作进行验证。
当最后一名人类玩家故意离开时，当前牌局会在不再发起 AI 请求的情况下结算，牌桌返回空闲状态。连接断开会暂停牌局以便恢复；在没有人类玩家连接时，不会运行任何 AI 请求或超时动作。
- 真实扑克规则 — 盲注 5/10、底牌、翻牌/转牌/河牌、摊牌、
弃牌/过牌/跟注/下注/加注/全下、最小加注递增、边池、
未被跟注的下注退还、奇数筹码平局决胜、大盲选项、单挑规则、
短全下“不重新开启下注”规则。
- 游戏代币 — 每位新玩家获得 10,000；买入默认
为 1,000。每次钱包变动都是一条不可变的账本条目
（transactionId, playerId, tableId, handId, amount, reason, createdAt），
仅限整数，幂等。牌局结果记录为审计条目。
- 实时性与一致性 — 服务器权威状态，扑克动作
commandId 去重，expectedVersion 防护，WebSocket 重连并
通过快照恢复，心跳，每位玩家的私有视图（没有人能看到
其他人未揭示的底牌），加密安全洗牌（绝不使用 Math.random）。
- 断线规则 — 当另一名人类玩家仍保持连接时，行动中的
玩家在 30 秒截止时间后面临下注时自动弃牌，否则
自动过牌。如果最后一名人类玩家断开连接，牌局冻结以便恢复；
座位在刷新后保持。
- 持久状态 — 牌桌、玩家身份、钱包和账本在
dsh web 重启后通过 DSH 存储域保留下来。

要求

- DeepSeek Harness dsh ≥ 0.1.0-rc.7，以常规方式运行：无需全局
安装，npx @deepseek-ai/dsh 即可解析它。
- PATH 上有 pnpm（dsh plugin 命令会转发给 pnpm）。

安装

该包是一个 profile bundle（package.json → dsh.bundle.patch，
与 @deepseek-ai/dsh-base 和 @deepseek-ai/dsh-web-app 使用的机制相同）：
用 dsh plugin 安装它会自动将其追加到 web profile 的
dsh.profile.bundles，并且其 cordis.patch.yml 会在每次启动时
自动插入 poker 加载器行。永远无需手动编辑
cordis.patch.yml。

1. pack the plugin (a tarball is the distributable artifact)
npm pack

2. install it into the web profile (from this directory, or point at the tarball)
npx @deepseek-ai/dsh plugin --profile web add -w file:/absolute/path/to/dsh-poker
or: npx @deepseek-ai/dsh plugin --profile web add -w file:./dsh-poker-0.1.0.tgz

3. restart the web UI (npx is the supported launcher)
npx @deepseek-ai/dsh web

就是这样：profile 的 dsh.profile.bundles 现在包含 dsh-poker，
并且 --dump-config 显示恰好一行 poker 加载器行（已由
npm run test:install 验证）。要从 profile 调整游戏配置，请在
~/.dsh/profiles/web/cordis.patch.yml 中按 id 覆盖该行（是补丁，而不是第二次
插入）：

- id: poker
config:
actionTimeoutMs: 15000

正在运行的 dsh web 会热应用 profile-patch 更改，但重启才是让
window.__DSH_BOOT__ 加载新客户端 bundle 的受支持方式。

本地游玩（多窗口多人对战）

1. 在两个浏览器窗口中打开 http://127.0.0.1:3080（或一个窗口 +
一个无痕窗口）。
2. 在两个窗口的侧边栏页脚中点击 ♠ Poker。
3. 窗口 1：输入昵称，创建牌桌。窗口 2：输入不同的
昵称，然后从列表中加入牌桌（或复制房间 ID 并
粘贴到“通过房间 ID 加入”中）。
4. 两名玩家入座并连接后，牌局立即开始。轮到你时
进行操作；倒计时会在超时时自动弃牌/过牌。
5. 游戏中途刷新页面：座位和牌桌状态会通过
resume 恢复。
6. 满员的牌桌可以观战：“观战”按钮会订阅
牌桌的公开快照，而不占用座位——绝不会显示底牌。
7. 在主机上运行的浏览器可以通过两步确认从大厅删除房间。
未完成的牌局会被取消，并在删除持久化房间记录之前
退还每个座位的当前筹码。

与 AI 玩家对战

本地游玩时，打开游戏标题栏中的 AI 设置——或点击 ＋ 加入机器人——
并输入 DeepSeek API 密钥。此选项仅对通过回环地址连接的
同源浏览器可用。密钥会直接发送到主机进程，
仅保存在内存中，绝不会写入游戏状态、账本、日志、
localStorage 或配置文件，并且页面无法读回。重启 dsh web 后
需要重新输入。

对于无人值守启动，请通过环境变量向主机提供密钥：

DEEPSEEK_API_KEY=sk-your-key npx @deepseek-ai/dsh web

创建并加入牌桌，然后点击 ＋ 加入机器人。第一个机器人会立即开始
单挑对战；更多机器人可以填补剩余座位，并从下一手牌
加入。当前适配器使用用户提供的 DeepSeek API
账户，并默认使用 deepseek-v4-flash。每个机器人回合会发起一次 API
请求。如果 API 超时、失败或返回非法操作，服务器
会选择安全的合法后备操作，因此牌桌绝不会卡住。

AI 数据披露

当 AI 座位行动时，主机会仅向配置的 API 提供商发送该座位
决策所需的状态：该 AI 座位的底牌、公共
牌、底池和下注状态、筹码量、玩家昵称、公开操作、合法
操作，以及最近 10 条公开日志记录。它绝不会发送其他玩家
未公开的底牌。运营者有责任告知玩家并
遵守所选提供商的服务条款及适用的隐私法律。

可选的 profile 覆盖项（密钥仍应保留为环境
变量）：

- id: poker
config:
deepseekModel: deepseek-v4-flash
deepseekBaseUrl: https://api.deepseek.com
botDecisionTimeoutMs: 12000
UI 具有响应式布局（1440 / 1024 / 390 px），并使用 DSH 主题令牌进行样式设计。

开发

npm install          # typescript + @types (node/ws/react) + react/react-dom
npm run typecheck    # tsc --noEmit over src/ + test/
npm run build        # tsc → lib/ + dist-test/, bundles the TSX/CSS client
npm test             # build + node --test
npm run test:ui      # browser layout/actions at desktop, tablet and mobile sizes
npm run test:install # install & distribution verification (see below)

布局：

src/
engine/   cards.ts (secure shuffle) · evaluator.ts (hand ranking)
engine.ts (state machine) · types.ts (domain types)
ledger.ts immutable Play Token ledger
protocol.ts wire schema (zod) + per-player view builders
host/     index.ts (cordis plugin) · table-service.ts · gateway.ts
bot-controller.ts · persistence.ts · types-augment.ts
client/   entry.ts + i18n/store/components/styles  ← TS/TSX browser source
cordis.patch.yml       ← the profile bundle patch (auto-inserts the poker row)
test/       evaluator · engine · ledger · service · full-game · frontend · bot
gateway · audit · simulation · package-exports · ui-layout
scripts/    build.mjs (artifact contract gate) · smoke-test.mjs (end-to-end)
install-test.sh

scripts/build.mjs 将 src/client/entry.ts 及其 TSX/CSS 依赖打包到分发的 lib/client.js __ModuleLoader__ 模块中。随后，构建过程会解析该最终包装器，并动态导入宿主和引擎产物，以在成功之前验证其公共导出契约。

无依赖的引擎也是一个公共包子路径，供机器人策略、模拟器和外部测试使用：

import { PokerEngine, seededRng, evaluateBest } from "dsh-poker/engine";

安装与分发验证

npm run test:install 打包 tarball，使用 npx @deepseek-ai/dsh 将其从 tarball 安装到一个全新的临时 DSH_HOME 中，断言 poker 加载器行在 --dump-config 中恰好出现一次，启动一个临时的 dsh web，并对其运行冒烟测试。

端到端冒烟测试

npx @deepseek-ai/dsh --profile web --port 3091 &   # or any profile with the plugin
node scripts/smoke-test.mjs ws://127.0.0.1:3091/poker/ws

通过 WebSocket 模拟两个浏览器窗口：创建/加入、打牌局，验证隐私、过期版本拒绝、重连/恢复、伪造令牌拒绝、旁观者隐私、筹码守恒和兑现。

配置

poker 行配置（全部可选）：

| key              | default | meaning                          |
| ---------------- | ------- | -------------------------------- |
| smallBlind     | 5     | small blind (chips)              |
| bigBlind       | 10    | big blind                        |
| buyIn          | 1000  | default buy-in per table         |
| maxSeats       | 6     | default table size (2–10)        |
| actionTimeoutMs| 30000 | 自动操作前的回合截止时间 |
| startingWallet | 10000 | 每个新玩家获得的 Play Tokens |
| deepseekApiKey | 未设置；回退到 DEEPSEEK_API_KEY | 服务端 AI API 密钥 |
| deepseekBaseUrl| https://api.deepseek.com | AI API 基础 URL |
| deepseekModel  | deepseek-v4-flash | AI 模型名称 |
| botDecisionTimeoutMs | 12000 | AI 决策请求超时 |

对于交互式本地游玩，优先使用游戏内仅内存的设置，或者对于无人值守启动使用
DEEPSEEK_API_KEY 环境变量。避免使用
deepseekApiKey，因为它会将密钥写入配置文件补丁。

重置 / 数据

所有游戏数据都存储在存储域单元 poker（JSON 后端）中：

rm ~/.dsh/storages/poker.json   # 清除牌桌、身份、钱包和账本

已知限制

参见 ARCHITECTURE.md → “已知限制”。

安全

WebSocket 网关会拒绝 Origin 与
DSH Web 主机不匹配的浏览器握手。这减少了对本地游戏服务的跨站访问，但
该插件仍然仅设计用于回环绑定的、受信任的本地 DSH
实例。在没有额外身份验证、TLS、速率限制和访问控制的情况下，不要通过
0.0.0.0、局域网或公共互联网将其暴露出去。

游戏内 AI 凭据配置还要求浏览器和
所请求的主机均为回环地址。远程客户端不会收到设置
控件，并且网关会拒绝伪造的配置消息。在本地操作员配置了提供方之后，任何已入座的
玩家都可以请求 AI 座位；
每个 AI 回合都可能消耗付费提供方的 token。

请根据 SECURITY.md 私下报告漏洞。

许可证

本插件采用 MIT。DSH 及其依赖项是受其自身许可证和条款约束的独立
项目。本插件不修改
或分叉 DSH，并且本仓库不授予任何上游商标或徽标的许可。

负责任使用

本软件是一款本地 play-token 游戏，出于娱乐和
软件开发目的提供。在未首先
获得特定司法管辖区的法律建议之前，不要添加存款、取款、可兑换
奖品、付费入场、抽水或其他真钱投注功能。运营者仍需对
API 提供方条款、隐私声明、年龄限制和当地法律负责。