MCP 與 Extensions：外部工具接入的兩條路

先玩再講。同一個外部能力「查天氣」，左邊走 MCP 橋，右邊走原生 Extension，兩條路同時接入。看三件事：工具名怎麼生成、伺服器斷線時模型視角發生什麼、兩條路的能力面差多少。點「播放」自動走完，或用「單步」逐幀看。

先解釋名詞。MCP（Model Context Protocol）是一個開放協議：任何人寫一個工具伺服器，任何支援 MCP 的客戶端都能連上去用它的工具。DSH 的 dsh-mcp-client 外掛就是這個協議的客戶端，一個外掛實例連一個伺服器，stdio 子行程和 streamable-http 兩種傳輸都支援。連線成功後它做的事很直白：listTools() 拉一遍工具清單，把每個工具用公開名註冊進 ctx.tools，模型從此把它們當原生工具用。

命名是第一個設計點。每個 MCP 工具有兩個名字：原始名只在網線上出現（tools/call 用它），模型看到的公開名是 mcp__伺服器名__原始名。這個格式與 Claude Code 和 Codex 一致，mcp-client 的 README 自己點了這一句。名字必須滿足 DeepSeek 函式名約定：最長 64 字元、只允許字母數字下劃線連字元。要是替換字元或截斷改動了名字，就在尾部追加一個 12 位十六進位制的 SHA-256 hash，保證兩個不同的工具身份絕不會摺疊成同一個名字。整個函式是 (serverName, rawName) 的純函式：連線順序、重新同步、別的伺服器，都改不了一個工具的名字。

export function publicToolName(serverName: string, rawName: string): string {
  const joined = `mcp__${serverName}__${rawName}`
  const normalized = joined.replace(INVALID_NAME_CHARS, '_')
  if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized
  const hash = createHash('sha256').update(`${serverName}\0${rawName}`).digest('hex').slice(0, HASH_LENGTH)
  return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`
}

第二個設計點是世代（generation）。伺服器的工具清單會變，變了就要重新同步。同步分兩階段：先把下一世代的全部工具定義拉完建好，任何一步失敗都不碰註冊表，上一世代原樣活著；拉完了才做交換，先登出舊世代、再註冊新世代。

交換階段的寫法值得講一下。註冊迴圈裡，每註冊成功一個工具就把它的登出函式存進一張表。任何一次註冊拋了衝突（意味著有外來註冊霸佔了這臺伺服器的名稱空間），catch 分支就把這張表裡已註冊的全部登出，一個工具都不留，然後記一條 error 日誌。註釋把意圖寫得很直白：回滾是為了讓模型看到的要麼是完整的一個世代，要麼什麼都沒有，絕不能是半套。

出處：packages/mcp/mcp-client/src/tools.ts 第 159 至 172 行的註冊與回滾分支，核對日期 2026-08-13。

斷線重連也建在世代上。stdio 子行程崩了，supervisor 用指數退避重啟它：首次延遲預設 500 毫秒，逐次翻倍，上限 30 秒，一次中斷最多試 10 次（README.zh.md 配置表）。中斷期間最後一個正常世代保持註冊，模型這時呼叫會失敗，但工具名不會憑空消失；重連成功後重新發現，恢復的世代整體替換舊世代，工具既不重複也不洩漏。serverName 沒變的話，新世代的名字逐字相同，KV cache 前綴都保得住。預算也有講究：連線存活超過 30 秒就重置嘗試預算，所以偶爾崩一次的伺服器可以無限恢復，反覆崩潰迴圈的伺服器最終會耗盡預算被登出，不會永遠重啟下去。

最後一個設計點最容易被忽略：這座橋刻意只橋了 MCP 的 tools 能力。MCP 協議裡還有 resources（資源）和 prompts（提示詞模板）兩類能力，DSH 一概沒接。README 的「已知限制與暫緩事項」一節寫得很坦白：

邏輯不難還原：harness 內部沒有誰會消費一個外部 resource 或外部 prompt，先造橋墩沒有意義。工具有明確的消費方（agent loop 的工具呼叫），所以先橋工具。這屬於按需造橋。圖片、音訊這類非文字結果也做了有損投影，在模型上下文裡變成佔位符，二進位載荷不進上下文。

第二條路完全不同。Cordis 是 DSH 的外掛框架，整個 harness 就是一棵 Cordis 外掛樹。Extensions 子系統讓模型在會話裡現寫一個 Cordis 外掛、當場跑起來：寫程式碼前先用 cordis_inspect 查詢當前執行時裡有哪些服務和介面可用，然後 cordis_define 提交原始碼，cordis_run 啟動，不要了就 cordis_stop 或 cordis_undefine。這五個工具由 packages/extensions/tool-cordis 註冊。

一個動態外掛分兩半。Host 半在 Node 側的 node:vm 沙箱裡跑邏輯，Browser 半在頁面裡渲染 UI，兩半的生命週期由 ctx.dynamicCordisRunner（packages/extensions/cordis-host-runner/src/index.ts 第 124 行起）統一管。帶 Browser 半的啟動要走審批：cordis/request-run 事件把請求送到頁面，使用者點了允許才繼續，還可以勾選一併放行這個外掛的後續版本（runHostHalf 的 approveFutureVersions 參數）。每個 Package 版本不可變，改程式碼就是追加新版本。

把兩條路放一起看，它們是正交的，各管一頭。MCP 橋面對的是行程外的現成能力，信任模型是隔離：伺服器崩了、返回垃圾、斷線，都被世代和錯誤路徑擋在橋外，但它能給模型的只有工具這一種東西。Extension 面對的是模型現場生成的程式碼，跑在自己行程裡，能力面大得多：能加工具、能發事件、能註冊服務、能畫介面，代價是每次執行都在審批和沙箱的看管之下。一個是接外面的電，一個是自己發電。