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 关停不受影响

安装

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

# 或从 npm 安装(发布后)
dsh plugin --profile web add dsh-open-browser

# 或从 git 安装
dsh plugin --profile web add github:you/dsh-open-browser

三平台安装命令完全一致(Windows 上 dsh 为 .cmd shim,CLI 已内部处理)。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

git 安装会执行 prepare 构建脚本(pnpm ≥10 需要授权),本包是纯 JS、无需构建,授权行形如 allowBuilds: dsh-open-browser: true;本地目录与 npm 安装无需任何授权。

平台矩阵

| 平台 | 命令 | 说明 | |---|---|---| | 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,需重述所有键):

# ~/.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)

平台分派命令与注意事项见上方平台矩阵。判定逻辑与官方 @deepseek-ai/dsh-host-apiproxy 的 canOpenNativePath 一致(WSL 标记 = WSL_DISTRO_NAME/WSL_INTEROP 或内核 release 含 microsoft)。

目录结构

dsh-open-browser/
├── package.json                  # 声明 dsh.bundle.patch(组合包 manifest)
├── 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

开发

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/[email protected],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),发布只需:

pnpm publish          # 从 dsh-open-browser/ 目录

用户侧一条命令安装,无 pnpm allowBuilds 授权负担(官方文档推荐的"分发构建产物"路径):

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

2. CI 自动发布(推荐配合 npm)

../.github/workflows/release.yml:打 v* tag 即跑测试 + 发布到 npm。在 GitHub 仓库设置里配好 NPM_TOKEN secret 后:

git tag v0.1.0 && git push origin v0.1.0

3. git 直装(兜底,本包无授权负担)

社区插件(plugin-registry、dsh-deep-whale)均为 private: true + git 分发。本包没有 prepare 构建脚本,源码即产物,git 安装无需 allowBuilds 授权:

dsh plugin --profile web add github:peach0x33a/dsh-open-browser#main&path:/dsh-open-browser

path: 需带前导斜杠,否则 pnpm 会把它拼进 commit-ish 解析失败。已在本机实测通过,无 allowBuilds 授权要求。

对比:TypeScript 插件的 git 安装必须提供自包含 prepare 脚本(官方 publish 文档的例子 turtle-ui 已不可访问),且 pnpm ≥10 默认拒绝执行 git 依赖的 prepare——这是 npm 发布成为首选的原因。

4. tarball(离线/内网)

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

许可

MIT