Preface¶

When running tasks with DSH, there is a period of downtime: the model is thinking and reasoning, and there is nothing else to do on the Web GUI, so you can only wait. dsh-xiangqi utilizes this downtime—a cartoon pet holding an ‘Elephant’ (Xiang) piece hovers over the DSH Web GUI, inviting you to play a few moves of Chinese Chess during the AI’s thinking gaps.

The game is purely leisurely human-machine play, completely independent of dialogue agents, and does not block the main loop. Below is an introduction to this plugin’s functions, installation methods, and usage notes.

What is this¶

dsh-xiangqi is developed by ovdoesw, open-sourced under the MIT license, current version 0.1.0. One-sentence positioning: A DSH Web Client plugin, a leisure pet that plays Chinese Chess while the AI is thinking, featuring a self-written engine and offline lines, with optional LLM commentary.

First, two basic attributes:

1. Completely playable offline. The local rule engine handles moves and lines, relying on no online services; LLM commentary is just a bonus, not using it won’t affect the game.
2. It is a Cordis client plugin package with dsh.client.platform set to web, peer dependency @deepseek-ai/cordis >=0.1.0 and react >=17.

Core Features¶

Features revolve around “a pet + a chessboard”:

• Floating Pet: Draggable and persistent position; pieces rise on hover, popping up random invitation bubbles.
• Small Panel Board: Click the pet to expand, supporting piece selection, difficulty switching, new game, undo, commentary, and fullscreen.
• Fullscreen Board: Amplify to fullscreen for play, press Esc to close; the background remains click-through, not affecting the operations of the underlying application.
• Local Lines: Opening names (Red Cannon / Guide Horse / Screen Horse / Smooth Cannon / Column Cannon) and Three Kingdoms Kill style kill, check, and checkmate lines. All offline and immediate.
• State Persistence: Game progress, difficulty, pet position, and settings are saved in the browser; refreshing won’t lose them.

Built-in Engine and Difficulty Levels¶

The engine is a pure TypeScript implementation by the author: negamax + α-β pruning + iterative deepening, executed asynchronously via sharding to avoid blocking the main thread. Difficulty is divided into three levels:

Something to be honest about: the author describes themselves as a beginner in chess, so the built-in engine is “comparatively weak,” just a simplified search combined with simple piece/position evaluation. See the “Typical Usage” section below for the corresponding solutions.

LLM Commentary (Optional)¶

• Default reuses the LLM service configured in DSH (ctx.llm);
• When a specific model is needed, fill in base / key / model in the plugin settings to connect directly to the OpenAI compatible /chat/completions endpoint;
• Supports automatic commentary per move and a manual commentary button, with a style switchable between “Professional Chess Commentary” and “Streamer Entertainment.”

All LLM failures will silently fall back to null, not interrupting or obscuring the game; when the network is down, the local lines still provide a complete experience.

Installation and Enabling¶

The plugin is installed by building from source. First, clone the repository, install dependencies, and then build the artifacts:

git clone https://github.com/ovdoesw/dsh-xiangqi.git
cd dsh-xiangqi
npm install
npm run build

npm run build produces lib/client.js and lib/index.js. See INTEGRATION.md in the repository for mounting methods, which includes cordis.patch.yml configuration and the dsh plugin command; for local development, you can use link: to point to the current directory.

After mounting via the steps above, it is recommended to run the core layer and AI layer unit tests in a pure Node environment first to confirm the build is normal—this step does not require the DSH frontend environment:

npm test          # node --import tsx --test test/*.test.ts
npm run typecheck # tsc --noEmit

npm run typecheck requires the DSH runtime types if needed; they must be loaded into DSH or the peer dependencies installed beforehand.

Typical Usage¶

Daily Play: Click the pet to expand the small panel, select pieces to move, switch difficulty, start a new game, or undo at any time. If you want to see more clearly, amplify to fullscreen and press Esc to close. The fullscreen background remains click-through, not occupying the underlying application.

Configuring Commentary: By default, nothing needs to be filled in; the plugin directly reuses DSH’s LLM service. If you want to change the model, fill in base / key / model in the plugin settings. Choose one style: “Professional Chess Commentary” or “Streamer Entertainment.”

Letting the Agent Tune the Engine Strength: When you feel the opponent is too weak, you can directly let the current AI Agent in DSH modify the engine. To make it stronger, increase the search depth of hard (modify maxDepth in src/ai/search.ts or the time limit in src/ai/engine.ts), or strengthen the evaluation function in src/ai/evaluate.ts. To make it more casual, increase the random perturbation of easy or reduce the search depth. The example command given in the README is “Help me make the hard difficulty stronger, don’t just respond randomly within 5 seconds.” After the Agent modifies it, run npm run build to repackage for immediate effect.

Scenarios and Notes¶

Suitable for two types of people: those who frequently wait for long tasks in the DSH Web GUI and want to find something to do; and those who want to assign an AI Agent a “visible, editable” small project—this pure TypeScript engine has zero dependencies and is suitable for letting the Agent modify it locally.

A few things to know before installation:

1. The plugin runs with the current dsh process permissions; source code and license should be checked before installation. This project is under the MIT license, and the source code is public on GitHub.
2. Long check / Long capture is a simplified arbitration: the side that makes the third occurrence of the same position loses. Full Asian rule arbitration is not within the scope of v1.
3. Kill lines are presented in text; there is currently no audio broadcast.
4. LLM commentary depends on the network and tokens; failures will silently fall back and will not affect the game itself.
5. The project explicitly does not include: online play, external UCI engines (e.g., Stockfish), or opening library deep learning.

Summary¶

dsh-xiangqi does not solve productivity problems; it solves how to kill waiting time: a local solution, playable offline, and if you aren’t satisfied with the engine strength, the Agent can modify it on the spot. The layered structure of core/ai/client plus the unit test structure using node –test also has reference value for developers who want to write DSH plugins.

Project source code: https://github.com/ovdoesw/dsh-xiangqi
Community directory entry: https://www.skillhub.cn/plugins/ovdoesw/dsh-xiangqi (This directory is an independent community site and has no official affiliation with DeepSeek / HF)