DeepSeek Harness 安装全指南：npm / 源码 / Python SDK 三种方式一次搞定

麻瓜记录Jackson

401人浏览 · 2026-08-14 15:16:44

麻瓜记录Jackson · 2026-08-14 15:16:44 发布

🚀 DeepSeek Harness 安装全指南：npm / 源码 / Python SDK 三种方式一次搞定

导读：本文面向想在本地跑起 DeepSeek Harness 的开发者，手把手教你三种安装方式——npm 一键安装、源码安装、Python SDK。每种方式适合什么人、怎么装、装完怎么验证，全部给你安排明白。全文按「前置准备 → 安装 → 验证 → 排错」的逻辑展开，跟着步骤走就行。

💡 这是什么？

在这里插入图片描述

DeepSeek Harness 是一个基于 Node.js 的 Agent 运行时：它能让 AI Agent 在你的本地项目里读写文件、执行命令、委派子代理并维护执行计划——就像一个能真正「干活」的编程助手。

官方提供了三种安装途径，先看结论：

安装方式	适合谁	产出
✅ npm 一键安装（推荐）	绝大多数用户：想最快体验 Web UI	启动 Web UI，默认 `http://127.0.0.1:3080`
🔧 源码安装	想开发插件、阅读源码、参与贡献	本地仓库 + 完整构建产物，可用 `pnpm dsh` 直接运行 TypeScript 入口
🐍 Python SDK	想在自己的 Python 程序中调用 Agent	`deepseek_harness` 包 + 内置运行时，无需系统 Node.js

一、安装前准备（前置要求）

DeepSeek Harness 的运行时基于 Node.js，官方推荐的一键安装方式不需要任何额外依赖。不同方式的依赖要求如下：

环境要求	npm 一键安装	源码安装	Python SDK
Node.js	✅ 必须	✅ 必须	❌ 不需要（SDK 自带运行时）
Git	⚪ 可选	✅ 必须	✅ 必须
pnpm	❌ 不需要	✅ 必须	❌ 不需要
Python 3.10+	❌ 不需要	❌ 不需要	✅ 必须
DeepSeek API 密钥	三种方式都需要（用于配置模型；也支持 OpenAI 兼容端点）

🗺️ 操作系统：Linux、macOS 或 Windows 均可。
补充：Python SDK 支持 Linux x64 / arm64 与 macOS 14+（arm64）。

先检查本机环境

打开终端，先确认基础环境是否就绪：

# 需要 Node.js，例如 v20+：
node -v

# 源码安装时需要 git：
git --version

📝 如果 node -v 没反应，说明 Node.js 还没装，先去 nodejs.org 下载 LTS 版本安装即可。

二、方式一：npm 一键安装（推荐）

如果你只是想快速体验 Web UI，这是最省事的路径。安装好 Node.js 后，在终端直接执行：

npx @deepseek-ai/dsh web

在这里插入图片描述

命令会启动 Web UI，首次运行会自动初始化 web 配置模板，然后打印访问地址——默认是 http://127.0.0.1:3080。

✅ 验证是否成功

在浏览器打开终端打印的地址（默认 http://127.0.0.1:3080）；
看到 DeepSeek Harness 的 Web 界面即安装成功；
⚠️ 注意：新 Web UI 在添加工作区之前不会选中任何工作区——这是正常现象，下一步会配置。

💡 小贴士

dsh 会把调用目录作为默认文件系统位置。建议先 cd 到你的项目目录，再执行上面的命令，这样后续选择工作区时最方便：

cd /path/to/your-project
npx @deepseek-ai/dsh web

三、方式二：从源码安装

适合开发插件、阅读源码或参与贡献的开发者。克隆仓库后按顺序执行：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install     # 安装依赖（需要 pnpm，可用 npm install -g pnpm 安装）
pnpm run build   # 构建包与前端产物（生产运行需要）
pnpm dsh web     # 以源码方式启动 Web UI

从源码运行时的其他入口

# 一次性运行一个任务并打印最终答案（适合脚本 / CI）
pnpm dsh --profile headless "run the tests"

# 查看实际启动的完整配置树（开发插件时很有用）
pnpm dsh --profile web --dump-config

四、方式三：Python SDK 安装

适合想在自己的 Python 程序中调用 Agent 的场景。

前置要求

Python 3.10+
Git
DeepSeek 兼容的 API 端点与凭据
一个 Agent 可以修改的隔离 workspace

安装步骤

创建虚拟环境并安装：

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

设置凭据

export DEEPSEEK_API_KEY=sk-your-key-here

# 如果模型不是默认 DeepSeek 端点，而是 OpenAI 兼容代理，还需要：
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash

✅ SDK 自带运行时，不需要系统提供 Node.js。

在自己的 Python 程序中使用

from deepseek_harness import DeepSeekHarness

📌 仓库内置的 examples/jsonrpc-agent/minimal.py 是 SDK 调用的轻量包装，可直接参考。运行后会打印 assistant 的最终回复，会话目录会收到包含模型请求与工具调用的 JSONL 日志。

五、首次配置与第一个任务

无论用哪种方式启动的 Web UI，首次使用都只需三步：

步骤	操作	说明
1️⃣ 配置模型	设置 → 模型	输入 DeepSeek API 密钥并保存。模型路由立即可用，无需重启服务器；也支持其他提供方与自定义 OpenAI 兼容端点
2️⃣ 选择工作区	点击「选择工作区」	添加启动 dsh 时所在的项目目录并选中。⚠️ 选中工作区前，会话输入框不可用
3️⃣ 运行任务	在会话中输入指令	例如 `Summarize this repository and identify its main packages.`——Agent 会读写工作区文件、运行命令、委派子代理并维护计划；超出权限策略的操作会先征求你的审批

🎯 第一个任务建议

官方快速入门指南建议：从轻量指令开始，先让 Agent 熟悉工作区，再逐步交付真实任务。

Summarize this repository and identify its main packages.

六、常用命令速查

命令	作用
`npx @deepseek-ai/dsh web`	启动 Web UI（等价于 `--profile web`）
`dsh --profile headless "任务描述"`	一次性运行一个任务，打印最终答案后退出（适合脚本 / CI）
`dsh plugin --profile <name> <pnpm 参数>`	管理某个 profile 的插件（转发给 pnpm 在 profile 目录执行）
`dsh --profile web --dump-config`	查看实际启动的完整配置树（不启动服务器）
`dsh --profile web --dump-default-config`	查看默认配置树（不含用户 patch）
`pip install deepseek-harness-sdk`	安装 Python SDK（自带运行时）

🤔 关于 Profile

web 与 headless 两个 profile 会在首次使用时从内置模板自动初始化；
其余 profile 需要通过 dsh plugin 创建；
dsh 的启动参数在前，应用参数在后，例如 dsh --profile web --port 8080 中 --port 属于 Web 应用。

七、常见问题与排错

❓ 问题 1：浏览器打不开 `http://127.0.0.1:3080`

确认终端里 dsh 进程仍在运行且没有报错；
若端口被占用，可以换一个端口：dsh --profile web --port 8080；
检查防火墙是否放行本地端口。

❓ 问题 2：npx 找不到 `@deepseek-ai/dsh` 或版本过旧

先确认 Node.js 已安装且版本较新（node -v）；
项目处于开发者预览阶段、迭代很快，必要时清空 npx 缓存后重试，或改用源码安装。

❓ 问题 3：源码安装时 `pnpm install` / `build` 失败

确认已安装 pnpm（npm install -g pnpm）；
网络受限时可为 npm / pnpm 配置镜像源；
构建要求 Node.js 版本满足仓库 package.json 的 engines 声明。

❓ 问题 4：会话输入框不可用 / Agent 无法读写文件

最常见原因：没有选择工作区——回到「选择工作区」添加并选中项目目录；
确认已在「设置 → 模型」中保存有效的 API 密钥，模型路由无需重启即可生效。

❓ 问题 5：Python SDK 运行时找不到 Node.js

SDK 自带运行时、正常情况下不需要系统 Node.js；
如果报运行时缺失，请确认安装的是与 SDK 同版本的完整包（python -m pip install deepseek-harness-sdk）；
并按官方前置要求使用 Linux x64 / arm64 或 macOS 14+（arm64）。

🎉 总结

需求	选它	一句话
最快体验	npm 一键安装	`npx @deepseek-ai/dsh web`，浏览器打开即用
二次开发 / 贡献源码	源码安装	clone → pnpm install → build → `pnpm dsh web`
写 Python 程序调用	Python SDK	`pip install deepseek-harness-sdk`，自带运行时