DeepSeek Harness 在 WSL2 里安装：DSH plugin 路径、浏览器联动与端口转发

WSL2 里装 DeepSeek Harness 的第一件事不是敲命令，而是决定「装哪一侧」——因为它决定了你的 DSH plugin 能操作哪些文件、dsh web 给谁看、以及后来所有路径问题长什么样。 三种玩法都成立：只装 WSL 侧（处理 Linux 项目最顺）、只装 Windows 侧（处理 Windows 项目、WSL 只当工具链）、两侧都装（各自独立、互不干扰）。真正容易踩的是三处：路径互操作（/mnt/c 的跨文件系统代价、Windows 反斜杠路径被 Markdown 转义吃掉）、浏览器联动（WSL 的端口转发什么时候会失效）、以及跨系统挂载带来的文件属主差异让插件写文件失败。

DeepSeek Harness 装哪一侧：WSL 侧与 Windows 侧的三种玩法

一句话结论：别问「WSL 能不能装 DeepSeek Harness」，要问「你要它操作哪一侧的文件」——按文件在哪决定装在哪，混装只会带来两套互不相通的环境。

方案 A：只装 WSL 侧（最常用）

一句话结论：在 WSL 里用 npm 全局装 @deepseek-ai/dsh、把 DSH_HOME 放在 WSL 原生文件系统里、起 dsh web 后由 Windows 浏览器经本机转发访问——这是 Linux 项目最顺的一条路。

1. 用 nvm 装 Node（避免 sudo npm -g 带来的权限问题）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 20 && nvm use 20 && node -v

2. 全局安装 DeepSeek Harness 本体：

npm i -g @deepseek-ai/dsh
dsh --version        # 预期：打印版本号

3. 把数据目录固定在 WSL 原生盘（放 /home 下，别放 /mnt/c）：

export DSH_HOME="$HOME/.dsh"     # 建议写进 ~/.bashrc 持久化
mkdir -p "$DSH_HOME"

4. 起 dsh web（参数名以 dsh web --help 为准）：

dsh web --port 3080
# 预期：WSL 内 curl -I http://127.0.0.1:3080 有响应

5. 在 Windows 浏览器打开 http://127.0.0.1:3080（WSL2 本机转发默认生效，见第 5 节）。

方案 B：装 Windows 侧 + 工作区走 /mnt/c

一句话结论：DeepSeek Harness 装在 Windows 侧、项目也在 Windows 盘上，WSL 只作为你的 shell——这样文件 IO 走 Windows 原生路径，代价是 WSL 侧命令看到的路径是 /mnt/c/...，引用要转换。

1. Windows 侧安装：在 Windows 终端里 npm i -g @deepseek-ai/dsh，用 dsh --version 验证。
2. 工作区用 Windows 路径加入；插件操作的是 Windows 盘上的文件，性能与属主都正常。
3. 要跨到 WSL 侧时用 \\wsl$\<发行版>\home\...（资源管理器）或 /mnt/...（WSL 侧命令）—— 别在 Windows 程序里写 Linux 风格路径，反之亦然。
4. 取舍提醒：这条玩法下你失去了「Linux 工具链一致性」——同一条插件命令在两侧表现可能不同（shell、路径分隔符、权限模型都不一样）。

方案 C：两侧都装（各自独立）

一句话结论：两侧都装完全可行，关键是从头就把两套环境当两个独立的机器**——各自一份 DSH_HOME、各自一份插件清单；任何「一边装了另一边怎么没有」的疑问，答案都是「它们本来就不共享」。**

1. 两侧分别设 DSH_HOME，并且不要把同一个卷/目录同时给两侧用（跨系统并发写同一份数据容易产生状态不一致）。
2. 插件各装各的：在 WSL 侧装的是给 WSL 环境用的，Windows 侧的插件操作 Windows 文件。装了哪个、什么版本，用 DSH Plugin Hub 的已装列表逐侧核对，比在两边命令行里对清单快。
3. 升级也要做两遍：两侧版本漂移是常态，见 多台机器统一更新 DeepSeek Harness。
4. 别共享凭据文件：两侧的品牌与账号体系独立，凭据格式也会有版本差异，强行共享会直接启动失败。

DSH plugin 与 Windows 的路径互操作：WSL2 三种写法与取舍

一句话结论：路径问题只有一条原则——谁执行、用谁的路径风格；而性能问题只有一条原则——项目放 WSL 原生盘，跨系统只放必须跨的产物。

1. 遇到「路径明明存在却打不开」，先看它在哪一侧执行、用的是哪种风格（跨系统时最常见的是把 C:\ 塞给了 WSL 侧命令）。
2. 遇到「图片/附件预览 404」，优先怀疑反斜杠转义把路径写坏了——优先改用正斜杠，这类问题在 Windows 路径被 Markdown 吃掉 有更细的现场。

让 Windows 浏览器打开 WSL 里的 DSH plugin 网页端：三条路

一句话结论：默认靠 WSL2 本机转发就能用 127.0.0.1 打开；转发失效时按「显式绑定 → 用 WSL IP → 手动端口转发」三步退，而不是去改鉴权设置。

1. 路一：本机转发（默认，优先用）。WSL2 会把 WSL 内监听的端口映射到 Windows 本机，直接在 Windows 浏览器访问 http://127.0.0.1:3080。
2. 路二：显式绑定 + 用 WSL IP 访问（转发失效时的退路）：

dsh web --host 0.0.0.0 --port 3080          # WSL 侧
ip addr show eth0 | grep "inet "             # 查 WSL 的 IP
# 然后在 Windows 浏览器访问 http://<WSL的IP>:3080

3. 路三：重建 WSL 网络，让转发重新生效：wsl --shutdown 后重新进入发行版——本机转发会在实例重建后刷新，这是最省事的一招。
4. 还打不开再查防火墙：Windows 防火墙或第三方安全软件会拦非常规端口，临时放行该端口验证一次即可定位。
5. 反过来也要会查：如果 WSL 内 curl 都不通，问题就在 dsh web 本身（端口被占/权限），与转发无关（见 DeepSeek Harness 端口冲突排查）。

WSL 里跑 DSH plugin 的前提与 DSH插件 排查注意事项

一句话结论：插件在 WSL 里与原生 Linux 行为一致，所以失败几乎都集中在「Node 装法（权限）」与「原生模块（编译）」两处；跨系统挂载再叠一层属主差异。

1. 全局安装权限：用 nvm 管理的 Node 装全局包不需要 sudo；如果报 EACCES，改用 nvm 而不是 sudo npm -g（后者会把文件属主写成 root，后续升级更麻烦）。
2. 原生模块编译：sudo apt-get install -y build-essential python3 之后再装；纯 JS 插件不受影响。
3. 文件属主差异：插件在 /mnt/c 下写文件可能失败或属主错乱——把需要频繁写入的目录放到 WSL 原生盘。
4. 环境变量与 shell：DSH_HOME 之类变量要写进 ~/.bashrc，否则新开的 shell 又回到默认数据目录，表现为「插件列表突然空了」。
5. 两侧清理与卸载：WSL 侧的卸载与 容器 / CI 环境里的清理 思路相同——先记录已装清单，再删数据目录。
6. 修复状态如实：本文命令基于官方 CLI 包与 WSL 官方网络文档；dsh web 的具体参数名以你机器上的 --help 输出为准，Windows 侧与 WSL 侧的差异行为可能随版本变化。

来源：apps/cli/README.md、README.zh.md、Microsoft Learn · WSL networking。