DeepSeek Harnessdsh使用教程从安装到 headless 任务一站式上手一句话先说清楚DeepSeek Harness 是 DeepSeek 官方开源的一个Agent 运行框架它的命令行入口叫dsh。你不用自己拼 API、写循环、管上下文它把跑一个智能体这件事打包成了几条命令。本文不堆概念直接带你把环境跑起来、把任务跑通。一、它到底是个什么东西很多人第一次听说 DeepSeek Harness会下意识把它和评测基准联想到一起。其实官方这个dsh不是评测框架而是一个Agent Harness智能体运行时。它的设计哲学只有一句话一切皆插件Everything is a Plugin底层由 Cordis 驱动。但它真正好用的地方是一个叫Profile配置方案的核心概念。你可以把一个 Profile 理解成一份运行配置里面定义了这个 Agent 要加载哪些插件、用哪个模型、系统提示词是什么。框架开箱内置了两个 Profileweb启动一个 Web 管理界面你在浏览器里管 Agent、插件和会话headless无界面模式适合跑一次性任务、嵌进脚本里。所以dsh这个命令的核心作用就一句话启动一个 Profile。后面所有命令基本都围着这件事转。⚠️ 重要提醒Harness 目前处于开发者预览Developer Preview阶段官方明确说会有不兼容的破坏性更新。生产环境慎用教程里的命令也可能随版本变化最可靠的一手资料永远是你本地装好的dsh --help。二、环境准备Node 版本是个硬门槛这是第一个坑也是最容易被忽略的。Harness 对 Node.js 版本有硬性要求^22.19.0 || 24.0.0翻译一下22.x 这条线必须是22.19.0 或更高或者直接上24.0.0 及以上23.x 全系列都不行非 LTS 且已 EOL官方直接放弃了这条线。先确认你本机的版本node-v如果你的版本低于要求比如常见的 18.x、20.x或者误装了 23.x装的时候可能不报错但一跑就出各种诡异问题。升级 Node 是最省事的解决办法。另外如果你打算从源码编译后面第三种方式还需要pnpm。官方仓库锁定pnpm11.7.0建议先打开 Corepackcorepackenable三、三种安装方式别一上来就全局装Harness 提供三种运行方式按你的使用场景选。方式一npx 一行启动最快尝鲜npx deepseek-ai/dsh webnpx会临时拉取包、跑完即释放什么都不往全局装。执行后浏览器自动打开本地界面默认地址http://127.0.0.1:3080。适合谁我就想看看这东西长啥样还没决定入坑。想加-y跳过确认也行npx -y deepseek-ai/dsh web。方式二全局安装推荐日常用npminstall-gdeepseek-ai/dsh dsh web装完之后你就有了一个dsh命令任意目录都能用后续启动不再重复下载、速度更快而且能解锁 profile 管理、插件管理等更多能力。适合谁日常开发调试、经常要起服务跑任务。验证装好没dsh--version方式三源码编译开发者 / 插件作者gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web构建这一步pnpm run build不能省否则pnpm dsh web可能起不来。构建完成后用pnpm dsh代替dsh即可参数完全一致。适合谁要改源码、调插件、做二次开发。四、第一次启动与配置 API Key无论哪种方式最终都会看到 Web UI 起来默认监听http://127.0.0.1:3080。第一次打开会弹一个内测声明毕竟还是 Developer Preview接口随时可能调点继续进主界面。接下来是关键一步——配置模型。一个全新的实例既没有模型也没选工作区这时候什么都干不了。你需要去 DeepSeek 开放平台 注册并创建一个 API Key记得账户里充一点额度把 Key 填进 Harness 的配置里。除了在界面里粘贴更推荐用环境变量省得每次重配exportDEEPSEEK_API_KEYsk-你的keydsh web配置好之后点左侧新会话就能进入对话界面开始用了。小提示地址栏里一定要用http而不是https很多网页打不开的乌龙都出在这儿。五、最常用的几条命令记住一个口诀启动用 profile任务用 headless插件用 plugin排查用 dump 和 doctor顺序永远 flag 在前。1. 启动 Web 界面dsh web# 等价于dsh--profileweb默认http://127.0.0.1:3080。不想让它自动开浏览器加--no-open要换端口加--portdsh web --no-open--port80802. 跑一次性任务headless这是我个人最高频的用法尤其写脚本和 CI 的时候dsh--profileheadless总结这个仓库的架构和主要模块Harness 会把这句话交给 Agent在无界面环境里执行跑完打印最终回答并退出。退出码很有用0任务成功非0失败或出错。所以它能直接嵌进 CI 脚本做判断dsh--profileheadless运行这个项目的单元测试if[$?-ne0];thenecho测试失败exit1fi几个实战例子dsh--profileheadless运行这个项目的测试套件报告失败的用例dsh--profileheadless检查从 API 网关到数据库的调用链路是否正常3. 插件管理Harness 的能力边界就是插件定义的不会装插件基本只能用内置功能。# 给 web profile 装一个插件转发给 pnpmdsh plugin--profilewebadd插件名# 卸载dsh plugin--profileweb remove插件名# 更新dsh plugin--profileweb update插件名# 查看某个依赖的来源dsh plugin--profileweb why插件名⚠️插件装完必须重启 profile 才生效。当前跑着的实例不会热加载新插件停掉重新dsh --profile web启动才会生效。很多人装完发现怎么没变化其实就是没重启。想让别人能搜到你的插件给仓库打上dsh-plugin这个 topic 即可。4. 配置排查三件套dsh --dump-default-config# 看出厂默认配置dsh --dump-config# 看叠加你的配置后最终生效的配置dsh--patchconfig-patch.json--profileweb# 启动时用补丁文件临时覆盖配置不改文件排查顺序建议先看--dump-config实际生效了啥 → 再--dump-default-config对比差异 → 最后用--patch临时验证。绝大多数配置问题能在这个流程里定位。--patch有个细节它是整体替换目标行的 config 值不是深度合并里面的键。别指望它能只改某个嵌套字段。六、最容易踩的坑参数顺序这是 Harness 最反直觉、也是坑最狠的一条规则。启动器自己的 flag--profile、--patch、各种 config dump必须写在最前面应用参数写在后面。正确的dsh--profileweb--port8080# --port 是 web 应用的参数 ✓dsh--profileheadlessrun the tests# 任务文本是应用参数 ✓错误的dsh--port8080--profileweb# 错--port 会被当成应用参数启动器看不到 --profiledsh总结仓库--profileheadless# 错任务文本跑到启动器参数前面了判断口诀就一句所有以-开头的启动器参数全部放在任务描述前面。把dsh后面的 flag 写完最后再放位置参数比如任务描述字符串就不会出问题。这条规则最恶心的地方在于——顺序错了不一定报错而是静默地做了跟你预期不同的事。这种 bug 最难查。七、环境变量与常见问题速查问题解决办法提示--profile is required命令里漏了 profile直接用dsh web即可提示pnpm not foundnpm install -g pnpm装一下浏览器打不开网页确认地址是http://127.0.0.1:3080是 http 不是 https执行任务报缺少密钥先export DEEPSEEK_API_KEY...网页端口被占用换端口例如dsh web --port 8080装完插件没反应重启 profile停掉重新dsh --profile web几个有用的环境变量DEEPSEEK_API_KEYDeepSeek API 密钥必填DSH_TELEMETRY_DISABLED设为任意非空值如1可关闭遥测上报。八、Windows 用户特别注意dsh是个标准 npm 包装和跑的命令在 macOS / Linux / Windows 上是一致的。但跑起来之后差异就来了主要集中在沙箱sandbox后端上——Windows 有已知的沙箱 bugmacOS 和 Linux 没有。在 Windows 上让 dsh 写文件系统之前建议先读官方 Windows 指南避免它误删或卡死在你的目录里。九、完整命令速查表命令作用dsh web启动 Web 界面等价于dsh --profile webdsh --profile name启动指定名字的 profiledsh --profile headless 任务跑一次性任务打印结果后退出dsh plugin --profile p add/remove/update/why 插件管理 profile 的插件转发给 pnpmdsh --help启动器自己的帮助dsh --profile web --helpWeb 应用自己的参数帮助dsh --dump-default-config打印内置默认配置dsh --dump-config打印叠加后最终生效的配置dsh --patch file --profile web用一次性覆盖层启动不改文件dsh --version显示版本号此外Harness 也支持通过MCP 协议对外暴露能力供 Claude Desktop 等 MCP 客户端调用具体 endpoint 和 SDK 用法以你安装版本的官方文档和dsh --help为准。十、小结半小时足够你建立整套肌肉记忆建议按这个顺序练一遍npx deepseek-ai/dsh web起界面逛一圈跑一个dsh --profile headless ...任务感受退出码dsh plugin --profile web add装一个插件重启看效果dsh --dump-config看看配置长啥样。Harness 还在快速演进命令会变但最核心的几个东西——Profile、插件、headless 任务——大概率不会变。抓住这几个概念后面怎么更新你都不会迷路。遇到诡异问题先跑一遍dsh --help和配置排查三件套能挡掉一半以上的环境问题。本文基于 deepseek-ai/deepseek-harness 官方 README 及社区实践整理。Harness 处于开发者预览阶段命令可能随版本变化实操时请以你本地dsh --help的输出为准。