dsh-gui

dsh-gui 是 DeepSeek Harness（dsh） 的原生桌面套壳：不打开浏览器、不重新实现 agent 逻辑，只把本机安装的 dsh 作为内核拉起来， 再在 Electron 原生窗口里加载 dsh 官方 Web UI。

它也以 dsh 原生插件的形式发布：声明了 dsh.bundle.patch，可以直接用 dsh plugin 安装，并自动创建/维护桌面快捷方式。

---

特性

• 🪟 Web 套壳：窗口内是官方 Web UI；官方前端/内核更新后无需改动本壳
• 🧩 dsh 插件化安装：dsh plugin --profile web add github:Aaaaamadeus/dsh-gui
• 🔗 自动快捷方式：每次 dsh profile 启动都会幂等刷新桌面快捷方式（含图标、隐藏控制台启动）
• 🧠 低耦合内核：只依赖 dsh 的 host-apiproxy 线协议，不 import 任何 @deepseek-ai/* 包
• 🛡️ 沙箱渲染：contextIsolation + sandbox，外链交给系统默认浏览器
• 🧬 一切皆插件：main 进程插件、RPC 权限声明、dshgui-plugin:// 资产协议、原生模式内置 UI 插件

快速安装（作为 dsh 插件）

前置：已安装 dsh CLI 与 pnpm。

:: 1. 安装为 web profile 的 bundle 插件
dsh plugin --profile web add "github:Aaaaamadeus/dsh-gui"

:: 2. 启动一次 dsh web（会执行插件并自动创建桌面快捷方式；之后可关闭）
dsh web

装完后 %USERPROFILE%\.dsh\profiles\web\package.json 会自动变成：

{
  "dependencies": { "dsh-gui": "github:Aaaaamadeus/dsh-gui" },
  "dsh": { "profile": { "bundles": [..., "dsh-gui"] } }
}

不需要手改 cordis.yml。以后双击桌面的 dsh-gui 即可：

1. 如果环境里已有运行中的 DSH_WEB_URL → 直接加载该地址；
2. 否则自动拉起 dsh web（默认 127.0.0.1:31680，端口占用自动换随机端口）→ 加载官方 Web UI。

卸载：

dsh plugin --profile web remove dsh-gui

pnpm 会拦截 Electron 二进制后置下载；dsh-gui.cmd 首次启动时会自动补齐 Electron 运行时（一次性下载）。需要镜像时可设置 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/。

从源码安装 / 开发

git clone https://github.com/Aaaaamadeus/dsh-gui
cd dsh-gui
npm install --ignore-scripts
node node_modules\electron\install.js

:: 安装为 dsh 插件并立即创建快捷方式
scripts\install-as-dsh-plugin.cmd

直接启动（不安装为插件）：

dsh-gui.cmd

工作方式

┌────────────────────────── dsh-gui（Electron 壳） ──────────────────────────┐
│  Web shell（默认）:  BrowserWindow ──加载──▶ dsh 官方 Web UI（内核提供）      │
│  Native UI（可选）:  renderer/shell.js + builtin/* 插件                     │
│        ▲ IPC / HTTP                                                         │
│  src/bridge.js —— IPC：按插件 manifest 动态授权 RPC、插件作用域 IPC           │
│  src/plugins/* —— manifest 校验、发现/激活、dshgui-plugin:// 资产协议         │
│  src/kernel/* —— 唯一知道 dsh 线协议的地方                                   │
│      ├─ http-adapter   POST /api/<method>、/api/respond、WebSocket downlink  │
│      ├─ host-manager   每次启动重新探测已安装 dsh CLI，`dsh web` 子进程        │
│      └─ contract       信封/能力/方法别名/版本兼容                             │
│  dsh（agent 循环、工具、目标、任务、会话持久化）                                │
└─────────────────────────────────────────────────────────────────────────────┘

• 会话/工作区/目标/任务与 CLI、浏览器 Web UI 共用 $DSH_HOME 下的同一份数据。
• 窗口外链（文档等）交给系统默认浏览器，套壳窗口不变成浏览器。

内核升级兼容策略

1. 不打包、不锁版本：每次启动重新探测已安装的 dsh （npm root -g / where dsh），npm i -g @deepseek-ai/dsh@latest 后重启即生效。
2. 启动参数自适应：先探测 dsh web --help 是否仍有 --host/--port，否则回退 --profile web；未来 CLI 变化可临时用 DSH_GUI_DSH_ARGS 覆盖内层参数。
3. 外挂内核：DSH_GUI_KERNEL_URL=http://127.0.0.1:<port> 不 spawn 子进程； 环境中已有 DSH_WEB_URL 时自动挂接。
4. 方法别名：call 遇到 method-not-found 类错误按别名重试，别名集中在 src/kernel/contract.js，也可用 DSH_GUI_METHOD_ALIASES 注入。
5. 事件前向兼容：未知 mux/host 帧忽略，host.describe 新字段保留并推导能力。
6. 兼容声明：插件 manifest 的 compat.dsh 只做提示/拦截，壳不因版本号拒绝启动。

配置

变量	默认	说明
DSH_GUI_MODE	web	web = 官方 Web UI 套壳；native = 实验性自绘插件 UI
DSH_HOME	dsh 默认	内核数据目录；GUI 插件目录为 $DSH_HOME/gui-plugins
DSH_GUI_PORT	31680	内部 dsh host 端口（占用时自动换随机端口）
DSH_GUI_DSH_CLI	自动探测	显式指定 dsh 的 lib/bin.js
DSH_GUI_DSH_ARGS	自动探测	覆盖传给 dsh 的内层 web 参数
DSH_GUI_KERNEL_URL	未设置	连接指定 host 的官方 Web UI
DSH_GUI_METHOD_ALIASES	内置空表	JSON 方法改名别名
DSH_GUI_PLUGIN_DIRS	未设置	追加插件目录（Windows 用 ; 分隔）
DSH_GUI_SHORTCUT_NAME	dsh-gui	快捷方式名称
DSH_GUI_SHORTCUT_DIR	桌面	快捷方式目录（诊断用）
DSH_GUI_ICON	内置 ico	自定义快捷方式图标（PNG/ICO）

日志：logs/gui.log、logs/dsh-host.log。

dsh 插件机制

本仓库根 package.json 声明：

"dsh": { "bundle": { "patch": "dsh-gui.patch.yml" } }

dsh-gui.patch.yml 通过 insert 向 booted profile 注入一个宿主层插件 dsh-gui-desktop（plugin/dsh-gui-desktop.mjs）。它只做两件事：

1. 创建/刷新桌面快捷方式（wscript → 隐藏启动器 → dsh-gui.cmd）；
2. 可选 autoOpen: true（在 patch 配置里打开）——dsh 启动时自动拉起 GUI。

快捷方式失败只会写日志，绝不阻塞 dsh profile 启动。

插件开发（native 模式 / 主进程扩展）

Web shell 窗口内是 dsh 官方前端，renderer 插件不注入其中；main 插件、manifest 权限与内核别名机制始终生效。renderer 扩展点在 DSH_GUI_MODE=native 下可用。

一个插件 = 目录 + dsh-gui-plugin.json：

{
  "id": "example.hello",
  "name": "Hello Plugin",
  "version": "0.1.0",
  "main": "main.js",
  "renderer": "renderer.js",
  "permissions": { "calls": ["session.list"] },
  "compat": { "shell": ">=0.2.0", "dsh": "*" },
  "order": 500
}

安装位置：builtin/ → plugins/ → $DSH_HOME/gui-plugins/ → DSH_GUI_PLUGIN_DIRS。

renderer 插件运行在沙箱里，只能通过 window.dsh / DSHGUI 白名单 API 调用 manifest 已声明的 RPC；main 插件与 dsh 插件同信任级，可通过 ctx.ipc.handle(channel, fn) 注册本插件命名空间 IPC。完整示例见 examples/hello-plugin。

目录结构

src/
  kernel/          内核适配层（线协议、host 管理、能力/别名）
  plugins/         GUI 插件系统（manifest、发现、资产协议）
  main.js          Electron 壳入口
  bridge.js        IPC 动态权限桥
  state.js         内核事件缓存
plugin/            dsh bundle 插件（自动快捷方式）
renderer/          native UI 壳与内置样式
builtin/           native UI 内置插件
examples/          示例插件
scripts/           安装器与 smoke 测试
assets/            图标（dsh-gui.ico）

验证

node scripts\smoke.js          :: 24 项内核/插件/协议端到端检查
node scripts\renderer-smoke.js :: 10 项 renderer 插件 DOM 检查（jsdom 可用时）

Electron 主进程 headless 检查：

set DSH_GUI_HEADLESS=1
set DSH_GUI_KERNEL_URL=http://127.0.0.1:3080
node_modules\.bin\electron .

兼容范围

• 开发验证：DeepSeek Harness 0.1.0-rc.5 / 0.1.0-rc.6，Windows，Node.js ≥ 20，Electron 37。
• dsh 仍是开发者预览版，未来可能有破坏性变更；协议修复集中在 src/kernel/。

许可证

MIT。本项目不包含 DeepSeek Harness 代码；dsh 及其生态的许可见各自仓库。