dsh-wsl-tool

dsh plugin --profile web add dsh-wsl-tool

dsh-wsl

[English](README.md) | 简体中文

面向模型（model-facing）的 WSL 工具插件，用于 DeepSeek Harness（DSH）。它让智能体直接通过

wsl.exe 执行 Linux 命令——无需手写 .sh 脚本或 pwsh 包装——并且在命令执行这一层基本对齐

Linux 原生 DSH：真实的 Linux 内核与 bash、退出码与信号、超时、截断与落盘、可用内置 job 工具读回的

后台作业、stdin，以及 Windows/WSL 路径自动转换。

它也能像你一样地干活：在一个能保持状态的 shell 里，一件事一个 shell，每条命令都连同退出码留下记录，

输入框上方只显示一行紧凑的子任务数量；当你点名自己打开的终端时，键盘点一下就能拿回来。

有两点限制值得在依赖它之前知道：wsl 调用位于 DSH 沙箱层之下，文件策略约束不到它

（见[沙箱边界](#沙箱边界)）；项目放在 Windows 盘上时仍是 Windows 的文件系统语义——没有 POSIX

权限位、文件名大小写不敏感、收不到文件变更通知——速度也低一个数量级（见[注意事项](#注意事项)）。

工具

插件注册十个工具。除 wsl-term 外每个都有独立开关，其中 wsl-doctor 与 wsl-bootstrap 默认关：

工具 · 用途

wsl · 执行 Linux 命令，返回带退出码、超时与截断标记的 stdout/stderr

wsl-path · 通过 wslpath 在 Windows 与 WSL 路径间互转

wsl-env · 汇总 WSL 环境（发行版、内核、CPU、内存、磁盘）

wsl-doctor · 对照项目清单与发行版实际能力，指出缺什么——包括那些其实是 Windows 二进制的命令。只读，默认关（需要诊断时再开）

wsl-bootstrap · 按固定配方在发行版里补装缺失的工具链，先出计划再动手

wsl-term · 在本会话的终端里工作：一件事一个 shell，每件事都在输入框上方留下记录

wsl-read · 读取发行版里的文本文件，整份或按行范围；二进制与非 UTF-8 直接拒绝

wsl-write · 写入发行版里的文本文件，原子替换，父目录自动创建

wsl-edit · 在发行版里的文件中替换唯一匹配的字符串

wsl-grep · 在发行版里按正则搜索文件内容，按文件分组返回带行号的匹配行

wsl

执行形式：

wsl.exe [-d <distro>] -e bash -lc "cd <workdir> && <command>"

返回 stdout/stderr，并附加 [exit code: N] / [killed by signal: ...] /

[timed out after Nms; the command was killed] / [output truncated: ...] 标记。

<distro> 取调用参数 distro，其次 DSH_WSL_DISTRO，都没有时完全不传 -d，

由 wsl.exe 使用系统默认发行版——这正是本插件能装到没有 Ubuntu-22.04 的机器上的原因。

超过 Windows 命令行上限（32767 字符）的脚本会改为通过 stdin 交给

wsl.exe [-d <distro>] -e bash -ls 执行，因此长命令没有体积上限。

传 stdin 可以把文本喂给命令（默认是 /dev/null，交互式命令会立刻 EOF）；传

runInBackground: true 则把命令交给宿主的任务注册表，模型随后用已有的

job_output 工具读它、用 job_kill 停它——不需要任何新工具。后台任务需要

preset 组合里有 @deepseek-ai/dsh-tool-jobs；没有时会直接报错说明，而不是悄悄退化成

前台执行。

wsl-path

双向转换路径：C:\Users\me\a.txt → /mnt/c/Users/me/a.txt，或

/home/me/a.txt → \\wsl.localhost\Ubuntu-22.04\home\me\a.txt。方向自动识别，

也可用 direction: 'win' | 'linux' 强制指定。

wsl-env

返回发行版列表、被探测的发行版、内核与架构、CPU 数、内存与磁盘占用，以及这台机器

实际能做什么：

distro: Ubuntu-22.04 (system default)
Linux 6.6.87.2-microsoft-standard-WSL2 x86_64
nproc: 24
Ubuntu 22.04.5 LTS · WSL2 · cgroup v2
systemd: yes · docker: not installed
GPU: /dev/dxg present (GPU passthrough enabled) · nvidia-smi: GPU 0: NVIDIA GeForce RTX 5070 Laptop GPU
drives: /mnt/c /mnt/d
/etc/wsl.conf: [boot];systemd=true;[user];default=xiny; · .wslconfig: not set
launcher: WSL 版本: 2.6.3.0 · 内核版本: 6.6.87.2-1 · WSLg 版本: 1.0.71 · Windows: 10.0.26200.9457

让智能体在动手前就知道有什么可用：WSL1 还是 WSL2、服务是否由 systemd 托管、cgroup 版本

（容器相关）、GPU 直通、docker（未装／只有 CLI／守护进程版本）、挂载了哪些盘，以及

/etc/wsl.conf 与 Windows 侧 .wslconfig 的配置。可传可选参数 distro。

每一项都是可选的，且如实降级：探针没跑成的行会被省略，读到了但为空的值会写明

（docker: not installed、.wslconfig: not set），探测失败会写进摘要而不是被丢掉，

发行版不存在则直接报错，而不是给出一份残缺答案。注意 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 自己会做什么，因此安装前就能看到具体改动。安装以 root 执行；

某一步失败即停下并附上它的输出末尾。

wsl-term

这里其他工具都是每次调用开一个全新 shell，这让它们可以安全并行，也是默认方式。wsl-term 反过来：

一件事一个 shell。它适合那些"shell 自身状态就是重点"的活——想看着它跑完的构建、交互式程序、

必须在多步之间保留的目录或环境。

wsl-term 就在这个终端里工作：

wsl-term({ action: "list" })                                  → 有哪些终端
wsl-term({ action: "read" })                                  → 当前屏幕
wsl-term({ action: "run", command: "make sta", subtask: "跑通 sta 流程" })
                                                              → 在那个终端里执行，返回输出与退出码
wsl-term({ action: "input", data: "ls", submit: true })       → 原始按键
wsl-term({ action: "interrupt" })                             → Ctrl-C
wsl-term({ action: "close", id: "…" }

…(truncated)