DSH Desktop故障排查手册：8个高频问题、诊断导出与恢复模式自救指南
项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness-desktop DSH Desktop 是面向 Windows 和 macOS 的开源 DeepSeek Harness 桌面客户端，把官方 Harness 的 Web UI、Host 服务与插件系统装进原生桌面应用。本文是一份 DSH Desktop 故障排查手册：先建立"正常运行"的基准，再逐个拆解 8 个最高频的问题场景，最后详解诊断导出与恢复模式两套自救工具，帮助新手快速定位并解决问题。
排查前先确认：正常的 DSH Desktop 长什么样
排查的前提是知道"正常"的样子。启动成功后，你应该看到：
- 左侧边栏显示工作区与历史会话，底部有"插件市场"和"设置"入口
- 主区域可以正常与模型对话，底部状态栏显示 LLM 延迟与 token 统计
- 关闭窗口后应用不会退出，而是驻留在系统托盘
只要实际表现偏离以上三点，就可以对照下面 8 个高频问题逐一排查。
8 个高频问题快速自查清单
1. 窗口消失了，应用是不是挂了？
先检查系统托盘。DSH Desktop 关闭窗口通常只是隐藏窗口，不是退出；右键托盘图标即可重新打开，选择"退出"才会真正结束应用。若托盘图标也消失了，再用 任务管理器/活动监视器 确认 DSH Desktop 进程是否还在。
2. 插件安装后没有出现？
三个常见原因，按顺序检查：
- 命令作用在了错误的 profile：插件命令默认作用于当前激活的 profile，必要时显式加
--profile <name>； - 没有重启应用：插件变更后必须重启 DSH Desktop，新的 bundle 才会进入 Loader 组合；
- 装到了别的 profile：切换 profile 不会把旧 profile 的插件自动复制过来。
3. 终端里 dsh 命令找不到？
Desktop 只在它自己打开的终端里注入了私有 dsh/pnpm/node shim，并不会修改系统 PATH。请从托盘或设置中重新选择 Open DSH Terminal，在欢迎信息中确认版本号与当前 profile 后，再执行插件命令。
4. 固定端口被占用导致启动失败？
Desktop 默认随机分配本地 Web 端口（dsh-desktop.port: 0）以避免冲突。但如果你在设置中指定了固定端口（例如供依赖 localStorage 的界面插件使用），该端口一旦被其他程序占用，Desktop 将无法启动。解决办法：释放该端口，或把设置改回 0 或换一个空闲端口，修改后应用会有序重启。
5. 更新一直没有提示？
后台检查失败时默认静默，不会打扰你。使用托盘菜单的 Check for Updates… 手动检查：即使已是最新版也会明确显示结果，检查失败会提示稍后重试。只有服务端版本严格高于本地版本时，才会询问是否下载。
6. Windows 更新时提示"应用仍在运行"或安装卡住？
新版安装器会先请求运行中的桌面端有序退出并清理 active-run.json 运行标记，再覆盖文件；旧版本则回退到精确匹配主进程名的停止逻辑，避免把安装目录下的无关辅助进程误判为主程序。升级完成并重启后，应用会询问是否删除安装包以释放磁盘空间。下载和安装失败不会破坏当前版本，托盘可随时重试。
7. 应用持续闪退，连托盘都进不去？
直接走"命令行导出诊断"路线：在 PowerShell 中运行安装后的程序并加上恢复参数（默认安装位置如下，若改过安装目录请替换 EXE 路径）：
& "$env:LOCALAPPDATA\Programs\DSH Desktop\DSH Desktop.exe" --export-diagnostics
该命令不会启动 Host、profile、插件或窗口，完成后会在终端输出诊断 ZIP 的绝对路径。通过 npm 安装过桌面启动器时，也可以直接运行 dsh-desktop --export-diagnostics。
8. 启动后界面一直转圈或加载失败？
这类"启动健康确认"阶段的失败通常由插件配置组合或 Renderer 启动异常引起。此时不必手动翻日志：应用检测到启动失败后会自动打开恢复助手（见下节），或者你在桌面设置的重启下拉菜单中主动选择 重启到恢复模式。
一键导出诊断包：诊断信息怎么生成
DSH Desktop 内置的诊断导出会在后台工作线程中打包证据，不阻塞界面，并设有 60 秒超时与 50 MB 证据上限（见 diagnostic-export.ts），确保导出不会卡死应用。
两种触发方式：
- 应用能进入托盘：右键托盘图标 → 导出诊断信息…，确认隐私提示后，应用生成
diagnostics-*.zip并自动在文件管理器中显示它； - 恢复模式内：在"诊断" Tab 中点击 导出诊断，同样保存为本地 ZIP，永远不会自动上传。
诊断包内容：最近的应用日志、本地 Crashpad .dmp 崩溃转储、当前运行标记和 system-info.txt（记录 Desktop、Electron、Node、平台与架构版本）。日志会对可识别的认证凭据自动脱敏（见 mask-secrets.ts），按天滚动的日志文件规则定义在 log-files.ts。
⚠️ 隐私提醒：诊断包中仍可能包含本地路径、工作区 ID、会话 ID 和崩溃时的内存片段。公开上传前务必检查；不适合公开的 dump 应通过可信渠道提供。
恢复模式自救：4 个 Tab 分别能做什么
当启动失败或你主动从重启菜单进入时，DSH Desktop 恢复助手会先展示进入原因与失败阶段（如"插件配置组合""插件 Host 启动""启动健康状态确认"，阶段文案见 recovery-copy.ts），然后提供 4 个 Tab 完成自救，核心逻辑由 startup-recovery-controller.ts 驱动：
| Tab | 适用场景 | 能做什么 |
|---|---|---|
| 🔧 插件管理 | 某个插件把应用"带崩"了 | 列出当前 Profile 的插件并直接卸载直接依赖项，无需进入终端 |
| 🔄 回滚 | 最近改坏了配置 | 从三个"健康启动 Checkpoint"槽位选一个，同时恢复 Profile、settings.yaml 与 DSH home 补丁 |
| 📂 切换 Profile | 当前 Profile 无法启动 | 切换到其他支持桌面端的 Profile，或新建一个 |
| 📦 诊断 | 需要提交证据 | 一键导出诊断包并"在文件夹中显示" |
自救流程建议：先看失败阶段 → 优先尝试回滚（成本最低）→ 回滚不可用再卸载可疑插件 → 仍不行就导出诊断包求助。恢复操作失败时窗口会保持打开并展示错误代码与技术详情，方便对照诊断包排查。
延伸阅读
- 用户指南（含完整排查章节）：user-guide.md
- 常见问题（平台、环境、数据边界）：faq.md
- 诊断导出实现：diagnostic-export.ts
- 诊断辅助模块：diagnostics.ts
- 恢复窗口文案与操作：recovery-copy.ts
- Windows 安装器升级验证证据：windows-installer-upgrade-2026-08-25.md
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/gitblog_00779/article/details/156353000
