Skip to content

WSL.md

Latest commit

 

History

History
75 lines (48 loc) · 6.15 KB

WSL.md

File metadata and controls

75 lines (48 loc) · 6.15 KB
Raw

DSH Tray Launcher WSL2 版

这个包是运行在 Windows 通知区域的 WPF 程序，DSH Web 服务实际运行在 WSL2 中。它与 Windows 原生版项目相互独立，源码位于 tray-wsl/，内嵌 Shell 后端位于 wsl/。

支持与已验证版本

项目 本次范围
托盘 v1.0.6，Windows 10/11 x64，WSL2；无需另装 .NET Runtime
真实环境 Windows + Ubuntu WSL2，Node.js 22.22.1
DSH 已验证 @deepseek-ai/dsh@0.1.1-rc.2、0.1.5-rc.2
新启动协议 --profile web 与新版本地 token 认证入口

上述两个 DSH 版本完成真实启动验证；其他版本及发行版未逐一验收，不承诺未来启动协议不变。Node.js 需符合所安装 DSH 的版本要求。第三方插件仅检查整套服务能否启动，不保证每项插件功能兼容。

前置条件

  • Windows 10/11 x64
  • 已启用 WSL2，并安装至少一个 Linux 发行版
  • WSL 中可执行 dsh、node、npm、curl、ps、setsid、ss
  • WSL 中已经安装并配置 @deepseek-ai/dsh
  • Windows 可以访问 http://127.0.0.1:3080

程序会自动检查所有普通 WSL 发行版，并识别 system、nvm、fnm、asdf 和 Volta 等安装方式下的绝对路径。只发现一个 DSH 时直接使用；发现多个时要求用户选择，并可记住选择。发行版名称、Linux 用户名和安装路径都不得写死。

服务管理

程序通过内嵌的 dsh-ctl.sh 管理服务。它只接受自己记录的令牌、PID、启动时间和进程组，不会按关键字杀掉全部 dsh web 进程，也不会调用 wsl --shutdown。如果 3080 端口被未受管程序占用，启动器会报告冲突而不终止该程序。

WSL 状态默认保存在 ${XDG_STATE_HOME:-$HOME/.local/state}/dsh-tray-launcher。双击托盘图标打开当前受管服务的地址。兼容新版 DSH 的 /?token=... 访问认证；令牌不写入 Windows 托盘日志，不需要手工复制。

更新

托盘的“检测更新”二级菜单包含两项：

  • 检测并更新 WSL 内的 DSH
  • 更新托盘启动器自身

DSH 更新流程为：获取 npm 元数据、比较版本、询问用户、停止受管服务及插件、保存仅核心启动方式、安装指定版本、校验版本、启动核心并验证 Windows 认证访问、恢复更新前运行或停止状态。全过程显示阶段、进度和详细输出。失败时会尝试安装旧版本并恢复更新前的运行状态。用户可以在稳定版与包含 rc、beta 等预发布版的通道之间切换。

启动器更新会下载 GitHub Release 中配对的 WSL ZIP 和 SHA-256 文件，校验归档路径、后端标记及程序版本，然后通过独立帮助程序备份、替换和重新启动。关闭进度窗口只取消仍可安全取消的阶段，不会中断正在进行的恢复操作。

同一版本号下替换过 Release 文件时，版本比较不会触发自更新；这种情况必须手动重新下载发布包。

v1.0.2 起，WSL 版可在托盘内分别检查 DSH 和启动器更新，并可选择包含预发布版本。更新前会要求确认；DSH 更新失败时会尝试恢复旧版本和原服务状态。

v1.0.5 启动方式

  • 仅核心：使用新的隔离 DSH home 和官方 web 模板，不加载原 web profile 或全局 cordis.patch.yml。保留官方 Web 界面与核心组件，不代表关闭 DSH 本身必需的官方插件。
  • 附加第三方插件：使用原 web profile 和全局补丁；插件文件不被删除、卸载或覆盖。
  • 更新成功后，第一次实际运行时显示一次选择窗口；关闭窗口等同继续核心模式。更新前已停止的服务会先临时启动验证，再停止，选择窗口留到下一次启动。
  • 以后通过右键“启动方式”切换。运行中切换会重启；已停止时只保存选择。第三方插件启动失败会尝试恢复核心，并显示结果。
  • 两种模式共享原有会话、缓存、附件、存储目录，以及 settings.yaml 和 .credentials.yaml 的读写路径。核心模式不载入自定义 agent preset 和配置补丁；依赖第三方插件的历史会话功能可能暂不可用。
  • 核心模式生成的 profile 只供启动器使用；更新第三方插件请在原环境执行 dsh plugin --profile web ...，不要在隔离核心环境里安装。新版核心每次按安装版本重新生成。
  • 启动器先显示托盘，再唤醒 WSL 并重试发现。Linux 就绪等待上限为 90 秒，Windows 转发健康检查会重试；不需要预先手动打开 WSL，也不调用 wsl --shutdown。

诊断与故障排查

  • 设置：%LOCALAPPDATA%\DSH Tray Launcher\settings.json
  • 托盘日志：%LOCALAPPDATA%\DSH Tray Launcher\dsh-tray.log
  • 未处理异常：%LOCALAPPDATA%\DSH Tray Launcher\crash.log
  • WSL 服务日志：${XDG_STATE_HOME:-$HOME/.local/state}/dsh-tray-launcher/dsh-web.log（可能含 DSH 本地访问令牌，分享前请遮盖）
  • 非交互自检：dsh-tray.exe --selftest

如果 WSL 未准备好，程序会在日志中记录具体依赖检查失败原因，并保持现有端口服务不变。

出现 Embedded shell resources must use LF line endings 表示嵌入的 .sh 文件含有 CRLF。不要在发布时临时绕过检查；应保留 .gitattributes 的 LF 规则，并用 git ls-files --eol -- '*.sh' 确认工作树为 w/lf 后重新构建。

如果点击更新后程序退出或没有重新启动，请先检查 crash.log、dsh-tray.log 和 Windows 事件查看器，再记录点击前后的完整步骤。不要仅依赖单元测试判断更新可用，发布前必须在交互桌面实际走完窗口显示、确认、进度、完成或失败提示。

问题反馈请提交到 GitHub Issues，并注明 WSL 发行版、wsl --list --verbose 输出、发布包名称和日志片段。不要提交个人目录、令牌或账号信息。

v1.0.6：WSL 校时与进程识别

进程身份使用 boot ID 和内核启动计数，不再依赖会随 WSL 校时变化的显示日期。旧记录仍进行严格校验；若旧版已经遗失管理记录，不会仅凭端口或进程名称接管、杀死进程，需要先核实归属后恢复。