DSH Desktop 故障排查指南：4 步从窗口消失救回应用-开发者社区

DSH Desktop 故障排查指南：4 步从窗口消失救回应用

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

DSH Desktop 是把 DeepSeek Harness 装进原生窗口的开源桌面客户端。这份排障指南覆盖四件最常发生的事：窗口消失、插件不生效、固定端口被占用、更新卡住。跟着"先定位卡点、再动手修、修不好就带证据求助"的路子走，大多数情况 5~15 分钟内能恢复正常；实在起不来的应用，也有一套兜底的恢复通道。

1. 窗口不见了，先确认应用还活着

关窗口只是藏起来，不是退出

点右上角关闭按钮后，窗口其实只是隐藏到系统托盘，进程还在跑。先找托盘图标，右键选Show把窗口叫回来。

托盘图标也不见了怎么办

打开任务管理器（macOS 用活动监视器），搜DSH Desktop；
进程还在：它多半是托盘渲染出了岔子，可以走托盘菜单的Quit干净退出再重启；
进程没了：那它确实退出了，直接双击重新启动，问题转到下一节看。

想彻底结束应用和 Host 进程，只在托盘菜单里选Quit。

2. 应用活着但行为不对

插件装完不出现

确认命令跑在当前激活的 profile上；拿不准就显式加--profile <name>；
装完、改完插件后重启DSH Desktop——新 bundle 要重启才会进入 Loader 组合。这一步救活大多数"插件不生效"的情况；
记住：切换 profile 不会把旧 profile 的插件带过来，到新 profile 里得重新装一遍。

dsh 命令在系统终端里找不到

这是正常的。Desktop 只会在它自己打开的 DSH 终端里注入私有的dsh/pnpm/nodeshim，不会碰你系统的 PATH。

从托盘或设置里选Open DSH Terminal；
看欢迎信息，核对版本号和当前 profile 对不对；
在这个终端里敲dsh plugin add、dsh plugin remove这类命令，都会生效。

固定端口被占用导致起不来

默认配置是dsh-desktop.port: 0，由系统随机分配本地 Web 端口，天然不冲突。只有你为了依赖localStorage的界面插件把端口写死，才会撞上占用。

先查出谁占着这个端口（做完会列出占用进程，记下 PID 后结束它）：

# Windows netstat -ano | findstr :<端口号> # macOS / Linux lsof -i :<端口号>

或者干脆把设置改回0、或换一个空闲端口，保存后应用会有序重启，端口就腾出来了。

更新一直没动静

后台检查更新失败时默认静默，不会打扰你。

托盘菜单里点Check for Updates…手动触发；
已是最新版会明确显示结果，失败会提示稍后重试；
只有服务端版本严格高于本地时，才会问你下不下载。

Windows 更新提示"应用仍在运行"

安装器需要先把正在跑的桌面端有序退出、清理active-run.json运行标记，然后才覆盖文件。新版安装器会主动请求退出；更老的版本回退到按主进程名精确停止，避免误杀安装目录下的辅助进程。升级完成后应用会问你要不要删安装包腾空间；下载或安装失败不会破坏当前版本，托盘里随时可以重试。

3. 应用起不来：导出诊断包与进入恢复模式

持续闪退时，先用命令行导出诊断

别反复硬启动。下面这条命令直接跑安装后的程序、不启动 Host、不加载插件、不开窗口，跑完终端会打印诊断 ZIP 的绝对路径——这就是"应用进不了托盘时也能拿到证据"的通道：

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

通过 npm 装过桌面启动器的话，直接dsh-desktop --export-diagnostics效果一样。

启动后一直转圈

应用检测到启动失败会自动打开恢复助手；你也可以从桌面设置的重启下拉菜单主动选重启到恢复模式。恢复助手首屏会告诉你失败发生在哪个阶段（如"插件配置组合""确认启动结果"），先看这个再动手。

恢复模式里有什么

页签	能做什么
插件管理	列出当前 Profile 直接装的插件，可禁用（保留安装不加载）或卸载直接依赖项，不用进终端
回滚	从三个健康启动 Checkpoint 任选一个，同时恢复 Profile、`settings.yaml`与 DSH home 补丁
切换 Profile	换到别的桌面端 Profile，或新建一个；原来的保留待查
诊断	一键导出诊断包，还能在文件管理器里显示它

另有"快速恢复"（含安全模式：临时环境启动，不加载原插件与数据）和"重置与数据管理"（改数据目录、恢复出厂），动大手术，建议排在后面。

动手顺序：看失败阶段 → 优先回滚（成本最低）→ 回滚不可用就卸载可疑插件 → 还不行就导出诊断包出去求助。任何恢复操作失败，窗口会保持打开并展示错误代码和技术详情，方便对照排查。

诊断包里都有什么

导出跑在后台线程，不阻塞界面，有 60 秒超时和 50 MB 上限（实现见 dsh-plugin-desktop/src/diagnostic-export.ts）。包内是：按天滚动的应用日志、本地 Crashpad.dmp崩溃转储、active-run.json运行标记、system-info.txt（Desktop / Electron / Node 版本与平台架构）。日志会对凭据自动脱敏；恢复模式内的导出永远不会自动上传。