文档说明

本文档为 DeepSeek-Harness 官方开源智能体框架 Windows 本地完整部署教程，全程零基础、手把手、可复制执行，包含：环境准备、清理冲突、源码下载、包管理器安装、依赖安装、编译构建、WebUI 启动、常见报错排错、运行规范。

部署固定路径：E:\ai\deepseek-harness

项目特性：基于 Cordis 架构、全插件化 AI Agent 运行框架、pnpm monorepo 多包工程、必须使用 Node22+/pnpm 环境。

---

一、前置环境准备（必做）

1.1 所需软件清单

部署前必须安装以下两款工具，缺一不可：

• Git：用于拉取开源源码

• Node.js 22.x 最新版：项目指定运行引擎（不支持低版本、不支持 Node20 及以下）

1.2 环境版本标准（官方兼容）

• Node.js：^22.19.0 || >=24.0.0

• pnpm：11.x 最新稳定版

• 系统：Windows10 / Windows11 均可

1.3 终端推荐

优先使用：Windows PowerShell 或 CMD（不推荐 VSCode 内置终端，容易权限异常）

---

二、旧环境清理（避免 90% 报错）

如果之前下载过、安装过依赖、构建失败、启动报错，必须先清理，否则持续报错。

2.1 删除旧项目文件夹

路径：E:\ai\deepseek-harness
直接手动删除整个文件夹，保证目录为空。

2.2 清理全局缓存（可选，推荐）

pnpm store prune
npm cache clean -f

---

三、安装 Git 并验证

3.1 安装 Git

官网下载安装：https://git-scm.com/，默认下一步安装即可。

3.2 验证安装成功

git --version

输出版本号即为成功，例如：git version 2.45.1.windows.1

---

四、安装 Node.js 22.x

4.1 下载地址

https://nodejs.org/download/release/v22.14.0/

选择：node-v22.14.0-x64.msi

4.2 安装注意事项

• 全程默认下一步

• 务必勾选 Add to PATH（自动加入系统环境变量）

• 安装完成 必须重启终端

4.3 验证 Node 版本

node -v

成功输出：v22.14.0

---

五、安装 pnpm 包管理器（核心依赖）

本项目为 pnpm monorepo 工程，禁止使用 npm / yarn 安装依赖。

5.1 全局安装 pnpm

npm install -g pnpm

成功安装示例日志：

added 1 package in 24s

1 package is looking for funding
  run `npm fund` for details

5.2 验证 pnpm 安装

pnpm -v

成功输出：11.7.0（或更高 11.x 版本）

常见问题：提示 pnpm 不是内部命令
解决方案：关闭所有终端，重新打开 PowerShell 再重试

---

六、Git Clone 拉取完整源码

6.1 创建目录并克隆源码

执行以下命令下载完整源码到固定路径：

git clone https://github.com/deepseek-ai/deepseek-harness.git E:\ai\deepseek-harness

6.2 下载成功标准输出（参考）

Cloning into 'E:\ai\deepseek-harness'...
remote: Enumerating objects: 284496, done.
remote: Total 284496 (delta 0), reused 0 (delta 0), pack-reused 284496 (from 1)
Receiving objects: 100% (284496/284496), 110.43 MiB | 326.00 KiB/s, done.
Resolving deltas: 100% (224191/224191), done.
Updating files: 100% (7412/7412), done.

6.3 进入项目根目录

cd E:\ai\deepseek-harness

---

七、安装项目全部依赖（关键步骤）

项目为大型 Monorepo，包含 apps、packages、native、python 等多子包，必须统一 workspace 安装。

7.1 执行依赖安装

pnpm install

作用：读取根目录 package.json + pnpm-workspace.yaml，自动批量安装所有子包依赖。

禁止操作：不要单独进子文件夹 install、不要 npm install、不要 yarn install

---

八、全局补全缺失依赖（解决 99% 构建报错）

官方开源版默认缺失部分构建依赖，必须手动全局安装，否则 build 报错。

pnpm add -D unrun -w
pnpm add -D tsdown -w
pnpm add -D vitest -w

参数 -w 代表 workspace 全局安装，对整个项目生效。

---

九、执行项目整体编译构建

9.1 执行 Build 编译

pnpm run build

执行逻辑：运行官方预设编译脚本，编译全部 TS 源码、打包子包、生成运行时产物。

9.2 构建成功标志

终端无报错、无红色日志、最终输出 build completed，即为编译成功。

---

十、启动 DeepSeek-Harness WebUI

10.1 启动命令

pnpm dsh web

10.2 启动成功访问地址

默认本地地址：http://127.0.0.1:3080

打开浏览器直接访问即可进入 AI Agent 可视化控制台。

10.2 服务启停规范

• 停止服务：终端按下 Ctrl + C

• 重启服务：无需重新 install / build，直接执行pnpm dsh web

---

十一、全程标准部署流程总结（最简复盘）

# 1. 环境准备
node -v
git --version
npm install -g pnpm

# 2. 拉取源码
git clone https://github.com/deepseek-ai/deepseek-harness.git E:\ai\deepseek-harness
cd E:\ai\deepseek-harness

# 3. 安装依赖 & 补全构建包
pnpm install
pnpm add -D unrun tsdown vitest -w

# 4. 编译 & 启动
pnpm run build
pnpm dsh web

---

十二、高频报错超详细解决方案

问题1：pnpm 不是内部或外部命令

原因：环境变量未刷新
方案：关闭所有终端，重新打开 PowerShell 重试

问题2：Node 版本过低、引擎不兼容

原因：项目强制要求 Node22+
方案：卸载旧 Node，重装 v22.14.0 版本

问题3：build 报错缺失 unrun / tsdown

方案：执行 pnpm add -D unrun tsdown -w 后重新 build

问题4：git clone 目录已存在

方案：手动删除 E:\ai\deepseek-harness 重新克隆

问题5：依赖安装报错、lock 冲突

方案：删除 pnpm-lock.yaml、node_modules，重新执行 pnpm install

问题6：启动后网页空白 / 接口报错

方案：必须先 build 再启动，不可直接启动

---

十三、后续模型配置说明

WebUI 启动成功后，可在系统设置中配置：

• DeepSeek 模型 Key

• 其他大模型 API

• 插件开关、Agent 推理循环配置、事件调度模式

---