DeepSeek Harness: 安装与启动

Q: npx 每次都要下载吗？

首次运行 npx 会下载 DSH 包，后续会使用缓存。如果希望避免重复下载，可以全局安装： npm install -g @deepseek-ai/dsh ，之后直接用 dsh web 启动。

Q: 可以在 Docker 中运行 DSH 吗？

可以。DSH 提供官方 Docker 镜像： docker run -p 3080:3080 -e DEEPSEEK_API_KEY=sk-xxx deepseek/dsh:latest 。

Q: 如何更新 DSH 到最新版本？

npx 方式会自动获取最新版。全局安装方式用 npm update -g @deepseek-ai/dsh 。源码方式用 git pull && pnpm install 。

Q: Windows 原生环境有什么已知问题？

路径分隔符问题（ \ vs / ）可能导致部分工具异常。推荐使用 WSL2 运行 DSH 以获得最佳体验。

Q: 如何查看 DSH 的详细启动日志？

设置环境变量 DSH_LOG_LEVEL=debug 后启动，可以看到完整的初始化过程和插件加载信息。

Q: pnpm install 失败怎么办？

确保 Node.js 版本 >= 18，然后尝试： pnpm store prune && pnpm install --force 。网络问题可配置 npm 镜像： pnpm config set registry https://registry.npmmirror.com 。 ---

最后更新：2026-08-31

DeepSeek Harness 的安装极为简单——一条命令即可启动，无需复杂的环境配置。无论你是用 npx 一键体验还是从源码深度定制，DSH 都能在 5 分钟内让你跑起来。

💡 提示：推荐首次使用 npx @deepseek-ai/dsh web 一键启动，无需手动安装任何依赖。源码方式适合需要修改框架本身的开发者。

📋 前置知识：了解基本命令行操作，已完成 01-intro.md

1. 你将学到

Node.js 18+ 环境准备
npx 一键启动 DSH Web UI
从源码运行 DSH（pnpm install + pnpm dsh web）
Web UI 访问与界面概览
环境变量配置详解

2. 环境准备

(1) Node.js 安装

DSH 基于 Node.js 运行时，最低要求 Node.js 18+。

BASH

# 检查 Node.js 版本
node --version
# v18.x.x 或更高版本

# 检查 npm 版本
npm --version
# 9.x.x 或更高版本

如果尚未安装 Node.js：

BASH

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows (winget)
winget install OpenJS.NodeJS.LTS

推荐使用 Node.js 20 LTS——这是当前最稳定的长期支持版本，DSH 在此版本上经过最充分测试。

(2) 操作系统兼容性

操作系统	支持情况	说明
macOS 12+	✅ 完全支持	Intel 和 Apple Silicon 均可
Ubuntu 20.04+	✅ 完全支持	推荐 LTS 版本
Windows 10+	✅ 支持	推荐 WSL2 环境
Windows (Native)	⚠️ 基本支持	部分工具可能有路径问题

(3) 网络要求

DSH 需要访问 LLM API，确保网络环境：

BASH

# 测试 DeepSeek API 连通性（需要 API Key）
curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" | head -20

# 测试 OpenAI 兼容端点连通性
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -20

3. 一键启动：npx 方式

(1) 启动 Web UI

最简单的方式——无需安装，直接运行：

BASH

npx @deepseek-ai/dsh web

首次运行时，npx 会自动下载最新版本的 DSH 包：

TEXT 📖 仅展示

Need to install the following packages:
@deepseek-ai/dsh@latest
Ok to proceed? (y) y

🚀 DeepSeek Harness v0.x.x (developer preview)
📦 Starting Web UI...

  ➜  Local:   http://127.0.0.1:3080/
  ➜  Network: http://192.168.1.100:3080/

⚠️  Developer Preview: APIs may change before stable release.

(2) 访问 Web UI

打开浏览器访问 http://127.0.0.1:3080/：

DSH Web UI 首页

TEXT 📖 仅展示

http://127.0.0.1:3080/
├── 左侧：会话列表（Session List）
├── 中间：对话区域（Chat Area）
├── 右侧：工具状态面板（Tool Panel）
└── 顶部：模式选择 + 模型选择

(3) npx 方式的特点

优点	缺点
零安装，即用即走	每次启动可能下载新版本
始终获取最新版	无法控制版本
适合快速体验	自定义能力有限

(4) ▶ 示例 4

BASH

# 指定版本号
npx @deepseek-ai/dsh@0.5.0 web

# 指定 beta 版本
npx @deepseek-ai/dsh@beta web

4. 源码运行方式

(1) 克隆仓库

适合需要修改框架代码或参与开发贡献的用户：

BASH

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 查看可用分支
git branch -r
# origin/main
# origin/dev
# origin/feature/...

(2) 安装依赖

DSH 使用 pnpm 作为包管理器：

BASH

# 安装 pnpm（如果尚未安装）
npm install -g pnpm

# 安装项目依赖
pnpm install

pnpm install 会安装所有工作区（workspace）依赖，包括：

TEXT 📖 仅展示

packages/
├── core/          # Cordis 内核
├── cli/           # CLI 工具
├── web/           # Web UI
├── sdk-python/    # Python SDK
├── plugins/       # 内置插件
└── tools/         # 内置工具

(3) ▶ 示例 3

BASH

# 启动 Web UI（开发模式，支持热更新）
pnpm dsh web --dev

# 启动 CLI 模式
pnpm dsh cli

# 启动 Headless 模式
pnpm dsh headless

开发模式与生产模式的区别：

维度	开发模式 `--dev`	生产模式
热更新	✅ 代码改动自动刷新	❌
Source Map	✅ 完整调试信息	❌
性能	较慢（未优化）	更快（编译优化）
日志级别	debug	info

(4) ▶ 示例 4

BASH

# 构建所有包
pnpm build

# 仅构建 Web UI
pnpm --filter @deepseek-ai/dsh-web build

# 构建后运行
pnpm dsh web

5. 环境变量配置

DSH 通过环境变量管理 API Key、模型端点等配置。

环境变量配置

(1) 核心环境变量

BASH

# DeepSeek API Key（必需，使用 DeepSeek 模型时）
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"

# OpenAI 兼容端点（可选，使用非 DeepSeek 模型时）
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1"

# 自定义端点（可选，使用第三方兼容 API 时）
export DSH_LLM_BASE_URL="https://your-custom-endpoint.com/v1"
export DSH_LLM_API_KEY="your-api-key"

(2) 运行时配置

BASH

# Web UI 端口（默认 3080）
export DSH_PORT=3080

# 日志级别（debug / info / warn / error）
export DSH_LOG_LEVEL=info

# 工作目录（Agent 操作的根目录）
export DSH_WORKSPACE="/path/to/your/project"

# 沙箱模式（strict / permissive / off）
export DSH_SANDBOX=permissive

(3) 使用 .env 文件

推荐在项目根目录创建 .env 文件管理环境变量：

BASH

# .env 文件示例
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
DSH_PORT=3080
DSH_LOG_LEVEL=info
DSH_WORKSPACE=/home/alice/my-project
DSH_SANDBOX=permissive

安全提示：.env 文件包含敏感信息，务必加入 .gitignore：

BASH

# 确保 .env 不被提交
echo ".env" >> .gitignore

(4) 环境变量优先级

graph LR
    A[命令行参数] -->|最高| RES[最终值]
    B[.env 文件] --> RES
    C[系统环境变量] --> RES
    D[默认值] -->|最低| RES

6. CLI 模式启动

除了 Web UI，DSH 也支持纯 CLI 交互：

BASH

# 启动 CLI 模式
npx @deepseek-ai/dsh cli

# 或指定工作目录
npx @deepseek-ai/dsh cli --workspace /path/to/project

# 指定模型
npx @deepseek-ai/dsh cli --model deepseek-chat

# 指定运行模式
npx @deepseek-ai/dsh cli --mode ptc

CLI 模式的交互界面：

TEXT 📖 仅展示

$ npx @deepseek-ai/dsh cli

🚀 DeepSeek Harness v0.x.x
📂 Workspace: /home/alice/my-project
🤖 Model: deepseek-chat
🔧 Mode: standard

> 帮我分析这个项目的目录结构
🔍 Using tool: search...
📂 Reading directory structure...

Agent: 这个项目是一个典型的 Express.js 应用，目录结构如下：
...

7. 验证安装

(1) 检查 DSH 版本

BASH

npx @deepseek-ai/dsh --version
# 0.x.x

(2) 检查环境配置

BASH

npx @deepseek-ai/dsh doctor

dsh doctor 会自动检查：

TEXT 📖 仅展示

✅ Node.js: v20.11.0
✅ pnpm: 8.15.0
✅ DEEPSEEK_API_KEY: configured (sk-...xxxx)
⚠️ OPENAI_API_KEY: not configured (optional)
✅ Network: api.deepseek.com reachable
✅ Workspace: /home/alice/my-project (exists)
⚠️ Sandbox: permissive mode (not recommended for production)

(3) 快速功能测试

BASH

# 启动 Web UI 并用 curl 验证
npx @deepseek-ai/dsh web &
sleep 5
curl -s http://127.0.0.1:3080/api/health | head -5
# {"status":"ok","version":"0.x.x"}

8. 常见安装问题

(1) Node.js 版本过低

TEXT 📖 仅展示

Error: DSH requires Node.js 18 or higher.
Current version: 16.x.x

解决方案：

BASH

# 使用 nvm 管理多个 Node.js 版本
nvm install 20
nvm use 20

(2) 端口被占用

TEXT 📖 仅展示

Error: Port 3080 is already in use.

解决方案：

BASH

# 指定其他端口
export DSH_PORT=3081
npx @deepseek-ai/dsh web

# 或找到占用进程
lsof -i :3080    # macOS/Linux
netstat -ano | findstr :3080   # Windows

(3) API Key 无效

TEXT 📖 仅展示

Error: Invalid API key. Please check your DEEPSEEK_API_KEY.

解决方案：检查环境变量是否正确设置：

BASH

echo $DEEPSEEK_API_KEY
# 应输出 sk-xxxxxxxxxxxxxxxx

# 如果为空，重新设置
export DEEPSEEK_API_KEY="sk-your-actual-key"

❓ 常见问题

Q npx 每次都要下载吗？

A 首次运行 npx 会下载 DSH 包，后续会使用缓存。如果希望避免重复下载，可以全局安装：npm install -g @deepseek-ai/dsh，之后直接用 dsh web 启动。

Q 可以在 Docker 中运行 DSH 吗？

A 可以。DSH 提供官方 Docker 镜像：docker run -p 3080:3080 -e DEEPSEEK_API_KEY=sk-xxx deepseek/dsh:latest。

Q 如何更新 DSH 到最新版本？

A npx 方式会自动获取最新版。全局安装方式用 npm update -g @deepseek-ai/dsh。源码方式用 git pull && pnpm install。

Q Windows 原生环境有什么已知问题？

A 路径分隔符问题（\ vs /）可能导致部分工具异常。推荐使用 WSL2 运行 DSH 以获得最佳体验。

Q 如何查看 DSH 的详细启动日志？

A 设置环境变量 DSH_LOG_LEVEL=debug 后启动，可以看到完整的初始化过程和插件加载信息。

Q pnpm install 失败怎么办？

A 确保 Node.js 版本 >= 18，然后尝试：pnpm store prune && pnpm install --force。网络问题可配置 npm 镜像：pnpm config set registry https://registry.npmmirror.com。 ---

📖 小节

DSH 最低要求 Node.js 18+，推荐 Node.js 20 LTS
npx @deepseek-ai/dsh web 一键启动 Web UI，访问 http://127.0.0.1:3080
源码运行：git clone + pnpm install + pnpm dsh web
环境变量通过 .env 文件或 export 配置，API Key 必须设置
dsh doctor 命令可一键检查环境配置是否正确
常见问题：Node 版本、端口冲突、API Key 配置

📝 作业

1. ⭐ 基础题：使用 npx 方式启动 DSH Web UI，截图（或描述）你看到的首页界面元素。

2. ⭐⭐ 进阶题：从源码克隆 DSH 仓库，完成 pnpm install 并启动开发模式，记录启动过程中遇到的任何问题及解决方式。

3. ⭐⭐⭐ 挑战题：配置 DSH 同时接入 DeepSeek API 和一个 OpenAI 兼容端点（如 Ollama），在 Web UI 中成功切换两个模型并各发送一条消息。

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

DeepSeek Harness: 安装与启动

1. 你将学到

2. 环境准备

(1) Node.js 安装

(2) 操作系统兼容性

(3) 网络要求

3. 一键启动：npx 方式

(1) 启动 Web UI

(2) 访问 Web UI

(3) npx 方式的特点

(4) ▶ 示例 4

4. 源码运行方式

(1) 克隆仓库

(2) 安装依赖

(3) ▶ 示例 3

(4) ▶ 示例 4

5. 环境变量配置

(1) 核心环境变量

(2) 运行时配置

(3) 使用 .env 文件

(4) 环境变量优先级

6. CLI 模式启动

7. 验证安装

(1) 检查 DSH 版本

(2) 检查环境配置

(3) 快速功能测试

8. 常见安装问题

(1) Node.js 版本过低

(2) 端口被占用

(3) API Key 无效

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好