DeepSeek 开源的 Agent 运行底座 DeepSeek Harnessdsh目前还处于开发者预览阶段官方文档对 Windows 环境着墨不多。本文记录在 Windows 上从零源码安装的完整过程包括国内网络环境下的加速方案以及安装过程中最容易翻车的几个坑。一、DeepSeek Harness 是什么DeepSeek Harness简称 dsh是 DeepSeek 开源的 Agent 运行底座MIT 协议。核心理念是一切皆插件——模型、工具、会话、沙箱、UI 全部可替换可以理解为对标 Claude Code 一类产品但定制自由度更高。它提供三条安装路线路线命令适合人群npx 直跑npx deepseek-ai/dsh web只想快速试用全局安装npm install -g deepseek-ai/dsh日常使用不想折腾源码源码安装git clone→pnpm install→pnpm run build想定制、想写插件、想控制落地位置前两条一行命令就能跑本文重点讲第三条——源码安装这也是坑最多的一条路。二、环境准备WINx安装前确认三样东西1. Node.js ≥ 22.19node -v版本不够的去官网或使用 nvm/mise 升级。想要统一管理一些环境的伙伴可以参考我的这篇文章【Tool】Windows 如何统一管理多个语言版本mise即为答案mise工具的安装及使用指南_mise管理-CSDN博客2. pnpmv10 即可dsh 仓库的package.json里通过packageManager字段锁定了 pnpm 版本。如果你已经有 pnpmpnpm -v没有的话两种装法任选# 方式一corepackNode 自带 corepack enable # 方式二npm 全局安装 npm install -g pnpm --registryhttps://registry.npmmirror.com3. Gitgit --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.gitghfast.top不可用时可以换gh-proxy.com等同类镜像。克隆下来约 7900 个文件视网络情况 1~5 分钟。四、第 2 步安装依赖最容易翻车的一步进入目录安装自己创建文件夹如E:\AI\DeepSeek\DeepSeekHarnesscd E:\AI\DeepSeek\DeepSeekHarness pnpm install --registryhttps://registry.npmmirror.com --config.trust-lockfiletrue这条命令有两个参数一个都不能省--registryhttps://registry.npmmirror.com走国内 npm 镜像下载速度差 10 倍。你也可以通过pnpm config set registry https://registry.npmmirror.com永久配置。--config.trust-lockfiletrue这是本文最重要的避坑点。pnpm v11 起默认开启供应链防护minimumReleaseAge: 1440——拒绝安装发布时间不满 24 小时的包防投毒。而 dsh 的依赖锁文件里有上千个条目只要有一个包是最近发布的安装就会直接失败报错类似ERR_PNPM_LOCKFILE_SUPPLY_CHAIN_CHECK Lockfile failed supply-chain policy check (1215 entries)由于锁文件是随官方仓库一起 git 克隆下来的属于可信基线加--config.trust-lockfiletrue跳过复查是安全的。注意这只是跳过锁文件的新鲜度复查不影响 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 分钟。期间终端没有输出、浏览器连接被拒都是正常现象不要急着 CtrlC等终端打出dsh web: http://...这行字再访问终端按CtrlC停止服务如果想让服务在后台常驻可以写个.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 21零件作用echo off关掉命令回显不然窗口会打印自己执行的每条命令cd /d 路径切到项目目录/d允许跨盘切换 dsh-web.log把输出追加写入日志覆盖追加21把错误输出也并进日志报错信息不丢失两个容易翻车的点PATH 问题双击.cmd时用的是系统 PATH。如果你的 node/pnpm 是靠 nvm、mise 这类工具激活的只在 PowerShell profile 里生效双击时可能找不到pnpm。稳妥写法是在脚本开头手动把工具目录塞进 PATHecho off cd /d D:\deepseek-harness start /min cmd /c node apps\cli\lib\bin.js web dsh-web.log 21窗口行为分两档上面这种写法窗口会常驻关窗口停服务直观但怕误关。想要静默后台跑加一层startecho off for /f tokens5 %%a in (netstat -ano ^| findstr :3080 ^| findstr LISTENING) do taskkill /pid %%a /f echo dsh stoppedstart后面那个空的是窗口标题占位符不能省省了会把后面的路径当成标题。配套的停止脚本后台模式下关不掉窗口需要按端口杀进程思路是netstat找到监听 3080 端口的进程 PIDtaskkill强制结束。保存为stop- dsh.cmd跟启动脚本放一起即可。终极版智能启动脚本推荐把上面的零件组合起来再加三个实用功能重复启动检测服务已在跑就直接开浏览器、后台跑服务不占常驻窗口、就绪后自动打开浏览器。双击体验几秒钟后浏览器自动弹出 dsh 界面全程不用敲一个字。bat echo off rem dsh 快捷启动脚本 - 编译版启动就绪后自动打开浏览器 set NODE_OPTIONS rem 把下面的路径换成你的 node 实际所在目录 set PATHD:\你的node目录;%PATH% rem 已在运行直接开浏览器走人 netstat -ano | findstr /c::3080 | findstr LISTENING nul 21 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 21 rem 轮询等端口就绪每秒查一次最多 30 秒 echo starting dsh... waiting for port 3080 set /a tries0 :waitloop timeout /t 1 nul netstat -ano | findstr /c::3080 | findstr LISTENING nul 21 if %errorlevel%0 goto ready set /a tries1 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启动停止都是双击一下的事。八、首次配置三步走填 API Key网页里进Settings → Models粘贴你的 DeepSeek API Key在 platform.deepseek.com 创建保存即时生效本地存储、重启不用重填选工作区点Choose workspace添加并选中要让 AI 操作的项目目录建议先拿练习目录试手别直接指生产代码开聊发一条消息试试比如总结一下这个仓库的主要包九、日常升级四条命令git pull pnpm install --registryhttps://registry.npmmirror.com --config.trust-lockfiletrue pnpm run build然后重启服务即可。十、避坑速查表症状原因 / 解法git clone卡死、443 超时GitHub 直连不通改走 ghfast.top 等镜像前缀报Lockfile failed supply-chain policy checkpnpm v11 的 minimumReleaseAge 防护拦截加--config.trust-lockfiletrue黄色 WARNUnsupported platform: linux-arm64Linux 原生包在 Windows 上跳过无害下载速度极慢没配国内镜像加--registryhttps://registry.npmmirror.com端口 3080 被占上次的 dsh 服务没停干净任务管理器结束残留 node 进程沙箱强隔离场景异常Windows 上有已知 bug强沙箱需求建议用 WSL十一、写在最后整体来看dsh 的源码安装本身不难真正卡人的只有两件事国内网络环境下的 GitHub/npm 访问以及 pnpm v11 新增的供应链防护机制。把这两个前置问题解决掉整个过程 10 分钟内可以完成。DeepSeek Harness 还在快速迭代本文安装时为 v0.1.1-rc.2遇到问题可以优先查阅官方仓库的 README 和 Issues。如果你在安装过程中踩到了本文没覆盖的坑欢迎在评论区留言交流。本文基于 Windows Node 22/24 pnpm 11 环境实测整理。 【Tool】DeepSeek Harness（dsh）Windows 源码安装保姆级教程：从克隆到跑通，附避坑指南
DeepSeek 开源的 Agent 运行底座 DeepSeek Harnessdsh目前还处于开发者预览阶段官方文档对 Windows 环境着墨不多。本文记录在 Windows 上从零源码安装的完整过程包括国内网络环境下的加速方案以及安装过程中最容易翻车的几个坑。一、DeepSeek Harness 是什么DeepSeek Harness简称 dsh是 DeepSeek 开源的 Agent 运行底座MIT 协议。核心理念是一切皆插件——模型、工具、会话、沙箱、UI 全部可替换可以理解为对标 Claude Code 一类产品但定制自由度更高。它提供三条安装路线路线命令适合人群npx 直跑npx deepseek-ai/dsh web只想快速试用全局安装npm install -g deepseek-ai/dsh日常使用不想折腾源码源码安装git clone→pnpm install→pnpm run build想定制、想写插件、想控制落地位置前两条一行命令就能跑本文重点讲第三条——源码安装这也是坑最多的一条路。二、环境准备WINx安装前确认三样东西1. Node.js ≥ 22.19node -v版本不够的去官网或使用 nvm/mise 升级。想要统一管理一些环境的伙伴可以参考我的这篇文章【Tool】Windows 如何统一管理多个语言版本mise即为答案mise工具的安装及使用指南_mise管理-CSDN博客2. pnpmv10 即可dsh 仓库的package.json里通过packageManager字段锁定了 pnpm 版本。如果你已经有 pnpmpnpm -v没有的话两种装法任选# 方式一corepackNode 自带 corepack enable # 方式二npm 全局安装 npm install -g pnpm --registryhttps://registry.npmmirror.com3. Gitgit --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.gitghfast.top不可用时可以换gh-proxy.com等同类镜像。克隆下来约 7900 个文件视网络情况 1~5 分钟。四、第 2 步安装依赖最容易翻车的一步进入目录安装自己创建文件夹如E:\AI\DeepSeek\DeepSeekHarnesscd E:\AI\DeepSeek\DeepSeekHarness pnpm install --registryhttps://registry.npmmirror.com --config.trust-lockfiletrue这条命令有两个参数一个都不能省--registryhttps://registry.npmmirror.com走国内 npm 镜像下载速度差 10 倍。你也可以通过pnpm config set registry https://registry.npmmirror.com永久配置。--config.trust-lockfiletrue这是本文最重要的避坑点。pnpm v11 起默认开启供应链防护minimumReleaseAge: 1440——拒绝安装发布时间不满 24 小时的包防投毒。而 dsh 的依赖锁文件里有上千个条目只要有一个包是最近发布的安装就会直接失败报错类似ERR_PNPM_LOCKFILE_SUPPLY_CHAIN_CHECK Lockfile failed supply-chain policy check (1215 entries)由于锁文件是随官方仓库一起 git 克隆下来的属于可信基线加--config.trust-lockfiletrue跳过复查是安全的。注意这只是跳过锁文件的新鲜度复查不影响 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 分钟。期间终端没有输出、浏览器连接被拒都是正常现象不要急着 CtrlC等终端打出dsh web: http://...这行字再访问终端按CtrlC停止服务如果想让服务在后台常驻可以写个.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 21零件作用echo off关掉命令回显不然窗口会打印自己执行的每条命令cd /d 路径切到项目目录/d允许跨盘切换 dsh-web.log把输出追加写入日志覆盖追加21把错误输出也并进日志报错信息不丢失两个容易翻车的点PATH 问题双击.cmd时用的是系统 PATH。如果你的 node/pnpm 是靠 nvm、mise 这类工具激活的只在 PowerShell profile 里生效双击时可能找不到pnpm。稳妥写法是在脚本开头手动把工具目录塞进 PATHecho off cd /d D:\deepseek-harness start /min cmd /c node apps\cli\lib\bin.js web dsh-web.log 21窗口行为分两档上面这种写法窗口会常驻关窗口停服务直观但怕误关。想要静默后台跑加一层startecho off for /f tokens5 %%a in (netstat -ano ^| findstr :3080 ^| findstr LISTENING) do taskkill /pid %%a /f echo dsh stoppedstart后面那个空的是窗口标题占位符不能省省了会把后面的路径当成标题。配套的停止脚本后台模式下关不掉窗口需要按端口杀进程思路是netstat找到监听 3080 端口的进程 PIDtaskkill强制结束。保存为stop- dsh.cmd跟启动脚本放一起即可。终极版智能启动脚本推荐把上面的零件组合起来再加三个实用功能重复启动检测服务已在跑就直接开浏览器、后台跑服务不占常驻窗口、就绪后自动打开浏览器。双击体验几秒钟后浏览器自动弹出 dsh 界面全程不用敲一个字。bat echo off rem dsh 快捷启动脚本 - 编译版启动就绪后自动打开浏览器 set NODE_OPTIONS rem 把下面的路径换成你的 node 实际所在目录 set PATHD:\你的node目录;%PATH% rem 已在运行直接开浏览器走人 netstat -ano | findstr /c::3080 | findstr LISTENING nul 21 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 21 rem 轮询等端口就绪每秒查一次最多 30 秒 echo starting dsh... waiting for port 3080 set /a tries0 :waitloop timeout /t 1 nul netstat -ano | findstr /c::3080 | findstr LISTENING nul 21 if %errorlevel%0 goto ready set /a tries1 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启动停止都是双击一下的事。八、首次配置三步走填 API Key网页里进Settings → Models粘贴你的 DeepSeek API Key在 platform.deepseek.com 创建保存即时生效本地存储、重启不用重填选工作区点Choose workspace添加并选中要让 AI 操作的项目目录建议先拿练习目录试手别直接指生产代码开聊发一条消息试试比如总结一下这个仓库的主要包九、日常升级四条命令git pull pnpm install --registryhttps://registry.npmmirror.com --config.trust-lockfiletrue pnpm run build然后重启服务即可。十、避坑速查表症状原因 / 解法git clone卡死、443 超时GitHub 直连不通改走 ghfast.top 等镜像前缀报Lockfile failed supply-chain policy checkpnpm v11 的 minimumReleaseAge 防护拦截加--config.trust-lockfiletrue黄色 WARNUnsupported platform: linux-arm64Linux 原生包在 Windows 上跳过无害下载速度极慢没配国内镜像加--registryhttps://registry.npmmirror.com端口 3080 被占上次的 dsh 服务没停干净任务管理器结束残留 node 进程沙箱强隔离场景异常Windows 上有已知 bug强沙箱需求建议用 WSL十一、写在最后整体来看dsh 的源码安装本身不难真正卡人的只有两件事国内网络环境下的 GitHub/npm 访问以及 pnpm v11 新增的供应链防护机制。把这两个前置问题解决掉整个过程 10 分钟内可以完成。DeepSeek Harness 还在快速迭代本文安装时为 v0.1.1-rc.2遇到问题可以优先查阅官方仓库的 README 和 Issues。如果你在安装过程中踩到了本文没覆盖的坑欢迎在评论区留言交流。本文基于 Windows Node 22/24 pnpm 11 环境实测整理。