DSH 启动器 · DeepSeek Harness 桌面版启动器（macOS）

deepseek-harness 启动器 / DeepSeek Harness 桌面版 / DSH 桌面启动器 一个面向 macOS 的桌面启动器：双击图标即可启动 DeepSeek Harness 的 Web UI（默认 http://127.0.0.1:3080），无需每次打开终端。

DeepSeek Harness（dsh）是 DeepSeek AI 开源的 agent harness。本启动器把 pnpm dsh web 封装成一个原生 macOS 应用（AppleScript stay-open applet），提供与普通桌面软件一致的使用体验。

特性

• 🖱️ 双击启动：桌面 DSH.app 图标，双击即后台启动 Web UI 并自动打开浏览器
• 🔂 严格单实例：三层保障（App 级 applet.pid 全局锁 / 启动器级原子锁 / 端口接管检查），任意情况下同时只有一个实例、一个服务
• 🔁 重复点击直接打开：已运行时再次点击图标 → 打开浏览器；30 秒内重复点击不会刷出多个标签页
• 🛑 Cmd+Q 停止：Dock 图标在服务存活期间常驻；退出即停止由启动器管理的服务，且不会误杀终端里手动启动的服务
• 🤝 自动接管：服务已在运行（包括终端启动的）→ 接管并记录监听者 PID，绝不重复启动
• 🧠 环境自愈：自动重建 Finder 启动环境缺失的 PATH，并在 nvm 各版本中挑选满足仓库要求（Node ^22.19 || >=24）的版本
• 🚀 就绪才开浏览器：确认首页真的返回了 GUI 页面（含 __DSH_BOOT__ 引导标记）后再打开，避免"页面打不开要手动刷新"
• 📋 日志与状态：~/Library/Logs/dsh-web.log（自动滚动），状态文件在 ~/Library/Application Support/DSH Launcher/

安装

方式一：下载 Release（推荐）

1. 在 Releases 下载 DSH.app.zip
2. 解压得到 DSH.app，放到桌面或拖入「应用程序」
3. 双击启动（首次需要本机已安装 DeepSeek Harness，见下方前置条件）

方式二：从源码构建

前置条件：

• Node.js ^22.19 || >=24（推荐 nvm）
• pnpm
• 已克隆并构建好的 deepseek-harness：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build

然后构建启动器：

git clone https://github.com/<your>/dsh-launcher.git
cd dsh-launcher
./build-app.sh          # 生成 DSH.app（osacompile + 图标 + 脚本 + 签名）
cp -R DSH.app ~/Desktop # 复制到桌面（或任意位置）

项目目录探测顺序：~/deepseek-harness → ~/Downloads/dshai/deepseek-harness → ~/dev|code|projects|work/deepseek-harness，或用环境变量 DSH_DIR 显式指定。

使用

操作	效果
双击 DSH.app	服务未运行 → 后台启动 + 打开浏览器；已运行 → 接管 + 打开浏览器
运行中再次点击	打开浏览器（30 秒内重复点击不新开标签页）
Cmd+Q 退出	停止由启动器管理的服务（未接管的服务不会被误杀）
服务停止后	Dock 图标自动消失；再双击即重新启动

配置

环境变量	默认值	说明
DSH_PORT	3080	监听端口
DSH_DIR	自动探测	deepseek-harness 项目目录

工作原理

• 外壳：AppleScript applet（osacompile -s，stay-open），on run / on reopen / on idle / on quit 四个 handler 驱动生命周期；on idle 每 5 秒探活，服务停止后自动退出。
• 单实例三层保障：① applet.pid 全局锁（跨副本，后来的实例转发请求后自退）；② launcher.lock 原子目录锁（并发冷启动只放行一个）；③ 端口已监听则只接管（lsof -sTCP:LISTEN 识别真实监听者，避免把浏览器连接当成服务器）。
• 就绪判断：curl 首页并确认含 __DSH_BOOT__ 引导标记，再等 2 秒收尾才打开浏览器。
• 标签页节流：last-open 时间戳，30 秒内不重复 open。

文件结构

dsh-launcher/
├── applet.applescript   # AppleScript 应用外壳
├── launcher.sh          # 启动逻辑（环境准备 / 接管 / 冷启动 / 就绪检查 / 节流）
├── stop-dsh.sh          # 停止逻辑（仅停已接管的服务）
├── build-app.sh         # 组装 DSH.app（osacompile + 图标 + 签名）
├── AppIcon.icns         # 应用图标（取自 deepseek-harness 官方 favicon 生成）
└── README.md

常见问题

• 提示"未找到项目目录"：项目不在默认探测位置，设置 DSH_DIR。
• 启动失败：查看 ~/Library/Logs/dsh-web.log 与状态目录下的 applet-err.log。
• Node 版本不符：启动器会自动在 nvm 里挑 ^22.19 || >=24；也可手动 nvm use 22。
• 想改端口：设置 DSH_PORT。

说明

• 本项目是 DeepSeek Harness 的社区桌面启动器，与 DeepSeek 官方无隶属关系。
• 修改 applet.applescript / launcher.sh / stop-dsh.sh 后运行 ./build-app.sh 重新生成，覆盖桌面副本即可。

License

MIT