本文介绍环境准备、三种安装启动方式与安装阶段常见故障排查，模型密钥配置、界面操作放在下一篇。
一、前置环境准备
DeepSeek Harness（命令行工具 dsh）基于 Node.js 运行，支持 Windows、macOS、Linux 操作系统。官方推荐 Node.js 版本为 22.19+ 或 24+，Node 23 版本存在兼容性问题，不建议使用。
打开终端，执行命令验证环境：
node -v
输出版本号，说明 Node.js 安装正常；如果提示“不是内部或外部命令”，需要先安装 Node.js。
- Windows：可通过 winget 安装
winget install OpenJS.NodeJS.LTS，或前往 Node.js 官网下载安装包，安装时勾选自动添加到系统PATH。 - macOS：
brew install node - Ubuntu/Debian：使用 nodesource 脚本安装对应 LTS 版本。
可选工具：
- pnpm：源码编译部署推荐使用，依赖安装速度更快；
- Git：仅源码安装场景需要；
- 模型API Key：安装本身不需要，但后续运行Agent必须准备 DeepSeek 或兼容 OpenAI 协议的模型密钥。
提示：Windows环境下，Shell伪终端相关功能存在限制，如果需要完整体验文件编辑、Shell执行，建议使用 WSL2。
二、三种安装启动方式
方式一：npx 一键快速体验（新手首选，无需全局安装）
npx 会临时拉取包，不会在系统全局写入，适合快速试用。在终端直接执行：
npx @deepseek-ai/dsh web
首次运行会自动下载依赖、初始化web配置模板。启动成功后，终端会输出访问地址，默认：http://127.0.0.1:3080 。
加上参数 --no-open，可以只启动服务，不自动打开浏览器，适合远程SSH环境：
npx @deepseek-ai/dsh web --no-open
方式二：npm全局安装（长期使用推荐）
全局安装后，任意终端可直接使用 dsh 命令，不再需要写 npx @deepseek-ai/ 前缀：
npm install -g @deepseek-ai/dsh
国内网络如果下载缓慢，可以切换镜像源：
npm install -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com
安装完成，直接启动Web界面：
dsh web
验证全局安装是否成功：
dsh --version
输出版本号即为安装成功。
方式三：源码部署（开发者，用于二次开发）
想要修改插件、阅读源码、自定义构建产物，选择源码部署。
# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
# 进入项目目录
cd deepseek-harness
# 安装依赖
pnpm install
# 编译构建项目
pnpm run build
# 启动Web服务
pnpm dsh web
构建完成后，同样访问 http://127.0.0.1:3080。源码方式适合插件开发、调试框架底层逻辑。
三、验证安装
- 执行启动命令，终端没有直接报错，并打印
Web UI started； - 浏览器打开
http://127.0.0.1:3080，正常加载 DeepSeek Harness 页面； - 页面成功进入工作台，即为安装成功。
注意：安装成功 ≠ Agent可以直接对话。模型API Key的配置、工作区选择、运行模式切换，将在《DeepSeek Harness 使用》中讲解。
四、安装阶段常见问题排查
- node不是命令
Node.js未安装，或者安装后没有重启终端；Windows安装务必勾选Add to PATH。 - dsh不是内部或外部命令
全局npm安装后未重启终端；或者npm全局路径未加入系统环境变量。 - 依赖下载超时、卡住
国内网络问题，使用npmmirror镜像安装；源码部署可更换pnpm镜像。 - 端口3080被占用
关闭占用端口的程序，或查阅文档修改监听端口。 - Windows编译报node-pty原生模块错误
需要安装Visual Studio Build Tools，并勾选C++桌面开发组件；或者改用WSL2环境。 - SSH远程服务器启动，浏览器打不开页面
使用--no-open参数，同时需要配置SSH端口转发，访问服务器3080端口。
五、卸载（可选）
全局npm安装的卸载命令：
npm uninstall -g @deepseek-ai/dsh
源码版本直接删除项目文件夹即可。
0 条笔记