tinybird-python-sdk-guidelines

tinybird-python-sdk-guidelines 技能概览

这个技能是做什么的

tinybird-python-sdk-guidelines 技能帮助你使用 tinybird-sdk 在 Python 中处理 Tinybird 资源。它最适合需要在 code-first 的 Tinybird 项目里定义 datasource、endpoint、connection 或 client 访问的场景，尤其适用于后端开发和数据摄取工作流。

谁应该使用它

如果你符合以下任一情况，就该使用 tinybird-python-sdk-guidelines 技能：

• 正在启动一个新的 Tinybird Python 项目
• 将旧版 .datasource / .pipe 文件迁移到 Python
• 把 Tinybird 接入后端服务
• 构建必须保持在服务端执行的查询、pipeline 或 ingestion 路径

它比通用提示词强在哪里

这个技能不只是“写 Tinybird 代码”。它会把代码背后的运行规则一起告诉你：配置是如何解析的、哪些 CLI 命令真正关键、client 文件该怎么组织、以及部署最常在哪些地方出错。对于主要风险不是语法，而是配置错乱、不安全的 token 处理，或者用了错误的 dev target 时，tinybird-python-sdk-guidelines 会更有用。

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

安装并启用它

先用仓库的 skill manager 安装 tinybird-python-sdk-guidelines 技能，然后把你的 agent 指向该技能路径：
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
• 运行上下文：本地开发、branch mode 或生产部署
• 输入形态：table schema、SQL、API 参数、secrets 或文件布局
• 期望输出：Python 定义、config 文件或部署计划

一个高质量提示词的示例：
“用 Python 为事件追踪创建一个 Tinybird datasource 和 endpoint。使用 tinybird-sdk，包含 tinybird.config.json，并展示如何在 lib/client.py 中查询它。假设使用 branch dev mode，并且只允许 server-side token 使用。”

按这个顺序阅读文件

要获得实用的 tinybird-python-sdk-guidelines 指导，建议按以下顺序阅读：

1. SKILL.md，了解适用范围和安装决策
2. rules/getting-started.md，了解项目初始化
3. rules/configuration.md，了解配置与 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. 确认配置和 dev_mode
3. 生成或更新 lib/*.py
4. 部署前先运行 tinybird build
5. 只有在本地结构验证通过后，才执行 tinybird deploy

这一点很重要，因为 tinybird-python-sdk-guidelines 的安装决策，往往取决于你更需要代码生成帮助，还是需要真正的 Tinybird 部署工作流。

tinybird-python-sdk-guidelines 技能常见问题

这个技能只适用于 Python 项目吗？

是的。tinybird-python-sdk-guidelines 技能是围绕 tinybird-sdk 和以 Python 为中心的资源定义构建的。如果你的项目主要是 SQL 文件或者 Tinybird UI，可能用另一套流程更简单。

我必须先有 Tinybird 经验吗？

不需要，但你得先知道自己要构建什么：datasource、endpoint、ingestion client 还是 connection。初学者通常会更快上手，只要他们提供一个示例 schema 或 query，而不是直接笼统地问一个宽泛的 Tinybird 架构问题。

它和普通提示词有什么不同？

普通提示词可以生成代码，但 tinybird-python-sdk-guidelines 技能还编码了 Tinybird 的特定约束：config 文件优先级、server-side token 处理、branch 与 main 的部署行为，以及 CLI 的 build/deploy 模式。这能减少反复试错。

什么时候不该用它？

如果你做的是浏览器端 token 流程、通用 Python API 设计，或者根本不涉及 Tinybird 资源的分析任务，就不要用 tinybird-python-sdk-guidelines。它也不适合那种只想临时写一个 SQL 查询、完全没有 Python 项目结构的场景。

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

提供明确的 Tinybird 对象和环境

想让 tinybird-python-sdk-guidelines 发挥最好效果，输入就要足够具体。明确说明你需要的是：

• define_datasource、define_endpoint、define_connection，还是 client setup
• dev_mode 的 branch 行为，还是本地行为
• 从旧文件迁移，还是从零搭建脚手架
• 单个资源，还是完整的项目结构

像“帮我搭一下 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 → 可部署代码”逐步迭代

如果第一次结果已经接近，但还不完整，可以通过补充以下信息来继续优化：

• 示例数据行
• 列类型和可空字段
• endpoint 参数和默认值
• 精确的 SQL 逻辑或 data source 名称

然后再要求第二轮检查配置、client imports，以及 build/deploy 的可执行性。这是把草稿快速打磨成真正适配 Tinybird 仓库的最快方式。