Agent智能體工程

本文最初發表在Addy Osmani的博客上，經授權轉載。

核心觀點：每當發現智能體犯錯，都應花時間設計一種解決方案，確保該錯誤不再發生。

過去兩年，我們一直在爭論模型：哪個最聰明、哪個能寫出最乾淨的React代碼、哪個幻覺更少。這種討論雖有一定價值，但忽略了系統的另一半。模型只是運行中智能體的一個輸入，其餘部分是約束框架（harness）：圍繞模型的提示、工具、上下文策略、鈎子、沙箱、子智能體、反饋循環和恢復路徑，以便智能體真正完成一些任務。

一箇中等模型搭配優秀的約束框架，效果勝過頂級模型搭配糟糕的約束框架。我多次在自己的工作中觀察到這一點。越來越有趣且重要的工程不在於選擇模型，而在於設計模型周圍的“腳手架”。

如今這一學科有了名稱。Viv Trivedy創造了“約束框架工程”這一術語，他的《智能體約束框架解剖》一文清晰闡述了約束框架是什麼以及各部分存在的原因。Dex Horthy持續跟蹤這一模式。HumanLayer將大多數智能體失敗歸結為“技能問題”，即配置問題而非模型權重問題。Anthropic的工程團隊發佈了我認為最好的關於如何為長期運行任務設計約束框架的公開分析。Birgitta Böckeler從用户角度也提供了很好的概述。

本文嘗試將這些線索整合起來。

究竟什麼是約束框架？

Viv的一句話概括了大部分內容：智能體 = 模型 + 約束框架。如果你不是模型，你就是約束框架。

約束框架是除模型本身之外的所有代碼、配置和執行邏輯。原始模型不是智能體，只有約束框架賦予其狀態、工具執行、反饋循環和可執行約束時，它才成為智能體。

具體而言，約束框架包括：系統提示、CLAUDE.md、AGENTS.md、技能文件和子智能體提示；工具、技能、MCP服務器及其描述；捆綁的基礎設施（文件系統、沙箱、瀏覽器）；編排邏輯（子智能體生成、交接、模型路由）；用於確定性執行的鈎子和中間件（壓縮、續領、lint檢查）；可觀測性（日誌、追蹤、成本和延遲計量）。

Simon Willison將循環部分精煉為：智能體是“循環運行工具以實現目標的系統”。技巧在於工具和循環的設計。

如果這聽起來像很大的表面積，確實如此。但這是你的表面積，而非模型提供商的。Claude Code、Cursor、Codex、Aider、Cline——這些都是約束框架。底層模型有時相同，但你體驗到的行為主要由約束框架決定。

編碼智能體 = AI模型 + 約束框架。這個由Viv闡述並被HumanLayer回應的等式，是實際工作所在。關於等式左邊的討論聲音很大，但實際上大部分槓桿作用在右邊。

“技能問題”的重新定義

我觀察到一種模式：工程師陷入其中。智能體做了蠢事，工程師責怪模型，然後將責備歸檔為“等待下一版本”。

約束框架工程的心態拒絕這種默認做法。失敗通常是可理解的。智能體不知道某個約定，那就將其添加到AGENTS.md中。智能體運行了破壞性命令，那就添加鈎子阻止它。智能體在40步任務中迷失，那就將其拆分為規劃器和執行器。智能體不斷“完成”損壞的代碼，那就將類型檢查反向壓力信號接入循環。

HumanLayer説：“這不是模型問題，而是配置問題。”約束框架工程就是你認真對待這句話時發生的事情。

在Viv的文章和HumanLayer中都出現了一個引人注目的數據點。在Terminal Bench 2.0上，運行在Claude Code中的Claude Opus 4.6得分遠低於同一模型運行在定製約束框架中的得分。Viv的團隊僅通過更改約束框架，就將一個編碼智能體從Top 30提升到Top 5。模型經過後訓練後與它們訓練時所針對的約束框架耦合在一起。將它們遷移到不同的約束框架——具有更好的代碼庫工具、更緊湊的提示和更鋭利的反向壓力——可以釋放原始約束框架未充分利用的能力。

這與“只需等待GPT-6”的敍事相反。當今模型能力與你所見到的能力之間的差距，很大程度上是約束框架的差距。

棘輪：每次錯誤都變成規則

約束框架工程中最重要的習慣是將智能體錯誤視為永久信號。不是可以一笑置之的趣聞，不是可以重試的“壞運行”，而是信號。

如果智能體提交了一個帶有被註釋掉的測試的PR，而我意外合併了它，那就是一個輸入。我的AGENTS.md下一個版本會説“永遠不要註釋測試；刪除它們或修復它們。”我的預提交鈎子下一個版本會掃描diff中的“.skip(”和“xit(”。我的審閲子智能體下一個版本會將註釋掉的測試標記為阻塞項。

只在看到實際失敗時才添加約束。只在有能力的模型使約束變得多餘時才移除它們。好的AGENTS.md中的每一行都應該能追溯到某個具體出錯的事情。

這也是約束框架工程是一門學科而非框架的原因。適合你代碼庫的約束框架是由你的失敗歷史塑造的。你無法下載它。

從期望行為反向設計

我發現Viv的框架在實際設計約束框架時最有用：從你期望的行為出發，推導出能夠實現該行為的約束框架部分。他的模式：期望的行為（或希望修正的行為）→ 幫助模型實現該目標的約束框架設計。

這樣推導的有用之處在於，每個約束框架組件都有特定職責。如果你無法説出某個組件所服務的行為，它可能就不應該存在。

本節其餘部分大致按照Viv的順序介紹各個部分，並附上我發現值得借鑑的具體模式。

文件系統和Git：持久狀態

文件系統是最基礎的原始構件，但由於其平淡無奇常常被低估。模型只能直接操作上下文中的內容。沒有文件系統，你只能複製粘貼到聊天窗口，那不是工作流程。

有了文件系統，智能體就獲得了讀取數據、代碼和文檔的工作空間；將中間工作卸載到文件系統而非保留在上下文中的地方；以及多個智能體與人類通過共享文件協調的表面。在此基礎上添加Git，便免費獲得了版本控制，因此智能體可以跟蹤進度、回滾錯誤和分支實驗。

大多數其他約束框架原始構件最終都指向文件系統。

Bash和代碼執行：通用工具

當前主要智能體循環是ReAct循環：模型推理，通過工具調用採取行動，觀察結果，然後重複。但約束框架只能執行它有邏輯的工具。你可以嘗試為每個可能動作預構建工具，或者給智能體Bash，讓它自己動態構建所需工具。

Willison的觀點是，智能體已經擅長shell命令；大多數任務歸結為幾個精心選擇的CLI調用。約束框架仍然提供專門的工具，但Bash加代碼執行已成為自主解決問題的默認通用策略。這就像教一個人使用單個廚房用具與給整個廚房的區別。

沙箱和默認工具

Bash只有在安全的地方運行時才有用。在筆記本電腦上運行智能體生成的代碼有風險，並且單個本地環境無法擴展到大量並行智能體。

沙箱為智能體提供隔離的操作環境。約束框架連接到沙箱來運行代碼、檢查文件、安裝依賴和驗證工作，而不是在本地執行。你可以允許列表命令、強制網絡隔離、按需創建新環境並在任務完成後拆除。

好的沙箱附帶好的默認配置：預裝語言運行時和包、Git和測試CLI、用於Web交互的無頭瀏覽器。瀏覽器、日誌、截圖和測試運行器讓智能體觀察自己的工作並關閉自我驗證循環。

模型不配置其執行環境。決定智能體在哪裏運行、哪些可用以及如何驗證輸出，都是約束框架層面的事情。

記憶和搜索：持續學習

模型除了權重和當前上下文中的內容外沒有額外知識。無法編輯權重的情況下，添加知識的唯一方法是通過上下文注入。

文件系統再次是原始構件。約束框架支持類似AGENTS.md的記憶文件標準，每次啓動時注入。隨着智能體編輯該文件，約束框架重新加載它，一個會話中的知識就傳遞到下一個會話。這是一種原始但有效的持續學習形式。

對於訓練時不存在的知識（新版庫、當前文檔、今日數據），Web搜索和Context7等MCP工具彌補了截止點。將這些工具內置到約束框架中比留給用户更有用。

對抗上下文衰退

上下文衰退是指隨着上下文窗口填滿，模型推理和完成任務的能力變差的現象。上下文稀缺，約束框架在很大程度上是良好上下文工程的交付機制。

三種技術反覆出現：

壓縮。當窗口接近滿載時，必須有所取捨。讓API出錯對於生產環境約束框架不可行，因此約束框架智能地總結並卸載較舊的上下文，使智能體繼續工作。

工具調用卸載。大型工具輸出（如2000行日誌文件）會干擾上下文而不增加多少信號。約束框架保留高於閾值的頭尾令牌，將完整輸出卸載到文件系統，智能體可以按需讀取。

漸進式披露技能。在啓動時將每個工具和MCP加載到上下文中會在智能體採取任何行動之前就降低性能。技能讓約束框架僅在任務實際需要時才揭示指令和工具。

Anthropic的約束框架文章為非常長的任務添加了另一種技術：完全上下文重置，即約束框架拆除會話並從緊湊的交接文件重建。他們明確指出，僅靠壓縮對長任務不夠；有時需要從結構化簡報重新開始。這更接近人類入職新工程師的方式，而不是我們通常對“記憶”的看法。

長期執行：Ralph循環、規劃、驗證

自主長期工作是聖盃，也是最難做對的事情。當今模型存在提前停止、複雜問題分解能力差以及工作跨越多個上下文窗口時的不連貫性。約束框架必須圍繞所有這些進行設計。

我之前在自我改進智能體和2026趨勢文章中寫過像Ralph循環這樣的自主編碼循環，但在本框架中值得重申：鈎子截獲模型退出意圖，將原始提示重新注入新的上下文窗口，強迫智能體繼續朝着完成目標工作。每次迭代從乾淨狀態開始，但通過文件系統讀取前一次的狀態。這是一個將單會話智能體轉變為多會話智能體的驚人簡單技巧，是僅憑“使用更智能的模型”永遠推導不出的原始構件。

規劃是指模型將目標分解為一系列步驟，通常寫入磁盤上的計劃文件。約束框架通過提示和關於如何使用計劃文件的提醒來支持這一點。