Lheyang/orca-dsh-launcher

🐋 Orca DSH Launcher

🌏 English | 中文

A Cordis plugin + native desktop app for DeepSeek Harness (DSH) that provides update checking, server start/stop, a system tray icon, a graphical console, and one-click installation.

Implementation: since v2.0.0 the desktop side is native executables built with C# / .NET 8 (WPF + WinForms), instead of PowerShell / VBScript. Startup and status polling are faster, and it is no longer affected by PowerShell execution-policy or script-encoding (BOM/GBK) differences.

Features

• Update check: on DSH startup, compares the local git commit against the official master branch; logs a message + notification when an update exists. Query only — never auto-updates, never touches DSH source.
• /orca command set: 15 subcommands covering status / start / stop / restart / open / logs / port / config / diagnostics / console / tray / setup.
• System tray: WinForms NotifyIcon — left-click opens the DSH UI; right-click menu starts/stops the server, opens the console, checks for updates.
• Graphical console: WPF window (Overview / Server / Install / Logs / Settings / About), dark & light themes plus 6 accent colors; opens even when DSH is not running.
• One-click install: the console "Install" page or the standalone wizard orca-setup.exe (self-contained single file) supports two paths —
  • Full version: git clone + pnpm install + pnpm run build + pnpm dsh web;
  • Official Web version: npx @deepseek-ai/dsh web (Node.js only).
• Automatic rebuild guard: DSH is a source checkout, so a git pull without a rebuild breaks startup. Both the "start" and "update" paths run a build check first (rebuild only when HEAD changed or one of 6 key artifacts is missing).
• Port ownership detection: only stops the process when it is really DSH — never kills unrelated Node processes.
• Billing badge: a peak/off-peak DeepSeek pricing chip in the DSH chat header (Beijing time; peak 09:00-12:00 and 14:00-18:00 costs about 2x off-peak).

Installation

Try DSH quickly (official Web version, no plugin needed)

npx @deepseek-ai/dsh web

Fresh machine: install DSH + this plugin in one click

Download orca-setup.exe from GitHub Releases and double-click it. It is a self-contained single file with the plugin package embedded — nothing needs to be pre-installed (not even .NET).

Existing DSH: install the plugin from source

:: In the repository root:
install.cmd
:: Then restart DSH

What it does: builds the C# solution → assembles the plugin package → copies it to ~/.dsh/profiles/web/node_modules/orca-dsh-launcher/ → registers it in cordis.patch.yml (UTF-8 without BOM) → backs up and removes v1.x PowerShell assets → creates the startup tray shortcut and the desktop icon (skip with --skip-startup / --skip-desktop).

Building requires the .NET 8 SDK; day-to-day use only needs the .NET 8 Desktop Runtime (or just use the self-contained orca-setup.exe).

Uninstall: uninstall.cmd (automatic backup; --kill-tray also closes the tray, --keep-shortcut keeps shortcuts).

Usage

/orca commands

plugin.js forwards the subcommand to bin\orca-cli.exe; the handler returns { kind: 'success' | 'error', text }. Configuration is re-read on every call, so console changes take effect immediately.

Command line (works without DSH)

bin\orca-cli.exe run status         :: any /orca subcommand
bin\orca-cli.exe quick-check        :: status as JSON (for scripts / monitoring)
bin\orca-cli.exe selftest           :: 9 built-in checks
bin\orca.exe --console              :: graphical console
bin\orca.exe --tray                 :: system tray
bin\orca.exe --setup                :: installation wizard
bin\orca.exe --start-server         :: start the DSH server silently (autostart entry)

Configuration

~/.dsh/orca-dsh-launcher.json (UTF-8 without BOM, shared by the tray, console and plugin; created with defaults on first run):

Extra fields you add by hand are preserved when settings are saved.

User data (do not delete): orca-dsh-launcher.json, orca-stats.json (usage stats, atomic writes), orca-dsh-server.log (rotated above 2 MB), update-check-state.json, orca-dsh-last-build.json, orca-backup/ (automatic install/uninstall backups).

Architecture

plugin.js                DSH plugin entry (thin shell: registers /orca, forwards to orca-cli.exe)
lib/client.js            DSH chat client plugin (peak/off-peak billing chip)
src/
├── Orca.Core/           Shared logic: config / server control / port ownership / build check /
│                        update check / stats / shortcuts / installer / theming / custom dialog
├── Orca.App/            orca.exe — one program, four modes:
│                        --console (WPF console, 6 pages)
│                        --tray    (WinForms NotifyIcon)
│                        --setup   (WPF wizard, 6 steps)
│                        --start-server (silent server start)
├── Orca.Cli/            orca-cli.exe — all /orca subcommands + install/uninstall/selftest
└── Orca.Package.proj    packaging: plugin package → payload.zip → single-file orca-setup.exe
build.cmd test.cmd install.cmd uninstall.cmd publish.cmd

Technical highlights

• One exe, several modes: orca.exe is a WinExe, so there is no console window and no need for wscript + .vbs wrappers — shortcuts simply pass an argument.
• Port ownership: GetExtendedTcpTable for the listening PID, then the target process PEB for its command line (microseconds, no WMI), matched against pnpm|dsh|deepseek|harness|tsx.
• Detached stop/restart: orca-cli.exe is a child of the DSH server process, so killing the process tree directly would kill itself; instead it schedules a background command chain (wait → taskkill → start) and exits first.
• Installer payload: the plugin package is zipped and embedded as a resource inside the self-contained orca-setup.exe, extracted to a temp folder at runtime (offline install works).
• Responsive UI: every long-running operation runs on a background thread; the UI refreshes through a DispatcherTimer.
• v1.x compatible: mutex and signal names are unchanged, so old and new versions never produce two trays and can close each other gracefully.

Development

Requirements: Windows 10/11, .NET 8 SDK, Node.js (for the plugin load test).

build.cmd      :: build
test.cmd       :: full test suite (build + 9 selftests + plugin.js load + quick-check + real Cordis load)
install.cmd    :: sync into the DSH runtime (with backup)
publish.cmd    :: build the distributable (dist\orca-setup.exe)

Project version vs runtime version: the repository is the source of truth; ~/.dsh/profiles/web/node_modules/orca-dsh-launcher/ is what DSH actually loads. Always run install.cmd after changes — never edit the installed copy directly. See CONTRIBUTING.md.

FAQ

What is Orca DSH Launcher? A Windows desktop companion and Cordis plugin for DeepSeek Harness (DSH, DeepSeek's open-source AI agent harness): update checks, server control, system tray, graphical console, one-click installation.

Why was it rewritten in C# for v2.0.0? The desktop side used to be PowerShell scripts: restricted by execution policy, sensitive to script encoding (BOM/GBK), prone to UI stalls while querying status, and awkward to ship as a real executable. C# / .NET 8 gives compiled native programs — fast startup, smooth UI, simple distribution — with feature parity.

Does it auto-update DSH? No. It only checks and notifies. It never auto-updates and never modifies DSH source files.

Which platforms are supported? Windows 10 / 11. Regular use needs the .NET 8 Desktop Runtime (bundled inside orca-setup.exe); DSH itself needs Node.js and git.

Do I need DSH installed first? For the plugin, yes. On a brand-new machine, orca-setup.exe installs DSH and the plugin for you.

What about port conflicts? Port usage is checked before starting; non-DSH processes are never killed, and the owner is reported explicitly.

Will upgrading to v2.0.0 lose my settings? No. Config, stats, logs and update state keep the same file names under ~/.dsh/; old PowerShell assets are backed up to ~/.dsh/orca-backup/ before removal.

Changelog

CHANGELOG.md

For LLMs / crawlers

Machine-readable project descriptions: llms.txt (summary) and llms-full.txt (full text), kept in sync with this README.

License

MIT

---

About the orca: orcas are smart, elegant and great team players — this tool aims to guard your DSH quietly and answer the moment you call.