在 n8n 中构建可复用子工作流：何时抽取…

当需要抽取共享逻辑、构建多步骤或跨工作流复用的逻辑、或工作流超过约 10 个节点时，用 n8n 子工作流实现封装、复用、可测试与可替换。

适用场景

解决思路

1. 构建前先搜索：用 n8n_list_workflows() 扫描工作流库，用 n8n_get_workflow({ id: "<candidate>" }) 读取候选工作流的输入/输出与主体；若已有匹配则直接使用并告知用户，若没有则以可被搜索到的名称新建。
2. Execute Workflow Trigger 默认使用 "Define Below" 模式并声明显式类型字段（string、number、boolean、array、object），这是唯一能给调用方提供 schema 的模式，也是 AI agent 通过 $fromAI 传值和结构化调用方映射字段的前提。
3. 仅在两种例外下使用 passthrough：需要接收二进制输入（图片/文件/PDF，类型字段仅支持 JSON）；或真正零输入的操作（Define Below 要求至少一个字段）。其他情况使用 passthrough 即为 bug。
4. 判断是否应抽取为子工作流：可能被其他工作流需要 → 抽取；通用关注点（认证、重试、解析、格式化、ID 生成）→ 几乎总是抽取；超过 5 个节点且概念上是一件事 → 大概率抽取；仅一次无逻辑包裹的 HTTP 调用 → 不抽取；与单一调用方数据形状紧耦合 → 先修正数据形状再抽取。
5. 抽取的额外理由：可读性（调用方显示一个节点而非五个）、可测试性（用 n8n_test_workflow 的 prepare 与 pinned 方法单独运行，需 N8N_MCP_ACCESS_TOKEN 与工作流的 "Available in MCP" 设置）、可替换性（替换实现不影响调用方）。
6. 20 节点工作流若主要是 Execute Workflow 调用与决策的线性序列则可接受；若是内联转换则不可接受。若工作流有 15+ 节点且主要不是子工作流调用与分支，应继续抽取。
7. 区分无状态与有状态子工作流：无状态为纯逻辑（输入进、输出出，无额外 I/O），如解析日期、计算 MRR、格式化发票；有状态为在干净契约背后读写外部状态（仓储模式），如按 id 获取客户、写入计费记录、通知值班人员。
8. 避免意外状态：不要将有副作用的子工作流命名和描述为纯函数；要么把副作用纳入契约（重命名、文档化、返回其结果），要么移出。
9. 在触发器上声明类型化输入，节点参数形如 workflowInputs.values 数组，每项含 name 与 type；在主体内用 $json.<field> 读取，或在下游用 $('When Executed by Another Workflow').first().json.<field> 读取。
10. 在工作流 description 中记录输入与输出：字段名、类型、用途及若干代表性关键词；description 是调用方（人与 agent）读取契约的依据，也是 n8n_list_workflows 匹配的对象。
11. 返回一致的自然形状而非存储形状：数组返回数组、对象返回对象、日期返回 ISO 字符串，无论底层存储是否为 JSON 字符串化文本；正确做法是解析缓存路径使其与新鲜路径返回相同自然形状，而非将新鲜路径字符串化。
12. 预期失败返回 { ok: false, error: "..." } 让调用方无需接错误输出即可分支；仅对真正意外失败才抛出异常。
13. 契约一旦有调用方即冻结：新增可选字段安全；重命名或删除字段危险，因为 n8n 不会对未识别输入字段报错，主体只会看到 undefined 而调用方毫不知情，造成静默契约破坏。变更字段时须枚举所有调用方（n8n_list_workflows 加检查每个 Execute Workflow 节点），在同一次变更中迁移，并用 validate_workflow 与 n8n_get_workflow 验证。
14. 用最终 Set / Edit Fields 节点（命名为 Return 或 Return <thing>）塑造输出；这是 Set 节点合法例外，因为子工作流最后节点的隐式消费者是每个调用方，显式 Set 让返回契约可见并剥离噪声字段。
15. 调用方 Execute Workflow 节点的 mode 选择：all（默认）运行一次、每次运行处理全部 N 个条目；each 运行 N 次、每次运行恰好一个条目。当主体假设只看到单个条目（每次运行的聚合、"这就是要处理的客户"逻辑、每次输入只触发一次的最终写入）时必须用 each，并跳过子工作流内部的 Loop Over Items 节点。
16. waitForSubWorkflow 默认 true（调用方阻塞直到子工作流返回并继续使用其输出）；设为 options.waitForSubWorkflow: false 即发即忘，调用方立即继续，子工作流后台运行，下游看不到返回数据。
17. mode: each 加 waitForSubWorkflow: false 是 n8n 唯一真正并行的子工作流执行方式：N 个条目派发 N 次并行运行（受实例并发限制），调用方不知何时或是否完成，因此必须配合独立的完成跟踪机制（通常是子工作流更新进度用的 Data Table）。
18. 按输入形状拆分（N+1 模式）：当子工作流有多条契约真正不同的输入路径（二进制 vs JSON、同步 vs 异步、不同认证方案）时，不要用一个触发器加 passthrough 加内部 Switch；为 N 种不同输入契约构建 N+1 个子工作流——每个外层处理其输入特定准备（校验、获取、哈希、提取）并调用一个共享的下游子工作流，共享核心只有单一类型化输入契约且不知道哪个外层调用了它。
19. 将类型化 Define Below 子工作流用作 AI agent 工具：agent 通过 $fromAI 填充声明字段，主体运行，结果作为工具观察返回；零输入情况仍可作为工具（agent 只决定是否调用）；二进制情况无法干净地作为工具接线，因为 agent 无法直接传二进制。
20. 避免反模式：不要在三处重复同一逻辑；不要不搜索就新建；不要在非二进制且非零输入时用 passthrough；零输入 passthrough 须以 "Keep Only Set" 的 Set 节点开头并加 sticky 注明 "no inputs expected"；不要将有副作用的子工作流命名/描述为纯函数；不要省略 description；不要用 Helper 3 之类无前缀名称；不要在假设单条目的主体上用 mode: all；不要重命名活跃输入字段而不迁移调用方；不要 30 节点工作流不抽取。
21. 了解社区 MCP 的限制：无法按 tag 过滤/发现工作流（仅 UI 支持），发现依赖名称，使用动词优先前缀与 n8n_list_workflows；无法捕获未识别输入字段，n8n 不报错，须手工跨调用方验证字段重命名；输入模式/字段必须由触发器节点声明 workflowInputs.values，用 n8n_update_partial_workflow（updateNode / patchNodeField）配置，用 get_node / validate_node 验证。
22. MCP 能做的事：用 n8n_update_partial_workflow（addNode / addConnection / updateNode / patchNodeField）构建子工作流及其调用方；用 n8n_list_workflows、n8n_get_workflow 发现已有；用 validate_workflow、n8n_validate_workflow 验证；用 n8n_test_workflow 隔离测试；用 n8n_executions 检查运行；用 n8n_manage_datatable 为有状态子工作流提供 Data Table；用 activateWorkflow 激活。
23. 发布子工作流前的检查清单：已用 n8n_list_workflows / n8n_get_workflow 搜索确认不存在；触发器使用 Define Below 与类型化 workflowInputs.values（除非二进制或零输入）；零输入 passthrough 以 "Keep Only Set" Set 节点加 sticky 开头；名称含动词优先前缀（Subworkflow:、<Domain>:、Tool:）；description 记录输入/输出形状并含可搜索关键词；通过最终 Return Set 节点返回自然一致形状而非存储形状；预期失败返回 { ok: false, error }，仅意外失败抛出；若主体假设单条目则调用方 mode 为 each（而非内部 Loop Over Items）；waitForSubWorkflow 被有意设置（false 仅在有完成跟踪机制时）；有状态子工作流在名称与描述中声明副作用；用 validate_workflow 验证并用 n8n_test_workflow 隔离测试。

适用边界 · 注意事项

• 仅一次无逻辑包裹的 HTTP 调用不值得抽取为子工作流，只会平白增加边界。
• 与单一调用方数据形状紧耦合的逻辑不要急于抽取，应先修正数据形状，否则只是把耦合换个地方。
• 二进制输入或真正零输入之外的场景不要使用 passthrough 触发器，否则会失去类型化 schema，agent 无法填充参数、结构化调用方无法绑定。