DeepSeek Harness 教程：从零开始上手最受欢迎的开源 AI 智能体

DeepSeek Harness 为何受欢迎？

DeepSeek Harness 的热度攀升很快，截至本文发布时，已获得超过 160,000 颗 GitHub 星标和 18,000 次 fork。

重要原因之一是开发者发现它能在不同模型（不仅是 DeepSeek）上取得出色效果。Reddit 上的用户常提到成功配合 Qwen3.8-27b 等模型使用，尤其在编码和较长链式智能体任务中表现良好。

另一个原因是其自主性与灵活性。用户反馈 Harness 能持续推进多步任务，从错误中恢复、管理长上下文，并在无需频繁干预的情况下持续执行。其插件式设计也便于更换模型、添加工具并自定义智能体工作流，而非被固定配置所束缚。

如果您在评估 Harness 与其竞争对手，我们的 Claude Code 替代方案指南将把七个主要选项进行并列对比。

DeepSeek Harness 的关键特性

主要特性包括：

• 插件式架构：智能体的大多数组件都可通过插件扩展或替换，便于自定义您的配置。

• 本地 Web 界面：运行 dsh web 可获得基于浏览器的界面，管理模型、会话、工作区、设置与智能体。

• Python SDK：使用 deepseek-harness-sdk 可在 Python 应用、脚本、测试与自动化工作流中直接运行 Harness 智能体。

• 多家模型提供方：不局限于 DeepSeek 模型。您可使用 OpenAI、Anthropic 等提供方，或连接自有的兼容端点。

• 工具调用：智能体可调用工具执行操作，而不仅是生成文本。

• 文件与终端工具：内置读、搜、改文件的工具，并在 Linux 与 macOS 提供 Bash，在 Windows 提供 PowerShell。

• 内置网页搜索：默认配置已包含 DeepSeek 的网页搜索提供方，并与模型使用同一个 DeepSeek API 密钥。

• 代码模式：Harness 可通过基于代码的执行模式暴露工具，使智能体对工具调用的组合与执行有更强掌控力。

• Trajectory：Trajectory 视图可逐步检查智能体的行为，包括模型响应、工具调用、嵌套工具活动、时序与 token 用量。

• 智能体预设：可创建具备独立工具与提示词的不同智能体配置，并在不同会话中复用。

• 会话统计：追踪回合数、步骤数、模型耗时、工具耗时、首 token 时间与解码时间等信息。

• 子智能体：主智能体可将任务部分委派给子智能体，适合更复杂的工作流。

• 社区插件：第三方插件可加入基座模型不具备的能力。本指南中，我们使用 ModLens 添加视觉支持。

• MIT 许可：DeepSeek Harness 采用宽松的 MIT 开源许可。

最大优势在于不被单一模型、工具集或智能体类型所绑定。您可以从默认配置起步，随着不同工作流的尝试逐步添加或替换组件。

如何设置 DeepSeek Harness？

我们先安装 DeepSeek Harness，并配置后续所需的一切。将安装 Node.js、DeepSeek Harness 与 pnpm，然后添加我们的 API 密钥。

安装 Node.js

DeepSeek Harness 运行于 Node.js。由于稍后我们还会使用 ModLens 实现视觉能力，建议使用 Node.js 22.19 或更高版本。

如果您使用 Ubuntu 或 Debian，可通过以下命令安装 Node.js：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

安装完成后，检查 Node.js 与 npm 是否可用：

node --version
npm --version

我的环境显示：

v24.19.0
11.17.0

您无需与上述版本完全一致。只要使用的 Node.js 版本足够新即可。

安装 DeepSeek Harness

接下来，安装 DeepSeek Harness 本体。

官方快速开始使用 npx，但我更倾向于全局安装，这样整个指南中我们都可以直接使用 dsh 命令。

运行：

npm install -g @deepseek-ai/dsh

然后检查是否安装成功：

dsh --version

我编写本指南时使用的版本为：

0.1.0-rc.7

安装 pnpm

我们还需要 pnpm。DeepSeek Harness 在添加或移除插件时会用到它。全局安装：

npm install -g pnpm

设置 API 密钥

本教程仅需两个 API 密钥：

• DeepSeek API 密钥：用于 DeepSeek 模型及其内置网页搜索。
• Gemini API 密钥：由 ModLens 用于图像理解。

我们现在先设置 DeepSeek 密钥，因为进行编码与网页搜索只需要它；稍后添加 ModLens 视觉能力时再加入 Gemini 密钥。

关于 DeepSeek，您需要创建 DeepSeek 账户、生成 API 密钥并为账户充值。建议至少充值 2 美元，这足以测试示例且无需一次性充值太多。

获得 API 密钥后，将其加入您的环境变量。

在 Linux 或 macOS 上：

export DEEPSEEK_API_KEY="your_deepseek_api_key"

在 Windows PowerShell 上：

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

这种设置的一个好处是我们无需单独的网页搜索 API。DeepSeek Harness 已内置 DeepSeek 的网页搜索提供方，并共享相同的 DEEPSEEK_API_KEY。

您也可以稍后在 Web 界面的 Settings → Models 中添加 DeepSeek API 密钥。

如何启动 DeepSeek Harness？

配置完成后，我们即可启动 DeepSeek Harness 并打开 Web 界面。直接运行 dsh web，默认会在端口 3080 上启动浏览器界面。

在浏览器中打开地址 http://127.0.0.1:3080 即可看到界面。

接下来，创建新工作区或选择现有工作区，启动新会话，并选择您要使用的 DeepSeek 模型。 

会话就绪后，我们便可开始测试编码、网页搜索、视觉及第三方模型支持。 

如何用 DeepSeek Harness 进行编码

既然 DeepSeek Harness 已在运行，我们先测试本次配置的主要能力。让我们以一个简单的编码任务开始： 

Create a simple Python calculator with a command-line interface.

DeepSeek Harness 可直接操作文件与终端，因此它可以在工作区内创建 Python 文件、编辑代码并运行命令。

任务完成后，您应能看到生成的文件及其运行说明。

若想更好发挥 Harness 背后 DeepSeek 模型的能力，我们的 DeepSeek V4 API 教程介绍了 V4 推理模式及 Python 中的 API 参数。

如何用 DeepSeek Harness 进行网页搜索

接着测试网页搜索。无需额外配置，因为 DeepSeek Harness 已内置 DeepSeek 的网页搜索提供方。

试试这样的提示词：

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

智能体应会搜索网页，并返回带来源的摘要。 

在其运行时，打开 Trajectory 选项卡。您应能看到诸如 SUBTOOL: web_search 的工具调用。

这表明智能体确实在使用网页搜索工具，而非仅依赖模型的既有知识。默认情况下，该搜索由 deepseek-official 提供方处理，并使用我们之前配置的同一个 DEEPSEEK_API_KEY。 

如何在视觉任务中使用 DeepSeek

Harness 中的 DeepSeek 对话模型是纯文本的，无法直接理解上传的图像。要添加视觉能力，我们将使用ModLens，它在 DeepSeek 与具备视觉能力的模型之间充当桥梁。

安装 ModLens 插件

当您上传图像时，ModLens 会用视觉模型处理图像，提取有用的视觉信息，并将这些信息回传给 DeepSeek 以便其进行推理。

先将 ModLens 插件安装到 web 配置档：

dsh plugin --profile web add @liustack/modlens@3.20.0

安装完成后，ModLens 会添加 modlens_read_image 工具，并创建诸如 ``DeepSeek-V4-Flash (modlens vision)` 的模型选项。

这些模型变体允许在仍以 DeepSeek 作为主要推理模型的前提下上传图像。

注册您的视觉后端

本指南中，我们将使用 Gemini API 作为视觉后端，因此需要 Gemini API 密钥。您可以从 Gemini API 免费层开始。Google 在免费层的限额内为受支持的 Gemini 模型提供免费访问，您无需添加付款信息即可按本指南测试视觉配置。

拿到密钥后，将其加入环境变量。

在 Linux 或 macOS 上：

export GEMINI_API_KEY="your_gemini_api_key"

在 Windows PowerShell 上：

$env:GEMINI_API_KEY="your_gemini_api_key"

安装并配置 ModLens CLI

接着安装 ModLens CLI：

npm install -g @liustack/modlens

然后使用 Gemini API 密钥进行配置。

在 Linux 或 macOS 上：

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

在 Windows PowerShell 上：

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

最后检查一切是否正常：

modlens doctor

您应能看到 gemini-api 被选作提供方并显示为就绪。

使用 ModLens 测试 DeepSeek Harness

现在来测试图像理解。

在模型选择器中，选择名称中带有 (modlens vision) 的模型，例如 DeepSeek-V4-Flash (modlens vision)。

粘贴或上传一张图片，然后询问：Explain what is shown in this image.

如上例所示，DeepSeek 现在可以描述并推理上传的图像。

在幕后，ModLens 将图像发送给 Gemini 进行视觉理解，并把提取的信息回传给 DeepSeek。这意味着我们可以继续以 DeepSeek 作为主要推理模型，仅将 Gemini 用于视觉部分。

如何在 DeepSeek Harness 中使用第三方模型

最后，让我们试用其他提供方的模型。打开 Settings → Models。

在这里，您可以添加OpenAI、Anthropic 等提供方，或使用您自己的 API 凭据配置其他受支持的模型提供方。 

您也可以添加自定义提供方，以连接自托管模型或其他兼容端点。这允许配置提供方 ID、基础 URL、API 类型、凭据与模型名称等细节。 

添加提供方后，返回您的会话并在模型选择器中选择新模型。

例如，尝试以下提示：

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

上例使用第三方 Kimi-K3 模型完成编码任务，表明 DeepSeek Harness 并不限于 DeepSeek 自家模型。

您可直接在模型选择器中切换已配置的模型，无需重启 Harness 服务器，更改会应用于下一次请求。

结语

在测试 DeepSeek Harness 之后，我个人在工作流中仍更偏好 Pi Coding Agent 和 OpenCode。

DeepSeek Harness 与 Pi Coding Agent 十分相似，因为二者都围绕插件生态构建。您可以安装不同扩展，根据需要为编码智能体增加能力。这种灵活性确实有用，但就我测试的体验而言，我仍未完全理解围绕 DeepSeek Harness 的热度。整体体验与我用过的其他编码智能体相比相当常规。

我也遇到了一些令人沮丧的问题。有时智能体会在任务中途停止却不给出原因，我不得不输入 continue 才能继续。安装与配置插件也是痛点——如果您不十分清楚要做什么，这会相当困难，而当前文档帮助有限。

话虽如此，DeepSeek Harness 仍然非常新，这些问题可以理解。我预计其体验、文档与插件生态会随时间显著改善。也不排除 DeepSeek 正在打造与自家模型配合尤为出色的 harness，这或许也是外界兴奋的原因之一。