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 dsh

Windows 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

构建完成后,再重新启动服务。

五、更新后要核对版本与模型接入配置

这类更新故障的排查主要围绕三个问题:

  1. 实际使用的是哪个安装入口?
  2. 故障发生在下载、安装还是启动阶段?
  3. 当前真正运行的版本是什么?

不少看似“更新没有生效”的问题,来自安装入口、故障阶段或实际版本与预期不一致。

对于同时维护 Agent 框架和模型接口的团队,还需要检查模型接入配置。插件与 Profile 层可能保存模型路由设置,版本回退后,请求使用的接口地址也可能随配置变化。

将接口定义集中管理,减少在多个 Profile 补丁中重复配置,有助于检查回退后的请求去向。Treerouter 作为提供统一模型接入的 API 网关,是将部分接入配置与插件生命周期分开管理的一种方式。

六、快速排查清单

  • 确认更新对象是桌面应用、npm 启动器还是 Profile 插件。
  • 列出机器上的全部 dsh 入口,核对实际执行路径。
  • 下载失败时读取完整错误信息。
  • 重装前备份 Harness 主目录和桌面用户数据。
  • 区分桌面更新渠道与 npm 发布标签。
  • 安装候选版本前,检查 dist-tags 和 Node.js 要求。
  • 安装完成后,打开新终端核对实际版本。
  • 更新完成但无法启动时,查看启动诊断报告。
  • 提交日志前,删除密钥和令牌。
  • 从源码运行时,切换版本后显式重新构建。

参考资料