dsh-plugin-wsl-env 怎么安装？

在已安装 dsh CLI 引擎的环境中，进入插件页复制安装命令一键执行即可；自动检查通过：npm 包已发布且 engines 声明满足基线（声明 Node ^22.19.0 || >=24.0.0）；该结论来自程序自动检查，未经人工实机验证。

dsh-plugin-wsl-env 兼容性怎么样？

自动检查通过：npm 包已发布且 engines 声明满足基线（声明 Node ^22.19.0 || >=24.0.0）；该结论来自程序自动检查，未经人工实机验证。

dsh-plugin-wsl-env 有中文文档吗？

已提供中文翻译 README（由 DeepSeek 最新模型翻译生成），本站可切换中英文对照阅读。

dsh-plugin-wsl-env 还在维护吗？

GitHub 6 星。最近一次上游提交在 2026/10/31。

WSL 环境 Big-Dao/dsh-plugin-wsl-env

DeepSeek Harnessv0.9.0

Big-Dao0 天前有提交已提供中文文档扫描：含敏感能力

在 GitHub 查看 ↗

一个 DeepSeek Harness 插件，在 Windows 的 WSL 2 发行版中打开项目工作区。

34.3/100

综合分

GitHub 星标

463

npm 周下载

—/5

用户评分

数据截至 2026/10/31 · 周下载取自 npm 全网（含 CI / 镜像），非本站安装数；综合分由星标、活跃度与兼容性检查合成。

安装命令 · 需先装 dsh CLI 引擎

dsh plugin --profile web add dsh-plugin-wsl-env

npm 源 · dsh-plugin-wsl-env 的发布者账号已校验与本仓库一致

状态速览

判定依据：实装验证 · 静态安装检查 · 自动扫描 · 仓库维护状态

信任档位：仅索引

是什么

dsh 原生插件 · security

装得上吗

静态安装检查通过

未做真实安装

L4 · 真实安装等级说明 →

安全吗

本站尚未对该插件做风险分级

暂未覆盖，不等同于无风险

还在维护吗

活跃：最近一次提交在 0 天前

档位由哪些信号合成

本站实装验证（真实安装 L4 覆盖全站；L5 为运行时冒烟或实机截图，覆盖范围小于 L4） · 验证所用 dsh 版本 · 静态安装检查 · 风险分级 · 仓库维护状态。下方各区块是它的证据明细。

验证判据与等级说明 →

社区实装还没有人打卡 · 装过的第一个就是你

安装兼容性检查✓ 自动检查通过

展开查看检查明细 ↓

以下结论由程序自动检查 npm 包、engines 声明与入口文件得出，未做人工实机验证——能装不等于用着没问题。

✓npm 包dsh-plugin-wsl-env @ 0.9.0

✓Node 引擎要求 ^22.19.0 || >=24.0.0 · 基线 Node 22.19 满足

✓dsh CLI 依赖未声明 dsh 版本约束

✓入口文件main/exports/bin 已声明

验证方式：npm registry 存在性 + package.json 静态校验 · 最后检查 2026/10/10 15:48:48

安全扫描自动 · 静态分析源码

v2.7.0

🔵 扫描：含敏感能力尚无人工评估

展开查看扫描说明与证据 ↓

静态扫描发现插件具备触达本地系统的能力：执行外部命令、读写/删除本地文件、读取剪贴板或密钥类环境变量（至少其一）。这是能力清单，不是危险判定——具体能力项与证据见下方，安装前请自行判断是否需要。

可执行外部命令读写/删除本地文件发起外部网络请求

查看扫描证据（共 20 处，展示前 19 条）

执行外部命令来自配置/变量
lib/agent.js:158
return spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, "sh", scriptPath], {
执行外部命令来自配置/变量
lib/agent.js:871
const child = spawn(this.wslPath, [...distroArgs, "--exec", "sh", "-c", 'kill -s "$1" "$2" 2>/dev/null', "sh", signal.replace(/^SIG/, ""), String(pid)
写入本地文件
lib/auto-preset.js:57
appendFileSync(TRACE, `${new Date().toISOString()} ${message}\n`);
读取本地文件
lib/picker.js:120
enterable = (await raceAbort(stat(path), signal)).isDirectory();
读取本地文件
lib/picker.js:362
const opening = opendir(target);
写入本地文件
lib/picker.js:421
await mkdir(target);
执行外部命令来自配置/变量
lib/wsl.js:49
execFile(file, args, { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8", timeout: deadlineMs }, (error, stdout, std
读取本地文件
lib/agent-shared.js:28
const AGENT_SCRIPT_DIGEST = createHash("sha256").update(readFileSync(AGENT_SCRIPT_PATH)).digest("hex");
执行外部命令来自配置/变量
lib/agent-shared.js:63
spawnTransport: ({ wslPath, distro: target, argvPrefix }) => spawn(wslPath, ["-d", target, "--exec", ...argvPrefix, prepared.path], {
执行外部命令来自配置/变量
lib/watcher.js:162
const doSpawn = spawnProcess ?? ((path, args) => spawn(path, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
执行外部命令来自配置/变量
lib/session-runtime.js:86
spawnTransport: ({ wslPath, distro, argvPrefix }) => spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, native.path], {
执行外部命令来自配置/变量
lib/session-runtime.js:107
const child = spawn(argv[0] ?? wslPath, argv.slice(1), {
执行外部命令来自配置/变量
lib/native-agent.js:119
const child = spawn(wslPath, ["-d", distro, "--exec", "sh", "-c", script, "sh"], {
发起网络请求
lib/fsio-agent.js:161
const result = await this.request(follow ? "stat" : "lstat", [linuxPath], signal);
发起网络请求
lib/fsio-agent.js:183
const result = await this.request("realpath", [linuxPath], signal);
发起网络请求
lib/fsio-agent.js:220
const result = await this.request("list", [linuxDir], signal);
发起网络请求
lib/fsio-agent.js:303
const result = await this.request("read", [linuxPath, String(offset), String(maxBytes === Number.MAX_SAFE_INTEGER ? FS_READ_CHUNK_BYTES : maxBytes - o
发起网络请求
lib/fsio-agent.js:363
const result = await this.request("read", [linuxPath, String(range.offset), String(range.length)], signal);
发起网络请求
lib/fsio-agent.js:392
const result = await this.request("read", [linuxPath, String(offset), String(FS_READ_CHUNK_BYTES)], signal);

扫描于 2026/10/31（1 天前） · 范围入口闭包 + 全包扫描 · 来源 npm 发布包

静态扫描只反映源码中出现的调用，不构成安全背书；人工评估与自动扫描相互独立、互不覆盖。

依赖的 DSH / Cordis 模块

@deepseek-ai/cordis@deepseek-ai/cordis-plugin-include@deepseek-ai/cordis-plugin-loader@deepseek-ai/dsh-bash-local@deepseek-ai/dsh-fs@deepseek-ai/dsh-fs-local@deepseek-ai/dsh-fs-sandbox@deepseek-ai/dsh-host-directory-picker@deepseek-ai/dsh-sandbox@deepseek-ai/dsh-sandbox-policy@deepseek-ai/dsh-subprocess@deepseek-ai/dsh-subprocess-local

给这个插件打分还没有人投票↓

用户评分

还没有人投票，来当第一个

广告精选好物

飞利浦 TAH6519 主动降噪耳机 ¥299

头戴式无线 anc 主动降噪，蓝牙连接，久戴舒适向。

·anc 主动降噪 · 头戴式无线
·价格与库存以商品页实时为准

去淘宝看看→

广告MCP 兼容手册

装完插件，给 AI 接上 MCP

Cursor、Claude Code、VS Code 逐个核对：能不能装、配置怎么写、装不上是什么原因。

·按客户端逐格核对
·结论标注依据与风险等级

查 MCP 兼容性→

功能亮点

WSL内运行会话
沙箱隔离
发行版内提供终端

在 WSL 发行版里跑 DeepSeek Harness 会话：ctx.shell、ctx.fs 和 GUI 终端都由发行版内部提供，用 bubblewrap 做沙箱隔离

最近更新

在 GitHub 查看全部 →

v0.15.02026-10-27

兼容性矩阵版本：支持表及其证据、让它保持最新的容器与每夜任务、这次运行暴露的两个新发行版首次运行修复，以及用一个配置键表达的互操作立场。

· 变更

· WSL-310：scripts/bootstrap-import.sh——一个 rootfs 压缩包一步变成插件就绪的发行版。这条命令把兼容性矩阵运行记录下来的导入陷阱都自动化了：ELF 头架构检测（遍历 bin/ 候选，容忍提前退出的 dd 引发的 SIGPIPE）、带幂等 already-exists 分支的 wsl --import、OOBE 卡死解困、写入 [boot] systemd 和 [user] default 的 /etc/wsl.conf（导入的默认 root 发行版会让智能体以 root 运行）、按发行版家族安装包管理器，包括 systemd-sysv——docker 导出的压缩包会剥掉 /sbin/init，正是它断了 systemd 启动链——以 root 开启 Linger，最后跑一遍 doctor。已在 Debian 13.5 上验证（systemd 家族：执行唯一必需的 wsl --shutdown 后所有检查全绿）和 Alpine minirootfs 上验证（OpenRC：按 WSL-201 走非 systemd 配置档，systemd 检查按声明的降级上报）。

· 修复

· WSL-307：受限常驻进程的 spawn 准备现在是一份具名自愈清单。WSL-305 修好了缺失的工作区根目录；同一类新发行版问题还有更多成员（没有 sh、没有 base64、没有 sha256sum——minirootfs 几乎不带这些）。受限工厂的 prepare 现在跑一次 sh -c 往返，第一个失败的步骤会自报名字（workspace-root、interpreter、base64、sha256sum），失败以 spawn checklist step '' failed in 的形式到达调用方，而不是一个光秃秃的握手码。根目录以 $1 传入，绝不插值进脚本正文。在 Debian 上以缺失工作区根目录做了端到端验证：清单创建了它，第一次受限写入成功落地。

· 修复

· WSL-306：名字含换行的目录在选择器里列为一行精确记录。选择器在发行版侧的列表原来是 ls -1ALp 按行解析——名字里的换行会拆成两行或整个丢掉。列表现在改为 find -L -maxdepth 1 -mindepth 1 -type d -print0（NUL 分隔，-type d 在 -L 解析符号链接的发行版内过滤），在宿主机侧排序。Busybox find 支持所有参数——用换行命名的测试样本在 alpine:3、debian:stable-slim 和 fedora:latest 上验证过，选择器探测现在也带着这个样本跑真实组合。LIMITATIONS 条目退役。

· 变更

· doctor 新增跨发行版会话视图（WSL-309），并标记活跃常驻进程（WSL-313 的可观测部分）。运行时检查之后新增一次巡检，列出每个运行中的发行版及其 dsh-wsl-*.scope、scope 状态，以及该发行版自己的 cgroup 证实的常驻进程 pid——并发会话的坐标路由由此变得可能，也变得可见。agent.handshake 检查现在会注明被巡检的发行版里已有活跃常驻进程在跑（并注明它的新探测读不到那个常驻进程的最后错误）。scope 报告在过期判定旁记录常驻进程 pid。空闲倒计时和 lastError 留在宿主机侧——不存在 IPC，这条边界记录在 LIMITATIONS 里。

· 真机探测现在每夜在自托管 runner 上运行。一个定时触发器（21:30 UTC）只触发 probes 任务——所有托管任务都跳过该事件——于是 Tier 1 的「探测套件 100%，每夜」指标自己收集证据，不用等手动派发。一个专用并发组把积压的漏跑夜晚（runner 离线）折叠进最新一次运行。探测仍要求关闭 harness 应用；应用开着的夜晚会如实报红。

· shell 智能体现在在 CI 里、在它声称支持的非 Ubuntu 容器内运行。test/agent-container.mjs 在 docker run 里对 debian:stable-slim、alpine:3、fedora:latest、opensuse/tumbleweed 和 archlinux 用 v5 帧驱动真实的 wsl-agent.sh——每个七项检查：带就地脚本摘要的 HELLO 握手、PING、带退出码和两个流的 EXEC、对后续命令生效的 SETENV，以及 sha256sum/base64

v0.14.02026-10-27

本次发布修复了兼容性矩阵测试在新导入发行版上发现的首次运行陷阱，并附上测试实测得到的支持表。

· 修复

· WSL-305：受限常驻进程现在会在首次启动前创建 workspace 根目录。bwrap 配置档会绑定 workspace 根目录，而 bwrap 拒绝不存在的绑定源，因此在新导入的发行版上，首次受限写入会失败，只报出 FS_IO_ERROR: agent exited during handshake (code=1) 和一条误导性的补救提示。agent-confined.js 新增了 prepare 钩子（仅 workspace-write 模式，也是唯一会绑定根目录的模式），在 bwrap 运行前对 Linux 拼写的根目录执行 mkdir -p，幂等且忽略自身结果：bwrap 仍是权威，拒绝仍会传回调用方。现在这条拒绝会带上证据：握手失败的消息里包含常驻进程 stderr 的有限尾部（此前它被吞掉，白白花了半天诊断）。新增三项检查覆盖 prepare 钩子、它的 argv 和 stderr 附带信息；substrate.sh 里新增一条全新根目录分支，在真实发行版上端到端跑一遍根目录缺失时的启动。

· 变更

· Debian 已端到端验证，测试还发现一个首次运行陷阱。四项 harness 级探针在新导入的 Debian 13.5 上针对 wslfs-debian 配置档全部通过，在发行版内部测试套件之上补齐了整条链路（docs/COMPATIBILITY.md）。过程中浮现一个真实问题：workspace 根目录尚不存在时，受限常驻进程拒绝启动——bwrap 配置档会绑定根目录，bwrap 要求绑定源存在，而全新发行版没有可绑定的东西。先创建根目录后，十个失败步骤全部转绿；此前的 Ubuntu 运行里根目录是早先探针留下的。该问题已连同建议的启动准备修复记录在矩阵页面。

· 兼容性矩阵从文字描述改为实测页面。docs/COMPATIBILITY.md 记录了 WSL-202 的证据：六款真实 WSL2 发行版（Ubuntu、Debian 13.5、Fedora 44、openSUSE Tumbleweed、Arch、Alpine 3.22）于 2026-10-26 在同一台机器上执行了发行版内部探针套件，页面解释了两处观察到的差异而非隐藏它们——会话沙箱后台存活分支在三款 systemd 发行版上与 WSL 会话拆除竞争（探针假象，不是插件声明），而在 Alpine 上同一分支按声明失败，因为非 systemd 发行版拿到的正是 P1.1/WSL-201 承诺的更窄的 sessionSandbox: auto 范围。页面还记录了各发行版的导入陷阱（Debian OOBE 卡死、Alpine minirootfs 默认 root、busybox mktemp、zypper 的交互提示）和复现命令。尚未实测：真实 aarch64 硬件、容器镜像矩阵。

· aarch64 原生智能体在 CI 中执行，而不只是构建。原生包任务安装 qemu 用户态模拟器和 binfmt 注册（qemu-user + qemu-user-binfmt；noble 没有真正的 qemu-user-static 包），并在 qemu-user 下对刚构建的 aarch64 musl 二进制和已提交的 agent/native/linux-aarch64/dsh-wsl-agent 运行完整的 18 项检查 spike 套件——后者正是 Windows-on-ARM 会话会加载的二进制。用户态模拟覆盖每一项检查（静态 musl 二进制和 v5 帧不依赖宿主系统），先在本地验证：qemu-aarch64 下 18/18 通过，/proc/self/exe 解析到目标，HELLO 摘要绑定保持不变。这补上了 WSL-202 的「仅构建测试」缺口；真实 aarch64 硬件上的运行仍待完成。

v0.13.22026-10-26

本次发布跟进 DeepSeek Harness 0.2.1-rc.3：peer 声明改成下限范围，新版 harness 不用改插件就能装，锁文件里传递依赖的 undici 也越过了 Dependabot 自己清不掉的安全公告。

· 修复

· 锁文件里的 undici 通过 pnpm override 升到修复安全问题的 8.12.3。undici 只是作为 @deepseek-ai/dsh-http-proxy 的精确传递依赖被带进来，这个包由上游控制，所以 Dependabot 的安全任务找不到已修复的版本（它报「最新可用版本……是 8.11.2」然后失败）。pnpm-workspace.yaml 现在带上 overrides: { undici: '>=8.12.3' }（pnpm 11 的设置位置，package.json 里的 pnpm 字段不再读取），锁文件只换掉这一个包，override 注释写明上游挪动这个精确版本后就撤掉。src/ 下没有任何代码读 undici，检查链不受影响。

· 变更

· peer 声明改成下限范围，新版 harness 不用改插件就能装。peerDependencies 里的 @deepseek-ai/dsh-* 条目从精确版本改成 >=0.2.1-rc.3，@deepseek-ai/cordis / @deepseek-ai/schemastery 从 ~ 放宽到 ^（^4.0.5、^3.18.5）。带更新 harness 版本的应用现在不用等插件发版就能满足 peer——同一线的 rc 升级和每个稳定版都能干净安装；只有全新的预发布线（0.2.2-rc.1 对 >=0.2.1-rc.3）仍会告警，因为 semver 只允许预发布版本匹配同一元组上的比较符，任何范围都无法承诺一条尚未发布的线。这部分残留正是每周 peer-canary 的用途：它仍会把下一个 dist-tag 解析到临时目录，并在该线越过下限时报警——这就是重跑 docs/PEER-PARITY.md 对比、并在对应 harness 发布的提交里抬高下限的信号。devDependencies 保留精确版本，门禁保持可复现，一致性审计也仍只指向一条线。scripts/doctor.mjs 学会了新写法（peerSatisfied 现在读 >= 和 ^，compareVersions 按 semver §11 排序预发布标识——rc.10 高于 rc.9），scripts/peer-canary.mjs 能解析并保留这些写法，AGENTS.md、CONTRIBUTING.md、SUPPORT.md 和 docs/PEER-PARITY.md 写明了新策略。

· dev 版本线移到 DeepSeek Harness 0.2.1-rc.3。devDependencies 里每个 @deepseek-ai/dsh-* 版本从 0.2.1-rc.2 改成 0.2.1-rc.3——也就是下一个 dist-tag 解析到的版本——pnpm-lock.yaml 随之刷新。@deepseek-ai/cordis 和 @deepseek-ai/schemastery 留在 4.0.5 / 3.18.5：上游的 vendor/ 在这条线上没变。

src/ 下没有任何模块改动，而这正是结论。本插件继承或复刻的三个 peer 在 rc.3 上发布的 lib/index.js 逐字节相同——dsh-fs-local（fsio 方言，仍是 909 行）、dsh-fs（FsVersion 品牌）和 dsh-bash-local（spill 机制）——所以 docs/PEER-PARITY.md 里每处行号引用仍指向同一段代码；只有 tarball 的摘要变了，一致性文档现在记录 0.2.1-rc.3 的摘要，复查日期为 2026-10-26。这种逐字节相同也是新 peer 下限的依据：同样的代码在 rc.3 以上照样成立。上游这条线的发布说明都在 UI 和 LLM 侧（导航入口定制、分析、官方 /models 列表）：唯一影响组合的变化是应用自己的 cordis.patch.yml 里多了一行入口定制 UI，它随应用的 bundle 走，不在本插件的层里。preset-wsl 不用重新生成——packages/bundle/web-app/presets/standard.patch.yml 在 rc.3 上逐字节相同——cordis.patch.yml 里的来源注释现在指向 rc.3 的代码树。

数据来自仓库的 GitHub Release，可能与插件实际版本不一致。

README

由 DeepSeek 最新模型翻译生成

dsh-plugin-wsl-env English · 中文一个 DeepSeek Harness 插件，在 Windows 的 WSL 2 发行版中打开项目工作区。 Harness 进程仍在 Windows 上。命令执行、shell 脚本和文件访问都在发行版的 Linux 空间内完成，以获得全套 Linux shell 工具链。发行版内不安装辅助服务或守护进程，也不开放端口，受限命令在 bubblewrap 中运行。仅支持 Windows + WSL 2。为什么用这个插件 Windows 上的编程工具要在 WSL 项目中工作，有三条路：把整个工具装进发行版、连接发行版内的辅助服务，或由插件直接提供发行版环境。本插件是第三条。两类会话共用一套流程，同时保留发行版的真实工具和命令沙箱。 - 真实的 Linux 环境。命令在发行版自己的登录 shell 中运行，PATH、nvm、cargo、pyenv 和 rc 文件都生效。文件工具通过发行版内的 agent 访问发行版路径，底层文件系统取决于路径。 - 发行版内没有服务。没有辅助服务、没有守护进程、没有监听端口。唯一持久化的内容是 ~/.cache/dsh-wsl/agent/ 下按内容寻址的原生 agent 副本。 - 默认有沙箱。受限命令在发行版内的 bubblewrap 中运行。

展开完整文档（README 剩余 1 节）

dsh-plugin-wsl-env

English · 中文

一个 DeepSeek Harness 插件，在 Windows 的 WSL 2 发行版中打开项目工作区。

Harness 进程仍在 Windows 上。命令执行、shell 脚本和文件访问都在发行版的 Linux 空间内完成，以获得全套 Linux shell 工具链。发行版内不安装辅助服务或守护进程，也不开放端口，受限命令在 bubblewrap 中运行。

仅支持 Windows + WSL 2。

为什么用这个插件

Windows 上的编程工具要在 WSL 项目中工作，有三条路：把整个工具装进发行版、连接发行版内的辅助服务，或由插件直接提供发行版环境。本插件是第三条。两类会话共用一套流程，同时保留发行版的真实工具和命令沙箱。

- 真实的 Linux 环境。 命令在发行版自己的登录 shell 中运行，PATH、nvm、cargo、pyenv 和 rc 文件都生效。文件工具通过发行版内的 agent 访问发行版路径，底层文件系统取决于路径。
- 发行版内没有服务。 没有辅助服务、没有守护进程、没有监听端口。唯一持久化的内容是 ~/.cache/dsh-wsl/agent/ 下按内容寻址的原生 agent 副本。
- 默认有沙箱。 受限命令在发行版内的 bubblewrap 中运行。缺少 bubblewrap 时命令直接失败，不会脱箱运行。
- 按会话生效。 打开发行版文件夹的会话获得发行版环境；打开 Windows 文件夹的会话保留 Windows 工具。两者可同时运行在一个 harness 进程中。
- 与 GUI 集成。 文件夹选择器列出已安装的发行版，终端在发行版内打开 shell，模型能看到监听端口。

为什么是 Linux，而不是 PowerShell

多数编程 agent 的训练材料以 Linux 为主，开源工具链也大多先在 Linux 上构建和测试。让 agent 在 Windows shell 里工作，等于要求它在每次调用时做一层翻译：

- 训练先验。 示例、CI 脚本、Dockerfile 和大多数公开答案用的是 POSIX shell 和 GNU 工具；模型的第一反应是 bash，不是 PowerShell。
- 工具链支持。 Node、Python、Rust、Go、C/C++ 和多数构建系统先在 Linux 上验证。Windows 支持往往是移植，引号、路径、换行和文件锁都不一样。
- Shell 语义。 PowerShell 和 cmd 在引号、转义、管道、环境变量、退出码和路径分隔符上都与 POSIX 不同。混用两套语法，很容易产生看起来像模型犯的低级错误。
- 环境漂移。 Windows 侧的 PowerShell 版本、执行策略、PATH 和已装工具因人而异；Linux 环境更容易复现和容器化。

结果是更多失败的命令、更多重试，以及更多时间花在语法而不是任务上。生成的代码也一样：shell 片段、构建命令和 CI 风格的一行命令通常按 POSIX 编写，发行版才是它们原样运行的地方。真实的 Linux 登录 shell 去掉了这层翻译。现代 PowerShell 和 Windows 原生工具在缩小差距，但默认先验和多数项目脚本仍然假设 POSIX。

本插件把 GUI 留在 Windows，只把执行环境移进发行版，让 agent 得到它的训练和工具链都假设的那个 shell。

方案对比

| | 桌面远程（VS Code、ZCode） | 本插件 |
| 发行版内 | 辅助服务 | 一个缓存的 agent 可执行文件 |
| 网络 | 监听端口 | 无 |
| 命令沙箱 | 无 | bubblewrap |
| 卸载 | 删除服务 | 删除缓存 |

桌面远程重连更快、更成熟。如果 CLI agent 能覆盖你的工作，直接装进 WSL 更简单。本插件面向的场景是：harness 留在 Windows，同时要求命令有沙箱。

要求

- Windows 10 或 11，启用 WSL 2，并至少有一个发行版。
- 发行版内安装 bubblewrap，必需。
- 默认的会话沙箱需要 systemd：在 /etc/wsl.conf 设置 [boot] systemd=true，重启 WSL，然后执行一次 loginctl enable-linger "$USER"。没有 systemd 时，在 wsl-shell 和 wsl-fs 上都设置 sessionSandbox: false。
- 可选：ripgrep 用于搜索，git 用于变更快照，inotify-tools 用于文件监视。

发行版内不需要 Node.js。

安装

在 Windows 终端执行：

dsh wsl --from-default-profile web --dump-config # 创建 profile
dsh plugin --profile wsl add dsh-plugin-wsl-env # 安装插件及其配置
dsh --profile wsl --dump-config # 检查：输出 "# == dsh-plugin-wsl-env"
dsh --profile wsl # 启动

第一条命令之前安装 bubblewrap：

wsl.exe -d <发行版> -u root -- apt-get install -y bubblewrap

在插件检出目录中，pnpm run bootstrap <发行版> 检查四个发行版工具，并按包管理器打印安装命令；加 --install 仅在缺少 bubblewrap 时执行该命令。若只缺少其他工具，请自行执行打印的命令。

升级：再次执行 add 命令。卸载：dsh plugin --profile wsl remove dsh-plugin-wsl-env；之后可删除 ~/.cache/dsh-wsl。如果你为了恢复预览在 profile 里加过 workspace-files-wsl 的临时覆盖，升级后请删掉：插件不再挂载该行。

使用

打开一个发行版文件夹作为工作区，例如 \\wsl.localhost\ubuntu\home\you\project。

- 打开哪个发行版的文件夹，就在哪个发行版执行——即使它不是 WSL 的默认发行版。
- 命令在发行版登录 shell 中运行。/home/you/x 与 \\wsl.localhost\ubuntu\home\you\x 是同一个文件。
- New terminal 在同一发行版、同一目录打开 shell。
- 模型能看到监听端口，并返回 dev server 的 URL。WSL 2 会把 localhost 转发到 Windows。
- 权限选择器：read-only、workspace-write（默认）、danger-full-access。只有 danger-full-access 不经过沙箱。

配置

配置写在 $DSH_HOME/profiles/<名字>/cordis.patch.yml 的命名行上。主要设置：

| 行 | 键 | 默认值 | 作用 |
| wsl-shell | distro | '' | 发行版模式；空/auto 跟随工作区，default 强制 WSL 默认 |
| | sandbox | true | 用 bubblewrap 约束命令 |
| | sessionSandbox | true | 会话命令跑在同一个 systemd user scope 中 |
| | agentBackend | auto | 发行版内 agent：auto、native 或 shell |
| | maskWindowsDrive | false | 让受限命令看不到 /mnt |
| wsl-fs | distro | '' | 发行版模式；空/auto 跟随每个目标路径 |
| | restrictToDistro | true | 固定发行版（default 或名字）时拒绝属于其他发行版的路径 |
| | sandbox | true | 按策略检查受限写入 |
| | sessionSandbox | true | 受限写入跑在会话 runtime 中 |
| | substrate | agent | 发行版内 agent；share 在启动时被拒绝 |
| directory-picker-wsl | includeHostHome | true | 同时列出 Windows 家目录 |
| subprocess-wsl | distro | '' | 发行版模式；空/auto 跟随启动目录 |

wsl-shell 和 wsl-fs 位于随包的 wsl preset 中，按 id 覆盖无效。要改就覆盖整个 preset-wsl 行；配方和其余键见 docs/CONFIGURATION.md。cordis.patch.yml 是随包值的注释参考。

架构

一个 harness 进程可同时服务 Windows 文件夹会话和发行版文件夹会话。服务分两层挂载：

应用层（每个进程一份） ├─ directory-picker-wsl、workspace-files、subprocess-wsl ├─ fs-routing：根级文件系统，按路径分流 └─ auto-preset：会话打开发行版文件夹时绑定 wsl preset

wsl preset（每个会话） ├─ wsl-shell：命令 └─ wsl-fs：文件操作

- wsl-shell 通过 systemd user scope 内的一个常驻 agent 执行命令。agent 默认是发行版架构（x86_64 或 aarch64）对应的包内静态 musl dsh-wsl-agent，shell agent 作为回退。每条命令在登录 shell 中、bubblewrap mount profile 下运行。scope 比命令活得久，所以后台服务存活，ps 能看到整个会话。设置 sessionSandbox: false 后，agent 仍按发行版常驻，但每条命令使用自己的 profile。
- wsl-fs 通过同一个发行版内 agent 提供读写。受限写入运行在 mount profile 与策略一致的常驻 agent 中，由内核执行写入边界。没有宿主机侧的文件回退：agent 不可用时文件操作直接失败。
- GUI 文件树和预览使用随包的 workspace-files 行，而不是插件的替换行：它的客户端半边是浏览器的 file 资源提供者。WSL 路径经根级路由读取，仍在发行版内，但会多几次 agent 往返。
- 应用层服务按路径分流：发行版 UNC 路径走发行版，Windows 盘符路径留在宿主。见 docs/root-fs-routing.md。

沙箱

| 模式 | 命令可以做什么 |
| read-only | 读整个发行版；挂载新的 /dev，其余不可写 |
| workspace-write | 上面的权限，加上会话工作区；会话 runtime 下 /tmp 是发行版真实 /tmp |
| danger-full-access | 不经过沙箱 |

设置 sessionSandbox: false 时，workspace-write 命令使用私有的 /tmp，而不是发行版的真实 /tmp；read-only 不挂载可写的 /tmp。

bubblewrap 是必需项。缺失或损坏时，受限命令报 SANDBOX_UNAVAILABLE，不会运行。在对应的行设置 sandbox: false 可关闭沙箱；模型会收到"该操作无沙箱"的说明。

隔离上报为 partial。发行版内的命令仍可通过 /mnt/c 启动 Windows 程序，bubblewrap 无法控制 Windows 进程。maskWindowsDrive: true 让受限视图看不到 /mnt，但会被 interopVisibility: visible 覆盖；遮罩只能收窄这个洞，不能关死。关闭 WSL interop 需要另行在发行版的 /etc/wsl.conf 中设置 [interop] enabled=false。见 docs/ARCHITECTURE.md 和 SECURITY.md。

常见问题

| 现象 | 处理 |
| 每条命令都报 SANDBOX_UNAVAILABLE | 在发行版内安装 bubblewrap，或设置 sandbox: false |
| 会话在第一条命令前就被拒绝 | 启用 systemd 和 linger，或在 wsl-shell、wsl-fs 上设置 sessionSandbox: false |
| 发行版内 glob、grep 很慢 | 运行 pnpm run bootstrap <发行版>，使用打印的安装命令安装 ripgrep |
| dsh plugin add 没有输出 | 插件已安装；这是成功 |
| 改了 lib/ 但不生效 | 运行 pnpm run sync:windows，然后重启应用 |

更多错误码和拒绝原因见 docs/ARCHITECTURE.md，插件不做的事见 docs/LIMITATIONS.md。

开发

pnpm install # 开发依赖
pnpm run build # 从 src/ 生成 lib/（lib/ 提交进仓）
pnpm test # 风格、语法、构建一致性、类型、单元测试
pnpm run test:coverage # 带覆盖率阈值的单元测试
pnpm run sync:windows # 更新应用加载的 Windows 侧副本

工具链跟随 harness 宿主：Node ^22.19.0 || >=24.0.0。src/ 是 TypeScript，lib/ 是生成并提交的产物，必须保持同步。应用加载的是 Windows 侧的 lib/ 副本，所以构建后要运行 sync:windows 并重启应用。

真机探针仅在 Windows + WSL 下运行。见 CONTRIBUTING.md 和 test/probe/。

文档

| 文档 | 内容 |
| docs/CONFIGURATION.md | 所有配置键及覆盖方法 |
| docs/ARCHITECTURE.md | 服务、路径路由、沙箱、错误码 |
| docs/LIMITATIONS.md | 插件不做的事 |
| docs/ROADMAP.md | 当前计划和推迟项 |
| docs/ROADMAP-1.0.md | 1.0 与生态优化计划 |
| docs/VALUE.zh.md | 价值与取舍 |
| CONTRIBUTING.md | 开发循环、质量门、探针 |
| SECURITY.md | 私下上报漏洞 |
| SUPPORT.md | 支持范围与提问渠道 |
| docs/RELEASING.md | 发布检查单 |

许可

MIT，见 LICENSE。