n8n-workflow-lifecycle

n8n 工作流生命周期

六个阶段

1. 规划（PLAN）。 收集需求、提出澄清问题，并搜索是否已有能实现该功能的工作流或子工作流。
2. 构建（BUILD）。 编写 SDK 代码（使用以下技能：subworkflows、node-config、expressions、code-nodes；可读性部分见下文）。使用 validate_node_config 作为迭代、调试或进行小型单节点修改时的辅助工具：它能提供清晰的参数级错误信息，不会产生整张图的噪声。它不能替代 VALIDATE 阶段的 validate_workflow。
3. 验证（VALIDATE）。 运行 validate_workflow，再用 get_workflow_details 检查连接，然后让用户逐节点验证凭据，并创建你无法创建的内容（缺失的凭据、文件夹等）。
4. 测试（TEST）。 使用 prepare_test_pin_data 配合 test_workflow 进行测试；持续迭代，直到输出符合预期。
5. 发布（PUBLISH）。 仅在第 3 和第 4 阶段均通过后，才运行 publish_workflow。
6. 交接（HANDOFF）。 交付生产环境：说明如何触发工作流、会返回什么、需要留意什么，以及如何才能用好它。

跳过任何阶段，都会导致工作流看起来已经完成，却在生产环境中出错，或者完全没解决对的问题。最常见的三种跳过方式：

• 先构建，后规划。 “用户要的是 X，我现在就开始写代码”，却没有确认 X 的含义、是否已有子工作流实现相同逻辑，或该工作流应该归属哪个文件夹或项目。先问一个澄清问题，比事后重做更省成本。
• 用户端尚未接线就先测试。 用户尚未逐节点验证凭据时运行 test_workflow，可能会访问错误的服务或返回 401。应在 VALIDATE 阶段完成用户端的设置。
• 未经测试就发布。 验证通过只代表 SDK 格式正确；这并不代表工作流正确。

不可妥协的要求

1. 发布前必须验证并核实。 对 SDK 代码运行 validate_workflow，然后在每次创建或更新后运行 get_workflow_details，检查 connections 对象。验证本身无法发现被静默丢弃的连线。validate_node_config 是独立的逐节点迭代工具，不能替代此步骤。
2. 向用户说明已知限制。 如果文件夹、MCP 访问权限或其他限制阻碍了请求，请明确说明，并提出可行方案。不要默默把工作流放到错误的位置，也不要对无法完全完成的请求声称成功。
3. 如果未自动固定测试数据的下游节点有副作用，测试前必须征得用户同意。 test_workflow 会自动固定触发器、有凭据的节点和 HTTP Request 节点。其他节点（Code、Edit Fields、If、Wait、Execute Command、文件操作、子工作流调用、Data Tables）都会真实运行。如果其中任何节点可能触发用户可见的副作用，运行前请先询问用户。参见 references/TESTING.md。

强烈建议的默认做法

• 发布前先测试，使用 test_workflow 配合 prepare_test_pin_data。关于如何根据触发器类型模拟、固定单个节点以及副作用范围，请参见 references/TESTING.md。对于你会观察其运行的一次性内部脚本，可以酌情放宽。
• 调用 create_workflow_from_code 时始终提供 description。 用 1-2 句话说明是什么以及为什么。参见下文的“可读性”。

验证还不够

validate_workflow 会检查架构和结构：缺少参数、类型错误、引用了不存在的节点。但它不会发现：

• .add() 中嵌套 .to() 的连接陷阱（连线被静默丢弃）
• 扇出连接被折叠为单个连接
• Merge 索引偏差 1
• 错误输出已接线，但未设置 onError: 'continueErrorOutput'
• 语法有效但语义错误的参数（例如，工作表 ID 错误、列名错误）

验证是必要条件，但并非充分条件。真正的发布门槛是：

1. validate_workflow 通过。
2. get_workflow_details 返回的 connections 对象符合预期。
3. test_workflow 使用有代表性的固定数据产生正确输出。

只有满足以上条件，才能调用 publish_workflow。

完整的发布前检查清单请参见 references/VALIDATION_CHECKLIST.md。

执行模型

n8n 工作流按从左到右、从上到下的顺序依次执行。画布上视觉上看似并行的分支（从一个来源分流到多个下游）会依次运行，顺序由目标节点在画布上的 Y 位置决定。系统不会自动并发执行。

实际影响：

• 分流到三个耗时较长的 HTTP 调用时，它们会串行运行；总延迟是各调用延迟之和，而非其中的最大值。
• “并行”分支会按执行顺序共享工作流状态；下游使用方看到的是最后一个分支留下的状态。
• 如需真正的并发，请使用 mode: 'each' 分派子工作流，并设置 waitForSubWorkflow: false。请参阅 n8n-loops 和 n8n-subworkflows。

这是平台行为，不是 SDK 的问题。设计分流时不要假设它们会并行运行。

命名约定

糟糕的命名会造成连锁影响：六个月后难以查找的工作流，很可能会被重复创建。

完整约定（动词-名词模式、大小写和前缀）请阅读 references/NAMING_CONVENTIONS.md。简要说明：

• **工作流：**以动词开头，并明确范围。使用 Send weekly customer report，而非 Customer report sender。
• **节点：**描述它们在此工作流中的作用，而非节点类型。使用 Fetch active customers，而非 Postgres1。
• **子工作流：**使用直白的描述性名称（Parse RFC2822 date）；通过标签（subworkflow、领域标签、tool）标注类别，而不是在名称前添加前缀。search_workflows({ tags }) 可按标签筛选。请参阅 n8n-subworkflows 的 references/NAMING_AND_DISCOVERY.md。
• **标签：**AI 侧的发现机制（n8n 2.27.0+）。MCP 可列出标签（list_tags）、筛选工作流（search_workflows({ tags })），并为工作流添加标签（update_workflow 的 addTags/removeTags；未知名称会自动创建）。使用小写，每个工作流添加 2-4 个标签。请参阅 references/NAMING_CONVENTIONS.md。

可读性：描述、节点组、便笺和约定

对于节点数超过约 5 个的工作流，可通过以下四种方式提升可读性：

• **工作流 description：记录缘由，包括 AI 推导出的背景。**用两句话说明工作流的作用和存在原因。最重要的是，记录你在对话中获知、但不会保留在文件中的背景（促成设计的约束、选择此方案而非替代方案的原因、用户提出请求的缘由）。否则，这些信息会随着聊天消失。
• **节点组：节点数超过约 10 个时，将每个逻辑步骤分组。**通过 update_workflow 的 setNodeGroups（n8n 2.28.0+）将画布划分为具名分组，每个逻辑步骤对应一个分组（Validate input、Enrich order、Notify）。每个分组都必须是一个不含触发器、连通且只有一个入口和一个出口的执行流（n8n 会拒绝其他形式）；折叠后，工作流呈现为各个步骤，而非各个节点。如果某个部分分支过多，无法组成一个分组，则用便笺标记。分组仅用于整理，组内节点仍会内联运行（复用和隔离应由子工作流负责）。
• **便笺：按用途对节点分组。**使用 n8n-nodes-base.stickyNote 节点，通过 Markdown content 添加内容（第一行为 ### Title，正文为 1-3 句话），并设置整数 color 1-7。标题应描述用途（使用 “Validate input”，而非 “If, Set, If”）。选择少量颜色并保持一致（例如，处理步骤使用灰色/黄色，错误使用红色，待办事项使用粉色）；随机使用颜色无法传达信息。
• **节点 notes：说明不明显的配置。**解释存在某种变通方案的原因，或 Code 节点的用途。明显的节点无需注释。

另外请注意两点：

• **先遵循现有项目约定，再引入自己的约定。**通过 search_workflows + get_workflow_details 查看几个相邻工作流，并沿用它们的便笺配色、命名和描述风格。
• **创建或更新时会自动应用布局。**非便笺节点的 SDK position 值会被忽略。便笺、节点组和命名是提升可读性的手段。

文件夹限制

MCP 可以将工作流放入已存在的文件夹中，但不能：

• 创建新文件夹
• 移动现有文件夹
• 在文件夹之间移动现有工作流

如果用户指定的文件夹不存在，请在构建之前说明。不要悄悄在项目根目录创建工作流，然后报告成功。请提供以下选项：

1. 用户手动创建文件夹，然后你将工作流放入其中。
2. 使用其他已存在的文件夹。
3. 确认放在根目录是否可以接受。

关于如何通过 search_folders 检测已存在的文件夹，以及完整协议，请阅读 references/FOLDER_LIMITATIONS.md。

每个工作流的 MCP 访问权限

每个工作流都有一个 availableInMCP 标志。默认值取决于创建者：

• 通过 MCP 创建的工作流（create_workflow_from_code）默认可通过 MCP 访问。无需切换开关：你可以通过 search_workflows 找到它们并立即操作。
• 在 n8n 界面中创建的工作流默认可能处于关闭状态。在用户切换开关之前，你无法看到该工作流。

最常见的情况是：用户在界面中手动创建了工作流，现在想让你检查或编辑，但你看不到它。 在假定工作流不存在或搜索了错误项目之前，请先让用户确认已启用 MCP 访问权限。

通过 MCP 调用的子工作流：调用方可以将它们用作代码级子工作流，无需切换开关。若要将其作为 MCP 暴露的工具调用，则必须启用开关（通过 MCP 创建的子工作流默认已启用）。

关于各种情况的完整指南和面向用户的提示，请阅读 references/MCP_ACCESS_PER_WORKFLOW.md。

用户端设置（第 3 阶段的一部分）

有些操作必须由用户完成，你无法代劳，而且必须在测试前完成，否则测试可能会使用错误的凭据、遇到缺失的文件夹，或返回 401。在 VALIDATE 阶段、TEST 之前，请用简短列表说明以下事项：

• 逐个节点核实凭据。 newCredential('Label') 只是外观上的设置。n8n 会自动分配最近编辑的同类型凭据；如果用户有多个凭据（例如生产环境和暂存环境的 Gmail 凭据、两个 API 密钥），就可能悄悄选错。请告诉用户：“打开每个使用凭据的节点，并确认选中了正确的凭据。”参见 n8n-credentials-and-security 中不可妥协的要求 #2。
• 创建缺失的凭据。 如果用户在聊天中粘贴了密钥，或工作流需要一个尚不存在的账户，请说明凭据的类型，并让用户在界面中创建。
• 创建缺失的文件夹。 MCP 无法创建文件夹。如果用户指定的文件夹不存在，必须先由用户创建，然后你才能将工作流放入其中。参见 references/FOLDER_LIMITATIONS.md。
• 为用户创建的工作流启用 MCP 访问权限。 你通过 MCP 创建的工作流默认可通过 MCP 访问。只有当测试依赖于从 MCP 调用通过界面创建的工作流时，才需要切换开关。参见 references/MCP_ACCESS_PER_WORKFLOW.md。

确认以上事项已完成后，再继续进行 TEST。

交接：生产环境交接（阶段 6）

在调用 publish_workflow 并通过测试后，工作流在技术层面已经上线，但用户仍需要充分了解相关情况，才能在生产环境中实际使用。请将此视为自由职业者向客户交接项目：简短、结构清晰，并着重说明后续如何操作。

需要包含的内容：

• 如何触发。 Webhook URL（发布后即可使用）、触发频率和时区、手动触发按钮、子工作流调用方，或其他适用方式。如果使用 Webhook，请提供 URL。
• 返回什么／数据去向。 用一句话说明。例如：“向 customers 表写入新行”、“向调用方返回 JSON”、“向值班 Slack 频道发送通知”。
• 如何实际调用，并提供示例。 例如：“使用 curl -X POST <url> -d '{...}' 调用 Webhook”、“在 UI 中手动触发”、“等到 UTC 时间 09:00 首次定时运行”。
• 需要关注什么。 说明会触发警报／错误的故障模式、上游服务的速率限制上限，以及出问题时首先该去哪里排查（执行记录标签页、错误工作流、审计日志等）。
• MCP 访问状态。 如果你是通过 MCP 创建工作流的，它已经可以通过 MCP 访问。告知用户，如果想限制访问，可以在 Settings 中撤销访问权限。如果用户是在 UI 中手动创建的，则需要开启 MCP 访问权限，其他 Agent 才能调用它。
• 用户仍需处理的事项。 如果令牌曾粘贴在聊天中，需要轮换密钥；你无法完成的后续连接；便笺中留下的已知待办事项。

保持简洁：大约六条要点，不要写成大段文字。用户不应该还要追问“好，然后呢？”

参考文件

文件	阅读时机
references/NAMING_CONVENTIONS.md	为新工作流、子工作流或节点命名时
references/FOLDER_LIMITATIONS.md	用户提到文件夹、项目结构，或希望整理工作流时
references/MCP_ACCESS_PER_WORKFLOW.md	构建你或其他 Agent 将通过 MCP 调用的工作流时
references/VALIDATION_CHECKLIST.md	刚完成工作流、准备调用 publish_workflow 时
references/REVIEW_CHECKLIST.md	审查或审计现有工作流时（不论创建时间或作者）。其中包含按严重程度分级的发现项，与发布前验证清单不同
references/TESTING.md	准备调用 test_workflow 或 execute_workflow、模拟触发器输入或处理副作用协议时

反模式

反模式	问题所在	修复方法
未经验证就调用 publish_workflow	有问题的工作流会进入生产环境	先验证、确认连接，然后测试
因请求的文件夹不存在而在根目录创建工作流	工作流会被遗忘，用户还得手动拖动它们	在开始构建之前说明此限制
使用通用节点名称（HTTP Request1、Set2）	一个月后工作流就会变得难以理解	重命名，使名称能描述操作
在 create_workflow_from_code 中缺少 description	工作流无法通过搜索找到，维护人员也不了解其背景	始终填写 1–2 句话
要求用户在通过 MCP 创建的工作流上打开 MCP 访问开关	浪费用户时间；Agent 创建的工作流默认可通过 MCP 访问	仅对通过 UI 创建的工作流提及此开关，或在用户想要撤销 Agent 创建的工作流的 MCP 访问权限时提及
未经询问，就对下游包含会产生副作用且未固定数据的节点的工作流运行 test_workflow	可能会实际写入 Data Table、触发子工作流副作用、产生真实的 Execute Command 输出等。触发器、带凭据的节点和 HTTP 节点会固定数据，其他节点则不会	先询问。请参阅 references/TESTING.md。
15 个节点的工作流没有便利贴	读者必须逐一阅读所有节点才能找到所需内容	按逻辑分区添加便利贴。请参阅上文的“可读性”
便利贴标题为“Set、If、Set”，或每张便利贴都使用不同颜色	重复显示已有信息／颜色变成纯粹的干扰	标题写明用途；每个类别使用一种颜色
description: "Sends Slack."	没有补充触发器和 Slack 节点中已有的信息	写明原因和 AI 推断的背景信息：“每周向创始人发送摘要。取代总是被搁置的手动报告。”
将扇出分支设计成并发执行	n8n 会按照 Y 坐标从上到下依次运行扇出分支。总运行时间是各分支运行时间之和，而不是最长分支的运行时间	如需真正并发，请使用 Execute Workflow，设置 mode: 'each' 和 waitForSubWorkflow: false 来分发任务。请参阅 n8n-subworkflows 中的“Fire-and-forget parallelization”