CMDC.Plugin.Builtin.LargeResultOffload (cmdc v0.5.1)

Copy Markdown View Source

大工具结果自动 offload 到 backend。

设计目标

防止单个工具一次返回 200KB+ 的 SQL / scrape 结果直接炸掉 LLM 上下文。

工作流程

  • :after_tool hook 检查 result 字符长度
  • 超阈值 tool_token_limit_before_evict（默认 20000 tokens ≈ 80KB）时：
    1. 写 backend /large_tool_results/<call_id> 保存完整内容
    2. emit :large_result_offloaded 事件（业务订阅 + telemetry 桥接）
    3. 通过 :replace_tool_result action 替换 raw_result 为 preview + 路径
  • Agent 看到的 tool result 是 head/tail preview + 文件路径引导
  • Agent 可调 read_file(file_path, offset, limit) 分页读取完整内容

配置

{LargeResultOffload, [
  backend: backend,                                  # 必填，CMDC.Backend.t()
  tool_token_limit_before_evict: 20_000,             # 默认 20K tokens (~80KB chars)
  excluded_tools: ["ls", "glob", "grep", "read_file",
                   "edit_file", "write_file"]
]}

排除工具

默认排除的工具自身已有 truncation 或返回小，不需要 offload。