一分钟上手 DeepSeek Harness：macOS 与 Windows 源码安装指南
目录
先确认版本要求
DeepSeek Harness 目前仍处于开发者预览阶段，项目会持续迭代，版本之间可能存在兼容性变化。源码安装前，建议先看当前仓库的 package.json，不要只依赖旧截图或旧文章。
当前仓库声明：
- Node.js：
^22.19.0 || >=24.0.0 - pnpm：
11.7.0
项目官方源码运行路径如下：
1 | git clone https://github.com/deepseek-ai/deepseek-harness.git |
pnpm run build 会准备仓库产物，pnpm dsh web 会直接使用这些产物启动 Web UI。
Node.js 可以从 官方下载页 获取。Windows 用户还需要 Git，可以参考 Git for Windows 官方安装说明。
macOS：先解决 pnpm 找不到
macOS 终端先报了这个错误：
1 | zsh: command not found: pnpm |
它说明当前 shell 找不到 pnpm，原因可能是尚未安装，也可能是安装目录没有进入 PATH。
先确认 Node.js 版本：
1 | node --version |
如果 Node.js 版本低于项目要求，需要先升级 Node.js。Node.js 准备好以后，可以使用 Corepack 安装仓库指定的 pnpm 版本：
1 | corepack enable |
如果当前 Node.js 环境没有 Corepack，也可以使用 npm 安装：
1 | npm install --global pnpm@11.7.0 |
确认 pnpm --version 可以正常输出后，再执行源码安装：
1 | git clone https://github.com/deepseek-ai/deepseek-harness.git |
如果 pnpm 刚安装完成，当前终端仍然提示找不到命令，可以先重新打开一个终端窗口，或者刷新 shell 的命令缓存：
1 | hash -r |
macOS 的处理顺序比较简单：先满足 Node.js 版本要求，再确认当前 shell 能找到 pnpm。
Windows：先准备 Node.js 和 Git
Windows 可以使用 Node.js 官方安装程序完成 Node.js 安装。Git 可以在 PowerShell 中通过 winget 安装：
1 | winget install --id Git.Git -e --source winget |
安装完成后，建议关闭当前 PowerShell，再打开一个新的窗口，检查环境：
1 | node --version |
如果这里的命令都能输出版本号，再进入 pnpm 安装步骤。
Windows 第一个问题：pnpm 无法识别
Windows 记录里首先出现的是：
1 | pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。 |
图 1：PowerShell 还没有找到 pnpm 命令。这说明问题发生在项目安装之前。
这时可以先检查系统里是否存在 pnpm：
1 | where.exe pnpm.* |
如果没有结果，说明 pnpm 尚未安装，或者安装目录没有加入 PATH。
接着尝试执行：
1 | npm install -g pnpm |
但这条命令又触发了 PowerShell 的脚本执行策略错误。
Windows 第二个问题：npm.ps1 被禁止运行
错误信息如下：
1 | npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。 |
图 2：npm 命令已经被找到，但 PowerShell 阻止了它对应的 .ps1 脚本。
记录中采用的处理方式是：
1 | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
这里的 CurrentUser 表示只修改当前用户的 PowerShell 策略，不是修改整台电脑的系统策略。相关机制可以参考 Microsoft 的 about_Execution_Policies。
修改后重新打开 PowerShell，再执行 pnpm 安装。
如果不希望调整 PowerShell 策略，也可以尝试直接调用 npm 的 Windows 命令文件：
1 | npm.cmd install --global pnpm@11.7.0 |
这条 npm.cmd 是备用路径，记录本身没有验证它。无论采用哪条路径，最后都应以 pnpm --version 的输出为准。
不要直接依赖 pnpm 的 latest 版本
截图中全局安装完成后显示：
1 | pnpm 12.4.1 |
图 3：全局安装命令完成，并提示 pnpm 有更新版本。
但后续项目安装完成时，输出又显示：
1 | Done in 1m 14.6s using pnpm v11.7.0 |
图 4：项目安装最终显示使用 pnpm v11.7.0。
记录里出现过 pnpm 12.4.1 和 11.7.0，但没有留下足够信息判断版本为何发生变化。与其猜测 Corepack、PATH 顺序或 pnpm shim 的影响，不如先把当前实际命令路径查清楚。
如果想确认当前 PowerShell 实际调用了哪一个 pnpm，可以执行：
1 | where.exe pnpm.* |
为了让源码安装更容易复现，建议显式安装项目声明的版本：
1 | npm.cmd install --global pnpm@11.7.0 |
也可以使用 Corepack 固定版本：
1 | corepack enable |
pnpm 官方安装文档 会随着 pnpm 发布版本变化，文档里的 latest 不等于当前项目的固定版本。
从源码安装并启动 Web UI
确认 Node.js、Git 和 pnpm 都可以正常使用后，执行：
1 | git clone https://github.com/deepseek-ai/deepseek-harness.git |
第一次安装会下载较多依赖，终端会出现大量下载记录：
图 5：依赖安装过程中会持续显示下载进度和包名。
看到 WARN、更新提示或者大量下载日志时，先看命令最后是否正常结束，以及是否出现类似下面的完成信息：
1 | Done in ... using pnpm v11.7.0 |
依赖安装完成后构建项目：
1 | pnpm run build |
构建过程可能会出现 chunk 较大的提示：
图 6：构建完成，同时提示部分 chunk 超过建议大小；只要退出码正常，就可以继续启动。
命令正常退出并出现 built 或类似完成信息后，再启动 Web UI：
1 | pnpm dsh web |
启动后访问：
1 | http://127.0.0.1:3080 |
图 7：Web UI 已经启动，说明本地服务可以访问；模型配置和实际请求还需要单独检查。
怎样区分 warning 和实际失败
| 终端现象 | 判断 |
|---|---|
WARN、更新提示、下载日志 |
通常是信息提示，继续看最终退出状态 |
Done ... using pnpm v11.7.0 |
依赖安装完成 |
| chunk 大小提示 | 构建 warning，不一定影响本地运行 |
ELIFECYCLE、gyp ERR! |
安装或构建确实失败 |
| 非零退出码 | 命令失败，需要继续排查 |
| 浏览器出现 Web UI | 只证明本地 Web 服务启动成功 |
黄色 warning 不必马上中断安装，绿色下载日志也不等于构建完成。判断依据还是最终完成行和退出码。
如果遇到原生依赖编译错误
这份安装记录没有出现 node-gyp 失败；其他 Windows 用户则报告过 fs-ext、node-pty 或 Visual Studio 工具链相关错误。
可以参考 DeepSeek Harness Discussion #5638。这类问题和 Node.js、pnpm、项目版本及本机编译工具有关，处理方式需要结合自己的日志判断。
排查时建议：
- 先确认 Node.js 版本符合仓库要求；
- 确认 pnpm 版本；
- 从日志中找到第一个实际的
gyp ERR!； - 不要用
--ignore-scripts把原生依赖安装脚本整体跳过。
如果错误来自另一条 npx @deepseek-ai/dsh 安装路径，也不要和源码安装问题混在一起。社区曾报告过 Windows 上 npm 依赖解析卡死或 OOM 的情况，可以参考 Discussion #4872。
最后整理成一条可复现路径
macOS：
1 | node --version |
Windows PowerShell：
1 | node --version |
如果 PowerShell 允许执行 npm 脚本，也可以使用：
1 | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
这条安装路径里，最容易忽略的是环境版本和命令来源：
pnpm找不到，先检查安装和 PATH；npm.ps1被阻止，先处理 PowerShell 执行策略；- pnpm 版本出现差异，先用
where.exe和Get-Command确认实际路径； - warning 不等于失败，最终退出码和完成信息才是判断依据；
- Web UI 能打开，说明本地服务启动成功，但模型配置和请求仍需要单独验证。
