DSH rc.3 MCP 版本门禁排查

DeepSeek Harness rc.3 MCP 工具消失：版本门禁与依赖

作者
DeepSeekAgent.io 编辑部
发布
更新

DeepSeek Harness Desktop 升级到 v0.2.1-rc.3 后，已经配置好的 MCP Server 可能仍保留在 cordis.patch.yml，工具列表里却找不到任何 mcp__<server>__* 工具。2026 年 10 月 25 日的社区复现最终定位到 Profile 依赖树：主程序已经升级到 rc.3，传递依赖 @deepseek-ai/dsh-mcp-client 仍停留在 rc.2，插件随后被启动期的版本兼容门禁拒绝。

这个故障的关键线索是 MCP 子进程从未启动。Playwright、Telegram 或其他 MCP Server 没有连接失败，stdio 也没有异常；插件在建立连接以前就被排除，因此常见的 MCP 网络、命令路径和沙箱排查无法触及根因。

工具消失发生在启动链的哪一层

社区案例的运行条件为 Windows 11、Desktop rc.3，并通过 cordis.patch.yml 在 desktop Profile 注册 MCP 插件。升级流程重新安装了 Profile 依赖树，但 lockfile 与版本范围解析继续选中 rc.2 的 MCP Client。

这份插件清单没有通过 engines.dsh 声明可接受的 DSH 范围，而是把多个 @deepseek-ai/dsh-* peer 精确固定在 0.2.1-rc.2。rc.3 启动时，dsh-app-boot 调用 evaluatePluginCompatibility，发现 peer 条件不满足，于是在插件加载阶段直接拒绝它。

完整链路可以概括为：

  1. Desktop 与核心包升级到 rc.3；
  2. Profile 中的传递依赖仍解析为 rc.2；
  3. 插件的 exact peer 与当前核心版本不匹配；
  4. Boot compatibility gate 拒绝插件；
  5. stdio 子进程没有创建，MCP Server 没有机会连接；
  6. 由该插件注册的全部工具从 Agent 能力表中消失。

为什么界面和日志看起来都很安静

如果 MCP Server 真正启动后失败，通常可以检查命令、环境、stderr、握手和超时。本案停在更前面的插件兼容性判断，failOnStartupError 也没有参与，因为连接尝试根本不存在。

这解释了三个容易混淆的现象：

  • 配置文件还在，不代表插件已经成功加载；
  • 没有 MCP 连接错误，不代表 MCP 链路健康；
  • 所有工具同时消失，更可能指向插件级拒绝，而非每个 Server 同时损坏。

社区复现中，将 @deepseek-ai/dsh-mcp-client 精确升级到 0.2.1-rc.3 后，23 个 MCP 工具恢复。这一结果也排除了 Windows 沙箱、Playwright/Chrome 依赖和配置丢失等方向。

推荐的排查顺序

遇到升级后 MCP 工具清零，可以按以下层次检查：

  1. 确认当前 DSH、Desktop、Profile 与 MCP Client 的实际版本；
  2. 检查 MCP Client 是直接依赖还是由其他 Profile 包传递引入；
  3. 查看 lockfile 是否仍解析到旧候选版本；
  4. 检查插件的 engines.dsh 与 peer dependencies，区分兼容范围和精确版本；
  5. 确认插件是否进入 loaded 状态，再检查 stdio 子进程；
  6. 插件已加载且子进程已启动后，才继续排查命令路径、环境、握手和工具发现。

这种顺序可以减少无效操作。反复重启 MCP Server、重新安装浏览器或修改 Server 命令，都无法修复一个在 Boot Gate 阶段被拒绝的插件。

预发布版本最容易暴露 exact peer 问题

SemVer 对预发布标识的处理比普通补丁版本更严格。0.2.1-rc.2 与 0.2.1-rc.3 是两个明确不同的版本；插件把 peer 写成 exact pin 时，每次候选版本升级都可能触发不兼容。

对于紧密耦合、必须与内部 API 同步的包，精确版本可以阻止危险组合。代价是升级器必须把整个兼容集合视为一个单元，不能只更新顶层应用。对于能够跨候选版本工作的插件，更合适的做法是维护经过验证的 engines.dsh 范围，并在 Profile 安装后执行依赖一致性检查。

产品层还应把兼容性拒绝显示给用户：插件名称、实际版本、要求的 DSH 范围和修复动作都应该出现在 Plugin Manager 或启动诊断中。沉默地移除工具会让 Agent 能力变化难以审计，也可能使原本依赖 MCP 的任务在缺少工具的情况下继续运行。

本篇关注工具为何没有注册。若工具数量过多、Schema 占用上下文，则可继续阅读大型 MCP 工具目录：Deferred Tools 与 Token 成本。两者分别对应“插件没有加载”和“工具已经加载但需要延迟发现”。

参考资料

常见问题

配置还在，为什么 MCP 工具会全部消失？

配置只说明 Server 已登记。负责加载配置和注册工具的插件如果被版本门禁拒绝，Server 不会启动，工具也不会进入 Agent 能力表。

没看到 stdio 错误，是否可以排除 MCP Client？

不能。插件可能在创建 stdio 子进程之前就被拒绝。先检查插件加载状态和依赖兼容性。

所有 MCP Server 同时消失时先查什么？

先查共享的 Profile、MCP Client 版本和兼容性门禁。多个独立 Server 同时发生相同连接故障的概率通常更低。