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

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

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

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

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

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

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

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

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

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

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

7. 一般性觀點(diǎn)：
   錯(cuò)誤保留、反Few-shot等更多是經(jīng)驗(yàn)總結(jié)
   缺乏定量evaluation和對(duì)比實(shí)驗(yàn)

全文翻譯：

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

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

在Manus項(xiàng)目的初期，我和團(tuán)隊(duì)面臨一個(gè)關(guān)鍵決策：是基于開(kāi)源基礎(chǔ)模型訓(xùn)練端到端的智能體模型，還是在前沿模型的上下文學(xué)習(xí)能力之上構(gòu)建智能體？

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

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

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

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

圍繞KV-Cache設(shè)計(jì)

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

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

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

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

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

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

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

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

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

掩碼，不要?jiǎng)h除

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

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

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

2. 2. 當(dāng)之前的動(dòng)作和觀察仍然引用當(dāng)前上下文中不再定義的工具時(shí)，模型會(huì)困惑。沒(méi)有約束解碼，這通常導(dǎo)致模式違規(guī)或幻覺(jué)動(dòng)作。

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

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

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

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

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

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

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

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

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

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

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

3. 3. 長(zhǎng)輸入很昂貴，即使有前綴緩存。你仍然要為傳輸和預(yù)填充每個(gè)令牌付費(fèi)。

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

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

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

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

通過(guò)背誦操控注意力

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

這不僅僅是可愛(ài)的行為——這是操控注意力的刻意機(jī)制。

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

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

保留錯(cuò)誤內(nèi)容

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

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

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

不要陷入Few-shot陷阱

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

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

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

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

結(jié)論

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

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

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

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

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

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

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