DeepSeek Harness 是近期受到广泛关注的开源 AI Agent 框架。与许多功能固定的 Coding Assistant 不同，它采用了一个非常鲜明的设计理念：
Everything is a plugin，一切皆可通过 Plugin 插件扩展。
在 DeepSeek Harness 中，模型、工具、用户界面，甚至 Agent 的运行逻辑，都可以根据需求进行添加、替换或移除。本文将从零开始安装 DeepSeek Harness，并搭建一个完整的 Agent 环境：
- 使用 DeepSeek 作为主要推理模型；
- 使用 DeepSeek 内置的 Web Search 获取实时信息；
- 使用 ModLens 与 Gemini 为文本模型增加图像理解能力；
- 通过 Web UI 测试 Coding、Web Search、Vision 和第三方模型接入。
如果你还不熟悉 AI Agent 如何规划任务、调用工具并自主执行，可以先了解 Agent 的基本组成，包括模型、工具、记忆、规划和执行循环等概念。
什么是 DeepSeek Harness？
DeepSeek Harness 是 DeepSeek AI 推出的开源 AI Agent Framework，主要面向希望拥有更高控制权的开发者。
传统 Coding Assistant 往往提供一套固定的模型、工具和交互方式，用户只能在既定范围内使用。而 DeepSeek Harness 并不把开发者限制在单一工作流中，而是将系统拆分成多个可替换组件。
其核心设计可以概括为：
- 模型可以替换；
- 工具可以扩展；
- 用户界面可以更换；
- Agent 的行为和执行循环可以定制；
- 不同工作流可以通过 Agent Preset 进行复用。
因此，DeepSeek Harness 更像是一个用于构建和运行 Coding Agent 的基础平台，而不是一个只能使用固定模型的封闭式产品。
为什么 DeepSeek Harness 受到关注？
DeepSeek Harness 在发布后迅速获得开发者关注。截至原文发布时，它已经获得超过 16 万个 GitHub Stars 和 1.8 万个 Forks。
它受到欢迎的原因主要有以下几个方面。
支持多种模型
虽然项目由 DeepSeek 推出，但 DeepSeek Harness 并不只支持 DeepSeek 模型。通过 Provider 和 Plugin 机制，开发者可以接入：
- DeepSeek；
- OpenAI；
- Anthropic；
- 其他兼容的 API Endpoint；
- 自托管或本地运行的模型。
这意味着 Harness 不会强制开发者绑定某一家模型服务商。
具备较强的自主执行能力
在实际使用中，开发者通常希望 Agent 能够连续执行多步任务，而不是每完成一步都等待人工确认。
DeepSeek Harness 支持：
- 多步骤任务执行；
- 文件读取、搜索和编辑；
- Terminal 命令执行；
- 错误恢复；
- 长上下文处理；
- Subagent 委派；
- 对 Agent 执行过程进行追踪。
对于代码生成、项目重构、脚本编写和仓库分析等任务，这种自主性非常重要。
Plugin 架构便于扩展
在 Harness 中，模型、工具和 Agent 行为都可以通过 Plugin 进行扩展。开发者可以从默认配置开始，再根据实际工作流逐步添加功能，而不必一次性搭建复杂系统。
DeepSeek Harness 的核心功能
DeepSeek Harness 目前提供了以下主要能力。
Plugin-based Architecture
Harness 的大多数模块都可以通过 Plugin 扩展或替换，包括：
- Model Provider；
- Tool；
- Agent；
- Agent Loop；
- Web UI；
- Vision 能力。
这种设计让开发者能够根据不同项目构建定制化的 Agent 环境。
Local Web UI
运行 dsh web 后，可以启动本地浏览器界面，用于管理：
- Models；
- Sessions；
- Workspaces；
- Settings；
- Agents；
- Plugins。
默认情况下，Web UI 运行在 3080 端口。
Python SDK
deepseek-harness-sdk 支持在 Python 应用、脚本、测试和自动化流程中直接运行 Harness Agent。
这意味着 Harness 不仅可以通过浏览器使用，也可以集成到已有的开发工具链中。
多模型 Provider
Harness 支持多个模型服务商，也允许开发者连接自定义的兼容 Endpoint。你可以在 Web UI 中添加 OpenAI、Anthropic 或其他 Provider，并在不同模型之间切换。
Tool Calling
Agent 不仅能够生成文本，还可以调用工具执行实际操作，例如：
- 读取文件；
- 搜索代码；
- 编辑文件；
- 执行 Shell 命令；
- 搜索互联网；
- 委派任务给 Subagent。
文件和 Terminal 工具
Harness 提供了用于读取、搜索和编辑文件的工具，并支持：
- Linux 和 macOS 上的 Bash；
- Windows 上的 PowerShell。
这使它能够直接在 Workspace 中创建项目、修改代码并运行测试。
内置 Web Search
DeepSeek Harness 默认集成了 DeepSeek 的 Web Search Provider。Web Search 与 DeepSeek 模型共用同一个 DEEPSEEK_API_KEY，因此不需要额外申请独立的搜索 API Key。
Code Mode
Code Mode 允许 Agent 通过代码方式组织和执行工具调用。与逐个调用工具相比，这种方式可以让 Agent 更灵活地组合多个工具，适用于复杂任务。
Trajectory
Trajectory 页面用于查看 Agent 的详细执行过程，包括：
- 模型响应；
- Tool Call；
- 嵌套工具调用；
- 每一步的耗时；
- Token 使用量；
- Agent 当前执行状态。
这对于调试 Agent 行为、分析错误原因和优化 Prompt 非常有帮助。
Agent Preset
你可以为不同场景创建独立的 Agent 配置，每个 Preset 都可以拥有自己的：
- Tools；
- System Prompt；
- Model；
- Agent 行为。
之后可以在多个 Session 中重复使用这些预设。
Session Statistics
Harness 会记录 Session 的运行统计信息，例如：
- Turn 数量；
- Step 数量；
- Model Time；
- Tool Time；
- Time to First Token；
- Decoding Time。
Subagents
主 Agent 可以将任务的一部分委派给子 Agent。对于代码库分析、资料收集或需要并行处理的复杂工作流，Subagent 能够减少主 Agent 的负担。
Community Plugins
社区 Plugin 可以为基础模型添加额外能力。本文后面将使用 ModLens，为文本模型增加图像理解功能。
MIT License
DeepSeek Harness 采用宽松的 MIT License 开源，允许开发者自由使用、修改和部署。
安装 DeepSeek Harness
下面开始安装所需依赖，并配置 API Key。
本文会用到：
- Node.js；
- DeepSeek Harness；
- pnpm；
- DeepSeek API Key；
- Gemini API Key；
- ModLens。
安装 Node.js
DeepSeek Harness 运行在 Node.js 环境中。由于后续还需要使用 ModLens，建议安装 Node.js 22.19 或更高版本。
在 Ubuntu 或 Debian 上，可以执行：
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
官方快速开始文档使用 npx，但为了后续直接使用 dsh 命令，这里选择全局安装：
npm install -g @deepseek-ai/dsh
然后检查安装结果：
dsh --version
测试时使用的版本为：
0.1.0-rc.7
由于 DeepSeek Harness 仍处于快速迭代阶段，实际版本可能与本文不同。
安装 pnpm
在添加或删除 Plugin 时，DeepSeek Harness 会使用 pnpm。因此需要将其全局安装：
npm install -g pnpm
配置 API Key
本文需要两个 API Key：
- DeepSeek API Key：用于运行 DeepSeek 模型和内置 Web Search；
- Gemini API Key：由 ModLens 使用，用于图像理解。
首先配置 DeepSeek API Key。
你需要先注册 DeepSeek 账号、创建 API Key，并为账号充值。测试本文示例时，建议至少充值 2 美元，通常已经足够完成基本测试。
在 Linux 或 macOS 上：
export DEEPSEEK_API_KEY="your_deepseek_api_key"
在 Windows PowerShell 上：
$env:DEEPSEEK_API_KEY="your_deepseek_api_key"
DeepSeek Harness 的一个便利之处在于，Web Search 不需要单独的搜索 API。它直接使用 DeepSeek 提供的搜索服务和同一个 DEEPSEEK_API_KEY。
你也可以稍后在 Web UI 的 Settings → Models 中添加 DeepSeek API Key。
启动 DeepSeek Harness Web UI
完成配置后，运行以下命令：
dsh web
默认情况下，Web UI 会监听 3080 端口。打开浏览器并访问：
进入界面后，可以创建新的 Workspace，也可以选择已有 Workspace。接着创建一个新的 Session，并选择要使用的 DeepSeek 模型。
Session 准备完成后，就可以开始测试 Coding、Web Search、Vision 和第三方模型功能。
使用 DeepSeek Harness 完成 Coding 任务
首先测试一个简单的 Python 编程任务：
Create a simple Python calculator with a command-line interface.
DeepSeek Harness 可以直接操作 Workspace 中的文件和 Terminal，因此能够：
- 创建 Python 文件；
- 编写计算器代码；
- 修改和完善代码；
- 执行命令；
- 根据运行结果继续修复问题。
任务完成后，Workspace 中应该可以看到生成的 Python 文件以及运行说明。
这种方式与普通的代码补全不同：Agent 不只是返回代码片段，而是能够直接在工作目录中创建和执行项目文件。
使用 DeepSeek Harness 进行 Web Search
接下来测试 Web Search。由于 Harness 已经内置 DeepSeek Web Search Provider，因此无需额外配置。
可以输入类似下面的 Prompt：
Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.
Agent 应该会搜索互联网，并返回带有来源的总结。
在 Agent 执行任务时，可以打开 Trajectory 标签页，查看它的工具调用过程。通常可以看到类似下面的记录：
SUBTOOL: web_search
这说明 Agent 确实调用了 Web Search 工具，而不是完全依赖模型训练数据中的已有知识。
默认情况下，该搜索由 deepseek-official Provider 处理，并使用之前配置的 DEEPSEEK_API_KEY。
为 DeepSeek Harness 增加 Vision 能力
Harness 中的 DeepSeek Chat Model 本身是纯文本模型，无法直接理解上传的图片。
为了增加图像理解能力，可以使用 ModLens 作为桥接层：
- 用户上传图片；
- ModLens 调用 Vision Model 分析图片；
- ModLens 提取图像中的关键信息；
- 提取结果被传回 DeepSeek；
- DeepSeek 基于这些信息进行推理和回答。
这样可以继续使用 DeepSeek 作为主要推理模型，同时让 Gemini 负责图像理解。
安装 ModLens Plugin
将 ModLens 安装到 web Profile：
dsh plugin --profile web add @liustack/[email protected]
安装完成后，ModLens 会添加 modlens_read_image 工具，并创建类似下面的模型选项：
DeepSeek-V4-Flash (modlens vision)
这些模型变体允许用户上传图片，并继续使用 DeepSeek 作为主要的 Reasoning Model。
配置 Gemini Vision Backend
本文使用 Gemini API 作为 Vision Backend，因此需要准备 Gemini API Key。
测试阶段可以使用 Gemini API Free Tier。Google 对部分 Gemini 模型提供免费额度，只要没有超过 Free Tier 的速率限制，就不需要额外配置付款信息。
配置环境变量。
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 Key 配置 ModLens。
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
如果配置正确，输出中应该能看到：
- 当前 Provider 为
gemini-api； - Provider 状态为 Ready；
- Gemini API Key 已成功识别。
测试图像理解
在模型选择器中，选择名称包含 (modlens vision) 的模型，例如：
DeepSeek-V4-Flash (modlens vision)
然后上传或粘贴一张图片，并输入：
Explain what is shown in this image.
此时，DeepSeek 就能够描述图片内容，并根据图片信息进行推理。
在后台，ModLens 会将图片发送给 Gemini 进行视觉分析，再把提取后的信息传递给 DeepSeek。DeepSeek 本身不需要直接处理图片，而是负责后续的文本推理与回答。
接入第三方模型
DeepSeek Harness 也支持接入其他模型服务商。
打开：
Settings → Models
在这里可以添加：
- OpenAI；
- Anthropic；
- Mistral；
- ZAI；
- 其他兼容的 Model Provider。
如果需要连接自托管模型或本地模型，还可以创建 Custom Provider，并配置：
- Provider ID；
- Base URL；
- API Type；
- Credentials；
- Model Name。
Provider 添加完成后，返回当前 Session，从模型选择器中选择新模型即可。
例如，可以让第三方模型完成下面的任务：
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 模型完成 Coding 任务。这说明 DeepSeek Harness 并不局限于 DeepSeek 自家的模型。
配置多个模型后，可以直接从 Model Picker 中切换。切换结果会应用于下一次请求，不需要重新启动 Harness Server。
DeepSeek Harness 的优点与不足
DeepSeek Harness 最大的优势，是它没有把用户绑定在单一模型、工具集合或 Agent 类型上。
你可以先使用默认配置，之后再逐步：
- 替换模型；
- 添加工具；
- 安装社区 Plugin；
- 自定义 Prompt；
- 创建新的 Agent Preset；
- 接入自托管模型；
- 调整 Agent 的执行流程。
不过，它目前仍然存在一些不足。
在实际使用中，Agent 偶尔会在任务执行到一半时停止，而且没有明确说明原因，有时需要手动输入 continue 才能继续执行。
此外，Plugin 的安装和配置过程也不够顺畅。如果不了解具体的 Profile、Provider 和配置方式，初次使用时可能会遇到较多困难。当前文档对部分高级功能的说明也还不够完善。
这些问题对于一个仍处于早期阶段的产品来说并不意外。随着版本迭代，预计它的稳定性、文档质量和 Plugin 生态都会逐步改善。
常见问题
DeepSeek Harness 是什么？
DeepSeek Harness，也称为 dsh，是 DeepSeek AI 推出的开源、MIT License 的 AI Agent Framework。
它采用“Everything is a plugin”的设计理念，模型、工具、界面，甚至 Agent Loop 都可以替换。Harness 可以作为本地 Coding Agent 运行，也支持浏览器 Web UI 和 Headless Mode。
它是 Model-agnostic 的，不会强制用户只能使用 DeepSeek 模型。
DeepSeek Harness 是免费的吗？
Harness 本身是免费开源软件，采用 MIT License。你可以免费安装、修改和自托管。
但运行 Agent 时仍然需要使用模型服务，因此可能产生 API 费用。例如：
- 使用 DeepSeek 模型和 Web Search，需要 DeepSeek API Key 并为账号充值；
- 使用 OpenAI 或 Anthropic，需要对应的 API 凭证；
- 使用自托管模型，则需要自行承担服务器和推理成本。
DeepSeek Harness 支持 DeepSeek 以外的模型吗？
支持。
由于模型适配器采用 Plugin 机制，因此可以接入 OpenAI、Anthropic 等 Provider，也可以将 Custom Provider 指向任意兼容 OpenAI API 的 Endpoint，包括本地模型和自托管模型。
已经配置好的模型可以从 Model Picker 中直接切换，无需重新启动 Server。
DeepSeek Harness 与 Claude Code 有什么区别？
两者都属于 Agent Harness，但定位不同。
Claude Code 是 Anthropic 推出的闭源产品，主要围绕 Anthropic 模型构建。而 DeepSeek Harness 采用 MIT License，并强调 Model-agnostic 和 Plugin-based Architecture。
在 DeepSeek Harness 中，从工具到 Agent Loop 都可以进行替换。它的灵活性更高，但目前也比 Claude Code 更年轻，仍处于快速迭代阶段，未来可能会出现兼容性变化。
如何为 DeepSeek Harness 添加图像理解能力？
DeepSeek Harness 中的 DeepSeek Chat Model 默认是文本模型，不能直接理解图片。
可以安装 ModLens 等社区 Plugin，让它连接具备 Vision 能力的模型。安装完成后，ModLens 会添加 modlens_read_image 工具，并提供类似下面的模型变体：
DeepSeek-V4-Flash (modlens vision)
之后配置一个 Vision Backend，例如 Gemini API，即可让 DeepSeek 处理图片相关任务。
总结
DeepSeek Harness 的核心价值，不只是提供一个 Coding Agent，而是提供了一套可组合、可替换的 Agent 基础设施。
通过 Plugin 架构，它可以支持：
- 多种模型；
- 文件和 Terminal 操作；
- Web Search；
- Vision；
- Code Mode；
- Subagents；
- 自定义 Provider；
- 本地 Web UI；
- Agent 执行过程追踪。
对于希望深入理解和定制 AI Agent 工作流的开发者来说，DeepSeek Harness 值得关注。
不过，它目前仍处于早期阶段，Plugin 配置、文档完整度和运行稳定性还有提升空间。如果你更看重成熟度和开箱即用体验，其他 Coding Agent 可能更适合日常工作；如果你希望掌控模型、工具和 Agent Loop，那么 Harness 的开放架构会更有吸引力。
关于
关注我获取更多资讯
