在模块一中,我们建立了鱼缸模型的全局视角——上下文窗口是一个有限容器,六类信息通过六根管道注入。现在的问题是:每根管道注入的是什么?流量有多大?工程师要做哪些管理决策?这一模块是全课的骨架——六模块坐标系将贯穿后续所有内容,无论是模块三的策略映射还是模块四的实战标注,都以这个坐标系为基准。
2.1 模块全景图:六大功能模块的角色与核心问题
在深入每个模块之前,我们先建立一个全景认知。下图展示了一个典型 Agent 上下文窗口中,六个模块的 token 消耗分布:
从这张分布图可以看出,对话历史和工具上下文通常是两个最大的"水龙头"——它们合计可能占据上下文窗口的 50% 以上。这就是为什么历史管理和工具管理往往是上下文工程的首要优化目标。
2.1.1 动手测量:六大模块 Token 占比计算
# === 六模块 Token 占比实测 ===
# 模拟 OpenClaw 各模块的典型内容(比例贴近真实 Agent 场景)
modules = {
"①系统提示": (
"你是 OpenClaw,一个专注于软件工程的 AI 助手。\n"
"## 人格与边界\n你的回复风格简洁专业,优先用代码示例说明问题。"
"遇到不确定的问题,主动说明而不是猜测。\n"
"## 用户画像\n用户是 Python 高级开发者,偏好函数式编程风格,使用 dark mode。\n"
"## 操作协议\n1. 记忆工具使用规范:save_*_memory 用于存储,search_*_memory 用于检索。\n"
"2. 回复长度控制:代码解释不超过 3 段,修改建议附带 diff。\n"
"3. 安全边界:不执行删除操作,不修改 .env 文件。\n"
"## 可用技能\n- 代码分析与重构建议\n- 文件读写与项目结构管理\n- 知识库检索与记忆管理\n"
"## 长期记忆\n**用户偏好**\n- 用户是 Python 开发者\n- 偏好简洁回复\n"
"**行为规则**\n- 不要在末尾添加总结段落"
),
"②对话历史": "\n".join(
[f"用户:帮我分析 {mod} 的性能瓶颈,看看数据库和缓存。\n"
f"AI:{mod} 分析完成。数据库平均 {45+i*12}ms,"
f"{['JOIN','子查询','全表扫描','索引缺失'][i%4]}是瓶颈,"
f"缓存命中 {85-i*3}%。建议{'加索引' if i%2==0 else '加 Redis'}。"
for i, mod in enumerate(["认证", "订单", "支付", "库存", "通知",
"分析", "搜索", "日志", "配置", "网关"])]
), # 10 轮对话,每轮含具体数据
"③记忆注入": "\n".join(
[f"- [{t}] {c}" for t, c in [
("用户偏好", "用户是 Python 高级开发者,偏好简洁代码风格"),
("行为规则", "回复时优先展示代码,然后解释"),
("项目上下文", "当前项目使用 FastAPI + React 架构"),
("参考资料", "API 文档位于 docs/api.md"),
("用户偏好", "用户习惯使用 dark mode"),
]]
), # 5 条 mem0 检索结果
"④工具上下文": "\n".join(
[f"tool: {name}\ndescription: {desc}\nparameters:\n - content: str (required) — The content to save or query\n - path: str (optional) — File path for reference\n - metadata: dict (optional) — Additional context tags"
for name, desc in [
("save_user_memory", "Save user profile information to long-term memory including name, role, technical background, coding preferences, and communication style."),
("save_feedback_memory", "Save behavioral rules and interaction preferences. Records how the user wants responses formatted, what to avoid, and workflow preferences."),
("save_project_memory", "Save project context including tech stack, architecture decisions, deployment setup, team conventions, and ongoing initiatives."),
("save_reference_memory", "Save reference links and resource locations: documentation URLs, API endpoints, file paths, repository links, and external resources."),
("search_user_memories", "Search user profile memories by semantic similarity. Returns relevant user preferences, background info, and personal context for personalization."),
("search_feedback_memories", "Search behavioral rule memories by semantic similarity. Returns interaction constraints, formatting rules, and workflow preferences."),
("search_project_memories", "Search project context memories by semantic similarity. Returns tech stack details, architecture info, and project conventions."),
("search_reference_memories", "Search reference link memories by semantic similarity. Returns documentation URLs, API endpoints, and resource paths."),
]]
), # 8 个工具,每个含完整 description + 3 个参数说明
"⑤任务状态": "当前任务:分析系统性能。已完成:模块1-3的数据库优化。下一步:模块4的缓存层设计。",
"⑥外部知识": (
"根据检索到的文档片段:\n"
"FastAPI 的依赖注入系统支持嵌套依赖,可以通过 Depends() 实现自动解析。"
"对于数据库连接,推荐使用 async session 配合 asyncpg 驱动。"
"性能测试表明,异步模式下 QPS 提升约 3 倍。\n"
"SQLAlchemy 2.0 的新 API 支持原生 async/await,不再需要 run_sync 包装。"
"建议使用 create_async_engine 替代 create_engine,并配合 async_sessionmaker。"
),
}
数据准备完毕,接下来用 DeepSeek Tokenizer 精确计算各模块的 token 占比:
# 计算每个模块的 token 数
total = 0
token_counts = {}
for name, content in modules.items():
tokens = count_tokens(content)
token_counts[name] = tokens
total += tokens
# 输出占比表
print(f" 模块 Token 数 占比")
print("-" * 42)
for name, tokens in token_counts.items():
pct = tokens / total * 100
padded = name + " " * (10 - len(name))
print(f" {padded} {tokens:>6} {pct:>5.1f}%")
print("-" * 42)
print(f" 合计 {total:>6} 100.0%")
# 重点结论
hist_key = "②对话历史"
tool_key = "④工具上下文"
hist_pct = token_counts[hist_key] / total * 100
tool_pct = token_counts[tool_key] / total * 100
print(f"\n对话历史({hist_pct:.0f}%) + 工具上下文({tool_pct:.0f}%) = {hist_pct+tool_pct:.0f}%,合计超过一半")
print(f"100 轮对话后,仅对话历史就会膨胀到约 {token_counts[hist_key] * 10:,} token")
| 模块 | Token数 | 占比 |
|---|---|---|
| ①系统提示 | 289 | 15.8% |
| ②对话历史 | 669 | 36.6% |
| ③记忆注入 | 101 | 5.5% |
| ④工具上下文 | 597 | 32.6% |
| ⑤任务状态 | 39 | 2.1% |
| ⑥外部知识 | 135 | 7.4% |
| 合计 | 1830 | 100.0% |
对话历史(37%) + 工具上下文(33%) = 69%,合计超过一半 100 轮对话后,仅对话历史就会膨胀到约 6,690 token
运行后你会看到:对话历史和工具上下文确实是两个最大的消耗源,合计超过 50%。而且这还只是 10 轮对话和 8 个工具——在真实的生产系统中,50+ 轮对话 + 30 个工具的组合会让上下文迅速触及有效窗口边界。
从输出中得到的启示:这个实测数据揭示了三个关键优化方向:
(1)对话历史是增长最快的模块——10 轮就已占比约 30%,50 轮后将膨胀 5 倍,必须优先启用压缩策略(trim + 摘要);
(2)工具上下文的占比远超大多数人的直觉,8 个工具就吃掉近 30% 的窗口,当工具数量超过 15 个时需要考虑动态加载;
(3)系统提示虽然是静态开销,但它每轮都重复发送,可以通过 Prompt Caching 实现 90% 的成本节省。
如何根据占比调整策略:如果你的 Agent 对话历史占比超过 35%,优先启用 trim_messages + LLM 摘要压缩;如果工具上下文占比超过 25%,考虑按任务阶段动态加载工具子集(而非全量注册);如果系统提示占比超过 15%,立即启用 Prompt Caching——这是零改动、最高收益的优化手段。