DeepSeek Harness 安装教程

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.jsv22.19 及以上（官方package.json中engines声明为^22.19.0 || >=24.0.0）。

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

node--versionnpm--version

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

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

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

Windows 安装

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

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

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

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

   node--versionnpm--version

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

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

2. 解压并运行安装。

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

   nvminstall22.19.0 nvm use22.19.0node--version

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

# 用 PowerShell（管理员）执行wingetinstallSchniz.fnm# 或直接下载安装脚本后初始化fnminstall22fnm use22node--version

方式四：用 winget 直接安装

wingetinstallOpenJS.NodeJS.LTS

macOS 安装

方式一：Homebrew（推荐）

# 安装 Node.js LTSbrewinstallnode@22# 让命令可用（Homebrew 会把 @22 链接到 PATH）brewlink--overwritenode@22# 验证node--versionnpm--version

方式二：官网.pkg安装包

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

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

3. 打开终端验证：

   node--versionnpm--version

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

# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh|bash# 重新加载 shell 配置（或新开一个终端）source~/.zshrc# 若用 bash 则 source ~/.bashrc# 安装并启用某个 LTS 版本nvminstall22nvm use22node--version

方式四：用 fnm

brewinstallfnm# 在 .zshrc 里加入 eval "$(fnm env --use-on-cd)" 后重开终端fnminstall22fnm use22node--version

更新 Node.js

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

Windows

# 用 nvm-windowsnvminstall<新版本号># 例如 nvm install 24.0.0nvm use<新版本号>node--version# 或用 winget 升级winget upgrade OpenJS.NodeJS.LTS

macOS

# 用 nvm 升级nvminstall24nvm use24node--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 uninstall22.19.0# 卸载指定版本# 彻底卸载 nvm-windows：到「控制面板 → 程序」卸载 NVM for Windows

macOS —— Homebrew

brew uninstall --ignore-dependencies node@22 brew cleanuprm-rf~/.npmrm-rf~/.node-gyp

macOS —— nvm

nvm uninstall22rm-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--profileweb--port8080

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

第三步：浏览器访问

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

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--profileheadless"运行当前项目的测试"# 查看组合后的完整配置树npx @deepseek-ai/dsh--profileweb --dump-config

更新 Harness

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

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

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

npminstall-g@deepseek-ai/dsh@latest

删除 Harness

方式一：清除 npx 缓存

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

方式二：若曾全局安装过

# 查看是否全局安装npmlist-g--depth=0# 卸载npmuninstall-g@deepseek-ai/dsh

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

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

常见问题排查

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

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

gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web

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