dsh-open-browser

Readme

# dsh-open-browser

DSH 插件:在 `dsh web` 启动完成、可以对外服务时,自动用系统默认浏览器打开 Web UI。

- **零运行时依赖**(仅 peer 使用 dsh 自带的 `@deepseek-ai/schemastery` 做配置校验)
- **跨平台**:macOS / Linux(X11 与 Wayland)/ Windows / WSL,见下方平台矩阵
- **无头安全**:Linux 无 `DISPLAY`/`WAYLAND_DISPLAY` 且非 WSL 时静默跳过并打一行提示(CI/容器里不会乱弹)
- **时机精确**:与 web-app 打印 URL 行同一就绪点(Loader 树 settle 之后),`--port 0` 的 OS 分配端口也能拿到
- **不阻塞关停**:opener 子进程 detached + `unref`,Ctrl-C/SIGTERM 关停不受影响

## 安装

已发布到 npm(`dsh-open-browser`,GitHub: [peach0x33a/dsh-open-browser](https://github.com/peach0x33a/dsh-open-browser)),三平台安装命令一致(Windows 上 `dsh` 为 `.cmd` shim,CLI 已内部处理):

```sh
# 从 npm 安装(首选)
dsh plugin --profile web add dsh-open-browser

# 或从 git 直装(纯 JS 无 prepare,无需 allowBuilds 授权)
dsh plugin --profile web add github:peach0x33a/dsh-open-browser

# 或本地目录(开发/验证)
dsh plugin --profile web add /path/to/dsh-open-browser
```

`dsh plugin` 会把包加入 profile 的 `dsh.profile.bundles` 层列表。之后正常启动:

```sh
npx @deepseek-ai/dsh web
```

启动完成后终端会打印两行:

```
dsh web: http://127.0.0.1:3080
dsh-open-browser: opened http://127.0.0.1:3080 via xdg-open
```

## 平台矩阵

| 平台 | 命令 | 说明 |
|---|---|---|
| macOS | `open <url>` | LaunchServices 默认浏览器;`/usr/bin/open` 始终存在 |
| Linux (X11) | `xdg-open <url>` | 走桌面环境默认浏览器;`$BROWSER` 已设置时直接用它 |
| Linux (Wayland) | `xdg-open <url>` | **同一命令,Wayland 通用**——xdg-open 通过 `xdg-desktop-portal`/会话默认浏览器打开,不依赖 X11;检测侧 `WAYLAND_DISPLAY` 即视为有桌面 |
| Windows | `powershell.exe -NoProfile -Command Start-Process '<url>'` | 无 shell、隐藏窗口;依赖系统自带 PowerShell(所有受支持 Windows 均内置) |
| WSL (1/2) | `powershell.exe ... Start-Process '<url>'` | 走 Windows 桌面默认浏览器;URL 无需 wslpath 转换;依赖 WSL interop(PATH 含 powershell.exe,默认开启) |
| 无头 Linux | 不执行 | 无 `DISPLAY`/`WAYLAND_DISPLAY` 且非 WSL → 打印跳过提示 |

平台判定与无头检测逻辑与官方 `@deepseek-ai/dsh-host-apiproxy` 的 `canOpenNativePath` 一致(WSL 标记 = `WSL_DISTRO_NAME`/`WSL_INTEROP` 或内核 release 含 `microsoft`)。

### 各平台注意事项

- **Linux `$BROWSER`**:按可移植约定直接作为单个可执行文件 spawn(与官方 opener 一致)。若你设置的是带参数形式(如 `firefox %s`),该分支会失败并打印 `console.error`——不设置 `$BROWSER`、交给 `xdg-open` 即可,日常路径不受影响。
- **极简 Linux**(无 xdg-utils):`xdg-open` 缺失时打印错误行,启动不受影响;安装 `xdg-utils` 或设置 `$BROWSER` 即可。
- **Windows 无桌面会话**(服务/SSH 非交互):`canOpenUrl` 对 win32 恒为 true,`Start-Process` 失败时打印错误行,启动不受影响。
- **WSL 关闭 interop**:`powershell.exe` 不可达时报错行,启动不受影响。

## 配置

默认值即"打开"。可在 profile 的 `cordis.patch.yml` 中按行 id 覆盖(注意 patch 会替换整份 `config`,需重述所有键):

```yaml
# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-open-browser
  config:
    open: false     # 关闭自动打开
    delayMs: 0      # 打开前额外延迟(毫秒),一般无需设置
```

## 工作原理

```
dsh web 启动
  └─ webServer 绑定端口(--port 0 时端口由 OS 分配)
       └─ Loader 树 settle —— web-app 在此打印 URL 行
            └─ 本插件读取 webServer.port → http://127.0.0.1:<port>
                 ├─ canOpenUrl()? 否 → 打印跳过提示,结束
                 └─ 是 → 平台分派 spawn(detached + unref + windowsHide)
```

## 目录结构

```
dsh-open-browser/                 # 仓库根即包根
├── package.json                  # 组合包 manifest(dsh.bundle.patch)+ keywords
├── cordis.patch.yml              # 层:插入 dsh-open-browser 行(含默认配置)
├── index.js                      # 插件入口:就绪点 + headless 守卫 + fire-and-forget
├── lib/open-url.js               # 纯函数:平台分派 / 无头检测 / 引号 / spawn
├── test/open-url.test.js         # keyless 快照测试(平台分派、无头检测、入口 no-op 路径)
├── test/platform-selfcheck.test.js # 真实平台自检:opener 命令在 PATH 中可解析
└── .github/workflows/
    ├── test.yml                  # CI:ubuntu / macos / windows × Node 22 / 24
    └── release.yml               # tag v* → 测试 + npm 自动发布
```

## 开发

```sh
pnpm install   # 仅安装 dev 依赖(@deepseek-ai/schemastery,用于测试)
node --test    # keyless 快照测试,零 mock 框架
```

测试中的平台分派均为注入 internals 的纯函数快照(三平台 CI 断言同一组输出);`platform-selfcheck` 则用真实 `process.platform`/`process.env` 分派并验证命令在 PATH 上可解析——在 Windows runner 上证明 `powershell.exe` 可达,在 macOS runner 上证明 `open` 存在,在 Linux runner 上证明 `xdg-open`/`$BROWSER` 已安装。

## 发布方式(调研结论)

参考了官方文档 `develop/basic/publish`、官方 examples、社区插件仓库(`@dsh-external/plugin-console`、`dsh-client-ui-skin-maid-atelier`),以及实战发布过的 [`HuanLinOTO/dsh-plugin-yet-another-subagent`](https://github.com/HuanLinOTO/dsh-plugin-yet-another-subagent)(npm `@huanlin/dsh-plugin-yet-another-subagent`,git 与 npm 双通道):

| 参考项目做法 | 说明 | 本包对照 |
|---|---|---|
| npm 发布 + `publishConfig.access: public` | scope 包需公开访问;`keywords: ["dsh-plugin"]` 进 npm 搜索 | 无 scope 无需 access;已加 `keywords` |
| **构建产物提交进 git 仓库**(`lib/` 入库) | git 直装无需 `prepare`/`allowBuilds` | 纯 JS 源码即产物,天然零负担 |
| 双安装通道 | 开发用 `link:` 本地热更新;分发用 `github:<user>/<repo>` 直装 | 见下方 1/3 |
| 版本化 peer 依赖 + 全部 optional | pnpm 不强装,解析回退 dsh 自带 | 本包仅 `@deepseek-ai/schemastery` 一个 peer(dsh 必带) |

发布路径按优先级如下(均已实测):

### 1. npm 发布(首选,零构建、零授权)

纯 JS 包没有构建产物问题,`files` 已配置好(`index.js`、`lib/`、`cordis.patch.yml`),发布只需:

```sh
pnpm publish          # 在仓库根执行
```

用户侧一条命令安装,无 pnpm `allowBuilds` 授权负担:

```sh
dsh plugin --profile web add dsh-open-browser
```

### 2. CI 自动发布(已启用)

`.github/workflows/release.yml`:打 `v*` tag 即跑测试 + 发布到 npm(`NPM_TOKEN` secret 已配置):

```sh
git tag v0.1.1 && git push origin v0.1.1
```

### 3. git 直装(兜底,零授权)

本包**没有 `prepare` 构建脚本**,源码即产物,git 安装无需 `allowBuilds` 授权、无需 `path:` 参数(仓库根即包根):

```sh
dsh plugin --profile web add github:peach0x33a/dsh-open-browser
```

> 对比:TypeScript 插件必须把构建产物入库(`lib/` 提交进 git)才能免掉 prepare——yet-another-subagent 就是这么做的;纯 JS 包天然不需要。

### 4. tarball(离线/内网)

```sh
pnpm pack            # 产出 dsh-open-browser-0.1.1.tgz
dsh plugin --profile web add ./dsh-open-browser-0.1.1.tgz
```

## 许可

MIT