桌面外壳 qq984876303/deepseek-DSH-Desktop

DSH Desktop

macOS 版 DeepSeek Harness（dsh）桌面外壳。

本文档为双语：每个章节先给出英文，再给出中文对照。

Run (dev) · 运行（开发模式）

npm install
npm start

The Electron main process spawns the published @deepseek-ai/dsh CLI (dsh web,
run as a Node process via ELECTRON_RUN_AS_NODE) and a BrowserWindow loads the
served UI. No need to clone or build the dsh monorepo from source — the published
npm package already bundles the web frontend.

- First launch shows a setup window for the DeepSeek API key. It is encrypted with
macOS Keychain (Electron safeStorage) and stored under
~/Library/Application Support/DSH Desktop/apikey.
- dsh home (DSH_HOME) is redirected to
~/Library/Application Support/DSH Desktop/dsh-home (profiles, session log,
installed plugins).
- The main process starts dsh web --port 0 (OS picks a free port), parses the
printed URL, and loads it.

中文 Electron 主进程会拉起已发布的 @deepseek-ai/dsh CLI（dsh web，通过 ELECTRON_RUN_AS_NODE 以 Node 进程方式运行），再由 BrowserWindow 加载它提供的 Web UI。无需克隆或从源码构建 dsh 的 monorepo——已发布的 npm 包已经自带前端界面。

- 首次启动会弹出设置窗口，用于录入 DeepSeek API key。该 key 通过 macOS 钥匙串（Electron safeStorage）加密，保存在 ~/Library/Application Support/DSH Desktop/apikey。
- dsh 主目录（DSH_HOME）重定向到 ~/Library/Application Support/DSH Desktop/dsh-home（存放配置档、会话日志、已安装插件）。
- 主进程启动 dsh web --port 0（由系统分配空闲端口），解析其打印出的 URL 并加载。

Features · 功能特性

- Settings panel — re-enter or clear the API key anytime from the app menu (DSH Desktop → Settings…, or ⌘,). No more deleting files by hand.
- Ollama local backend — switch the model backend to Ollama and run models entirely on your machine, no API key required. The shell points dsh's OpenAI- compatible provider at http://localhost:11434/v1; pick the model name inside the
dsh Web UI.
- Native macOS menu — application / edit / view / window / help menus, with About, Settings, developer tools, and a direct link to the GitHub repo.
- Dark mode — follows the system appearance by default, or force Dark / Light from the View menu.
- Update check — unsigned apps can't self-update via Sparkle, so the Help menu checks the latest GitHub Release and opens the download page when a newer version exists.

功能特性

- 设置面板 —— 随时从应用菜单（DSH Desktop → 设置…，或 ⌘,）重新录入或清除 API key，不用再手动删文件。
- Ollama 本地后端 —— 把模型后端切到 Ollama，模型全部跑在本机，无需 API key。
外壳会把 dsh 的 OpenAI 兼容服务商指向 http://localhost:11434/v1；模型名在
dsh Web UI 里选。
- 原生 macOS 菜单 —— 应用 / 编辑 / 视图 / 窗口 / 帮助菜单，含关于、设置、开发者工具，以及直达 GitHub 仓库的入口。
- 深色模式 —— 默认跟随系统外观，也可在视图菜单里强制深色 / 浅色。
- 更新检查 —— 未签名应用无法通过 Sparkle 自更新，因此帮助菜单会查询最新的 GitHub Release，发现新版本时打开下载页。

Build from source · 本地重建 dmg

npm run dist # outputs: out/DSH Desktop-<version>-arm64.dmg (and -x64.dmg)
English — Prerequisites
- macOS（推荐 Apple Silicon / arm64；也会产出 x64 版本）。
- Node.js 18+（本项目用 Node 22 构建）和 npm。
- 约 1.5 GB 空闲磁盘，留给 node_modules 和构建产物。

English — Steps
1. 克隆并进入项目： sh
git clone https://github.com/qq984876303/deepseek-DSH-Desktop.git
cd deepseek-DSH-Desktop
2. 安装依赖（这一步也会下载 Electron 二进制和 dsh 运行时包）： sh
npm install
如果安装后 node_modules/electron/dist 不见了，手动拉取二进制：
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js
3. 打包 dmg： sh
npm run dist
4. 在 out/ 里找到产物： DSH Desktop-<version>-arm64.dmg（还有 -x64.dmg）。

English — Notes
- identity: null 会产出未签名版本。首次打开时，macOS Gatekeeper 会拦截——右键 App → 打开，放行一次即可。
- asar 是故意关掉的，这样拉起的 Node 进程才能读取磁盘上的 dsh 文件。
- .dmg 不会提交到这个仓库（超过 GitHub 100 MB 文件上限）。请从 Releases 页面下载。
- API key 绝不打包进去——它只存在你本机的钥匙串里。

中文 — 前置条件
- macOS（推荐 Apple Silicon / arm64；也会同时产出 x64 版本）。
- Node.js 18+（本项目使用 Node 22）与 npm。
- 约 1.5 GB 空闲磁盘空间，用于 node_modules 与构建产物。

中文 — 步骤
1. 克隆并进入项目： sh
git clone https://github.com/qq984876303/deepseek-DSH-Desktop.git
cd deepseek-DSH-Desktop
2. 安装依赖（这一步会下载 Electron 二进制以及 dsh 运行时依赖包）： sh
npm install
若安装后 node_modules/electron/dist 为空，可手动补全二进制：
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js
3. 打包 dmg： sh
npm run dist

4. 在 out/ 目录下查看产物： DSH Desktop-<version>-arm64.dmg（以及 -x64.dmg）。

中文 — 说明
- identity: null 表示打包出的是未签名版本。首次打开时 macOS 的 Gatekeeper 会拦截——右键 App →「打开」即可放行一次。
- asar 被刻意关闭，以便拉起的 Node 子进程能直接读取磁盘上的 dsh 文件。
- .dmg 不会提交进本仓库（超过 GitHub 单文件 100 MB 上限）。请从 Releases 页面下载安装包。
- API key 绝不会被打进包里——它只存在于你本机的钥匙串中。

Architecture notes · 架构说明

- src/main.js — boot flow: API key → spawn dsh → parse URL → load window.
- src/preload.js — contextBridge for the setup window.
- src/setup.html — first-run API key entry form.
- build/entitlements.mac.plist — hardened-runtime entitlements (used when signing).
- build/entitlements.mac.sandbox.plist — App Sandbox entitlements (future use).

- src/main.js —— 启动流程：读 API key → 拉起 dsh → 解析 URL → 加载窗口。
- src/preload.js —— 设置窗口的 contextBridge 桥接。
- src/setup.html —— 首次启动录入 API key 的表单页。
- build/entitlements.mac.plist —— Hardened Runtime 权限（签名时使用）。
- build/entitlements.mac.sandbox.plist —— App Sandbox 权限（预留，未来启用）。

Sandbox caveat (important) · 沙箱注意事项（重要）

dsh 是一个代码执行型 harness：它会拉起子进程（shell、PTY、LSP）。macOS 的 App Sandbox 会限制任意子进程拉起，因此 App Sandbox 与完整的代码执行型智能体在根本上存在冲突。

- v1 版本默认不开启 App Sandbox，而是依赖 dsh 自身的审批策略 + hardened-runtime 权限。这一点已体现在构建配置中。
- 仓库中提供了 entitlements.mac.sandbox.plist 以备将来启用。一旦启用，需要把 DSH_HOME 重定向进沙箱容器，并且会限制 shell 执行类工具的能力。
- dsh 自带的 Landlock 沙箱仅支持 Linux，在 macOS 上本就是空操作（已发布的包在 macOS 上无需它也能正常运行）。