DeepSeek Harness(dsh)Windows 源码安装保姆级教程(从克隆到跑通附避坑指南)

DeepSeek 开源的 Agent 运行底座 DeepSeek Harness（dsh）目前还处于开发者预览阶段，官方文档对 Windows 环境着墨不多。本文记录在 Windows 上从零源码安装的完整过程，包括国内网络环境下的加速方案，以及安装过程中最容易翻车的几个坑。

一、DeepSeek Harness 是什么

DeepSeek Harness（简称 dsh）是 DeepSeek 开源的 Agent 运行底座，MIT 协议。核心理念是"一切皆插件"——模型、工具、会话、沙箱、UI 全部可替换，可以理解为对标 Claude Code 一类产品，但定制自由度更高。

它提供三条安装路线：

前两条一行命令就能跑，本文重点讲第三条——源码安装，这也是坑最多的一条路。

二、环境准备

WIN+x    

安装前确认三样东西：

1. Node.js ≥ 22.19

 node -v

版本不够的去官网或使用 nvm/mise 升级。

2. pnpm（v10+ 即可）

dsh 仓库的 package.json 里通过 packageManager 字段锁定了 pnpm 版本。如果你已经有 pnpm：

 pnpm -v

没有的话两种装法任选：

 # 方式一：corepack（Node 自带）
 corepack enable
 ​
 # 方式二：npm 全局安装
 npm install -g pnpm --registry=https://registry.npmmirror.com

3. Git

 git --version

三、第 1 步：克隆仓库

标准操作：

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

国内用户注意：GitHub 直连经常 443 连不上、克隆卡死。这时候走镜像加速，在仓库地址前面加一个镜像前缀即可：

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

ghfast.top 不可用时可以换 gh-proxy.com 等同类镜像。克隆下来约 7900 个文件，视网络情况 1~5 分钟。

四、第 2 步：安装依赖（最容易翻车的一步）

进入目录安装：（自己创建文件夹如：E:\AI\DeepSeek\DeepSeekHarness）

cd E:\AI\DeepSeek\DeepSeekHarness
 pnpm install --registry=https://registry.npmmirror.com --config.trust-lockfile=true

这条命令有两个参数，一个都不能省：

--registry=https://registry.npmmirror.com 走国内 npm 镜像，下载速度差 10 倍。你也可以通过 pnpm config set registry https://registry.npmmirror.com 永久配置。

--config.trust-lockfile=true 这是本文最重要的避坑点。pnpm v11 起默认开启供应链防护 minimumReleaseAge: 1440——拒绝安装发布时间不满 24 小时的包（防投毒）。而 dsh 的依赖锁文件里有上千个条目，只要有一个包是最近发布的，安装就会直接失败，报错类似：

 ERR_PNPM_LOCKFILE_SUPPLY_CHAIN_CHECK  Lockfile failed supply-chain policy check (1215 entries)

由于锁文件是随官方仓库一起 git 克隆下来的，属于可信基线，加 --config.trust-lockfile=true 跳过复查是安全的。注意这只是跳过锁文件的"新鲜度"复查，不影响 pnpm 其他的安装期防护。

正常现象：安装过程中会出现几条黄色警告：

WARN  Unsupported platform: wanted linux-arm64/linux-x64, current win32-x64

这是项目里 Linux 专属的原生依赖包在 Windows 上自动跳过，无害，直接忽略。

顺利的话约 900+ 个包、2~3 分钟装完。

五、第 3 步：构建

pnpm run build

一两分钟跑完，产出约 200 个客户端构建产物，没有任何报错即为成功。

六、第 4 步：启动

pnpm dsh web

• 服务监听 http://127.0.0.1:3080，首次启动会自动打开浏览器
• 注意启动耗时：pnpm dsh 使用 tsx 在运行时现场编译 CLI 代码，从敲下命令到端口就绪需要 1~3 分钟。期间终端没有输出、浏览器连接被拒都是正常现象，不要急着 Ctrl+C，等终端打出 dsh web: http://... 这行字再访问
• 终端按 Ctrl+C 停止服务
• 如果想让服务在后台常驻，可以写个 .cmd 脚本双击运行，写法见下一节

嫌启动慢？直接跑编译产物（实测快 40 倍）

pnpm run build 除了前端，还会产出 CLI 的编译版。跳过 tsx 现场编译，直接跑它：

node apps\cli\lib\bin.js web

实测同一台机器：tsx 版约 165 秒才就绪，编译版 约 4 秒。日常使用强烈推荐这种方式（后文的启动脚本也基于它）。

代价只有一个：git pull 更新代码后必须重新 pnpm run build，否则跑的还是旧版本代码。

⚠️ 高频报错：Cannot find module ... bin.js（找不到模块）

apps\cli\lib\bin.js 是相对路径——它指的是"当前目录下的 apps\cli\lib\bin.js"。如果你在别的文件夹里直接敲这条命令，node 就找不到文件。必须先 cd 进项目根目录再运行：

cd 如：D:\deepseek-harness        # 你 clone 项目的位置
node apps\cli\lib\bin.js web

也可以用绝对路径一步到位（路径换成你自己的）：

node D:\deepseek-harness\apps\cli\lib\bin.js web

另一个高频报错：EADDRINUSE（端口被占用）

说明已经有一个 dsh 实例在跑（3080 端口被占）。先停掉旧实例再启动：Windows 下用 netstat -ano | findstr :3080 查到占用进程的 PID，然后 taskkill /PID <那个数字> /F 结束它；或者直接访问 http://127.0.0.1:3080 使用现有实例就好。

代价只有一个：git pull 更新代码后必须重新 pnpm run build，否则跑的还是旧版本代码。

七、进阶：写一个双击启动的 .cmd 脚本

每次启动都要开终端敲命令有点繁琐，可以写两个脚本放在桌面，双击即用。

新建文本，改后缀为 start-dsh.cmd , stop-dsh.cmd

通用骨架（四件套）：

@echo off
cd /d "D:\deepseek-harness"
node apps\cli\lib\bin.js web >> dsh-web.log 2>&1

两个容易翻车的点：

PATH 问题：双击 .cmd 时用的是系统 PATH。如果你的 node/pnpm 是靠 nvm、mise 这类工具激活的（只在 PowerShell profile 里生效），双击时可能找不到 pnpm。稳妥写法是在脚本开头手动把工具目录塞进 PATH：

@echo off
cd /d "D:\deepseek-harness"
start "" /min cmd /c "node apps\cli\lib\bin.js web >> dsh-web.log 2>&1"

窗口行为分两档：上面这种写法窗口会常驻，关窗口=停服务，直观但怕误关。想要静默后台跑，加一层 start：

@echo off
for /f "tokens=5" %%a in ('netstat -ano ^| findstr :3080 ^| findstr LISTENING') do taskkill /pid %%a /f
echo dsh stopped

start 后面那个空的 "" 是窗口标题占位符，不能省，省了会把后面的路径当成标题。

           配套的停止脚本（后台模式下关不掉窗口，需要按端口杀进程）：

           思路是：netstat 找到监听 3080 端口的进程 PID，taskkill 强制结束。保存为 stop-      dsh.cmd，跟启动脚本放一起即可。

终极版：智能启动脚本（推荐）

把上面的零件组合起来，再加三个实用功能：重复启动检测（服务已在跑就直接开浏览器）、后台跑服务（不占常驻窗口）、就绪后自动打开浏览器。双击体验：几秒钟后浏览器自动弹出 dsh 界面，全程不用敲一个字。

```bat
@echo off
rem dsh 快捷启动脚本 - 编译版启动，就绪后自动打开浏览器
set "NODE_OPTIONS="
rem 把下面的路径换成你的 node 实际所在目录
set "PATH=D:\你的node目录;%PATH%"
rem 已在运行？直接开浏览器走人
netstat -ano | findstr /c:":3080 " | findstr LISTENING >nul 2>&1
if %errorlevel%==0 (
    echo dsh is already running, opening browser...
    start "" "http://127.0.0.1:3080"
    timeout /t 2 >nul
    exit /b 0
)
cd /d "D:\deepseek-harness"
echo ===== [%date% %time%] starting dsh web ===== >> dsh-web.log
rem 服务丢到最小化后台窗口跑，日志追加写入
rem --no-open 很关键：dsh 自己也会开浏览器，不加这个参数会开两个窗口
start "" /min cmd /c "node apps\cli\lib\bin.js web --no-open >> dsh-web.log 2>&1"
rem 轮询等端口就绪（每秒查一次，最多 30 秒）
echo starting dsh... waiting for port 3080
set /a tries=0
:waitloop
timeout /t 1 >nul
netstat -ano | findstr /c:":3080 " | findstr LISTENING >nul 2>&1
if %errorlevel%==0 goto ready
set /a tries+=1
if %tries% geq 30 (
    echo timeout after 30s - check dsh-web.log for details
    pause
    exit /b 1
)
goto waitloop
:ready
echo dsh is up! opening http://127.0.0.1:3080
start "" "http://127.0.0.1:3080"
timeout /t 3 >nul
```

几个实现细节：

• if %errorlevel%==0 是判断上一条命令（findstr）是否找到了结果，找到说明端口有监听
• 等待循环用 goto 而不是 for，这样 %errorlevel% 每圈都能重新取值（写在括号块里的变量不会即时刷新，是批处理的经典坑）
• 结尾的 timeout /t 3 让窗口停留 3 秒再自动关闭，你能看到"dsh is up!"的确认信息；启动失败时用 pause，窗口停住等你按键，方便看报错

把这个保存为 start-dsh.cmd，配合前面的 stop-dsh.cmd，启动停止都是双击一下的事。

八、首次配置（三步走）

1. 填 API Key：网页里进 Settings → Models，粘贴你的 DeepSeek API Key（在 platform.deepseek.com 创建）保存，即时生效，本地存储、重启不用重填
2. 选工作区：点 Choose workspace，添加并选中要让 AI 操作的项目目录（建议先拿练习目录试手，别直接指生产代码）
3. 开聊：发一条消息试试，比如"总结一下这个仓库的主要包"

九、日常升级

四条命令：

git pull
pnpm install --registry=https://registry.npmmirror.com --config.trust-lockfile=true
pnpm run build

然后重启服务即可。

十、避坑速查表

十一、写在最后

整体来看，dsh 的源码安装本身不难，真正卡人的只有两件事：国内网络环境下的 GitHub/npm 访问，以及 pnpm v11 新增的供应链防护机制。把这两个前置问题解决掉，整个过程 10 分钟内可以完成。

DeepSeek Harness 还在快速迭代（本文安装时为 v0.1.1-rc.2），遇到问题可以优先查阅官方仓库的 README 和 Issues。如果你在安装过程中踩到了本文没覆盖的坑，欢迎在评论区留言交流。

本文基于 Windows + Node 22/24 + pnpm 11 环境实测整理。

到此这篇关于DeepSeek Harness(dsh)Windows 源码安装保姆级教程(从克隆到跑通附避坑指南)的文章就介绍到这了,更多相关DeepSeek Harness保姆级教程内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论