启动自动开浏览器 peach0x33a/dsh-open-browser

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），三平台安装命令一致（Windows 上 dsh 为 .cmd shim，CLI 已内部处理）：

从 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 层列表。之后正常启动：

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 | LaunchServices 默认浏览器；/usr/bin/open 始终存在 |
| Linux (X11) | xdg-open | 走桌面环境默认浏览器；$BROWSER 已设置时直接用它 |
| Linux (Wayland) | xdg-open | 同一命令，Wayland 通用——xdg-open 通过 xdg-desktop-portal/会话默认浏览器打开，不依赖 X11；检测侧 WAYLAND_DISPLAY 即视为有桌面 |
| Windows | powershell.exe -NoProfile -Command Start-Process '' | 无 shell、隐藏窗口；依赖系统自带 PowerShell（所有受支持 Windows 均内置） |
| WSL (1/2) | powershell.exe ... Start-Process '' | 走 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，需重述所有键）：

~/.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: ├─ 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 自动发布

开发

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（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:/ 直装 | 见下方 1/3 |
| 版本化 peer 依赖 + 全部 optional | pnpm 不强装，解析回退 dsh 自带 | 本包仅 @deepseek-ai/schemastery 一个 peer（dsh 必带） |

发布路径按优先级如下（均已实测）：

1. npm 发布（首选，零构建、零授权）

纯 JS 包没有构建产物问题，files 已配置好（index.js、lib/、cordis.patch.yml），发布只需：

pnpm publish # 在仓库根执行

用户侧一条命令安装，无 pnpm allowBuilds 授权负担：

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

2. CI 自动发布（已启用）

.github/workflows/release.yml：打 v* tag 即跑测试 + 发布到 npm（NPM_TOKEN secret 已配置）：

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

3. git 直装（兜底，零授权）

本包没有 prepare 构建脚本，源码即产物，git 安装无需 allowBuilds 授权、无需 path: 参数（仓库根即包根）：

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

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

4. tarball（离线/内网）

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

许可

MIT