📦 n8n Pilot

n8n Pilot ⚙️ 设计、构建、部署、测试并加固高级 n8n 工作流。不是 API 包装器——而是从意图到生产的流程架构师。 何时使用 任务涉及 n8n 时：设计工作流、构建自动化、部署实例、诊断故障、优化性能或加固 webhook/凭据。

配套技能 clawhub install n8n —— CRUD 操作 API 客户端（列出/创建/激活工作流） clawhub install docker-pilot —— 容器生命周期管理，用于部署 n8n

安全架构 ⚠️ 部署任何工作流前，扫描以下危险模式：

模式 | 风险 | 检测 ---|---|--- 无最大循环的 Loop | 🔴 无限执行 | Split In Batches 未设 batchSize，或 Code 节点含 while(true) 无过滤的 Delete | 🔴 数据毁灭 | 数据库 delete/HTTP DELETE 无 WHERE/过滤条件 无鉴权 Webhook | 🟡 任意触发 | Webhook 节点 authentication=none 访问私有 IP 的 HTTP | 🟡 SSRF 风险 | 请求 10.x、172.16-31.x、192.168.x、localhost 无上限邮件/发送 | 🟡 批量垃圾 | 循环 + 邮件/发送节点无上限 无错误处理 | 🟡 静默失败 | 工作流无 Error Trigger 或错误分支 硬编码密钥 | 🔴 凭据泄露 | Code 节点明文含 API 密钥、密码、令牌

规则：含 🔴 模式必须修复后方可部署；🟡 模式需用户确认。

确认闸门 新工作流部署：展示逻辑图 → 确认 → 部署为停用 → 测试 → 激活 工作流修改：展示 diff（变更内容）→ 确认 → 部署 破坏性操作（删除工作流、清理执行）：完整审计 + 显式确认

紧急停止 工作流失控时： # 立即停用所有工作流 python3 scripts/n8n_api.py list-workflows --active true | \ python3 -c "import sys,json; [print(w['id']) for w in json.load(sys.stdin)['data']]" | \ xargs -I{} python3 scripts/n8n_api.py deactivate --id {}

工作流设计：意图 → 逻辑图 → JSON 步骤 1：明确意图 用自然语言描述：“老板发重要邮件时，我希望能收到 Telegram 通知。”

步骤 2：绘制逻辑图 向用户展示并确认： 📧 邮件触发（新邮件）→ 🧠 IF 节点（发件人含 "boss@company.com"）→ ✅ 是：摘要内容 → 📱 Telegram 通知（摘要）→ ❌ 否：跳过

步骤 3：生成工作流 JSON 将逻辑图转为 n8n 工作流 JSON： { "name": "Boss Email → Telegram Alert", "nodes": [...], "connections": {...}, "settings": { "executionOrder": "v1", "timezone": "Europe/Berlin" } }

关键 JSON 字段 typeVersion —— 必须与实例安装的节点版本一致 position —— [x, y] 坐标，API 必需 credentials —— 嵌入格式 {credential_type: {id, name}}，非仅 ID parameters —— 节点专属配置，表达式加 = 前缀 settings.executionOrder —— 必须为 "v1" pinData —— 逐节点注入模拟数据用于测试

流程逻辑模式 分支（IF / Switch） 触发 → IF（条件）→ 真分支：[处理 A] → 假分支：[处理 B 或 停止] IF 节点配置： { "type": "n8n-nodes-base.if", "parameters": { "conditions": { "boolean": [{ "value1": "={{ $json.sender }}", "operation": "contains", "value2": "boss@company.com" }] } } } Switch 节点（多路分支）： { "type": "n8n-nodes-base.switch", "parameters": { "rules": [ { "output": 0, "conditions": {...} }, { "output": 1, "conditions": {...} } ] } }

合并（Merge 节点） 分支 A → Merge → 继续 分支 B ↗ 模式：append —— 合并所有项；mergeByPosition —— 按索引对齐；mergeByKey —— 按共享字段连接（类似 SQL JOIN）

循环（Split In Batches / Loop Over Items） 大数据集 → Split In Batches（size=100）→ 处理批次 → 循环返回 → 完成继续 ⚠️ 必须设置 batchSize，防止大数据耗尽内存。

子工作流（Execute Workflow 节点） 主工作流 → Execute Workflow（子工作流 ID）→ 在主线中使用子结果 用途：复用逻辑（如“发送通知”子工作流被 5 条主线调用），拆分复杂流程。 注意：子工作流需含可接受父调用的触发（Workflow Trigger 节点）。

错误处理（Error Trigger + 错误分支） 模式 1：Error Trigger 节点 [独立工作流] Error Trigger → 通知（Telegram/邮件）含错误详情 模式 2：节点级错误分支 HTTP Request → [出错] → 记录错误 + 备用动作 → [成功] → 正常继续

指数退避重试 n8n 无内置退避重试，用 Code 节点实现： // Code 节点内包装 API 调用 const maxRetries = 3; const baseDelay = 1000; //