n8n-workflow-lifecycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Workflow Lifecycle

n8n工作流生命周期

The six stages

六个阶段

PLAN. Gather requirements, ask clarifying questions, search for existing workflows / sub-workflows that already do this.
BUILD. Write SDK code (with skills: subworkflows, node-config, expressions, code-nodes; readability section below).
VALIDATE.
```
validate_workflow
```
+
```
get_workflow_details
```
for connections, then have the user verify per-node credentials and create anything you couldn't (missing credentials, folders, etc).
TEST.
```
test_workflow
```
with
```
prepare_test_pin_data
```
; iterate until output matches intent.
PUBLISH.
```
publish_workflow
```
only after stages 3 and 4 are clean.
HANDOFF. Production handoff: how to trigger it, what it returns, what to watch, what they should know to use it well.

Skipping a stage produces workflows that look done but break in production, or solve the wrong problem entirely. Three most common skips:

Build before plan. "User asked for X, I'll start coding" without confirming what X means, whether the same logic already exists as a sub-workflow, or which folder/project it belongs in. Cheaper to ask one clarifying question than to rebuild after.
Test before user-side wire-up. Running
```
test_workflow
```
before the user has verified credentials per node hits the wrong service or 401s. Get the user-side setup done as part of VALIDATE.
Publish without test. Validation passing means the SDK is well-formed; it does NOT mean the workflow is correct.

规划阶段。收集需求，提出澄清问题，查找已有的可实现该功能的工作流/子工作流。
构建阶段。编写SDK代码（涉及技能：子工作流、node-config、表达式、代码节点；详见下文可读性部分）。
验证阶段。调用
```
validate_workflow
```
+
```
get_workflow_details
```
检查连接情况，然后让用户验证每个节点的凭据，并创建你无法完成的内容（缺失的凭据、文件夹等）。
测试阶段。结合
```
prepare_test_pin_data
```
调用
```
test_workflow
```
；反复迭代直到输出符合预期。
发布阶段。仅在完成第3和第4阶段且无问题后，调用
```
publish_workflow
```
。
交付阶段。生产环境交付：说明触发方式、返回内容、需要监控的事项，以及用户有效使用该工作流需了解的信息。

跳过任一阶段会导致工作流看似完成但在生产环境中故障，或完全解决错误的问题。最常见的三种跳过情况：

未规划先构建。“用户要X，我直接开始编码”，未确认X的具体含义、是否已有子工作流实现相同逻辑，或该工作流所属的文件夹/项目。提前问一个澄清问题比事后重建成本更低。
未完成用户端配置先测试。在用户验证每个节点的凭据前调用
```
test_workflow
```
，会导致请求错误服务或返回401未授权。将用户端配置作为验证阶段的一部分完成。
未测试就发布。验证通过仅表示SDK格式规范，但不代表工作流逻辑正确。

Non-negotiables

不可协商的规则

Validate AND verify before publish. Run
```
validate_workflow
```
on the SDK code, then
```
get_workflow_details
```
after every create/update to check the
```
connections
```
object. Validation alone misses silently dropped wires.
Surface known limitations to the user. If folders, MCP access, or any other limitation blocks the request, say so explicitly and propose a path. Don't silently dump workflows at the wrong location or report success on a request you couldn't fully fulfill.
Ask before testing when not-auto-pinned downstreams have side effects.
```
test_workflow
```
auto-pins triggers, credentialed nodes, and HTTP Request nodes. Everything else (Code, Edit Fields, If, Wait, Execute Command, file ops, sub-workflow calls, Data Tables) runs for real. Ask the user before running if any of those would fire user-visible side effects. See
```
references/TESTING.md
```
.

发布前必须完成验证与确认。对SDK代码调用
```
validate_workflow
```
，然后在每次创建/更新后调用
```
get_workflow_details
```
检查
```
connections
```
对象。仅靠验证无法发现静默丢失的连接。
向用户明确告知已知限制。如果文件夹、MCP权限或其他限制阻碍请求，需明确说明并提出解决方案。不得将工作流静默放置在错误位置，或在未完全满足请求的情况下报告成功。
当非自动固定的下游节点存在副作用时，测试前需询问用户。
```
test_workflow
```
会自动固定触发器、凭据节点和HTTP请求节点。其他节点（代码节点、编辑字段节点、条件节点、等待节点、执行命令节点、文件操作、子工作流调用、数据表）会真实运行。如果这些节点会产生用户可见的副作用，运行前需询问用户。详见
```
references/TESTING.md
```
。

Strong defaults

Validation isn't enough

仅靠验证远远不够

validate_workflow

runs schema and shape checks: missing parameters, type errors, references to non-existent nodes. It does not catch:

The
```
.to()
```
-inside-
```
.add()
```
connection trap (silent dropped wires)
Fan-outs collapsed to a single connection
Merge index off-by-one
Error outputs wired without
```
onError: 'continueErrorOutput'
```
Parameters that are syntactically valid but semantically wrong (e.g., wrong sheet ID, wrong column name)

Validation is necessary but not sufficient. The real gate is:

```
validate_workflow
```
passes.

get_workflow_details

returns a

connections

object that matches your intent (see

n8n-connections

and its

VERIFICATION.md

```
test_workflow
```
produces the right output on representative pinned data.

Only then call

publish_workflow

For the full pre-publish checklist, see

references/VALIDATION_CHECKLIST.md

validate_workflow

会进行 schema 和格式检查：检查缺失的参数、类型错误、引用不存在的节点。但它无法检测以下问题：

```
.add()
```
内部使用
```
.to()
```
的连接陷阱（静默丢失连接）
扇出分支被合并为单个连接
合并索引偏移
错误输出已连接但未设置
```
onError: 'continueErrorOutput'
```
参数语法有效但语义错误（例如错误的表格ID、错误的列名）

验证是必要但不充分的。真正的发布门槛是：

```
validate_workflow
```
验证通过。

get_workflow_details

返回的

connections

对象符合预期（详见

n8n-connections

及其

VERIFICATION.md

）。

```
test_workflow
```
在代表性固定数据上产生正确输出。

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

publish_workflow

。

完整的发布前检查清单，详见

references/VALIDATION_CHECKLIST.md

。

Naming conventions

命名规范

Bad names compound: a workflow that's hard to find six months from now gets duplicated.

For full conventions (verb-noun patterns, capitalization, prefixes), read

references/NAMING_CONVENTIONS.md

. Short version:

Workflows: verb-first, scoped.

Send weekly customer report

not

Customer report sender

Nodes: describe what they do in this workflow, not the node type.
```
Fetch active customers
```
not
```
Postgres1
```
.

Sub-workflows: prefix with the domain or

Subworkflow:

for stateless reusable ones.

Subworkflow: Parse RFC2822 date

. The prefix is what

search_workflows({ query })

matches on. See

n8n-subworkflows

references/NAMING_AND_DISCOVERY.md

Tags: UI-only. The MCP can't read or write tags, so they're for humans browsing the UI. Don't rely on them for AI discovery.

糟糕的命名会导致问题恶化：六个月后难以找到的工作流会被重复创建。

完整的命名规范（动名词格式、大小写、前缀）详见

references/NAMING_CONVENTIONS.md

。简化版如下：

工作流：动词开头，明确范围。例如
```
Send weekly customer report
```
（发送每周客户报告），而非
```
Customer report sender
```
（客户报告发送器）。
节点：描述该节点在当前工作流中的作用，而非节点类型。例如
```
Fetch active customers
```
（获取活跃客户），而非
```
Postgres1
```
。
子工作流：无状态可复用的子工作流需添加领域前缀或
```
Subworkflow:
```
前缀。例如
```
Subworkflow: Parse RFC2822 date
```
。该前缀是
```
search_workflows({ query })
```
的匹配依据。详见
```
n8n-subworkflows
```
的
```
references/NAMING_AND_DISCOVERY.md
```
。
标签：仅适用于UI界面。MCP无法读取或写入标签，因此标签仅供人类浏览UI时使用。不要依赖标签进行AI检索。

Readability: descriptions, sticky notes, conventions

可读性：描述、便签、规范

For any workflow over ~5 nodes, three levers carry the readability load:

Workflow
description
: capture the why, including AI-derived context. Two sentences: what it does and why it exists. Most importantly, capture context you had during conversation that won't otherwise survive into the file (the constraint that drove the design, why this approach over the alternative, the user's reason for asking). Otherwise it dies with the chat.
Sticky notes: group nodes by purpose. Use the
```
n8n-nodes-base.stickyNote
```
node with markdown
```
content
```
(
```
### Title
```
on the first line, 1-3 sentences of body) and an integer
```
color
```
1-7. Title each with the purpose ("Validate input" not "If, Set, If"). Pick a small palette and stick to it (e.g. gray/yellow for processing, red for errors, pink for TODOs); random colors communicate nothing.
Node
notes
for non-obvious config. Explain why a workaround exists or a Code node does what it does. Don't annotate obvious nodes.

Plus two notes:

Match existing project conventions before introducing your own. Skim a couple of nearby workflows via
```
search_workflows
```
+
```
get_workflow_details
```
and mirror the sticky palette, naming, and description style.
Layout is auto-applied on create / update. SDK
```
position
```
values for non-sticky nodes are ignored. Stickies and naming are your readability levers.

对于节点数超过约5个的工作流，提升可读性主要依靠三个手段：

工作流
description
：说明设计初衷，包括AI推导的上下文。用两句话说明工作流的功能和存在意义。最重要的是，记录对话过程中产生的、不会保存到文件中的上下文信息（驱动设计的约束条件、选择该方案的原因、用户提出需求的背景）。否则这些信息会随对话结束而丢失。
便签节点：按用途分组节点。使用
```
n8n-nodes-base.stickyNote
```
节点，内容采用markdown格式（首行是
```
### 标题
```
，正文1-3句话），并设置1-7的整数
```
color
```
值。标题需说明用途（例如“验证输入”，而非“条件、设置、条件”）。选择少量颜色并保持一致（例如灰色/黄色用于处理环节，红色用于错误处理，粉色用于待办事项）；随机颜色无法传递有效信息。
节点
notes
：注释非显而易见的配置。说明为何需要使用变通方案，或代码节点的作用。无需对明显的节点添加注释。

另外两点注意事项：

遵循现有项目规范，再引入自定义规范。通过
```
search_workflows
```
+
```
get_workflow_details
```
查看几个同项目的工作流，模仿其便签颜色、命名和描述风格。
创建/更新时会自动应用布局。SDK中非便签节点的
```
position
```
值会被忽略。便签和命名是提升可读性的关键手段。

Folder limitations

文件夹限制

The MCP can place a workflow into a folder that already exists. It cannot:

Create new folders
Move existing folders
Move existing workflows between folders

If the user asks for a folder that doesn't exist, say so before building. Don't silently create at the project root and report success. Surface options:

User creates the folder manually, then you place workflows into it.
Use a different existing folder.
Confirm root-level placement is acceptable.

For the full protocol including detecting existing folders via

search_folders

, read

references/FOLDER_LIMITATIONS.md

MCP仅能将工作流放入已存在的文件夹。它无法：

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

如果用户要求放入不存在的文件夹，需在构建前告知用户。不得静默将工作流创建在项目根目录并报告成功。需提供以下选项：

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

有关通过

search_folders

检测现有文件夹的完整流程，详见

references/FOLDER_LIMITATIONS.md

。

Per-workflow MCP access

按工作流划分的MCP权限

Each workflow has an

availableInMCP

flag. The default depends on who created it:

Workflows created via the MCP (
```
create_workflow_from_code
```
) default to MCP-accessible. No toggle step needed: you can find them via
```
search_workflows
```
and operate on them right away.
Workflows created in the n8n UI can default to off. Until the user flips the toggle, the workflow is invisible to you.

The #1 case where this bites: the user built a workflow manually in the UI and now wants you to inspect or edit it, but you can't see it. Before assuming it doesn't exist or you're searching the wrong project, ask the user to confirm MCP access is enabled.

Sub-workflows called via MCP: the caller can use them as code-level sub-workflows without the toggle. To invoke as MCP-exposed tools, the toggle is required (and is on by default for MCP-created sub-workflows).

For the full case-by-case guide and user-facing message, read

references/MCP_ACCESS_PER_WORKFLOW.md

每个工作流都有

availableInMCP

标志。默认值取决于创建者：

通过MCP创建的工作流（
```
create_workflow_from_code
```
）默认支持MCP访问。无需额外操作：你可通过
```
search_workflows
```
找到并直接操作这些工作流。
在n8n UI中创建的工作流默认关闭MCP访问。除非用户开启该开关，否则你无法看到这些工作流。

最常见的问题场景：用户在UI中手动创建了工作流，现在希望你检查或编辑，但你无法看到它。在假设工作流不存在或检索项目错误前，需先让用户确认已开启MCP访问权限。

通过MCP调用的子工作流：调用者可将其作为代码级子工作流使用，无需开启开关。若要作为MCP暴露的工具调用，则需开启开关（通过MCP创建的子工作流默认已开启）。

完整的场景指南和面向用户的提示信息，详见

references/MCP_ACCESS_PER_WORKFLOW.md

。

User-side wire-up (part of stage 3)

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

There are things the user has to do that you can't, and they need to be done before testing, otherwise the test fires against the wrong credential, hits a missing folder, or 401s. Surface these as a short list during VALIDATE, before TEST:

Verify credentials per node.
```
newCredential('Label')
```
is cosmetic. n8n auto-assigns the most recently edited credential of the right type, which silently picks the wrong one when the user has multiples (prod vs staging Gmail, two API keys). Tell them: "open every node that uses a credential and confirm the right one is selected." See
```
n8n-credentials-and-security
```
non-negotiable #2.
Create missing credentials. If the user pasted a secret in chat or the workflow needs an account that doesn't exist yet, name the credential type and have them create it in the UI.
Create missing folders. The MCP can't create folders. If the user wanted a folder that doesn't exist, they create it before you can place the workflow there. See
```
references/FOLDER_LIMITATIONS.md
```
.
MCP access toggle for user created workflows. Workflows you create via the MCP are MCP-accessible by default. The toggle only matters when the test depends on a UI-created workflow being callable from the MCP. See
```
references/MCP_ACCESS_PER_WORKFLOW.md
```
.

Don't proceed to TEST until these are confirmed done.

有些操作必须由用户完成，且需在测试前完成，否则测试会使用错误的凭据、访问不存在的文件夹或返回401未授权。在验证阶段、测试前，需向用户列出以下操作：

验证每个节点的凭据。
```
newCredential('Label')
```
仅为标识。n8n会自动分配最近编辑的对应类型凭据，当用户拥有多个凭据（生产环境与测试环境的Gmail凭据、两个API密钥）时，可能会静默选择错误的凭据。告知用户：“打开每个使用凭据的节点，确认已选择正确的凭据。”详见
```
n8n-credentials-and-security
```
的不可协商规则第2条。
创建缺失的凭据。如果用户在对话中粘贴了密钥，或工作流需要尚未创建的账户，需告知凭据类型并让用户在UI中创建。
创建缺失的文件夹。MCP无法创建文件夹。如果用户需要的文件夹不存在，需让用户先创建，然后你才能将工作流放入其中。详见
```
references/FOLDER_LIMITATIONS.md
```
。
用户创建的工作流需开启MCP访问开关。你通过MCP创建的工作流默认支持MCP访问。仅当测试依赖于可通过MCP调用的UI创建工作流时，才需要开启该开关。详见
```
references/MCP_ACCESS_PER_WORKFLOW.md
```
。

在用户确认完成以上操作前，不得进入测试阶段。

Handoff: production handoff (stage 6)

交付：生产环境交付（第6阶段）

After

publish_workflow

and a clean test, the workflow is technically live, but the user still needs enough context to actually use it in production. Treat this like the freelancer-to-customer handoff: short, structured, and oriented toward how they'll operate it from here.

What to include:

How it triggers. Webhook URL (live now that it's published), schedule cadence + timezone, manual trigger button, sub-workflow caller, whichever applies. For webhooks, hand them the URL.
What it returns / where the data goes. One sentence. "Writes new rows to the
```
customers
```
table," "responds JSON to the caller," "fires the on-call Slack channel."
How to invoke it for real, with an example. "Hit the webhook with
```
curl -X POST <url> -d '{...}'
```
," "trigger manually from the UI," "wait until 09:00 UTC for the first scheduled run."
What to watch. Failure modes that surface as alerts/errors, rate-limit ceilings on upstream services, and where to look first when something breaks (executions tab, error workflow, audit log, etc.).
MCP access status. If you created the workflow via the MCP, it's already MCP-accessible. Let the user know they can revoke access in Settings if they want to lock it down. If they hand-built it in the UI, they need to flip MCP access on for any other agent to call it.
Anything still pending on their side. Secret rotation if a token was pasted in chat, follow-up wiring you couldn't reach, known TODOs left in stickies.

Keep it tight: half a dozen bullets, not a wall of text. The user shouldn't have to ask "ok, what now?"

调用

publish_workflow

并完成测试后，工作流已正式上线，但用户仍需要足够的上下文才能在生产环境中实际使用。将此视为自由职业者向客户交付成果：内容简洁、结构化，聚焦于用户后续的操作方式。

需包含的内容：

触发方式。Webhook URL（发布后立即生效）、调度周期+时区、手动触发按钮、子工作流调用者，根据实际情况选择。对于Webhook，需提供URL。
返回内容/数据去向。一句话说明。例如“将新行写入
```
customers
```
表”“向调用者返回JSON数据”“发送消息至值班Slack频道”。
实际调用示例。例如“使用
```
curl -X POST <url> -d '{...}'
```
调用Webhook”“在UI中手动触发”“等待UTC时间09:00进行首次调度运行”。
监控要点。会触发警报/错误的故障模式、上游服务的速率限制上限，以及出现问题时首先查看的位置（执行选项卡、错误工作流、审计日志等）。
MCP权限状态。如果你通过MCP创建工作流，它默认支持MCP访问。告知用户若要锁定权限，可在设置中撤销访问。如果用户在UI中手动创建工作流，需开启MCP访问开关才能被其他Agent调用。
用户仍需完成的事项。例如对话中粘贴的密钥需要轮换、你无法完成的后续配置、便签中记录的已知待办事项。

内容需简洁：大约6个要点，不要长篇大论。用户不应再问“接下来该怎么做？”

Reference files

参考文件

File	Read when
`references/NAMING_CONVENTIONS.md`	Naming a new workflow, sub-workflow, or node
`references/FOLDER_LIMITATIONS.md`	User mentions a folder, project structure, or wants workflows organized
`references/MCP_ACCESS_PER_WORKFLOW.md`	Building a workflow that you or another agent will call via MCP
`references/VALIDATION_CHECKLIST.md`	Just finished a workflow and about to call `publish_workflow`
`references/REVIEW_CHECKLIST.md`	Reviewing or auditing an existing workflow (any age, any author). Severity-tiered findings, distinct from the pre-publish validation checklist
`references/TESTING.md`	About to run `test_workflow` or `execute_workflow` , mocking trigger input, side-effect protocol

文件	阅读场景
`references/NAMING_CONVENTIONS.md`	为新工作流、子工作流或节点命名时
`references/FOLDER_LIMITATIONS.md`	用户提及文件夹、项目结构，或要求整理工作流时
`references/MCP_ACCESS_PER_WORKFLOW.md`	构建可通过MCP调用的工作流时
`references/VALIDATION_CHECKLIST.md`	完成工作流并准备调用 `publish_workflow` 时
`references/REVIEW_CHECKLIST.md`	审核现有工作流（无论创建时间和作者）时。包含按严重程度分级的检查项，与发布前验证清单不同
`references/TESTING.md`	准备调用 `test_workflow` 或 `execute_workflow` 、模拟触发器输入、处理副作用时

Anti-patterns

反模式

Anti-pattern	What goes wrong	Fix
Calling `publish_workflow` without validating	Broken workflows reach production	Validate, verify connections, then test
Skipping `get_workflow_details` after create	Silent connection bugs ship	Always pull the workflow back. See `n8n-connections`
Creating workflows at root because the requested folder doesn't exist	Workflows get lost, and the user has to drag them manually	Surface the limitation before building
Generic node names ( `HTTP Request1` , `Set2` )	Workflows are unreadable a month later	Rename to describe the action
Missing `description` on `create_workflow_from_code`	Workflow invisible in search, no context for maintainers	Always include 1-2 sentences
Asking the user to flip the MCP access toggle on a workflow you created via the MCP	Wastes their time, agent-created workflows default to MCP-accessible	Only mention the toggle for UI-created workflows, or when the user wants to revoke MCP access on an agent-created one
Running `test_workflow` on a workflow with side-effecty non-pinned downstreams without asking	Real Data Table write, real sub-workflow side effects, real Execute Command output, etc. Triggers + credentialed nodes + HTTP get pinned, nothing else does	Ask first. See `references/TESTING.md` .
No sticky notes on a 15-node workflow	Reader has to read every node to find what they want	Add stickies per logical section. See "Readability" above
Sticky titled "Set, If, Set" or sticky-of-every-color	Re-states what's visible / color becomes pure noise	Title with the purpose; one color per category
`description: "Sends Slack."`	Adds nothing visible from the trigger and Slack node	Include why + AI-derived context: "Sends weekly summary to founders. Replaces manual report that kept getting skipped."
Designing fan-out branches as if they execute concurrently	n8n runs fan-out branches sequentially, top-to-bottom by Y-position. Total runtime is the sum of branches, not the max	For real concurrency, dispatch via `Execute Workflow` with `mode: 'each'` + `waitForSubWorkflow: false` . See `n8n-subworkflows` "Fire-and-forget parallelization"

反模式	问题	解决方案
未验证就调用 `publish_workflow`	故障工作流进入生产环境	先验证、确认连接，再测试
创建后未调用 `get_workflow_details`	静默连接错误被发布	始终重新获取工作流详情。详见 `n8n-connections`
因请求的文件夹不存在而将工作流创建在根目录	工作流丢失，用户需手动拖动	构建前告知用户该限制
通用节点名称（ `HTTP Request1` 、 `Set2` ）	一个月后工作流难以阅读	重命名为描述具体操作的名称
调用 `create_workflow_from_code` 时未添加 `description`	工作流在检索中不可见，维护者无上下文	始终添加1-2句话的描述
要求用户为你通过MCP创建的工作流开启MCP访问开关	浪费用户时间，Agent创建的工作流默认支持MCP访问	仅对UI创建的工作流提及该开关，或当用户希望撤销Agent创建工作流的MCP访问权限时提及
未询问用户就对存在副作用的非固定下游节点调用 `test_workflow`	真实的数据表写入、真实的子工作流副作用、真实的执行命令输出等。触发器+凭据节点+HTTP GET节点会被固定，其他节点不会	先询问用户。详见 `references/TESTING.md`
15节点的工作流未添加便签	阅读者需逐个查看节点才能找到目标	按逻辑模块添加便签。详见上文“可读性”部分
便签标题为“设置、条件、设置”或使用多种随机颜色	重复可见内容/颜色无意义	标题需说明用途；同一类别使用同一种颜色
`description: "Sends Slack."`	未提供触发器和Slack节点之外的信息	包含设计初衷+AI推导的上下文：“向创始人发送每周汇总报告。替代经常被遗漏的手动报告。”
将扇出分支设计为并发执行	n8n会按Y坐标从上到下顺序执行扇出分支。总运行时间为各分支时间之和，而非最长分支时间	如需真正的并发，通过 `Execute Workflow` 设置 `mode: 'each'` + `waitForSubWorkflow: false` 实现。详见 `n8n-subworkflows` 的“即发即弃并行化”部分