n8n 工作流构建器

环境准备

需配置以下两个环境变量：

• N8N_URL — n8n 实例地址（例如：https://your-n8n.example.com）
• N8N_API_KEY — n8n API 密钥（设置 → API → 创建 API 密钥）

工作流构建流程

1. 理解自动化需求 — 明确触发方式（Webhook / 定时调度 / 手动执行）、数据源、处理逻辑、输出目标及错误处理要求。

2. 设计工作流 JSON — 依据 references/workflow-schema.md 中定义的 Schema 编写合法的 n8n 工作流 JSON。可参考 references/workflow-patterns.md 中提供的常用模式作为模板。

3. 通过 API 部署 — 使用 scripts/n8n-api.sh create 命令从文件部署，或通过管道将 JSON 输入至 scripts/n8n-api.sh create-stdin。

4. 启用工作流 — 对于基于触发器的工作流，使用 scripts/n8n-api.sh activate 启用。

5. 验证部署结果 — 列出所有工作流以确认是否成功部署：scripts/n8n-api.sh list。

API 脚本参考

# 列出全部工作流
scripts/n8n-api.sh list

# 从 JSON 文件创建工作流
scripts/n8n-api.sh create /tmp/workflow.json

# 从标准输入创建工作流
echo '{"name":"Test",...}' | scripts/n8n-api.sh create-stdin

# 获取、启用、停用、删除、执行工作流
scripts/n8n-api.sh get 
scripts/n8n-api.sh activate 
scripts/n8n-api.sh deactivate 
scripts/n8n-api.sh delete 
scripts/n8n-api.sh execute 

# 列出凭证与标签
scripts/n8n-api.sh credentials
scripts/n8n-api.sh tags

构建 Workflow JSON

每个工作流必须包含：name、nodes[]、connections{}、settings{}。

每个节点必须包含：id、name、type、typeVersion、position、parameters。

连接关系（connections）以源节点的显示名称（display name）为键，映射其输出至目标节点。

完整 Schema、支持的节点类型及表达式语法，请参阅 references/workflow-schema.md； 涵盖 Webhook、定时调度、AI Agent、数据库同步、错误处理等场景的完整工作流示例，请参阅 references/workflow-patterns.md。

关键规范

• settings 中必须始终设置 "executionOrder": "v1"
• 节点名称（name）在单个工作流内必须唯一
• 节点 ID（id）必须唯一 — 建议使用具描述性的 slug，例如 webhook1、code1
• 节点位置（position）应从 [250, 300] 开始，并保持约 200px 的水平间距
• IF 节点具有两个输出分支：索引 0 表示 true 分支，索引 1 表示 false 分支
• Webhook 类型工作流 若 responseMode 设为 responseNode，则必须包含 respondToWebhook 节点
• 凭证（Credentials）必须已在 n8n 中预先创建 — 可通过 scripts/n8n-api.sh credentials 检查
• 启用前务必测试 — 对手动触发类工作流，使用 scripts/n8n-api.sh execute 进行验证
• 对存在风险的 HTTP/API 节点，应设置 continueOnFail: true，并在后续节点中显式检查错误

常见房地产领域工作流示例

• 线索接入（Lead intake）：Webhook → 数据校验 → 去重 → 写入数据库 → Slack/SMS 通知
• 电话跟进（Call follow-up）：定时调度 → 查询数据库中已完成通话记录 → 根据通话结果发送 SMS/Email
• 培育式营销（Drip campaign）：定时调度 → 按线索阶段查询 → 发送对应阶段的 Email/SMS
• CRM 同步（CRM sync）：Webhook → 数据转换 → 同步更新 HubSpot/Salesforce 及内部数据库
• 房源提醒（Property alerts）：定时调度 → 爬取或调用房源 API → 筛选新增房源 → 推送通知给潜在客户
• AI 线索甄别（AI qualification）：Webhook → AI Agent（识别客户意图）→ 分流至对应销售管线