100:1性能優化：基于 Manus 看 Agent 的上下文工程優秀實踐
Manus 近天在其官網發布了一篇關于構建上下文工程的 Blog 文章，本來打算學習下公開的解讀文章，但發現大部分自媒體都是把原文簡單翻譯了下，沒有過多的進一步拆解。沒辦法我就自己昨天花了半天時間研讀了下，發現其中的確很多值得學習的工程技巧，so 有了這篇。
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
總體來說，Manus 團隊分享的五個工程實踐經驗，最大的價值在于其普適性。但需要說明的是，這些工程經驗更適合需要精細控制的場景。對于 RAGFlow、Dify 這類高度封裝的開源框架來說，這些底層優化技巧很難直接應用。
為了深入理解這些實踐背后的技術細節，我使用 YouMind 的 Agent 功能對原文中的十多處疑難點進行了系統性追問和梳理。并讓 Manus 針對 Blog 原文創作了一份結構化的 PPT，接下來的內容也會圍繞這些 PPT 頁面展開。
這篇試圖說清楚：
Agent 性能優化的幾個核心概念、五個工程實踐經驗的代碼形式解析、復現架構參考，以及工程化經驗總結。
以下，enjoy:
1、四個核心概念
在深入分析 Manus 的工程實踐之前，需要先明確四個關鍵概念，它們是 Agent 性能優化的理論基礎：
1.1Prefilling（預填充）
LLM 推理的第一階段，模型并行處理所有輸入 tokens，包括系統提示、工具定義、歷史對話等完整上下文。這個階段速度快但計算量大，模型需要"理解"整個上下文并建立 attention 機制。
1.2Decoding（解碼）
LLM 推理的第二階段，模型基于 prefilling 階段的理解，順序生成輸出 tokens。每生成一個 token 都要基于之前所有 context 預測下一個 token，是自回歸的過程。這個階段速度慢但每步計算量相對較小。
1.3KV-Cache（鍵值緩存）
Transformer 架構中的一種優化技術，緩存 prefilling 階段計算的鍵值對。當新請求的上下文前綴與緩存匹配時，可以直接復用計算結果，大幅減少重復計算。對于具有相同前綴的長上下文，KV-Cache 能顯著降低延遲和成本。
1.4In-Context Learning（上下文學習）
一種讓 LLM 在不更新模型參數的情況下學習新任務的方法。通過在輸入中提供示例、指令和上下文信息，模型可以理解任務要求并生成相應輸出。與傳統微調相比，可以通過上下文中的示例和指令學習、不更新模型參數。
說個題外話，In-Context Learning 和 Prompt Engineering（提示詞工程）是不同層面的兩個概念。一言以蔽之，如果把 In-Context Learning 比作"公式"或"定理"的話，那么 Prompt Engineering 就是套用公式或定理來解題。
2、Prefilling 與 Decoding 的不對稱性
理解上述四個概念后，來看看為什么 AI Agent 特別適合 in-context learning，以及這種特性如何影響性能優化策略。
2.1Agent 場景的 Token 使用特征
# 傳統聊天機器人
輸入: "今天天氣怎么樣？" (~10 tokens)
輸出: "今天北京天氣晴朗，溫度25度..." (~100 tokens)
比例: 1:10 (相對平衡)
# AI Agent
輸入: 系統提示 + 工具定義 + 歷史動作 + 觀察結果 (~5000 tokens)
輸出: {"tool": "browser_click", "args": {"id": "submit"}}} (~50 tokens)
比例: 100:1 (高度傾斜)Agent 這種 100:1 的傾斜比例意味著：
大部分計算資源都花在了 prefilling 階段
Agent 每次執行動作都要重新處理大量相同的上下文前綴
正是這種特性讓 KV-Cache 優化在 Agent 場景中變得至關重要，畢竟大部分計算都花在了處理相同的長上下文前綴上。
3、實戰中的 API 調用優化
KV-Cache 的本質是緩存 Transformer 注意力機制中的 Key-Value 向量。以下演示下在 OpenAI 和 Claude API 中的具體實現 KV-Cache的方式：
3.1OpenAI API 的 KV-Cache 利用
import openai
client = openai.OpenAI()
# 第一次調用 - 建立緩存
first_response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": SYSTEM_PROMPT}, # 會被緩存
{"role": "user", "content": "分析第一份簡歷"}
]
)
# 后續調用 - 利用緩存（保持相同前綴）
second_response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": SYSTEM_PROMPT}, # 命中緩存！
{"role": "user", "content": "分析第一份簡歷"},
{"role": "assistant", "content": first_response.choices[0].message.content},
{"role": "user", "content": "分析第二份簡歷"} # 只有這部分是新的
]
)3.2Claude API 的 KV-Cache 利用
import anthropic
client = anthropic.Anthropic()
# 第一次調用 - 建立緩存
first_response = client.messages.create(
model="claude-3-sonnet-20240229",
messages=[
{"role": "user", "content": f"{SYSTEM_PROMPT}
分析第一份簡歷"}
],
max_tokens=1000
)
# 后續調用 - 利用緩存
second_response = client.messages.create(
model="claude-3-sonnet-20240229",
messages=[
{"role": "user", "content": f"{SYSTEM_PROMPT}
分析第一份簡歷"},
{"role": "assistant", "content": first_response.content[0].text},
{"role": "user", "content": "分析第二份簡歷"} # 新增內容
],
max_tokens=1000
)3.3實現方式異同
商業 LLM 的 API 基本都在后端自動實現了 KV-Cache 優化，只需要在發起請求的時候保持消息前綴一致即可享受緩存加速。
# OpenAI API：
使用標準的messages數組格式
system角色獨立存在
響應通過choices[0].message.content獲取
# Claude API：
將系統提示合并到user消息中
沒有獨立的system角色
響應通過content[0].text獲取
共同特點
兩個API的KV-Cache使用原理完全一致：
前綴一致性要求：必須保持完全相同的消息前綴
追加式構建：只能在歷史對話末尾追加新內容
自動緩存：API會自動檢測和利用緩存，無需額外配置3.4本地開源模型 KV-Cache 實現
vLLM 在 KV-Cache 管理上最為成熟，但需要根據 GPU 顯存調整 max_model_len，利用 vLLM 的連續批處理能力，保持會話狀態以最大化緩存命中率。
總的來說，商業 API 的 KV-Cache 使用更簡單（自動管理），而本地部署需要選擇合適的推理框架來獲得最佳性能。以下是 vLLM 的實現方式參考：
from vllm import LLM
# 啟用KV-Cache
llm = LLM(
model="meta-llama/Llama-2-7b-chat-hf",
gpu_memory_utilizatinotallow=0.8,
max_model_len=4096
)
# vLLM自動管理KV-Cache，支持連續對話4、文件系統作為外部記憶
LLM 雖然現在普遍擁有 128K+的上下文窗口，但在實際 Agent 場景中仍面臨三大挑戰：
觀察結果過大：網頁、PDF 等非結構化數據輕易超出上下文限制
性能衰減：超過一定長度后模型表現下降
成本過高：長輸入即使有緩存也很昂貴
Manus 的解決方案是把文件系統視為"外部大腦"，實現可恢復壓縮：
# 核心邏輯：壓縮大型觀察結果為文件引用
def compress_observation(action, observation):
if len(observation) > THRESHOLD:
# 保存到文件系統
filename = f"obs_{action_id}_{timestamp}.txt"
save_to_file(filename, observation)
# 返回輕量級引用（~10 tokens）
return f"[內容已保存至 {filename}]"
return observation
# 按需恢復機制
def restore_when_needed(compressed_ref):
if is_file_reference(compressed_ref):
return load_from_file(extract_filename(compressed_ref))
return compressed_ref這種設計巧妙的讓 Agent 擁有了近乎無限的記憶能力，同時保持了上下文的精簡和高效。
5、動態工具管理
當 Agent 的工具數量激增（尤其是支持 MCP 協議后），動態管理工具成為一個關鍵挑戰。Manus 的核心策略是通過掩碼約束而不是動態移除工具。因為工具定義通常位于上下文前端，任何變更都會使后續緩存失效。其次，歷史動作可能引用已被移除的工具，導致模型困惑和幻覺。
OpenAI API 的工具約束實現示例如下：
# 核心邏輯：通過tool_choice參數約束工具選擇
def constrain_tool_selection(current_state, user_input):
all_tools = get_all_tools() # 完整工具列表始終保持不變
if current_state == "browser_task":
# 場景1：限制只能使用瀏覽器工具
browser_tools = [t for t in all_tools if t["name"].startswith("browser_")]
return {
"tools": browser_tools,
"tool_choice": "required" # 強制使用工具
}
elif current_state == "user_response":
# 場景2：需要回復用戶，禁用所有工具
return {
"tools": all_tools, # 工具定義保持完整
"tool_choice": "none" # 禁止使用任何工具
}
elif current_state == "specific_tool":
# 場景3：強制使用特定工具
return {
"tools": all_tools,
"tool_choice": {"type": "function", "function": {"name": "browser_click"}}
}
else:
# 默認：自動選擇
return {
"tools": all_tools,
"tool_choice": "auto"
}這種設計讓 Manus 能夠在保持工具完整性的同時，精確控制 Agent 在不同階段的行為。BTW，這也和上述提到的 KV-Cache 優化邏輯類似，都是依托現有 API 規范，充分利用了現有基礎設施的能力邊界尋求工程化價值最大化。
6、注意力操控技巧
在長任務執行的過程當中，Agent 容易出現偏離原始目標或遺忘關鍵信息。Manus 的給出的解決方案是通過定期復述把重要信息推入模型的近期注意力范圍。
核心實現邏輯演示如下：
# 簡化的注意力管理機制
def manage_attention(task_goal, current_step, total_steps):
"""定期將關鍵信息推入上下文末尾"""
if current_step % 5 == 0: # 每5步更新一次
# 核心策略：復述關鍵信息到上下文末尾
todo_update = f"""
# 當前進度更新 (第{current_step}/{total_steps}步)
主要目標: {task_goal}
當前焦點: 正在執行第{current_step//5 + 1}階段
下一步計劃: [根據當前狀態動態生成]
---
重要提醒：始終圍繞主要目標執行，避免偏離核心任務
"""
return {
"action": "file_write",
"args": {
"path": "todo.md",
"content": todo_update
}
}
return None
# 使用示例
for step in range(50):
attention_action = manage_attention(
task_goal="分析20份簡歷并生成報告",
current_step=step,
total_steps=50
)
if attention_action:
# 執行注意力維護動作
execute_action(attention_action)
# 執行實際任務
execute_main_task(step)正如原 Blog 中所說，這實際上是"使用自然語言來偏置模型對任務目標的關注"，是一種無需架構改動的注意力操控技術。
7、避免模式固化陷阱
Few-shot prompting 雖然是提升 LLM 輸出質量的常用技術，但在 Agent 系統中可能適得其反。LLM 擅長識別和復制上下文中的行為模式，在批量處理任務的時候特別容易出現，尤其是 LLM 會過度關注近期相似的動作序列。
檢測與干預機制示例如下：
# 簡化的多樣性注入器
def detect_and_break_patterns(action_history, current_action):
"""檢測模式固化并注入多樣性"""
# 檢測重復模式（每5個動作檢查一次）
if len(action_history) >= 5:
recent_actions = action_history[-5:]
similarity_scores = []
for i in range(1, len(recent_actions)):
# 簡單的相似度計算（實際可用更復雜的方法）
similarity = calculate_action_similarity(
recent_actions[i-1],
recent_actions[i]
)
similarity_scores.append(similarity)
avg_similarity = sum(similarity_scores) / len(similarity_scores)
# 如果相似度過高，注入多樣性
if avg_similarity > 0.8: # 閾值可調
return inject_diversity(current_action)
return current_action
def inject_diversity(base_action):
"""注入結構化變異"""
# 策略1：變換序列化格式
format_variants = [
{"action": base_action["type"], "target": base_action["target"]},
{"operation": base_action["type"], "object": base_action["target"]},
{"task": base_action["type"], "focus": base_action["target"]}
]
# 策略2：添加反思提示
if len(action_history) % 7 == 0: # 每7步插入反思
return {
"type": "reflection",
"content": "暫停思考：確保每個案例都得到獨特分析",
"next_action": base_action
}
# 策略3：隨機選擇格式變體
return random.choice(format_variants)
# 實際應用示例
action_history = []
for i, resume in enumerate(resumes):
base_action = {"type": "analyze_resume", "target": f"resume_{i}"}
# 檢測并打破模式
final_action = detect_and_break_patterns(action_history, base_action)
# 執行動作
result = execute_action(final_action)
action_history.append(final_action)通過主動注入多樣性，可以有效避免這種脆弱性，讓 Agent 在處理重復性任務時保持靈活性和創造性。
8、SSM 架構的潛在突破
根據原 Blog 的思考，當前 Manus 的文件系統外化策略可能為 State Space Model（SSM）在 Agent 場景的應用提供了重要啟發。
先看核心設計理念：
# SSM + 文件系統的核心邏輯
def ssm_with_external_memory(input_sequence):
"""SSM通過文件系統實現長期記憶"""
state = initialize_state(size=128) # 固定狀態大小
file_memory = {}
for token in input_sequence:
# SSM線性狀態更新（O(1)復雜度）
state = linear_transform(state, token)
# 關鍵策略：長期信息外化到文件
if is_long_term_info(token):
file_id = save_to_file(token)
# 狀態中只保留文件指針
state = embed_file_pointer(state, file_id)
# 按需檢索外部記憶
if need_retrieval(state):
external_info = load_from_file(decode_pointer(state))
state = integrate_external_info(state, external_info)
return state如原文所說，這種設計可能成為 Neural Turing Machines 的真正繼承者。文件系統提供近乎無限的記憶容量，SSM 負責短期推理，文件系統負責長期記憶。而且隨著任務復雜度增加，性能優勢更加明顯。雖然目前還只是概念驗證，但確實指明了一個很有潛力的方向。
9、復現思路參考
最后呢，我放了一張 mermaid 圖示。我接下來也打算用這個架構，結合 Python 和 LangChain 的基礎組件，來動手復現和測試一下 blog 里提到的這些策略。相關的進展和發現，預計月底前后測試好專門再寫篇文章，歡迎各位蹲一蹲。
上下文組裝器 ? KV-Cache
優化上下文組裝器作為整個系統的"記憶中樞"，負責整合用戶輸入、長期記憶和注意力控制信息。在這個環節實現 KV-Cache 優化最為自然。
工具執行器 ? 動態工具管理
工具執行器天然承擔著工具調用的職責，是實現"掩碼而非移除"策略的理想位置。通過在工具執行前動態調整 tool_choice 參數，既保持了工具定義的完整性（有利于 KV-Cache），又實現了精確的行為控制。
長期記憶模塊 ? 文件系統外化
長期記憶模塊直接對應文件系統策略。把大型觀察結果壓縮為文件引用，不僅解決了上下文長度限制，更重要的是實現了"可恢復壓縮"。
注意力控制 ? todo.md 機制
注意力控制模塊通過定期更新 todo.md 文件，把關鍵任務信息推送到上下文末尾。
輸出解析器 ? 多樣性注入
通過分析動作歷史的相似度，在必要時注入結構化變異，避免 Agent 陷入重復性行為陷阱。
10、寫在最后
Manus 的這些實踐其實揭示了一個重要趨勢：在 AI Infra 日趨標準化的今天，真正的競爭優勢往往來自于對現有 LLM 能力的巧妙組合和深度利用。這也解釋了為什么 Manus 選擇"做船而不是柱子"的策略。
在工程層面找到杠桿點，核心價值在于速度。這些優化技巧可以在數小時內實現和驗證，通過把產品快速的推向市場，在真實用戶場景中收集反饋，并基于實際需求進行快速迭代。畢竟，用戶的真實需求比理論上的最優解更重要。通過持續的工程優化和用戶反饋循環，產品能夠在市場競爭中保持敏捷性和適應性。
這種思路對企業 LLM 應用落地也特別有價值。既能快速見效，又能隨著底層模型的進步自動獲得性能提升，無疑是一種非常務實的技術路線選擇。
