The design philosophy of DSH (DeepSeek Harness) is “everything is a plugin,” which allows developers to flexibly extend functionality. In practical development, frequently starting Harness instances is a common operation. If the target port is already occupied, starting directly usually fails, requiring manual investigation of processes or shutting down old instances. Manually managing these environments is not only cumbersome but also error-prone.

Below is dsh-launch-in-one-click, a DSH plugin designed for Windows environments. It creates a self-contained .bat launcher on the desktop, resolving environment checks and port conflicts in the startup process.

Plugin Introduction

dsh-launch-in-one-click is a client plugin maintained by 233fxr-collab. Its core value lies in providing one-click startup capability, with a built-in port detection mechanism to prevent multiple Harness instances from starting when the port is already occupied.

  • License: MIT
  • Plugin Type: Client
  • Core Capabilities: Generates an independent launcher, checks the runtime environment, detects port occupation, and refuses conflicting starts.

Core Features

  1. Generate a Self-Contained Launcher: The plugin writes an independent .bat file to the desktop. This file contains all the logic required to start Harness and does not depend on the plugin itself.
  2. Environment Pre-check: Before the launcher runs, it automatically checks whether node and npx are available.
  3. Workspace Validation: Before startup, it checks whether the configured workspace exists.
  4. Port Detection and Conflict Prevention:
    • The launcher probes port status by binding to the target port and identifying the 401 fingerprint.
    • If the port is free, it starts Harness.
    • If the port is already occupied by Harness, it refuses to start and prompts you to use the URL of that instance.
    • If the port is occupied by another program, it refuses to start and reports the PID of the occupant.
  5. Language Switching: Supports switching the launcher language (--lang en/zh/auto).
  6. Standalone Operation: The generated launcher does not import this plugin. Even if the plugin is uninstalled, the .bat file on the desktop can still work independently.

Installation and Enablement

After installing the plugin, the plugin generates the launcher on load based on the configuration (under default settings).

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

After installation is complete, a .bat file generated by the plugin will appear on the desktop.

Typical Usage

The plugin provides command-line tools and slash commands.

Slash Commands

/launch                      # 使用默认部署设置安装并生成启动器
/launch doctor               # 运行诊断，检查环境、端口和启动器状态
/launch list                 # 列出桌面上所有由该插件生成的启动器及其设置
/launch --port 3111          # 在指定端口启动 Harness
/launch --lang zh            # 将生成的启动器语言设为中文（--lang en | auto）
/launch --name "Work.bat"    # 指定启动器的文件名
/launch --overwrite          # 强制覆盖一个非插件生成的启动器
/launch --dry-run            # 仅显示将要写入的内容，不实际执行

Tool Commands

launcher_doctor              # 诊断环境（Node, npx, 端口, 工作区等）
launcher_install             # 写入启动器（原子操作，包含自检）
launcher_uninstall           # 卸载启动器（仅限该插件生成的文件）

Launcher Parameters

The launcher itself also supports the following parameters:

--port N                     # 指定端口
--workdir DIR                # 指定工作目录
--no-open                    # 不自动打开浏览器
--silent                     # 无控制台窗口，输出到日志
--dry-run                    # 检查并显示计划，不启动
--help                       # 显示帮助信息

Notes and Limitations

  • Independence: The launcher is self-contained. Uninstalling the plugin does not delete the desktop .bat file, and the file can still run normally.
  • Automatic Updates: The launcher records the version of the plugin that generated it. If a new plugin version is loaded and autoUpdate: true is configured, it automatically updates the file on the desktop.
  • Safe Rewriting: If /launch or launcher_install is explicitly executed, the launcher rewrites the file. If writing fails (self-check does not pass), it rolls back instead of leaving a corrupted file.
  • Log Location: The launcher’s runtime logs are saved in %LOCALAPPDATA%\dsh-launch\launcher.log. In --silent mode, all output is also written to this log.
  • Exit Code Conventions: The launcher’s exit codes follow conventions to facilitate scripting:
    • 0: Normal run or dry-run success
    • 1: Missing node or npx
    • 2: Port is occupied by Harness
    • 3: Port is occupied by another program
    • 4: Invalid arguments
    • 5: Workspace does not exist
    • 9: Port detection failed
    • 20: Harness run failed
  • Configuration Cost: Adding a config line to a bundle patch increases cost; configuration is activated only after a restart.
  • Silent Loading: Set provisionOnLoad: false to allow the plugin to load silently without automatically generating the launcher.

Conclusion

dsh-launch-in-one-click simplifies the Harness startup process by encapsulating the startup logic into a desktop script. It ensures the uniqueness of port usage and guarantees the independence and persistence of the tool through a self-contained .bat file.

  • Plugin directory: [catalog_url]
  • Source address: [github_url]