# dsh-funnel

[English](README.md) | 中文

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

## 问题

每次工具结果都会追加进对话，并在**之后每一轮模型请求里重发**。跑一次 `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 行：

   ```diff
   - [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、抓取的网页、文件内容——被就地替换；错误结果永不触碰。

## 安装

```sh
dsh plugin add github:YuanyuanMa03/dsh-funnel
```

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

## 配置

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

```yaml
- 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](LICENSE)