dsh-blackjack 0.1.0

package/dist/client.js

@@ -0,0 +1,26 @@
+import{useCallback as p,useEffect as T,useState as k}from"react";import{jsx as t,jsxs as r}from"react/jsx-runtime";var v={S:"\u2660",H:"\u2665",D:"\u2666",C:"\u2663"},j=new Set(["H","D"]),d=e=>e.toLocaleString("en-US"),x={hit:"\u8981\u724C",stand:"\u505C\u724C",double:"\u53CC\u500D",split:"\u5206\u724C",insure:"\u4E70\u4FDD\u9669",decline:"\u4E0D\u4E70\u4FDD\u9669"},h=`
+.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 {
+  width: 38px; height: 54px; border-radius: 6px; display: flex; align-items: center;
+  justify-content: center; font-weight: 700; font-size: 15px; box-shadow: 0 1px 2px rgba(0,0,0,.35);
+  background: #fdfdf8; border: 1px solid rgba(0,0,0,.15);
+}
+.bj-card-red { color: #c0392b; }
+.bj-card-black { color: #1a1a1a; }
+.bj-card-back {
+  background-image: repeating-linear-gradient(45deg, #2a5aa0, #2a5aa0 4px, #1d4278 4px, #1d4278 8px);
+  border: 1px solid rgba(255,255,255,.4);
+}
+.bj-actions { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 8px; }
+.bj-actions button {
+  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-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 t("div",{className:"bj-card bj-card-back","aria-label":"\u6697\u724C"});let n=v[e.suit]??e.suit,a=j.has(e.suit)?"bj-card-red":"bj-card-black";return t("div",{className:`bj-card ${a}`,children:`${e.rank}${n}`})}function S({hand:e,label:n}){let a=e.soft?"\u8F6F":"";return r("div",{children:[r("div",{className:"bj-meta",children:[n,"\uFF08",a,e.total,"\uFF09",e.doubled?" [\u53CC\u500D]":""]}),t("div",{className:"bj-hand",children:e.cards.map((s,o)=>t(u,{card:s},o))})]})}function w({dealer:e}){return r("div",{children:[r("div",{className:"bj-meta",children:["\u5E84\u5BB6",e.total!==void 0?`\uFF08${e.total}\uFF09`:""]}),t("div",{className:"bj-hand",children:e.cards.map((n,a)=>t(u,{card:n},a))})]})}function y(){return t("div",{className:"bj-table",children:r("p",{children:["\u8BF7\u5148\u5728\u547D\u4EE4\u884C\u8F93\u5165 ",t("code",{children:"/blackjack agree"}),"\uFF0C\u9605\u8BFB\u5E76\u540C\u610F\u89C4\u5219\u540E\u624D\u80FD\u5F00\u59CB\u3002"]})})}function C({me:e}){return r("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?t("div",{children:e.sponsorText}):null]})}function N({round:e}){if(e.phase!=="settled")return null;let n=e.payoutChips??0;return r("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?r("div",{children:["\u672C\u671F\u5956\u6C60\u5DF2\u53D1\u5B8C\uFF0C\u6539\u4E3A\u53D1\u653E ",d(e.pointsGranted)," \u79EF\u5206\u3002"]}):null]})}function E({round:e,onAction:n}){return e.actions.length===0?null:t("div",{className:"bj-actions",children:e.actions.map(a=>t("button",{type:"button",onClick:()=>n(a),children:x[a]??a},a))})}function A({me:e,onDeal:n}){return r("div",{children:[t("div",{className:"bj-meta",children:"\u5F53\u524D\u6CA1\u6709\u8FDB\u884C\u4E2D\u7684\u724C\u5C40\u3002"}),r("div",{className:"bj-actions",children:[t("button",{type:"button",onClick:()=>n(),children:"\u5F00\u59CB\u4E00\u5C40\uFF08\u9650\u514D\uFF09"}),e?r("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:s}){if(!e.consented)return t(y,{});let{me:o,round:i}=e;return r("div",{className:"bj-table",children:[t("style",{children:h}),s?t("div",{className:"bj-error",children:s}):null,o?t(C,{me:o}):null,i?r("div",{children:[i.hands.map((b,l)=>t(S,{hand:b,label:i.hands.length>1?`\u4F60\u7684\u7B2C ${l+1} \u624B`:"\u4F60\u7684\u724C"},l)),t(w,{dealer:i.dealer}),t(N,{round:i}),t(E,{round:i,onAction:n})]}):t(A,{me:o,onDeal:a})]})}import{jsx as J}from"react/jsx-runtime";var D=["slots"];async function f(e,n){let a=await fetch(e,n),s=await a.text(),o=s.length>0?JSON.parse(s):{};if(!a.ok){let i=typeof o?.error=="string"?o.error:`${a.status}`;throw new Error(i)}return o}var B="\u4E0A\u4E00\u6B21\u64CD\u4F5C\u6CA1\u6709\u6210\u529F\uFF0C\u5DF2\u4E3A\u4F60\u5237\u65B0\u5230\u6700\u65B0\u72B6\u6001\u3002";function R(){let[e,n]=k(null),[a,s]=k(null),o=p(()=>{f("/blackjack/api/state").then(n).catch(()=>n({consented:!1}))},[]);T(()=>{o()},[o]);let i=p((c,g)=>{f(c,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(g)}).then(()=>{s(null),o()}).catch(()=>{s(B),o()})},[o]),b=p(c=>i("/blackjack/api/deal",c===void 0?{}:{betChips:c}),[i]),l=p(c=>i("/blackjack/api/action",{action:c}),[i]);return e===null?null:J(m,{state:e,onAction:l,onDeal:b,error:a??void 0})}function P(e){e.slots.inject("conversation.chat.commandview",()=>e.slots.register({name:"conversation.chat.commandview",key:"blackjack",inject:()=>({})},R))}export{P as apply,D as inject};

package/dist/commands.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Api } from './api.js';
+import type { Identity } from './identity.js';
+/**
+ * Register the zero-token blackjack table commands. Every handler here runs
+ * through `ctx.commands.register`, so its result never enters model history
+ * and no player text is ever sent as a session message — the whole point of
+ * the table costing nothing.
+ *
+ * Handlers must never throw: an uncaught throw settles as `command/done`
+ * with `kind:'error'` and writes internal detail into the session log, so
+ * every branch below is wrapped to translate failures into plain Chinese.
+ */
+export declare function registerCommands(ctx: Context, deps: {
+    api: Api;
+    identity: Identity;
+}): void;

package/dist/commands.js

@@ -0,0 +1,262 @@
+import { ApiError } from './api.js';
+import { CONSENT_TEXT, renderMe, renderRound } from './render.js';
+const AGREE_HINT = '请先阅读须知并执行 /blackjack agree 后再使用。';
+const NO_ROUND_HINT = '当前没有进行中的牌局，先用 /blackjack deal 开一局。';
+const USAGE = 'agree | deal [注额] | exchange [数量] | reset';
+const n = (v) => v.toLocaleString('en-US');
+const ACTIONS = [
+    { name: 'bj-hit', action: 'hit', description: '21 点：向牌桌要一张牌' },
+    { name: 'bj-stand', action: 'stand', description: '21 点：停牌，进入结算' },
+    { name: 'bj-double', action: 'double', description: '21 点：加倍注额并再要一张牌' },
+    { name: 'bj-split', action: 'split', description: '21 点：把一对相同点数的牌分成两手' },
+    { name: 'bj-insure', action: 'insure', description: '21 点：庄家明牌为 A 时购买保险' },
+    { name: 'bj-decline', action: 'decline', description: '21 点：不购买保险' },
+];
+function ok(text) {
+    return { kind: 'success', text };
+}
+function fail(text) {
+    return { kind: 'error', text };
+}
+/**
+ * Register the zero-token blackjack table commands. Every handler here runs
+ * through `ctx.commands.register`, so its result never enters model history
+ * and no player text is ever sent as a session message — the whole point of
+ * the table costing nothing.
+ *
+ * Handlers must never throw: an uncaught throw settles as `command/done`
+ * with `kind:'error'` and writes internal detail into the session log, so
+ * every branch below is wrapped to translate failures into plain Chinese.
+ */
+export function registerCommands(ctx, deps) {
+    const { api, identity } = deps;
+    // Cheap in-memory hint for "which round is active" so most actions skip a
+    // round-trip; always falls back to the server (api.activeRound) when this
+    // is empty, e.g. right after a process restart.
+    let activeRoundId;
+    function noteRound(round) {
+        activeRoundId = round.phase === 'settled' ? undefined : round.id;
+    }
+    /** Translate a caught failure into player-safe Chinese. Never leaks status codes, URLs, or stack traces. */
+    async function mapError(e, token) {
+        if (!(e instanceof ApiError))
+            return fail('操作没有成功，请稍后再试。');
+        if (e.status === 0 || e.status >= 500)
+            return fail('暂时连不上牌桌服务，请稍后再试。');
+        if (e.status === 403 && e.code === 'no free hands left')
+            return fail('今天的免费手用完了，明天再来。');
+        if (e.status === 403 && e.code === 'below threshold')
+            return fail('余额还没到兑换门槛。');
+        if (e.status === 402)
+            return fail('余额不足以完成这个动作。');
+        // 404 = 这局在服务端已经不存在了（最常见的来路：玩家刚在图形牌桌上把它打
+        // 完，而这里的 activeRoundId 还停在旧 id 上）。缓存必须清掉，否则下一条动作
+        // 命令会拿着同一个死 id 再撞一次；提示也要说清楚该怎么办，而不是给一句通用
+        // 的"操作没有成功"。
+        if (e.status === 404) {
+            activeRoundId = undefined;
+            return fail(NO_ROUND_HINT);
+        }
+        if (e.status === 409) {
+            if (token) {
+                try {
+                    const round = await api.activeRound(token);
+                    if (round) {
+                        noteRound(round);
+                        return fail(['已经有一局在进行中。', renderRound(round)].join('\n'));
+                    }
+                }
+                catch {
+                    // fall through to the plain message below — never let a nested
+                    // failure here mask the original 409.
+                }
+            }
+            return fail('已经有一局在进行中。');
+        }
+        return fail('操作没有成功，请稍后再试。');
+    }
+    /** Resolve the bearer token, guiding to consent when absent, then run `body` catching every failure. */
+    async function withToken(body) {
+        const token = await identity.current();
+        if (!token)
+            return fail(AGREE_HINT);
+        try {
+            return await body(token);
+        }
+        catch (e) {
+            return mapError(e, token);
+        }
+    }
+    /** Memory-first, server-fallback lookup for the id an action command needs. */
+    async function currentRoundId(token) {
+        if (activeRoundId)
+            return activeRoundId;
+        const round = await api.activeRound(token);
+        if (!round)
+            return undefined;
+        noteRound(round);
+        return round.id;
+    }
+    async function showStatus() {
+        const token = await identity.current();
+        if (!token)
+            return ok(CONSENT_TEXT);
+        try {
+            const round = await api.activeRound(token);
+            if (round) {
+                noteRound(round);
+                return ok(renderRound(round));
+            }
+            activeRoundId = undefined;
+            const me = await api.me(token);
+            return ok(renderMe(me));
+        }
+        catch (e) {
+            return mapError(e, token);
+        }
+    }
+    async function doAgree() {
+        try {
+            await identity.accept();
+            return ok([
+                '已确认须知，欢迎上桌。',
+                '/blackjack deal 开始今天的免费手，或 /blackjack deal <注额> 用余额加注。',
+            ].join('\n'));
+        }
+        catch (e) {
+            return mapError(e);
+        }
+    }
+    async function doDeal(token, betArg) {
+        const body = betArg === undefined
+            ? { mode: 'free' }
+            : (() => {
+                const bet = Number(betArg);
+                if (!Number.isInteger(bet) || bet <= 0)
+                    return undefined;
+                return { mode: 'raise', betChips: bet };
+            })();
+        if (!body)
+            return fail('注额必须是正整数。');
+        const round = await api.startRound(token, body);
+        noteRound(round);
+        return ok(renderRound(round));
+    }
+    /**
+     * Exchange has TWO paths, and which one applies is a property of the player,
+     * not of the command:
+     *
+     * - **Never bound** (`me.githubLogin === null`): the browser dance is
+     *   unavoidable — only a browser can complete GitHub's authorization-code
+     *   flow — so hand back a pairing code and link.
+     * - **Already bound**: `POST /api/exchange` does it directly, in one command,
+     *   with no link to open. Routing an already-bound player through pairing
+     *   anyway would be busywork: a fresh code, a browser tab, and a form, all to
+     *   reach an endpoint the plugin can already call with the token it holds.
+     *
+     * The bound path needs an amount, because unlike the pairing page there is no
+     * form to fill in afterwards; asking for it up front beats guessing (an
+     * implicit "exchange everything" would be irreversible and unasked-for).
+     */
+    async function doExchange(token, amountArg) {
+        const me = await api.me(token);
+        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 <数量> 就能兑换，不必再开浏览器。',
+            ].join('\n'));
+        }
+        if (amountArg === undefined) {
+            return fail([
+                `已绑定 GitHub 账号：${me.githubLogin}`,
+                `当前余额：${n(me.chips)} CHIP　兑换门槛：${n(me.exchangeThresholdChips)} CHIP`,
+                '请用 /blackjack exchange <数量> 指定要兑换的 CHIP 数量。',
+            ].join('\n'));
+        }
+        const chips = Number(amountArg);
+        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'));
+    }
+    async function doReset(confirmArg) {
+        if (confirmArg !== 'confirm') {
+            return ok('这会清除本机保存的牌桌凭证（不影响服务端记录，重新配对即可找回）。确认请执行 /blackjack reset confirm');
+        }
+        try {
+            await identity.clear();
+            activeRoundId = undefined;
+            return ok('已清除本机凭证，可用 /blackjack agree 重新开始。');
+        }
+        catch (e) {
+            return mapError(e);
+        }
+    }
+    // The six bj-* commands register `doAction` directly as their handler —
+    // unlike blackjackHandler, there is no outer try/catch wrapping the
+    // registration, so this function's own try/catch must cover EVERY await
+    // in its body, including the token fetch. `identity.current()` resolves
+    // through the credentials service, which a file-backed provider can throw
+    // from (I/O or parse error); a throw here must never escape past this
+    // function, or the command runtime records it verbatim (with internal
+    // detail) into the session log instead of the generic failure text.
+    async function doAction(action) {
+        let token;
+        try {
+            token = await identity.current();
+            if (!token)
+                return fail(AGREE_HINT);
+            const id = await currentRoundId(token);
+            if (!id)
+                return fail(NO_ROUND_HINT);
+            const result = await api.act(token, id, action);
+            noteRound(result);
+            return ok(renderRound(result));
+        }
+        catch (e) {
+            return mapError(e, token);
+        }
+    }
+    async function blackjackHandler(inv) {
+        try {
+            const parts = inv.rawInput.trim().split(/\s+/).filter(Boolean);
+            const sub = parts[0] ?? '';
+            switch (sub) {
+                case '': return await showStatus();
+                case 'agree': return await doAgree();
+                case 'deal': return await withToken((token) => doDeal(token, parts[1]));
+                case 'exchange': return await withToken((token) => doExchange(token, parts[1]));
+                case 'reset': return await doReset(parts[1]);
+                default: return fail(`未知子命令「${sub}」。可用：${USAGE}`);
+            }
+        }
+        catch (e) {
+            // Belt-and-suspenders: every branch above already catches, but a
+            // handler must never throw — a thrown error would be recorded verbatim
+            // into the session log by the command runtime.
+            return mapError(e);
+        }
+    }
+    ctx.commands.register({
+        name: 'blackjack',
+        description: '打开 21 点牌桌：查看状态、开局、兑换额度、重置本机凭证',
+        input: { hint: USAGE },
+        handler: blackjackHandler,
+    });
+    for (const { name, action, description } of ACTIONS) {
+        ctx.commands.register({
+            name,
+            description,
+            handler: () => doAction(action),
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+import Schema from '@deepseek-ai/schemastery';
+/** Cordis plugin name, also used in loader diagnostics and log lines. */
+export declare const PLUGIN_NAME = "dsh-blackjack";
+/**
+ * Credential reference holding this player's server-issued bearer token.
+ * A POSIX env-var-shaped name, as `CredentialRef` requires.
+ */
+export declare const TOKEN_REF = "DSH_BLACKJACK_TOKEN";
+export interface ConfigType {
+    serverUrl: string;
+    enabled: boolean;
+}
+export declare const Config: Schema<Partial<ConfigType>, ConfigType>;

package/dist/config.js

@@ -0,0 +1,16 @@
+import Schema from '@deepseek-ai/schemastery';
+/** Cordis plugin name, also used in loader diagnostics and log lines. */
+export const PLUGIN_NAME = 'dsh-blackjack';
+/**
+ * Credential reference holding this player's server-issued bearer token.
+ * A POSIX env-var-shaped name, as `CredentialRef` requires.
+ */
+export const TOKEN_REF = 'DSH_BLACKJACK_TOKEN';
+export const Config = Schema.object({
+    // 默认指向本项目运营者自托管的那一份服务。想自建奖池的人把这一项改成自己的
+    // 地址即可 —— 服务端与插件同仓开源，自托管是一等公民（见仓库 README）。
+    serverUrl: Schema.string()
+        .default('https://server-production-493c.up.railway.app')
+        .description('牌局服务端地址；自建奖池时改成你自己的部署地址'),
+    enabled: Schema.boolean().default(true).description('停用后不注册命令也不挂路由'),
+});

package/dist/identity.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Api } from './api.js';
+export interface Identity {
+    current(): Promise<string | undefined>;
+    accept(): Promise<string>;
+    clear(): Promise<void>;
+}
+/**
+ * The player's server-issued token doubles as the consent record: no token
+ * means the one-time notice has not been accepted yet.
+ */
+export declare function createIdentity(ctx: Context, api: Api): Identity;

package/dist/identity.js

@@ -0,0 +1,28 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { TOKEN_REF } from './config.js';
+/**
+ * The player's server-issued token doubles as the consent record: no token
+ * means the one-time notice has not been accepted yet.
+ */
+export function createIdentity(ctx, api) {
+    const ref = credentialRef(TOKEN_REF);
+    async function current() {
+        const resolved = await ctx.credentials.resolve(ref);
+        const value = resolved?.value;
+        return value ? value : undefined;
+    }
+    return {
+        current,
+        async accept() {
+            const existing = await current();
+            if (existing)
+                return existing;
+            const { token } = await api.register();
+            await ctx.credentials.set(ref, token);
+            return token;
+        },
+        async clear() {
+            await ctx.credentials.unset(ref);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type ConfigType } from './config.js';
+export declare const name = "dsh-blackjack";
+/**
+ * Services this plugin genuinely reads:
+ * - `commands` — the zero-token table entry point.
+ * - `llm` — adapter registration plus the `llm/stream` fallback waterfall.
+ * - `credentials` — the player's server-issued token.
+ * The web pieces (HTTP routes, table component) are a NESTED plugin injecting
+ * `webServer`, so a headless host leaves that fiber pending instead of failing.
+ */
+export declare const inject: string[];
+export { Config };
+export declare function apply(ctx: Context, config: ConfigType): void;

package/dist/index.js

@@ -0,0 +1,39 @@
+import { createApi } from './api.js';
+import { registerCommands } from './commands.js';
+import { Config, PLUGIN_NAME } from './config.js';
+import { createIdentity } from './identity.js';
+import { registerRouter } from './router.js';
+import { registerRoutes } from './routes.js';
+export const name = PLUGIN_NAME;
+/**
+ * Services this plugin genuinely reads:
+ * - `commands` — the zero-token table entry point.
+ * - `llm` — adapter registration plus the `llm/stream` fallback waterfall.
+ * - `credentials` — the player's server-issued token.
+ * The web pieces (HTTP routes, table component) are a NESTED plugin injecting
+ * `webServer`, so a headless host leaves that fiber pending instead of failing.
+ */
+export const inject = ['commands', 'llm', 'credentials'];
+export { Config };
+export function apply(ctx, config) {
+    if (!config.enabled)
+        return;
+    const api = createApi({ serverUrl: config.serverUrl });
+    const identity = createIdentity(ctx, api);
+    registerCommands(ctx, { api, identity });
+    // The switch notice goes to ctx.logger.info and nowhere else — never a
+    // session message, so a fallback can never pollute model-visible
+    // conversation history. That also means the player does not normally SEE
+    // it; see the known-limitation note on `registerRouter` for why no
+    // in-conversation channel is reachable from a waterfall listener here.
+    registerRouter(ctx, { serverUrl: config.serverUrl, identity });
+    // The graphical table's HTTP surface is a NESTED plugin injecting
+    // `webServer` — a headless/tui host simply leaves this fiber pending
+    // (no `webServer` service to satisfy the inject) while the commands
+    // above keep working unaffected.
+    ctx.plugin({
+        name: 'dsh-blackjack-web',
+        inject: ['webServer'],
+        apply: (webCtx) => registerRoutes(webCtx, { api, identity }),
+    });
+}

package/dist/render.d.ts

@@ -0,0 +1,16 @@
+import type { Card, HiddenCard, MeView, RoundView } from './api.js';
+/**
+ * Regex of vocabulary this project's copy must never contain (parent spec §2
+ * red line 6, 文案去赌场化).
+ *
+ * THE single definition for the whole repo, not just this package: the
+ * server's `test/pairing.test.ts` imports it across the workspace (test-only,
+ * via a relative path) so the plugin's command output and the server's pairing
+ * HTML are held to the exact same list. It used to be duplicated inline there,
+ * which meant tightening one copy silently left the other looser.
+ */
+export declare const BANNED: RegExp;
+export declare const CONSENT_TEXT: string;
+export declare function renderCard(card: Card | HiddenCard): string;
+export declare function renderRound(view: RoundView): string;
+export declare function renderMe(me: MeView): string;

package/dist/render.js

@@ -0,0 +1,70 @@
+const SUITS = { S: '♠', H: '♥', D: '♦', C: '♣' };
+/**
+ * Regex of vocabulary this project's copy must never contain (parent spec §2
+ * red line 6, 文案去赌场化).
+ *
+ * THE single definition for the whole repo, not just this package: the
+ * server's `test/pairing.test.ts` imports it across the workspace (test-only,
+ * via a relative path) so the plugin's command output and the server's pairing
+ * HTML are held to the exact same list. It used to be duplicated inline there,
+ * which meant tightening one copy silently left the other looser.
+ */
+export const BANNED = /赌|博彩|casino|赢钱|下注赢|筹码/i;
+export const CONSENT_TEXT = [
+    '【首次使用请先阅读】',
+    '· 这是社区开发者发布的第三方小游戏，与任何模型厂商均无关联，不代表其立场。',
+    '· 参与免费：每日有限次免费手，输了不扣任何东西，你自己的密钥与余额不受影响。',
+    '· 赢得的 CHIP 只能在本插件内兑换为模型额度消费：不可提现、不可转让、不可转入任何厂商账户。',
+    '· 奖励有赛季有效期，赛季结束后未使用的部分按规则回收。',
+    '',
+    '同意以上内容后执行 /blackjack agree 开始。',
+].join('\n');
+export function renderCard(card) {
+    if ('hidden' in card)
+        return '??';
+    return `${card.rank}${SUITS[card.suit] ?? card.suit}`;
+}
+const n = (v) => v.toLocaleString('en-US');
+export function renderRound(view) {
+    const lines = [];
+    for (const [i, hand] of view.hands.entries()) {
+        const label = view.hands.length > 1 ? `你的第 ${i + 1} 手` : '你的牌';
+        const cards = hand.cards.map(renderCard).join(' ');
+        const soft = hand.soft ? '软' : '';
+        lines.push(`${label}：${cards}（${soft}${hand.total}）${hand.doubled ? ' [双倍]' : ''}`);
+    }
+    const dealer = view.dealer.cards.map(renderCard).join(' ');
+    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。` : '本手没有收获，明天再来。');
+        if (view.pointsGranted)
+            lines.push(`本期奖池已发完，改为发放 ${n(view.pointsGranted)} 积分。`);
+        if (won > 0)
+            lines.push('（已获得的 CHIP 有效期至本赛季末）');
+    }
+    else {
+        const map = {
+            hit: '/bj-hit 要牌', stand: '/bj-stand 停牌', double: '/bj-double 双倍',
+            split: '/bj-split 分牌', insure: '/bj-insure 买保险', decline: '/bj-decline 不买保险',
+        };
+        const actions = view.actions.map((a) => map[a] ?? a).join('　');
+        if (actions)
+            lines.push(`可选：${actions}`);
+    }
+    return lines.join('\n');
+}
+export function renderMe(me) {
+    const lines = [
+        `余额：${n(me.chips)} CHIP　已兑换额度：${n(me.exchangedChips)} CHIP`,
+        `今日剩余免费手：${me.freeHandsRemaining}　赛季：${me.seasonId}`,
+        `兑换门槛：${n(me.exchangeThresholdChips)} CHIP（达标后可用 /blackjack exchange 兑换）`,
+    ];
+    if (me.points > 0)
+        lines.push(`积分：${n(me.points)}`);
+    if (me.poolEmpty)
+        lines.push('提示：本期奖池已发完，现在赢牌将发放积分。');
+    if (me.sponsorText)
+        lines.push(me.sponsorText);
+    return lines.join('\n');
+}

package/dist/router.d.ts

@@ -0,0 +1,100 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { Identity } from './identity.js';
+/** Provider route the pool adapter is registered under; also the loop-guard for `shouldFallback`. */
+export declare const POOL_PROVIDER = "blackjack-pool";
+/**
+ * Decide whether one finished call should be retried on the pool route.
+ *
+ * NOTE on `QUOTA_EXCEEDED_CODE` vs `isQuotaExceededError`: the brief's
+ * original sketch called `isQuotaExceededError(reason.failure)` directly on
+ * the failure object. Checking the installed `@deepseek-ai/dsh-llm@0.1.0-rc.6`
+ * package directly shows `isQuotaExceededError(detail: string): boolean` is a
+ * *raw provider wording* classifier (regexes over free text such as
+ * "insufficient quota") — it is what an adapter uses internally while
+ * normalizing a thrown provider error into a `LlmFailure`, not something a
+ * downstream consumer applies to an already-normalized `finish` chunk as-is.
+ * The normalized signal to compare first is `LlmFailure.code` against
+ * `QUOTA_EXCEEDED_CODE`; `isQuotaExceededError` is kept only as a secondary,
+ * string-joined fallback for adapters that never normalized at all (see
+ * `isQuotaFailure` above).
+ */
+export declare function shouldFallback(input: {
+    finish: StreamChunk & {
+        type: 'finish';
+    };
+    emittedContent: boolean;
+    hasToken: boolean;
+    provider: string;
+}): boolean;
+export interface FallbackDeps {
+    hasToken: () => Promise<boolean>;
+    poolStream: (options: GenerateOptions) => AsyncIterable<StreamChunk>;
+    notify: (line: string) => void;
+    /** Diagnostic-only sink for a swallowed pool-retry failure; never required, never surfaced to the player. */
+    logError?: (error: unknown) => void;
+}
+/**
+ * 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
+ * failure of that retry surfaces the ORIGINAL failure, so installing this
+ * plugin can never make a call worse than not having it.
+ *
+ * Two invariants the pool-retry branch upholds that are easy to get wrong:
+ * - The stream ALWAYS ends with exactly one terminal `finish` chunk. A pool
+ *   retry that throws mid-stream (after already forwarding content), or one
+ *   that simply ends without ever sending its own finish, would otherwise
+ *   leave the consumer's `BlockAssembler` defaulting an absent finish to
+ *   `{kind: 'stop'}` — silently presenting a FAILED fallback as a successful,
+ *   truncated turn. `poolFinished` tracks whether the pool ever produced its
+ *   own terminal finish; whenever it did not, the ORIGINAL failure is yielded
+ *   as the terminal chunk instead (legal even after open content blocks,
+ *   since its `reason.kind` is `'error'`).
+ * - `usage` never gets forwarded twice. Adapters emit at most one `usage`
+ *   chunk, just before their finish. The primary attempt's `usage` (if any)
+ *   is buffered rather than forwarded immediately, so it can be dropped
+ *   entirely once a fallback is underway — the pool call reports its own —
+ *   instead of both being forwarded and double-counting tokens.
+ */
+export declare function runWithFallback(options: GenerateOptions, next: () => AsyncIterable<StreamChunk>, deps: FallbackDeps): AsyncIterable<StreamChunk>;
+/**
+ * Register the pool-route adapter and hang the `llm/stream` fallback
+ * waterfall off it.
+ *
+ * KNOWN LIMITATION — where the switch notice actually goes. `notify` defaults
+ * to `ctx.logger.info`, which means the player normally never SEES it: in dsh
+ * 0.1.0-rc.6 a waterfall listener has no FIRE-AND-FORGET notice channel it may
+ * use. Everything reachable from here was checked (see the plugin spec's §7
+ * appendix for the full record): no host service in this plugin's dependency
+ * closure is a notification sink (`agents`, `sessions`, `credentials`,
+ * `commands`, `llm`, `webServer`, `conversation`, `chatFileMentions`). The one
+ * human-visible in-conversation seam that does exist elsewhere in the host,
+ * `ctx.userQuestions.ask()`, BLOCKS on a human answer and needs a GUI
+ * provider — wrong semantics for a passive notice, and it would stall the very
+ * stream this fallback is rescuing. `commands` only runs when the player types
+ * a slash command;
+ * `agent.inject()` writes a model-visible `user/message`, which is exactly
+ * what this project forbids; and `SurfaceEventType` is a CLOSED three-member
+ * set, so the UI's generic unclaimed-event fallback covers only
+ * model-visible events — a log-only custom event has no renderer at all.
+ * Surfacing it would take a plugin-owned `ConversationNodeDefinition` in the
+ * client bundle, i.e. a new feature that still would not reach TUI/headless
+ * players. The README says plainly that the notice lands in the log, rather
+ * than promising an on-screen one. Revisit when dsh grows a plugin-usable
+ * in-session notice slot.
+ *
+ * What is NOT negotiable either way: the notice must never be injected into
+ * model messages, so a fallback can never pollute conversation history.
+ *
+ * `ctx.llm.registerAdapter()` already ties its disposal to the calling
+ * fiber (cordis re-binds a service's `this.ctx` to whichever context reads
+ * it, so the registration's own internal `ctx.effect` lands on OUR plugin's
+ * fiber, not `llm`'s construction context — confirmed by disposing a probe
+ * fiber and observing the route drop from `listProviders()` with no extra
+ * wrapping). No separate `ctx.effect` around `registration` is needed.
+ */
+export declare function registerRouter(ctx: Context, deps: {
+    serverUrl: string;
+    identity: Identity;
+    notify?: (line: string) => void;
+}): void;