dsh-blackjack

Readme

# dsh-blackjack

DeepSeek-dealt **21 点 (Blackjack) for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)**. The DeepSeek model plays dealer — it deals, decides, and trash-talks as one of two selectable personas — while every round is **event-sourced** into the session log, so hands replay and fork identically. One package ships both the **host game service** and the **browser sidebar UI** (a dual-face bundle), installed in a single `dsh plugin add`.

<!-- markdownlint-disable MD033 -->
English · [中文](README.zh.md)
<!-- markdownlint-enable MD033 -->

> **Install status**
> - ✅ **Complete GitHub install** (verified against `dsh web`): one package = host service + browser UI. The plugin declares both `dsh.bundle` (the host plugin row) and `dsh.client` (the web frontend entry); once installed the host layer mounts and the client module system picks the UI up into the frontend boot graph automatically.
> - All dependencies are the **published `@deepseek-ai/*` npm packages** (`0.1.0-rc.6`) — no sibling monorepo checkout, no unpublished internal packages.

## Features

**Host side**

- **Two dealer personas** you pick per session (durable through `blackjack/persona` events):
  - 🐟 **大肥鱼 / Big Fat Fish** — a gluttonous, lazy deep-sea fish ("咕噜咕噜").
  - 😼 **雌小鬼 / Brat** — a smug, cheeky brat who calls you "杂鱼".
- **Model-dealt decisions**: the dealer decides hit/stand through an auxiliary LLM call, one visible step at a time.
- **Cross-round memory**: the dealer's prompts carry the running score and the shared chatter history.
- **Event sourcing**: `blackjack/game-start|hit|stand|dealer-hit|settle|banter|emotion|persona` are durable session events; the fold replays identically.
- **Graceful degrade**: with the LLM route absent or failing, the dealer falls back to per-persona preset lines.

**Browser UI**

- A 🃏 entry in the sidebar footer opens the 21 table in the right details column.
- The table, dealer-mood badge, lifetime record, a chatter feed (dealer banter plus a staggered card-flip draw animation), and an emoji quick-bar.
- Talks to the host through a self-mounted `blackjack` Remote namespace; the UI holds no game state of its own.

## UI preview

The screenshots below come from verified `dsh web` sessions. The exact cards, dealer lines, and record counters vary with the session log, but they show the complete browser half: the sidebar entry, the table, the chatter feed, and the action bar.

![Sidebar entry](docs/screenshots/01-sidebar-entry.png)

![21-point table](docs/screenshots/02-table-settled.png)

![Dealer chatter and session state](docs/screenshots/03-table-dealt.png)

![Player actions and emoji quick-bar](docs/screenshots/04-table-action.png)

## Install (complete: host + UI)

The plugin is a dsh **dual-face bundle** (`dsh.bundle` → `cordis.patch.yml` + `dsh.client` → `lib/client.js`):

```sh
dsh plugin --profile <name> add github:<owner>/dsh-blackjack
```

A git install fetches sources, so the first `add` needs the self-contained `prepare` build allowed once — copy the pnpm key into the profile's `pnpm-workspace.yaml` under `allowBuilds` (see the [official publishing guide](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)) and re-run `add`. Only allow sources you trust.

Verify and boot:

```sh
dsh --profile <name> --dump-config   # shows the "# == dsh-blackjack" layer
dsh --profile <name>                 # web surface: dsh web / dsh --profile <name> web
```

After restarting `dsh web`, a 🃏 entry in the sidebar footer means the UI is live: the host layer shows in `--dump-config`, and the client module system automatically scans the `dsh.client` declaration and weaves the UI into the frontend boot graph (`__DSH_BOOT__`) — no extra configuration.

Configuration (override in your profile's `cordis.patch.yml`):

```yaml
- id: blackjack
  config:
    dealerPersona: 雌小鬼   # initial persona; the durable pick is per-session
    randomBanterChance: 0.3  # unsolicited taunt probability after a hit
```

## Gameplay

Standard Blackjack over one deterministic 52-card deck (seed stored in the `game-start` event): Aces 11/1, face cards 10, hit/stand, dealer draws to ≥17. Busts lose immediately; equal totals push.

## Repo layout

```
dsh-blackjack/
├── cordis.patch.yml            # bundle patch: mounts the `blackjack` host row
├── src/
│   ├── game/                   # pure rules engine (zero deps), bundled inline
│   ├── service/                # host plugin: @Remote verbs, fold, LLM dealer, banter
│   ├── client/                 # browser half: React 21 table (BlackjackPanel et al.)
│   ├── css-modules.d.ts        # CSS Modules type declarations
│   └── typert.remote-client.ts # `blackjack` Remote types + runtime contribution (self-mounted)
├── tests/                      # host unit tests (92)
├── tests-client/               # browser-half tests (44, jsdom + __ModuleLoader__ stub)
├── tsdown.config.ts            # host build: tsc (native decorators) → bundle → types
├── tsdown.client.config.ts     # browser-half build: closure-factory client bundle
├── tsdown.client.ts            # official client build preset (from the dsh base, CSS Modules inline)
├── web-platform.ts             # platform module table (shell-shared module list)
└── package.json                # dsh.bundle + dsh.client dual-face manifest + self-contained prepare build
```

Dev: `pnpm install`, `pnpm run build`, `pnpm test` (136 tests: 92 host + 44 UI). All `@deepseek-ai/*` deps are the **published** packages — no sibling monorepo checkout needed.

## License

[MIT](LICENSE)

Tag this repository with the [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic so dsh users can find it.