WSL 计算后端 KonataRings/dsh-wsl

dsh-wsl

面向 Windows 上 DeepSeek Harness 的 WSL 计算后端。

把 DSH 留在 Windows 上做编辑、查文献和写作；计算放到 WSL 里跑。这个插件就是两者之间的接缝：六个宿主侧工具，负责在 conda 环境里启动 Python、运行 bash、管理长任务——不用再手工驱动 wsl.exe，也就没有随之而来的引号、环境和编码问题。

Windows: DSH、你的编辑器、你的文件 → wsl_py / wsl_sh / wsl_job WSL: conda 环境、PySCF、重活累活 ← 6 个工具，无需改配置档

没有任何东西绑定到某一台机器：发行版、Linux home、conda 安装位置和默认环境都在首次使用时探测，每一项都能在配置档里覆盖。wsl_doctor 会打印探测到了什么，以及每个值来自哪里。

状态：哪些已验证，哪些没有

在信任一次长任务之前，先读这一节。

测试矩阵

下面所有内容都由仓库自带的测试套件（node selftest.mjs 和 node tests/.mjs）执行，任何一项检查失败都会以非零码退出。

| 套件 | 检查项 | 运行环境 | 覆盖内容 |
| selftest.mjs | 73 | 任意环境，无需 WSL | DSH 0.2 工具契约、wsl -l -v 解析（本地化表头、带空格的名称）、路径转换、解释器解析、启动器噪声过滤 |
| tests/drivetest.mjs | 56 | Windows + WSL | 探测、全部六个工具、env="none"、无 conda 模式、发行版不匹配报错 |
| tests/jobtest.mjs | 28 | Windows + WSL | 提交、轮询、增量日志、收集、终止、来源字段 |
| tests/edgecases.mjs | 38 | Windows + WSL | 刁钻的工作目录、失败任务记录、超时、200 KB 输出、用户代码里的 heredoc 分隔符、注入形态的输入、无 conda 模式端到端 |

在作者机器上实测（Windows 11、WSL2 Ubuntu 20.04、32 核、六个 conda 环境）：wsl_py 热启动约 1 s，wsl_sh 约 150 ms，wsl_env list 列出六个环境约 2 s，探测每个进程约 300 ms。

已知限制与缺陷

这些是当前真实存在的限制——不是路线图。

1. 每个实例只用一个发行版。 多发行版用户要在配置里选一个。没有按调用传 distro 的参数；wsl_doctor 会列出所有已安装的发行版，至少让这个选择有据可依。
2. 无 conda 路径靠模拟测试，没在真正没装 conda 的机器上跑过。 condaRoot: none 走的是同一段代码路径，但维护者手上没有一台真正缺 conda 的机器，所以首次在那种机器上运行，把握不如其余部分。
3. conda 探测靠一份猜测列表加一次登录 shell 探测。 装在非常规位置（micromamba 根目录、自定义前缀、conda 属于别的用户）需要显式指定 condaRoot。探测会报告它试过哪些候选。
4. 必须有 bash。 脚本通过管道喂给 bash -s；没有 bash 的发行版（Alpine、部分基于容器的镜像）会被明确拒绝并给出提示，而不是悄悄降级。
5. wsl -l -v 的解析对区域设置有一定容错，但只用手写的中文表头测过，没在真正本地化的 Windows 安装上验证。
6. WSL1 发行版未测试。 代码里没有任何地方假定 WSL2，但手头没有 WSL1 环境。
7. timeoutMs 到期只会杀掉 wsl.exe 启动器，不一定会杀掉它启动的 Linux 进程。 凡是必须能停掉的任务，请用 wsl_job 和 kill。
8. collect 需要 \\wsl$\<distro> 共享。 共享不可用时，工具会明确提示，并指向 wsl_sh；不会自动回退。
9. workdir 必须已存在。 工具故意不创建目录：目录缺失多半是笔误，而不是有意为之。
10. 任务不排队、不限流。 每次 wsl_job run 都立即启动；没有并发上限，也没有调度器。
11. budgetSeconds 只是提示。 超预算的任务会在 status 里标出，但绝不会被杀掉。
12. 没有客户端部分。 没有 UI；工具本身就是接口，也没有浏览器刷新可触发。
13. 只支持 DSH 工具契约 ≥ 0.2。 仍接受 { content, isError } 的构建不受支持；六个定义会注册失败。
14. 非 Windows 主机上不生效。 插件只记一条错误日志，不注册任何东西。
15. 环境清单不会自动刷新。 调用 wsl_env list 时会重新读取，但内部的环境名缓存只在重载时清空。

0.3.0 中发现并修复的缺陷（四个在 0.2.0 中同样存在）记录在 CHANGELOG.md：任务失败会破坏自己的状态记录、wsl_env install 吞掉 pip 失败、wsl_job run 同时接受 code 和 script、固定 heredoc 分隔符可能被用户代码提前闭合。

环境要求

- Windows 10/11，带 WSL2 和至少一个发行版（wsl.exe 在 PATH 上）。
- 支持 0.2 工具契约的 DSH 构建 —— 定义里声明 output: { schema, render }。
- 发行版内有 bash（见限制 4）。
- conda 可选。有 conda 就能用命名环境和 wsl_env；没有的话，工具回退到发行版的 python3。
- Node ≥ 22 仅测试需要；DSH 自带运行时。

为什么需要它

从 Windows 智能体调用 WSL 很容易出错，而且每种故障看起来都像别的问题：

| 症状 | 真正原因 |
| ModuleNotFoundError: No module named 'pyscf' | PATH 前置不生效：~/.bashrc 会跑 conda 的 init，把 anaconda3/bin 又放回最前面，所以裸 python 是 base，不是你的环境 |
| 命令被搞乱、$var 提前展开、正则失效 | 三层引号（PowerShell → wsl.exe → bash）；转义无法可靠解决 |
| 找不到 node/conda | BASH_ENV 只被非交互 bash 读取，而且必须被继承，所以 wsl bash -c 永远不加载你的 shell 配置档 |
| 中文变成 ?? 或乱码 | WSL 命令行输出到 Windows 是 UTF-16LE；直接按 UTF-8 解码就会读错 |
| 任务「成功」了，却什么都没产出 | heredoc 吃掉了 stdin，启动后台进程的那行命令根本没执行 |

上面每一条都在这里做了专门处理，也都在源码里对应的位置写了文档。

工具

| 工具 | 用途 |
| wsl_py | 在指定的 conda 环境里跑 Python（env="none" 表示用系统的 python3）。参数：code、env、workdir、timeoutMs。 |
| wsl_sh | 跑一段 bash 脚本。参数：script、env、workdir、timeoutMs。 |
| wsl_path | 在 C:\x ↔ /mnt/c/x、\\wsl$\Distro\x ↔ /x 之间互转，并把 ~ 换成检测到的 home 目录；check=true 时在 WSL 里 stat 目标路径。 |
| wsl_env | list 列出环境（Python 版本、发行版数量、大小）；packages 查某个环境的包；diff 对比两个环境；install 往某个环境里装包。需要 conda。 |
| wsl_job | run 启动一个脱离终端的任务；status 查状态；logs 看日志（用 offset 增量读取）；kill 杀掉；collect 把运行记录收回 Windows。 |
| wsl_doctor | 检测报告与预检：发行版、home、conda、解释器、资源、包版本、编码、GPU、workdir。 |

每个工具都返回文本；脚本以非零码退出时，工具调用会失败（isError），但 stdout 和 stderr 照样保留。

wsl_job 详解

- run 启动一个脱离终端的进程（nohup … &、disown），DSH 重启后它依然活着；status 靠读它的目录重新接上。
- 它会记录溯源信息：主机、内核、CPU 核数、解释器路径、Python/numpy/scipy/pyscf 版本、载荷的 sha256、git commit 与脏状态，还有一行 reproduce。
- 它会报告自己的退出码和峰值内存（/usr/bin/time -f %M）。
- 任务产出的文件落在它的 workdir 里——这些文件属于你的项目。collect 只复制运行自身的记录。
- logs 按字节偏移读取，返回 NEXT_OFFSET，所以反复调用不会重复发送输出。

安装

插件就是普通的 DSH bundle：一个 package.json，带 dsh.bundle.patch 条目；一个 bundle 补丁；一个 ESM 文件，导出 name 和 apply。没有依赖，也没有客户端部分。

dsh plugin --profile <profile> add @konatarings/dsh-wsl

重启 DSH，让模型跑一下 wsl_doctor——第一次调用要付检测的代价，并会打印检测结果。

开发时可以直接安装一份 checkout：

git clone https://github.com/KonataRings/dsh-wsl.git
dsh plugin --profile <profile> add link:/abs/path/to/dsh-wsl

配置

全部可选。在你的配置档 cordis.patch.yml 里覆盖任意字段：

- id: dsh-wsl
name: dsh-wsl
config:
distro: Ubuntu-22.04 # pin a distribution when several are installed
home: /home/you # only if $HOME is not what you want
condaRoot: /opt/conda # only if detection guesses wrong
defaultEnv: base # only if you do not want the default
budgetSeconds: 14400

| 字段 | 默认值 | 含义 |
| distro | detected | 传给 wsl -d 的发行版。不设置 = 由 wsl.exe 决定用哪个默认发行版。 |
| home | detected | Linux 主目录，也是默认工作目录。不设置 = $HOME。 |
| condaRoot | detected | conda 安装位置。不设置 = 依次探测 ~/anaconda3、~/miniconda3、~/miniforge3、~/mambaforge、~/miniconda、~/anaconda、/opt/conda、/opt/anaconda3、/usr/local/anaconda3，再执行 bash -lc 'conda info --base'。设为 none 可强制回退到 python3。 |
| defaultEnv | base / none | 调用未指定环境时使用的环境。有 conda 时为 base，否则为 none。 |
| jobsRoot | <home>/.dsh-wsl/jobs | 作业目录所在位置。 |
| windowsJobsRoot | %USERPROFILE%\.dsh\wsl-jobs | Windows 侧的镜像目录，collect 没有 output 时使用。 |
| budgetSeconds | 14400（4 小时） | 超出预算的作业会在 status 里标记，但不会被杀掉。 |
| defaultTailBytes | 65536 | wsl_job logs 默认的日志窗口大小。 |
| detectTimeoutMs | 30000 | 一次性探测往返的超时上限。 |

wsl_doctor 会为每个解析出的值标注来源：config、detected、detected (default)、derived 或 default。

作业目录结构

<jobsRoot>/<id>/
payload.sh the code or script, plus the environment preamble
run.sh self-contained runner; re-runnable by hand
write-meta.py the provenance writer (kept so job.json can be rebuilt)
started_at ended_at exit_code done maxrss_kb
stdout.log stderr.log
job.json host, kernel, cpus, python/pkg versions, payload sha256,
git commit and dirty state, and a reproduce line

故障排查

| 现象 | 处理方式 |
| 会话里没有 wsl_ 工具 | 定义没有注册成功。检查 DSH 构建是否接受 output: { schema, render }；定义被拒绝时会记录 dsh-wsl: could not register …。 |
| no conda installation was found | 设置 condaRoot，或者有意使用 env: "none"。wsl_doctor 会列出探测过的候选路径。 |
| bash was not found in "<distro>" | 该发行版没有 bash。安装 bash，或换一个发行版。 |
| distribution "X" is not installed | 配置里指定的名字不存在；错误信息会列出实际存在的发行版。 |
| collect 在 \\wsl$\… 上失败 | 改从 WSL 内部复制：wsl_sh: cp -r <linuxDir> <target>。 |
| DISTS 里某个环境显示 - | 该环境是 Python 2，没有 importlib.metadata。 |
| wsl_py 无法导入某个包 | 用 wsl_doctor 查看选中的是哪个解释器；PATH 上裸的 python 并不是同一个东西。 |
| 作业的 status 看起来不对 | 直接读 job.json 和作业自己的 stdout.log/stderr.log；记录就是普通文件。 |

测试

node selftest.mjs # offline: contract, distro-list parsing, path translation, noise filter
node tests/drivetest.mjs # live: detection + every tool
node tests/jobtest.mjs # live: submit, poll, tail, collect, kill
node tests/edgecases.mjs # live: hostile paths, failed jobs, timeouts, injection shapes

selftest.mjs 不需要 WSL：它通过 mock registry 注册工具，该 registry 执行与 @deepseek-ai/dsh-tools 相同的规则，检查纯函数，并断言没有任何默认值携带机器相关的路径。

live 套件用与插件相同的方式探测环境，并接受 DSH_WSL_TEST_DISTRO、DSH_WSL_TEST_HOME、DSH_WSL_TEST_CONDA 和 DSH_WSL_TEST_ENV 作为覆盖项。任何检查失败都会以非零状态退出。

License

MIT