DeepSeek Harness 与 MCP 协议组合部署实操指南

2026-09-21 12:56 2 阅读

DeepSeek Harness 和 MCP 各自的角色

DeepSeek Harness（简称 dsh）是 DeepSeek AI 在 2026 年推出的开源 Agent 运行时框架，核心理念是“Everything is a Plugin”。它负责管理会话流程、加载插件、执行 Agent 推理循环，并提供 Web UI 供用户交互。底层基于 Cordis 构建，允许开发者通过组合插件来扩展能力，而不是把所有功能硬编码进主程序。

MCP（Model Context Protocol）则是一套协议规范，目标是让 LLM 应用能以统一方式访问外部工具、上下文和提示词。它定义了 Host（即 LLM 应用）、Client（Host 内部的连接器）和 Server（提供能力的服务端）三者之间的交互规则，使用 JSON-RPC 2.0 作为通信格式，支持 stdio（本地子进程）和 HTTP + SSE（网络服务）两种传输方式。

简单说：dsh 是 Agent 的“身体”，MCP 是连接“身体”和“外部世界”的“神经接口”。

为什么要把它们组合起来

单独使用 dsh，你只能运行内置或硬编码的工具；单独使用 MCP，你没有完整的 Agent 循环和用户界面。两者结合后，dsh 可以通过一个 MCP Client 插件，动态发现并调用任意符合 MCP 规范的 Server 提供的工具。

这种组合带来几个实际好处：

解耦：工具的实现（Server）和调用逻辑（dsh）完全分离。更新一个数据库查询工具，不需要动 dsh 核心代码。
复用：同一个 MCP Server（比如文件检索服务）可以同时被 dsh、另一个 LLM 应用甚至命令行工具调用。
标准化：所有工具都通过 tools/list 和 tools/call 接口暴露，输入输出都有明确的 JSON Schema，减少集成混乱。

但也要注意代价：多一层协议意味着多一层出错可能，比如连接超时、认证失败、Schema 不匹配等。更重要的是，能发现工具不等于能安全执行工具——权限和副作用控制必须由 Server 或插件层显式处理。

环境准备与启动 dsh

dsh 当前处于 developer preview 阶段（版本 0.1.6-alpha.2），对运行环境有明确要求：Node.js 版本需为 ^22.19.0 或 >=24.0.0，包管理器推荐 pnpm 11.7.0。

快速启动（推荐）

最简单的方式是直接使用 npm 包：

node --version  # 确认版本符合要求
npx @deepseek-ai/dsh web

这条命令会在 http://127.0.0.1:3080 启动 Web UI，并尝试自动打开浏览器。如果不想自动打开，加 --no-open 参数：

npx @deepseek-ai/dsh web --no-open

注意：默认只监听本地回环地址，远程访问需通过 SSH 端口转发或配置带认证的反向代理，切勿直接绑定 0.0.0.0 暴露到公网。

从源码运行（用于调试或查看插件）

如果你需要查看插件实现或修改代码，可以从 GitHub 克隆仓库：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web --no-open

pnpm run build 会生成构建产物，后续命令基于这些产物运行。由于项目处于预览阶段，升级前务必保存 package.json、pnpm-lock.yaml 和自定义插件配置，以防破坏性变更导致无法回滚。

MCP 的最小工作流程

MCP 的交互基于标准的 JSON-RPC 2.0，典型流程如下：

初始化握手：Client 发送 initialize 请求，Server 返回协议版本和支持的能力；Client 收到后发送 initialized 通知，完成握手。
工具发现：Client 调用 tools/list，Server 返回可用工具列表，每个工具包含名称、描述和 inputSchema（JSON Schema 定义输入参数）。
工具调用：Agent 选择工具并生成符合 Schema 的参数，Client 发送 tools/call 请求，Server 执行操作并返回结果。
错误处理：业务逻辑错误（如文件不存在）应在结果中设置 isError: true，而不是抛出协议级错误。

一个典型的工具定义如下：

{
  "name": "search_docs",
  "description": "Search approved internal documentation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 20 }
    },
    "required": ["query"]
  }
}

传输方式上，stdio 适合本地子进程（如 Python 脚本），HTTP + SSE 适合远程服务。远程 Server 必须启用 TLS、请求认证和来源 IP 校验，否则等于开放一个无鉴权的 API 端点。

在 dsh 中接入 MCP

截至 2026 年 9 月，dsh 官方尚未承诺 MCP 插件配置格式的跨版本稳定性，因此以下方法应视为架构模板，具体字段需以当前插件代码为准。

第一步：独立验证 MCP Server

在接入 dsh 前，先确保 MCP Server 本身工作正常。可以用一个简单的客户端脚本测试：

Server 能否启动？
能否完成 initialize 握手？
tools/list 是否返回预期工具？
传入合法参数后，tools/call 是否返回结构化结果？

常见问题包括：Server 把日志写到 stdout（污染协议消息）、参数不符合 Schema、未处理异步超时等。调试时重点看 Server 的 stderr 和 JSON-RPC 错误码。

第二步：配置 dsh 的 MCP 插件

假设 dsh 的 MCP 插件支持如下配置（仅为示例）：

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/docs-server.mjs"],
      "env": {
        "DOCS_ROOT": "/absolute/path/to/approved-docs"
      }
    }
  }
}

插件需要完成四件事：

读取配置，启动或连接 MCP Server；
管理连接生命周期（重连、超时、关闭）；
将 tools/list 返回的工具映射为 dsh 可识别的能力；
在执行高风险操作前（如写文件、发消息）弹出确认对话框。

不要在插件中复制工具的 Schema，也不要将 API Key 或内部路径硬编码进代码库。所有敏感信息应通过环境变量或安全配置中心注入。

对于需要调用大模型的场景，可参考七牛云等平台提供的 dsh 接入文档，配置推理 API 地址和密钥。但要注意，这些只是配置示例，具体可用模型和计费以服务商控制台为准。

安全与排错要点

MCP 工具的最大风险不是协议漏洞，而是权限过度授予。一个能执行任意 shell 命令的工具，一旦被恶意 prompt 触发，后果严重。

常见故障排查

npx 找不到包：检查 Node 版本是否符合要求，网络是否能访问 npm registry。可加 --yes 强制安装：npx --yes @deepseek-ai/dsh web --no-open。
Web UI 打开但工具列表为空：确认 MCP Client 是否完成 initialize。stdio Server 必须将协议消息写入 stdout，日志写入 stderr，否则 dsh 会解析失败。
tools/call 返回参数错误：严格对照 inputSchema 检查必填字段、类型、范围。不要为了“让调用成功”而放宽 Schema 限制。
远程 Server 连接超时：检查 TLS 证书、DNS 解析、认证头、SSE 保活机制，以及反向代理的超时设置（通常需大于 60 秒）。
插件升级后启动失败：dsh 处于预览阶段，破坏性变更是预期行为。回滚到已验证的版本，并重新运行最小握手测试。