DeepSeek Harness 下载与
完整安装教程

TL;DR30 秒快速开始

只想尽快跑起来？装好 Node.js 后，两条命令即可。无需下载本页的压缩包。

node -v                                  # 需要 v22.19.0 及以上，或 v24 / v26
npx @deepseek-ai/dsh@0.2.0-rc.2 web     # 首次运行会自动下载依赖，稍等片刻

启动后终端会打印地址 http://127.0.0.1:3080 并自动打开浏览器。随后在 设置 → 模型 填入 DeepSeek API Key，再选择工作区目录，即可开始使用。

01下载与校验

压缩包直接放在本站，可直接下载；同时给出 GitHub 官方原始地址，二者内容完全一致。

下载后校验文件完整性（强烈建议）

压缩包传输过程中可能损坏。请用下面的命令计算 SHA-256，并与上方数值逐字符比对：

# 进入下载目录
cd $HOME\Downloads

# 计算 SHA-256
Get-FileHash .\deepseek-harness-0.2.0-rc.2-source.tar.gz -Algorithm SHA256 | Format-List

certutil -hashfile deepseek-harness-0.2.0-rc.2-source.tar.gz SHA256

cd ~/Downloads
shasum -a 256 deepseek-harness-0.2.0-rc.2-source.tar.gz

cd ~/Downloads
sha256sum deepseek-harness-0.2.0-rc.2-source.tar.gz

02环境要求

先把这几项准备好，后面的步骤就不会卡住。

如果还没有 Node.js

# 安装 Node.js 24 LTS
winget install OpenJS.NodeJS.LTS

# 关掉并重新打开终端后验证
node -v
npm -v

# 方式一：Homebrew
brew install node@24

# 方式二：nvm（更推荐，方便切换版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24
nvm use 24

node -v

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

# 或使用官方 NodeSource 源（Ubuntu / Debian）
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

node -v

03三条安装路线怎么选

绝大多数人只需要路线 A。想改代码、写插件再选路线 C。

04路线 A：用 npx 直接运行（推荐）

不需要下载压缩包，也不需要提前安装 pnpm。只要机器上有 Node.js 22.19+ 即可。

1. 打开终端

   Windows 用 PowerShell 或 Windows Terminal；macOS 用 Terminal；Linux 用你常用的 shell。 以下命令三平台完全一致。

2. 确认 Node 版本

   node -v

   输出应为 v22.19.0 及以上，或 v24.x / v26.x。 如果提示找不到命令，先回到 环境要求 安装 Node.js。

3. 启动 Web UI

   npx @deepseek-ai/dsh@0.2.0-rc.2 web

   首次执行会询问是否安装该包，输入 y 回车即可；随后会自动下载依赖并启动服务。 启动成功后终端会打印类似下面的地址，并自动打开默认浏览器：

   http://127.0.0.1:3080

   如果不希望自动打开浏览器（例如在远程 SSH 里），加上 --no-open：

   npx @deepseek-ai/dsh@0.2.0-rc.2 web --no-open

4. 在浏览器中打开

   访问 http://127.0.0.1:3080。若 3080 端口被占用，可以换端口：

   npx @deepseek-ai/dsh@0.2.0-rc.2 web --port 8080

5. 配置模型并开始使用

   进入 第 7 节：首次使用配置，填入 API Key、选择工作区，然后就可以对话了。

05路线 B：全局安装

适合需要反复启动、或希望在任何目录直接敲 dsh 的用户。

# 1) 全局安装（如提示权限不足，Windows 请用管理员终端，macOS/Linux 加 sudo）
npm install -g @deepseek-ai/dsh@0.2.0-rc.2

# 2) 验证版本
dsh --version          # 应输出 0.2.0-rc.2

# 3) 启动 Web UI
dsh web

之后每次启动只需在任意目录执行 dsh web。当前工作目录会被作为默认文件系统位置， 因此建议先 cd 到你想让 agent 操作的项目目录再启动。

06路线 C：用本页源码包安装（开发者）

从源码构建可以修改代码、调试内部实现、开发自己的插件。请按顺序执行，不要跳步。

第 1 步 · 解压压缩包

cd $HOME\Downloads
tar -xzf deepseek-harness-0.2.0-rc.2-source.tar.gz
cd deepseek-harness-dsh-v0.2.0-rc.2
dir

cd ~/Downloads
tar -xzf deepseek-harness-0.2.0-rc.2-source.tar.gz
cd deepseek-harness-dsh-v0.2.0-rc.2
ls

cd ~/Downloads
tar -xzf deepseek-harness-0.2.0-rc.2-source.tar.gz
cd deepseek-harness-dsh-v0.2.0-rc.2
ls

第 2 步 · 启用 pnpm（版本必须是 11.7.0）

仓库用 packageManager 字段锁定 pnpm@11.7.0。用 Corepack 是最省事的方式：

# 方式一：Corepack（Node 22/24 自带）
corepack enable
corepack prepare pnpm@11.7.0 --activate

# 如果上面提示 corepack 不存在或已被移除，用方式二：
npm install -g pnpm@11.7.0

# 验证：必须输出 11.7.0
pnpm -v

第 3 步 · 设置源码提交号（从压缩包安装时的关键一步）

构建过程会把「源码提交号」写进前端产物。GitHub 的源码压缩包不包含 .git 目录， 构建脚本会尝试执行 git rev-parse HEAD 并因此失败。显式提供提交号即可绕过：

$env:DSH_CLIENT_COMMIT_HASH = "639ed015397290b3745d163aafe02ffee4aa3f84"

export DSH_CLIENT_COMMIT_HASH=639ed015397290b3745d163aafe02ffee4aa3f84

该值就是 tag dsh-v0.2.0-rc.2 对应的提交（2026-09-29）。 注意：只对当前这个终端窗口有效，下一步必须在同一个窗口里执行。若你改用 git clone 获取源码，则不需要这一步。

第 4 步 · 安装依赖

pnpm install

这一步耗时最长，通常会下载 1 GB 以上的依赖。国内网络慢可临时指定镜像源：

pnpm install --registry=https://registry.npmmirror.com

第 5 步 · 构建

pnpm run build

构建分阶段执行：原生模块 → Host/Client 的 TypeScript 编译与打包 → 前端资源。 成功时最后一行会打印类似 build: recorded ... client artifact(s) ...。 首次构建通常需要几分钟到十几分钟。

第 6 步 · 启动

pnpm dsh web

启动后访问 http://127.0.0.1:3080。pnpm dsh 会直接复用上一步的构建产物，不会重新构建。 换端口：pnpm dsh web --port 8080。

第 7 步 · 修改代码后怎么办

• 改动了服务端 / 包源码：重新执行 pnpm run build，再 pnpm dsh web。
• 只想调前端并热更新：用 pnpm run dev:web（构建 + 启动 + 监听源文件重新打包一条龙）。
• 只想做类型检查：pnpm run typecheck。

git clone --depth 1 --branch dsh-v0.2.0-rc.2 https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

07首次使用：配置模型与工作区

服务启动后，Web UI 还不能直接干活，需要先配置模型、再选择工作区。下面三步做完即可开始。

1. 打开设置，填入 DeepSeek API Key

   在 Web UI 左侧进入 设置 → 模型，找到 DeepSeek 卡片，把 API Key 粘进去并保存。 Key 在 platform.deepseek.com 申请。

   • 保存后立即生效，不需要重启服务。
   • 密钥是只写的：页面之后只会拿到脱敏描述符，永远不会回显明文。
   • 密钥实际保存在 $DSH_HOME/.credentials.yaml，默认即 ~/.dsh/.credentials.yaml。
2. 选择工作区（Workspace）

   点击 Choose workspace，把启动 dsh 时所在的目录添加进来并选中。 没有选中工作区之前，输入框是无法使用的。

   agent 只能在你选定的工作区内读写文件、执行命令——这是它最主要的安全边界。

3. 跑第一个任务

   新建一个会话，输入一句话试试，例如：

   总结这个仓库，并说明它的主要包分别负责什么。

   agent 可以读取和修改工作区文件、执行命令、拆分并并行处理子任务、维护任务计划。 遇到需要批准的操作时，Web UI 会先弹出确认。

想用第三方模型或中转站？

设置 → 模型 → 添加模型提供商 里既可选内置提供商（如 openai、anthropic、Kimi 的 moonshotai、GLM 的 zai）， 也可以选「自定义模型 API」填写中转站 / 公司网关 / 自建服务的地址、协议与密钥。 协议支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三种。

08常见问题 FAQ

按报错信息或现象查，基本能覆盖 90% 的安装问题。

$env:DSH_CLIENT_COMMIT_HASH = "639ed015397290b3745d163aafe02ffee4aa3f84"
pnpm run build

export DSH_CLIENT_COMMIT_HASH=639ed015397290b3745d163aafe02ffee4aa3f84
pnpm run build

node -v      # 查看当前版本
nvm install 24
nvm use 24
node -v

npm install -g pnpm@11.7.0
pnpm -v      # 必须是 11.7.0

pnpm install --registry=https://registry.npmmirror.com

# macOS / Linux
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
pnpm install

# Windows PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY  = "http://127.0.0.1:7890"
pnpm install

npx @deepseek-ai/dsh@0.2.0-rc.2 web --port 8080
# 或源码方式
pnpm dsh web --port 8080

ssh -L 3080:127.0.0.1:3080 user@your-server

https://codeload.github.com/deepseek-ai/deepseek-harness/tar.gz/refs/tags/dsh-v0.2.0-rc.2

09安全与权限

dsh 是一个能真实操作你电脑的 agent，请认真读完这一节。

• 能力范围：agent 可以读取 / 修改工作区文件、执行命令、访问网络、并行委派子任务。它不是一个只读的聊天窗口。
• 审批策略：需要审批的操作会在 Web UI 中先弹确认。请保持审批开启，尤其是首次使用时。
• 工作区边界：只把需要处理的项目目录加入工作区，不要把整个用户主目录或磁盘根目录交出去。
• 密钥：API Key 保存在 ~/.dsh/.credentials.yaml，属于敏感文件，不要提交到 Git，也不要截图外发。
• 网络暴露：默认只监听 127.0.0.1，不要随意改成 0.0.0.0 暴露到公网。
• 来源可信：插件生态是开放的，只安装你信任来源的插件。

10压缩包目录结构

解压后根目录名为 deepseek-harness-dsh-v0.2.0-rc.2，各目录职责如下。

11升级与卸载

升级

npx @deepseek-ai/dsh@<新版本号> web
# 不写版本号则使用 npm 上 latest 标签的版本
npx @deepseek-ai/dsh web

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

cd 新的解压目录
export DSH_CLIENT_COMMIT_HASH=<新版本对应的提交号>   # Windows 用 $env: 写法
pnpm install
pnpm run build
pnpm dsh web

卸载

# 全局安装
npm uninstall -g @deepseek-ai/dsh

# 源码方式：直接删除解压出来的目录即可
rm -rf ~/Downloads/deepseek-harness-dsh-v0.2.0-rc.2

# 如需连配置和会话一起清除（谨慎：会删除密钥与历史记录）
rm -rf ~/.dsh

12资源与许可