clanker25/ai

新增提供者套件

新增一個完整的 @ai-sdk/<provider> 第一方套件，其需遵循現有的提供者介面、儲存庫慣例、安全需求與發布流程。

閱讀現有真相來源

在實作任何內容之前，請先閱讀：

• 新增提供者 了解目前的套件與發布需求
• 提供者開發備註 了解命名規則、架構與工作流程序列化
• 提供者架構 了解提供者的抽象結構
• 安全的 URL 處理 了解當提供者需要拉取輪詢、圖片、音訊、影片或其他 URL 時的安全準則

以 PR #18595 作為一個最新的端到端範例，但請選擇目前提供者套件中，其 API 格式與模型型別最接近新提供者者，作為實作的參考依據。

第三方發行者可以在本儲存庫之外發布提供者套件。新的 @ai-sdk/<provider> 第一方套件需要先在 issue 中進行討論。請確認已達成共識後再開始實作。

發掘 API 合約

在設計模型類別之前，請在提供者的文件或儲存庫中尋找官方且已版本化的 OpenAPI 或 Swagger 規格。優先使用第一方規格，並在其實作筆記或 Pull Request 中記錄來源 URL、版本、發布日期或 commit。

使用規格與官方文件來識別：

• 基礎 URL 與驗證方案
• 支援的端點、模型類型與功能
• 請求參數與回應格式
• 串流傳輸方式與事件格式
• 錯誤回應格式
• 非同步輪詢與下載 URL 流程

請將 OpenAPI 規格視為實作證據，而非絕對真理。規格對於伺服器發送事件、串流增量、多型內容、工具呼叫、nullable 欄位與錯誤的描述常常不完整。預設情況下，不要新增生成的客戶端或生成的正式型別。實作最小化的手寫型別與 Zod 架構，然後根據官方文件和捕獲的 API 回應進行驗證。

如果不存在官方規格，請從官方文件和真實回應的 fixture 推導出合約，並在 Pull Request 中註明這個限制。

規劃提供者格式

判斷該提供者支援哪些 AI SDK 模型介面，例如 LanguageModelV4、EmbeddingModelV4、ImageModelV4、SpeechModelV4、TranscriptionModelV4、RerankingModelV4 或 Experimental_VideoModelV4。

在引入新的依賴項、公開 API 模式或新的抽象層之前，請先閱讀 contributing/decisions/README.md 及相關的已接受 ADR。優先使用現有的提供者工具函式與實作模式。

搭建套件骨架

透過改編一個當前可比的提供者套件來建立 packages/<provider>/。一個典型的套件包含：

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<model-type>-model.ts
│   ├── <provider>-<model-type>-model.test.ts
│   └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js

請保留當前的套件慣例，不要憑記憶重新建立設定：

• 將儲存庫套件版本設定為 2.0.0，不要有預發行版後綴。
• 建立 CHANGELOG.md，並以 # @ai-sdk/<provider> 標題開頭。
• 使用共用的 tsdown 設定以及來自可比提供者套件的當前套件版本注入模式。
• 擴充 ./node_modules/@vercel/ai-tsconfig/ts-library.json，啟用複合專案，並為工作區依賴項加入套件參照。
• 包含標準的 build、clean、type-check、Node 測試與 Edge 測試腳本。
• 包含標準的 files、文件預包裝、repository、bugs、engines 與公開來源發布中繼資料。
• 對於 AI SDK 工作區依賴項使用 workspace:*。只有當測試中使用到 @ai-sdk/test-server 時才加入它。
• 支援儲存庫中 Zod 3 與 Zod 4 的相依性範圍，並為新的實作架構使用 zod/v4。

在新增或變更工作區依賴項後，執行 pnpm update-references。

實作提供者工廠

請遵循當前的提供者工廠模式：

• 定義一個繼承 ProviderV4 的提供者介面。
• 匯出 create<Provider>(settings) 與一個預設的提供者實例。
• 當它擁有意義的預設模型類型，且可比較的提供者也遵循此模式時，讓提供者可被呼叫；否則回傳一個提供者物件。
• 設定 provider.specificationVersion = 'v4'。
• 實作 ProviderV4 要求的、已完整指定的工廠方法，例如 languageModel、embeddingModel 與 imageModel。
• 僅在能改善提供者 API 時，才加入像是 chat、embedding 或 image 的短別名。
• 從不支援的必備模型工廠中拋出 NoSuchModelError。
• 支援適合該提供者的設定，例如 apiKey、baseURL、headers 以及自訂的 fetch 實作。
• 使用 loadApiKey 或適當的共用工具函式載入憑證，標準化可設定的 baseURL，並將套件版本包含在使用者代理字串後綴中。
• 從 src/index.ts 匯出提供者工廠、預設實例、公開選項類型、模型 ID 類型與 VERSION。

實作模型類別

使用 @ai-sdk/provider 中的適當介面以及 @ai-sdk/provider-utils 中的共用工具函式，來實作每個支援的模型。

提供者選項類型和架構必須遵循 儲存庫命名與匯出規則。面向使用者的選項欄位應使用 .optional()，除非 null 具有特定意義。回應架構應保持最小化，容忍未使用的提供者欄位，並在 API 可能省略或回傳 null 時使用 .nullish()。

所有模型類別都必須實作提供者開發備註中描述的工作流程序列化合約：

• 將模型組態標頭設為可選
• 加入 WORKFLOW_SERIALIZE 與 WORKFLOW_DESERIALIZE 靜態方法
• 使用 serializeModel、serializeModelOptions 或相匹配的現有模式
• 確保驗證及其他不可序列化的函式可以從請求選項或工作流程環境中還原

安全地處理回應、錯誤與 URL

• 在正式環境程式碼中絕不使用 JSON.parse。請使用 @ai-sdk/provider-utils 中的 parseJSON 或 safeParseJSON。
• 使用最小化的架構與共用的回應處理器（例如 createJsonResponseHandler 及 createJsonErrorResponseHandler）來驗證成功與失敗的回應。
• 僅在套件需要新的公開 SDK 錯誤類型時才引入自訂的 AISDKError 子類別；一般的提供者 HTTP 錯誤應使用共用的 API 錯誤處理。
• 在每次 getFromApi 呼叫上明確設定 validateUrl。
• 當 URL 的主機或協議來自提供者回應時使用 validateUrl: true；當其來自開發者設定的 base URL 時則使用 false。
• 對於可能指向已設定私有或自託管端點的正當回應 URL，使用 trustedOrigin。
• 當憑證可能在第一次跳躍時發送時使用 credentialedOrigin，以便將其從非來源 URL 和重新導向中保留。

在實作任何輪詢或提供者提供的下載 URL 流程之前，請先閱讀安全的 URL 處理。

根據實際合約進行測試

為以下項目加入重點測試：

• 提供者預設值、自訂設定、工廠別名以及不支援的模型類型
• 請求序列化與回應解析
• 串流事件、使用量、結束原因、警告、工具呼叫與提供者中繼資料（若支援）
• 錯誤回應解析與格式錯誤的回應
• 工作流程序列化與反序列化
• 針對輪詢或下載的 URL 信任決策
• Node.js 與 Edge 兩種執行環境

在實際可行的情況下，使用真實的提供者回應作為 fixture。在捕獲它們之前，請先閱讀捕獲 API 回應測試 fixture 技能。僅在不會改變語義時，才修剪過大的 fixture。

加入範例與儲存庫整合

在加入範例之前，請先閱讀AI Functions 範例技能。

對於每個支援的模型類型，將入口範例放在：

examples/ai-functions/src/<function>/<provider>/basic.ts

將其他範例放在同一個提供者目錄下，並使用描述性的 kebab-case.ts 檔案名稱。不要建立像是 src/generate-text/<provider>.ts 的扁平化提供者檔案。

同時更新相關的儲存庫整合點：

• 將 @ai-sdk/<provider> 加入 examples/ai-functions/package.json
• 將其專案參照加入 examples/ai-functions/tsconfig.json
• 將所需的憑證加入 examples/ai-functions/.env.example
• 必要時將憑證名稱加入根目錄的 turbo.json 環境設定中
• 執行 pnpm update-references 來更新根目錄與套件的 TypeScript 參照

針對真實的 API 執行具代表性的範例，並在支援的情況下確認非串流與串流行為。

加入套件與提供者文件

• 撰寫套件的 README.md，包含安裝、驗證、設定、支援的模型及基本使用方式。
• 加入 content/providers/01-ai-sdk-providers/<最後一個數字 + 10>-<provider>.mdx，內容包含設定、模型功能、提供者選項與範例。
• 設定套件的文件預包裝腳本，使其包含該提供者頁面。

準備發布

為新的提供者套件建立一個 major changeset。儲存庫套件保持在純粹的 2.0.0；不要加入 -beta、-canary 或其他預發行版後綴。

在首次自動化發布之前，請與 Vercel IT 團隊協調，以在 npm 上以 0.0.0 版本建立一個空的 @ai-sdk/<provider> 套件，並設定其 Trusted Publisher。遵循引導新的 @ai-sdk/* 套件。這個臨時的 npm 引導版本與儲存庫套件版本是分開的。

當 main 分支處於預發行模式時，請勿將新的套件回溯移植到穩定的 vX.Y 分支。

驗證完整的變更

至少執行以下指令：

pnpm --filter @ai-sdk/<provider> build
pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/<provider> type-check
pnpm type-check:full
pnpm check

同時也使用必要的提供者憑證執行新的範例。當對共享套件或建置設定的變更可能產生影響時，請執行根目錄的建置。

完成檢查清單

• 第一方套件已於 issue 中獲得批准
• 已審閱官方的 OpenAPI 規格，或已記錄其缺失
• 已對照文件與實際回應檢查 API 規格
• 已選擇一個當前可比較的提供者實作
• 儲存庫套件已建立，版本為 2.0.0
• 已加入套件、TypeScript、建置、測試、來源證明與文件的設定
• 提供者工廠實作了 ProviderV4
• 已實作支援的模型類別與公開選項類型
• 已為每個模型類別實作工作流程序列化
• 回應解析、錯誤處理與 URL 擷取遵循儲存庫安全規則
• Node 與 Edge 測試通過，並使用具代表性的回應 fixture
• 已加入巢狀的 AI Functions 範例並成功執行
• 已更新範例的依賴項、TypeScript 參照、環境變數與 Turbo 設定
• 已加入 README 與提供者文件
• 已加入 Major Changeset
• 已協調 npm 套件與 Trusted Publisher 的引導作業
• 套件建置、測試、完整型別檢查與儲存庫檢查均通過