honghuachen/deepseekharness-desktop

DSH Web —— 官方 DeepSeek Harness 桌面容器

一个极薄的跨平台（macOS + Windows）桌面容器：窗口里运行的始终是 deepseek-ai/deepseek-harness 官方 Web 壳，容器本身不做任何业务界面。

核心能力：优先使用本地已装内核秒级启动，后台自动检测并平滑升级官方运行时。

┌─────────────────────────────────────────────────────┐
│  DSH Web.app (Electron 薄壳)                         │
│                                                     │
│  1. 优先校验本地已装内核 (秒级直接拉起，无网络阻塞)   │
│  2. 启动官方 dsh web 服务 (127.0.0.1:)         │
│  3. 窗口加载官方页面 ←—— 界面 100% 官方               │
│  4. 后台静默检测壳/内核/插件更新，侧边栏徽标轻量提醒  │
│  5. 检查更新面板一键平滑升级与版本无感切换           │
└─────────────────────────────────────────────────────┘

设计原则

| 决策 | 理由 |
| --- | --- |
| 壳零业务逻辑，只做「更新 + 拉起 + 开窗」 | 官方迭代飞快，薄壳永不与上游冲突 |
| 运行时按版本号装入独立目录，符号链接切换 | 升级失败秒回旧版；旧版本保留用于回滚 |
| pnpm 构建脚本白名单（allowBuilds）预置 | 只允许 node-pty/koffi 等已知原生模块执行脚本 |
| 便携 Node v22 随 APP 分发 | 不依赖系统 Node 版本；ABI 与原生模块一致 |
| 数据目录独立于壳 | 会话数据在 ~/.dsh，升级/重装壳均不受影响 |

快速开始

开发模式

npm install          # 安装 Electron 等 devDependencies
npm run fetch-tools  # 下载 vendor/pnpm + vendor/node（便携 Node）
npm start

首次启动会下载官方运行时（约 1–2 分钟，视网络），之后启动只在有新版时才下载。

打包成 APP

npm run dist         # 产出 macOS (dmg/zip) + Windows (NSIS 安装器/zip)

一次构建双平台（electron-builder 交叉打包，Windows 目标在 macOS 上直接构建）：

| 平台 | 产物 |
| --- | --- |
| macOS arm64 | DSH Web--arm64.dmg / -mac.zip |
| Windows x64 | DSH-Web-Setup--x64.exe / -win.zip |

Windows 说明：

- 未签名，首次运行会有 SmartScreen 提示（「仍要运行」即可）；安装器为辅助模式，可选安装目录
- 随包内置便携 node.exe 与 pnpm；版本切换用 NTFS junction（无需管理员权限），受限环境自动回退指针文件
- 任务完成角标以任务栏叠加数字呈现；会话日志解析依赖系统 zstd 命令（如无则角标功能静默降级，可用 scoop install zstd 补上）

更新机制

每次启动，除非已手动固定某个内核版本（见下文）：

1. GET https://registry.npmjs.org/@deepseek-ai/dsh/latest 取最新版本；
2. 与本地激活版本 semver 比较（支持 -rc.N 预发布排序）；
3. 有新版：下载安装到 /runtime/versions/v/，成功后把 runtime/current 符号链接原子切换过去；失败则保留原版本继续用旧的；
4. 自动清理：仅保留最近 2 个版本（若有手动固定的版本，额外保留它——见下文）。

离线时跳过检测，直接用已装版本；本地无任何版本且离线才报错。

菜单 关于 DSH Web 会同时显示容器版本与内核版本（官方运行时 @deepseek-ai/dsh 的当前激活版本）。

检查更新窗口

菜单栏 DSH Web → 检查更新…（⌘U）打开一个独立窗口，同时覆盖容器和内核两部分：

检查更新窗口：容器卡片显示当前版本以及 GitHub 上是否有新 Release，内核卡片列出全部已发布的 npm 版本，带标签、发布时间和切换按钮

- 容器（壳应用本身）：与本仓库 GitHub Releases 上的最新 tag 比较。
- Windows：接了 electron-updater，可以直接"下载并安装"，装完点"重启并安装"原地替换重启；因为安装包未签名，关闭了运行时的 Authenticode 签名校验（electron-builder.yml 里 win.verifyUpdateCodeSignature: false）。发版时除了安装包本身，还要把 electron-builder 生成的 latest.yml/.blockmap 一起传到 Release，否则自动更新查不到新版本。
- macOS：未签名/未公证，Squirrel.Mac 强制要求签名才能自动更新，继续只做检测 + 提供跳转到 Release 页面的按钮。
- 内核（@deepseek-ai/dsh）：按时间倒序列出 npm 上发布过的全部版本，标注 alpha / rc（或者一旦官方真的发布正式版，stable），npm latest dist-tag 对应的那个版本标"推荐"。可以切换到列表里的任意版本；切换会短暂重启后台服务，并实时展示安装日志。
- 切换版本后会固定它：用户可以根据需要自由切换到列表中的任意版本，切换后始终保持固定，prune() 清理也不会碰当前激活与固定的版本。
- 容器和内核两边的检测互相独立——GitHub API 抖动只会让容器那张卡片显示"检测失败，点击重试"，不影响内核那边正常工作。

这里的"推荐"指的是 npm 的 latest dist-tag（官方从一开始就在维护这个标签），不是 semver 里"无预发布后缀"那个概念。截至目前，@deepseek-ai/dsh 发布的每一个版本仍然带 -rc.N/-alpha.N 后缀，还没有真正的正式版——UI 上刻意不用"稳定版"这个词，就是这个原因。

目录布局

/                      # 打包后 ~/Library/Application Support/DSH Web；开发期仓库下 .data/
├── runtime/
│   ├── versions/v0.1.1-rc.2/   # 每个版本一套完整 node_modules
│   └── current -> versions/v0.1.1-rc.2
├── pnpm-store/                 # 内容寻址存储，多版本间去重
├── logs/app-YYYY-MM-DD.log     # 运行日志
└── settings.json               # 用户配置

配置

settings.json（菜单可打开）：

{
"port": 43130,             // web 服务端口，被占用时自动向后试探
"channel": "latest",       // 更新频道（当前为 npm latest）
"autoCheckUpdates": true,  // 后台自动检测更新（壳、内核及插件）
"dshHome": "",             // 留空 = 官方标准 ~/.dsh；可指向自定义目录隔离
"taskBadge": true,         // 会话任务完成后在 Dock/任务栏图标显示完成数量角标
"pinnedKernelVersion": "" // 留空 = 跟随最新版本；在"检查更新"窗口里手动切换版本后会写入这里
}

与第三方壳的数据关系

APP 默认使用官方标准数据目录 ~/.dsh，会话历史与官方 CLI 完全互通。

第三方容器（如旧版 DSH Desktop）可能通过插件市场往 profile 里塞社区插件，
它们常与官方新版本不兼容，会导致 web 服务启动即崩（表现为窗口白屏）。对此本 APP 提供：

管理第三方插件窗口：按 profile 分组列出官方/第三方插件，标注 bundle/补丁层引用位置，可勾选批量移除或检查更新

1. 插件管理器（菜单：DSH Web → 管理第三方插件…）：按 profile 浏览全部插件，
区分官方 / 第三方及其引用位置（bundle、补丁层），勾选后精准移除；
移除前二次确认，原文件自动备份到 profile 目录的 .sanitized-backup-*。
2. 首次启动自动清理：web profile 若被污染则恢复官方默认形态，
保留 Funplay MCP 等官方组件的用户层配置；
3. 崩溃自愈：服务意外退出自动重启；若从未清理过则先清理再重启。

注意：desktop profile 属于旧版 DSH Desktop。移除其中的插件会让旧壳的市场功能失效
（这正是去污染的目的）；建议先退出旧壳再操作。如需安装插件，请用官方方式：
dsh plugin --profile  add 。

社区插件市场

菜单 DSH Web → 社区插件市场…（⌘⇧M，也可在"管理第三方插件"窗口内切换到该 Tab）打开：

社区插件市场窗口：按分类浏览严选 Top 10 社区插件，支持搜索、跳转开源地址与一键安装到指定 profile

- 汇聚社区主流插件市场（dsh-1024store、dsh-market）的高星、高安装量插件，按 11 个分类
（工具与能力、UI 增强、开发与运行时、技能包、会话与消息、模型与接入、工作流自动化、
记忆管理、主题外观、通知集成、趣味娱乐）分别严选 Top 10，同一 GitHub 仓库/包名的重复收录会去重合并；
- 支持按插件名称、中文功能描述、作者或关键词实时搜索，也可按分类筛选；
- 已安装的插件会在卡片上标注，避免重复安装；选择目标 profile 后点"一键安装"即可写入对应
package.json 依赖与 dsh.profile.bundles，无需手动编辑文件；
- 点击插件名称或「开源地址」徽标，在系统默认浏览器打开其 GitHub/npm 主页；
- 市场数据本地缓存 12 小时；网络不可用或接口异常时无缝降级为内置的 Top 100 种子数据，
市场列表始终可用。

Token 用量统计（成本估算）

菜单 DSH Web → Token 用量统计…（⌘⇧T）打开一个独立窗口，统计 ~/.dsh/sessions 下所有会话的 token 用量与估算花费：

Token 用量统计窗口：按模型分组视图，显示总 token 数、估算费用、缓存命中率，以及每个模型的输入/输出/缓存分项

- 时间范围：今日 / 昨天 / 本周 / 本月 / 全部 / 自定义区间
- 分组维度：按项目（沿 .git 向上归并到仓库根，支持 worktree）/ 按模型 / 按会话（最多显示 50 条，按最近活跃排序）
- 每行显示 token 总量、缓存命中率、估算费用；按模型/按会话额外显示 输入/输出/缓存写入/缓存读取 的分项花费
- 点击项目/会话行会在 Finder（Windows 上是资源管理器）里打开对应目录
- 窗口打开后每 60 秒自动重新扫描一次

费用估算基于本地可编辑的定价表：首次打开会把内置的 pricing.default.json 拷贝一份到应用数据目录下的 pricing.json，之后只读写这份用户副本（不会被应用更新覆盖）。DeepSeek Harness 可以路由到任意 provider/模型（社区实测出现过 OpenRouter、SenseNova、Zhipu、Google 等各家模型），这份定价表只内置了 DeepSeek 官方模型；其余模型会显示"未知定价"，需要自己按同样的 JSON 结构补充单价。DeepSeek 官方 API 按 UTC 高峰/非高峰时段分时计价，这里只取"非高峰"（较低）价位做单一近似估算，费用是 ≈ 估算值，不是精确账单。

性能与跨平台：解压 .zstd 会话日志优先使用系统安装的 zstd 命令行（实测比纯 JS 快一个数量级），没有的话（典型是没额外装过命令行工具的 Windows 机器）自动落回纯 JS 的 fzstd 库，两条路径都不依赖任何原生编译，保证 Windows 上也能正常工作。整个扫描/解压/解析过程跑在独立的 worker 线程里，不会阻塞主进程或界面。

注意事项

- 不要同时运行两个 DSH 容器（如旧的 DSH Desktop.app）：两者共用 ~/.dsh 会话数据，并行写有风险。迁移到本 APP 后建议退出/删除旧壳。
- 默认端口 43130，避开旧 DSH Desktop 的 43120。
- 原生模块（node-pty、koffi）全部使用官方 prebuilt 二进制，无需 Xcode 命令行工具。
- 如需分发给别人，配置 Apple 签名（CSC_LINK 环境变量）后重新 npm run dist。

工程结构

src/main/
├── main.js              # 启动编排、窗口、菜单、生命周期、崩溃自愈
├── config.js            # 路径与常量（registry URL、构建白名单）
├── updater.js           # 更新引擎：检测/安装/原子切换/清理（纯 node，可测）
├── kernel-versions.js   # 拉取 @deepseek-ai/dsh 在 npm 上全部已发布版本（纯 node，可测）
├── shell-update.js      # 查 GitHub Releases 判断容器是否有新版（纯 node，可测）
├── shell-auto-updater.js # 容器自动更新：封装 electron-updater（仅 Windows）
├── kernel-switch.js     # 内核版本切换状态机：安装 → 激活 → 落盘 pin（纯 node，可测）
├── update-window.js     # 检查更新窗口（容器+内核）+ 其 IPC
├── runner.js            # 官方服务进程管理：拉起/双重健康检查/优雅退出
├── plugin-guard.js      # 第三方插件守卫：外科手术式恢复官方 profile
├── plugin-manager.js    # 第三方插件管理器窗口
├── badge.js             # 任务完成 Dock/任务栏角标监听
├── semver.js            # 预发布感知的版本比较
├── status-window.js     # 启动进度窗口（纯文本，非产品界面）
├── logger.js            # 文件日志
└── token-usage/         # Token 用量统计：扫描/解压/解析/去重/聚合/定价/统计窗口
├── scanner.js        # 递归找 session.jsonl(.zstd)
├── decompress.js     # 优先系统 zstd，兜底纯 JS fzstd
├── parser.js         # 解析会话事件为用量记录
├── dedup.js          # 按 requestId 去重（流式快照会重复写）
├── aggregator.js     # 按项目/模型/会话聚合 + 估算费用
├── pricing.js        # 定价表加载（内置默认 + 用户可编辑副本）
├── cache.js           # 按文件 mtime/size 的增量缓存
├── scan-worker.js     # worker 线程里跑实际扫描，不阻塞主进程
├── service.js         # 编排以上各步
├── window.js          # 统计窗口 + IPC
└── stats-window.html  # 统计窗口 UI
scripts/
├── fetch-tools.mjs        # 构建期下载 pnpm/便携 Node 到 vendor/
├── e2e-update-test.mjs    # 无头端到端测试（真实 registry 全链路）
├── test-plugin-update.mjs # 第三方插件更新逻辑自测
├── test-token-usage.mjs   # Token 用量统计模块自测（含真实文件解压回归）
├── kernel-versions-test.mjs # npm 版本列表解析/分类/排序自测
├── shell-update-test.mjs  # GitHub Releases 更新检测自测
├── kernel-switch-test.mjs # 内核切换状态机自测（含 pin / 失败不改状态）
├── badge-test.mjs         # 任务完成角标自测
├── plugin-guard-test.mjs  # 插件守卫自测
├── repair-session.mjs     # 修复损坏的 session.jsonl(.zstd) 序号
└── verify-session-file.cjs # 校验 session 文件的 zstd 分帧/序号连续性

测试

npm test          # 快速回归套件：角标 / 插件守卫 / 插件更新 / Token 用量统计 / 内核版本列表 / 容器更新检测 / 内核切换（无网络依赖）
npm run test:e2e  # 端到端更新流程测试（真实连 npm registry，较慢）

贡献

欢迎提 Issue / PR。提交前请先看 CONTRIBUTING.zh.md（含开发流程与提交信息规范）。

许可协议

MIT