桌面套壳工具yanxi-lu/dsh-desktop

dsh-desktop

DeepSeek Harness（dsh）的 Windows 桌面套壳：一键启动、更新、重启与托盘驻留。

Harness 官方上游：deepseek-ai/deepseek-harness。

功能

- 一键启动：自动拉起本机 dsh web --no-open（127.0.0.1:3080）并在桌面窗口中使用
- 桌面一键启动：安装器自动创建“DeepSeek Harness”桌面图标和开始菜单快捷方式
- 官方版本检查：启动后查询 DeepSeek 官方 npm latest 版本，发现新版时在控制栏提示
- 版本列表与切换：展示官方 npm 已发布版本，可选择指定版本安装、重装或回退
- 一键安装/更新 Harness：安装官方 npm 包 @deepseek-ai/dsh@latest，完成后自动恢复服务
- 预发布版启动兼容：自动读取 Harness 0.1.2+ 输出的一次性 Token URL，兼容旧版裸地址且不把 Token 发送到桌面控制页
- 可视化用量统计：提供调用次数、实际总 Tokens、缓存命中率、会话数、费用概览，以及按小时/日期趋势、模型统计、会话统计和可分页的最近调用
- 官方账户余额：自动复用 Harness 已配置的 DeepSeek Key，展示总余额、充值余额、赠送余额和账户可用状态；Key 不进入页面
- 分时与自定义估价：按每次调用的时间和实际模型自动套用官方价格，也可固定高峰/空闲档或设置本机自定义单价
- Node.js 一键安装：目标主机未安装 Node.js 时，可通过 Windows Package Manager 一键安装官方 Node.js LTS
- 可见安装进度：首次安装下载内容较多时每 5 秒更新状态，可随时取消，最长等待 15 分钟
- 首次启动耐心等待：Harness 初次初始化可能超过 30 秒，桌面壳最多等待 120 秒并持续显示用时
- 双重重启：可单独重启 Harness 服务，也可重启整个桌面应用
- 独立控制栏：即使 Harness 页面异常，顶部更新/重启按钮仍可操作
- 首次引导：未装 dsh/Node 时显示引导页，可一键安装或复制安装命令
- 托盘驻留：关闭窗口后服务在后台运行，托盘可重新打开；「退出」会连同 dsh 进程树一起结束
- 单实例：重复启动只会聚焦已有窗口
- 崩溃恢复：dsh 意外退出时弹窗提示，可一键重启服务

安装

1. 可预先安装 Node.js（https://nodejs.org）；若未安装，首次启动页可点击“一键安装 Node.js LTS”
2. 可预先安装 dsh：npm install -g @deepseek-ai/dsh；也可启动桌面壳后点击“一键安装/更新 dsh”
3. 从 GitHub Releases 下载 dsh-desktop-setup-x.y.z.exe，安装完成后双击桌面“DeepSeek Harness”图标即可

安装包未做代码签名，SmartScreen 提示时选「仍要运行」。

图标

应用图标与托盘图标来自项目根目录的高清源图（2048×2048 鲸鱼娘 PNG）。
npm run icon（scripts/gen-icon.ps1）会从源图重新生成：

- assets/icon.ico — 多尺寸 ICO（16~512），嵌入 exe、安装包与桌面/开始菜单快捷方式
- assets/icon.png — 1024×1024 应用 PNG
- assets/tray.png — 32×32 托盘图标

本项目为非官方套壳，与 DeepSeek 无隶属关系。

开发

npm install
npm test        # 单元测试(vitest)
npm start       # 开发运行
npm run icon    # 重新生成图标
npm run dist    # 打 NSIS 安装包

更新机制

- 版本来源：固定查询和安装 DeepSeek 官方发布的 @deepseek-ai/dsh@latest。
- 更新 Harness：主窗口顶部或托盘点击“更新 DeepSeek Harness”，应用会停止当前服务、通过本机配置的 npm 镜像安装官方包，再自动启动新版服务。首次下载通常需要数分钟，界面会显示实时进度并支持取消。
- 切换 Harness 版本：点击顶部“用量/版本”，从官方 npm 版本列表中选择一个版本安装。回退版本可能与较新版本生成的 ~/.dsh 配置不兼容，重要环境请先备份。
- 为什么不直接 git pull：官方源码运行还需要 Git、pnpm、依赖安装和完整构建；普通用户使用官方 README 推荐的 npm 发布包更稳定。Git 仓库只作为官方源码上游，不作为终端用户的运行目录。

用量与预估价格

- 数据来源：只从 Harness 本机会话日志提取时间、Provider、模型和 usage 元数据，不返回或展示提示词、回复正文、工具参数、工作目录或 API Key。
- 统计范围：支持今天、近 7 天、近 30 天和自定义起止日期，并可按 Provider/模型筛选。概览展示调用次数、实际总 Tokens、缓存命中率、涉及会话和预估费用。
- 统计明细：趋势图今天按小时、其他范围按日期展示四类 Token 与费用；另有模型统计、按总 Tokens 排序的会话统计和最近模型调用列表。最近调用由主进程分页查询，支持每页 10/20/50/100 条。会话统计使用截断后的会话 ID，不展示对话标题或正文。Harness 日志没有稳定的 HTTP 状态/延迟字段，因此不展示虚构的成功率或响应耗时。
- 图表实现：趋势图使用随安装包本地分发的 Apache ECharts 6.1.0，支持双轴、平滑曲线、悬浮明细、图例开关、滚轮缩放和窗口自适应，不依赖在线 CDN。第三方许可证随图表文件一同保留。
- 去重口径：同一 turn/step 的流式 usage 与最终消息只采用最终值，与 Harness 自身 tokenUsage 投影规则一致，避免重复计数。
- 估价模型：支持 DeepSeek-V4-Flash-0731、DeepSeek-V4-Pro-0813 和 DeepSeek-V4-Flash-Vision-Exp。
- 官方分时价格：默认依据每条调用记录的北京时间自动选择高峰时段（9:00–12:00、14:00–18:00）或空闲时段，并按日志中的实际 DeepSeek 模型匹配单价；未知模型使用用户选择的兜底模型。
- 自定义价格：可分别设置缓存命中、缓存未命中和输出的“元/百万 tokens”单价，配置只保存在本机桌面壳。
- 价格来源：DeepSeek API 官方定价，当前内置价格核对日期为 2026-08-22。
- 重要说明：估算值不是官方账单。非 DeepSeek 模型、第三方代理加价、失败重试、分叉或导入会话都可能造成差异；实际费用以服务商账单为准。

官方账户余额

- 查询来源：固定请求 DeepSeek 官方 GET https://api.deepseek.com/user/balance 接口，不支持第三方中转服务余额。
- 展示内容：账户是否可用，以及接口返回的人民币/美元总余额、充值余额和未过期赠送余额。
- 密钥来源：自动按 Harness 的优先级解析启动环境、$DSH_HOME/.credentials.yaml、项目 .env 和用户 .env 中现有的 DEEPSEEK_API_KEY，页面不再要求重复输入。
- 安全说明：API Key 只在主进程内解析并发送到 DeepSeek 官方接口，不会进入页面、日志或统计结果，桌面壳也不会额外保存副本。

手动验收清单

- [ ] 未装 dsh → 引导页，状态显示正确，复制命令可用
- [ ] 未装 Node.js → 点击一键安装 LTS → 安装完成后无需重启电脑即可继续安装 dsh
- [ ] 装好 dsh 点「重新检测」→ 自动进入主窗
- [ ] 启动后检测官方 npm latest → 有新版时控制栏提示当前版与最新版
- [ ] 顶部「更新 Harness」→ npm 升级后版本号刷新，服务恢复
- [ ] 顶部「用量/版本」→ 概览、时间筛选、模型筛选、趋势图、模型/会话/最近调用明细和官方版本列表正常显示
- [ ] 自定义时间范围 → 首尾日期均计入统计，最近模型调用可连续翻页且跨页不重复
- [ ] Harness 已配置官方 DeepSeek Key → 查询余额后总余额、充值余额、赠送余额和账户状态正确显示
- [ ] 选择指定 Harness 版本 → 安装完成后当前版本刷新且服务恢复
- [ ] 顶部「重启 Harness」→ 服务停止并重新启动，页面恢复
- [ ] 顶部「重启应用」→ 桌面壳与 Harness 均正常重新启动
- [ ] 主窗关闭 → 托盘驻留，dsh 进程仍在
- [ ] 托盘「退出」→ node/dsh 进程树被杀净
- [ ] 二次启动 → 聚焦已有窗口
- [ ] 安装包安装/卸载正常，桌面“DeepSeek Harness”快捷方式存在且可启动

常见问题

- 端口 3080 被占用：若被其他程序占用，轮询可能误判就绪；先释放端口再启动
- 提示 30000ms 内未就绪：这是 0.2.1 及更早版本等待时间过短造成的误判；升级桌面壳至 0.2.2 后会等待 120 秒并显示启动进度
- Node.js 一键安装不可用：该功能依赖 Windows 10/11 的 winget；请从 Microsoft Store 安装“应用安装程序”，或从 nodejs.org 手动安装 LTS
- 用量显示为 0：请先在较新的 Harness 中完成至少一次模型对话，确认时间/模型筛选范围后点击“刷新统计”
- 余额无法查询：余额功能只支持 DeepSeek 官方 API Key。确认密钥有效、网络可访问 api.deepseek.com，并避免使用第三方中转服务的 Key
- 主窗空白：dsh 服务正常时按 Ctrl+Shift+I 打开开发者工具查看报错（开发模式）
- DSH_BIN/DSH_HOME：可用环境变量显式指定 dsh 位置，优先级高于 PATH