DeepSeek Harness 装插件总报错?这份避坑 SOP 一次装好

前阵子折腾 DeepSeek Harness 的 Web UI 插件，从 clone 到启动一路踩坑：dsh 命令找不到、pnpm 构建脚本被拦、GitHub 装包走 SSH 连不上。把每一步的坑和经过验证的做法整理成一份 SOP，照着走基本一次能成。

下面按「先准备环境 → 踩坑怎么办 → 标准安装流程」的顺序来。

一、先准备好环境

• 操作系统：Windows
• 包管理器：pnpm（官方就用它，别换 npm）
• Node.js：建议 ≥ 22.19.0
• 项目路径：别放在 C:\Windows\System32 这类系统保护目录，会出权限问题和环境变量干扰。clone 到用户目录，比如 C:\Users\你的用户名\deepseek-harness

二、六个常见坑，对照着排

坑 1：dsh 提示“不是内部或外部命令”

你直接在项目目录敲 dsh web，报错。

原因：git clone 下来的只是源码，dsh 没全局装，得用 pnpm 调。

解决：在项目根目录用 pnpm dsh 或 pnpm exec dsh，别进 ~/.dsh/profiles/web 子目录去执行。

pnpm dsh web

坑 2：安装插件报 ERR_PNPM_IGNORED_BUILDS

装 dshmarket 之类插件时，提示 Ignored build scripts: cloudflared、cpu-features、ssh2。

原因：pnpm 出于安全默认拦了这些要编原生二进制的脚本。

解决：进到 dsh 给该 profile 建的工作目录 C:\Users\你的用户名\.dsh\profiles\web，跑 pnpm approve-builds，选允许全部或逐个确认；然后回项目根目录重跑安装。

坑 3：在 profile 目录执行 pnpm dsh 反而失败

你 cd 进 C:\Users\li\.dsh\profiles\web 再敲 pnpm dsh plugin，报“dsh 不是内部或外部命令”。

原因：profile 目录只是放插件依赖的工作区，里面没有 dsh 可执行文件。

解决：所有 dsh 操作都在项目根目录（含 pnpm-workspace.yaml 的目录）跑。

坑 4：用 github: 安装时 SSH 认证失败

装 github:zhu1090093659/dsh-web-ui 报 git ls-remote ... exit 128，SSH 连不上。

原因：dsh 默认走 SSH 克隆，你没配 SSH 密钥或 22 端口被封。

解决（任选其一）：

• 方案 A：配 SSH 密钥并加到 GitHub。
• 方案 B：让 Git 把 SSH 地址强制转 HTTPS：

git config --global url."https://github.com/".insteadOf git@github.com:

再用：

pnpm dsh plugin --profile web add "github:zhu1090093659/dsh-web-ui#main"

• 方案 C（最省事）：直接用 tarball 地址，免认证：

pnpm dsh plugin --profile web add https://github.com/zhu1090093659/dsh-web-ui/archive/refs/heads/main.tar.gz

坑 5：dsh-web-ui@latest 返回 404

装 dsh-web-ui@latest 报 registry.npmmirror.com ... 404。

原因：这包没发到 npm，只在 GitHub 上，不能用 npm 包名装。

解决：改用上面的 GitHub 方式（见坑 4）。

坑 6：批准构建脚本后还是报错

解决建议：

• 确认 profile 目录下 package.json 已生成，可删 node_modules 和 pnpm-lock.yaml 后重新 pnpm install。
• 用 pnpm peers check 看 peer 依赖冲突（通常不影响功能）。
• 若构建涉及 Python 或 C++ 编译，装好对应的构建工具（如 Windows Build Tools）。

三、照这套流程，一次装好

假设项目在用户目录。

1. 克隆并进入根目录

git clone https://github.com/deepseek-ai/deepseek-harness.gitcd deepseek-harness

2. 装依赖并构建

pnpm installpnpm run build

3. 装插件（用 tarball，避开 SSH 和 npm 问题）

pnpm dsh plugin --profile web add https://github.com/zhu1090093659/dsh-web-ui/archive/refs/heads/main.tar.gz

中途若提示构建脚本被忽略，按坑 2 批准即可。

4. 启动 Web UI

pnpm dsh web

浏览器开 http://127.0.0.1:3080，插件应该已经加载。

四、还有几点要注意

• 路径：千万别放 C:\Windows\System32 等系统目录，权限不够会装不上或跑异常。
• 代理：用了代理可能让 git 或 npm 请求失败，试着取消代理或配好代理环境变量。
• 版本：插件版本要和 dsh 核心兼容，看插件文档或 release 说明。

五、一张表速查

装环境最怕的就是反复试错，把这几条记牢，下次基本一遍过。你踩到的要是上面没写到的坑，也欢迎留言，我接着补进这份 SOP。