一键启动器 Hjay1101/dsh-launcher

🐋 dsh-launcher

面向 DeepSeek Harness 的极简原生 macOS 启动器。

DeepSeek Harness Web 一键启动器 —— 在你的工作区中启动 Web UI，等待服务器真正响应，并自动打开浏览器。可通过 CLI（dsh-launcher）、双击 .command 文件，或作为原生 macOS 应用（DeepSeek Harness.app）使用，具备真正的 Cocoa 事件循环、稳定的 Dock 图标，以及“关闭应用 = 停止服务”的生命周期。

一键启动 DeepSeek Harness Web：自动进入工作区、启动服务、HTTP 就绪后自动打开浏览器。支持 CLI 命令行、双击 .command、以及原生 macOS 应用三种形态——原生 app 有稳定 Dock 图标，关闭即可停止服务。

Why it's unique: while most DSH desktop projects are heavy Electron/Rust shells, this is the only native, lightweight macOS launcher in the ecosystem — a ~200 KB .app with zero browser engine and near-zero memory footprint.

独特性：生态中大多数 DSH 桌面端是 Electron/Rust 重型外壳，这是唯一一个原生、轻量的 macOS 启动器——整个 .app 不到 200KB，无浏览器引擎、几乎零内存占用。

Why / 为什么需要它

DeepSeek Harness's web UI must be started from the directory you want as the workspace root (that directory becomes the session root). Remembering the command, the right directory, and waiting for the port every time is tedious. dsh-launcher wraps all of it:

DSH 的 Web 界面必须在「你想作为工作区根目录的目录」下启动（该目录会成为会话根目录）。每次记住命令、切换目录、等待端口就绪很繁琐。dsh-launcher 把这些全包了：

- ✅ cd into your workspace automatically
- ✅ Detect the dsh binary (PATH → npx cache → fallback to npx)
- ✅ Skip startup if the server is already running — just open the browser
- ✅ Fixed port 3080 by default (DSH_RANDOM_PORT=1 for a random free port) — predictable URL
- ✅ HTTP readiness probe (opens the browser only when Harness really responds)
- ✅ macOS: build a native DeepSeek Harness.app with the official whale icon (Dock-ready)
- ✅ Isolated app data dir (DSH_HOME) for the .app — separate from the system ~/.dsh

macOS app & icon / macOS 应用与图标

Want a real app on your Desktop / Dock with the DeepSeek whale icon? We build one:

想要桌面/程序坞上带鲸鱼图标的原生应用？仓库自带构建脚本：

./build-app.sh # → ~/Desktop/DeepSeek Harness.app
./build-app.sh ~/Documents # → custom output dir
双击 .app → 完全静默后台启动 dsh web（无终端窗口），就绪后自动打开浏览器。关闭 app 即关闭服务：Dock 图标右键 → 退出（或 Cmd+Q），launcher 会先停掉 dsh 再退出。日志在 $WORKSPACE/.dsh/dsh.log（工作区不可写时回退 ~/.dsh/dsh.log）。可拖到程序坞。

本版新增：
- 固定端口 3080（默认）：启动地址可预测（设 DSH_RANDOM_PORT=1 可改为随机空闲端口，避免冲突）。
- 应用专属数据目录：.app 用 ~/Library/Application Support/DeepSeek Harness/dsh 当 DSH_HOME，与 CLI 的 ~/.dsh 隔离；首次运行自动迁移 profiles/ 和 plugins/。（.command/CLI 仍用 ~/.dsh。）
- HTTP 就绪探测：Harness 真正能响应后再开浏览器（而非只看端口通）；启动失败会弹清晰提示，不再静默失败。

工作原理：launcher 作为 dsh 的父进程保持存活——Dock 图标亮着 = 服务在跑；退出时 macOS 发 SIGTERM，launcher 先杀掉 dsh 子进程再退出，服务随之停止。同时自动补全常见 node/dsh 路径（GUI 启动的进程 PATH 精简，且 nvm 默认 Node 优先于 /usr/local 的旧版本）。

构建脚本会自动对应用做 ad-hoc 签名（macOS 强制要求，未签名的 .app 双击会毫无反应打不开）。

想给任意文件/文件夹设置自定义图标？用 set-icon.sh（零依赖，走系统 AppKit）：

./set-icon.sh assets/favicon.svg ~/Desktop/MyFolder
./set-icon.sh assets/AppIcon.icns ~/Desktop/launcher.command

图标资源在 assets/：AppIcon.icns（多尺寸）、1024px 源图和原始 favicon.svg（DSH 官方鲸鱼，取自 DeepSeek Harness Web 前端）。

图标设计（macOS HIG）： 白色圆角方形背景——1024×1024 画布，824×824 内容区居中，185.4px 圆角半径（Big Sur 图标网格），鲸鱼占内容宽度的 75%。两种变体：图标设计（macOS 规范）：白底圆角方形——1024 画布、居中 824×824 内容区、圆角 185.4px（Big Sur 图标网格）、鲸鱼占内容区宽度 75%。两个版本：

- AppIcon-1024.png / AppIcon.icns — 方形白底；macOS 会自动应用圆角遮罩（用于 .app）
- AppIcon-rounded-1024.png — 圆角白底已直接做进图里（用于通过 set-icon.sh 设置的文件图标，这些图标不会被系统加遮罩）

- AppIcon-1024.png / AppIcon.icns — 方形白底，圆角由 macOS 系统遮罩自动切（.app 用）
- AppIcon-rounded-1024.png — 圆角直接做进图里（.command 等文件图标用，系统不给文件图标加遮罩）

随时可重新生成/调整参数（如改 WHALE_PCT）：

随时可重新生成/调整参数（如改 WHALE_PCT）：

python3 generate-icon.py assets/favicon.svg # requires svglib+reportlab

快速开始 / 快速开始

方案 A — 克隆并直接运行

git clone https://github.com/Hjay1101/dsh-launcher.git
cd dsh-launcher
./dsh-launcher.sh --workspace /path/to/your/workspace

方案 B — 安装到 PATH

./install.sh # installs to ~/.local/bin/dsh-launcher
dsh-launcher -w /path/to/your/workspace

方案 C — macOS 双击运行

dsh-launcher.command 是一个可双击运行的启动器（需要 Terminal 应用）。通过编辑文件内的 DEFAULT_WORKSPACE 来设置默认工作区，或在 ~/.zshrc 中导出 DSH_WORKSPACE：

export DSH_WORKSPACE="/path/to/your/workspace"

然后双击 dsh-launcher.command。

用法 / 用法

Usage: dsh-launcher [options]

Options:
-w, --workspace Workspace root (default: $DSH_WORKSPACE or current dir)
-p, --port Web port (default: $DSH_PORT or 3080)
-b, --dsh-bin Explicit dsh binary path (default: auto-detect)
-n, --no-browser Do not auto-open the browser
-h, --help Show this help

环境变量 / 环境变量

| Variable | Description |
| DSH_WORKSPACE | Default workspace root (same as -w) |
| DSH_PORT | Default port (same as -p) |
| DSH_BIN | Explicit dsh binary path (same as -b) |
| DSH_NO_BROWSER | Set to 1 to disable auto-open (same as -n) |

示例 / 示例

Default port 3080, browser auto-opens
dsh-launcher -w ~/my-workspace

Custom port
dsh-launcher -w ~/my-workspace -p 8080

Headless (no browser)
dsh-launcher -w ~/my-workspace --no-browser

The server is already running → just opens the browser
dsh-launcher -w ~/my-workspace

工作原理 / 工作原理

1. cd 进入工作区（⚠️ 这是会话根目录——请从你想要的目录启动）
2. 检查端口是否已被占用 → 如果是，则打开浏览器并退出
3. 定位 dsh：
- 如果提供了 DSH_BIN，则使用它
- PATH 中的 dsh
- ~/.npm/_npx/*/node_modules/.bin/dsh 中最新的副本
- 否则使用 npx --yes @deepseek-ai/dsh web
4. 在后台启动 dsh web
5. 轮询端口（最多 60 秒），然后自动打开浏览器
6. 按 Ctrl+C 停止

停止 / 停止

在运行启动器的终端窗口中按 Ctrl+C。

许可证 / 许可证

MIT © Hjay1101