DeepSeek Harness（dsh）安装教程：npx / 源码 / Python SDK

Wed, 26 Aug 2026 16:17:00 +0800

DeepSeek Harness（命令行名 dsh）是 DeepSeek AI 开源的 Agent Harness：模型负责「想」，Harness 负责让 Agent 在真实环境里读文件、改代码、跑终端、管会话、走审批。官方口号是 Agent = Model + Harness，架构原则是 一切皆插件（基于 Cordis）。

官方仓库：github.com/deepseek-ai/deepseek-harness
产品页：deepseek.com/harness
npm 包：@deepseek-ai/dsh

先分清两个同名项目

网上搜「deepseek-harness」会撞上两套东西：

你要的	不是它
官方 Agent 运行时：`npx @deepseek-ai/dsh web`	PyPI 上另一个 `pip install deepseek-harness`（第三方协议客户端）
仓库：`deepseek-ai/deepseek-harness`	其它同名 fork / 批处理 CLI

本文只讲官方 dsh。

环境要求

项目	要求
操作系统	Windows 10+、macOS、主流 Linux / WSL
Node.js	`^22.19.0` 或 `>=24.0.0`。22.18 及更早、整条 23.x 都不算支持
Git / pnpm	仅源码安装需要
Python 3.10+	仅 Python SDK 需要；SDK 自带运行时，不要求系统再装 Node
API Key	DeepSeek 或其它 OpenAI 兼容端点。密钥在 Web UI 里配置即可
GPU	不需要。Harness 只编排，模型走远程 API

先检查版本：

node -v
npm -v

期望看到 v22.19.x / v24.x 或更新。若是 v20、v18 或 v22.14 这类，先升级 Node，再继续。

推荐用 nvm / fnm 切版本：

nvm install 24
nvm use 24
node -v

Windows 也可用 nodejs.org 的 LTS 安装包，或：

winget install OpenJS.NodeJS.LTS

装完 重开终端，再查 node -v。

方式一：npx 一键体验（推荐先走这条）

不永久安装，只把包拉到 npm 缓存并启动 Web UI：

npx @deepseek-ai/dsh web

建议先 cd 到你准备给 Agent 改的项目目录，再执行这条命令——默认工作区位置跟启动目录有关，后面选目录会省事。

第一次运行时：

npx 可能问是否安装 @deepseek-ai/dsh，输入 y。
终端打印本地地址，默认是 http://127.0.0.1:3080。
本机启动一般会自动打开浏览器；不想自动打开就加 --no-open。
通过 SSH 转发启动时，终端只打印宿主机 URL，本地端口由你的 SSH / 编辑器持有。

常用变体：

# 只起服务，不弹浏览器
npx @deepseek-ai/dsh web --no-open

# 查看版本
npx @deepseek-ai/dsh --version

关掉这个终端，服务通常会停。适合先玩十分钟。

方式二：全局安装（经常用再装）

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

如果提示找不到 dsh，全局 bin 没进 PATH。查一下前缀：

npm prefix -g

把输出目录下的 bin（Windows 往往是这个目录本身）加进环境变量，然后重开终端。

方式三：从源码运行（改插件 / 跟 main）

需要 Git 和 pnpm。没有 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

pnpm run build 准备仓库产物；pnpm dsh web 直接用已构建产物，不会再编一遍。

国内 clone 慢时，可改镜像或先浅克隆：

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

方式四：Python SDK（脚本 / 自动化）

官方 Python SDK 包名是 deepseek-harness-sdk（注意不是那个同名第三方包）。平台目前主要是 Linux x64 / arm64、macOS 14+ arm64。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
python -m pip install deepseek-harness-sdk

设置密钥后再跑仓库示例：

export DEEPSEEK_API_KEY=sk-your-key-here
# 走 OpenAI 兼容代理时再设：
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1

python examples/jsonrpc-agent/minimal.py \
 --workspace /absolute/path/to/workspace \
 --session-root /absolute/path/to/sessions \
 --session-id example-001 \
 "Inspect the repository and fix the failing tests."

工作区和会话目录请用绝对路径，并单独准备一个可被 Agent 改写的目录，不要直接指向生产仓库。

第一次打开 Web UI：必须做的两步

服务起来后访问 http://127.0.0.1:3080。界面能开，不代表 Agent 已经能干活——官方指南明确了顺序。

1. 配模型

打开 设置 → 模型，填入 DeepSeek API Key 并保存。保存后路由立刻生效，一般不用重启。

也可以换成其它提供方，或自定义 OpenAI 兼容端点。细节见仓库里的模型配置指南：docs/user/guide/providers.zh.md。

2. 选工作区

点 选择工作区，把你要让 Agent 操作的项目目录加进去并选中。

没选中工作区时，会话输入框不可用。 这是很多人觉得「页面开了但不能打字」的原因。

建议单独建一个练习目录，例如 ~/playground/dsh-demo，不要一上来就把家目录或重要生产仓交给它。

3. 发第一条任务

选中工作区后，开一个会话，例如：

总结这个仓库的目录结构，列出主要包和它们各自负责什么。

Agent 可以读/改工作区文件、跑命令、委派子任务、维护计划。当前权限策略要求审批时，Web UI 会先问你。

界面语言可在 Settings 里切到中文（若当前版本提供该选项）。

其它运行方式

dsh 是统一入口。源码仓库里用 pnpm dsh ...，全局安装后用 dsh ...，npx 则写成 npx @deepseek-ai/dsh ...。

# Web UI（和 dsh web 等价）
dsh --profile web

# 无头一次性任务：跑完退出
dsh --profile headless "fix the failing test"

# 查看当前组合配置树
dsh --profile web --dump-config

旧文档里的 dsh run 已经去掉，一次性任务改用 --profile headless <任务>。

四种常见运行模式（名称可能随预览版微调）：

Standard：完整编码 Agent（文件、终端、搜索、技能、计划、子 Agent 等）
Code / PTC：让模型写一段代码来编排多轮工具调用
Minimal：几乎只留 shell + 文件编辑，偏评测
Creative：检查运行时、在内存里试插件、组合新模式

常见问题

npx / node 不是内部或外部命令
Node 没装好，或装完没重开终端。Windows 必要时注销一次。

装得上但运行报错，版本看起来也是 22
确认是 22.19+。22.0–22.18 经常在 node:sqlite 或依赖的 engines 上翻车。更省事的选择是直接上 Node 24。

页面开了但不能输入
还没选工作区。

配了 Key 仍报 MISSING_CREDENTIAL / UNKNOWN_MODEL
回设置页确认保存成功、模型名写对。自定义端点还要核对 Base URL。

想停掉服务
回到启动它的终端按 Ctrl + C。

国内 npm 慢或超时
临时换镜像后再跑 npx，例如：

npm config set registry https://registry.npmmirror.com
npx @deepseek-ai/dsh web

用完可改回官方源。源码安装失败时，优先检查 Node 版本和 pnpm 是否装上，而不是反复重试同一条 npx。

Agent 乱改文件怎么办
用独立工作区；认真看审批弹窗；重要仓库先 git status / 提交再开会话。Harness 能跑 shell，权限策略挡不住你主动点「允许」。

把这篇发到你的 Hugo 站点

把本文件放到站点的内容目录，例如：

your-hugo-site/content/posts/deepseek-harness-install.md

若主题不是 PaperMod，可删掉 ShowToc / TocOpen，或把 notice shortcode 改成普通引用：

> **注意：** 当前仍是开发者预览，接口可能随时变。

本地预览：

hugo server -D

参考链接

官方仓库：https://github.com/deepseek-ai/deepseek-harness
中文 README：https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md
Web UI 指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.zh.md
产品介绍：https://www.deepseek.com/harness/
API Key：https://platform.deepseek.com/api_keys
讨论区：https://github.com/deepseek-ai/deepseek-harness/discussions
插件发现话题：https://github.com/topics/dsh-plugin

版本在预览期会频繁跳动（本文对照官方 README 与仓库 engines 字段整理于 2026-08-26）。动手前再看一眼仓库首页的 Run 小节，以仓库为准。

安装教程 on 远思码技术实验室