superplane-canvas-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SuperPlane Canvas Builder

SuperPlane 工作流画布构建器

Translate workflow requirements into SuperPlane canvas YAML.

将工作流需求转换为SuperPlane画布YAML文件。

Quick Reference

快速参考

Task	Command
List components	`superplane index components`
Components from integration	`superplane index components --from <integration>`
Describe a component	`superplane index components --name <name>`
List triggers	`superplane index triggers --from <integration>`
Create canvas	`superplane canvases create --file canvas.yaml`
Update canvas	`superplane canvases update -f canvas.yaml`

任务	命令
列出组件	`superplane index components`
查看集成中的组件	`superplane index components --from <integration>`
查看组件详情	`superplane index components --name <name>`
列出触发器	`superplane index triggers --from <integration>`
创建画布	`superplane canvases create --file canvas.yaml`
更新画布	`superplane canvases update -f canvas.yaml`

Order of Operations

操作流程

Always follow this sequence. The CLI is the primary path — it gives exact names, IDs, and schemas that documentation cannot reliably substitute.

请严格遵循以下步骤。CLI是首选方式——它能提供文档无法可靠替代的准确名称、ID和模式。

1. Verify CLI and Connect

1. 验证CLI并完成连接

bash

superplane whoami

command not found

: stop. Tell the user to install the CLI from https://docs.superplane.com/installation/cli and re-run the task. Do not attempt to install it on their behalf. Do not silently fall back to doc-based design.

If not yet connected:

bash

superplane connect <URL> <TOKEN>
superplane whoami

bash

superplane whoami

如果出现

command not found

：停止操作。告知用户从https://docs.superplane.com/installation/cli安装CLI后再重新执行任务。请勿尝试代用户安装，也不要默认使用基于文档的设计方式。

如果尚未完成连接：

bash

superplane connect <URL> <TOKEN>
superplane whoami

2. Understand the Workflow

2. 理解工作流需求

Before running discovery commands, identify what the workflow needs:

What starts it? → trigger (schedule, webhook, GitHub push, manual)
What steps happen? → each step is a component node
Any decisions? → If or Filter components for branching
Any waits? → Approval, Time Gate, Wait components
Which external systems? → each maps to a provider (e.g., GitHub, Slack, Daytona)

Collect the list of required providers from this analysis — you will check them in the next step.

在执行发现命令之前，先明确工作流的需求：

工作流的启动方式？ → 触发器（定时调度、Webhook、GitHub推送、手动触发）
包含哪些步骤？ → 每个步骤对应一个组件节点
是否需要分支判断？** → 使用If或Filter组件实现分支
是否需要等待环节？** → 使用Approval、Time Gate、Wait组件
涉及哪些外部系统？ → 每个系统对应一个提供商（例如GitHub、Slack、Daytona）

通过分析收集所需提供商列表，下一步将进行验证。

3. Discover and Verify Integrations

3. 发现并验证集成

Run

superplane integrations list

to get all connected integrations in the org. Compare against the required providers from step 2.

If any required provider is missing: stop and tell the user before writing any YAML. Example:

This canvas needs GitHub and Daytona integrations. Your org has GitHub connected but Daytona is not connected. Please connect it in the SuperPlane UI (Settings → Integrations) before proceeding.

Do not generate YAML that references providers the org has not connected — it will fail with "integration is required" on every affected node.

Once all providers are confirmed connected, discover exact names and schemas:

bash

superplane integrations list                          # connected instances → real integration IDs
superplane index triggers --from <provider>           # exact trigger names
superplane index components --from <provider>         # exact component names

Inspect required config fields and payload shape:

bash

superplane index triggers --name github.onPush
superplane index components --name semaphore.runWorkflow

List runtime options for

integration-resource

fields:

bash

superplane integrations list-resources --id <id> --type <type>

执行

superplane integrations list

获取组织中所有已连接的集成，与步骤2中收集的所需提供商列表进行对比。

**如果缺少任何所需提供商：**停止操作并告知用户，再开始编写YAML。示例：

该画布需要GitHub和Daytona集成。您的组织已连接GitHub，但未连接Daytona。请先在SuperPlane UI（设置→集成）中完成连接，再继续操作。

请勿生成引用未连接提供商的YAML文件——这会导致受影响的节点出现“integration is required”错误。

确认所有提供商已连接后，获取准确的名称和模式：

bash

superplane integrations list                          # 已连接实例 → 实际集成ID
superplane index triggers --from <provider>           # 准确的触发器名称
superplane index components --from <provider>         # 准确的组件名称

查看所需的配置字段和负载结构：

bash

superplane index triggers --name github.onPush
superplane index components --name semaphore.runWorkflow

列出

integration-resource

字段的运行时选项：

bash

superplane integrations list-resources --id <id> --type <type>

4. Select Components and Wire the Graph

4. 选择组件并连接工作流图

Use the exact trigger and component names from step 3 — not guesses from documentation.

If the trigger supports built-in filtering (content filter, action filter, ref filter), configure it at the trigger level. Only add a separate Filter or If node when you need logic the trigger's native config cannot express.
Every component needs at least one incoming edge
Triggers have no incoming edges
Use named channels for branching (If →
```
true
```
/
```
false
```
, Approval →
```
approved
```
/
```
rejected
```
)
Filter only emits to
```
default
```
when the expression is true; false events stop silently
Use Merge to fan-in parallel branches

See Components & Triggers Reference for the full list.

使用步骤3中获取的准确触发器和组件名称——不要根据文档猜测。

如果触发器支持内置过滤（内容过滤、操作过滤、引用过滤），请在触发器层面配置。仅当触发器原生配置无法实现所需逻辑时，再添加独立的Filter或If节点。
每个组件至少需要一条入站连接边
触发器没有入站连接边
使用命名通道实现分支（If →
```
true
```
/
```
false
```
，Approval →
```
approved
```
/
```
rejected
```
）
Filter仅在表达式为true时向
```
default
```
通道发送事件；false事件会静默终止
使用Merge组件合并并行分支

完整列表请查看组件与触发器参考。

5. Position Nodes

5. 节点定位

Every node needs a

position: { x, y }

. Nodes are 515px wide × 215px tall — use these spacing rules to prevent overlap:

Direction	Increment	Why
Horizontal (x)	+600px per column	515 width + 85 gap
Vertical (y)	+300px per row	215 height + 85 gap

Start the first node (trigger) at

{ x: 120, y: 100 }

Linear pipeline — same y, increment x:

Trigger: { x: 120, y: 100 }  →  Step A: { x: 720, y: 100 }  →  Step B: { x: 1320, y: 100 }

Branching — branches share the same x column, spread on y. Center the source node vertically relative to its branches:

                                ┌─ Branch A: { x: 1320, y: 100 }
Source: { x: 720, y: 250 }  ───┤
                                └─ Branch B: { x: 1320, y: 400 }

Fan-in (Merge) — next x column after branches, y centered between them:

Branch A: { x: 1320, y: 100 } ──┐
                                 ├── Merge: { x: 1920, y: 250 }
Branch B: { x: 1320, y: 400 } ──┘

For 3+ branches, keep adding 300 to y for each branch and center the source/merge accordingly.

每个节点都需要配置

position: { x, y }

。节点尺寸为515px宽 × 215px高——请遵循以下间距规则避免重叠：

方向	增量	原因
水平方向（x）	+600px 每列	515px宽度 + 85px间距
垂直方向（y）	+300px 每行	215px高度 + 85px间距

第一个节点（触发器）的起始位置为

{ x: 120, y: 100 }

。

线性流水线 —— y值相同，x值递增：

Trigger: { x: 120, y: 100 }  →  Step A: { x: 720, y: 100 }  →  Step B: { x: 1320, y: 100 }

分支结构 —— 分支位于同一x列，y值分散。源节点垂直居中于分支节点之间：

                                ┌─ Branch A: { x: 1320, y: 100 }
Source: { x: 720, y: 250 }  ───┤
                                └─ Branch B: { x: 1320, y: 400 }

合并（Fan-in） —— 位于分支的下一列x，y值居中于分支节点之间：

Branch A: { x: 1320, y: 100 } ──┐
                                 ├── Merge: { x: 1920, y: 250 }
Branch B: { x: 1320, y: 400 } ──┘

对于3个及以上分支，每个分支的y值依次增加300，并相应调整源节点/合并节点的居中位置。

6. Configure Expressions

6. 配置表达式

STOP before writing any expression that references payload fields you have not confirmed. Do not guess field paths from trigger or component names.

注意：在编写任何引用负载字段的表达式之前，请先确认字段的存在。不要根据触发器或组件名称猜测字段路径。

Envelope

信封结构

Every node output is wrapped in an envelope:

{ data: {...}, timestamp, type }

. All three access patterns return this envelope, so you always need

.data.

to reach the actual payload:

Pattern	Description
`$['Node Name'].data.field`	Access any upstream node's output by name
`root().data.field`	Access the root event that started the run
`previous().data.field`	Access the immediate upstream node's output

Common mistake: writing
$['Create Sandbox'].id
instead of
$['Create Sandbox'].data.id
. Always include
.data.
.

Use double curly braces

{{ }}

for expressions in configuration fields:

{{ $['GitHub onPush'].data.ref }}

每个节点的输出都包裹在信封中：

{ data: {...}, timestamp, type }

。以下三种访问方式都会返回该信封，因此必须使用

.data.

才能访问实际负载：

方式	描述
`$['Node Name'].data.field`	通过名称访问任意上游节点的输出
`root().data.field`	访问启动工作流运行的根事件
`previous().data.field`	访问直接上游节点的输出

常见错误：写成
$['Create Sandbox'].id
而非
$['Create Sandbox'].data.id
。请始终包含
.data.
。

在配置字段中使用双大括号

{{ }}

包裹表达式：

{{ $['GitHub onPush'].data.ref }}

How to confirm payload fields

如何确认负载字段

Check these sources in order — use the first one available:

Existing executions — inspect real payloads from prior runs (most reliable):
bash
```
superplane executions list --canvas-id <id> --node-id <nid> -o yaml
```
Provider reference files in this skill — check the
```
references/
```
directory for the provider you are using. These contain payload examples and known gotchas.
SuperPlane docs — fetch the provider's component page from the LLM-friendly docs:
- Compact index: https://docs.superplane.com/llms.txt
- Full content: https://docs.superplane.com/llms-full.txt

After the first real execution, always go back to source 1 to verify and correct expressions. The trigger name does not map 1:1 to payload structure — always check the provider reference file or docs for the actual webhook event a trigger maps to.

请按以下顺序检查来源——使用第一个可用的来源：

现有执行记录 —— 查看之前运行的真实负载（最可靠）：
bash
```
superplane executions list --canvas-id <id> --node-id <nid> -o yaml
```
本技能中的提供商参考文件 —— 查看
```
references/
```
目录下对应提供商的文件。这些文件包含负载示例和已知问题。
SuperPlane文档 —— 从LLM友好的文档中获取提供商的组件页面：
- 精简索引：https://docs.superplane.com/llms.txt
- 完整内容：https://docs.superplane.com/llms-full.txt

首次执行后，请务必回到来源1验证并修正表达式。触发器名称与负载结构并非一一对应——请始终查看提供商参考文件或文档，确认触发器映射的实际Webhook事件。

7. Apply

7. 应用配置

bash

superplane canvases create --file canvas.yaml

bash

superplane canvases create --file canvas.yaml

or update an existing canvas:

或更新现有画布：

superplane canvases update --file canvas.yaml


Then verify:

```bash
superplane canvases get <name>

Check for

errorMessage

warningMessage

on any node.

superplane canvases update --file canvas.yaml


然后验证：

```bash
superplane canvases get <name>

检查是否有节点存在

errorMessage

或

warningMessage

。

Fallback: When CLI Is Not Available

备选方案：当CLI不可用时

If the CLI cannot be installed or used (e.g., user declines, environment restriction):

Build the canvas YAML from documentation and skill references.
Use placeholders for integration IDs (e.g.,
```
<GITHUB_INTEGRATION_ID>
```
) and list which providers the canvas requires.
Add a clear note to the user that they must:
- Connect any missing integrations in the SuperPlane UI (Settings → Integrations).
- Install the CLI or use the UI to obtain real integration IDs.
- Replace all placeholders before applying.
- Run
```
superplane canvases create --file canvas.yaml
```
  (or use the UI) to apply.

This path is slower and less reliable. Always prefer the CLI.

如果无法安装或使用CLI（例如用户拒绝、环境限制）：

根据文档和技能参考构建画布YAML文件。
为集成ID使用占位符（例如
```
<GITHUB_INTEGRATION_ID>
```
），并列出画布所需的提供商。
向用户添加明确说明：
- 在SuperPlane UI（设置→集成）中连接所有缺失的集成。
- 安装CLI或使用UI获取真实的集成ID。
- 应用前替换所有占位符。
- 执行
```
superplane canvases create --file canvas.yaml
```
  （或使用UI）完成应用。

此方式速度更慢且可靠性更低。请优先使用CLI。

Common Patterns

常见模式

Linear: Trigger → A → B → C

线性流水线：Trigger → A → B → C

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 1320, y: 100 } }
  - { id: c, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: a, targetId: b, channel: default }
  - { sourceId: b, targetId: c, channel: default }

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 1320, y: 100 } }
  - { id: c, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: a, targetId: b, channel: default }
  - { sourceId: b, targetId: c, channel: default }

Branch: If → true / false

分支结构：If → true / false

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: check, ..., component: { name: if }, position: { x: 720, y: 250 } }
  - { id: on-true, ..., position: { x: 1320, y: 100 } }
  - { id: on-false, ..., position: { x: 1320, y: 400 } }
edges:
  - { sourceId: trigger, targetId: check, channel: default }
  - { sourceId: check, targetId: on-true, channel: true }
  - { sourceId: check, targetId: on-false, channel: false }

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: check, ..., component: { name: if }, position: { x: 720, y: 250 } }
  - { id: on-true, ..., position: { x: 1320, y: 100 } }
  - { id: on-false, ..., position: { x: 1320, y: 400 } }
edges:
  - { sourceId: trigger, targetId: check, channel: default }
  - { sourceId: check, targetId: on-true, channel: true }
  - { sourceId: check, targetId: on-false, channel: false }

Gate: Filter (pass or stop)

过滤网关：Filter（通过或终止）

Filter only emits to

default

when true. False events stop — no edge needed.

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: filter, ..., component: { name: filter }, position: { x: 720, y: 100 } }
  - { id: next-step, ..., position: { x: 1320, y: 100 } }
edges:
  - { sourceId: trigger, targetId: filter, channel: default }
  - { sourceId: filter, targetId: next-step, channel: default }

Filter仅在表达式为true时向

default

通道发送事件。false事件会静默终止——无需配置连接边。

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 100 } }
  - { id: filter, ..., component: { name: filter }, position: { x: 720, y: 100 } }
  - { id: next-step, ..., position: { x: 1320, y: 100 } }
edges:
  - { sourceId: trigger, targetId: filter, channel: default }
  - { sourceId: filter, targetId: next-step, channel: default }

Fan-out / Fan-in

扇出/扇入结构

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 720, y: 400 } }
  - { id: merge, ..., position: { x: 1320, y: 250 } }
  - { id: final, ..., position: { x: 1920, y: 250 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: trigger, targetId: b, channel: default }
  - { sourceId: a, targetId: merge, channel: default }
  - { sourceId: b, targetId: merge, channel: default }
  - { sourceId: merge, targetId: final, channel: default }

yaml

nodes:
  - { id: trigger, ..., position: { x: 120, y: 250 } }
  - { id: a, ..., position: { x: 720, y: 100 } }
  - { id: b, ..., position: { x: 720, y: 400 } }
  - { id: merge, ..., position: { x: 1320, y: 250 } }
  - { id: final, ..., position: { x: 1920, y: 250 } }
edges:
  - { sourceId: trigger, targetId: a, channel: default }
  - { sourceId: trigger, targetId: b, channel: default }
  - { sourceId: a, targetId: merge, channel: default }
  - { sourceId: b, targetId: merge, channel: default }
  - { sourceId: merge, targetId: final, channel: default }

Approval Gate

审批网关

yaml

nodes:
  - { id: ci-done, ..., position: { x: 120, y: 100 } }
  - { id: timegate, ..., position: { x: 720, y: 100 } }
  - { id: approval, ..., position: { x: 1320, y: 100 } }
  - { id: deploy, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: ci-done, targetId: timegate, channel: default }
  - { sourceId: timegate, targetId: approval, channel: default }
  - { sourceId: approval, targetId: deploy, channel: approved }

yaml

nodes:
  - { id: ci-done, ..., position: { x: 120, y: 100 } }
  - { id: timegate, ..., position: { x: 720, y: 100 } }
  - { id: approval, ..., position: { x: 1320, y: 100 } }
  - { id: deploy, ..., position: { x: 1920, y: 100 } }
edges:
  - { sourceId: ci-done, targetId: timegate, channel: default }
  - { sourceId: timegate, targetId: approval, channel: default }
  - { sourceId: approval, targetId: deploy, channel: approved }

When to Use Other Skills

何时使用其他技能

Need	Use Skill
CLI commands and authentication	superplane-cli
Debug a failed run	superplane-monitor

需求	使用技能
CLI命令与认证	superplane-cli
调试失败的运行	superplane-monitor

Documentation

文档

For agents that can fetch URLs, the full SuperPlane docs are available in LLM-friendly format:

Compact index: https://docs.superplane.com/llms.txt
Full content: https://docs.superplane.com/llms-full.txt

对于可获取URL的Agent，完整的SuperPlane文档提供LLM友好格式：

精简索引：https://docs.superplane.com/llms.txt
完整内容：https://docs.superplane.com/llms-full.txt

References

参考资料

Components & Triggers — Built-in components and trigger types
GitHub — Triggers, components, payload examples, gotchas
Daytona — Components, payload examples, gotchas

组件与触发器 —— 内置组件和触发器类型
GitHub —— 触发器、组件、负载示例、已知问题
Daytona —— 组件、负载示例、已知问题