摘要：DeepSeek 开源的 agent 框架 DeepSeek Harness（dsh）采用「一切皆插件」架构，目前处于开发者预览阶段。本文基于实际操作，完整演示在 Windows 下从源码安装的流程：下载源码 → 安装依赖 → 构建项目 → 启动 Web 页面 → 配置模型，每一步附命令与截图说明。适合想在本地跑起来、二次开发或研究其插件架构的前端 / Node.js 开发者。
一、背景：DeepSeek Harness 是什么
DeepSeek Harness（命令名 dsh）是 DeepSeek 开源的 agent harness（智能体框架），主打**一切皆插件（Everything is a Plugin）**的架构，底层由 Cordis 驱动。
两点先说清楚：
- 它目前处于开发者预览阶段，迭代很快，后续版本可能出现破坏兼容性的变更；
- 官方提供了两种运行方式：npm 直接运行 （
npx @deepseek-ai/dsh web，免构建）和源码运行。本文讲的是后者------适合想读源码、改代码、跟进最新提交的场景。
仓库地址：deepseek-ai/deepseek-harness
二、环境准备
- 系统：Windows 10 / 11（本文实操环境）
- Node.js：
^22.19.0 || >=24.0.0（这是仓库package.json里engines字段的硬性要求，版本低了会装不上或跑不起来） - pnpm：仓库使用 pnpm workspace 管理多包，必须用 pnpm 安装依赖
- Git：克隆仓库和后续构建都需要 git 环境（注意：即使手动下载 ZIP，构建步骤同样依赖 Git，未安装会在构建时报错，详见步骤 1 的说明）
- 磁盘空间：克隆后源码 +
node_modules体积不小，预留几个 GB
检查环境的命令：
bash
node -v
pnpm -v
git --version如果没装 pnpm：
bash
npm install -g pnpm三、源码安装步骤
步骤 1：获取源码
方式 A：命令下载（推荐）
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git方式 B：手动下载
打开仓库主页，点击绿色 Code 按钮 → Download ZIP ，解压到本地目录。适合网络环境不便或不想装 Git 的情况，但后续无法 git pull 更新。
注意：即使走手动下载 ZIP 这条路，后面的构建步骤（
pnpm install/pnpm run build）依然需要本机有 Git 环境 。构建过程会依赖 git 命令，没装 Git 的话到这一步会报错。所以除非实在没法装 Git，否则更建议直接走方式 A。手动下载的另一个不足是后续无法git pull更新。
步骤 2：进入目录
bash
cd deepseek-harness进入后能看到 apps、packages、scripts、pnpm-workspace.yaml 等目录和文件------这是一个 pnpm workspace 多包仓库。
小技巧（Windows）：在资源管理器中打开该目录后，在地址栏输入 cmd 回车，即可在当前路径直接打开命令行，不用手动 cd。
步骤 3：安装依赖
bash
pnpm install这一步会根据 pnpm-lock.yaml 拉取全部 workspace 依赖，耗时取决于网络，耐心等进度条走完。
步骤 4：构建项目
bash
pnpm run buildpnpm run build 会准备好仓库的全部构建产物（前端页面、CLI 等）。后面启动时直接使用这些产物，不会重新构建------所以这一步不能省。
步骤 5：启动 Web 页面
bash
pnpm dsh web启动成功后，默认在 http://127.0.0.1:3080 提供 Web UI，本机启动时会自动用默认浏览器打开页面。如果不想自动打开浏览器，可以加参数：
bash
pnpm dsh web --no-open
四条命令连起来就是：
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web步骤 6：配置模型
打开页面后，进入设置 → 模型进行配置：
- 配置 DeepSeek ：DeepSeek 卡片提供了一个 API 密钥字段，输入密钥并保存即可。密钥是只写的，保存后页面只会收到脱敏描述符，明文存储在本地
$DSH_HOME/.credentials.yaml中。 - 添加目录提供方：选择「添加提供方」，可选取 Anthropic、OpenAI 等，输入对应 API 密钥保存。
- 添加自定义提供方：对于自建网关或目录里没有的服务，选择「添加自定义提供方」，填写小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。凡兼容 OpenAI 协议的接口都可以走这个入口接入（例如各厂商的 OpenAI 兼容端点）。
模型变更会在下一次请求时生效，不需要重启服务器。
四、常见问题 / 避坑
Q1：pnpm install 报 Node 版本错误怎么办？
A：仓库 engines 要求 ^22.19.0 || >=24.0.0。用 node -v 检查，版本过低先升级 Node（建议用 nvm 管理多版本）。
Q2：pnpm 不是内部或外部命令？
A：没装 pnpm。执行 npm install -g pnpm，或用 corepack enable 启用 Node 自带的包管理器支持。
Q3：clone 很慢或失败？
A：网络问题。可以改用方式 B 手动下载 ZIP；或给 git 配置代理；pnpm install 慢则可以考虑切换 npm 镜像源。注意手动下载 ZIP 并不能省掉 Git------构建步骤依然依赖 git 环境，没装的话先装 Git。
Q4：手动下载 ZIP 后，pnpm run build 报 git 相关错误？
A：构建过程依赖 git 命令，手动下载的目录不是 git 仓库且本机没有 Git 环境时会失败。安装 Git 后重试；或者改用 git clone 方式获取源码。
Q5：pnpm dsh web 和 pnpm dev:web 有什么区别？
A：dsh web 直接使用 pnpm run build 产出的构建产物，不重新构建；dev:web 是开发模式（watch + 热更新），适合改源码调试。只想跑起来的，按本文流程用 dsh web 即可。
Q6：启动后浏览器没自动打开？
A：手动访问 http://127.0.0.1:3080；SSH 远程场景下按终端打印的宿主机 URL 访问。
Q7：一定要从源码装吗？
A：不需要。只是体验功能的话，官方提供了免构建方式：
bash
npx @deepseek-ai/dsh web源码安装的意义在于：能读源码、能改代码、能跟进最新提交，适合研究「一切皆插件」架构或做插件开发的开发者。
五、总结
DeepSeek Harness 的源码安装流程非常规整：clone → install → build → run 四步走，Web UI 默认跑在 3080 端口，模型在「设置 → 模型」里配置密钥即可用。整体上是一个比较标准的 pnpm workspace monorepo 工程，前端同学上手门槛不高。
值得留意的两点：一是项目处于开发者预览阶段，更新频繁，建议 git pull 后重新 pnpm install && pnpm run build；二是它的插件化架构是主要看点，后续可以尝试写一个自己的插件跑起来。具体界面与功能以官方文档和实际版本为准，有问题欢迎在评论区交流。
延伸阅读
- 官方仓库：https://github.com/deepseek-ai/deepseek-harness
- 配置模型（官方中文文档）：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/guide/providers.zh.md
- Web UI 使用指南：https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/guide/index.zh.md
- Cordis 框架：https://github.com/cordiverse/cordis