tinybird-typescript-sdk-guidelines

tinybird-typescript-sdk-guidelines 技能概覽

這個 tinybird-typescript-sdk-guidelines 技能是做什麼的

tinybird-typescript-sdk-guidelines 技能可幫你在以程式碼定義 Tinybird 資源的 TypeScript 專案中使用 @tinybirdco/sdk。它特別適合需要型別安全的 datasources、pipes、endpoints、connections 和 typed clients，且不想靠猜 Tinybird 語法或部署流程的後端開發者。

使用者通常需要什麼

多數人安裝 tinybird-typescript-sdk-guidelines 技能，是為了更快完成三類工作之一：正確定義新的 Tinybird 資源、將舊版 .datasource 與 .pipe 檔案遷移到 TypeScript，或在使用 tinybird dev、tinybird build 和 tinybird deploy 時避免破壞性變更。

這個技能為什麼不一樣

這個技能不只是快速翻一下 repo。它把導入時真正重要的實務規則集中起來：支援的設定格式、CLI 工作流程、僅限伺服器端的限制、可安全分支開發的方式，以及 Tinybird 在 TypeScript 中預期的具體資源模式。

如何使用 tinybird-typescript-sdk-guidelines 技能

安裝並確認是否適用

使用 npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-typescript-sdk-guidelines 安裝 tinybird-typescript-sdk-guidelines 技能。使用前，先確認你的專案真的屬於 Tinybird TypeScript 工作流程：Node.js 20+、TypeScript 4.9+，而且只能在伺服器端執行。當你的需求牽涉 @tinybirdco/sdk 時，這才是正確的技能；如果只是一般 SQL 或 API client 任務，就不適合。

從正確的檔案開始

先讀 SKILL.md，再依照任務選用對應的規則檔：

• rules/getting-started.md：安裝與專案結構
• rules/configuration.md：tinybird.config.*
• rules/defining-datasources.md 與 rules/defining-endpoints.md：資源撰寫
• rules/typed-client.md：生成的 client 用法
• rules/cli-commands.md：tinybird init、dev、build、deploy 和 migrate

如果你的任務會碰到外部資料，也要一併查看 rules/connections.md、rules/materialized-views.md、rules/copy-sink-pipes.md 和 rules/tokens.md。

把模糊目標改寫成有用的提示詞

給這個技能具體目標、repo 背景與部署限制。好的輸入會提到資源類型、檔案應該放哪裡，以及你是在做遷移還是從零開始。

範例：“Create a TypeScript Tinybird datasource for event ingestion in src/tinybird/datasources.ts, use mergeTree, add nullable country, and keep it compatible with branch dev mode.”

較弱的輸入：“Set up Tinybird.”

採用真正重要的工作流程

新專案用 tinybird init，舊檔案轉換用 tinybird migrate，迭代同步用 tinybird dev，驗證用 tinybird build，等準備好上線再用 tinybird deploy。當你需要透過 devMode 把開發與部署目標清楚分開時，tinybird-typescript-sdk-guidelines guide 特別有用。

tinybird-typescript-sdk-guidelines 技能 FAQ

這個技能只適合後端開發嗎？

是。tinybird-typescript-sdk-guidelines for Backend Development 才是它預期的使用情境。它不應該用在瀏覽器程式碼上，因為 tokens 必須維持在伺服器端。

如果我已經懂 Tinybird，還需要這個技能嗎？

如果你已經懂 Tinybird，但需要可靠的 TypeScript 定義、typed output，或從舊檔案安全遷移，這個技能仍然有價值。它可以減少你反覆確認正確 config 形狀、CLI 指令與資源定義模式的時間。

它和一般提示詞有什麼不同？

一般提示詞可能會產出看起來合理的 Tinybird 建議。這個技能則提供安裝、設定、資源定義與指令流程的 repo-backed 規則，降低產出看似正確、實際上在真實專案中會失敗的程式碼風險。

什麼情況下不該使用它？

如果你的任務與 Tinybird 無關、只需要一般 SQL 說明，或你正在做無法安全保存 tokens 的純前端功能，就不要使用 tinybird-typescript-sdk-guidelines skill。

如何改進 tinybird-typescript-sdk-guidelines 技能

提供精確的資源形狀

最好的輸出，來自一開始就把資源與限制說清楚：datasource、endpoint、connection、materialized view、copy pipe，或 sink pipe。把 schema 欄位、sort keys、params、schedule，以及目標是 branch、local 還是 production 一起講明。

補上 repo 與遷移背景

如果這個技能是針對既有程式碼庫運作，請告訴它檔案位置以及目前已經有哪些內容。例如：“Migrate tinybird//*.datasourceandtinybird//.pipeintosrc/tinybird/.ts, preserve current names, and keep mixed-format compatibility during rollout.” 這會比泛泛地要求一份遷移計畫好得多。

留意常見失敗模式

最常見的錯誤是把 tokens 暴露在 client 程式碼中、跳過 tinybird.config.*、把 devMode 行為搞混，或省略影響 inference 的型別細節。如果第一版輸出太寬泛，就要求更聚焦的成果：單一 datasource 檔、單一 endpoint，或一個可直接執行的 CLI 遷移步驟。

以驗證為導向持續迭代

第一版之後，接著要求下一個具體檢查點：修正後的 config、更完整的 schema、更安全的 query，或部署檢查清單。對 tinybird-typescript-sdk-guidelines guide 來說，最快的改善迴圈是：先定義一個資源，用 tinybird build 驗證，再根據實際錯誤或缺少的型別推斷結果做調整。