安装与环境准备

本章介绍 三种安装方式：npm 一键安装、源码安装与 Python SDK。绝大多数用户只需第一种即可快速体验 Web UI。

安装前准备

DeepSeek Harness 的运行时基于 Node.js，官方推荐的一键安装方式不需要任何额外依赖；源码安装还需要 pnpm 与 Git；Python SDK 方式需要 Python 3.10 及以上。

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

先检查本机环境（需要 Node.js，推荐 v20+）：

node -v
# 源码安装时还需要 Git
git --version

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

安装 Node.js 后，在终端执行：

npx @deepseek-ai/dsh web

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

验证是否成功：

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

方式二：从源码安装

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

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

从源码运行时的其他入口：

pnpm dsh --profile headless "run the tests"   # 一次性运行任务并打印最终答案
pnpm dsh --profile web --dump-config         # 查看实际启动的完整配置树

方式三：Python SDK 安装

前置要求：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

设置凭据后即可在程序中调用（SDK 自带运行时，不需要系统提供 Node.js）：

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

首次配置与第一个任务

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

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

第一个任务建议从轻量指令开始：Summarize this repository and identify its main packages.，先让 agent 熟悉工作区，再逐步交付真实任务。

常用命令速查

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

常见问题与排错