DeepSeek Harness搭建完整的AI Agent本地开发环境的实战指南

2026 年 8 月 13 日，DeepSeek 开源了自家的 Agent 运行时框架 DeepSeek Harness（简称 dsh）。与目前主流的 coding agent 相比，dsh 的设计思路更偏向底层。它没有绑定任何特定模型，一切皆插件，就是所有功能组件都通过插件形式装配，由开发者按需拼装成适合的 Agent 形态。

在实际使用中，当 Agent 运行起来并需要进行写代码、修改系统配置等具体操作时，通常需要相应的底层开发工具支持。本文将探讨如何将 dsh 与 ServBay 结合，构建起包含服务、数据库、AI Gateway 与模型管理的完整 AI Agent 开发环境。

一、DeepSeek Harness 的架构定位

DeepSeek 在设计 dsh 就说了，Agent = Model + Harness。其中，Model 负责逻辑推理，Harness 负责连接物理环境。dsh 的工作重心在 Harness 层。

dsh 基于 Cordis 插件内核构建，采用 TypeScript 编写，以 MIT 协议开源。架构设计有三个特点：

1. 一切皆插件
   ：模型接入、工具集、会话上下文、执行沙箱、底层存储、运行循环以及 UI 界面等，全部通过插件装配，能够独立进行无缝替换。

2. 执行轨迹可追溯
   ：系统提示词（prompts）、中间思维链、工具调用入参与返回值、子 Agent 调度等都会写入 append-only 的 session 日志中，支持回放与状态分叉调试。

3. 支持多种运行模式
   ：包括用于日常交互的 Web UI 模式，适合 CI/CD 和脚本调用的 Headless 命令行模式，以及对外提供接口的 Server 模式。

到8 月 17 日，短短4天，dsh 版本已迭代至 0.1.0-rc.6，生态内插件数量超过 1800 个。

二、物理环境层：为什么需要 ServBay

虽然 dsh 解决了 Agent 运行时的框架逻辑，但 Agent 要完成具体的代码编写和运行任务，仍然需要依赖数据库、Web 服务器以及证书等基础设施。

例如，当开发者要求 Agent "搭建一个 WordPress 博客"时，Agent 需要执行以下操作：

• 创建 MySQL 数据库并配置权限。
• 启动对应的 PHP 执行环境。
• 配置 Nginx 虚拟主机和反向代&理。
• 签发 SSL 证书，绑定开发域名。

如果仅靠 Agent 在宿主机上用 shell 命令去逐个安装和配置这些服务，容易因为依赖冲突或系统环境差异导致运行失败。

ServBay 作为一个AI开发管理平台，内置了 50 多种常用开发服务（包括 MySQL、PostgreSQL、Redis、MongoDB、PHP、Node.js、Go 等），并原生集成了 MCP Server 与 AI Gateway 功能。两者的结合正好互补：

三、环境配置步骤

1. 通过 ServBay 准备运行环境

dsh 运行需要 Node.js ≥ 22.19 环境。在 ServBay 中可以一键安装和管理 Node.js 版本，无需手动下载或使用 nvm 等工具：

• 打开 ServBay 应用面板，进入服务管理
• 找到 Node.js，选择 22.x 最新版本，一键安装并启用
• 安装完成后，终端中即可直接使用 node 和 npm 命令

：Node.js 版本不能低于 22.19。在早期版本中，缺少 createZstdDecompress 以及 AbortSignal.timeout 会导致 dsh 运行时直接崩溃，相关排障记录可参考官方讨论区 #100 与 #311。

同时，确保已在 platform.deepseek.com 获取 DeepSeek API Key，后续需要填入 dsh 的配置文件中。

2. 安装与运行 dsh

Node.js 环境就绪后，在终端执行以下命令拉取并启动 dsh：

npx -y @deepseek-ai/dsh web

首次下载依赖包大约需要 1 到 3 分钟。启动成功后，终端会提示：

dsh web: http://127.0.0.1:3080

打开浏览器访问该地址即可进入 Web 交互界面。为了提高后续的启动速度，建议使用全局安装：

npm install -g @deepseek-ai/dsh
dsh web

在 dsh 界面中，输入框旁可以选择推理档位。执行常规的文件读写或简单的脚本运行建议选择 low 档（或关闭深度思考），以缩短 Agent 在每次调用工具前的推理等待时间；进行复杂逻辑重构时再切换至 high 或 max 档。

3. 配置 ServBay MCP Server

MCP（Model Context Protocol）是目前通用的 AI 互操作协议。ServBay 内置的 MCP Server 能够将开发服务的管理接口安全地暴露给 Agent。

编辑 dsh 的全局配置文件 ~/.dsh/settings.yaml，在 mcpServers 下方添加 ServBay 的连接声明：

mcpServers:
  servbay:
    command: servbay-mcp-server
    args: []
    env: {}

配置后，dsh 运行的 Agent 将获得以下操作环境的权限：

• 启停和重载 Nginx、MySQL、Redis、MongoDB 等 50 多种服务。
• 自动创建开发域名（如 *.servbay.host）并一键签发 SSL 证书。
• 动态切换 PHP（5.6 - 8.4）或 Node.js 等运行时版本。
• 读写指定服务的日志以进行故障排查。

四、实战演练：一句话自动建站与配库

在配置好 MCP Server 之后，在 dsh 的 Web 界面中输入以下要求：

"请帮我建立一个 WordPress 开发环境，步骤如下：

1. 启动 MySQL 8.0 和 PHP 8.3 服务；
2. 创建一个名为 wp_db 的数据库；
3. 创建网站域名 myblog.servbay.host，配置对应的 SSL 证书以启用 HTTPS。"

Agent 接收到任务后，会根据 dsh 框架的逻辑拆解步骤，并通过 MCP 协议依次调用 ServBay 的后台接口：

graph TD
    dsh[dsh Agent] -->|MCP 调用| s1[启用 MySQL & PHP 8.3]
    dsh -->|MCP 调用| s2[创建 wp_db 数据库]
    dsh -->|MCP 调用| s3[绑定 myblog.servbay.host 并签发 SSL]
    s1 --> servbay[ServBay 开发环境]
    s2 --> servbay
    s3 --> servbay

在右上角的 Trajectory（轨迹记录）面板中，可以看到 Agent 调用的接口以及返回的 JSON 状态。无需开发者在终端中手动输入 SQL 命令或编辑 Nginx 配置文件，整个站点的服务架构即可搭建完成。

有 MCP 和没有 MCP 的差异对比

操作	没有 ServBay MCP	有 ServBay MCP
启动 MySQL	Agent 输出一段操作指南，开发者手动执行	Agent 直接调用接口启动，返回确认状态
创建数据库	Agent 给出 SQL 语句，开发者自己连接执行	Agent 调用工具完成，返回数据库名和连接信息
配置 HTTPS 网站	Agent 输出 Nginx 配置模板 + 证书申请步骤	Agent 一次调用完成域名绑定 + 证书签发 + 配置

差异很明显：接入 MCP 之后，Agent 从一个只能给建议的角色，变成了能够直接执行操作的角色。

五、使用 AI Gateway 管理模型凭证与优化成本

Agent 执行任务时通常需要调用多种大模型。如果在每个项目的配置文件里都明文写入 API Key，一旦将代码推送到公开仓库，就容易造成凭证泄露。同时，频繁的思考与工具链调用会消耗大量 token。

ServBay 提供的 AI Gateway 是一个统一的模型分发网关。它提供统一的服务端点（https://gateway.servbay.host），充当模型的路由总线。

1. 统一管理模型后端

在 ServBay AI Gateway 的配置界面中，可以将不同厂商的云端模型以及 Ollama 运行的开源模型统一配置为上游渠道，并在 Gateway 内部进行分组和路由。

2. 修改 dsh 配置文件

将 dsh 的提供商端点修改为 Gateway 地址，并使用 Gateway 分发的虚拟密钥：

providers:
  - name: servbay-gateway
    baseUrl: https://ai.servbay.host/v1
    apiKey: sb_vk_dev_project_alpha
    models:
      - deepseek-v4-flash
      - deepseek-v4-pro
      - qwen-2.5-coder-local

3. AI Gateway 带来的优势

• 凭证隔离安全
  ：真实 API Key 始终保存在 ServBay 的加密存储中，外部配置文件只记录 Gateway 下发的虚拟 Key。若发现密钥有泄露风险，在 ServBay 面板中直接吊销虚拟 Key 即可，真实 Key 不受影响。

• 模型无缝 fallback
  ：开发者可以在 Gateway 中设置规则，当云端 DeepSeek 接口超时或受限时，自动将请求转发给 Ollama 运行的开源模型，确保开发流程不中断。

• token 消耗监控
  ：Gateway 记录了每次调用的 token 数量和费用，方便开发者评估 Agent 在开发周期中的 API 使用成本。dsh 在工具链任务中会频繁调用模型（每个工具调用前都要推理一次），如果不做统计，月底的账单可能会有意外。

• 模型切换零改动
  ：需要从 DeepSeek V4 Flash 换到 V4 Pro，或者切到 Ollama 模型，只需要在 Gateway 面板中调整路由规则，dsh 侧的配置不用动。

六、常见问题

首次通过 npx 安装dsh，会下载500多个npm包，在Windows系统上可能需要8分钟以上。这里建议采用 npm install -g @deepseek-ai/dsh 进行全局安装，如此一来，后续启动的速度会快很多。倘若不想手动安装Node.js环境，那可以直接借助ServBay，一键安装和管理Node.js版本，这样就能省去nvm/volta等工具链的配置麻烦。

dsh 默认采用的是deepseek-v4-flash和deepseek-v4-pro。不过，借助插件和配置，它能够接入任何兼容OpenAI API格式的模型后端。要是再搭配ServBay AI Gateway，那就可以在一个统一的端点下，对DeepSeek、OpenAI、Anthropic、Google、Ollama等多个模型渠道进行管理。

不冲突。MCP 是一套标准协议，ServBay MCP Server 可以同时被 dsh、Claude Code、Cursor、Codex 等多个 Agent 工具调用。每个工具有独立的配置文件，互不干扰。

所有真实 API Key 存储在 ServBay 的加密体系中，不会上传到任何外部服务器。Gateway 对外签发的虚拟 Key 即使泄露，也可以在面板中一键吊销，不影响真实 Key 的安全。

dsh 当前版本为 0.1.0-rc.6，仍处于预发布阶段，部分 API 和插件接口还在迭代中。社区 dsh-handbook 中记录了不少已知问题和踩坑经验，生产环境使用需要做好充分评估。

七、总结

DeepSeek Harness 的开源为开发者提供了一个结构清晰、高度可定制的 Agent 运行时框架。借助 ServBay 提供的 50 余种开发服务，以及内置的 MCP Server 和 AI Gateway，开发者能够快速搭建起一个安全、可监控的 AI Agent 开发环境。