🐛 fix(sdk): MCP/LSP 域十项修复——孤儿进程回收、连接退避、spawn 环境白名单与写超时

[CavinHuang]

概述

修复 sdk 全量 review 提出的 10 个 issue（MCP + LSP 域），每个 commit 独立可跑绿。

Issue	修复
#311 (P1)	connectMCPServer catch 内 best-effort close()——listTools 抛错后已 spawn 的 stdio 子进程回收，孤儿进程不再累积
#312 (P1)	ensureConnected 失败负缓存指数退避 5s→60s + force 绕过（sidecar 手动诊断走 force）——挂死 server 不再阻塞每次 run 启动 30-60s
#380 (P1 安全)	LSP server spawn 环境改 getDefaultEnvironment 最小白名单 + server.env 显式合并——项目可控 lsp.json 不再被动读取宿主 API key/token（对齐 MCP 路径既有收口）
#327 (P1)	LSP stdin 写入加 10s 超时并触发既有 fail()/重启链路——僵死语言服务器不再永久挂起 Write/Edit 全路径
#325	wrapper 名去重提升 manager 实例级集合（同步段内 release+claim 防跨 server 窃名、断开回收）——大小写折叠碰撞后工具静默覆盖消除
#326	新建 mcp/naming.ts 共享 util：规范化 + 64 字符截断 + shortHash 消歧，两拼装点收口——非法字符直通 provider 致整轮 400 关闭
#375	callTool 在途 disconnect 时结果 undefined 即抛 protocol_error，不再把空文本伪装成成功喂给模型
#384	defaultClientFactory 接 tools/list_changed，generation+client 双校验地重拉 listTools 原地刷新——server 动态增删工具不再陈旧至重连
#328	SwiftLint 适配器按实际解析 shell 选调用符（shellKind 提升 utils 共享）——win32 Git Bash 下行首 & 语法错误消除
#374	lspmux 探测缓存按 resolve(cwd) 键控 Map，正向 TTL 30s/负向 5min，启动失败主动失效回退直连

验证

• tsc --noEmit 干净；src/mcp/ 31 pass / 0 fail；lsp+bash 组合 46 pass / 0 fail
• 五文件组合跑（含 tools/bash、utils/process-sandbox 等敏感邻居）零串扰，正反序双验证
• 独立 code review 两轮通过：首轮抓出 lspmux 测试 mock.module('node:child_process') 全进程污染套件（CI bun 1.3.13 严格导出检查下必炸），返工为 probeSpawn/clientConstructor 双 seam 注入方案零 mock.module；复核确认 seam 默认路径逐参等价、复位语义正确
• [P1][sdk/mcp] client.connectMCPServer 半途失败不清理 client，孤儿子进程累积泄漏 #311/[P1][sdk/mcp] 连接失败无负缓存/退避，挂死服务器让每次 run 启动阻塞 30-60s #312 含真实子进程红绿测试

Closes #311, closes #312, closes #325, closes #326, closes #327, closes #328, closes #374, closes #375, closes #380, closes #384

🤖 Generated with Claude Code

[CavinHuang]

Code Review

十项逐项核对：七项（#325/#326/#327/#328/#374/#375/#384）真实落地、方向正确、测试钉死有效；但三项与 main 已合入实现重复，且分支 CONFLICTING——须 rebase 去重后才能合。

重复冲突项（阻塞）

#	状态	处置建议
#311 孤儿回收	PR#437 已合入等价实现，issue 已 CLOSED	删除对应 commit
#312 负缓存退避	PR#437 已合入 nextRetryAt 方案；两套退避选项名并存会打架	移植 force 绕过（main 缺失的真增量）进 main 方案
#380 spawn 白名单	PR#443 已合入 getDefaultEnvironment 逐参等价	移植 env 解析+merge（LSPMUX_SERVER 覆盖问题）进 main 代码

rebase 后需人工核对 workspace-mcp-manager 探测点同时保留 main 的 mapPublicError 包装与本分支 {force:true}。

真增量七项核验（rebase 后原样保留）

• [P2][sdk/lsp] stdin 写入回调无超时、abortSignal 未贯通文档同步，僵死语言服务器挂死 Write/Edit 全路径 #327 LSP stdin 写超时→fail() 重启链路：send 是唯一写入口，settle 双路 clearTimeout 无泄漏；notify 路径此前确可永久挂起
• [P2][sdk/mcp] wrapper 名去重集合按 server 独立，跨 server 规范化碰撞后工具被静默覆盖 #325 wrapper 名去重提升实例级：claim/release 全在同步段无撕裂
• [P2][sdk/mcp] SDK MCP server 与外部 MCP 工具名原样拼装，非法字符直通 provider API 致整轮 400 #326 naming.ts 收口 + engine 分组前缀同步（顺修 raw name 不匹配既有 bug）
• [P3][sdk/lsp] lspmux 探测缓存全局单例且 5 分钟不复检 running 状态 #374 lspmux 探测缓存按 resolve(cwd) 键控+正负 TTL：main 单条目全局缓存多 workspace 互相污染属实
• [P3][sdk/mcp] callTool 进行中 disconnect 竞态产出成功的空结果 #375 callTool 在途 disconnect 即抛 protocol_error 无误重试；[P2][sdk/mcp] manager 活路径 client 未接 tools/list_changed，server 动态增删工具后工具列表永久陈旧 #384 tools/list_changed 原地刷新（seam 注入规避 CI bun 1.3.13 mock.module 坑）；[P2][sdk/lsp] SwiftLint 适配器 win32 硬编码 PowerShell 调用符，Bash 实际优先 bash 时恒失效 #328 SwiftLint shellKind 与 Bash 工具同源

非阻塞 P3

• 碰撞去重后缀可突破 64 上限（base 已钳 64 + _hash6 = 71），触发窄但命中即回 [P2][sdk/mcp] SDK MCP server 与外部 MCP 工具名原样拼装，非法字符直通 provider API 致整轮 400 #326 要治的整轮 400
• engine mcpTools startsWith 对截断加哈希的 >64 工具名漏报（仅状态展示层）

另注意合并顺序协调：PR#444（dead-code）同样触碰 mcp/client.ts / sdk-mcp-server.ts / README.md，先合者会制造新冲突。

[CavinHuang]

Code Review

七项新修复(#384 listChanged 订阅/#325 takenWrapperNames/#327 stdin 写超时/#374 lspmux 键控/#375 callTool 守卫/#328 SwiftLint win32/#405 seam 化测试)全部实证正确,但基线落后 main 三个已合 PR(#437 关掉 #311/#312,#443 关掉 #380),需 rebase 解冲突后再合。

[P1·合并操作风险] 原样合入将回退 main 已有修复

merge-tree 实测 4 文件冲突,其中两处若按分支版本解决会静默丢弃:

• apps/sidecar/src/services/mcp/workspace-mcp-manager.ts:main 的 mapPublicError 脱敏 try/catch(🔒 fix(sdk,sidecar): MCP 客户端栈三缺口——调用超时/死连接自愈/testServer 脱敏 #441)× 分支的 {force:true} → 两者合并进同一 try 块
• packages/sdk/src/mcp/client.ts:[P1][sdk/mcp] client.connectMCPServer 半途失败不清理 client，孤儿子进程累积泄漏 #311 重复实现 → 整块取 main 版(含 [P2][sdk/mcp] MCP 客户端栈三缺口：调用无超时 / 死连接假 connected / testServer 绕过脱敏 #403 withCallTimeout)
• packages/sdk/src/lsp/client.ts:[P1][sdk/lsp] LSP 子进程继承宿主全量 process.env，项目可控命令可读取 API key/token #380 双实现,仅注释差异 → 取 main 版 spawn 行
• packages/sdk/src/mcp/manager.ts:双 [P1][sdk/mcp] 连接失败无负缓存/退避，挂死服务器让每次 run 启动阻塞 30-60s #312 实现(main 的 nextRetryAt 水位 vs 分支的 lastFailedAt)+ [P2][sdk/mcp] MCP 客户端栈三缺口：调用无超时 / 死连接假 connected / testServer 绕过脱敏 #403 onclose 块 → 骨架取 main,仅移植四组新增量:force 选项、takenWrapperNames/naming、callTool undefined→protocol_error 守卫、list_changed 刷新;failureRetryBaseMs/MaxMs 命名保留(sidecar 无参构造,改名零影响)

[P2] disconnect() 不清自身负缓存

与 PR 描述"显式 disconnect 清零"矛盾(靠 force 兜底);main 版行为是清零的。rebase 时建议顺手对齐。

[P3] 死代码上的重复投资

client.ts/sdk-mcp-server.ts 属 #388 判定的死代码路径,#311/#326 hunk 是对死代码的重复修复;真实承接面是存活的 manager.ts 栈(#444 将删除死路径,故 #440 先合、#444 后 rebase)。

测试

seam 化(setDefaultMcpSdkClientConstructor/setLspmuxProbeSpawn)替代 mock.module,符合 CI bun 1.3.13 严格导出约束 ✓;seam 未泄漏进公共导出 ✓

结论

修复合并基线后可合——rebase 弃重复 hunk,按上述方案解四处冲突。