dsh-wsl-launcher

当 dsh 住在 WSL 里时，给 DeepSeek Harness Web 界面一个「双击直达」的入口。

English

你的 dsh web 跑在 WSL 里，但鼠标在 Windows 上。每次打开界面都要重复同一套仪式：

打开 Windows 终端  →  wsl  →  dsh web  →  等它启动  →  切到浏览器  →  敲网址  →  回车

这个插件把这套仪式删掉。安装后，你的 Windows 桌面上会出现一个应用风格的 快捷方式（黑鲸图标）。双击它：

1. 由 wsl.exe -d <你的发行版> --exec /bin/bash <launcher.sh> 直接拉起——不需要 Windows 终端；
2. 启动脚本会找到 dsh（PATH → 登录 shell → 安装时记录的路径）；
3. 如果 Web 端口已经在监听，直接打开浏览器（天生幂等——连点十下也不坏，没有端口冲突）；
4. 否则启动 dsh web --port 3080，这个控制台窗口就是服务器窗口（关窗即停服务），轮询端口就绪后自动打开 Windows 默认浏览器。

同时注册 wsl_launcher 模型工具：会话里的 agent 自己就能 install / status / open / uninstall 这个启动器。

✅ 兼容性

📦 安装 / 升级 / 卸载

需要一个 dsh profile（例如你跑 dsh web 的 web profile）。

安装

# 从 npm（发布之后）
dsh plugin --profile web add dsh-wsl-launcher

# 或直接来自 GitHub（monorepo 子路径写法）
dsh plugin --profile web add github:Small-tailqwq/dsh-deep-whale#path:/wsl-launcher

# 或本地 checkout / tarball
dsh plugin --profile web add /path/to/dsh-wsl-launcher
dsh plugin --profile web add /path/to/dsh-wsl-launcher-0.1.0.tgz

dsh plugin 通过包的 dsh.bundle 清单自动把它注册为 bundle 层—— 无需手工编辑任何 cordis.patch.yml。

升级 / 卸载

dsh plugin --profile web update dsh-wsl-launcher
dsh plugin --profile web remove dsh-wsl-launcher

然后重启 dsh web。激活时若 autoInstall: true（默认），插件会自动 （重新）创建启动文件与桌面快捷方式。卸载包不会删你的快捷方式——请用 wsl_launcher 的 uninstall 动作（或下面的手动步骤）清理。

🚀 快速开始

1. 安装插件（见上文）并重启 dsh web。
2. 看你的 Windows 桌面：DeepSeek Harness Web（鲸鱼图标）。
3. 双击它 → 首次启动 dsh web 并打开浏览器；之后如果服务已在运行，双击只开浏览器。
4. 可复现验证：在任意会话里让 agent 调用 wsl_launcher，动作 status—— 应返回 isWsl: true、distro: "<你的发行版>"、running: true 与 http://127.0.0.1:3080。

WSL2 说明：服务器监听 WSL 内的 127.0.0.1；WSL 的 localhost 转发 让 Windows 浏览器用同一个 URL 就能访问——不需要 --host 参数。

🤖 wsl_launcher 工具

⚙️ 配置

在 profile 的 cordis.patch.yml（如 ~/.dsh/profiles/web/cordis.patch.yml） 中覆盖插件行。patch 会整体替换该行 config，请保留需要保留的键：

- id: wsl-launcher
  config:
    autoInstall: true            # 激活时创建/刷新启动器与快捷方式（默认 true）
    port: 3080                   # Web 端口（默认 3080）
    distro: ""                   # WSL 发行版名；留空 = 自动（WSL_DISTRO_NAME）
    wslUser: ""                  # 快捷方式使用的 WSL 用户（wsl --user）；留空 = 发行版默认
    linkName: "DeepSeek Harness Web.lnk"   # 桌面快捷方式文件名
    launcherDir: ""              # 启动器目录；留空 = ~/.dsh/dsh-wsl-launcher
    scriptName: dsh-web-launcher.sh        # 启动脚本文件名
    withIcon: true               # 复制鲸鱼图标并应用到快捷方式

启动策略

默认 launchMode: installed。启动器会解析已经安装的 dsh 二进制文件（PATH、登录 shell、常见 Node 版本管理器目录、安装时记录的路径），不会访问 npm。

如果只通过 npx 使用或需要一次性运行，请显式启用，并锁定精确包版本：

- id: wsl-launcher
  config:
    launchMode: npx
    npxPackage: "@deepseek-ai/dsh@0.1.1-rc.2"

这会生成 npx --yes @deepseek-ai/dsh@0.1.1-rc.2 web --port 3080 --no-open。npxPackage 只接受一个精确的 npm 包版本：不允许省略版本、latest、语义化版本范围、空白字符或 shell 语法。npx 模式绝不会作为自动兜底。非交互式 WSL 启动环境中必须有 Node.js 和 npx；首次运行需要访问 npm registry，并可能下载该固定版本。

不涉及任何敏感信息。

🔐 权限与数据

🔧 工作原理

┌──────────────────────────────┐   ┌────────────────────────────────────────────┐
│  DeepSeek Harness Web        │──▶│  wsl.exe -d <发行版> --exec /bin/bash      │
│  （Windows 桌面 .lnk，        │   │      ~/.dsh/dsh-wsl-launcher/              │
│  鲸鱼图标经 \\wsl.… 映射）     │   │      dsh-web-launcher.sh --port 3080       │
└──────────────────────────────┘   └────────────────────┬───────────────────────┘
                                                        │ （WSL 内部）
                        ┌───────────────────────────────┼─────────────────────────┐
                        ▼                               ▼                         ▼
                  dsh 在哪？                   端口 3080 在监听吗？       启动 `dsh web --port 3080`
        （PATH → 登录 shell →            （打开 Windows 浏览器，      （控制台 = 服务器窗口；
         记录的绝对路径）                  exit 0——幂等）             轮询 /dev/tcp → explorer.exe）

• cordis.patch.yml — bundle patch：一条 loader 行（id: wsl-launcher、 name: dsh-wsl-launcher）；dsh plugin add 依据 dsh.bundle 清单自动把它 归入 profile 的 bundle 栈。
• lib/launcher.js — WSL 检测（内核 banner + WSL_DISTRO_NAME / WSL_INTEROP 兜底）、启动模板渲染（纯 ASCII）、wsl.exe 参数构造（含命令行 引号处理）、Windows 图标候选（\\wsl.localhost\<发行版>\… 优先、\\wsl$\… 兜底）、以及建/删快捷方式的 PowerShell 构造。所有 PowerShell 字符串值都用 单引号 + '' 转义。
• lib/index.js — Cordis 插件（name: 'wsl-launcher'、inject: ['tools']、 zod Config schema）+ 基于 @deepseek-ai/dsh-tools defineTool 的 wsl_launcher 工具。
• lib/template.sh.txt — 生成的启动脚本：解析 dsh（PATH → bash -ic 登录 shell（覆盖 nvm）→ 记录的绝对路径），用 bash /dev/tcp 探测端口（不依赖 curl/netcat），开浏览器按 explorer.exe → PowerShell Start-Process → cmd.exe /c start 的顺序兜底（部分 WSL 环境，如容器化 WSL，explorer.exe 会直接退出、开不了浏览器），并把控制台窗口的生命周期 绑定到服务器（EXIT/INT/TERM 上挂 trap）。
• icons/whale.ico — 多尺寸鲸鱼图标；安装时复制到启动器目录，Windows 侧 通过 \\wsl.localhost 映射读取它来给 .lnk 上图标。

🩺 故障排查

回滚：dsh plugin --profile web remove dsh-wsl-launcher，再调用 wsl_launcher 的 uninstall（删除 .lnk 与 ~/.dsh/dsh-wsl-launcher）。 不会留下其他任何东西。

🛠️ 开发

• 无构建步骤 — lib/ 是纯 ESM JavaScript；除 dsh 的 peer 依赖外零运行时依赖。
• 测试：npm test（node:test——无需任何第三方依赖）。
• 真实 WSL 里手动 E2E：node tools/e2e-wsl.mjs install|verify|uninstall （开发辅助，不随包发布）。
• 发布：bump package.json 的 version → pnpm pack → 发布 / 推仓库。 dsh.bundle 清单意味着 dsh plugin update 会自动激活新版本。

❓ 常见问题

Q: 快捷方式会以管理员权限运行吗？ 不会。wsl.exe 与启动脚本都以你的普通用户权限运行。

Q: 会干扰正在运行的 dsh web 吗？ 不会——端口探测发现服务在运行就直接进浏览器。

Q: 为什么是 bash 脚本而不是 exe / cmd？ WSL 侧是 Linux：bash + /dev/tcp 零额外依赖、纯 ASCII、约 100 行，运行前可以通读。Windows 侧只有一个标准的 .lnk。

Q: 非 WSL 环境？ 插件正常加载、不安装任何东西，wsl_launcher 工具保持可用（status 全平台可用；open 退化为「请手动打开」提示；install/uninstall 返回明确的 no-op 消息）。

Q: WSL1 能用吗？ 能——用到的只有 interop 与文件，WSL1 两者都有。

📜 许可

MIT —— 见 LICENSE。

稳定性与容错

• 启动、停止按端口使用原子锁，避免双击产生重复 dsh web 进程。
• PID 文件必须是完整数字，停止前还会校验进程命令和进程组；陈旧或不匹配的 PID 只会被清理，不会误杀其他进程。
• status、install、stop、uninstall 的外部文件和 Windows 互操作错误会返回可读结果。
• 自动停止默认关闭。启用 autostopEnabled 后，只有同源 JSON 请求中的合法浏览器 client id 才会计入在线状态；错误请求会被拒绝。
• uninstall 可重复执行；它只删除插件创建的快捷方式、Windows wrapper 和 launcher 目录，不会停止外部启动的服务。