装 DeepSeek Harness 之前先做六项预检:Node、pnpm、磁盘、权限、网络与端口
DeepSeek Harness 装不上,多数不是安装命令的问题,而是命令执行前的六项条件里已经有一项不满足。 提前花两分钟预检,比装到一半再回滚省事得多。
装 DeepSeek Harness 前为什么要先预检
安装失败分两类:环境不满足,与安装方式选错。 后者换命令能解决,前者换多少次命令都一样失败。
预检的价值是把「装到一半失败」变成「开始前就知道」。 尤其是在别人的机器、CI 镜像或新服务器上,环境差异比想象中大。
把六项一次列出来对照,比临时想起来一项查一项更可靠。
六项都过,再执行安装命令。 对照如下:
| 项目 | 检查命令 | 通过标准 | 不通过会怎样 |
|---|---|---|---|
| Node | node -v | 能输出版本号 | 命令直接不存在 |
| 包管理器 | npm -v、pnpm -v | 至少 npm 可用 | 插件安装报 pnpm not found |
| 磁盘 | df -h ~ | 剩余空间足够 | 解包中途失败、缓存写满 |
| 权限 | test -w ~ && echo ok | 输出 ok | 配置与会话写不进去 |
| 网络 | npm ping | 返回 PONG | 下载超时、证书错误 |
| 端口 | lsof -i :3080 | 无输出或占用者明确 | 启动失败,安装不受影响 |
六项里前三项决定能不能装,后三项决定装完能不能用。 不要只查前三项。
dsh 运行时三项:Node、npm 与 pnpm
版本错位比版本过低更常见。 按顺序确认:
- 执行
node -v,记录当前终端实际使用的版本; - 执行
which -a node,确认是否存在多份 Node(nvm、Homebrew、系统自带各一份); - 执行
npm -v与npx -v,确认包管理器与执行器同源; - 执行
pnpm -v,没有就先装上,避免插件阶段返工; - 打开一个新的终端再查一次,确认配置对「新开的窗口」也生效。
为什么强调新终端: PATH 改动只在重新加载后生效,老窗口里的结果不代表新窗口。很多「装完还是 command not found」就出在这里(来源)。
dsh 系统条件三项:磁盘、权限与端口
这三项平时不报错,出问题时最难查。 分别验证:
- 磁盘:
df -h ~看剩余空间;npx 缓存、profile 依赖与桌面端运行时会各占一份,空间不足时解包会中断。 - 权限:
test -w ~ && echo ok;不 ok 说明当前用户无法写主目录,配置只能落到别处,后续会出现「配置改了不生效」。 - 端口:
lsof -i :3080;有输出说明被占用,先决定换端口还是处理进程,别等到启动时才发现。
端口占用不影响安装。 这一点常被误解,导致有人为了装 DSH 去杀掉别的服务。
dsh 网络条件:registry、代理与证书
网络问题有三种表现,对应三种检查。 分开测比一次性猜有效:
- registry 可达性:
npm ping,返回 PONG 说明源可用; - 代理:
env | grep -i proxy,确认 HTTPS_PROXY 与实际出口一致; - 证书:
curl -I https://registry.npmjs.org,出现证书错误说明中间证书缺失或被替换; - 镜像:企业镜像可能缺包或滞后,必要时临时切回官方源对照。
三项里证书最隐蔽。 它通常不报「网络不通」,而是报一串 TLS 错误,看起来像安装器坏了。
dsh 预检结果怎么读、六项怎么一次跑完
每一项不通过,都对应一类后续失败,按类处理。 对照下面四条:
- Node 不可用 → 命令找不到,先修 PATH,不要重装 DSH;
- pnpm 缺失 → 插件阶段失败,装 pnpm 后重试;
- 权限不足 → 安装看似成功但配置写不进,先修目录权限;
- 网络或证书 → 下载中断,先修网络,再重跑安装。
预检只负责定位类别,不负责修复。 修复方法各自独立,别把六项混在一起试;而把这六项写成脚本,团队里每个人都能先跑一遍。参考写法:
#!/usr/bin/env bash
echo "node: $(node -v 2>/dev/null || echo MISSING)"
echo "npm: $(npm -v 2>/dev/null || echo MISSING)"
echo "pnpm: $(pnpm -v 2>/dev/null || echo MISSING)"
df -h ~ | tail -n 1
test -w ~ && echo "home writable" || echo "home NOT writable"
npm ping >/dev/null 2>&1 && echo "registry OK" || echo "registry FAIL"
lsof -i :3080 >/dev/null 2>&1 && echo "3080 BUSY" || echo "3080 free"
脚本输出六行,任何一行异常就先停下。 它不替代安装,只保证你不在必然失败的环境里反复尝试。
下一步:预检通过后继续安装 DeepSeek Harness
预检通过后再选安装方式。 想看第一次安装的完整步骤,读 DeepSeek Harness 第一次安装;想看环境类报错怎么修,读 安装失败与环境报错;想看端口占用,读 3080 端口冲突;想看命令找不到,读 dsh 命令找不到。
常见问题
安装 DeepSeek Harness 本体不强制 pnpm,但管理 profile 插件时会用到。只跑 npx 可以先不装;一旦要装插件,缺 pnpm 会直接报 pnpm not found,提前装上能省一次返工。
装 dsh 时多半漏了一项:实际执行命令的 Node 与「你以为的 Node」不是同一个。用 which -a node 与 node -v 对照当前终端,nvm 多版本并存时最容易出现版本错位。
安装 dsh 时 3080 被占用不影响安装,只影响启动。安装阶段可以先继续,启动前再用 lsof -i :3080 找到占用者,能换端口就换,不能换再处理进程,不必为安装提前杀进程。
装 DeepSeek Harness 前,公司网络要同时检查 registry 可达性、代理环境变量与证书链三项。任何一项不对,表现都是下载超时或证书错误;先用 npm ping 与 curl 各测一次,再决定是否改镜像。
相关术语
- 预检
- 预检是在执行安装命令前逐项验证环境条件的过程,目的不是装得更快,而是提前发现必然失败的条件。— DeepSeek Harness 官方文档
- pnpm
- pnpm 是 DeepSeek Harness 管理 profile 插件时使用的包管理器,缺失时插件安装会报 pnpm not found。— dsh CLI README
- registry
- registry 是 npm 包的分发源,默认是官方源,也可以配置为企业镜像;解析与下载都依赖它可达。— dsh CLI README
- 监听端口
- 监听端口是服务接受连接的本地端口,dsh web 默认使用 3080;被占用时启动会失败但安装不受影响。— dsh CLI README
来源
- deepseek-harness 仓库· deepseek-ai
- dsh CLI README· deepseek-ai
- DeepSeek Harness 官方文档· deepseek-harness