價值千萬！Manus技術精華：如何高效構建 AI智能體的上下文工程？

Manus 官網周末更新了一篇文章，分享了他們為 Manus 搭建合適的上下文工程的經驗教訓。作者季逸超 (Peak)，Manus 公司聯合創始人、首席科學家。

原文需要魔法去看，且是英文，網站的中文翻譯很差，我用Claude4翻譯一遍，學習完，再總結了技術要點，希望對大家有幫助！

而且我沒想到的是，最核心的竟然是KV cache，這個我熟啊！淚流滿面，后端工程師的第二春？第一個技術核心點像是后端的JD哈哈！

省流版全文核心技術要點

1. 1. KV-Cache優化策略（這個很關鍵）（后端工程師看到了自己的熟悉領域和價值！）
   問題核心：Agent的輸入輸出比例嚴重不平衡（100:1），前綴填充成本巨大
   解決方案：
   保持prompt前綴穩定（別在開頭加時間戳，你們這些新手老愛犯這錯誤！）
   確保上下文只追加，不修改
   顯式標記緩存斷點
   成本影響：緩存命中可降低10倍成本（Claude: 0.30 vs 3 USD/MTok）

2. 2. 工具空間管理（掩碼策略）
   核心思想："掩碼，不要刪除"
   技術實現：使用響應預填充約束動作空間
   Auto模式：<|im_start|>assistant
   Required模式：<|im_start|>assistant
   Specified模式：<|im_start|>assistant{"name": "browser_
   避免的坑：動態添加/刪除工具會破壞KV緩存且讓模型困惑

3. 3. 文件系統作為上下文存儲
   痛點：128K token窗口在真實場景下不夠用，且性能下降、成本高
   解決思路：將文件系統作為無限大、持久化的上下文
   壓縮策略：可恢復性壓縮（保留URL/文件路徑，內容可重新獲取）

4. 4. 注意力操控機制
   實現方式：通過todo.md文件持續更新任務列表
   技術原理：將全局計劃"背誦"到上下文末尾，避免"迷失在中間"問題
   效果：50步平均任務中保持目標對齊

5. 5. 錯誤保留策略
   反直覺做法：保留錯誤trace而不是清理
   技術依據：讓模型從失敗中學習，更新內部先驗
   實際效果：錯誤恢復是真正智能體行為的標志

6. 6. 反Few-shot策略
   問題：過度相似的示例會讓模型陷入模式固化
   解決：引入結構化多樣性，打破模式，增加序列化變化
   技術含量評估

   高價值點：
   KV-Cache優化策略非常實用，直擊生產環境痛點
   工具空間管理的掩碼方法很巧妙
   文件系統作為外部記憶的思路有創新性

7. 一般性觀點：
   錯誤保留、反Few-shot等更多是經驗總結
   缺乏定量evaluation和對比實驗

全文翻譯：

AI智能體的上下文工程：構建Manus的經驗教訓

2025年7月18日 - Yichao 'Peak' Ji

在Manus項目的初期，我和團隊面臨一個關鍵決策：是基于開源基礎模型訓練端到端的智能體模型，還是在前沿模型的上下文學習能力之上構建智能體？

回顧我在NLP領域的第一個十年，我們沒有這樣的選擇權。在遙遠的BERT時代（是的，已經過去七年了），模型必須經過微調和評估才能遷移到新任務。這個過程每次迭代都需要數周時間，盡管那時的模型相比今天的大語言模型來說非常小。對于快速發展的應用，特別是在產品市場契合（PMF）之前，如此緩慢的反饋循環是致命的。這是我上一家初創公司的痛苦教訓，當時我從零開始訓練開放信息抽取和語義搜索模型。然后GPT-3和Flan-T5橫空出世，我的內部模型一夜之間變得毫無意義。諷刺的是，正是這些模型標志著上下文學習時代的開始——以及一條全新的發展道路。

這個慘痛的教訓讓選擇變得明確：Manus將押注上下文工程。這讓我們能夠在幾小時而非幾周內發布改進，并保持產品與底層模型的正交性：如果模型進步是漲潮，我們希望Manus是船，而不是固定在海底的柱子。

然而，上下文工程遠非直截了當。這是一門實驗科學——我們已經重構了四次智能體框架，每次都是在發現更好的上下文塑造方法之后。我們親切地將這種架構搜索、提示調優和經驗猜測的手動過程稱為"隨機研究生下降"。這不優雅，但有效。

本文分享我們通過自己的"SGD"（"Stochastic Gradient Descent"（隨機梯度下降，SGD），網站中文翻譯是"隨機研究生下降" 。。。）達到的局部最優解。如果你正在構建自己的AI智能體，我希望這些原則能幫助你更快收斂。

圍繞KV-Cache設計

如果我必須選擇一個指標，我認為KV緩存命中率是生產級AI智能體最重要的單一指標。它直接影響延遲和成本。要理解原因，讓我們看看典型智能體的運作方式：

接收用戶輸入后，智能體通過一系列工具使用來完成任務。在每次迭代中，模型基于當前上下文從預定義的動作空間中選擇一個動作。該動作隨后在環境中執行（例如Manus的虛擬機沙箱）以產生觀察結果。動作和觀察被追加到上下文中，形成下一次迭代的輸入。這個循環持續到任務完成。

可以想象，上下文隨著每一步增長，而輸出——通常是結構化的函數調用——相對較短。這使得智能體中前綴填充和解碼之間的比例相比聊天機器人嚴重傾斜。例如，在Manus中，平均輸入輸出令牌比約為100:1。

幸運的是，具有相同前綴的上下文可以利用KV緩存，這大大減少了首令牌時間（TTFT）和推理成本——無論你使用自托管模型還是調用推理API。我們談論的不是小額節省：以Claude Sonnet為例，緩存輸入令牌成本為0.30美元/百萬令牌，而未緩存的成本為3美元/百萬令牌——相差10倍。

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

1. 1. 保持提示前綴穩定 ：由于LLM的自回歸性質，即使單個令牌的差異也會使從該令牌開始的緩存失效。一個常見錯誤是在系統提示開頭包含時間戳——特別是精確到秒的時間戳。確實，這讓模型能告訴你當前時間，但也會殺死你的緩存命中率。

2. 2. 使上下文僅追加 ：避免修改之前的動作或觀察。確保序列化是確定性的。許多編程語言和庫在序列化JSON對象時不保證穩定的鍵排序，這可能悄無聲息地破壞緩存。

3. 3. 在需要時顯式標記緩存斷點 ：一些模型提供商或推理框架不支持自動增量前綴緩存，而是需要在上下文中手動插入緩存斷點。分配這些斷點時，要考慮潛在的緩存過期，至少確保斷點包含系統提示的結尾。

此外，如果你使用vLLM等框架自托管模型，確保啟用前綴/提示緩存，并使用會話ID等技術在分布式工作器間一致路由請求。

掩碼，不要刪除

隨著智能體承擔更多能力，其動作空間自然變得更加復雜——簡言之，工具數量爆炸性增長。最近MCP的流行只是火上澆油。如果你允許用戶配置工具，相信我：總有人會將數百個神秘工具插入你精心策劃的動作空間。結果，模型更可能選擇錯誤動作或采取低效路徑。簡而言之，你的重裝智能體變笨了。

自然反應是設計動態動作空間——也許使用類似RAG的方式按需加載工具。我們在Manus中也嘗試過。但我們的實驗表明一個明確規則：除非絕對必要，避免在迭代中動態添加或刪除工具。主要有兩個原因：

1. 1. 在大多數LLM中，工具定義在序列化后位于上下文前端附近，通常在系統提示之前或之后。因此任何更改都會使所有后續動作和觀察的KV緩存失效。

2. 2. 當之前的動作和觀察仍然引用當前上下文中不再定義的工具時，模型會困惑。沒有約束解碼，這通常導致模式違規或幻覺動作。

為了解決這個問題同時仍然改進動作選擇，Manus使用上下文感知狀態機來管理工具可用性。我們不刪除工具，而是在解碼期間掩碼令牌logits來防止（或強制）基于當前上下文選擇某些動作。

在實踐中，大多數模型提供商和推理框架支持某種形式的響應預填充，這允許在不修改工具定義的情況下約束動作空間。通常有三種函數調用模式（我們使用NousResearch的Hermes格式作為例子）：

? 自動 – 模型可以選擇調用函數或不調用。通過僅預填充回復前綴實現：<|im_start|>assistant

? 必需 – 模型必須調用函數，但選擇不受約束。通過預填充到工具調用令牌實現：<|im_start|>assistant

? 指定 – 模型必須從特定子集調用函數。通過預填充到函數名開頭實現：<|im_start|>assistant {"name": "browser_

使用這個，我們通過直接掩碼令牌logits來約束動作選擇。例如，當用戶提供新輸入時，Manus必須立即回復而不是采取動作。我們還故意設計了具有一致前綴的動作名稱——例如，所有瀏覽器相關工具以browser_開頭，命令行工具以shell_開頭。這讓我們能夠輕松強制智能體只從給定狀態的某個工具組中選擇，而無需使用有狀態的logits處理器。

這些設計有助于確保Manus智能體循環保持穩定——即使在模型驅動的架構下。

使用文件系統作為上下文

現代前沿LLM現在提供128K令牌或更多的上下文窗口。但在現實世界的智能體場景中，這通常不夠，有時甚至是負擔。有三個常見痛點：

1. 1. 觀察可能很龐大，特別是當智能體與網頁或PDF等非結構化數據交互時。很容易超過上下文限制。

2. 2. 模型性能往往在超過某個上下文長度后下降，即使窗口技術上支持它。

3. 3. 長輸入很昂貴，即使有前綴緩存。你仍然要為傳輸和預填充每個令牌付費。

為了應對這個問題，許多智能體系統實施上下文截斷或壓縮策略。但過于激進的壓縮不可避免地導致信息丟失。問題是根本性的：智能體本質上必須基于所有先前狀態預測下一個動作——而你無法可靠預測哪個觀察在十步后可能變得關鍵。從邏輯角度看，任何不可逆壓縮都有風險。

這就是為什么我們將文件系統視為Manus的終極上下文：大小無限、本質持久，并且智能體本身可以直接操作。模型學會按需寫入和讀取文件——將文件系統不僅用作存儲，還用作結構化的外部化記憶。

我們的壓縮策略總是設計為可恢復的。例如，只要保留URL，網頁內容就可以從上下文中刪除，只要路徑在沙箱中仍然可用，文檔內容就可以省略。這允許Manus縮短上下文長度而不永久丟失信息。

在開發這個功能時，我發現自己在想象狀態空間模型（SSM）在智能體設置中有效工作需要什么。與Transformer不同，SSM缺乏完全注意力并且在長程反向依賴方面有困難。但如果它們能掌握基于文件的記憶——外部化長期狀態而不是在上下文中保持——那么它們的速度和效率可能解鎖新一類智能體。智能體SSM可能是神經圖靈機的真正繼承者。

通過背誦操控注意力

如果你使用過Manus，你可能注意到一些奇怪的事情：處理復雜任務時，它傾向于創建todo.md文件——并隨著任務進展逐步更新，勾選完成的項目。

這不僅僅是可愛的行為——這是操控注意力的刻意機制。

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

通過不斷重寫待辦事項列表，Manus將其目標背誦到上下文末尾。這將全局計劃推入模型的近期注意力范圍，避免"迷失在中間"問題并減少目標錯位。實際上，它使用自然語言偏向自己對任務目標的關注——無需特殊架構變更。

保留錯誤內容

智能體會犯錯誤。這不是缺陷——這是現實。語言模型會產生幻覺，環境返回錯誤，外部工具行為異常，意外邊緣情況時常出現。在多步任務中，失敗不是例外；它是循環的一部分。

然而，一個常見沖動是隱藏這些錯誤：清理跟蹤，重試動作，或重置模型狀態并寄希望于神奇的"溫度"。這感覺更安全、更可控。但這是有代價的：抹除失敗就是移除證據。沒有證據，模型無法適應。

根據我們的經驗，改進智能體行為最有效的方法之一出人意料地簡單：在上下文中保留錯誤轉向。當模型看到失敗動作——以及結果觀察或堆棧跟蹤——它隱式更新其內部信念。這將其先驗從類似動作中轉移，減少重復同樣錯誤的機會。事實上，我們相信錯誤恢復是真正智能體行為最清晰的指標之一。然而，它在大多數學術工作和公共基準中仍然代表性不足，這些通常關注理想條件下的任務成功。

不要陷入Few-shot陷阱

Few-shot提示是改進LLM輸出的常見技術。但在智能體系統中，它可能以微妙的方式適得其反。

語言模型是優秀的模仿者；它們模仿上下文中的行為模式。如果你的上下文充滿相似的過去動作-觀察對，模型會傾向于遵循那個模式，即使不再是最優的。

這在涉及重復決策或動作的任務中可能很危險。例如，使用Manus幫助審查一批20份簡歷時，智能體經常陷入節奏——重復相似動作僅僅因為這是它在上下文中看到的。這導致漂移、過度泛化或有時產生幻覺。

解決方案是增加多樣性。Manus在動作和觀察中引入少量結構化變化——不同的序列化模板、替代措辭、順序或格式的輕微噪聲。這種受控隨機性有助于打破模式并調整模型注意力。換句話說，不要讓few-shot把自己困在老路上。你的上下文越統一，你的智能體就越脆弱。

結論

上下文工程仍然是一門新興科學——但對智能體系統來說，它已經是必需的。模型可能變得更強、更快、更便宜，但再多的原始能力也無法替代對記憶、環境和反饋的需求。你如何塑造上下文最終定義了你的智能體如何行為：運行多快、恢復多好、擴展多遠。

在Manus，我們通過反復重寫、死胡同和跨數百萬用戶的真實世界測試學到了這些教訓。我們在這里分享的都不是普遍真理——但這些是對我們有效的模式。如果它們能幫助你避免哪怕一次痛苦的迭代，那么這篇文章就完成了它的使命。

智能體的未來將一次一個上下文地構建。好好工程化它們。

參考鏈接：Context Engineering for AI Agents: Lessons from Building Manus ， https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

回復【智能體】，討論研究智能體技術、智能體平臺和智能體搞錢。

其實后端工程師轉型AI專家，有很多成功的例子。下一篇，我打算寫一下Gemini的研發之路，聊聊Jeff Dean是如何從掌舵谷歌的大數據三駕馬車核心基礎設施研發，轉型到谷歌大腦負責人，做出Gemini這樣能跟chatGPT抗衡的AI多模態神器。Jeff Dean，YYDS！

我是刀哥，大廠架構師，出海創業者，深入研究AI工具和AI編程。關注我，了解更多AI知識！