原生启动器 NaleenB/harness-desk-macos

Harness Desk

一个小巧的原生 macOS 启动器，用来启动 DeepSeek Harness。

整个项目就是一个 Swift 文件，包在 WKWebView 外面。它启动本地 dsh web 服务（或连上已经在跑的那个），等拿到带认证的 URL，然后在原生窗口里加载正常的 Harness UI。不用 Electron，不带运行时，也不额外复制一份 dsh。

非官方。 本项目与 DeepSeek 没有关联，也未获其背书。它只是社区给开源 Harness Web UI 套的一层壳。

状态

源码优先。仓库里没有预编译的二进制文件：请用 Xcode Command Line Tools 在本地构建。构建脚本会对产物做 ad-hoc 签名，仅供本地使用；公开分发需要 Developer ID 和公证（见 SECURITY.md）。

为什么还要一个启动器？

官方桌面应用是 Electron 的，而且写这份文档时还没有发布任何产物。通用的「Web 应用」包装器也缺了这里最关键的部分：它们不会启动、连接或重启 dsh web，也不处理按进程生成的启动 token 和绑定端口的 cookie。Harness Desk 刻意做小，只干这件事。

- 原生 AppKit/WebKit 窗口，二进制约 200 KB（外加系统自带的 WebKit 运行时）。
- 用你已经装好的 dsh，绝不会跑一份过期的内置副本。
- 连上正在运行的服务，而不是再起一个；每个用户只允许一个启动器实例。
- 对服务做健康检查，失败后按 1/2/4 秒退避重启，并用新 token 重新加载同一个窗口。
- 处理 UI 需要的 WebKit 细节：OAuth/登录弹窗、麦克风采集、带 token 的「Open in Browser」、⌘W。
- 启动 token 和启动器日志以 0600 权限保存，日志里的 token 会被抹掉。
- 标题栏有个低调的价格指示器（Peak/Normal），依据 UTC 星期窗口和当前系统时区计算；悬停可看时间表、本地时间，以及当前时段结束的倒计时。

要求

- macOS 13 或更新版本（默认构建 arm64）。
- Xcode Command Line Tools：xcode-select --install。
- 已安装 DeepSeek Harness，命令为 dsh：

npm install -g --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty,@google/genai,protobufjs @deepseek-ai/dsh

当前安装说明和模型配置见 DeepSeek Harness 文档。

构建与运行

git clone https://github.com/NaleenB/harness-desk-macos.git
cd harness-desk-macos
./scripts/build.sh --install
open "/Applications/HarnessDesk.app"

--install 是可选的；不加的话，应用构建在 build/HarnessDesk.app，不会复制到别处。纯价格规则的测试用 ./scripts/test.sh 运行。
构建脚本用 swiftc 编译，写入应用包，把应用标识注入 Resources/Info.plist.in，对产物做 ad-hoc 签名，需要时再复制到 $INSTALL_DIR。用环境变量覆盖标识：

DISPLAY_NAME="Harness Desk" \
BUNDLE_ID="dev.example.harnessdesk" \
VERSION="0.1.0" \
INSTALL_DIR="$HOME/Applications" \
./scripts/build.sh --install

工作原理

1. 如果已有另一份应用在运行，就拒绝启动。
2. 在 3080–3090 上探测是否有 DSH 服务在运行（判断依据是它返回 401 dsh web authentication required）。找到就用临时 cookie jar 校验已保存的 token 并接入；找不到就回退到该端口对应的 WebView cookie。
3. 如果没有服务，就选第一个空闲端口，在工作目录下运行 dsh web --no-open --port <n>，抓取 dsh web: http://127.0.0.1:<port>/?token=… 这一行，然后加载它。
4. 把带 token 的 URL 写入 ~/.dsh/web-ui-url.txt（权限 0600），再在 WKWebView 里加载，WebView 会收到有效期 30 天的签名 cookie。
5. 每 5 秒检查一次端口。连续两次失败就触发重启，退避间隔为 1/2/4 秒（共三次尝试）；同一个 WebView 重新加载新 token。
⌘Q 会停掉应用自己启动的服务；接入的服务保持运行。

配置

应用读取的环境变量：

| 变量 | 默认值 | 用途 |
| DSH_WEB_WORKSPACE | 依次取 ~/Projects、~/Developer、~/coding_projects，最后是 ~ | dsh web 的工作目录 |
| DSH_LAUNCHER_PORT_START | 3080 | 扫描/使用的起始端口 |
| DSH_LAUNCHER_PORT_END | 3090 | 扫描/使用的结束端口 |
| DSH_LAUNCHER_INSPECTABLE | 未设置 | 设为 1 后可从 Safari 检查 WebView |

构建期变量：APP_NAME、DISPLAY_NAME、BUNDLE_ID、VERSION、 BUILD_NUMBER、INSTALL_DIR、ICON_PATH（个人构建可选用的 .icns；仓库默认是一个中性图标）。

安全

Harness Desk 以你的用户权限运行，并启动 dsh，而 dsh 能执行命令、读取 ~/.dsh（凭据、会话）。请把它当作可信的本地代码，从源码构建，运行前先读代码。它没有遥测，也不会自行发起网络连接。

启动 token 是运行中服务的有效凭据。它写入 ~/.dsh/web-ui-url.txt，权限 0600，启动器日志会把它脱敏。每次 dsh web 启动时 token 都会轮换。

构建脚本对应用做 ad-hoc 签名。这对本机没问题；换一台 Mac，Gatekeeper 会拒绝。如果要分发二进制，请使用 Developer ID、hardened runtime 和公证。见 SECURITY.md。

已知限制

- 仅支持 macOS，默认 arm64。Intel 或通用构建请改 scripts/build.sh 里的 -target。
- 启动 URL 从 dsh web: 的 stdout 行解析。上游一旦改动这一行，启动器就会不断重试，最终弹出提示，直到适配为止。
- 不自动更新，没有偏好设置窗口、原生文件对话框、下载、通知，也不支持多窗口。
- 连接到不是本应用启动的服务器时，按 ⌘Q 退出后该服务器仍在运行。需要时用 pkill -f "dsh web" 停掉它。
- 重新构建会改变 ad-hoc 签名；macOS 可能再次请求麦克风权限。
- 价格指示器只按 UTC 工作日时段计算，不含中国法定节假日。
- 账户资料/余额请求可能从 platform.deepseek.com 返回 403。该端点位于 AWS WAF 之后，宿主进程不会发送浏览器的 aws-waf-token cookie。走 API key 的模型调用不受影响。

故障排查

- 登录时提示「There is no application set to open the URL about:blank」 —— 这个构建版本太旧，不支持弹窗。请从本仓库重新构建。
- 提示「This browser cannot record audio」 —— 应用包缺少 NSMicrophoneUsageDescription，请重新构建。如果提示麦克风访问已禁用，请在系统设置 → 隐私与安全性 → 麦克风中允许 Harness Desk。
- 提示「Harness authentication required」 —— 有 DSH 服务器在运行，但本应用没有该端口的有效 token 或 cookie（例如该服务器是在终端里启动的）。用 pkill -f "dsh web" 退出它再重新打开，或者在浏览器中打开它打印的 token URL。
- 端口 3080–3090 被占用 —— 其他服务占着这些端口。启动器会跳过非 DSH 端口；需要时修改 DSH_LAUNCHER_PORT_START/END。
- 日志 —— ~/.dsh/logs/web-launcher.log。

兼容性

已在 macOS 27.0.1 上用 dsh 0.2.1-rc.2 测试。DeepSeek Harness 是开发者预览版；它的命令行输出和插件配置可能在不同 rc 版本之间变化。升级后如果启动器出问题，请查看日志并提交 issue。

许可证

MIT。见 LICENSE。DeepSeek Harness 是独立项目，遵循它自己的许可证。