渐进式披露策略

渐进式披露策略

学习目标

读完本章后，你将能够：

• 理解渐进式披露的核心思想和 token 经济学
• 设计三层搜索工作流模式
• 实现按层展开的上下文注入管线
• 评估渐进式披露相比全量注入的节省效果

核心概念

为什么需要渐进式披露

当 Agent 需要检索历史记忆时，最常见的错误做法是一次性拉取所有相关记忆的完整内容。这会导致：

1. Token 爆炸：检索 20 条记忆，每条 500-1000 token，总消耗 10,000-20,000 token
2. 信息过载：大量不相关的细节淹没在上下文中，反而降低 Agent 的判断能力
3. 延迟增加：获取和解析大量数据的时间成本

渐进式披露的策略是：先获取轻量索引，再逐步展开感兴趣的细节，类似于学术搜索中先浏览摘要再下载全文。

三层工作流模式

第 1 层：搜索索引（search）

返回紧凑的索引列表，包含 ID、标题、日期、类型等元数据。每条约 50-100 token。

search(query="authentication bug", limit=20)
→ [{id: 123, title: "修复认证中间件 session 泄漏", date: "2026-05-27", type: "bugfix"},
   {id: 456, title: "重构 JWT token 刷新逻辑", date: "2026-05-26", type: "refactor"},
   ...]

第 2 层：时间线（timeline）

围绕选定的锚点 ID，获取前后相邻的记忆条目，提供上下文。帮助 Agent 判断该事件前后发生了什么。

timeline(anchor=123, depth_before=3, depth_after=3)
→ [120: 用户报告认证问题, 121: 调查 auth middleware, 122: 发现 session 泄漏,
   123: 修复认证中间件 session 泄漏, 124: 添加测试, 125: 部署验证]

第 3 层：完整详情（get_observations）

仅获取 Agent 判定为相关的 ID 的完整内容。每条约 500-1000 token。

get_observations(ids=[123, 456])
→ [{id: 123, facts: [...], narrative: "...", files_modified: [...]},
   {id: 456, ...}]

Token 经济学

策略	Token 消耗（20 条结果）
全量注入	20 × 750 = 15,000 token
渐进式披露	20 × 75 + 6 × 75 + 3 × 750 = 3,900 token

渐进式披露节省约 74% 的 token 消耗。

上下文注入管线

渐进式披露不仅适用于搜索，也适用于会话启动时的上下文注入：

1. Header：项目名、记忆统计、token 经济学概览
2. Timeline：按时间排列的近期记忆索引（轻量）
3. Summary：最近会话的摘要（如果存在）
4. Footer：统计信息和操作提示

Agent 可以根据需要，通过搜索工具逐层展开感兴趣的记忆。

设计权衡

优势

• Token 高效：避免一次性加载大量不相关数据
• Agent 自主控制：Agent 自己决定展开哪些细节
• 延迟可控：第一层响应快速，按需加载后续层

代价

• 多轮往返：需要多次工具调用才能获取完整信息
• Agent 需要学习模式：Agent 必须理解三层工作流的用法
• 实现复杂度：需要维护多层数据结构和索引关系

替代方案

方案	优势	劣势
全量注入	一次获取所有信息	Token 浪费严重
单层摘要	简洁、快速	可能遗漏关键细节
渐进式披露（本方案）	Token 高效、灵活	多轮往返

参考来源

• Model Context Protocol Specification