dsh-wsl-tool 1.9.0 → 1.10.0

package/README.md

@@ -134,13 +134,48 @@ A background job is owned by the calling session (`owner: exec.agent.id`), which
 is what lets the model read it back with `job_output`/`job_kill` and what keeps
 other sessions out; an execution with no agent starts the job unowned.
 
-## A WSL terminal in the sidebar
+## The WSL panel (left sidebar)
 
-Installing this plugin also gives the desktop app's sidebar terminal a **WSL**
-shell. `cordis.patch.yml` overrides the composed `terminal-controller` row, whose
-configured shell is listed **first** and selected by default; the shells that row
-discovers (`powershell`, `cmd`, `bash`, …) stay selectable, so 新建终端 offers WSL
-next to them.
+The plugin ships a small client half: a **WSL** entry in the desktop app's left
+sidebar, whose panel carries one switch per feature, each with a one-line
+explanation.
+
+| Switch | What it controls |
+|---|---|
+| `wsl` 命令执行 | registers the `wsl` tool |
+| `wsl-path` 路径转换 | registers the `wsl-path` tool |
+| `wsl-env` 能力体检 | registers the `wsl-env` tool |
+| 后台任务 | whether `wsl` accepts `runInBackground` |
+| 自动转换路径 | the default for the per-call `translatePaths` |
+| 默认跟随会话工作区 | start in the session's directory instead of `~` when `workdir` is omitted |
+| 危险命令守卫 | whether a destructive command needs an explicit `allowDangerous` |
+
+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
+variables. `lib/config.js` owns the precedence — **plugin configuration, then the
+environment, then the built-in defaults** — and a switch left at its default lets
+the layer below decide, which is why `DSH_WSL_WORKDIR=session` keeps working for
+someone who never opened the panel.
+
+**A change takes effect at the next DSH start**: the host reads this configuration
+once per mount, and the panel says so. Distro and timeout are values rather than
+features — set them in the patch or with `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_MS`,
+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
+and only the panel is missing.
+
+## Optional: a WSL terminal in the sidebar
+
+The desktop app's sidebar terminal can open WSL instead of a Windows shell. It is
+**opt-in** — installing this plugin does not change which shell your terminals
+open — and the patch that enables it ships in the package as
+[`extras/terminal-wsl.patch.yml`](extras/terminal-wsl.patch.yml).
+
+To turn it on, copy that entry into your profile's own patch layer
+(`$DSH_HOME/profiles/<profile>/cordis.patch.yml`); a CLI launch can instead pass
+`--patch <path to the installed file>`. It applies at the next app start.
 
 ```yaml
 - id: terminal-controller
@@ -151,26 +186,19 @@ next to them.
       args: ['-e', 'bash', '-l']
 ```
 
+- The sidebar's 新建终端 list is built from the composed `terminal-controller`
+  row: it lists the configured `shell` first and keeps the shells it discovers
+  (`powershell`, `cmd`, `bash`, …) selectable. The picker is core UI, so overriding
+  that row is the supported way in — which is also why this cannot be a plain
+  plugin entry.
 - No distribution is pinned, so `wsl.exe` follows the system default — the same
-  rule the tools use when `DSH_WSL_DISTRO` is unset.
+  rule the tools use when `DSH_WSL_DISTRO` is unset. Add `-d <name>` to `args` to
+  pin one.
 - The session workspace is a Windows path that `wsl.exe` translates, so the
   terminal opens in `/mnt/<drive>/…` exactly like the Windows shells do; and it is
   a real PTY (`xterm-256color`), so full-screen programs work.
-- **Pinning a distribution, or choosing a different default, is a later patch
-  layer** — a profile's own `cordis.patch.yml` wins over this bundle:
-
-  ```yaml
-  - id: terminal-controller
-    config:
-      shell:
-        path: 'C:\Windows\System32\wsl.exe'
-        name: WSL
-        args: ['-d', 'Ubuntu-22.04', '-e', 'bash', '-l']
-  ```
-
-  An id-targeted patch replaces that row's whole config, so restate anything else
-  you had set on it.
-- Applies at the next app start.
+- An id-targeted patch replaces that row's whole config, so restate anything else
+  you had set on it (terminal limits, scrollback, a custom `shellCandidates` list).
 
 ## `wsl` parameters
 

package/README.zh-CN.md

@@ -116,11 +116,39 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 `job_output`/`job_kill` 读回它的依据，也是其他会话读不到它的围栏；exec 里没有 agent 时
 任务则是无主的。
 
-## 在侧边栏开一个 WSL 终端
+## 左侧栏的 WSL 面板
 
-装了这个插件，桌面版侧边栏终端就多出一个 **WSL** shell：插件的 `cordis.patch.yml` 覆盖组合里的
-`terminal-controller` 行，而该行配置的 shell 会排在**第一位**并成为默认；它由 `shellCandidates`
-发现的 `powershell`/`cmd`/`bash` 等仍然可选，所以「新建终端」里 WSL 与它们并列。
+插件带了一个小的客户端半：桌面版左侧栏里多一个 **WSL** 入口，面板里每个功能一个开关，每个开关
+配一行说明。
+
+| 开关 | 管什么 |
+|---|---|
+| `wsl` 命令执行 | 是否注册 `wsl` 工具 |
+| `wsl-path` 路径转换 | 是否注册 `wsl-path` 工具 |
+| `wsl-env` 能力体检 | 是否注册 `wsl-env` 工具 |
+| 后台任务 | `wsl` 是否接受 `runInBackground` |
+| 自动转换路径 | 每次调用的 `translatePaths` 默认值 |
+| 默认跟随会话工作区 | 未传 `workdir` 时从会话目录开始，而不是 `~` |
+| 危险命令守卫 | 危险命令是否必须显式 `allowDangerous` |
+
+面板改的是插件自己的配置，所以同样的值也可以手写进 profile patch（`- id: tool-wsl` 加 `config:`）
+或用环境变量设。优先级由 `lib/config.js` 定：**插件配置 > 环境变量 > 内置默认值**；开关停在默认值时
+下层说了算 —— 这正是"从没打开过面板的人，`DSH_WSL_WORKDIR=session` 依然生效"的原因。
+
+**改动在下次启动 DSH 后生效**：宿主每次挂载只读一次该配置，面板里也写着这句。发行版与超时属于"值"
+而不是"功能"：在 patch 里或用 `DSH_WSL_DISTRO` / `DSH_WSL_TIMEOUT_MS` 设置，面板只显示当前生效值。
+
+这个设置界面需要 `@deepseek-ai/schemastery`（插件把它声明为可选 peer 依赖）：没有它三个工具照常按
+默认值工作，只是没有面板。
+
+## 可选：在侧边栏开一个 WSL 终端
+
+桌面版侧边栏终端可以开 WSL 而不是 Windows shell。这是**可选**的 —— 装插件**不会**改你终端默认
+开什么 —— 启用用的 patch 随包提供：[`extras/terminal-wsl.patch.yml`](extras/terminal-wsl.patch.yml)。
+
+启用方式：把里面的条目复制进你自己 profile 的 patch 层
+（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）；命令行启动也可以改成
+`--patch <已安装文件路径>`。**下次启动应用时生效。**
 
 ```yaml
 - id: terminal-controller
@@ -131,23 +159,15 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
       args: ['-e', 'bash', '-l']
 ```
 
-- **不锁定发行版**：`wsl.exe` 跟随系统默认，与工具在未设 `DSH_WSL_DISTRO` 时的规则一致。
+- 「新建终端」的列表来自组合里的 `terminal-controller` 行：它把配置的 `shell` 排在最前，同时保留
+  它发现的 `powershell`/`cmd`/`bash` 等可选。那个选择列表属于核心 UI，所以**按 id 覆盖该行**是
+  受支持的入口 —— 这也是它没法做成普通插件条目的原因。
+- **不锁定发行版**：`wsl.exe` 跟随系统默认，与工具在未设 `DSH_WSL_DISTRO` 时的规则一致。要锁定就
+  在 `args` 里加 `-d <名字>`。
 - 会话工作区是 Windows 路径，`wsl.exe` 会自动翻译，因此终端像 Windows shell 一样落在
   `/mnt/<盘>/…`；而且是**真 PTY**（`xterm-256color`），全屏程序可用。
-- **要锁定发行版或换默认 shell**，在更靠后的 patch 层里重述该行即可 —— profile 自己的
-  `cordis.patch.yml` 优先于本组合包：
-
-  ```yaml
-  - id: terminal-controller
-    config:
-      shell:
-        path: 'C:\Windows\System32\wsl.exe'
-        name: WSL
-        args: ['-d', 'Ubuntu-22.04', '-e', 'bash', '-l']
-  ```
-
-  按 id 的 patch 会**整段替换**该行 config，其他设置要一并重述。
-- **下次启动应用时生效。**
+- 按 id 的 patch 会**整段替换**该行 config，你之前在该行上设过的东西（终端上限、scrollback、
+  自定义 `shellCandidates`）要一并重述。
 
 ## `wsl` 参数
 

package/cordis.patch.yml

@@ -6,6 +6,10 @@
 # `tool "wsl" is already registered in this scope`. To keep the tools out of a
 # composition, override this row by id in a later patch layer (`- id: tool-wsl`
 # with `disabled: true`) instead of duplicating it.
+#
+# This file deliberately changes nothing else: installing a tool plugin must not
+# reshape someone's session. Pointing the desktop app's sidebar terminal at WSL is
+# offered as an opt-in instead — see `extras/terminal-wsl.patch.yml`.
 
 # The entry name is PATH-RELATIVE on purpose. DSH anchors a relative `name:` to
 # the directory of the patch file that declared it (`anchorInsertedPluginNames`),
@@ -19,35 +23,3 @@
 - insert:
     - id: tool-wsl
       name: './index.js'
-
-# ── Sidebar terminal: a WSL shell, listed first and selected by default ────────
-#
-# The desktop app's 新建终端 list is built from the composed `terminal-controller`
-# row: it discovers shells from `shellCandidates` and puts the configured `shell`
-# first. Overriding that row here is what makes installing this plugin also give
-# you a Linux terminal in the sidebar. (A candidate entry cannot do it: a shell
-# discovered by name gets `-i` appended, and `wsl.exe -i` is a hard error.)
-#
-# The path is absolute because the configured shell must resolve, and a shell that
-# cannot resolve makes every new terminal fail rather than just this one: wsl.exe
-# ships with Windows at a fixed location, so this resolves even where no
-# distribution is installed yet.
-#
-# No distro is pinned, so `wsl.exe` follows the system default — the same rule the
-# tools use when DSH_WSL_DISTRO is unset. Add `-d <name>` to `args` to pin one.
-#
-# This changes the default terminal shell, which is deliberate for a WSL plugin
-# and reversible: a later patch layer wins, so restating the row in a profile's own
-# cordis.patch.yml overrides it (and a profile that sets its own `shell` there is
-# unaffected by this row).
-#
-# An id-targeted patch replaces the whole config, so anything the layer below set
-# on this row (limits, scrollback, a custom shellCandidates list) falls back to its
-# schema default. Only `shell` is set here on purpose. Never add `disabled:` here:
-# that would switch off the terminal feature for the user instead of just this row.
-- id: terminal-controller
-  config:
-    shell:
-      path: 'C:\Windows\System32\wsl.exe'
-      name: WSL
-      args: ['-e', 'bash', '-l']

package/extras/terminal-wsl.patch.yml

@@ -0,0 +1,34 @@
+# OPTIONAL — give the desktop app's sidebar terminal a WSL shell.
+#
+# This is deliberately NOT part of the bundle patch: installing a tool plugin must
+# not change which shell someone's terminals open by default. To opt in, copy the
+# entry below into the profile's own patch layer
+# (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`), or hand this file to a CLI
+# launch with `--patch <path to this file>`. It applies at the next app start.
+#
+# Why an id-targeted override: the sidebar's 新建终端 list is built from the
+# composed `terminal-controller` row, which discovers shells from
+# `shellCandidates` and lists the configured `shell` first. A candidate entry
+# cannot do it — a shell found by name gets `-i` appended, and `wsl.exe -i` is a
+# hard error. The picker itself is core UI, so a plugin cannot add an entry to it;
+# overriding the row is the supported way in.
+#
+# The path is absolute because a configured shell that fails to resolve makes every
+# new terminal fail, not just this one, and wsl.exe ships with Windows at a fixed
+# location whether or not a distribution is installed yet.
+#
+# No distribution is pinned, so `wsl.exe` follows the system default — the same
+# rule the tools use when `DSH_WSL_DISTRO` is unset. Add `-d <name>` to `args` to
+# pin one.
+#
+# An id-targeted patch replaces that row's whole config, so anything a layer below
+# set on it (terminal limits, scrollback, a custom `shellCandidates` list) falls
+# back to its schema default; only `shell` is set here on purpose. Never add
+# `disabled:` — that would switch the whole terminal feature off instead of
+# adjusting it.
+- id: terminal-controller
+  config:
+    shell:
+      path: 'C:\Windows\System32\wsl.exe'
+      name: WSL
+      args: ['-e', 'bash', '-l']

package/index.js

@@ -1,6 +1,7 @@
 // dsh-wsl: model-facing WSL tools for DeepSeek Harness (DSH).
 //
-// Registers three tools:
+// Registers up to three tools, each one switchable from the plugin's
+// left-sidebar panel:
 //   - `wsl`      : run a Linux command through wsl.exe, returning stdout/stderr
 //                  with exit-code / signal / timeout / truncation markers.
 //   - `wsl-path` : convert between Windows and WSL paths via `wslpath`.
@@ -11,10 +12,14 @@
 // plugin publishes nothing and only consumes the host-plane `subprocess` and
 // `tools` registries, so it sits loose in an agent preset without a realm.
 //
-// The implementation lives in `lib/`: `config` (defaults and environment
-// overrides), `paths` (path translation and shell quoting), `guard` (the
-// destructive-command rules), `result` (markers and truncation), `runner` (the
-// one spawn path) and `tools/` (the three tool definitions).
+// The implementation lives in `lib/`: `config` (defaults, environment overrides
+// and the plugin's own switches), `paths` (path translation and shell quoting),
+// `guard` (the destructive-command rules), `result` (markers and truncation),
+// `runner` (the one spawn path), `tools/` (the three tool definitions) and
+// `client.js` (the sidebar panel, a separate web-platform bundle).
+//
+// A configuration change is a mount, not something a running session re-reads:
+// every switch below is consulted once, in `apply`.
 
 import { resolveConfig } from './lib/config.js'
 import { createRunner } from './lib/runner.js'
@@ -25,15 +30,54 @@ import { createWslEnvTool } from './lib/tools/wsl-env.js'
 export const name = 'tool-wsl'
 export const inject = ['tools', 'subprocess']
 
-export function apply(ctx) {
-  // Read the environment once per mount: a configuration change is a mount
-  // (i.e. a DSH restart), not something a running session re-reads.
-  const config = resolveConfig()
+// The schema is what gives this plugin a settings surface at all: the platform
+// derives the namespace the sidebar panel writes to from the entry's id plus this
+// schema. It needs `@deepseek-ai/schemastery`, which a real DSH profile supplies
+// (the plugin declares it as an optional peer dependency) but which is absent when
+// this module is imported standalone, as `test/smoke.mjs` does. A soft import
+// keeps the tools runnable there: without a schema every switch keeps its default
+// and only the panel is missing.
+let Schema = null
+try {
+  ({ Schema } = await import('@deepseek-ai/schemastery'))
+} catch {
+  Schema = null
+}
+
+/**
+ * The plugin's own configuration.
+ *
+ * Every field is ALSO settable by hand in a profile patch
+ * (`- id: tool-wsl` / `config:`) and by the environment, and `lib/config.js`
+ * documents the precedence: this configuration wins, the environment is the
+ * deployment default, the built-in defaults are last.
+ *
+ * `distro` and `timeoutMs` are deliberately absent from the sidebar panel (they
+ * are values, not features) but stay here so a patch or a panel could grow a
+ * field for them without a schema change.
+ */
+export const Config = Schema?.object({
+  tools: Schema.object({
+    wsl: Schema.boolean().default(true).description('注册 `wsl` 工具：在 WSL 里执行 Linux 命令。'),
+    path: Schema.boolean().default(true).description('注册 `wsl-path` 工具：Windows 路径与 /mnt/... 互转。'),
+    env: Schema.boolean().default(true).description('注册 `wsl-env` 工具：汇总 WSL 环境能力。'),
+  }).description('要注册哪几个工具。'),
+  backgroundJobs: Schema.boolean().default(true).description('允许 `runInBackground`，由内置 job 工具读回结果。'),
+  translatePaths: Schema.boolean().default(true).description('默认把命令里的 Windows 路径转成 /mnt/...。'),
+  startInSessionWorkspace: Schema.boolean().default(false).description('未传 `workdir` 时从会话工作区开始，而不是 Linux 家目录。'),
+  dangerGuard: Schema.boolean().default(true).description('危险命令必须显式 `allowDangerous` 才放行。关掉后模型可直接删除/分区。'),
+  distro: Schema.string().default('').description('要固定使用的发行版；留空则用系统默认（也可用 DSH_WSL_DISTRO）。'),
+  timeoutMs: Schema.number().default(0).description('默认命令超时毫秒数；0 表示用内置默认（也可用 DSH_WSL_TIMEOUT_MS）。'),
+}).description('dsh-wsl 的功能开关与默认值。')
+
+export function apply(ctx, settings = {}) {
+  // Resolved once per mount: a settings change is a restart, not a live edit.
+  const config = resolveConfig(process.env, settings)
   const runner = createRunner(ctx, config)
-  // `ctx` is passed for the optional `jobs` service only (background commands);
-  // it is read with ctx.get at call time, never injected, so a preset without
-  // tool-jobs still mounts this plugin.
-  ctx.tools.register(createWslTool({ ctx, config, runner }))
-  ctx.tools.register(createWslPathTool({ config, runner }))
-  ctx.tools.register(createWslEnvTool({ config, runner }))
+  // `ctx` is passed to the `wsl` tool for the optional `jobs` service only
+  // (background commands); it is read with ctx.get at call time, never injected,
+  // so a preset without tool-jobs still mounts this plugin.
+  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 }))
 }

package/lib/client.js

@@ -0,0 +1,691 @@
+// dsh-wsl-tool, browser half.
+//
+// This file is a PLAIN hand-written bundle, exactly like the ones DSH ships: no
+// build step, no `import`/`export` keywords, no JSX, no TypeScript. The page
+// loads it as a script, the module loader below hands it a `require`, and the
+// only two modules it may ask for are React and the client UI primitives.
+//
+// What it contributes:
+//   - one rail entry in the left sidebar (`sidebar.panellist`, a list seat), and
+//   - the panel behind that entry (`main`, a keyed seat under the same id),
+//     whose switches edit this plugin's own Host configuration row.
+//
+// The Host half reads its settings ONCE per mount (see `lib/config.js`), so a
+// switch here changes the documented file/profile configuration; it does not
+// reconfigure a running session. The panel says so in one line instead of
+// pretending otherwise.
+//
+// Layout facts this file depends on (all verified against the shipped client):
+//   - `sidebar.panellist` entries carry `id`, `order` and `label`, and render
+//     their own icon (there is no icon field).
+//   - `main` is keyed by that same id, and its `inject` callback supplies extra
+//     props to the panel component.
+//   - `ctx.configForms.get(rowId)` returns a scope with
+//     `getSnapshot()` / `subscribe(listener)` / `mutate(ops, revision)`, where a
+//     snapshot is `{ status, value, base, user, writable, revision }` and one op
+//     is `{ op: 'set', path, value }` or `{ op: 'unset', path }`.
+
+window.__ModuleLoader__.load({
+  id: 'dsh-wsl-tool',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+    const primitives = require('@deepseek-ai/dsh-client-ui-primitives')
+
+    /**
+     * Panel identity. The layout pairs one `sidebar.panellist` entry with the
+     * `main` entry registered under the same key, so these two must agree; the
+     * rail entry's `label` is the visible text, the accessible name and the
+     * collapsed tooltip.
+     */
+    const PANEL_ID = 'dsh-wsl'
+
+    /**
+     * Loader row id of this bundle's Host half, read from our own
+     * `cordis.patch.yml`. `configForms.get` addresses a Host configuration entry
+     * by that row id — not by the package name, because one package may be
+     * composed as several rows under different ids.
+     */
+    const CONFIG_ROW_ID = 'tool-wsl'
+
+    // Theme tokens, read as CSS custom properties so the panel follows the
+    // active light/dark theme without importing any stylesheet. Each carries a
+    // neutral fallback: an unknown token must not make text invisible.
+    const LABEL_PRIMARY = 'var(--dsw-alias-label-primary, inherit)'
+    const LABEL_SECONDARY = 'var(--dsw-alias-label-secondary, inherit)'
+    const LABEL_TERTIARY = 'var(--dsw-alias-label-tertiary, inherit)'
+    const BORDER_SOFT = 'var(--dsw-alias-border-l2, rgba(127, 127, 127, 0.25))'
+    const BORDER_BADGE = 'var(--dsw-alias-border-l3, rgba(127, 127, 127, 0.35))'
+    const WARN_LABEL = 'var(--dsw-alias-state-warn-label, #b45309)'
+    const LINK_LABEL = 'var(--dsw-alias-link, inherit)'
+    const CODE_FILL = 'var(--dsw-alias-markdown-code-block, rgba(127, 127, 127, 0.12))'
+    const CODE_LABEL = 'var(--dsw-alias-markdown-inline-code, inherit)'
+    const RADIUS = 'var(--dsw-radius-xs, 4px)'
+
+    /**
+     * The switches, grouped into the two sections the panel renders.
+     *
+     * `path`   - path inside this plugin's configuration object (settings ops are
+     *            path-addressed, so a nested section is one array, not a string).
+     * `label`  - visible row text; also the switch's accessible name.
+     * `hint`   - the one-line explanation under the label.
+     * `when`   - the composed default for the row, used ONLY when the resolved
+     *            value does not carry the field at all (an older Host half, or a
+     *            field the Host schema does not declare). Reading a missing field
+     *            as `false` would silently mislabel a default-on feature.
+     * `danger` - marks a switch whose off state widens what the model may run.
+     */
+    const SECTIONS = [
+      {
+        id: 'tools',
+        title: '工具',
+        rows: [
+          {
+            path: ['tools', 'wsl'],
+            label: 'wsl 命令执行',
+            hint: '注册 `wsl` 工具：让模型在 WSL 发行版里执行 Linux 命令（一次一个全新 shell）',
+            when: true,
+          },
+          {
+            path: ['tools', 'path'],
+            label: 'wsl-path 路径转换',
+            hint: '注册 `wsl-path` 工具：在 Windows 路径与 `/mnt/...` 之间互转',
+            when: true,
+          },
+          {
+            path: ['tools', 'env'],
+            label: 'wsl-env 能力体检',
+            hint: '注册 `wsl-env` 工具：汇总发行版、内核、systemd、cgroup、GPU 直通、docker、挂载盘与两侧配置',
+            when: true,
+          },
+        ],
+      },
+      {
+        id: 'behavior',
+        title: '行为',
+        rows: [
+          {
+            path: ['backgroundJobs'],
+            label: '后台任务',
+            hint: '允许长任务用 `runInBackground` 后台执行，再由内置 job 工具读回结果',
+            when: true,
+          },
+          {
+            path: ['translatePaths'],
+            label: '自动转换路径',
+            hint: '命令里的 Windows 路径自动转成 `/mnt/...`（每次调用仍可用 `translatePaths` 覆盖）',
+            when: true,
+          },
+          {
+            path: ['startInSessionWorkspace'],
+            label: '默认跟随会话工作区',
+            hint: '未传 `workdir` 时从会话所在目录开始（关掉则从 Linux 家目录 `~` 开始）',
+            when: false,
+          },
+          {
+            path: ['dangerGuard'],
+            label: '危险命令守卫',
+            hint: '删除、分区、关机等命令必须显式 `allowDangerous` 才放行。关掉后模型可直接执行这类命令，请谨慎',
+            when: true,
+            danger: true,
+          },
+        ],
+      },
+    ]
+
+    /**
+     * The sidebar-terminal snippet, verbatim.
+     *
+     * It is a String.raw template AND its lines start at column 0 on purpose: it
+     * must come out byte-for-byte as the YAML a user pastes into a profile patch,
+     * backslashes in the Windows path included. Re-indenting it or writing it with
+     * ordinary escapes would quietly corrupt the path.
+     */
+    const TERMINAL_PATCH_YAML = String.raw`- id: terminal-controller
+  config:
+    shell:
+      path: 'C:\Windows\System32\wsl.exe'
+      name: WSL
+      args: ['-e', 'bash', '-l']`
+
+    /** A setting nobody can read yet; shaped like a scope snapshot so the panel
+     *  can treat it uniformly. `status: 'unavailable'` is the platform's own word
+     *  for "this Host does not serve that configuration entry". */
+    const UNAVAILABLE_SNAPSHOT = {
+      status: 'unavailable',
+      value: undefined,
+      base: undefined,
+      user: undefined,
+      writable: false,
+      revision: undefined,
+    }
+
+    // ---------------------------------------------------------------- helpers
+
+    /** Read one path out of a possibly absent object, never throwing. */
+    function readPath(target, path) {
+      let cursor = target
+      for (const step of path) {
+        if (cursor === null || typeof cursor !== 'object') return undefined
+        cursor = cursor[step]
+      }
+      return cursor
+    }
+
+    /**
+     * Whether the USER layer itself carries this path — i.e. whether the value is
+     * an override rather than inherited from the composition or the schema
+     * default. Presence is what marks an override, not a value comparison: an
+     * override that happens to equal the default is still an override.
+     */
+    function hasPath(target, path) {
+      let cursor = target
+      for (const step of path) {
+        if (cursor === null || typeof cursor !== 'object') return false
+        if (!Object.prototype.hasOwnProperty.call(cursor, step)) return false
+        cursor = cursor[step]
+      }
+      return true
+    }
+
+    /**
+     * Everything this panel knows about the Host configuration.
+     *
+     * Both the service and the row are optional, so every read is tolerant:
+     * a missing `configForms`, a row this Host does not serve, and a scope whose
+     * `getSnapshot` throws all end at `unavailable` instead of an exception in
+     * the middle of a render.
+     */
+    function createConfigModel() {
+      let served = false
+      let scope
+      let unsubscribe
+      const listeners = new Set()
+
+      const publish = () => {
+        // Copy first: a listener may unsubscribe itself while being notified.
+        for (const listener of Array.from(listeners)) {
+          try {
+            listener()
+          } catch (error) {
+            console.error('dsh-wsl-tool: a settings panel listener failed', error)
+          }
+        }
+      }
+
+      const read = () => {
+        if (scope === undefined || scope === null || typeof scope.getSnapshot !== 'function') {
+          return UNAVAILABLE_SNAPSHOT
+        }
+        try {
+          const snapshot = scope.getSnapshot()
+          return snapshot !== null && typeof snapshot === 'object' ? snapshot : UNAVAILABLE_SNAPSHOT
+        } catch (error) {
+          console.error('dsh-wsl-tool: reading the configuration scope failed', error)
+          return UNAVAILABLE_SNAPSHOT
+        }
+      }
+
+      return {
+        /** Whether the `configForms` service was there at all. A service this DSH
+         *  does not ship reads differently from a row it does not serve. */
+        hasService: () => served,
+        /** Bind the scope once the service appears. */
+        attach: (next) => {
+          if (next === undefined || next === null) return
+          served = true
+          scope = next
+          if (typeof scope.subscribe === 'function') {
+            try {
+              unsubscribe = scope.subscribe(publish)
+            } catch (error) {
+              console.error('dsh-wsl-tool: subscribing to the configuration scope failed', error)
+            }
+          }
+          publish()
+        },
+        /** Release the scope subscription; the caller's effect owns the call. */
+        detach: () => {
+          if (typeof unsubscribe === 'function') {
+            try {
+              unsubscribe()
+            } catch (error) {
+              console.error('dsh-wsl-tool: releasing the configuration scope failed', error)
+            }
+          }
+          unsubscribe = undefined
+        },
+        read,
+        subscribe: (listener) => {
+          listeners.add(listener)
+          return () => {
+            listeners.delete(listener)
+          }
+        },
+        /**
+         * Submit exactly one path-addressed write against the revision read just
+         * now, and answer whether the Host accepted it.
+         *
+         * The revision matters: the settings service refuses a write that was
+         * composed against a value somebody else has already replaced, rather than
+         * silently overwriting it. Its own settings form treats any falsy answer as
+         * a refusal, so this panel does the same — `false` means "not saved", and
+         * the panel words it instead of pretending the switch moved.
+         */
+        write: async (op) => {
+          const snapshot = read()
+          if (scope === undefined || typeof scope.mutate !== 'function') return false
+          if (snapshot.writable !== true) return false
+          try {
+            const landed = await scope.mutate([op], snapshot.revision)
+            return Boolean(landed)
+          } catch (error) {
+            console.error('dsh-wsl-tool: writing the configuration failed', error)
+            return false
+          }
+        },
+      }
+    }
+
+    /** Stand-in model for a seat that somehow renders without injected props, so
+     *  a missing prop shows the "not served" note instead of throwing. */
+    const DETACHED_MODEL = createConfigModel()
+
+    // ----------------------------------------------------------------- styles
+
+    const PANEL_STYLE = {
+      boxSizing: 'border-box',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '24px',
+      height: '100%',
+      maxWidth: '760px',
+      overflowY: 'auto',
+      padding: '24px',
+      color: LABEL_PRIMARY,
+      fontFamily: 'inherit',
+      fontSize: '13px',
+      lineHeight: '20px',
+    }
+    const HEADER_STYLE = { display: 'flex', flexDirection: 'column', gap: '4px' }
+    const TITLE_STYLE = { margin: 0, fontSize: '18px', fontWeight: 600, lineHeight: '26px' }
+    const DESCRIPTION_STYLE = { margin: 0, color: LABEL_SECONDARY }
+    const NOTE_STYLE = { margin: 0, color: LABEL_TERTIARY, fontSize: '12px', lineHeight: '18px' }
+    const STACK_STYLE = { display: 'flex', flexDirection: 'column', gap: '24px' }
+    const SECTION_STYLE = { display: 'flex', flexDirection: 'column', gap: '4px' }
+    const SECTION_TITLE_STYLE = { margin: 0, fontSize: '14px', fontWeight: 500, lineHeight: '20px' }
+    const ROWS_STYLE = { display: 'flex', flexDirection: 'column' }
+    const ROW_STYLE = {
+      display: 'flex',
+      alignItems: 'flex-start',
+      justifyContent: 'space-between',
+      gap: '16px',
+      padding: '14px 0',
+      borderBottom: '0.5px solid ' + BORDER_SOFT,
+    }
+    const ROW_COPY_STYLE = { display: 'flex', flexDirection: 'column', gap: '2px', minWidth: 0 }
+    const ROW_LABEL_STYLE = { display: 'flex', alignItems: 'center', gap: '6px', fontWeight: 500 }
+    const ROW_ACTIONS_STYLE = { display: 'flex', alignItems: 'center', gap: '8px', flexShrink: 0 }
+    const HINT_STYLE = { margin: 0, color: LABEL_TERTIARY, fontSize: '12px', lineHeight: '18px', maxWidth: '66ch' }
+    const BADGE_STYLE = {
+      border: '0.5px solid ' + BORDER_BADGE,
+      borderRadius: RADIUS,
+      color: LABEL_SECONDARY,
+      fontSize: '11px',
+      lineHeight: '16px',
+      padding: '1px 6px',
+      whiteSpace: 'nowrap',
+    }
+    const DANGER_STYLE = {
+      border: '0.5px solid currentColor',
+      borderRadius: RADIUS,
+      color: WARN_LABEL,
+      fontSize: '11px',
+      lineHeight: '16px',
+      padding: '0 4px',
+      whiteSpace: 'nowrap',
+    }
+    const RESET_STYLE = {
+      background: 'none',
+      border: 'none',
+      color: LINK_LABEL,
+      cursor: 'pointer',
+      fontFamily: 'inherit',
+      fontSize: '12px',
+      fontWeight: 'inherit',
+      padding: 0,
+      textDecoration: 'underline',
+    }
+    const DEFINITION_ROW_STYLE = { display: 'flex', alignItems: 'baseline', gap: '12px' }
+    const DEFINITION_LABEL_STYLE = { color: LABEL_SECONDARY, minWidth: '13em' }
+    const DEFINITION_VALUE_STYLE = { color: LABEL_PRIMARY }
+    const PRE_STYLE = {
+      margin: 0,
+      padding: '12px',
+      background: CODE_FILL,
+      borderRadius: RADIUS,
+      color: CODE_LABEL,
+      fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+      fontSize: '12px',
+      lineHeight: '18px',
+      overflowX: 'auto',
+      whiteSpace: 'pre',
+    }
+
+    // ------------------------------------------------------------ components
+
+    /**
+     * The rail icon. A `sidebar.panellist` entry draws its own glyph: an 18×18
+     * terminal prompt in `currentColor`, so the layout's selected/hover colours
+     * come through untouched.
+     */
+    function WslIcon() {
+      return React.createElement(
+        'svg',
+        {
+          width: 18,
+          height: 18,
+          viewBox: '0 0 20 20',
+          fill: 'none',
+          stroke: 'currentColor',
+          strokeWidth: 1.5,
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+          'aria-hidden': 'true',
+          focusable: 'false',
+        },
+        // The terminal frame, the prompt chevron, and the command line.
+        React.createElement('path', {
+          d: 'M3.5 4.5h13a1 1 0 0 1 1 1v9a1 1 0 0 1-1 1h-13a1 1 0 0 1-1-1v-9a1 1 0 0 1 1-1Z',
+        }),
+        React.createElement('path', { d: 'M6.5 8.5 8.5 10.5 6.5 12.5' }),
+        React.createElement('path', { d: 'M10.5 13h3' }),
+      )
+    }
+
+    /** One read-only label/value line, used by the effective-defaults section. */
+    function definitionRow(label, value) {
+      return React.createElement(
+        'div',
+        { style: DEFINITION_ROW_STYLE },
+        React.createElement('span', { style: DEFINITION_LABEL_STYLE }, label),
+        React.createElement('span', { style: DEFINITION_VALUE_STYLE }, value),
+      )
+    }
+
+    /** A section frame: a heading plus its body, which may be several nodes. */
+    function section(key, title, ...children) {
+      return React.createElement(
+        'section',
+        { key, style: SECTION_STYLE },
+        React.createElement('h3', { style: SECTION_TITLE_STYLE }, title),
+        ...children,
+      )
+    }
+
+    /**
+     * The panel behind the rail entry.
+     *
+     * It renders whatever the scope currently says — `ready`, still `loading`, or
+     * `unavailable` — because a settings panel that throws or renders nothing on a
+     * stripped composition is worse than one that explains itself. Reading goes
+     * through the injected model so a service that appears later needs no remount.
+     */
+    function WslPanel(props) {
+      const model = props !== null && props !== undefined && props.model !== undefined ? props.model : DETACHED_MODEL
+      const [snapshot, setSnapshot] = React.useState(model.read())
+      // `busy` is the path key of the write in flight; `refused` remembers that the
+      // Host did not accept the last one, so the panel can say so.
+      const [busy, setBusy] = React.useState(undefined)
+      const [refused, setRefused] = React.useState(false)
+
+      React.useEffect(
+        () =>
+          model.subscribe(() => {
+            setSnapshot(model.read())
+          }),
+        [model],
+      )
+
+      /**
+       * Send one write and reflect its outcome. The promise is returned so a
+       * caller (or a test) can await the settled state; React ignores the return
+       * value of an event handler, and `model.write` never rejects.
+       */
+      const submit = (op, key) => {
+        setBusy(key)
+        setRefused(false)
+        return model.write(op).then((landed) => {
+          setBusy(undefined)
+          setRefused(!landed)
+          setSnapshot(model.read())
+          return landed
+        })
+      }
+
+      /** One switch row: switch, label and hint on the left, override controls and
+       *  the switch itself on the right. */
+      const rowElement = (row) => {
+        const key = row.path.join('.')
+        const overridden = hasPath(snapshot.user, row.path)
+        const disabled = snapshot.writable !== true || busy !== undefined
+        const effective = readPath(snapshot.value, row.path)
+        const checked = effective === undefined ? row.when : effective === true
+        return React.createElement(
+          'div',
+          { key, style: ROW_STYLE },
+          React.createElement(
+            'div',
+            { style: ROW_COPY_STYLE },
+            React.createElement(
+              'div',
+              { style: ROW_LABEL_STYLE },
+              row.label,
+              row.danger === true ? React.createElement('span', { style: DANGER_STYLE }, '有风险') : null,
+            ),
+            React.createElement('p', { style: HINT_STYLE }, row.hint),
+          ),
+          React.createElement(
+            'div',
+            { style: ROW_ACTIONS_STYLE },
+            overridden ? React.createElement('span', { style: BADGE_STYLE }, '已覆盖') : null,
+            overridden
+              ? React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    style: RESET_STYLE,
+                    disabled,
+                    // Returned as well as performed: React ignores a handler's
+                    // return value, but awaiting it is how a test sees the write
+                    // settle.
+                    onClick: () => submit({ op: 'unset', path: row.path }, key),
+                  },
+                  '恢复默认',
+                )
+              : null,
+            React.createElement(primitives.Switch, {
+              checked,
+              label: row.label,
+              disabled,
+              ...(row.danger === true
+                ? { title: '有风险：关掉后模型可以直接执行删除、分区、关机等命令' }
+                : {}),
+              onChange: (next) => submit({ op: 'set', path: row.path, value: next === true }, key),
+            }),
+          ),
+        )
+      }
+
+      const children = []
+
+      children.push(
+        React.createElement(
+          'header',
+          { key: 'header', style: HEADER_STYLE },
+          React.createElement('h2', { style: TITLE_STYLE }, 'WSL'),
+          React.createElement('p', { style: DESCRIPTION_STYLE }, '通过 WSL 在 Windows 上执行 Linux 命令的开关与说明'),
+          React.createElement('p', { style: NOTE_STYLE }, '改动会在下次启动 DSH 后生效'),
+        ),
+      )
+
+      // The switches — or the one reason they cannot be shown right now.
+      if (model.hasService() !== true) {
+        children.push(
+          React.createElement(
+            'p',
+            { key: 'note-service', style: NOTE_STYLE },
+            '此 DSH 未提供配置表单服务（configForms），无法在这里调整设置。',
+          ),
+        )
+      } else if (snapshot.status === 'loading') {
+        children.push(React.createElement('p', { key: 'note-loading', style: NOTE_STYLE }, '正在读取配置…'))
+      } else if (snapshot.status !== 'ready') {
+        children.push(
+          React.createElement('p', { key: 'note-unavailable', style: NOTE_STYLE }, '此 DSH 未提供该插件的配置作用域'),
+        )
+      } else {
+        const blocks = SECTIONS.map((group) =>
+          section(group.id, group.title, React.createElement('div', { style: ROWS_STYLE }, group.rows.map(rowElement))),
+        )
+        if (refused) {
+          blocks.unshift(
+            React.createElement('p', { key: 'note-refused', style: NOTE_STYLE }, '保存被拒绝：配置没有被写入，请重试'),
+          )
+        }
+        children.push(React.createElement('div', { key: 'switches', style: STACK_STYLE }, blocks))
+      }
+
+      // The effective values of the two knobs that have no switch, because they
+      // are a distro name and a duration rather than a boolean.
+      if (snapshot.status === 'ready') {
+        const distro = readPath(snapshot.value, ['distro'])
+        const timeoutMs = readPath(snapshot.value, ['timeoutMs'])
+        children.push(
+          section(
+            'defaults',
+            '当前默认值',
+            React.createElement(
+              'div',
+              null,
+              definitionRow(
+                '发行版 distro',
+                typeof distro === 'string' && distro.trim() !== '' ? distro : '系统默认发行版',
+              ),
+              definitionRow(
+                '命令超时 timeoutMs',
+                typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) ? timeoutMs + ' 毫秒' : '—',
+              ),
+            ),
+            React.createElement(
+              'p',
+              { style: HINT_STYLE },
+              '这两个值来自插件配置，可以在 profile 的 cordis.patch.yml 里写，也可以用环境变量 DSH_WSL_DISTRO / DSH_WSL_TIMEOUT_MS 覆盖。',
+            ),
+          ),
+        )
+      }
+
+      // Opt-in, read-only: the snippet goes ABOVE its explanation, which refers to
+      // it as 「上面这段」.
+      children.push(
+        section(
+          'terminal',
+          '侧边栏 WSL 终端（可选）',
+          React.createElement(
+            'p',
+            { style: HINT_STYLE },
+            '插件还可以把桌面端的侧边栏终端指向 WSL；这是可选项，默认不开。',
+          ),
+          React.createElement('pre', { style: PRE_STYLE }, TERMINAL_PATCH_YAML),
+          React.createElement(
+            'p',
+            { style: HINT_STYLE },
+            '把上面这段加进 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 后重启 DSH，新建终端里就会出现 WSL（详见插件 README）',
+          ),
+        ),
+      )
+
+      return React.createElement('div', { style: PANEL_STYLE }, children)
+    }
+
+    // ------------------------------------------------------------------ apply
+
+    /**
+     * Mount the rail entry and the panel.
+     *
+     * This function must never throw: a client half that fails to apply takes its
+     * whole bundle's surface down with it, and the WSL tools work fine without any
+     * of this. So a missing `slots` service, a missing `configForms`, an unserved
+     * configuration row and a scope that refuses to be read all degrade into a note
+     * in the panel instead of an exception.
+     */
+    function apply(ctx) {
+      const model = createConfigModel()
+
+      // `configForms` is reached through `ctx.inject`, never through this module's
+      // own `inject` array: the panel is a convenience, not a reason to refuse to
+      // mount on a composition that does not ship the settings service.
+      try {
+        if (typeof ctx.inject === 'function') {
+          ctx.inject(['configForms'], (inner) => {
+            let scope
+            try {
+              scope = inner.configForms.get(CONFIG_ROW_ID)
+            } catch (error) {
+              console.error('dsh-wsl-tool: this DSH serves no "' + CONFIG_ROW_ID + '" configuration row', error)
+              return
+            }
+            model.attach(scope)
+            // The subscription lives exactly as long as this fiber: `effect` runs
+            // the returned disposer on unload or recomposition.
+            if (typeof inner.effect === 'function') {
+              inner.effect(() => () => model.detach(), 'dsh-wsl-tool: configuration scope')
+            }
+          })
+        }
+      } catch (error) {
+        console.error('dsh-wsl-tool: asking for the configuration service failed', error)
+      }
+
+      try {
+        if (ctx.slots === undefined || ctx.slots === null) {
+          console.error('dsh-wsl-tool: this DSH has no slots service; the WSL panel stays unmounted')
+          return
+        }
+        // Both seats are registered from the innermost callback, exactly as the
+        // shipped panels do: the rail entry and the panel it opens appear together
+        // or not at all. The callback's return value is the disposer chain.
+        ctx.slots.inject('main', () =>
+          ctx.slots.inject('sidebar.panellist', () => {
+            const stopMain = ctx.slots.register(
+              { name: 'main', key: PANEL_ID, inject: () => ({ model }) },
+              WslPanel,
+            )
+            const stopIcon = ctx.slots.register(
+              { name: 'sidebar.panellist', id: PANEL_ID, order: 50, label: () => 'WSL' },
+              WslIcon,
+            )
+            return () => {
+              if (typeof stopIcon === 'function') stopIcon()
+              if (typeof stopMain === 'function') stopMain()
+            }
+          }),
+        )
+      } catch (error) {
+        console.error('dsh-wsl-tool: registering the WSL panel failed', error)
+      }
+    }
+
+    // `slots` is the one service this module needs before it can do anything.
+    // `configForms` is optional and is asked for above, at runtime.
+    const inject = ['slots']
+
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/lib/config.js

@@ -1,9 +1,20 @@
 // Resolved settings for one mounted plugin instance.
 //
-// Everything tunable lives here. The numeric knobs are environment-overridable
-// so a deployment can tune them without editing this package; an unparsable or
-// out-of-range value falls back to the default instead of failing the mount,
-// because one bad environment variable must not take all three tools down.
+// Everything tunable lives here, and it is resolved from three layers, most
+// specific first:
+//
+//   1. the plugin's own configuration — the switches in the left-sidebar panel
+//      (a host `Config` schema; see index.js), stored in the profile patch;
+//   2. the environment, for a deployment that tunes a headless install with no
+//      UI at all;
+//   3. the built-in defaults below.
+//
+// A layer only speaks when it actually says something: an unset switch, an empty
+// distro or a zero timeout falls THROUGH to the layer beneath instead of pinning
+// the default over it. That is what keeps `DSH_WSL_WORKDIR=session` working for a
+// user who never opened the panel. An unparsable or out-of-range value falls back
+// rather than failing the mount, because one bad environment variable must not
+// take all three tools down.
 
 import { windowsPathToWsl } from './paths.js'
 
@@ -28,6 +39,16 @@ export const DEFAULTS = {
   maxCommandChars: 30_000,
   /** `setTimeout` stores its delay in a signed 32-bit int; larger fires at once. */
   maxTimerDelayMs: 2 ** 31 - 1,
+  /** Which tools this plugin registers at all. */
+  tools: { wsl: true, path: true, env: true },
+  /** Whether `wsl` accepts `runInBackground` (the built-in job tools read it back). */
+  backgroundJobs: true,
+  /** Whether a Windows path in `command` is rewritten to /mnt/... by default. */
+  translatePaths: true,
+  /** Whether the destructive-command guard may be bypassed only by the caller's
+   *  explicit `allowDangerous`. Never set this from the environment: it is the
+   *  one switch whose off position is a footgun, and the panel marks it as such. */
+  dangerGuard: true,
 }
 
 /**
@@ -69,8 +90,18 @@ function envInt(env, name, fallback, min, max) {
   return value >= min && value <= max ? value : fallback
 }
 
-/** @returns a distribution name to pin, or null to use the system default. */
-function envDistro(env) {
+/** A configured boolean, or the fallback when the layer did not set one. */
+function setting(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/**
+ * @param env - the environment layer.
+ * @param configured - the plugin's own configuration layer (may be undefined).
+ * @returns a distribution name to pin, or null to use the system default.
+ */
+function resolveDistro(env, configured) {
+  if (typeof configured === 'string' && configured.trim() !== '') return configured.trim()
   const raw = env.DSH_WSL_DISTRO
   return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : null
 }
@@ -78,15 +109,19 @@ function envDistro(env) {
 /**
  * Where a call starts when the caller passes no `workdir`.
  *
- * `home` (the default) keeps the documented `~`. `session` starts in the
- * session's working directory — the plugin's own process cwd, the same source
- * `dsh-pwsh-local` uses by default — which is what an agent working on a
- * Windows checkout usually wants, since its files live at `/mnt/<drive>/...`
- * rather than in the Linux home. Anything else is an explicit default path.
+ * `home` keeps the documented `~`. `session` starts in the session's working
+ * directory — the plugin's own process cwd, the same source `dsh-pwsh-local` uses
+ * by default — which is what an agent working on a Windows checkout usually
+ * wants, since its files live at `/mnt/<drive>/...` rather than in the Linux home.
+ * Anything else is an explicit default path.
  *
  * @returns a path, or null meaning "the process working directory".
  */
-function envWorkdir(env) {
+function resolveWorkdir(env, settings) {
+  // Only the ON position is authoritative: off means "whatever the layers below
+  // say", so `DSH_WSL_WORKDIR=session` keeps working for a user who never opened
+  // the panel, and a fresh install still starts in `~`.
+  if (settings.startInSessionWorkspace === true) return null
   const raw = env.DSH_WSL_WORKDIR
   if (typeof raw !== 'string' || raw.trim() === '') return DEFAULTS.workdir
   const value = raw.trim()
@@ -103,27 +138,45 @@ function envWorkdir(env) {
  * stream and would be discarded exactly when it is most useful.
  *
  * @param env - environment to read (injectable for tests).
+ * @param settings - the plugin's own configuration, as the composition resolved
+ *   it against the Config schema (injectable for tests; may be undefined).
  */
-export function resolveConfig(env = process.env) {
+export function resolveConfig(env = process.env, settings = {}) {
   const maxOutputBytes = envInt(
     env, 'DSH_WSL_MAX_OUTPUT_BYTES', DEFAULTS.maxOutputBytes, OUTPUT_BYTES_MIN, OUTPUT_BYTES_MAX,
   )
   const maxCommandTimeoutMs = envInt(
     env, 'DSH_WSL_MAX_TIMEOUT_MS', DEFAULTS.maxCommandTimeoutMs, TIMEOUT_MS_MIN, DEFAULTS.maxTimerDelayMs,
   )
+  const tools = settings.tools ?? {}
+  // 0 means "not configured", so the environment and the built-in default still
+  // decide; a positive value is the user's own deadline.
+  const configuredTimeoutMs = Number.isInteger(settings.timeoutMs) && settings.timeoutMs > 0
+    ? settings.timeoutMs
+    : undefined
   return {
     ...DEFAULTS,
+    tools: {
+      wsl: setting(tools.wsl, DEFAULTS.tools.wsl),
+      path: setting(tools.path, DEFAULTS.tools.path),
+      env: setting(tools.env, DEFAULTS.tools.env),
+    },
+    backgroundJobs: setting(settings.backgroundJobs, DEFAULTS.backgroundJobs),
+    translatePaths: setting(settings.translatePaths, DEFAULTS.translatePaths),
+    dangerGuard: setting(settings.dangerGuard, DEFAULTS.dangerGuard),
+    startInSessionWorkspace: settings.startInSessionWorkspace === true,
     // null means "whatever wsl.exe uses by default", which is what makes the
     // package portable: `Ubuntu-22.04` exists on the author's machine, not
     // necessarily on a storefront user's.
-    distro: envDistro(env),
-    defaultWorkdir: envWorkdir(env),
+    distro: resolveDistro(env, settings.distro),
+    defaultWorkdir: resolveWorkdir(env, settings),
     maxOutputBytes,
     maxSpillBytes: Math.max(DEFAULTS.maxSpillBytes, maxOutputBytes),
     maxCommandTimeoutMs,
     // The default deadline obeys the cap too, so the two knobs cannot disagree.
     commandTimeoutMs: Math.min(
-      envInt(env, 'DSH_WSL_TIMEOUT_MS', DEFAULTS.commandTimeoutMs, TIMEOUT_MS_MIN, DEFAULTS.maxTimerDelayMs),
+      configuredTimeoutMs
+      ?? envInt(env, 'DSH_WSL_TIMEOUT_MS', DEFAULTS.commandTimeoutMs, TIMEOUT_MS_MIN, DEFAULTS.maxTimerDelayMs),
       maxCommandTimeoutMs,
     ),
   }

package/lib/tools/wsl.js

@@ -195,7 +195,7 @@ export function createWslTool({ ctx, config, runner }) {
         },
         translatePaths: {
           type: 'boolean',
-          description: 'Default true: rewrite Windows paths in `command` to /mnt/... . Set false to pass `command` verbatim, e.g. a native path for a Windows program launched through interop. `workdir` is always translated.',
+          description: `Default ${config.translatePaths}: rewrite Windows paths in \`command\` to /mnt/... . Set false to pass \`command\` verbatim, e.g. a native path for a Windows program launched through interop. \`workdir\` is always translated.`,
         },
       },
       required: ['command', 'description'],
@@ -263,9 +263,11 @@ export function createWslTool({ ctx, config, runner }) {
         }
       }
 
-      const command = args.translatePaths === false ? args.command : windowsPathToWsl(args.command)
+      // The switch is the default, the parameter is the per-call override.
+      const translatePaths = args.translatePaths ?? config.translatePaths
+      const command = translatePaths === false ? args.command : windowsPathToWsl(args.command)
       const reason = destructiveReason(command)
-      if (reason !== null && args.allowDangerous !== true) {
+      if (reason !== null && args.allowDangerous !== true && config.dangerGuard) {
         throw new Error(
           `wsl: refused a destructive command (${reason}). ` +
           'If this is intended, re-issue it with `allowDangerous: true`.',
@@ -283,6 +285,16 @@ export function createWslTool({ ctx, config, runner }) {
       }
 
       if (args.runInBackground === true) {
+        // The switch is checked here rather than hidden from the schema: a model
+        // that was told about `runInBackground` (by a cached prompt, or a
+        // transcript resumed from before the switch moved) must be told why it is
+        // refused instead of silently running in the foreground.
+        if (!config.backgroundJobs) {
+          throw new Error(
+            'wsl: background jobs are switched off in this plugin\'s settings ' +
+            '(left sidebar, WSL panel -> 后台任务). Run it in the foreground, or turn the switch back on.',
+          )
+        }
         // A background job is meant to outlive the foreground deadline, so the
         // configured default does NOT apply; an explicit timeoutMs still does.
         return startInBackground(command, { ...opts, timeoutMs: args.timeoutMs }, exec)

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "dsh-wsl-tool",
-  "version": "1.9.0",
-  "description": "Run Linux commands from Windows through WSL, essentially matching a native Linux DSH for command execution: background jobs, stdin, path translation, a destructive-command guard and a WSL capability report. WSL calls run below the DSH sandbox, and a project on a Windows drive keeps Windows filesystem semantics.",
+  "version": "1.10.0",
+  "description": "Run Linux commands from Windows through WSL, essentially matching a native Linux DSH for command execution: background jobs, stdin, path translation, a destructive-command guard and a WSL capability report. A left-sidebar panel switches each capability on or off, each with a one-line explanation, and an opt-in patch gives the desktop app's sidebar terminal a WSL shell. WSL calls run below the DSH sandbox, and a project on a Windows drive keeps Windows filesystem semantics.",
   "type": "module",
   "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,12 +44,13 @@
     "README.md",
     "README.zh-CN.md",
     "PUBLISHING.md",
+    "extras",
     "screenshots.json",
     "assets",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node test/smoke.mjs",
+    "test": "node test/smoke.mjs && node test/client.mjs",
     "test:real": "node test/smoke.mjs --real && node test/real-seam.mjs",
     "sync": "node scripts/sync-profile.mjs"
   },
@@ -46,6 +61,13 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
     }
   }
 }