dsh-remote-wsl
将 WSL 项目连接到 DeepSeek Harness，使用 Linux 工具、终端和原生文件交付。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:MFJip612/dsh-remote-wsl#8c41d6719f492ea92f813c6d758936a840129b54Remote Wsl 以 dsh-remote-wsl 发布，当前版本为 0.1.3。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
Open a project inside a WSL distribution directly in DeepSeek Harness (DSH): "Add workspace" gains a Connect WSL entry, where you pick a distribution, browse Linux folders, and make the selected directory a DSH workspace. In that workspace the sidebar terminal runs inside the distribution, and the agent's bash / read / write / edit / glob / grep likewise execute on the Linux side.
Target environment: Windows 10/11 + WSL2. The plugin uses only official DSH services; it neither depends on nor calls any third-party WSL plugin.
1. Entry point. The "+" in the sidebar workspace header and "Add workspace" on the new-session page share one add flow. The dialog now first asks where the folder is:
2. Choose a distribution. The "Connect WSL" dialog lists every distribution on the machine (stopped ones included) with its running state, and can refresh from the top-right corner. Distributions are enumerated with wsl.exe -l -v --all; UTF-16LE output is detected automatically, * marks the default distribution, and the list is cached for 5 seconds.
3. Choose a project. After a distribution is selected, browsing starts at that distribution's default user $HOME:
Ubuntu / home / me) are clickable;4. Register as a workspace.
\\wsl.localhost\<distro>\<path> (the \\wsl$ fallback form is probed automatically)./mnt/<drive>/... are registered as the real Windows path (for example D:\work\proj) — WSL's 9P share denies access to /mnt, so only the real drive path is readable and writable; the plugin remembers which distribution it came from.5. Terminal inside the distribution. Opening the sidebar terminal in this workspace actually runs
wsl.exe -d <distro> --cd <linux path>, that is the distribution's login shell, starting in the project directory.
6. Agent tools inside the distribution. In sessions of this workspace:
| Tool | Behavior |
|---|---|
bash | Runs bash -lc inside the distribution, with the workspace as the default directory; every call is a fresh shell |
read / write / edit | Use Linux paths; writes and edits publish atomically via a temporary file plus rename (WSL's 9P share does not support DSH's native hard-link publish) |
glob / grep | Search inside the distribution with globstar / GNU grep |
Windows PowerShell tools are hidden in WSL workspaces; ordinary Windows workspaces are unaffected.
Install the local directory from DSH's Plugins page, or:
dsh plugin --profile web add github:MFJip612/dsh-remote-wsl
The repository contains TypeScript sources only. Run npm ci (which builds automatically) or npm run build before installing a local directory. GitHub installs build through prepare; if pnpm blocks build scripts, allow the exact package key reported by the installer in that profile's pnpm-workspace.yaml, then retry. Alternatively, run npm pack and install the tarball containing compiled artifacts.
You can also ask the agent in a session to install that directory with the plugin manager. link: only guarantees that files in this directory are read; it does not guarantee a running Host reloads code. Under the default configuration, Host-side code changes require a full quit and restart of DSH; browser-side code changes only need a page refresh. DSH's default HMR configuration is root: [], which watches only configuration files. If the quit prompt reports a running task, wait for it to finish before restarting.
Before publishing, WSL write / edit enter the official fs/write-intent / fs/edit-intent so DSH captures the pre-edit content; on success they record fs/observed. Tool results reuse the native write/edit output format, metadata, and diff presentation, and the official workspace-changes produces the modified-file list and comparison at turn end. Read-only, out-of-bounds, unobserved, and stale-version writes are still rejected.
present keeps using the official executor and the deliverables/presented event; the plugin converts Linux absolute paths, relative paths, ~/, and mounted-drive paths into paths Windows can access, preserving descriptions, file limits, regular-file validation, and click-to-preview/open behavior. UNC paths pointing at another distribution are rejected.
The modified-file list automatically aggregates successful modifications from file tools; a standalone file card is still published by the model calling present, and the plugin does not publish a card for every source change automatically. When files are modified only through bash, non-Git directories lack the file tools' pre-capture; ask the model to call present explicitly when you need a standalone card.
Override the plugin row's config in the profile's cordis.patch.yml:
- id: dsh-remote-wsl
name: 'dsh-remote-wsl'
config:
terminal: true
tools: true
| Field | Default | Description |
|---|---|---|
terminal | true | Whether the sidebar terminal of WSL workspaces opens inside the distribution |
tools | true | Whether to enable Linux-side tools for sessions of WSL workspaces |
execTimeoutMs | 15000 | Timeout for a single wsl.exe call (milliseconds) |
distroCacheMs | 5000 | Cache duration for the distribution list |
maxEntries | 2000 | Maximum entries returned for one directory level by the picker |
maxReadBytes | 2000000 | Maximum bytes returned by a single read |
defaultDistro | '' | Reserved: default-distribution override (empty = use the WSL default) |
mountRoot | '' | automount root (empty = read the distribution's /etc/wsl.conf, falling back to /mnt) |
remote | false | Whether non-loopback clients may call the plugin's routes |
sidebar.workspaces.directoryFlow and conversation.hero.workspace.directoryFlow, and renders its own "Local folder / Connect WSL" picker with a lower priority than the official occupant; the dialog is drawn in shell.overlay. Choosing "Local folder" calls the official ctx.uiWorkspace.pickDirectory() (or the desktop-injected __DSH_DIRECTORY_PICKER__), so native picker behavior is unchanged.GET /dsh-remote-wsl/{status,distros,warm,list} and POST /dsh-remote-wsl/connect. All same-origin JSON, cross-site requests rejected, loopback-only by default; connect registers the workspace through the official workspaceRegistry.create().wsl.exe -d <distro> --exec bash --noprofile --norc -c "printf '%s\n' '<sentinel>' \"$WSL_DISTRO_NAME\" \"$(id -un)\" \"$HOME\"" (so rc-file output cannot pollute the identity), falling back to reading /etc/wsl.conf and /etc/passwd on failure.\\wsl.localhost share; when the share denies access it falls back to find inside the distribution.subprocess.spawnTerminal and replaces argv only when the cwd falls inside a WSL workspace; other terminals pass through unchanged. If an official upgrade changes this internal method, terminals fall back to the Windows shell and the connect flow is unaffected.agent/created; if it falls inside a WSL workspace, registers Linux tools within that agent's scope (scope tools shadow same-named global tools and do not affect other sessions) and hides the Windows shell via tools.restrict. Write operations honor ctx.sandboxPolicy.resolve(): read-only rejects writes and bash, workspace-write allows only targets inside the workspace (or a temporary directory), and danger-full-access permits everything.The tools' directory gate checks only the target path of write / edit; it is not Linux process isolation: under workspace-write, bash still runs with the distribution user's privileges and must not be treated as an operating-system sandbox.
wsl.exe, while other tools (web, subagent, todo, etc.) remain native DSH implementations.bash call is a fresh shell, so cd / export do not persist across calls; chain them in one command, or use workdir.run_in_background).working_directory tool does not recognize Linux paths (v1 limitation); cd inside the bash command when you need to change directory./mnt are unreliable, and the picker suggests upgrading to WSL 2.Maintained sources live in src/: Host ESM modules, src/client.ts for the browser, and src/scripts/repair-legacy.cts for the explicit recovery CLI. The compiled browser script keeps the DSH module-loader registration and uses the host's React instance.
npm ci
npm run check # Build the plugin, then strictly typecheck tests and the build script
npm run build # Generate loadable JavaScript and Host declarations
npm test # Build, check public entries/config, and run behavior regressions
npm pack # Build automatically before packaging
Requires Node.js >= 24.9.0. Product sources, build scripts, and tests are all TypeScript. Previous JavaScript files at the root and under lib/ have been removed. All JavaScript and Host declarations are generated only into Git-ignored dist/; generated artifacts are not committed. Public package entries point to dist/, and packaging automatically builds the runtime files and static resources. The build works independently of the DSH source checkout.
The recovery CLI source is src/scripts/repair-legacy.cts; execute its compiled dist/scripts/repair-legacy.cjs entry. It still defaults to report-only and modifies logs only with explicit --apply.
The exported Standard Schema Config is compatible with Cordis and preserves existing fields, defaults, and input normalization. Development types use Cordis 4.0.5, matching the Desktop used for validation; runtime services and React remain supplied by DSH.
For linked installs, build source changes before restarting the Host or refreshing the browser. Host changes still require fully exiting and restarting DSH. Real-WSL sections of npm test skip when WSL is unavailable; the two Desktop integration tests below require real WSL and fail when it is missing.
$env:ELECTRON_RUN_AS_NODE='1'
$exe = "$env:LOCALAPPDATA\Programs\DeepSeek Harness\DeepSeek Harness.exe"
& $exe test\pure.test.ts # pure functions (distribution parsing, path mapping, wsl.conf/passwd)
& $exe test\run.ts # Host services + real WSL (identity, directories, bash)
& $exe test\tools.test.ts # tool runtime + real WSL (write/read/edit/glob/grep/bash/sandbox gate)
& $exe test\registration.test.ts # registration layer (agent-scoped tool set, terminal routing wrapper)
& $exe test\desktop-runtime.cts | Out-String # the installed DSH's real Agent/tool execution chain + real WSL; no model cost
& $exe test\desktop-deliveries.cts | Out-String # real file-change summary, diff, and present delivery events; isolated WSL test directory
When no node.exe is on PATH, run with the Electron bundled with DSH Desktop in Node mode (as above). Sections that need a real WSL show skipped when it is unavailable.
test/desktop-runtime.cts must run through the installed DSH Desktop executable and requires access to WSL; it fails rather than skips when the environment is missing. The test replaces model network responses while keeping DSH's real Cordis, Agent loop, inbox, tool registration, tool execution, and subprocess services, covering a new session completing a conversation, in-memory inbox recovery, and multi-frame Zstd on-disk corruption rejection, write-lock exclusion, backup, and post-repair official reads. Conversations are created in memory and run read-only commands in the Linux HOME; disk tests use only temporary directories and do not change desktop sessions or user projects.
See CHANGELOG.md.
MIT