dsh-hub

@marecgents/dsh-hub —— DeepSeek Harness（dsh）的桌面端框架：以原生 WebView2 窗口运行 dsh Web UI，提供托盘、主题同步、窗口记忆、右侧栏与系统通知。

版本状态（2026-08-16）：0.0.1-rc.14 是 WebView2 壳的最终 rc 版本（dev-v1 分支已冻结）。rc.13 发布后曾暴露全新环境首启崩溃 bug（ERR_MODULE_NOT_FOUND，见 docs/关键踩坑记录.md#33），rc.14 为修复版。正式版将在 Tauri 2.x 壳（dev-v2）迁移完成并达到良好体验后发布——多端支持（Windows / macOS / Linux）、~10MB 体积、自定义壳 UI。迁移期间插件层（client + config/workspace API）原样保留，壳层整体重写（见 docs/dsh桌面端技术路线-2026-08-16.md）。

[]()

分支状态

分支	状态	说明
`main`	发布分支（唯一合并目标）	当前 = `0.0.1-rc.14`（WebView2 最终版，含全新环境首启修复）
`dev-v1`	永久冻结（WebView2 时代存档）	不再接收任何更新/同步；历史收尾 = rc.13 / rc.14
`dev-v2`	唯一开发分支（Tauri 2.x 壳）	所有更新在此开发，merge 只到 main

功能特性

原生桌面化：用系统 WebView2 打开 dsh Web UI，无浏览器标签页干扰。
品牌化 Splash：主题色 + dsh logo + spinner 覆盖从窗口打开到 SPA 首绘的加载过程，无白/黑闪块。
系统托盘：
- 显示主界面 / 隐藏主界面（按窗口状态动态切换）
- 打开工作区（自动激活并前置 Explorer）
- 新建任务（走官方 ctx.workspaces.startSession 流程，UI 即时刷新）
- 退出（写 quit.marker 后干净退出，避免误判崩溃重启）
窗口状态记忆：最大化状态、分辨率、主题等持久化到 $DSH_HOME/dsh-hub/config.json。
主题同步：MutationObserver 事件驱动，标题栏深浅色实时跟随 dsh 页面主题（koffi FFI 直调 Dwm API，~1ms）。
设置卡片：dsh 设置 → 插件页提供桌面壳配置（窗口尺寸 / 主题 / 托盘行为 / 会话完成通知 / 提示音 / 多实例开关 / 界面皮肤 / 背景图）。
多实例保护：启动时检测已有 dsh 实例（任意端口），默认拒绝共存以防会话数据损坏；确需共存可在设置中显式开启（附危险警告）。
右侧栏：概览（Token 统计）、文件树、Git 变更三页；收起后保留窄栏快捷按钮。
置顶会话：会话行 hover 置顶（同名会话安全跳过、不误标）；置顶区常驻列表顶部（可独立滚动）；持久化于 $DSH_HOME/dsh-hub/pins.json（localStorage 兜底）。注：多标签/多实例下 pins 为整体替换语义（最后写者胜）；同标签内 PUT 依赖 fetch 顺序保序。
会话完成通知 + 事件提示音：
- 提示音（独立开关）：用户提交问题（开始音）、任务正常完成（完成音）、AI 请求批准（需要你）、任务出错（出错音）——四段原创合成音效（scripts/synthesize-sounds.mjs 生成，无第三方素材），窗口隐藏到托盘时依然可闻。
- Toast：任务完成/出错时弹 Windows 原生通知，点击恢复窗口；30s 冷却。聚焦会话策略：正在查看的会话完成时只响提示音不弹 Toast（结果就在眼前）；后台会话完成或窗口隐藏时仍弹 Toast。
独立进程身份：桌面壳以 dsh-hub.exe（应用）+ dsh-hub-guard.exe（守护）运行，任务管理器显示 DeepSeek Harness Hub 图标与名称，不再是 "Node.js JavaScript Runtime"（首次启动自动生成并缓存，Node 升级自动重建）。
启动门控：仅当通过本项目启动时注入桌面壳与插件页面；普通 dsh web 完全不受影响。

安装与使用

方式一：自动安装（推荐）

按需选择版本（--allow-scripts 允许 dsh-hub 与其原生依赖 koffi 的安装脚本，避免 npm 安全机制拦截导致缺少快捷方式/原生模块的警告）：

# 正式版（稳定，推荐）
npm i -g @marecgents/dsh-hub --allow-scripts=@marecgents/dsh-hub,koffi

# 预览版（rc，尝鲜最新功能）
npm i -g @marecgents/dsh-hub@rc --allow-scripts=@marecgents/dsh-hub,koffi

版本	安装命令	说明
正式版（latest）	`npm i -g @marecgents/dsh-hub --allow-scripts=@marecgents/dsh-hub,koffi`	稳定版本，适合日常使用
预览版（rc）	`npm i -g @marecgents/dsh-hub@rc --allow-scripts=@marecgents/dsh-hub,koffi`	候选版本（预览版），包含最新功能，可能有未完善之处

预览版以 npm rc 标签发布，不会覆盖正式版；随时可切换到正式版重装。

提示：若忘记加 --allow-scripts，npm 会警告 install-scripts blocked（postinstall 未执行）。可执行 npm i -g --allow-scripts=@marecgents/dsh-hub,koffi @marecgents/dsh-hub 补装，或一次性放行后重装：npm config set allow-scripts=@marecgents/dsh-hub,koffi --location=user。

安装脚本会自动检测 dsh / pnpm（缺失则一并安装），并在 Windows 创建桌面快捷方式「DeepSeek Harness」。

启动：

# 方式 A：双击桌面快捷方式（无控制台）
# 方式 B：终端命令（继承输出）
dsh-hub

方式二：手动 / 从源码安装

git clone https://github.com/MarecGents/deepseek-harness-hub.git
cd deepseek-harness-hub
npm install
npm run build
npm run build:client

开发模式启动：

dsh-hub

依赖 dsh 的 Web 端（dsh web）已可用。本项目作为 dsh 插件通过 cordis.patch.yml 挂载，不修改 dsh 源码。

方式三：自编译安装（本地构建，等同 npm 发布安装）

从源码构建并安装到 npm 全局包位置——与 npm i -g 发布安装别无二异：全局包在 npm prefix -g 下、dsh-hub 命令可用、桌面快捷方式自动创建（postinstall 运行）。

一条命令（推荐）：

npm run install:local

分步执行（等价于上面一条命令）：

# 1. 构建 + 打包（prepack 自动执行 build + build:client，产物即发布 tgz）
npm pack --pack-destination ./dist

# 2. 安装到 npm 全局（--allow-scripts 放行 postinstall 快捷方式 + koffi 原生构建）
npm i -g ./dist/marecgents-dsh-hub-<version>.tgz --allow-scripts=@marecgents/dsh-hub,koffi

⚠️ 若桌面壳正在运行（托盘驻留），覆盖安装会报 EBUSY——先退出桌面壳再执行。安装完成后可用 node scripts/install-local.mjs 自带的校验输出确认：全局包版本、dsh-hub 命令 shim、快捷方式指向。

验证门控

dsh web

普通 CLI 启动不会加载桌面壳：无窗口、无托盘、无插件注入。

技术架构

双 half 模型

┌──────────────────┐   spawn --port 0   ┌────────────────────────────────────┐
│ bin/launcher.mjs │ ─────────────────▶ │ dsh web（Cordis 插件树）            │
│ 桌面快捷方式 →     │  findDsh + junction│  ┌──────────────────────────────┐  │
│ wscript+VBS 隐藏  │  注册 bundle       │  │ dsh-hub（host half）          │  │
│ 控制台            │                   │  │ src/index.ts ── src/desktop.ts │  │
└──────────────────┘                   │  │      │  services/*             │  │
┌──────────────────┐                   │  └──────┼───────────────────────┘  │
│ bin/dsh-hub.mjs  │ ── spawn ────────▶│         │ WebView2 窗口            │
│ 终端命令           │                   │  ┌──────▼───────────────────────┐  │
└──────────────────┘                   │  │ dsh Web UI（SPA）              │  │
                                       │  │  + dsh-hub（client half）      │  │
                                       │  │  src/client/*                  │  │
                                       │  └────────────────────────────────┘  │
                                       └────────────────────────────────────┘

host half（dsh 进程内，Node）：src/index.ts + src/desktop.ts + src/services/*。
client half（浏览器内）：src/client/*，由 dsh 的 client-modules 自动编入 __DSH_BOOT__。

通信通道

通道	用途
HTTP 路由	配置读写：`/api/dsh-hub/config`、`/api/dsh-hub/workspace/*`
IPC / evaluateScript 桥	托盘命令派发、主题切换、当前工作区查询
事件桥	`session/event` → 会话完成通知

关键机制

启动链路：快捷方式 → launcher.vbs（隐藏控制台）→ launcher.mjs（单实例锁 + 找 dsh + junction 注册 bundle + spawn dsh web --port 0）→ dsh 加载插件 → openDesktopShell() 打开 WebView2。
主题跟随：body[data-ds-dark-theme] 变化 → MutationObserver → IPC → 标题栏主题/图标。
托盘命令：独立 tray-helper.mjs 进程 → JSON IPC → 主进程执行。
崩溃自动重启：非正常退出时最多自动重启 3 次；主动退出写 quit.marker 不重启。
关闭到托盘：隐藏保活窗口方案，规避 webviewjs 无关闭拦截的限制。

目录结构

dsh-hub/
├── package.json            # dsh.bundle.patch + dsh.client + bin + scripts
├── cordis.patch.yml        # 插件行（启动来源门控）
├── tsconfig.json
├── tsdown.config.ts        # client bundle 构建配置
├── bin/
│   ├── launcher.mjs        # 快捷方式启动器
│   ├── launcher.vbs        # 隐藏控制台包装
│   ├── dsh-hub.mjs          # 终端命令入口
│   └── tray-helper.mjs     # 独立托盘进程
├── scripts/
│   ├── postinstall.mjs     # 检测 dsh/pnpm + 创建快捷方式
│   ├── postuninstall.mjs   # 清理快捷方式
│   ├── build-client.mjs    # client 构建 + SDK junction
│   └── generate-icon.mjs
├── assets/                 # dsh favicon（PNG/ICO/SVG）
├── src/
│   ├── index.ts            # host 插件入口
│   ├── desktop.ts          # WebView2 壳
│   ├── client/             # client half（设置卡片 + 右侧栏）
│   └── services/           # config / theme / tray / state / icons ...
├── docs/
│   └── 关键踩坑记录.md      # 踩坑索引
└── lib/                    # 构建产物

自编译

# 编译 host（tsc）
npm run build

# 构建 client bundle（tsdown，自动建立 SDK junction）
npm run build:client

⚠️ 执行 npm i 新依赖会清掉 build-client 建立的 SDK junction（@deepseek-ai/dsh-*），装完必须重新运行 npm run build:client。

依赖

类型	主要依赖
runtime	`@webviewjs/webview`、`koffi`、`clsx`、`@deepseek-ai/schemastery`
peer	`@deepseek-ai/cordis`、dsh host/client 相关包、`react`、`react-dom`
dev	`typescript`、`tsdown`、`@deepseek-ai/dsh-*` 系列、`react` / `react-dom` 类型

完整依赖见 package.json。

技术路线

当前壳层：@webviewjs/webview（WebView2）+ koffi FFI，Windows 专属。
目标壳层：Tauri 2.x —— 自定义壳层 UI（decorations: false 自定义标题栏）、Linux / Windows / macOS 多端一致、包体 ~10MB、官方插件生态（tray / notification / window-state / single-instance / updater）。
正式版前置条件：迁移至 Tauri 2.x 并达到较好体验后再发布正式版（当前为 rc 预览版）。
dsh 生态适配：壳层与内容解耦（dsh Web UI 为独立 SPA），Tauri 壳仅负责窗口/托盘/通知/系统集成；client half（React）与 dsh 插件代码零改动。
详细决策见外部文档 docs/dsh桌面端技术路线-2026-08-16.md。

发布

# scoped 包：发布必须 --access public + 官方 registry
npm publish --access public --registry=https://registry.npmjs.org/

# 发布候选版（rc 标签，不影响 latest）
npm publish --access public --tag rc --registry=https://registry.npmjs.org/

致谢

DeepSeek Harness —— 一切皆插件的 DSH 生态。
dsh-web-ui —— 插件/皮肤集合与右侧栏参考。
DSH-better-sidebar —— body portal 右侧栏与工作台参考。
awesome-dsh-plugin —— dsh 插件精选列表与生态索引。
DeepSeek Harness Desktop —— 同生态桌面化项目参考。

文档

开发约束（AGENTS.md，开发前必读） —— 全部开发 harness 总纲 + 分层子 harness 索引
关键踩坑记录（勿重蹈）

deepseek-harness-hub

项目标签

README

dsh-hub

分支状态

功能特性

安装与使用

方式一：自动安装（推荐）

方式二：手动 / 从源码安装

方式三：自编译安装（本地构建，等同 npm 发布安装）

验证门控

技术架构

双 half 模型

通信通道

关键机制

目录结构

自编译

依赖

技术路线

发布

致谢

文档

分类依据

deepseek-harness-hub

项目标签

README

dsh-hub

分支状态

功能特性

安装与使用

方式一：自动安装（推荐）

方式二：手动 / 从源码安装

方式三：自编译安装（本地构建，等同 npm 发布安装）

验证门控

技术架构

双 half 模型

通信通道

关键机制

目录结构

自编译

依赖

技术路线

发布

致谢

文档

分类依据

同类项目

deepseek-harness

learn-harness-engineering

deepseek-harness-desktop