DeepSeek Harness 安装与测试全攻略（dsh 命令行 + Web UI 实战）

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

适用系统：Windows / macOS / Linux 当前版本：@deepseek-ai/dsh v0.1.7-rc.2 更新时间：2026-09-28

一、DeepSeek Harness 是什么

DeepSeek Harness（深度求索官方 Agent 编排框架）是 DeepSeek 官方开源的 Agent 运行时 / 插件化 Harness，其命令行工具名为 dsh。

它把一个个"插件包（plugin bundle）"按固定顺序叠加成不同的 Profile（配置层），从而启动不同形态的 Agent 应用：

本文带你从零完成 安装 → 验证 → 配置 API Key → 跑通测试 的完整闭环。

二、环境准备

2.1 安装 Node.js（必须）

dsh 基于 Node.js 运行，需要 Node.js 18 LTS 及以上版本（推荐 20/22 LTS）。

打开终端验证是否已安装：

node –version
npm –version

• 若已显示版本号（如 v22.22.2），跳过下一步。
• 若提示 command not found，前往官网下载安装 LTS 版： 👉 https://nodejs.org/zh-cn/download

Windows 用户建议安装时勾选 “Automatically install the necessary tools”，并把 Node 加入 PATH。

三、三种安装方式（按需选择）

方式一：npm 全局安装（推荐新手）

最省事的方式，装完即可在任意目录使用 dsh 命令：

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

# 验证版本
dsh –version

预期输出：

0.1.7-rc.2

国内网络慢可加镜像加速：

npm install -g @deepseek-ai/dsh –registry=https://registry.npmmirror.com

方式二：npx 临时使用（不想污染全局环境）

# 不安装，直接拉取并启动 Web UI
npx @deepseek-ai/dsh web

适合只是想临时试用一下的情况。

方式三：源码安装（开发者 / 需要定制）

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

# 使用 pnpm（项目官方包管理器）
pnpm install
pnpm run build

# 启动 Web UI
pnpm dsh web

源码方式首次 pnpm install 可能耗时较长（依赖较多），请耐心等待，勿中途中断。

四、验证安装

安装完成后，先看帮助确认环境正常：

dsh –help

正常会打印出如下用法说明（节选）：

Usage: dsh [–profile] <name> [options] [app-args…]
dsh plugin –profile <name> <pnpm-args…>

Examples:
dsh web boot the web profile
dsh headless "run the tests" answer one task, print the result, and exit
dsh tui –patch ./extra.yml boot a custom profile
dsh web –help the web app's own flags and help

只要能正常打印帮助，说明 CLI 已就绪。

五、获取并配置 DeepSeek API Key

Harness 调用的是真实的 DeepSeek 大模型，必须配置 API Key。

配置 Key 有两种方式：

方式 A：环境变量（推荐命令行 / 测试用）

# Linux / macOS
export DEEPSEEK_API_KEY="sk-你的key"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk-你的key"

方式 B：Web UI 内置配置（推荐交互用）

启动 dsh web 后，首次打开页面会要求你填入 DeepSeek API Key（在 Models 页面写入，由凭证服务托管），填一次即可。

六、运行测试

6.1 Headless 命令行测试（单次任务）

dsh headless "1+1等于几？只回答数字"

成功输出：

2

再试一个稍复杂的知识问答，验证 Agent 能力：

dsh headless "用一句话说明TCP三次握手的目的"

成功输出：

TCP三次握手的目的是让通信双方在传输数据前确认彼此的收发能力正常，并同步初始序列号，从而建立一条可靠的连接。

6.2 启动 Web UI（可视化交互）

dsh web

终端会提示服务已启动，浏览器自动打开 http://127.0.0.1:3080 。 首次进入会有内测声明，点击「继续」；随后在 Models 页面填入 API Key，即可进入主界面开始对话。

6.3 启动 TUI（终端交互）

dsh tui

七、常见问题排查（Troubleshooting）

问题 1：MISSING_CREDENTIAL: no API key

原因：未配置 DEEPSEEK_API_KEY，或 Web UI 里没填 Key。 解决：按第五节配置环境变量，或在 Web UI 的 Models 页面写入 Key。

问题 2：QUOTA: Insufficient Balance

原因：Key 有效、认证通过，但 账户余额不足。 解决：去 https://platform.deepseek.com/ 充值后重试。注意此错误说明你的 Key 本身没问题。

问题 3：dsh: command not found

原因：全局安装后命令不在 PATH，或用了非全局方式安装。 解决：确认 npm install -g 成功；或改用 npx @deepseek-ai/dsh 前缀调用。

问题 4：安装过程中被中断 / 卡住

原因：依赖较多 + 网络慢。 解决：换国内镜像（–registry=https://registry.npmmirror.com），并保持终端运行直到出现 added xxx packages。

问题 5：Node 版本过低

原因：低于 18 LTS 可能运行报错。 解决：升级到 Node.js 20 / 22 LTS 后重试。

八、一键速查表

# 1. 安装
npm install -g @deepseek-ai/dsh

# 2. 验证
dsh –version

# 3. 配置 Key（Linux/macOS，Windows 用 $env:）
export DEEPSEEK_API_KEY="sk-你的key"

# 4. 命令行测试
dsh headless "你好，介绍一下你自己"

# 5. 启动 Web UI
dsh web

九、小结

本文完整覆盖了 DeepSeek Harness 的 环境准备 → npm/npx/源码三种安装 → 验证 → API Key 配置 → headless/web/tui 三种测试 → 常见报错排查。按步骤操作，几分钟内即可在本地跑通一个由 DeepSeek 模型驱动的 Agent Harness。

安全提示：API Key 等同于账户凭证，不要明文发布到公开仓库或聊天记录中；测试完成后建议到开放平台后台轮换（删除重建）Key。