渐进式披露

一句话理解：先给模型一份“目录”，让它知道有什么；等它判断需要时，再加载“正文”和“附录”——工具、Skill 和文档都应该这样按需进入上下文。

一个售后 Agent 接入了订单、支付、退款、发票、工单五个系统，每个系统七八个工具，再加上 Slack、邮件、日程的 MCP Server，工具数量很快过百。团队还写了二十个 Skill、上百页的业务文档。如果在每次调用时把这些全部塞进上下文，会同时出现三个问题：成本高、上下文腐化，以及 模型在一大堆相似的工具之间选错。

渐进式披露（Progressive Disclosure）是应对这个问题的通用设计模式。它原本是界面设计里的概念——先展示最常用的选项，高级设置折叠起来——放到 Agent 里，就是“按需加载上下文”。

直觉：一本组织良好的手册

想象你第一天入职，主管递给你一本 500 页的操作手册。好的手册不会要求你先读完 500 页再干活，而是：

图 1 · 三层加载：同一模式适用于手册、Skill 与工具

Agent 的上下文也应该这样组织。目录层必须写得足够好，模型才能判断“什么时候该翻哪一章”；正文与附录则不占常驻预算。

Anthropic 在介绍 Agent Skills 的设计时，正是这样描述的：Skill 的名称和描述在启动时预先放入系统提示；模型判断相关时，才读取完整的 SKILL.md；SKILL.md 里引用的其他文件，再在需要时进一步读取。因此一个 Skill 能打包的内容量几乎不受上下文限制。

三类对象的渐进式披露

工具：先搜索，再加载定义

工具定义每一步都在上下文里，数量一多就是一笔很大的常驻开销。Claude 的官方文档给过一个具体的例子：同时接入 GitHub、Slack、Sentry、Grafana、Splunk 几个 MCP Server，光工具定义就可能占用约 5.5 万 Token；文档还提到，当可用工具超过 30 到 50 个时，模型选对工具的能力会下降。

对应的做法是 工具搜索：

图 2 · 工具搜索：先搜索，再加载少数匹配工具的定义

Claude API 提供了内置的工具搜索（工具可标记为延迟加载），也允许用自己的检索逻辑实现。无论用哪种，产品上都要注意：

命名要有命名空间：order_get、refund_list_attempts、invoice_get_status，一次搜索就能命中一组。
描述要用用户的语言：用户说“退款政策”，描述里就要出现“退款政策”，而不是只写 refund_rule。
高频工具保持常驻：每次都要用的工具不应该多一步搜索。

工具设计的其他原则见工具设计原则。

Skill：描述驱动的触发

Skill 是把方法和 SOP 打包成能力包（参见 Skill 是什么）。它的渐进式披露分三层：

层级	内容	何时进入上下文	售后场景的例子
元数据	名称 + 描述	始终	“退款异常排查：当用户询问退款未到账、退款失败时使用”
主体	`SKILL.md` 的步骤说明	模型判断相关时	排查的 6 个步骤、每步用哪个工具
资源	模板、脚本、参考资料	主体中提到且需要时	错误码对照表、报告模板、计算退款时限的脚本

这里的关键风险在第一层：描述写得不好，Skill 就永远不会被触发，写得太宽，又会在不相关的任务里被误加载。触发机制与写法的细节见 Skill 如何被发现与加载。

文档与规则：按位置、按路径加载

业务文档和项目规则也可以分层。Claude Code 的做法是一个很好的参考：

项目根目录的说明文件在会话开始时加载，官方建议每个文件控制在 200 行以内。
子目录里的说明文件，在 Agent 读取该目录下的文件时才加载。
可以为规则声明适用的文件路径，只在处理匹配路径的文件时才进入上下文。
多步骤的流程和只与部分代码相关的说明，官方建议放进 Skill 或按路径生效的规则，而不是塞进常驻说明。

迁移到业务 Agent：常驻指令只写“每一步都适用”的规则；“退款政策”“发票开具规范”这类只在特定任务中需要的文档，通过检索或 Skill 按需进入。

用轻量标识代替原文

渐进式披露的另一种形式，是在上下文里 只放“指针”，不放内容。Anthropic 把这称为“即时（just-in-time）”获取：Agent 手里持有文件路径、记录 ID、查询语句这类轻量标识，需要时再通过工具取回内容。

不推荐：把 50 笔异常订单的完整 JSON 全部放进上下文
推荐：  放一张清单（订单号 + 异常类型 + 金额），Agent 逐笔调用 get_order 查看详情

这些标识本身也携带信息：文件名、目录结构、更新时间、异常类型，都能帮助模型判断先看哪个。Coding Agent 在大仓库里工作时，就是靠文件树和搜索结果决定读哪些文件，而不是把整个仓库读进来。

代价与平衡

渐进式披露不是免费的：

代价	说明	缓解方式
多一步调用	搜索、读取都会增加延迟和调用次数	高频内容保持常驻
可能漏加载	模型没意识到应该去查	改进描述；关键规则由程序在触发点注入
可能误加载	描述太宽，加载了无关内容	描述写清“何时不用”
排查更复杂	要看 Trace 才知道加载了什么	在 Trace 中记录每次加载

因此现实中的最佳方案通常是 混合的：少量高频、关键、体积小的内容常驻；其余按需。判断标准可以回到上下文五问中的 When 与 How much。

常见误区

“按需加载就是把东西藏起来。” 目录层必须足够清晰，否则模型根本不知道有什么可以加载。渐进式披露的质量取决于第一层写得好不好。
“所有工具都延迟加载最省。” 每次都要用的工具多一步搜索，只会增加延迟和出错机会。
“指令里写‘需要时请查阅退款政策’就够了。” 模型不一定会主动去查。高风险规则应当在触发时强制注入或由程序校验。

设计要点

统计常驻上下文的构成：指令、工具定义、Skill 元数据、常驻文档各占多少。
工具超过十几个时，考虑工具搜索；为工具名加命名空间前缀。
每个 Skill 和按需文档的描述，都要写清“做什么”和“什么时候用”，用用户会说的词。
上下文里优先放 ID、路径、清单，详情通过工具获取。
在 Trace 中记录每一次按需加载，定期检查“该加载没加载”和“不该加载却加载”的案例。

练习

为订单售后诊断 Agent 设计一份“三层目录”：

列出你设想的全部工具（至少 20 个），为它们设计带命名空间的名称，并圈出应该常驻的 3–5 个。
写 3 个 Skill 的元数据（名称 + 一两句描述），每个描述都要包含“何时使用”。
列出常驻指令里保留的规则（不超过 10 条），其余规则说明通过什么方式按需进入。
找一位同事，只给他看第 1–2 步的“目录”，问他遇到“退款一直没到账”时会选哪个工具和 Skill，看是否与你预期一致。

下一步

上下文的结构不仅影响效果，也影响成本与延迟。下一课「提示缓存」会讲如何复用不变的前缀，以及它反过来如何约束上下文的排列方式。

渐进式披露