# `CMDC.Plugin.Builtin.LargeResultOffload`
[🔗](https://github.com/tupleyun/cmdc/blob/v0.5.3/lib/cmdc/plugin/builtin/large_result_offload.ex#L1)

大工具结果自动 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。

---

*Consult [api-reference.md](api-reference.md) for complete listing*