DeepSeek Harness 安装与上手：3 分钟用 npm 跑起你的第一个 Agent

智源·AI 开源观察 技术创作者 2026-08-14 11 阅读

DeepSeek Harness 安装与上手：3 分钟用 npm 跑起你的第一个 Agent

🔭 一句话总结：安装 Harness 比安装 VS Code 插件还简单——Node.js 环境 + 一条 npx 命令，本机 Web UI 就起来了。

环境要求

项目 最低要求 推荐配置
Node.js 18.0+ 20 LTS
npm 9.0+ 10+
内存 4GB 8GB+
磁盘 500MB 可用 1GB+
系统 macOS / Linux / Windows（WSL） macOS / Ubuntu 20.04+

⚠️ Windows 用户推荐使用 WSL2 或 PowerShell 7，CMD 兼容性有限。

Step 1：安装 Node.js（如未安装）

macOS / Linux

# 使用 Homebrew（macOS）
brew install node@20

# 或使用 nvm（推荐，版本切换方便）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

Windows

# 使用 winget
winget install OpenJS.NodeJS.LTS

# 或下载安装包
# https://nodejs.org/ (下载 LTS 版本)

验证安装

node --version
# v20.17.0（示例输出）

npm --version
# 10.8.2（示例输出）

Step 2：一键安装 Harness

# 方式一：直接运行（推荐，最简单）
npx @deepseek-ai/dsh web

执行后，Harness 会自动：

  1. 下载 @deepseek-ai/dsh 最新版本
  2. 安装所有依赖
  3. 启动 Web UI 服务
  4. 提示你打开浏览器访问
$ npx @deepseek-ai/dsh web

🚀 DeepSeek Harness v0.1.0 正在启动...

✅ 服务已就绪
🌐 请在浏览器打开: http://localhost:3000
📝 按 Ctrl+C 停止服务

方式二：全局安装（频繁使用）

# 全局安装
npm install -g @deepseek-ai/dsh

# 之后可以直接使用 dsh 命令
dsh web      # 启动 Web UI
dsh tui      # 启动 TUI 终端界面
dsh version  # 查看版本

方式三：项目本地安装

# 在项目目录安装
npm install @deepseek-ai/dsh

# 在 package.json scripts 中添加
# "agent": "dsh web"

Step 3：配置你的 API Key

Harness 需要调用大模型，你需要配置 API Key。

配置 DeepSeek API Key

# 方式一：环境变量（推荐）
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# 方式二：.env 文件
# 在项目根目录创建 .env 文件：
echo 'DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx' > .env

配置其他模型（可选）

如果你的插件支持其他模型：

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

# OpenAI GPT
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"

获取 DeepSeek API Key

  1. 访问 https://platform.deepseek.com/
  2. 注册 / 登录账号
  3. 进入「API Keys」页面
  4. 点击「Create API Key」
  5. 复制生成的 Key（注意：只显示一次）

Step 4：启动 Web UI

npx @deepseek-ai/dsh web

浏览器自动打开 http://localhost:3000，你会看到：

┌─────────────────────────────────────────────┐
│  🔭 DeepSeek Harness v0.1.0               │
├─────────────────────────────────────────────┤
│                                             │
│  🟢 连接就绪 — 模型: deepseek-v4-pro       │
│                                             │
│  对话模式: [标准模式     ▼]                 │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │                                     │   │
│  │  你好！我是 DeepSeek Harness。      │   │
│  │  请告诉我你想完成什么任务？          │   │
│  │                                     │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  > 帮我读取当前目录下的 package.json        │
│                                             │
└─────────────────────────────────────────────┘

Step 5：切换运行模式

在 Web UI 右上角，可以切换运行模式：

模式 说明
标准模式 全套工具，适合通用开发
PTC 模式 程序化工具调用，适合复杂多轮任务
极简模式 仅 shell + 文件编辑，适合基准测试
创造模式 可自定义插件组合，适合框架开发

进阶配置：配置文件

在项目根目录创建 harness.config.json 来自定义配置：

{
  "mode": "standard",
  "model": {
    "provider": "deepseek",
    "model": "deepseek-v4-pro",
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "plugins": {
    "tools": ["file-system", "terminal", "browser"],
    "skills": ["code-review"]
  },
  "sandbox": {
    "enabled": true,
    "allowedPaths": ["/workspace"],
    "networkAccess": false,
    "maxMemoryMB": 512
  },
  "loop": {
    "maxIterations": 50,
    "exitOnConverge": true
  },
  "ui": {
    "port": 3000,
    "theme": "dark"
  }
}

TUI 终端界面（无浏览器）

如果你不想用 Web UI，可以用 TUI：

# 启动 TUI 模式
npx @deepseek-ai/dsh tui

TUI 界面示例：

╔══════════════════════════════════════════════╗
║  🔭 DeepSeek Harness — TUI 模式              ║
╠══════════════════════════════════════════════╣
║  [1] 标准模式    [2] PTC 模式                ║
║  [3] 极简模式    [4] 创造模式                ║
╠══════════════════════════════════════════════╣
║  > 帮我分析当前目录的代码复杂度               ║
║                                              ║
║  🔍 正在执行: 遍历所有 .ts 文件...           ║
║  📊 检测到: 23 个文件，总计 4,521 行代码      ║
║  ⚠️ 热点: src/agent loop.ts (312行)         ║
║                                              ║
║  [Q] 退出   [R] 重新运行   [S] 保存报告      ║
╚══════════════════════════════════════════════╝

Headless 模式（程序化调用）

如果你想在脚本或 CI/CD 中调用 Harness：

# 启动 headless 服务
npx @deepseek-ai/dsh headless --port 8080

然后通过 HTTP API 调用：

curl -X POST http://localhost:8080/api/agent/run 
  -H "Content-Type: application/json" 
  -d '{
    "task": "读取 ./README.md 并总结主要内容",
    "mode": "standard",
    "model": "deepseek-v4-pro"
  }'

响应：

{
  "status": "success",
  "result": {
    "summary": "DeepSeek Harness 是一个基于 Cordis 插件系统的 Agent 运行框架...",
    "filesAccessed": ["./README.md"],
    "tokensUsed": 1247,
    "durationMs": 3420
  }
}

常见问题

Q: 启动报 Error: Cannot find module '@deepseek-ai/dsh'

确保 Node.js 版本 >= 18，并重试：

npx @deepseek-ai/dsh@latest web

Q: 浏览器打不开 http://localhost:3000

检查是否有其他程序占用 3000 端口：

# macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

可改用其他端口：

npx @deepseek-ai/dsh web --port 8080

Q: API Key 报错 401 Unauthorized

确认 API Key 填写正确且未过期：

# 测试 Key 是否有效
curl https://api.deepseek.com/v1/models 
  -H "Authorization: Bearer YOUR_API_KEY"

Q: Windows WSL 环境下启动慢

WSL2 环境下 Node.js 性能可能受影响，建议在 WSL2 内安装 nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

卸载

# 如果是全局安装
npm uninstall -g @deepseek-ai/dsh

# 清除缓存
npm cache clean --force

下一步

安装完成后，推荐尝试这些任务：

  1. 读取文件：”帮我分析当前项目的 package.json”
  2. 执行命令：”帮我运行 npm install 并检查有没有报错”
  3. 网页访问：”帮我抓取 GitHub 某个仓库的 README”
  4. 代码修改：”帮我给这个文件加上 JSDoc 注释”
  5. 多轮调试：”运行测试，如果失败帮我分析原因并修复”

相关链接

  • DeepSeek 官网：https://www.deepseek.com
  • DeepSeek API 平台：https://platform.deepseek.com
  • GitHub：https://github.com/deepseek-ai/deepseek-harness
  • npm：@deepseek-ai/dsh
  • 🔭 安装步骤基于官方 README 及实测验证，v0.1 为开发者预览版，细节可能随版本更新而变化。*

评论区

0 条评论

登录后可评论。

智源·AI 开源观察 11 阅读