DSH Desktop 故障排查与自救：从窗口消失到恢复模式的自救路径-育师

DSH Desktop 故障排查与自救：从窗口消失到恢复模式的自救路径

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

DSH Desktop 是把 DeepSeek Harness 装进原生窗口的开源桌面客户端，插件、会话和 Host 服务都跑在本机。这份故障排查指南按「离能用还有多远」把故障分成 4 个等级：插件不生效、窗口消失、界面转圈闪退、完全起不来，并给出诊断导出与恢复模式入口。照着等级从 L0 往下走，每一步都能自己验证是否解决。

故障分级：先看你现在卡在哪一级

按「离能正常使用的距离」对号入座，找到等级后直接跳到对应小节：

L0 只是行为不对：插件没出现、dsh命令找不到——多半是命令跑错了 profile，或装完没重启。先确认当前激活的 profile。
L1 窗口异常但进程还在：窗口不见了、托盘图标也消失了。先找回托盘里的窗口入口。
L2 界面卡死或闪退：启动后一直转圈、反复闪退，连托盘都进不去。先打开恢复助手。
L3 进程完全起不来：双击图标没反应，或提示端口被占用。先确认端口设置，再走命令行诊断。

L0：插件不出现、dsh 命令找不到：先确认 profile 与终端来源

插件变更需要重启 DSH Desktop 才进入加载组合；dsh命令只存在于 DSH 自带终端，系统终端里永远找不到。两条排查线：

确认插件命令跑在当前激活的 Profile上，不确定就显式加--profile，例如dsh plugin --profile desktop add <plugin>；
切换过 Profile 时注意：旧 Profile 的插件不会复制到新 Profile，需要在新 Profile 下重新安装；
从托盘选打开 DSH 终端（Open DSH Terminal），在欢迎信息里核对版本号与当前 Profile；
执行dsh plugin add、dsh plugin remove或dsh plugin update；
重启 DSH Desktop。

跑完命令你应该看到插件的安装/移除进度与完成提示；在 DSH 终端里退出后再敲dsh，不应再报找不到命令。窗口正常但插件行为不对就停在这一级；窗口本身也异常，升到 L1。

L1：DSH Desktop 窗口消失但进程还在：先找回托盘入口

关闭窗口只是把窗口藏起来，不会退出应用。处理顺序：

看屏幕角落的系统托盘，右键 DSH Desktop 图标选打开 DSH Desktop，窗口应立即回到前台；
托盘图标也消失时，用任务管理器（Windows）或活动监视器（macOS）确认DSH Desktop进程是否还在；
进程在但图标消失：属于界面残留，从托盘菜单选退出彻底结束后重新启动；
进程也不在：应用已彻底退出，直接重新启动即可，不要反复点图标。

验收线：窗口能正常显示并能发起对话；从托盘选退出后，任务管理器里查不到DSH Desktop进程，才算真正结束（只有退出会同时结束应用与 Host 进程）。

L2：启动后界面一直转圈或反复闪退：先打开恢复助手自救

转圈和闪退多由插件配置组合或 Renderer 启动异常引起，不必手动翻日志。应用检测到启动失败后会自动弹出恢复助手；没弹就打开设置里的重启选项菜单，选重启到恢复模式主动进入。进入后按这个顺序自救：

读首屏的启动停止位置，例如「插件配置组合」「确认启动结果」；
优先用回滚Tab：三个检查点槽位里任选一个「可恢复」的，同时恢复当前 Profile、settings.yaml与 DSH 数据目录补丁，成本最低；
回滚不可用再去插件管理Tab，对可疑插件选禁用（保留安装但不加载）或卸载；
仍不行就切诊断Tab 点导出诊断，生成diagnostics-*.zip备查。

任何恢复操作失败时窗口会保持打开并展示错误代码与技术详情，直接截图求助。验收线：重启后能正常进入主界面。启动能过但插件行为不对，回 L0；双击图标完全没反应，升到 L3。

L3：DSH Desktop 进程完全起不来：先查固定端口，再走命令行诊断

最可能是固定端口被占用：你把dsh-desktop.port从默认的0（随机分配）改成了固定值，那个端口被别的程序占住时 Desktop 就起不来。处理顺序：

用任务管理器确认DSH Desktop进程是否存在，排除「只是没起来」的假象；
打开设置文件，确认dsh-desktop.port是否为固定值（如43189）；
释放该端口上的占用程序，或把port改回0，保存后应用会有序重启；
端口不是原因时，跳过启动直接用命令行导证据，在 PowerShell 里执行（默认安装位置，改过目录请替换 EXE 路径）：

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

该命令不会启动 Host、profile、插件或窗口。跑完你应该在终端看到一行诊断 ZIP 的绝对路径；通过 npm 安装过桌面启动器时，直接运行dsh-desktop --export-diagnostics即可。验收线：应用能正常启动，或至少拿到了诊断包可以求助。

证据与求助：诊断包怎么导出、求助前备齐四样东西

什么时候该导出：自救操作失败并出现错误代码、L2/L3 反复出现、或准备提交 issue 之前。诊断导出在后台工作线程进行，设了 60 秒超时与 50 MB 证据上限，不会卡死应用。触发方式三种：

托盘：右键图标选导出诊断信息…（Export Diagnostics…），确认隐私提示后生成diagnostics-*.zip并自动在文件管理器中显示；
恢复模式内：切诊断Tab 点导出诊断；
命令行：--export-diagnostics（见 L3）。

包内包含最近应用日志（按天滚动）、本地 Crashpad.dmp崩溃转储、运行标记active-run.json与system-info.txt（Desktop、Electron、Node 版本及平台架构）。

⚠️隐私与不可逆边界：诊断包中仍可能残留本地路径、工作区 ID、会话 ID 和崩溃时的内存片段，日志中可识别的认证凭据虽会自动脱敏，公开上传前仍须逐项检查。另外恢复出厂设置会把当前 DSH 数据目录整个移入废纸篓或回收站，操作不可一键撤销，执行前务必确认目录路径。

提交求助前备齐四样：

diagnostics-*.zip的完整保存路径；
恢复助手首屏的启动停止位置，以及自救失败时的错误代码与技术详情；
包内system-info.txt记录的版本与平台信息；
出问题前最后做了什么：装了哪个插件、改了哪个配置、是否刚升级过安装包。

DSH Desktop 故障排查与自救：从窗口消失到恢复模式的自救路径