dsh-wsl-tool 1.8.1 → 1.9.0

package/PUBLISHING.md

@@ -61,10 +61,11 @@ both that the entry stays relative and that it resolves.
    ```
 
    `npm run sync` defaults to
-   `%USERPROFILE%/.dsh/profiles/web/node_modules/dsh-wsl` — the folder the
+   `%USERPROFILE%/.dsh/profiles/desktop/node_modules/dsh-wsl` — the folder the
    profile's dependency key created, which need not match the npm name. Pass a
    path to target another profile. Restart DSH afterwards: the plugin is imported
-   once at load.
+   once at load. A patch change (the tool row, or the sidebar terminal override)
+   is read at composition time, so it needs that restart too.
 
 3. The tag runs the pipeline. The order is deliberate — the release asset goes
    **first** because it is the market's critical path, then npm, so a failing npm
@@ -100,6 +101,14 @@ 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.
 
+   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
+   endpoint can already report the new version while `npm install` still answers
+   `404` for its tarball. Re-query instead of concluding the publish failed, and
+   cache-bust the tarball URL (`?cb=<random>`) to tell a stale negative entry apart
+   from an artifact that is genuinely missing.
+
    **Market asset** (this is what users install, and it is independent of npm):
 
    ```sh

package/README.md

@@ -2,7 +2,18 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-A model-facing **WSL** tool plugin for DeepSeek Harness (DSH). It lets an agent run Linux commands through `wsl.exe` directly — no hand-written `.sh` scripts or `pwsh` wrappers.
+A model-facing **WSL** tool plugin for DeepSeek Harness (DSH). It lets an agent run
+Linux commands through `wsl.exe` directly — no hand-written `.sh` scripts or `pwsh`
+wrappers — and for command execution it essentially matches a native Linux DSH: a
+real Linux kernel and bash, exit codes and signals, timeouts, truncation with spill
+files, background jobs the built-in job tools read back, stdin, and automatic
+Windows/WSL path translation.
+
+Two limits are worth knowing before you rely on it. A `wsl` call runs below DSH's
+sandbox, so a file policy does not confine it (see [Sandboxing](#sandboxing)); and a
+project kept on a Windows drive keeps **Windows** filesystem semantics — no POSIX
+permissions, case-insensitive names, no file-change notifications — at a fraction
+of the speed (see [Notes](#notes)).
 
 ## Tools
 
@@ -123,6 +134,44 @@ 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
+
+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.
+
+```yaml
+- id: terminal-controller
+  config:
+    shell:
+      path: 'C:\Windows\System32\wsl.exe'
+      name: WSL
+      args: ['-e', 'bash', '-l']
+```
+
+- No distribution is pinned, so `wsl.exe` follows the system default — the same
+  rule the tools use when `DSH_WSL_DISTRO` is unset.
+- 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.
+
 ## `wsl` parameters
 
 | Param | Required | Type | Notes |
@@ -184,7 +233,21 @@ takes effect on restart.
   workspace: /mnt/d/DSHworkarea (Windows drive mount /mnt/d — builds, installs and git are much slower here; prefer a path under /home when it matters)
   ```
 
-  It is worth believing. Measured on the author's machine: a 128 MB sequential write ran at ~2.1 GB/s on ext4 against ~247 MB/s on `/mnt/d`, and creating 400 small files took under 10 ms against 0.72 s.
+  It is worth believing. Measured on the author's machine: a 128 MB sequential write
+  ran at ~2.1 GB/s on ext4 against ~247 MB/s on `/mnt/d`, and creating 400 small
+  files took under 10 ms against 0.72 s (a later re-run: 884 vs 116 MB/s, and 13 ms
+  against 745 ms — the ratios hold at roughly 8× and 50×).
+
+  It is not only slower. `/mnt/<drive>` is a 9p (drvfs) mount, so it keeps **Windows**
+  filesystem semantics: `chmod`/`chown` do not stick (a `chmod 600` reads back as
+  `777`), names are case-insensitive (so a case-sensitive import only fails on Linux
+  CI), symlinks and the executable bit are synthetic, and **inotify does not work at
+  all** — a watcher inside the distro receives no events for writes from either side
+  (measured with an inotify probe on `/mnt/d`: zero events for a Windows-side write
+  and for a Linux-side write, while the same probe on ext4 reported create, modify
+  and close-write). Dev servers, `--watch` modes and file-watching tests are
+  therefore blind on a Windows drive. Keep a project under `/home` when it matters:
+  it recovers real semantics, real watch events, and the speed above.
 - Destructive commands are refused unless the call passes `allowDangerous: true`:
   - **any recursive delete** — `rm -r`, `rm -rf`, `rm -r -f`, `rm -R --force`, `rm --recursive` — because with stdin on `/dev/null` nothing prompts, so `rm -r tree` deletes silently. Each `rm` invocation is judged on its own command segment, so `rm a -f; rm b -r` cannot combine into a pass;
   - `dd` onto a block device, `mkfs`, partitioning/wiping tools (`fdisk`, `parted`, `wipefs`, `mkswap`, …), power control (`shutdown`, `reboot`, `systemctl reboot`, …), redirection onto a block device, and fork bombs;
@@ -317,7 +380,7 @@ A `file:` dependency is a **copy**, so editing this checkout does not change wha
 DSH loads. After any change:
 
 ```sh
-npm run sync                  # copies into ~/.dsh/profiles/web/node_modules/dsh-wsl
+npm run sync                  # copies into ~/.dsh/profiles/desktop/node_modules/dsh-wsl
 npm run sync -- /path/to/profiles/<profile>/node_modules/<your-key>
 ```
 

package/README.zh-CN.md

@@ -2,7 +2,14 @@
 
 [English](README.md) | 简体中文
 
-面向模型（model-facing）的 **WSL** 工具插件，用于 DeepSeek Harness（DSH）。它让智能体直接通过 `wsl.exe` 执行 Linux 命令——无需手写 `.sh` 脚本或 `pwsh` 包装。
+面向模型（model-facing）的 **WSL** 工具插件，用于 DeepSeek Harness（DSH）。它让智能体直接通过
+`wsl.exe` 执行 Linux 命令——无需手写 `.sh` 脚本或 `pwsh` 包装——并且在**命令执行**这一层基本对齐
+Linux 原生 DSH：真实的 Linux 内核与 bash、退出码与信号、超时、截断与落盘、可用内置 job 工具读回的
+后台作业、stdin，以及 Windows/WSL 路径自动转换。
+
+有两点限制值得在依赖它之前知道：`wsl` 调用位于 DSH 沙箱层之下，文件策略约束不到它
+（见[沙箱边界](#沙箱边界)）；项目放在 Windows 盘上时仍是 **Windows** 的文件系统语义——没有 POSIX
+权限位、文件名大小写不敏感、收不到文件变更通知——速度也低一个数量级（见[注意事项](#注意事项)）。
 
 ## 工具
 
@@ -109,6 +116,39 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 `job_output`/`job_kill` 读回它的依据，也是其他会话读不到它的围栏；exec 里没有 agent 时
 任务则是无主的。
 
+## 在侧边栏开一个 WSL 终端
+
+装了这个插件，桌面版侧边栏终端就多出一个 **WSL** shell：插件的 `cordis.patch.yml` 覆盖组合里的
+`terminal-controller` 行，而该行配置的 shell 会排在**第一位**并成为默认；它由 `shellCandidates`
+发现的 `powershell`/`cmd`/`bash` 等仍然可选，所以「新建终端」里 WSL 与它们并列。
+
+```yaml
+- id: terminal-controller
+  config:
+    shell:
+      path: 'C:\Windows\System32\wsl.exe'
+      name: WSL
+      args: ['-e', 'bash', '-l']
+```
+
+- **不锁定发行版**：`wsl.exe` 跟随系统默认，与工具在未设 `DSH_WSL_DISTRO` 时的规则一致。
+- 会话工作区是 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，其他设置要一并重述。
+- **下次启动应用时生效。**
+
 ## `wsl` 参数
 
 | 参数 | 必填 | 类型 | 说明 |
@@ -186,8 +226,17 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
   workspace: /mnt/d/DSHworkarea (Windows drive mount /mnt/d — builds, installs and git are much slower here; prefer a path under /home when it matters)
   ```
 
-  这个提示值得当真。作者机器实测：128 MB 顺序写在 ext4 上约 **2.1 GB/s**，在 `/mnt/d` 上约 **247 MB/s**；
-  创建 400 个小文件 ext4 **不到 10 ms**，`/mnt/d` 要 **0.72 s**。
+  这个提示值得当真。作者机器实测：128 MB 顺序写在 ext4 上约 **2.1 GB/s**，在 `/mnt/d` 上约
+  **247 MB/s**；创建 400 个小文件 ext4 **不到 10 ms**，`/mnt/d` 要 **0.72 s**
+  （后来复测：**884 vs 116 MB/s**、**13 ms vs 745 ms**，比值稳定在约 8× 与 50×）。
+
+  不只是慢。`/mnt/<盘>` 是 9p（drvfs）挂载，保留的是 **Windows** 的文件系统语义：
+  `chmod`/`chown` 不生效（`chmod 600` 读回来是 `777`）、文件名**大小写不敏感**（大小写写错只在
+  Linux CI 上才炸）、符号链接与可执行位是合成的，而且 **inotify 完全不工作**——发行版里的 watcher
+  对两侧写入都收不到任何事件（用 inotify 探针实测：`/mnt/d` 上 Windows 侧写入与 Linux 侧写入均为
+  **0 事件**，而同一探针在 ext4 上正常报出创建/修改/关闭写入）。因此 dev server、`--watch` 模式
+  与文件监听的测试在 Windows 盘上都是瞎的。需要时把项目放到 `/home` 下：语义、监听事件与上面那档
+  速度一次性都回来。
 - 危险命令默认被拒绝，除非调用时传 `allowDangerous: true`：
   - **任何递归删除**——`rm -r`、`rm -rf`、`rm -r -f`、`rm -R --force`、`rm --recursive`——
     因为 stdin 指向 `/dev/null` 时不会产生任何提示，`rm -r tree` 会静默删除整棵树。
@@ -302,7 +351,7 @@ DSH_SUBPROCESS_LOCAL=/path/to/dsh/node_modules npm run test:real
 `file:` 依赖是**副本**，改本仓库不会改变 DSH 实际加载的内容。任何改动之后：
 
 ```sh
-npm run sync                  # 复制到 ~/.dsh/profiles/web/node_modules/dsh-wsl
+npm run sync                  # 复制到 ~/.dsh/profiles/desktop/node_modules/dsh-wsl
 npm run sync -- /path/to/profiles/<profile>/node_modules/<你的依赖名>
 ```
 

package/cordis.patch.yml

@@ -1,5 +1,11 @@
-# This bundle layer registers the wsl tool plugin in an agent preset.
-# Presets can also add the row manually instead of relying on this patch.
+# This bundle layer inserts the wsl tool plugin process-wide, so every agent
+# preset gets the `wsl`/`wsl-path`/`wsl-env` tools without declaring anything.
+#
+# Do NOT also add a `tool-wsl` row to a preset. DSH registers tools by name and
+# the second registration fails with
+# `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.
 
 # The entry name is PATH-RELATIVE on purpose. DSH anchors a relative `name:` to
 # the directory of the patch file that declared it (`anchorInsertedPluginNames`),
@@ -13,3 +19,35 @@
 - 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-wsl-tool",
-  "version": "1.8.1",
-  "description": "Model-facing WSL tools for DeepSeek Harness: run Linux commands from Windows with background jobs, stdin, path translation, destructive-command guard and WSL capability diagnostics.",
+  "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.",
   "type": "module",
   "main": "index.js",
   "license": "MIT",