如何安装 DeepSeek Harness (dsh)：npx 一行命令、源码构建、无头模式与插件

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

DeepSeek Harness 是什么——以及它不是什么

Deep​Seek 的内部公式，经高级研究员 Chen Deli 证实，就是模型 + Harness = 智能体。模型是大脑；Harness 是将模型转变为能实际完成工作的系统所涉及的一切：上下文与记忆管理、工具调用、任务规划、文件读写、终端执行、错误反馈，以及判断任务何时完成。Deep​Seek Harness 就是这一层，于 2026 年 8 月 13 日在 MIT 许可证下开源——同一天，DeepSeek V4 Pro 0813 构建也上线了 Deep​Seek API。

两个事实决定了安装体验。首先，其架构是“一切皆插件”，建立在 Cordis（一个 TypeScript 插件容器）之上——因此你安装的是一个小型核心，外加一组提供模型适配器、工具、会话和 UI 的插件。其次，今天 npm 上的版本是0.1.0-rc.6，这是一个发布候选版本，项目自身将其标注为开发者预览版：README 以大写字母警告说，破坏兼容性的变更即将到来。人气是真实存在的——发布后 12 小时内 GitHub 星标达到 5 万，约 42 小时达到 10 万，据中国科技媒体报道，到 8 月 16 日已超过 12 万——但星标衡量的是兴趣，而非稳定性。要像规划预览版那样规划你的安装：试起来要快，丢弃时也要便宜。

开始之前：实际系统要求

唯一硬性要求是 Node.js。项目支持的引擎版本范围为 ^22.19.0 || >=24.0.0 —— 通俗来说，即 Node 22.19 或更高版本，或任意 Node 24.x。用以下命令检查你的版本：node --version。如果你使用的是较旧的 Node，npx 安装将失败或行为异常，而不会优雅降级。

其他一切都比模型优先人群所认为的更轻：

• 模型 API 密钥。 dsh 会运行真实模型；因此需要 Deep​Seek API 或你配置的任何 Open​AI 兼容提供商的密钥。首次启动后，你可以在 Web UI 中添加一个。

• pnpm——仅用于从源码构建。使用以下命令安装一次：npm install -g pnpm。

• 约1 GB可用磁盘空间，用于npm包、工作区和会话日志，再加上本地模型可能需要的空间（dsh本身不运行权重）。

• 操作系统：npm 路径适用于 Windows、macOS 和 Linux。Python SDK 的支持范围较窄（Linux x64/arm64、macOS 14+ arm64——不支持原生 Windows），详见下文。

你不需要GPU。工具链仅负责编排；模型通过API远程运行。

方法 1 — npx 一行命令（推荐几乎所有人使用）

官方的快速入门只需要一条命令，而且确实就是一条命令：

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

首次启动恰好有两个设置步骤：

• 添加模型密钥。设置 → 模型 → 输入你的 API 密钥。它存储在 $DSH_HOME/.credentials.yaml中，之后不会以明文显示。在常规安装中，DSH_HOME默认为 ~/.dsh。

• 选择工作区。添加允许 dsh 工作的项目目录。完成这两个步骤前，输入将保持锁定。

然后发送第一个任务——一个很好的冒烟测试是“总结这个仓库并识别其主要包。”如果摘要返回，并且工具调用出现在运行轨迹中，那么你的安装就正常工作了。

方法 2 — 从源代码构建

更喜欢从仓库运行？官方路径是：

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

cd deepseek-harness

pnpm install

运行 pnpm 构建

pnpm dsh web

你需要为此安装 pnpm（贡献者固定使用 pnpm 11.7.0）。在以下情况下请选择源码构建：你想运行最新的 main 分支而非已发布的候选版本；你计划阅读或修改测试框架；或者你想从仓库的 apps/cli/config/agent-presets/ 目录构建自定义预设。对于其他用户，npx 方式使用的是同一套软件，且更省事——源码构建并不会解锁 npm 包所没有的功能。

三个配置文件：web、headless 和 tui

dsh 以三种运行配置文件的形式提供，你使用哪一种取决于工作在何处进行：

• web（默认）— 端口 3080 上的完整浏览器界面。这就是npx @deepseek-ai/dsh web启动的，也是大多数人会首先安装的配置。

• headless — 只执行一个任务，然后退出。dsh --profile headless "run the test suite and report failures" 会启动会话、运行任务、写入结果，然后终止。headless 运行时明确是单任务进程：你无法在运行中途注入后续指令，修正需要针对同一工作区重新运行。这是适合集成到脚本和 CI 的配置文件。

• tui — 一个用于键盘驱动会话的终端用户界面：dsh --profile tui。

这三者共享相同的配置（~/.dsh/profiles/<name>/）以及相同的插件系统，因此将任务从 Web UI 迁移到无头模式只是更换命令，而非重新安装。

添加插件

插件管理是一等 CLI 命令，而非就地编辑：

npx @deepseek-ai/dsh plugin --profile web add <source>

来源可以是 npm 包名、GitHub 仓库（github:user/repo）、tarball 或本地文件夹。最值得先安装的是官方插件市场，它将插件发现变成 UI：

npx @deepseek-ai/dsh plugin --profile web add dshmarket

然后重启 Web 服务，并打开“设置 → Plugin Market”从目录中浏览并一键安装。有两个容易踩坑的规则：插件包会在 profile 启动时挂载，所以新添加的插件需要重启 dsh web；而单纯的 npm install并不会将插件注册到 profile 中——你必须使用 dsh plugin。这个生态还很年轻，但并非空白：由社区维护的 awesome-dsh-plugin 列表已经收录了数百个插件，涵盖 UI、技能、工具、提供商和通知等类别。

MCP、四个预设和轨迹回放

一旦你完成了基本安装，有三个功能很重要：

MCP。dsh 使用模型上下文协议，通过内置的@deepseek-ai/dsh-mcp-client插件。目前这是在文件中配置的，而不是在 UI 中：你编辑~/.dsh/profiles/web/cordis.patch.yml（或项目本地补丁）并声明每个服务器的传输方式——stdio用于本地命令，例如npx @playwright/mcp@latest，streamable-http用于远程 URL。它能用，但这是预览版中打磨最少的界面；可能会偶尔不稳定，而且没有用于开关服务器的 GUI。

预设。 dsh 每次会话加载四种代理预设之一，每种预设都代表不同的权衡取舍：

• Standard — 完整工具集：文件编辑、Shell、文件与网页检索、技能、规划、子代理、工作流。日常默认选择。

• PTC（Programmatic Tool Calling）——标准版加上 Code Mode SDK，让模型可以编写 TypeScript 程序来编排多轮工具调用。更强大，副作用也更多。

• 极简—— 仅需bash和一个文件编辑器，除此之外再无其他。专为模型基准测试与最小复现而构建；Deep​Seek V4 Flash API 文档在披露自身智能体评分时所引用的模式，正是运行于"DeepSeek Harness 极简模式"之上。

• 创建——一个运行时演练场：在内存中检查和加载 Cordis 插件，进行试验，并将可行的组合固化为新的预设。

轨迹回放。每次运行都会写入一份仅追加的会话日志——系统提示、推理过程、工具调用及其结果、子智能体调度。轨迹视图可让你按来源检查、恢复、分叉、搜索和重放一次运行。这就是智能体工作的调试器：当任务失败时，你不必重新运行并寄希望于运气；你可以重放失败的轨迹，在出错的步骤处将其分叉，并在不丢弃原始记录的情况下测试修复。

Python SDK 选项

如果你更愿意用 Python 而不是浏览器来驱动 harness，有一个官方 SDK：pip install deepseek-harness-sdk。它自带 dsh 运行时（pip wheel 里内置了 Node 运行时，因此无需单独安装 Node），用法是上下文管理器：构建一个 Deep​SeekHarness 实例，然后调用 run("task")。它会继承标准环境变量，例如 DEEPSEEK_API_KEY 和 DEEPSEEK_BASE_URL，因此更换提供商只需更改配置。但有个问题：它要求 Python 3.10+，并且仅支持 Linux x64/arm64 和 macOS 14+ arm64——没有原生的 Windows wheel；如果你以 Windows 作为主机，这确实是个短板。在 Windows 上，还是走 npm 路线吧。

将 dsh 指向您付费的模型

dsh 需要一个模型 API 密钥，并且它特意与提供商无关：设置 → 模型 接受带有 Open​AI 兼容基础 URL 的自定义提供商（在 settings.yaml 中，即 api: openai-completions、baseURL 以及一个 models 列表）。默认是 Deep​Seek 自己的 API；自定义提供商正是路由网关发挥作用的地方。

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

先把边界说清楚：OrcaRouter 托管模型的 dsh 调用；它本身并不托管 dsh。dsh 是一个本地代理运行时，由你在自己的机器上运行。

本指南在哪些方面对您不适用——预览版需要正视的问题

一个只告诉你该输入什么的安装教程只算完成了一半工作。以下是预览版今天会出错的地方，免得你凌晨两点才发现：

• 破坏性变更是一种承诺，而非警告。你正处于 0.1.0-rc.6。配置键、插件 API 和预设格式都可能随时变动。请将~/.dsh视为可丢弃状态——一次糟糕更新的代价就是重装，而在这个阶段这是可以接受的，因为安装只是一条命令。

• 你不需要 dsh 就能将 Deep​Seek 模型用作智能体。 如果你现在的唯一目标是在智能体中使用 DeepSeek V4 Flash 或 DeepSeek V4 Pro，那么 Deep​Seek 的 Anthro​pic 兼容端点已经能在 Claude Code 和其他智能体工具中直接使用，无需任何新软件。dsh 是第一方选项，并非先决条件。在明确需要原生框架之前，请跳过此安装。

• MCP 通过文件配置，且偶尔不稳定。没有 GUI，也没有按服务器启停的开关。实际使用报告称会出现间歇性故障。如果你的工作流依赖 MCP 服务器，请预留时间进行 YAML 调试。

• 插件信任是一个安全决策。第三方插件在宿主程序的核心进程中运行，安装时没有签名或来源验证。只安装你阅读过或来自可信来源的插件，并在用于实际工作前，先在一次性工作区中进行测试。danger-full-access沙盒配置文件可以修改任何可见文件——请仅将其用于一次性检出。

• 预览版存在已知缺陷。挂起的 bash 循环是一种已记录的故障模式（中断并重试），长时间运行会话的行为仍在完善中。

• 非官方桌面构建是个陷阱。一些社区封装器把 dsh 打包成点击即可安装的桌面应用，并捆绑了 Node 运行时。它们确实能用，但未经过签名，也不由 Deep​Seek 维护；如果你使用其中一个，就是在把掌握你文件系统权限的工具托付给第三方。

• 如果你需要生产稳定性，请等待非 rc 版本的发布。这个 harness 很强大，但还不够成熟。对于生产级 agent 技术栈，成熟且久经考验的 harness——或者兼容 Anthro​pic 的端点路由——才是稳妥之选，直到 dsh 达到稳定版本标签。

底线

在任何安装了 Node 22.19+ 的机器上，安装 Deep​Seek Harness 确实只需一条命令：npx @deepseek-ai/dsh web，添加模型密钥和工作区，发送一个测试任务即可。只有当你想修改或跟踪 main 分支时，才需要选择源码构建；脚本场景请使用 headless；尽早添加插件市场；并将 MCP 视为仍在开发中的功能。项目在自己的 README 中写下的坦诚告诫也同样适用：这是一个 0.1.0-rc 预览版，在通往稳定版的路上会破坏一些东西。如果你想看看 Deep​Seek 正把 agent 层带向何方，这个取舍是值得的——而它所运行的模型 DeepSeek V4 Flash 和 DeepSeek V4 Pro，今天就可以通过 OrcaRouter 以标价获得，随时准备在安装完成后为 harness 提供动力。