tool result budget

Tool Result Budget 是上下文管理的第一层防线，限制单个工具结果的大小。

设计目标

防止单个工具结果消耗过多 token：

• 文件读取可能返回数万行代码

• 搜索结果可能包含数百个匹配

• Shell 命令输出可能非常冗长

实现机制

大小限制

const MAX_TOOL_RESULT_SIZE = 50000; // 字符

function enforceToolResultBudget(result: string): string {
  if (result.length <= MAX_TOOL_RESULT_SIZE) {
    return result;
  }
  
  return truncateToolResult(result);
}

截断策略

function truncateToolResult(content: string): string {
  const maxSize = MAX_TOOL_RESULT_SIZE;
  
  // 保留 70% 开头 + 30% 结尾
  const headSize = Math.floor(maxSize * 0.7);
  const tailSize = Math.floor(maxSize * 0.3);
  
  const head = content.slice(0, headSize);
  const tail = content.slice(-tailSize);
  
  const truncatedSize = content.length - maxSize;
  
  return `${head}\n\n[... truncated ${truncatedSize} characters ...]\n\n${tail}`;
}

智能裁剪

基于 explanation 的裁剪

function intelligentPrune(
  content: string,
  explanation: string
): string {
  // 提取关键词
  const keywords = extractKeywords(explanation);
  
  // 按行分割
  const lines = content.split('\n');
  
  // 找出相关行
  const relevantLines = lines.filter(line =>
    keywords.some(kw => line.toLowerCase().includes(kw.toLowerCase()))
  );
  
  // 如果相关内容太少，返回原始内容
  if (relevantLines.length < lines.length * 0.1) {
    return content;
  }
  
  // 添加上下文（前后各 2 行）
  const withContext = addContextLines(relevantLines, lines, 2);
  
  return withContext.join('\n');
}

结构化裁剪

对于代码文件，保留结构：

function pruneCodeFile(content: string): string {
  // 解析 AST
  const ast = parse(content);
  
  // 提取签名
  const signatures = extractSignatures(ast);
  
  // 保留导入和导出
  const imports = extractImports(ast);
  const exports = extractExports(ast);
  
  return `
${imports.join('\n')}

${signatures.map(s => s.signature).join('\n\n')}

${exports.join('\n')}
  `.trim();
}

工具特定策略

ReadFile

class ReadFileTool {
  async execute(input, context) {
    const content = await fs.readFile(input.path, 'utf-8');
    
    // 应用智能裁剪
    const pruned = intelligentPrune(content, input.explanation);
    
    // 应用大小限制
    const budgeted = enforceToolResultBudget(pruned);
    
    return { success: true, output: budgeted };
  }
}

GrepSearch

class GrepSearchTool {
  async execute(input, context) {
    const matches = await grep(input.query, input.includePattern);
    
    // 限制匹配数量
    const limited = matches.slice(0, 50);
    
    // 格式化输出
    const formatted = limited.map(m => 
      `${m.file}:${m.line}: ${m.content}`
    ).join('\n');
    
    return { success: true, output: formatted };
  }
}

BashTool

class BashTool {
  async execute(input, context) {
    const result = await exec(input.command);
    
    // 截断长输出
    const truncated = truncateOutput(result.stdout);
    
    return { success: true, output: truncated };
  }
}

用户控制

skipPruning 参数

用户可以禁用裁剪：

await readFile({
  path: 'large-file.ts',
  skipPruning: true,  // 返回完整内容
});

分段读取

对于超大文件，支持分段读取：

// 第一次读取
await readFile({
  path: 'huge-file.ts',
  start_line: 1,
  end_line: 1000,
});

// 第二次读取
await readFile({
  path: 'huge-file.ts',
  start_line: 1001,
  end_line: 2000,
});

性能影响

Token 节省

典型场景的 token 节省：

场景	原始大小	裁剪后	节省
读取大文件	100K	30K	70%
搜索结果	50K	10K	80%
Shell 输出	80K	20K	75%

响应速度

• 减少 token 数量 → 更快的 API 响应

• 更少的内容 → 更快的解析和处理

• 更小的上下文 → 更好的 AI 理解

下一步

• 了解 Microcompact 的压缩算法

• 探索 Context Collapse 的折叠策略

• 查看 Auto Compact 的自动触发