dsh-plugin-poker：DeepSeek Harness 的德州扑克插件

前言¶

DeepSeek Harness（DSH）的核心是构建智能体。当智能体需要处理包含复杂状态机或需要确定性逻辑的环境（如德州扑克游戏）时，直接依赖大模型的输出往往不稳定。dsh-plugin-poker 为 DSH 提供了一个完整的德州扑克环境：它既是一个可以被模型调用的工具集，也是一个可视化的浏览器界面。

这个插件解决了模型“想玩牌但缺乏规则”的痛点，将复杂的扑克规则、对手逻辑和博弈计算封装成标准的 DSH 工具，让模型能够通过自然语言或函数调用参与到真实的牌局中。

核心功能¶

插件提供了“宿主半”和“浏览器半”两套实现。

完整规则实现¶

引擎实现了无限注德州扑克（NLH）的完整规则。包括最小加注、不足额全下处理、边池分层与合并、未获跟注退款以及所有人全下后的自动发牌结算。牌力评估采用 7 选 5 算法，且整局游戏的状态可以通过日志复现。

六种性格对手与 AI 对手¶

系统内置了六种基于启发式策略的对手（如岩石、紧凶、松凶、跟注站、疯子、老练），它们会根据位置、底池赔率和桌上实际倾向动态调整打法。
同时支持接入任意 OpenAI 兼容的接口（如 /v1/chat/completions）作为 AI 对手。API Key 仅存储在宿主端，页面获取设置时不会回传密钥，且具备超时自动回退机制。

教练模式¶

提供独立的可拖动教练窗口，实时计算局面分析。包括牌力评估、底池赔率、MDF、SPR、读牌范围宽度以及胜率估算。教练分为“简洁”和“GTO”两种风格，可即时切换，帮助模型或用户理解当前的决策逻辑。

浏览器牌桌与交互¶

提供了一个真实的绒面牌桌界面。关键特性是：所有的操作按钮直连宿主路由，绝不向对话流发送消息。这避免了工具调用和手动点击在聊天记录中产生冗余信息。界面支持 2-9 人桌，金额以 BB 为单位显示，并带有下注尺度助手。

零依赖与热重载¶

插件不依赖任何运行时库，安装后即可使用。代码修改支持热重载，修改 impl.js 等文件后无需重启宿主，牌局状态不会丢失。

安装与启用¶

通过命令行安装插件：

dsh plugin --profile web add dsh-plugin-poker

安装完成后，必须重启 dsh web 进程，并在浏览器中刷新一次页面。这是因为客户端的引导图被烧录在 HTML 中，重启才能正确加载插件。

如果需要本地开发或免重启测试，也可以手动编辑 cordis.patch.yml 文件：

- insert:
    - id: poker
      name: 'dsh-plugin-poker'

典型用法¶

开启牌局¶

在对话中调用 poker_new_table 工具。例如，开一桌 3 个机器人、起始筹码 5000、盲注 25/50 的牌局：

{
  "tools": ["poker_new_table"],
  "arguments": {
    "bot_count": 3,
    "starting_chips": 5000,
    "small_blind": 25,
    "big_blind": 50
  }
}

模型交互与决策¶

模型可以调用工具推进牌局，也可以直接在侧栏面板点击按钮。常见指令包括：
* “跟注”
* “加注到 600”
* “我现在胜率多少？”（调用 poker_equity）
* “让机器人认真想想再打”（切换对手模式）

查看状态¶

模型或用户可以调用 poker_table 工具读取当前牌桌状态与最近记录。

架构说明¶

插件采用“引擎唯一事实来源”的设计原则。
* 状态隔离：牌桌状态通过 WeakMap 进行会话隔离。
* 渲染层：工具层只负责翻译逻辑，具体的牌桌卡片和侧栏面板由浏览器端渲染。
* 安全：设置页面的 API Key 仅存于宿主配置，前端页面通过 GET /poker/settings 仅获取是否存在密钥，不回传具体内容。

注意事项¶

权限检查：安装前请检查源码与许可证（MIT）。
运行环境：插件运行在当前 DSH 进程的权限范围内。
版本一致性：根据资料核实，插件在 README 中显示为 0.2.0，线索中显示为 0.1.0，安装时以本地 package.json 为准。

总结¶

dsh-plugin-poker 为 DSH 提供了一个完整的、可落地的德州扑克模拟环境。它通过模型可调用的工具和浏览器可视化的结合，让智能体能够处理复杂的博弈逻辑，同时保持了零依赖和热重载的开发体验。