使用 Agent-Harness-Kit 擴展 AI 代理工作流程

從單一提示 AI 助手轉向多代理系統是當前軟體工程中最重要的轉變之一。雖然單一代理可以撰寫函式或說明錯誤，但全倉庫的複雜變更需要協調的努力——一種模仿專業工程團隊的分工。然而，為此協調建立基礎設施——狀態管理、權限界限與交接協議——往往是一個繁瑣的手動過程。

這就是 agent-harness-kit (ahk) 的出現，它被設計為 AI 代理協調的「Vite」。透過提供標準化的腳手架流程，它讓開發者能快速部署多代理 harness，將一群單獨的代理轉變為一個一致的系統。

協調架構

在核心上，agent-harness-kit 專注於「harness」——允許代理在定義環境中運作的結構支撐。套件不依賴單一單體代理，而是以四個專門角色為基礎構建系統，每個角色都有明確的權限界限：

• Lead Orchestrator: 專案經理。它挑選任務並協調其他代理。
• Explorer (Read-Only): 研究員。它在任何程式碼被修改前了解倉庫並繪製依賴關係。
• Builder (Write: src/): 實作者。它僅被允許寫入 src/ 與 tests/ 目錄。
• Reviewer (Gatekeeper): 驗證者。它確保未通過測試的任務不會被標記為完成。

這種關注點分離可防止「幻覺迴圈」——代理嘗試修復錯誤時引入新錯誤，然後在缺乏全局目標觀的情況下再度嘗試修復新錯誤。

主要技術特點

為了超越簡單提示，agent-harness-kit 實作了多項基礎設施原語：

SQLite 作為唯一真相來源

系統不依賴 LLM 易變的上下文窗口，而是使用 SQLite 資料庫來維持狀態。這提供了持久的記憶層，儲存代理活動、任務狀態與協調規則，使系統能從失敗中復原，並在不同代理回合間保持一致的歷史紀錄。

Model Context Protocol (MCP) 整合

套件內建 MCP 伺服器，使代理能以標準化方式與外部工具與資料來源互動。這使系統與供應商無關，支援如 Claude Code 與 OpenCode 等工具，同時在 MCP 不可用的環境提供 Markdown 後備方案。

自動化腳手架

部署透過簡單的 CLI 指令 (npx @cardor/agent-harness-kit init) 完成，該指令會產生必要的基礎設施：用於角色定義的 AGENTS.md、具型別的設定檔、SQLite 資料庫，以及用於系統監控的 health.sh 腳本。

批判性觀點與工程挑戰

雖然腳手架方法充滿前景，社群仍提出多項技術考量，關於代理工作流程的長期可行性。

「LLM 評審」問題

主要批評之一涉及驗證流程。如果 Lead 代理僅閱讀子代理的輸出以判斷任務是否完成，Lead 就會成為隱含的審查者。正如社群成員所指出的，這引發了系統是基於 typed state（硬資料）還是 raw output（自然語言）進行推理的問題。要打造真正穩健的系統，必須以程式方式檢查後置條件，而非僅依賴 LLM 的批准。

狀態轉換與錯誤處理

管理代理之間的「交接」是眾所周知的痛點。常見的失敗模式是「無盡重試迴圈」，即代理失敗卻未回報具體錯誤，導致排程器無限重試。

「最棘手的部分是被中止卻沒有明顯的錯誤… 必須有方式說明『發生了這件事，但不是我們想要的』，例如 'blocked_quota' 或 'blocked_no_credentials'。」

有效的協調需要一種紀律，確保代理永不寫入「半狀態」，且每次執行都以已記錄的終端狀態結束。

沙箱與隔離

為防止代理在本機環境中造成災難性失敗，強烈建議整合自動 worktree 建立與沙箱機制。使用 git worktrees 與 Bubblewrap 等工具可將代理的環境隔離，確保其實驗不會污染主要開發分支。

路線圖與未來方向

該專案目前正擴展整合能力，以超越本機檔案系統。計畫中的 Jira、Linear 與 GitHub Issues 介面暗示系統將直接與專案的專案管理軟體結合，使代理能直接從待辦清單取得任務，並將更新推回至工單。

透過標準化「harness」，agent-harness-kit 試圖降低多代理系統的入門門檻，讓產業更接近 AI 代理作為可擴展且有紀律的工程團隊的願景。