桌面客户端 JeffioZ/dsh-box

[!IMPORTANT]
DeepSeek 官方桌面版已发布，DSHBox 使命完成。 当初做这个项目，是因为 dsh 只有 Web 和 CLI；现在官方有了桌面版，推荐直接使用：https://www.deepseek.com/harness/

已发布的版本仍可正常使用与下载，但不会再开发新功能。谢谢大家。

DSHBox

English · 为什么做 DSHBox · 架构 · 开发指南 · 故障排查 · 安全模型

DSHBox（包名 dsh-box）是 DeepSeek Harness（dsh）的跨平台桌面外壳，基于 Tauri v2、Rust 与原生 HTML/CSS/JavaScript。主界面直接加载官方 dsh web，外壳负责运行环境、窗口、托盘、更新与本地系统集成，不 fork 或 patch dsh。

[!IMPORTANT]
发布产物保持未签名，系统可能要求手动放行。详情见安全模型。

快速开始

从 Releases 下载对应平台的成品，按下方“安装与首次启动”运行。首次启动会引导准备运行时和配置模型。

从源码构建时，先安装 Rust 1.85+、Node.js ^22.19.0 或 >=24.0.0，以及对应平台的 Tauri v2 系统依赖。Windows 构建：

git clone https://github.com/JeffioZ/dsh-box.git
cd dsh-box
npm ci
npm run check
pwsh -NoLogo -NoProfile -File .\build.ps1

Windows 产物位于 dist\DSHBox.exe。macOS/Linux 的构建命令和依赖说明见开发指南。

功能

| 能力 | 说明 |
| 开箱即用 | 自动检测 Node.js、安装 dsh，并在 Windows 缺少 WebView2 时引导安装 |
| 服务生命周期 | 系统分配端口回退、外部 dsh 安全接入、进程树清理、服务看门狗和页面心跳恢复 |
| 桌面体验 | 自绘标题栏（含余额 chip）、系统托盘、通知、窗口位置记忆、Windows 11 贴边布局浮层（Win10 自动回退）、深浅色和中英双语 |
| 安全更新 | dsh/Node 事务化更新和中断恢复；Windows 应用附件按精确 tag 与 SHA-256 校验 |
| 本地文件菜单 | 默认打开、VS Code/记事本打开、文件管理器定位、复制路径与 UTF-8 文本 |
| 插件管理 | 通过官方 dsh plugin 搜索、安装、卸载与更新；首次内置插件可明确取消 |
| 用量与余额 | 会话 token 按日/模型聚合、月历热图、最近 14 天与模型下钻；供应商余额与订阅额度卡片，后台周期监测、瞬错保旧与低余额预警 |
| 便携模式 | Windows exe 同级放置 portable.txt，外壳配置与运行时改存相邻 data/；dsh 会话和凭据仍使用 $DSH_HOME |

平台

| 平台 | 架构 | 最低环境 | 发布形式 |
| Windows | x64 | Windows 10；WebView2 Runtime | 单个 DSHBox.exe |
| macOS | arm64 / x64 | macOS 13.5+ | 未签名 dmg |
| Linux | x64 / arm64 | WebKitGTK 4.1 及兼容发布产物的 glibc；最低发行版尚未实机验证 | zip |

Windows 是主要本地测试平台；五个目标由 GitHub Actions 构建。Linux 上 dsh 的 Landlock 需要内核 5.13+，不满足时由 dsh 自身降级。

安装与首次启动

从 Releases 下载对应产物：

- Windows：运行 DSHBox.exe。
- macOS：把应用拖入 Applications。若 Gatekeeper 拦截，按住 Control 点击应用并选择“打开”，或在“系统设置 → 隐私与安全性”中允许。
- Linux：解压后运行 DSHBox；请先安装发行版要求的 WebKitGTK 4.1 依赖。

首次启动会准备运行时（安装过程可随时取消，不会退出应用），然后显示首次配置页。配置页所有项都可保持默认或直接跳过——DeepSeek API Key 也可留空，之后在 dsh 自己的设置中填写：

1. API Key 写入 dsh 的 $DSH_HOME/.credentials.yaml，不会再复制到 DSHBox 的 config.json。
2. 语言与主题写入 dsh 的设置存储（新版 dsh 为 cordis.patch.yml，旧版为 settings.yaml，按已安装版本自动选择），与官方 CLI/Web 界面共享。
3. 开机自启动使用各平台系统机制。
4. 「安装内置插件」默认勾选，但可取消；未勾选时不会自动安装。

之后如需替换或清除密钥，请在 dsh 官方界面（Web 设置或 CLI）中操作；DSHBox 的设置弹窗不收取 API Key。

配置与数据

数据目录

默认数据根目录：

| 平台 | 路径 |
| Windows | %LOCALAPPDATA%\DSHBox |
| macOS | ~/Library/Application Support/com.deepseek.dsh-box |
| Linux | $XDG_DATA_HOME/com.deepseek.dsh-box，未设置时为 ~/.local/share/com.deepseek.dsh-box |

目录内容

- config.json：用户可理解的外壳设置。
- state.json：窗口位置、首次引导和后台维护标记；不建议手工编辑。
- node/、dsh/、package-manager/：DSHBox 管理的 Node、dsh 与固定版本 pnpm。
- npm-cache/、pnpm-store/：安装与插件维护共用的本地包缓存。
- logs/dshbox.log：UTC 日志，超过 2 MiB 轮转为 .old。
- $DSH_HOME：默认 ~/.dsh，由官方 dsh 与 DSHBox 共享，不位于上述数据根目录。

config.json

config.json 支持：

{
"port": 18080,
"api_base": "https://api.deepseek.com",
"language": "zh-CN",
"hide_tool_calls": false,
"hide_balance": false,
"auto_update_plugins": true,
"task_notifications": true,
"usage_token_limit_m": null,
"dsh_update_channel": "latest",
"close_behavior": "tray",
"launch_behavior": "window",
"download_source": "auto"
}

usage_token_limit_m 为每日用量提醒阈值（单位：百万 token；null 或缺省 = 关闭），预计今日 token 用量越过该值时发送一次系统通知（每天至多一次）。dsh_update_channel 可取 latest、预览通道 next 或风险更高的尝鲜通道 alpha；切换通道后可在「检查更新」中升级或降级（切换）到该通道的最新版本。close_behavior 可取 tray / quit，launch_behavior 可取 window / tray，download_source 可取 auto / official / mirror。config.json 与 state.json 职责严格分离，不读取旧文件中的跨界字段。

端口策略

port 是本地托管服务的首选端口，不是必须占用的固定端口。DSHBox 先尝试上次成功端口和该首选端口；均不可用时通过 dsh web --port 0 让操作系统一次分配可用端口，并把结果记入 state.json，不会顺序扫描大段端口。

接入外部 dsh 服务

启动时若在首选端口或 dsh 官方默认端口 3080 发现通过页面与 host.describe 双重校验的外部 dsh，DSHBox 会先询问是否连接并记住该服务指纹。首次运行时该选择优先于本地设置；选择外部服务会暂缓只适用于本地运行时的凭据与插件引导，日后首次改用本地服务时再补充显示。外部模式只负责显示与重连，不会停止、重启或更新该进程，也不会改写其凭据、模型或插件；服务消失时会明确报错，用户可重试或改用本地服务。

环境变量

环境变量优先于 config.json：

| 变量 | 作用 |
| DSH_BOX_ROOT | 覆盖数据根目录 |
| DSH_BOX_PORT | 覆盖监听端口 |
| DSH_BOX_API_KEY | 覆盖 DeepSeek API Key |
| DSH_BOX_API_BASE | 覆盖 API 基地址 |
| DSH_HOME | 覆盖 dsh 官方主目录 |
| DSHD_LANG | 固定 zh-CN 或 en |

API Key 解析顺序为：DSH_BOX_API_KEY → DEEPSEEK_API_KEY → $DSH_HOME/.credentials.yaml。

内置插件

首次引导可选择安装：

- DSH Market（dshmarket）
- DSH File Upload（dsh-file-upload）

同意后，未安装的内置插件会在 dsh 就绪后安装；仍保持内置身份的已安装插件每 24 小时检查一次更新。更换预置插件时，仍由 DSHBox 管理的旧包会迁移到新包；用户曾主动卸载旧包则沿用原选择，不会借换包重新安装。用户主动卸载后，插件页会保留手动重装入口；装回后按普通用户插件管理，不再恢复内置标签或自动更新。安装、更新和卸载都走 dsh plugin CLI；多个变更会合并为一次重启，自动维护只在会话空闲后应用。

插件管理页另有「社区插件」列表，仅提供来源和手动安装入口，不会自动安装或更新；卸载后会重新出现在该列表中。

插件是与 dsh 同环境执行的第三方代码。社区清单、内置或市场收录都不构成安全背书；安装前应核实来源。清单维护规则见 resources/README.md。

开发

要求 Rust 1.85+、Node.js ^22.19.0 或 >=24.0.0，以及对应平台的 Tauri 系统依赖。Windows 推荐 PowerShell 7。

npm install
npm run checkbash
cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --all-targets

Windows 构建与开发： powershell pwsh -NoLogo -NoProfile -File .\build.ps1 pwsh -NoLogo -NoProfile -File .\dev-build.ps1 pwsh -NoLogo -NoProfile -File .\dev-run.ps1

开发模式从本地 4321 端口加载 ui/，只改 UI 不用重编 Rust。完整环境、图标、版本和发布流程见开发指南。

项目结构 text desktop/ ├─ assets/brand/ # 唯一品牌 SVG 源 ├─ ui/ # 无打包器的内置页面、共享样式与双语文案 │ ├─ index.html + startup.* # 启动页与首次配置 │ ├─ control-center.* # 用量与余额/更新/插件/设置/关于（统一弹窗） │ ├─ titlebar.* # 主窗口子 WebView（含余额 chip） │ ├─ tray-menu.html + menu.js # 托盘与菜单交互 │ ├─ edit-context.js # 内置页输入框编辑菜单（撤销/重做/剪贴板） │ └─ common.* + i18n.js # 共享工具、设计 token、文案 ├─ src-tauri/ │ ├─ resources/ # 内置插件清单与页面注入资源 │ └─ src/ │ ├─ bootstrap.rs / lib.rs # 应用装配与公共边界 │ ├─ app_state/ # 配置、状态、JSON/文本持久化 │ ├─ commands/ # 仅做 IPC 来源校验与转发 │ ├─ runtime/ # Node 与 dsh 运行时的检测、安装与就绪 │ ├─ dsh.rs # dsh 服务启动、外部接入与看门狗 │ ├─ control_center.rs # 统一自绘弹窗（用量/插件/设置/更新/关于） │ ├─ titlebar.rs # 标题栏子 WebView 的创建与扩展控制 │ ├─ updater/ # 检查、平台更新与事务恢复 │ ├─ plugins/ # CLI 执行、维护策略与手动操作 │ ├─ usage/ # 用量与余额聚合、缓存与账户监测 │ ├─ tray.rs / tray_menu.rs # 系统托盘与托盘菜单窗口 │ ├─ webview/ # 导航边界、自定义协议与注入 │ └─ platform/windows/ # Windows 专属 WebView2 预检与贴边布局浮层 ├─ scripts/ # 一致性检查、图标、构建辅助 └─ .github/workflows/ # 三平台 CI 与 tag 发布

详细依赖方向和启动时序见架构文档。

项目边界

DSHBox 只通过三条通道与 dsh 协作：

1. 向官方 Web 页面注入受限的初始化/菜单脚本。
2. 读取会话日志，行级合并写入 dsh 设置存储（新版 cordis.patch.yml / 旧版 settings.yaml）与 .credentials.yaml。
3. 调用 dsh web 和 dsh plugin ...。

不 fork dsh、不 patch npm 包、不修改会话格式、不重复实现官方 Web UI。更多取舍见为什么做 DSHBox。

参与与许可

提交前请阅读 CONTRIBUTING.md 和 SECURITY.md。项目代码采用 MIT License；依赖、运行时下载项和品牌资源说明见 THIRD_PARTY_NOTICES.md。