安装 DeepSeek Harness（dsh）

环境要求

你需要 Node.js。仓库声明的 engines 范围是 ^22.19 || >=24，更老的运行时要么直接装不上，要么在后面以看起来像 harness bug 的方式挂掉。开始前先查一下你的版本：

node -v

走 npx 这条路，要求就这些。如果想从源码构建，还需要 git 和 pnpm——仓库是按 pnpm 配置的。本页没有任何一步要求你全局安装 dsh；在预览版变动这么快的阶段，锁在项目里的版本比一个装完就忘的全局二进制更好推理。

用 npx 快速上手

一条命令就能得到一个带 Web 界面的运行中 harness：

npx @deepseek-ai/dsh web

npm 会拉取这个包，harness 把 Web UI 提供在 http://127.0.0.1:3080。这个地址是回环地址：只在你自己的机器上响应，别处访问不到——对一个能读你的文件、能执行命令的工具来说，这是正确的默认值。

CLI 还接受 --profile 参数——dsh --profile <profile>——用来选择启动时加载哪一组插件。自带的 profile 包括 headless。请对你自己那个版本执行 dsh --help，而不是相信一份发布次日写下的清单：可用的 profile 和 bundle 恰恰是预览版会在版本之间重新洗牌的东西。

从源码运行

如果你打算写插件，多花几分钟从仓库构建是值得的，因为你能直接读到真实的包 API，而不是从 README 里猜：

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

第一次执行 pnpm dsh web 之前先跑构建——文档给出的顺序就是这样。你会进到同样在 3080 端口的 Web UI，但这次跑的是工作区代码，所以你可以改一个包、重新构建、马上看到结果。这也是搞清楚某个版本到底改了什么的最快办法，毕竟一个动得这么快的预览版，往往跑在自己的文档前面。

cordis.yml 的位置

dsh 的组织思想是一切皆插件。模型、工具、skill、会话、沙箱、文件系统、agent 循环、编排和用户界面，全都是加载进同一个共享运行时的插件。这个运行时就是 Cordis，harness 所构建于其上的元框架；@deepseek-ai/cordis 是每个 harness 包的 peer dependency。

加载哪些插件、以什么参数加载，由一份 cordis.yml 加载器配置决定：

# cordis.yml
plugins:
  dsh-example-plugin:

plugins: 下的每个 key 对应一个插件；下面那块是该插件的配置，如果默认值够用也可以什么都不写。官方包以 @deepseek-ai/dsh-<name> 发布，加载器的 key 一般是去掉 npm scope 后的包名。插件作者有时会另选 key，所以你要装的那个插件的 README 优先于任何经验法则——包括这一条。

添加一个社区插件

添加插件分两步：装包，然后在加载器配置里注册。

npm install dsh-example-plugin

# cordis.yml
plugins:
  dsh-example-plugin:

重启 harness，插件就会和其他插件一起加载。想找值得装的东西，可以浏览收录的 7900 个仓库，或者按分类缩小范围。其中 3942 个是已验证的——意思是我们在仓库里找到了对 Cordis 运行时的依赖或一份 cordis.yml，所以它们确实能加载。其余的只挂了 dsh-plugin 这个 GitHub 标签，背后没有任何接线。这一点很重要，因为这个标签同时也是发现机制：如果你发布了插件，挂上标签就是让生态找到你的方式。

疑难排查

安装时报 engine 错误或语法错误

几乎总是 Node.js 太老。仓库要求 ^22.19 || >=24；低于这个版本可能在安装时失败，也可能在某个依赖深处抛出解析错误——看起来像包坏了，其实不是。查一下 node -v 然后升级；如果机器上还有别的项目需要老版本，用 nvm 或 fnm 这类版本管理器是干扰最小的做法。

3080 端口已被占用

有别的东西占着这个端口——常见的是上一次没退干净的 dsh 进程。在 macOS 或 Linux 上这样找：

lsof -i :3080

停掉那个进程再启动。如果你宁可挪 harness 也不想动另一个服务，请去查 dsh --help 和你 cordis.yml 里 web 插件的配置项，别去猜参数名：预览版的参数面还在变，上周某篇博客里能用的参数，在你的构建里可能根本不存在。

上周还好好的，现在不行了

这是开发者预览版预期之内的失效方式，不是什么谜团。README 直说了破坏兼容性的变更就要来，而按旧加载器格式写的插件，在 harness 升级后可能悄无声息地不再加载。两个习惯有帮助：锁住你测试过的版本；在怪自己配置之前，先看看这个插件最后一次推送是什么时候——我们每个插件页都标了这个日期。

npx @deepseek-ai/dsh@<version> web

如果某个东西是真的坏了而不只是改了名，项目有 GitHub Discussions 和 Discord，在这样的一周里，它们都比任何第三方指南更及时。

常见问题

必须全局安装 dsh 吗？

不用。npx 快速上手会按需下载并运行这个包；从源码那条路则是在克隆下来的仓库里通过 pnpm 跑 CLI。因为预览版会发布破坏兼容性的变更，锁在每个项目里的版本比一个你装完就忘的全局二进制更经得起时间。

DeepSeek Harness 是免费的吗？

harness 本身以 MIT 协议开源，你可以免费运行、修改和再分发。你接的那个模型是另一回事，模型服务商收多少钱不在 harness 的协议范围内。

为什么 Web UI 监听 127.0.0.1 而不是我的网络地址？

那是回环地址，意味着这个界面只对启动它的那台机器响应。除非你刻意在前面加了代理或隧道，否则局域网里的任何设备都访问不到 http://127.0.0.1:3080——对一个能在你机器上执行命令的工具来说，这是个合理的默认值。

现在能用 dsh 做生产环境的工作吗？

不安全。DeepSeek Harness 是 2026 年 8 月 13 日发布的开发者预览版，README 用大写字母警告会有破坏兼容性的变更。把它当成用来试验、用来写插件的东西，而不是你会挂上 on-call 轮值的基础设施。

cordis.yml 到底是什么？

它是加载器配置，决定你的 harness 启动时带哪些插件、每个插件怎么配。因为 dsh 把模型、工具、skill、会话、沙箱乃至界面都当作插件，cordis.yml 实际上就是「你这套安装能做什么」的定义。

接下来看什么

如果插件这套模型对你还很陌生，先从 agent harness 到底是什么 开始——它解释了 dsh 为什么把这么多东西放在一份加载器配置后面。如果你在拿 dsh 和手头已有的工具做权衡，我们把它和 Claude Code 做了对比，包括 dsh 明显还没准备好的那些地方。