DeepSeek Harness：官方开源 AI Agent 框架，我给它套了个 macOS 外壳
内容提要
DeepSeek Harness是官方开源的AI Agent框架，作者为其开发macOS桌面客户端，解决终端启动门槛。客户端采用Electron壳加宿主进程，支持双击打开、自动分配端口，打包为dmg并配置CI自动化。目前为POC，未签名公证，适合自用演示，源码和dmg已公开。
延伸解读
为什么不能只打包静态文件
作者最初尝试将 Vite 构建的静态文件直接打包进客户端，但发现界面功能依赖宿主进程动态提供插件 bundle、接口桥和 WebSocket 流，官方配置也明确拒绝裸静态文件启动。这提醒我们，对于依赖后端服务的 Web 应用，简单打包前端资源往往不够，必须确保后端进程同时运行。
进程管理与端口分配细节
客户端采用 Electron 壳加宿主进程的架构，端口使用 `--port 0` 让系统自动分配，避免冲突；窗口关闭时先 SIGTERM 再 SIGKILL，确保子进程被彻底清理。这些细节对保证应用稳定性和避免僵尸进程很重要，值得开发者借鉴。
当前限制与分发门槛
该客户端目前是 POC，未签名未公证，首次打开需右键选择打开才能绕过 Gatekeeper。此外，壳内未内置宿主代码，运行时需从安装目录向上查找仓库 checkout，因此不适合直接分发给普通用户。正式分发需签名公证，并将宿主和 Node 运行时打包进应用资源。
Q&A
DeepSeek Harness 是什么？
DeepSeek Harness 是 DeepSeek AI 官方开源的 AI Agent 框架，采用 MIT 协议，代码在 GitHub 上完全公开。其核心设计是“一切皆插件”，模型接入、工具注册、会话日志甚至 agent 主循环都可以通过插件方式替换，由 Cordis 框架组合装配。
如何快速启动 DeepSeek Harness 的 Web 界面？
通过 npm 执行 `npx @deepseek-ai/dsh web`，然后浏览器访问 http://127.0.0.1:3080，填入 DeepSeek API Key 并选择工作区即可使用。
为什么不能只打包静态文件作为桌面客户端？
因为 Vite 构建出的静态文件只是外壳，实际功能依赖宿主进程动态提供，包括插件 bundle 服务、接口桥和 WebSocket 流。官方在构建配置中明确禁止裸静态文件启动，因此必须采用 Electron 壳加宿主进程的架构。
macOS 客户端是如何处理端口和进程管理的？
客户端使用 `--port 0` 让系统自动分配端口，避免冲突；窗口关闭时先发送 SIGTERM，超时后再 SIGKILL，确保宿主子进程被彻底清理，不留僵尸进程。
如何构建 macOS 客户端？
在 desktop 目录下执行 `npm run dist:mac:arm64`，使用 electron-builder 生成 .app、dmg 和 zip 文件。也可以从 GitHub Actions 自动构建，推送代码到 desktop/ 目录或打 tag 即可触发。
当前 macOS 客户端有哪些限制？
目前是 POC，未签名未公证，首次打开需右键→打开才能通过 Gatekeeper；且未内置宿主代码，运行时需从安装目录向上查找仓库 checkout。正式分发需签名公证，并将宿主和 Node 运行时打包进应用。
在哪里可以获取 DeepSeek Harness 的桌面客户端？
官方仓库在 github.com/deepseek-ai/deepseek-harness；作者加了桌面客户端的 fork 在 github.com/leonhe/deepseek-harness，其中 desktop/ 目录是客户端源码，dist/ 下有现成的 dmg。
