
Composio 與 Vercel AI SDK v7 兼容性測試實戰從安裝、類型檢查到工具執行的全鏈路驗證【免費下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項目地址: https://gitcode.com/GitHub_Trending/co/composio導讀composio/vercel是 Composio 為 Vercel AI SDK 提供的官方 Provider它把 Composio 生態中的 1000 工具包裝成 AI SDK 標準的Tool帶inputSchema與execute供 Agent 調用。本篇文章以倉庫中 ts/e2e-tests/runtimes/node/vercel-ai-sdk-v7/README.md 為核心骨架深入剖析這套專為 AI SDK v7 打造的端到端e2e兼容性測試套件它如何以「消費者視角」安裝 Provider 的真實發布產物、如何用tsc --noEmit做類型契約校驗、如何驗證對象輸入 / JSON 字符串輸入 / v7 獨有的ToolExecutionOptions三種執行路徑以及對應的底層實現原理。讀完本文你將理解 Composio 如何保證同一 Provider 在 AI SDK v6 與 v7 兩個大版本上同時穩定工作并掌握如何在自己的項目里復現這套驗證流程。測試背景為什么要專門為 AI SDK v7 建一套 e2e 套件composio/vercel將ai聲明為跨多個大版本的 peer dependencyai: ^6.0.0 || ^7.0.0見 ts/packages/providers/vercel/package.json。這意味著同一份 Provider 代碼必須同時兼容 AI SDK 的兩個大版本而 v7 引入了與 v6 不同的ToolExecutionOptions形狀會直接影響tool.execute被調用時攜帶的第二個參數。正因為存在這種跨版本的兼容壓力倉庫分別維護了兩套互稱 sibling 的測試套件vercel-ai-sdk-v7守衛^6.0.0 || ^7.0.0范圍中v7 那一支重點覆蓋 v7 特有的ToolExecutionOptions參數形狀vercel-ai-sdk-v6守衛 v6 那一支防止未來的改動悄悄破壞 v6 消費者。兩者共享幾乎相同的結果標記marker與流程差異集中在鎖定版本v7 套件固定ai7.0.2和 v7 特有的執行選項校驗上。這套「一版本一套件」的設計本質上是把版本兼容性從「口頭承諾」變成「每次 CI 都會跑的可執行斷言」。測試覆蓋范圍六項核心斷言v7 套件的驗證目標可以歸納為一張標記表每個標記都會在夾具運行后出現在 stdout 中并由測試用例逐一斷言Marker覆蓋內容對應測試用例vercel ai sdk compatibility typecheck passed打包后的 Provider 類型在ai7下通過tsc --noEmit夾具fixtures/index.tsinstalls and typechecks successfullyWRAPPED_TOOL_INPUT_SCHEMA_OKwrapTool返回帶inputSchemaexecute的 AI SDK 工具wraps tools using inputSchemaOBJECT_INPUT_EXECUTION_OK對象輸入被原樣轉發給executeToolexecutes object inputsSTRING_INPUT_EXECUTION_OKJSON 字符串輸入在交給executeTool前被規范化normalize為對象normalizes JSON string inputsV7_EXECUTION_OPTIONS_OK包裝后的工具能接受 AI SDK v7 的ToolExecutionOptionsaccepts AI SDK v7 execution optionsTOOL_SET_OKwrapTools產出與ToolSet兼容的工具集合produces a ToolSet-compatible collection其中V7_EXECUTION_OPTIONS_OK是 v7 套件區別于 v6 套件的關鍵新增項——v6 套件的標記表中并沒有這一行這正是 AI SDK v7ToolExecutionOptions形狀變化在測試層面的直接體現。夾具結構三種文件各司其職fixtures/ ├── index.mjs # 運行時執行包裝工具并斷言執行行為 ├── index.ts # 純類型校驗tsc --noEmit斷言 Provider 類型與 ai7 對齊 └── package.json # 聲明 composio/corelink、ai7、typescript、zodindex.mjs以 ESM 方式在 Node 中真實運行包裝一個模擬的 Composio 工具后逐項驗證執行行為并打印上表標記index.ts只做類型層面的編譯檢查不產生任何運行時行為用于證明composio/vercel導出的類型與ai7的類型能夠互相賦值package.json鎖定依賴版本其中ai固定為7.0.2、zod為4.5.4、typescript為5.8.3見 fixtures/package.json。夾具的type字段為module因此運行時夾具采用 ESM 語法import/await這與composio/vercel自身type: module的 ESM 發布形態保持一致。關鍵設計用npm pack模擬消費者的真實安裝路徑這套套件最具說服力的設計在于安裝方式Provider 的安裝方式與真實消費者完全一致先對composio/vercel執行npm pack再安裝產出的 tarball——因此被測對象是發布后的dist與peerDependencies而不是 workspace 里的源碼。這一步由 fixtures 的安裝腳本實現見 fixtures/package.jsonVERCEL_TGZ$(npm pack /app/ts/packages/providers/vercel --pack-destination . --silent) \ test -n $VERCEL_TGZ \ npm install --ignore-scripts --legacy-peer-deps --package-lockfalse ./$VERCEL_TGZ腳本做了三件關鍵事情npm pack打真實發布包從ts/packages/providers/vercel打出 tarball。結合 vercel/package.json 中exports指向./dist/index.mjs與./dist/index.d.mts的配置可知消費者實際加載的是構建產物dist而不是src/index.ts源碼--legacy-peer-deps兼容 peer 沖突由于夾具自身聲明了composio/core為file:本地鏈接依賴版本 0.12.0 的 Provider 要求composio/core 0.10.0加上 AI SDK 生態常見的 peer 依賴橫跳--legacy-peer-deps確保安裝不會因 peer 沖突中途失敗從而把關注點聚焦在兼容性本身--ignore-scripts與--package-lockfalse跳過安裝鉤子腳本、不生成 lock 文件讓安裝過程盡量輕量、可復現同時由后續的typecheck步驟獨立承擔驗證職責。安裝后緊接著執行tsc --noEmit echo vercel ai sdk compatibility typecheck passedtsc --noEmit在真實安裝的ai7類型上編譯fixtures/index.ts只有編譯通過才會打印標記隨后 e2e 測試用例斷言該標記出現在 stdout 中見 e2e.test.ts。執行階段三種輸入路徑 v7 執行選項運行時夾具index.mjs見 fixtures/index.mjs構造了一個最小化的模擬工具slug: TEST_TOOL帶一個必填的query: string參數并提供一個executeTool樁函數記錄每次調用。隨后依次驗證四條執行路徑1. 對象輸入原樣轉發await wrapped.execute({ query: object input });斷言executeTool收到的slug TEST_TOOL且params.query object input即對象輸入不加任何改寫直接透傳對應標記OBJECT_INPUT_EXECUTION_OK。2. JSON 字符串輸入規范化await wrapped.execute(JSON.stringify({ query: string input }));模型以及部分 MCP 傳輸層偶爾會把工具調用參數以JSON 字符串而非對象的形式發出來。這里驗證的是 Provider 會在執行前把字符串解析回對象。其底層實現在 ts/packages/core/src/utils/toolArguments.ts 的normalizeToolArgumentsnull/undefined→{}無參工具常見純對象 → 原樣返回字符串 →JSON.parse空串/純空白串 →{}解析結果不是普通對象數組、原始類型、無法解析的字符串→ 拋出帶工具 slug 的可讀錯誤ComposioInvalidToolArgumentsError避免下游出現tool_use.input: Input should be a valid dictionary這類晦澀報錯。值得留意的是該工具函數文件頭注釋明確指出Vercel AI SDK streaming 正是觸發「參數變成 JSON 字符串」的常見來源之一且所有 Provider 都統一走這個歸一化入口保證行為在各框架間完全一致對應標記STRING_INPUT_EXECUTION_OK。3. AI SDK v7 的 ToolExecutionOptionsawait wrapped.execute( { query: options input }, { toolCallId: call_1, messages: [], context: {}, } );這里傳入的第二個參數就是 v7 版本的ToolExecutionOptions含toolCallId、messages、context。由于 AI SDK v7 改變了該類型的形狀本測試專門驗證包裝后的execute能接受該類型且參數仍能正確抵達executeTool對應標記V7_EXECUTION_OPTIONS_OK——這是 v7 套件獨有的斷言。4. wrapTools 產出 ToolSet 兼容集合const toolSet provider.wrapTools([composioTool], executeTool); if (!toolSet.TEST_TOOL) throw new Error(...);驗證wrapTools返回的對象以slug為鍵組織且能直接作為 AI SDK 的ToolSet使用對應標記TOOL_SET_OK。底層原理wrapTool 是如何把 Composio 工具變成 AI SDK 工具的測試所驗證的wrapTool/wrapTools實現在 ts/packages/providers/vercel/src/index.tswrapToolL113-L169先對inputParameters執行deduplicateJsonSchemaRequiredArrays在「廠商 schema 輸出邊界」上規范required數組若構造 Provider 時啟用了strict: true結構化輸出模式則調用toStrictJsonSchema把 schema 改寫成「所有屬性必填、封閉對象、無注解關鍵字」的嚴格形式可選參數轉為 nullable無法嚴格表達的構造會打警告并保留原始寬松 schema通過dereferenceJsonSchema$ref內聯未解析引用回退 sentinel與jsonSchemaToZodSchema把 JSON Schema 轉成 AI SDK 依賴的 Zod schema作為inputSchemaexecute內部先做normalizeToolArguments歸一化參數再調用executeTool(slug, params)嚴格模式下還會用omitNullToolArguments剔除「以 null 表示省略」的參數。wrapToolsL234-L239用reduce把每個工具按slug收集進一個VercelToolCollection即 AI SDK 的ToolSet類型別名與測試中toolSet.TEST_TOOL的訪問方式一一對應。類型層面fixtures/index.ts還額外做了賦值性冒煙檢查const _wrappedToolSet: VercelToolCollection tools satisfies ToolSet;用satisfies同時約束 Provider 導出的類型與ai7的ToolSet互相兼容這正是「typecheck passed」標記背后的代碼依據。隔離工具與多版本矩陣Docker 三個 Node 版本測試隔離工具是Docker并且在同一矩陣上跑了三個 Node.js 版本22.22.3、24.17.0、25.9.0見 e2e.test.ts。這與composio/vercel的engines聲明node 22.22.3見 vercel/package.json保持一致——最低支持版本恰好就是矩陣中的第一個版本保證「聲明的最低版本真實可用」。執行流程上setup階段npm run install:vercel npm run typecheck在 Docker volume 內完成安裝與類型檢查隨后夾具index.mjs在只讀掛載的node_modules上運行。只讀掛載進一步保證了「被測代碼就是安裝產物、運行期不被任何寫操作污染」的可信度。如何運行這套測試在倉庫根目錄執行pnpm test:e2e即可觸發整套 e2e 測試含vercel-ai-sdk-v7在內的所有 runtimes 套件。針對單個套件的斷言細節測試文件 e2e.test.ts 用bun:test編寫beforeAll給 setup 階段預留了300_000ms5 分鐘超時因為其中包含npm packnpm install的完整安裝鏈路。總結與延伸閱讀vercel-ai-sdk-v7套件回答了一個關鍵工程問題當 Provider 的 peer 依賴橫跨ai6與ai7兩個大版本時如何低成本、可信地守住每一支的兼容性。它的答案可以拆成三條可復用的經驗用npm pack的真實產物做測試讓 CI 驗證的是消費者會拿到的dist與peerDependencies而非倉庫源碼運行時斷言 類型斷言雙軌并行index.mjs驗證行為、index.tstsc --noEmit驗證類型契約兩者缺一不可同一套標記體系橫向對比v6 與 v7 兩套件共用標記命名唯一差異V7_EXECUTION_OPTIONS_OK恰好精確指向兩個大版本的 API 變化點。如果想進一步深入可以繼續閱讀vercel Provider 源碼wrapTool/wrapTools的完整實現與strict模式邏輯參數歸一化實現normalizeToolArguments的完整規則與錯誤處理vercel 單元測試 與 vercel-ref 測試更細粒度的 Provider 行為驗證v6 兼容套件與本文套件互補的 AI SDK v6 覆蓋。【免費下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項目地址: https://gitcode.com/GitHub_Trending/co/composio創作聲明:本文部分內容由AI輔助生成(AIGC),僅供參考