DeepSeek Harness 安装教程

官方仓库：https://github.com/deepseek-ai/deepseek-harness
快速命令：npx @deepseek-ai/dsh web
默认访问地址：http://127.0.0.1:3080

DeepSeek Harness（简称 DSH）是 DeepSeek AI 开源的 Agent 运行框架。它让大模型能够真正读写本地文件、执行命令、拆分任务，是「Model + Harness = Agent」的一整套可插拔运行时。目前处于开发者预览版，需要 Node.js 环境。

---

目录

1. 第一步：安装 Node.js
   • Windows 安装
   • macOS 安装
   • 更新 Node.js
   • 删除 Node.js
2. 第二步：安装并启动 Harness
3. 第三步：浏览器访问
4. 首次使用三步配置
5. 常用维护与卸载
6. 常见问题排查

---

第一步：安装 Node.js

Harness 需要 Node.js v22.19 及以上（官方 package.json 中 engines 声明为 ^22.19.0 || >=24.0.0）。

安装前先检查本机是否已安装及其版本：

node --version
npm --version

如果能输出版本号说明已装好，直接跳到 第二步。

💡 版本管理工具（强烈推荐）
相比手动下载安装包，更推荐使用版本管理工具来安装 Node.js。它能让你随时切换、升级、多版本共存，也方便彻底卸载。

• Windows 用 nvm-windows 或 fnm
• macOS 用 nvm 或 fnm

Windows 安装

方式一：官网安装包（最省事）

1. 访问 Node.js 官网 https://nodejs.org ，下载 LTS（长期支持）版本安装包（.msi）。

2. 双击运行，一路「下一步」即可。默认会同时安装 npm 并写入系统 PATH。

3. 安装完成后，重新打开终端，验证：

   node --version
   npm --version
   

方式二：用 nvm-windows（多版本切换）

1. 到 nvm-windows 的 GitHub 发布页下载 nvm-setup.zip：https://github.com/coreybutler/nvm-windows/releases

2. 解压并运行安装。

3. 安装并启用某个 LTS 版本：

   nvm install 22.19.0
   nvm use 22.19.0
   node --version
   

方式三：用 fnm（快速且跨平台）

# 用 PowerShell（管理员）执行
winget install Schniz.fnm
# 或直接下载安装脚本后初始化

fnm install 22
fnm use 22
node --version

方式四：用 winget 直接安装

winget install OpenJS.NodeJS.LTS

macOS 安装

方式一：Homebrew（推荐）

# 安装 Node.js LTS
brew install node@22

# 让命令可用（Homebrew 会把 @22 链接到 PATH）
brew link --overwrite node@22

# 验证
node --version
npm --version

方式二：官网 .pkg 安装包

1. 访问 https://nodejs.org 下载 macOS LTS 的 .pkg 安装包。

2. 双击运行，按提示完成安装。

3. 打开终端验证：

   node --version
   npm --version
   

方式三：用 nvm（多版本切换）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell 配置（或新开一个终端）
source ~/.zshrc   # 若用 bash 则 source ~/.bashrc

# 安装并启用某个 LTS 版本
nvm install 22
nvm use 22
node --version

方式四：用 fnm

brew install fnm
# 在 .zshrc 里加入 eval "$(fnm env --use-on-cd)" 后重开终端
fnm install 22
fnm use 22
node --version

更新 Node.js

⚠️ 版本管理工具（nvm / fnm）会方便得多，建议优先使用。

Windows

# 用 nvm-windows
nvm install <新版本号>   # 例如 nvm install 24.0.0
nvm use <新版本号>
node --version

# 或用 winget 升级
winget upgrade OpenJS.NodeJS.LTS

macOS

# 用 nvm 升级
nvm install 24
nvm use 24
node --version

# 或用 Homebrew 升级
brew upgrade node@22

删除 Node.js

Windows —— 方式一（安装包方式）

1. 「设置 → 应用 → 已安装的应用」中找到 Node.js，点击卸载。

2. 删除残留目录（可选，用于彻底清理）：

   rd /s /q "%APPDATA%\npm"
   rd /s /q "%APPDATA%\npm-cache"
   rd /s /q "C:\Program Files\nodejs"
   

Windows —— 方式二（nvm-windows）

nvm uninstall 22.19.0   # 卸载指定版本
# 彻底卸载 nvm-windows：到「控制面板 → 程序」卸载 NVM for Windows

macOS —— Homebrew

brew uninstall --ignore-dependencies node@22
brew cleanup
rm -rf ~/.npm
rm -rf ~/.node-gyp

macOS —— nvm

nvm uninstall 22
rm -rf ~/.nvm
# 再移除 .zshrc / .bashrc 里与 nvm 相关的加载行

---

第二步：安装并启动 Harness

确认 Node.js 版本满足要求后，打开终端（Windows 用 CMD 或 PowerShell，macOS 用「终端」），执行：

npx @deepseek-ai/dsh web

首次运行会发生以下几件事：

1. npx 会询问是否安装 @deepseek-ai/dsh 包，输入 y 回车确认。
2. 自动从 npm 拉取并安装依赖（需要联网，首次可能稍慢）。
3. 下载完成后自动在本地启动 Web 服务。

快捷方式：若已全局安装过（npm install -g @deepseek-ai/dsh），可直接用 dsh web 启动。

想用别的端口（当 3080 被占用时）：

npx @deepseek-ai/dsh --profile web --port 8080

看到终端输出本地地址后，说明启动成功。保持这个终端窗口不要关闭，服务运行期间关闭终端会停止服务。

---

第三步：浏览器访问

启动成功后，打开浏览器访问：

http://127.0.0.1:3080

• 这是本地回环地址，只在本机生效，不会对外暴露，不用担心别人访问。
• 首次打开会弹出页面，让你填入模型 API Key。
• 若该页面未能打开，请先确认上面启动命令的终端窗口仍在运行。

---

首次使用三步配置

浏览器打开后，界面输入框默认是灰色的，需要先完成三步才能开始对话：

1. 配置模型 API Key
   进入 Settings → Models，在 DeepSeek 卡片中填入你的 API Key（以 sk- 开头）。没有的话到 DeepSeek 开放平台创建一个。也支持接入 OpenAI、Anthropic、Google 等近 40 家厂商或任意 OpenAI 兼容接口。

   Key 只保存在本地 $DSH_HOME/.credentials.yaml（Windows 下默认 C:\Users\<用户名>\.dsh），界面不回显明文。

2. 选择工作区
   点击 Choose workspace，添加并选中你想让 Agent 操作的项目目录。未选中前输入框不可用。

3. 派发任务
   新建会话，输入一句任务指令（例如「总结这个仓库，说明主要的包结构」），Agent 会开始读取文件、执行命令并给出结果。涉及写操作时会按权限策略弹出确认。

---

常用维护与卸载

常用命令

# 启动 Web 界面
npx @deepseek-ai/dsh web

# 用 headless 模式运行一次性任务（适合脚本 / CI）
npx @deepseek-ai/dsh --profile headless "运行当前项目的测试"

# 查看组合后的完整配置树
npx @deepseek-ai/dsh --profile web --dump-config

更新 Harness

由于用 npx 按需拉取，每次运行 npx @deepseek-ai/dsh web 时 npx 会优先使用 npm 缓存，若需要强制更新到最新版：

# 清掉 npx 缓存后重装
npx --yes @deepseek-ai/dsh@latest web

若是全局安装方式，则直接升级：

npm install -g @deepseek-ai/dsh@latest

删除 Harness

方式一：清除 npx 缓存

npm cache clean --force
npx clear-npx-cache   # 部分 npm 版本可用

方式二：若曾全局安装过

# 查看是否全局安装
npm list -g --depth=0

# 卸载
npm uninstall -g @deepseek-ai/dsh

方式三：清理本地配置与数据

删除 Harness 保存在本地的配置目录（Windows 默认为 C:\Users\<用户名>\.dsh，macOS/Linux 在 $DSH_HOME 对应目录）。删除后本地 API Key、会话记录等将一并清除，请谨慎操作。

---

常见问题排查

现象	处理方法
node: not found / 'node' 不是内部或外部命令	Node.js 未安装或未写入 PATH，重新安装或重开终端
Node.js version ... is not supported	Node 版本过低，升级到 v22.19+（见更新 Node.js）
首次 npx 卡住或下载失败	检查网络，必要时配置 npm 镜像后重试：npm config set registry https://registry.npmmirror.com
端口 3080 被占用	换端口：npx @deepseek-ai/dsh --profile web --port 8080
页面打不开	确认启动命令的终端窗口仍开着，且地址确实是 http://127.0.0.1:3080
输入框灰色无法输入	还未选择工作区，去 Choose workspace 选中目录
提示需要 API Key	进入 Settings → Models 填入以 sk- 开头的 Key

---

补充：从源码运行（可选）

如果想体验最新开发版本或参与贡献，可以克隆源码运行（需要 pnpm，用 npm install -g pnpm 安装）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

⚠️ 预览版迭代较快，接口和插件可能有破坏性变更，请留意版本兼容性。