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 提供了一個完整的、可落地的德州撲克模擬環境。它通過模型可調用的工具和瀏覽器可視化的結合，讓智能體能夠處理複雜的博弈邏輯，同時保持了零依賴和熱重載的開發體驗。