用代码创建你的第一个工作流
在本教程中,你将使用 Workflow SDK 编写一个工作流文件,用 validate_workflow 检查它,并用 create_workflow_from_code 将其保存到你的实例。
提示
给编码代理的提示词
连接到 n8n MCP 服务器,调用 get_workflow_sdk_reference,然后为下文描述的工作流编写 Workflow SDK 文件。使用完整代码调用 validate_workflow,修复 hint 指出的每个错误,然后调用 create_workflow_from_code 并返回工作流 URL。
你需要准备什么
- 一个已启用 MCP 访问的 n8n 实例,以及一个已连接到该实例的 MCP 客户端。客户端连接示例涵盖了 Claude Code、Claude Desktop 和 Cursor。
- 无需本地安装,由实例解析代码。
你将学到什么
- Workflow SDK 文件的结构。
- 如何在创建工作流之前检查代码。
- 如何添加分支。
编写工作流文件
创建包含以下内容的 github-stars.ts。它包含一个手动触发器、一个 HTTP Request 节点和一个 Edit Fields (Set) 节点:
import { workflow, node, trigger, expr } from '@n8n/workflow-sdk';
const start = trigger({
type: 'n8n-nodes-base.manualTrigger',
version: 1,
config: { name: 'Start' }
});
const fetchRepo = node({
type: 'n8n-nodes-base.httpRequest',
version: 4.3,
config: {
name: 'Fetch repository',
parameters: { method: 'GET', url: 'https://api.github.com/repos/n8n-io/n8n' }
}
});
const keepStars = node({
type: 'n8n-nodes-base.set',
version: 3.4,
config: {
name: 'Keep stars',
parameters: {
mode: 'manual',
includeOtherFields: false,
assignments: {
assignments: [
{ id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
]
}
}
}
});
export default workflow('github-stars', 'GitHub stars')
.add(start)
.to(fetchRepo)
.to(keepStars);
需要记住三条规则:
- 先声明每个节点,最后再组合工作流。
- 使用编辑器所用的节点类型 id 和
version。MCP 服务器上的search_nodes和get_node_types会返回它们。 - 用
expr()包裹表达式。其中的文本与编辑器中的相同。
检查代码
让你的 MCP 客户端调用 validate_workflow,并将完整文件作为 code 参数传入。有效的文件会返回:
{ "valid": true, "nodeCount": 3 }
如果 valid 为 false,响应中会包含 errors 列表,通常还会有 hint。按照提示修复问题,然后再次运行该工具。常见原因包括缺少 export default、节点 version 错误,或使用了节点不具备的参数。
创建工作流
使用相同的 code 调用 create_workflow_from_code。响应中包含 workflowId 和 url。打开该 URL,在编辑器中运行一次工作流,并检查 Keep stars 节点是否输出了 stars 字段。
该工具会将它在实例上找到的凭据分配给需要凭据的节点。它会跳过 HTTP Request 节点,因此如果你调用的 API 需要凭据,请手动为该节点设置凭据。
添加分支
将 Keep stars 节点替换为一个 If 节点,让热门仓库走一条路径,其余仓库走另一条路径。为每个分支添加一个 Edit Fields 节点。每个 If 条件都需要 options、conditions 和 combinator。完整文件如下:
import { workflow, node, trigger, ifElse, expr } from '@n8n/workflow-sdk';
const start = trigger({
type: 'n8n-nodes-base.manualTrigger',
version: 1,
config: { name: 'Start' }
});
const fetchRepo = node({
type: 'n8n-nodes-base.httpRequest',
version: 4.3,
config: {
name: 'Fetch repository',
parameters: { method: 'GET', url: 'https://api.github.com/repos/n8n-io/n8n' }
}
});
const isPopular = ifElse({
version: 2.2,
config: {
name: 'Is popular?',
parameters: {
conditions: {
options: { caseSensitive: true, leftValue: '', typeValidation: 'strict' },
conditions: [
{ leftValue: expr('{{ $json.stargazers_count }}'), operator: { type: 'number', operation: 'gt' }, rightValue: 100000 }
],
combinator: 'and'
}
}
}
});
const markPopular = node({
type: 'n8n-nodes-base.set',
version: 3.4,
config: {
name: 'Mark popular',
parameters: {
mode: 'manual',
includeOtherFields: false,
assignments: {
assignments: [
{ id: 'popular', name: 'popular', value: true, type: 'boolean' },
{ id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
]
}
}
}
});
const markNotPopular = node({
type: 'n8n-nodes-base.set',
version: 3.4,
config: {
name: 'Mark not popular',
parameters: {
mode: 'manual',
includeOtherFields: false,
assignments: {
assignments: [
{ id: 'popular', name: 'popular', value: false, type: 'boolean' },
{ id: 'stars', name: 'stars', value: expr('{{ $json.stargazers_count }}'), type: 'number' }
]
}
}
}
});
export default workflow('github-stars', 'GitHub stars')
.add(start)
.to(fetchRepo)
.to(isPopular
.onTrue(markPopular)
.onFalse(markNotPopular));
每个分支都是一条完整路径:可以在 .onTrue() 或 .onFalse() 中使用 .to() 串联更多节点。
要修改你已创建的工作流,不要再创建第二个。请使用工作流 ID 和由部分更改(例如 addNode 或 updateNodeParameters)组成的 operations 数组调用 update_workflow。工具参考列出了所有操作。
后续步骤
- 阅读你的实例提供的完整参考:在 n8n MCP 服务器上调用
get_workflow_sdk_reference。patterns部分包含循环、并行分支、多个触发器和 AI 代理的完整示例。 - 使用
technique: "list"调用get_workflow_best_practices,查看有指南的用例,例如聊天机器人、调度和数据提取。 - 如需在不使用 MCP 服务器的情况下将代码转换为工作流 JSON,请参阅 SDK README。
- 使用使用 AI 构建设置你的编码代理。