工具输出漏斗 YuanyuanMa03/dsh-funnel

dsh-funnel

在工具输出进入模型上下文之前先过一道漏斗——留住要紧的行，其余落盘留指针。更快、更省、注意力更集中，且对所有工具生效。

问题

每次工具结果都会追加进对话，并在之后每一轮模型请求里重发。跑一次 npm test 打出 500 行，这 500 行就跟着会话走到底：每一轮都为它付费，上下文窗口被它填满，模型真正需要的那一行 AssertionError 反而被埋掉。

现有层都不覆盖这件事：

| 层 | 已有 | 没做的 |
| 捕获（执行器） | 64 MB spill 防进程 OOM | 与模型看到什么无关 |
| 执行（仅 bash） | maxOutputBytes 字节顶、头部截断 | 只覆盖 shell 工具；盲切，不留 error 行 |
| 压缩时点 | 官方 tool-result-pruner 重写超预算结果的 surface | 只在压缩时触发；盲切头尾；模型读不回原文 |
| 摄入——每个结果、立即生效 | —— | ← dsh-funnel |

压缩时点的修剪是预算爆了之后补救；dsh-funnel 让预算别爆。两者互补。

你能得到什么

1. 装完即忘。 一条命令、零配置。覆盖所有返回文本的工具——bash、文件读取、网页抓取、搜索——低于门槛的结果字节级原样通过，省钱之前你完全感觉不到它的存在。
2. 实测约 24 倍的视图缩减。 真实 headless 会话中，2001 行（8,893 字节）的 bash 结果以 370 字符到达模型：头、尾、加上所有 error/warning 行：

- [2001 行原始输出]
+ [dsh-funnel] output curated: 2001 lines → 40 kept (head 15, tail 25, 0 pattern-matched). Full output: .dsh-funnel/2026-08-15T09-21-56-548Z-bash-1.log
+ 1 … 15
+ [dsh-funnel] … 1959 similar lines omitted …
+ 1977 … 2000

会话之后的每一轮都只为 370 字符付费而不是 8,893——节省随请求次数复利。
3. 信息不丢，模型自己会找回。 全文落盘到 .dsh-funnel/，通知里带路径。实测中模型在治理视图里看不到中间某行，自己搜索落盘文件并给出了正确答案——治理是分页，不是删除。落盘目录同时也是"agent 到底看到了什么"的审计留痕。
4. 长任务更扛造。 上下文更小意味着每轮更便宜、压缩更晚触发、注意力更少被稀释——agent 在会话深处保持敏锐，而不是随垃圾积累逐渐变笨。
5. 按自己的工作流调策略。 门槛、保留行数、关键词模式（加上你项目自己的失败标记）、按工具分级、落盘开关。

边界：错误结果永不触碰（短且承重）；它是压缩的互补而非替代。

工作原理

dsh-funnel 挂在 tools/execute 扩展点（官方 timeout guard 的同款接缝），治理成功结果的 canonical value：注册表从 value 重新投影模型可见内容，所以治理视图就是模型看到、也是会话日志记录的内容。value 里的长字符串字段——stdout、stderr、抓取的网页、文件内容——被就地替换；错误结果永不触碰。

安装

dsh plugin add github:YuanyuanMa03/dsh-funnel

对所有返回文本的工具生效——bash、文件读取、web fetch、搜索。

配置

全部可选，写在 profile 的插件条目下：

- id: dsh-funnel
name: 'dsh-funnel'
config:
maxChars: 4000 # 不超过此长度的结果原样通过 keepHead: 15 # 头部保留行数 keepTail: 25 # 尾部保留行数（错误通常在尾部）
keepPatterns: [error, warn, fail, fatal, exception, assert, denied, panic]
maxLineChars: 1000 # 单行超长（压缩/JSON 行）截断 spill: true # 全文落盘并引用 tools: # 按工具覆盖
web_fetch: { maxChars: 2000 }

安全属性

- 错误结果永不触碰——短且承重。
- 落盘层无损——全文保留，模型按需读回。
- 模型可见 ⟺ 已记录——治理视图在工具接缝处替换结果，会话日志记录的就是模型看到的。
- 字节级原样通过——低于 maxChars 的结果返回原对象，闲置时零分配。

状态

v0.1.0 —— 已在真实 headless 会话中端到端验证：2001 行的 bash 结果被治理为 40 行（模型视图与日志一致），模型通过读取落盘文件补回了被省略的中段（它自己的原话："the tool curates long output for display … verified against the complete saved output"）。单元测试覆盖治理逻辑与插件包装。计划中：会话级节省记账（"本次会话已避免 N token"）。

许可

MIT