DeepSeek Harness 更新失败,可能发生在桌面应用、npm 启动器或 Profile 插件三个不同环节。本文按照安装入口和故障阶段,梳理下载失败、安装后版本未变化、更新后无法启动等问题的处理方法。
一、先确认你更新的是哪个组件
截至原文撰写时,DeepSeek Harness 仍处于开发者预览阶段。桌面应用、npm 启动器和插件系统分别通过不同渠道更新,更新其中一个组件,并不意味着另外两个组件也会同步升级。
11 月 13 日发布的 v0.2.2-rc.3 修复了 Windows 平台的两个问题:应用内更新失败,以及更新后无法自动重启。该版本在 GitHub 上标记为预发布版本,npm 的 latest 标签并未指向它。
因此,开始排查前,需要先确认当前使用的安装入口。
| 安装入口 | 版本检查方式 | 需要注意的地方 |
|---|---|---|
| 桌面应用 | 在应用菜单检查更新,并通过“关于”页面确认版本 | 应用内置的 dsh 运行时随桌面应用更新 |
| npm 启动器 | 指定版本运行 npx,或检查 npm 全局安装 | 使用 dsh --version 查看实际执行版本 |
| Profile 插件 | 插件页面或 dsh plugin 命令 | 插件更新管理对应 Profile 的依赖,不会升级 Harness 核心 |
如果使用桌面应用,在菜单中的“关于 DeepSeek Harness”查看版本。如果通过终端启动,则执行:
dsh --version桌面应用也可以通过“管理 dsh 命令”功能注册终端入口。由这种方式注册的命令,其运行时版本跟随桌面应用。
如果机器上存在多个 dsh,应先列出它们的位置。
macOS 和 Linux:
type -a dshWindows PowerShell:
Get-Command dsh -All确认终端实际调用的路径后,再决定更新桌面应用还是 npm 全局包。
另外,下面的命令更新的是 web Profile 插件的依赖:
dsh plugin --profile web update它不会更新 Harness 核心。按照原文对 rc.3 的核验,官方帮助中没有 dsh update 自更新命令,也没有 dsh doctor 诊断命令。
更新应沿着原来的安装渠道进行,不能用插件更新代替主程序升级。
二、桌面端更新卡住,按所处阶段处理
下载失败时,先查看具体错误
从应用菜单中的“检查更新”,或左下角的更新入口,查看当前状态。
按照 rc.3 桌面端文档,下载失败后会保留重试提示,需要用户再次操作。自动检查更新本身不会自动下载安装包。
处理前,先读错误信息:
- 如果提示磁盘空间不足,检查对应磁盘的剩余容量。
- 如果提示写入权限不足,检查报错路径的权限。
- 如果提示文件被占用,确认相关进程是否仍在运行。
- 如果提示配置异常,根据错误详情定位配置文件,修正 JSON 格式或具体字段,再选择“重新加载配置”。
不要因为某个配置字段出错,就直接删除整个用户目录。这样可能丢失会话和设置,而且未必能解决下载问题。
更新渠道也需要区分。在“设置 → 通用 → 更新渠道”中,生产渠道标记为 stable,开发渠道标记为 nightly。
桌面更新渠道由发布方独立配置,stable 渠道也可能提供候选版本。因此,不能仅凭版本号中的 rc 后缀判断所属渠道,也不能把桌面端的 stable、nightly 与 npm 的 latest、next 混为一谈。
下载完成后,需要确认安装
关闭窗口不等于安装更新,普通退出操作也不代表更新已经应用。
先等待当前任务结束,再通过应用内的更新入口确认安装。如果此前隐藏了更新提示,重新打开窗口,查看是否仍有待确认的安装操作。
安装过程中按提示等待,避免反复启动应用。
如果安装程序提示应用仍在运行,需要彻底退出:
- Windows:在系统托盘中选择“退出 DeepSeek Harness”。
- macOS:从应用菜单退出程序。
- 终端:结束仍在使用桌面版运行时的命令。
关闭主窗口可能只是隐藏界面,后台进程仍然存在,也可能继续占用安装所需的文件。
内置更新器反复失败时,使用官方安装包
如果旧版本的内置更新器持续失败,可以从官方 DeepSeek Harness 下载入口获取新的安装包。
下载时确认操作系统、处理器架构和目标版本。安装前,彻底退出旧程序。
在 Windows 上,安装程序会更新其检测到的现有安装位置。安装完成后,再到“关于”页面核对版本,不要仅根据“安装成功”的提示判断更新结果。
覆盖更新与主动卸载的数据处理范围不同:
| 操作 | 数据处理方式 |
|---|---|
| Windows 覆盖更新 | 保留用户数据 |
| 主动卸载 | 清理 Electron 用户数据目录 |
| Harness 主目录 | 按独立的数据保留规则处理 |
重新安装前,备份当前使用的 Harness 主目录和桌面应用用户数据。不要把“卸载重装”作为第一步。
如果安装程序明确报告旧目录恢复失败,应保留错误报告中列出的备份目录,联系官方支持后再处理重装。官方文档将这种情况单独列出。
可以按下面的状态表判断下一步:
| 当前状态 | 建议操作 |
|---|---|
| 下载失败 | 重新打开重试入口,按具体错误处理 |
| 下载完成,等待安装 | 结束当前任务,确认安装并重启 |
| 更新反复失败 | 获取官方安装包,彻底退出旧程序后更新 |
| 安装已经结束 | 在“关于”页面核对版本;无法启动时进入启动诊断 |
三、npm 更新成功,版本却没有变化
latest 是一个发布标签,不代表版本号最高的候选版本。
按照原文记录的 2026 年 11 月 16 日 npm 官方仓库快照:
latest指向0.2.2-rc.1。next指向0.2.2-rc.3。
在这种情况下,反复安装 latest,得到的仍然是 rc.1。这并不一定是缓存故障,而是标签本身就指向该版本。
安装前,先查询发布标签、目标包的 Node.js 要求,以及本机 Node.js 版本:
npm view @deepseek-ai/dsh dist-tags --json
npm view @deepseek-ai/dsh@0.2.2-rc.3 engines --json
node --version如果配置了 npm 镜像,可以在查询命令后附加官方仓库地址,对照结果,而不必永久修改配置:
npm view @deepseek-ai/dsh dist-tags --json --registry=https://registry.npmjs.org/标签会变化,应以执行查询时返回的结果为准。
遇到 EBADENGINE,检查 Node.js 版本
原文所述 rc.3 npm 包要求:
Node.js >= 24.9.0如果出现 EBADENGINE 错误,先检查系统 Node.js 版本是否符合要求。
桌面应用自带运行时,因此不能把 npm 包的 Node.js 要求直接套用到所有桌面用户身上。给系统安装 Node.js,并不是修复桌面版更新问题的通用方法。
指定版本验证运行结果
如果需要验证指定候选版本,可以运行:
npx @deepseek-ai/dsh@0.2.2-rc.3 --version
npx @deepseek-ai/dsh@0.2.2-rc.3 web如果此前采用的是 npm 全局安装,则使用:
npm install -g @deepseek-ai/dsh@0.2.2-rc.3
dsh --version安装提示成功,但显示的版本仍然没有变化时,重新检查命令解析路径,并打开一个新的终端再次验证。
当前 Shell 可能缓存命令路径,导致终端继续执行原先找到的程序。机器上同时存在桌面版入口和 npm 全局入口时,更要核对实际调用位置。
遇到 EACCES,处理安装权限
全局安装出现 EACCES,通常指向文件系统权限问题。
按照 npm 官方指导,可以使用 Node.js 版本管理器管理安装环境和权限范围。
清理 Harness 配置不能解决全局安装目录的权限问题,还可能造成设置丢失。应根据错误中列出的目录处理权限,而不是删除应用配置。
四、更新已经完成,但应用无法启动
如果程序文件已经替换完成,随后出现插件或 Host 启动失败,应转入启动诊断。
这个阶段反复下载相同安装包,通常不能解决问题。
桌面端先获取诊断报告
如果桌面应用弹出原生崩溃恢复对话框,先选择“获取诊断报告”。
如果对话框指出问题来自第三方插件,可以使用“禁用第三方插件、备份 Profile 补丁并重启”选项。
按照原文描述,该操作会处理第三方组件并备份 Profile 用户补丁,同时保留已安装包和此前的备份,不改动主目录级别的补丁。它不等于清空全部配置。
命令行以实际输出的报告路径为准
如果 CLI 输出:
Full diagnostics:应打开它后面实际列出的文件路径。
必需插件激活失败时,诊断报告默认保存在:
~/.dsh/logs/如果设置了自定义 DSH_HOME,报告位置也会随之变化。
提交日志前,删除 API Key、Token 等敏感信息。
源码运行需要重新构建
从源码运行的用户还需要检查构建状态。
按照原文引用的官方文档,执行:
pnpm dsh web不会自动重新构建项目。
切换到目标版本源码后,先保留本地修改、停止旧服务,再执行:
pnpm install
pnpm run build构建完成后,再重新启动服务。
五、更新后要核对版本与模型接入配置
这类更新故障的排查主要围绕三个问题:
- 实际使用的是哪个安装入口?
- 故障发生在下载、安装还是启动阶段?
- 当前真正运行的版本是什么?
不少看似“更新没有生效”的问题,来自安装入口、故障阶段或实际版本与预期不一致。
对于同时维护 Agent 框架和模型接口的团队,还需要检查模型接入配置。插件与 Profile 层可能保存模型路由设置,版本回退后,请求使用的接口地址也可能随配置变化。
将接口定义集中管理,减少在多个 Profile 补丁中重复配置,有助于检查回退后的请求去向。Treerouter 作为提供统一模型接入的 API 网关,是将部分接入配置与插件生命周期分开管理的一种方式。
六、快速排查清单
- 确认更新对象是桌面应用、npm 启动器还是 Profile 插件。
- 列出机器上的全部
dsh入口,核对实际执行路径。 - 下载失败时读取完整错误信息。
- 重装前备份 Harness 主目录和桌面用户数据。
- 区分桌面更新渠道与 npm 发布标签。
- 安装候选版本前,检查
dist-tags和 Node.js 要求。 - 安装完成后,打开新终端核对实际版本。
- 更新完成但无法启动时,查看启动诊断报告。
- 提交日志前,删除密钥和令牌。
- 从源码运行时,切换版本后显式重新构建。
参考资料
- DeepSeek Harness 桌面端故障恢复与诊断文档(rc.3)
- Treerouter 模型目录与接口说明






