n8n-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

[H1][N8N-BUILDER]

Dictum: Schema compliance enables n8n import without runtime validation errors.

Generate valid n8n workflow JSON.

Tasks:

Read schema.md — Root structure, settings
Read nodes.md — Node definition, typeVersion
Read connections.md — Graph topology, AI types
(dynamic values) Read expressions.md — Variables, functions
(specific nodes) Read integrations.md — Node parameters
Generate JSON — Apply template from workflow.template.md

Validate — Run

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

[REFERENCE]: index.md — File listing.

准则: 遵循架构规范可确保n8n导入时无运行时验证错误。

生成有效的n8n工作流JSON。

任务:

阅读 schema.md — 根结构、设置项
阅读 nodes.md — 节点定义、typeVersion
阅读 connections.md — 图拓扑、AI类型
（动态值）阅读 expressions.md — 变量、函数
（特定节点）阅读 integrations.md — 节点参数
生成JSON — 应用 workflow.template.md 中的模板

验证 — 运行

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

[参考文献]: index.md — 文件列表。

[0][N8N_2.0]

Dictum: Breaking changes invalidate pre-2025 patterns.

Breaking Changes (December 2025):

```
Database
```
— PostgreSQL required; MySQL/MariaDB support dropped.

Python

—

"language": "python"

removed; use

"pythonNative"

with task runners.

```
Security
```
—
```
ExecuteCommand
```
and
```
LocalFileTrigger
```
disabled by default.
```
Code Isolation
```
— Environment variable access blocked in Code nodes (
```
N8N_BLOCK_ENV_ACCESS_IN_NODE=true
```
).
```
Agent Type
```
— Agent type selection removed (v1.82+); all agents are Tools Agent.

准则: 重大变更会导致2025年前的模式失效。

重大变更（2025年12月）:

```
Database
```
— 要求使用PostgreSQL；已移除对MySQL/MariaDB的支持。
```
Python
```
— 已移除
```
"language": "python"
```
；需搭配任务运行器使用
```
"pythonNative"
```
。
```
Security
```
—
```
ExecuteCommand
```
和
```
LocalFileTrigger
```
默认禁用。
```
Code Isolation
```
— Code节点中禁止访问环境变量（
```
N8N_BLOCK_ENV_ACCESS_IN_NODE=true
```
）。
```
Agent Type
```
— 已移除Agent类型选择（v1.82+）；所有Agent均为Tools Agent。

[1][SCHEMA]

Dictum: Root structure enables n8n parser recognition and execution.

Guidance:

```
AI Workflows
```
— Require
```
executionOrder: "v1"
```
in settings; async node ordering fails without.
```
Portability
```
— Credential IDs and errorWorkflow UUIDs are instance-specific; expect reassignment post-import.
```
Optional Fields
```
— Include empty objects (
```
"pinData": {}
```
) over omission; prevents import edge cases.
```
Sub-Workflow Typing
```
— Use
```
workflowInputs
```
schema on trigger nodes to validate caller payloads before execution.
```
pinData Limits
```
— Keep under 12MB; large payloads slow editor rendering and cannot contain binary data.

Best-Practices:

[ALWAYS] Set
```
"active": false
```
on generation; activation is a deployment decision.
[NEVER] Hardcode credential IDs; use placeholder names for cross-instance transfer.

准则: 根结构确保n8n解析器可识别并执行工作流。

指导说明:

```
AI工作流
```
— 需在设置中指定
```
executionOrder: "v1"
```
；否则异步节点排序会失败。
```
可移植性
```
— 凭据ID和错误工作流UUID为实例专属；导入后需重新分配。
```
可选字段
```
— 应包含空对象（如
```
"pinData": {}
```
）而非省略；避免导入时出现边缘情况。
```
子工作流类型
```
— 在触发节点上使用
```
workflowInputs
```
架构，可在执行前验证调用方负载。
```
pinData限制
```
— 大小需保持在12MB以下；大负载会拖慢编辑器渲染速度，且不能包含二进制数据。

最佳实践:

[始终] 生成时设置
```
"active": false
```
；激活属于部署决策。
[切勿] 硬编码凭据ID；使用占位符名称以实现跨实例迁移。

[2][NODES]

Dictum: Unique identity enables deterministic cross-node references.

Guidance:

```
Name Collisions
```
— n8n auto-renames duplicates (Set→Set1); breaks
```
$('NodeName')
```
expressions silently.
```
Version Matching
```
— typeVersion must match target n8n instance; newer versions may lack backward compatibility.
```
Error Strategy
```
— Use
```
onError: "continueErrorOutput"
```
for fault-tolerant pipelines; default stops execution.
```
Node Documentation
```
— Use
```
notes
```
field for inline documentation;
```
notesInFlow: true
```
displays on canvas.

Best-Practices:

[ALWAYS] Generate UUID per node before building connections; connections reference node.name.
[ALWAYS] Space nodes 200px horizontal, 150px vertical for canvas readability.

准则: 唯一标识确保节点间引用的确定性。

指导说明:

```
名称冲突
```
— n8n会自动重命名重复节点（如Set→Set1）；这会导致
```
$('NodeName')
```
表达式静默失效。
```
版本匹配
```
— typeVersion必须与目标n8n实例匹配；新版本可能不兼容旧版本。
```
错误策略
```
— 对于容错管道，使用
```
onError: "continueErrorOutput"
```
；默认设置会终止执行。
```
节点文档
```
— 使用
```
notes
```
字段添加内联文档；设置
```
notesInFlow: true
```
可在画布上显示。

最佳实践:

[始终] 在构建连接前为每个节点生成UUID；连接会引用node.name。
[始终] 将节点水平间隔200px、垂直间隔150px，以提升画布可读性。

[3][CONNECTIONS]

Dictum: Connection types enable workflow mode distinction at parse time.

Guidance:

```
AI vs Main
```
— AI nodes require specialized types (
```
ai_tool
```
,
```
ai_languageModel
```
);
```
main
```
causes silent tool invisibility.
```
Fan-out
```
— Single output to multiple nodes executes in parallel; order within array is non-deterministic.
```
Multi-output
```
— Array index maps to output port; IF node: index 0 = true branch, index 1 = false branch.
```
Single Model
```
— Agent accepts exactly one
```
ai_languageModel
```
connection; multiple models conflict silently.
```
Memory Scope
```
—
```
ai_memory
```
persists within single trigger execution only; no cross-session persistence.

Best-Practices:

[ALWAYS] Match connection key AND
```
type
```
property; mismatches cause silent failures.
[NEVER] Connect AI tools via
```
main
```
type; agent cannot discover them.
[NEVER] Connect multiple language models to single agent; use Model Selector node for dynamic selection.

准则: 连接类型可在解析阶段区分工作流模式。

指导说明:

```
AI与主流程
```
— AI节点需使用专用类型（
```
ai_tool
```
、
```
ai_languageModel
```
）；使用
```
main
```
类型会导致工具静默不可见。
```
扇出
```
— 单个输出连接到多个节点时会并行执行；数组内的顺序是非确定性的。
```
多输出
```
— 数组索引对应输出端口；IF节点：索引0 = 真分支，索引1 = 假分支。
```
单一模型
```
— Agent仅接受一个
```
ai_languageModel
```
连接；多个模型会静默冲突。
```
内存范围
```
—
```
ai_memory
```
仅在单次触发执行内持久化；无跨会话持久化。

最佳实践:

[始终] 匹配连接键和
```
type
```
属性；不匹配会导致静默失败。
[切勿] 通过
```
main
```
类型连接AI工具；Agent无法发现这些工具。
[切勿] 为单个Agent连接多个语言模型；使用Model Selector节点进行动态选择。

[4][EXPRESSIONS]

Dictum: Dynamic evaluation eliminates hardcoded parameters.

Guidance:

```
Static vs Dynamic
```
— Prefix
```
=
```
signals evaluation; without it, value is literal string including
```
{{ }}
```
.
```
Pinned Data
```
— Test mode pins lack execution context;
```
.item
```
fails, use
```
.first()
```
or
```
.all()[0]
```
instead.
```
Complex Logic
```
— IIFE pattern
```
{{(function(){ return ... })()}}
```
enables multi-statement evaluation.
```
Scope Confusion
```
—
```
$json
```
accesses current node input only; use
```
$('NodeName').item.json
```
for other nodes.

Best-Practices:

[ALWAYS] Use
```
$('NodeName')
```
for cross-node data;
```
$json
```
only accesses current node input.
[ALWAYS] Escape quotes in JSON strings or use template literals to prevent invalid JSON.
[NEVER] Assume
```
.item
```
works in all contexts; pinned data testing requires explicit accessors.

准则: 动态评估可消除硬编码参数。

指导说明:

```
静态与动态
```
— 前缀
```
=
```
表示需要评估；无此前缀时，值为包含
```
{{ }}
```
的字面字符串。
```
固定数据
```
— 测试模式下的固定数据缺乏执行上下文；
```
.item
```
会失效，需改用
```
.first()
```
或
```
.all()[0]
```
。

复杂逻辑

— IIFE模式

{{(function(){ return ... })()}}

支持多语句评估。

```
作用域混淆
```
—
```
$json
```
仅访问当前节点的输入；访问其他节点需使用
```
$('NodeName').item.json
```
。

最佳实践:

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

[5][INTEGRATIONS]

Dictum: Node type selection determines integration capability.

Guidance:

```
Trigger Selection
```
— Webhook for external calls, scheduleTrigger for periodic; choose based on initiation source.
```
AI Tool Visibility
```
— Sub-workflow tools require
```
description
```
parameter; agent uses it for tool selection reasoning.
```
Code Language
```
— Use
```
"pythonNative"
```
for Python;
```
"python"
```
is deprecated.
```
Error Propagation
```
— Use
```
stopAndError
```
node for controlled failures; triggers designated error workflow.
```
2025 Features
```
— MCP nodes enable cross-agent interoperability; Guardrails nodes enforce AI output safety.
```
Output Parser
```
—
```
outputParserStructured
```
jsonSchema must be static; expressions in schema are ignored silently.
```
Batch Processing
```
— Use
```
splitInBatches
```
for large datasets to prevent memory exhaustion; process in chunks.

Best-Practices:

[ALWAYS] Set
```
responseMode: "lastNode"
```
for webhook→response patterns; ensures output reaches caller.
[ALWAYS] Include
```
description
```
on HTTP nodes used as AI tools; undocumented tools are invisible to agent.
[ALWAYS] Include unique
```
webhookId
```
per workflow to prevent path collisions across workflows.

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

指导说明:

```
触发选择
```
— 外部调用使用Webhook，周期性任务使用scheduleTrigger；根据触发源选择。
```
AI工具可见性
```
— 子工作流工具需包含
```
description
```
参数；Agent会使用该参数进行工具选择推理。
```
代码语言
```
— Python需使用
```
"pythonNative"
```
；
```
"python"
```
已弃用。
```
错误传播
```
— 使用
```
stopAndError
```
节点实现可控失败；触发指定的错误工作流。
```
2025新特性
```
— MCP节点支持跨Agent互操作性；Guardrails节点可强制AI输出安全。
```
输出解析器
```
—
```
outputParserStructured
```
的jsonSchema必须是静态的；架构中的表达式会被静默忽略。
```
批量处理
```
— 处理大型数据集时使用
```
splitInBatches
```
以避免内存耗尽；分块处理数据。

最佳实践:

[始终] 对于webhook→响应模式，设置
```
responseMode: "lastNode"
```
；确保输出能返回给调用方。
[始终] 作为AI工具使用的HTTP节点需包含
```
description
```
；未文档化的工具对Agent不可见。
[始终] 为每个工作流设置唯一的
```
webhookId
```
，以避免跨工作流的路径冲突。

[6][RAG]

Dictum: RAG pipelines ground LLM responses in domain-specific knowledge.

Guidance:

```
Vector Store Selection
```
— Simple for development; PGVector/Pinecone/Qdrant for production persistence.
```
Embedding Consistency
```
— Same embedding model required for insert and query; mismatch causes semantic drift.
```
Chunk Strategy
```
— Recursive Character splitter recommended; splits Markdown/HTML/code before character fallback.
```
Memory vs Chains
```
— Only agents support memory; chains are stateless single-turn processors.
```
Retriever Modes
```
— MultiQuery for complex questions; Contextual Compression for noise reduction.

Best-Practices:

[ALWAYS] Match embedding model between document insert and query operations.
[ALWAYS] Use
```
ai_memory
```
connection type for memory nodes;
```
main
```
silently fails.
[NEVER] Use Simple Vector Store in production; data lost on restart, global user access.

准则: RAG管道让大语言模型的响应基于领域专属知识。

指导说明:

```
向量存储选择
```
— 开发阶段使用Simple；生产环境持久化使用PGVector/Pinecone/Qdrant。
```
嵌入一致性
```
— 插入和查询需使用相同的嵌入模型；不匹配会导致语义漂移。
```
分块策略
```
— 推荐使用Recursive Character拆分器；先拆分Markdown/HTML/代码，再回退到字符拆分。
```
内存与链
```
— 仅Agent支持内存；链是无状态的单轮处理器。
```
检索器模式
```
— 复杂问题使用MultiQuery；降噪使用Contextual Compression。

最佳实践:

[始终] 文档插入和查询操作使用相同的嵌入模型。
[始终] 为内存节点使用
```
ai_memory
```
连接类型；
```
main
```
类型会静默失败。
[切勿] 在生产环境使用Simple Vector Store；重启后数据丢失，且所有用户均可访问。

[7][VALIDATION]

Dictum: Pre-export validation prevents n8n import failures.

Script:

bash

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

Checks (12 automated):

```
root_required
```
— name, nodes, connections present
```
node_id_unique
```
/
```
node_name_unique
```
— no duplicates
```
node_id_uuid
```
— valid UUID format
```
conn_targets_exist
```
— connection targets reference existing nodes
```
conn_ai_type_match
```
— AI connection key matches type property

settings_exec_order_ai

— LangChain workflows require

executionOrder: "v1"

```
settings_caller_policy
```
/
```
node_on_error
```
— enum value validation

Guidance:

```
API Deployment
```
— Use POST then PUT pattern; single POST may ignore settings due to API bug.
```
Performance
```
—
```
saveExecutionProgress: true
```
triggers DB I/O per node; disable for high-throughput (>1000 RPM).
```
Source Control
```
— Strip
```
instanceId
```
when sharing; credential files contain stubs only, not secrets.

准则: 导出前验证可避免n8n导入失败。

脚本:

bash

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部署
```
— 使用POST后接PUT的模式；单次POST可能因API bug导致设置被忽略。
```
性能
```
—
```
saveExecutionProgress: true
```
会在每个节点触发数据库I/O；高吞吐量场景（>1000 RPM）需禁用。
```
版本控制
```
— 分享时需移除
```
instanceId
```
；凭据文件仅包含存根，不包含密钥。