n8n-workflow-lifecycle-official

n8n 工作流生命周期

六个阶段

1. 规划。 收集需求，提出澄清问题，搜索是否已有可实现该需求的工作流／子工作流。
2. 构建。 编写 SDK 代码（使用以下技能：子工作流、节点配置、表达式、代码节点；另请参阅下文的可读性部分）。迭代、调试或编辑少量单节点时，可将 validate_node_config 用作辅助工具：它能提供简洁的逐参数错误信息，不会产生整张图的冗余信息。它不能替代 VALIDATE 阶段中的 validate_workflow。
3. 验证。 使用 validate_workflow，再使用 get_workflow_details 检查连接，然后让用户逐个节点验证凭据，并创建你无法创建的内容（缺失的凭据、文件夹等）。
4. 测试。 使用 prepare_workflow_pin_data 和 test_workflow 进行测试；持续迭代，直到输出符合预期。
5. 发布。 只有在第 3 和第 4 阶段都通过后，才能调用 publish_workflow。
6. 交接。 完成交付：说明如何触发工作流、它会返回什么、需要关注什么，以及如何才能更好地使用它。

跳过任何一个阶段，都会导致工作流看起来已经完成，却在生产环境中出故障，或完全没有解决正确的问题。最常见的三种跳过情况：

• 未规划就开始构建。 “用户要 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_workflow_pin_data。有关按触发器类型模拟、固定单个节点以及副作用范围的说明，请参阅 references/TESTING.md。对于有人监看的内部一次性脚本，可以适当放宽。
• 使用 create_workflow_from_code 时，始终提供 description。用 1～2 句话说明其作用和原因。请参阅下文的“可读性”。

验证并不足够

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

• .to() 写在 .add() 内部导致的连接问题（连线被静默丢弃）
• 多路分支被合并成单个连接
• Merge 索引偏一
• 错误输出未使用 onError: 'continueErrorOutput' 进行连线
• 语法有效但语义错误的参数（例如，错误的工作表 ID、错误的列名）

验证必不可少，但并不足够。真正的关卡是：

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

只有完成这些步骤后，才能调用 publish_workflow。

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

执行模型

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

实际影响：

• 分流到 3 个较慢的 HTTP 调用会依次运行；总延迟是各调用延迟之和，而非最大值。
• “并行”分支按执行顺序共享工作流状态；下游使用者会看到最后一个分支留下的状态。
• 如需真正的并发，请使用 mode: 'each' 分发子工作流，并将 waitForSubWorkflow: false。参见 n8n-loops-official 和 n8n-subworkflows-official。

这是平台行为，并非 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-official 的 references/NAMING_AND_DISCOVERY.md。
• 标签： AI 侧的发现机制（n8n 2.27.0+）。MCP 可列出标签（list_workflow_tags）、筛选标签（search_workflows({ tags })），并为工作流添加或移除标签（update_workflow 的 addTags/removeTags；未知名称会自动创建）。每个工作流使用 2-4 个小写标签。参见 references/NAMING_CONVENTIONS.md。

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

共有 4 种提升可读性的方式：节点数达到 7 个时开始分组，其他 3 种方式则从大约 5 个节点开始：

• 工作流 description：记录原因，包括 AI 推导出的上下文。 用两句话说明工作流的作用及其存在原因。最重要的是，记录你在对话中获得、但不会以其他方式保留在文件中的上下文（促使设计的约束、选择这种方案而非替代方案的原因、用户提出请求的原因）。否则，这些信息会随着聊天记录一同消失。
• 节点组：唯一的节点分组方式。 使用命名框架，每个逻辑步骤一个（Validate input、Enrich order、Notify）。节点组仅用于组织，组内节点仍会内联运行（复用和隔离由子工作流负责）。创建或编辑任何组之前，以及任何报告组存在问题的保存操作之后，都请阅读 references/NODE_GROUPS.md。 需要提前了解的 3 点：
  • 何时使用： 超过 7 个框时，通常分成 3-5 组，并将每组折叠。框包括触发器、每个组和每个未分组的节点；子节点和便签不计入。
  • 组必须是无触发器的连通区域，每个方向最多只能有一个成员向外连接；Agent 的子节点必须全部位于组内或全部位于组外。成员使用节点名称，而非 ID。
  • 无效的组操作会被跳过，而非导致操作失败；无关编辑还可能悄无声息地删除有效的现有组，因此看似正常的保存也可能导致组丢失。唯一的例外是描述超过 145 个字符：这会导致整个 update_workflow 调用被拒绝。每次创建和更新时都要检查组字段，并在报告完成之前修复问题。
• 便签：用于标注，而非分组。 分组是节点组的职责（见上文）。便签承载的是组名无法表达的内容：提示、待办事项或警告。放置便签前，请先阅读 references/STICKY_NOTES.md。
  • 创建时，始终锚定节点。 sticky(content, [nodes], { color }) 会在布局完成后根据所包裹的节点确定便签框。坐标是对尚不存在的画布进行猜测；两者都省略更糟，因为回退行为会将便签置于整个图表下方的中央，只避开其他便签，不会避开节点。如果无法说清便签针对哪些节点，它就不该出现在画布上。
  • 便签有三种用途，锚定范围也由用途决定。 阶段区域锚定一个阶段的节点；提示锚定它所警示的单个节点；灰色的标题栏锚定整个流程，这种情况很少见，仅用于你有意不分组的画布。
  • 规模： 节点少于约 5 个时，不用便签。节点框为 5 到 7 个时，每个阶段放一个区域。超过 7 个时，节点组通过自身描述来划分并说明画布内容；不要将便签锚定到已分组的节点：这些位置是折叠芯片的槽位，因此便签会压在展开的组上方，而折叠时则无法匹配。
  • 区域所需空间要大于推导出的框体。 单行区域设置 height: 272，分支扇形区域设置 464（Message an Agent v2+ 时增加 32）。不要设置宽度。然后，等画布定稿后，在一次批量 update_workflow 中扩大每个区域：x = min(node.x) - 56，width = span + 112。这些值根据节点计算，因此重复运行也无妨，但这应是收尾步骤，而非每次编辑都做。
  • update_workflow 没有便签操作。 在其中添加便签时，应使用 parameters 中包含 content、width、height、color 的 n8n-nodes-base.stickyNote addNode；若省略 position，则默认为 [0, 0]。
  • 内容和颜色： 使用说明要点的 ### Title，再加一行简短说明。只有顶部 64px 不会遮挡节点，因此不要为了容纳更多文字而增加高度；较长的文字应放入节点 notes 或工作流 description。color 1-7 表示对应位置发生的情况：绿色表示创建或涉及人员，红色表示具有破坏性或不可逆，蓝色表示路由和转换，灰色表示文档说明。用户偏好优先，其次参考附近的工作流。
• 用节点 notes 说明不明显的配置。 解释变通方案存在的原因，或 Code 节点的用途。不要给显而易见的节点加注释。

另外两点：

• 采用自己的约定前，先遵循项目现有约定。 通过 search_workflows + get_workflow_details 浏览几个相邻工作流，并沿用其便签配色、命名和描述风格。
• 布局只在创建时运行，更新时不会运行。 create_workflow_from_code 会为所有未设置明确 position 的节点自动布局，因此请省略这些位置并交由它处理。部分节点设置位置、部分不设置，是错误做法：已设置的位置会原样保留，其余节点则围绕它们布局，节点因此可能堆叠。update_workflow 完全不运行布局，因此新增内容会精确放在你指定的位置。

文件夹管理

对于已注册的实例，MCP 会创建和管理文件夹：create_folder、update_folder（重命名/移动）、move_workflows_to_folder，以及用于创建时指定位置的 create_workflow_from_code 中的 folderId。search_folders 可根据名称查找 ID。

如果用户想要的文件夹不存在，请先创建它，不要在根目录创建后再报告成功。如果文件夹工具不可用，则表示该实例尚未注册：UI 中也无法使用文件夹，因此请让用户先注册（免费，可在 Settings 中操作），不要手动创建文件夹。没有工具可以删除文件夹，项目则为只读。

完整协议请阅读 references/FOLDER_LIMITATIONS.md。

按工作流控制 MCP 访问权限

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

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

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

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

完整的逐情况指南和面向用户的消息，请参阅 references/MCP_ACCESS_PER_WORKFLOW.md。

用户端接线（第 3 阶段的一部分）

有些事情需要用户完成，你无法代劳；这些事情必须在测试前完成，否则测试可能会使用错误的凭据、遇到缺失的文件夹，或返回 401。在 VALIDATE 阶段、TEST 之前，将这些事项列成简短清单：

• 验证每个节点的凭据。 newCredential('Label') 只是外观标记。n8n 会自动分配最近编辑的、类型匹配的凭据；如果用户有多个凭据（例如生产环境与测试环境的 Gmail，或两个 API 密钥），就可能在不提示的情况下选错。请告知他们：“打开每个使用凭据的节点，并确认选择了正确的凭据。”参见 n8n-credentials-and-security-official 中不可妥协的要求 #2。
• 创建缺失的凭据。 如果用户在聊天中粘贴了密钥，或工作流需要尚不存在的账户，请说明凭据类型，并让他们在 UI 中创建。
• 注册文件夹工具（仅当工具缺失时）。 文件夹工具需要注册实例。如果这些工具不存在，用户需要先注册（免费，位于 Settings 中），之后你才能创建或放置文件夹；否则，你可以自行处理文件夹。参见 references/FOLDER_LIMITATIONS.md。
• 为用户创建的工作流启用 MCP 访问权限。 你通过 MCP 创建的工作流默认可通过 MCP 访问。只有当测试依赖于某个由 UI 创建、且需通过 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 手动触发”“等到 09:00 UTC 进行首次计划运行”。
• 需要关注什么。 可能触发告警或错误的故障模式、上游服务的速率限制上限，以及出现问题时应首先查看的位置（执行记录标签页、错误工作流、审计日志等）。
• MCP 访问状态。 如果你通过 MCP 创建了工作流，它就已经可以通过 MCP 访问。请告知用户，如需限制访问，可在 Settings 中撤销访问权限。如果用户是在 UI 中手动创建的工作流，则需要开启 MCP 访问权限，其他 Agent 才能调用它。
• 用户仍需处理的事项。 如果令牌曾粘贴在聊天中，应轮换密钥；无法访问的后续接线工作；便签中遗留的已知待办事项。

保持简洁：大约六条要点，不要写成长篇大论。用户不应该还要追问“好，那接下来呢？”

参考文件

文件	何时阅读
references/NAMING_CONVENTIONS.md	为新工作流、子工作流或节点命名时
references/NODE_GROUPS.md	创建或编辑任何节点组之前，或保存操作报告跳过或移除了节点组之后
references/STICKY_NOTES.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。
画布上有超过 7 个顶层框，却没有节点组	读者必须逐个查看节点才能找到所需内容	为每个逻辑步骤分组。参见 references/NODE_GROUPS.md
未读取分组字段就报告创建或更新已完成（创建时的 skippedGroups；更新时的 skippedOperations / removedGroups）	分组操作被静默跳过，或现有分组被不相关的编辑删除，但保存仍显示成功	每次调用都检查这些字段并修复。参见 references/NODE_GROUPS.md
用便签伪装分组，或便签使用各种颜色	分组应由节点组负责；颜色会变成纯粹的噪音	使用节点组进行分组；便签仅用于标注说明，每个类别使用一种颜色
在 create_workflow_from_code 中手动放置便签	布局运行前就确定了坐标，因此便签会偏离其描述的节点	将节点传给 sticky(content, [nodes])，让系统自动确定便签框的位置。参见 references/STICKY_NOTES.md
description: "Sends Slack."	相比触发器和 Slack 节点，没有提供任何可见的新信息	补充原因和 AI 推断的背景：“向创始人发送每周摘要。替代总是被跳过的手动报告。”
将扇出分支设计成并发执行	n8n 会按 Y 坐标从上到下顺序执行扇出分支。总运行时间是各分支运行时间之和，而不是最长分支的运行时间	如需真正的并发，通过 Execute Workflow 使用 mode: 'each' + waitForSubWorkflow: false 进行分派。参见 n8n-subworkflows-official 中的“Fire-and-forget parallelization”