dsh-gui

Readme

# dsh-gui

[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-✓-6e40c9)](https://github.com/topics/dsh-plugin)
[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-blue.svg)](#)
[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.x-lightgrey)](#兼容范围)

**dsh-gui** 是 [DeepSeek Harness](https://github.com/deepseek-ai/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。

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

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

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

```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。

卸载：

```bat
dsh plugin --profile web remove dsh-gui
```

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

## 从源码安装 / 开发

```bat
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
```

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

```bat
dsh-gui.cmd
```

## 工作方式

```text
┌────────────────────────── 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` 声明：

```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`：

```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`](examples/hello-plugin)。

## 目录结构

```text
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）
```

## 验证

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

Electron 主进程 headless 检查：

```bat
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 及其生态的许可见各自仓库。