DSH Desktop 故障自救完整指南：从窗口消失到恢复模式，3 级操作一次搞定

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

DSH Desktop 是把 DeepSeek Harness 插件生态装进原生窗口的开源桌面客户端。遇到窗口消失、插件不生效、端口冲突或更新卡住时，按这份 DSH Desktop 自救指南走三步：先自己诊断，再自己修复，修不好就带着证据去求助。

先诊断再动手：四步自查

别急着翻日志，按顺序过一遍这四个问题，先确定故障落在哪一级：

1. 进程还在吗？看系统托盘图标是否还在；图标消失时，用任务管理器（Windows）或活动监视器（macOS）搜DSH Desktop进程。进程活着但窗口没了，是窗口隐藏问题，去第一级处理。
2. 应用能启动吗？正常双击启动，观察是否报端口冲突、是否一直卡住。直接起不来，多为固定端口被占或安装残留，去第二级处理。
3. 界面有没有反应？进入主界面后，试着开一次对话、看一下插件列表。界面能操作但行为不对——插件不出现、终端里dsh命令找不到——属于操作层失误，回第一级核对。
4. 是不是配置或更新问题？上面三项都正常却仍不对劲，最大嫌疑是更新流程：没有更新提示、安装卡住、升级后行为异常，去第二级的更新与回滚小块。

按严重度修复：从最轻点击到最重操作

原则：成本从低到高逐级尝试。上一级能解决就不要往下走，避免误操作。

第一级：操作层自救（点几下就解决）

窗口不见了，应用真的挂了吗？没有。关闭窗口只是隐藏，进程还活着。

1. 右键托盘图标，重新打开窗口。
2. 托盘图标也消失时，用任务管理器 / 活动监视器确认DSH Desktop进程是否还在，再决定重启还是排查。
3. 只有从托盘菜单选择退出，应用和 Host 进程才会真正结束。

插件装完不出现？最可能：命令作用在了错误的 profile，或者装完没有重启。

1. 确认操作发生在当前激活的 profile上，不确定就显式加--profile <name>。
2. 重启 DSH Desktop——插件变更后必须重启，新 bundle 才会进入 Loader 组合。
3. 切换 profile 不会带过来旧 profile 的插件，需要在新 profile 下重新安装。

系统终端里dsh命令找不到？Desktop 只会在它自己打开的 DSH 终端里注入私有dsh/pnpm/nodeshim，不会修改系统 PATH。

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

第二级：状态层自救（涉及重置）

固定端口被占用导致启动失败，3 步解决？默认设置dsh-desktop.port: 0让系统随机分配端口，本不会冲突；只有你在设置里写死固定端口（通常是为依赖localStorage的界面插件）才会被占。

1. 释放该端口上占用的程序。
2. 或把设置改回0、或换一个空闲端口。
3. 修改后应用会有序重启，无需手动处理。

更新一直没有提示？后台检查失败时默认静默，不打扰你。

1. 用托盘菜单的Check for Updates…手动检查。
2. 已是最新版也会明确显示结果，检查失败会提示稍后重试。
3. 只有服务端版本严格高于本地版本时，才会询问是否下载。

Windows 更新时提示"应用仍在运行"或安装卡住？安装器必须先让运行中的桌面端有序退出并清理active-run.json运行标记，才能覆盖文件。

1. 新版安装器会主动请求有序退出；旧版本回退到精确匹配主进程名的停止逻辑，不会误杀安装目录下的无关辅助进程。
2. 下载或安装失败不会破坏当前版本，托盘可随时重试。
3. 升级完成并重启后，应用会询问是否删除安装包释放磁盘空间。

改完配置起不来了，怎么回滚？最可能：最近一次配置变更破坏了启动组合。

1. 从设置的重启下拉菜单选择重启到恢复模式，进入恢复助手（启动失败被自动检测到时，它也会自己打开）。
2. 首屏会先告诉你进入原因与启动停止位置（如"插件配置组合""启动插件服务"，阶段文案见 recovery-copy.ts），先记下这个位置。
3. 切到回滚 Tab，从三个"健康启动 Checkpoint"槽位任选其一，重启后 Profile、settings.yaml与 DSH 数据目录补丁会一起回滚，是成本最低的修复路径。
4. 回滚不可用或无效时，再考虑在恢复助手里禁用 / 卸载可疑插件，或切换到其他可用的 profile。

第三级：带证据求助 📦

应用还能进托盘时，如何导出诊断包？两种途径任选：

1. 右键托盘图标 →导出诊断信息…，确认隐私提示后生成diagnostics-*.zip，并自动在文件管理器中显示它。
2. 已处在恢复模式时，切到诊断 Tab 点导出诊断，同样保存为本地 ZIP。
3. 导出跑在后台工作线程里，设有 60 秒超时与 50 MB 证据上限（见 diagnostic-export.ts），不会卡死界面，永远不会自动上传。

应用闪退、托盘都进不去时，怎么导出？走命令行，在 PowerShell 中运行安装后的程序并加恢复参数（改过安装目录请替换 EXE 路径）：

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

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

包内有什么？四项证据一次备齐：

1. 最近的应用日志（按天滚动，规则见 log-files.ts）
2. 本地 Crashpad.dmp崩溃转储
3. 运行标记active-run.json
4. system-info.txt：Desktop、Electron、Node 版本及平台与架构

日志对可识别的认证凭据会自动脱敏（见 mask-secrets.ts）。

⚠️隐私提醒：诊断包中仍可能残留本地路径、工作区 ID、会话 ID 和崩溃时的内存片段。公开上传前逐项检查，不适合公开的 dump 请通过可信渠道单独提供。

让问题一次被答清楚：提交前备齐 4 样东西

求助前把这四项写进问题描述，能省掉来回追问：

1. 诊断包路径：diagnostics-*.zip的完整保存位置。
2. 启动停止位置：恢复助手首屏显示的失败阶段（如"插件配置组合""桌面界面启动"），以及自救操作失败时的错误代码与技术详情。
3. 系统与版本信息：包内system-info.txt记录的 Desktop、Electron、Node 版本及平台与架构。
4. 操作复现步骤：出问题前最后做了什么——装了哪个插件、改了哪个配置、是否刚升级过安装包。

延伸阅读

• 用户指南（含完整排查章节）：docs/user-guide.md
• 常见问题（平台、环境、数据边界）：docs/faq.md
• Windows 安装器升级验证证据：docs/evidence/windows-installer-upgrade-2026-08-25.md

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