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 UI：运行 dsh web 可获得基于浏览器的界面，用于管理模型、会话、工作区、设置与智能体。

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

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

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

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

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

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

• 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 UI 的 Settings → Models 中添加 DeepSeek API 密钥。

如何启动 DeepSeek Harness？

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

在浏览器中打开 http://127.0.0.1:3080 即可看到 UI。

接下来，创建新工作区或选择现有工作区，开启新会话并选择您要使用的 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，这或许也是令人兴奋的原因之一。