dawsondx/dsh-web-open

中文

一句话：dsh web 启动完成 → 完整链接自动打印 → 浏览器自动打开。
装一次，任何装了 dsh 的机器都能用；零依赖、跨平台、故障安全。

以前 vs 现在

| 以前（每次都要） | 现在（一次装好） |
|---|---|
| 记一长串 npx @deepseek-ai/dsh web | 输 dsh web 即可（想更省事可自建快捷方式/别名） |
| 启动后自己拼 http://127.0.0.1:3080/ 复制进浏览器 | 链接自动打印，浏览器自动打开 |
| 每台机器手动配 PATH、建快捷方式 | dsh plugin --profile web add @dawsondx/dsh-web-open 一行安装 |

效果长这样

$ dsh web
[web-open] Web GUI ready: http://127.0.0.1:3080/
↑ 完整链接自动打印，浏览器同时自动打开 —— 全程零手动操作

本仓库包含什么（安装前先看清楚）

| 部分 | 内容 | 安装方式 | 平台 |
|---|---|---|---|
| 插件本体（核心） | index.js / opener.js / cordis.patch.yml：dsh web 就绪后打印链接并自动打开浏览器 | dsh plugin --profile web add @dawsondx/dsh-web-open（或 GitHub 直装） | Windows / macOS / Linux |
| 可选：Windows 启动器 | contrib/windows/dsh-web.cmd：一键启动 + 自动检查官方新版 | 自行复制到 PATH 目录，或为它建桌面快捷方式 | 仅 Windows |
| 可选：Windows 更新脚本 | contrib/windows/dsh-update.cmd：一键更新 harness | 同上 | 仅 Windows |
| 可选：Unix shell 函数 | contrib/unix/dsh-fn.sh：dsh = dsh web | 加入 ~/.bashrc / ~/.zshrc | macOS / Linux |

插件本体不包含更新功能，也不包含桌面快捷方式——桌面快捷方式、PATH 配置属于每台机器自己的事，仓库不替你创建；可选的 Windows 脚本复制到 PATH 后即可使用。

为什么需要它

官方 dsh (0.1.0-rc.6) 目前只有 printUrl（把链接打印到日志里），没有“启动后自动打开浏览器”的能力；CLI 也没有 --open 参数。社区现有的 dsh-plugin-browser / @anweat/dsh-browser 是给模型用的无头浏览器工具（Playwright 抓网页），与本插件解决的问题不同——本插件打开的是你自己的浏览器来看 GUI。

这个插件解决一个问题：dsh web 启动完成后，打印 URL 并自动打开浏览器。跨平台、零运行时依赖、故障安全设计。

前提条件：已安装 dsh、已初始化 profile（跑过一次 dsh web 即可），且 PATH 里有 pnpm。

从 npm 安装（推荐，已发布）

dsh plugin --profile web add @dawsondx/dsh-web-open

或从 GitHub 安装

dsh plugin --profile web add github:dawsondx/dsh-web-open

dsh plugin 会自动把包装进 profile 的 node_modules，并注册到 dsh.profile.bundles。无需手动配置。重启生效：

dsh web
→ [web-open] Web GUI ready: http://127.0.0.1:3080/
→ 浏览器自动打开

验证是否生效：

dsh web --dump-config   # 输出里应能看到 "id: web-open"

插件等待 Loader 就绪，轮询 webServer 获取绑定端口（最多重试 40×250ms），然后打印 URL 并启动默认浏览器。即使使用 dsh web --port 0（系统分配端口）也能正确打开。

默认行为：打印 URL + 打开浏览器。可在 profile 的 cordis.patch.yml 里覆盖：

~/.dsh/profiles/web/cordis.patch.yml
- id: web-open
config:
open: false          # 只打印链接，不打开浏览器
printUrl: true
url: http://x:8080/      # 覆盖默认 http://127.0.0.1:/
retryAttempts: 40       # 等待服务绑定的重试次数（默认 40 × 250ms）
retryIntervalMs: 250

或用环境变量临时关闭：

DSH_OPEN_BROWSER=0 dsh web   # 只打印，不打开浏览器

兼容性与更新策略

这个插件故意只依赖稳定层：

| 依赖 | 稳定性 | 失效时会怎样 |
|---|---|---|
| @deepseek-ai/cordis（peer，>=4.0.0） | 稳定的插件核心，独立版本号 | 插件无法加载 → dsh 有明确报错，移除插件即恢复 |
| dsh 内部服务 loader / webServer | 0.1.0-rc 阶段可能改名 | 降级为 no-op：只打一行 warning，dsh web 照常启动，只是不自动打开 |

防失效设计

1. apply() 永不抛错。因为 cordis-plugin-loader 对“插件 apply 抛错”的处理是整个 boot 失败，所以本插件把所有步骤包进 try/catch——最坏情况 = 少一个功能，绝不是起不来。
2. 缺服务就静默降级。webServer 拿不到就不打开；API 改名只影响本插件，不影响别的。
3. profile 锁版本。插件装进 ~/.dsh/profiles/web 后由 pnpm lockfile 固定，dsh 官方发新版不会自动升级你 profile 里的插件。
4. 零 rc 依赖。没有依赖任何 0.1.0-rc.x 的内部包，只依赖稳定核心，降低被 rc 版本牵连的概率。

已知的真实风险（写清楚比藏着好）

- 若 dsh 官方把 loader / webServer 服务改名（rc 阶段完全可能），本插件需要一次小更新（改两个服务名）；期间表现为“不自动打开”，不影响使用。
- 若官方未来原生支持 --open，本插件可以退役（卸载即可）；为了不撞车，本插件故意不用 CLI 参数，只用 profile 配置控制。
- 恢复/卸载：dsh plugin --profile web remove @dawsondx/dsh-web-open，或直接编辑 ~/.dsh/profiles/web/package.json 的 bundles 列表。

跨平台兼容性（第一性原理审查）

结论：可以跨平台安装并正确运行（Windows / macOS / Linux，含 WSL）。以下逐层对照 dsh 0.1.0-rc.6 实际源码验证过，不是想当然：

| 层 | 实际机制（源码依据） | 结论 |
|---|---|---|
| 安装 | dsh plugin --profile web add  → pnpm 装入 profile → 命令内 reconcile 把声明了 dsh.bundle 的包写进 dsh.profile.bundles（plugin-*.js） | 需要 pnpm（dsh 官方要求）；boot 不会自动 reconcile，所以必须走 dsh plugin add，手动 pnpm add 不生效 |
| 装载 | row 的 name 由 Node 内部加载器从 profile 目录解析（mountRootInclude / cordis-plugin-loader），与官方 @deepseek-ai/dsh-web-app 完全同路径 | 任意 OS 一致；纯 Cordis 插件，无需 TYPERT 清单（无 ./typert 导出的包会被 typert 注册表静默跳过，不报错） |
| 契约 | 导出 name / apply / config；Cordis unwrapExports 兼容具名导出；无 Config 导出也可（只在有 Config 时才校验） | 与官方插件同款写法 |
| 错误语义 | cordis-plugin-loader：任一插件 apply 抛错 = 整个 boot 失败（loader entries failed to apply） | 本插件 apply() 全 try/catch、永不抛错 → 任何情况下都不会拖垮 dsh web |
| 服务读取 | ctx.get("loader").await() + ctx.get("webServer").port（官方 web-app 的 printUrl 同款） | 任意 OS 一致；拿不到就降级 no-op + 警告 |
| 打开浏览器 | win32 cmd start（走 SystemRoot\System32\cmd.exe 绝对路径，GUI 启动 PATH 被裁剪也不怕）；darwin /usr/bin/open；linux xdg-open → sensible-browser → google-chrome → chromium → firefox 逐级回退 | v0.1.1 修复：spawn 挂 error 监听 + 启动前 PATH 探测，缺 xdg-open 的 Linux 也不会崩（只警告并打印链接） |
| 编码 | 插件文件全部 UTF-8（JS/YAML），Node 与 js-yaml 原生支持 | 中/英/日文系统均无乱码问题 |

已知边界（不是 bug，是环境事实）：

- Linux 无图形环境（服务器 / 容器 / WSL 无 DISPLAY）：浏览器打不开，但 dsh web 照常运行，链接照常打印——行为可预期；
- headless / CI：用 DSH_OPEN_BROWSER=0 关掉自动打开；
- 需要 pnpm：dsh plugin 的管理命令本身要求 pnpm（没装会提示安装）；
- dsh 版本：在 0.1.0-rc.6 上验证。rc 系列内用的都是官方 web-app 同款机制，大概率兼容；若未来 rc 改动了 loader/webServer 服务名，本插件按设计自动降级为 no-op（不报错、不影响启动），等一次小更新即可。
如何更新（官方更新后）

先分清边界：插件本体（dsh-web-open）只负责“启动后打印链接 + 自动打开浏览器”，不包含更新 harness 的功能——插件运行在 dsh 进程内部，无法更新正在运行的宿主。更新 harness 是终端/脚本层面的事：

| 场景 | 命令 / 操作 | 说明 |
|---|---|---|
| 更新 harness（任何系统） | npm install -g @deepseek-ai/dsh@latest | 更新 launcher = 更新整个 harness：官方 bundle（dsh-base / dsh-web-app）按“安装优先”从 launcher 解析，重启即生效 |
| 更新 profile 里的插件 | dsh plugin --profile web update | 本插件已发布到 npm，用此命令升级；GitHub 直装版需重新 dsh plugin add |
| Windows 可选一键脚本 | 把 contrib/windows/dsh-update.cmd 复制到 PATH 目录后执行 dsh-update，或自己为它建桌面快捷方式 | 自动对比 registry → 执行上面两条 |
| Windows 可选启动器自动检查 | 用 contrib/windows/dsh-web.cmd 启动器时，每次打开会静默检查新版并提示；设 DSH_AUTO_UPDATE=1 自动更新后再启动，DSH_SKIP_UPDATE_CHECK=1 关闭 | 同上，需先把脚本放入 PATH |

注意：官方 npx @deepseek-ai/dsh web 不会自动更新——npx 复用本地缓存，只有显式 @latest 才会重新拉取。
可选的 shell 便利层

插件解决的是“启动后自动打开”，跨平台一致。但“dsh 三个字母 = 启动 Web”属于 shell 层，插件做不到，需要每个用户自己的终端配置：

Windows：把 dsh-web.cmd 启动器放进 PATH（见 contrib/windows/），或自己为它创建桌面快捷方式（右键 → 发送到 → 桌面快捷方式）。

macOS / Linux：在 ~/.bashrc / ~/.zshrc 加：

dsh() {
if [ $# -eq 0 ]; then command dsh web; else command dsh "$@"; fi
}

装了插件之后，这些便利层里“等待端口 + 打开浏览器”的逻辑都可以删掉（插件会做），只保留启动本身。

开发与测试

npm test    # 13 项单元测试：平台命令形状、URL 构建、apply 永不抛错、打开/抑制路径

真实的端到端验证（dsh web 启动后浏览器弹出）请在没有占用 3080 端口的环境里跑一次。

License

MIT

English

一句话：当 dsh web 就绪时 → 打印完整 URL → 浏览器自动打开。
安装一次，在任何装有 dsh 的机器上都能用。零依赖、跨平台、故障安全。

之前 vs 之后

| 之前（每一次） | 之后（一次性设置） |
|---|---|
| 记住 npx @deepseek-ai/dsh web | 运行 dsh web（或配置别名 / 快捷方式） |
| 手动拼出 http://127.0.0.1:3080/ 并粘贴到浏览器 | 自动打印 URL，浏览器自行打开 |
| 在每台机器上配置 PATH / 快捷方式 | dsh plugin --profile web add @dawsondx/dsh-web-open —— 一行搞定 |

效果展示

$ dsh web
[web-open] Web GUI ready: http://127.0.0.1:3080/
↑ 打印完整 URL，浏览器自动打开 —— 零手动步骤

本仓库内容（安装前请阅读）

| 部分 | 内容 | 安装 | 平台 |
|---|---|---|---|
| 插件核心 | index.js / opener.js / cordis.patch.yml：当 dsh web 就绪时打印 URL 并打开浏览器 | dsh plugin --profile web add @dawsondx/dsh-web-open（或 GitHub） | Windows / macOS / Linux |
| 可选：Windows 启动器 | contrib/windows/dsh-web.cmd：一键启动 + 检查官方更新 | 自行复制到 PATH 目录，或创建桌面快捷方式 | 仅 Windows |
| 可选：Windows 更新器 | contrib/windows/dsh-update.cmd：一键更新 harness | 同上 | 仅 Windows |
| 可选的 Unix shell 函数 | contrib/unix/dsh-fn.sh：dsh = dsh web | 添加到 ~/.bashrc / ~/.zshrc | macOS / Linux |

插件核心没有更新功能，也不附带桌面快捷方式 —— PATH 放置和快捷方式因机器而异，由用户自行管理。可选的 Windows 脚本在复制到 PATH 目录后即可使用。

为什么需要这个

官方 dsh（0.1.0-rc.6）只有 printUrl 来记录 URL —— 它不会在就绪时自动打开你的浏览器。也没有 --open CLI 标志。像 dsh-plugin-browser / @anweat/dsh-browser 这样的社区插件是供模型使用的无头浏览器工具（用于网页抓取的 Playwright），而不是用来打开你自己的浏览器查看 GUI 的。

这个插件只解决一个问题：当 dsh web 就绪时，打印 URL 并自动打开它。跨平台、零运行时依赖、设计上故障安全。

要求：已安装 dsh，已初始化 profile（运行一次 dsh web），并且 pnpm 在 PATH 中。

从 npm 安装（推荐，已发布）

dsh plugin --profile web add @dawsondx/dsh-web-open

或从 GitHub 安装

dsh plugin --profile web add github:dawsondx/dsh-web-open

dsh plugin 会自动将 bundle 添加到你的 profile 的 node_modules 中，并在 dsh.profile.bundles 中注册它。无需手动配置。重启以激活：

dsh web
→ [web-open] Web GUI ready: http://127.0.0.1:3080/
→ Browser opens automatically

验证它已激活：

dsh web --dump-config   # Should show "id: web-open"

插件等待 Loader 稳定，轮询 webServer 获取绑定的端口（最多重试 40 次 × 250ms），然后打印 URL 并启动你的默认浏览器。即使使用 dsh web --port 0（由操作系统分配端口）也能正常工作。

默认行为：打印 URL + 打开浏览器。在你的 profile 的 cordis.patch.yml 中覆盖：

~/.dsh/profiles/web/cordis.patch.yml
- id: web-open
config:
open: false          # Only print URL, don't open browser
printUrl: true
url: http://x:8080/      # Override default http://127.0.0.1:/
retryAttempts: 40       # Wait attempts (default 40 × 250ms)
retryIntervalMs: 250

或使用环境变量临时禁用：

DSH_OPEN_BROWSER=0 dsh web   # Print only, no browser

兼容性与更新策略

这个插件刻意只依赖稳定的层：

| 依赖 | 稳定性 | 如果它出问题 |
|---|---|---|
| @deepseek-ai/cordis（peer，>=4.0.0） | 稳定的插件核心，独立版本管理 | 插件无法加载 → dsh 显示清晰的错误，移除即可恢复 |
| dsh 内部服务 loader / webServer | 在 0.1.0-rc 期间可能变更 | 优雅降级：打印警告，dsh web 正常启动，只是不会自动打开 |

故障安全设计

1. apply() 永不抛出异常。由于 cordis-plugin-loader 会在插件出错时导致整个启动失败，每一步都包裹在 try/catch 中——最坏情况 = 缺少一个功能，绝不会导致启动失败。
2. 缺失的服务静默降级。如果 webServer 不可用，它会发出警告并跳过打开；其他插件不受影响。
3. Profile 锁定版本。安装在 ~/.dsh/profiles/web 中的插件由 pnpm lockfile 固定；官方 dsh 更新不会自动升级你的插件。
4. 零 rc 依赖。没有内部 0.1.0-rc.x 包，只有稳定的 Cordis 核心——降低破坏性变更风险。

已知风险（透明说明）

- 如果 dsh 重命名 loader / webServer 服务（在 rc 期间可能发生），此插件需要小幅更新（更改两个服务名称）；在此期间它会静默跳过自动打开，而不会破坏 dsh。
- 如果官方 dsh 添加原生 --open，此插件可以退役（直接卸载即可）。为避免冲突，此插件刻意避免使用 CLI 参数，仅使用 profile 配置。
- 卸载：dsh plugin --profile web remove @dawsondx/dsh-web-open 或编辑 ~/.dsh/profiles/web/package.json 的 bundles 列表。

跨平台兼容性（第一性原理审查）

逐层对照 dsh 0.1.0-rc.6 源码验证，而非基于假设：

| 层级 | 实际机制（源码依据） | 结果 |
|---|---|---|
| 安装 | dsh plugin --profile web add  → pnpm 安装到 profile → 在该命令内完成协调，将声明了 dsh.bundle 的 bundles 写入 dsh.profile.bundles | 需要 pnpm（官方要求）；启动时不会协调，因此必须使用 dsh plugin add——仅手动 pnpm add 不会激活它 |
| 加载 | 行 name 通过 Node 的内部加载器从 profile 目录解析（mountRootInclude / cordis-plugin-loader）——与官方 @deepseek-ai/dsh-web-app 使用的完全相同的路径 | 在所有操作系统上相同；普通 Cordis 插件，不需要 TYPERT 清单（没有 ./typert 导出的包会被 typert 注册表静默跳过） |
| 契约 | 导出 name / apply / config；Cordis unwrapExports 处理命名导出；Config 导出是可选的（仅在存在时验证） | 与官方插件相同的编写风格 |
| 错误语义 | cordis-plugin-loader：一个插件在 apply 中抛出异常会导致整个启动失败 | 此插件的 apply() 完全包裹在 try/catch 中且永不抛出 → 绝不会拖垮 dsh web |
| 服务读取 | ctx.get("loader").await() + ctx.get("webServer").port（与官方 web-app 的 printUrl 相同模式） | 在所有操作系统上相同；如果不可用则降级为 no-op + 警告 |
| 打开浏览器 | win32 cmd start（绝对路径 SystemRoot\System32\cmd.exe，即使在 GUI 启动时 PATH 被剥离也安全）；darwin /usr/bin/open；linux xdg-open → sensible-browser → google-chrome → chromium → firefox | v0.1.1 中已修复：spawn 错误监听器 + 启动前 PATH 探测——没有 xdg-open 的 Linux 会发出警告并打印链接，而不是让 dsh 崩溃 |
| 编码 | 插件文件为 UTF-8（JS/YAML）；Node 和 js-yaml 原生支持 | 在任何 locale 下都不会出现乱码 |

已知的环境边界（并非 bug）：

- 没有图形会话的 Linux（服务器 / 容器 / 没有 DISPLAY 的 WSL）：浏览器不会打开，但 dsh web 正常运行，链接仍会打印——行为可预测。
- 无头 / CI：使用 DSH_OPEN_BROWSER=0 禁用自动打开。
- 需要 pnpm：dsh plugin 本身需要 pnpm（如果缺失会提示安装）。
- dsh 版本：已在 0.1.0-rc.6 上验证。在 rc 系列内，它使用与官方 web-app bundle 相同的机制，因此兼容性极有可能；如果未来的 rc 重命名了 loader / webServer，该插件会按设计降级为 no-op（无错误、无启动影响），直到进行小幅更新。
如何更新（在正式发布之后）

先明确边界：插件核心（dsh-web-open）只打印 URL 并打开浏览器——它没有 harness 更新功能，因为在 dsh 内运行的插件无法更新自己的宿主。更新 harness 是终端 / 脚本层面的事情：

| 场景 | 命令 / 操作 | 备注 |
|---|---|---|
| 更新 harness（任何操作系统） | npm install -g @deepseek-ai/dsh@latest | 更新启动器 = 更新整个 harness：官方 bundle（dsh-base / dsh-web-app）会从启动器优先解析安装——下次启动时生效 |
| 更新 profile 插件 | dsh plugin --profile web update | 升级此插件（发布在 npm 上）；通过 GitHub 安装的副本需要重新执行 dsh plugin add |
| 可选的 Windows 一键操作 | 将 contrib/windows/dsh-update.cmd 复制到 PATH 目录，然后运行 dsh-update（或自行创建快捷方式） | 与注册表比较 → 运行上述两条命令 |
| 可选的 Windows 启动器检查 | 使用 contrib/windows/dsh-web.cmd，每次启动都会静默检查是否有更新版本并打印通知；DSH_AUTO_UPDATE=1 会先更新，DSH_SKIP_UPDATE_CHECK=1 会禁用 | 需要先将脚本放入 PATH |

注意：官方的 npx @deepseek-ai/dsh web 不会自动更新——npx 会复用其本地缓存；只有显式使用 @latest 才会重新获取。
可选的 shell 便捷层

该插件跨平台解决了“启动后自动打开”的问题。但“输入 dsh = 启动 web”是 shell 层面的事情，插件无法处理——每个用户自行配置自己的终端：

Windows：将 contrib/windows/ 中的 dsh-web.cmd 放入 PATH，或自行为其创建桌面快捷方式（右键 → 发送到 → 桌面）。

macOS / Linux：添加到 ~/.bashrc / ~/.zshrc：

dsh() {
if [ $# -eq 0 ]; then command dsh web; else command dsh "$@"; fi
}

插件安装后，这些 shell 快捷方式可以去掉“等待端口 + 打开浏览器”的逻辑（插件会处理它），只需调用 dsh。

开发与测试

npm test    # 13 个单元测试：平台命令、URL 构造、apply 永不抛错、打开/抑制路径

要进行真实的端到端验证（在 dsh web 后浏览器确实弹出），请在 3080 端口空闲的环境中测试。

许可证

MIT