上下文工程：構建高效、可恢復、可擴展智能體的系統方法
本文翻譯整理自?Yichao “Peak” Ji 于 2025 年 7 月 18 日發表的文章《Context Engineering for AI Agents》，并結合 dev.to 社區和 r/MachineLearning 討論進行補充。
https://medium.com/@peakji/context-engineering-for-ai-agents-lessons-from-building-manus-71883f0a67f2
一、Context Engineering 勝于重訓模型
在 Manus 項目早期，團隊面臨兩個方向選擇：訓練專屬 Agent 模型，還是基于最先進 LLM 做“上下文工程”。歷史告訴我們：BERT 微調時代迭代慢、成本高，GPT-3 出現后 in-context 的范式更靈活。所以，Manus 堅決押注上下文工程：
- 迭代周期從周級 -> 小時級；
- 與底層模型解耦，可以隨模型能力提升迅速接入新能力。
二、KV?Cache 命中率：主導 latency 與成本的關鍵指標
上下文增長快是 Agent 的常態。Manus 統計上下文輸入輸出比為 100:1。因此：
- KV?Cache 命中率直接決定延遲（TTFT）與費用。
- 以 Claude?Sonnet 為例：緩存命中 token 約 $0.30/百萬，冷緩存則約 $3/百萬，10 倍差距。
實踐建議：
1. 前綴穩定：去除每次調用中可能變化的元素，如時間戳等。
2. 追加不修改上下文，不變序列化順序。
3. 手動 cache breakpoints，保障緩存失效時有明確切割 (manus.im)。
三、Mask 不 Remove：靜態定義 + 動態遮-mask
Agent 中工具（function calls）爆炸增長，會導致：
- Context 改動 → KV?cache 無效；
- 上下文歷史中提到的工具如果被刪除，容易混淆或造成幻覺。
Manus 的策略：
- 保留所有工具定義不變；
- 根據當前狀態，用logits mask 阻止模型選用不應啟用的工具；
- 對命名做統一前綴（如browser_,shell_），便于批量 mask 控制。
四、用本地文件系統擴展上下文長度
上下文窗口雖已 128K+，但實際 agent 場景仍有三大痛點：
1. 大量網頁/PDF內容會迅速用滿上下文；
2. 非結構化文本過長會拖慢模型；
3. 即使有緩存，傳輸與 KV-prefill 費用仍高。
Manus 的實踐：
- 將歷史記錄寫入 sandbox 文件系統；
- 上下文中只保留路徑和摘要——如網頁 URL 而非全文；
- 模型按需讀取、重構 Context；
- 所有壓縮手段可逆，能按需完全恢復信息。
五、Recitation 技巧：todo.md 持續強化注意力機制
復雜任務中，Manus 往往包含 50+ 次工具調用。在這種長循環里容易 “中途走神”。
解決方式：
- 使用todo.md 文件存儲當前待辦列表；
- 每輪迭代追加檢查，結束后 recitation（復述）到上下文結尾；
- 自然語言將全程焦點重新引導進 attention window，避免任務漂移。
六、錯誤保留 ≠ 隱藏
Agent 執行失敗是在所難免的事實。Manus 的做法是：
- 不隱藏錯誤輸出，而是將 stack trace / error 留在上下文；
- 這相當于給模型一個 implicit 學習信號，告訴它“這類操作容易失敗”，減少重復錯誤。
如 LinkedIn 上總結所說：“leaving error information … helps models avoid repeating mistakes”
七、不要陷入 Few-shot 模式化陷阱
Few-shot 能改善單步輸出，但會導致 Agent 在長任務中陷入“套路化”模式：
- Manus 遇到簡歷批處理等任務時，若上下文模板一致，容易反復走相似路徑 → 發散或幻覺。
對策：
- 在示例 action-observation 中引入微小變化：模板排版、措辭、序列調整；
- 控制隨機性“打散”套路，讓模型對不同情況適應更靈活。
八、Stochastic Graduate Descent：上下文架構的實驗式重構
上下文工程不是理論推導，而是 “實驗科學”。Manus 已重構框架 4 次，每一次都是為了優化 context 結構、prompt 機制、cache 效率等指標 (manus.im)。
團隊稱此過程為“Stochastic Graduate Descent”：在 prompt + 架構空間持續迭代搜索 → 不聰明，但實用奏效。
小結：Manus 提煉的上下文工匠心法
方法 | 目的 | 效果 |
前綴穩定 + append?only | 提升 KV?Cache 命中率 | ?? 延遲 & 成本，快速響應 |
Mask 不 Remove 工具 | 控制 action 空間 | 避免 cache 斷裂、context confusion |
文件系統做上下文擴展 | 實現無限上下文 | 支持長任務與恢復能力 |
todo.md Recitation | 強化注意力 | 減少任務漂移、中途 off?target |
錯誤上下文保留 | 引導模型學習失敗 | 提高魯棒、降低重復出錯 |
Few-shot 多樣化 | 避免套路陷阱 | 增強靈活性與準確率 |
多輪 SGD 實踐迭代 | 提煉工程思路 | 快速優化與系統穩定性提升 |
未來展望：從 Transformer 到 SSM-contextual Agents
最后，作者提出一個大膽愿景：如果 SSM（State Space Models）能配合“文件記憶”機制，解決跨長距離依賴問題，它們也許能成為真正高效的 Agent engine，繼承 Neural Turing Machine 的設想。
寫在最后
上下文工程不是“高級技巧”，而是構建高效 AI Agent 的 必須工序。Manus 用真金白銀和使用反饋告訴我們：只有結構良好、緩存高效、上下文完整、行為魯棒、可恢復、可管理，智能 Agent 才可能從實驗室走向產線上線。?
本文轉載自????PyTorch研習社????，作者：南七無名士
