從四套系統(tǒng)到一個網(wǎng)關(guān)tsm-hub 如何把 LLM、Tools、MCP、Skills 收進(jìn)同一個入口如果你最近在做 Agent 相關(guān)的東西大概率已經(jīng)受夠了這種狀態(tài)大模型 API 要單獨(dú)對接函數(shù)調(diào)用要自己實現(xiàn)MCP server 這個倉庫一個、那個倉庫一個Skills 腳本又是另一套加載邏輯。我也是被這幾樣?xùn)|西來回折騰了幾個月最后忍無可忍才動手寫了 tsm-hub 這個統(tǒng)一網(wǎng)關(guān)。簡單說它就是把 LLM、Tools、MCP、Skills 四類組件收進(jìn)同一個入口讓你面向一個網(wǎng)關(guān)編程而不是同時維護(hù)四五套集成方式。這篇文章講講我為什么這么設(shè)計、核心模塊怎么拆以及你照著落地會碰到的那些坑。這個內(nèi)容適合誰適合正在做 AI Agent、企業(yè)內(nèi)部 AI 中臺或者單純覺得“工具調(diào)用越來越亂”的開發(fā)者。不管你是剛接觸 MCP 協(xié)議還是已經(jīng)寫了十幾個 Agent 服務(wù)這套網(wǎng)關(guān)的思路都能直接拿過去用——就算你不打算引入 tsm-hub光是把下面這些模塊劃分和配置規(guī)范看明白也能幫你把現(xiàn)有項目理清楚。1. 為什么需要 tsm-hub四個孤島問題1.1 一個真實任務(wù)暴露出的四個孤島先看一個很普通的場景你想做一個“幫我查會議室、預(yù)訂空閑時段、順便在群里發(fā)通知”的 Agent。就這么一個小任務(wù)你至少要面對以下四套東西第一是 LLM。你選一個模型供應(yīng)商搞定它的鑒權(quán)、消息格式、流式響應(yīng)如果哪天想換成另一家模型所有調(diào)用代碼都要跟著改。第二是 Tools。你寫好了查會議室、訂會議室的業(yè)務(wù)函數(shù)要把它們變成模型可以“看見”的工具描述還要自己處理函數(shù)參數(shù)的 JSON Schema。第三是 MCP server。公司有個統(tǒng)一會議系統(tǒng)開放了 MCP 協(xié)議你要在 Agent 里初始化 MCP client管理 server 的進(jìn)程生命周期、連接握手、協(xié)議版本。第四是 Skills。你可能之前已經(jīng)在 Claude Code 或同類工具里攢了不少 skill 包它們靠自然語言指令驅(qū)動跟你現(xiàn)在寫代碼調(diào)函數(shù)的 Agent 完全是兩套邏輯。這些組件單獨(dú)用都挺順手一旦組合起來就出問題。最常見的一種崩潰現(xiàn)場是模型說“我要調(diào) get_meeting_room”你的 Tools 注冊表里確實有這個函數(shù)但 MCP server 那邊也暴露了同名工具兩邊優(yōu)先級沒定義模型隨機(jī)選擇結(jié)果一會兒走直連函數(shù)、一會兒走 MCP 通道日志里行為全靠猜。更麻煩的是 Skills它本質(zhì)上是一套“教模型怎么做”的文本指令跟普通的“工具函數(shù)調(diào)用”還不一樣沒法用統(tǒng)一方式觸發(fā)。這就催生了我的核心需求能不能做一個網(wǎng)關(guān)把四類組件注冊到同一套路由表里讓模型、工具、MCP server、skill 都通過一個入口對外服務(wù)1.2 統(tǒng)一網(wǎng)關(guān)的三種解法思路針對上面這個問題按經(jīng)驗大體上有三條路可以走。第一種是自以為省事的“協(xié)議翻譯層”方案。在每個 Agent 里分別裝 SDK把 MCP 協(xié)議翻譯成內(nèi)部工具調(diào)用把 Skills 翻譯成 prompt。這種做法初期開發(fā)快但每加一個新 Agent、每接一個新 MCP server翻譯邏輯就要復(fù)制一遍后期維護(hù)成本翻著倍往上漲。第二種是做“服務(wù)網(wǎng)關(guān)”但只做透傳。它把 MCP server 的地址統(tǒng)一管理起來LLM 和 Tools 仍然走各自的路徑。這種網(wǎng)關(guān)解決不了“一個 Agent 同時需要模型、工具、技能”的編排問題治標(biāo)不治本。第三種才是 tsm-hub 走的路子定義一中立的運(yùn)行時內(nèi)核讓 LLM、Tools、MCP、Skills 全部以“能力單元”的形式注冊到網(wǎng)關(guān)里由網(wǎng)關(guān)統(tǒng)一處理鑒權(quán)、路由、批量調(diào)度與重試。Agent 側(cè)只有一個輸入輸出協(xié)議你給網(wǎng)關(guān)發(fā)一條帶目標(biāo)意圖的請求網(wǎng)關(guān)自己決定是調(diào)模型、走工具、連 MCP 還是激活某個 skill。我最終選了第三種因為它的長期維護(hù)成本最低后續(xù)新增能力時只是給網(wǎng)關(guān)增加一個注冊項不會污染業(yè)務(wù)代碼。2. tsm-hub 架構(gòu)拆解核心模塊與統(tǒng)一協(xié)議2.1 核心模塊模型網(wǎng)關(guān)、工具路由、MCP 適配器、技能庫tsm-hub 內(nèi)部拆成四個核心模塊它們的職責(zé)邊界非常清楚。第一個模塊是模型網(wǎng)關(guān)Model Gateway。它統(tǒng)一封裝了各家 LLM API對外只暴露 chat 和 stream 兩類接口。你需要在這里做供應(yīng)商適配器比如 OpenAI 系列的 function calling 格式、Anthropic 的 tool use 格式、國產(chǎn)模型的 tool 格式——各家有各家的差異但內(nèi)部都翻譯成統(tǒng)一的消息體。這個模塊的另一個關(guān)鍵職責(zé)是超時管理因為不同模型供應(yīng)商的響應(yīng)速度差異極大必須有統(tǒng)一的超時策略否則一個慢模型會把整個網(wǎng)關(guān)拖住。第二個模塊是工具路由Tool Router。它維護(hù)一張能力注冊表每一項工具或能力都有唯一標(biāo)識、用途描述、輸入輸出 Schema以及可調(diào)用的后端列表。這個模塊解決的核心問題是“同名工具”沖突當(dāng)你同時接入了直連函數(shù)和 MCP server 暴露的同名工具時可以按服務(wù)商優(yōu)先級、健康狀態(tài)、響應(yīng)延遲來決定路由到誰。沒有這個路由層你就只能在業(yè)務(wù)代碼里寫死 if else。第三個模塊是 MCP 適配器MCP Adapter。它負(fù)責(zé)所有 MCP server 的生命周期管理。MCP 協(xié)議比較特別它同時支持 HTTP SSE 傳輸和 stdio 進(jìn)程內(nèi)傳輸兩種方式適配器要處理連接池、心跳檢測、重連、以及 MCP 版本兼容。這一層還承擔(dān)一個隱藏任務(wù)把 MCP server 暴露的“工具列表”拉回來動態(tài)注冊進(jìn)工具路由表。這樣你不需要在網(wǎng)關(guān)里預(yù)先寫死“某個 MCP server 有什么工具”啟動時自動發(fā)現(xiàn)即可。第四個模塊是技能庫Skills Registry。它有點(diǎn)像插件管理器。一個 skill 包通常包含一個 SKILL.md 文件自然語言說明書以及可被調(diào)用的腳本、Prompt 模板、參考資源。技能庫負(fù)責(zé)打包、索引、版本管理這些 skill 包并且把它們從“prompt 文本的世界”映射成“可供路由的工具描述”。核心轉(zhuǎn)化手段是給每個 skill 生成一個“技能觸發(fā)描述”告訴模型什么場景下該激活這個 skill然后網(wǎng)關(guān)去按描述匹配調(diào)用。這四個模塊之間的消息流是一條完整鏈路Agent 發(fā)請求進(jìn)來模型網(wǎng)關(guān)先讓 LLM 判斷意圖如果模型決定需要外部能力就會輸出結(jié)構(gòu)化工具調(diào)用工具路由根據(jù)調(diào)用目標(biāo)去查注冊表找到對應(yīng)的 MCP server 或本地函數(shù)MCP 適配器隨后執(zhí)行遠(yuǎn)程調(diào)用或進(jìn)程內(nèi)調(diào)用把結(jié)果返回給模型網(wǎng)關(guān)最終由模型生成面向用戶的答案。2.2 為什么選 MCP 做統(tǒng)一協(xié)議基于各家工具的融合我在設(shè)計 tsm-hub 時最被反復(fù)問到的就是“為什么統(tǒng)一協(xié)議選了 MCPTools 和 Skills 不是各自有各自的格式嗎”我講講我的取舍過程。兩點(diǎn)考慮。第一MCP 已經(jīng)事實上成為工具調(diào)用的開放標(biāo)準(zhǔn)之一生態(tài)里能直接接入的現(xiàn)成服務(wù)越來越多比如設(shè)計稿解析、瀏覽器操作、接口調(diào)試、測試平臺這些方向都有可用的 MCP server。你不接入 MCP 生態(tài)就等于要手動為每一個外部服務(wù)重寫一套工具接口那工作量可觀。第二MCP 協(xié)議本身定義得足夠完整——它有 client/server 模型、工具發(fā)現(xiàn)機(jī)制、標(biāo)準(zhǔn)化的參數(shù)描述格式這些都跟 tsm-hub 想要的“能力注冊與自動發(fā)現(xiàn)”高度匹配。那 Tools 和 Skills 怎么辦我的處理方式是“全部向 MCP 靠齊”本地函數(shù)寫一層薄薄的 adapter 包裝成 MCP serverSkills 也通過技能庫包裝成一個“虛擬 MCP server”暴露一個名為 invoke_skill 的統(tǒng)一工具。這樣從路由層的視角看所有能力都是 MCP tool統(tǒng)一走同一套發(fā)現(xiàn)、調(diào)用、返回鏈路。你可能覺得這有點(diǎn)過度設(shè)計但實際操作中你會發(fā)現(xiàn)這個好處特別明顯新增能力時不用改 Agent 的代碼只需要注冊一個新的 MCP server整個系統(tǒng)的可擴(kuò)展性一下子打開了。3. 實操從零搭建 tsm-hub 的完整落地過程3.1 技術(shù)選型與前置準(zhǔn)備這部分是實操我就直接說我自己的選型以及為什么這么選方便你拿來參考或者按你的偏好替換。后端主體我用的 Python 3.11 FastAPI。原因有三一是 LLM 生態(tài)里 Python 的庫最齊全各個模型供應(yīng)商的 SDK 基本都是 Python 優(yōu)先二是 MCP 官方的 Python SDK 支持比較完善能省掉不少協(xié)議層的手寫工作三是 FastAPI 的異步能力足夠支撐流式響應(yīng)和 SSE 推送。內(nèi)部通信走 JSON配置管理用 YAML 文件加環(huán)境變量覆蓋。進(jìn)程管理器我用的是內(nèi)置的 asyncio 任務(wù)調(diào)度——因為 MCP server 里有不少是 stdio 模式必須由主進(jìn)程拉起子進(jìn)程并通信用 asyncio.create_subprocess_exec 去管理生命周期最方便。前置準(zhǔn)備其實不復(fù)雜你需要在環(huán)境里安裝這些依賴fastapi提供 HTTP 服務(wù)框架uvicornASGI 服務(wù)器用來跑服務(wù)mcpMCP 官方 Python SDKhttpx異步調(diào)用 LLM APIpydantic做數(shù)據(jù)校驗和 Schema 定義安裝好之后建議在項目根目錄建好 config/ 和 adapters/ 兩個目錄。前者放全局配置和供應(yīng)商賬號信息后者專門放各家 LLM 的適配器。目錄清晰了后面每一步都會省力很多。3.2 第一步定義統(tǒng)一消息格式在接入任何東西之前先把內(nèi)部消息格式定好。這是整個網(wǎng)關(guān)的地基后面所有模塊都要圍繞這個格式工作。我定義的核心消息體由三層組成。第一層是請求頭部 request帶上請求 ID、Agent 標(biāo)識、會話上下文。第二層是意圖結(jié)構(gòu) intent記錄模型判斷出的目標(biāo)代號、原始自然語言指令、可選的參數(shù)列表。第三層是能力路由結(jié)果 route記錄最終命中的工具類型、服務(wù)地址、請求超時時間。這里有一個比較隱蔽的設(shè)計點(diǎn)不要把某個模型供應(yīng)商的執(zhí)行結(jié)果直接塞進(jìn)內(nèi)部消息體。比如 OpenAI 返回的 tool_calls 數(shù)組和 Anthropic 返回的 tool_use 塊結(jié)構(gòu)差別很大如果你直接透傳將來換模型時就得多寫一層兼容邏輯。正確做法是在供應(yīng)商適配器里把這些差異統(tǒng)一翻譯成內(nèi)部格式——統(tǒng)一的工具名、統(tǒng)一的參數(shù) JSON、統(tǒng)一的執(zhí)行狀態(tài)碼。這樣后面無論對接哪家供應(yīng)商路由層看到的都是同一種結(jié)構(gòu)。統(tǒng)一消息結(jié)構(gòu)定義完成后需要一個注冊中心來登記所有能力。我把注冊表做成了 YAML 文件加一個自動發(fā)現(xiàn)機(jī)制啟動時掃描 rules/ 目錄把每個 MCP server 的 tools 列表拉回來合并成一個全局能力表。這部分邏輯我用一個簡化的偽代碼表示async def load_tools(): all_tools {} for server in config.mcp_servers: client await MCPClient.connect(server) tools await client.list_tools() for tool in tools: # 統(tǒng)一封裝成 ToolSchema all_tools[tool.name] { description: tool.description, input_schema: tool.input_schema, server: server.name, } return all_tools3.3 第二步接入一個 LLM 供應(yīng)商適配器接口統(tǒng)一了接著寫適配器。我以最常用的 OpenAI 兼容接口為例來講。適配器要做什么簡單說就是把網(wǎng)關(guān)的內(nèi)部消息體——包括系統(tǒng)提示、歷史對話、工具定義列表——翻譯成某家供應(yīng)商 API 能識別的格式。以 OpenAI 為例你需要把工具定義列表映射成 functions 數(shù)組每個函數(shù)包含名稱、描述、參數(shù) JSON Schema。當(dāng)模型返回 tool_calls 時你要把其中的 function name 和 arguments 抽取出來轉(zhuǎn)換成內(nèi)部路由請求。實操里比較容易被坑的點(diǎn)是流式響應(yīng)。OpenAI 的流式返回里工具調(diào)用的內(nèi)容是分片到達(dá)的——有的 chunk 給函數(shù)名有的 chunk 給參數(shù)片段有的 chunk 追加內(nèi)容。你要自己維護(hù)一個“正在流式構(gòu)建的 tool call 緩沖區(qū)”等所有分片到達(dá)后再組裝完整參數(shù)。我建議把這個邏輯寫死在適配器里不要讓上層業(yè)務(wù)感知到分片過程。我的實現(xiàn)里采用了異步生成器配合一個簡單的狀態(tài)機(jī)管理工具調(diào)用的開始、進(jìn)行、結(jié)束三個階段。不同供應(yīng)商之間的差異主要體現(xiàn)在消息字段和鑒權(quán)方式上。OpenAI 用 Authorization Bearer tokenAnthropic 除了 token 還要額外帶 version 頭部分國產(chǎn)模型需要在請求體里加 extra_body 字段。我把這些差異全部收斂到 adapter 類的 get_request_headers 和 format_request_body 兩個方法里每加一家模型就是新增一個 adapter 文件完全不影響其他模塊。這里有一個關(guān)于超時的經(jīng)驗統(tǒng)一網(wǎng)關(guān)的超時不要只看“整體請求超時”要拆成“首 token 等待時間”和“流式空閑超時”兩段。前者用來暴露模型服務(wù)是否掛了后者用來處理流式傳輸中斷的情況。我在配置里默認(rèn)設(shè)置首 token 等待 30 秒流式空閑超時 60 秒——你根據(jù)模型供應(yīng)商的實際情況去調(diào)。相關(guān)的參數(shù)發(fā)散我放到 4.3 節(jié)再細(xì)講。3.4 第三步把普通 Tools 注冊成 MCP Server現(xiàn)在到了最關(guān)鍵的一步把已有的普通 Python 函數(shù)變成可以通過 MCP 協(xié)議調(diào)用的工具。理論上你可以給這些本地函數(shù)直接建一個內(nèi)部 tool registry不走 MCP但為了統(tǒng)一協(xié)議我更推薦把它們包成 MCP server哪怕用 stdio 模式在本地起進(jìn)程。好處是如果你以后想把這個工具開放給其他服務(wù)直接把這個 MCP server 部署出去就行不用改任何代碼。整個包裝過程分三步。第一步定義工具 Schema明確函數(shù)名稱、描述、參數(shù)結(jié)構(gòu)這一步會直接影響模型能不能正確調(diào)用。第二步用 MCP SDK 注冊 FastMCP 實例把函數(shù)綁定進(jìn) server。第三步啟動 MCP server 并把它配置到網(wǎng)關(guān)的連接池里。下面是一個實際例子。假設(shè)你有一個查詢訂單狀態(tài)的函數(shù)那么注冊成一個 MCP server 的代碼大致是from mcp.server.fastmcp import FastMCP mcp FastMCP(order-service) mcp.tool() async def get_order_status(order_id: str) - dict: 根據(jù)訂單號查詢訂單當(dāng)前狀態(tài)。 return {order_id: order_id, status: 已發(fā)貨} if __name__ __main__: mcp.run(transportstdio)然后你在網(wǎng)關(guān)的 config 里加一行 MCP server 地址配置把這個 server 掛進(jìn)來。就這么簡單。我踩過的一個小坑是工具描述寫得太隨意。模型對工具的理解完全依賴這段描述你不能寫“查詢訂單”而要寫“根據(jù)訂單號查詢訂單當(dāng)前物流狀態(tài)及簽收時間適用于用戶追問物流進(jìn)度時調(diào)用”。描述越具體選工具的正確率越高。這個點(diǎn)怎么強(qiáng)調(diào)都不過分很多人在 MCP server 跑通之后抱怨“模型老選錯工具”八成就是描述寫得太模糊。3.5 第四步把 Skills 納入網(wǎng)關(guān)Skills 的處理思路跟普通 Tools 不太一樣。一個 skill 包一般不是單純的“輸入?yún)?shù)-返回結(jié)果”的函數(shù)它更像是一份操作指南加一組可執(zhí)行腳本。比如“用 Playwright 做表格數(shù)據(jù)抓取”這個 skill里面的 SKILL.md 會告訴你抓取步驟、翻頁策略、反爬注意事項配套腳本才是真正執(zhí)行動作的代碼。tsm-hub 處理 Skills 的策略是這樣的技能庫在啟動時掃描 skills 目錄讀取每個 skill 的 SKILL.md提取出標(biāo)題、用途、觸發(fā)條件和主入口。然后把這些信息映射成一個虛擬工具工具名按 skill 包名生成比如 skill_web_scraper。當(dāng)模型決定調(diào)用這個虛擬工具時網(wǎng)關(guān)就把“目標(biāo)自然語言指令skill 的說明文檔”一起交給底層的 driver——通常是 Claude Code 或 Codex 這類具備 agent 能力的執(zhí)行器——去實際執(zhí)行。這個設(shè)計的核心是把 skill 調(diào)用變成一種“懶執(zhí)行”。模型不需要理解 skill 內(nèi)部的復(fù)雜步驟只需要識別“這個場景適合觸發(fā)某個 skill”執(zhí)行細(xì)節(jié)全部交給 executor。這條路走通之后我發(fā)現(xiàn)一個新玩家入場特別快比如想接入“前端開發(fā)”相關(guān)的新 skill只需準(zhǔn)備一個標(biāo)準(zhǔn)格式的 skill 包把它丟進(jìn) skills 目錄網(wǎng)關(guān)重啟后自動注冊業(yè)務(wù)代碼一行都不用動。對團(tuán)隊的擴(kuò)展效率來說這種體驗提升是非常明顯的。4. 常見問題與排查技巧實錄4.1 從 MCP 連接超時到設(shè)計原理的排查第一批問題集中在 MCP 連接的建立階段最典型的是兩種。一種是 stdio 模式的 MCP server 啟動失敗。特征是日志里出現(xiàn)類似“子進(jìn)程退出退出碼 1”的報錯。排查思路按下面這幾步走先手動在同目錄下跑一遍啟動命令看是不是缺依賴再確認(rèn)子進(jìn)程的 cwd 設(shè)置是否正確最后檢查 stdout/stderr 重定向——stdio 模式的 MCP server 會把協(xié)議數(shù)據(jù)都打在主進(jìn)程創(chuàng)建的管道上但有些 server 會把正常的 print 日志混進(jìn) stdout導(dǎo)致協(xié)議解析錯亂。解決方案是讓 server 端的日志全部走 stderr或者在網(wǎng)關(guān)的 stdio 適配邏輯里把 stdout 和 stderr 分開處理我在 tsm-hub 里就是分別建立了兩個管道流下面的代碼片段展示了一個可用配置proc await asyncio.create_subprocess_exec( cmd, stdinasyncio.subprocess.PIPE, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, cwdworkdir, )另一個高頻問題是 HTTPSSE 模式連接上了但 tools 列表返回為空。這通常不是網(wǎng)關(guān)的錯而是 server 端工具的注冊目錄跟你預(yù)期的不一致。遠(yuǎn)程 server 經(jīng)歷過多次重新部署后工具列表可能發(fā)生變化。解決方法是把“工具發(fā)現(xiàn)結(jié)果”加一層持久化緩存并在啟動日志里打清楚工具總數(shù)和明細(xì)——否則出了問題你連問誰都說不清。建議在配置里加一個 auto_sync_tools 開關(guān)啟動時從 server 拉取工具列表運(yùn)行中每 60 秒做一次增量同步確保 tools 表與真實暴露接口一致。4.2 從 model 誤調(diào)用到 Schema 兼容性日常報錯排查等鏈路跑通之后最常見的報錯集中在模型與工具的 Schema 兼容上。一個小數(shù)問題在 AI 工程里其實非常常見但好多人第一次碰到會慌。首先是“模型返回了不存在的工具名”。這種情況十有八九是工具描述與工具名之間的關(guān)聯(lián)做錯了比如 Agent 的 system prompt 里出現(xiàn)了一個舊版工具名稱或者你把兩個不同 MCP server 的同名工具合并時沒有做好路由。建議在工具注冊階段就對工具名做命名空間隔離比如 order_service_get_status 和 legacy_order_get_status能極大減少誤調(diào)用。第二類是“參數(shù)校驗失敗的報錯”。模型生成的參數(shù)有時候會不符合 JSON Schema——比如該傳整數(shù)卻傳了字符串。處理這類問題的工具化方案是雙保險網(wǎng)關(guān)做一層預(yù)校驗把不合法參數(shù)攔截下來再添加一個 repair 機(jī)制將錯誤信息連同原參數(shù)回傳給模型讓模型自己糾正輸出。實測下來修復(fù)成功率很高比直接報錯強(qiáng)太多。下面是可供參考的實現(xiàn)def validate_args(schema: dict, args: dict) - list[str]: # 此處用 jsonschema 庫做嚴(yán)格校驗 errors [] validator Draft202012Validator(schema) for err in validator.iter_errors(args): errors.append(f{err.json_path}: {err.message}) return errors第三類是流式上下文被截斷的問題。某些模型在流式返回工具調(diào)用過程中會中途插話或吐出與工具調(diào)用無關(guān)的文本。這時你要在適配器里把工具調(diào)用數(shù)據(jù)與模型的自然語言回復(fù)分開緩存不能混在一起交付給路由層。我自己曾因為這個問題排查整晚最后發(fā)現(xiàn)原因荒謬某供應(yīng)商的流式輸出中文本與 tool_call 是無序的必須做完整的重排。如果你對接的供應(yīng)商比較多這類“各家有各家的毛病”的場景會不斷出現(xiàn)寫適配器時不要假設(shè)所有格式都規(guī)范。4.3 資源隔離與性能問題并發(fā)、超時、查找優(yōu)化網(wǎng)關(guān)跑起來后性能與隔離的問題是我后續(xù)才注意到的以下三件事比預(yù)想的更重要。一是并發(fā)度限制。MCP stdio server 本質(zhì)上是本地子進(jìn)程它的并發(fā)能力很有限。你在網(wǎng)關(guān)里如果同時喂給單個 stdio server 幾十個請求它會徹底卡死或者出錯。我建議給每個 server 配置獨(dú)立的并發(fā)池比如 max_concurrent_tasks 4超出部分的請求走排隊策略而不是無限并發(fā)。對于 HTTP 型 SSE server并發(fā)上限可以放寬到 10 到 20實測這個配置可以讓集群的吞吐發(fā)揮到較優(yōu)水平。二是超時參數(shù)必須要分層。最早我統(tǒng)一設(shè)了一個 60 秒超時結(jié)果有的工具調(diào)用量大、耗時天然就長而有些模型供應(yīng)商的流式響應(yīng)原本只需 2 秒偶爾的慢請求把整個鏈路拖到用戶不可接受。后來我拆成三層模型供應(yīng)商請求超時 30 秒MCP server 單次調(diào)用超時 45 秒整個 Agent 任務(wù)的最長執(zhí)行時間 120 秒。這三層超時用配置變量獨(dú)立管理比單一大超時要準(zhǔn)確得多。三是工具數(shù)量變大之后的查找鏈路優(yōu)化。開始只有十幾個工具時線性遍歷完全沒問題當(dāng)工具規(guī)模上升到幾百個甚至上千個時每次模型請求都把所有工具描述塞給模型是不現(xiàn)實的——上下文長度不夠、token 成本也太高。我當(dāng)時設(shè)計并測試后的方案是給工具描述做“索引標(biāo)簽”比如按領(lǐng)域打上“meeting”“email”“order”等標(biāo)簽在模型調(diào)用之前先做一次粗粒度的標(biāo)簽過濾只把命中的工具子集——通常不超過 30 個——放進(jìn)模型請求里這樣既快又省 token。實測下來工具調(diào)用準(zhǔn)確率反而比全量塞進(jìn)去更好因為模型在大量無關(guān)工具干擾下容易選錯。4.4 避坑清單我踩過的 7 個坑最后整理一份自己反復(fù)踩過的坑清單希望能幫你少走點(diǎn)彎路。第一定義工具 Schema 時一定要寫“何時用、何時不用”的邊界而不是只寫一句話。第二stdio 模式的 MCP server 千萬不要在代碼里往 stdout 打印業(yè)務(wù)日志一旦混入?yún)f(xié)議數(shù)據(jù)整個調(diào)用鏈路直接廢了。第三網(wǎng)關(guān)里的工具注冊表一定要有版本和來源字段不然等工具來自多個 MCP server 的時候你根本沒法回溯是誰定義的。第四統(tǒng)一網(wǎng)關(guān)里不要直接透傳底層異常細(xì)節(jié)給上游否則用戶會看到一堆內(nèi)部錯誤堆棧安全性和體驗都差包裝成一個標(biāo)準(zhǔn)錯誤碼結(jié)構(gòu)更合適。第五所有連接到網(wǎng)關(guān)的 Agent 要有獨(dú)立的 API Key不然無法做審計和權(quán)限隔離。第六技能包的版本更新一定要走完整的注冊與審核流程不要直接在線上覆蓋目錄否則會出現(xiàn) SKILL.md 更新了但配套腳本文件還是舊的這種詭異狀態(tài)。第七監(jiān)控不能只看調(diào)用成功率和延遲還要專門看“工具調(diào)用重試率”和“工具誤選率”——這兩個指標(biāo)才是網(wǎng)關(guān)質(zhì)量的核心直接反映了你工具定義和描述寫得好不好。我自己的體會是做一個 Agent 中臺最難的從來不是寫代碼而是把各種不同形態(tài)的能力收斂到一致的抽象層上。tsm-hub 這個項目的一次次迭代讓我確認(rèn)了一件事——統(tǒng)一網(wǎng)關(guān)的價值 80% 來自“路由規(guī)劃與 Schema 治理”的設(shè)計只有 20% 來自 API 代理本身的代碼實現(xiàn)。如果你正苦惱于模型、工具、MCP 與技能各管各的、改一處牽連一片試試先把它們收進(jìn)同一個注冊表里。這比任何單點(diǎn)優(yōu)化都值得你花時間。