SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-11-21

DeepSeek Harness 安装与版本错误修复

最新 DeepSeek Harness 仍是预发布版。固定确切的 dsh 版本,清理 npx 缓存,并确认实际运行的 npm;Node.js 还需至少 24.9.0。

DeepSeek Harness 安装的实际含义

DeepSeek Harness 的安装只有一条命令:npx @deepseek-ai/dsh web。没有安装程序,也没有需要配置的服务。大多数问题根本不是安装问题,而是版本解析问题:@deepseek-ai/dsh 的 npx 今天决定运行哪个构建版本,以及您的 Node.js 版本是否能够运行它。启动后,默认绑定地址是 localhost;--host 和 --port 会覆盖监听设置,输出的地址在配置后使用 --public-url。默认绑定,以及为什么 Web UI 只能在 127.0.0.1:3080 上响应,与本文介绍的问题相互独立。

下面的内容由两个事实决定。第一,截至 27 October 2026,发布到 npm 的每个 @deepseek-ai/dsh 版本都是预发布版本。其中大多数是候选发布版(-rc.N),自 30 August 2026 起也有 alpha 构建版(-alpha.N)。latest 标签指向一个候选发布版。截至 6 November 2026,该版本是 0.2.2-rc.1。第二,项目 README 说明该 harness 处于 developer preview 阶段,迭代速度很快,并且会发生破坏兼容性的变更。上周有效的标志,本周可能已经被移除。在基于它构建任何内容之前,请固定版本。

先说明几个术语。dsh 是 DeepSeek Harness 命令行工具。Node.js 是它所需的 JavaScript 运行时。npx 是随 npm(node package manager)发布的软件包运行器,会按需获取软件包,而不是将其永久安装。如果该句中的 harness 一词含义不明确,请参阅agent harness 是包裹在模型外部的程序:它负责维护循环、工具、权限和会话状态。因此,未由您选择的版本号也可能改变 agent 的行为。

dsh 需要哪个 Node.js 版本?

2026 年 10 月 10 日,当仓库版本为 0.2.1-alpha.2 时,其根目录 package.json 声明了 "engines": {"node": "^22.19.0 || >=24.0.0"}。这已不再是当前要求。2026 年 10 月 27 日,在仓库版本为 0.2.1-rc.3 时,根目录 package.json 声明了 "engines": {"node": ">=24.9.0"},CLI 自身的源文件 package.json 现在也声明了相同要求。2026 年 10 月 15 日的项目决策记录指出,Node 22 安装必须升级;Node 24.0 也不够,因为入口点依赖 import.meta.main,而 24.0 不具备该功能。因此要求 Node 24.9.0 或更高版本。Node 20 和 Node 22 均不符合要求,任何低于 24.9.0 的 Node 24 版本也不符合要求。2026 年 10 月 27 日检查时,0.2.1-rc.2 的发布标签、其指向的构建 latest 以及 0.2.1-rc.3 仍使用旧版本范围,因此新的最低版本是在这些版本之后才确定的。无论如何都应按 24.9.0 进行规划,因为这是项目当前声明的版本范围。

先检查现有环境。

node -v
npm -v

以下情况容易令人困惑。截至 2026 年 10 月 27 日,已发布的 @deepseek-ai/dsh 包在其截至 0.2.1-rc.4 的全部 38 个版本中,仍没有自己的 engines 字段。monorepo 根目录声明了该字段,但根目录文件不会发布到 npm。CLI 的源文件 package.json 在 2026 年 10 月 15 日的提交中新增了该字段,但 2026 年 10 月 27 日检查的已发布构建都没有包含它。因此,这些构建没有向 npm 提供 dsh 专用的 Node 版本要求供其检查。截至 2026 年 11 月 6 日,已发布的 0.2.2-rc.1 包声明了 "engines": {"node": ">=24.9.0"}。除非设置 engine-strict,否则 npm 会将 engines 视为提示信息,因此默认设置下最多只会出现警告。在不受支持的 Node 上,安装过程看起来可能成功,但在稍后加载的代码使用运行时不具备的语法或 API 时才会失败。没有一个稳定且统一的错误字符串可供搜索,因为最先失败的代码行取决于哪个模块先加载。应阅读 node -v,不要只看崩溃信息。

如果 Node 版本过旧,nvm(Node 版本管理器)是在 VPS 上侵入性最小的修复方式,因为它会安装在您的主目录下,不会修改系统 Node。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v 现在应输出以 v24. 开头的版本。如果 shell 仍报告旧版本,请运行 which node。如果路径不在 ~/.nvm 下,通常有两个原因。其一,nvm shell 函数未加载;请打开新的登录 shell,然后重试。其二,shell 配置文件中的某一行在加载 nvm 的行之后修改了 PATH,并将另一个 Node 放在前面;请将该行移到 nvm 相关行之前。2026 年 10 月 10 日,Node 24 是当前 active LTS(长期支持)版本线,并于 2026 年 10 月 20 日进入维护阶段。截至 2026 年 10 月 29 日,其最新版本为 24.22.2,远高于 24.9.0 的最低要求。>=24.9.0 范围也允许使用 Node 26;Node 26 于 2026 年 10 月 28 日以 26.13.0 进入 active LTS。两者都满足最低版本要求,并且都捆绑了包含下文所述 range-cache 修复的 npm 版本。官方 Node 26 Linux 二进制文件还要求 libatomic,您的发行版可能需要单独安装该库。

为什么 npx 每天运行的版本都不同?

npx @deepseek-ai/dsh web不指定版本。除非当前目录中的项目已经安装了@deepseek-ai/dsh,此时 npx 会运行该副本;否则,npx 会从注册表获取latest标签当前指向的版本。该标签会频繁移动。0.1.0-rc.8于 19 August 2026 发布,比0.1.0-rc.7晚两天。到 10 October 2026,latest指向0.2.0-rc.2;到 27 October 2026,则指向0.2.1-rc.2。每次标签移动后,笔记中的命令都会开始运行不同的代码。命令不会提示您,也不会在执行前显示变更日志。

您可以从命令行检查每个会变化的部分。

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags显示latest当前指向的位置。在 10 October 2026,latest和next都指向0.2.0-rc.2;另一个标签alpha则指向前一天发布的0.2.1-alpha.2。在 27 October 2026,latest指向0.2.1-rc.2,next指向前一天发布的0.2.1-rc.4,alpha指向0.2.1-alpha.5。截至 6 November 2026,latest指向0.2.2-rc.1。在 4 November 2026,next指向0.2.1-rc.5,alpha指向0.2.2-alpha.3。latest标签仍选择预发布版本。versions列表更值得关注,因为其中存在缺失版本。在 10 October 2026,该列表包含 31 个版本,从0.0.1-rc.1到0.2.1-alpha.2;到 27 October 2026,已包含 38 个版本,且全部仍是预发布版本。0.0.1 系列从-rc.2跳到-rc.5,0.1.0 系列从-rc.3跳到-rc.6,alpha 构建从0.1.2-alpha.2和0.1.3-alpha.2开始,并且完全没有0.1.4。已发布列表中缺少一些编号,alpha 构建和候选发布版本还交错出现在同一个列表中。在部署脚本中猜测下一个-rc.N会失败,因此应读取列表,而不是按编号递增推算。

为什么 npx 会一直运行旧版本?

这是相反的情况。两种情况都可能发生,具体取决于包规格、本地安装状态以及实际运行的 npm 版本。

npx 使用独立的包目录。该目录与 tarball 缓存分开,位于 npm 缓存中的 _npx 目录。打印路径并检查该目录。

npm config get cache
ls "$(npm config get cache)/_npx"

npm 10.9.3 在项目安装之外使用裸包名时,已经会检查 registry。npm 11.2.0 修改了版本范围的缓存新鲜度检查。当规格是裸包名,且当前项目中尚未安装该包时,npx 会使用 preferOnline: true 获取清单;只有解析出的 tarball 与 registry 返回的内容匹配时,才会复用 _npx 中的缓存副本。裸包名仍会匹配当前项目已安装的版本,且不会检查 registry。对于版本范围,npm 10.9.3 接受缓存中匹配的版本;npm 11.2.0 及更高版本会检查该范围是否解析到了更新的版本。

实际行为取决于您运行的 npm。除非您使用 npm install -g npm 单独升级过 npm,否则运行的是 Node 版本自带的 npm:

  • Node 20.20.2 自带 npm 10.8.2。
  • Node 22.19.0 自带 npm 10.9.3。
  • Node 22.23.4 是截至 27 October 2026 的最新 22 版本,自带 npm 10.9.9。
  • Node 24.9.0 是 harness 当前支持的最低版本,自带 npm 11.6.0。
  • Node 24.19.0 自带 npm 11.17.0。
  • Node 24.22.2 是截至 29 October 2026 的最新 24 版本,自带 npm 11.19.1。
  • Node 26.13.0 是截至 29 October 2026 的最新 26 版本,自带 npm 11.20.0。

因此,整个 Node 22 系列自带的 npm 都早于 11.2.0。harness 支持 Node 22 到 2026 年 10 月中旬,现已不再支持。但在此之前运行过 dsh 的服务器可能仍在使用该版本。Node 22.19.0 自带的 npm 10.9.3 已经会在项目安装之外,针对 registry 重新检查裸 npx @deepseek-ai/dsh web,因此,单独存在旧的 _npx 条目并不能解释为什么仍会使用旧的候选版本。harness 目前接受的每个 Node 版本,从 24.9.0 开始,都自带 npm 11.6.0 或更高版本,其中也包含版本范围缓存修复。项目中的安装仍可能优先于其他版本。请让工具报告其实际使用的版本:

npx @deepseek-ai/dsh --version

清理 npx 缓存

在 npm 11.2.0 及更高版本中,有专用的子命令。

npm cache npx ls
npm cache npx rm --force

如果不使用 --force,npm 会拒绝清除全部内容,并输出 Please use --force to remove entire npx cache。如果要按键删除单个条目,而不是清除全部条目,请先使用 npm cache npx ls。

npm 10 不提供这些子命令,因此请手动删除该目录。

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force 在这里不起作用。它会清除 _cacache(即 tarball 存储),但会保留 _npx。这正是 npm 后来增加 npm cache npx 子命令的原因。清除 _npx 不会造成永久影响:其中保存的是已下载的包,而您的 harness 状态单独存储在 $DSH_HOME 下,包括 profiles/<name>、sessions、storages 和 .credentials.yaml,不会受到影响。

如何固定精确的候选发布版本?

写出完整的版本字符串,包括 -rc.N 部分。

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

本页示例使用 0.1.0-rc.7。请替换为您实际测试过的构建版本。截至 27 October 2026,latest 标签指向 0.2.1-rc.2。

--yes 可在非交互模式下接受 npx 的软件包安装确认。

精确版本会固定 dsh 软件包,但不能保证离线启动。npx 根据您输入的规范字符串确定缓存目录的键,并可以复用其中已安装的精确版本。不过,如果本地不存在匹配的安装版本,前面的本地目录检查会先使用 preferOnline: true 获取清单,然后再检查 _npx。在本地项目中安装匹配的精确版本,可以避免查询该清单。在项目外运行会安装 dsh 的裸名称时,也会触发清单查询,包括 npm 10.9.3。

全局安装使用相同的固定方式,并提供一个简短命令。

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

找不到 @deepseek-ai/dsh@^0.1.0 的匹配版本

截至 27 October 2026,直接使用插入符或波浪号范围时,该软件包匹配失败。npm install -g @deepseek-ai/dsh@^0.1.0 返回错误代码 ETARGET,并输出以下行:No matching version found for @deepseek-ai/dsh@^0.1.0. 注册表正常。这是 semver 规则:除非范围中的某个比较器指定了与候选发布版本具有相同主版本、次版本和补丁版本号的预发布版本,否则版本范围不会匹配预发布版本。截至 27 October 2026,该软件包发布的每个构建版本都是预发布版本,分别为 -rc.N 或 -alpha.N;而 ^0.1.0 未指定任何预发布版本,因此没有匹配结果。请写出精确版本。

该规则具有双重作用。普通范围不会自动切换到新的候选发布版本,但指定预发布版本的范围可能会切换。^0.1.0-rc.7 表示 >=0.1.0-rc.7 <0.2.0-0,因此它接受 0.1.0-rc.8,也会接受最终的 0.1.0;而 0.1.1-rc.1 不会被接受,因为版本号不同。这是一种介于精确版本和动态标签之间的半固定状态。即使您不做任何更改,它也可能改变实际运行的版本。如果您只想运行已测试的构建版本,而不接受其他版本,请写出精确版本。

应使用 npx,还是全局安装 dsh?

首次了解 dsh 时使用 npx,因为该软件包会保存在缓存目录中,而您现在已经知道如何清理该目录。对于重启后仍必须正常工作的内容,例如您在 VPS 上持续运行的编码代理,请使用固定版本的全局安装。

如果同一台服务器上两种方式都使用过,它们可能会产生不同结果,因此请进行比较。

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh在成功全局安装后仍找不到任何内容,几乎总是因为 npm 的全局 bin 目录未包含在您的 PATH 中。运行 npm prefix -g 打印根目录,全局二进制文件位于该目录下的 bin 文件夹中。

还有一个安全问题。npx 每当解析到新内容时,都会从注册表获取并执行代码。对服务器而言,这是真实的暴露面,而不是理论风险。固定版本是解决方案的一部分。其余措施请参阅npm 供应链攻击如何入侵服务器。

开发者预览对可复现性的含义

0.1.0-rc.6于 2026 年 8 月 13 日发布,0.1.0-rc.7于 2026 年 8 月 17 日发布。两者相隔 4 天。此后发布速度并未放缓:2026 年 8 月 19 日至 10 月 9 日期间又发布了 24 个版本,其中包括 9 月 28 日发布的 0.2.0-rc.1 和次日发布的 0.2.0-rc.2;2026 年 10 月 14 日至 26 日期间又发布了 7 个版本,最新为 0.2.1-rc.4。按此速度,一个月前编写的说明可能描述一个已经不存在的命令行,其中也包括本页面。记录每条版本信息时都标注日期,包括您自己的笔记。

两个习惯可以让预览版更易于维护。在每条命令和每个脚本中固定确切版本,这样重建服务器时会选择相同的 dsh 版本。仅此还不能复现其依赖项:已发布的 0.2.2-rc.1 软件包使用 js-yaml: ^4.3.2 和 commander: ^15.0.0 之类的版本范围,并且未附带 npm shrinkwrap。要重复安装依赖项,请将 dsh 保存在本地项目中,提交 package-lock.json,并使用 npm ci 重建。然后读取固定版本构建的帮助输出,不要读取任意指南中的内容。

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

可复现性的另一半是配置文件。dsh --profile <name> 会加载存储在 $DSH_HOME/profiles/<name> 中的配置文件,web 和 headless 配置文件会在首次使用时根据随附模板自动创建。配置文件补丁可以保存模型和端点设置,但保存的 API 密钥位于 $DSH_HOME/.credentials.yaml 中,而设置只保留凭据引用。因此,固定版本和可用配置是需要分别正确处理的两件事。用户级补丁和命令行补丁可以覆盖配置文件设置。内置软件包从当前运行的 dsh 安装中解析,这意味着更改固定版本也会改变这些软件包。外部插件的行为不同。它们位于配置文件目录中,dsh plugin --profile <name> add <package> 会将其参数转发给 pnpm 进行安装。因此,pnpm 必须位于您的 PATH 中;如果不存在,dsh 会明确报告这一点。您添加的每个插件都会以代理使用的相同权限运行,因此在安装前检查插件可以访问哪些内容。配置文件自身的 package.json 会声明这些插件;请保留其 pnpm-lock.yaml,并使用 pnpm install --frozen-lockfile 同样复现它们的依赖版本。

如果您曾经在服务器上将 Python 工具置于隔离环境中,就会熟悉这种拆分:工具本身和添加到工具中的内容分别在不同位置固定。工具开始运行后,下一个问题通常是网络连接,而不是版本。这时可以参考从远程 VPS 访问 dsh Web UI,以及在 VPS 上安装 DeepSeek Harness中的详细操作流程。

实际会看到的参数错误

这些错误来自 CLI 自身的解析器,每条消息都会指出确切的问题。不同构建版本中的措辞基本保持不变,但并不完全一致。因此,下面的消息已根据 0.2.0-rc.2 在 6 October 2026 的表现进行核对。

error: --profile <name> is required

您在未指定子命令和 profile 的情况下运行了 npx @deepseek-ai/dsh。不带参数的命令会启动一个 profile,因此必须提供名称。dsh web 可以在不使用 --profile 的情况下运行,因为解析器会将第一个不带选项的单词读取为 profile 名称,并为您启动随附的 web profile。

error: --patch needs a path

您使用 --patch 时没有在其后提供任何内容。该选项可以重复使用,每次出现都必须接收一个文件路径。

error: --dump-config and --dump-default-config are mutually exclusive

只能选择其中一个。在 0.2.0-rc.2 中,2026 年 10 月 6 日指向的构建版本 latest 会列出第三个选项,消息显示为 error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive,因为用于输出 profile 条目和补丁的 JSON Schema 的 --dump-config-schema 已加入另外两个选项。--dump-default-config 会输出随附的 bundle 层,并且不接受任何 --patch。--dump-config 会输出某个 profile 的组合配置。这三个选项都不会启动 harness,但收集 schema 时会导入插件模块,并可能调用 getter 和延迟构建器;只能检查受信任的插件,并在脚本中设置外部超时。

error: plugin needs pnpm arguments to forward (e.g. add <package>)

您运行 dsh plugin --profile <name> 时没有提供要转发的内容。缺少 profile 时,该子命令会先初始化 profile,然后将命令行的其余部分交给 pnpm,因此必须提供类似 add @scope/dsh-plugin-example 的参数。

FAQ

DeepSeek Harness 需要哪个 Node.js 版本?

需要 Node.js 24.9.0 或更高版本。2026 年 10 月 27 日查看时,仓库版本为 0.2.1-rc.3,其根目录中的 package.json 声明了 >=24.9.0。2026 年 10 月 10 日时,该声明为 ^22.19.0 || >=24.0.0;但一份日期为 2026 年 10 月 15 日的项目决策说明移除了 Node 22,并将最低版本提高到 24.0 以上。Node 20 和 Node 22 无法运行,低于 24.9.0 的 Node 24 版本也无法运行。截至 2026 年 10 月 27 日,没有任何已发布的 npm 构建版本拥有自己的 engines 字段,因此 npm 无法根据 dsh 自身的 Node 要求发出警告或阻止安装,不受支持的运行时会在之后的步骤中失败。2026 年 11 月 6 日检查的已发布 0.2.2-rc.1 包现在在 engines.node 中声明了 >=24.9.0;npm 默认会发出警告,启用 engine-strict 后会拒绝不兼容的运行时。请先检查 node -v。所有达到最低版本要求的 Node 版本都捆绑了 npm 11 或更高版本,其中包含 npm 11.2.0 引入的 npx 范围缓存修复。

如何强制 npx 使用最新的 dsh,而不是缓存中的版本?

npm 10.9.3 和当前版本的 npm 已会为未指定版本的包名重新检查注册表;但如果当前目录是一个已安装 dsh 的项目,npx 会运行该项目中的本地副本。使用 npx @deepseek-ai/dsh@latest --version 显式请求注册表的 latest 标签。npm 11.2.0 更改了版本范围的新鲜度检查,但未更改未指定版本包名的处理方式。在 npm 11.2.0 及更高版本中,使用 npm cache npx rm --force 清除 npx 缓存;在 npm 10 中,使用 rm -rf "$(npm config get cache)/_npx" 删除该目录。然后使用 npx @deepseek-ai/dsh --version 确认。请注意,npm cache clean --force 清除的是另一个目录,无法解决此问题。

为什么安装 @deepseek-ai/dsh@^0.1.0 会失败?

截至 2026 年 10 月 27 日,npm 返回了错误代码 ETARGET,并显示行 No matching version found for @deepseek-ai/dsh@^0.1.0.。该检查时所有已发布的构建版本都是预发布版本,例如 0.2.0-rc.2 或 0.2.1-alpha.2;semver 范围不会匹配预发布版本,除非该范围本身指定了具有相同 major、minor 和 patch 数字的预发布版本。请安装完整的版本字符串,包括后缀。运行 npm view @deepseek-ai/dsh versions --json 查看现有哪些版本,因为版本序列存在缺口。

应该全局安装 dsh,还是通过 npx 运行?

npx 适合首次试用,因为该包会保留在缓存目录中;该 harness 还会创建持久化的配置文件状态。对于必须持续运行的场景,固定版本的全局安装(例如 npm install -g @deepseek-ai/dsh@0.1.0-rc.7)更合适,因为版本只有在您主动更改时才会变化。如果全局安装后找不到 dsh 命令,说明 npm 的全局 bin 目录不在您的 PATH 中;npm prefix -g 会输出该目录所在的根路径。

DeepSeek Harness 是否已经足够稳定,可以基于它构建项目?

还没有,这是该项目自己的描述。README 声明该项目处于开发者预览阶段,正在快速迭代,并且会发生破坏兼容性的更改。0.1.0-rc.6 和 0.1.0-rc.7 两个候选版本于 2026 年 8 月相隔 4 天发布;0.2.0-rc.1 和 0.2.0-rc.2 于 2026 年 9 月相隔 1 天发布;0.2.1-rc.1 和 0.2.1-rc.2 于 2026 年 10 月同一天发布。支持的 Node 范围也在 2026 年 10 月发生了变化。请固定一个确切版本,并从该固定版本的构建中读取 --help,不要依赖任何指南中的内容。为您自己的记录注明日期,以便判断它们已经过时了多久。

这篇文章对您有帮助吗?