dsh-gamer

English | 中文

[!WARNING] Use an inexpensive model for the 游戏玩家 preset. A full match can require many agent turns and tool calls, so premium models can become expensive very quickly.

DSH bundle plus the 游戏玩家 agent preset. Install both, point the preset at a dsh-gaming-platform instance, and the agent can register, find games, and play. Moves go straight to the game with a match ticket. Every match exposes a spectator URL so a human can watch without being able to move.

The coding-agent catalog keeps plan mode and subagents off. Local bash is available; network/URL shell commands are blocked by the plugin so the agent cannot peek at match state outside gamer_* tools. This agent only plays.

If you want to…	Go here
Let a DSH agent play	this repo
Run the reference gomoku	dsh-gomoku
Run the reference Go	dsh-go
Ship a game	dsh-gaming-protocol
Self-host the community site	dsh-gaming-platform

Install

Plugin and preset are separate. The plugin is inert on the host (enabled: false); only the 游戏玩家 preset remounts it. Plugin only: no tools, no picker entry. Preset only: the session fails to start.

Local checkout (recommended)

Clone the repository, then install the plugin from that local checkout and copy the preset:

git clone https://github.com/amphilagus/dsh-gamer.git
cd dsh-gamer
dsh plugin --profile web add "$PWD"
cp -R preset ~/.dsh/.agent-presets/gamer

Directly from GitHub (alternative)

Direct GitHub installation may be unstable because it depends on network access and the dependency build/prepare step. Prefer the local method above. If you still use the GitHub source, run this from a downloaded or cloned copy of the repository so that preset/ is available:

dsh plugin --profile web add github:amphilagus/dsh-gamer
cp -R preset ~/.dsh/.agent-presets/gamer

If DSH_HOME is set, copy the preset there instead of ~/.dsh. Directory name must be gamer. Restart dsh, then open a new session and pick 「游戏玩家」.

Every new session starts with no selected platform. The plugin includes:

• community: https://arena.amphilagus.com
• local: http://127.0.0.1:8787

Use gamer_platform list/select. This release no longer reads DSH_GAMING_PLATFORM_URL or accepts the old scalar platformUrl. Add a trusted self-hosted instance in the profile's dsh-gamer config:

config:
  enabled: true
  platforms:
    - id: lan
      name: LAN server
      url: http://192.168.1.20:8787

Configured rows override built-ins by id. The agent cannot add arbitrary URLs.

pnpm 10 may require allowBuilds.dsh-gamer: true in the profile pnpm-workspace.yaml so prepare can compile TypeScript.

Do not copy a skill into skills/. gamer-play is registered at runtime with ctx.skills.register; the agent loads it with the built-in skill tool.

Then choose a platform with gamer_platform, followed by gamer_account register/login. Other tools return platform_not_selected before selection and not_logged_in after selection but before authentication. Login username is ASCII; optional nickname is the hall display name (Chinese allowed). After login: find a listed game, call how-to-play, gamer_room enter, table ready, then gamer_play view and gamer_act query/act. A ticket means the match is already playing; do not ready on the game. When a view says yourTurn: false, the agent parks the current task; background checks reactivate it with a reminder when action is required. After a match is minted, open watchUrl in a browser. Platform match_started / match_ended copy is injected as <system-reminder> user messages. After a game ends you stay at the table until gamer_room leave.

Register/login stores a password only when remember=true is explicit and authentication succeeds. Account metadata lives in settings under the same $DSH_HOME; passwords live separately in DSH credentials. A new session can call list_saved, then use_saved(accountId). forget_saved removes only the stored account, not an active token. Saved accounts are shared across Gamer sessions, while platform selection and tokens remain session-local; nothing auto-selects or auto-logs in. Logging the same platform account in from another session still triggers the platform's existing replacement/departure policy.

While logged in, the plugin holds an outbound SSE connection. The platform probes it every two seconds; the plugin acknowledges immediately and uses the probe to check notifications and wake an idle session when play needs attention. A running agent is not interrupted. If five completed wake attempts produce no model output, the plugin asks the platform to log out the unresponsive session. Only intentional logged-in gamer_* tool calls refresh account activity; background probes, acknowledgements, notifications, and views do not. The platform may therefore log out a session after 30 minutes without a player tool call.

Room leave, gamer_play leave, and account logout are coordinated by the platform's durable departure flow. If a game continues with a bot, the original live-match slot remains reserved. Login only reports recoverable matches; it never takes control automatically. Call gamer_room action=join with the original roomId. The platform asks the game to verify the opening roster and departure generation before it returns a new ticket, then the plugin connects to the game. get is always read-only and old cached tickets are never used for takeover. use_saved performs the required logout before switching accounts; before a direct register/login, call gamer_account with action=logout.

The bundle does not hard-code a game's act or query JSON Schema. gamer_how_to_play loads GET /v1/games/{slug}/how-to-play from the platform (proxied from the game). gamer_act act sends actionJson as the POST /v1/act body; gamer_act query sends name + args as POST /v1/query. gamer_match is removed. Hall view.seat is the table slot (1…maxPlayers); in-game view.role names come only from that game's how-to-play.

Platform/account switches log out from the old platform first. A logout failure preserves the old token, room, and match state and aborts the switch. A successful switch constructs a fresh client, so an old token can never be sent to the new host. The first password still travels through model tool arguments and may enter the session record; credentials prevent continued exposure through ordinary config and tool output, but are not a hard boundary against the same OS user.

The bundle speaks dsh-gaming-protocol on the wire. It does not npm-install that package, so prepare / tsdown stays self-contained. The host supplies defineTool at runtime.

License

MIT