TanStack/ai 是什麼？

這個專案要解決的是「同一個聊天或 agent 邏輯，換模型供應商、換前端框架就得重寫」的問題。它用 adapter 與 activity 兩層組合，把 streaming、tool calling、結構化輸出與多模態收進一組套件；代價是套件拆分很細、版本演進快，採用前得先確認自己要的 provider 與框架組合真的被覆蓋。

TanStack/ai 可以商用嗎？

可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。

TanStack/ai 還在維護嗎？

有在維護。儲存庫在最近一天內有新的提交。

TanStack/ai 是用什麼程式語言寫的？

主要是 TypeScript（依據 GitHub 的語言統計）。

TanStack AI 評測：provider-agnostic 的 TypeScript AI SDK 該不該採用

秒懂

它是什麼？: 這個專案要解決的是「同一個聊天或 agent 邏輯，換模型供應商、換前端框架就得重寫」的問題。它用 adapter 與 activity 兩層組合，把 streaming、tool calling、結構化輸出與多模態收進一組套件；代價是套件拆分很細、版本演進快，採用前得先確認自己要的 provider 與框架組合真的被覆蓋。
適合誰用？: 已經在用 TanStack 生態、而且需要在多個 provider 與多個前端框架之間共用同一套 tool 定義的團隊，這個專案值得排進評估清單；只接單一 provider、只需要一個聊天畫面的專案，額外的套件拆分與抽象層不會帶來對應回報。動手前先確認三件事：你要用的 provider 是否有對應的 @tanstack/ai-* 套件、你要的框架綁定是否已發布、以及 @tanstack/ai 與 provider 套件的版本是否落在同一條相容線上。
可以商用嗎？: 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
還在維護嗎？: 有在維護。儲存庫在最近一天內有新的提交。
用什麼語言寫的？: 主要是 TypeScript（依據 GitHub 的語言統計）。

以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。

開源專案深度解析

Hysen Labs 編輯部 · 2026年9月10日 · TanStack/ai

先確認它要取代的是哪一層程式碼

多數 TypeScript 專案接上 LLM 的方式，是在路由處理器裡直接呼叫某家供應商的 SDK，把回傳的串流轉成 SSE 或 WebSocket 推給前端。這條路在單一專案裡沒問題，痛點出現在第二個維度：當你想同時支援 OpenAI、Anthropic 與 Gemini，或是想把同一段聊天邏輯放進 React 與 Svelte 兩個前端，供應商專屬的訊息格式、tool call 結構、串流事件型別就會滲進業務程式碼。TanStack AI 針對的正是這層滲漏。README 把它定位成 provider-agnostic 的 TypeScript SDK，涵蓋 streaming chat、tool-calling agents、structured outputs、realtime voice 與 media generation，並提供 React、Solid、Vue、Svelte、Preact 的框架原生 client 以及一個 headless client。目標讀者是有多個 provider 或多個前端框架要顧、且已經在用 TypeScript 型別當作契約的團隊。若你的情境只有一個 provider、一個前端，這層抽象的成本會大於收益。

adapter 與 activity：兩層組合的實際切法

README 對架構的說明只有一句關鍵描述：「built from composable activities and provider adapters」。從程式碼範例可以還原出資料流。最外層是 activity，例如 chat() 這個函式，它接收 adapter、messages，必要時加上 outputSchema，回傳一個串流物件。adapter 由 provider 套件提供，範例中的寫法是 openaiText('gpt-5.2')，也就是把模型名稱綁進一個 provider 專屬的 adapter 實例。串流物件再交給 toServerSentEventsResponse() 轉成 HTTP 回應。這代表供應商差異被壓縮在 adapter 這一層，activity 與後續的傳輸格式不需要知道背後是哪一家。工具則走另一條路徑：toolDefinition() 先宣告 name、description、inputSchema、outputSchema，再用 .server() 掛上實作。README 特別點出同一個定義可以掛 server 或 client 實作，且輸入輸出型別一致。這個設計的實際意義是，型別契約與執行位置被拆開，工具要在伺服器跑還是瀏覽器跑，變成掛載方式的選擇而不是重寫。

安裝與最小可跑的串流端點

核心套件與 provider 套件分開發布。README 給的第一個指令是 pnpm add @tanstack/ai @tanstack/ai-openai。要做 React 聊天介面時，指令變成 pnpm add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-openai，可以看出 client 與框架綁定各自是獨立套件。若想用一組 API key 存取多家模型，README 建議的起點是 pnpm add @tanstack/ai @tanstack/ai-openrouter。伺服器端最小範例是一個匯出 POST 的函式：從 @tanstack/ai 匯入 chat 與 toServerSentEventsResponse，從 @tanstack/ai-openai 匯入 openaiText，讀取 request.json() 取得 body.messages，呼叫 chat({ adapter: openaiText('gpt-5.2'), messages: body.messages })，最後回傳 toServerSentEventsResponse(stream)。結構化輸出則是在同一個 chat() 呼叫裡多帶一個 outputSchema，範例用 Zod 定義 z.object({ name: z.string(), age: z.number() })，並以 await 取得結果而非串流。README 也列出 JSON Schema、ArkType、Valibot 可作為 schema 來源。專案另外提供 Agent Skills，Claude Code 與 Cursor 用 /plugin marketplace add TanStack/ai 與 /plugin install tanstack-ai 安裝，其他 agent 用 npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration，專案內則用 npx @tanstack/intent@latest install 把技能寫進 AGENTS.md 或 CLAUDE.md。這些指令會改動你的 agent 設定檔，屬於要進版控審查的變更。

套件拆得細，換來的是安裝面的複雜度

這個專案的模組化程度很高。README 明說可以只匯入 chat，需要時再加 image、audio、video、speech、transcription、summarization、realtime、Code Mode、devtools 與框架綁定。好處是 bundle 不必背用不到的 provider 程式碼，壞處是依賴清單會隨功能線性成長，而且每個功能面都有自己的套件版本。從 release 紀錄可以看到這件事的具體樣貌：@tanstack/openai-base 在 2026-09-03 同一天發布 0.10.9 與 0.10.10，@tanstack/ai 當天發布 0.53.0。核心套件已經走到 0.53，provider 底層還在 0.10，兩條版本線明顯不同步。這不代表不能用，但意味著升級時不能只看 @tanstack/ai 的版號，必須一併確認 provider 套件的相容範圍。對於把 AI 功能視為長期基礎設施的團隊，這種多套件、快節奏的發布模式需要對應的鎖版策略，否則 CI 會在不相關的 provider 更新上中斷。

Code Mode 與工具審批：能力邊界要自己畫

README 提到 Code Mode agents 讓 LLM 在隔離沙箱中撰寫並執行 TypeScript，用來編排帶迴圈、分支與平行呼叫的工具。文件只寫到 isolated sandbox 這個層級，沒有交代沙箱的實作方式、資源上限或網路限制。這是一個需要讀者自行查證的空白：把模型產生的程式碼拿去執行，風險取決於隔離機制，而不是取決於 API 好不好用。同一類問題也出現在工具審批上，README 有指向 Tool Approval Flow 的文件連結，但未在首頁說明審批流程的預設行為是阻擋還是放行。相對地，Lazy Tool Discovery 這類設計反映的是另一個現實限制：工具數量一多，全部塞進 prompt 會吃掉 context 並拉高延遲，所以需要按需揭露。這些都指向同一個判斷：這個 SDK 把機制交給你，但不替你決定安全邊界。

與 Vercel AI SDK 的差異在哪裡

README 自己列了一頁對比文件，標題是 TanStack AI vs Vercel AI SDK，並註明比較的是 architecture、feature coverage 與 tradeoffs。從本頁可見的資訊，能指出的實質差異在組合方式。TanStack AI 把 provider 差異收斂在 adapter，把能力切成可獨立安裝的 activity，框架綁定另立套件，並提供 headless client 給自訂 runtime。它的工具定義是 toolDefinition() 加上 .server() 或 client 實作的掛載模式，型別契約與執行位置分離。要判斷哪一邊適合，不能只看功能清單，得看你的既有程式碼把供應商假設放在哪一層。如果你的工具已經寫成與框架無關的純函式，這裡的掛載模式會貼合；如果你的邏輯本來就綁在某個框架的 server action 或 route handler 上，換過來的遷移成本主要會落在工具與串流的接線上。專案本身也提供 tanstack-ai-migration 這個 skill，說明遷移是被預期的使用情境。

授權、維護成本與採用判斷

授權是 MIT，對商業使用與修改沒有額外限制，這是採用門檻最低的一種。維護面則要看發布節奏：核心套件與 provider 套件分線發布，且近期在數小時內連續出過 patch，代表上游 provider 的變動會直接反映到套件更新上。這對採用者的實際要求是建立版本鎖定與升級驗證流程，而不是被動接受最新版。另外要注意的是，本頁沒有任何關於測試覆蓋率、執行期效能或正式環境案例的資訊，我沒有實際安裝或執行過這個專案，因此無法對串流延遲、bundle 大小或 sandbox 隔離強度做出判斷。要採用，先把你要用的 provider 套件與框架綁定套件在 npm 上確認存在且版本相容，再用 README 的 POST 範例跑通一條最小串流路徑，之後才談工具與多模態的擴充。

編輯結論

已經在用 TanStack 生態、而且需要在多個 provider 與多個前端框架之間共用同一套 tool 定義的團隊，這個專案值得排進評估清單；只接單一 provider、只需要一個聊天畫面的專案，額外的套件拆分與抽象層不會帶來對應回報。動手前先確認三件事：你要用的 provider 是否有對應的 @tanstack/ai-* 套件、你要的框架綁定是否已發布、以及 @tanstack/ai 與 provider 套件的版本是否落在同一條相容線上。最後一項尤其要自己驗，因為 @tanstack/openai-base 在 2026-09-03 一天內就出了 0.10.9 與 0.10.10 兩個版本。

官方來源

社群筆記