大家好，我是玄姐。

在 Manus 項目啟動之初，團隊面臨一個關鍵抉擇：是基于開源基礎模型訓練端到端的智能體，還是借助前沿模型的核心能力搭建 AI 智能體？回溯 NLP 生涯前十年，我們根本沒有這樣的選擇余地。在七年前的 BERT 時代，模型必須經過繁瑣的微調與評估，才能遷移到新任務中，即便這些模型相較于如今的 LLM 體積小巧，每次迭代仍需耗費數周時間。對于亟待快速迭代的應用而言，尤其是在尚未實現產品市場匹配（PMF）的階段，這種緩慢的反饋循環堪稱致命缺陷。這是上一個創業項目的慘痛教訓：當時我們從零開始訓練模型，用于開放信息提取與語義搜索，可 GPT-3 與 Flan-T5 的橫空出世，讓我們的自研模型一夜之間淪為雞肋。頗具諷刺意味的是，正是這些模型開啟了上下文學習的全新賽道，指明了截然不同的前進方向。

這段來之不易的經歷讓決策變得清晰：Manus 果斷押注上下文工程。這一選擇不僅讓我們的產品改進周期從數周壓縮至數小時，更讓產品與底層模型保持了靈活的適配性，若將模型進步比作上漲的潮水，我們希望 Manus 是順勢航行的船，而非固定在海床的柱。

然而，上下文工程絕非易事，它更像是一門實驗科學。我們先后四次重構智能體框架，每一次都是在探索出更優的上下文塑造方式后推倒重來。我們戲稱這種手動調整架構、優化提示詞與反復試錯的過程為 “隨機研究生下降”（SGD），雖不優雅，卻行之有效。本文將分享我們通過這套 “SGD” 方法摸索出的實踐心得，希望能幫助正在構建 AI 智能體的開發者少走彎路，更快找到最優解。

一、圍繞 KV 緩存設計：把控核心性能指標

若要挑選一個生產環境中 AI 智能體的關鍵指標，我認為 KV 緩存命中率當之無愧，它直接決定了系統的響應延遲與運營成本。要理解其重要性，首先需明確 AI 智能體的工作邏輯：

接收用戶輸入后，智能體會通過一系列工具調用鏈推進任務。每一輪迭代中，模型會根據當前上下文，從預定義的動作空間中選擇合適動作，在環境（例如：Manus 的虛擬機沙盒）中執行后產生觀察結果，而動作與觀察結果會持續追加到上下文，作為下一輪迭代的輸入。這個循環會一直持續到任務完成。

不難想象，隨著迭代推進，上下文會不斷膨脹，但輸出（通常是結構化的函數調用）卻相對簡短。這使得智能體的輸入與輸出 token 比例嚴重傾斜，以 Manus 為例，平均比例約為 100:1。幸運的是，擁有相同前綴的上下文可借助 KV 緩存技術，大幅降低首個 token 生成時間（TTFT）與推理成本，無論你使用自托管模型還是調用推理 API，節省效果都十分顯著：以 Claude Sonnet 為例，緩存后的輸入 token 成本僅為 0.30 美元 / 百萬 token，未緩存則高達 3 美元 / 百萬 token，差距達 10 倍。

從上下文工程角度，提升 KV 緩存命中率需遵循三大核心實踐：

1. 保持提示詞前綴穩定：LLM 的自回歸特性決定了，哪怕單個 token 的差異，都會導致該 token 后的緩存失效。常見誤區是在系統提示詞開頭加入精確到秒的時間戳，雖能讓模型獲取當前時間，卻會嚴重拉低緩存命中率；
2. 采用 “只追加” 式上下文：避免修改歷史動作或觀察結果，同時確保序列化過程的確定性，許多編程語言和庫在序列化 JSON 時不保證鍵順序穩定，這可能會隱性破壞緩存；
3. 明確標記緩存斷點：部分模型提供商或推理框架不支持自動增量前綴緩存，需手動在上下文中插入斷點。設置斷點時需考慮緩存過期問題，且至少要包含系統提示詞的結尾部分。

# 系統提示詞（固定不變的基礎規則+結構化工具定義）
你是一個數據分析智能體，只能使用以下工具處理數據：
1. 數據導入工具：導入指定數據表，參數：table_name（必填）、time_range（可選）；
2. 篩選工具：篩選數據維度，參數：region（可選）、date（可選）；
3. 計算工具：計算統計指標，參數：indicator（必填，支持同比增長率/環比增長率）。
處理步驟：1. 解析用戶需求；2. 選擇工具；3. 執行并返回結果。


## 第1輪對話
用戶需求：分析2025年Q3的銷售數據；
代理動作：調用“數據導入工具”，參數：{"table_name": "2025Q3_sales", "time_range": "2025-07-01至2025-09-30"}；
執行結果：成功導入2025年Q3銷售數據表，包含全國各地區銷售額、客單價等字段，共1200條數據。


## 第2輪對話
用戶補充需求：只看華東地區的數據，先篩選再計算；
代理動作：調用“篩選工具”，參數：{"region": "華東地區"}；
執行結果：成功篩選出華東地區Q3銷售數據，共320條，涉及上海、江蘇、浙江、安徽4個省份。


# 固定引導語（穩定前綴，避免系統提示微調導致緩存失效）
以下是當前任務的動態上下文：
<!-- CACHE_BREAKPOINT -->  # 緩存斷點（固定位置，始終在系統提示+引導語之后）
# 斷點之后：動態上下文（順序追加）


# 最新待處理需求（第3輪要執行的新內容）
用戶需求：計算華東地區Q3銷售額同比增長率；

此外，若使用 vLLM 等框架自托管模型，需確保啟用前綴 / 提示詞緩存，并通過會話 ID 等技術，在分布式工作節點間實現請求的一致路由。

二、遮蔽而非移除：穩定動作空間

隨著智能體能力增強，其動作空間會自然變得復雜，本質上是工具數量的爆炸式增長，而近期流行的 MCP（多工具組合平臺）更讓這一問題雪上加霜。若允許用戶自定義工具，必然會出現數百個功能不明的工具被插入到精心設計的動作空間中的情況，導致模型更易選擇錯誤動作或低效路徑，讓 “武裝過度” 的智能體反而變得 “愚蠢”。

面對這一問題，常見思路是設計動態動作空間，比如采用類似 RAG 的方法按需加載工具。在 Manus 中也曾嘗試過這種方案，但實驗結果明確了一條規則：除非絕對必要，否則避免在迭代過程中動態添加或移除工具。原因有二：

1. 大多數 LLM 中，工具定義序列化后會位于上下文前部（通常在系統提示詞前后），任何修改都會導致后續所有動作和觀察結果的 KV 緩存失效；
2. 若歷史動作與觀察結果仍引用當前上下文已移除的工具，模型會陷入困惑，在無約束解碼的情況下，極易出現模式違規或幻覺動作。

為解決這一問題并優化動作選擇，Manus 采用上下文感知的狀態機管理工具可用性：不直接移除工具，而是在解碼過程中掩蔽 token 的 logits，基于當前上下文阻止或強制選擇特定動作。

在實踐中，多數模型提供商與推理框架支持響應預填充功能，可在不修改工具定義的前提下約束動作空間。函數調用通常包含三種模式（以 NousResearch 的 Hermes 格式為例）：

• 自動模式：模型可自主選擇是否調用函數，僅需預填充回復前綴：??<<|im_start|>assistant??；
• 必需模式：模型必須調用函數，選擇不受約束，預填充至工具調用令牌：??<<|im_start|>assistant<tool_call>??；
• 指定模式：模型需從特定工具子集選擇調用，預填充至函數名稱開頭：??<<|im_start|>assistant<tool_call>{"name": "browser_??。

我們一起看個電商客服智能體的案例如下：

假設你在做一個「電商客服 AI 智能體」，需要用到這些工具：

• 瀏覽器工具（??browser_查詢訂單???、??browser_查詢物流??）
• 命令行工具（??shell_修改地址???、??shell_發起退款??）
• 表單工具（??form_收集售后信息??）總共 5 個工具，全部寫在系統提示里，不會刪除。

現在遇到兩個核心問題：

1. 用戶剛發消息 “查一下我的訂單”，此時 AI 應該只調用瀏覽器工具，不能選退款、收集信息工具；
2. 后續用戶說 “想退款”，AI 應該只能選退款和查詢訂單工具（查訂單確認信息后才能退款），不能選物流查詢、修改地址工具。

按 “動態移除工具” 和 “遮蔽工具” 兩種方式對比，就能明白區別：

第一、先看「動態移除工具」的坑（為什么不能這么做）

如果用 “動態移除” 思路，處理用戶 “查訂單” 需求時，會把系統提示里的 ??shell_修改地址???、??shell_發起退款???、??form_收集售后信息?? 這 3 個工具刪掉，只留瀏覽器工具。

• 坑 1：工具定義在上下文前部，刪除后，后面的歷史對話（比如之前用戶問過物流）的 KV 緩存全失效，下一輪請求要重新計算，延遲變高；
• 坑 2：如果歷史對話里提到過 “退款”（比如用戶之前問過 “能退款嗎”），現在工具里沒了??shell_發起退款??，AI 會困惑：“之前說的退款工具去哪了？” 可能亂選工具或胡言亂語。

第二、再看「遮蔽工具」的正確操作（一步步實操）

我們不刪除任何工具，而是通過「預填充回復前綴」+「工具統一前綴」，讓 AI “看不見” 不該選的工具（即遮蔽），具體分 3 種情況：

情況 1：用戶剛發消息，AI 需先回復確認（自動模式）

用戶輸入：“在嗎？我想查訂單”此時 AI 不能直接調用工具，得先回應用戶，再問訂單號 —— 用「自動模式」遮蔽所有工具調用：

• 預填充回復前綴：??<<|im_start|>assistant??
• 效果：AI 只能輸出自然語言回復（比如 “你好呀！請告訴我你的訂單號，我幫你查詢～”），沒法調用任何工具（因為沒觸發??tool_call??令牌，工具相關的 token 被遮蔽了）。

情況 2：用戶提供訂單號，AI 必須調用工具（必需模式）

用戶補充：“訂單號是 123456”此時 AI 必須調用工具，不能再閑聊 —— 用「必需模式」遮蔽 “自然語言回復”，只允許調用工具：

• 預填充回復前綴：??<<|im_start|>assistant<tool_call>??
• 效果：AI 只能輸出工具調用格式（比如??{"name": "browser_查詢訂單", "parameters": {"order_id": "123456"}}??），沒法說廢話，且能選所有工具（但我們下一步會進一步限制）。

情況 3：用戶查訂單，AI 只能選瀏覽器工具（指定模式）

接著上面的場景，AI 必須調用 “查詢訂單” 工具，不能選退款、修改地址 —— 用「指定模式」遮蔽其他工具，只允許選瀏覽器工具：

• 預填充回復前綴：??<<|im_start|>assistant<tool_call>{"name": "browser_??
• 效果：AI 只能在 “browser_” 開頭的工具里選（即??browser_查詢訂單???、??browser_查詢物流???），沒法選??shell_???或??form_???開頭的工具（這些工具的 token 被遮蔽了，AI “看不見”）。最終 AI 會輸出：??<<|im_start|>assistant<tool_call>{"name": "browser_查詢訂單", "parameters": {"order_id": "123456"}}??

情況 4：用戶后續說 “想退款”（切換指定模式）

用戶輸入：“訂單查到了，我想退款”此時 AI 只能選??shell_發起退款???和??browser_查詢訂單??（查訂單確認狀態）—— 用「指定模式」+「工具前綴」：

• 預填充回復前綴：??<<|im_start|>assistant<tool_call>{"name": "??
• 同時利用工具統一前綴：告訴 AI“只能選 browser_或 shell_開頭的工具，且優先 shell_發起退款”（不用刪工具，只是遮蔽其他前綴的工具）。
• 效果：AI 只能選??browser_查詢訂單???（二次確認）或??shell_發起退款???，不會選??form_收集售后信息??這類無關工具。

#舉個 System Prompt 的實際寫法（電商客服場景）
你是電商客服AI智能體，需遵循以下模式規則：
1. 模式類型及觸發條件：
   - 自動模式：用戶剛發起對話、需求模糊（無具體參數）、咨詢規則時，可自主選擇自然語言回復或調用工具，回復開頭無強制前綴，僅需符合對話邏輯；
   - 必需模式：用戶提供明確參數（如訂單號、地址）、需要查實時數據（物流/訂單）或執行操作（退款/改地址）時，必須調用工具，不能閑聊，回復開頭必須是<tool_call>{"name": "；
   - 指定模式：用戶需求明確指向某類工具（如“查訂單”“退款”）時，必須調用對應前綴的工具（查訂單→browser_開頭，退款→shell_開頭），回復開頭必須是<tool_call>{"name": "工具前綴"（如browser_、shell_）；
2. 工具列表（永久保留，不刪除）：
   - browser_查詢訂單（參數：order_id）、browser_查詢物流（參數：order_id）；
   - shell_修改地址（參數：order_id、new_address）、shell_發起退款（參數：order_id、reason）；
   - form_收集售后信息（參數：problem、contact）；
3. 輸出要求：嚴格按當前模式的預填充開頭續寫，不偏離格式，不調用無關工具。

通過這種方式，我們可直接通過掩碼 token 的 logits 約束動作選擇。例如，當用戶提供新輸入時，Manus 需立即回復而非執行動作。同時，我們為同類工具設計了統一前綴（如瀏覽器工具以??browser_???開頭，命令行工具以??shell_??開頭），無需依賴有狀態的 logits 處理器，即可輕松確保智能體在特定狀態下僅從指定工具組中選擇，保障智能體循環的穩定性。

三、以文件系統為上下文：突破窗口限制

現代前沿 LLM 的上下文窗口已擴展至 128K 令牌甚至更高，但在真實的代理應用場景中，這一容量仍顯不足，有時甚至會成為負擔，主要存在三大痛點：

1. 觀察結果可能異常龐大，尤其是代理與網頁、PDF 等非結構化數據交互時，極易超出上下文限制；
2. 超過一定上下文長度后，即便模型技術上支持該窗口大小，性能也會明顯下降；
3. 長輸入的傳輸與預填充成本高昂，即便使用前綴緩存，仍需為每個 token 付費。

為解決這一問題，許多代理系統采用上下文截斷或壓縮策略，但過度激進的壓縮必然導致信息丟失。從邏輯層面看，代理需基于所有歷史狀態預測下一個動作，而我們無法預判哪些觀察結果會在后續步驟中發揮關鍵作用，因此任何不可逆的壓縮都存在風險。

正是基于這一考量，Manus 將文件系統視為 “終極上下文”—— 它不僅容量無限制、天然支持持久化，還能被代理直接操作。模型會學會按需讀寫文件，將文件系統既作為存儲介質，也作為結構化的外部記憶。我們的壓縮策略始終遵循 “可恢復性” 原則：例如，移除網頁內容時保留 URL，省略文檔內容時保留沙盒中的文件路徑，確保在縮短上下文長度的同時，不永久丟失關鍵信息。

在開發這一功能時，我不禁思考狀態空間模型（SSM）在智能體環境中的應用潛力。與 Transformer 不同，SSM 缺乏完整的注意力機制，處理長距離后向依賴的能力較弱，但如果能讓它們掌握基于文件的記憶方式 —— 將長期狀態外部化而非存儲在上下文中，其速度與效率優勢或許能催生出全新類型的智能體，成為神經圖靈機的真正繼任者。

四、通過復述操控注意力：錨定核心目標

Manus 處理復雜任務時，平均需要約 50 次工具調用。如此長的循環中，依賴 LLM 做決策的智能體極易偏離主題，或忘記早期設定的目標，尤其是在長上下文或復雜任務場景中，“丟失在中間” 的問題尤為突出。

對此，我們設計了一種刻意的注意力操控機制：Manus 會創建??todo.md??文件，在任務推進過程中持續更新，通過反復重寫待辦事項列表，將目標 “復述” 到上下文末尾。這一操作能將全局計劃納入模型的近期注意力范圍，有效避免目標偏移，減少行動與目標的不一致性。本質上，這是通過自然語言引導模型注意力偏向核心任務，無需對模型架構做任何特殊修改，卻能顯著提升任務完成度。

五、保留錯誤內容：助力自主迭代優化

智能體犯錯是不可避免的現實，語言模型會產生幻覺、環境會返回錯誤、外部工具可能出現異常，意外的邊緣情況隨時可能發生。在多步驟任務中，失敗不是例外，而是循環的一部分。

面對錯誤，許多團隊的本能反應是 “掩蓋痕跡”：清理錯誤記錄、重試操作，或重置模型狀態，寄希望于通過調整 “溫度” 參數解決問題。這種做法看似更安全可控，卻存在隱性代價：擦除失敗痕跡意味著模型失去了學習的依據，沒有這些證據，模型無法調整自身行為，自然難以避免重復犯錯。

根據我們的實踐經驗，改善智能體行為的有效方法出奇地簡單：將錯誤嘗試完整保留在上下文中。當模型看到失敗的動作、對應的觀察結果或堆棧跟蹤時，會隱性更新內部信念，調整決策先驗，從而降低重復犯錯的概率。事實上，我們認為錯誤恢復能力是真正代理行為的核心標志之一，但這一點在當前多數學術研究與公共基準測試中仍未得到充分關注， 它們往往更側重理想條件下的任務成功率。

六、打破少樣本局限：注入受控隨機性

少樣本提示是提升 LLM 輸出一致性的常用技術，但在代理系統中，它可能會以微妙的方式適得其反。語言模型本質上是優秀的模仿者，會復刻上下文的行為模式。如果上下文充斥著重復的行動 - 觀察對，模型會傾向于沿用該模式，即便它已不再是最優選擇。

這一問題在涉及重復決策或動作的任務中尤為危險。例如，使用 Manus 審查 20 份簡歷時，智能體可能會陷入固定節奏，僅僅因為上下文呈現的都是類似行動，就機械重復相同操作，最終導致目標偏離、過度泛化甚至產生幻覺。

解決這一問題的關鍵在于增加多樣性。Manus 會在行動與觀察的呈現中，引入少量結構化變化，比如采用不同的序列化模板、替代性措辭，或在順序、格式上加入微小 “噪音”。這種受控的隨機性能有效打破固有模式，調整模型注意力，避免智能體陷入少樣本學習的窠臼。換句話說，上下文的單一性會導致智能體的脆弱性，適度的變化才能提升系統的魯棒性。

七、結語

上下文工程雖仍是一門新興科學，卻已成為 AI 智能體開發的核心支柱。無論底層模型如何迭代升級，變得更強大、更快速、更經濟，都無法替代對記憶管理、環境交互與反饋機制的優化，如何塑造上下文，最終決定了智能體的運行速度、恢復能力與擴展邊界。

這些經驗源于 Manus 團隊的反復試錯、無數次彎路，以及面向數百萬用戶的實戰檢驗。我們分享的并非放之四海而皆準的真理，而是經過實踐驗證的有效模式。如果這些內容能幫助你避免哪怕一次痛苦的迭代，這篇文章便實現了它的價值。

智能體的未來，正在于每一個精心設計的上下文。愿你能在實踐中不斷探索，構建出更強大的智能系統。

好了，這就是我今天想分享的內容。

本文轉載自??玄姐聊AGI??  作者：玄姐