dsh-web-window-companion

Readme

<div align="center">

# DSH Web Window Companion

**关掉浏览器窗口 = 停掉 dsh web 服务**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows-blue?style=flat)]()
[![dsh plugin](https://img.shields.io/badge/dsh-plugin-4D6BFE?style=flat)]()
[![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933?style=flat&logo=node.js&logoColor=white)]()

[English](README-en.md) | 中文

</div>

## 这是什么

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 Web profile 插件（bundle）。装上之后，`dsh web` 的行为变为：

1. 不再往默认浏览器里扔一个标签页；
2. 改为用 Edge / Chrome 的 **App 模式**（`--app=`）打开一个独立窗口，自带认证 token，走专用浏览器 profile，不碰你日常浏览器的任何状态；
3. **你关掉这个窗口，dsh web 服务就随之优雅退出**——端口释放、进程归零，不留后台残留。

适合把 DSH Web 当桌面应用用的人：开窗即用，关窗即走。

> 如果你不想敲命令、想要双击桌面图标启动，请看姊妹项目 [dsh-win-quick-launcher](https://github.com/big0lives/dsh-win-quick-launcher)（免终端启动器）。⚠️ **两者二选一，不要同时启用**：它们使用同一个浏览器专用 profile，同时运行时两个窗口进程会互踢，导致窗口闪退、服务被误停。

## 安装

在 web profile 中安装（git 安装即可，本插件为纯 JavaScript，无构建步骤）：

```sh
dsh plugin --profile web add github:big0lives/dsh-web-window-companion
```

源码安装的用户在仓库根目录执行：

```sh
pnpm dsh plugin --profile web add github:big0lives/dsh-web-window-companion
```

验证插件层已生效：

```sh
dsh --profile web --dump-config   # 应看到 "# == dsh-web-window-companion" 层
```

卸载：

```sh
dsh plugin --profile web remove dsh-web-window-companion
```

## 使用

装好后什么都不用改，照常启动：

```sh
dsh web
```

- 终端仍会打印带 token 的 URL（`dsh web: http://127.0.0.1:3080/?token=...`），App 窗口打不开时可以手动复制使用；
- 关闭 App 窗口 → 服务优雅退出（root fiber dispose，exit code 0）；
- SSH 远程启动时插件自动保持静默，不抢窗口。

## 工作原理

```
dsh web
  └─ Loader 树就绪后，插件注入 connection / webServer 服务
       ├─ connection.authenticatedUrl() 生成带 token 的 URL
       ├─ spawn 浏览器：--app=<url> --user-data-dir=<专用 profile>
       │    └─ 专用 profile ⇒ 浏览器进程生命周期 == 窗口生命周期
       └─ 窗口关闭 → 浏览器进程退出 → ctx.root.fiber.dispose() → 服务优雅停止
```

同时，bundle 的 patch 会把官方 `web-runtime` 行的 `openBrowser` 覆盖为 `false`（其余键原样重述），抑制默认浏览器跳转；`printUrl` 保持开启作为兜底。

- **零依赖、零配置、纯 JavaScript**：git 安装无需 `allowBuilds` 白名单；
- 浏览器探测顺序：Edge (x86 → x64) → Chrome (x64 → x86)；都找不到时打印警告并保留 URL 兜底。

## 故障排除

| 症状 | 原因与处理 |
| --- | --- |
| 没有弹出 App 窗口 | 确认已装 Edge 或 Chrome；看终端是否有 `[window-companion]` 警告；URL 兜底始终可用 |
| 又弹了默认浏览器标签页 | 插件层未生效，运行 `dsh --profile web --dump-config` 检查是否有 `# == dsh-web-window-companion` |
| 关窗后服务没退出 | 窗口必须来自插件打开的专用 profile（标题栏无标签页）；手动新开标签页不影响服务生命周期 |
| 想恢复默认行为 | `dsh plugin --profile web remove dsh-web-window-companion` 即可完全还原 |

## License

[MIT](LICENSE) © 2026 big0lives