turbo-builder

流水线构建器

边界

• 构建新流水线。不要诊断故障流水线——这属于 /turbo-doctor 的职责。
• 不要充当 YAML 参考文档。如果用户只需要查询字段或语法，请改用 /turbo-pipelines 技能。
• 查询数据集时，请使用 /datasets。
• 使用 REST 查询单个钱包的余额或转账记录，属于 /feeds 的范畴。只有在需要将数据行写入用户自己的数据库或 Webhook 时，才构建流水线。

逐步引导用户从头开始构建完整的流水线。生成有效的 YAML 配置、进行验证并部署。

构建器工作流

步骤 1：验证身份验证状态

运行 goldsky project list 2>&1 检查登录状态。

• **如果已登录：**记下当前项目并继续。
• **如果未登录：**使用 /auth-setup 技能获取指导。

步骤 2：了解目标

询问用户想要索引什么。可以询问：

• 哪个区块链/链？（Ethereum、Base、Polygon、Solana 等）
• 哪些数据？（转账、兑换、特定合约发出的事件、所有交易等）
• 数据应该写入哪里？（PostgreSQL、ClickHouse、Kafka、S3 等）
• 是否需要转换？（筛选、聚合、丰富数据）
• 是一次性回填还是持续流式处理？

如果用户已经描述了目标，请从描述中提取答案。

步骤 3：选择数据集

使用 /datasets 技能查找合适的数据集。

要点：

• 常见数据集：<chain>.raw_logs、<chain>.raw_transactions、<chain>.erc20_transfers、<chain>.raw_traces
• 对于 EVM 链上已解码的合约事件：从 <chain>.raw_logs 读取，并且只按 address 筛选；然后添加一个 SQL 转换，调用 _gs_log_decode(_gs_fetch_abi(<explorer-url>, <source>), topics, data) AS decoded，接着使用 WHERE decoded.event_signature = '<EventName>(<types>)' 在下游筛选。切勿在源筛选条件中放入 topic0 哈希——完整模式请参阅 /turbo-transforms。不存在可供消费的 <chain>.decoded_logs 数据集；解码始终在转换中进行。
• 对于预解码的常见代币事件，可使用 <chain>.erc20_transfers、<chain>.erc721_transfers、<chain>.erc1155_transfers，无需解码转换。
• 对于 Solana：使用 solana.transactions、solana.token_transfers 等。

向用户展示数据集选择并请其确认。

步骤 4：配置数据源

编写 YAML 的数据源部分：

sources:
  my_source:
    type: dataset
    dataset_name: <chain>.<dataset>
    version: 1.0.0
    start_at: latest  # REQUIRED — see below. `latest` or `earliest` (Solana uses `start_block` instead)

必须指定起始位置，不能省略。 绝不要在未明确设置 start_at 的情况下输出数据集数据源——EVM、NEAR、Bitcoin 和 Stellar 都使用此字段。省略它并不意味着“从现在开始”：后端会从最早可用的数据开始，因此管道会悄悄回填整条链的历史数据。这会导致管道运行数天、写入数百万行，并在到达实时数据之前就填满其接收端。Solana 是例外——它使用数字 start_block，省略该字段会从最新的 slot 开始，因此请明确说明你选择了什么，不要让用户猜测。

如果用户尚未说明起始位置，请先询问，再编写 YAML——准确提供以下三个选项：

1. 从现在开始（start_at: latest）——不回填，仅处理实时数据。
2. 从历史中的特定位置开始——使用 start_at: earliest，并在数据源的 filter 中添加 block_number 谓词（在数据源处预先应用，因此被排除的范围不会到达接收端）。Solana 使用数字 start_block；Stellar 也接受 ledger 序列号（start_at: 60000000）。在其他链上，区块号不是有效的 start_at 值：EVM、NEAR 和 Bitcoin 只能使用 earliest 或 latest，不能使用其他值。
3. 完整历史数据（start_at: earliest）——明确说明这会重放整条链的历史数据：实时数据到达前需要数天回填，并会产生数百万行；接收端必须有足够空间容纳所有数据。

还要询问：

• 结束区块： 仅适用于 Solana 作业模式下的回填——EVM 数据集数据源会静默忽略 end_block，因此应使用 filter 中的 block_number 谓词来限定 EVM 范围。流式处理时省略。
• 数据源级筛选器： 用于在数据源处减少数据的可选筛选器（例如，指定合约地址）

步骤 5：配置转换（如有需要）

如果用户需要转换，请使用 /turbo-transforms 技能提供帮助：

• SQL 转换——使用 DataFusion SQL 筛选、聚合、联接或重塑数据
• TypeScript 转换——用于自定义逻辑、外部 API 调用和复杂处理
• 动态表——与 PostgreSQL 表或内存允许列表联接

编写转换部分：

transforms:
  my_transform:
    type: sql
    primary_key: id
    sql: |
      SELECT * FROM my_source
      WHERE <conditions>

步骤 6：配置汇聚目标

询问数据应该写入哪里。使用 /turbo-pipelines 技能配置汇聚目标：

汇聚目标	关键配置
PostgreSQL	secret_name、schema、table、primary_key（可选，用于启用 upsert）
MySQL	secret_name、schema、table、primary_key（可选，用于启用 upsert）
ClickHouse	secret_name、table、primary_key（必填，用于设置排序和去重）
Kafka	secret_name、topic
Pub/Sub（仅限 Turbo）	secret_name、topic
SQS	secret_name、queue_url
S3	bucket、region、prefix、format
Webhook	url、format

如果用户指定了多个目标，请生成一个包含多个汇聚目标的管道——不要为每个目标分别生成一个管道。 每个汇聚目标都有一个 from: 字段，用于按名称引用数据源（或转换），各汇聚目标独立运行。如果不同汇聚目标需要同一数据源的不同视图，请使用扇出模式——为每个视图添加一个 SQL 转换，然后将每个汇聚目标的 from: 指向相应的转换。示例请参阅 /turbo-pipelines 中的 references/architecture-patterns.md 和 templates/multi-sink-pipeline.yaml。

仅当数据源根本不同（例如生命周期独立的不同链）或用户明确要求分开时，才拆分为多个管道。

对于需要 secret_name 的汇聚目标，请检查密钥是否存在：

goldsky secret list

如果密钥不存在，请使用 /secrets 技能帮助创建。

还没有 Postgres 数据库？ 在 Scale 套餐或更高套餐中，你可以创建由 Goldsky 托管的 Postgres（Neon）数据库，并一步将其凭据存储为密钥：

goldsky hosted-sink create --type postgres

此命令会打印所创建密钥的名称、ID 和类型（绝不会打印连接字符串）。将打印出的名称用作汇聚目标的 secret_name。如果账户没有访问权限，该命令会返回 Scale 套餐升级提示及团队账单 URL——此时请改用 /secrets 技能接入外部 Postgres。

推荐汇聚目标前，请根据回填数据量评估其容量。 如果步骤 4 中的起始位置是 earliest，或用户描述的是数月范围或完整历史范围，请在推荐免费套餐数据库之前明确说明这一点，无论数据库是用户自己的还是新创建的。512 MB 的免费套餐无法容纳高流量数据集数月的回填，而且故障表现很隐蔽：管道验证和部署成功，状态显示为 Running，随后却报错 could not extend file because project size limit (512 MB) has been exceeded，同时检查点超时且没有写入任何数据。请在部署前推荐付费或容量足够的数据库，或者缩小起始范围。事后诊断请参阅 /turbo-operations 中有关存储空间超限的条目。

步骤 7：选择模式

使用 /turbo-pipelines 技能获取指导：

• 流式模式（默认）——持续处理，不设置 end_block，无限期运行
• 作业模式——一次性回填，设置 job: true，并指定一个边界：在 EVM 的数据源 filter 中设置 block_number 上限（这也会使数据源有界），或在 Solana 中设置 end_block

步骤 8：生成、验证并展示

组装完整的管道 YAML。使用描述性名称，并遵循以下约定：<chain>-<data>-<sink>（例如 base-erc20-transfers-postgres）。

1. 将 YAML 文件写入磁盘（例如 <pipeline-name>.yaml）。
2. 向用户展示 YAML 之前，先运行验证：

goldsky turbo validate <pipeline-name>.yaml

3. 如果验证失败，请修复问题并重新验证。验证通过前，不要向用户展示 YAML。常见修复项：

   • 数据集数据源缺少 version 字段
   • 数据集名称无效（检查链前缀）
   • 数据库汇聚目标缺少 secret_name
   • 转换中的 SQL 语法错误

4. 验证通过后，向用户展示完整的 YAML 供其审阅。

步骤 9：部署

用户确认 YAML 无误后：

goldsky turbo apply <pipeline-name>.yaml

第 10 步：验证

部署后：

goldsky turbo list

建议运行 inspect 来验证数据流：

goldsky turbo inspect <pipeline-name> -p

要筛选特定节点：goldsky turbo inspect <pipeline-name> -n <node-name> -p。

提供摘要：

## Pipeline Deployed

**Name:** [name]
**Chain:** [chain]
**Dataset:** [dataset]
**Sink:** [sink type]
**Mode:** [streaming/job]

**Next steps:**
- Verify data flow with `goldsky turbo inspect <name> -p`
- Check logs with `goldsky turbo logs <name>`
- Use /turbo-doctor if you run into issues

重要规则

• 向用户展示完整 YAML 前，务必先进行验证。切勿展示未经验证的完整流水线 YAML。
• 部署前务必进行验证。
• 部署前务必向用户展示完整 YAML。
• 对于作业模式的流水线，请提醒用户它们会在完成约 1 小时后自动清理。
• 测试流水线时，使用 blackhole sink，避免写入真实目标。
• 如果用户想修改现有流水线，请确认它是流式模式（原地更新）还是作业模式（必须先删除）。
• 切勿在没有明确起始位置的情况下输出数据集源。切勿默认使用 start_at: earliest——请询问用户是从现在开始、从历史中的特定位置开始，还是从完整历史开始；如果用户选择完整历史，请警告他们系统会在接收实时数据前重放整条链的全部历史记录，并确认 sink 有足够的空间。
• 对于跨多个月或全历史回填，切勿推荐免费版数据库（512 MB）作为 sink。
• 数据集源中务必包含 version: 1.0.0。

相关内容

• /turbo-pipelines — YAML 配置和架构参考
• /turbo-doctor — 诊断并修复流水线问题
• /turbo-operations — 生命周期命令和监控参考
• /turbo-transforms — SQL 和 TypeScript 转换参考
• /datasets — 数据集名称和链前缀
• /secrets — sink 凭据管理