n8n 结构化输出完全指南outputParserStructured、JSON Schema 与 autoFix 修复模型实战【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp本文是 n8n AI Agent 体系中结构化输出Structured Output的深度实战指南主题来自本仓库技能包n8n-agents的核心参考文档 STRUCTURED_OUTPUT.md。它解决一个高频痛点AI Agent 返回的自由文本无法被下游节点直接消费而模型偶尔产出的畸形 JSON 会让整个工作流瞬间中断。读完本文你将掌握n8n/n8n-nodes-langchain.outputParserStructured节点的完整配置方法、manualJSON Schema 的编写原则、autoFix修复模型Fixer Model的正确选型以及一张可直接对照排查的解析失败速查表。一条不可妥协的底线解析必须配套失败重试结构化输出在 n8n 中的第一原则是输出解析器必须同时具备解析与失败重试retry两条能力缺一不可。如果没有重试机制模型任何一次格式错误的响应都会让整个工作流停摆——这不是偶发事件而是大模型输出的常态。承载这条原则的节点是n8n/n8n-nodes-langchain.outputParserStructuredn8n 官方 LangChain 节点族它通过ai_outputParser连接槽接入 Agent或 Basic LLM Chain。在技能包 SKILL.md 中这条被列为 Agent 设计的两条不可妥协原则之一Structured output must parse AND autoFix—outputParserStructuredwithautoFix: trueand acoding-capable fixer modelis the production pattern. Without autoFix, one malformed JSON response halts the whole workflow.也就是说生产级模式是outputParserStructuredautoFix: true 一个具备编码能力的修复模型。标准接线模式解析器节点对象在 n8n 工作流 JSON 中解析器节点对象的标准形态如下autoFix开启并为它单独挂一个修复模型{ parameters: { schemaType: manual, inputSchema: { \type\: \object\, \properties\: { \score\: { \type\: \integer\, \minimum\: 1, \maximum\: 5 }, \reason\: { \type\: \string\ } }, \required\: [\score\, \reason\] }, autoFix: true }, type: n8n/n8n-nodes-langchain.outputParserStructured, typeVersion: 1.3, name: Structured Output Parser }接线分两步连接都定义在子节点自己身上这是 n8n 所有ai_*子节点的通用规则参见 SKILL.md 的sub-node pattern一节解析器 → Agent通过ai_outputParser连接让 Agent 的最终答案进入解析器修复模型 → 解析器通过ai_languageModel连接让解析器在失败时把坏输出交给修复模型。Structured Output Parser: { ai_outputParser: [[{ node: AI Agent, type: ai_outputParser, index: 0 }]] }, Fixer LLM: { ai_languageModel: [[{ node: Structured Output Parser, type: ai_languageModel, index: 0 }]] }同时在 Agent 上设置hasOutputParser: true激活ai_outputParser槽位否则连接不会生效。接线中的关键细节sourceOutput如果你通过 MCP 工具n8n_update_partial_workflow以增量操作diff 操作构建 Agent连接必须明确sourceOutput类型。仓库中的 AI Agent 构建指南 ai-agents-guide.ts 明确列出ai_outputParser用于连接结构化/JSON 输出解析器操作形如{type: addConnection, source: Structured Output Parser, target: AI Agent, sourceOutput: ai_outputParser}并且提醒AI 子节点OpenAI 模型、输出解析器等不需要main主连接它们只使用ai_languageModel、ai_tool、ai_memory、ai_outputParser这类 AI 专用连接类型参见 n8n-update-partial-workflow.ts。若把解析器误接进main而不是ai_outputParser验证工具会将其标记为未连接。完整示例无状态 Agent 核心中的解析器与修复模型技能包 EXAMPLES.md 给出了一个完整的无状态 Agent 核心节点片段其中的解析器采用 Block Kit 联合类型 schemaoneOf并单独接线了一个Fixer LLM (coding-capable){ parameters: { schemaType: manual, inputSchema: { \type\: \object\, \properties\: { \text\: { \type\: \string\ }, \blocks\: { \type\: \array\, \items\: { \oneOf\: [ { \type\: \object\, \properties\: { \type\: { \const\: \header\ }, \text\: { \type\: \object\ } }, \required\: [\type\, \text\] }, { \type\: \object\, \properties\: { \type\: { \const\: \section\ }, \text\: { \type\: \object\ } }, \required\: [\type\, \text\] }, { \type\: \object\, \properties\: { \type\: { \const\: \divider\ } }, \required\: [\type\] } ] } } }, \required\: [\text\, \blocks\] }, autoFix: true }, type: n8n/n8n-nodes-langchain.outputParserStructured, typeVersion: 1.3, name: Structured Output Parser (Block Kit) }对应连接为Structured Output Parser (Block Kit): { ai_outputParser: [[{ node: AI Agent, type: ai_outputParser, index: 0 }]] }, Fixer LLM (coding-capable): { ai_languageModel: [[{ node: Structured Output Parser (Block Kit), type: ai_languageModel, index: 0 }]] }注意其中同时存在两个模型主模型接在 Agent 上修复模型接在解析器上——两者都通过ai_languageModel连接但目标节点不同。这正是Agent 一个模型、解析器另一个模型的生产级架构。为什么用 Schema 而不是示例ExampleschemaType: manual 一段真正的 JSON Schema 是默认做法。jsonSchemaExample即schemaType: fromJson粘贴一段示例 JSON 让 n8n 推断 schema看起来更省事但一段示例本质上无法表达约束必填与可选字段——示例只是某个时刻的一个快照解析器无法判断哪些键是强制的枚举Enums——示例里写category: compliance并不能约束模型只能输出compliance | history | risk模型会自行发明新类别数值范围——示例里写score: 3不等于声明了1-5模型返回7或0.85也能通过数组约束——min/max items、元素类型的一致性示例均无法表达字符串格式——email、UUID、ISO 日期、正则示例同样无能为力。一份真正的 schema 同时做两件事给模型更清晰的规则给解析器真正的校验能力。下面的 schema 是一个审核决策输出涵盖了枚举、数值范围、嵌套数组对象与布尔字段{ type: object, properties: { decision: { type: string, enum: [approve, reject, escalate] }, confidence: { type: number, minimum: 0, maximum: 1 }, reasons: { type: array, items: { type: object, properties: { category: { type: string, enum: [compliance, history, risk] }, weight: { type: number, minimum: 0, maximum: 1 }, note: { type: string } }, required: [category, weight] } }, follow_up_required: { type: boolean } }, required: [decision, confidence, reasons, follow_up_required] }什么情况下才用fromJsonjsonSchemaExample只用于你确定永远不会再增加约束的一次性形状throwaway shapes。一旦某个字段需要变成可选、枚举或范围受限你迟早要重写解析器——不如一开始就用 schema。附带提醒inputSchema和jsonSchemaExample在节点参数里都是包含 JSON 的字符串而不是对象参见 INPUT_SCHEMA.md。粘贴进工作流 JSON 时注意转义如果节点无法保存或模型看不到字段先把这段 JSON 单独验证一遍。联合类型场景下 schema 更是唯一选择聊天平台的 Block KitSlack与 adaptive cardsTeams对 schema 的依赖更强它们依赖oneOf联合类型区分不同 block 类型再叠加每个 block 内部的枚举如style等。技能包 CHAT_AGENT_PATTERNS.md 明确指出这类场景jsonSchemaExample完全无法表达且会产生自信但错误的 block 树被平台拒收——所以文档原话是manual schema 在此时更加必要。autoFix: true 与修复模型Fixer Model模型产出的 JSON 往往差一点就合法尾逗号、缺字段、类型错误或者把 JSON 包在 markdown 代码块里。没有autoFix工作流直接中断开启后解析器会把坏输出连同修复提示发给修复模型重试后继续执行。修复模型以独立子节点的形式接入解析器的ai_languageModel槽位。选型要求明确必须使用具备编码能力的模型Sonnet 级别或更高。原因在于——把损坏的 JSON 对照一份含枚举、范围、必填字段的 schema 重新修复本质上是结构化输出 / 编码类任务弱模型或通用模型通常会再产出一份新的畸形 JSON既达不到目的又白白烧掉 token参见 SKILL.md 的 non-negotiables 与 STRUCTURED_OUTPUT.md 的 fixer 一节。自定义重试提示Customize Retry Prompt默认的重试提示通常够用但如果需要定制设置customizeRetryPrompt: true并提供prompt。提示中支持三个占位符在重试时被自动填充{instructions}——原始输出指令含 schema{completion}——模型这次给出的、未通过校验的输出{error}——解析器捕获的具体错误信息。默认的重试提示模板如下建议一般情况保持默认Instructions: -------------- {instructions} -------------- Completion: -------------- {completion} -------------- Above, the Completion did not satisfy the constraints in the Instructions. Error: -------------- {error} -------------- Please try again with an answer that satisfies the constraints. This is a structured output parser tool in n8n. Ensure the output format is correct to pass parsing. DO NOT wrap the output in a markdown code block.只有当你对重试行为有明确理由时比如需要更强硬的措辞、补充业务约束才覆盖它。DO NOT wrap the output in a markdown code block这条指令是承重墙这一行是整个方案的承重指令load-bearing。模型默认倾向于把 JSON 包在三个反引号的json代码块里而这会直接破坏解析器。如果你看到解析失败但输出内容明显是代码块里的合法 JSON修复方式就是把这句话同时加进重试提示如上模板最后一行主模型的系统提示——如果主模型包裹行为严重When responding with structured output, return raw JSON only. DO NOT wrap in markdown code blocks. DO NOT include any prose before or after the JSON.系统提示 解析器双保险Belt and Suspenders解析器把 schema 告诉模型系统提示里也应该再次声明输出形状。技能包 SYSTEM_PROMPT.md 将系统提示定位为 Agent 的承重配置其中就包括全局输出规则。示例## Output Format Respond with a JSON object matching this exact shape: { score: 1-5 integer, reason: brief explanation } ONLY output the JSON. No prose, no markdown wrapping.这看起来是重复但模型对系统提示的遵从度更高重复强化有效而解析器负责兜底捕获漏网之鱼。常见解析失败与修复速查表症状可能原因修复方式提示 Failed to parse output但文本看起来是 JSON输出被包在 markdown 代码块里在重试提示和系统提示中加入 DO NOT wrap in markdownschema 需要值的字段却为空模型认为自己可以省略未知字段明确指示 Use empty string or null for unknown fields, never omit类型错误数字被输出成字符串schema/示例中的类型表达不清在 schema 中使用真正的 number 类型而不是字符串JSON 被截断花括号未闭合生成中途达到 max tokens 上限提高 max tokens收紧提示让输出更短字段名被改写如 Score 变成 scoreschema 没有钉死字段名在系统提示中声明 Field names are exactly as shownautoFix无限重试修复模型对当前 schema 来说太弱换成具备编码能力的Sonnet 级别修复模型收紧重试提示这张速查表直接源自原文档是排查线上解析问题的第一手工具。什么时候不该用解析器解析器不是万能药。以下三类场景不要加解析器面向用户的自由文本聊天回复——对话文本不需要解析只有工具调用、没有最终结构化输出——如果用户可见的输出是纯文本跳过解析器琐碎的键值提取——一个 Set 节点配合JSON.parse($json.output)就足够了。判断标准很清晰只有当下游节点必须消费严格 JSON 时才需要解析器。从 MCP 视角验证与调试本仓库作为 n8n 的 MCP 服务端提供了一整套验证手段参见 SKILL.md 的 Whats NOT available via the community MCP 一节get_node/search_nodes——查看目标实例上outputParserStructured的实际参数与版本节点版本与模型可用性会随 n8n 版本变化务必在目标实例上核实validate_workflow——校验整张图包括 AI 连接是否正确解析器接在main上会被标记为断开n8n_update_partial_workflow——以addConnectionsourceOutput: ai_outputParser增量接线n8n_get_workflow——拉取保存后的 JSON核对ai_outputParser/ai_languageModel连接是否落在正确节点上。检查清单与延伸阅读配置一个生产级结构化输出时逐项确认schemaType: manual 完整 JSON Schema枚举、范围、required 齐全autoFix: true独立的编码能力修复模型接入解析器的ai_languageModel槽位主模型与修复模型是两个不同节点Agent 上hasOutputParser: true系统提示声明输出形状 raw JSON only, no markdown用validate_workflown8n_get_workflow验证接线。本主题的延伸阅读均为仓库内文档相对路径以仓库根目录为起点系统提示的另一半职责persona、全局输出规则→ SYSTEM_PROMPT.md为什么用 Agent 以及四个子节点槽位总览 → SKILL.md完整接线示例含 Block Kit 联合类型 schema 与修复模型→ EXAMPLES.mdBlock Kit / adaptive cards 对 manual schema 的强依赖 → CHAT_AGENT_PATTERNS.mdMCP 侧ai_outputParser连接操作说明 → ai-agents-guide.ts、n8n-update-partial-workflow.ts记住核心结论解析器让输出可校验autoFix 让解析器可容错编码级修复模型让 autoFix 真正生效——三者缺一不可这就是 n8n 结构化输出的生产级配方。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考