DeepSeek Harness 从零到一运行教程

本教程面向 Windows 用户，手把手教你从环境搭建到成功运行 DeepSeek Harness。

让程序员扣棣的粉丝也能跟着跑起来！

一、项目简介

DeepSeek Harness 是一个基于 Cordis 的插件式 AI 编码智能体框架，支持：

CLI 模式：命令行直接给 AI 下达任务
Web UI 模式：浏览器可视化界面与 AI 交互

二、Node.js 版本选择（重要！）

Node 版本	CLI 模式	Web UI 模式	dev:web 开发模式
22.19.x ✅	正常	正常	有兼容性问题
24.x	正常	正常	有兼容性问题

结论：推荐使用 Node 22.19.0 LTS，这是最稳定的选择。

⚠️ pnpm run dev:web 是开发者用于热更新客户端插件的命令，内部依赖 import-without-cache@0.4.0，该包在 Node 22/24 下均有兼容性问题。普通用户不需要运行此命令 ，直接用 pnpm dsh web 启动 Web UI 即可。

三、环境准备

3.1 安装 nvm-windows（Node 版本管理器）

访问 https://github.com/coreybutler/nvm-windows/releases
下载最新的 nvm-setup.exe 并安装
安装完成后，重新打开 PowerShell

3.2 安装 Node.js 22.19.0

powershell 复制代码

nvm install 22.19.0
nvm use 22.19.0

验证安装：

powershell 复制代码

node --version
# 应输出: v22.19.0

3.3 启用 pnpm

项目使用 pnpm 作为包管理器，通过 Node.js 内置的 corepack 启用：

powershell 复制代码

corepack enable
corepack prepare pnpm@11.7.0 --activate

验证：

powershell 复制代码

pnpm --version
# 应输出: 11.7.0

四、获取项目源码

powershell 复制代码

# 克隆仓库体（替换为你的仓库地址）
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness

五、安装依赖

由于国内访问 npm 官方源较慢，推荐使用npmmirror 镜像：

powershell 复制代码

pnpm install --registry=https://registry.npmmirror.com

💡 首次安装约需 5-10 分钟，取决于网络速度。安装约 923 个包。

如果看到 WARN Unsupported platform 关于 linux-arm64 或 linux-x64 的警告，可以忽略，这是因为 landlock-run 是 Linux 专用的安全沙箱，Windows 上不需要。

安装成功的标志：

复制代码

Done in XXs using pnpm v11.7.0

六、构建项目

DeepSeek Harness 是 TypeScript 项目，运行前需要先编译：

powershell 复制代码

pnpm run build

💡 构建约需 1-3 分钟。会依次编译 host 端、client 端和 Web 前端。

构建成功的标志（最后几行）：

复制代码

✔ [@deepseek-ai/dsh] Build complete in XXXXXms
✓ built in X.XXs

⚠️ 常见错误 ：如果跳过此步直接运行，会报错 Cannot find module '...lib\typert.host.js'。必须先 build！

七、配置 API Key

DeepSeek Harness 需要 DeepSeek API Key 才能运行。

7.1 获取 API Key

访问 https://platform.deepseek.com/
注册/登录账号
进入「API Keys」页面创建一个新 Key（格式为 sk-xxxx）

7.2 创建 .env 配置文件

在项目根目录 创建 .env 文件（注意开头的点号）：

powershell 复制代码

# 在 PowerShell 中创建
Set-Content -Path ".env" -Value "DEEPSEEK_API_KEY=sk-你的API密钥"

或手动创建文件，内容为：

复制代码

DEEPSEEK_API_KEY=sk-你的API密钥

⚠️ 安全提醒 ：.env 文件已在 .gitignore 中，不会被提交到 Git。请勿将 API Key 分享给他人或提交到代码仓库。

八、运行项目

方式一：CLI 命令行模式（最简单）

powershell 复制代码

pnpm dsh --profile headless "你好，请用一句话介绍自己"

成功运行后，你会看到 AI 的回复：

复制代码

你好！我是 DeepSeek Harness 的编码智能体，基于 deepseek-v4-flash 模型构建...

方式二：Web UI 浏览器模式（推荐新手）

powershell 复制代码

pnpm dsh web

启动成功后会显示：

复制代码

dsh web: http://127.0.0.1:3080

打开浏览器访问 http://127.0.0.1:3080 即可看到 Web 界面。

💡 按 Ctrl+C 停止服务。

九、完整命令速查

powershell 复制代码

# === 一次性环境搭建 ===
nvm install 22.19.0
nvm use 22.19.0
corepack enable
corepack prepare pnpm@11.7.0 --activate

# === 获取项目 ===
git clone <仓库地址>
cd deepseek-harness

# === 安装依赖（国内镜像加速） ===
pnpm install --registry=https://registry.npmmirror.com

# === 构建项目 ===
pnpm run build

# === 配置 API Key ===
Set-Content -Path ".env" -Value "DEEPSEEK_API_KEY=sk-你的密钥"

# === 运行 CLI ===
pnpm dsh --profile headless "你的任务指令"

# === 运行 Web UI ===
pnpm dsh web
# 然后浏览器打开 http://127.0.0.1:3080

十、常见问题排查

Q1: `pnpm: 无法将"pnpm"项识别为 cmdlet`

原因：pnpm 未安装或未启用。

解决：

powershell 复制代码

corepack enable
corepack prepare pnpm@11.7.0 --activate

Q2: `Cannot find module '...lib\typert.host.js'`

原因：未执行构建步骤。

解决：

powershell 复制代码

pnpm run build

Q3: `EADDRINUSE: address already in use 127.0.0.1:3080`

原因：端口 3080 被占用（可能之前的实例还在运行）。

解决：

powershell 复制代码

# 查找并关闭占用端口的进程
Stop-Process -Id (Get-NetTCPConnection -LocalPort 3080).OwningProcess -Force
# 然后重新启动
pnpm dsh web

Q4: `pnpm install` 非常慢或超时

原因：默认 npm 源在国内访问慢。

解决：使用国内镜像：

powershell 复制代码

pnpm install --registry=https://registry.npmmirror.com

Q5: `DEEPSEEK_API_KEY` 相关错误

原因：API Key 未配置或配置错误。

解决：

检查 .env 文件是否存在于项目根目录
检查内容格式是否正确：DEEPSEEK_API_KEY=sk-xxxx
确认 Key 有效（可在 DeepSeek 平台测试）

Q6: 切换 Node 版本后 pnpm 丢失

原因：每个 Node 版本有独立的 corepack 环境。

解决：切换 Node 版本后重新启用 pnpm：

powershell 复制代码

nvm use 22.19.0
corepack enable
corepack prepare pnpm@11.7.0 --activate

十一、项目结构简述

复制代码

deepseek-harness/
├── apps/
│   ├── cli/          # CLI 入口
│   └── web/          # Web 前端
├── packages/         # 核心包（200+ 个工作区包）
│   ├── core/         # 核心 API：session、tools、agent loop
│   ├── llm/          # LLM 能力：DeepSeek 提供商
│   ├── shell/        # Shell 命令执行
│   ├── fs/           # 文件系统操作
│   └── ...           # 更多功能插件
├── vendor/           # vendored Cordis 源码
├── docs/             # 文档
├── examples/         # 示例配置
└── scripts/          # 构建脚本

十二、进阶用法

使用自定义配置运行

项目支持通过 cordis.yml 自定义插件组合：

powershell 复制代码

# 使用示例配置运行
pnpm dsh --profile headless --config examples/headless-agent/cordis.yml "你的任务"

运行 Demo

powershell 复制代码

# Cordis Demo：AI 修改自身运行时
pnpm run demo:cordis

# ACP 自动化服务器
pnpm run demo:acp

总结

整个流程其实就是 5 步：

装 Node 22.19 → nvm install 22.19.0 && nvm use 22.19.0
装依赖 → pnpm install --registry=https://registry.npmmirror.com
构建 → pnpm run build
配 Key → 创建 .env 写入 DEEPSEEK_API_KEY=sk-xxx
运行 → pnpm dsh web 或 pnpm dsh --profile headless "任务"

就这么简单！

DeepSeek Harness 从零到一运行教程