Progressive Disclosure for Large Files

直接加载大文件（如PDF、DOCX、图片）会撑爆上下文窗口（context window）。一个5-10MB的PDF可能仅包含10-20KB的相关文本或表格，但人们往往会将整个文件塞入context，这既浪费令牌（tokens），又会导致性能下降。

采用渐进式披露策略：先加载文件元数据，再提供工具按需加载内容。

核心方法：

1. 始终在prompt中包含文件元数据（而非完整内容）：

文件列表：
  - id: f_a1
    文件名: my_image.png
    文件大小: 500,000
    已预加载: false
  - id: f_b3
    文件名: report.pdf
    文件大小: 8,500,000
    已预加载: false

1. 可选择性预加载符合要求的MIME类型文件的前N KB内容（可按工作流配置，支持设置为0）

2. 提供三类文件操作工具：

   • load_file(id) - 将整个文件加载至context中
   • peek_file(id, start, stop) - 加载文件的指定片段
   • extract_file(id) - 将PDF/DOCX/PPT转换为简化文本

3. 内置large_files技能，说明这些工具的使用场景与方法

# 文档对比的Agent工作流
1. Prompt中包含report_2024.pdf和report_2025.pdf的文件元数据
2. Agent识别到大型PDF文件，查阅large_files技能说明
3. Agent调用：extract_file("report_2024.pdf")
4. Agent调用：extract_file("report_2025.pdf")
5. Agent利用最小化context对比提取出的文本内容

# 图像分析的Agent工作流
1. Prompt中包含screenshot.png的文件元数据
2. Agent识别到PNG类型文件，调用：load_file("screenshot.png")
3. 图像内容加载完成后，Agent对视觉内容进行分析

最佳适用场景：

• 文档对比工作流（多份PDF）
• 带文件附件的工单系统（图片、PDF）
• 导出数据分析（多种格式的大型报告）
• 任何需要文件内容但文件体积过大的Agent工作流

实现注意事项：

• 文件id应为工具调用提供稳定的引用
• extract_file应返回简化后的文本（表格、文本内容）
• 对于超大型提取任务，可考虑让extract_file返回一个虚拟file_id
• 预加载前N字节内容为可选操作——无需完整加载即可为Agent提供初始context

工具设计：

def load_file(file_id: str) -> str:
    """将整个文件内容加载到context窗口中。"""

def peek_file(file_id: str, start: int, stop: int) -> str:
    """加载文件的特定字节范围内容。"""

def extract_file(file_id: str) -> str:
    """将PDF/DOCX/PPT转换为简化的文本表示形式。"""

优点：

• 支持处理远大于context window的文件
• Agent可自主控制加载内容与加载时机
• 可通过large_files技能在多工作流中复用
• 提取出的内容体积通常仅为原文件的1/100

缺点：

• 增加工具调用开销（涉及多轮往返交互）
• 需要预加载启发式规则（难以界定“足够的加载量”）
• 若无原生依赖，从复杂格式（如DOCX）中提取内容速度可能较慢
• 缺乏恰当引导时，Agent可能做出不合理的加载决策

预加载的权衡：

• 预加载：为Agent提供即时context，但会削弱其控制权
• 不预加载：Agent拥有最大控制权，但需要发起显式加载调用