n8n-builder

[H1][N8N-BUILDER]

箴言： 符合架构可确保 n8n 导入时不会出现运行时验证错误。

生成有效的 n8n 工作流 JSON。

任务：

1. 阅读 schema.md — 根结构、设置
2. 阅读 nodes.md — 节点定义、typeVersion
3. 阅读 connections.md — 图拓扑、AI 类型
4. （动态值）阅读 expressions.md — 变量、函数
5. （特定节点）阅读 integrations.md — 节点参数
6. 生成 JSON — 应用 workflow.template.md 中的模板
7. 验证 — 运行 uv run .claude/skills/n8n-builder/scripts/validate-workflow.py

REFERENCE: index.md — 文件列表。

---

[0][N8N_2.0]

箴言： 重大变更会使 2025 年之前的模式失效。

重大变更（2025 年 12 月）：

• Database — 必须使用 PostgreSQL；不再支持 MySQL/MariaDB。
• Python — 已移除 "language": "python"；请使用带任务运行器的 "pythonNative"。
• Security — ExecuteCommand 和 LocalFileTrigger 默认禁用。
• Code Isolation — 代码节点中的环境变量访问已被阻止（N8N_BLOCK_ENV_ACCESS_IN_NODE=true）。
• Agent Type — 已移除 Agent 类型选择（v1.82+）；所有 Agent 均为 Tools Agent。

---

[1][SCHEMA]

箴言： 根结构有助于 n8n 解析器识别并执行工作流。

指导：

• AI Workflows — 设置中必须包含 executionOrder: "v1"；否则异步节点排序会失败。
• Portability — 凭据 ID 和 errorWorkflow UUID 是实例专属的；导入后需要重新分配。
• Optional Fields — 与其省略，不如包含空对象（"pinData": {}）；这可避免导入边缘情况。
• Sub-Workflow Typing — 在触发器节点上使用 workflowInputs 架构，以便在执行前验证调用方的有效负载。
• pinData Limits — 保持在 12MB 以内；过大的有效负载会拖慢编辑器渲染，且不能包含二进制数据。

最佳实践：

• [ALWAYS] 生成时设置 "active": false；是否激活属于部署决策。
• [NEVER] 不要硬编码凭据 ID；请使用占位名称，以便跨实例传输。

---

[2][NODES]

箴言： 唯一标识可确保跨节点引用具有确定性。

指导：

• Name Collisions — n8n 会自动重命名重复项（Set→Set1）；这会导致 $('NodeName') 表达式静默失效。
• Version Matching — typeVersion 必须与目标 n8n 实例匹配；较新版本可能不向后兼容。
• Error Strategy — 对容错工作流使用 onError: "continueErrorOutput"；默认行为会停止执行。
• Node Documentation — 使用 notes 字段添加内联文档；notesInFlow: true 会在画布上显示这些内容。

最佳实践：

• [ALWAYS] 构建连接前为每个节点生成 UUID；连接通过 node.name 引用节点。
• [ALWAYS] 节点水平间隔 200px、垂直间隔 150px，以便在画布上清晰查看。

[3][连接]

准则： 连接类型可在解析时区分工作流模式。

指南：

• AI vs Main — AI 节点需要专用类型（ai_tool、ai_languageModel）；main 会导致工具静默不可见。
• 扇出 — 单个输出连接到多个节点时会并行执行；数组内的顺序不确定。
• 多输出 — 数组索引对应输出端口；IF 节点：索引 0 = true 分支，索引 1 = false 分支。
• 单一模型 — Agent 只接受一个 ai_languageModel 连接；连接多个模型会静默冲突。
• 记忆范围 — ai_memory 仅在单次触发执行期间持久化；不会跨会话持久化。

最佳实践：

• [ALWAYS] 同时匹配连接键和 type 属性；不匹配会导致静默失败。
• [NEVER] 不要通过 main 类型连接 AI 工具；Agent 无法发现这些工具。
• [NEVER] 不要向单个 Agent 连接多个大模型；使用 Model Selector 节点进行动态选择。

[参考：] →connections.md

---

[4][表达式]

准则： 动态求值可避免参数硬编码。

指南：

• 静态与动态 — 前缀 = 表示求值；没有此前缀时，值是包含 {{ }} 的字面字符串。
• 固定数据 — 测试模式下的固定数据缺少执行上下文；.item 会失败，应改用 .first() 或 .all()[0]。
• 复杂逻辑 — IIFE 模式 {{(function(){ return ... })()}} 支持多语句求值。
• 作用域混淆 — $json 仅访问当前节点输入；要访问其他节点，请使用 $('NodeName').item.json。

最佳实践：

• [ALWAYS] 使用 $('NodeName') 获取跨节点数据；$json 仅访问当前节点输入。
• [ALWAYS] 转义 JSON 字符串中的引号，或使用模板字面量，以避免 JSON 无效。
• [NEVER] 不要假设 .item 在所有上下文中都可用；测试固定数据时需要使用显式访问器。

[参考：] →expressions.md

---

[5][集成]

准则： 节点类型的选择决定集成能力。

指南：

• 触发器选择 — 外部调用使用 Webhook，定期执行使用 scheduleTrigger；应根据启动来源进行选择。
• AI 工具可见性 — 子工作流工具需要 description 参数；Agent 会据此进行工具选择推理。
• 代码语言 — Python 使用 "pythonNative"；"python" 已弃用。
• 错误传播 — 使用 stopAndError 节点来控制失败；它会触发指定的错误工作流。
• 2025 功能 — MCP 节点支持跨 Agent 互操作；Guardrails 节点可确保 AI 输出安全。
• 输出解析器 — outputParserStructured 的 jsonSchema 必须是静态的；schema 中的表达式会被静默忽略。
• 批处理 — 对大型数据集使用 splitInBatches 以防内存耗尽；分块处理。

最佳实践：

• [ALWAYS] 对于 webhook→response 模式，设置 responseMode: "lastNode"；确保输出传递给调用方。
• [ALWAYS] 为用作 AI 工具的 HTTP 节点添加 description；未记录的工具对 Agent 不可见。
• [ALWAYS] 为每个工作流设置唯一的 webhookId，以防不同工作流之间发生路径冲突。

[参考：] →integrations.md

---

[6][RAG]

箴言： RAG 流水线将大模型的响应建立在特定领域知识之上。

指导：

• Vector Store Selection — 开发时使用简单方案；生产环境持久化存储使用 PGVector/Pinecone/Qdrant。
• Embedding Consistency — 插入和查询必须使用相同的嵌入模型；模型不匹配会导致语义偏移。
• Chunk Strategy — 推荐使用 Recursive Character splitter；先拆分 Markdown/HTML/代码，再按字符拆分。
• Memory vs Chains — 只有 Agent 支持记忆；链是无状态的单轮处理器。
• Retriever Modes — 复杂问题使用 MultiQuery；减少噪声使用 Contextual Compression。

最佳实践：

• [ALWAYS] 文档插入和查询操作使用相同的嵌入模型。
• [ALWAYS] 记忆节点使用 ai_memory 连接类型；使用 main 会静默失败。
• [NEVER] 在生产环境中使用 Simple Vector Store；重启后数据会丢失，且所有用户都可访问。

---

[7][VALIDATION]

箴言： 导出前进行验证，可避免 n8n 导入失败。

脚本：

uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json
uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json --strict

检查项（12 项自动检查）：

• root_required — 必须包含 name、nodes、connections
• node_id_unique / node_name_unique — 不得重复
• node_id_uuid — UUID 格式有效
• conn_targets_exist — 连接目标必须引用现有节点
• conn_ai_type_match — AI 连接键必须与 type 属性匹配
• settings_exec_order_ai — LangChain 工作流要求 executionOrder: "v1"
• settings_caller_policy / node_on_error — 枚举值验证

指导：

• API Deployment — 使用先 POST 后 PUT 的模式；由于 API 缺陷，单次 POST 可能会忽略设置。
• Performance — saveExecutionProgress: true 会为每个节点触发一次数据库 I/O；高吞吐量（>1000 RPM）时应禁用。
• Source Control — 分享时移除 instanceId；凭据文件仅包含存根，不含密钥。