跳过主要内容
全部文章
教程

如何在 macOS、Windows、Linux 上安装 DeepSeek Harness（2026）

DeepSeek Harness 在 macOS、Windows、Linux 上的安装步骤，涵盖 Node 版本坑、Arch Linux 的 node-pty 报错，以及 Windows 目录选择器的已知 bug。

DeepSeek Harness（dsh）在每个平台上的安装命令都一样——npx @deepseek-ai/dsh web——但失败模式各不相同：过旧的 Node.js 会在 macOS 和 Linux 上悄无声息地报错，Arch Linux 会拦截某个原生依赖的安装脚本，Windows 则有一个已被记录、有对应解决方案的目录选择器 bug。本文覆盖基础安装，加上我们能从官方仓库及其 GitHub Discussions 中核实到的每一个平台专属问题。

通用基础要求（所有平台）

要求值
Node.js^22.19.0 || >=24.0.0
CI 测试覆盖的 Node 版本22.19、24、26
pnpm一旦开始装插件就需要（dsh plugin 直接调用它）
Git2.26+，仅在你要从源码构建时需要

三个平台上最常见的安装失败原因,其实都是同一个:Node.js 版本过旧。dsh 用到了 node:zlib 的 createZstdDecompress,这个 API 是 Node 22.15 才加入的。在更旧的 Node 版本上,npx @deepseek-ai/dsh web 会立刻报错:

The requested module 'node:zlib' does not provide an export named 'createZstdDecompress'

解决方法就是升级 Node——目标是 22.19+ 或 24+,以匹配 dsh 的 engines 字段的真实要求,而不只是那个 API 需要的 22.15 下限。

macOS

除了上面的 Node 版本要求外，macOS 没有其他平台专属的安装问题。直接走标准路径即可:

npx @deepseek-ai/dsh web

如果你用 nvm、fnm 或 asdf 管理 Node,运行命令前先用 node -v 确认当前激活的版本——一个停留在旧 Node 上的过期 shell 会话,是 macOS 上触发上面那个 zlib 报错最常见的原因。

Python SDK（在另一篇文章里详细讲）在 macOS 上也受支持,但仅限于 macOS 14+（arm64）——Intel Mac 并不在 SDK 内置运行时的官方支持列表里。

Windows

Windows 的命令行安装方式和其他平台一样,但有两个问题值得提前了解。

目录选择器失败

一份有据可查的 Discussion（#30，20 条评论，含被采纳的回答）描述了"添加工作区"失败并报错:

directory picker failed: win32 folder dialog worker exited before reporting a result

根因是原生目录选择器依赖一个叫 koffi 的原生绑定,它的安装脚本在 Windows 上有时会构建失败。解决方案分两步:

  1. 用 --ignore-scripts 重新安装,跳过失败的原生构建步骤:

    npm i -g @deepseek-ai/dsh --ignore-scripts --registry=https://registry.npmjs.org

  2. 编辑 ~/.dsh/profiles/web/cordis.patch.yml，把该 profile 的目录选择器从原生后端切换到浏览式（应用内）后端——禁用 directory-picker/directory-picker-native/directory-picker-auto，改为插入 directory-picker-browse 及其对应的客户端 UI 包。两种选择器后端在用户侧长什么样,可以参考我们的 Web UI 指南。

全局安装后找不到某个包

另一份报告（Discussion #55）描述在 Windows 11 + Node 24 + pnpm 11.9 的组合下,执行 pnpm add -g @deepseek-ai/dsh 之后,dsh --profile headless --help 会崩溃并报错 Cannot find package '@deepseek-ai/cordis-plugin-timer'——这是这个特定组合下依赖解析出现的缺口。社区讨论里声称"已解决",但截至本次调研,尚未看到已合并到主线的公开修复细节。如果你遇到这个问题,可以尝试清空 pnpm store 后重装（pnpm store prune），或者干脆改用 npx @deepseek-ai/dsh web 而不是全局安装,这样能完全绕开全局依赖树。

中文（及其他非 ASCII）工作区路径

两份独立的 Discussion（#47「The workspace does not support Chinese path names」和 #107「中文路径选择截断」）都反映了 Windows 上含中文字符的工作区路径会被截断或拒绝。截至本文撰写时,尚未确认官方修复方案——如果你的项目所在路径含有非 ASCII 字符,建议先把它移到纯 ASCII 路径下,再让 dsh 把它当作工作区。

Linux

基础的 npx @deepseek-ai/dsh web 安装在大多数发行版上都能正常工作。有一个发行版专属的问题被记录了下来:

Arch Linux：node-pty 的安装脚本被拦截

Discussion #49 记录了在 Arch 上,npx @deepseek-ai/dsh web 会在加载插件树时报错,错误指向 node-pty——Arch 上的 npm 默认不信任 node-pty 自行执行编译步骤的安装脚本。有两个记录在案的解决方案:

# 方案 A：改用 bun,它默认信任 node-pty 的安装脚本
bun add --global @deepseek-ai/dsh

# 方案 B：继续用 npm,自己手动全局安装 node-pty,再清空 npx 缓存
npm install -g node-pty
rm -rf ~/.npm/_npx

任选一种方案修复后,重新执行 npx @deepseek-ai/dsh web。

.env 是一个目录而不是文件

如果你的工作目录下恰好有一个名为 .env 的目录（而不是文件）,dsh 每次启动都会打印 failed to load .env: EISDIR。这是一个已确认的 bug（Discussion #71）——.env 加载逻辑在读取路径前没有先判断它是不是一个常规文件。有两处独立的代码路径都会触发这个问题,所以即便你以为修好了一次,它也可能再次出现。解决办法很简单:在那个目录下启动 dsh 之前,先重命名或删除那个 .env 目录。

从源码安装（任意平台）

如果你想跑还未发布的 master 分支,或者你正在为 dsh 本身贡献代码:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

这里有两点值得注意。第一，master 分支的 package.json 版本号可能落后于 npm 上实际已发布的版本——判断"我到底在跑哪个版本"时,应该以 npm 的 latest 标签为准,而不是仓库自己的版本字符串。第二,从源码执行 pnpm run build 时报 [ELIFECYCLE] Command failed with exit code 1 的问题已被记录（Discussion #86）,根因是仓库自己的构建脚本内部混用了 npm run 和 pnpm 调用——dsh 的构建工具链是 pnpm-only 的,即便某些内部脚本引用了 npm run,构建步骤也不要改用 npm 或 yarn 替代。

Python SDK 的平台限制

如果你打算用编程方式而不是 CLI/Web UI 来驱动 dsh,要注意 Python SDK（pip install deepseek-harness-sdk）支持的平台范围比 CLI 窄很多：仅限 Linux x64、Linux arm64 和 macOS 14+（arm64）——即便 CLI 本身在 Windows 上运行良好,Python SDK 内置运行时目前也没有官方文档记录的 Windows 支持。

FAQ

DeepSeek Harness 对 Node.js 的最低版本要求是多少？

按 package.json engines 字段是 ^22.19.0 || >=24.0.0。一个更低的版本——哪怕是 22.14——看起来几乎能用,但一旦 dsh 需要 createZstdDecompress（Node 22.15+ 才有）,就会立刻报 node:zlib 错误。

DeepSeek Harness 是原生支持 Windows,还是只能靠 WSL？

原生 Windows 支持是存在的（CLI、Web UI,以及一个基于 Windows ACL 的沙箱后端）,但要预期上面提到的两个已记录的粗糙点：依赖 koffi 的目录选择器,以及中文路径处理问题。如果你踩到了其中任何一个,WSL 是一个合理的退路,因为它相当于走 Linux 的安装路径。

为什么 npx 单单在 Arch Linux 上会失败？

Arch 的 npm 配置默认不信任 node-pty 的安装脚本,而 dsh 的终端功能依赖 node-pty。改用 bun add --global @deepseek-ai/dsh 可以绕开这个问题,因为 bun 默认信任这个脚本。

我能在没有网络连接的情况下安装 DeepSeek Harness 吗？

官方没有文档说明支持这种方式——npx 需要拉取包,插件安装也要通过 pnpm 访问 npm/GitHub 仓库。官方文档里没有描述任何离线打包格式。

安装看起来成功了,但还是有些东西不对劲——接下来该去哪里查？

去看 DeepSeek Harness 排障指南,那里有一份更全面的、来自官方 GitHub Discussions 的已确认错误信息和修复方法清单（dsh 的 Issues 功能已被禁用,所以 Discussions 是最接近官方 bug 追踪器的渠道）。

Next steps