n8n-architect

n8n 架构师

所有 n8n-as-code 工作都使用此技能：工作区就绪检查、环境管理、本地托管实例、隧道、工作流编写、验证、同步、推送和拉取。

优先使用 npx --yes n8nac 作为主要接口。仅在 n8n-manager 明确提供相关命令时，才使用 npx --yes @n8n-as-code/n8n-manager 执行本地托管运行时生命周期管理、隧道和工作流展示命令。

上下文根目录协议

• 将当前上下文根目录视为包含 n8nac-config.json、AGENTS.md、.agents/skills 和已配置 workflowsPath 的目录。
• 生成的上下文根目录提示：未嵌入。使用启动 shell 时所在的目录，或用户明确指定的工作区路径。
• 进行任何 n8n 工作之前，先从上下文根目录运行 npx --yes n8nac update-ai，然后读取 AGENTS.md。update-ai 旨在创建或刷新 n8n-as-code 区块，同时不破坏现有的用户或 Agent 指令。
• 使用 AGENTS.md 中列出的确切 n8nac command 和 n8n-manager command。这些上下文根目录命令优先于本技能中的通用示例。
• 除非用户明确指定其他上下文根目录，否则所有 npx --yes n8nac env ...、npx --yes n8nac workspace ...、npx --yes n8nac list、pull、push、validate、test 和 update-ai 命令都必须从上下文根目录运行。
• AGENTS.md 仅用于引导初始化，不是配置事实来源。
• 不要根据 AGENTS.md 推断环境、项目或 workflowsPath。
• 进行 n8n 工作之前，先从后端解析有效上下文：

npx --yes n8nac env status --json

• 使用返回的 workflowsPath 存放工作流文件。这是当前环境配置的工作流目录。
• 不要根据环境名称或 ID、instanceIdentifier、instanceUserIdentifier、projectId、projectName 或旧版同步字段重新构造 workflowsPath。
• 绝不要手动写入 n8nac-config.json、~/.n8n-manager 或 n8n-manager 密钥文件。

工作区就绪状态

进行工作流相关工作之前，先通过后端解析有效环境：

npx --yes n8nac env status --json

• 将 env status --json 视为有效工作区就绪状态的事实来源。
• 不要根据原始文件、生成的 Agent 文档或目录名称推断就绪状态。
• 首次使用时，如果工作区 .env 中含有 N8N_HOST（以及 N8N_API_KEY、N8N_NATIVE_MCP_URL、N8N_NATIVE_MCP_TOKEN 中的任意项），则会配置 default 环境：此时 env status --json 会直接解析成功，无需运行 env add、env auth set、env use 或 native-mcp configure。
• 如果 env status --json 因工作区尚未配置而失败，请使用 env add、env auth set 和 env use 创建或选择一个 V4 工作区环境。
• 本地托管实例仍是机器级的运行时资源。
• 工作区环境仍限定于工作区范围内，并通过 npx --yes n8nac env ... 管理。

初始化顺序

1. cd 到上下文根目录。
2. 运行 npx --yes n8nac update-ai，然后读取 AGENTS.md。
3. 运行 npx --yes n8nac env status --json。如果解析结果为 accessStatus: "ready"，则工作区已就绪——跳过第 4-9 步。如果解析结果为 missing-api-key 或 invalid-api-key，则仅表示缺少凭据：转到第 7 步。
4. 如果上下文根目录尚未就绪，请使用 npx --yes @n8n-as-code/n8n-manager instance list 检查本地托管实例。
5. 在适用时，复用现有环境或本地托管实例。
6. 如果没有合适的环境，请停止并询问用户是否要连接远程 n8n URL，或创建/复用本地托管 n8n 实例。默认不要创建基础设施。如果用户选择本地托管实例，请另外询问他们是否需要公共隧道。
7. 仅当明确选择远程 n8n 环境时，才询问主机地址/API 密钥。
8. 使用以下命令配置环境：

npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

对于本地托管实例：

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

9. 更改环境后，如果 facade 未自动执行，请运行 npx --yes n8nac update-ai。

环境

使用 npx --yes n8nac env ... 管理工作区环境、远程 URL、当前活动环境、API 密钥绑定、项目和工作流路径。

npx --yes n8nac env status --json
npx --yes n8nac env list
npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

• API 密钥优先使用 --api-key-stdin。
• 创建并固定默认环境时，优先使用 env add --pin，在一个流程中完成，而不是另外运行 env use。
• 不要在 shell 参数中直接传递密钥。
• env auth set 会将密钥绑定到一个环境，因此多个环境可以共用一个基础 URL，每个环境各用一个密钥。每个环境运行一次；如果环境使用自己的密钥，env status --json 中的 apiKeySource 为 workspace-environment。
• 如果用户需要的是托管式本地 Docker 实例，不要询问主机地址或 API 密钥。
• 不要向用户显示 API 密钥或凭据密钥值。
• 如果不熟悉某个命令或标志，请运行 npx --yes n8nac env --help 或 npx --yes n8nac env <subcommand> --help。

使用 npx --yes n8nac env ... 将托管式本地实例连接到工作区：

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

托管式本地运行时

仅在管理本地托管实例的生命周期、隧道，以及属于本地运行时层的工作流展示命令时，使用 npx --yes @n8n-as-code/n8n-manager。

更改本地机器状态前，先检查现有的托管实例：

npx --yes @n8n-as-code/n8n-manager instance list
npx --yes @n8n-as-code/n8n-manager instance --help
npx --yes @n8n-as-code/n8n-manager config get

不要臆造 n8n-manager 子命令。不确定时，运行 npx --yes @n8n-as-code/n8n-manager <subcommand> --help。

如果尚未配置上下文根目录，且没有合适的现有实例，请停止并询问用户如何选择。默认情况下不要创建基础设施。

清楚地列出以下选项：

• 如果有可用的现有托管式本地实例，则使用该实例；
• 创建新的托管式本地 n8n 实例；
• 通过 npx --yes n8nac env 将远程 n8n URL 配置为工作区环境。

如果用户选择托管式本地 Docker 实例，请单独询问是否需要隧道：

• 不使用公共隧道：仅运行本地 n8n，适用于常规 UI/API 工作流操作；
• 使用公共隧道：通过公共 URL 暴露实例，适用于 Webhook/表单/聊天触发器和远程回调。

除非用户明确要求公共访问、测试 Webhook，或批准使用隧道，否则不要启用、刷新或启动公共隧道。如果不需要公共访问，请在不使用 --tunnel 的情况下创建/启动托管实例。

只有在用户明确选择相应选项后，才能运行以下命令。

不使用公共隧道的托管式本地实例：

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance list

使用公共隧道的托管式本地实例：

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>

实例和隧道操作针对各个托管式本地实例分别进行：

npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance stop <id>
npx --yes @n8n-as-code/n8n-manager instance remove <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>
npx --yes @n8n-as-code/n8n-manager tunnel stop <id>

• 除非用户明确要求进行破坏性删除，否则不要删除本地实例数据。
• 如果 Docker 不可用或守护进程已停止，请报告后端诊断信息并停止。不要循环重试。
• 如果命令反复失败，最多尝试两次，然后停止并说明后端诊断信息。

同步规范

• 读取或修改现有工作流前，先拉取。
• 每次修改后都要推送。
• 使用 list 查看工作流 ID、文件路径和同步状态。

npx --yes n8nac list
npx --yes n8nac pull <workflowId>
npx --yes n8nac push <path-to-workflow.workflow.ts> --verify

• push 需要完整的工作流文件路径，可以是绝对路径，也可以相对于上下文根目录。不要只传文件名。
• 在 n8n 2.x 上，推送已发布的工作流也会将其发布到生产环境——API 会在更新时重新发布。将每次对已发布工作流的推送都视为部署。如果用户想先在 n8n 中检查更改，请使用 push --draft：它会重新固定之前发布的版本，让生产环境继续运行当前版本。
• 对于新工作流，请在 env status --json 返回的 workflowsPath 中创建文件，然后使用 npx --yes n8nac list --local 确认。
• 如果 push 或 pull 报告冲突，请使用明确的冲突解决命令。不要盲目覆盖远程更改。
• pull 和冲突解决操作一次只针对一个工作流 ID。
• list 是可一次检查所有工作流的轻量级命令。
• 如果跳过 pull，之后的 push 可能会因远程内容已更改而被乐观并发控制拒绝。

冲突处理

如果 push 或 pull 报告冲突，请停止操作并检查冲突。选择预期方向后，再使用明确的冲突解决命令：

npx --yes n8nac resolve <workflowId> --mode keep-current
npx --yes n8nac resolve <workflowId> --mode keep-incoming

• keep-current 会强制推送本地版本。
• keep-incoming 会强制拉取远程版本。
• 切勿在不提示的情况下强制推送并覆盖远程更改。

先查架构再操作

切勿猜测 n8n 节点参数。

npx --yes n8nac skills examples search "<workflow pattern>"
npx --yes n8nac skills search "<node or capability>"
npx --yes n8nac skills node-info <nodeName>
npx --yes n8nac skills validate <workflow.workflow.ts>

• 批量查询节点：使用 npx --yes n8nac skills node-info <node1> <node2> ... --compact 在一条命令中查询多个节点，以便在快速且节省令牌的操作中检查必要属性、必填参数和有效选项。
• 使用 node-info 返回的准确节点 type 和有效的 typeVersion 值。
• 使用架构输出中的准确资源、操作、选项和参数名称。
• resourceLocator 类型的参数必须采用 { __rl: true, value: '...', mode: 'list' | 'id' | 'url' } 结构。
• 不要臆造参数、操作、凭据类型或 CLI 标志。
• 即使示例或记忆与架构输出不一致，也要将架构输出视为绝对依据。
• 优先使用架构输出返回的最高有效 typeVersion。
• 对于 Switch/If 规则、Wait 表单字段或嵌套选项等固定集合，写入值前请先阅读完整的 node-info 输出。

可选的原生 n8n MCP 辅助功能

n8n-as-code MCP 服务是 N8NAC 工具的客户端适配器。原生 n8n MCP 服务是单独的实时 n8n 实例端点。原生 n8n MCP 可以在原生知识、实时状态和运行时执行方面辅助此工作流，但不能替代 npx --yes n8nac、内置知识、.workflow.ts、Git 或同步规范。

请按以下路由策略操作：

• 默认使用本地 npx --yes n8nac 进行代码优先的工作流编写、验证、拉取、推送、凭据管理、执行历史查看和展示。将 npx --yes n8nac skills 用作内置离线知识的默认来源。
• 原生 MCP 辅助功能按 n8n-as-code 环境配置。创建或更新环境时，提供使用 npx --yes n8nac native-mcp configure <environment> --token-stdin 进行配置的选项；不要要求用户为 Claude Code 或 VS Code Workbench 手动配置单独的 MCP 服务。
• 如果已配置原生 MCP 辅助功能，可在与 n8n-as-code 相辅相成的场景中使用它：只读实时发现、服务端验证、原生 SDK/参考知识、实时节点定义、不含密钥的凭据元数据、执行检查、项目、文件夹，以及受支持时的明确运行时执行/测试策略。
• 依赖原生工具之前，先使用 npx --yes n8nac native-mcp status --include-tools --json 检查原生功能是否可用。
• 对于用户关于当前/实时 n8n 实例、现有远程工作流、此实例中可用的节点、凭据元数据、项目、文件夹、执行记录、偏差或重复项发现的请求，在检查状态后优先使用原生 MCP 只读工具。当原生 MCP 只读工具可用时，不要将本地 npx --yes n8nac list、fetch、verify 或内置 skills 作为获取这些实时审计事实的主要来源。
• 除非 MCP 传输已通过身份验证，且已明确设置 N8NAC_NATIVE_MCP_ALLOW_REMOTE=1，否则不要通过非回环 HTTP/SSE 传输暴露原生 MCP 辅助功能。
• 除非用户明确需要执行负载数据，且已设置 N8NAC_NATIVE_MCP_ALLOW_EXECUTION_DATA=1，否则不要使用 includeData=true 请求完整的实时执行负载。
• 如果执行策略是测试真实的 webhook、chat 或 form 触发器契约，优先使用 npx --yes n8nac test。
• 仅当生成的执行策略明确要求使用原生运行时执行，且它比 npx --yes n8nac test 更合适时，才优先使用原生运行时执行，例如按工作流 ID 执行、测试非 webhook 工作流、准备原生固定数据测试，或直接进行执行诊断。
• 将原生执行/测试视为会产生副作用的运行时操作，与 npx --yes n8nac test 一样；不要仅仅因为存在此工具就运行它。
• 除非用户明确请求直接原生 MCP 模式，且该工具受权限控制，否则不要使用原生 MCP 创建、更新、发布、取消发布、归档或破坏性数据表工具。
• 如果通过原生 MCP 直接模式创建或更改了工作流，请立即使用 npx --yes n8nac pull <workflowId> 将其拉回，以确保 .workflow.ts 文件和 Git 仍是事实来源。
• 如果原生 MCP 验证与本地验证结果不一致，请停止操作并报告差异，不要强行推送或直接更新。
• 切勿将原生 MCP 令牌放入项目文件、生成的文档、命令参数或回复中。

用例路由示例：

• 工作流的编写、编辑、拉取、推送、同步、凭据管理和持久化变更：使用本地 npx --yes n8nac 命令和 .workflow.ts 文件。
• 离线节点知识、示例、文档和以架构为先的编写：优先使用本地 npx --yes n8nac skills 命令。
• 实时工作流发现、漂移调查、项目、文件夹、凭据元数据、重复项发现和执行检查：已配置时优先使用原生 MCP 只读工具，因为用户询问的是当前实例状态。
• 已连接版本的节点定义或服务端验证：当用户询问此实例中有哪些内容，或需要针对已连接的 n8n 版本进行验证时，优先使用原生 MCP 只读工具。如果无需实时实例状态，则使用内置知识进行离线编写。
• 运行时执行：对于真实的 webhook、聊天或表单触发器契约，优先使用 npx --yes n8nac test；仅在明确要求按工作流 ID 执行、进行非 webhook 测试、准备原生固定数据或直接诊断执行问题时，才优先使用原生运行时执行。
• 直接创建、更新、发布、取消发布、归档原生工作流或执行破坏性操作：不要将其作为自动操作路径；必须获得明确的直接原生操作请求，并制定回同步计划。

不要将存在任何 MCP 服务视为可以调用原生 n8n MCP 工具的许可。只有在生成的执行或调查策略需要本地 N8NAC 同样无法提供的实时 n8n 功能时，才使用原生 n8n MCP。

原生 MCP 辅助是知识、实时状态和运行时增强的补充路径，而不是主要的编写或同步路径。

知识命令

如果你的运行时提供 n8n-as-code MCP 工具（search_n8n_knowledge、get_n8n_node_info、 search_n8n_workflow_examples、validate_n8n_workflow），请优先使用它们，而非以下命令。 它们通过常驻进程提供答案，该进程只解析一次本体，因此首次调用后的每次调用几乎不产生开销；而每条 shell 命令都需要重新启动进程。

否则，请使用以下命令，而不要猜测：

npx --yes n8nac skills search "<node or capability>"
npx --yes n8nac skills node-info <nodeName>
npx --yes n8nac skills node-schema <nodeName>
npx --yes n8nac skills docs "<topic>"
npx --yes n8nac skills guides "<topic>"
npx --yes n8nac skills examples search "<workflow pattern>"
npx --yes n8nac skills examples info <id>
npx --yes n8nac skills examples download <id>

• 在 search、node-info 和 node-schema 中优先使用 --compact：架构相同，输出有界（必需参数 + 代码片段 + 门控标志）。
• 优先使用一次 batch --compact，而不是分 N 次单独查询：一个进程只解析一次本体。传入 --calls '<json>'、--calls-file <path>（文件可避免 shell 引号转义），或通过标准输入传入 JSON。--compact 适用于 search、node-info、node-schema；examples-search 和 examples-info 始终返回完整工作流数据。示例：npx --yes n8nac skills batch --compact --calls '[{"cmd":"search","query":"gmail"},{"cmd":"node-info","name":"gmailTool"}]'。
• 一次查询多个节点时，node-info 和 node-schema 也支持直接接收多个名称：npx --yes n8nac skills node-info <node1> <node2> ... --compact。
• 当用户询问常见自动化模式时，从 examples search 开始。
• 只有在不知道如何连接某项内容、工作流异常复杂，或用户明确提出要求时，才获取社区示例。每次下载都需要完整的往返操作：对于常规任务，本地知识（search、node-info、batch）速度更快，且更具权威性。其他情况下跳过示例。
• 使用示例来了解模式，不要将其作为当前节点架构的权威依据。
• 如果不熟悉某条命令或标志，请运行 npx --yes n8nac <subcommand> --help；不要自行编造标志。

工作流编写规则

• 使用 @n8n-as-code/transformer 中的 TypeScript 装饰器。
• 常规节点通过 source.out(0).to(target.in(0)) 连接。
• AI 子节点通过 .uses() 连接，绝不要使用 .out().to()。
• ai_tool 和 ai_document 连接是数组：ai_tool: [this.Tool.output]。
• 其他 AI 连接类型是单个引用，例如 ai_languageModel: this.Model.output。
• 如果节点公开了多个相同类型的输入，也可以传入数组，其中位置就是输入索引：ai_languageModel: [this.Model.output, this.FallbackModel.output]（备用模型、Model Selector）。
• 声明 .uses() 连接前，请先查看 node-info，确认是否有依赖连接的布尔标志。

每个 .workflow.ts 文件都以 <workflow-map> 块开头。先阅读该映射，找到所需的属性名，然后只阅读相关的类部分。

最精简的工作流结构

import { workflow, node, links } from '@n8n-as-code/transformer';

@workflow({
  name: 'Workflow Name',
  active: false
})
export class MyWorkflow {
  @node({
    name: 'Descriptive Name',
    type: '/* exact type from node-info */',
    version: 4,
    position: [250, 300]
  })
  MyNode = {
    /* parameters from node-info */
  };

  @node({
    name: 'Next Node',
    type: '/* exact type from node-info */',
    version: 3,
    position: [520, 300]
  })
  NextNode = {};

  @links()
  defineRouting() {
    this.MyNode.out(0).to(this.NextNode.in(0));
  }
}

表达式语法

• 优先使用现代表达式：{{ $json.fieldName }}。
• 必要时使用特定节点表达式：{{ $('Node Name').item.json.field }}。
• 除非你是在保留现有工作流且有充分理由，否则避免使用旧版 $node["Name"].json.field。
• 在 Switch/If 比较中，value1 是要计算的表达式，value2 是字面比较值。

节点命名

• 使用描述性名称，例如 Get Customers、Send Slack Alert 或 Normalize Payload。
• 如果有更具体的名称，请避免使用 Node1、HTTP Request 或 Code 这类名称。
• 连接引用必须与 TypeScript 类中的节点属性名完全一致。

高效读取工作流文件

加载大型工作流文件前，请先将 <workflow-map> 块用作索引。

// <workflow-map>
// Workflow : My Workflow
// Nodes   : 12  |  Connections: 14
//
// NODE INDEX
// Property name                    Node type (short)         Flags
// ScheduleTrigger                  scheduleTrigger
// AgentGenerateApplication         agent                      [AI] [creds]
// OpenaiChatModel                  lmChatOpenAi               [creds] [ai_languageModel]
// Memory                           memoryBufferWindow         [ai_memory]
// GithubCheckBranchRef             httpRequest                [onError->out(1)]
//
// ROUTING MAP
// ScheduleTrigger
//   -> Configuration
//     -> BuildProfileSources -> LoopOverProfileSources
//
// AI CONNECTIONS
// AgentGenerateApplication.uses({ ai_languageModel: OpenaiChatModel, ai_memory: Memory })
// </workflow-map>

导航规则：

1. 先阅读 <workflow-map>。
2. 找到所需的属性名。
3. 在文件中搜索该属性。
4. 仅阅读相关节点或路由部分，除非需要更广泛的上下文。

AI 和 LangChain 节点规则

AI 子节点不是常规数据流节点。

@links()
defineRouting() {
  this.ChatTrigger.out(0).to(this.AiAgent.in(0));

  this.AiAgent.uses({
    ai_languageModel: this.OpenaiModel.output,
    ai_memory: this.Memory.output,
    ai_outputParser: this.OutputParser.output,
    ai_tool: [this.SearchTool.output],
  });
}

• 对语言模型、记忆、工具、解析器、嵌入、向量存储、检索器及其他 AI 子节点使用 .uses()。
• 绝不要通过 .out().to() 连接 AI 子节点。
• ai_tool 和 ai_document 必须是数组；每个条目都连接到输入索引 0。
• 大多数其他 AI 连接类型是单个引用；如果节点公开了多个相同类型的输入，也可以传入数组，其中位置 = 输入索引。
• needsFallback: true（Agent、Basic LLM Chain）需要在输入 1 上连接第二个模型：ai_languageModel: [this.Model.output, this.FallbackModel.output]。Model Selector 节点也一样。
• 某些节点需要布尔标志才能公开 AI 端口或受控参数。声明 .uses() 前，请先查看 node-info。

应避免的常见错误

• 节点类型错误：使用架构输出返回的完整类型，包括其中提供的包前缀。
• 使用过时或不存在的 typeVersion：使用架构输出中的值。
• 操作/资源值无效：使用架构中的准确选项值。
• 资源与操作不匹配：每种资源都有其对应的操作。
• 猜测嵌套结构：固定集合具有精确结构。
• 连接名称错误：与 TypeScript 属性名完全一致。
• 虚构节点、凭据、操作或参数。
• 使用 .out().to() 连接 AI 子节点。
• 使用 ai_tool: this.Tool.output，而不是 ai_tool: [this.Tool.output]。
• 颠倒 Switch/If 的 value1 和 value2。
• 使用旧版 Wait 表单结构，例如 formFieldsUi.fieldItems，而当前架构要求使用 formFields: { values: [...] }。
• 向 push 传入未经处理的文件名。
• 将 Class A 的运行时/配置缺失问题当作工作流代码错误。

验证、测试和展示

优先使用 push --verify：它会获取已推送的工作流，并在同一进程中对其进行验证。在 push --verify 后立即单独运行 verify 会重复检查相同状态，除非你在推送时没有使用 --verify，否则应跳过。

npx --yes n8nac push <path> --verify
npx --yes n8nac test-plan <workflowId> --json

对于 webhook、聊天或表单工作流，优先采用生产环境测试流程：

npx --yes n8nac workflow activate <workflowId>
npx --yes n8nac test <workflowId> --prod

• A 类配置缺失需要用户／配置操作，而不是重写工作流。
• 未启用测试 webhook 等运行时状态问题，并非工作流代码错误。
• B 类接线错误可在工作流文件中修复。
• 同一诊断信息重复出现两次后，即停止尝试。

工作流展示规范

npx --yes n8nac workflow present 是向用户展示工作流的标准方式。它支持 v4 环境，并且是工作流编写循环的一部分。

符合以下任一条件时，都要运行此命令：

• 你创建了工作流；
• 你修改并推送了工作流；
• 你运行或测试了工作流，且用户需要查看它；
• 用户要求展示、打开、呈现、显示工作流，或提供工作流的 URL／链接。

npx --yes n8nac workflow present <workflowId> --json

规则：

• 不要手动构造 n8n 工作流 URL。
• 如果有可用于展示的 URL，不要向用户返回内部本地 n8n URL。
• 将 workflow present --json 返回的 url 用作面向用户的 URL。
• 如果不知道工作流 ID，先运行 npx --yes n8nac list，然后选择匹配的工作流。
• 不要调用 npx --yes @n8n-as-code/n8n-manager presentWorkflowResult；这是旧版运行时命令，且不支持工作区环境。
• 如果 workflow present 失败，请报告后端诊断信息，然后仅在备用情况下提供最合适的直接 n8n URL。
• 如果任务创建、修改、推送或运行了工作流，或明确要求展示工作流，请在最终回复前执行此操作。

可测试性协议

对于 webhook、聊天或表单工作流：

1. 尽可能在推送时进行验证。
2. 运行 test-plan，检查触发器类型、端点和建议的负载。
3. 激活工作流。
4. 默认使用 --prod 进行测试。

npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
npx --yes n8nac test-plan <workflowId> --json
npx --yes n8nac workflow activate <workflowId>
npx --yes n8nac test <workflowId> --prod

仅当你有意在 n8n 编辑器中启用了测试 URL 时，才使用不带参数的 npx --yes n8nac test <workflowId>。

对于从 $json.query 读取数据的 GET／HEAD webhook，优先使用：

npx --yes n8nac test <workflowId> --query '{"key":"value"}' --prod

执行调试

如果 webhook 返回成功，但工作流行为不正确，请检查执行记录，而不要猜测：

npx --yes n8nac execution list --workflow-id <workflowId> --limit 5 --json
npx --yes n8nac execution get <executionId> --include-data --json

• HTTP 触发器成功仅表示 n8n 已接受请求。
• 执行仍可能在工作流后续环节中失败。
• 使用执行数据确定出错的节点和实际负载结构。

凭据工作流

如果工作流因缺少凭据而受阻，应解决凭据缺失问题，不要重写无关的工作流逻辑。

npx --yes n8nac workflow credential-required <workflowId> --json
npx --yes n8nac credential schema <type>
npx --yes n8nac credential list --json
npx --yes n8nac credential create --type <type> --name <name> --file cred.json --json
npx --yes n8nac workflow activate <workflowId>

• 如果至少缺少一个凭据，workflow credential-required 会以非零状态退出。应将其视为需要采取行动的信号，而不是工作流代码故障。
• 使用 credential schema 查找必需字段。
• 必要时向用户索要机密值。
• 创建凭据时优先使用 --file。不要在 shell 参数中直接传递机密。
• 不要向用户输出 API 密钥或凭据机密值。
• 如果创建凭据失败，请阅读验证消息，并在重试前修改负载。

操作流程

对于大多数工作流任务：

1. 使用 env status --json 解析上下文。
2. 从后端响应中读取 workflowsPath。
3. 使用 list 检查现有工作流。
4. 编辑现有工作流前先拉取。
5. 搜索示例和架构。
6. 编辑或创建 .workflow.ts 文件。
7. 在本地验证。
8. 使用 --verify 推送。
9. 如果工作流由 HTTP 触发，则进行测试。
10. 如果行为不明确，则检查执行记录。
11. 使用 npx --yes n8nac workflow present <workflowId> --json 展示最终工作流链接。

响应规范

• 说明具体操作和命令结果，不要泛泛而谈能力。
• 当用户询问 URL 或要求直观检查工作流时，运行 npx --yes n8nac workflow present <workflowId> --json，不要手动拼接 URL。
• 如果缺少设置，请对工作区环境使用 n8nac env ...，仅对受管理的本地实例使用 n8n-manager。
• 除非用户选择远程 n8n 环境，否则不要询问主机或 API 密钥。
• 如果你可以自行运行非交互式命令，就不要让用户运行设置命令。
• 使用相同诊断信息重复失败两次后，请停止并清楚说明后端错误。