DeepSeek Harness 安装报错与版本冲突解决方法

DeepSeek Harness 安装的本质

DeepSeek Harness 的安装仅需一条命令：npx @deepseek-ai/dsh web。它没有安装程序，也无需配置服务。用户遇到的大多数问题并非源于安装过程，而是版本解析问题：即 npx 当天决定运行 @deepseek-ai/dsh 的哪个构建版本，以及你的 Node.js 版本是否支持该构建。程序启动后，其打印的地址绑定在 localhost 上，而 Web UI 仅在 127.0.0.1:3080 响应的原因 是一个独立于本页面所述的问题。

以下内容基于两个事实。首先，目前发布到 npm 的所有 @deepseek-ai/dsh 版本均为预发布版本。其中大多数是发布候选版（-rc.N），自 2026 年 8 月 30 日起，还出现了 alpha 构建版本（-alpha.N）。latest 标签指向的是一个发布候选版。截至 2026 年 10 月 6 日，该版本为 0.2.0-rc.2，发布于 2026 年 9 月 29 日。其次，项目 README 指出该 harness 处于开发者预览阶段，迭代迅速，且会包含破坏兼容性的变更。上周有效的标志位本周可能就会被移除。在基于它构建任何内容之前，请锁定版本。

首先说明一些术语。dsh 是 DeepSeek Harness 的命令行工具。Node.js 是它所需的 JavaScript 运行时。npx 是随 npm（node package manager）一同发布的包运行器，它按需获取包，而非将其永久安装。如果这句话中 “harness” 一词让你感到陌生，代理 harness 是包裹在模型周围的程序，它负责维护循环、工具、权限和会话状态，这就是为什么你未主动选择的版本号可能会改变代理行为的原因。

dsh 需要哪个版本的 Node.js？

仓库根目录下的 package.json 声明了 "engines": {"node": "^22.19.0 || >=24.0.0"}，此信息读取于 2026 年 10 月 6 日，当时仓库版本为 0.2.1-alpha.1。因此，需要 Node 22.19.0 或更高版本的 22 系列，或者 Node 24 及以上版本。Node 20 不受支持。

在进行任何操作前，请先检查当前版本。

node -v
npm -v

以下内容往往会让人感到意外。已发布的 @deepseek-ai/dsh 包本身不包含 engines 字段。只有 monorepo 根目录声明了该字段，而该根文件不会发布到 npm。因此，npm 没有可检查的对象，它不会打印 EBADENGINE 警告，也不会拒绝安装。在 Node 20 上，安装过程看起来一切正常，但故障会在稍后出现，即加载的代码触及了运行时环境不支持的语法或 API 时。由于哪个模块先加载决定了哪一行代码先报错，因此没有单一的稳定错误字符串可供搜索。请阅读 node -v，而不是去分析崩溃信息。

如果你的 Node 版本过旧，nvm (node version manager) 是在 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 仍然报告旧版本，说明 nvm shell 函数未加载，请打开一个新的登录 shell 并重试。截至 2026 年 10 月 6 日，Node 24 是当前的 LTS（长期支持）版本系列，该日期最新的发布版本为 24.21.0。出于下文所述的第二个原因，它是更推荐的目标版本。

为什么 npx 每天运行的版本都不一样？

npx @deepseek-ai/dsh web 没有指定版本，因此 npx 会向注册表查询 latest 标签当前指向的内容。该标签会频繁变动。0.1.0-rc.8 发布于 2026 年 8 月 19 日，即 0.1.0-rc.7 发布两天后；到 2026 年 10 月 6 日，latest 已经更新至 0.2.0-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 当前的指向。在 2026 年 10 月 6 日，latest 和 next 都指向 0.2.0-rc.2，而第三个标签 alpha 则指向 0.2.1-alpha.1。这些标签都不是可供切换的稳定渠道。versions 列表更值得关注，因为它存在版本缺失。在 2026 年 10 月 6 日，该列表包含 30 个版本，从 0.0.1-rc.1 到 0.2.1-alpha.1 不等。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"

多年来，对于裸包名，npx 总是复用此处找到的任何内容，而不再向 registry 发起请求。npm 11.2.0 改变了这一行为。当规范为裸包名或版本范围时，npx 现在会获取清单，仅在解析后的 tarball 与 registry 最新返回的结果匹配时，才会复用缓存副本。

你所获得的行为取决于你的 Node 版本，因为 Node 捆绑了特定的 npm：

• Node 20.20.2 捆绑了 npm 10.8.2。
• Node 22.19.0 捆绑了 npm 10.9.3。
• Node 22.23.3（截至 2026 年 10 月 6 日最新的 22 版本）捆绑了 npm 10.9.9。
• Node 24.19.0 捆绑了 npm 11.17.0。
• Node 24.21.0（截至 2026 年 10 月 6 日最新的 24 版本）捆绑了 npm 11.19.0。

因此，本测试套件官方支持的整个 Node 22 系列，其内置的 npm 版本均低于 11.2.0。在 Node 22 上，执行裸的 npx @deepseek-ai/dsh web 命令将持续运行几周前缓存的发布候选版本。而在 Node 24 上，同样的命令每次运行都会重新解析。同一个命令，两种行为，且均无任何提示。请查询工具版本以确认：

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 也不会造成任何永久性损失：它仅存放已下载的包，而你的测试套件状态位于 $DSH_HOME/profiles/<name> 下，不会受到影响。

如何锁定特定的发布候选版本？

请指定完整的版本字符串，包括 -rc.N 部分。

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

本页示例使用 0.1.0-rc.7。请替换为您实际测试过的构建版本。在 2026 年 10 月 6 日，latest 标签指向 0.2.0-rc.2。

在脚本中使用 --yes 非常重要，否则 npx 在安装未见过的包之前会打印提示信息，并等待永远不会到来的用户确认。

指定确切版本也是最快的执行路径。npx 会根据您输入的版本规范字符串来索引缓存目录；对于确切版本，它会将其与已安装的包 ID 进行比对，无需访问注册表即可直接运行。在 npm 11.2.0 及更高版本中，仅使用包名会导致每次启动时都进行一次清单获取。

全局安装也可以采用同样的锁定方式，并为您提供简短的命令。

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

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

插入符号 (caret) 或波浪号 (tilde) 范围无法匹配此包。npm install -g @deepseek-ai/dsh@^0.1.0 会返回错误代码 ETARGET 以及行 No matching version found for @deepseek-ai/dsh@^0.1.0.。注册表运行正常。这是 semver 的规则：除非版本范围本身明确指定了预发布版本，否则版本范围不会匹配预发布版本。此包的每个已发布构建版本均为预发布版本，即 -rc.N 或 -alpha.N，因此 ^0.1.0 无法匹配任何内容。请写入确切的版本号。

该规则有一个有用的副作用。由于版本范围不会自动漂移到新的发布候选版本，因此不存在需要考虑的“半锁定”状态。您要么处于确切版本，要么处于动态标签。

我应该使用 npx 还是全局安装 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 月 3 日期间又发布了 23 个版本，其中包括 9 月 28 日的 0.2.0-rc.1 和次日的 0.2.0-rc.2。按照这种速度，一个月前编写的指南可能描述的是已不存在的命令行，本页面也不例外。请为你记录的每一个版本声明标注日期，包括你自己的笔记。

养成两个习惯可以应对预览版的不确定性。在每个命令和脚本中固定确切的版本号，确保重建服务器时能得到相同的环境。此外，应阅读已固定版本的帮助输出，而不是参考任何指南。

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 配置文件会在首次使用时根据内置模板自动生成。该目录也是 harness 读取 其 API 密钥、模型和端点设置 的位置，因此固定版本和有效的配置是两码事。内置包会根据当前运行的 dsh 安装版本进行解析，这意味着更改固定版本也会同步更改这些包。树外插件的行为则不同。它们位于配置文件目录中，dsh plugin --profile <name> add <package> 会将参数转发给 pnpm 进行安装。因此，pnpm 必须存在于你的 PATH 中，如果缺失，dsh 会明确提示。你添加的每个插件都拥有与代理相同的权限，因此 在安装插件前检查其访问范围 非常重要。配置文件的 package.json 用于固定这些插件，因此完整的版本锁定需要覆盖两个文件，而非一个。

如果你曾 在服务器上将 Python 工具保持在隔离环境中，这种拆分方式会让你感到熟悉：工具本身和你添加的组件在不同的位置进行版本锁定。一旦 harness 启动，接下来的问题通常是网络而非版本，此时可以参考 访问远程 VPS 上的 dsh Web UI 以及 在 VPS 上安装 DeepSeek Harness 中的详细操作指南。

您实际会遇到的参数错误

这些错误来自 CLI 自带的解析器，每一条都指出了具体问题。虽然措辞在不同版本间基本保持稳定，但并非完全一致，因此下文中的消息已于 2026 年 10 月 6 日针对 0.2.0-rc.2 进行了核对。

error: --profile <name> is required

您在运行 npx @deepseek-ai/dsh 时未提供子命令，也未指定 profile。直接运行该命令会启动一个 profile，因此必须提供名称。dsh web 无需 --profile 即可运行，因为解析器会将第一个单词视为 profile 名称，从而为您启动内置的 web profile。

error: --patch needs a path

--patch 后面没有跟任何内容。该标志可重复使用，且每次出现时都需要指定一个文件路径。

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

请二选一。在 2026 年 10 月 6 日所指的 0.2.0-rc.2 版本 latest 中，该消息提到了第三个标志，内容为 error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive，这是因为 --dump-config-schema（用于打印 profile 条目和补丁的 JSON Schema）已加入到前两者中。--dump-default-config 会打印内置的 bundle 层，且不接受任何 --patch。--dump-config 会打印 profile 的组合配置。所有这些命令在打印后都会退出，而不会启动 harness，因此这是查看新发布候选版本（release candidate）变更的最安全方式。

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

dsh plugin --profile <name> 没有接收到需要转发的内容。该子命令会在 profile 缺失时对其进行初始化，然后将命令行剩余部分传递给 pnpm，因此它需要类似 add @scope/dsh-plugin-example 的参数。

FAQ

DeepSeek Harness 需要哪个版本的 Node.js？

该仓库在其根目录的 ^22.19.0 || >=24.0.0 中声明了 package.json，读取时间为 2026 年 10 月 6 日，当时仓库版本为 0.2.1-alpha.1。因此需要 Node 22.19.0 或 22 系列的更高版本，或者 Node 24 及更新版本。Node 20 无法运行。已发布的 npm 包没有自己的 engines 字段，因此 npm 不会发出警告也不会阻止安装，故障会在运行时出现。请首先检查 node -v。无论如何，Node 24 是更好的选择，因为它捆绑了 npm 11，修复了 npx 版本重用的问题。

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

在 npm 11.2.0 及更高版本中，npx @deepseek-ai/dsh 每次运行时都会重新检查注册表中的裸包名。在所有 Node 22 版本捆绑的 npm 10 中，它不会这样做。在 npm 11 上使用 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 会失败？

npm 返回错误代码 ETARGET，并显示 No matching version found for @deepseek-ai/dsh@^0.1.0.。每个已发布的构建都是预发布版本，例如 0.2.0-rc.2 或 0.2.1-alpha.1，而 semver 范围除非明确指定，否则不会匹配预发布版本。请安装包含后缀的精确版本字符串。运行 npm view @deepseek-ai/dsh versions --json 查看存在哪些版本，因为序列中存在从未发布构建的间隙。

我应该全局安装 dsh 还是通过 npx 运行它？

npx 适合初步尝试，因为除了缓存目录外不会保留任何内容。像 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 月相隔四天发布，0.2.0-rc.1 和 0.2.0-rc.2 于 2026 年 9 月相隔一天发布。请锁定精确版本，并阅读该锁定构建中的 --help，而不是参考任何指南。请为您的笔记标注日期，以便判断它们是否已过时。