dsh-wsl-launcher 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhaoruoqing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# dsh-wsl-launcher
+
+**One double-click entry point to the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI — for when `dsh` lives inside WSL.**
+
+[中文文档](README.zh.md)
+
+You run `dsh web` inside a WSL distribution, but your mouse is on Windows.
+Every time you open the UI you perform the same ritual:
+
+```
+open Windows terminal  →  wsl  →  dsh web  →  wait for boot  →  switch to browser  →  type the URL  →  Enter
+```
+
+This plugin deletes the ritual. After installing it, your **Windows desktop** hosts an
+app-style shortcut (black-whale icon). Double-click it and:
+
+1. `wsl.exe -d <your-distro> --exec /bin/bash <launcher.sh>` boots — no Windows terminal needed;
+2. the launcher finds `dsh` (PATH → login shell → recorded install path),
+3. if the Web UI port already listens it **just opens the browser** (idempotent — double-click it ten times, nothing breaks),
+4. otherwise it starts `dsh web --port 3080` as a detached background daemon, polls the port until ready, then opens your default Windows browser; the console can close without stopping the server.
+
+It also registers a `wsl_launcher` model tool, so any agent in a session can
+`install` / `status` / `open` / `uninstall` the launcher itself.
+
+---
+
+## ✅ Compatibility
+
+| | |
+|---|---|
+| dsh | Verified on `0.1.1-rc.2` (unit tests + scratch-profile composition via `dsh plugin add` / `--dump-config`) |
+| Node | `>=20` (as declared in `engines`) |
+| Host | WSL1/WSL2 on Windows 10 1607+ / Windows 11 with **interop enabled** (the default) and a Windows drive mounted under `/mnt/<drive>` |
+| dsh location | anywhere in the distro: `npm -g`, nvm, local checkout — the launcher resolves it at runtime |
+| Last verified | 2026-08-28 (WSL2, Ubuntu 24.04, dsh `0.1.1-rc.2`, Node 24) |
+
+## 📦 Install / Upgrade / Uninstall
+
+Requires a `dsh` profile (e.g. the `web` profile where you run `dsh web`).
+
+**Install**
+
+```sh
+# from npm (once published)
+dsh plugin --profile web add dsh-wsl-launcher
+
+# or straight from GitHub (monorepo sub-path)
+dsh plugin --profile web add github:Small-tailqwq/dsh-deep-whale#path:/wsl-launcher
+
+# or from a local 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` uses the package's `dsh.bundle` manifest to register it as a bundle
+layer automatically — **no manual `cordis.patch.yml` edits**.
+
+**Upgrade / Uninstall**
+
+```sh
+dsh plugin --profile web update dsh-wsl-launcher
+dsh plugin --profile web remove dsh-wsl-launcher
+```
+
+Then restart `dsh web`. On activation with `autoInstall: true` (the default) the
+plugin (re)creates the launcher files and the desktop shortcut. Uninstalling the
+package does not remove your shortcut — use `wsl_launcher` with action
+`uninstall` (or the manual steps below) to clean up.
+
+## 🚀 Quick start
+
+1. Install the plugin (see above) and restart `dsh web`.
+2. Look at your Windows desktop: **DeepSeek Harness Web** (whale icon).
+3. Double-click it → first run boots `dsh web` and opens the browser; later runs
+   just open the browser if the server is already up.
+4. Reproducible check: ask any agent in a session to call `wsl_launcher` with
+   action `status` — expect `isWsl: true`, `distro: "<your distro>"`,
+   `running: true` and the URL `http://127.0.0.1:3080`. Use `wsl_launcher` action `stop` to stop only the daemon recorded by this launcher.
+
+> **WSL2 note:** the server listens on `127.0.0.1` inside WSL; WSL's
+> localhost forwarding makes it reachable from the Windows browser at the same
+> URL — no `--host` flag needed.
+
+## 🤖 wsl_launcher tool
+
+| Action | Effect |
+|---|---|
+| `install` | (Re)create the launcher script + icon in `~/.dsh/dsh-wsl-launcher` and the whale-icon desktop shortcut (WSL only) |
+| `status` | WSL detection, distribution, interop availability, launcher files, and whether the Web UI port is listening (any platform) |
+| `stop` | Stop only a live `dsh web` daemon whose PID and command identity match this launcher; never take over another process |
+| `open` | Open the Web UI in the default Windows browser (WSL interop) |
+| `uninstall` | Remove the desktop shortcut and the whole `~/.dsh/dsh-wsl-launcher` directory (WSL only) | safe to repeat; it only removes launcher-owned files |
+
+## ⚙️ Configuration
+
+Override the plugin row in your profile's `cordis.patch.yml`
+(e.g. `~/.dsh/profiles/web/cordis.patch.yml`). A patch replaces the whole row
+config, so restate the keys you keep:
+
+```yaml
+- id: wsl-launcher
+  config:
+    autoInstall: true            # create/refresh launcher + shortcut on activation (default true)
+    port: 3080                   # Web UI port (default 3080)
+    distro: ""                   # WSL distro name; empty = auto (WSL_DISTRO_NAME)
+    wslUser: ""                  # WSL user for the shortcut (wsl --user); empty = distro default
+    linkName: "DeepSeek Harness Web.lnk"   # shortcut file name on the desktop
+    launcherDir: ""              # launcher folder; empty = ~/.dsh/dsh-wsl-launcher
+    scriptName: dsh-web-launcher.sh        # launcher file name
+    withIcon: true               # copy the whale icon + apply it to the shortcut
+  autostopEnabled: false        # opt-in: stop the daemon after all browser tabs close
+  autostopGraceMs: 30000       # idle grace period in milliseconds
+  autostopMinUptimeMs: 45000   # startup protection in milliseconds
+```
+
+### Launch strategy
+
+`launchMode: installed` is the default. The launcher resolves an already installed `dsh` binary (PATH, login shell, common Node manager paths, then the recorded path) and does not contact npm.
+
+For a disposable or `npx`-only setup, opt in explicitly and pin the exact package version:
+
+```yaml
+- id: wsl-launcher
+  config:
+    launchMode: npx
+    npxPackage: "@deepseek-ai/dsh@0.1.1-rc.2"
+```
+
+This generates `npx --yes @deepseek-ai/dsh@0.1.1-rc.2 web --port 3080 --no-open`. The package field accepts only one exact npm package/version specifier: no omitted version, `latest`, semver range, whitespace, or shell syntax. `npx` mode is never used as an automatic fallback. Node.js and `npx` must be available to the non-interactive WSL launcher; the first run needs npm-registry network access and may download the pinned package.
+
+No secrets are involved.
+
+## 🔐 Permissions & data
+
+| Area | What the plugin does |
+|---|---|
+| Files written (WSL side) | `~/.dsh/dsh-wsl-launcher/dsh-web-launcher.sh` and `~/.dsh/dsh-wsl-launcher/icons/whale.ico` |
+| Files written (Windows side) | One `.lnk` on your desktop (`DeepSeek Harness Web.lnk`) — created by `powershell.exe` (WScript.Shell), no other Windows files touched |
+| Files read | Only its own template and icon inside the package, plus `/proc/version` for WSL detection |
+| Processes | Spawns `powershell.exe` (shortcut create/remove, browser fallback) and `explorer.exe` / `cmd.exe` (open browser) through WSL interop; the launcher itself is an ASCII bash script you can read before it runs |
+| Network | Loopback only: probes `http://127.0.0.1:<port>` for status; the browser is opened by the OS, not by the plugin |
+| Credentials | None — never reads, stores, or sends credentials |
+
+## 🔧 How it works
+
+```
+┌──────────────────────────────┐   ┌────────────────────────────────────────────┐
+│  DeepSeek Harness Web        │──▶│  wsl.exe -d <distro> --exec /bin/bash      │
+│  (Windows desktop .lnk,      │   │      ~/.dsh/dsh-wsl-launcher/              │
+│  whale .ico via \\wsl.…)     │   │      dsh-web-launcher.sh --port 3080       │
+└──────────────────────────────┘   └────────────────────┬───────────────────────┘
+                                                        │ (inside WSL)
+                        ┌───────────────────────────────┼─────────────────────────┐
+                        ▼                               ▼                         ▼
+                  where is dsh?                port 3080 listening?      start `dsh web --port 3080`
+        (PATH → login shell →          (open Windows browser,          (console = server window;
+         recorded install path)         exit 0 — idempotent)            poll /dev/tcp → explorer.exe)
+```
+
+- **`cordis.patch.yml`** — the bundle patch: one loader row (`id: wsl-launcher`,
+  `name: dsh-wsl-launcher`); `dsh plugin add` reconciles it into the profile's
+  bundle stack from the `dsh.bundle` manifest.
+- **`lib/launcher.js`** — WSL detection (kernel banner + `WSL_DISTRO_NAME` /
+  `WSL_INTEROP` fallbacks), launcher template rendering (pure ASCII),
+  `wsl.exe` argument building with command-line quoting, Windows icon
+  candidates (`\\wsl.localhost\<distro>\…` first, `\\wsl$\…` fallback), and the
+  PowerShell builders for shortcut create/remove. All PowerShell string values
+  are single-quoted with `''` escaping.
+- **`lib/index.js`** — the Cordis plugin (`name: 'wsl-launcher'`,
+  `inject: ['tools']`, zod `Config` schema) plus the `wsl_launcher` tool via
+  `@deepseek-ai/dsh-tools` `defineTool`.
+- **`lib/template.sh.txt`** — the generated launcher: resolves `dsh` (PATH →
+  `bash -ic` login shell (covers nvm) → recorded absolute path), probes the port
+  with bash `/dev/tcp` (no curl/netcat), opens the browser via `explorer.exe`,
+  falling back to PowerShell `Start-Process` and then `cmd.exe /c start`
+  (needed on some WSL setups, e.g. containerized WSL, where `explorer.exe`
+  exits without opening a browser), and ties the console window's lifetime to
+  the server (`trap` on EXIT/INT/TERM).
+- **`icons/whale.ico`** — multi-size whale icon; at install time it is copied
+  into the launcher directory so Windows can reach it through the
+  `\\wsl.localhost` mapping for the `.lnk` icon.
+
+## 🩺 Troubleshooting
+
+| Symptom | Cause & fix |
+|---|---|
+| No shortcut after restart | Check `dsh web` logs for a `dsh-wsl-launcher: auto install skipped: …` warning. Usually WSL interop is disabled: set `interop = true` under `[boot]` in `C:\Users\<you>\.wslconfig` (or wsl.conf), restart the distro, then retry `wsl_launcher install`. |
+| `powershell.exe not found` in tool output | Same as above — interop disabled or no Windows drive mounted under `/mnt`. |
+| Shortcut appears but with a generic icon | The `\\wsl.localhost` mapping may be missing (older Windows). The plugin falls back to `\\wsl$`; if that is gone too the shortcut still works, iconless. Update Windows or set `withIcon: false` to silence the probe. |
+| Desktop icon lands in the wrong place | OneDrive-managed desktops: the shortcut targets `%USERPROFILE%\Desktop`, `%OneDrive%\Desktop` or `%USERPROFILE%\OneDrive\Desktop` in that order — the first existing one wins, same as Explorer sees it. |
+| Launcher says `dsh was not found` | In the default `installed` mode, `dsh` is not reachable from a non-interactive shell. Install it in the distro (`npm install -g @deepseek-ai/dsh`); if you use nvm, the login-shell probe finds it — or set the recorded path by reinstalling the plugin from the same environment. Alternatively configure explicit, version-pinned `launchMode: npx`. |
+| Launcher says `npx was not found` | `launchMode: npx` requires Node.js with `npx` available in the non-interactive WSL environment. Install Node.js/npm or set `NPX_BIN` to an executable `npx` path; keep `npxPackage` an exact pinned version. |
+| Launcher says `dsh web exited early` | Read the console output above the error (profile/CLI problem, not a launcher bug). |
+| `EADDRINUSE` / port already bound | The launcher detects any listening service and opens the browser instead; it never kills or replaces an unrelated service. Use another `port` in the config if needed. |
+| Server stops after the launcher window closes | Current versions use a detached daemon. Use `wsl_launcher stop` or the generated script's `stop` action; an autostop-enabled daemon stops after its browser presence grace period. |
+| Autostop endpoints reject requests | The browser client sends same-origin JSON POST requests. Requests with another origin, wrong method, missing JSON content type, malformed JSON, or invalid client ids are rejected. |
+| Uninstall says the shortcut is absent | This is an idempotent success state. The Windows shortcut and wrapper are removed when present, and the WSL launcher directory is removed. |
+| Browser opens but the page shows a transport/403 error | The **browser-trust fence** rejected a cross-origin call to the local API — open DevTools → Network → the failed request → check its `Origin`; it must be `http://127.0.0.1:<port>`. A browser extension or leftover tab is the usual culprit. |
+| No browser window appears | The launcher selects one Windows interop opener: `explorer.exe` when available, otherwise PowerShell `Start-Process` or `cmd.exe /c start`; it never chains launchers after an attempt, preventing duplicate tabs. If none is available it prints the URL. If none works in your WSL setup, check WSL interop; the printed URL is always shown in the console as a last resort. |
+| Shortcut boots the wrong distro / user | The `.lnk` encodes `wsl.exe -d <distro> [--user <name>]`. Set `distro` / `wslUser` in the config, then `wsl_launcher install`. |
+| Closing the console mid-session | The normal launcher starts a detached daemon, so closing the console does not stop it. Use `wsl_launcher stop`; foreground mode remains available for debugging. |
+
+**Rollback**: `dsh plugin --profile web remove dsh-wsl-launcher`, then
+`wsl_launcher` with action `uninstall` (removes the `.lnk` and
+`~/.dsh/dsh-wsl-launcher`). Nothing else is left behind.
+
+## 🛠️ Development
+
+- **No build step** — plain ESM JavaScript in `lib/`; zero runtime dependencies
+  beyond the dsh peer packages.
+- **Tests**: `npm test` (node:test — no third-party dependencies).
+- **Manual E2E in a real WSL**: `node tools/e2e-wsl.mjs install|verify|uninstall`
+  (dev helper, not published).
+- **Release**: bump `version` in `package.json` → `pnpm pack` → publish / push.
+  The `dsh.bundle` manifest means `dsh plugin update` picks up new versions.
+
+## ❓ FAQ
+
+**Q: Does the shortcut run anything as admin?** No. `wsl.exe` and the launcher
+run with your normal user permissions.
+
+**Q: Does it interfere with a running `dsh web`?** No — the port probe finds a
+live server and skips straight to the browser.
+
+**Q: Why a bash script and not a .exe / .cmd?** WSL side is Linux: bash +
+`/dev/tcp` needs zero extra tools, stays pure ASCII, and is ~100 lines you can
+read before it runs. The Windows side is one standard `.lnk`.
+
+**Q: Non-WSL hosts?** The plugin loads fine, installs nothing, and keeps the
+`wsl_launcher` tool active (`status` works everywhere; `open` degrades to a
+"open manually" message; `install`/`uninstall` report a clear no-op).
+
+**Q: WSL1?** Works — everything used is interop + files, both present in WSL1.
+
+## 📜 License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,223 @@
+# dsh-wsl-launcher
+
+**当 `dsh` 住在 WSL 里时，给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web 界面一个「双击直达」的入口。**
+
+[English](README.md)
+
+你的 `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 | 已在 `0.1.1-rc.2` 验证（单元测试 + 草稿 profile 的 `dsh plugin add` / `--dump-config` 组合检查） |
+| Node | `>=20`（`engines` 声明） |
+| 运行环境 | Windows 10 1607+ / Windows 11 上的 WSL1/WSL2，**interop 开启**（默认开启），且有 Windows 盘挂载在 `/mnt/<盘符>` |
+| dsh 位置 | 发行版内的任意位置：`npm -g`、nvm、本地 checkout 均可——启动脚本运行时自行解析 |
+| 最后验证 | 2026-08-28（WSL2、Ubuntu 24.04、dsh `0.1.1-rc.2`、Node 24） |
+
+## 📦 安装 / 升级 / 卸载
+
+需要一个 `dsh` profile（例如你跑 `dsh web` 的 `web` profile）。
+
+**安装**
+
+```sh
+# 从 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`**。
+
+**升级 / 卸载**
+
+```sh
+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 工具
+
+| 动作 | 效果 |
+|---|---|
+| `install` | （重新）创建 `~/.dsh/dsh-wsl-launcher` 下的启动脚本 + 图标，以及鲸鱼图标的桌面快捷方式（仅 WSL） |
+| `status` | WSL 检测、发行版名、interop 可用性、启动文件、Web 端口是否在监听（全平台） |
+| `open` | 用 Windows 默认浏览器打开 Web 界面（经 WSL interop） |
+| `uninstall` | 删除桌面快捷方式与整个 `~/.dsh/dsh-wsl-launcher` 目录（仅 WSL） |
+
+## ⚙️ 配置
+
+在 profile 的 `cordis.patch.yml`（如 `~/.dsh/profiles/web/cordis.patch.yml`）
+中覆盖插件行。patch 会整体替换该行 config，请保留需要保留的键：
+
+```yaml
+- 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` 使用或需要一次性运行，请显式启用，并锁定精确包版本：
+
+```yaml
+- 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，并可能下载该固定版本。
+
+不涉及任何敏感信息。
+
+## 🔐 权限与数据
+
+| 领域 | 插件做了什么 |
+|---|---|
+| 写入文件（WSL 侧） | `~/.dsh/dsh-wsl-launcher/dsh-web-launcher.sh` 与 `~/.dsh/dsh-wsl-launcher/icons/whale.ico` |
+| 写入文件（Windows 侧） | 仅桌面一个 `.lnk`（`DeepSeek Harness Web.lnk`）——由 `powershell.exe`（WScript.Shell）创建，不碰其他 Windows 文件 |
+| 读取文件 | 只读包内自带的模板与图标，以及 `/proc/version`（WSL 检测） |
+| 进程 | 经 WSL interop 拉起 `powershell.exe`（建/删快捷方式、浏览器兜底）与 `explorer.exe` / `cmd.exe`（开浏览器）；启动器本体是纯 ASCII 的 bash 脚本，运行前可以通读 |
+| 网络 | 仅回环：`status` 探测 `http://127.0.0.1:<port>`；浏览器由操作系统打开，不是插件打开 |
+| 凭据 | 无——从不读取、存储、发送凭据 |
+
+## 🔧 工作原理
+
+```
+┌──────────────────────────────┐   ┌────────────────────────────────────────────┐
+│  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 web` 日志里 `dsh-wsl-launcher: auto install skipped: …` 警告。通常是 WSL interop 被关：在 `C:\Users\<你>\.wslconfig` 的 `[boot]` 下设 `interop = true`（或改 wsl.conf），重启发行版，再跑 `wsl_launcher install`。 |
+| 工具输出 `powershell.exe not found` | 同上——interop 关闭，或 `/mnt` 下没有挂载的 Windows 盘。 |
+| 快捷方式出现了但图标是通用的 | 可能是 `\\wsl.localhost` 映射缺失（较老的 Windows）。插件会回退到 `\\wsl$`；若两者都没有，快捷方式照样能用，只是没图标。升级 Windows，或设 `withIcon: false` 跳过探测。 |
+| 快捷方式出现在奇怪的位置 | OneDrive 托管桌面：插件按 `%USERPROFILE%\Desktop` → `%OneDrive%\Desktop` → `%USERPROFILE%\OneDrive\Desktop` 的顺序取第一个存在的目录——与 Explorer 所见一致。 |
+| 启动脚本提示 `dsh was not found` | 默认 `installed` 模式下，非交互 shell 里找不到 `dsh`。在发行版里装好（`npm install -g @deepseek-ai/dsh`）；如果用 nvm，登录 shell 探测会找到它——或从同一环境重装插件以刷新记录路径。也可改为显式、固定版本的 `launchMode: npx`。 |
+| 启动脚本提示 `npx was not found` | `launchMode: npx` 要求非交互式 WSL 环境中可用 Node.js 和 `npx`。请安装 Node.js/npm，或将 `NPX_BIN` 指向可执行的 `npx`；`npxPackage` 必须保持精确固定版本。 |
+| 提示 `dsh web exited early` | 看错误上方控制台的输出（profile/CLI 问题，不是启动脚本的 bug）。 |
+| `EADDRINUSE` / 端口被占用 | 启动器检测到端口在监听会直接开浏览器。需要换端口就在 config 里设 `port`。 |
+| 浏览器开了但页面报 transport/403 | **浏览器信任围栏**拦截了跨源调用——DevTools → Network → 失败请求 → 看 `Origin`，必须是 `http://127.0.0.1:<port>`。常见元凶是浏览器扩展或残留标签页。 |
+| 没有弹出浏览器窗口 | 启动器会选择一种 Windows interop 启动方式：优先 `explorer.exe`，否则使用 PowerShell `Start-Process` 或 `cmd.exe /c start`；一次启动不会再串联其他方式，从而避免重复标签页。若全部不可用，会在控制台打印网址；请检查 WSL interop。 |
+| 快捷方式拉起了错误的发行版/用户 | `.lnk` 里编码了 `wsl.exe -d <发行版> [--user <用户>]`。在 config 里设 `distro` / `wslUser` 后重新 `wsl_launcher install`。 |
+| 关掉控制台窗口会怎样 | 故意的：控制台窗口就是服务器窗口——关窗会停掉 `dsh web`（脚本转发信号）。 |
+
+**回滚**：`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](LICENSE)。
+
+
+## 稳定性与容错
+
+- 启动、停止按端口使用原子锁，避免双击产生重复 `dsh web` 进程。
+- PID 文件必须是完整数字，停止前还会校验进程命令和进程组；陈旧或不匹配的 PID 只会被清理，不会误杀其他进程。
+- `status`、`install`、`stop`、`uninstall` 的外部文件和 Windows 互操作错误会返回可读结果。
+- 自动停止默认关闭。启用 `autostopEnabled` 后，只有同源 JSON 请求中的合法浏览器 client id 才会计入在线状态；错误请求会被拒绝。
+- `uninstall` 可重复执行；它只删除插件创建的快捷方式、Windows wrapper 和 launcher 目录，不会停止外部启动的服务。

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-wsl-launcher bundle layer -- applied when a profile lists this bundle
+# (package.json's `dsh.bundle.patch` points at this file; `dsh plugin add`
+# reconciles the package into the profile's bundle stack automatically).
+# `name` is the package name (resolved from the profile's node_modules),
+# not a relative path.
+#
+# The autostop settings are read from the environment at boot:
+#   DSH_WEB_AUTOSTOP=1            enable "stop the server when every browser
+#                                 tab is closed" (the launcher script exports
+#                                 it when it starts the background daemon)
+#   DSH_WEB_AUTOSTOP_GRACE_MS     idle window before shutdown (default 30000)
+#   DSH_WEB_AUTOSTOP_MIN_UPTIME_MS startup grace before any shutdown (default
+#                                 45000 -- covers page load + first beat)
+- insert:
+    - id: wsl-launcher
+      name: dsh-wsl-launcher
+      # webServer feeds the optional autostop feature (lib/autostop.js).
+      # On a non-web host this row simply fails to load (the loader
+      # continues without it) and the plugin is absent.
+      inject: [webServer]
+      config:
+        autostopEnabled: !!js process.env.DSH_WEB_AUTOSTOP === '1'
+        autostopGraceMs: !!js (Number(process.env.DSH_WEB_AUTOSTOP_GRACE_MS) || 30000)
+        autostopMinUptimeMs: !!js (Number(process.env.DSH_WEB_AUTOSTOP_MIN_UPTIME_MS) || 45000)