dsh-blackjack 0.1.2 → 0.1.4

package/README.md

@@ -94,6 +94,21 @@ dsh --profile web
 出一个残缺的状态。这不是本插件独有的坑，其它社区 dsh 插件的安装文档也踩过同一
 处并确认了同样的结论。
 
+### 先进入一个会话，再用 `/blackjack`
+
+在 dsh 的**启动页**（新开 dsh 时那个 “Into the Unknown” 界面）执行 `/blackjack`，
+命令会真的执行，但**画面上什么都不会出现**——牌桌要等你进入一个会话后才显示。
+
+这不是本插件的问题：宿主对**所有插件注册的命令**都这样（用一个只返回一行文字、
+不碰任何服务的最小插件验证过，表现完全一致），而宿主自己的内置命令（如 `/goal`）
+则会正常渲染并切进会话视图。
+
+所以**第一次使用请先让对话真正开始**——随便发一句话，或者从侧边栏打开一个已有
+对话——再执行 `/blackjack agree`。注意点“新建会话”是没用的：那会把你送回启动页，
+正是坏掉的那个状态。
+
+只要对话已经开始，后面全程正常，牌桌、按钮、结算都没有任何问题。
+
 ### 版本要求：本插件锁定 dsh `0.1.0-rc.6`
 
 插件把 `@deepseek-ai/dsh-*` 的 peer 全部**精确锁**在 `0.1.0-rc.6`，不是写成

package/dist/api.d.ts

@@ -40,6 +40,11 @@ export interface MeView {
     exchangeThresholdChips: number;
     baseBetChips: number;
     githubLogin: string | null;
+    /**
+     * 加注上限。**可选**：插件发到 npm 后可能连到任何一版服务端，比这个字段更早的
+     * 服务端不会返回它。缺失时图形牌桌只隐藏自定义注额输入，预设按钮照常可用。
+     */
+    maxRaiseBetChips?: number;
 }
 /** Every failure this client surfaces: HTTP status plus the server's error code. */
 export declare class ApiError extends Error {

package/dist/client/Table.d.ts

@@ -24,7 +24,31 @@ export interface BlackjackTableProps {
     state: BlackjackApiState;
     onAction: (action: string) => void;
     onDeal: (betChips?: number) => void;
+    /** 玩家收起已结算的牌局，回到空闲态。 */
+    onDismiss: () => void;
     /** Brief inline notice for a failed action/deal call (container-owned; cleared on the next successful one). */
     error?: string;
 }
-export declare function BlackjackTable({ state, onAction, onDeal, error }: BlackjackTableProps): JSX.Element;
+/**
+ * 把纯文本里的裸链接变成可点的。命令回复是纯文本（终端 profile 也要能读），
+ * 但在图形界面里让人手动复制粘贴一条 60 字符的 URL 是不合理的——运营者的
+ * 原话是「应该直接打开一个浏览器」。插件进程里 spawn `open` 依赖运行环境
+ * 且很唐突，可点的链接是这个场景下最合适的实现。
+ */
+export declare function Linkified({ text }: {
+    text: string;
+}): JSX.Element;
+/**
+ * 动作要额外掏多少 CHIP。镜像服务端 `game.ts` 的 INCREMENT：双倍/分牌各再出
+ * 一份注额，保险出一半。抽成导出的纯函数，好让"余额不足时必须置灰"能被断言。
+ */
+export declare function actionCostChips(action: string, betChips: number): number;
+/**
+ * 注额校验。抽成导出的纯函数，好让边界（0、小数、超余额、超服务端上限）
+ * 能被直接断言，而不是只能靠驱动输入框间接覆盖。
+ */
+export declare function betError(chips: number, opts: {
+    balanceChips: number;
+    maxChips: number;
+}): string | null;
+export declare function BlackjackTable({ state, onAction, onDeal, onDismiss, error }: BlackjackTableProps): JSX.Element;

package/dist/client/Table.js

@@ -1,4 +1,6 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { stakeLine, outcomeLine } from '../copy.js';
 const SUITS = { S: '♠', H: '♥', D: '♦', C: '♣' };
 const RED_SUITS = new Set(['H', 'D']);
 const n = (v) => v.toLocaleString('en-US');
@@ -24,13 +26,35 @@ const CSS = `
   font: inherit; padding: 6px 14px; border-radius: 6px; border: 1px solid var(--bj-line);
   background: rgba(255,255,255,.08); color: inherit; cursor: pointer;
 }
-.bj-actions button:hover { background: rgba(255,255,255,.16); }
+.bj-actions button:hover:not(:disabled) { background: rgba(255,255,255,.16); }
+.bj-actions button:disabled { opacity: .4; cursor: not-allowed; }
+.bj-custom { display: flex; gap: 8px; align-items: center; margin-top: 8px; flex-wrap: wrap; }
+.bj-custom input {
+  font: inherit; width: 9em; padding: 5px 8px; border-radius: 6px;
+  border: 1px solid var(--bj-line); background: rgba(255,255,255,.06); color: inherit;
+}
+.bj-hint { opacity: .7; font-size: 12px; }
+.bj-group { margin-top: 12px; }
+.bj-group-title { font-weight: 600; margin-bottom: 2px; }
+.bj-note { opacity: .75; font-size: 12px; margin-bottom: 6px; }
 .bj-meta { opacity: .85; margin-bottom: 8px; }
 .bj-error {
   color: #c0392b; border: 1px solid rgba(192,57,43,.4); border-radius: 6px;
   padding: 4px 8px; margin-bottom: 8px;
 }
 `;
+/**
+ * 把纯文本里的裸链接变成可点的。命令回复是纯文本（终端 profile 也要能读），
+ * 但在图形界面里让人手动复制粘贴一条 60 字符的 URL 是不合理的——运营者的
+ * 原话是「应该直接打开一个浏览器」。插件进程里 spawn `open` 依赖运行环境
+ * 且很唐突，可点的链接是这个场景下最合适的实现。
+ */
+export function Linkified({ text }) {
+    const parts = text.split(/(https?:\/\/[^\s，。）)]+)/g);
+    return (_jsx(_Fragment, { children: parts.map((part, i) => /^https?:\/\//.test(part)
+            ? _jsx("a", { href: part, target: "_blank", rel: "noreferrer noopener", children: part }, i)
+            : part) }));
+}
 function CardFace({ card }) {
     if ('hidden' in card) {
         return _jsx("div", { className: "bj-card bj-card-back", "aria-label": "\u6697\u724C" });
@@ -49,26 +73,94 @@ function DealerRow({ dealer }) {
 function ConsentPrompt() {
     return (_jsx("div", { className: "bj-table", children: _jsxs("p", { children: ["\u8BF7\u5148\u5728\u547D\u4EE4\u884C\u8F93\u5165 ", _jsx("code", { children: "/blackjack agree" }), "\uFF0C\u9605\u8BFB\u5E76\u540C\u610F\u89C4\u5219\u540E\u624D\u80FD\u5F00\u59CB\u3002"] }) }));
 }
+/**
+ * 余额条。除了数字，还必须回答"赢来的 CHIP 有什么用"——只用图形界面的人此前
+ * 完全看不到兑换这回事（门槛只在文字命令的 renderMe 里出现过），于是不知道
+ * CHIP 能干什么，而那正是这个产品的全部意义。没到门槛时显示还差多少，本身
+ * 就是回访的理由。
+ */
 function MeHeader({ me }) {
-    return (_jsxs("div", { className: "bj-meta", children: ["\u4F59\u989D\uFF1A", n(me.chips), " CHIP\u3000\u4ECA\u65E5\u5269\u4F59\u514D\u8D39\u624B\uFF1A", me.freeHandsRemaining, me.points > 0 ? `　积分：${n(me.points)}` : '', me.poolEmpty ? '（本期奖池已发完，现在赢牌将发放积分）' : '', me.sponsorText ? _jsx("div", { children: me.sponsorText }) : null] }));
+    const short = me.exchangeThresholdChips - me.chips;
+    return (_jsxs("div", { className: "bj-meta", children: ["\u4F59\u989D\uFF1A", n(me.chips), " CHIP\u3000\u4ECA\u65E5\u5269\u4F59\u514D\u8D39\u624B\uFF1A", me.freeHandsRemaining, me.points > 0 ? `　积分：${n(me.points)}` : '', me.exchangedChips > 0 ? `　已兑换额度：${n(me.exchangedChips)} CHIP` : '', _jsx("div", { className: "bj-note", children: short <= 0
+                    ? `已达兑换门槛（${n(me.exchangeThresholdChips)} CHIP）· 用 /blackjack exchange 把 CHIP 换成模型额度`
+                    : `还差 ${n(short)} CHIP 到兑换门槛（${n(me.exchangeThresholdChips)}）· 过线后可用 /blackjack exchange 换成模型额度` }), me.exchangedChips > 0 ? (_jsxs("div", { className: "bj-note", children: ["\u5DF2\u5151\u6362\u7684 ", n(me.exchangedChips), " CHIP \u4F1A\u5728\u4F60\u81EA\u5DF1\u7684\u6A21\u578B\u989D\u5EA6\u8017\u5C3D\u65F6\u81EA\u52A8\u63A5\u7BA1\u90A3\u4E00\u6B21\u8BF7\u6C42\uFF0C\u5E73\u65F6\u4E0D\u4F1A\u52A8\u7528\u3002"] })) : null, me.poolEmpty ? _jsx("div", { children: "\uFF08\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u73B0\u5728\u8D62\u724C\u5C06\u53D1\u653E\u79EF\u5206\uFF09" }) : null, me.sponsorText ? _jsx("div", { children: me.sponsorText }) : null] }));
 }
 function RoundFooter({ round }) {
-    if (round.phase !== 'settled')
-        return null;
-    const payout = round.payoutChips ?? 0;
-    return (_jsxs("div", { className: "bj-meta", children: [payout > 0 ? `本手赢得 ${n(payout)} CHIP。` : '本手没有收获，明天再来。', round.pointsGranted ? _jsxs("div", { children: ["\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u6539\u4E3A\u53D1\u653E ", n(round.pointsGranted), " \u79EF\u5206\u3002"] }) : null] }));
+    return (_jsxs("div", { className: "bj-meta", children: [round.phase === 'settled' ? outcomeLine(round) : stakeLine(round), round.pointsGranted ? _jsxs("div", { children: ["\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u6539\u4E3A\u53D1\u653E ", n(round.pointsGranted), " \u79EF\u5206\u3002"] }) : null] }));
 }
-function ActionBar({ round, onAction }) {
+/**
+ * 动作要额外掏多少 CHIP。镜像服务端 `game.ts` 的 INCREMENT：双倍/分牌各再出
+ * 一份注额，保险出一半。抽成导出的纯函数，好让"余额不足时必须置灰"能被断言。
+ */
+export function actionCostChips(action, betChips) {
+    if (action === 'double' || action === 'split')
+        return betChips;
+    if (action === 'insure')
+        return Math.ceil(betChips / 2);
+    return 0;
+}
+function ActionBar({ round, me, onAction }) {
     if (round.actions.length === 0)
         return null;
-    return (_jsx("div", { className: "bj-actions", children: round.actions.map((action) => (_jsx("button", { type: "button", onClick: () => onAction(action), children: ACTION_LABELS[action] ?? action }, action))) }));
+    const chips = me?.chips ?? 0;
+    return (_jsx("div", { className: "bj-actions", children: round.actions.map((action) => {
+            // 服务端只按牌面给可选动作，不看余额；余额不够时点下去必然 402，
+            // 只换来一句笼统的失败提示。这里替玩家先拦住并说明原因。
+            const cost = actionCostChips(action, round.betChips);
+            const short = cost > chips;
+            return (_jsxs("button", { type: "button", disabled: short, title: short ? `还要再出 ${n(cost)} CHIP，余额不足` : undefined, onClick: () => onAction(action), children: [ACTION_LABELS[action] ?? action, cost > 0 ? `（${n(cost)}）` : ''] }, action));
+        }) }));
+}
+/**
+ * 注额校验。抽成导出的纯函数，好让边界（0、小数、超余额、超服务端上限）
+ * 能被直接断言，而不是只能靠驱动输入框间接覆盖。
+ */
+export function betError(chips, opts) {
+    if (!Number.isInteger(chips) || chips < 1)
+        return '注额要填正整数。';
+    if (chips > opts.maxChips)
+        return `单局最多 ${n(opts.maxChips)} CHIP。`;
+    if (chips > opts.balanceChips)
+        return '余额不足以下这个注。';
+    return null;
+}
+function DealButtons({ me, onDeal, freeLabel }) {
+    const freeLeft = me?.freeHandsRemaining ?? 0;
+    const presets = me ? [me.baseBetChips, me.baseBetChips * 2] : [];
+    return (_jsxs("div", { className: "bj-actions", children: [_jsxs("button", { type: "button", disabled: freeLeft <= 0, onClick: () => onDeal(), children: [freeLabel, me ? `·剩 ${freeLeft} 手` : ''] }), presets.map((amount) => (_jsxs("button", { type: "button", disabled: (me?.chips ?? 0) < amount, onClick: () => onDeal(amount), children: [n(amount), " CHIP"] }, amount)))] }));
+}
+/**
+ * 自定义注额。**只在服务端给出了 `maxRaiseBetChips` 时出现**——插件可能连到
+ * 比这个字段更早的服务端，那时没有可信上界，宁可退化成只有预设按钮，也不要
+ * 让玩家填一个必定被服务端 400 掉的数字。
+ */
+function CustomBet({ me, onDeal }) {
+    const max = me.maxRaiseBetChips;
+    const [open, setOpen] = useState(false);
+    const [text, setText] = useState('');
+    if (max === undefined)
+        return null;
+    const chips = Number(text);
+    const err = text.trim() === '' ? '请输入注额。' : betError(chips, { balanceChips: me.chips, maxChips: max });
+    return (_jsxs("div", { children: [_jsx("div", { className: "bj-actions", children: _jsx("button", { type: "button", onClick: () => setOpen(!open), children: "\u81EA\u5B9A\u4E49\u6CE8\u989D" }) }), open ? (_jsxs("div", { className: "bj-custom", children: [_jsx("input", { type: "number", min: 1, max: max, value: text, onChange: (e) => setText(e.target.value), "aria-label": "\u81EA\u5B9A\u4E49\u6CE8\u989D" }), _jsx("button", { type: "button", disabled: err !== null, onClick: () => onDeal(chips), children: "\u5F00\u59CB" }), _jsx("span", { className: "bj-hint", children: err ?? `1 ～ ${n(max)} CHIP` })] })) : null] }));
+}
+function IdleTable({ me, onDeal }) {
+    const freeLeft = me?.freeHandsRemaining ?? 0;
+    const base = me?.baseBetChips ?? 0;
+    const presets = me ? [base, base * 2] : [];
+    const affordable = me ? presets.some((a) => me.chips >= a) : false;
+    return (_jsxs("div", { children: [_jsx("div", { className: "bj-meta", children: "\u5F53\u524D\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684\u724C\u5C40\u3002" }), _jsxs("div", { className: "bj-group", children: [_jsxs("div", { className: "bj-group-title", children: ["\u514D\u8D39\u624B \u00B7 ", freeLeft > 0 ? `今日剩 ${freeLeft} 手` : '今日已用完，明天再来'] }), me ? (_jsxs("div", { className: "bj-note", children: ["\u4E0D\u7528\u51FA CHIP\u3002\u8D62\u4E86\u62FF ", n(base), " CHIP\uFF1B\u5934\u4E24\u5F20\u724C\u5C31\u51D1\u6210 21 \u70B9\uFF08A \u914D 10/J/Q/K\uFF09\u62FF", ' ', n(Math.floor(base * 1.5)), "\u3002\u8F93\u4E86\u6216\u5E73\u5C40\u90FD\u4E0D\u635F\u5931\u4EFB\u4F55\u4E1C\u897F\u3002"] })) : null, _jsx("div", { className: "bj-actions", children: _jsx("button", { type: "button", disabled: freeLeft <= 0, onClick: () => onDeal(), children: "\u5F00\u59CB\u514D\u8D39\u7684\u4E00\u5C40" }) })] }), me ? (_jsxs("div", { className: "bj-group", children: [_jsxs("div", { className: "bj-group-title", children: ["\u7528\u4F59\u989D\u52A0\u6CE8", affordable ? '' : ' · 余额不足'] }), _jsx("div", { className: "bj-note", children: "\u52A0\u6CE8\u7684 CHIP \u4ECE\u4F60\u7684\u4F59\u989D\u91CC\u51FA\uFF0C\u8D62\u4E86\u7FFB\u500D\uFF0C\u8F93\u4E86\u6536\u4E0D\u56DE\u3002" }), _jsx("div", { className: "bj-actions", children: presets.map((amount) => (_jsxs("button", { type: "button", disabled: me.chips < amount, onClick: () => onDeal(amount), children: [n(amount), " CHIP"] }, amount))) }), _jsx(CustomBet, { me: me, onDeal: onDeal })] })) : null] }));
 }
-function NoRound({ me, onDeal }) {
-    return (_jsxs("div", { children: [_jsx("div", { className: "bj-meta", children: "\u5F53\u524D\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684\u724C\u5C40\u3002" }), _jsxs("div", { className: "bj-actions", children: [_jsx("button", { type: "button", onClick: () => onDeal(), children: "\u5F00\u59CB\u4E00\u5C40\uFF08\u9650\u514D\uFF09" }), me ? (_jsxs("button", { type: "button", onClick: () => onDeal(me.baseBetChips), children: ["\u5F00\u59CB\u4E00\u5C40\uFF08", n(me.baseBetChips), " CHIP\uFF09"] })) : null] })] }));
+/**
+ * 结算后的出口。牌局结算不再让画面直接跳回空闲态——完整牌面与结果留在原地，
+ * 由玩家决定再来一局还是收起（0.1.2 之前这里什么都没有，爆牌瞬间就被冲掉了）。
+ */
+function SettledBar({ me, onDeal, onDismiss }) {
+    return (_jsxs("div", { children: [_jsx(DealButtons, { me: me, onDeal: onDeal, freeLabel: "\u518D\u6765\u4E00\u5C40\uFF08\u514D\u8D39" }), _jsx("div", { className: "bj-actions", children: _jsx("button", { type: "button", onClick: onDismiss, children: "\u6536\u8D77" }) })] }));
 }
-export function BlackjackTable({ state, onAction, onDeal, error }) {
+export function BlackjackTable({ state, onAction, onDeal, onDismiss, error }) {
     if (!state.consented)
         return _jsx(ConsentPrompt, {});
     const { me, round } = state;
-    return (_jsxs("div", { className: "bj-table", children: [_jsx("style", { children: CSS }), error ? _jsx("div", { className: "bj-error", children: error }) : null, me ? _jsx(MeHeader, { me: me }) : null, round ? (_jsxs("div", { children: [round.hands.map((hand, i) => (_jsx(HandRow, { hand: hand, label: round.hands.length > 1 ? `你的第 ${i + 1} 手` : '你的牌' }, i))), _jsx(DealerRow, { dealer: round.dealer }), _jsx(RoundFooter, { round: round }), _jsx(ActionBar, { round: round, onAction: onAction })] })) : (_jsx(NoRound, { me: me, onDeal: onDeal }))] }));
+    return (_jsxs("div", { className: "bj-table", children: [_jsx("style", { children: CSS }), error ? _jsx("div", { className: "bj-error", children: error }) : null, me ? _jsx(MeHeader, { me: me }) : null, round ? (_jsxs("div", { children: [round.hands.map((hand, i) => (_jsx(HandRow, { hand: hand, label: round.hands.length > 1 ? `你的第 ${i + 1} 手` : '你的牌' }, i))), _jsx(DealerRow, { dealer: round.dealer }), _jsx(RoundFooter, { round: round }), _jsx(ActionBar, { round: round, me: me, onAction: onAction }), round.phase === 'settled' ? _jsx(SettledBar, { me: me, onDeal: onDeal, onDismiss: onDismiss }) : null] })) : (_jsx(IdleTable, { me: me, onDeal: onDeal }))] }));
 }

package/dist/client/index.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useState } from 'react';
-import { BlackjackTable } from './Table.js';
+import { BlackjackTable, Linkified } from './Table.js';
+import { reduce, rowPlan } from './state.js';
 /**
  * Client module entry: registers the graphical table into the KEYED
  * `conversation.chat.commandview` slot under `key: 'blackjack'`, so every
@@ -23,41 +24,64 @@ async function getJson(path, init) {
 }
 /** Brief, vocabulary-safe notice shown when an action/deal call fails; never echoes the raw server error text. */
 const ACTION_FAILED_NOTICE = '上一次操作没有成功，已为你刷新到最新状态。';
-/** Container: owns data fetching. Refetches state after every action — no polling timer. */
-function BlackjackTableContainer() {
+/**
+ * Container: owns data fetching. 牌局以发牌/动作的**返回值**为准，只有玩家点
+ * "收起"才清空；余额刷新单独走，绝不碰牌局。0.1.2 之前这里把动作返回值整个
+ * 丢掉、再拉一次 /api/state，而那个端点只报进行中的牌局——于是玩家一爆牌，
+ * 画面就跳回"当前没有进行中的牌局"，从头到尾看不见自己怎么输的。
+ */
+function BlackjackTableContainer({ node }) {
+    // 这一行渲染什么由子命令决定。keyed 槽按命令名分发，注册 `blackjack` 会顶掉
+    // 宿主负责渲染文字的 GenericCommandCard —— 不自己把文字渲染回来，
+    // /blackjack exchange 的配对码和 /blackjack agree 的须知就会凭空消失。
+    const plan = rowPlan(node);
     const [state, setState] = useState(null);
     const [actionError, setActionError] = useState(null);
-    const refresh = useCallback(() => {
+    /** 整份同步：挂载时，以及动作失败后状态存疑时。 */
+    const sync = useCallback(() => {
         getJson('/blackjack/api/state')
-            .then(setState)
+            .then((payload) => setState((s) => reduce(s ?? { consented: false }, { type: 'synced', payload })))
             .catch(() => setState({ consented: false }));
     }, []);
+    /** 只取 me：动作之后余额与免费手会变，但牌局必须留着。 */
+    const refreshMe = useCallback(() => {
+        getJson('/blackjack/api/state')
+            .then((payload) => setState((s) => (s ? reduce(s, { type: 'meRefreshed', me: payload.me }) : s)))
+            .catch(() => { });
+    }, []);
     useEffect(() => {
-        refresh();
-    }, [refresh]);
-    const runAction = useCallback((path, body) => {
+        if (plan.table)
+            sync();
+    }, [sync, plan.table]);
+    const post = useCallback((path, body) => {
         getJson(path, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify(body),
         })
-            .then(() => {
+            .then((round) => {
             setActionError(null);
-            refresh();
+            setState((s) => (s ? reduce(s, { type: 'round', round }) : s));
+            refreshMe();
         })
             .catch(() => {
-            // A failed action (including the 404 "no active round" case) still
-            // resyncs state so the UI never shows a stale action bar, but the
-            // notice stays up until the next successful action clears it.
+            // 失败（含 404 "no active round"）后牌局状态存疑，整份重同步，
+            // 免得动作栏停在一个已经不存在的牌局上。
             setActionError(ACTION_FAILED_NOTICE);
-            refresh();
+            sync();
         });
-    }, [refresh]);
-    const onDeal = useCallback((betChips) => runAction('/blackjack/api/deal', betChips === undefined ? {} : { betChips }), [runAction]);
-    const onAction = useCallback((action) => runAction('/blackjack/api/action', { action }), [runAction]);
+    }, [refreshMe, sync]);
+    const onDeal = useCallback((betChips) => post('/blackjack/api/deal', betChips === undefined ? {} : { betChips }), [post]);
+    const onAction = useCallback((action) => post('/blackjack/api/action', { action }), [post]);
+    const onDismiss = useCallback(() => setState((s) => (s ? reduce(s, { type: 'dismissed' }) : s)), []);
+    // 样式内联：文字型的行不渲染牌桌，Table 里那段 <style> 也就不会挂载，
+    // 靠 class 的话须知全文会被压成一行。
+    const notice = plan.text === undefined ? null : (_jsx("div", { style: { whiteSpace: 'pre-wrap', marginBottom: '8px', ...(plan.isError ? { color: '#c0392b' } : {}) }, children: _jsx(Linkified, { text: plan.text }) }));
+    if (!plan.table)
+        return notice;
     if (state === null)
-        return null;
-    return _jsx(BlackjackTable, { state: state, onAction: onAction, onDeal: onDeal, error: actionError ?? undefined });
+        return notice;
+    return (_jsxs("div", { children: [notice, _jsx(BlackjackTable, { state: state, onAction: onAction, onDeal: onDeal, onDismiss: onDismiss, error: actionError ?? undefined })] }));
 }
 export function apply(ctx) {
     ctx.slots.inject('conversation.chat.commandview', () => ctx.slots.register({

package/dist/client/state.d.ts

@@ -0,0 +1,67 @@
+import type { MeView, RoundView } from '../api.js';
+/**
+ * 图形牌桌的状态迁移。抽成纯函数是为了让"结算后的牌局必须留在屏幕上"这条
+ * 能被直接断言——它原先埋在 React 容器里，没有 DOM 环境就测不到，于是
+ * 0.1.2 带着这个缺陷发了出去。
+ *
+ * 关键不变式：**只有 `dismissed` 能清掉 `round`。** 余额刷新绝不碰它。
+ * @module dsh-blackjack/client/state
+ */
+export interface TableState {
+    consented: boolean;
+    me?: MeView;
+    round?: RoundView;
+}
+export type TableEvent = 
+/** 挂载时的一次性同步：整份状态以服务端为准（含"当前没有进行中的牌局"）。 */
+{
+    type: 'synced';
+    payload: {
+        consented: boolean;
+        me?: MeView;
+        round?: RoundView;
+    };
+}
+/** 发牌/动作的返回值。牌局以它为准——包括结算态，那正是要留在屏幕上的东西。 */
+ | {
+    type: 'round';
+    round: RoundView;
+}
+/** 动作之后余额与免费手会变，只更新 me。 */
+ | {
+    type: 'meRefreshed';
+    me?: MeView;
+}
+/** 玩家点了"收起"，回到空闲态。 */
+ | {
+    type: 'dismissed';
+};
+export declare function reduce(state: TableState, event: TableEvent): TableState;
+/** 宿主传给命令行组件的那份命令生命周期节点（只用到我们关心的字段）。 */
+export interface CommandNodeLike {
+    args: string | null;
+    outcome: {
+        kind: 'success' | 'error';
+        text?: string;
+    } | null;
+}
+/** 这一行该渲染什么。 */
+export interface RowPlan {
+    /** 要显示的命令回复文字；缺省表示这一行不靠文字表达。 */
+    text?: string;
+    /** 该文字是否是失败提示。 */
+    isError: boolean;
+    /** 是否渲染图形牌桌。 */
+    table: boolean;
+}
+/**
+ * 决定 `/blackjack …` 的某一行怎么渲染。
+ *
+ * 存在的理由：`conversation.chat.commandview` 是**按命令名分发**的 keyed 槽，
+ * 注册 `blackjack` 会顶掉宿主负责渲染文字的 GenericCommandCard。0.1.3 的容器
+ * 完全无视这个节点、永远渲染牌桌，于是 `/blackjack exchange` 的配对码和
+ * `/blackjack agree` 的须知全文被凭空吞掉——运营者因此以为"命令没反应"。
+ *
+ * 不变式：**永远不吞文字**。未知子命令默认走文字，所以以后新增子命令不会再犯。
+ */
+export declare function rowPlan(node: CommandNodeLike): RowPlan;

package/dist/client/state.js

@@ -0,0 +1,34 @@
+export function reduce(state, event) {
+    switch (event.type) {
+        case 'synced':
+            return { consented: event.payload.consented, me: event.payload.me, round: event.payload.round };
+        case 'round':
+            return { ...state, round: event.round };
+        case 'meRefreshed':
+            return { ...state, me: event.me };
+        case 'dismissed':
+            return { ...state, round: undefined };
+    }
+}
+/** 牌桌是这些子命令的正确视图；其余一律以文字为准。 */
+const TABLE_SUBCOMMANDS = new Set(['', 'deal']);
+/**
+ * 决定 `/blackjack …` 的某一行怎么渲染。
+ *
+ * 存在的理由：`conversation.chat.commandview` 是**按命令名分发**的 keyed 槽，
+ * 注册 `blackjack` 会顶掉宿主负责渲染文字的 GenericCommandCard。0.1.3 的容器
+ * 完全无视这个节点、永远渲染牌桌，于是 `/blackjack exchange` 的配对码和
+ * `/blackjack agree` 的须知全文被凭空吞掉——运营者因此以为"命令没反应"。
+ *
+ * 不变式：**永远不吞文字**。未知子命令默认走文字，所以以后新增子命令不会再犯。
+ */
+export function rowPlan(node) {
+    const sub = (node.args ?? '').trim().split(/\s+/)[0] ?? '';
+    const isTable = TABLE_SUBCOMMANDS.has(sub);
+    const outcome = node.outcome;
+    const isError = outcome?.kind === 'error';
+    // 牌桌型子命令平时不重复显示文字（牌桌已经把状态画出来了），但失败提示必须露出来。
+    if (isTable)
+        return { table: true, isError, ...(isError && outcome?.text ? { text: outcome.text } : {}) };
+    return { table: false, isError, ...(outcome?.text !== undefined ? { text: outcome.text } : {}) };
+}

package/dist/client.js

@@ -3,7 +3,7 @@ window.__ModuleLoader__.load({
 	factory: (require) => {
 		var module = { exports: {} };
 		var exports = module.exports;
-"use strict";var b=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var j=Object.getOwnPropertyNames;var x=Object.prototype.hasOwnProperty;var h=(e,n)=>{for(var a in n)b(e,a,{get:n[a],enumerable:!0})},S=(e,n,a,i)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of j(n))!x.call(e,o)&&o!==a&&b(e,o,{get:()=>n[o],enumerable:!(i=v(n,o))||i.enumerable});return e};var w=e=>S(b({},"__esModule",{value:!0}),e);var $={};h($,{apply:()=>P,inject:()=>I});module.exports=w($);var s=require("react");var t=require("react/jsx-runtime"),y={S:"\u2660",H:"\u2665",D:"\u2666",C:"\u2663"},C=new Set(["H","D"]),d=e=>e.toLocaleString("en-US"),N={hit:"\u8981\u724C",stand:"\u505C\u724C",double:"\u53CC\u500D",split:"\u5206\u724C",insure:"\u4E70\u4FDD\u9669",decline:"\u4E0D\u4E70\u4FDD\u9669"},E=`
+"use strict";var C=Object.defineProperty;var P=Object.getOwnPropertyDescriptor;var V=Object.getOwnPropertyNames;var $=Object.prototype.hasOwnProperty;var L=(e,n)=>{for(var i in n)C(e,i,{get:n[i],enumerable:!0})},B=(e,n,i,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let a of V(n))!$.call(e,a)&&a!==i&&C(e,a,{get:()=>n[a],enumerable:!(o=P(n,a))||o.enumerable});return e};var D=e=>B(C({},"__esModule",{value:!0}),e);var ae={};L(ae,{apply:()=>oe,inject:()=>te});module.exports=D(ae);var l=require("react");var j=require("react");var m=e=>e.toLocaleString("en-US");function y(e){return e.mode==="free"?`\u8FD9\u662F\u514D\u8D39\u7684\u4E00\u5C40\uFF1A\u8D62\u4E86\u62FF ${m(e.betChips)} CHIP\uFF0C\u8F93\u4E86\u4E0D\u635F\u5931\u4EFB\u4F55\u4E1C\u897F\u3002`:`\u672C\u5C40\u5DF2\u52A0\u6CE8 ${m(e.betChips)} CHIP\uFF0C\u4ECE\u4F60\u7684\u4F59\u989D\u91CC\u51FA\u3002`}function w(e){let n=e.payoutChips??0,i=e.betChips;return e.hands.length>0&&e.hands.every(o=>o.outcome==="push")?e.mode==="free"?"\u5E73\u5C40\u3002\u8FD9\u624B\u4E0D\u635F\u5931\u4E5F\u4E0D\u83B7\u5F97\u3002":`\u5E73\u5C40\u3002\u52A0\u6CE8\u7684 ${m(i)} CHIP \u539F\u6837\u9000\u56DE\u3002`:n>0?e.mode==="free"?`\u8D62\u4E86\uFF0C\u62FF\u5230 ${m(n)} CHIP\u3002`:`\u8D62\u4E86\uFF0C\u62FF\u56DE ${m(n)} CHIP\uFF08\u52A0\u6CE8 ${m(i)}\uFF09\u3002`:e.mode==="free"?"\u8FD9\u624B\u8F93\u4E86\u3002\u514D\u8D39\u624B\u4E0D\u635F\u5931\u4EFB\u4F55\u4E1C\u897F\u3002":`\u8FD9\u624B\u8F93\u4E86\uFF0C\u52A0\u6CE8\u7684 ${m(i)} CHIP \u6536\u4E0D\u56DE\u3002`}var t=require("react/jsx-runtime"),M={S:"\u2660",H:"\u2665",D:"\u2666",C:"\u2663"},J=new Set(["H","D"]),d=e=>e.toLocaleString("en-US"),A={hit:"\u8981\u724C",stand:"\u505C\u724C",double:"\u53CC\u500D",split:"\u5206\u724C",insure:"\u4E70\u4FDD\u9669",decline:"\u4E0D\u4E70\u4FDD\u9669"},X=`
 .bj-table { --bj-felt: #0f3d2e; --bj-line: rgba(255,255,255,.18); font-size: 14px; }
 .bj-hand { display: flex; gap: 6px; flex-wrap: wrap; align-items: center; margin: 4px 0; }
 .bj-card {
@@ -22,13 +22,23 @@ window.__ModuleLoader__.load({
   font: inherit; padding: 6px 14px; border-radius: 6px; border: 1px solid var(--bj-line);
   background: rgba(255,255,255,.08); color: inherit; cursor: pointer;
 }
-.bj-actions button:hover { background: rgba(255,255,255,.16); }
+.bj-actions button:hover:not(:disabled) { background: rgba(255,255,255,.16); }
+.bj-actions button:disabled { opacity: .4; cursor: not-allowed; }
+.bj-custom { display: flex; gap: 8px; align-items: center; margin-top: 8px; flex-wrap: wrap; }
+.bj-custom input {
+  font: inherit; width: 9em; padding: 5px 8px; border-radius: 6px;
+  border: 1px solid var(--bj-line); background: rgba(255,255,255,.06); color: inherit;
+}
+.bj-hint { opacity: .7; font-size: 12px; }
+.bj-group { margin-top: 12px; }
+.bj-group-title { font-weight: 600; margin-bottom: 2px; }
+.bj-note { opacity: .75; font-size: 12px; margin-bottom: 6px; }
 .bj-meta { opacity: .85; margin-bottom: 8px; }
 .bj-error {
   color: #c0392b; border: 1px solid rgba(192,57,43,.4); border-radius: 6px;
   padding: 4px 8px; margin-bottom: 8px;
 }
-`;function u({card:e}){if("hidden"in e)return(0,t.jsx)("div",{className:"bj-card bj-card-back","aria-label":"\u6697\u724C"});let n=y[e.suit]??e.suit,a=C.has(e.suit)?"bj-card-red":"bj-card-black";return(0,t.jsx)("div",{className:`bj-card ${a}`,children:`${e.rank}${n}`})}function A({hand:e,label:n}){let a=e.soft?"\u8F6F":"";return(0,t.jsxs)("div",{children:[(0,t.jsxs)("div",{className:"bj-meta",children:[n,"\uFF08",a,e.total,"\uFF09",e.doubled?" [\u53CC\u500D]":""]}),(0,t.jsx)("div",{className:"bj-hand",children:e.cards.map((i,o)=>(0,t.jsx)(u,{card:i},o))})]})}function T({dealer:e}){return(0,t.jsxs)("div",{children:[(0,t.jsxs)("div",{className:"bj-meta",children:["\u5E84\u5BB6",e.total!==void 0?`\uFF08${e.total}\uFF09`:""]}),(0,t.jsx)("div",{className:"bj-hand",children:e.cards.map((n,a)=>(0,t.jsx)(u,{card:n},a))})]})}function B(){return(0,t.jsx)("div",{className:"bj-table",children:(0,t.jsxs)("p",{children:["\u8BF7\u5148\u5728\u547D\u4EE4\u884C\u8F93\u5165 ",(0,t.jsx)("code",{children:"/blackjack agree"}),"\uFF0C\u9605\u8BFB\u5E76\u540C\u610F\u89C4\u5219\u540E\u624D\u80FD\u5F00\u59CB\u3002"]})})}function R({me:e}){return(0,t.jsxs)("div",{className:"bj-meta",children:["\u4F59\u989D\uFF1A",d(e.chips)," CHIP\u3000\u4ECA\u65E5\u5269\u4F59\u514D\u8D39\u624B\uFF1A",e.freeHandsRemaining,e.points>0?`\u3000\u79EF\u5206\uFF1A${d(e.points)}`:"",e.poolEmpty?"\uFF08\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u73B0\u5728\u8D62\u724C\u5C06\u53D1\u653E\u79EF\u5206\uFF09":"",e.sponsorText?(0,t.jsx)("div",{children:e.sponsorText}):null]})}function J({round:e}){if(e.phase!=="settled")return null;let n=e.payoutChips??0;return(0,t.jsxs)("div",{className:"bj-meta",children:[n>0?`\u672C\u624B\u8D62\u5F97 ${d(n)} CHIP\u3002`:"\u672C\u624B\u6CA1\u6709\u6536\u83B7\uFF0C\u660E\u5929\u518D\u6765\u3002",e.pointsGranted?(0,t.jsxs)("div",{children:["\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u6539\u4E3A\u53D1\u653E ",d(e.pointsGranted)," \u79EF\u5206\u3002"]}):null]})}function H({round:e,onAction:n}){return e.actions.length===0?null:(0,t.jsx)("div",{className:"bj-actions",children:e.actions.map(a=>(0,t.jsx)("button",{type:"button",onClick:()=>n(a),children:N[a]??a},a))})}function V({me:e,onDeal:n}){return(0,t.jsxs)("div",{children:[(0,t.jsx)("div",{className:"bj-meta",children:"\u5F53\u524D\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684\u724C\u5C40\u3002"}),(0,t.jsxs)("div",{className:"bj-actions",children:[(0,t.jsx)("button",{type:"button",onClick:()=>n(),children:"\u5F00\u59CB\u4E00\u5C40\uFF08\u9650\u514D\uFF09"}),e?(0,t.jsxs)("button",{type:"button",onClick:()=>n(e.baseBetChips),children:["\u5F00\u59CB\u4E00\u5C40\uFF08",d(e.baseBetChips)," CHIP\uFF09"]}):null]})]})}function m({state:e,onAction:n,onDeal:a,error:i}){if(!e.consented)return(0,t.jsx)(B,{});let{me:o,round:r}=e;return(0,t.jsxs)("div",{className:"bj-table",children:[(0,t.jsx)("style",{children:E}),i?(0,t.jsx)("div",{className:"bj-error",children:i}):null,o?(0,t.jsx)(R,{me:o}):null,r?(0,t.jsxs)("div",{children:[r.hands.map((p,l)=>(0,t.jsx)(A,{hand:p,label:r.hands.length>1?`\u4F60\u7684\u7B2C ${l+1} \u624B`:"\u4F60\u7684\u724C"},l)),(0,t.jsx)(T,{dealer:r.dealer}),(0,t.jsx)(J,{round:r}),(0,t.jsx)(H,{round:r,onAction:n})]}):(0,t.jsx)(V,{me:o,onDeal:a})]})}var f=require("react/jsx-runtime"),I=["slots"];async function k(e,n){let a=await fetch(e,n),i=await a.text(),o=i.length>0?JSON.parse(i):{};if(!a.ok){let r=typeof o?.error=="string"?o.error:`${a.status}`;throw new Error(r)}return o}var X="\u4E0A\u4E00\u6B21\u64CD\u4F5C\u6CA1\u6709\u6210\u529F\uFF0C\u5DF2\u4E3A\u4F60\u5237\u65B0\u5230\u6700\u65B0\u72B6\u6001\u3002";function D(){let[e,n]=(0,s.useState)(null),[a,i]=(0,s.useState)(null),o=(0,s.useCallback)(()=>{k("/blackjack/api/state").then(n).catch(()=>n({consented:!1}))},[]);(0,s.useEffect)(()=>{o()},[o]);let r=(0,s.useCallback)((c,g)=>{k(c,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(g)}).then(()=>{i(null),o()}).catch(()=>{i(X),o()})},[o]),p=(0,s.useCallback)(c=>r("/blackjack/api/deal",c===void 0?{}:{betChips:c}),[r]),l=(0,s.useCallback)(c=>r("/blackjack/api/action",{action:c}),[r]);return e===null?null:(0,f.jsx)(m,{state:e,onAction:l,onDeal:p,error:a??void 0})}function P(e){e.slots.inject("conversation.chat.commandview",()=>e.slots.register({name:"conversation.chat.commandview",key:"blackjack",inject:()=>({})},D))}
+`;function S({text:e}){let n=e.split(/(https?:\/\/[^\s，。）)]+)/g);return(0,t.jsx)(t.Fragment,{children:n.map((i,o)=>/^https?:\/\//.test(i)?(0,t.jsx)("a",{href:i,target:"_blank",rel:"noreferrer noopener",children:i},o):i)})}function N({card:e}){if("hidden"in e)return(0,t.jsx)("div",{className:"bj-card bj-card-back","aria-label":"\u6697\u724C"});let n=M[e.suit]??e.suit,i=J.has(e.suit)?"bj-card-red":"bj-card-black";return(0,t.jsx)("div",{className:`bj-card ${i}`,children:`${e.rank}${n}`})}function O({hand:e,label:n}){let i=e.soft?"\u8F6F":"";return(0,t.jsxs)("div",{children:[(0,t.jsxs)("div",{className:"bj-meta",children:[n,"\uFF08",i,e.total,"\uFF09",e.doubled?" [\u53CC\u500D]":""]}),(0,t.jsx)("div",{className:"bj-hand",children:e.cards.map((o,a)=>(0,t.jsx)(N,{card:o},a))})]})}function _({dealer:e}){return(0,t.jsxs)("div",{children:[(0,t.jsxs)("div",{className:"bj-meta",children:["\u5E84\u5BB6",e.total!==void 0?`\uFF08${e.total}\uFF09`:""]}),(0,t.jsx)("div",{className:"bj-hand",children:e.cards.map((n,i)=>(0,t.jsx)(N,{card:n},i))})]})}function U(){return(0,t.jsx)("div",{className:"bj-table",children:(0,t.jsxs)("p",{children:["\u8BF7\u5148\u5728\u547D\u4EE4\u884C\u8F93\u5165 ",(0,t.jsx)("code",{children:"/blackjack agree"}),"\uFF0C\u9605\u8BFB\u5E76\u540C\u610F\u89C4\u5219\u540E\u624D\u80FD\u5F00\u59CB\u3002"]})})}function z({me:e}){let n=e.exchangeThresholdChips-e.chips;return(0,t.jsxs)("div",{className:"bj-meta",children:["\u4F59\u989D\uFF1A",d(e.chips)," CHIP\u3000\u4ECA\u65E5\u5269\u4F59\u514D\u8D39\u624B\uFF1A",e.freeHandsRemaining,e.points>0?`\u3000\u79EF\u5206\uFF1A${d(e.points)}`:"",e.exchangedChips>0?`\u3000\u5DF2\u5151\u6362\u989D\u5EA6\uFF1A${d(e.exchangedChips)} CHIP`:"",(0,t.jsx)("div",{className:"bj-note",children:n<=0?`\u5DF2\u8FBE\u5151\u6362\u95E8\u69DB\uFF08${d(e.exchangeThresholdChips)} CHIP\uFF09\xB7 \u7528 /blackjack exchange \u628A CHIP \u6362\u6210\u6A21\u578B\u989D\u5EA6`:`\u8FD8\u5DEE ${d(n)} CHIP \u5230\u5151\u6362\u95E8\u69DB\uFF08${d(e.exchangeThresholdChips)}\uFF09\xB7 \u8FC7\u7EBF\u540E\u53EF\u7528 /blackjack exchange \u6362\u6210\u6A21\u578B\u989D\u5EA6`}),e.exchangedChips>0?(0,t.jsxs)("div",{className:"bj-note",children:["\u5DF2\u5151\u6362\u7684 ",d(e.exchangedChips)," CHIP \u4F1A\u5728\u4F60\u81EA\u5DF1\u7684\u6A21\u578B\u989D\u5EA6\u8017\u5C3D\u65F6\u81EA\u52A8\u63A5\u7BA1\u90A3\u4E00\u6B21\u8BF7\u6C42\uFF0C\u5E73\u65F6\u4E0D\u4F1A\u52A8\u7528\u3002"]}):null,e.poolEmpty?(0,t.jsx)("div",{children:"\uFF08\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u73B0\u5728\u8D62\u724C\u5C06\u53D1\u653E\u79EF\u5206\uFF09"}):null,e.sponsorText?(0,t.jsx)("div",{children:e.sponsorText}):null]})}function F({round:e}){return(0,t.jsxs)("div",{className:"bj-meta",children:[e.phase==="settled"?w(e):y(e),e.pointsGranted?(0,t.jsxs)("div",{children:["\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u6539\u4E3A\u53D1\u653E ",d(e.pointsGranted)," \u79EF\u5206\u3002"]}):null]})}function G(e,n){return e==="double"||e==="split"?n:e==="insure"?Math.ceil(n/2):0}function q({round:e,me:n,onAction:i}){if(e.actions.length===0)return null;let o=n?.chips??0;return(0,t.jsx)("div",{className:"bj-actions",children:e.actions.map(a=>{let r=G(a,e.betChips),s=r>o;return(0,t.jsxs)("button",{type:"button",disabled:s,title:s?`\u8FD8\u8981\u518D\u51FA ${d(r)} CHIP\uFF0C\u4F59\u989D\u4E0D\u8DB3`:void 0,onClick:()=>i(a),children:[A[a]??a,r>0?`\uFF08${d(r)}\uFF09`:""]},a)})})}function K(e,n){return!Number.isInteger(e)||e<1?"\u6CE8\u989D\u8981\u586B\u6B63\u6574\u6570\u3002":e>n.maxChips?`\u5355\u5C40\u6700\u591A ${d(n.maxChips)} CHIP\u3002`:e>n.balanceChips?"\u4F59\u989D\u4E0D\u8DB3\u4EE5\u4E0B\u8FD9\u4E2A\u6CE8\u3002":null}function Q({me:e,onDeal:n,freeLabel:i}){let o=e?.freeHandsRemaining??0,a=e?[e.baseBetChips,e.baseBetChips*2]:[];return(0,t.jsxs)("div",{className:"bj-actions",children:[(0,t.jsxs)("button",{type:"button",disabled:o<=0,onClick:()=>n(),children:[i,e?`\xB7\u5269 ${o} \u624B`:""]}),a.map(r=>(0,t.jsxs)("button",{type:"button",disabled:(e?.chips??0)<r,onClick:()=>n(r),children:[d(r)," CHIP"]},r))]})}function W({me:e,onDeal:n}){let i=e.maxRaiseBetChips,[o,a]=(0,j.useState)(!1),[r,s]=(0,j.useState)("");if(i===void 0)return null;let u=Number(r),p=r.trim()===""?"\u8BF7\u8F93\u5165\u6CE8\u989D\u3002":K(u,{balanceChips:e.chips,maxChips:i});return(0,t.jsxs)("div",{children:[(0,t.jsx)("div",{className:"bj-actions",children:(0,t.jsx)("button",{type:"button",onClick:()=>a(!o),children:"\u81EA\u5B9A\u4E49\u6CE8\u989D"})}),o?(0,t.jsxs)("div",{className:"bj-custom",children:[(0,t.jsx)("input",{type:"number",min:1,max:i,value:r,onChange:g=>s(g.target.value),"aria-label":"\u81EA\u5B9A\u4E49\u6CE8\u989D"}),(0,t.jsx)("button",{type:"button",disabled:p!==null,onClick:()=>n(u),children:"\u5F00\u59CB"}),(0,t.jsx)("span",{className:"bj-hint",children:p??`1 \uFF5E ${d(i)} CHIP`})]}):null]})}function Y({me:e,onDeal:n}){let i=e?.freeHandsRemaining??0,o=e?.baseBetChips??0,a=e?[o,o*2]:[],r=e?a.some(s=>e.chips>=s):!1;return(0,t.jsxs)("div",{children:[(0,t.jsx)("div",{className:"bj-meta",children:"\u5F53\u524D\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684\u724C\u5C40\u3002"}),(0,t.jsxs)("div",{className:"bj-group",children:[(0,t.jsxs)("div",{className:"bj-group-title",children:["\u514D\u8D39\u624B \xB7 ",i>0?`\u4ECA\u65E5\u5269 ${i} \u624B`:"\u4ECA\u65E5\u5DF2\u7528\u5B8C\uFF0C\u660E\u5929\u518D\u6765"]}),e?(0,t.jsxs)("div",{className:"bj-note",children:["\u4E0D\u7528\u51FA CHIP\u3002\u8D62\u4E86\u62FF ",d(o)," CHIP\uFF1B\u5934\u4E24\u5F20\u724C\u5C31\u51D1\u6210 21 \u70B9\uFF08A \u914D 10/J/Q/K\uFF09\u62FF"," ",d(Math.floor(o*1.5)),"\u3002\u8F93\u4E86\u6216\u5E73\u5C40\u90FD\u4E0D\u635F\u5931\u4EFB\u4F55\u4E1C\u897F\u3002"]}):null,(0,t.jsx)("div",{className:"bj-actions",children:(0,t.jsx)("button",{type:"button",disabled:i<=0,onClick:()=>n(),children:"\u5F00\u59CB\u514D\u8D39\u7684\u4E00\u5C40"})})]}),e?(0,t.jsxs)("div",{className:"bj-group",children:[(0,t.jsxs)("div",{className:"bj-group-title",children:["\u7528\u4F59\u989D\u52A0\u6CE8",r?"":" \xB7 \u4F59\u989D\u4E0D\u8DB3"]}),(0,t.jsx)("div",{className:"bj-note",children:"\u52A0\u6CE8\u7684 CHIP \u4ECE\u4F60\u7684\u4F59\u989D\u91CC\u51FA\uFF0C\u8D62\u4E86\u7FFB\u500D\uFF0C\u8F93\u4E86\u6536\u4E0D\u56DE\u3002"}),(0,t.jsx)("div",{className:"bj-actions",children:a.map(s=>(0,t.jsxs)("button",{type:"button",disabled:e.chips<s,onClick:()=>n(s),children:[d(s)," CHIP"]},s))}),(0,t.jsx)(W,{me:e,onDeal:n})]}):null]})}function Z({me:e,onDeal:n,onDismiss:i}){return(0,t.jsxs)("div",{children:[(0,t.jsx)(Q,{me:e,onDeal:n,freeLabel:"\u518D\u6765\u4E00\u5C40\uFF08\u514D\u8D39"}),(0,t.jsx)("div",{className:"bj-actions",children:(0,t.jsx)("button",{type:"button",onClick:i,children:"\u6536\u8D77"})})]})}function T({state:e,onAction:n,onDeal:i,onDismiss:o,error:a}){if(!e.consented)return(0,t.jsx)(U,{});let{me:r,round:s}=e;return(0,t.jsxs)("div",{className:"bj-table",children:[(0,t.jsx)("style",{children:X}),a?(0,t.jsx)("div",{className:"bj-error",children:a}):null,r?(0,t.jsx)(z,{me:r}):null,s?(0,t.jsxs)("div",{children:[s.hands.map((u,p)=>(0,t.jsx)(O,{hand:u,label:s.hands.length>1?`\u4F60\u7684\u7B2C ${p+1} \u624B`:"\u4F60\u7684\u724C"},p)),(0,t.jsx)(_,{dealer:s.dealer}),(0,t.jsx)(F,{round:s}),(0,t.jsx)(q,{round:s,me:r,onAction:n}),s.phase==="settled"?(0,t.jsx)(Z,{me:r,onDeal:i,onDismiss:o}):null]}):(0,t.jsx)(Y,{me:r,onDeal:i})]})}function h(e,n){switch(n.type){case"synced":return{consented:n.payload.consented,me:n.payload.me,round:n.payload.round};case"round":return{...e,round:n.round};case"meRefreshed":return{...e,me:n.me};case"dismissed":return{...e,round:void 0}}}var ee=new Set(["","deal"]);function H(e){let n=(e.args??"").trim().split(/\s+/)[0]??"",i=ee.has(n),o=e.outcome,a=o?.kind==="error";return i?{table:!0,isError:a,...a&&o?.text?{text:o.text}:{}}:{table:!1,isError:a,...o?.text!==void 0?{text:o.text}:{}}}var f=require("react/jsx-runtime"),te=["slots"];async function k(e,n){let i=await fetch(e,n),o=await i.text(),a=o.length>0?JSON.parse(o):{};if(!i.ok){let r=typeof a?.error=="string"?a.error:`${i.status}`;throw new Error(r)}return a}var ne="\u4E0A\u4E00\u6B21\u64CD\u4F5C\u6CA1\u6709\u6210\u529F\uFF0C\u5DF2\u4E3A\u4F60\u5237\u65B0\u5230\u6700\u65B0\u72B6\u6001\u3002";function ie({node:e}){let n=H(e),[i,o]=(0,l.useState)(null),[a,r]=(0,l.useState)(null),s=(0,l.useCallback)(()=>{k("/blackjack/api/state").then(c=>o(b=>h(b??{consented:!1},{type:"synced",payload:c}))).catch(()=>o({consented:!1}))},[]),u=(0,l.useCallback)(()=>{k("/blackjack/api/state").then(c=>o(b=>b&&h(b,{type:"meRefreshed",me:c.me}))).catch(()=>{})},[]);(0,l.useEffect)(()=>{n.table&&s()},[s,n.table]);let p=(0,l.useCallback)((c,b)=>{k(c,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(b)}).then(R=>{r(null),o(v=>v&&h(v,{type:"round",round:R})),u()}).catch(()=>{r(ne),s()})},[u,s]),g=(0,l.useCallback)(c=>p("/blackjack/api/deal",c===void 0?{}:{betChips:c}),[p]),E=(0,l.useCallback)(c=>p("/blackjack/api/action",{action:c}),[p]),I=(0,l.useCallback)(()=>o(c=>c&&h(c,{type:"dismissed"})),[]),x=n.text===void 0?null:(0,f.jsx)("div",{style:{whiteSpace:"pre-wrap",marginBottom:"8px",...n.isError?{color:"#c0392b"}:{}},children:(0,f.jsx)(S,{text:n.text})});return!n.table||i===null?x:(0,f.jsxs)("div",{children:[x,(0,f.jsx)(T,{state:i,onAction:E,onDeal:g,onDismiss:I,error:a??void 0})]})}function oe(e){e.slots.inject("conversation.chat.commandview",()=>e.slots.register({name:"conversation.chat.commandview",key:"blackjack",inject:()=>({})},ie))}
 		return module.exports;
 	}
 });

package/dist/commands.js

@@ -163,12 +163,17 @@ export function registerCommands(ctx, deps) {
         if (me.githubLogin === null) {
             const pairing = await api.startPairing(token);
             const minutes = Math.max(1, Math.round(pairing.expiresInSeconds / 60));
+            // 只给链接，不单独列配对码：链接里已经含它了，而单独列出会让人以为要
+            // 手动填到某处（运营者第一次用就这么理解了，连开了三次都没敢往下走）。
             return ok([
-                '首次兑换需要先在浏览器里绑定 GitHub 账号：',
-                `配对码：${pairing.code}`,
-                `链接：${pairing.url}`,
-                `有效期：约 ${minutes} 分钟`,
-                '绑定完成后，以后直接用 /blackjack exchange <数量> 就能兑换，不必再开浏览器。',
+                '首次兑换要先绑定 GitHub，只需做这一次。',
+                '',
+                '请在浏览器里打开这个链接：',
+                pairing.url,
+                '',
+                '打开后点「用 GitHub 继续」授权，然后在同一个页面填写要兑换的数量并提交。',
+                `链接约 ${minutes} 分钟内有效；过期了就再执行一次 /blackjack exchange 拿一个新的。`,
+                '绑定完成后，以后直接用 /blackjack exchange <数量> 兑换，不用再开浏览器。',
             ].join('\n'));
         }
         if (amountArg === undefined) {
@@ -182,9 +187,12 @@ export function registerCommands(ctx, deps) {
         if (!Number.isInteger(chips) || chips <= 0)
             return fail('兑换数量必须是正整数。');
         const result = await api.exchange(token, chips);
+        // 必须讲清楚这份额度什么时候会被用上：运营者兑换完就问"我该怎么用"——
+        // 因为兑换成功的提示从没说过触发条件，玩家以为兑换完就能直接花。
         return ok([
             `已兑换 ${n(result.chips)} CHIP。`,
             `累计已兑换额度：${n(result.exchangedChips)} CHIP`,
+            '这份额度会在你自己的模型额度耗尽时，自动接管那一次失败的请求；平时不会动用，你不需要做任何事。',
             result.note,
         ].join('\n'));
     }

package/dist/copy.d.ts

@@ -0,0 +1,8 @@
+import type { RoundView } from './api.js';
+/** 这一局的性质与代价。进行中时显示，让玩家随时知道自己在打哪种局。 */
+export declare function stakeLine(round: RoundView): string;
+/**
+ * 结算结果。分模式措辞——原先两种局共用一句「本手没有收获，明天再来」，
+ * 而加注局只要有余额马上就能再来，那句话是错的。
+ */
+export declare function outcomeLine(round: RoundView): string;

package/dist/copy.js

@@ -0,0 +1,37 @@
+/**
+ * 牌局文案的单一来源。命令面（render.ts）与图形牌桌（client/Table.tsx）共用
+ * 这里的字符串，否则两边会各说各话——而运营者第一次自己上手时，正是因为
+ * 界面没讲清楚"免费手"和"加注"的区别而看不懂在玩什么。
+ *
+ * 红线（见 render.ts 的 BANNED）：单位一律 CHIP，不用「筹码」；不出现赌博词汇。
+ * @module dsh-blackjack/copy
+ */
+const n = (v) => v.toLocaleString('en-US');
+/** 这一局的性质与代价。进行中时显示，让玩家随时知道自己在打哪种局。 */
+export function stakeLine(round) {
+    return round.mode === 'free'
+        ? `这是免费的一局：赢了拿 ${n(round.betChips)} CHIP，输了不损失任何东西。`
+        : `本局已加注 ${n(round.betChips)} CHIP，从你的余额里出。`;
+}
+/**
+ * 结算结果。分模式措辞——原先两种局共用一句「本手没有收获，明天再来」，
+ * 而加注局只要有余额马上就能再来，那句话是错的。
+ */
+export function outcomeLine(round) {
+    const payout = round.payoutChips ?? 0;
+    const bet = round.betChips;
+    // 加注局平局会原样退回本金，payout > 0 —— 先判平局，否则会被说成赢了。
+    if (round.hands.length > 0 && round.hands.every((h) => h.outcome === 'push')) {
+        return round.mode === 'free'
+            ? '平局。这手不损失也不获得。'
+            : `平局。加注的 ${n(bet)} CHIP 原样退回。`;
+    }
+    if (payout > 0) {
+        return round.mode === 'free'
+            ? `赢了，拿到 ${n(payout)} CHIP。`
+            : `赢了，拿回 ${n(payout)} CHIP（加注 ${n(bet)}）。`;
+    }
+    return round.mode === 'free'
+        ? '这手输了。免费手不损失任何东西。'
+        : `这手输了，加注的 ${n(bet)} CHIP 收不回。`;
+}

package/dist/render.js

@@ -1,3 +1,4 @@
+import { stakeLine, outcomeLine } from './copy.js';
 const SUITS = { S: '♠', H: '♥', D: '♦', C: '♣' };
 /**
  * Regex of vocabulary this project's copy must never contain (parent spec §2
@@ -37,13 +38,14 @@ export function renderRound(view) {
     lines.push(`庄家：${dealer}${view.dealer.total !== undefined ? `（${view.dealer.total}）` : ''}`);
     if (view.phase === 'settled') {
         const won = view.payoutChips ?? 0;
-        lines.push(won > 0 ? `本手赢得 ${n(won)} CHIP。` : '本手没有收获，明天再来。');
+        lines.push(outcomeLine(view));
         if (view.pointsGranted)
             lines.push(`本期奖池已发完，改为发放 ${n(view.pointsGranted)} 积分。`);
         if (won > 0)
             lines.push('（已获得的 CHIP 有效期至本赛季末）');
     }
     else {
+        lines.push(stakeLine(view));
         const map = {
             hit: '/bj-hit 要牌', stand: '/bj-stand 停牌', double: '/bj-double 双倍',
             split: '/bj-split 分牌', insure: '/bj-insure 买保险', decline: '/bj-decline 不买保险',

package/dist/router.d.ts

@@ -27,6 +27,23 @@ export declare function shouldFallback(input: {
     hasToken: boolean;
     provider: string;
 }): boolean;
+/**
+ * 这次失败是否该提示玩家"你有已兑换额度，但续命现在用不上"。
+ *
+ * 续命的触发条件是**你自己的额度耗尽**（QUOTA_EXCEEDED），不是根本没配 key。
+ * 运营者兑换到 50,000 CHIP 后问"我该怎么用"，正是因为他没配 key、报的是
+ * MISSING_CREDENTIAL，于是什么都没发生，也没有任何东西解释为什么。这里只负责
+ * 说明，不改变任何行为——原始失败照样原样透传。
+ */
+export declare const NO_CREDENTIAL_HINT = "\u7EED\u547D\u53EA\u5728\u4F60\u81EA\u5DF1\u7684\u6A21\u578B\u989D\u5EA6\u8017\u5C3D\u65F6\u63A5\u7BA1\uFF1B\u5F53\u524D\u662F\u6CA1\u6709\u914D\u7F6E key\uFF0C\u6240\u4EE5\u7528\u4E0D\u5230\u4F60\u5DF2\u5151\u6362\u7684\u989D\u5EA6\u3002";
+/** 抛出来的错误是否读作"没配 key"。 */
+export declare function isMissingCredentialError(error: unknown): boolean;
+export declare function shouldHintNoCredential(input: {
+    finish: StreamChunk & {
+        type: 'finish';
+    };
+    provider: string;
+}): boolean;
 export interface FallbackDeps {
     hasToken: () => Promise<boolean>;
     poolStream: (options: GenerateOptions) => AsyncIterable<StreamChunk>;

package/dist/router.js

@@ -43,6 +43,36 @@ export function shouldFallback(input) {
         return false;
     return isQuotaFailure(reason.failure);
 }
+/**
+ * 「没配 key」的错误码。dsh-llm@0.1.0-rc.6 只导出了 INVALID_CREDENTIAL_CODE 和
+ * QUOTA_EXCEEDED_CODE，这个没有导出常量——字面值由该包源码里 INVALID_CREDENTIAL
+ * 的注释（"Distinct from `MISSING_CREDENTIAL`"）与宿主 UI 上的徽章共同确认。
+ */
+const MISSING_CREDENTIAL_CODE = 'MISSING_CREDENTIAL';
+/**
+ * 这次失败是否该提示玩家"你有已兑换额度，但续命现在用不上"。
+ *
+ * 续命的触发条件是**你自己的额度耗尽**（QUOTA_EXCEEDED），不是根本没配 key。
+ * 运营者兑换到 50,000 CHIP 后问"我该怎么用"，正是因为他没配 key、报的是
+ * MISSING_CREDENTIAL，于是什么都没发生，也没有任何东西解释为什么。这里只负责
+ * 说明，不改变任何行为——原始失败照样原样透传。
+ */
+export const NO_CREDENTIAL_HINT = '续命只在你自己的模型额度耗尽时接管；当前是没有配置 key，所以用不到你已兑换的额度。';
+/** 抛出来的错误是否读作"没配 key"。 */
+export function isMissingCredentialError(error) {
+    const e = error;
+    if (e && typeof e === 'object' && e.code === MISSING_CREDENTIAL_CODE)
+        return true;
+    return typeof e?.message === 'string' && /no API key|MISSING_CREDENTIAL/i.test(e.message);
+}
+export function shouldHintNoCredential(input) {
+    if (input.provider === POOL_PROVIDER)
+        return false;
+    const reason = input.finish.reason;
+    if (reason.kind !== 'error')
+        return false;
+    return reason.failure.code === MISSING_CREDENTIAL_CODE;
+}
 /**
  * Wrap one model call: pass everything through, and only when the call ends
  * with a content-free quota failure retry it against the pool route. Any
@@ -69,18 +99,36 @@ export async function* runWithFallback(options, next, deps) {
     let emittedContent = false;
     let finish;
     const pendingUsage = [];
-    for await (const c of next()) {
-        if (c.type === 'finish') {
-            finish = c;
-            break;
+    try {
+        for await (const c of next()) {
+            if (c.type === 'finish') {
+                finish = c;
+                break;
+            }
+            if (c.type === 'usage') {
+                pendingUsage.push(c);
+                continue;
+            }
+            if (CONTENT_TYPES.has(c.type))
+                emittedContent = true;
+            yield c;
         }
-        if (c.type === 'usage') {
-            pendingUsage.push(c);
-            continue;
+    }
+    catch (error) {
+        // 没配 key 时适配器在发请求前就抛，根本不产出 finish 分片。只说明，
+        // 不改变行为——原始错误原样抛出去，装了这个插件不会让任何调用变差。
+        if (options.provider !== POOL_PROVIDER && isMissingCredentialError(error)) {
+            let hinted = false;
+            try {
+                hinted = await deps.hasToken();
+            }
+            catch {
+                hinted = false;
+            }
+            if (hinted)
+                deps.notify(NO_CREDENTIAL_HINT);
         }
-        if (CONTENT_TYPES.has(c.type))
-            emittedContent = true;
-        yield c;
+        throw error;
     }
     if (!finish)
         return;
@@ -90,6 +138,21 @@ export async function* runWithFallback(options, next, deps) {
     // a credential resolve, and a credentials-provider rejection can only ever
     // affect a call this plugin was already about to intervene on.
     if (!shouldFallback({ finish, emittedContent, hasToken: true, provider: options.provider })) {
+        // 唯一的例外：没配 key 时，玩家可能正攥着一份用不上的已兑换额度而不知道
+        // 为什么。这条只说明、不改行为。await hasToken() 只发生在这个已经失败
+        // 且罕见的分支上，正常调用仍然不付凭证解析的代价。
+        if (shouldHintNoCredential({ finish, provider: options.provider })) {
+            let hinted = false;
+            try {
+                hinted = await deps.hasToken();
+            }
+            catch {
+                hinted = false;
+            }
+            if (hinted) {
+                deps.notify(NO_CREDENTIAL_HINT);
+            }
+        }
         yield* pendingUsage;
         yield finish;
         return;
@@ -113,6 +176,11 @@ export async function* runWithFallback(options, next, deps) {
     try {
         for await (const c of deps.poolStream({ ...options, provider: POOL_PROVIDER })) {
             if (c.type === 'finish' && c.reason.kind === 'error') {
+                // 奖池这一侧的失败必须留痕。原先它被静默丢弃、连日志都没有，于是
+                // "续命明明接管了却还是失败"这种情况从外面完全看不出来——真实事故里
+                // 奖池回的是 `unknown model: deepseek-v4-flash`（模型不在价目表里），
+                // 而玩家只看到原始的 Insufficient Balance，跟没装插件一模一样。
+                deps.logError?.(new Error(`dsh-blackjack: pool retry failed after a quota exhaustion; pool said ${JSON.stringify(c.reason.failure)}`));
                 yield finish;
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-blackjack",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "社区福利小游戏插件：在 dsh 里玩 21 点赢取可消费的模型额度",
   "license": "MIT",
   "keywords": [