dsh-Launch in One Click

English | 中文

Switch the generated launcher's language at any time — /launch --lang zh, /launch --lang en, or /launch --lang auto to follow the console.

A DeepSeek Harness plugin for Windows that writes a self-contained one-click launcher — a .bat on your Desktop — and refuses to start a second Harness instance when the port already serves one.

The launcher it writes does not import this plugin. Uninstall the plugin and the .bat on your Desktop keeps working; it is a single file with everything it needs already inside it.

What it does

Installing it puts the launcher on your Desktop

A marketplace hot-mounts a plugin whose bundle patch is a plain insert, so this one goes live the moment you click Install — and that is when the launcher appears. It is created only when your Desktop has none: an existing launcher, yours or an older one of ours, is left exactly as it is, because a plugin load is not a decision by you. Replacing one stays an explicit action (/launch, or the launcher_install tool). Set provisionOnLoad: false to have the plugin load silently instead.

What the install does

launcher_install resolves your Desktop the way Windows defines it (including a OneDrive-redirected or localized Desktop folder), checks that the folder accepts a new file, encodes the launcher for your console's code page, writes it atomically, and then runs it once in dry-run mode to prove it parses and reaches its own logic. A launcher that fails that self-test is rolled back, not left on your Desktop.

The generated launcher then does the following every time it is double-clicked:

1. Checks that node runs and that the runner (npx or dsh) answers.
2. Checks that the configured workspace still exists and enters it.
3. Probes the port by binding it, then fingerprints whatever already answers:
   • free — starts the harness;
   • serves a Harness instance — refuses, and tells you to use that instance's own URL;
   • held by anything else — refuses, and reports the owning PID;
   • probe failed — refuses rather than guessing.

Only the first case starts anything. There is no flag that starts a second instance.

Why the port check is not just a courtesy

dsh web mints a per-process launch token and prints an authenticated URL carrying it; the server answers every unauthenticated request with 401 dsh web authentication required. So opening a bare http://127.0.0.1:3080 while an instance is running shows a 401 page, not your session — and starting a second instance fails on the bind anyway. A launcher therefore has exactly two honest options when the port is busy, and this one takes the second: say which URL to use, and start nothing.

The fingerprint is the 401 body itself, so "a Harness instance" is detected rather than assumed — a different program holding the port is reported as a different program, with its PID.

Install

dsh plugin --profile web add dsh-launch-in-one-click

Or straight from the repository:

dsh plugin --profile web add github:233fxr-collab/dsh-launch-in-one-click

Remove the row from your profile to uninstall it. Existing launchers keep working — they are self-contained.

Use

Three tools, plus a slash command.

Tool	Effect
launcher_doctor	Read-only. Reports Node, npx, the console code page, the resolved Desktop, whether it is writable, what holds the target port, and the state of any launcher already installed. Optionally runs an installed launcher in dry-run mode.
launcher_install	Writes the launcher (atomic, backed up, self-tested).
launcher_uninstall	Deletes a launcher this plugin wrote. Refuses a file it did not write unless force is set.

/launch                      install with the deployment defaults
/launch doctor               same report as launcher_doctor
/launch --port 3111          start the harness on another port
/launch --lang zh            write the launcher in Chinese  (--lang en | --lang auto)
/launch --name "Work.bat"    choose the file name
/launch --overwrite          replace a file this plugin did not write
/launch --dry-run            show what would be written

--language is the long form of --lang. Switching language rewrites the launcher this plugin wrote, keeping a timestamped backup, and changes nothing else about it: the port, the workspace, and the runner stay as they were.

The launcher itself accepts --port N, --workdir DIR, --no-open, --dry-run, and --help.

Exit codes

The launcher's exit code is its contract, so a shortcut wrapper or a scheduled task can branch on it without parsing localized text.

Code	Meaning
0	the harness ran and exited cleanly, or a dry run printed its plan
1	node or the runner is missing
2	the port already serves a Harness instance — nothing was started
3	another program holds the port — nothing was started
4	an argument was invalid
5	the work directory is missing or cannot be entered
9	the port probe could not reach a verdict
20	the harness itself failed; its own exit code is printed above

Configuration

Optional, in the bundle's patch row:

- id: launch-in-one-click
  name: dsh-launch-in-one-click
  config:
    defaultPort: 3080                # port a generated launcher targets
    language: auto                   # auto | en | zh
    runner: npx                      # npx | dsh
    packageSpec: '@deepseek-ai/dsh'  # what npx resolves
    openBrowser: true                # let `dsh web` open the browser
    provisionOnLoad: true            # create the launcher on load, if absent

⚠️ Adding a config: row here has a cost. A marketplace hot-mounts only a plain id/name insert, so a bundle patch carrying configuration activates on the next restart instead of immediately. That is why every default above lives in code, not in this file: install with no patch row at all, and the launcher still appears the moment you click Install.

Edge cases it handles

• Redirected or localized Desktop — resolved through the shell known-folder API, then both registry keys, then %USERPROFILE%\Desktop. A source pointing at a folder that does not exist is skipped rather than trusted.
• Console code pages — the launcher targets the system OEM code page, which is the one a freshly started console has and therefore the one a double-clicked batch file is read in. That is deliberately not the code page of the process that installs it: installing from a UTF-8 terminal on a Chinese Windows produced an English UTF-8 launcher, measured while building this. The installing console's code page is used only when the registry cannot be read, and the doctor reports both. The file switches the console to its own code page before its first non-ASCII byte. Verified on Windows 11: a console reporting code page 936 still reads a batch file as UTF-8 until the file tells it otherwise.
• Language — auto (the default) follows the console: a Chinese-capable code page gets Chinese, an English one gets English with no warning, because matching the console is the point rather than a fallback. An explicit language: zh is honoured even on a console that cannot print it, by writing the file in UTF-8 and switching the console to match.
• Double-byte trail bytes — in GBK and its relatives the second byte of a character can be |, &, <, >, ^, %, (, ), or ". cmd.exe does not know the pair is one character and starts a pipe, a redirect, or a variable expansion. Every file is scanned for this before it is written.
• A path the code page cannot carry — a Chinese profile directory on an English console, for example. English does not fix a path, so the launcher switches itself to UTF-8 instead of failing.
• Files this plugin did not write — refused, and left untouched. With overwrite, replaced with a timestamped backup.
• Timestamp-only changes — an identical launcher is left alone instead of being rewritten under the user; force refreshes it.
• Transient rename failures — MoveFileEx fails with EPERM while an indexer or antivirus holds the destination open, so the rename is retried with backoff.
• A double-clicked window — failures pause so the message can be read; a scripted caller sees no prompt, because the pause happens only when cmd was started to run that very file.
• npx versus npx.cmd — Node ships an extensionless POSIX shim beside npx.cmd. PATH resolution tries PATHEXT candidates first, so the shim cmd cannot run never wins.

Development

npm install --legacy-peer-deps   # iconv-lite; the rest are peer dependencies
npm test

The suite is 90 tests. The interesting ones generate a launcher and run it with real cmd.exe against real listeners — a fake Harness server that answers the 401 fingerprint, an unrelated HTTP server, and a free port — then assert the exit codes. That is what caught the two defects unit tests could not: a file written with bare LF endings (cmd reads it as one enormous line) and a code page switch placed after the first multi-byte character.

test/plugin.test.js checks the manifest contract a plugin marketplace verifies, including the peer range. That range is deliberately long:

>=0.0.1-rc.1 <0.2.0-0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.1-rc.1 <0.2.0-0 ||
>=0.1.2-alpha.1 <0.2.0-0 || >=0.1.3-alpha.1 <0.2.0-0 || >=0.1.5-alpha.1 <0.2.0-0

node-semver only lets a prerelease satisfy a range when some comparator carries that exact major.minor.patch tuple and a prerelease tag. A range that looks generous — >=0.0.1-rc.1 <0.2.0, or even >=0.0.0-0 — therefore excludes every published 0.1.x prerelease, and users hit an ERESOLVE they have to work around by hand. The enumerated form admits each published line; a test asserts that the tuple of the harness installed here is one of them.

When the harness packages resolve, the same file validates every tool schema against the real defineTool compiler; otherwise it reports the skip.

Requirements

• Windows 10 or 11.
• Node 20+ for the plugin; the harness itself targets Node 22.
• npx (with Node) for the default runner, or an installed dsh command if you set runner: dsh.

License

MIT