我把 DeepSeek Harness 装好了，顺手把 12 个坑都踩了一遍（附一键启动脚本）

先说点废话。前两天想在本机跑一个“能自己动手写代码”的 AI 智能体，朋友推荐了 DeepSeek Harness，说是 DeepSeek 官方开源的，还能在浏览器里聊天。我一想挺好，装！结果这一装，从下午折腾到晚上。

网上的教程要么是英文的，要么只讲“装三步、跑一下”，真正会卡住的地方一个字没提。所以我把整个过程，包括我踩过的每一个坑，都写下来。这篇东西你照着走，应该能比我顺利很多。

---

一、先说清楚：它到底是干嘛的

1.1 一句话版本
DeepSeek Harness（下面我都叫它 dsh）是一个“AI 智能体框架”。普通聊天工具只会回你文字，它不一样：它把大模型装进一个能碰电脑的“壳子”里——模型负责想，框架负责动手，读写文件、跑命令、调工具都行，然后给你一个网页聊天界面，你就在里面跟它说话。

官网在 https://github.com/deepseek-ai/deepseek-harness，MIT 协议，免费开源。

1.2 拆开看，它由这么几块组成

组件	干嘛的	大白话
模型层	接 DeepSeek 官方 API	大脑
Agent 核心	规划任务、调工具、多步执行	神经中枢
工具层	文件、Shell、网页检索、Skills	手脚
插件机制	一切皆插件（基于 Cordis）	能装 App 一样扩展
Web UI / CLI	网页界面 + 命令行模式	对话窗口

1.3 你发一句话，背后发生了什么

你在网页打字发出去
      ↓
Web UI 把消息交给 Agent 核心
      ↓
Agent 想：要不要读文件 / 跑命令 / 直接答？
      ↓
需要工具就去调工具（读文件、执行命令……）
      ↓
模型拿到结果接着推理
      ↓
答案一句句流回网页

1.4 为什么要泼一盆冷水
它现在还处于“开发者预览版”，官方 README 原话是：会有不兼容的破坏性变更。翻译一下就是：界面、配置、插件接口都可能说变就变。所以别太依赖网上老教程，以官方 README 为准；升级前记得把配置目录备份一下（位置后面会讲）。

---

二、动手装：环境要求 + 三步安装

2.1 电脑环境要求

项目	要求	备注
系统	Windows 10/11、macOS、Linux	本文按 Windows 讲
Node.js	22.19+（或 24.x / 25.9+）	必须先装 Node
pnpm	11.x（项目锁 11.7.0）	用 Node 自带 corepack 启用
Git	2.26+	可选，用 zip 源码可以不要
浏览器	Chrome / Edge	打开界面用
磁盘	至少 5 GB 空余	源码加依赖不小
网络	能连 GitHub 和 npm	连不上看踩坑 ①

先打开 PowerShell，敲这三条看看齐不齐：

node --version
pnpm --version
git --version

没有 Node 的话先去官网装 LTS 版，装完重开一个终端再试。

补充一句很多人会问的：仓库里那个 Python SDK 要求 Python 3.10 以上，但咱们用网页和命令行模式根本用不到 Python。你机器上只有 3.6、3.9 也没关系，跳过就行。

2.2 三步安装

第一步：拿源码

官方推荐这么拉：

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

要是 GitHub 拉不动（八成会拉不动，看踩坑 ①），就改成下官方 zip：

curl -L -o deepseek-harness.zip https://codeload.github.com/deepseek-ai/deepseek-harness/zip/refs/heads/master

解压到你想放的位置，比如 你的磁盘:\你的目录\Deepseek harness（重点：目录名别带中文空格容易出幺蛾子，空格和括号勉强能用）。解压完确认根目录里有 package.json、pnpm-workspace.yaml、apps、packages 这些就对了。

第二步：装依赖

cd "你的磁盘:\你的目录\Deepseek harness"
pnpm install

这一步会下载几百个包，第一次十几分钟很正常，别催。看到结尾 Done in … 就成功了。

第三步：构建

pnpm run build

构建完会生成 apps\cli\lib\bin.js 这种成品文件，结尾有 ✓ built in … 就是好了。

最后验证一下：

pnpm dsh --version

能打印出版本号（比如 0.1.0-rc.5），安装就算全部完成。

2.3 第一次打开，怎么用起来

① 启动服务

在安装目录里运行：

pnpm dsh web

等它打印出 dsh web: http://127.0.0.1:3080，手动复制到浏览器打开。注意它不会自己弹浏览器，这是故意的，别傻等。

首页-选择工作区

② 先填 API Key（不填 = 没反应）

点左下角“设置”齿轮 → 模型，把你的 DeepSeek 官方 API Key 粘进去保存。不想点界面的话，也可以在安装目录下建一个 .env 文件，写一行 DEEPSEEK_API_KEY=sk-你的密钥。

模型设置

③ 选一个工作区（这一步不做，输入框是灰的）
顶部点“选择工作区”，加一个你自己的项目文件夹（建议单独建个空目录，比如 D:\dsh-workspace）。不选工作区，底下输入框根本不能打字，发送按钮也是禁用的。新手十有八九卡在这。

选择工作区后的界面

④ 发第一句话
输入“你好，请用一句话介绍你自己”，回车。我实测首字大概 3 秒多就出来了，底下还会显示用了多少 token、速度多少：

首次对话

⑤ 不想开网页？用命令行模式

临时跑个一次性任务，用 headless：

pnpm dsh --profile headless "请用一句话介绍你自己"

跑完会自动退出，屏幕上就是答案：

无头模式终端演示

⑥ 嫌每次敲命令麻烦？看第三部分的“一键启动”

普通用户我强烈建议做成一键快捷方式，双击图标、自动开浏览器、还没有黑框。方案和脚本我放在第三部分后面，路径都打了码，自己改一下就能用。

一键启动方案-文件清单

快捷方式属性与恢复

三、我替你踩过的坑（现象 → 原因 → 怎么救）

下面这些坑都是我真真切切踩过的，按“安装 → 使用 → 做一键启动”的顺序写，每一条都给了解决办法。

坑 ① GitHub 死活拉不动

现象：git clone 卡在那半天不动，最后超时；git fetch 也一样。

原因：就是网络连 GitHub 不稳，国内常态。

办法：别硬刚，去下官方 zip：https://codeload.github.com/deepseek-ai/deepseek-harness/zip/refs/heads/master，或者用文首那条 curl 命令。zip 解压和 git clone 出来的源码是一样的。

坑 ② 提示 pnpm 不是内部或外部命令

现象：敲 pnpm install，报“无法将 pnpm 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。

原因：Node 自带的是 corepack，pnpm 没启用，所以命令行里找不到。

办法：

corepack enable pnpm
corepack prepare pnpm@11.7.0 --activate

再敲 pnpm --version 能出版本号就正常了。

坑 ③ PowerShell 不让跑 pnpm.ps1

现象：pnpm.ps1 cannot be loaded because running scripts is disabled on this system。

原因：Windows 默认禁止运行脚本文件。

办法：把当前用户的执行策略放开（不用管理员）：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

不想动设置的话，把命令里的 pnpm 全改成 pnpm.cmd 也行。

坑 ④ 装好了，聊天却“没反应”

现象：网页能打开，发消息没回复；命令行模式也没输出。

原因：没配 API Key。命令行其实给了明确报错：dsh: MISSING_CREDENTIAL: llm-deepseek: no API key for provider route “deepseek-official”，意思就是“没找到密钥”。

办法：设置 → 模型里填密钥，或在 .env 里写 DEEPSEEK_API_KEY=sk-…。填完不用重启。

坑 ⑤ 输入框是灰的，发不了消息

现象：界面正常，就是底下输入框不能打字，发送键是禁用的。

原因：没选工作区。dsh 的智能体得在一个目录里干活，不选它就不开工。

办法：顶部“选择工作区”→ 添加并选中一个目录。选完输入框就亮了。

坑 ⑥ 打开是白屏，要刷新才出界面

现象：浏览器打开 http://127.0.0.1:3080 一片白，或者提示连不上。

原因：服务是“端口先开、页面后加载”，你开浏览器开太早了。

办法：等控制台打出 dsh web: http://127.0.0.1:3080 再开；已经白屏就 F5。想彻底告别白屏，用后面的一键启动脚本，它会把网页探测到能用了再开浏览器。

坑 ⑦ 端口被占

现象：启动报错说端口被占用，或者启动失败。

办法：换个端口：pnpm dsh web --port 8080，然后访问 http://127.0.0.1:8080。

坑 ⑧ 服务起来了，浏览器却不自动开

现象：命令行显示服务正常，但没有弹出浏览器。

原因：这本来就是它的设计，只打印地址，不开浏览器。

办法：自己复制地址打开，或者直接用一键快捷方式。

坑 ⑨ 火绒把我做的快捷方式/脚本删了

现象：桌面快捷方式、.dsh 文件夹里的脚本突然没了，双击图标没反应。

原因：一开始我把启动器做成了“隐藏窗口 + PowerShell 脚本”的组合，这跟木马的手法太像，火绒直接当成危险文件处理了。

办法：把脚本和快捷方式加进火绒信任区/白名单；被删了就用后面附录的恢复命令重建。别想着用什么混淆手段去“绕过”杀软，正经软件走白名单就行。

坑 ⑩ 批处理报“C:\Users\你的用户名 不是内部或外部命令”

现象：写好的 .cmd 双击运行，报“不是内部或外部命令，也不是可运行的程序”，而且命令像是被从中间截断。

原因：.cmd 文件编码和换行符不对。用 UTF-8 带 BOM 保存，第一行 @echo off 前面会藏一个看不见的字符；换行符要是 LF 而不是 CRLF，批处理会把一行命令从中间拆开执行。

办法：用“UTF-8 无 BOM + CRLF 换行”保存，脚本开头加一行 chcp 65001 >nul 防中文乱码。

坑 ⑪ 脚本以为服务“一直在跑”，其实没跑

现象：一键脚本没启动服务，直接去开浏览器，结果打不开。

原因：我用 netstat | findstr “:3080” 判断服务状态，结果 findstr 匹配到的是“目标地址行”（状态 SYN_SENT），不是“监听行”，就误判了。

办法：两级过滤 netstat -ano | findstr “:3080” | findstr “LISTENING”，或者干脆别管端口，用 curl 直接探测网页是不是返回 200，返回 200 才算真正就绪。一键脚本里用的就是后者。

坑 ⑫ start 命令开不了浏览器

现象：脚本里写了 start “” “http://127.0.0.1:3080”，双击后浏览器没反应。

原因：start 走系统“默认浏览器”，有些环境（默认浏览器被改、装了代理软件）会失灵。

办法：直接指定 Chrome 的路径来打开：

Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" "http://127.0.0.1:3080"

一键脚本里也是这么写的。

---

四、一键启动：双击就用，还不用看黑框

前面说的都是命令行，普通用户哪受得了。我做了一个“双击图标就自动启动 + 自动开 Chrome + 全程无黑框”的方案。做法和脚本都放下面，路径全部打了码，你们照着改成自己的就行。

4.1 要准备的文件

文件	作用
你的用户目录.dsh\dsh-web-launcher.cmd	一键启动器，唯一要用的脚本
你的用户目录.dsh\server.pid	后台服务进程号（自动生成，不用管）
你的安装目录\Deepseek harness	源码安装目录
桌面\DeepSeek Harness Web.lnk	桌面快捷方式
开始菜单\DeepSeek Harness Web.lnk	开始菜单快捷方式

4.2 脚本长这样（通用版，带注释）

把下面整段存成 dsh-web-launcher.cmd，改 3 个路径就能用。注释里写清楚了每处该填什么。

@echo off
chcp 65001 >nul
setlocal EnableExtensions EnableDelayedExpansion
 
rem ============================================================
rem  DeepSeek Harness 一键启动脚本（网友通用版）
rem  使用前必改 3 处：NODE、DSH_DIR、CHROME（见下方注释）
rem  改好后保存为 dsh-web-launcher.cmd，
rem  右键 → 发送到 → 桌面快捷方式，双击即用。
rem ============================================================
 
rem ① 网页地址（默认 3080，端口换了就一起改）
set "URL=http://127.0.0.1:3080"
 
rem ② Chrome 路径（绝大多数电脑是这个；不对就改成你的）
set "CHROME=C:\Program Files\Google\Chrome\Application\chrome.exe"
 
rem ③ 你的 node.exe 完整路径
rem    打开 PowerShell 输入 where node 就能看到，例如：
rem    C:\Users\你的用户名\AppData\Local\你的Node目录\node.exe
set "NODE=C:\Users\你的用户名\AppData\Local\你的Node目录\node.exe"
 
rem ④ DeepSeek Harness 安装目录（改成你解压源码的文件夹）
rem    例如：D:\AI\Deepseek harness
set "DSH_DIR=你的磁盘:\你的目录\Deepseek harness"
 
rem ⑤ 记录服务进程号的文件（用 %USERPROFILE% 自动取当前用户）
set "PIDFILE=%USERPROFILE%\.dsh\server.pid"
 
rem ---- 先看服务是不是已经在跑，在跑就直接开浏览器 ----
curl.exe -s -o nul -w "%%{http_code}" "%URL%" >"%TEMP%\dsh-http.txt" 2>nul
set /p CODE=<"%TEMP%\dsh-http.txt"
if "!CODE!"=="200" goto openbrowser
 
echo 正在后台启动 DeepSeek Harness，首次约 10-20 秒...
rem 用隐藏窗口拉起服务进程，不弹黑框
powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -Command "$p=Start-Process -FilePath %NODE% -ArgumentList @(apps\cli\lib\bin.js,web) -WorkingDirectory %DSH_DIR% -WindowStyle Hidden -PassThru; $p.Id | Out-File %PIDFILE%"
 
rem ---- 每秒探测一次，页面返回 200 才算就绪，最多等 120 秒 ----
for /l %%i in (1,1,120) do (
  timeout /t 1 /nobreak >nul
  curl.exe -s -o nul -w "%%{http_code}" "%URL%" >"%TEMP%\dsh-http.txt" 2>nul
  set /p CODE=<"%TEMP%\dsh-http.txt"
  if "!CODE!"=="200" goto openbrowser
)
echo 启动超时，请手动打开 %URL%
exit /b 1
 
:openbrowser
rem 优先用 Chrome，没有 Chrome 就用系统默认浏览器
if exist "%CHROME%" (
  start "" "%CHROME%" "%URL%"
) else (
  start "" "%URL%"
)
exit /b 0

几个地方说明一下：

NODE：必改。敲 where node 把输出的完整路径贴过来。
DSH_DIR：必改。填你解压源码的那个文件夹。
CHROME：一般不用动，Chrome 装在其他盘就改一下。

脚本里用 %USERPROFILE% 自动取当前用户，所以你不用把用户名写死在文件里，换台电脑也能用。

4.3 快捷方式怎么做（纯鼠标操作）

1. 打开资源管理器，进到 你的用户目录.dsh；

2. 右键 dsh-web-launcher.cmd → 发送到 → 桌面快捷方式；

3. 右键桌面那个新快捷方式 → 属性：

目标：你的用户目录.dsh\dsh-web-launcher.cmd；

起始位置：你的磁盘:\你的目录\Deepseek harness；

运行方式：最小化（免得双击时闪一下黑框）；

4. 确定保存。想放开始菜单，把这个快捷方式拖进去就行。

4.4 被误删了怎么恢复

用 PowerShell 跑这段，两处带“你的”的地方改一下就行：

# 把 WorkingDirectory 那行改成你自己的安装目录
$ws = New-Object -ComObject WScript.Shell
$t1 = Join-Path ([Environment]::GetFolderPath("Desktop")) "DeepSeek Harness Web.lnk"
$t2 = "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\DeepSeek Harness Web.lnk"
foreach ($t in @($t1, $t2)) {
  $sc = $ws.CreateShortcut($t)
  $sc.TargetPath = "$env:USERPROFILE\.dsh\dsh-web-launcher.cmd"
  $sc.WorkingDirectory = "你的磁盘:\你的目录\Deepseek harness"
  $sc.WindowStyle = 7   # 7 表示最小化
  $sc.Save()
}

4.5 想停掉后台服务怎么办

因为服务是隐藏进程，没有窗口可以关。两种办法：任务管理器里结束命令行带 apps\cli\lib\bin.js 的 node 进程，或者干脆重启电脑。放心，只关浏览器页面不会停服务，下次打开还是秒进。

4.6 关于这个方案的小结

这套方案是我从“隐藏窗口 + PowerShell 脚本”一路改过来的。第一版被火绒直接删了（坑 ⑨），第二版会留个最小化黑框，第三版才做到完全隐藏 + 双击即用。中间还因为 .cmd 编码和端口检测写错，来回折腾了好几次（坑 ⑩、坑 ⑪）。写出来就是希望大家别再踩我踩过的坑。

---

五、几个常见问题速查

问题	原因	办法
pnpm 找不到	corepack 没启用	corepack enable pnpm
脚本被系统禁了	执行策略限制	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
聊天没反应	没配 API Key	设置 → 模型 填密钥
输入框灰的	没选工作区	先“选择工作区”
白屏要刷新	浏览器开太早	等服务打印地址再开 / 用一键脚本
要不要装 Python	只有 Python SDK 用得到	只用网页/命令行不用装
配置数据在哪	用户目录	C:\Users\你的用户名.dsh

---

最后说两句

装 dsh 本身真的不难，难的是三件事：网络（GitHub 拉不动）、环境（corepack 和执行策略）、还有“每次都要敲命令”的体验。前两个本文都给了办法，第三个用一键快捷方式解决。

另外再提醒一次：它还是开发者预览版，哪天更新后界面变了、配置变了都别惊讶。升级前把 C:\Users\你的用户名.dsh 整个文件夹备份一下，稳一点。

好了，就说这么多。祝你们装得顺利，少踩坑。

文中所有截图均为本地实测，涉及个人会话、密钥等信息已打码；脚本和路径都做成了通用占位，填自己的路径即可。