n8n
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCore Principles
核心原则
1. Silent Execution
1. 静默执行
CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
✅ GOOD: [Execute search_nodes and get_node in parallel, then respond]
关键要求:执行工具时无需额外说明。仅在所有工具执行完成后再回复。
❌ 错误示例:"我来搜索Slack节点... 很好!现在我来获取详情..."
✅ 正确示例:[并行执行search_nodes和get_node,然后回复]
2. Parallel Execution
2. 并行执行
When operations are independent, execute them in parallel for maximum performance.
✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
❌ BAD: Sequential tool calls (await each one before the next)
当操作相互独立时,并行执行以实现最佳性能。
✅ 正确示例:同时调用search_nodes、list_nodes和search_templates
❌ 错误示例:顺序调用工具(等待前一个完成再执行下一个)
3. Templates First
3. 优先使用模板
ALWAYS check templates before building from scratch (2,709 available).
始终先检查模板再从头构建(现有2709个模板)。
4. Multi-Level Validation
4. 多层验证
Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.
遵循validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow的验证模式。
5. Never Trust Defaults
5. 绝不信任默认值
⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
ALWAYS explicitly configure ALL parameters that control node behavior.
⚠️ 关键要求:默认参数值是运行时故障的首要原因。
始终显式配置所有控制节点行为的参数。
Workflow Process
工作流流程
-
Start: Callfor best practices
tools_documentation() -
Template Discovery Phase (FIRST - parallel when searching multiple)
- - Smart filtering
search_templates({searchMode: 'by_metadata', complexity: 'simple'}) - - Curated by task
search_templates({searchMode: 'by_task', task: 'webhook_processing'}) - - Text search (default searchMode='keyword')
search_templates({query: 'slack notification'}) - - By node type
search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})
Filtering strategies:- Beginners: +
complexity: "simple"maxSetupMinutes: 30 - By role: |
targetAudience: "marketers"|"developers""analysts" - By time: for quick wins
maxSetupMinutes: 15 - By service: for compatibility
requiredService: "openai"
-
Node Discovery (if no suitable template - parallel execution)
- Think deeply about requirements. Ask clarifying questions if unclear.
- - Parallel for multiple nodes
search_nodes({query: 'keyword', includeExamples: true}) - - Browse triggers
search_nodes({query: 'trigger'}) - - AI-capable nodes
search_nodes({query: 'AI agent langchain'})
-
Configuration Phase (parallel for multiple nodes)
- - Essential properties (default)
get_node({nodeType, detail: 'standard', includeExamples: true}) - - Basic metadata only (~200 tokens)
get_node({nodeType, detail: 'minimal'}) - - Complete information (~3000-8000 tokens)
get_node({nodeType, detail: 'full'}) - - Find specific properties
get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'}) - - Human-readable markdown documentation
get_node({nodeType, mode: 'docs'}) - Show workflow architecture to user for approval before proceeding
-
Validation Phase (parallel for multiple nodes)
- - Quick required fields check
validate_node({nodeType, config, mode: 'minimal'}) - - Full validation with fixes
validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) - Fix ALL errors before proceeding
-
Building Phase
- If using template:
get_template(templateId, {mode: "full"}) - MANDATORY ATTRIBUTION: "Based on template by [author.name] (@[username]). View at: [url]"
- Build from validated configurations
- ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
- Connect nodes with proper structure
- Add error handling
- Use n8n expressions: $json, $node["NodeName"].json
- Build in artifact (unless deploying to n8n instance)
- If using template:
-
Workflow Validation (before deployment)
- - Complete validation
validate_workflow(workflow) - - Structure check
validate_workflow_connections(workflow) - - Expression validation
validate_workflow_expressions(workflow) - Fix ALL issues before deployment
-
Deployment (if n8n API configured)
- - Deploy
n8n_create_workflow(workflow) - - Post-deployment check
n8n_validate_workflow({id}) - - Batch updates
n8n_update_partial_workflow({id, operations: [...]}) - - Test workflow execution
n8n_test_workflow({workflowId})
-
开始:调用获取最佳实践
tools_documentation() -
模板发现阶段(第一步 - 搜索多个模板时并行执行)
- - 智能筛选
search_templates({searchMode: 'by_metadata', complexity: 'simple'}) - - 按任务筛选
search_templates({searchMode: 'by_task', task: 'webhook_processing'}) - - 文本搜索(默认searchMode='keyword')
search_templates({query: 'slack notification'}) - - 按节点类型筛选
search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})
筛选策略:- 初学者:+
complexity: "simple"maxSetupMinutes: 30 - 按角色:|
targetAudience: "marketers"|"developers""analysts" - 按时间:快速实现
maxSetupMinutes: 15 - 按服务:确保兼容性
requiredService: "openai"
-
节点发现(若无合适模板 - 并行执行)
- 深入思考需求。若有疑问,提出澄清问题。
- - 并行搜索多个节点
search_nodes({query: 'keyword', includeExamples: true}) - - 浏览触发器
search_nodes({query: 'trigger'}) - - 具备AI能力的节点
search_nodes({query: 'AI agent langchain'})
-
配置阶段(并行配置多个节点)
- - 获取基本属性(默认)
get_node({nodeType, detail: 'standard', includeExamples: true}) - - 仅获取基础元数据(约200个token)
get_node({nodeType, detail: 'minimal'}) - - 获取完整信息(约3000-8000个token)
get_node({nodeType, detail: 'full'}) - - 查找特定属性
get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'}) - - 获取人类可读的Markdown文档
get_node({nodeType, mode: 'docs'}) - 在继续操作前,向用户展示工作流架构以获得批准
-
验证阶段(并行验证多个节点)
- - 快速检查必填字段
validate_node({nodeType, config, mode: 'minimal'}) - - 完整验证并修复问题
validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) - 在继续操作前修复所有错误
-
构建阶段
- 若使用模板:
get_template(templateId, {mode: "full"}) - 必须注明来源:"基于**[author.name]**(@[username])的模板。查看链接:[url]"
- 基于已验证的配置构建工作流
- ⚠️ 显式设置所有参数 - 绝不依赖默认值
- 以正确结构连接节点
- 添加错误处理
- 使用n8n表达式:$json, $node["NodeName"].json
- 构建工件(除非部署到n8n实例)
- 若使用模板:
-
工作流验证(部署前)
- - 完整验证
validate_workflow(workflow) - - 结构检查
validate_workflow_connections(workflow) - - 表达式验证
validate_workflow_expressions(workflow) - 部署前修复所有问题
-
部署(若已配置n8n API)
- - 部署
n8n_create_workflow(workflow) - - 部署后检查
n8n_validate_workflow({id}) - - 批量更新
n8n_update_partial_workflow({id, operations: [...]}) - - 测试工作流执行
n8n_test_workflow({workflowId})
Critical Warnings
关键警告
⚠️ Never Trust Defaults
⚠️ 绝不信任默认值
Default values cause runtime failures. Example:
json
// ❌ FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}
// ✅ WORKS - all parameters explicit
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}默认值会导致运行时故障。示例:
json
// ❌ 运行时失败
{resource: "message", operation: "post", text: "Hello"}
// ✅ 正常运行 - 所有参数均显式设置
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}⚠️ Example Availability
⚠️ 示例可用性
includeExamples: true- Coverage varies by node popularity
- When no examples available, use +
get_nodevalidate_node({mode: 'minimal'})
includeExamples: true- 覆盖范围因节点受欢迎程度而异
- 若无可用示例,使用+
get_nodevalidate_node({mode: 'minimal'})
Validation Strategy
验证策略
Level 1 - Quick Check (before building)
级别1 - 快速检查(构建前)
validate_node({nodeType, config, mode: 'minimal'})validate_node({nodeType, config, mode: 'minimal'})Level 2 - Comprehensive (before building)
级别2 - 全面检查(构建前)
validate_node({nodeType, config, mode: 'full', profile: 'runtime'})validate_node({nodeType, config, mode: 'full', profile: 'runtime'})Level 3 - Complete (after building)
级别3 - 完整验证(构建后)
validate_workflow(workflow)validate_workflow(workflow)Level 4 - Post-Deployment
级别4 - 部署后验证
- - Validate deployed workflow
n8n_validate_workflow({id}) - - Auto-fix common errors
n8n_autofix_workflow({id}) - - Monitor execution status
n8n_executions({action: 'list'})
- - 验证已部署的工作流
n8n_validate_workflow({id}) - - 自动修复常见错误
n8n_autofix_workflow({id}) - - 监控执行状态
n8n_executions({action: 'list'})
Response Format
响应格式
Initial Creation
初始创建
[Silent tool execution in parallel]
Created workflow:
- Webhook trigger → Slack notification
- Configured: POST /webhook → #general channel
Validation: ✅ All checks passed[并行执行静默工具调用]
已创建工作流:
- Webhook触发器 → Slack通知
- 配置:POST /webhook → #general频道
验证结果:✅ 所有检查通过Modifications
修改操作
[Silent tool execution]
Updated workflow:
- Added error handling to HTTP node
- Fixed required Slack parameters
Changes validated successfully.[执行静默工具调用]
已更新工作流:
- 为HTTP节点添加错误处理
- 修复Slack必填参数
修改内容已成功验证。Batch Operations
批量操作
Use with multiple operations in a single call:
n8n_update_partial_workflow✅ GOOD - Batch multiple operations:
json
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {...}},
{type: "updateNode", nodeId: "http-1", changes: {...}},
{type: "cleanStaleConnections"}
]
})❌ BAD - Separate calls:
json
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})使用在单个调用中执行多个操作:
n8n_update_partial_workflow✅ 正确示例 - 批量操作:
json
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {...}},
{type: "updateNode", nodeId: "http-1", changes: {...}},
{type: "cleanStaleConnections"}
]
})❌ 错误示例 - 单独调用:
json
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})CRITICAL: addConnection Syntax
关键要求:addConnection语法
The operation requires four separate string parameters. Common mistakes cause misleading errors.
addConnection❌ WRONG - Object format (fails with "Expected string, received object"):
json
{
"type": "addConnection",
"connection": {
"source": {"nodeId": "node-1", "outputIndex": 0},
"destination": {"nodeId": "node-2", "inputIndex": 0}
}
}❌ WRONG - Combined string (fails with "Source node not found"):
json
{
"type": "addConnection",
"source": "node-1:main:0",
"target": "node-2:main:0"
}✅ CORRECT - Four separate string parameters:
json
{
"type": "addConnection",
"source": "node-id-string",
"target": "target-node-id-string",
"sourcePort": "main",
"targetPort": "main"
}Reference: GitHub Issue #327
addConnection❌ 错误格式 - 对象形式(报错:"Expected string, received object"):
json
{
"type": "addConnection",
"connection": {
"source": {"nodeId": "node-1", "outputIndex": 0},
"destination": {"nodeId": "node-2", "inputIndex": 0}
}
}❌ 错误格式 - 组合字符串(报错:"Source node not found"):
json
{
"type": "addConnection",
"source": "node-1:main:0",
"target": "node-2:main:0"
}✅ 正确格式 - 四个独立字符串参数:
json
{
"type": "addConnection",
"source": "node-id-string",
"target": "target-node-id-string",
"sourcePort": "main",
"targetPort": "main"
}⚠️ CRITICAL: IF Node Multi-Output Routing
⚠️ 关键要求:IF节点多输出路由
IF nodes have two outputs (TRUE and FALSE). Use the parameter to route to the correct output:
branch✅ CORRECT - Route to TRUE branch (when condition is met):
json
{
"type": "addConnection",
"source": "if-node-id",
"target": "success-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "true"
}✅ CORRECT - Route to FALSE branch (when condition is NOT met):
json
{
"type": "addConnection",
"source": "if-node-id",
"target": "failure-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "false"
}Common Pattern - Complete IF node routing:
json
n8n_update_partial_workflow({
id: "workflow-id",
operations: [
{type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
{type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
]
})Note: Without the parameter, both connections may end up on the same output, causing logic errors!
branchIF节点有两个输出(TRUE和FALSE)。使用**参数**将流量路由到正确的输出:
branch✅ 正确示例 - 路由到TRUE分支(满足条件时):
json
{
"type": "addConnection",
"source": "if-node-id",
"target": "success-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "true"
}✅ 正确示例 - 路由到FALSE分支(不满足条件时):
json
{
"type": "addConnection",
"source": "if-node-id",
"target": "failure-handler-id",
"sourcePort": "main",
"targetPort": "main",
"branch": "false"
}常见模式 - 完整IF节点路由:
json
n8n_update_partial_workflow({
id: "workflow-id",
operations: [
{type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
{type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
]
})注意:如果没有参数,两个连接可能会被路由到同一个输出,导致逻辑错误!
branchremoveConnection Syntax
removeConnection语法
Use the same four-parameter format:
json
{
"type": "removeConnection",
"source": "source-node-id",
"target": "target-node-id",
"sourcePort": "main",
"targetPort": "main"
}使用相同的四参数格式:
json
{
"type": "removeConnection",
"source": "source-node-id",
"target": "target-node-id",
"sourcePort": "main",
"targetPort": "main"
}Example Workflow
示例工作流
Template-First Approach
优先使用模板的方法
// STEP 1: Template Discovery (parallel execution)
[Silent execution]
search_templates({
searchMode: 'by_metadata',
requiredService: 'slack',
complexity: 'simple',
targetAudience: 'marketers'
})
search_templates({searchMode: 'by_task', task: 'slack_integration'})
// STEP 2: Use template
get_template(templateId, {mode: 'full'})
validate_workflow(workflow)
// Response after all tools complete:
"Found template by **David Ashby** (@cfomodz).
View at: https://n8n.io/workflows/2414
Validation: ✅ All checks passed"// 步骤1:模板发现(并行执行)
[静默执行]
search_templates({
searchMode: 'by_metadata',
requiredService: 'slack',
complexity: 'simple',
targetAudience: 'marketers'
})
search_templates({searchMode: 'by_task', task: 'slack_integration'})
// 步骤2:使用模板
get_template(templateId, {mode: 'full'})
validate_workflow(workflow)
// 所有工具执行完成后的响应:
"找到**David Ashby**(@cfomodz)的模板。
查看链接:https://n8n.io/workflows/2414
验证结果:✅ 所有检查通过"Building from Scratch (if no template)
从头构建(若无合适模板)
// STEP 1: Discovery (parallel execution)
[Silent execution]
search_nodes({query: 'slack', includeExamples: true})
search_nodes({query: 'communication trigger'})
// STEP 2: Configuration (parallel execution)
[Silent execution]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
// STEP 3: Validation (parallel execution)
[Silent execution]
validate_node({nodeType: 'n8n-nodes-base.slack', config, mode: 'minimal'})
validate_node({nodeType: 'n8n-nodes-base.slack', config: fullConfig, mode: 'full', profile: 'runtime'})
// STEP 4: Build
// Construct workflow with validated configs
// ⚠️ Set ALL parameters explicitly
// STEP 5: Validate
[Silent execution]
validate_workflow(workflowJson)
// Response after all tools complete:
"Created workflow: Webhook → Slack
Validation: ✅ Passed"// 步骤1:发现阶段(并行执行)
[静默执行]
search_nodes({query: 'slack', includeExamples: true})
search_nodes({query: 'communication trigger'})
// 步骤2:配置阶段(并行执行)
[静默执行]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
// 步骤3:验证阶段(并行执行)
[静默执行]
validate_node({nodeType: 'n8n-nodes-base.slack', config, mode: 'minimal'})
validate_node({nodeType: 'n8n-nodes-base.slack', config: fullConfig, mode: 'full', profile: 'runtime'})
// 步骤4:构建
// 基于已验证的配置构建工作流
// ⚠️ 显式设置所有参数
// 步骤5:验证
[静默执行]
validate_workflow(workflowJson)
// 所有工具执行完成后的响应:
"已创建工作流:Webhook → Slack
验证结果:✅ 通过"Batch Updates
批量更新
json
// ONE call with multiple operations
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
{type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
{type: "cleanStaleConnections"}
]
})json
// 单次调用执行多个操作
n8n_update_partial_workflow({
id: "wf-123",
operations: [
{type: "updateNode", nodeId: "slack-1", changes: {position: [100, 200]}},
{type: "updateNode", nodeId: "http-1", changes: {position: [300, 200]}},
{type: "cleanStaleConnections"}
]
})Important Rules
重要规则
Core Behavior
核心行为
- Silent execution - No commentary between tools
- Parallel by default - Execute independent operations simultaneously
- Templates first - Always check before building (2,709 available)
- Multi-level validation - Quick check → Full validation → Workflow validation
- Never trust defaults - Explicitly configure ALL parameters
- 静默执行 - 工具调用之间无需额外说明
- 默认并行 - 同时执行独立操作
- 优先使用模板 - 从头构建前始终先检查模板(现有2709个)
- 多层验证 - 快速检查 → 完整验证 → 工作流验证
- 绝不信任默认值 - 显式配置所有参数
Attribution & Credits
来源归因与致谢
- MANDATORY TEMPLATE ATTRIBUTION: Share author name, username, and n8n.io link
- Template validation - Always validate before deployment (may need updates)
- 必须注明模板来源:分享作者姓名、用户名和n8n.io链接
- 模板验证 - 部署前始终验证模板(可能需要更新)
Performance
性能优化
- Batch operations - Use diff operations with multiple changes in one call
- Parallel execution - Search, validate, and configure simultaneously
- Template metadata - Use smart filtering for faster discovery
- 批量操作 - 使用差异操作在单次调用中执行多个修改
- 并行执行 - 同时进行搜索、验证和配置操作
- 模板元数据 - 使用智能筛选加快模板发现速度
Code Node Usage
代码节点使用
- Avoid when possible - Prefer standard nodes
- Only when necessary - Use code node as last resort
- AI tool capability - ANY node can be an AI tool (not just marked ones)
- 尽可能避免 - 优先使用标准节点
- 仅在必要时使用 - 将代码节点作为最后手段
- AI工具能力 - 任何节点都可以作为AI工具(不只是标记为AI的节点)
Most Popular n8n Nodes (for get_node):
最受欢迎的n8n节点(用于get_node):
- n8n-nodes-base.code - JavaScript/Python scripting
- n8n-nodes-base.httpRequest - HTTP API calls
- n8n-nodes-base.webhook - Event-driven triggers
- n8n-nodes-base.set - Data transformation
- n8n-nodes-base.if - Conditional routing
- n8n-nodes-base.manualTrigger - Manual workflow execution
- n8n-nodes-base.respondToWebhook - Webhook responses
- n8n-nodes-base.scheduleTrigger - Time-based triggers
- @n8n/n8n-nodes-langchain.agent - AI agents
- n8n-nodes-base.googleSheets - Spreadsheet integration
- n8n-nodes-base.merge - Data merging
- n8n-nodes-base.switch - Multi-branch routing
- n8n-nodes-base.telegram - Telegram bot integration
- @n8n/n8n-nodes-langchain.lmChatOpenAi - OpenAI chat models
- n8n-nodes-base.splitInBatches - Batch processing
- n8n-nodes-base.openAi - OpenAI legacy node
- n8n-nodes-base.gmail - Email automation
- n8n-nodes-base.function - Custom functions
- n8n-nodes-base.stickyNote - Workflow documentation
- n8n-nodes-base.executeWorkflowTrigger - Sub-workflow calls
Note: LangChain nodes use the prefix, core nodes use
@n8n/n8n-nodes-langchain.n8n-nodes-base.- n8n-nodes-base.code - JavaScript/Python脚本
- n8n-nodes-base.httpRequest - HTTP API调用
- n8n-nodes-base.webhook - 事件驱动触发器
- n8n-nodes-base.set - 数据转换
- n8n-nodes-base.if - 条件路由
- n8n-nodes-base.manualTrigger - 手动执行工作流
- n8n-nodes-base.respondToWebhook - Webhook响应
- n8n-nodes-base.scheduleTrigger - 基于时间的触发器
- @n8n/n8n-nodes-langchain.agent - AI Agent
- n8n-nodes-base.googleSheets - 电子表格集成
- n8n-nodes-base.merge - 数据合并
- n8n-nodes-base.switch - 多分支路由
- n8n-nodes-base.telegram - Telegram机器人集成
- @n8n/n8n-nodes-langchain.lmChatOpenAi - OpenAI聊天模型
- n8n-nodes-base.splitInBatches - 批量处理
- n8n-nodes-base.openAi - OpenAI旧版节点
- n8n-nodes-base.gmail - 邮件自动化
- n8n-nodes-base.function - 自定义函数
- n8n-nodes-base.stickyNote - 工作流文档
- n8n-nodes-base.executeWorkflowTrigger - 子工作流调用
注意:LangChain节点使用前缀,核心节点使用前缀
@n8n/n8n-nodes-langchain.n8n-nodes-base.