dsh-wsl-tool 1.10.11 → 1.11.0

package/PUBLISHING.md

@@ -78,7 +78,7 @@ both that the entry stays relative and that it resolves.
    It must print `function` and the resolved defaults. If it prints `undefined`,
    the plugin declares no `Config`, the platform has no schema to project, the
    entry's config status stays `absent` and the sidebar panel renders without a
-   single switch while all three tools keep working. The fragile step is the
+   single switch while every tool keeps working. The fragile step is the
    interop hop: `@deepseek-ai/schemastery` exports its builder as the **default**
    export, so `const { Schema } = await import(...)` silently yields `undefined`
    (see `lib/schema.js`, and the regression test that pins the picking).
@@ -117,6 +117,22 @@ both that the entry stays relative and that it resolves.
    artifact, not just the metadata. Scripted requests to `npmjs.com`'s HTML hit a
    Cloudflare challenge; the registry API is the source of truth.
 
+   Two things make a published release look unpublished, so rule them out before
+   believing a negative:
+
+   - **A green run is not proof that npm was published.** The `Publish to npm`
+     step exits 0 with a warning when `NPM_TOKEN` is absent, so the run stays
+     green while npm is skipped. Ask the jobs API whether the step really ran —
+     a real run has `started_at`; a skipped one has `conclusion: skipped` and no
+     timestamp — and ask the registry what actually handles the version
+     (`time[<version>]` on the packument).
+
+   - **A failing `npm whoami` says nothing about the release.** A stale token in
+     `~/.npmrc` only means that machine cannot publish by hand; CI has its own
+     credential. Release state lives in the three artifacts — the tag's commit,
+     the release asset, and the registry tarball — so compare their bytes rather
+     than your credentials.
+
    Expect the registry's caches to lag a publish by minutes, and to lag
    *inconsistently*: the full packument, the abbreviated (install) packument,
    `/-/package/<name>/dist-tags` and the tarball URL each cache separately, so one
@@ -171,24 +187,43 @@ consequences worth remembering:
   hand-written keys are `url`, `name`, `category`, `tarball` and `description`;
   everything else (including `screenshots`) is generated and must not be written by
   hand. Only the description needs a PR against `awesome-dsh-plugin`.
-- **Replacing a file in place refreshes the preview at the same URL**, which is why
-  `assets/screenshot-1.png` keeps its name across redesigns. GitHub's raw endpoint
-  caches, so a stale image can survive a few minutes to a day.
-
-The current preview is rendered from `assets/market-preview.html` (the editable
-source of truth) with headless Edge:
+- **Replacing a file in place does NOT refresh the preview.** Two caches are keyed on
+  the exact URL string and neither revalidates the bytes: dsh-market loads images
+  through the `images.weserv.nl` proxy (`?url=<the raw URL>&h=<height>&we=1` — see its
+  `client/client.js`), and the DSH desktop webview keeps its own HTTP disk cache under
+  `%APPDATA%\@deepseek-ai\dsh-desktop\Cache\Cache_Data`. A redesign committed over the
+  same path therefore keeps serving the previous image for as long as those copies
+  live. The 2026-10-05 preview did exactly that: the mode-picker screenshot (with
+  `WSL Dev` ticked) was replaced in place at `assets/screenshot-1.png`, and the listing
+  went on showing it. **Ship a preview under a new filename** — add the file, point
+  `screenshots.json` and the README embed at it, and retire the old path.
+  Retiring it costs one day of transition: the catalog's `screenshots` array is
+  generated from this repository and published about once a day, so a client still
+  holding the previous catalog requests the old URL after the file is gone and finds
+  nothing. Keep the old file until the next catalog publish when that URL is worth
+  keeping alive; delete it in the same change when the point is to retire the URL
+  (as here), accepting the empty slot until the rebuild.
+
+The preview is rendered from `assets/market-preview.html` (the editable source of
+truth) with headless Edge, under a **new filename each redesign** — the name is what
+defeats the caches, so the render target changes with the design:
 
 ```powershell
+$out = Join-Path $PWD 'assets\market-preview-<new>.png'
+$url = 'file:///' + ($PWD.Path -replace '\\','/') + '/assets/market-preview.html'
 & 'C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe' --headless=new `
   --disable-gpu --hide-scrollbars --force-device-scale-factor=2 `
-  --window-size=1280,800 --virtual-time-budget=3000 `
-  --user-data-dir="$env:TEMP\edge-shot" `
-  --screenshot="assets\screenshot-1.png" "file:///$PWD/assets/market-preview.html"
+  --window-size=1280,800 --virtual-time-budget=4000 `
+  --user-data-dir="$env:TEMP\edge-shot" --screenshot="$out" $url
 ```
 
-It renders 2560×1600 (1280×800 at 2×) in a few seconds with no browser window. The
-`--user-data-dir` keeps it away from the user's real Edge profile. Edit the HTML,
-re-run, and commit the PNG: no build step, no design tool.
+Two things the renderer demands: `--screenshot` must be an **absolute** path (Edge
+resolves it against its own working directory, and a relative one fails with
+"Failed to write file … 系统找不到指定的路径"), and `--headless=new` needs a moment
+before the file appears. It renders 2560×1600 (1280×800 at 2×) in a few seconds with
+no browser window; `--user-data-dir` keeps it away from the user's real Edge profile.
+Edit the HTML, re-run, commit the PNG, and point `screenshots.json` plus the README
+embed at the new name: no build step, no design tool.
 
 ## Things that bite
 

package/README.md

@@ -15,17 +15,20 @@ project kept on a Windows drive keeps **Windows** filesystem semantics — no PO
 permissions, case-insensitive names, no file-change notifications — at a fraction
 of the speed (see [Notes](#notes)).
 
-![The three tools, the left-sidebar switch panel, and the two limits](assets/market-preview.png)
+![The feature list and the left-sidebar switch panel](assets/market-preview-features-3.png)
 
 ## Tools
 
-The plugin registers three tools:
+The plugin registers five tools (the last two can be switched off independently,
+and `wsl-bootstrap` is OFF by default):
 
 | Tool | Purpose |
 |---|---|
 | `wsl` | Run a Linux command and return `stdout`/`stderr` with exit-code, timeout and truncation markers. |
 | `wsl-path` | Convert between Windows and WSL paths via `wslpath`. |
 | `wsl-env` | Summarize the WSL environment (distros, kernel, cpu, mem, disk). |
+| `wsl-doctor` | Compare what a project needs with what the distribution has — including commands that are really Windows binaries. Read-only. |
+| `wsl-bootstrap` | Install the missing toolchain inside the distribution, from a fixed recipe list, plan first. |
 
 ### `wsl`
 
@@ -90,6 +93,96 @@ unknown distro is an error rather than a partial answer. Note that `wsl --versio
 is **localized**, so its labels are passed through as the launcher printed them
 rather than parsed by name; the Direct3D/MSRDC/DXCore versions are omitted.
 
+### `wsl-doctor`
+
+Answers the question a project's own README cannot: **will the tooling this
+checkout expects actually work inside this distribution?** It reads the manifests
+in the directory (`package.json` and lockfiles, `.nvmrc`, `tsconfig.json`,
+`Cargo.toml`, `go.mod`, `pyproject.toml`, `requirements.txt`, `Dockerfile`,
+`docker-compose.yml`, `Makefile`, `CMakeLists.txt`) and reports, per need, whether
+it resolves on the Linux side:
+
+```
+distro: Ubuntu-22.04 (system default)
+workspace: /mnt/d/proj (Windows drive mount /mnt/d — builds, installs and git are much slower here; …)
+project: package.json, pnpm-lock.yaml
+
+needs (from the project): node, npm, pnpm
+  MISSING node — not on PATH in this distribution (from package.json)
+  WINDOWS npm — resolves to /mnt/c/Program Files/nodejs/npm, a Windows binary reached through interop; …
+  MISSING pnpm — not on PATH in this distribution (from pnpm-lock.yaml)
+
+usable on the Linux side: python3 3.10.12, gcc 11.4.0, make 4.3, git 2.34.1, curl, rsync, tar, sudo
+Windows binaries on the Linux PATH (interop): npm -> /mnt/c/Program Files/nodejs/npm, npx -> …
+privileges: uid=1000 (xiny) · sudo: requires a password (unusable from a tool call) · root: switched off
+
+next: node, npm are not usable — wsl-bootstrap({ recipes: ["node", "pnpm"] }) installs them …
+```
+
+That `WINDOWS` row is the reason the tool exists. WSL appends the Windows `PATH`
+to the Linux one, so `npm` resolves on a machine whose distribution has no `node`
+at all — measured here as `/mnt/c/Program Files/nodejs/npm` — and the errors a
+model gets from running it against a Linux directory name neither cause. Overall
+it is read-only, cheap, and worth running before blaming a failed command on the
+command. Takes an optional `workspace` (a Linux directory; default: the configured
+directory, else the session workspace) and `distro`.
+
+### `wsl-bootstrap`
+
+Installs the missing toolchain **inside the distribution**, from a fixed recipe
+list and nothing else: `node` (Node.js LTS into `/usr/local`, checksum-verified,
+with corepack), `pnpm`, `python` (python3 + pip + venv), `build`
+(build-essential), `tools` (jq, rsync, curl, git, ca-certificates). Dependencies
+are added when they are needed: `pnpm` brings `node`, and `node` brings `tools`
+when `curl` is missing.
+
+**It is off by default**, and its `dryRun` defaults to `true`, so the first call
+prints the plan and changes nothing:
+
+```
+dry run — nothing has been installed (distro Ubuntu-22.04)
+
+already present:
+  python — python3, pip and venv (apt)
+
+to install (python, tools):
+  [tools] apt packages: ca-certificates curl git jq rsync — runs as root inside the distribution
+      export DEBIAN_FRONTEND=noninteractive; apt-get update && apt-get install -y ca-certificates curl git jq rsync
+
+apt would report:
+  Inst libjq1 (1.6-2.1ubuntu3.2 Ubuntu:22.04/jammy-updates [amd64])
+  …
+
+run it for real with `dryRun: false`.
+```
+
+The apt recipes collapse into **one** step (the `apt-get update` is the slow half,
+and running it once per recipe would look like a hang), and an `apt-get -s`
+simulation is included so the plan shows what apt itself would do. Recipes already
+satisfied are skipped, so a second run is cheap. The steps run through
+`wsl -u root` — see the next section for why — and a failing step stops the run
+with the tail of its output.
+
+## Running privileged commands (`asRoot`)
+
+`sudo` cannot work from a tool call: it needs a password, and stdin is `/dev/null`
+unless you send one. WSL has its own answer — `wsl.exe -u root` needs no password
+(measured: it answers `uid=0` on a machine where `sudo -n` fails) — so the `wsl`
+tool exposes it as `asRoot: true`, gated by a switch in the panel
+(「管理员模式（root）」, off by default):
+
+```
+wsl({ command: 'apt-get install -y jq', description: 'install jq', asRoot: true })
+```
+
+The authorisation is the switch, not the parameter: with it off, `asRoot: true` is
+**refused with that instruction** rather than quietly downgraded to your user
+account — a caller that asked for root and got a permission error would look for
+the cause in the wrong place. Every privileged result is marked
+(`[ran as root: wsl -u root]`) so a transcript says what happened, and the
+destructive-command guard applies independently: `rm -rf` still needs
+`allowDangerous: true`, as root or not.
+
 ## Install
 
 The published npm package is **`dsh-wsl-tool`**, not `dsh-wsl`: the registry
@@ -110,8 +203,10 @@ specifier you install under.
    checkout (which names the dependency after this package).
 
 2. Nothing else. The package's `cordis.patch.yml` inserts the `tool-wsl` row
-   itself when the bundle is loaded, process-wide, so the three tools are
-   available to every agent preset without further wiring.
+   itself when the bundle is loaded, process-wide, so the tools are
+   available to every agent preset without further wiring. **There is no mode to
+   pick and nothing to add to a preset** — the left-sidebar WSL panel arrives the
+   same way.
 
    Do **not** also list `tool-wsl` in a preset: DSH registers tools by name, and
    the second registration fails with
@@ -122,13 +217,23 @@ specifier you install under.
 The settings panel is the one optional piece: its form needs
 `@deepseek-ai/schemastery`, which most profiles already have (any plugin that
 depends on it brings it in — add it to the profile's dependencies if yours does
-not). Without it, the three tools and the panel's 「WSL 终端启动路径」 field work
+not). Without it, the tools and the panel's 「WSL 终端启动路径」 field work
 as usual and only the switches are absent — the panel says so instead of waiting
 forever.
 
 ## Compatibility
 
-Verified against DSH **0.1.7-rc.2** (and 0.1.5-rc.2 before it): the tool schemas
+The manifest declares the DSH it needs — `"engines": { "dsh": ">=0.1.7-rc.2" }` —
+which is the floor this section documents. The plugin market reads that
+declaration from the published manifest and shows it as a requirement on the
+entry (`DSH >=0.1.7-rc.2`), warning before an install or update onto an older
+host; DSH itself ignores `engines`, so the declaration is advice, not a gate.
+The `-rc.2` is load-bearing: `>=0.1.7` alone excludes the `0.1.7-rc.2` release
+this line was verified on, and the market would then report the plugin as
+incompatible with its own verified host.
+
+Verified against DSH **0.1.7-rc.2** (earlier releases of this plugin were verified
+on 0.1.5-rc.2): the tool schemas
 pass DSH's own `assertSupportedJsonSchema`, the subprocess seam is exercised
 against the real provider rather than a shim, and the background-job path is
 checked against the real job registry, including the session-id ownership fence
@@ -160,6 +265,9 @@ explanation.
 | Linux 默认工作目录 | a fixed Linux directory (for example `/mnt/d/project`) used when `workdir` is omitted. Filling it in wins over the switch above; clearing it goes back to following the session |
 | WSL 终端启动路径 | the optional sidebar terminal's startup directory — `--cd <dir>` on the `terminal-controller` row of your **profile patch** (see [Optional: a WSL terminal in the sidebar](#optional-a-wsl-terminal-in-the-sidebar)). Empty clears it, and the panel reads the current value from the same file |
 | 危险命令守卫 | whether a destructive command needs an explicit `allowDangerous` |
+| 管理员模式（root） | whether `wsl` accepts `asRoot: true` (`wsl -u root`). WSL's root needs no password, so this switch is the authorisation itself; **off by default** |
+| wsl-doctor 项目体检 | registers `wsl-doctor` |
+| wsl-bootstrap 安装工具链 | registers `wsl-bootstrap`, which may install into the distribution. **Off by default**, and its `dryRun` still has to be turned off per call |
 
 The panel edits the plugin's own configuration, so the same values can be written
 by hand (`- id: tool-wsl` with `config:` in a profile patch) or by environment
@@ -179,7 +287,7 @@ features — set them in the patch or with `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_M
 and the panel shows what is currently in effect.
 
 The settings surface needs `@deepseek-ai/schemastery`, which the plugin declares as
-an optional peer dependency: without it the three tools still run on their defaults
+an optional peer dependency: without it the tools still run on their defaults
 and only the panel is missing.
 
 At the bottom of the panel there is one feedback entry, next to it a short
@@ -246,10 +354,18 @@ start too.
 | `stdin` | no | string | text written to the command stdin (UTF-8) before it runs |
 | `runInBackground` | no | boolean | run as a job and return its id immediately; read with `job_output`, stop with `job_kill` |
 | `allowDangerous` | no | boolean | set `true` to run destructive commands |
+| `asRoot` | no | boolean | run this call as root (`wsl -u root`); refused unless the panel's 管理员模式 switch is on |
 | `translatePaths` | no | boolean | default `true`; set `false` to pass `command` through verbatim |
 
 ## Configuration
 
+The panel's switches and value fields (`tools.wsl`, `tools.path`, `tools.env`,
+`tools.doctor`, `tools.bootstrap`, `backgroundJobs`, `translatePaths`,
+`startInSessionWorkspace`, `workdir`, `dangerGuard`, `allowRoot`, `distro`,
+`timeoutMs`) live in the profile patch and take effect as described on each row.
+Two of them have no environment variable on purpose: `dangerGuard` (its OFF
+position is the footgun) and `allowRoot` (WSL's root needs no password, so the
+switch IS the authorisation). The environment layer:
 | Environment variable | Default | Effect |
 |---|---|---|
 | `DSH_WSL_DISTRO` | (system default) | Pin the distribution for every call. |
@@ -259,7 +375,7 @@ start too.
 | `DSH_WSL_MAX_OUTPUT_BYTES` | `65536` | Per-stream in-memory window (1 KiB – 8 MiB). Also raises the spill ceiling when set above 64 MiB. |
 
 An unparsable or out-of-range value falls back to the default: one bad variable
-must not take all three tools down. Values are read once per mount, so a change
+must not take every tool down. Values are read once per mount, so a change
 takes effect on restart.
 
 ## Notes
@@ -362,9 +478,11 @@ is split by concern:
 | `lib/result.js` | Launcher-noise filters, truncation facts, marker rendering. |
 | `lib/diagnostics.js` | The `wsl-env` capability probe, its parser and its lines. |
 | `lib/runner.js` | The single spawn path plus launcher-error classification. |
-| `lib/tools/*.js` | The three tool definitions (schema, execute, presentCall). |
+| `lib/tools/*.js` | The tool definitions (schema, execute, presentCall). |
+| `lib/doctor.js` | The project probe for `wsl-doctor`: one shell script, its parser, the report composer. |
+| `lib/bootstrap.js` | The recipes, plan builder and outcome rendering for `wsl-bootstrap`. |
 
-- `apply()` resolves the configuration and registers three tools, each with a
+- `apply()` resolves the configuration and registers the enabled tools, each with a
   JSON-schema parameter definition, an output schema, a `render` hook and an
   async `execute`.
 - Every call goes through one spawn path (`runner.runWsl`): `wsl.exe -d <distro>
@@ -394,8 +512,8 @@ is split by concern:
   segments, judges each `rm` invocation on its own flags, and matches the
   device/power tools at command position before dispatch.
 
-The plugin publishes no services of its own, so it sits loose in an agent
-preset without a realm.
+The plugin publishes no services of its own and is inserted process-wide by its own
+bundle patch, so it needs no realm — and no preset entry either.
 
 ## Development
 
@@ -406,19 +524,19 @@ DSH host plane. Iterate by pointing a profile dependency at the checkout:
 { "dependencies": { "dsh-wsl-tool": "file:/path/to/dsh-wsl" } }
 ```
 
-then restart DSH and exercise the tools from a session that uses a preset
-containing the `tool-wsl` row.
+then restart DSH and call the tools from **any** session: the bundle patch registers
+them process-wide, so no preset declares the row.
 
 ### Tests
 
 ```sh
-npm test          # 260+ checks against real WSL, with a shim standing in for ctx.subprocess
+npm test          # 591 host checks against real WSL (shim for ctx.subprocess) + 133 client checks
 npm run test:real # the same checks against the REAL provider, plus the seam-fact suite
 ```
 
 `npm test` substitutes only `ctx.subprocess`, with a shim that reproduces the
 seam's bounded tail windows, spill files and termination ladder, and drives the
-three tools against the real WSL installation. It covers path translation,
+the tools against the real WSL installation. It covers path translation,
 workdir quoting, the destructive guard, distro selection, exit-code/timeout/
 truncation markers, `wsl-path`, `wsl-env`, argument validation, configuration
 parsing, launcher-error classification, the returned shape against each declared

package/README.zh-CN.md

@@ -11,17 +11,19 @@ Linux 原生 DSH：真实的 Linux 内核与 bash、退出码与信号、超时
 （见[沙箱边界](#沙箱边界)）；项目放在 Windows 盘上时仍是 **Windows** 的文件系统语义——没有 POSIX
 权限位、文件名大小写不敏感、收不到文件变更通知——速度也低一个数量级（见[注意事项](#注意事项)）。
 
-![三个工具、左侧栏开关面板与两条限制](assets/market-preview.png)
+![功能清单与左侧栏开关面板](assets/market-preview-features-3.png)
 
 ## 工具
 
-插件注册三个工具：
+插件注册五个工具（后两个可单独关掉，其中 `wsl-bootstrap` **默认关**）：
 
 | 工具 | 用途 |
 |---|---|
 | `wsl` | 执行 Linux 命令，返回带退出码、超时与截断标记的 `stdout`/`stderr` |
 | `wsl-path` | 通过 `wslpath` 在 Windows 与 WSL 路径间互转 |
 | `wsl-env` | 汇总 WSL 环境（发行版、内核、CPU、内存、磁盘） |
+| `wsl-doctor` | 对照项目清单与发行版实际能力，指出缺什么——包括那些其实是 Windows 二进制的命令。只读 |
+| `wsl-bootstrap` | 按固定配方在发行版里补装缺失的工具链，先出计划再动手 |
 
 ### `wsl`
 
@@ -78,6 +80,82 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
 发行版不存在则直接报错，而不是给出一份残缺答案。注意 `wsl --version` 输出是**本地化**的，
 因此其标签按启动器原样透传、不按名称解析；Direct3D/MSRDC/DXCore 版本作为噪声被省略。
 
+### `wsl-doctor`
+
+回答一个项目自己的 README 答不了的问题：**这份代码指望的工具链，在这套发行版里真的能用吗？**
+它读取目录里的清单（`package.json` 与各种 lockfile、`.nvmrc`、`tsconfig.json`、`Cargo.toml`、
+`go.mod`、`pyproject.toml`、`requirements.txt`、`Dockerfile`、`docker-compose.yml`、`Makefile`、
+`CMakeLists.txt`），然后逐项给出它在 Linux 侧的位置：
+
+```
+distro: Ubuntu-22.04 (system default)
+workspace: /mnt/d/proj (Windows drive mount /mnt/d — builds, installs and git are much slower here; …)
+project: package.json, pnpm-lock.yaml
+
+needs (from the project): node, npm, pnpm
+  MISSING node — not on PATH in this distribution (from package.json)
+  WINDOWS npm — resolves to /mnt/c/Program Files/nodejs/npm, a Windows binary reached through interop; …
+  MISSING pnpm — not on PATH in this distribution (from pnpm-lock.yaml)
+
+usable on the Linux side: python3 3.10.12, gcc 11.4.0, make 4.3, git 2.34.1, curl, rsync, tar, sudo
+Windows binaries on the Linux PATH (interop): npm -> /mnt/c/Program Files/nodejs/npm, npx -> …
+privileges: uid=1000 (xiny) · sudo: requires a password (unusable from a tool call) · root: switched off
+
+next: node, npm are not usable — wsl-bootstrap({ recipes: ["node", "pnpm"] }) installs them …
+```
+
+那行 `WINDOWS` 就是它存在的理由。WSL 会把 Windows 的 `PATH` 接到 Linux 的后面，于是
+`npm` 在一套**根本没有 `node`** 的发行版里"找得到"（本机实测就是
+`/mnt/c/Program Files/nodejs/npm`），模型拿它去跑 Linux 目录时报的错两头都不沾。整体只读、
+开销很小，值得在把失败归咎于命令本身之前先跑一次。可选参数 `workspace`（Linux 目录；默认取
+配置的目录，否则取会话工作区）与 `distro`。
+
+### `wsl-bootstrap`
+
+**在发行版内部**补装缺失的工具链，只认固定配方：`node`（Node.js LTS 装进 `/usr/local`，
+校验 sha256，并启用 corepack）、`pnpm`、`python`（python3 + pip + venv）、`build`
+（build-essential）、`tools`（jq、rsync、curl、git、ca-certificates）。依赖按需带上：
+`pnpm` 会带上 `node`，`curl` 缺失时 `node` 会带上 `tools`。
+
+**它默认关**，且 `dryRun` 默认为 `true`，所以第一次调用只打印计划、什么都不改：
+
+```
+dry run — nothing has been installed (distro Ubuntu-22.04)
+
+already present:
+  python — python3, pip and venv (apt)
+
+to install (python, tools):
+  [tools] apt packages: ca-certificates curl git jq rsync — runs as root inside the distribution
+      export DEBIAN_FRONTEND=noninteractive; apt-get update && apt-get install -y ca-certificates curl git jq rsync
+
+apt would report:
+  Inst libjq1 (1.6-2.1ubuntu3.2 Ubuntu:22.04/jammy-updates [amd64])
+  …
+
+run it for real with `dryRun: false`.
+```
+
+所有 apt 配方会**合并成一步**（`apt-get update` 是慢的那一半，每个配方各跑一次看起来就像卡死），
+并附带一条 `apt-get -s` 只读模拟，让计划直接显示 apt 自己会做什么。已经满足的配方会被跳过，
+所以第二次跑很便宜。步骤通过 `wsl -u root` 执行——为什么见下一节——某一步失败即停下并附上
+它的输出末尾。
+
+## 以 root 执行（`asRoot`）
+
+`sudo` 在工具调用里根本用不了：它要密码，而除非你显式喂 stdin，stdin 就是 `/dev/null`。
+WSL 自带答案——`wsl.exe -u root` **免密**（本机实测：`sudo -n` 失败时它照样给出 `uid=0`）——
+于是 `wsl` 工具把它暴露成 `asRoot: true`，由面板里一项开关把关（「管理员模式（root）」，默认关）：
+
+```
+wsl({ command: 'apt-get install -y jq', description: 'install jq', asRoot: true })
+```
+
+授权来自开关而不是参数：开关关着时，`asRoot: true` 会被**明确拒绝并给出开关位置**，而不是
+悄悄降级成你的普通用户——一个要了 root 却拿到权限错误的人，会去错误的地方找原因。每次以 root
+执行的结果都会标注（`[ran as root: wsl -u root]`），转录里说得清发生过什么；危险命令守卫则
+独立生效：`rm -rf` 无论是不是 root 都仍需 `allowDangerous: true`。
+
 ## 安装
 
 发布到 npm 的包名是 **`dsh-wsl-tool`**，不是 `dsh-wsl`：registry 判定 `dsh-wsl` 与既有包
@@ -96,7 +174,8 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
    （依赖名会取本包自身的名字）。
 
 2. 不必再做别的。本包的 `cordis.patch.yml` 会在组合包加载时**自己插入** `tool-wsl` 行
-   （进程级），因此三个工具对所有 agent preset 都可用，无需额外接线。
+   （进程级），因此这些工具对所有 agent preset 都可用，无需额外接线。**不需要选择任何模式，
+   也不要在 preset 里加任何东西**——左侧栏的 WSL 面板同样是这样出现的。
 
    **不要**再在 preset 里列一遍 `tool-wsl`：DSH 按名字注册工具，第二次注册会直接失败
    —— `tool "wsl" is already registered in this scope`。这一行只由组合包提供。
@@ -104,12 +183,18 @@ launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71
 3. 重启 DSH。
 
 设置面板是唯一可选的一块：它的表单需要 `@deepseek-ai/schemastery`，多数 profile 已经有了
-（只要装过任何依赖它的插件；没有的话把它加进 profile 的依赖即可）。没有它时，三个工具与
+（只要装过任何依赖它的插件；没有的话把它加进 profile 的依赖即可）。没有它时，工具与
 面板里的「WSL 终端启动路径」照常可用，只是开关不显示 —— 面板会直接说明这一点，不会一直转圈等待。
 
 ## 兼容性
 
-已在 DSH **0.1.7-rc.2** 上验证（此前为 0.1.5-rc.2）：工具 schema 通过 DSH 自己的
+清单里声明了它需要的 DSH —— `"engines": { "dsh": ">=0.1.7-rc.2" }`，也就是本节记录的
+下限。插件市场会从已发布的清单读取这条声明，在条目上标成要求（`DSH >=0.1.7-rc.2`），并在
+装到更老的宿主上之前给出提醒；DSH 自身不读 `engines`，所以它是提示而不是门禁。那个
+`-rc.2` 不能省：只写 `>=0.1.7` 会把本条验证过的 `0.1.7-rc.2` 排除掉，市场于是会把插件
+判成与它自己验证过的宿主不兼容。
+
+已在 DSH **0.1.7-rc.2** 上验证（本插件的更早版本曾在 0.1.5-rc.2 上验证）：工具 schema 通过 DSH 自己的
 `assertSupportedJsonSchema`；subprocess 接缝是跑在**真实 provider** 上而非替身；后台任务
 路径跑在**真实 job 注册表**上，包含 0.1.7 收紧的「会话 id 属主围栏」。这套检查就是
 `test/real-seam.mjs`，约一分钟即可重验一个新宿主——升级后把它指向新的 DSH 安装即可：
@@ -138,6 +223,9 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 | Linux 默认工作目录 | 未传 `workdir` 时使用的固定 Linux 目录（如 `/mnt/d/project`）。填了就优先于上面的开关；清空则回到跟随会话 |
 | WSL 终端启动路径 | 可选的侧边栏终端从哪个目录启动 —— 写进你 **profile patch** 里 `terminal-controller` 那一行的 `--cd <目录>`（见[可选：在侧边栏开一个 WSL 终端](#可选在侧边栏开一个-wsl-终端)）。留空则删掉该参数；当前值也是从这个文件读的 |
 | 危险命令守卫 | 危险命令是否必须显式 `allowDangerous` |
+| 管理员模式（root） | `wsl` 是否接受 `asRoot: true`（`wsl -u root`）。WSL 的 root 免密，所以这项开关就是授权本身；**默认关** |
+| wsl-doctor 项目体检 | 注册 `wsl-doctor` |
+| wsl-bootstrap 安装工具链 | 注册 `wsl-bootstrap`，它可能往发行版里装东西。**默认关**，且每次调用还得显式关掉 `dryRun` |
 
 面板改的是插件自己的配置，所以同样的值也可以手写进 profile patch（`- id: tool-wsl` 加 `config:`）
 或用环境变量设。优先级由 `lib/config.js` 定：**插件配置 > 环境变量 > 内置默认值**；开关停在默认值时
@@ -150,7 +238,7 @@ patch 层 —— 每次写入前先备份该文件，只重写终端那一行的
 **改动在下次启动 DSH 后生效**：宿主每次挂载只读一次该配置，面板里也写着这句。发行版与超时属于"值"
 而不是"功能"：在 patch 里或用 `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_MS` 设置，面板只显示当前生效值。
 
-这个设置界面需要 `@deepseek-ai/schemastery`（插件把它声明为可选 peer 依赖）：没有它三个工具照常按
+这个设置界面需要 `@deepseek-ai/schemastery`（插件把它声明为可选 peer 依赖）：没有它工具照常按
 默认值工作，只是没有面板。
 
 面板**最底部**是一个反馈入口，旁边跟着一段简短的提交指南，以及一个「复制插件信息」按钮（详见
@@ -205,10 +293,17 @@ patch 层 —— 每次写入前先备份该文件，只重写终端那一行的
 | `stdin` | 否 | string | 在命令运行前写入其 stdin 的文本（UTF-8） |
 | `runInBackground` | 否 | boolean | 作为后台任务运行并立即返回任务 id；用 `job_output` 读、`job_kill` 停 |
 | `allowDangerous` | 否 | boolean | 置 `true` 才允许执行危险命令 |
+| `asRoot` | 否 | boolean | 本次调用以 root 执行（`wsl -u root`）；面板「管理员模式」关着时会被拒绝 |
 | `translatePaths` | 否 | boolean | 默认 `true`；置 `false` 时 `command` 原样传入，不做路径改写 |
 
 ## 配置
 
+面板里的开关与取值字段（`tools.wsl`、`tools.path`、`tools.env`、`tools.doctor`、
+`tools.bootstrap`、`backgroundJobs`、`translatePaths`、`startInSessionWorkspace`、`workdir`、
+`dangerGuard`、`allowRoot`、`distro`、`timeoutMs`）都写在 profile patch 里，各自行上有说明。
+其中两项**故意没有环境变量**：`dangerGuard`（它的关闭位置本身就是风险）与 `allowRoot`
+（WSL 的 root 免密，所以那项开关就是授权本身）。环境变量这一层：
+
 | 环境变量 | 默认值 | 作用 |
 |---|---|---|
 | `DSH_WSL_DISTRO` | （系统默认） | 为所有调用固定发行版 |
@@ -217,7 +312,7 @@ patch 层 —— 每次写入前先备份该文件，只重写终端那一行的
 | `DSH_WSL_MAX_OUTPUT_BYTES` | `65536` | 每条流的内存窗口（1 KiB – 8 MiB）；设到 64 MiB 以上时也会抬高落盘上限 |
 | `DSH_WSL_WORKDIR` | `home` | 不传 `workdir` 时的起点：`home`（Linux 的 `~`）、`session`（会话工作目录，Windows 检出对应 `/mnt/<盘>/...`），或任意显式路径 |
 
-无法解析或越界的值会回退到默认值——一个写错的环境变量不该让三个工具一起挂掉。
+无法解析或越界的值会回退到默认值——一个写错的环境变量不该让所有工具一起挂掉。
 配置在挂载时读取一次，改动需重启 DSH 生效。
 
 ## 注意事项
@@ -331,9 +426,11 @@ argv 包一层过 `ctx.sandbox`）和文件系统服务（`@deepseek-ai/dsh-fs-s
 | `lib/result.js` | 启动器噪声过滤、截断事实、标记渲染 |
 | `lib/diagnostics.js` | `wsl-env` 的能力探针、解析器与输出行 |
 | `lib/runner.js` | 唯一的 spawn 路径与启动器错误分类 |
-| `lib/tools/*.js` | 三个工具定义（schema / execute / presentCall） |
+| `lib/tools/*.js` | 工具定义（schema / execute / presentCall） |
+| `lib/doctor.js` | `wsl-doctor` 的项目探针：一段 shell、它的解析器与报告组装 |
+| `lib/bootstrap.js` | `wsl-bootstrap` 的配方、计划生成与结果渲染 |
 
-- `apply()` 解析配置并注册三个工具，每个都有 JSON-schema 参数定义、输出 schema、
+- `apply()` 解析配置并注册被启用的工具，每个都有 JSON-schema 参数定义、输出 schema、
   `render` 钩子与异步 `execute`。
 - 所有调用都走同一条 spawn 路径（`runner.runWsl`）：通过宿主 `subprocess` 执行
   `wsl.exe -d <distro> -e bash -lc "<exports; cd workdir && command>"`，stdout/stderr
@@ -353,7 +450,8 @@ argv 包一层过 `ctx.sandbox`）和文件系统服务（`@deepseek-ai/dsh-fs-s
 - 危险命令防护把命令按 `;`／`&`／`|`／换行切成段，每次 `rm` 调用按自身标志单独判定，
   设备/电源类工具在命令位置匹配后才拦截。
 
-插件不发布任何自身服务，因此它可以无 realm 地挂在 agent preset 中。
+插件不发布任何自身服务，且由它自己的组合包 patch **进程级**插入，因此既不需要 realm，
+也不需要任何 preset 条目。
 
 ## 开发
 
@@ -364,17 +462,18 @@ argv 包一层过 `ctx.sandbox`）和文件系统服务（`@deepseek-ai/dsh-fs-s
 { "dependencies": { "dsh-wsl-tool": "file:/path/to/dsh-wsl" } }
 ```
 
-然后重启 DSH，在包含 `tool-wsl` 行的 preset 会话中调用工具验证。
+然后重启 DSH，在**任意**会话里调用工具即可：组合包 patch 是进程级注册的，没有哪个 preset
+需要声明这一行。
 
 ### 测试
 
 ```sh
-npm test          # 260+ 项检查，跑在真实 WSL 上，仅用 shim 顶替 ctx.subprocess
+npm test          # 591 项宿主检查（跑在真实 WSL 上，仅用 shim 顶替 ctx.subprocess）+ 133 项客户端检查
 npm run test:real # 同一套检查改跑真实 provider，外加 seam 事实套件
 ```
 
 `npm test` 只替换 `ctx.subprocess`，用一个复刻了 seam 行为（有界尾窗、落盘文件、
-终止阶梯）的 shim 驱动三个工具跑在真实 WSL 上，覆盖路径改写、workdir 引号处理、
+终止阶梯）的 shim 驱动这些工具跑在真实 WSL 上，覆盖路径改写、workdir 引号处理、
 危险命令防护、发行版选择、退出码/超时/截断标记、`wsl-path`、`wsl-env`、参数校验、
 配置解析、启动器错误分类、返回结构与各自 `output.schema` 的一致性，以及模型可见
 目录的 token 预算。

package/SUPPORT.md

@@ -32,5 +32,5 @@ The panel ends with **one** feedback entry: a submission guide beside it (how to
 
 ## 修复的节奏 / How fixes happen
 
-报告 → 复现（必要时我会请你补 `wsl-env` 输出）→ 改代码 → 测试（这个插件有 347 项宿主检查 + 76 项客户端检查）→ 发版（npm + 市场资产同一次发布，逐字节一致）→ 你升级后回帖确认 → 关闭。
-Report → reproduce (I may ask for a full `wsl-env`) → fix → tests (the plugin ships with 347 host checks and 76 client checks) → release (npm and the market asset go out byte-identical in one run) → you confirm after upgrading → close.
+报告 → 复现（必要时我会请你补 `wsl-env` 输出）→ 改代码 → 测试（这个插件有 591 项宿主检查 + 133 项客户端检查）→ 发版（npm + 市场资产同一次发布，逐字节一致）→ 你升级后回帖确认 → 关闭。
+Report → reproduce (I may ask for a full `wsl-env`) → fix → tests (the plugin ships with 591 host checks and 133 client checks) → release (npm and the market asset go out byte-identical in one run) → you confirm after upgrading → close.

package/index.js

@@ -10,7 +10,9 @@
 //
 // Each call runs in a fresh shell, so no state persists between calls. This
 // plugin publishes nothing and only consumes the host-plane `subprocess` and
-// `tools` registries, so it sits loose in an agent preset without a realm.
+// `tools` registries, so it needs no realm. Its own `cordis.patch.yml` inserts
+// the `tool-wsl` row process-wide, which is why the tools reach every agent
+// preset with no preset entry of its own (and why adding one there would fail).
 //
 // The implementation lives in `lib/`: `config` (defaults, environment overrides
 // and the plugin's own switches), `paths` (path translation and shell quoting),
@@ -33,6 +35,8 @@ import { readTerminalCwd, reviewTerminalWrite, writeTerminalCwd } from './lib/te
 import { createWslTool } from './lib/tools/wsl.js'
 import { createWslPathTool } from './lib/tools/wsl-path.js'
 import { createWslEnvTool } from './lib/tools/wsl-env.js'
+import { createWslDoctorTool } from './lib/tools/wsl-doctor.js'
+import { createWslBootstrapTool } from './lib/tools/wsl-bootstrap.js'
 
 export const name = 'tool-wsl'
 export const inject = ['tools', 'subprocess']
@@ -89,12 +93,15 @@ export const Config = Schema?.object({
     wsl: Schema.boolean().default(true).description('注册 `wsl` 工具：在 WSL 发行版中执行 Linux 命令。').volatile(),
     path: Schema.boolean().default(true).description('注册 `wsl-path` 工具：在 Windows 路径与 `/mnt/...` 之间互转。').volatile(),
     env: Schema.boolean().default(true).description('注册 `wsl-env` 工具：汇总发行版、内核、systemd、cgroup、GPU 直通、docker 与挂载盘。').volatile(),
-  }).description('要注册哪些工具；这三项在重启 DSH 后生效。'),
+    doctor: Schema.boolean().default(true).description('注册 `wsl-doctor` 工具：对照项目清单与发行版实际能力，指出缺什么，以及哪些命令其实是 Windows 的。').volatile(),
+    bootstrap: Schema.boolean().default(false).description('注册 `wsl-bootstrap` 工具：在发行版里补装缺失的工具链。默认关；打开后它以 root 执行固定配方，且调用方仍需显式 `dryRun: false`。').volatile(),
+  }).description('要注册哪些工具；这几项在重启 DSH 后生效。'),
   backgroundJobs: Schema.boolean().default(true).description('允许长任务以 `runInBackground` 后台执行，结果由内置 job 工具读取。').volatile(),
   translatePaths: Schema.boolean().default(true).description('命令中的 Windows 路径默认转为 `/mnt/...`。').volatile(),
   startInSessionWorkspace: Schema.boolean().default(true).description('未传 `workdir` 时从会话目录启动；默认开。关闭后使用下方固定目录，该目录留空时为家目录 `~`。').volatile(),
   workdir: Schema.string().default('').description('未传 `workdir` 时使用的固定 Linux 目录（如 `/mnt/d/project`），优先于「跟随会话工作区」；留空表示不指定。').volatile(),
   dangerGuard: Schema.boolean().default(true).description('危险命令（删除、分区、关机等）需显式 `allowDangerous` 才放行；关闭后模型可直接执行。').volatile(),
+  allowRoot: Schema.boolean().default(false).description('允许 `wsl` 以 root 执行（`asRoot: true`）。WSL 的 root 免密，所以这项开关就是授权本身；默认关。').volatile(),
   distro: Schema.string().default('').description('固定使用的发行版；留空表示使用系统默认（也可用 `DSH_WSL_DISTRO`）。').volatile(),
   timeoutMs: Schema.number().default(0).description('默认命令超时（毫秒）；0 表示使用内置默认（也可用 `DSH_WSL_TIMEOUT_MS`）。').volatile(),
 }).description('dsh-wsl 的功能开关与默认值。')
@@ -583,6 +590,7 @@ async function selfInfo(config, runner) {
       translatePaths: config.translatePaths,
       startInSessionWorkspace: config.startInSessionWorkspace,
       dangerGuard: config.dangerGuard,
+      allowRoot: config.allowRoot,
       distro: config.distro,
       commandTimeoutMs: config.commandTimeoutMs,
       maxOutputBytes: config.maxOutputBytes,
@@ -601,6 +609,11 @@ export function apply(ctx, settings = {}) {
   if (config.tools.wsl) ctx.tools.register(createWslTool({ ctx, config, runner }))
   if (config.tools.path) ctx.tools.register(createWslPathTool({ config, runner }))
   if (config.tools.env) ctx.tools.register(createWslEnvTool({ config, runner }))
+  if (config.tools.doctor) ctx.tools.register(createWslDoctorTool({ config, runner }))
+  // The installer is the one tool that is NOT registered by default: turning on
+  // its switch is the user's decision to let this plugin add software to their
+  // distribution.
+  if (config.tools.bootstrap) ctx.tools.register(createWslBootstrapTool({ config, runner }))
 
   // ---------------------------------------------------------------- self info
   //