tinybird-python-sdk-guidelines

tinybird-python-sdk-guidelines 技能概覽

這個技能是用來做什麼的

tinybird-python-sdk-guidelines 技能可協助你用 tinybird-sdk 在 Python 中處理 Tinybird 資源。當你需要在以程式碼為主的 Tinybird 專案裡定義 datasource、endpoint、connection，或 client 存取時，它最有用，特別適合後端開發與資料擷取（ingestion）工作流程。

適合誰使用

如果你符合以下情境，就適合使用 tinybird-python-sdk-guidelines 技能：

• 正在建立新的 Tinybird Python 專案
• 想把舊的 .datasource / .pipe 檔案遷移到 Python
• 要把 Tinybird 串接進後端服務
• 正在建立必須維持在 server-side 的查詢、pipeline 或 ingestion 路徑

它比一般提示詞強在哪裡

這個技能不只是「寫 Tinybird 程式碼」而已。它會把程式碼背後的操作規則一起帶給你：設定是怎麼被解析的、哪些 CLI 指令真的重要、client 檔案要怎麼組織，以及部署時最常在哪裡出錯。也就是說，當主要風險不是語法，而是設定錯誤、不安全的 token 處理，或選錯開發目標時，tinybird-python-sdk-guidelines 會更實用。

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

安裝並啟用它

先用這個 repo 的 skill manager 安裝 tinybird-python-sdk-guidelines 技能，然後把 agent 指向 skill 路徑：
npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-python-sdk-guidelines

如果你的工作流程支援直接讀取 skill 檔案，就從 skills/tinybird-python-sdk-guidelines/SKILL.md 開始。

給它正確類型的任務

tinybird-python-sdk-guidelines 最適合搭配這種提示詞資訊：

• 資源類型：datasource、endpoint、client、connection、copy pipe，或 migration
• 執行環境：local dev、branch mode，或 production deploy
• 輸入內容：table schema、SQL、API 參數、secrets，或檔案結構
• 預期產出：Python 定義、config 檔，或 deployment plan

強而有力的提示詞範例：
“Create a Tinybird datasource and endpoint in Python for event tracking. Use tinybird-sdk, include tinybird.config.json, and show how to query it from lib/client.py. Assume branch dev mode and server-side token usage only.”

依照這個順序閱讀檔案

如果你要實際運用 tinybird-python-sdk-guidelines，建議依序閱讀：

1. SKILL.md：確認範圍與安裝判斷
2. rules/getting-started.md：專案設定
3. rules/configuration.md：config 與 token 解析
4. rules/defining-datasources.md 與 rules/defining-endpoints.md：核心定義
5. rules/client.md 與 rules/cli-commands.md：使用方式與 build/deploy 流程

如果你要做外部整合，再加看 rules/connections.md、rules/materialized-views.md，以及 rules/copy-sink-pipes.md。

通常最容易成功的工作流程

建議照這個順序進行：

1. 先定義你需要的 Tinybird 物件
2. 確認 config 與 dev_mode
3. 產生或更新 lib/*.py
4. 部署前先執行 tinybird build
5. 只有在本機結構驗證無誤後，才使用 tinybird deploy

這一點很重要，因為 tinybird-python-sdk-guidelines 的安裝與使用決策，往往取決於你要的是程式碼產生協助，還是實際的 Tinybird 部署流程。

tinybird-python-sdk-guidelines 技能 FAQ

這只適用於 Python 專案嗎？

是。tinybird-python-sdk-guidelines 技能是圍繞 tinybird-sdk 與以 Python 為主的資源定義設計的。如果你的專案主要是 SQL 檔或 Tinybird UI，可能有別的工作流程更簡單。

我需要先有 Tinybird 經驗嗎？

不需要，但你需要清楚知道自己要做什麼：datasource、endpoint、ingestion client，還是 connection。初學者通常只要提供範例 schema 或查詢，比起要求一個籠統的 Tinybird 架構，更容易更快得到可用結果。

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

一般提示詞也許能產生程式碼，但 tinybird-python-sdk-guidelines 技能還把 Tinybird 特有的限制一起編進去：config 檔優先順序、server-side token 處理、branch 與 main 的部署行為，以及 CLI 的 build/deploy 模式。這能減少反覆試錯。

什麼情況下不該用它？

不要把 tinybird-python-sdk-guidelines 用在瀏覽器端 token flow、一般性的 Python API 設計，或不涉及 Tinybird 資源的分析工作上。如果你只想做一次性的 SQL 查詢，而且沒有 Python 專案結構，它也不是理想選擇。

如何改善 tinybird-python-sdk-guidelines 技能

提供明確的 Tinybird 物件與環境

要讓 tinybird-python-sdk-guidelines 發揮最好效果，輸入一定要夠精準。請直接說明你需要的是：

• define_datasource、define_endpoint、define_connection，或 client 設定
• dev_mode 分支行為，或本機行為
• 從舊檔案遷移，或從零建立 scaffolding
• 單一資源，還是整個專案結構

像「幫我設好 Tinybird」這種模糊需求，通常只會得到很泛的輸出。相較之下，「為 clickstream events 定義一個 datasource，使用 t.date_time()、t.string() 與 merge tree sorting key，然後示範 client 檔案」就能提供足夠結構，產出更實用的內容。

先把限制條件講清楚

請一開始就把可能阻礙採用的限制一起提供：

• secret 處理需求
• 現有資料夾結構，例如 lib/ 或 tinybird/
• 部署目標，以及 main 是否受保護
• 你需要的是 tinybird build、tinybird dev，還是 tinybird migrate

這些資訊很重要，因為 tinybird-python-sdk-guidelines 的輸出只有在避開不安全預設值，並選對 CLI 路徑時，才最有價值。

從 schema 迭代到可部署程式碼

如果第一次結果已經接近，但還不完整，可以再補充：

• 範例資料列
• 欄位型別與 nullable 欄位
• endpoint 參數與預設值
• 精確的 SQL 邏輯或 data source 名稱

接著再要求第二輪檢查 config、client imports，以及 build/deploy 的可用性。這是把草稿快速整理成真正符合 Tinybird repo 的最快方式。