德州扑克牌桌 Eapp1e/dsh-poker

dsh-plugin-poker

DeepSeek Harness 的德州扑克插件：无限注规则、机器人对手、真实感牌桌，教练模式讲解打法与赔率。

Texas Hold'em table for DeepSeek Harness: model-callable poker tools, six heuristic opponents, an optional coach, and a browser table whose buttons never post a chat message.

德州扑克牌桌与教练窗口

浏览器牌桌面板（左：绒面牌桌、行动按钮与下注尺度助手；右：教练窗口的实时推理）。

DeepSeek Harness 的无限注德州扑克插件，一个包提供两半：

- 宿主半：确定性德州引擎 + 6 个模型可调用工具（开桌 / 行动 / 看牌 / 下一手 / 机器人决策 / 胜率）。
- 浏览器半：Web GUI 把每次工具调用渲染成可视化牌桌卡片，另有侧栏常驻面板——所有按钮直连宿主路由，从不往对话里发消息。

你在对话里用自然语言出牌（"跟注""加注到 400""弃牌"），模型调用工具推进牌局；也可以直接点面板按钮，牌桌状态由引擎维护。

特性

- 完整规则实现：最小加注、不足额全下不重开行动轮、边池分层与合并、未获跟注退款、所有人全下自动发完摊牌；7 选 5 牌力评估；整局可从日志复现（状态内 PRNG）。
- 六种性格对手：岩石 / 紧凶 / 松凶 / 跟注站 / 疯子 / 老练，翻前按位置与价格定范围，翻后按牌面与赔率下注，并会根据桌上其他人的实际倾向动态调整自己。
- AI 对手：把若干座位交给任意 OpenAI 兼容接口（/v1/chat/completions）出牌；超时或返回不合法动作时自动退回内置策略，API Key 只存宿主、绝不回传页面。
- 可选教练层：局面、读牌、底池赔率、MDF、SPR、复盘与概念卡，数字是实时算出来的；一键整层关闭。
- 2–9 人桌，所有金额附 BB 换算；下注尺度助手给出 1/3–1 池的标准尺度与牌面判读。
- 零运行时依赖、零构建步骤，npm test 自带 6 个套件 1180+ 条断言。

安装

dsh plugin --profile web add dsh-plugin-poker # 从 npm
dsh plugin --profile web add link: # 或从本地目录

安装后重启 dsh web 并刷新一次页面（客户端 boot graph 烧在页面 HTML 里）。

开发期也可以手工把一行插入 profile 的 cordis.patch.yml（免重启热组合）：

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

两种方式只能选一种，同时使用会加载两次并在工具名上冲突。

快速开始

开一桌德州扑克，3 个机器人，起始筹码 5000，盲注 25/50

之后自然语言出牌即可："跟注"、"加注到 600"、"我现在胜率多少？"、"让机器人认真想想再打"。
侧栏页脚点 ♠ 牌桌 打开浮动面板：绒面牌桌、座位卡、底池筹码、行动按钮与牌局记录都在里面，可拖动、可固定。
牌没开时面板直接给人数选择器（2–9 人）与"开一桌"按钮。

工具

| 工具 | 作用 |
| poker_new_table | 开桌并发第一手牌。可选机器人数（1–8，默认 5 = 六人桌）、性格、筹码、盲注、随机种子。 |
| poker_action | 执行动作：fold / check / call / bet / raise / allin。amount 是"加注到"的本轮总额。 |
| poker_next_hand | 当前手结束后发下一手。 |
| poker_table | 读取当前牌桌状态与最近记录。reveal: true 仅供调试（显示全部底牌）。 |
| poker_opponent | 切换机器人脑袋（auto 内置策略 / model 模型逐手决策），或为等待中的机器人提交动作。 |
| poker_equity | 蒙特卡罗估算某席胜率（默认 1500 次）。 |

对手

内置策略：性格只调松紧、激进度与诈唬率，底层规则相同——翻前按"身后还有几人待行动"查开池范围；面对加注按"价格 + 位置"决定继续范围（压上筹码的加注只跟真货）；翻后比较牌力与底池赔率而不是固定门槛；下注尺度跟牌面走（干燥面小注、湿润面保护），也跟对手走（对跟注站停止诈唬）。每个座位都在数别人实际怎么做，并据此微调自己（幅度有界，性格始终认得出来）。实测 3000 手六人桌：白送大盲从 23% 降到 10%，跟全下的范围收成真正的强牌。

AI 对手：设置页（设置 → 德州扑克）填 Base URL / API Key / 模型后，前 N 个座位由该接口出牌。接口只许回一个 JSON 动作；超时（默认 8 秒）、离线或胡说八道都退回内置策略，牌局不中断。密钥存在宿主用户设置里，GET /poker/settings 只回是否已保存、不回传密钥。

教练

独立的可拖动窗口，七个板块：🧭 局面、🃏 你的牌、🎯 下注逻辑与建议、🔍 读牌、🧮 数学、📝 复盘、🎓 本手概念。
建议带具体牌型、位置与人数（"弃牌：A6o 在 UTG 太弱（后面还有 5 人）"），动作按钮上方重复同一句话并高亮对应按钮；读牌是量化的——范围宽度由位置、动作与尺度推出，胜率对抗收窄后的范围用蒙特卡罗算出，带 ±误差。
教练只看公开信息，不读对手底牌（有测试断言守着）。💡 一键整层关闭。

两种风格：简洁 / GTO

风格可以在两处切换：设置里的教练风格（改完立即生效，不用点保存），或者教练窗口标题栏上的简洁 | GTO 开关 —— 后者更顺手，因为"这一手要不要看 EV"是当下的判断，不是一次性配置。

切换会记住（写进设置），并且立刻改变屏幕上的分析：宿主会重存一次当前牌桌（设置就是在那一步盖到牌桌上的），于是面板拉到的下一份视图已经是新风格。万一没变，窗口会直接写明原因（"已保存；当前宿主还不认得教练风格，重启一次 dsh web 后生效"）—— "点了没反应"是最难自己排查的一类失败：宿主侧新增的代码要重启才会加载， And this can't be seen from the interface. After saving on the settings page, it will also tell you which state you're in (a normal "Saved", or a restart is required once).

GTO style switches the same situation into the language of range + break-even point + EV, adding two more sections (♟ GTO advice / ♟ GTO math / 🧩 range and role):

- The break-even point is calculated for you to see: when facing a bet, it gives the required equity (bet ÷ final pot), the MDF minimum defense frequency (pot ÷ (pot + bet)),
and the value:bluff ratio corresponding to the opponent's sizing — for example, half pot: calling needs 25%, defense line 67%, 1 bluff for every 3 value hands.
- The EV of every legal action (folding as the 0 baseline): call = equity × final pot − call; check = equity × pot;
bet = fold rate × pot + (1−fold rate) × (equity after being called × final pot − risk). The formulas are listed together with the numbers, so you can press through them yourself.
Two details are the source of "the formula looks right, but the conclusion is absurd", and both have been corrected according to real poker logic:
- The equity after being called must be discounted: the range that will call is stronger than the range you're currently up against, and the larger the proportion of chips invested relative to the stack, the tighter the calling range
(a 2.5BB open will be called by almost anything, while a 200BB all-in will only be called by the top). Earlier, the raw equity was used directly, so an all-in was always "very profitable".
- The final pot must be calculated according to what the opponent actually puts in: when there is already 100 in the pot and you raise to 250, the opponent only adds 150 (not another 250).
The earlier pot + 2×risk added an extra pot out of thin air on every raise.
- The fold rate comes from actual measurement: use each seat's "facing a bet/folding to a bet (counted separately postflop)" in the engine, then exponentiate by the number of opponents still in the hand
— two players each folding 60% means this bet takes down the pot immediately only 36% of the time, not 60% (this difference makes bluffing look "free"). The fold rate for raising is calculated separately: it is only discounted when facing a real raise (more than one big blind) — the blinds are not a "bet", and opening against the blinds should not be treated as a reraise.
- When the opponent is all-in, there is no raising line: no one can fold anymore (fold rate = 0), and no one can call your raise either — raising would just return the extra chips. So at this point the EV table has only the two lines call or fold, and it will explain why. (The engine was changed accordingly too: raise/all-in buttons that no one can call no longer appear, to avoid adding an option at the table that says "all-in 20,850" but is only 250 more than a call.)
- Approximate mixed frequencies: two lines with close EV are assigned frequencies according to how close they are (bet 92% / check 8%), and it explains why;
if the gap is large, it says directly "no mixing needed". Mixing is divided by line (bet/check/call/fold), not the four sizings of the same action.
The threshold for "close" is very small (6% of the pot, minimum 0.2BB): earlier, when the threshold was as wide as 3BB, a line behind by 40 chips could still get a 30%
frequency — that was no longer "mixing", but recommending you play a worse hand 30% of the time.
- Three fallback rules (to ensure the advice itself is correct, rather than "looking like GTO"):
1. Never recommend a line with clearly worse EV — when folding costs nothing, it will not have you call a −40 bet;
2. When EV is equivalent, choose by range — single-street EV cannot see the value of postflop position, so it once folded hands that the button should open; now this situation is left to the engine's own positional range system, and the EV table explains "why both lines are defensible";
3. Do not create fake mixing — if it was chosen by range, it says plainly "chosen by range: open", and will not then list "fold 60%" below in contradiction.
- Range role: classify this hand as value / semi-bluff / showdown value (bluff-catcher) / marginal / air, and explain how this type of hand is played in a GTO plan.
- Preflop is also calculated: preflop has no made hands, draws, or MDF, but it has all the other elements of this layer — this hand ranks in the top X% of starting hands, how much equity a call needs, and the EV of fold / call / open 2.5BB / 3BB / 4BB / 3-bet / all-in (preflop sizings are given in multiples of the big blind, because no one talks about preflop in "fractions of the pot"). And it will state plainly that "there is no such thing as MDF preflop", rather than forcing postflop concepts onto it.

Honest boundary: this is the arithmetic of one board, not a solver — there is no full tree, no street-by-street range iteration, and future streets are replaced by a rough estimate. What it gives is "what exactly are the odds and EV at this step, and why both lines are defensible", which is exactly the half of GTO that can be used at the table.

(Preflop used to be excluded, on the grounds that "with no community cards there is nothing to calculate for single-street EV" — that was a mistake: most decisions are preflop, so players switched styles and found the content completely unchanged. Now preflop also has its own break-even points and EV table.)

Settings

Settings → Texas Hold'em (a separate page registered under settings.section), five groups:
| Group | Content |
| General | Enable plugin (turning it off hides the sidebar entry and table cards; the tools remain usable as usual and will not interrupt an ongoing conversation), coach layer, coach style (concise / GTO), advice badge, hand history |
| New table defaults | Number of bots, opponent personality, starting stack, small/big blind — only take effect when the caller does not pass its own; when the model calls the tool, the parameters it passes still take precedence |
| Panel and replay | Replay speed (0.5× / standard / 2×, scaling the entire timeline together), auto-expand on page load |
| AI opponent | Enable, number of seats, Base URL, API Key, model, temperature, timeout, JSON mode, maximum reply length, test connection |
| About and updates | Installed version (read from this installation package's package.json, no need to fill it in manually), repository (can be changed to your own fork), update / recheck |

- Automatic update check: automatically checks once when the page loads (the host caches for 10 minutes, so a window will only bother GitHub once). When there is a new version,
a small yellow dot appears on the sidebar entry (hovering states the version), and the settings page shows the result directly when opened — you don't need to click any button first.
- Give the conclusion first, then the button: this line normally shows one sentence — Already the latest version (v0.1.0) / New version v0.2.0 available (current v0.1.0) / Unable to check the latest version for now. Only when there really is a new version does the "Update to v0.2.0" button appear, with an "Ignore this time" next to it to dismiss it (no more reminders in this session); when already up to date, the button position is a quiet "Recheck" link (bypassing the cache to check again) plus a "Release page" link.
- One-click update will really update:
- If the plugin is a git checkout (there is a .git in the directory) → run git -C pull --ff-only (this package has not yet been published to npm, so npm install would only 404);
- Otherwise → in the installation directory, choose pnpm add / yarn add / npm install according to the lock file, installing the exact version reported on the release page.
- 跑完把结果（含命令输出尾部）写在按钮旁边，并提示“刷新页面；若提示宿主还不认得，再重启一次 dsh web”。
- 页面上不能指定任何东西：包名、版本、目录都由宿主决定，版本号还要先过一遍严格校验 —— 页面只能说“要这个仓库的最新发布”。
- 失败也不装死：把真实报错、手动命令和发布页链接一起给你。
- 说明放在悬浮里：设置页每行的解释挂在行本身（鼠标悬浮显示），正文只留标签和控件 —— 一页设置不该把自己的说明书全印在屏幕上。页头也只有标题，“保存后立即生效”跟着保存键走。
- 测试连通（就在 AI 那一组里，挨着它测的那些字段）：点一下就用屏幕上当前的值（含还没保存的 Key）发一次最小请求，回你三种结果之一——✅ 连通：382ms · 模型 · 回复“pong”、❌ 失败：HTTP 401 · invalid api key、❌ 失败：超时（8000ms）。测试不落库、不改设置。
- 保存：页脚只有「保存」和旁边一句“保存后立即生效”（面板级的开关——回放节奏等——刷新页面后生效，这句挂在悬浮里）。
- 密钥只进不出：Key 写进宿主的用户设置文档；GET /poker/settings 只回 hasApiKey: true/false，页面把它渲染成密码框（已保存时显示占位点）。
- 页面自绘：GET /poker/settings 除了值，还回一份字段描述（分组、控件类型、上下限、选项、帮助文字、action/info 这类特殊控件），设置页照描述画控件 —— 以后加设置只改 lib/settings.js 一处，前端一行都不用动。页面标题用的是和侧栏入口同一枚手绘黑桃（设置列表本身没有 per-plugin 图标位，所以标记画在模块内部）。
- 保存即生效：插件开关、教练层立刻生效；AI 席位数会平移到当前这张牌桌（不用重开）；面板级的开关（记录、徽章、节奏）刷新页面后生效。

浏览器牌桌

- 两个表面：对话内的牌桌卡片（每次工具调用替换成当时局面）+ 侧栏页脚的常驻浮动面板（带实时摘要，跨会话保留位置与状态）。
- 直连宿主：按钮点击走 POST /poker/action 等同源路由，规则拒绝只在面板上显示红色告示，一个字不进对话；路由不可用时才退回对话。
- 过程回放：机器人行动按真实节奏一拍一拍放（含落牌动画与行动进度），弃牌后仍能看到整手打完。
- 细节：金额全部带 BB 药丸（筹码/BB 双向联动输入）；尺度助手按底池与翻前 BB 两种口径给标准尺度；庄家按钮、成牌名、台词、结算徽章齐全；浅色/深色主题都能读。

架构

lib/
cards.js # 牌、种子 PRNG、洗牌 evaluator.js # 牌力评估与牌型名 engine.js # 牌局状态机（下注轮、边池、摊牌） bots.js # 内置策略对手 + 蒙特卡罗胜率 render.js # 模型可读的牌桌文本 ai.js # AI 对手（OpenAI 兼容接口、失败回退） settings.js # 全部设置：schema + 分组描述（设置页据此自绘）+ 掩码 gto.js # GTO 风格：无差点、各动作 EV、近似混合频率、范围角色 update.js # 检查更新：GitHub 最新 release/tag 与本地版本比较 coach.js # 教练（可关） impl.js # 工具实现层（可热重载） index.js # 入口：6 个工具、/poker 路由、牌桌注册表 client.js # 浏览器半：牌桌卡片 + 侧栏面板 test/ # 6 个套件，见下

设计要点：引擎是唯一事实来源，工具只做翻译；牌桌状态按会话隔离（WeakMap）+ 一张全场共享的“当前牌桌”；impl.js 及其依赖改完即热重载（牌桌不丢，改坏了自动回退上一份可用代码），只有入口层和 patch 需要重启。

测试

npm test # 全部六套，一次跑完（零依赖，不需要 npm install）
node test/run.mjs # 引擎与不变量（含 2000-3000 手随机对局）
node test/host.mjs # Host 契约（工具定义、教练 payload、不泄露底牌）
node test/client.mjs # 客户端 bundle（无浏览器）
node test/coach.mjs # 教练（含 GTO 风格的无差点与 EV）
node test/hot.mjs # 热重载
node test/pack.mjs # 打包契约（dsh.bundle、一行描述、许可证等）

每次 push 都会在 GitHub Actions 上跑（Node 20 / 22 矩阵）。

License

MIT