macOS 原生窗口 barisuraz/dsh-mac

dsh-mac

给 DeepSeek Harness 用的原生 macOS 应用。它在自己的窗口里跑真正的 DSH 网页界面，所以你的智能体不会和你日常浏览共用浏览器配置档、会话或键盘快捷键。

它启动 dsh web，等它开始监听，在 WKWebView 里显示图形界面，你退出时停掉服务端。

应用窗口

安装

一条命令搞定。下载最新发行版，校验其校验和与签名，把应用放进 /Applications，信任它，然后打开：

curl -fsSL https://raw.githubusercontent.com/barisuraz/dsh-mac/main/install.sh | sh

也可以手动来：从 Releases 打开 dsh-mac-<version>.dmg，把应用拖进 Applications，然后自己清掉隔离标记：

xattr -dr com.apple.quarantine "/Applications/DeepSeek Harness.app"

需要这个标记，是因为构建产物只做了临时签名，没有公证，而公证要付费的 Apple Developer 账号。从源码构建就完全绕开了这一步。

install.sh 读取三个可选变量：DSH_INSTALL_DIR、DSH_VERSION（形如 v1.2 的标签）和 DSH_NO_OPEN。

环境要求

- macOS 13 或更高版本
- Node 和 npm，用来拉取 harness

不必先安装 DSH，见首次运行。

或者从源码构建

需要 Xcode Command Line Tools（xcode-select --install）。

git clone https://github.com/barisuraz/dsh-mac
cd dsh-mac
./build.sh
cp -R "build/DeepSeek Harness.app" /Applications/

build.sh 不下载任何东西，几秒就跑完。

build/ 下的 bundle 是构建产物，不是你实际用的应用——把它复制到 /Applications，再启动那份副本。build.sh 会给该目录打标记，让 Spotlight 不去管它；不打这个标记，散落的 bundle 会被索引成第二个「DeepSeek Harness」，在 Spotlight 和 Launchpad 里显示为重复项。如果已经注册了一个，删掉它并注销那个游离路径：

rm -rf "build/DeepSeek Harness.app"
lsregister -u "$PWD/build/DeepSeek Harness.app"

其中 lsregister 指 /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister。
之后重启 Dock（killall Dock），让 Launchpad 重建列表。

它是什么

一个 Swift 文件。它是个外壳，不是分支：没有 harness 逻辑，没有重写的界面，没有 DSH 配置、API 或插件接口。窗口里的一切都是上游 DSH，所以新的 harness 功能一发布就会出现。

它不是聊天客户端。它不调用任何模型 API，不保存对话，也不管理凭据。

更新

DSH 还在开发者预览阶段，变化不断，所以应用每次启动都会更新它，就像 Android 的 A/B 系统更新。保留两份副本，更新只会落进空闲的那份：

slot a ── running now new versions install into the idle slot,
槽位 B ── 已知可用的回退版本 绝不覆盖你正在用的那份副本

1. 优先槽位启动，显示你的 GUI。不等待任何下载。
2. 运行中的版本稳定运行一分钟后，最新版本安装到另一个槽位。
3. 那份副本在临时端口上启动，必须先能提供 UI，才会被信任。
4. 下次启动时它成为你的版本，被它替换的那份留作回退。

如果新版本有问题，应用会自行恢复并告知你：

- 它起不来。 在成为你的运行版本之前就被拦下并丢弃。
- 它启动了但反复退出。 三次提前退出后，应用停止重试，标记它损坏，并切回旧版本。

无论哪种情况，都会有一张卡片写明失败的版本、你当前使用的版本，以及原因。警告会一直保留，直到你关闭；进度提示会自动淡出。

回滚通知 启动失败的版本不会被再次下载 —— ⌘U 清除该状态并重试，Reinstall Harness… 重建空闲槽位。

两份副本各占约 600 MB，另外应用在 ~/Library/Application Support/DeepSeekHarness 下维护一份自己的 npm 缓存。你自己的 npm 缓存不受影响。

首次运行

你无需自己安装 DSH。如果没有任何 harness，首次启动会安装一个并提供服务。如果你已经有了，就直接使用那份副本 —— 首次启动和你习惯的一样快 —— 同时在后台准备一个受管槽位。无论哪种情况，你现有的设置都保持原样。

行为

你现有的 harness 不受打扰。 如果端口 3080 被占用，应用会向操作系统申请一个空闲端口，而不是争抢。

应用退出后不留残余。 服务器在监管进程下运行，即使应用被强制结束，监管进程也会关掉它，因此不会有孤立的 node 进程占着端口。

会话延续。 应用和命令行使用同一个 ~/.dsh，所以现有会话、工作区和凭据都会出现，无需迁移。

存储独立。 webview 使用应用自己的容器，cookie 和本地存储不会与 Chrome 或 Safari 混在一起。

配置

全部可选，从环境变量读取，因此要从终端启动才能使用。

| 变量 | 默认值 | 含义 |
| DSH_WRAPPER_PORT | 3080 | 优先使用的端口；被占用时回退到操作系统分配的端口。 |
| DSH_MANAGED | 1 | 设为 0 可跳过槽位和更新，直接使用 dsh 解析到的版本。 |
| DSH_NO_AUTO_UPDATE | 0 | 设为 1 可保留槽位，但启动时从不拉取。 |
| DSH_NO_SYSTEM_DSH | 0 | 设为 1 可忽略 PATH 上的任何 harness，只用受管槽位。 |
| DSH_SLOT_VERSION | 最新 | 把槽位固定到某个版本，而不是跟踪最新版。 |
| DSH_BIN | 自动检测 | 显式指定 dsh 可执行文件的路径。 |
| DSH_APP_SUPPORT | ~/Library/Application Support/DeepSeekHarness | 槽位和更新状态所在位置。 |
| DSH_WRAPPER_LOG | ~/Library/Logs/DeepSeekHarness/wrapper.log | 诊断日志的写入位置。 |
DSH_HOME 以及 DSH 环境的其余部分原样继承，不做改动。

键盘

| 快捷键 | 操作 |
| ⌘R | 重新加载 GUI |
| ⇧⌘R | 重启 harness |
| ⌘U | 检查 Harness 更新 |
| ⌘+ / ⌘- / ⌘0 | 缩放 |
| ⌘Q | 退出并停止 harness |

维护

任何 wrapper 都有风险：上游一动，wrapper 就烂掉。所以这个 wrapper 始终只绑定一份契约：

1. 能解析到 dsh 可执行文件，
2. dsh web --no-open --port N 在 loopback 上提供 GUI，
3. 它打印一个 loopback URL，带 token 参数。

第 3 条是日志行，不是文档化的接口，所以一旦它漂移，--test-parser 和 --check-contract 就会大声报错。CI 在每次 push 和每周都跑这两个检查，把上游变更变成一次红色构建，并点名坏掉的那条契约，而不是变成一个永远加载不出来的窗口。

诊断

APP="/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeekHarness"

"$APP" --selftest # what it resolved
"$APP" --install-harness # fetch a harness into a slot, headless
"$APP" --check-contract # start a real harness and verify the contract
"$APP" --screenshot out.png --notice rollback # render the window to a PNG

./tools/test-ab.sh # recovery, against deliberately broken harnesses
./tools/test-repair.sh # session-log repair, against synthetic logs

Recover a session a plugin made unloadable (see below).
python3 tools/repair-sessions.py <session.v3.jsonl.zstd> --type <event-type>

单元测试运行器不在 release 构建里——在那种构建里，--test-parser 和其余命令都以退出码 2 结束。要构建一个带它们的版本：

DSH_BUILD_DIR=build-tests DSH_BUILD_TESTS=1 ./build.sh
BIN="build-tests/DeepSeek Harness.app/Contents/MacOS/DeepSeekHarness"

"$BIN" --test-parser # readiness-line parser, including refusals
"$BIN" --test-update # A/B slots and crash-loop detection
"$BIN" --test-notice # notice card rendering
"$BIN" --test-concurrency # the state lock and healthCheck, under real threads

--test-concurrency 是那个要盯紧的：它从多个线程同时驱动更新路径，这是让其中竞态暴露出来的唯一办法。

恢复无法加载的会话

会话日志里只要含有 harness 不认识的事件类型，就会被直接拒绝，除非该事件带有 ignorable: true 标记。这项检查是刻意为之：悄悄跳过一条会影响重建的事件，就会恢复出一个微妙地错误的会话。

陷阱在仓库外的插件。harness 的已知类型目录在仓库内生成，所以插件自己的事件类型天然就在目录之外，而 Session.append() 也没给插件设置该标记的办法。于是插件追加一条这样的事件，就写出了一份任何 harness 都打不开的日志——包括写它的那个 harness，因为 append 在写入时不校验。故障只在下次打开会话时才出现：

会话「...」里有一个事件类型「<plugin>/event-name」（seq 18），当前 harness 不认识它，也没有标记为可忽略，因此拒绝解析这份日志

tools/repair-sessions.py 把指定的事件类型标记为可跳过，让日志重新加载。它只处理你明确点名的事件类型，绝不猜测——因为把某个事件标记为可忽略，等于告诉之后每一个读取方丢弃它：对请求记录来说这很安全，对任何会影响会话内容的事件则不安全。它会把每份原始文件复制到 ~/.dsh/session-format-repairs/ 下，并且在仍有 harness 持有该会话时拒绝运行，因为那个 harness 下次 flush 会覆盖掉修复结果。

python3 tools/repair-sessions.py \
~/.dsh/sessions/<workspace>/<session>/session.v3.jsonl.zstd \
--type <plugin>/<event>

更好的修法在插件那边：别再写这个事件。修复之前，先到插件源码里确认这个事件只是信息性的。

安全

harness 把本地代码执行放在 loopback URL 后面，本应用遵守这条边界：

- 只加载 127.0.0.1 或 localhost 上带 token 的 http URL，解析器也针对非 loopback 输入做过测试。
- token 从 harness 的输出里读取，只用一次，并在所有诊断信息中脱敏。
- DSH 拒绝绑定 0.0.0.0，本应用不会改变这一点。
- 指向其他站点的链接在默认浏览器里打开，不在 harness 窗口里打开。
- 安装时用应用自己的缓存运行 npm install。不往全局装任何东西，也不改动 shell 配置档。
- DSH 处于开发者预览阶段。在你自己的机器上运行任何东西之前，请先审查。

项目结构

Sources/main.swift the entire app: window, launcher, supervisor, slots, diagnostics
(HarnessLifecycle decides what runs; AppDelegate draws it)
install.sh the download-and-install one-liner
build.sh compiles, assembles, icons, and signs the bundle
tools/package.sh builds a release disk image and verifies it by mounting it
tools/make-dmg.sh the disk image itself
tools/notarize.sh sign, notarize, and staple a release build
tools/test-ab.sh end-to-end update and recovery tests
tools/repair-sessions.py marks informational plugin events ignorable so their logs load
tools/test-repair.sh tests for the repair tool's rewrites and its refusals
tools/known-event-types.json the harness's event catalog, as this build knows it
tools/make-icon.swift the icon, drawn as vectors at each required size
docs/ screenshots, rendered by the app itself

发布版本

构建默认做 ad-hoc 签名，本地自用足够了。想让别人打开时不必走 quarantine 那一步，就必须用 Developer ID Application 证书签名，并通过 Apple 公证，这需要一个付费的 Apple Developer 账号。
build.sh 始终启用强化运行时，所以你在本地测试的内容，就是最终拿去公证的内容：

xcrun notarytool store-credentials "dsh-mac" \
--apple-id "you@example.com" --team-id "YOURTEAMID" --password "app-specific-password"

DSH_SIGN_IDENTITY="Developer ID Application: Your Name (YOURTEAMID)" ./tools/notarize.sh

脚本先构建，然后检查签名：如果不是 Developer ID、没有启用强化运行时、或者没有时间戳，就拒绝继续。检查通过后执行公证，并给应用和磁盘映像两者都打上票据（staple），再确认 Gatekeeper 分别接受它们。最后留下 build/dsh-mac-<version>.dmg，可以直接上传。配置细节见 tools/notarize.sh 的文件头。

只提交磁盘映像，映像里的应用也会被公证，但只有映像带票据；而 install.sh 会把应用复制到 /Applications，之后它就要单独接受评估。所以两者都做公证，让每个产物都能自给自足。

应用不需要任何权限例外：强化运行时的限制按二进制分别生效，而它以独立进程的方式启动 node 和 zsh。

License

MIT，见 LICENSE。

应用图标使用 DeepSeek 鲸鱼标志，从 DSH 网页前端附带的矢量资源中解析得到。该标志归 DeepSeek 所有，仅用于标识应用运行的是什么；如果你以其他名称重新分发，请替换掉它。本项目与 DeepSeek 无隶属关系，也未获其背书。