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

Copy Markdown View Source

大工具结果自动 offload 到 backend — Phase 12 NEW.1（v0.4.1 完整版）。

设计目标

对标 deepagents FilesystemMiddleware._intercept_large_tool_result： 防止单个工具一次返回 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 + 路径 （v0.4.1 新增的 Plugin Pipeline action）
  • 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"]
]}

排除工具

TOOLS_EXCLUDED_FROM_EVICTION 这些工具自身有 truncation 或返回小，不需要 offload。 对应 deepagents 的同名常量。