配置 n8n 节点时如何避免参数猜测导致的验证错误

在配置任何 n8n 节点（HTTP、Webhook、数据库、Slack/Gmail/Discord、AI、触发器、Merge 等）时，通过工具获取实时参数结构而非凭记忆猜测。

适用场景

解决思路

1. 在配置节点前，调用 `get_node_types` 并传入 discriminators（resource、operation、mode），否则只能拿到通用结构，会缺失操作特定的参数和必填字段。
2. 以 `get_node_types` 的实时输出为参数结构的唯一权威来源；技能中的 references 只涵盖模式、陷阱、安全规则和决策（何时用哪个操作、为何用凭证而非文本字段、引擎重试上限等），不涵盖参数名或字段结构。若 reference 示例与 `get_node_types` 返回冲突，以工具为准。
3. 绝不猜测 resource-locator 或 load-options 的值。当 `get_node_types` 显示某参数带 `@searchListMethod` 或 `@loadOptionsMethod`（如 Slack channels、Sheets tabs/docs、DB tables/columns、model lists、labels）时，用 `explore_node_resources`（传入来自 `list_credentials` 的 `credentialId`）解析真实值并使用返回的 `value`。若已知确切 ID 则直接用；若有多个匹配且意图不明则询问用户。例外：`toolWorkflow.workflowId` 没有 search method，需通过 `search_workflows` 解析并使用 `mode: 'id'`。
4. 操作优先配置：先设置 `resource` 和 `operation`，条件参数才会显现。大多数「字段不存在」错误实际是「尚未设置父操作」。
5. 不要跨操作携带参数。更改 `operation` 时，从新结构重新推导。上一操作的残留参数会触发验证失败。
6. 按以下流程处理任何新节点：1) `search_nodes(['<能力关键词>'])` 返回匹配的节点 ID 和 discriminators；2) 为任务选择正确的 (resource, operation)；3) `get_node_types([{ name: '...', resource: '...', operation: '...' }])` 返回含条件字段的精确参数结构；4) 对该结构中的任何 RLC / load-options 参数，用 `explore_node_resources({ nodeType, version, methodName, methodType, credentialType, credentialId, currentNodeParameters? })` 获取真实值，使用返回的 `value`，不要编造 ID；5) 依据该结构构建节点配置；6) `validate_workflow` 并修复错误；7) `get_workflow_details` 检查已保存配置，确认参数已落地；8) 用 pinned data 执行 `test_workflow` 确认运行时行为。跳过任何一步都会放大下一步的问题，最常见的跳过是第 3 步，导致「Cannot read property X」错误，实为「未传 discriminators」。
7. 将 `validate_node_config([{ type, typeVersion, parameters, isToolNode? }])` 作为侧通道使用：它对孤立节点配置运行与 `validate_workflow` 相同的 Zod schema，仅做 schema 级校验，不能替代 `validate_workflow`（后者仍是发布门禁）。适用于：构建过程中迭代单个节点（比每次微调都重跑 `validate_workflow` 更快）；对现有工作流做小改动（接线未变时只检查改动的节点，发布前再全量验证）；调试配置错误的节点（逐参数报错，无图噪声）。对于通过 `ai_tool` 接线的工具子节点，设置 `isToolNode: true` 以评估正确的 `displayOptions` 分支。
8. 注意属性依赖陷阱：某字段仅在另一字段取特定值时才必填；某字段根据 mode 接受不同类型；某字段的选项来自另一字段的值。例如 HTTP Request 的 `authentication: 'genericCredentialType'` 需要 `genericAuthType` 和 `credentials`，而 `'predefinedCredentialType'` 需要不同结构；Postgres 的 `operation: 'executeQuery'` 需要 `query`，而 `operation: 'select'` 需要 `table` 和 `columns`；Slack 的 `messageType: 'block'` 会启用 `messageType: 'text'` 下不存在的 block-builder 字段。始终通过 `get_node_types` 检查具体操作，不要复用其他操作的配置并期望其通过验证。
9. 当选项来自另一字段（`@loadOptionsMethod`）时，用 `explore_node_resources`（`methodType: 'loadOptions'`）解析实时选项，并在方法依赖先前选择时通过 `currentNodeParameters` 传入（例如列出某 spreadsheet 的 tabs 需要 `documentId`）。
10. 按节点类别阅读对应 reference 文件：`references/HTTP_NODES.md`（配置 HTTP Request：auth、分页、query/body 参数、重试）；`references/WEBHOOK_NODES.md`（配置 Webhook trigger 或 Respond to Webhook：body 解析、响应结构、异步模式）；`references/COMMS_NODES.md`（Slack、Gmail、Discord、email：凭证类型、消息结构、附件）；`references/DATABASE_NODES.md`（Postgres、MySQL、Mongo、Supabase：query vs operation、参数绑定、错误处理）；`references/AI_NODES.md`（AI Agent 节点配置项：streaming、vision、`maxIterations`、模型子节点的重试；设计问题交给 `n8n-agents-official`）；`references/TRIGGER_NODES.md`（Webhook、Schedule、Manual、Execute Workflow Trigger：输入 schema、轮询 vs 实时）；`references/SWITCH_FALLBACK.md`（配置 Switch 节点：未命名输出/缺失 fallback 会静默丢弃未匹配项）；`references/MERGE_NODE.md`（配置 Merge 节点，或看到 `useDataOfInput`、`numberOfInputs` 或分支汇聚）。
11. 避免以下反模式：凭去年对该节点的记忆构建配置（参数结构已漂移，验证会以晦涩错误失败）——每次会话每个节点都要 `get_node_types`；在 `get_node_types` 中跳过 discriminators（拿到通用结构，缺失操作特定必填字段）——始终传 `resource` + `operation`（以及存在时的 `mode`）；把一个操作的节点配置复制到另一操作再微调（残留参数触发验证失败，条件字段不适用）——从新操作的结构重新推导；在节点文本字段中硬编码 token/凭证（导出时泄露，见 `n8n-credentials-and-security-official`）——始终使用凭证；配置后不用 `test_workflow` 测试（运行时错误只在真实数据上暴露）——发布前始终用 pinned data 测试。

适用边界 · 注意事项

• 不适用于不使用 n8n 或无法访问 `get_node_types`、`explore_node_resources`、`validate_workflow` 等 n8n 专用工具的场景。
• 不适用于纯设计决策（如 AI Agent 的 prompt、tools、memory、结构化输出设计），这些应交给 `n8n-agents-official`。