WSL for DSH

在 Windows + WSL2 上运行 DeepSeek Harness（DSH）的两个可复用技能（skill）：

• wsl — 日常在 WSL 里执行 Linux 命令、转换 Windows↔WSL 路径、双向拷贝文件、托管 HTTP 服务器、管理 WSL 内 DSH。
• dsh-wsl-install — 从零在 WSL 中安装并运行 DSH 的完整流程（含所有已踩过的坑、systemd 自启、WSL 空闲关闭修复与自动化脚本）。

两个技能来自一次完整的实战部署（Windows 侧 DSH 3080 + WSL 内 DSH 3081 并存），经验全部实测验证。

当前版本：v1.1.0（2026-09-10）— 合并了 v0.1 发布包的通用化改进与本机 v0.2 运行经验，并把文档同步到实测环境（DSH 0.1.5-rc.1、Ubuntu 26.04 / 发行版 Ubuntu1、systemd 托管、networkingMode=nat）。详见 版本历史。

---

快速开始

方式一：把整个仓库当作 DSH 技能根

DSH 的技能发现规则：扫描 <root>/<name>/SKILL.md 或 <root>/<name>.md。把本仓库 clone 或复制到 $DSH_HOME/skills/（默认 ~/.dsh/skills/）下即可：

# Windows PowerShell
git clone https://github.com/<you>/WSL-for-DSH.git "$env:USERPROFILE\.dsh\skills\repo-WSL-for-DSH"
# 或直接复制两个技能目录
Copy-Item .\skills\* "$env:USERPROFILE\.dsh\skills\" -Recurse

之后 DSH 技能目录会出现 wsl 与 dsh-wsl-install，模型可按需加载。

方式二：只复制单个技能，或直接用发布包

# 只要 wsl
Copy-Item .\skills\wsl "$env:USERPROFILE\.dsh\skills\" -Recurse
# 只要安装流程
Copy-Item .\skills\dsh-wsl-install "$env:USERPROFILE\.dsh\skills\" -Recurse

发布包（解压即得两个技能目录）：dist/Fullset.v1.1.0.zip，由 tools/package.sh 从 skills/ 生成，内容与源码一致、可复现。

---

技能说明

wsl — 日常 WSL 调用

配套脚本：skills/wsl/scripts/wsl.ps1（PowerShell，处理 wsl.exe UTF-16 乱码、发行版选择、路径与拷贝）。

wsl.ps1 -List                            # 列出发行版
wsl.ps1 -Run '<bash 命令>'               # 执行命令（默认 Ubuntu-24.04，不存在则自动选第一个发行版）
wsl.ps1 -Distro <名> -Run '...'          # 指定发行版
wsl.ps1 -PathToWsl 'D:\path'             # Windows → WSL 路径
wsl.ps1 -PathToWin '/mnt/d/path'         # WSL → Windows 路径
wsl.ps1 -ToWsl 'D:\a' -To '/home/x/a'    # Windows → WSL 拷贝（二进制安全）
wsl.ps1 -FromWsl '/home/x/a' -To 'D:\a'  # WSL → Windows 拷贝
wsl.ps1 -Serve 8137 -ServeDir ~/site     # WSL 内托管 HTTP（跨调用存活）
wsl.ps1 -StopServer 8137                 # 停止 HTTP 服务器
wsl.ps1 -DshWeb 3081                     # 启动 WSL 内 dsh web（有 systemd 单元则走 systemctl start）
wsl.ps1 -StopDshWeb                      # 停止 WSL 内 dsh web（优先 systemctl stop）

权限要求：DSH 的 workspace-write 沙箱会拦截 wsl.exe 与 WSLService 的命名管道 IPC（报 E_ACCESSDENIED）。使用本技能需将会话权限切为 danger-full-access。

dsh-wsl-install — 从零安装 DSH 到 WSL

配套脚本：skills/dsh-wsl-install/scripts/install-dsh-wsl.sh（bash，Node 24 + pnpm + DSH + systemd 单元一键安装），以及 Windows 侧一键启动模板 skills/dsh-wsl-install/scripts/bat/。

bash install-dsh-wsl.sh                完整安装（Node + pnpm + dsh + systemd 单元）
bash install-dsh-wsl.sh --no-dsh       只装 Node/pnpm
bash install-dsh-wsl.sh --no-systemd   装软件但不动 systemd
bash install-dsh-wsl.sh --systemd      只安装/刷新 dsh-web.service（开机自启）
bash install-dsh-wsl.sh --verify       端到端验证（headless LLM + 工具调用）
SUDO_PW='<密码>' bash install-dsh-wsl.sh   # sudo 非免密时（密码经 stdin，不落盘）

覆盖内容：前置检查 → NodeSource Node 24 → pnpm（corepack）→ DSH 全局安装（含 --allow-scripts 原生模块）→ ~/.dsh 迁移/初始化（凭据 600）→ web profile 依赖与皮肤包特殊处理 → systemd 托管 + WSL 空闲自动关闭修复 → 端口冲突与冷启动竞态 → Chrome PWA 皮肤跟随（PWA-only 启动策略 + cookie 门控）→ 工作区注册 → 常见错误速查。

---

仓库结构

WSL-for-DSH/
├── README.md
├── LICENSE
├── skills/
│   ├── wsl/                             # 技能：日常 WSL 调用
│   │   ├── SKILL.md
│   │   └── scripts/wsl.ps1
│   └── dsh-wsl-install/                 # 技能：DSH 安装流程
│       ├── SKILL.md
│       └── scripts/
│           ├── install-dsh-wsl.sh       # 一键安装（支持 SUDO_PW / systemd 单元）
│           └── bat/                     # Windows 侧一键启动模板（纯 ASCII + CRLF）
│               ├── wsl-dsh-launch.bat
│               ├── wsl-dsh-stop.bat
│               ├── wsl-dsh-install-pwa.bat
│               ├── wsl-dsh-install-pwa.ps1
│               └── dsh-ensure-cookie.ps1
├── scripts/                             # 独立辅助脚本（不依赖技能加载）
│   ├── windows/                         # PWA 检测辅助（启动/停止统一由 skills/.../bat 提供）
│   └── wsl/{dsh-web.service,wsl-dsh-stop.sh,wsl-dsh-manage.sh}
├── configs/wslconfig.example            # Windows 侧 .wslconfig 模板（含空闲关闭修复）
├── tools/package.sh                     # 打包 dist/Fullset.<version>.zip
└── dist/                                # 打包产物

---

版本历史

版本	日期	内容
v1.1.0	2026-09-10	合并两条线：① 并入 v0.1 发布包的通用化改进（wsl.ps1 发行版自动探测、安装器 SUDO_PW、冷启动竞态规则、WSL_E_DISTRO_NOT_FOUND、.credentials.yaml 生成、随包 bat 模板、PWA 差异法脚本）；② 保留 main 的运行经验（systemd 自启、WSL 空闲关闭修复、停服脚本委托）；③ 文档同步实测环境（0.1.5-rc.1、Ubuntu 26.04 / Ubuntu1、/usr/local/bin/node、--no-open、journal、networkingMode=nat）；④ 新增 tools/package.sh 可复现打包；⑤ 技能 frontmatter 增加 metadata.version。
v0.2（仅 main）	2026-08-19	补 systemd 自启（dsh-web.service）、WSL 空闲自动关闭修复、wsl-dsh-stop.sh 委托。未发布为 Release。
v0.1（Release 资产）	2026-08-16/17	首次发布：两个技能 + bat 模板的通用化版本（发行版名占位化）。
v0.1（tag v0.1/v1.0.0）	2026-08-16	首次提交的本机版技能（v1.0.0 tag 与 v0.1 指向同一初始 commit，且无对应 Release）。

历史遗留：仓库里曾有一份 Fullset v0.1.zip，它与 Release 上的同名资产内容并不一致（少了 bat 模板）；v1.1.0 起改为由 tools/package.sh 从 skills/ 生成 dist/Fullset.v1.1.0.zip，单一来源、可复现。

---

打包

bash tools/package.sh              # 生成 dist/Fullset.v1.1.0.zip（版本取自 skills/*/SKILL.md 的 metadata.version）
bash tools/package.sh --check      # 只校验（frontmatter / ASCII+CRLF / bash -n），不打包

---

发布到 GitHub（供 DeepSeek 官方发现）

官方 deepseek-harness README 明确要求：

Add the dsh-plugin topic to your plugin repository for discoverability.

因此发布本仓库时，请务必：

1. 仓库名：GitHub 仓库名不含空格，用 WSL-for-DSH（本目录的显示名是「WSL for DSH」）。
2. 添加 topic：在 GitHub 仓库页面 → 右侧 About → 齿轮图标 → Topics 中填入 dsh-plugin（官方可发现性要求）。
3. 打版本 tag：

git tag -a v1.1.0 -m "WSL for DSH skills v1.1.0"
git push origin main --tags

4. 发布 Release：上传 dist/Fullset.v1.1.0.zip 作为资产（与 tag 内容一致）。
5. 保持技能格式合法：skills/<name>/SKILL.md 的 frontmatter 必须含 name（kebab-case）与 description（可选 whenToUse / metadata / disable-model-invocation / user-invocable）；当前两个技能均符合。

---

关键经验（都写进了 SKILL.md）

• WSL 需要 danger-full-access：沙箱拦截 wsl.exe↔WSLService IPC。
• WSL 空闲自动关闭必须禁用：instanceIdleTimeout=-1 + vmIdleTimeout=-1（两层都要设，-1 才是禁用），否则发行版 15 秒后被回收，表现为「WSL 内无法对话」。
• systemd 托管 dsh web：dsh-web.service + /usr/bin/env node ... --no-open（nvm 的 node 不在 /usr/bin）；停止必须 systemctl stop，kill 会被 Restart=on-failure 拉起。
• 冷启动竞态：VM 停机时 wsl -e bash -lc "... & disown" 客户端立即退出会把刚启动的 VM 一起回收——必须让客户端轮询到服务就绪再退出。
• 写 .bat 的硬规则：纯 ASCII + CRLF；if 块内 echo 不含 ()；用 if not "%X%"==""；复杂 PowerShell 拆成 .ps1；wsl -d 参数不加引号。
• Chrome PWA 皮肤：--app=<url> 不读 meta theme-color（标题栏灰），真 PWA（--app-id）才跟随皮肤；无静默安装 flag；首次访问需用 journal 里的 token URL 换 30 天 cookie。
• 凭据权限：~/.dsh/.credentials.yaml 必须 chmod 600。
• 皮肤包特殊处理：maid-atelier@0.1.1 不在 npm registry；headless profile 也要皮肤包（装入共享 profiles/node_modules）。

---

许可

MIT License — 见 LICENSE。