建立具備人工核准與測試驗證的 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. 套用並識別提交。 若獲核准，寫入服務會檢查分支是否仍指向已核准的基礎提交，套用已核准的修補內容，並回傳新的提交 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 處理審查，但它不是安全邊界。權限與分支限制必須在提示詞之外強制執行。

驗證已核准的變更

僅在寫入服務回傳提交 ID 後才觸發測試執行環境。設定執行環境簽出該 ID，而不是分支最新的提交，並執行團隊定義於允許清單中的指令。若儲存庫維護者選用了以下指令，它可以是一個範例：

npm test

該指令僅供示意；請使用專案實際的測試指示。將儲存庫程式碼、相依套件安裝指令碼及測試輸出視為不可信內容。執行時應限制網路與檔案系統存取，不使用正式環境機密資訊，並設定時間與資源限制。測試套件通過只能表示所選檢查在該環境中通過，不能證明變更安全或正確。

回傳精簡結果，包含已核准的基礎提交、新提交、測試指令、通過或失敗狀態，以及日誌連結。若測試失敗，Agent 可以提出修訂後的修補內容，但再次寫入需要另行核准。不要因審查者核准了先前的工具呼叫就自動合併。

疑難排解與運作限制

核准請求缺少有用的脈絡

檢查哪些輸入由 AI 提供，以及哪些會顯示在 $tool.parameters 中。將修補內容識別資訊、分支與基礎修訂版本放入可供審查的工具輸入，或提供安全且不可變的審查產物。如果審查者無法識別確切的寫入內容，就應拒絕。

Agent 無法呼叫工具

先獨立於儲存庫權限測試一個無害工具。對照最新文件檢查 n8n 節點、OneMux 端點、所選模型及必要的工具呼叫參數。所提供的來源並未驗證特定模型與節點的組合。

分支已變動或測試未完成

應拒絕基礎版本已過時的寫入，而非將修補內容套用至不同的基礎提交。若發生逾時、執行環境錯誤或缺少日誌，請回報驗證未完成。適當時可針對相同提交重新執行；若提議的寫入內容改變，則須重新取得核准。

結論

有效的界線應維持明確：由人員核准特定的儲存庫寫入，再由隔離的執行環境驗證產生的提交。n8n 提供文件記載的工具層級暫停與核准流程；其餘防護措施則由儲存庫服務、執行環境、權限及審查程序提供。只有確認所選端點與參數能配合 n8n 設定後，才將 OneMux 用作模型存取層。

參考資料

• n8n: Human-in-the-loop for tools — 工具核准行為、設定方式、審查管道及審查訊息變數。
• OneMux 文件 — 可查閱最新 API 連線資訊。