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

這篇文章并非空泛的理論，而是 Manus 團(tuán)隊(duì)在構(gòu)建 AI 智能體時(shí)，從無(wú)數(shù)次失敗、踩坑和迭代中提煉出的寶貴實(shí)戰(zhàn)經(jīng)驗(yàn)，充滿了在戰(zhàn)壕里摸爬滾打后總結(jié)出的真知灼見。我們希望通過(guò)這次翻譯，將這些寶貴的實(shí)戰(zhàn)經(jīng)驗(yàn)分享給更多中文世界的開發(fā)者。

出品丨AI 科技大本營(yíng)（ID：rgznai100）

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

在 Manus 項(xiàng)目伊始，我和團(tuán)隊(duì)面臨一個(gè)關(guān)鍵抉擇：是應(yīng)該利用開源基礎(chǔ)模型來(lái)訓(xùn)練一個(gè)端到端的 Agent，還是基于前沿模型的上下文學(xué)習(xí)（in-context learning）能力來(lái)構(gòu)建？

回溯我從事自然語(yǔ)言處理（NLP）的頭十年，我們根本沒(méi)有這樣的選擇。在遙遠(yuǎn)的 BERT 時(shí)代（是的，已經(jīng)七年了），模型必須先經(jīng)過(guò)微調(diào)和評(píng)估，才能勝任新任務(wù)。盡管那時(shí)的模型比今天的大語(yǔ)言模型（LLM）小得多，但這個(gè)過(guò)程每次迭代仍需數(shù)周。

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

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

即便如此，上下文工程的實(shí)踐之路也遠(yuǎn)非一帆風(fēng)順。它是一門實(shí)驗(yàn)科學(xué)——我們已經(jīng)重構(gòu)了四次 Agent 框架，每一次都是因?yàn)榘l(fā)現(xiàn)了塑造上下文的更優(yōu)方法。我們將這種手動(dòng)進(jìn)行架構(gòu)搜索、調(diào)試提示（prompt）和憑經(jīng)驗(yàn)猜測(cè)的摸索過(guò)程，戲稱為“隨機(jī)研究生下降”（Stochastic Graduate Descent）——這是對(duì)“隨機(jī)梯度下降”（Stochastic Gradient Descent）的一個(gè)文字游戲。這個(gè)方法聽起來(lái)不那么優(yōu)雅，但確實(shí)有效。

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

圍繞 KV 緩存進(jìn)行設(shè)計(jì)

如果非要我只選一個(gè)指標(biāo)，我認(rèn)為KV緩存命中率（KV-cache hit rate）是生產(chǎn)級(jí) AI Agent 最重要的單一指標(biāo)，因?yàn)樗苯佑绊懷舆t和成本。要理解這一點(diǎn)，我們先來(lái)看看一個(gè)典型 Agent 的工作流程：

收到用戶輸入后，Agent 會(huì)通過(guò)一系列工具調(diào)用來(lái)完成任務(wù)。在每次迭代中，模型根據(jù)當(dāng)前上下文，從預(yù)定義的操作空間中選擇一個(gè)動(dòng)作。該動(dòng)作在環(huán)境（如 Manus 的虛擬機(jī)沙箱）中執(zhí)行后，產(chǎn)生一個(gè)觀察結(jié)果。這個(gè)動(dòng)作和觀察結(jié)果會(huì)被追加到上下文中，作為下一次迭代的輸入。此循環(huán)不斷重復(fù)，直至任務(wù)完成。

可以想見，上下文會(huì)隨著每一步而增長(zhǎng)，而輸出——通常是一個(gè)結(jié)構(gòu)化的函數(shù)調(diào)用——?jiǎng)t相對(duì)較短。這使得 Agent 的輸入與輸出 token 比例，和聊天機(jī)器人相比嚴(yán)重失衡。例如，在 Manus 中，這個(gè)比例平均約為 100:1。

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

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

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

2. 讓上下文只增不減（append-only）。避免修改歷史動(dòng)作或觀察結(jié)果。同時(shí)要確保序列化過(guò)程是確定性的。許多編程語(yǔ)言和庫(kù)在序列化 JSON 對(duì)象時(shí)，不保證鍵的順序穩(wěn)定，這會(huì)悄無(wú)聲息地破壞緩存。

3. 在需要時(shí)明確標(biāo)記緩存斷點(diǎn)。一些模型提供商或推理框架不支持自動(dòng)的增量前綴緩存，需要手動(dòng)在上下文中插入緩存斷點(diǎn)。在設(shè)置斷點(diǎn)時(shí)，要考慮到緩存的生命周期，并至少確保斷點(diǎn)設(shè)在系統(tǒng)提示之后。

此外，如果你在使用 vLLM 等框架自托管模型，請(qǐng)確保啟用了前綴/提示緩存功能，并使用會(huì)話 ID 等技術(shù)，將來(lái)自同一用戶的請(qǐng)求持續(xù)路由到固定的工作節(jié)點(diǎn)上。

AI產(chǎn)品爆發(fā)，但你的痛點(diǎn)解決了嗎?8.15-16 北京威斯汀·全球產(chǎn)品經(jīng)理大會(huì)PM-Summit，3000+AI產(chǎn)品人社群已就位。

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

進(jìn)群后，您將有機(jī)會(huì)得到：

· 最新、最值得關(guān)注的 AI 產(chǎn)品資訊及大咖洞見

· 獨(dú)家視頻及文章解讀 AGI 時(shí)代的產(chǎn)品方法論及實(shí)戰(zhàn)經(jīng)驗(yàn)

· 不定期贈(zèng)送AI產(chǎn)品干貨資料和秘籍

巧用掩碼，而非直接移除

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

一個(gè)自然的想法是設(shè)計(jì)一個(gè)動(dòng)態(tài)的操作空間——比如用類似 RAG 的方式按需加載工具。我們?cè)?Manus 中也嘗試過(guò)。但實(shí)驗(yàn)得出了一個(gè)明確的結(jié)論：除非絕對(duì)必要，否則不要在迭代過(guò)程中動(dòng)態(tài)增刪工具。主要原因有二：

1. 在大多數(shù) LLM 中，工具定義在序列化后位于上下文的前部，通常緊跟在系統(tǒng)提示之后。因此，任何改動(dòng)都會(huì)導(dǎo)致后續(xù)所有動(dòng)作和觀察結(jié)果的 KV 緩存全部失效。

2. 如果歷史動(dòng)作和觀察結(jié)果引用了當(dāng)前上下文中已不復(fù)存在的工具，模型就會(huì)感到困惑。若不進(jìn)行約束解碼，這通常會(huì)導(dǎo)致輸出格式錯(cuò)誤（schema violation）或產(chǎn)生幻覺(jué)動(dòng)作。

為了解決這個(gè)問(wèn)題，同時(shí)又能優(yōu)化動(dòng)作選擇，Manus 采用了一個(gè)感知上下文的狀態(tài)機(jī)來(lái)管理工具的可用性。它并非直接移除工具，而是在解碼階段對(duì) token 的對(duì)數(shù)幾率（logits）進(jìn)行掩碼（masking），從而根據(jù)當(dāng)前狀態(tài)，阻止或強(qiáng)制模型選擇某些動(dòng)作。

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

• 自動(dòng)（Auto）：模型可自行決定是否調(diào)用函數(shù)。通過(guò)預(yù)填充回復(fù)前綴 <|im_start|>assistant 實(shí)現(xiàn)。

• 必需（Required）：模型必須調(diào)用一個(gè)函數(shù)，但可自由選擇。通過(guò)預(yù)填充至 <|im_start|>assistant 實(shí)現(xiàn)。

• 指定（Specified）：模型必須從一個(gè)給定的子集中選擇函數(shù)。通過(guò)預(yù)填充至函數(shù)名開頭，如 <|im_start|>assistant {"name": "browser_ 實(shí)現(xiàn)。

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

這些設(shè)計(jì)確保了 Manus Agent 的執(zhí)行循環(huán)，即便在模型驅(qū)動(dòng)的架構(gòu)下，也能保持高度的穩(wěn)定性。

將文件系統(tǒng)作為外部上下文

當(dāng)前的前沿 LLM 已提供 128K 甚至更長(zhǎng)的上下文窗口。但在真實(shí)的 Agent 場(chǎng)景中，這往往還不夠，有時(shí)甚至是一種負(fù)擔(dān)。以下是三個(gè)常見痛點(diǎn)：

1. 觀察結(jié)果可能極其龐大，尤其是當(dāng) Agent 與網(wǎng)頁(yè)、PDF 等非結(jié)構(gòu)化數(shù)據(jù)交互時(shí)，極易超出上下文長(zhǎng)度限制。

2. “大海撈針”問(wèn)題，即模型性能在上下文長(zhǎng)度超過(guò)某一閾值后會(huì)開始下降，即便窗口在技術(shù)上仍未溢出。

3. 成本高昂，即使有前綴緩存，你仍需為傳輸和預(yù)填充每個(gè) token 付費(fèi)。

為了應(yīng)對(duì)這些問(wèn)題，許多 Agent 系統(tǒng)采用了上下文截?cái)嗷驂嚎s策略。但過(guò)于激進(jìn)的壓縮必然導(dǎo)致信息丟失。這是一個(gè)根本性矛盾：Agent 的天性決定了它必須基于所有歷史狀態(tài)來(lái)預(yù)測(cè)下一步動(dòng)作，而你無(wú)法可靠地預(yù)知哪個(gè)觀察結(jié)果會(huì)在十步之后變得至關(guān)重要。從邏輯上講，任何不可逆的壓縮都伴隨著風(fēng)險(xiǎn)。

因此，在 Manus 中，我們將文件系統(tǒng)視為最終的上下文：它容量無(wú)限，天然持久，且能被 Agent 直接操作。我們訓(xùn)練模型按需讀寫文件，將文件系統(tǒng)不僅用作存儲(chǔ)，更用作一種結(jié)構(gòu)化的外部記憶。

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

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

通過(guò)復(fù)述（Recitation）操控注意力

如果你使用過(guò) Manus，可能會(huì)注意到一個(gè)有趣的現(xiàn)象：在處理復(fù)雜任務(wù)時(shí)，它會(huì)創(chuàng)建一個(gè) todo.md 文件，并隨著任務(wù)的推進(jìn)逐步更新，勾掉已完成的項(xiàng)。

這并非簡(jiǎn)單的裝飾行為，而是一種有意為之的注意力操控機(jī)制。

在 Manus 中，一個(gè)典型任務(wù)平均需要約 50 次工具調(diào)用。這是一個(gè)相當(dāng)長(zhǎng)的執(zhí)行鏈。由于 Manus 的決策依賴 LLM，它很容易在長(zhǎng)上下文或復(fù)雜任務(wù)中偏離主題或忘記早期目標(biāo)。

通過(guò)不斷重寫這個(gè)待辦事項(xiàng)列表，Manus 相當(dāng)于在將它的核心目標(biāo)“復(fù)述”到上下文的末尾。這使得全局計(jì)劃始終處于模型近期的注意力范圍內(nèi)，有效避免了“迷失在中間”（lost-in-the-middle）的問(wèn)題，降低了目標(biāo)漂移的風(fēng)險(xiǎn)。實(shí)際上，它是在用自然語(yǔ)言來(lái)引導(dǎo)自身的注意力，使其聚焦于任務(wù)目標(biāo)，而無(wú)需任何特殊的架構(gòu)調(diào)整。

保留失敗的嘗試

Agent 會(huì)犯錯(cuò)。這不是缺陷，而是現(xiàn)實(shí)。語(yǔ)言模型會(huì)產(chǎn)生幻覺(jué)，環(huán)境會(huì)返回錯(cuò)誤，外部工具會(huì)出故障，各種意想不到的邊緣情況總會(huì)發(fā)生。在多步驟任務(wù)中，失敗不是例外，而是循環(huán)的一部分。

然而，人們有一種常見的沖動(dòng)，想要隱藏這些錯(cuò)誤：清理執(zhí)行記錄、重試動(dòng)作，或者重置模型狀態(tài)，然后寄希望于調(diào)高“temperature”參數(shù)來(lái)“隨機(jī)”出正確結(jié)果。這看似更安全、更可控，但代價(jià)是：抹去失敗，也就抹去了學(xué)習(xí)的證據(jù)。沒(méi)有證據(jù)，模型就無(wú)法適應(yīng)和改進(jìn)。

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

事實(shí)上，我們認(rèn)為錯(cuò)誤恢復(fù)（error recovery）能力是衡量真正 Agent 智能最清晰的標(biāo)志之一。然而，在大多數(shù)學(xué)術(shù)研究和公開基準(zhǔn)測(cè)試中，這一點(diǎn)仍然被嚴(yán)重低估，它們往往只關(guān)注理想條件下的任務(wù)成功率。

警惕少樣本提示的陷阱

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

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

這在涉及重復(fù)性決策或動(dòng)作的任務(wù)中尤其危險(xiǎn)。例如，在使用 Manus 審閱 20 份簡(jiǎn)歷時(shí)，Agent 常常會(huì)陷入一種固定的節(jié)奏——僅僅因?yàn)樯舷挛闹谐錆M了類似的操作記錄，它就開始機(jī)械地重復(fù)這些動(dòng)作。這會(huì)導(dǎo)致行為漂移、過(guò)度泛化，有時(shí)甚至產(chǎn)生幻覺(jué)。

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

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

結(jié)語(yǔ)

上下文工程仍是一門新興的科學(xué)，但對(duì)于 Agent 系統(tǒng)而言，它已是成功的基石。模型也許正變得更強(qiáng)、更快、更便宜，但任何原始能力的提升，都無(wú)法取代對(duì)記憶、環(huán)境和反饋的精心設(shè)計(jì)。你如何塑造上下文，最終決定了你的 Agent 將如何行事：它的運(yùn)行速度、糾錯(cuò)能力，以及擴(kuò)展的潛力。

在 Manus，我們通過(guò)一次次的重構(gòu)、失敗的嘗試以及對(duì)數(shù)百萬(wàn)用戶的真實(shí)世界測(cè)試，才學(xué)到了這些經(jīng)驗(yàn)。本文分享的并非放之四海而皆準(zhǔn)的真理，但它們是于我們行之有效的模式。如果這些經(jīng)驗(yàn)?zāi)軒椭隳呐轮槐苊庖淮瓮纯嗟牡?，那這篇文章就實(shí)現(xiàn)了它的價(jià)值。

Agent 的未來(lái)，將由一個(gè)個(gè)上下文精心構(gòu)建而成。

AI 產(chǎn)品爆發(fā)，但你的痛點(diǎn)解決了嗎？

2025 全球產(chǎn)品經(jīng)理大會(huì)

8 月 15–16 日

北京·威斯汀酒店

互聯(lián)網(wǎng)大廠、AI 創(chuàng)業(yè)公司、ToB/ToC 實(shí)戰(zhàn)一線的產(chǎn)品人

12 大專題分享，洞察趨勢(shì)、拆解路徑、對(duì)話未來(lái)。

立即掃碼領(lǐng)取大會(huì)PPT

搶占 AI 產(chǎn)品下一波紅利