Token 优化与 Agent 响应策略

Token 优化与 Agent 响应策略

学习目标

读完本章后，你将能够：

• 理解为什么面向 Agent 的响应不能直接面向人类用户
• 掌握四种 Token 优化策略：语义摘要、分块提取、文件引用、分页控制
• 在设计 MCP 工具时做出正确的响应格式决策
• 识别响应过大导致的上下文窗口耗尽问题

---

核心问题

AI Agent 每次接收响应都会消耗上下文窗口的 Token。一个未经优化的性能 Trace 可能包含 50,000+ 行 JSON（数十万 Token），但 Agent 真正需要的可能只是一句话：“LCP was 3.2s, caused by a render-blocking script”。

为什么 Token 优化很重要？

• 上下文窗口有限：即使模型支持 200K Token，工具响应也不应吃掉大半
• 成本递增：输入 Token 通常按量计费
• 信噪比：大量原始数据中，Agent 难以定位关键信息
• 多工具累积：一次 Agent 循环可能调用多个工具，每个工具的响应叠加

策略一：语义摘要（Semantic Summaries）

原则：返回人类可读的结论性文本，而非原始数据。

// ❌ 不好的响应：原始 JSON
{"metric": "largestContentfulPaint", "value": 3200, "unit": "ms", "rating": "needs-improvement", "breakdown": [...]}

// ✅ 好的响应：语义摘要
LCP: 3.2s (needs improvement). Largest element: <img src="hero.jpg">.
Caused by render-blocking script: app.js (450ms delay).

设计要点：

• 摘要应包含结论 + 原因 + 关键元素
• 对阈值型指标（如 Core Web Vitals），标注评级（good / needs-improvement / poor）
• 保留关键数值，省略中间过程数据

策略二：分块提取（Chunked Extraction）

原则：从大数据中提取独立的、有意义的子块，而非整体。

以性能 Trace 为例：

提取层级	内容	Token 量级
完整 Trace	所有 CDP 事件	100K+
主线程任务	每个任务的时间线	10K+
Trace 摘要	关键指标汇总	~500
单个 Insight	一个具体问题的详情	~200

设计要点：

• 提供 summary 和 detail 两个层级的工具（如 performance_analyze_insight）
• 让 Agent 先看摘要，再按需深入细节
• 每个 Insight 独立可查，不依赖完整 Trace

策略三：文件引用（Reference over Value）

原则：对于重量级资源（截图、Trace、视频），返回文件路径而非原始数据。

// ❌ 不好的响应：Base64 编码的图片内嵌在文本中
{"content": [{"type": "image", "data": "iVBORw0KGgoAAAANSUhEUgAA...", "mimeType": "image/png"}]}

// ✅ 好的响应：文件路径
Screenshot saved to: /tmp/chrome-devtools-mcp/screenshot.png

设计要点：

• 文件路径应使用临时目录或工作区内的可访问路径
• 在 MCP 协议中，ImageContent 可以作为独立 content 项发送，部分客户端支持直接显示
• 但对于文本响应中的大型数据（如 network response body），始终返回文件路径
• 明确说明哪些客户端支持内嵌资产（如 Claude Code 可以显示图片）

策略四：分页控制（Pagination）

原则：当数据量不可预测时，提供分页机制。

{
  "tool": "list_network_requests",
  "params": {
    "pageIdx": 0,
    "pageSize": 50
  }
}

设计要点：

• 设置合理的默认 pageSize（通常 50-100）
• 返回总页数或 hasMore 标志，让 Agent 知道是否还有更多数据
• Agent 侧需要根据 hasMore 决定是否继续翻页

设计权衡

策略	优势	代价	适用场景
语义摘要	Token 极少，信噪比高	丢失细节，Agent 无法自主分析	快速诊断、状态检查
分块提取	兼顾整体与细节	需要额外的提取工具	性能分析、日志审查
文件引用	零 Token 消耗	Agent 无法直接在上下文中处理	截图、Trace、大文件
分页	可控的 Token 消耗	Agent 可能需要多次调用	请求列表、控制台消息

陷阱与对策

陷阱	后果	对策
返回完整原始 JSON	上下文窗口耗尽，后续对话失败	始终先提供摘要，detail 按需获取
摘要过于精简	Agent 缺少足够信息做判断	包含结论 + 原因 + 关键元素三要素
文件路径不在 Agent 可访问范围内	Agent 无法读取文件内容	使用工作区 roots 内的路径或 MCP client 支持的临时目录
分页没有总数提示	Agent 不知道是否需要翻页	返回 totalPages 或 hasMore

设计决策框架

当设计一个 MCP 工具的响应时，问以下问题：

参考来源

• Chrome DevTools MCP Design Principles
• MCP Specification - Content Types