桌面套壳窗口 Aaaaamadeus/dsh-gui

dsh-gui

dsh-plugin
license
platform
dsh

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/、/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: 不 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 及其生态的许可见各自仓库。