季逸超親述 Manus 構建之謎，一文讀懂 AI 智能體的上下文工程

本文是對 Manus 創始人季逸超（Jiyichao）在其博客上發表的《Context Engineering for AI Agents: Lessons from Building Manus》一文的全文翻譯。

這篇文章并非空泛的理論，而是 Manus 團隊在構建 AI 智能體時，從無數次失敗、踩坑和迭代中提煉出的寶貴實戰經驗，充滿了在戰壕里摸爬滾打后總結出的真知灼見。我們希望通過這次翻譯，將這些寶貴的實戰經驗分享給更多中文世界的開發者。

出品丨AI 科技大本營（ID：rgznai100）

原文 | https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

在 Manus 項目伊始，我和團隊面臨一個關鍵抉擇：是應該利用開源基礎模型來訓練一個端到端的 Agent，還是基于前沿模型的上下文學習（in-context learning）能力來構建？

回溯我從事自然語言處理（NLP）的頭十年，我們根本沒有這樣的選擇。在遙遠的 BERT 時代（是的，已經七年了），模型必須先經過微調和評估，才能勝任新任務。盡管那時的模型比今天的大語言模型（LLM）小得多，但這個過程每次迭代仍需數周。

對于快速變化的應用，尤其是在產品尚未與市場契合（pre-PMF）的階段，如此緩慢的反饋循環是致命的。這是我上一次創業時得到的慘痛教訓，當時我為了實現開放信息抽取和語義搜索，從零開始訓練模型。然而，GPT-3 和 Flan-T5 的橫空出世，讓我自研的模型一夜之間變得毫無價值。諷刺的是，也正是這些模型，開啟了上下文學習的時代，并指明了一條全新的道路。

這個來之不易的教訓讓我們的選擇變得異常清晰：Manus 將賭注押在上下文工程（Context Engineering）上。這使我們能將產品改進的周期從數周縮短至幾小時，并讓我們的產品與底層模型的發展保持正交：如果說模型技術的進步是上漲的潮水，我們希望 Manus 是水漲船高的船，而非被固定在海床上的橋墩。

即便如此，上下文工程的實踐之路也遠非一帆風順。它是一門實驗科學——我們已經重構了四次 Agent 框架，每一次都是因為發現了塑造上下文的更優方法。我們將這種手動進行架構搜索、調試提示（prompt）和憑經驗猜測的摸索過程，戲稱為“隨機研究生下降”（Stochastic Graduate Descent）——這是對“隨機梯度下降”（Stochastic Gradient Descent）的一個文字游戲。這個方法聽起來不那么優雅，但確實有效。

本文將分享我們通過自己的“SGD”方法所摸索出的局部最優解。如果你也在構建自己的 AI Agent，希望這些原則能幫助你更快地找到方向。

圍繞 KV 緩存進行設計

如果非要我只選一個指標，我認為KV緩存命中率（KV-cache hit rate）是生產級 AI Agent 最重要的單一指標，因為它直接影響延遲和成本。要理解這一點，我們先來看看一個典型 Agent 的工作流程：

收到用戶輸入后，Agent 會通過一系列工具調用來完成任務。在每次迭代中，模型根據當前上下文，從預定義的操作空間中選擇一個動作。該動作在環境（如 Manus 的虛擬機沙箱）中執行后，產生一個觀察結果。這個動作和觀察結果會被追加到上下文中，作為下一次迭代的輸入。此循環不斷重復，直至任務完成。

可以想見，上下文會隨著每一步而增長，而輸出——通常是一個結構化的函數調用——則相對較短。這使得 Agent 的輸入與輸出 token 比例，和聊天機器人相比嚴重失衡。例如，在 Manus 中，這個比例平均約為 100:1。

幸運的是，擁有相同前綴的上下文可以利用 KV 緩存，從而大幅降低首個token 生成時間（TTFT）和推理成本——無論你使用的是自托管模型還是第三方推理 API。這帶來的成本節約是巨大的：以 Claude Sonnet 為例，緩存過的輸入 token 成本為 0.30 美元/百萬 token，而未緩存的則為 3 美元/百萬 token，成本相差整整 10 倍。

從上下文工程的角度看，提高 KV 緩存命中率有幾個關鍵實踐：

1. 保持提示詞前綴的穩定性。由于 LLM 的自回歸特性，哪怕只有一個 token 的差異，也會使該 token 之后的所有緩存失效。一個常見錯誤是在系統提示的開頭包含時間戳——尤其是精確到秒的時間戳。這固然能讓模型告知當前時間，但也會徹底破壞你的緩存命中率。

2. 讓上下文只增不減（append-only）。避免修改歷史動作或觀察結果。同時要確保序列化過程是確定性的。許多編程語言和庫在序列化 JSON 對象時，不保證鍵的順序穩定，這會悄無聲息地破壞緩存。

3. 在需要時明確標記緩存斷點。一些模型提供商或推理框架不支持自動的增量前綴緩存，需要手動在上下文中插入緩存斷點。在設置斷點時，要考慮到緩存的生命周期，并至少確保斷點設在系統提示之后。

此外，如果你在使用 vLLM 等框架自托管模型，請確保啟用了前綴/提示緩存功能，并使用會話 ID 等技術，將來自同一用戶的請求持續路由到固定的工作節點上。

AI產品爆發，但你的痛點解決了嗎?8.15-16 北京威斯汀·全球產品經理大會PM-Summit，3000+AI產品人社群已就位。

• 直面AI落地難題·拆解頭部案例·對接精準資源掃碼登記信息，添加小助手進群，搶占AI產品下一波紅利

進群后，您將有機會得到：

· 最新、最值得關注的 AI 產品資訊及大咖洞見

· 獨家視頻及文章解讀 AGI 時代的產品方法論及實戰經驗

· 不定期贈送AI產品干貨資料和秘籍

巧用掩碼，而非直接移除

隨著 Agent 的能力不斷擴展，其操作空間（Action Space）會自然變得愈發復雜——簡而言之，工具的數量會爆炸式增長。近期流行的MCP更是火上澆油。如果允許用戶自定義工具，那總會有人把成百上千個稀奇古怪的工具塞進你精心設計的操作空間里。其結果是，模型更容易選錯工具或采取低效路徑。一言以蔽之，全副武裝的 Agent 反而變笨了。

一個自然的想法是設計一個動態的操作空間——比如用類似 RAG 的方式按需加載工具。我們在 Manus 中也嘗試過。但實驗得出了一個明確的結論：除非絕對必要，否則不要在迭代過程中動態增刪工具。主要原因有二：

1. 在大多數 LLM 中，工具定義在序列化后位于上下文的前部，通常緊跟在系統提示之后。因此，任何改動都會導致后續所有動作和觀察結果的 KV 緩存全部失效。

2. 如果歷史動作和觀察結果引用了當前上下文中已不復存在的工具，模型就會感到困惑。若不進行約束解碼，這通常會導致輸出格式錯誤（schema violation）或產生幻覺動作。

為了解決這個問題，同時又能優化動作選擇，Manus 采用了一個感知上下文的狀態機來管理工具的可用性。它并非直接移除工具，而是在解碼階段對 token 的對數幾率（logits）進行掩碼（masking），從而根據當前狀態，阻止或強制模型選擇某些動作。

實踐中，大多數模型提供商和推理框架都支持某種形式的響應預填充（response prefill），讓你可以在不修改工具定義的前提下約束操作空間。函數調用通常有三種模式（以 NousResearch 的 Hermes 格式為例）：

• 自動（Auto）：模型可自行決定是否調用函數。通過預填充回復前綴 <|im_start|>assistant 實現。

• 必需（Required）：模型必須調用一個函數，但可自由選擇。通過預填充至 <|im_start|>assistant 實現。

• 指定（Specified）：模型必須從一個給定的子集中選擇函數。通過預填充至函數名開頭，如 <|im_start|>assistant {"name": "browser_ 實現。

利用這種機制，我們通過直接掩碼 logits 來約束動作選擇。例如，當用戶提供新輸入時，Manus 必須立即回復而非執行動作。我們還有意將動作名稱設計成擁有統一的前綴，例如，所有瀏覽器工具均以 browser_ 開頭，所有命令行工具均以 shell_ 開頭。這使得我們可以在特定狀態下，輕松地強制 Agent 只從某一類工具中選擇，而無需依賴復雜 Stateful Logits Processor。

這些設計確保了 Manus Agent 的執行循環，即便在模型驅動的架構下，也能保持高度的穩定性。

將文件系統作為外部上下文

當前的前沿 LLM 已提供 128K 甚至更長的上下文窗口。但在真實的 Agent 場景中，這往往還不夠，有時甚至是一種負擔。以下是三個常見痛點：

1. 觀察結果可能極其龐大，尤其是當 Agent 與網頁、PDF 等非結構化數據交互時，極易超出上下文長度限制。

2. “大海撈針”問題，即模型性能在上下文長度超過某一閾值后會開始下降，即便窗口在技術上仍未溢出。

3. 成本高昂，即使有前綴緩存，你仍需為傳輸和預填充每個 token 付費。

為了應對這些問題，許多 Agent 系統采用了上下文截斷或壓縮策略。但過于激進的壓縮必然導致信息丟失。這是一個根本性矛盾：Agent 的天性決定了它必須基于所有歷史狀態來預測下一步動作，而你無法可靠地預知哪個觀察結果會在十步之后變得至關重要。從邏輯上講，任何不可逆的壓縮都伴隨著風險。

因此，在 Manus 中，我們將文件系統視為最終的上下文：它容量無限，天然持久，且能被 Agent 直接操作。我們訓練模型按需讀寫文件，將文件系統不僅用作存儲，更用作一種結構化的外部記憶。

我們的壓縮策略始終被設計為可恢復的。例如，只要保留了網頁的 URL，其內容就可以從上下文中移除；只要文檔的路徑在沙箱中可用，其內容就可以被省略。這使得 Manus 可以在不永久丟失信息的前提下，有效縮減上下文長度。

在開發此功能時，我常常思考：如何讓狀態空間模型（SSM）在 Agent 場景中高效工作？與 Transformer 不同，SSM 缺乏全局注意力，難以處理長程依賴。但如果它們能掌握基于文件的記憶——將長期狀態外化存儲，而非全部保留在上下文中——那么它們的速度和效率優勢或許能催生一類全新的 Agent。具備這種能力的 Agent SSM，或許才是神經圖靈機的真正繼承者。

通過復述（Recitation）操控注意力

如果你使用過 Manus，可能會注意到一個有趣的現象：在處理復雜任務時，它會創建一個 todo.md 文件，并隨著任務的推進逐步更新，勾掉已完成的項。

這并非簡單的裝飾行為，而是一種有意為之的注意力操控機制。

在 Manus 中，一個典型任務平均需要約 50 次工具調用。這是一個相當長的執行鏈。由于 Manus 的決策依賴 LLM，它很容易在長上下文或復雜任務中偏離主題或忘記早期目標。

通過不斷重寫這個待辦事項列表，Manus 相當于在將它的核心目標“復述”到上下文的末尾。這使得全局計劃始終處于模型近期的注意力范圍內，有效避免了“迷失在中間”（lost-in-the-middle）的問題，降低了目標漂移的風險。實際上，它是在用自然語言來引導自身的注意力，使其聚焦于任務目標，而無需任何特殊的架構調整。

保留失敗的嘗試

Agent 會犯錯。這不是缺陷，而是現實。語言模型會產生幻覺，環境會返回錯誤，外部工具會出故障，各種意想不到的邊緣情況總會發生。在多步驟任務中，失敗不是例外，而是循環的一部分。

然而，人們有一種常見的沖動，想要隱藏這些錯誤：清理執行記錄、重試動作，或者重置模型狀態，然后寄希望于調高“temperature”參數來“隨機”出正確結果。這看似更安全、更可控，但代價是：抹去失敗，也就抹去了學習的證據。沒有證據，模型就無法適應和改進。

根據我們的經驗，提升 Agent 行為最有效的方法之一，簡單得令人意外：將失敗的嘗試保留在上下文中。當模型看到一個失敗的動作——以及由此產生的錯誤信息或堆棧跟蹤（stack trace）——它會隱式地更新其內部認知，從而降低在未來采取類似動作的先驗概率，減少重復犯錯的可能。

事實上，我們認為錯誤恢復（error recovery）能力是衡量真正 Agent 智能最清晰的標志之一。然而，在大多數學術研究和公開基準測試中，這一點仍然被嚴重低估，它們往往只關注理想條件下的任務成功率。

警惕少樣本提示的陷阱

少樣本提示（Few-shot prompting）是提升 LLM 輸出質量的常用技巧，但在 Agent 系統中，它可能會以一種微妙的方式適得其反。

語言模型是出色的模仿者，它們會模仿上下文中的行為模式。如果上下文中充滿了大量相似的“動作-觀察”對，模型就會傾向于遵循這種模式，即便它已不再是當前情況下的最優解。

這在涉及重復性決策或動作的任務中尤其危險。例如，在使用 Manus 審閱 20 份簡歷時，Agent 常常會陷入一種固定的節奏——僅僅因為上下文中充滿了類似的操作記錄，它就開始機械地重復這些動作。這會導致行為漂移、過度泛化，有時甚至產生幻覺。

解決方法是增加多樣性。Manus 會在動作和觀察結果中引入少量結構化的變體——例如，使用不同的序列化模板、調整措辭、在順序或格式上引入微小的噪音。這種受控的隨機性有助于打破行為定式，并重新激活模型的注意力。

換言之，不要讓少樣本提示把自己困在思維定式里。你的上下文越是千篇一律，你的 Agent 就會變得越脆弱。

結語

上下文工程仍是一門新興的科學，但對于 Agent 系統而言，它已是成功的基石。模型也許正變得更強、更快、更便宜，但任何原始能力的提升，都無法取代對記憶、環境和反饋的精心設計。你如何塑造上下文，最終決定了你的 Agent 將如何行事：它的運行速度、糾錯能力，以及擴展的潛力。

在 Manus，我們通過一次次的重構、失敗的嘗試以及對數百萬用戶的真實世界測試，才學到了這些經驗。本文分享的并非放之四海而皆準的真理，但它們是于我們行之有效的模式。如果這些經驗能幫助你哪怕只避免一次痛苦的迭代，那這篇文章就實現了它的價值。

Agent 的未來，將由一個個上下文精心構建而成。

AI 產品爆發，但你的痛點解決了嗎？

2025 全球產品經理大會

8 月 15–16 日

北京·威斯汀酒店

互聯網大廠、AI 創業公司、ToB/ToC 實戰一線的產品人

12 大專題分享，洞察趨勢、拆解路徑、對話未來。

立即掃碼領取大會PPT

搶占 AI 產品下一波紅利