[bug] dsh-mcp-client 写死 versionNegotiation: auto：对现代探测回 501 的 streamable-http 服务端永久连接失败（Sketch MCP 实测，附根因与修复方向）

[xxYaOho]

环境

项	值
dsh	0.2.0-rc.2（macOS 桌面 App，打包版）
服务端	Sketch MCP 2.0（Sketch macOS 内置，http://127.0.0.1:31126/mcp，GCDWebServer，protocolVersion 2024-11-05，8 个工具）
探测用客户端	@modelcontextprotocol/client 2.0.0
平台	macOS（Apple Silicon）

现象

在 ~/.dsh/cordis.patch.yml 里以 streamable-http 注册该服务端后：

• 工具从未注册：会话中不存在任何 mcp__sketch__*；
• 查询该 server 的 MCP 资源直接返回 mcp-client(sketch): server is disconnected；
• 没有任何面向用户的错误。唯一痕迹是插件自身的日志：先重试 10 次（500ms 起指数退避，上限 30s），随后永久放弃并注销全部工具，直到插件重载或 Host 重启。

服务端本身完全正常：initialize 返回 SketchMCP 2.0，tools/list 返回 8 个工具；用官方 SDK 直连也能拿到这 8 个工具。

根因（三层，逐层附证据）

1. 打包版把协商模式写死为 auto，配置无从关闭

• 桌面 App 0.2.0-rc.2 的 app.asar 中，客户端构造处是 versionNegotiation: { mode: "auto" } 字面量（整个包中仅此一处），不读取 Config；
• 同一运行时的 dsh-mcp-client Config schema 中没有 versionNegotiation 字段（stdio 与 streamable-http 两个分支都没有）。

因此"为这个 server 指定 legacy"在打包版里无法表达——用户改配置也无解。

2. 探测被回 501，而 SDK 把所有 ≥500 判为致命

• 现代探测使用 JSON-RPC 方法 server/discover，该端点对它回 HTTP 501（同一端点 GET → 405）；
• SDK 的分类逻辑（classifyHttpError）：401/403 → 致命；≥500 → 致命 EraNegotiationFailed；其余状态码与无法识别的 JSON-RPC 错误 → 回退 legacy（-32001 / -32020 / -32021 明确保守回退）。

501 Not Implemented 的语义恰恰是"本服务端不实现该方法"，与 404/405 同类，却被归入"服务端故障"。

3. 协商失败被并进重连预算，最终永久注销

探测失败 → connectGeneration 失败 → 重连监督器（默认 maxAttempts: 10、500ms→30s）耗尽 → 注销该 server 的全部工具且不再重试。整个过程对外只表现为"工具不存在"。

最小复现

# 1) 服务端对现代探测的回答
curl -s -o /dev/null -w '%{http_code}\n' -X GET http://127.0.0.1:31126/mcp
# 405
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:31126/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}'
# 501

// 2) 同一 SDK、同一 URL，只改协商模式
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'

for (const mode of ['auto', 'legacy']) {
  const client = new Client(
    { name: 'probe', version: '0' },
    { capabilities: {}, versionNegotiation: { mode } },
  )
  try {
    await client.connect(new StreamableHTTPClientTransport(new URL('http://127.0.0.1:31126/mcp')))
    console.log(mode, 'ok', (await client.listTools()).tools.length)
  } catch (error) {
    console.log(mode, 'fail:', String(error))
  } finally {
    await client.close().catch(() => {})
  }
}

结果：

auto   fail: SdkHttpError: Version negotiation failed: the server answered the probe with HTTP 501
legacy ok   8

对照：在带 per-server versionNegotiation 的源码构建上，同一份配置（legacy）30ms 内完成连接并暴露 8 个工具（同一 SDK、同一 transport、同一 URL）。

影响面

• 任何 streamable-http MCP 服务端，只要对 server/discover 回 5xx（501 Not Implemented 是最典型的一种，常见于较老的、嵌入式 HTTP 服务器实现），在打包版上即永久不可用；
• 失败静默：模型只看到"工具不存在"，用户看不到原因，本次定位消耗了一整轮对话；
• 附带一处版本分裂：同一份配置在源码构建与打包版上行为不同。

建议

1. 恢复 per-server versionNegotiation: auto | legacy（默认仍为 auto）。这是最小、可验证的解药；实现（含中英文文档与回归测试）本地已有一份，维护者认可方向的话我可以直接提 PR。
2. 把 501 Not Implemented 归入 legacy 回退（与 404/405 同桶），或至少在 DSH 侧对 EraNegotiationFailed 尝试一次降级——501 不是服务端故障。
3. 让"最终放弃"可见：目前唯一症状是工具消失。一条会话/启动级提示（含探测状态码与失败阶段）就能把这类问题从"一轮对话"缩短到"一分钟"。

与既有报告的关系

按 @weijiafu14 在 #247 的归并，dsh-mcp-client 的连接监督器此前已有四个面：

• #247：就绪没有总预算
• #3489：重连只被传输层 close 驱动
• #1249：通知路径 EPIPE 崩溃退出
• #618：list_changed 重同步替换阶段清空世代

本条是第五个面：协商阶段的失败被当作连接失败，吃掉重连预算后永久注销工具——仍然落在同一个问题上，即"何时算失败、失败后保留什么、何时换代"缺少统一规范。

与 #314（streamable-http 激活挂起）相邻但根因不同：那边是零连接挂起，这边是连接被拒后放弃。

[mengge237]

这条缺陷在 Windows + 0.2.0-rc.2（命令行安装，不是桌面 App）+ 云端服务端上也复现，而且探测回的不止 501。

环境：@deepseek-ai/dsh 0.2.0-rc.2、@deepseek-ai/dsh-mcp-client 0.2.0-rc.2、@modelcontextprotocol/client 2.0.0，Windows 11。
服务端：阿里云百炼 Harness 的 7 台 Streamable HTTP MCP（https://dashscope.aliyuncs.com/api/v1/mcps/<X>/mcp），
共 11 个工具。服务端本身正常：原生 initialize 回 HTTP 200，声明 protocolVersion: 2024-11-05，tools/list 正常。

探测请求的原文（抓的是插件路径下真实的 fetch）：

POST https://dashscope.aliyuncs.com/api/v1/mcps/EnhancedSearch/mcp
  accept: application/json, text/event-stream
  mcp-method: server/discover
  mcp-protocol-version: 2026-07-28
  body: {"jsonrpc":"2.0","id":"server-discover-probe-1","method":"server/discover","params":{"_meta":{...}}}
-> HTTP 500，响应体为空

受影响面比 501 更宽：dist/index.cjs（ESM 侧 index.mjs 同）的 classifyHttpError 只把 401/403 判鉴权错、
把 status >= 500 一律判成 EraNegotiationFailed，只有"非 500 且不在 NOT_PROBE_RECOGNIZED 里"才退回 legacy。
所以任何对未知方法回 5xx 的服务端都会整台不可用，而唯一可见症状是 mcp-client(<name>): server is disconnected
（判据是 !generation || connectedAt === undefined）——排查的人会先去查网络、鉴权、URL。

修法在本机验过，且是以"最小改动"的形式：在 classifyHttpError 的 5xx 分支前加一句

if (outcome.status >= 500 && context.fallbackAvailable) return { kind: "legacy" };

（保留对真正支持 server/discover 的服务端的协商能力；fallbackAvailable 是同一函数里已有的判据，见 2476 行附近）
改后用真插件 apply（不是另写一个客户端）逐台跑：7/7 台握手成功、注册出 11 个工具
（search 1 / fetch 1 / place 2 / code 1 / image 3 / tts 1 / asr 2），插件侧零告警。
反向对照也做了：把 mode 单独改成 legacy 或整块去掉 versionNegotiation，同一批服务端同样全部可用——
也就是说这套服务端的 legacy 通路一直是好的，问题只在"探测失败被当成致命"。

[xxYaOho]

补充：打包版下一条已验证的绕过路径（profile 本地覆盖）

前提不变：0.2.0-rc.2 的打包客户端把协商模式写死为 auto，且 Config 里没有 versionNegotiation，所以配置层面无解。但在等 release 期间，不修改 App 包也能让打包版跑上带修复的实现——用 profile 本地副本覆盖那一条入口。

做法

# 1) 在带修复的源码里构建并打包这个插件
pnpm --filter @deepseek-ai/dsh-mcp-client run build
pnpm --filter @deepseek-ai/dsh-mcp-client pack --pack-destination /tmp

# 2) 把 tarball 放进目标 profile，解成真实目录（不要用 symlink，理由见下）
mkdir -p ~/.dsh/profiles/<profile>/.dsh-override
cp /tmp/deepseek-ai-dsh-mcp-client-<version>.tgz ~/.dsh/profiles/<profile>/.dsh-override/
mkdir -p ~/.dsh/profiles/<profile>/node_modules/@deepseek-ai/dsh-mcp-client
tar -xzf ~/.dsh/profiles/<profile>/.dsh-override/*.tgz \
  -C ~/.dsh/profiles/<profile>/node_modules/@deepseek-ai/dsh-mcp-client --strip-components=1

# 3) 在 profile 的 package.json 里声明这个依赖（file: 指向 profile 内的 tarball）
#    "@deepseek-ai/dsh-mcp-client": "file:.dsh-override/deepseek-ai-dsh-mcp-client-<version>.tgz"

# 4) 重启 Host / App

为什么这样能生效

• 入口模块按其所属树的 baseUrl 解析（vendor/loader/src/config/tree.ts 的 tree.import → internal.import(name, ctx.baseUrl)），根树的 baseUrl 就是 profile 目录；
• profile 内的导入方 + 该包名列在 profile 依赖里 → 直接走 native 解析，profile 本地副本优先（packages/boot/app-boot/src/profile-resolution/resolver.ts 的 routeLocalPackage）；
• 判定条件就是 installedProfilePackageNames：manifest 里有这个名字，且 <profile>/node_modules/<name>/package.json 存在。

两个容易踩的点：

1. 用真实目录，不要 symlink。profile node_modules 下的 symlink 会被 linkedProfileRoots 归入 linked root，走另一条解析分支；file: 装出来的真实目录才是"profile 本地包"。
2. bundles 没有这个能力。resolveBundleDir 明确写了安装优先（"never from a profile-local copy"），所以 dsh.profile.bundles 里的内置 bundle 覆盖不了——只有入口行（name: 指向的插件）可以。

实测结果（macOS 桌面版 0.2.0-rc.2 + Sketch MCP 2.0）

重启后：

检查项	覆盖前	覆盖后
mcp-sketch 行的 packageDir	…/app.asar/dsh/node_modules/@deepseek-ai/dsh-mcp-client	~/.dsh/profiles/<profile>/node_modules/@deepseek-ai/dsh-mcp-client
该行的实时 Config schema	无 versionNegotiation	含 versionNegotiation（默认 auto）
该 server 的 resources 请求	mcp-client(sketch): server is disconnected	正常返回
工具注册	0 个 mcp__sketch__*	8 个全部在线

最后经 mcp-minimal（mcp_minimal_search → activate → mcp_minimal_call）实际调用 get_document_info，拿到 Sketch 返回的实时文档信息——配置里那条 versionNegotiation: legacy 生效，501 不再出现。

适用面与代价

不只是这一条：任何"打包版缺一个配置开关、或上游已修但尚未发版"的内置插件行，都能这么顶一段时间。代价是重启 Host 一次，以及要记得在正式版带上修复后删掉这份覆盖（依赖行 + 目录）。

顺带一个诊断经验：cordis-inspect 的 Config 查询会返回该行的 packageDir 与投影后的 Config schema——前者自证"跑的是哪一份代码"，后者自证"这份代码认不认那个字段"。定位这类"配置写了但没生效"的问题时，这两个字段比日志直接得多。

[mengge237]

profile 本地覆盖这条我记下了 —— 之前只想到"等 release"或者改 App 包，没往 routeLocalPackage 那个判据（manifest 里有名字 + 目录里有 package.json）上想。

补两个 Windows 侧的读数（0.2.0-rc.2，命令行安装，不是桌面 App）。探测回来的是 HTTP 500、响应体空，classifyHttpError 的 status >= 500 分支一样判致命；同一台机器上只有 DashScope 这条线受影响，它原生 initialize 回 200、声明 2024-11-05、tools/list 正常。

我这边走的是第三条路：不碰 App 包也不动 profile 依赖，直接改宿主安装树里那份 node_modules/@modelcontextprotocol/client。这份包是双构建，dist/index.cjs:2387 和 dist/index.mjs:2384 是同一段代码的两个副本，两处都得改。改完 7 台服务端全通、注册出 11 个工具。判据和你那两条一样 —— 重启后不再报 disconnected、mcp__<name>__* 从 0 个变成在线。