yunxiyang/dsh-stepwise-distill

dsh-stepwise-distill

English

花大约两倍的钱和两倍的时间，让上下文变得更密，从而让模型拿到的东西值得它花注意力。

一段很长的会话会腐化成它自己的历史：agent 反复重读它早已想完的思考、早已写进文件的补丁、早已从中得出结论的输出——而它真正需要的那个东西，也就是当初交给它的那个要求，只占这一大段提示词里很小的一部分。这个插件花钱把这件事倒过来：同一段会话，少装一点它做过什么，多装一点它知道什么。

办法是两步：让最新一步保留它自己的原始材料，同时把更早的每一步换成一条记录。两样都不删除任何东西——事件日志只追加，history_read 可以按 seq 取回任何原文。具体怎么做见怎么工作。

为什么是这两样

目标不是把账单变小——这个插件是花 token、花时间的，见代价。目标是：同一个 token 预算里，装下更多模型需要的东西、更少它已经处理过的东西。

所以问题在于：一段长会话里，哪一部分值得花掉它的 token。答案不是看起来最大的那一部分。

跨会话统计下来，assistant 自己的输出大致是：

| | 占 assistant 内容的比例 |
|---|---|
| 推理 | 17% |
| 回复正文 | 28% |
| 工具调用参数（补丁、脚本正文） | 55% |

推理的分布很不均匀。某次会话里它在多数轮里为零，而前四轮共计 143 KB——那是探索阶段，模型在弄明白任务到底是什么。也就是说，被拿掉的材料不只是最大的一块，还是最不密的一块：文字很多，决定很少。

工具调用参数通常是补丁或脚本正文：内容早已落进文件，每轮重发全文买不到任何东西。它产生的结论已经进了记录，它的原文离一次 history_read 也不远。留在投影里的是下一步自己重建不出来的东西。

怎么工作

1. 把最新一步自己的材料放回投影。

Session.deriveMessages() 是消息列表的唯一来源——请求由它构建，运行时的不变式拿它与请求比对。包装这一个方法让两边一起动，所以不变式是被满足的，而不是被绕过的。

纯函数 deriveEventMessage 刻意不动：十一个子系统共用它，包括 token 计量，它们必须继续看到日志里记下的东西。

2. 写下每一步。

一步完成后，额外发一次请求，携带当前上下文加一句短指令。它只回答刚刚那一步。

答案是那一步的完整记录，不是它的摘要。写下的文字是 agent 之后唯一还能看到的该步记录，所以把写薄就是让 agent 丢掉自己的任务史：早先的版本要求「一到三句话」，产出的描述薄到无法据以工作，agent 只好把已经做过的事重新推一遍。长度应当跟着这一步走。

发的是真实上下文而不是摘录，这正是要点：看不到任务的答案只能报告那一步做了什么（「对 Y 跑了 cat」），而拿得到上下文的答案能说出它意味着什么（「在 Y 里确认了 X，Z 需要它」）。

刻意留在外面的是推理本身——把思考也带下去，只会在一个更高的层次上重建这个插件本来要消除的那种翻来覆去。

记录由模型写，永远不由规则合成。判断一步里什么要紧，是对意图的判断，模式做不到这件事。

3. 扣留已小结的材料。

一步被写下来之后，它的消息就不再进入投影。下一次请求携带的是更早的那些记录加上最新一步的原始材料。日志里什么都还在。

代价

这是一笔交易，价钱提前写明：输入 token 大约翻倍，每步多一个模型往返。买到的是这样一份上下文——有用的内容没有被「它已经处理过的那些」冲淡。

stepSummary 默认打开。 多出来的那次请求不是那一步的摘要：它携带摘要用的系统提示词、完整的投影上下文，和一句短指令，所以它的输入开销与你本来就要发的那次请求同一个量级，外加它写下的那条记录。

它还会让每一步都变慢。 小结要在下一次请求构建之前发出，因为「决定那次请求包含什么」正是它存在的全部目的。于是每一步要等的不是一个模型往返而是两个，在长任务上这是可以感觉到的总时长增加。

stepSummary: false 时完全不发额外请求，debug: false（默认）在碰到日志文件之前就返回。两种情况都不删除、不改写任何东西：变的只是模型被展示的内容。

节省随会话变长而增长，这些开销却是固定的，所以盈亏平衡点在长会话那一边。单个短任务上，token 和时间都会比不用这个插件更多。长期只做短任务时，把 stepSummary 和 turnSummary 关掉。

配置

- id: stepwise-distill
config:
stepSummary: true         # 每完成一步写一条记录（默认：开）
turnSummary: true         # 每轮结束写一条补充记录（默认：开）
debug: false

stepSummary 与 turnSummary 默认开着：它们就是这个插件在做的事，装上就该生效。代价见代价。不接受这笔开销时，在上面把对应的开关改成 false。

改完下一步生效，不需要重启：bundle patch 是普通插入，配置没有被冻结。设置页那张「蒸馏」卡片改的也是同一处。

三个取值都可以在 Settings > Plugins > 蒸馏 里改；配置文件里的值作为默认值，卡片改动覆盖它。

启动日志会打出这三个开关的当前值，形如：

[stepwise-distill] loaded stepSummary=true turnSummary=true debug=false

装了之后不生效，先看这一行，再看卡片。两个小结开关默认都是开的；日志里是 false 就说明配置文件或卡片把它关掉了。

安装

dsh plugin --profile  add dsh-stepwise-distill

度量

在会话里，/distill 报告这个插件扣下了什么：一共有多少步、其中多少步已经小结、以及之后各轮不再携带的原始材料共多少字节。

/distill

src/ 下的纯逻辑由 npm test 覆盖；那里不需要跑起来的宿主环境。

开发

npm run build   # src/ -> lib/
npm test        # vitest
npm run check   # lib/ 必须与 src/ 一致

DESIGN.md 放着完整设计、每条宿主约束对应的代码证据，以及分阶段的计划。

宿主包

history_read 是通过 @deepseek-ai/dsh-tools 的 defineTool 注册的，与每一个宿主工具用的是同一个调用。那个包在 DSH 随附的版本上没有发布到 npm，而且它带着一条很深的 peer 依赖链，所以不能声明成普通依赖。它由 DSH 在运行时提供；本地开发时用 npm run link-host-deps 从已安装的应用里把它——以及链上的全部——拷出来：

npm run link-host-deps          # 从 /Applications/DSH Desktop.app
npm run link-host-deps -- --optional   # DSH 不存在时只警告，不失败

postinstall 会带 --optional 跑它，所以 npm install 会自动恢复这些包，并且在没装 DSH Desktop 的机器上仍然成功（只是那里跑不了测试）。拷贝过程直接解析 asar 归档——不用 asar 包，不联网。链是从各个包的 manifest 走出来的，不是一张固定清单，所以升级 DSH 不会让它悄悄失效。