Introduction¶

In the DSH web GUI, some common operations originally required repeated mouse clicks: focusing input boxes, creating new sessions, toggling the sidebar, toggling the detail panel, scrolling the conversation, and toggling themes. @blue-a11y/dsh-client-shortcuts registers these browser-side UI actions as global keyboard shortcuts and provides a settings page for viewing, recording, resetting, and validating key combinations.

The following sections introduce its positioning, core features, installation methods, typical usage, development and building, and notes.

What is it¶

@blue-a11y/dsh-client-shortcuts is a web GUI plugin for DeepSeek Harness maintained by blue-a11y, licensed under the MIT license. It is a browser-side UI plugin; node half is specifically designed to be empty, and the entire functionality runs on the browser side.

It provides the ShortcutRegistry service, i.e., ctx.shortcuts. This service attaches a keydown listener in the capture phase to window and dispatches registered key combinations.

It also provides a settings page:
- Registered under settings.section;
- Built based on @deepseek-ai/dsh-client-ui-primitives;
- Lists all bindable actions;
- Supports recording key combinations, resetting key bindings, conflict detection, and intercepting reserved combinations.

This package declares dsh.bundle, which is a composite package. In package.json, dsh.bundle.patch points to ./cordis.patch.yml, and it activates its configuration layer upon installation.

This plugin only forwards browser keyboard gestures to UI actions and does not interact with any model requests.

Core Features¶

Global Shortcut Registration¶

The core service is ShortcutRegistry, i.e., ctx.shortcuts. It is responsible for:
- Listening to keydown in the capture phase on window;
- Parsing and matching registered key combinations;
- Dispatching to the corresponding UI actions;
- Providing the ability to unbind actions.

mod matches Cmd on macOS and Ctrl on other platforms. The documentation and UI write combination keys in a cmd-friendly format; for example, cmd and mod are correspondingly handled in combination key expressions by convention.

Text Input Protection¶

By default, keyboard events are allowed when focus is inside a text input box to avoid affecting normal input.

If a binding explicitly declares availability within the input box, it will only respond there.

Bindable Actions¶

The plugin lists all bindable actions, including:
- Focus input box;
- New session;
- Toggle sidebar;
- Toggle detail panel;
- Previous session;
- Next session;
- Toggle light/dark theme;
- Scroll to conversation top;
- Scroll to conversation bottom;
- Fork current session.

Among these, actions without safe default values are not bound by default. Users can record key combinations on the settings page to enable them, or reset them to an unbound state.

Session Switching Order¶

Session switching mirrors the full display order of the sidebar, skipping “New Task” blank entries and archived sessions, and cycling between the ends. In other words, when switching from the last session, it returns to the first available session, and when switching from the first session, it returns to the last available session.

Key Rebinding and Conflict Detection¶

The settings page supports:
- Recording new key combinations;
- Resetting to unbound;
- Validating against existing bindings;
- Rejecting browser reserved combinations;
- Rejecting macOS Option/Alt rewrite combinations.

Browser reserved key combinations are consumed by the browser before the page listener executes preventDefault, so web plugins cannot bind them. macOS’s Option/Alt rewrite combinations may cause event.key to no longer match the registered key; therefore, the settings page will reject such combinations.

Key Rebinding Lifecycle¶

Key rebinding is only valid within the plugin fiber lifecycle. After refreshing the page, it reverts to the default state; currently, user key rebinding results are not persisted.

Installation and Enablement¶

Prerequisites¶

First, install the dsh CLI:

npm i -g @deepseek-ai/dsh

Then ensure the runtime environment meets:
- Node 22.19 or higher;
- pnpm available.

Installation from npm¶

It is recommended to install from npm:

dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts

This package is a composite package, and it activates its configuration layer upon installation.

Installation from Local Checkout¶

During development, you can install a local directory:

dsh plugin --profile web add ./dsh-client-shortcuts

Installation from Bundled Artifact¶

If you have a bundled artifact, you can also use a tarball:

dsh plugin --profile web add ./dsh-client-shortcuts-0.1.0.tgz

Restart and Verification¶

After adding a new plugin line, you need to restart dsh web once because the plugin line is found in the cache at every startup.

First, view the configuration:

dsh --profile web --dump-config

In the configuration, you should be able to see the id: shortcuts line.

Then start the web GUI:

dsh web

After the browser opens, go to “Settings -> Shortcuts”, and you should see the shortcuts settings page.

Update and Uninstall¶

When updating, re-run the install command:

dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts

If you need to lock the version, you need to specify the version number.

Uninstall command:

dsh plugin --profile web remove @blue-a11y/dsh-client-shortcuts

Uninstall will also remove related dependencies and the configuration layer.

pnpm Build Authorization¶

If using pnpm 10 or higher, you may need to authorize the profile once in the allowBuilds section of pnpm-workspace.yaml.

Typical Usage¶

Opening the Settings Page¶

After starting dsh web, enter in the browser:

Settings -> Shortcuts

The settings page lists all bindable actions and displays current key combinations and trigger counts.

Recording Key Combinations¶

For actions that are unbound by default, you can use the recording control on the settings page to press the key combination you want to bind.

The recording control pauses the registry dispatch, and the pressed combination is captured rather than triggering directly. The settings page will validate if the combination conflicts with existing bindings and reject illegal or reserved combinations.

Resetting Key Combinations¶

If an action no longer needs custom key bindings, you can reset it to clear it back to the unbound state.

Session Switching¶

After binding the session switching action, the shortcut key will move according to the full display order of the sidebar, skipping “New Task” blank entries and archived sessions, and cycling between the first and last.

Not Touching Model Requests¶

These shortcuts are only used for UI operations within the browser. The plugin will not initiate model requests, nor will it change the model invocation path.

Development and Build¶

Clone Repository¶

git clone https://github.com/blue-a11y/dsh-client-shortcuts.git
cd dsh-client-shortcuts
pnpm install

Common Commands¶

pnpm install
pnpm run build
pnpm test

pnpm run build generates build artifacts, and pnpm test runs tests.

Local Hot Module Replacement¶

During local development, you can first install the local directory:

dsh plugin --profile web add ./dsh-client-shortcuts

After modifying source code and rebuilding, the client HMR link can automatically replace the module. Only when adding or removing plugin lines, do you need to restart dsh web.

Dependencies¶

The package’s peer dependencies include:

@deepseek-ai/cordis ^4.0.1
@deepseek-ai/dsh-invariants ^0.1.0-rc.6

Scenarios and Notes¶

Who is it suitable for¶

Suitable for developers using dsh web and wanting to reduce mouse operations, especially:
- Need to frequently focus input boxes;
- Need to quickly create new sessions;
- Need to frequently toggle the sidebar or detail panel;
- Need to quickly move between multiple sessions;
- Need to quickly scroll to the conversation top or bottom;
- Need to perform lightweight customization of browser UI actions.

It is suitable to place in DSH’s plugin workflow as a keyboard enhancement plugin for the web GUI. The plugin introduced here comes from an independent community directory, not from the DeepSeek or Huanquan official app store.

Security Notes¶

This plugin joins the current dsh web profile configuration layer and loads and runs with the current dsh process. Source code, license, and dependencies should be checked before installation.

The plugin license is MIT. It only handles browser keyboard events and UI actions and does not interact with model requests, but any third-party plugin should confirm its source and build artifacts before use.

Behavioral Boundaries¶

Note the following boundaries:
- Key rebinding is not persisted; it reverts to default after refreshing the page;
- Keyboard events are allowed by default when focus is inside an input box, unless the binding explicitly declares availability within the input box;
- Browser reserved combinations cannot be bound by web plugins;
- macOS’s Option/Alt rewrite combinations will be rejected by the settings page;
- Focusing input boxes relies on [data-phase] DOM queries because the current composer does not expose a focus service;
- A restart of dsh web is required after adding a new plugin line.

Conclusion¶

The value of @blue-a11y/dsh-client-shortcuts is relatively concentrated: it provides a set of bindable UI shortcuts for dsh web and provides a settings page that is recordable, resettable, and verifiable. It does not change the model request chain; it only optimizes the operation path within the browser.

Repository address:

https://github.com/blue-a11y/dsh-client-shortcuts

@blue-a11y/dsh-client-shortcuts: Global shortcut plugin for the dsh web GUI