WSL 项目服务 mvalentsev/dsh-wsl-projects

每个项目一个 DeepSeek Harness web 服务器，跑在 WSL2 里 —— 从 Windows 应用的面板里启动、停止、打开。

问题

dsh web 只服务一个工作区 —— 也就是它的 dsh home 最后打开的那个。把它指向第二个项目，两个项目就会抢同一个 home、同一个端口、同一个 token：链接打开错误的项目，会话混在一起，重启会杀掉你的登录。想同时跑多个项目，就得手动折腾终端和端口。

这个插件给每个项目一块自己的地盘 —— 再用一个面板统管它们。

你能得到什么

- 每个项目一个 systemd 用户服务。 从面板启动和停止；终端关掉，服务照样活着。
- 每个项目一个端口。 端口绝不会分给第二个项目，所以链接永远打开它所属的那个项目。
- 每个项目一个 dsh home。 对话和会话都留在各自项目里。账号只复制一次，之后不会再让你登录。
- 能应答的链接。 服务器应答之后，面板才会显示链接 —— 没有失效的 token。
- 应用里的面板。 每个服务都带着自己的状态、端口和控制按钮：Open、Stop、Start、Restart、Remove。启动项目只需选中它、起个名字、挑个端口。状态每五秒刷新一次，面板显示的就是此刻的真实情况。
- 给程序用的两个入口。 /wsl-projects/api/ 下的 REST API，以及 wsl_dsh 智能体工具，让模型拥有同样的操作能力。

环境要求

- Windows，并已安装 DeepSeek Harness 应用。
- WSL2，并装好一个 Linux 发行版。插件在 Ubuntu 上测试过，其他发行版未测试。
- 该发行版里有 dsh，且在 PATH 中可直接调用。
- 该发行版里有 systemd —— 插件用的是 systemctl --user。
- 该发行版里有 bash。
- 一个存放项目的文件夹：默认 ~/projects，可配置。

安装

1. 在 Windows 的终端里运行这条命令：

dsh plugin --profile desktop add <path-or-github-spec>

如果用的是普通的 dsh web 配置档，把 --profile 换成 web。也可以直接给本地克隆的路径。

2. 退出 DeepSeek Harness 应用，再重新启动。

只刷新页面不够。应用加载插件两半的时机不同：面板随客户端那一半一起到达，而宿主那一半属于启动流程的一部分。

使用

1. 打开面板 —— 它在侧边栏底部。
2. 在 Start a project 下选择一个项目。
3. 点击 Start a service for this project。
4. 在新出现的行里点击 Open。

配置

把设置加进配置档补丁：

- id: wsl-projects
name: dsh-wsl-projects
config:
distro: Ubuntu
projectsRoot: ~/projects
unit: dsh-web.service
defaultPort: 19800
configFiles:
- ~/.dsh/settings.yaml
- ~/.dsh/profiles/web/cordis.patch.yml

| 键 | 含义 | 默认值 |
| distro | 要使用的发行版。 | WSL 默认发行版 |
| projectsRoot | 存放项目的文件夹。 | ~/projects |
| unit | 掌管 WSL 里 dsh 的 systemd 用户单元。 | dsh-web.service |
| defaultPort | 新服务的起始端口。 | 19800 |
| configFiles | 面板可以编辑的文件。 | dsh 的标准文件 |

面板的位置

面板默认在侧边栏底部。另外还有两个位置可选 —— 在 bundle 启动前设置一个全局变量：

window.__DSH_WSL_PROJECTS_SURFACE__ = 'settings' // a page in Settings
window.__DSH_WSL_PROJECTS_SURFACE__ = 'floating' // a movable panel

工作原理

项目是控制单位。每个项目都有自己的 dsh home，位于 ~/.dsh/dsh-wsl-projects/homes/<folder>-<tag>/。tag 来自路径，所以文件夹同名的两个项目会拿到各自独立的 home。首次启动时，启动器创建 home，从 ~/.dsh 一次性复制账号，再把项目写进该 home 的工作区存储。

隔离才是关键，而 dsh 的行为决定了三条规则：

- dsh 打开的是 $DSH_HOME/storages/workspace.json 指定的工作区 —— 它不会拿这个工作区和启动它的文件夹做比较。每个项目一个 home，才能让每个服务都待在自己的项目上。
- dsh 用主机和端口来标识浏览器会话。每个项目一个端口，才能什么能防止会话跨项目串味。
- 一个 token 只属于一个进程，所以更早一次启动留下的 token 已经失效。只有运行中的服务端应答之后，才会给出链接。

自动化

REST 接口在 /wsl-projects/api/ —— state、units、projects、distros、start、stop、restart、stop-unit、restart-unit、remove-unit、config、alias。智能体工具 wsl_dsh 把同样的操作开放给模型。

故障排查

面板毫无反应，还说主机那一半版本太旧。

应用一启动就会运行主机那一半。退出应用，再重新启动。刷新页面不够。

Open 显示的项目不对。

看地址。一个端口只服务一个项目，每个项目有自己的 home。重新启动该项目，然后在它自己那一行点 Open。

Open 报认证相关的错误。

链接太旧了。点 Stop，再点 Start。面板在显示链接之前会先检查它。

某个项目又要求登录。

该项目的 home 里存着一份账号副本，这份副本不会跟着 ~/.dsh 之后的改动走。删掉副本，再启动项目：

rm ~/.dsh/dsh-wsl-projects/homes/<folder>-<tag>/.credentials.yaml

某个服务起不来。

看它的日志：

journalctl --user -u dsh-web-<folder>-<tag>.service -n 40

开发

npm run check # every check, in one sequence
npm run check:offline # only the checks that need no distribution

上面的面板图片是真实面板的截图：node scripts/capture-panel.mjs <url> 可以从运行中的应用重新截取。横幅和架构图是绘制的，各有浅色、深色和窄版三种变体，放在 docs/。

CI 在 Node 20、22 和 24 上跑离线检查。每项检查覆盖什么，以及怎么跑那些需要真实发行版或浏览器的检查，见 CONTRIBUTING.md。

安全

- 插件以你的权限运行：它使用 systemctl --user，并读写发行版里的文件。
- 主机只接受来自面板自身 origin 的请求；origin 不同的请求会收到错误。
- origin 检查不是认证：本地进程只要拥有相同的用户权限，仍然能访问回环端口。

许可证

MIT —— 见 LICENSE。