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 需要执行以下操作：

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

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

ServBay 作为一个AI开发管理平台，内置了 50 多种常用开发服务（包括 MySQL、PostgreSQL、Redis、MongoDB、PHP、Node.js、Go 等），并原生集成了 MCP Server 与 AI Gateway 功能。两者的结合正好互补：dsh 控制 Agent 的思考逻辑与步骤编排，ServBay 提供稳定、相互隔离的服务环境。

三、环境配置步骤

1. 通过 ServBay 准备运行环境

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

1. 打开 ServBay 应用面板，进入服务管理
2. 找到 Node.js，选择 22.x 最新版本，一键安装并启用
3. 安装完成后，终端中即可直接使用 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/dshdsh 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 将获得以下操作环境的权限：

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

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

在配置好 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 的差异对比

差异很明显：接入 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 带来的优势

1. 凭证隔离安全：真实 API Key 始终保存在 ServBay 的加密存储中，外部配置文件只记录 Gateway 下发的虚拟 Key。若发现密钥有泄露风险，在 ServBay 面板中直接吊销虚拟 Key 即可，真实 Key 不受影响。
2. 模型无缝 fallback：开发者可以在 Gateway 中设置规则，当云端 DeepSeek 接口超时或受限时，自动将请求转发给 Ollama 运行的开源模型，确保开发流程不中断。
3. token 消耗监控：Gateway 记录了每次调用的 token 数量和费用，方便开发者评估 Agent 在开发周期中的 API 使用成本。dsh 在工具链任务中会频繁调用模型（每个工具调用前都要推理一次），如果不做统计，月底的账单可能会有意外。
4. 模型切换零改动：需要从 DeepSeek V4 Flash 换到 V4 Pro，或者切到 Ollama 模型，只需要在 Gateway 面板中调整路由规则，dsh 侧的配置不用动。

六、常见问题

dsh 安装时间很长怎么办？

首次通过 npx 安装 dsh 会下载 500 多个 npm 包，Windows 上可能需要 8 分钟以上。建议改用 npm install -g @deepseek-ai/dsh 全局安装，后续启动会快很多。如果不想手动安装 Node.js 环境，可以直接通过 ServBay 一键安装和管理 Node.js 版本，省去 nvm/volta 等工具链的配置。

dsh 支持哪些模型？

dsh 默认使用 deepseek-v4-flash 和 deepseek-v4-pro，但通过插件和配置可以接入任意兼容 OpenAI API 格式的模型后端。配合 ServBay AI Gateway，可以在一个统一端点下管理 DeepSeek、OpenAI、Anthropic、Google、Ollama 等多个模型渠道。

ServBay MCP Server 和 Claude Code 的 MCP 配置冲突吗？

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

AI Gateway 的 Key 安全吗？

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

dsh 目前适合在生产环境使用吗？

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

七、总结

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

注：这篇内容以 dsh 0.1.0-rc.6 撰写。dsh 当前处于预发布阶段，功能和 API 可能在后续版本中发生变化。