n8n-skills 路由器指南:用 using-n8n-mcp-skills 为 n8n 工作流构建流程掌舵

原创2026-10-09 16:50:001,333 阅读
文章标签:AI 技能AI 插件工作流自动化流程编排

n8n-skills 路由器指南:用 using-n8n-mcp-skills 为 n8n 工作流构建流程掌舵

using-n8n-mcp-skills 是 n8n-skills 技能包中常驻会话的"路由器"(Router)技能:它本身不承载深度参考内容,而是在每个会话开始时就告诉 Claude 哪一项专家技能 该接管眼前的任务,并一次性给出所有 n8n-mcp 工具的可用知识。本指南以该技能的 README.md 与 SKILL.md 为骨架,结合仓库中 hooks、session-start.sh 等源码佐证,完整讲解路由器的三条不可协商规则、强默认值、red-flags 路由表、技能索引、n8n-mcp 工具全景以及按序执行的工作协议。读完你将掌握:在任何 n8n 构建任务开始前正确选路、避免让工作流在生产环境静默崩坏的套路化陷阱,以及如何在没有 hook 的普通客户端上依然保持纪律。


一、路由器定位:先选路,再动手,最后让专家技能干活

using-n8n-mcp-skills 的自我定位是 router, not a reference(路由器而非参考手册)。它只回答一个核心问题:"手头的任务归哪项技能管?"——然后立刻让位("get out of the way"),把实际指导交给对应的专家技能正文。

因此该技能刻意保持"薄":

设计哲学是"组合而非重复":路由器不复制任何技能的内容,只是指向它们。它最常移交的三个技能是 n8n-mcp-tools-expert(工具使用)、n8n-workflow-patterns(架构设计)与 n8n-node-configuration(节点配置)。

激活方式

该技能在两种场景下激活:

  1. 作为 Claude Code / Codex 插件安装时:由插件的 SessionStart hook 在每个会话开始时自动加载(详见下文"加载机制源码深挖");
  2. 作为普通技能上传到 Claude.ai 等无 hook 环境时:只要用户提到 n8n、workflow、nodes、automation 等词,它就会按 description 自动触发匹配。

典型触发查询示例:

  • "Build me an n8n workflow that …"
  • "Which n8n skill should I use for …?"
  • "How do I edit a workflow with the n8n-mcp tools?"

版本与兼容性:README.md 标注版本为 1.0.0;兼容对象是 n8n-mcp MCP 服务器,而 hook 机制依赖 Claude Code / Codex 插件安装方式。


二、三条不可协商规则(Non-negotiables)

以下三条规则没有例外,每一条都对应着一类"看起来正确、到生产环境才炸"的失败模式。

规则 1:任何 n8n 动作之前,先调用匹配的技能

不是只在 MCP 调用前才想起技能,而是在写表达式、配置节点、设计工作流、接线、写 Code 之前,都必须先调用匹配的专家技能。需要特别警惕的是:PreToolUse hooks 确实会在最高影响的工具调用上提醒你,但这些 hooks 只存在于 Claude Code 插件安装中。

在其余所有环境——Claude.ai 技能上传、以及任何把本包作为 Agent Plugin 加载的客户端(Codex、Cursor、Copilot 等)——没有任何东西会提醒你,责任完全在自己。SKILL.md 给出的实操判据是:除非亲眼看到本会话里 hook 触发过,否则一律假设自己处于无 hook 状态。

规则 2:激活前必须"校验 + 验证"双保险

在激活(activate)之前运行 validate_workflow(或按 id 运行 n8n_validate_workflow);每次 create 或 update 之后调用 n8n_get_workflow 检查 connections 对象。原因在于:

  • 校验通过只代表 JSON 格式良好,不代表工作流正确;
  • 校验单独发现不了:被静默丢弃的连线(silently dropped wires)、Merge 索引 off-by-one、从未接线的 error outputs;
  • 绿色测试运行也不是证据:{{ }} 内的 JS 错误会静默解析为 null(一个条件写错的 Filter 会丢掉所有条目却仍显示成功),所以必须检查输出值本身。详见 skills/n8n-expression-syntax/。

仓库中的 validate-workflow PreToolUse hook(hooks/pre-tool-use/validate-workflow.sh)对此做了印证——它在校验前强制注入反模式扫描提醒,明确写到:"validate_workflow does not catch any of these; only the manual scan does"(校验捕获不了任何反模式,只有人工扫描能)。

规则 3:密钥永远不进文本字段

Token、API key、密码一律走 n8n 凭据系统(credential system)。如果没有原生节点可用,就使用 HTTP Request 节点搭配官方凭据类型。SKILL.md 给了一个生动的反例:

用 Set 节点持有 token 再通过 {{ $json.token }} 引用——这是"绕了更多弯的泄漏"。

详见 skills/n8n-mcp-tools-expert/。仓库中 hooks/pre-tool-use/manage-credentials.sh 也把凭据操作定位为"最高风险调用":凭据持有真实密钥,误路由写入会把密钥放到错误的实例上。


三、依靠技能与实时工具,而非训练数据

n8n 的变化速度超过任何模型的训练截止时间(cutoff)。工具名、参数、节点 typeVersion、默认行为都会在版本间漂移。SKILL.md 的核心主张是:

"记住"的参数名往往是静默错误的——它们作为普通字符串校验通过,然后在运行时什么都不做。

信任顺序被明确定义:

  1. 技能与实时工具(get_node、search_nodes、tools_documentation)优先于记忆;
  2. 如果技能与你的记忆矛盾,相信技能;
  3. 如果 get_node 与技能矛盾,相信工具并向用户报告漂移(missing tool、changed parameter、diverging behavior),同时建议更新技能包与实例。

四、强默认值(Strong defaults)

各专家技能拥有自己的例外,以下是路由器层面给出的默认纪律:

默认值 说明 关联技能
Code 节点是最后手段 优先表达式 → Edit Fields 内的箭头函数 → 两者都办不到才用 Code 节点 skills/n8n-code-javascript/
喂给 0~1 个消费者的 Set 节点几乎总是错的 应把表达式内联到消费者节点上 skills/n8n-expression-syntax/
逐条迭代是自动的 不要为了"让它循环"而添加 Loop Over Items 节点,默认的 per-item 执行已覆盖该场景 —
永远从实时 schema 配置,而不是凭记忆 设置参数之前先 get_node skills/n8n-node-configuration/

get-node 的 PreToolUse hook(hooks/pre-tool-use/get-node.sh)把这些默认值落实到了每次节点查询上:对 set、code、merge、splitInBatches(Loop Over Items)、dateTime、dataTable、nodes-langchain.agent 等高风险节点类型,它每次查询都会重新触发针对性警告(而非每会话一次),因为"重新查询某种高风险节点类型,几乎总是 Agent 在重新考虑另一个反模式实例"。


五、Red flags:当你冒出这些念头时 → 先调用对应技能

SKILL.md 提供了一张高频决策路由表。只要捕捉到自己正在想这些事,就停下来先调用指定的技能:

念头 应调用
"这个工作流很简单,我直接建就行" n8n-workflow-patterns —— 多数"简单"流程上线时都有 10+ 个节点
"我加个 Set 节点来映射这些字段" n8n-expression-syntax —— Set 喂 ≤1 个消费者是头号反模式
"直接用 Code 节点,更省事" n8n-code-javascript —— 门槛很高;多数需求用表达式或 Edit Fields 即可
"用户提到了数据,我写 Python" n8n-code-javascript —— 默认 JS;Python(n8n-code-python)只在用户明确要求时使用
"我要写一个供 AI 代理调用的代码" n8n-code-tool —— 与 Code 节点是完全不同的运行时契约
"日期计算——我放个 DateTime 节点" n8n-expression-syntax —— 内联 Luxon 几乎总是对的
"我要用 3 个来源接 Merge" n8n-node-configuration —— Merge 默认只有 2 个输入,第 3 个会静默丢失
"校验通过了,我准备激活" n8n-validation-expert + n8n-workflow-patterns —— 先跑反模式扫描
"校验报了个看不懂的错误" n8n-validation-expert —— 每条错误/警告的含义,哪些必须修、哪些只是最佳实践建议
"我在这里引用 $json.x" n8n-expression-syntax —— 分支型工作流优先 $('Node').item.json.x
"这个 webhook/定时流程只走 happy-path" n8n-error-handling —— 每个易失败节点都要接错误分支;4xx 是调用方过错,5xx 是你的过错
"我把这个文件/图片当 JSON 传过去" n8n-binary-and-data —— 文件内容在 $binary 里,无法跨过 agent-tool 边界
"我接一个 AI Agent 并给模型一些工具" n8n-agents —— 工具名与描述本身就是 prompt;memory、结构化输出、拓扑都有陷阱
"我要把这套逻辑复制到另一个工作流" / "这个变大了" n8n-subworkflows —— 抽取可复用的子工作流;构建前先搜索
"我来创建那个凭据 / 打开那个工作流"(账号有多个实例) n8n-multi-instance —— 每次调用都会命中当前指向的实例;读操作会静默错路,歧义凭据写入以 INSTANCE_AMBIGUOUS 失败关闭

六、技能索引:谁拥有什么任务

技能 何时使用
using-n8n-mcp-skills 本路由器(自动加载)。指出哪项技能拥有当前任务
n8n-mcp-tools-expert 选择或调用任何 n8n-mcp 工具;节点发现;凭据;数据表;安全审计;模板
n8n-workflow-patterns 设计或构建工作流;挑选架构(webhook / HTTP API / 数据库 / AI agent / 定时 / 批处理)
n8n-node-configuration 配置任意节点;按操作区分的必填字段;属性依赖;外科手术式字段编辑
n8n-expression-syntax 写 {{ }}、$json/$node/$now;节点间数据映射;转换门卫;Set 节点纪律
n8n-validation-expert 解读校验错误/警告;误报;校验循环;自动修复;评审既有工作流
n8n-code-javascript 任意 JavaScript Code 节点;数据访问;this.helpers;DateTime;SplitInBatches 循环模式
n8n-code-python 用户明确要求 Python 的 Code 节点;原生运行时(只有 _items/_item,默认封锁导入,旧式 _input 代码会失败)
n8n-code-tool 可被 AI 代理调用的自定义代码工具(toolCode)——返回字符串,没有 $fromAI/$input
n8n-error-handling webhook/API 或无人值守工作流;接线错误输出;重试;4xx/5xx 响应形态;静默失败
n8n-binary-and-data 文件、图片、PDF、附件、上传/下载、视觉;把文件传给/取回 agent 工具
n8n-subworkflows 可复用 / 多步骤构建;Execute Workflow;抽取共享逻辑;Define-Below 输入;all-vs-each;把工作流暴露为 agent 工具
n8n-agents AI Agent / LLM-with-tools / Text Classifier;工具设计与 $fromAI;系统提示词;结构化输出;记忆;RAG;人工评审;聊天机器人
n8n-multi-instance 拥有多个实例的账号(存在 n8n_instances 工具时);切换目标实例;凭据写入前验证;从意外的 NOT_FOUND、错误/空读取、INSTANCE_AMBIGUOUS 凭据写入失败关闭中恢复
n8n-self-hosting 部署而非构建工作流 —— 在 VM 上自托管/安装/部署 n8n(Docker Compose + Caddy,单机 vs 队列模式),或升级/备份/加固。它自行触发,不属于上述构建流程

七、n8n-mcp 工具全景:从第一回合就具备可用知识

技能包把"工具完整描述要等首次使用才加载"的空白,用一份紧凑清单填补掉。限定名形如 mcp__<server>__<tool>(<server> 通常为 n8n-mcp)。

两个层级:如何判断你手里是哪一个

  • 文档与校验类工具(tools_documentation、search_nodes、get_node、validate_node、search_templates/get_template)离线可用、始终存在;
  • n8n_* 管理类工具需要连接一个活的 n8n 实例,只有连上了才会出现。

如果管理类工具缺失,说明没坏、也没有可重试的东西——直说即可,并引导用户按其安装方式修复:

部署方式 连接方式
托管版(https://api.n8n-mcp.com/mcp) 首次使用时通过客户端弹出的 OAuth 提示登录,然后在 dashboard 中连接 n8n 实例。无需环境变量,也无需把 API key 粘贴进配置文件(mcp.json 中登记的正是这个 streamable-http 端点)
自托管版(npx n8n-mcp、Docker) 服务器环境需要 N8N_API_URL 和 N8N_API_KEY,在客户端启动前导出

n8n_health_check 用于确认连接有效,并返回已解析的实例信息。

发现与文档

  • tools_documentation —— 每个工具的元文档;{topic:"ai_agents_guide", depth:"full"} 可获取 Agent 指南;
  • search_nodes —— 按关键词查找节点;
  • get_node —— 节点信息。接受单个 SHORT 形式 的 nodeType(如 nodes-base.httpRequest、nodes-langchain.agent),另有 detail(minimal/standard/full)与 mode(info/docs/search_properties/versions)参数;
  • validate_node —— 隔离校验单个节点的配置(profiles:minimal/runtime/ai-friendly/strict);
  • search_templates / get_template —— 模板库(按关键词、节点、任务、元数据)。

构建与编辑

  • n8n_create_workflow —— 用完整工作流 JSON 创建;
  • n8n_update_partial_workflow —— 增量 diff 操作({id, operations:[…]}):addNode、updateNode、patchNodeField、addConnection、setNodeGroups、activateWorkflow 等。编辑首选;
  • 画布分组(n8n 2.28+):编辑时无需管理也能存活——被删除的分组节点会从组内剪除,n8n 不再接受的组会被解组以保证编辑落地——节点与连线不受影响,每次调整都会在 details.warnings 中报告。创建或修改分组使用 setNodeGroups 操作(整体替换;[] 表示全部解组)。详见 skills/n8n-mcp-tools-expert/;
  • n8n_update_full_workflow —— 整体替换;
  • n8n_autofix_workflow —— 自动修复常见问题;
  • n8n_deploy_template —— 把模板部署到实例。

校验(必要但不充分——务必搭配反模式扫描)

  • validate_workflow —— 传入完整 JSON,输出 errors/warnings/fixes。此处的节点类型是 LONG 形式(n8n-nodes-base.set);
  • n8n_validate_workflow —— 按 {id} 校验已部署的工作流(无节点 JSON 可查)。

检查与生命周期

  • n8n_get_workflow —— 获取工作流(full / structure / active / filtered / minimal)。编辑后用 mode="filtered" + nodeNames 只读取单个重量级节点(如很长的 Code 源码),避免拉取整个工作流导致客户端侧截断;
  • n8n_list_workflows —— 列表/筛选(复制逻辑前先搜索);
  • n8n_delete_workflow、n8n_workflow_versions(历史/回滚/差异;source: "local" 是 n8n-mcp 自己的快照,source: "native" 是 n8n 自身历史,含用户在 UI 里的编辑)、n8n_instances(仅多实例账号:列出/切换目标实例,见 skills/n8n-multi-instance/)、n8n_health_check(返回解析后的 instanceName,外加 officialMcp 块说明实例级 MCP 服务器是否已配置且可达)。

测试与运行

  • n8n_test_workflow —— 运行真实节点(Code、HTTP、DB 写入、发送都会真实触发)。存在副作用时先询问用户。method 选择路径:auto(默认)和 trigger 通过 HTTP 触发已激活工作流上的 webhook/form/chat 触发器;prepare/pinned/direct 经由 n8n 自身的 MCP 服务器,可运行完全没有 HTTP 触发器的工作流(Manual、Schedule、子工作流)。详见 skills/n8n-mcp-tools-expert/;
  • n8n_executions —— 列出/检查执行记录。注意:没有 execute_workflow 这个工具;
  • n8n_evaluations —— 评估测试运行:列出运行、聚合指标、逐用例结果(n8n ≥ 2.30),以及 run/cancel(n8n ≥ 2.32)。run 会针对整个数据集执行工作流——真实节点会触发,所以要先问用户。出现 403 可能意味着:API key 创建早于该动作的最低版本(需为 testRun 作用域重新创建)、当前套餐不含 evaluations 授权、或 key 所有者没有该工作流访问权限——对 run/cancel 而言,具体是 workflow:execute 作用域。

数据、文件夹、凭据、审计

  • n8n_manage_datatable —— 数据表 CRUD、过滤、dry-run。addColumn/deleteColumn/renameColumn 能修改既有表的列(Public API 做不到),通过 n8n 的 MCP 服务器完成——deleteColumn 会连同列的值一并删除;
  • n8n_manage_folders —— 工作流文件夹 CRUD,带内容计数(n8n ≥ 2.19、已注册 Community 及以上套餐;projectId 默认 personal)。通过 n8n_create_workflow 上的 parentFolderId 或 moveToFolder 操作(n8n ≥ 2.32)放置工作流。放置是只写的——要通过文件夹的 get 计数验证,绝不能靠读工作流。不带 transferToFolderId 的 delete 会把该文件夹的工作流移到项目根并 ARCHIVE(归档)——它们仍然存在,但被停用(transferToFolderId: "0" = 转移到项目根而不归档);
  • n8n_manage_credentials —— 凭据 CRUD + getSchema 发现;
  • n8n_audit_instance —— 安全审计(硬编码密钥、未认证 webhook、错误处理缺口)。

实例级 MCP 服务器

这是与 Public API 并行的第二个端点,由 N8N_MCP_ACCESS_TOKEN 门控(n8n 2.34+)。n8n_health_check 会报告其是否可达;没有它时,这些调用会以 NOT_CONFIGURED 应答,而不是含糊地失败:

  • n8n_manage_agents —— 持久化的 n8n Agents:拥有独立生命周期的独立助手构件(模型、指令、技能、任务、记忆、渠道),不是 AI Agent 工作流节点。call 会用真实凭据实时运行它,可能返回 approvals<a href="https://link.gitcode.com/i/00a84c0a117028d0f3579f167b6fd511" target="_blank">];只有用户要求时才 publish。见 [skills/n8n-agents/;
  • n8n_explore_node_resources —— 用真实凭据解析节点的实时下拉框/资源定位器值,而不是猜 ID。见 skills/n8n-node-configuration/;
  • n8n_list_catalog —— 列出 projects(获取 projectId)或 tags。它是这里唯一没有 token 也能工作的工具;
  • 同一服务器还支撑 n8n_test_workflow 的 prepare/pinned/direct、n8n_workflow_versions 的 source: "native"、以及 n8n_manage_datatable 的列操作。这些还要额外受每个工作流"Available in MCP"设置门控;被拒绝时读取 WORKFLOW_NOT_EXPOSED,而打开该设置(exposeToMcp: true)是可见的持久变更——先问用户。

节点类型形式的陷阱

Node-type form trap(节点类型形式陷阱):get_node / validate_node 接受 SHORT 形式(nodes-base.set);而 validate_workflow / n8n_create_workflow 内部的工作流 JSON 使用 LONG 形式(n8n-nodes-base.set)。混用二者是常见且静默的错误——详见 skills/n8n-mcp-tools-expert/。

仓库源码也印证了这一点:get-node hook(hooks/pre-tool-use/get-node.sh)注释明确写到,n8n-mcp 的 get_node 接受单个 SHORT 形式的节点类型,如 nodes-base.set 或 nodes-langchain.agent,位于 .tool_input.nodeType(而非官方 get_node_types 的数组形式),其锚定正则即匹配短形式。


八、按序执行的工作协议(The protocol, in order)

SKILL.md 给出了每次任务的标准操作顺序:

  1. 从索引识别匹配的技能,并在第一次 MCP 调用之前调用它;
  2. 每会话粗略扫一遍 tools_documentation 刷新工具面(如果不确定);
  3. 配置任何节点之前 get_node——读实时 schema,不要假设;
  4. 构建 / 编辑,然后激活前 validate_workflow、激活后 n8n_get_workflow 检查 connections;
  5. 汇报你注意到的任何漂移(工具缺失、参数变化、行为偏离)。

这一协议在仓库的 hook 链中被逐层落实:create-workflow hook(hooks/pre-tool-use/create-workflow.sh)在 JSON 落地前强制架构/命名/复用决策;update-workflow hook(hooks/pre-tool-use/update-workflow.sh)在更新前提醒校验 connections——因为"连接处藏着最微妙的 bug(静默丢弃的连线、Merge 索引 off-by-one)";validate-workflow hook 在 validate_workflow/n8n_validate_workflow 之前强制反模式扫描;test-workflow hook(hooks/pre-tool-use/test-workflow.sh)在 n8n_test_workflow 之前提示错误分支是否接好,并要求有副作用时先问用户、跑完告诉用户哪些节点真实执行了。


九、When in doubt:拿不准时的兜底决策

  • 找不到用户在 UI 里建的工作流? 最常见原因是该工作流按工作流的 MCP 访问开关没开。让用户在 n8n 中打开它,进入 Settings 并启用 MCP access;
  • 用户说它坏了? 相信用户。对照 get_node 重新检查参数、追踪数据引用、检查执行记录。见 skills/n8n-validation-expert/;
  • 没有技能匹配且任务不平凡? 先问,再猜。

SKILL.md 的收尾声明也值得注意:"These are opinionated best practices, not laws. Disagree with a call? It's all markdown — edit the skill."(这是有主见的最佳实践,不是法律。不同意某个判断?全是 markdown——改掉它。当然,在当前只读仓库上下文中,你的修改应落到你自己的技能包副本中。)


十、加载机制源码深挖:路由器如何进入每个会话

路由器技能由插件的 SessionStart hook 注入。相关源码可逐一核对:

hooks.json:事件与匹配器

hooks/hooks.json 声明了三类 hook:

  • SessionStart:匹配器为 startup|resume|clear|compact,执行 hooks/session-start.sh——这正是路由器技能在每个会话(以及恢复、清空、压缩后)被重新注入的入口;
  • PreToolUse:分别针对 get_node、n8n_create_workflow、n8n_update_partial_workflow/n8n_update_full_workflow、validate_workflow/n8n_validate_workflow、n8n_test_workflow、n8n_instances、n8n_manage_credentials 七个匹配器挂载提醒脚本;
  • PostToolUse:针对 validate_workflow 挂载校验后置脚本(hooks/post-tool-use/validate-workflow.sh)。

session-start.sh:additionalContext 注入

hooks/session-start.sh 的实现细节:

  1. 通过 ${CLAUDE_PLUGIN_ROOT:-...} 定位插件根目录,读取 skills/using-n8n-mcp-skills/SKILL.md;
  2. 在 clear / compact 时,额外清除本会话的 PreToolUse marker 文件——因为清空/压缩后 Agent 已经丢失了此前 hook 注入的 additionalContext,若不重置 marker,剩下的会话里按节点类型的警告会一直保持静默;
  3. 把 SKILL.md 正文作为 additionalContext 注入,使协议在压缩(compaction)后依然存活;
  4. 失败设计是 fail-open:文件缺失或不可读时直接 exit 0,绝不让 hook 阻塞会话启动;JSON 编码优先用 jq,缺失时回退 python3,两者都无则跳过注入而非输出畸形 JSON。

_emit.sh:一次性的 PreToolUse 提醒

hooks/pre-tool-use/_emit.sh 是所有 PreToolUse 提醒的共享助手:读取 stdin 的 JSON 获取 session_id,用 TMPDIR/n8n-mcp-skills-state/<session_id>-<marker>.loaded 做每会话去重(marker 先落盘,避免编码失败导致重复触发),再注入约 25 token 的紧凑提醒。所有 PreToolUse 脚本(如 hooks/pre-tool-use/create-workflow.sh、hooks/pre-tool-use/validate-workflow.sh)都以 exec .../_emit.sh <marker> <text> 方式委托给它。

安装视角:plugin.json 与 mcp.json

  • plugin.json 定义插件元数据:n8n-mcp-skills,版本 1.35.0,关键词覆盖 n8n / workflow / automation / mcp / validation / expressions / code / javascript / python,采用 MIT 许可;
  • mcp.json 登记 MCP 服务器:n8n-mcp,类型 streamable-http,URL 指向 https://api.n8n-mcp.com/mcp(托管端点)。

若 SKILL.md 文件缺失或 hook 不可用,会话照常进行,技能仍会按 description 触发——这正是"无 hook 环境靠 description 激活"设计的源码保证。


结语

using-n8n-mcp-skills 是整个 n8n-skills 技能包的入口与守卫:它用一张路由表把"正在做什么"映射到"该读哪项专家技能",用三条不可协商规则与一组强默认值拦截生产环境中会静默爆发的反模式,并用一份完整工具清单让 Agent 从会话第一回合就具备对 n8n-mcp 工具面的正确认知。配合仓库中 hooks/hooks.json 与各 hook 脚本实现的自动注入与实时提醒,路由器在插件环境里近乎"隐形地"工作;而在 Claude.ai 等无 hook 环境,它退化为纯描述触发,责任完全交给使用者——先选路,再让专家技能干活,永远信任实时工具超过记忆,这就是它教给你的核心方法论。

登录后查看全文
n8n-skills