fix: retire uncertain MCP names so late OpenCode adds cannot replace live connections

2026-10-01 00:08:50 +08:00
parent f7f501a8e3
commit 9cc5dc1244
5 changed files with 319 additions and 45 deletions
@@ -1,5 +1,22 @@
 # 工作栏实现与验证进度

+## 2026-10-01：本地 MCP 晚到初始化覆盖新连接
+
+根因修复见[本地 MCP 初始化失败恢复](./runtime-process-reuse-technical-design.md#41-本地-mcp-初始化失败恢复)。
+已核对随包 OpenCode 1.18.29：`MCP.add` 的初始化不随客户端取消而中止，完成后写入同名状态，
+并关闭该名称下已有的连接；`disconnect` 只处理当时已登记的客户端。旧实现在 `mcp.add`
+超时或取消后仍复用同一名称，前一轮的晚到初始化（授权已撤销，结果为 `failed`）会覆盖下一轮
+刚建立的连接。现在响应不确定的名称作废，后续改用唯一替代名称。
+
+验证：新增真实 OpenCode＋实际网关用例，通过本地代理挂起第一次 MCP `initialize`，
+使第一轮在 3 秒控制超时后结束，第二轮建立连接后再放行挂起的初始化。修复前该用例
+复现为第二轮连接状态从 `connected` 变为 `failed`；修复后第二轮连接保持 `connected`
+且请求完成。`opencode-runtime`、`opencode-runtime-lifecycle`、`knowledge-mcp-gateway`
+三个测试文件 180 项通过；`npm run typecheck` 通过；相关文件 ESLint 通过。模型为本地合成
+服务，外部模型调用 0 次。9 月 30 日那次失败的原始时序没有底层日志，未确认就是这一竞态；
+本次修复的是已复现的同类失败路径。尚未发布或替换已安装应用。
+
+
 ## 2026-09-30：本地 MCP 连接诊断与恢复

 已实现[本地 MCP 初始化失败恢复](./runtime-process-reuse-technical-design.md#41-本地-mcp-初始化失败恢复)。
@@ -183,7 +183,14 @@ SelectedRuntimeManager
 工具和自定义 MCP 共用连接逻辑：仅对明确的连接拒绝、连接重置、断管或传输超时，在
 一秒内成功断开失败连接后重试一次。SDK 返回的无 HTTP response 网络错误和抛出的网络
 错误采用同一判定；HTTP/API 错误、鉴权或协议错误、未知失败不自动重试。
-取消立即终止后续尝试，断开失败的名称槽位保持占用。Prompt 和工具调用不重放。
+取消立即终止后续尝试。Prompt 和工具调用不重放。
+
+OpenCode 1.18.x 的 `mcp.add` 在服务端独立执行：客户端超时或取消不会中止初始化，
+`disconnect` 也只清理当时已登记的连接。晚到的初始化完成后会按名称写入状态，并关闭同名
+的现有连接。因此，`mcp.add` 未得到 HTTP 响应（抛错、超时、取消或无 response 的网络错误），
+或断开未确认成功时，该名称即作废；同一槽位之后改用本客户端内唯一的替代名称
+（前缀加 8 位 base-36 序号，仍为 12 个字符）。槽位随请求结束释放，不因断开失败而长期占用。
+已得到响应的正常失败继续复用原名称。

 界面显示有界、脱敏的失败详情。`runtime.mcp.failed` 诊断记录连接或断开阶段、失败类别、
 耗时、尝试次数、内置或自定义类型及可用的 HTTP 状态；通过本轮令牌的 SHA-256 摘要与