deepseek-harness-shortcut

Readme

# deepseek-harness-shortcut

English | [中文](README.zh.md)

<p align="center">
  <img src="assets/icon.jpg" alt="DeepSeek Harness shortcut icon" width="128">
</p>

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that creates a **desktop shortcut to start or open your local DSH web UI with one click** (Windows).

The shortcut icon: [assets/icon.jpg](assets/icon.jpg) · [assets/icon.ico](assets/icon.ico)

Double-clicking the shortcut:

- if the DSH service is **already running** → opens the browser directly;
- if it is **not running** → starts it (`npx --yes @deepseek-ai/dsh web` by default), waits until port 3080 answers, then opens the browser.

## Features

- ✅ One command: `/desktop-shortcut`
- ✅ Smart launcher script (start-vs-open, wait-for-ready, up to 30s)
- ✅ Customizable: shortcut name, URL, port, icon, working directory, start command
- ✅ Zero runtime dependencies (Node ≥ 18 built-ins only)
- ✅ Ships as a DSH **bundle**: installing the package auto-activates it in the profile

## Install

### From GitHub

```sh
dsh plugin --profile web add github:Ho11ow8/deepseek-harness-shortcut
```

### From a local checkout

```sh
dsh plugin --profile web add file:D:\DeepseekHarness\deepseek-harness-shortcut
```

Then restart `dsh web`. In the chat, run:

```
/desktop-shortcut
```

A `start-dsh.bat` launcher is written to your workspace and a `DeepSeek Harness.lnk` shortcut appears on your desktop.

> Bundle activation is automatic: `dsh plugin` appends any dependency that declares `dsh.bundle` to the profile's `dsh.profile.bundles` layer stack. (See `dsh --help` / `dsh plugin --help`.)

## What it generates

The plugin does not ship a pre-built launcher — running `/desktop-shortcut` generates the files on your machine:

| Generated file | Location | Purpose |
|---|---|---|
| `start-dsh.bat` | your workspace (or `launcherDir`) | Smart launcher: checks port 3080 → opens the browser if the service is already running, otherwise starts it and waits until ready |
| `DeepSeek Harness.lnk` | your desktop | Shortcut that runs `start-dsh.bat` when double-clicked |

Icon resolution (first match wins):

1. `iconPath` from your config, if set;
2. the first `.ico`/`.png` found in `launcherDir`;
3. the plugin's bundled `assets/icon.ico` (shipped with the package) — so every user gets a nice icon even without their own.

Re-run `/desktop-shortcut` any time to refresh the shortcut (e.g. after changing the config or the icon).

## Slow startup? Switch to a China npm mirror

The launcher starts the service with `npx --yes @deepseek-ai/dsh web`. On every launch, npx
contacts the npm registry to resolve the `@deepseek-ai/dsh` version. When your access to
`registry.npmjs.org` is slow or unstable (common in China), this step can take several
seconds — or much longer when the connection is reset and npm retries with backoff.

Point npm at a China-based mirror (npmmirror.com — Alibaba's sync of the official registry):

```sh
npm config set registry https://registry.npmmirror.com
```

This writes `registry=https://registry.npmmirror.com` to your **user-level** `.npmrc`
(`C:\Users\<you>\.npmrc` on Windows), so all npm/npx commands you run use the mirror.
Verify with `npm config get registry`.

- Package contents are identical — npmmirror mirrors the official registry; your local npm cache stays valid.
- New releases can lag the official registry by a few minutes to hours.
- Revert with: `npm config set registry https://registry.npmjs.org/`.

> The mirror only speeds up the npx network step before DSH boots. Once the service is
> running, the browser loads everything from `127.0.0.1:3080`, which has nothing to do
> with the registry.

## Configuration

Override any key through a later patch row in the profile's `cordis.patch.yml`:

```yaml
- id: desktop-shortcut
  config:
    shortcutName: My Harness
    url: 'http://127.0.0.1:8080'
    port: 8080
    iconPath: 'C:\icons\my.ico'
    launcherDir: 'D:\launchers'
    workdir: 'D:\DeepseekHarness'
    command: 'npx --yes @deepseek-ai/dsh web'
    waitSeconds: 45
```

| Key | Default | Meaning |
|---|---|---|
| `shortcutName` | `DeepSeek Harness` | Shortcut file name (no extension) |
| `url` | `http://127.0.0.1:3080` | URL the launcher opens |
| `port` | `3080` | Port probed to decide start-vs-open |
| `iconPath` | `""` | `.ico`/`.exe`/`.dll` icon for the shortcut (falls back to first `.ico`/`.png` in `launcherDir`) |
| `launcherDir` | workspace | Directory for the generated `start-dsh.bat` |
| `workdir` | launcher dir | Working directory used by the launcher |
| `command` | `npx --yes @deepseek-ai/dsh web` | Command that starts the service |
| `waitSeconds` | `30` | Max seconds to wait for the service |

### Changing the icon

Two ways to use your own icon:

**Option A — drop the icon into your workspace (easiest)**

1. Copy your icon (`.ico` or `.png`) into the workspace (the directory where you run `dsh web`, e.g. `D:\DeepseekHarness`);
2. Re-run the command:

```
/desktop-shortcut
```

The plugin picks up the first `.ico`/`.png` found in the workspace. If several icons exist, remove the old ones or make sure yours sorts first.

**Option B — pin an exact path with `iconPath`**

Set `iconPath` in the plugin config:

```yaml
- id: desktop-shortcut
  config:
    iconPath: 'D:\my-icons\my-custom.ico'
```

Then restart `dsh web` and re-run `/desktop-shortcut`.

> If the desktop still shows the old icon after changing it, refresh the desktop (press **F5**) or right-click the desktop → Refresh — Windows caches icons. `.ico` is recommended for crisp rendering at all sizes.

## License

MIT