DSH Desktop 故障排查：从崩溃循环到更新失败的三步自救清单-平芜编程栈

DSH Desktop 故障排查：从崩溃循环到更新失败的三步自救清单

【免费下载链接】deepseek-harness-desktop为 DeepSeek Harness (DSH) 插件生态打造的现代化桌面端解决方案。万物皆「插件」，桌面本身也是「插件」。项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop

DSH Desktop 是把 DeepSeek Harness 装进原生窗口的开源桌面客户端，遇到启动失败、插件不生效、更新卡顿、崩溃循环时，下面按处置成本递进的三层清单带你自查、自救，最后再提交有效反馈。如果你只有 30 秒：先确认系统托盘里还有没有 DSH Desktop 进程，找不到的话直接运行dsh-desktop --export-diagnostics导出诊断包提交。

分层排查路径

排查按成本递进：先点两下能解决的，再动手敲命令，最后才进恢复模式。当前层够用就别跳层。

第一层：点几下就能修好

现象：窗口关掉后再也找不到

窗口消失了，但应用多半没挂。这是因为关闭窗口只是隐藏，进程仍在后台运行。

先看系统托盘，右键 DSH Desktop 图标重新打开窗口；
托盘图标也不见时，用任务管理器 / 活动监视器确认 DSH Desktop 进程是否还活着；
想让应用和 Host 进程真正结束，必须在托盘菜单里选择退出。

现象：更新过去好几天都没提示

后台更新检查失败了，而且默认静默。网络错误、非 200 响应或服务端版本不新，应用都不会打扰你。

打开托盘菜单，手动触发Check for Updates…查看明确结果；
已是最新版也会显示"已是最新"，检查失败会提示稍后重试；
只有服务端版本严格高于本地时，才会询问是否下载，不会自动安装。

现象：终端里 dsh 命令找不到

你把命令敲进了系统终端。DSH Desktop 只会在它自己打开的 DSH 终端里注入私有dsh/pnpm/nodeshim，从不修改系统 PATH。

从托盘或 Desktop 设置中选择Open DSH Terminal；
在欢迎信息里核对版本号与当前 profile；
再执行dsh plugin add、dsh plugin remove这类命令。

点几下解决不了，就该动手了。

第二层：需要手动操作

现象：插件装完却迟迟不出现

命令作用在了错误的 profile，或者装完没重启。新的 bundle 必须重启后才会进入 Loader 组合。

确认命令跑在当前激活的 profile 上，不确定就显式加--profile <name>；
重启DSH Desktop，让变更生效；
切换 profile 不会把旧 profile 的插件复制过来，需要在新 profile 下重新安装。

现象：启动直接失败，提示端口被占用

你在设置里写死了固定端口，且被别的程序占了。默认dsh-desktop.port: 0由系统随机分配，不会发生这种冲突。

找到并释放占用该端口的程序；
或把设置改回0、或换一个空闲端口：

dsh-desktop: port: 0

保存后应用会有序重启，无需手动杀进程。

现象：Windows 更新提示"应用仍在运行"或安装卡住

安装器需要先让运行中的桌面端有序退出，并清理active-run.json运行标记。新版安装器会主动请求有序退出；旧版本回退到精确匹配主进程名的停止逻辑，避免误杀安装目录下的无关辅助进程。

当前版本过旧就先升到最新安装器，再重试更新；
升级完成并重启后，应用会询问是否删除安装包释放磁盘空间，也可以保留；
下载或安装失败不会破坏当前版本，托盘可随时重试。

上面都试完还不行，就只能进恢复模式了。别慌，先别急着重装。

第三层：进入恢复模式

现象：持续闪退，连托盘都进不去

反复硬启动只会堆积不完整的运行标记。别硬重启，直接走命令行导出诊断路线。

在 PowerShell 中运行安装后的程序并加上恢复参数（默认安装位置，改过安装目录请替换 EXE 路径）：

& "$env:LOCALAPPDATA\Programs\DSH Desktop\DSH Desktop.exe" --export-diagnostics

该命令不会启动 Host、profile、插件或窗口，完成后在终端输出诊断 ZIP 的绝对路径；
通过 npm 安装过桌面启动器时，直接运行dsh-desktop --export-diagnostics即可。

现象：启动停在某个阶段，界面一直转圈

启动健康确认没通过，多半是插件配置组合或 Renderer 启动异常引起的。

应用检测到启动失败后会自动打开恢复助手，不必手动翻日志；
也可以随时从桌面设置的重启下拉菜单选择重启到恢复模式；
在恢复助手首屏记下进入原因与启动停止位置（如"插件配置组合""启动插件服务""确认启动结果"），后续自救就照着它定位，阶段文案见 recovery-copy.ts，核心逻辑由 startup-recovery-controller.ts 驱动。

现象：改坏了配置回不去，当前 profile 彻底起不来

这正是恢复助手的用武之地，回滚成本最低。

在回滚Tab 选一个"健康启动"检查点（共 3 个轮换槽位，见 profile-checkpoint.ts），同时恢复 Profile、settings.yaml与 DSH home 补丁；
有嫌疑插件时，在插件管理Tab 直接禁用（保留安装但不加载）或卸载，无需进终端；
急需先用起来，就在切换 Profile切到其他支持桌面端的 profile 或新建一个，当前 profile 保留待查；
快速恢复里可进入安全模式，用临时环境启动、不加载原有插件与数据；
重置与数据管理是最重的操作，只在以上都无效时再用。

任何恢复操作失败时窗口会保持打开并展示错误代码与技术详情，对照诊断包继续排查即可。