DeepSeek Harness 本地运行指南：环境要求与性能实测

DeepSeek Harness 到底是什么

很多人第一次听到这个项目时容易叫错名字，把它当成 Nous Research 的 Hermes Agent。这里先纠正一个常见误区：DeepSeek^广告官方开源的 Agent 框架名叫 DeepSeek Harness（简称 DSH），用 TypeScript 编写，运行在 Node.js 之上，采用插件化的智能体架构，并针对 Prefix Cache 做了优化。而 Nous Research 的 Hermes Agent 则以 Python 为主、附带 Node（用于 MCP），两者完全是不同的项目。

关键的一点是：DSH 本身不包含大模型权重，它只是一个 Agent 调度框架。真正的推理由远程 API（如 DeepSeek API 或其他 OpenAI 兼容接口）完成，DSH 负责组装提示词、定义工具、发起 HTTP 请求、解析返回并决定是否调用工具。理解这一点，后面所有关于环境和性能的问题就都清晰了。

插件化智能体架构是指将 Agent 的各类能力（如文件读写、Shell 执行、网络搜索等）拆分成独立插件模块，框架在运行时按需加载和卸载，而不是把所有工具硬编码在主逻辑里。这样做的好处是：开发者可以只启用自己需要的工具集，降低攻击面和内存开销；也可以在不修改核心代码的情况下添加自定义工具。Prefix Cache 优化则是大模型推理侧的一项技术：当多轮对话中系统提示词（System Prompt）保持不变时，API 服务端可以缓存对这段前缀的 KV 计算结果，后续请求直接复用，从而减少重复计算、降低延迟和 Token 计费成本。DSH 在组装提示词时会刻意将系统提示与工具定义放在前缀固定位置，正是为了最大化命中这一缓存机制。

本地运行的硬性环境要求

想在本地跑起 DSH，有几个硬性门槛必须满足：

Node.js 版本：必须 >= 22.19.0，或者直接用 Node 24。Node 20 及以下会直接报错启动失败。这是最容易踩的坑，很多人卡在这一步。
包管理器：推荐 PNPM 11.7.0 以上。项目使用 CorePack，开启后会自动启用对应版本的 PNPM。
Git：用于拉取源码。
模型密钥：DeepSeek API Key，或其他 OpenAI 兼容模型的密钥。
操作系统：Windows 10 及以上、macOS、Linux、WSL2 均支持。
硬件：普通 PC 即可，不需要 GPU，因为模型推理走远程 API。

如果你想脱离云端、在本地跑大模型，可以让 DSH 对接 Ollama。但要注意，需要显卡显存的是 Ollama，而不是 DSH 本身。

CorePack 是 Node.js 官方内置的包管理器版本管理工具，从 Node 16.9 起随 Node 附带，但默认处于禁用状态。执行 corepack enable 后，它会读取项目 package.json 中的 packageManager 字段（例如 "packageManager": "pnpm@11.7.0"），自动下载并切换到指定版本的 PNPM，而无需手动全局安装。这意味着你不需要提前单独安装 PNPM——只要 Node 版本满足要求，corepack enable 一条命令就能确保包管理器版本与项目完全一致，避免因 PNPM 版本差异导致的依赖解析错误。

两种启动方式

方式一：npx 直接跑（最简单）

不用克隆源码，一行命令直接拉起 Web 界面：

npx @deepseek-ai/dsh web

启动后访问 http://127.0.0.1:3080，填入 DeepSeek API Key 即可使用。npx 模式不需要手动打包 TS 源码，因为 npm 包已经预编译好了，对新手非常友好。

方式二：源码本地开发

如果你要修改 TS 源码或做二次开发，走这条路：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm build
pnpm dsh web

源码模式下，TS 需要经过 pnpm build 编译成 JS 并打包。这一步就是 TS 转 JS 的过程。

PMPM Build

需要澄清的是：正常使用并不需要打包成单文件二进制 exe。运行时直接在 Node.js 环境里跑编译后的 JS 就行。只有当你想脱离 Node 环境、打包成独立可执行文件分发时，才需要用 pkg、--build 之类的方式，属于可选操作。

Node.js 吃性能吗？先给结论

很多人担心 Node.js 会不会拖垮电脑。结论很明确：DSH 这个 TS 框架本身几乎不吃 CPU 和显存，它只是个调度器。真正耗性能的永远是大模型推理。

Node.js 在 DSH 里做的事情——接收提示词、组装系统提示与工具定义、发 HTTP 请求、解析返回、管理会话与插件、跑 Web 界面——全部是 IO 密集型任务，而 Node.js 天生就适合 IO，CPU 占用很低。普通电脑跑 DSH 本体，CPU 通常在几个百分点，内存几十到 200MB。

反手指向本机跑 Node

这里要分清两种负载场景：

场景 A：调用 DeepSeek 云端 API。模型跑在 DeepSeek 服务器上，本机只跑 Node，几乎不耗性能，瓶颈是网络和 API 响应速度。
场景 B：对接本地 Ollama。Node 依然很轻，但 Ollama 才是吃 CPU 和显存的大户——7B 模型用 CPU 跑会很慢，显卡至少要 6G 显存；14B 模型建议 10G 以上显存。Node 进程只是在旁边发请求，资源开销可以忽略。

Node.js 的性能特点也决定了它的边界：单线程事件循环，适合 IO，不适合大量重型 CPU 计算。默认堆内存上限约 1.4G，DSH 正常使用完全够用。只有一次性加载超大文件、超长上下文时才可能触发内存溢出，这时可以手动调大：--max-old-space-size=4096。

事件循环（Event Loop） 是 Node.js 处理并发的核心机制。Node.js 运行在单线程上，但通过事件循环将 IO 操作（网络请求、文件读写）交给操作系统异步完成，主线程在等待 IO 返回期间可以继续处理其他回调，而不是阻塞等待。这使得 Node.js 在大量并发 HTTP 请求的场景下 CPU 利用率极低——非常契合 DSH 这种"发出 API 请求、等待模型返回、解析 JSON、再发下一个请求"的工作模式。代价是：一旦出现需要占用主线程的重型 CPU 计算（如解析超大 JSON、复杂字符串处理），事件循环会被阻塞，导致整个进程卡顿。因此 DSH 明确不适合在框架层做大量本地向量化或数值计算，这类任务应交给专门的服务处理。

Node.js 占内存吗？

会占，但在 DSH 的场景下占用不大。参考区间如下：

长时间运行内存观察

刚启动：50MB ~ 120MB
正常聊天、少量工具调用：100MB ~ 250MB
大量读取本地文件、上下文很大：300MB ~ 500MB

超过 500MB 的情况很少，除非一次性加载巨大文本或开很多并发会话。要强调的是，这只是 Node/DSH 进程本身，本地 Ollama 大模型的显存内存是另外单独算的，不属于 Node 进程。

Node 的内存机制是按需申请、有垃圾回收（GC）的，长时间运行内存会波动、偶尔上涨后回落。DSH 长时间连续使用可能存在缓慢的内存爬升（Node 项目常见现象），严重时重启即可释放。主要消耗点在于保存对话历史、读取本地文件内容进内存、Web 服务和插件实例。如果需要限制，可以在启动时加 --max-old-space-size=512（单位 MB）。

什么才算“普通电脑”

针对只跑 DSH + 云端 DeepSeek API 的场景，对配置几乎没要求。

什么叫普通电脑

最低配置：

CPU：双核以上，2015 年后的 Intel i3 / AMD 大多满足
内存：4G 即可，DSH 本身只占几十到 200MB
系统：Windows 10/11、macOS、Linux
硬盘：空闲 1G 以上（存放 node_modules 和源码）

日常推荐配置： i5 / R5 级别四核 CPU，8G 以上内存。现在主流笔记本台式机标配 8G，同时开浏览器、VSCode、DSH 毫无压力。哪怕是轻薄本，只要 8G 内存、对接 DeepSeek API，就完全够用。

但如果你要本地跑 Ollama，就不在“普通电脑”范畴了：7B 模型至少 8G 内存、有独显更好；14B 模型建议 16G 内存加独显。这部分开销属于 Ollama，与 Node/DSH 无关。

2010 年前的老电脑、2G 内存的迷你主机不推荐——不是跑不了 DSH，而是系统本身就卡了。

安全与选型提醒

有两个坑必须提醒：

Node 版本别用 22.18 及以下，否则直接启动失败。
DSH 可以执行本地 Shell 命令、读写文件，权限风险很高。Windows 原生 PowerShell 可以跑，但部分 Shell 工具沙盒推荐用 WSL2，且不要在生产主机上直接裸跑。

和 Python 版的 Hermes Agent 相比，两者都是 IO 为主，但 Python 的基础开销比 Node 略高一点。DSH 用 TS + Node，在模型频繁来回调用工具时，响应会更顺滑一些，不过个人使用感受差距不大。

对多数个人用户来说，DSH 的门槛其实很低：一台能正常上网、能跑 Node 22 的电脑就够了。把资源焦虑留给大模型推理，而不是这个轻量的调度框架。