n8n-validation-expert

用途

n8n-validation-expert 是一个面向 n8n 工作流验证的专家指南技能，用于解读验证错误并指导修复。当遇到验证错误、验证警告、误报、运算符结构问题等情况时，可借助该技能理解问题所在并采取对应措施。

该技能强调“尽早验证、频繁验证”。验证通常是迭代过程，而非一次性完成：预期会出现验证反馈循环，通常需要 2-3 轮“验证 → 修复”循环。根据其引用的遥测数据，平均约 23 秒用于思考错误，58 秒用于修复错误。

错误（必须修复）：会阻止工作流执行，必须在激活前解决。类型包括 missing_required（缺少必填字段）、invalid_value（值不在允许选项内）、type_mismatch（数据类型错误）、invalid_reference（引用的节点不存在）、invalid_expression（表达式语法错误）。
警告（应当修复）：不阻止执行，工作流可激活但可能存在问题。类型包括 best_practice（最佳实践建议）、deprecated（使用了旧 API/功能）、performance（潜在性能问题）。
建议（可选）：锦上添花的改进，类型包括 optimization（可更高效）、alternative（实现同一结果的更好方式）。

典型模式为：配置节点 → 调用 validate_node_operation → 仔细阅读错误信息 → 修复错误 → 再次验证 → 重复直到通过（通常 2-3 次迭代）。该技能以 Slack 节点为例展示了从缺少 name、缺少 text 到最终通过的多轮迭代过程，并强调多次迭代是正常现象。

minimal：用于编辑期间的快速检查，仅验证必填字段和基本结构。最快、最宽松，但可能遗漏问题。
runtime（推荐）：用于部署前验证，验证必填字段、值类型、允许值和基本依赖。平衡性好，能捕获真实错误，但可能遗漏部分边缘情况。是大多数场景的推荐配置。
ai-friendly：用于 AI 生成的配置，验证范围与 runtime 相同，但减少误报、对次要问题更宽容。对 AI 工作流噪音更少，但可能允许一些可疑配置。
strict：用于生产部署和关键工作流，验证一切内容，包括最佳实践、性能问题和安全问题。安全性最高，但警告多、存在部分误报。

missing_required：缺少必填字段。可用 get_node_essentials 查看必填字段，补充缺失字段并给出合适值。
invalid_value：值不在允许选项内。查看错误信息中的允许值，用 get_node_essentials 查看选项，更新为有效值。
type_mismatch：字段数据类型错误。根据错误信息中的期望类型转换值。
invalid_expression：表达式语法错误。可参考 n8n Expression Syntax 技能，检查是否缺少 {{}} 或存在拼写错误，并核实节点/字段引用。
invalid_reference：引用的节点不存在。检查节点名称拼写，确认节点存在于工作流中，更新为正确名称。

自动清理会在任何工作流更新时运行（如 n8n_create_workflow、n8n_update_partial_workflow 及任何工作流保存操作），自动修复常见的运算符结构问题：

二元运算符（equals、notEquals、contains、notContains、greaterThan、lessThan、startsWith、endsWith）：移除 singleValue 属性。
一元运算符（isEmpty、isNotEmpty、true、false）：添加 singleValue: true。
IF/Switch 元数据：为 IF v2.2+ 和 Switch v3.2+ 添加完整的 conditions.options 元数据。

它无法修复的情况包括：损坏的连接（可用 cleanStaleConnections 操作处理）、分支数量不匹配、以及 API 返回损坏数据却拒绝更新的矛盾损坏状态（可能需要手动数据库干预）。

误报是指技术上“错误”但在特定用例下可接受的验证警告。常见误报包括：缺少错误处理、无重试逻辑、缺少速率限制、无界查询。该技能分别说明了每种误报在何种情况下可接受、何时应当修复。可通过使用 ai-friendly 配置文件减少误报。

验证结果包含 valid、errors、warnings、suggestions 和 summary 字段。阅读时应先检查 valid 字段，优先修复 errors，再审查 warnings，最后考虑 suggestions。

validate_workflow 用于验证整个工作流而非单个节点，检查节点配置、连接、表达式和流程结构。常见工作流错误包括：损坏的连接、循环依赖、多个起始节点、未连接的节点。

策略 1：从头开始：配置严重损坏时，从 get_node_essentials 记录必填字段，创建最小有效配置，逐步添加功能并每次验证。
策略 2：二分查找：工作流验证通过但执行不正确时，移除一半节点进行验证和测试，逐步隔离问题。
策略 3：清理陈旧连接：出现“节点未找到”错误时，使用 cleanStaleConnections 操作。
策略 4：使用自动修复：运算符结构错误时，先用 n8n_autofix_workflow 预览（applyFixes: false），再应用修复（applyFixes: true）。

应当：每次重大更改后验证；完整阅读错误信息；逐个迭代修复错误；部署前使用 runtime 配置文件；在假定成功前检查 valid 字段；对运算符问题信任自动清理；不清楚要求时使用 get_node_essentials；记录接受的误报。

不应：激活前跳过验证；试图一次性修复所有错误；忽略错误信息；开发期间使用 strict 配置文件（噪音过多）；假定验证已通过（始终检查结果）；手动修复自动清理问题；带着未解决的错误部署；忽略所有警告。

该技能为指南性质，具体工具调用与行为依赖 n8n 环境；自动清理无法处理损坏连接、分支数量不匹配和矛盾损坏状态；误报需要用户自行判断是否接受。