Manus 官網(wǎng)周末更新了一篇文章，分享了他們?yōu)?Manus 搭建合適的上下文工程的經(jīng)驗教訓。作者季逸超 (Peak)，Manus 公司聯(lián)合創(chuàng)始人、首席科學家。

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

而且我沒想到的是，最核心的竟然是KV cache，這個我熟?。I流滿面，后端工程師的第二春？第一個技術(shù)核心點像是后端的JD哈哈！

省流版全文核心技術(shù)要點

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

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

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

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

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

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

   高價值點：
   KV-Cache優(yōu)化策略非常實用，直擊生產(chǎn)環(huán)境痛點
   工具空間管理的掩碼方法很巧妙
   文件系統(tǒng)作為外部記憶的思路有創(chuàng)新性

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

全文翻譯：

AI智能體的上下文工程：構(gòu)建Manus的經(jīng)驗教訓

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

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

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

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

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

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

圍繞KV-Cache設(shè)計

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

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

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

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

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

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

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

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

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

掩碼，不要刪除

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

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

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

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

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

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

? 自動 – 模型可以選擇調(diào)用函數(shù)或不調(diào)用。通過僅預填充回復前綴實現(xiàn)：<|im_start|>assistant

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

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

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

這些設(shè)計有助于確保Manus智能體循環(huán)保持穩(wěn)定——即使在模型驅(qū)動的架構(gòu)下。

使用文件系統(tǒng)作為上下文

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

1. 1. 觀察可能很龐大，特別是當智能體與網(wǎng)頁或PDF等非結(jié)構(gòu)化數(shù)據(jù)交互時。很容易超過上下文限制。

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

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

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

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

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

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

通過背誦操控注意力

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

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

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

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

保留錯誤內(nèi)容

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

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

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

不要陷入Few-shot陷阱

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

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

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

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

結(jié)論

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

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

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

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

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

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

我是刀哥，大廠架構(gòu)師，出海創(chuàng)業(yè)者，深入研究AI工具和AI編程。關(guān)注我，了解更多AI知識！