构建带人工审批与测试验证的 n8n 代码变更工作流

工作流概览

使用 n8n 让 AI agent 提出代码仓库变更，但将写入操作置于人工审批之后。写入获批后，针对生成的确切提交运行测试并报告结果。合并或部署应作为单独的决策。

关键区别在于工具审批与输出审批。在 n8n 中，人工审核步骤可以在 AI Agent 执行选定工具之前暂停流程。审核人员可以看到拟调用的工具及其参数；批准后会执行该调用，拒绝则会取消调用并通知 agent。这一行为记录在 n8n 人工参与工具调用指南中。

OneMux 通过一个 OpenAI 兼容 API 提供 AI 模型访问。它是这一设计中可选的模型访问途径，并非已验证的 n8n 集成方案。请参照 OneMux API 文档，根据计划使用的端点和参数检查 n8n 节点配置。

构建前需要准备什么

• 一个配有 AI Agent、合适的聊天模型连接，并可访问 Slack 或 n8n Chat 等人工审核渠道的 n8n 实例。
• 一个代码仓库集成或自定义服务，能够读取指定修订版本并将补丁应用到非生产分支。其写入凭据应仅拥有操作该仓库和分支所需的权限。
• 一个与生产凭据和生产系统隔离的测试运行环境。它必须接受确切的提交标识符，并返回状态以及指向结果的链接或引用。
• 如果选择 OneMux 调用模型，需要 OneMux 账户和 API 访问权限。有关当前连接详情，请查阅快速入门；选择可用模型时，请查阅模型目录。
• 一个测试命令已知、默认分支受保护的代码仓库，以及一名有权审核拟议变更的人员。

这是一种实现模式，而不是可直接导入的工作流。代码仓库工具、运行环境集成、模型选择和具体的 n8n 字段取决于你的环境。尤其要注意，所提供的文档并未证明某个特定 OneMux 模型支持 n8n AI Agent 所需的工具调用行为。依赖这一设计前，请先验证相关支持情况。

围绕确切修订版本设计工作流

一个实用的流程如下：

1. 接收请求。 从可信的工作流配置中获取代码仓库、问题描述、目标工作分支、基础提交和允许执行的测试命令。
2. 读取并提出变更。 让 agent 检查基础提交中的相关文件并准备补丁。读取权限不应允许修改代码仓库。
3. 审核写入。 将补丁应用工具接入 n8n 人工审核流程，由审核人员批准或拒绝拟议的工具调用。
4. 应用并确定提交。 获批后，写入服务检查分支是否仍指向已获批的基础提交，应用已获批的补丁，并返回新的 commit ID。如果基础提交发生变化，应按默认拒绝原则终止操作，并请求重新提出方案和审批。
5. 验证。 在隔离的运行环境中针对这个确切的新提交运行配置好的测试，记录命令、提交、状态和结果引用。
6. 报告。 将提交和测试结果发送给审核人员与请求人。测试失败、取消或结果缺失都不算通过。

这些是建议采取的控制措施，并非 n8n 人工审核步骤保证提供的功能。特别是，代码仓库服务必须强制执行基础提交检查，并确保实际应用的补丁就是已获批的补丁。

配置模型连接

在 n8n 中，选择支持配置 OpenAI 兼容端点并且支持 AI Agent 所需工具调用行为的聊天模型配置。使用当前 OneMux 文档中指定的端点、身份验证方式和模型标识符。将凭据存储在 n8n 的凭据系统中，而不是放在提示词或工作流消息里。

接入代码仓库访问权限之前，先发送一个小型测试请求，检查响应是否符合 n8n 节点预期的格式，然后测试一次无害的工具调用。OpenAI 兼容并不意味着所有端点、参数或工具调用格式都可以互换：这里的兼容性取决于双方是否都支持所需的请求和响应。本文未测试这一配置。

如果可用的模型连接无法支持 agent 的工具调用，不要通过向模型提供直接写入凭据来绕过审批。应使用兼容的配置，或构建一个独立且经过明确审核的流程，将操作交给写入服务。

为代码仓库写入设置人工审批关卡

在 AI Agent 节点中，打开 Tools 连接器，在 Tools Panel 中找到 Human review。选择审批渠道并配置其凭据。将代码仓库写入工具连接到审核步骤的工具连接器。在适当情况下，将只读工具单独设置；其他可能改变外部状态的工具，也应分别置于审核或同等控制措施之后。

n8n 文档指出，审核人员可以收到工具名称和 AI 提供的参数。例如，可以使用以下内容配置审核消息：

Proposed tool: {{ $tool.name }}
Proposed parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

选择一个写入工具，使其可审核的输入包含代码仓库、分支、基础提交和完整补丁，或者包含带摘要的不可变补丁引用。如果补丁对该渠道而言过大，应提供安全且可访问的审核位置，并验证写入服务应用的是相同内容。“修复测试”这类含糊的指令不足以作为批准特定代码仓库变更的依据。

文档中列出的 $tool.parameters 值包括使用 $fromAI() 表达式配置的字段；不要假设消息会展示所有固定凭据、隐藏配置值或下游影响。应限制固定设置，并为审核人员提供单独的检查方式。避免在工具参数中放入密钥等机密信息，因为参数可能出现在审批消息中。

添加一条系统指令，指明受审批控制的工具，并告知 agent 在请求被拒绝时如何处理。例如：

Repository writes require human approval. Propose a patch against the
specified base commit and request the write tool only for that patch.
If approval is denied, do not retry the write or use another tool to make
the change. Tell the requester it was denied and ask for clarification.
Report test results only when supplied by the test runner.

这条指令有助于 agent 处理审核，但它不是安全边界。权限和分支限制应在提示词之外强制执行。

验证已获批的变更

仅在写入服务返回 commit ID 后才触发测试运行环境。配置运行环境检出该 ID，而不是分支最新的 head，并执行团队定义的允许列表中的命令。对于维护人员选择使用该命令的代码仓库，示例命令可以是：

npm test

该命令仅作示例；请使用项目实际的测试说明。将代码仓库中的代码、依赖安装脚本和测试输出都视为不可信内容。运行时应限制网络和文件系统访问，不提供生产环境机密，并设置时间和资源限制。测试套件通过只能说明所选检查在该环境中通过，并不能证明变更安全或正确。

返回简明结果，包含已获批的基础提交、新提交、测试命令、通过或失败状态，以及日志链接。如果测试失败，agent 可以提出修订后的补丁，但再次写入需要单独审批。不要因为审核人员批准了先前的工具调用就自动合并。

故障排查与操作限制

审批请求缺少有用的上下文

检查哪些输入由 AI 提供，以及哪些输入在 $tool.parameters 中可见。将补丁标识、分支和基础修订版本放入可审核的工具输入，或提供安全、不可变的审核材料。如果审核人员无法确定具体的写入内容，应拒绝该请求。

Agent 无法调用工具

首先独立于代码仓库权限测试一个无害工具。对照当前文档检查 n8n 节点、OneMux 端点、所选模型及所需的工具调用参数。所提供的来源未验证特定模型与节点的组合。

分支已变动或测试未完成

如果写入所依据的基础版本已过期，应拒绝写入，不要将补丁应用到不同的基础版本上。遇到超时、运行环境错误或日志缺失时，应报告验证未完成。在适当情况下，可针对同一提交重新运行测试；如果拟议写入发生变化，则需要重新审批。

结论

这里的关键边界很明确：由人工批准一次特定的代码仓库写入，再由隔离的运行环境验证生成的提交。n8n 提供文档中描述的工具级暂停和审批流程；其余保障措施则由代码仓库服务、运行环境、权限和审核流程提供。只有确认所选端点和参数能够配合你的 n8n 配置后，才应使用 OneMux 作为模型访问层。

参考来源

• n8n：工具调用中的人工参与 — 工具审批行为、设置、审核渠道和审核消息变量。
• OneMux 文档 — 请查阅当前 API 连接详情。