tinybird-typescript-sdk-guidelines

tinybird-typescript-sdk-guidelines 技能概览

这个 skill 用来做什么

tinybird-typescript-sdk-guidelines skill 帮助你在使用 @tinybirdco/sdk 的 TypeScript 项目中，以代码方式定义 Tinybird 资源。它最适合需要类型安全的 datasources、pipes、endpoints、connections 和 typed clients 的后端开发者，避免你靠猜 Tinybird 语法或部署流程来推进。

用户通常需要什么

大多数人安装 tinybird-typescript-sdk-guidelines skill，是为了更快完成三类工作之一：正确定义新的 Tinybird 资源、把旧的 .datasource 和 .pipe 文件迁移到 TypeScript，或者在使用 tinybird dev、tinybird build 和 tinybird deploy 时避免破坏性变更。

这个 skill 为什么不一样

这个 skill 不只是简单扫一遍 repo。它聚焦的是落地时真正重要的实操规则：支持的配置格式、CLI 工作流、仅服务端使用的限制、适合分支开发的安全流程，以及 Tinybird 在 TypeScript 中期望的具体资源模式。

如何使用 tinybird-typescript-sdk-guidelines skill

安装并确认是否适配

使用 npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-typescript-sdk-guidelines 安装 tinybird-typescript-sdk-guidelines skill。使用前先确认你的项目确实是 Tinybird 的 TypeScript 工作流：Node.js 20+、TypeScript 4.9+，并且只能在服务端执行。只有当你的需求涉及 @tinybirdco/sdk 时，这个 skill 才是合适选择；如果只是通用 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。

把模糊目标变成可用的 prompt

给 skill 明确目标、仓库上下文和部署约束。高质量输入会说明资源类型、文件应该放在哪里，以及你是在迁移还是从头开始。

示例：“在 src/tinybird/datasources.ts 里创建一个用于事件采集的 TypeScript Tinybird datasource，使用 mergeTree，增加可空的 country 字段，并保持与 branch dev mode 兼容。”

弱输入：“帮我搭个 Tinybird。”

按真正重要的工作流来走

新项目用 tinybird init，旧文件转换用 tinybird migrate，迭代同步用 tinybird dev，校验用 tinybird build，只有准备好上线时才用 tinybird deploy。当你需要通过 devMode 把开发目标和部署目标严格分开时，tinybird-typescript-sdk-guidelines guide 尤其有用。

tinybird-typescript-sdk-guidelines skill 常见问题

这个 skill 只适合后端开发吗？

是的。tinybird-typescript-sdk-guidelines for Backend Development 这个使用场景才是它的目标定位。它不应该用于浏览器代码，因为 tokens 必须保留在服务端。

如果我已经懂 Tinybird，还需要这个 skill 吗？

如果你已经懂 Tinybird，但需要可靠的 TypeScript 定义、typed 输出，或者希望从旧文件安全迁移，这个 skill 仍然有价值。它能减少你反复核对精确 config 形状、CLI 命令和资源定义模式的时间。

它和普通 prompt 有什么区别？

普通 prompt 可能会给出看起来合理的 Tinybird 建议。这个 skill 提供的是基于 repo 的安装、配置、资源定义和命令流程规则，能降低生成“看起来对、实际项目里却会失败”的代码风险。

什么情况下不应该用它？

如果你的任务和 Tinybird 无关，或者你只需要通用 SQL 解释，或者你在构建一个无法安全保存 tokens 的纯前端功能，就不要使用 tinybird-typescript-sdk-guidelines skill。

如何改进 tinybird-typescript-sdk-guidelines skill

提供准确的资源形态

最好的输出来自一开始就把资源和约束说清楚：datasource、endpoint、connection、materialized view、copy pipe 或 sink pipe。把 schema 字段、sort keys、params、schedule，以及目标环境是 branch、local 还是 production 一并说明。

加上仓库与迁移上下文

如果 skill 是在现有代码库上工作，告诉它文件放在哪里、当前已经有什么。例如：“把 tinybird/**/*.datasource 和 tinybird/**/*.pipe 迁移到 src/tinybird/*.ts，保留现有名称，并在 rollout 期间保持混合格式兼容。”这比泛泛要一个迁移方案要有效得多。

留意常见失败模式

最常见的错误是把 tokens 暴露到 client 代码里、跳过 tinybird.config.*、混淆 devMode 的行为，或者遗漏驱动推断所需的类型细节。如果第一版输出太宽泛，就要求一个更窄的产物：一个 datasource 文件、一个 endpoint，或者一个可以直接执行的 CLI 迁移步骤。

以验证为中心逐步迭代

在第一版之后，继续要求下一个具体检查点：修正后的 config、更强的 schema、更安全的 query，或者一份部署清单。对于 tinybird-typescript-sdk-guidelines guide，最快的改进循环是：先定义一个资源，用 tinybird build 验证，再根据具体报错或缺失的类型推断继续修正。