桌面客户端 fatwang2/dsh-client

DSH Client

[!IMPORTANT]
这个项目已归档，不再维护。 DeepSeek 现已推出官方 DeepSeek Harness 桌面应用，支持 macOS（Apple silicon）和 Windows。到 deepseek.com/harness 下载。

这个客户端不会再收到更新。想切换的话，先退出这个应用，再安装官方版本；它使用相同的 DeepSeek Harness.app 名称，会替换掉 /Applications 里的这一个。替换应用不会删除你的 ~/.dsh 目录（凭据、设置、会话）。

DSH Client 是 DeepSeek Harness（dsh）Web GUI 的原生客户端。打包后的应用名为 DeepSeek Harness。它的外壳负责监管一个回环 dsh web 宿主进程，掌管应用生命周期，并把锁定版本的 harness 运行时原样放入打包应用——无需单独安装 Node.js，也不会弹出终端窗口。

这是独立的社区项目，与 DeepSeek 无隶属关系，也未获其背书。

DeepSeek Harness for macOS

架构

src/main.ts Electron shell: window, app menu, security hardening, boot wiring
src/host-supervisor.ts dsh web child process: spawn, readiness URL parsing, graceful shutdown
src/window-lifecycle.ts close-to-hide and quit sequencing, independent from Electron
src/update-controller.ts electron-updater states: quiet check, background download, restart prompt
scripts/stage-runtime.mjs materializes the pinned dsh dependency closure into runtime-host/
scripts/verify-packaged-runtime.cjs afterPack guard: reject packages missing Host artifacts
scripts/release-mac.sh local signed + notarized build entrypoint (never publishes)
scripts/release-mac.mjs release preflight, packaging verification; uploads only in CI
scripts/release-assets.mjs the asset set that makes a Release "complete", shared by both scripts
scripts/smoke-host.mjs release gate: boots the staged Host and validates its readiness line
scripts/track-dsh.mjs compares the pin with upstream's newest dsh Release; bumps pin, app version, release notes
scripts/semver-compare.mjs SemVer precedence for the tracker, which runs before any npm ci
scripts/verify-inset.mjs CDP check of the traffic-light inset geometry on a running app
scripts/make-icons.swift regenerates build/icon.png from the harness mark
.github/workflows/track-dsh.yml scheduled: new upstream dsh → release
.github/workflows/release.yml manual: release the version currently on main
.github/workflows/release-macos.yml the shared build, sign, notarize, verify, publish job
runtime/package.json exact @deepseek-ai/dsh version pin (no compatibility promise upstream)
runtime-host/package-lock.json committed lockfile for the rest of the Host closure

外壳和宿主如何配合：
1. 启动时，supervisor 会拉起 dsh web --host 127.0.0.1 --port 0。操作系统分配一个空闲的 loopback 端口，所以永远不会撞上 3080。
2. harness 会打印它那行标准的就绪信息（dsh web: http://127.0.0.1:<port>/?token=<secret>；token 是随 0.1.5-alpha 版 harness 一起出现的，更早的版本只打印裸 origin）。supervisor 增量解析这行信息，并严格校验（loopback HTTP、根路径、显式端口、最多只能有那一个 token 查询参数），然后把 loopback URL——origin 加 token——交给窗口。
3. 窗口的首次导航会带上 token（API 围栏把会话绑定到它，并拒绝未带 token 的 loopback 请求）；之后的导航被锁定到那个 origin。其他 HTTP(S) 链接在系统浏览器中打开；所有权限请求一律拒绝；渲染进程在沙箱中运行，不集成 Node。
4. 关闭窗口只是把它隐藏，Host 仍然存活；点击 Dock 图标即可恢复。显式退出会先销毁 Host（先 SIGTERM，等 harness 的 5s 排空后 SIGKILL），然后才释放 Electron 的退出流程。
5. 打包后的构建通过 Electron 自带的 Node 运行时（ELECTRON_RUN_AS_NODE=1）运行已暂存的命令行，所以不会额外附带第二个 Node 二进制文件。

macOS 红绿灯按钮内边距

随附的 harness 前端并不知道无边框的 hiddenInset 外壳，所以外壳会注入一份样式表，在侧边栏列顶部预留 40px 的条带，给关闭/最小化/缩放按钮用，并把整宽的顶部条带标记为原生窗口拖拽区域（[class="sidebarCol"] 属性选择器，在 css-module 哈希变化时依然稳定）。交互控件被显式排除在拖拽区域之外，这样它们仍能收到指针事件。注入在 loadURL 之前排队，并在 dom-ready 时重新应用；它从不被 await，因为渲染进程提交文档之前调用 insertCSS 可能会卡住启动。

只给侧边栏加内边距，会让中间列和第三列从红绿灯按钮下方开始，所以样式表还会把它们的表头行下推到侧边栏 logo 所在的那一行：[data-slot="conversation.session.header"] > header（中间列的会话表头——前端自己的标题/标签页/操作条）获得 60px 的顶部内边距，[data-slot="details"] > > [class="_header"]（详情面板的表头行）获得 62px。data-slot 是前端为这些条带声明的稳定接缝，而同一元素上的 css-module 哈希不是，所以两条规则都按属性加元素类型选择，而不是按类名；每条规则的对齐几何都在 src/main.ts 中注入的 CSS 旁边有注释说明。

scripts/verify-inset.mjs 通过 CDP 检查实际生效的几何（用 --remote-debugging-port=<port> 启动）：拖拽区域必须在 40px 高度上横跨整个窗口宽度，logo 行必须从红绿灯条带下方开始。

开发

npm installsh
npm run stage # 把锁定版本的 dsh 运行时闭包落到 runtime-host/
npm run dev # 构建 + 启动；用应用菜单或 Cmd+Q 退出

DSH_MAC_NODE_EXECUTABLE 可以覆盖开发用的 Node 二进制。开发宿主共用你平时的 ~/.dsh（凭据、设置、会话）。

测试与类型检查 sh
npm test
npm run typecheck

打包 sh
npm run package # 当前平台的未打包应用（dist/）
npm run dist # 未签名的 macOS DMG + 更新 ZIP，用于本地验证
npm run dist:signed # 已签名 + 已公证的 DMG/ZIP + 更新元数据

staging 这一步会依据仓库里提交的 runtime-host/package-lock.json 执行 npm ci，安装 Host 闭包；保留 npm 的扁平布局（不用 pnpm 的符号链接存储），去掉 bin 符号链接；如果缺少 CLI 入口或 Web 前端 dist，或者 harness 包并非全部来自锁定版本，构建就会失败。afterPack 钩子会在签名前，对照锁定版本重新校验整个闭包。签名发布流程（scripts/release-mac.mjs）还会额外启动一次真正 staging 出来的 Host（scripts/smoke-host.mjs），这样如果 harness 的就绪行 shell 解析不了，发布就会失败，而不是把问题版本发出去；打包前还会清空 dist/，确保产物严格按发布版本校验和上传。

签名构建完成后，验证安装的产物： sh codesign --verify --deep --strict --verbose=2 "dist/mac-arm64/DeepSeek Harness.app" spctl --assess --type execute --verbose=4 "dist/mac-arm64/DeepSeek Harness.app" xcrun stapler validate "dist/mac-arm64/DeepSeek Harness.app"

发布与自动更新

签名发布使用 electron-updater，订阅公开的 fatwang2/dsh-client GitHub Releases feed。electron-builder 会把该仓库写进应用，并生成 ZIP、blockmap 和 latest-mac.yml，供 Squirrel.Mac 使用。

发布只由 GitHub Actions 构建和发布。 干活的工作流只有一个—— .github/workflows/release-macos.yml——由两个入口调用，这样自动路径和手动路径不会跑偏：

| 入口 | 触发方式 | 发布内容 |
| .github/workflows/track-dsh.yml | 每四小时一次，或 Run workflow（可选指定确切的 harness 版本） | 最新的上游 @deepseek-ai/dsh，来自它自己写的 bump 提交；也会重试某个 Release 仍缺失或不完整的版本 |
| .github/workflows/release.yml | 在 main 上 Run workflow* | main 上已有的版本——客户端改动走这个发布按钮 |

两者都调用 release-macos.yml，由它在 GitHub macOS arm64（Apple silicon）runner 上构建、签名、公证、验证并发布。由于共用同一个工作流级并发组（dsh-release，运行中永不取消），同一时间只有一个发布流程会碰版本 tag，发布任务还会重新检查任何版本号 bump 之后都会做完整性检查，所以排队中的重复运行会跳过昂贵的构建，而不是重新构建一个已经发布的版本。（GitHub 每个分组只保留一个运行中加一个待处理运行；第三个排队的运行会替换掉待处理的那个，所以一波密集的 dispatch 会合并，而不是层层堆积。）

那台 runner 是 Apple silicon，所以 Releases 和自动更新源目前只服务 Apple silicon 安装包。本地跑 npm run dist:signed 会在宿主架构上驱动同一批 electron-builder 目标；electron-builder 的 arch 参数（--x64、--arm64）可以指定另一种架构。

自动跟踪上游

.github/workflows/track-dsh.yml 每四小时运行一次，也可以在 Actions 标签页手动触发（Run workflow）。它把 runtime/package.json 里的 pin 和 deepseek-ai/deepseek-harness 中最新的 dsh-v Release 做比较（取最高版本，包含 alpha；上游把每次切版都标成 prerelease，所以 npm 的 latest dist-tag 会滞后）。当上游发布了更新的版本、并且该版本也上了 npm 时，发布流程会：

1. bump pin，重新解析 Host 闭包（stage-runtime.mjs --relock），启动该闭包一次，验证 shell 仍能解析它的 readiness 行，bump 应用的 patch 版本，并写入 .github/release-notes/<version>.md，其中写明捆绑的 harness；
2. 跑测试和 typecheck，只有通过后才以 github-actions[bot] 身份提交到 main 并推送——这样客户端无法启动的 harness 会在工作区里让运行失败，而不是落到 main 上；
3. 构建、签名、公证、验证、发布。

应用版本刻意与 harness 版本独立：harness 发布的是 release candidate，而稳定版上的已安装应用会跳过 prerelease 更新。每次跟踪到的升级对应一次 patch bump；Release 标题和说明会写明它捆绑了哪个 harness。

如果构建在 bump 提交落地之后失败，下一次运行会注意到当前应用版本还没有完整的 Release，于是重试发布，不再 bump。完整是指 Release 可公开消费——已发布、不是 draft、不是 pre-release——并且带有更新源的全部资产：DMG、更新 ZIP、它的 .zip.blockmap，以及 latest-mac.yml，其中 version: 必须写明同一个版本。任何一项不满足的 Release 都算未发布，所以下一次运行会在现有 tag 上重新构建并修复它（顺带清掉误留的 draft/pre-release 标记）。

运行只在 main 上继续（两个 job 都基于该分支的 pin 做判断，而 workflow_dispatch 没有分支过滤，所以每个入口都自己用 github.ref 做守卫）。当显式版本指定的是那个版本而不是上游最新的 Release 时，比当前 pin 更旧的版本会被拒绝：显式版本不允许降级。有两种上游的临时状态不会让运行失败：版本已在上游打 tag 但还没上 npm 时会保持固定版本，并在之后的某个 tick 重试；如果固定的版本比上游最新的 Release 还新，就保持不动，而不是往回降。

工作流需要这些仓库 secret （Settings → Secrets and variables → Actions）：

| Secret | 内容 |
| CSC_LINK | Developer ID Application .p12 的 Base64 |
| CSC_KEY_PASSWORD | 该 .p12 的密码 |
| APPLE_API_KEY_P8 | App Store Connect API key .p8 的内容 |
| APPLE_API_KEY_ID | 该 API key 的 Key ID |
| APPLE_API_ISSUER | 该 API key 的 Issuer ID |

在一台登录 Keychain 里已经存有该身份的 Mac 上，从 Keychain Access 把 Developer ID Application 证书连同私钥导出为 .p12，然后： sh gh secret set CSC_LINK --body "$(base64 -i DeveloperID.p12)" gh secret set CSC_KEY_PASSWORD gh secret set APPLE_API_KEY_P8 < ~/.appstoreconnect/private_keys/AuthKey_XXXXXXXXXX.p8 gh secret set APPLE_API_KEY_ID --body XXXXXXXXXX gh secret set APPLE_API_ISSUER --body 00000000-0000-0000-0000-000000000000

CSC_LINK 和 CSC_KEY_PASSWORD 是一对，不是两项独立设置：重新导出 .p12 会生成新密码，所以两者必须来自同一次导出。只更新其中一个，签名步骤会失败，报 security: SecKeychainItemImport: MAC verification failed during PKCS12 import (wrong password?) —— 密码真的填错时也是同样的报错。secret 读不回来，所以区分这两种情况靠的是 electron-builder 在 -P 参数位置打印的 sha256：两次运行哈希不变，说明变的不是密码，过时的是证书。上传前先一起验证 .p12 和它的密码，不要碰登录 keychain： sh security create-keychain -p verify /tmp/verify.keychain
security import DeveloperID.p12 -k /tmp/verify.keychain -P "$PASSWORD" &&
security find-identity -p codesigning /tmp/verify.keychain
security delete-keychain /tmp/verify.keychain

发布客户端改动

1. 在 main 上合并改动，并提升 package.json 里的 version（需要发布说明时，加上 .github/release-notes/<version>.md）。
2. Actions → Release current main* → Run workflow。
- dry_run 会构建、签名、公证并验证，但不发布，也不向 main 推送任何东西 —— 一次演练让仓库保持原样，所以之后 tracker 不会捡起这个版本。
- harness_version 会额外先把那个确切的 @deepseek-ai/dsh 固定下来（这条路径会自己给应用版本打补丁号，所以用了它就别动 version）。
- allow_republish 只在替换一个已经完整发布的版本时才需要；不加它运行会拒绝，这正是防止同一版本发两次的护栏。重新发布同一个版本到不了已安装的客户端：electron-updater 比较版本号，所以修复必须以新版本发出。
这次运行需要一份干净的 main 检出，所以先把版本号提上去再推送。之后的预检要求分支为 main，且 HEAD == origin/main，满足后才会签名、公证、校验更新元数据，并创建 Release。提升版本号是发布的前提：如果你改了客户端代码却没提版本号，追踪器在 main 上看到的仍是已发布的版本，于是什么都不会发布——这是防护机制在起作用，不是失败。（反过来，某个版本已经在 main 上但还没有 Release，即使你从不按那个按钮，追踪器下一轮也会把它捡起来。）

在维护者的 Mac 上构建

本地运行会构建、签名、公证并校验 CI 将要发布的内容，但绝不发布。有两处机制保证这一点：本地入口点（scripts/release-mac.sh）在交接前会丢掉发布相关的变量；scripts/release-mac.mjs 只在真正的 GitHub Actions runner 上（GITHUB_ACTIONS=true 加上 run id）且设置了 DSH_RELEASE_UPLOAD=1 时才上传。npm run package 和 npm run dist 出于同样的原因传入 --publish never。这是防护，不是编译器：在一台已经对发布仓库完成认证的机器上手动导出所有这些变量，照样会发布，所以请把本地流程只当作构建与校验。

把 .env.release.example 复制为被忽略的 .env.release，配置好 Developer ID 身份和 App Store Connect API key，然后运行： sh
npm run dist:signed # sign, notarize, verify; artifacts stay in dist/

给自己机器用的未签名构建（不需要凭据）是 npm run dist —— 它生成 DMG/ZIP 但不签名，因此绝不会被误认为可分发的 Release。

签名后的应用会在启动后静默检查，在后台下载，只有更新就绪后才提示重启。选择重启时，会先通过正常的优雅退出路径关掉内置 Host。（本地构建的 bundle 没有自己的更新源——npm run package 生成的是 --dir 应用，不带 app-update.yml——所以要接收更新，请安装 Release DMG。）

环境变量

| 变量 | 作用 |
| DSH_MAC_OWN_HOME=1 | 把 harness 状态限制在应用的数据目录（~/Library/Application Support/dsh-mac/dsh-home），而不是共享的 ~/.dsh。 |
| DSH_MAC_NODE_EXECUTABLE | 仅开发用：用来运行已暂存 CLI 的 Node 兼容二进制文件。 |
| DSH_MAC=1 | 导出到 Host 进程环境的标记。 |
| DSH_RELEASE_ENV | 可选的本地发布环境文件路径；默认为 .env.release。 |
| DSH_RELEASE_TAG | 可选的 Release tag 覆盖值；默认为 v<package version>。 |
| DSH_RELEASE_UPLOAD=1 | 上传到 GitHub Releases。只由发布工作流设置；本地机器即使设置了也会被拒绝。 |
| DSH_REQUIRE_NEW_RELEASE=1 | 拒绝发布已有完整 Release 的版本（手动发布时使用；对 dry run 同样生效）。 |
| SKIP_UPLOAD=1 | 明确禁止某次运行上传，否则这次运行会发布（双保险；本地运行从不发布）。 |

其他所有环境变量都会透传给 Host（DEEPSEEK_API_KEY、代理等）。

更新 harness

harness 是快速迭代的候选版本，明确不承诺兼容性，而且只锁定 @deepseek-ai/dsh 并不能锁定 Host。它约 230 个同族包通过脱字符范围互相依赖，^0.1.0-rc.6 会匹配 0.1.0-rc.7，所以没有 lockfile 的安装会悄悄产出一个命令行，它来自某个候选版本，却坐在另一个候选版本的内部实现上，Web 前端又来自第三个。因此 runtime-host/package-lock.json 被提交进仓库，staging 运行 npm ci，staging 和 afterPack 钩子都会拒绝这样的依赖树：其中 harness 包并非全部携带锁定的版本。

只要上游发布新版本，跟踪工作流就会自动执行这次升级（见 自动跟踪上游）。手动操作也是同样三步： sh

1. bump the exact pin in runtime/package.json

2. resolve the closure afresh and rewrite the lockfile

npm run stage -- --relock

3. commit runtime/package.json and runtime-host/package-lock.json together

不加 --relock，npm ci 会拒绝 lockfile 不满足的锁定版本，所以版本提升绝不会意外进入某个包。升级后，重新验证启动，并重新运行 scripts/verify-inset.mjs：harness 前端对红绿灯内嵌样式表所针对的 DOM 不作任何兼容承诺。

License

MIT。打包后的应用内嵌 MIT 许可的 @deepseek-ai/dsh 运行时；分发前请查看其仓库的 THIRD_PARTY_NOTICES.md，了解传递依赖的许可。