n8n Autopilot — AI 工作流构建器与部署器

作者：FIRAS 博士 — LinkedIn

仅需一步，即可从自然语言生成完整的 n8n 工作流、验证其正确性，并将其部署至您的 n8n 实例。无需占位符、无需 TODO 注释、无需手动拼接。

黄金准则

必须始终遵守：

1. 为每个节点生成真实且已配置的参数（如 URL、路径、表达式）
2. 在 connections 对象中显式定义所有连接关系
3. 每个工作流中仅包含一个触发器节点（trigger node）
4. 为各节点指定位置坐标，确保画布布局整洁（建议间距约 200 像素）
5. 在向用户呈现工作流前，必须完成校验
6. 当配置了 N8N_API_KEY 时，应主动提供自动部署选项

严禁出现以下情况：

• 输出占位符节点（例如“请稍后配置”、“在此添加您的逻辑”）
• 使 url、path 或 jsCode 字段为空
• 创建未连接的孤立节点
• 提交不完整流程，要求用户手动补全

环境配置

需设置两个环境变量：

通过 OpenClaw 配置文件设置（~/.config/openclaw/settings.json）：

{
  "skills": {
    "n8n-autopilot": {
      "env": {
        "N8N_API_KEY": "your-key",
        "N8N_BASE_URL": "https://your-n8n.example.com"
      }
    }
  }
}

验证连通性：

python3 scripts/n8n_deploy.py ping

工作流生成流程

针对每个工作流请求，请严格遵循以下步骤：

步骤 1 — 理解意图

在编写 JSON 前，明确以下四点：

• 触发方式：Webhook、定时调度（schedule）、手动触发，还是外部事件？
• 数据源：来自 Webhook 请求体、API、数据库，还是文件？
• 处理逻辑：是否需要转换、条件判断或数据增强？
• 输出动作：调用 API、发送通知、写入数据库，还是返回 Webhook 响应？

若需求清晰，可直接进入生成阶段；切勿过度追问。

步骤 2 — 规划节点链路

在脑中映射执行流程：

触发器 → [数据接入] → [数据转换] → [分支判断？] → [执行动作] → [响应/存储]

步骤 3 — 生成 JSON

使用 WorkflowForge 构建器（参见 scripts/workflow_forge.py），或直接编写原始 JSON。最终输出一个合法、单一的 JSON 对象，可直接用于 n8n 的 “Import from JSON” 功能。

步骤 4 — 自检校验

逐项核对下方校验清单，所有问题修复完毕后方可交付用户。您也可运行：

python3 scripts/workflow_inspector.py check --file workflow.json

步骤 5 — 部署（若已配置 API）

python3 scripts/n8n_deploy.py push --file workflow.json
python3 scripts/n8n_deploy.py push --file workflow.json --activate

步骤 6 — 解释说明

提供简明的逐节点说明表格，以及导入和凭证配置指引。

JSON 骨架结构

{
  "name": "描述性工作流名称",
  "nodes": [],
  "connections": {},
  "active": false,
  "settings": { "executionOrder": "v1" }
}

节点结构

{
  "id": "unique-uuid-v4",
  "name": "可读性强的节点名",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4,
  "position": [500, 300],
  "parameters": { ... },
  "credentials": { "httpHeaderAuth": { "id": "1", "name": "My Auth" } }
}

连接结构

{
  "connections": {
    "源节点名称": {
      "main": [
        [{ "node": "目标节点名称", "type": "main", "index": 0 }]
      ]
    }
  }
}

• 键（key）为节点的 名称（非 ID）
• main 是二维数组（外层数组对应输出索引，内层数组对应多个目标节点）
• IF 节点：索引 0 表示 true 分支，索引 1 表示 false 分支
• 终端节点（如 NoOp、Respond to Webhook）不得作为 connections 的键出现

节点目录（速查表）

触发器节点

逻辑与转换节点

HTTP 与响应节点

常用集成节点

AI / LLM 节点

完整凭证映射关系请参阅 references/node-catalog.md。

表达式速查表

校验清单

在输出任何工作流前，请确认以下各项均已满足：

结构完整性：

• nodes 数组存在且非空
• connections 覆盖所有非终端节点
• 每个节点均包含 id、name、type、typeVersion、position 和 parameters

数据一致性：

• 恰好存在一个触发器节点
• 所有节点名称唯一
• 所有节点 ID 均为符合标准的 UUID v4
• 无任何必填参数为空（如 url、path、jsCode）

图结构正确性：

• 所有连接目标节点名称均真实存在
• IF / Switch 节点已正确定义所有预期输出分支
• 不存在不可达（未连接）节点
• 执行图中不存在环路

凭证配置：

• 需要认证的节点均包含 credentials 字段
• 凭证类型名与对应节点兼容

表达式有效性：

• 所有 ={{ ... }} 表达式引用的字段，均由上游节点实际输出

CLI 参考手册

部署命令（n8n_deploy.py）

# 连通性检测
python3 scripts/n8n_deploy.py ping

# 列出工作流
python3 scripts/n8n_deploy.py ls [--active]

# 推送（创建）工作流
python3 scripts/n8n_deploy.py push --file workflow.json [--activate]

# 查看已部署工作流详情
python3 scripts/n8n_deploy.py inspect --id 

# 启用 / 停用工作流
python3 scripts/n8n_deploy.py on --id 
python3 scripts/n8n_deploy.py off --id 

# 触发手动执行
python3 scripts/n8n_deploy.py run --id  [--payload '{"key":"val"}']

# 查看最近执行记录
python3 scripts/n8n_deploy.py history --id  [--limit 10]

# 查看单次执行详情
python3 scripts/n8n_deploy.py exec-detail --id 

# 查看执行统计信息
python3 scripts/n8n_deploy.py stats --id  [--days 7]

# 删除工作流
python3 scripts/n8n_deploy.py rm --id 

校验与诊断命令（workflow_inspector.py）

# 校验本地文件
python3 scripts/workflow_inspector.py check --file workflow.json

# 校验已部署工作流
python3 scripts/workflow_inspector.py check --id 

# 全面诊断报告（结构 + 性能）
python3 scripts/workflow_inspector.py diagnose --id  [--days 14]

# 仅输出优化建议
python3 scripts/workflow_inspector.py optimize --id 

程序化构建器（workflow_forge.py）

# 根据 YAML 配方构建并部署
python3 scripts/workflow_forge.py build --recipe recipe.yaml --deploy

# 导出为 JSON 文件
python3 scripts/workflow_forge.py build --recipe recipe.yaml --output wf.json

优化启发式规则

在生成工作流时应主动应用以下优化策略：

1. 优先扇出而非串行：相互独立的 API 调用应并行分支执行，避免顺序等待。
2. 大数据集应批处理：优先使用 splitInBatches 节点，而非在 Code 节点中实现循环。
3. 显式错误路径：对外部 API 调用的工作流，应添加 Error Trigger 或基于 IF 的错误分支。
4. 设置超时阈值：对长时运行流程，在 settings 中配置 executionTimeout。
5. 避免重复拉取：数据仅拉取一次，后续通过 Set 或 Code 节点进行重塑。
6. 节点数超 15 时拆分：建议使用 Execute Workflow 节点将大流程拆分为子工作流。

输出格式规范

每个工作流响应必须包含以下内容：

1. 一句话概括该工作流的核心目的
2. 完整 JSON 内容（置于代码块中）
3. 节点说明表格：

4. 导入指引：“打开 n8n → Workflows → Import from JSON → 粘贴”
5. 用户导入后需自行配置的凭证列表
6. （若已配置 API）提供自动部署选项

常见流程模式

Webhook → 转换 → 响应

Webhook → Set（提取）→ Code（转换）→ Respond to Webhook

定时调度 → 获取 → 存储

Schedule → HTTP Request（获取）→ Code（处理）→ Google Sheets（追加）

Webhook → 分支 → 多动作

Webhook → IF →  true: Slack notify  → NoOp
              false: Email alert   → NoOp

带错误处理的轮询流程

Schedule → HTTP Request → IF（是否成功？）→  true: Process → Store
                                          false: Slack error alert

项目文件结构

n8n-autopilot/
├── SKILL.md                     # 本文档
├── README.md                    # 项目概述
├── scripts/
│   ├── n8n_deploy.py           # API 客户端 + 部署 CLI
│   ├── workflow_forge.py       # 程序化工作流构建器
│   └── workflow_inspector.py   # 校验 + 诊断工具
└── references/
    └── node-catalog.md         # 节点类型与凭证映射表

故障排查