dsh-reasoning-distill

把过长的模型思考压缩成核心内容，之后每次请求都重放压缩版，省下重复发送的 token；同时给出每个会话的开销与节省报告。

插件默认关闭，装好后需要在「设置 → 思考压缩」里选中一个改写后端并手动打开总开关。

版本与安装方式（先看这里）

• 可能适配的 DSH 版本：0.2.0-rc.1 ～ 0.2.1-rc.1。这一范围内的补丁、类型与语义都逐版本验证过，明细见下文「经过测试的 DSH 版本」。
• 已知可以正常运行 in-place 后端的版本：0.2.1-alpha.1、0.2.1-alpha.5。
• 想要全部功能与最佳体验，请使用从源码构建的 DSH（clone 官方仓库后从源码运行或构建）。从 npm 直接下载的版本和第三方打包版（例如 dsh-desktop）无法给宿主源码打补丁，in-place 后端用不了，只能退而使用 message-edit。

---

一、它做什么

• 监视每次模型输出里的思考内容（reasoning），并估算其 token 数。
• 某一步的思考超过该模型的触发阈值（默认 4000 token）时，把这一步的思考（可选附上工具调用与结果）交给蒸馏模型（默认 deepseek-official/deepseek-flash，思考强度 off）改写成更短的版本。
• 压缩发生在下一步请求之前，下一步会等它。等待上限由该模型的超时决定：到点就放弃这一次压缩（原始思考不动、不记账）；填 0 表示不设限、一直等到出结果。
• 只有压缩结果至少能省下最低节省（默认 600 token）时才真正采用，否则只花钱、不替换。
• 被采用的压缩版会替换"模型看到的思考内容"，因此之后每个请求都少带这些 token；会话日志里的思考原文保持不动，本插件的账本存放在会话日志旁边的 sidecar 文件里。
• 「思考压缩」标签页显示：触发次数、蒸馏开销、已采用次数、当前单次请求减量、历史累计节省、净收益，以及最近一步"为什么没有触发"。

三种会话有各自独立的开关：主对话、可续聊子代理（例如队友）、一次性子代理（跑完即结束的委派）。默认只对主对话和可续聊子代理开启。

关于"缓存断裂"：改写被放在该思考块第一次被重放之前，所以正常情况下这一步本来就是缓存未命中，不额外产生缓存断裂开销，报告里的 cacheBreakTokens / cacheBreakCost 恒为 0。少数回退路径（sidecar 读失败后恢复、写回失败留给轮询补写、插件停用后宿主仍持有压缩版）会让改写点之后的整段重新按未命中计费，这时报告会高估净收益。

---

二、助手消息改写后端：二选一

本插件只负责"算出压缩版"；把压缩版真正写回会话历史需要一个改写后端。两个后端里必须装好并选中一个，否则总开关会被强制关闭并锁定。

内置原位后端（in-place）与宿主补丁（首选）

• 不需要安装任何包；它的前置条件是给 DSH 本体打补丁（scripts/dsh-inplace-patch.mjs）。快速安装里的 in-place 就是打这个补丁。
• 补丁给会话加了两样能力：在不改变日志长度、seq、消息 id 的前提下，替换某条助手消息里的思考块；以及让持久化层能就地改写已存的记录。共 14 处编辑（其中 1 处带两份版本锚点，见下）。
• 好处：不新建分支、不产生额外会话，对话列表和归档列表保持干净。
• 风险：这是修改 DSH 本体源码的补丁。DSH 跨版本升级很容易出问题——补丁按字面锚点匹配，任何一处对不上就整体拒绝，不会写一半。升级 DSH 前建议先回退，升级后再用 --check 复查、必要时重打；打不上就用 --checkout <DSH 源码目录> 指路，不要手工改宿主源码。
• 打完补丁需要重启 dsh web 才生效。回退：node scripts/dsh-inplace-patch.mjs --revert --build。
• 打包版 DSH 用不了这个后端：像 dsh-desktop 这类把 harness 装成只读、只有 node_modules 而没有源码的安装，没有可写的源码树可以打补丁；这类安装请用 message-edit。

经过测试的 DSH 版本

分三档看，别把"补丁能打上"当成"整套在真实会话里跑过"：

档位	覆盖的版本	做到了什么
已知可运行 in-place	0.2.1-alpha.1、0.2.1-alpha.5	alpha.1 是本插件开发机（补丁已长期在真实会话中使用）；alpha.5 是反馈该问题的用户所在版本，补丁与插件均确认可用
完整启动	0.2.1-rc.1	独立 clone 全量构建后装入插件并启动 web，插件的安装页与报告页路由都能正常应答
补丁 + 类型 + 语义	0.2.0-rc.1、0.2.0-rc.2、0.2.1-alpha.1～0.2.1-alpha.5、0.2.1-rc.1	独立 clone 上逐版本 --apply → --check → --revert（回退后工作树逐字节干净）、打过补丁的包 tsc -b 通过、持久化探针 scripts/probe-inplace-durability.mjs 通过（none 与 zstd）、插件依赖的宿主 API 兼容探针通过

• 也就是说：在 0.2.x 范围内，in-place 补丁与插件的宿主 API 都有逐版本实测依据；其中 0.2.1-alpha.1 与 0.2.1-alpha.5 已知可正常运行 in-place，完整启动验证过的是 0.2.1-rc.1。其余版本请先在可回退的环境里试。
• 版本差异最大的一处：packages/session/session-persistence-jsonl/src/storage.ts 的 install() 从 0.2.1-alpha.3 起改成了 generator effect + 闭包变量（writers 取代 this.writers，在 generator 内部 this 已不是那个实例）。补丁脚本为此处带两份锚点，会按宿主实际形态自动选择匹配的那份。
• scripts/probe-inplace-durability.mjs 同时适配了 jsonl 后端的两种导出形态：0.2.1-alpha.2 及以前 default export 提供者类，0.2.1-alpha.3 起是 name + apply 的 Cordis 插件。

旧后端 message-edit（保留兼容，不推荐）

• 这是其他开发者发布的第三方插件：https://github.com/Moeblack/dsh-message-edit。
• 本仓库在开发初期引入它，只作为不想给 DSH 本体打补丁时的临时体验后端，不推荐长期使用。
• 它的做法是每次压缩都新建一个分支会话。由此带来几个限制：
  • 每压缩一次就多出一个分支会话，很快会堆满对话列表或归档列表，需要自己清理。
  • 它是分支型后端，不能承接委派：选中它时两条子代理开关会被强制关闭并锁定；再加上默认「有后台工作/子代理时不压缩」，因此在有后台任务或子代理的会话里无法使用。
  • 当前测试不充分，行为不保证。
• 本仓库通过 vendor/dsh-message-edit-0.2.3-patched4.tgz 加 scripts/patch-message-edit.py 来安装与修补它；装完同样要重启 dsh web。
• 它是打包版 DSH（例如 dsh-desktop）唯一可用的后端：只装进 profile，不需要给宿主打补丁。

（旧）message-edit 后端安装流程

本仓库验证过的完整流程是 scripts/install-backend.sh message-edit（官方 CLI 装包 → 打补丁 → 逐字节校验），等价于下面三步：

cd <DSH 源码目录>   # 或用 DSH_CHECKOUT 指定
pnpm dsh plugin --profile web add <本插件目录>/vendor/dsh-message-edit-0.2.3-patched4.tgz
DSH_PLUGIN_ROOTS="$DSH_HOME/profiles/web" python3 <本插件目录>/scripts/patch-message-edit.py
# 校验：解出 vendor 包，与 $DSH_HOME/profiles/web/node_modules/dsh-message-edit/ 下的
#       index.mjs、client.js 逐字节比对（cmp）

需要本机有 pnpm 与 python3。装完重启 dsh web 生效（客户端半边硬刷新即可）。

---

三、安装

1. 安装本插件

前置条件：Node >= 20；DSH 本体能正常启动（插件需要会话持久化 sessionPersistence 服务）。

从 npm 安装：

dsh plugin --profile web add dsh-reasoning-distill

也可以直接从 GitHub 装源码。pnpm 会要求你允许它执行构建脚本 prepare：第一次 add 会失败并打印出包名，把包名加进 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试即可（这等于授权该包在安装时执行代码，请确认信任来源）：

dsh plugin --profile web add github:huhu23333/dsh-reasoning-distill

本地开发（从本仓库源码以 link: 方式装进 profile）：

cd dsh-reasoning-distill
npm install
npm run build
scripts/install.sh web

装完重启一次 dsh web（bundle 元数据要重启才会重新扫描）。

scripts/install.sh 做三件事：构建插件、把 profile 共享的 @deepseek-ai/* 运行时软链进插件、用官方 CLI 把本插件加进 profile。注意：之后只要重跑过 npm install（任何依赖变化），脚本建的软链会被清掉，需要重新执行一次 scripts/install.sh。

2. 装好并选中一个后端

打开「设置 → 思考压缩 → 快速安装后端」，选好后端后可以：

• 用脚本安装：走本仓库验证过的固定流程，可复现、有逐步进度、随时取消，装完自动校验；
• 让 agent 安装：会把对应的安装提示词填进一个新会话的输入框，发不发由你决定。

也可以手动执行。in-place 后端：

node scripts/dsh-inplace-patch.mjs --locate         # 只定位 DSH 源码目录，不改文件
node scripts/dsh-inplace-patch.mjs --apply --build  # 打补丁并构建校验
node scripts/dsh-inplace-patch.mjs --check          # 打全了输出 PATCHED
# 然后重启 dsh web

--checkout <DSH 源码目录> 可显式指定宿主源码位置；脚本找不到时会列出所有试过的路径。

3. 启用

在「设置 → 思考压缩」里：选中一个已安装的后端 → 打开「启用思考压缩」。之后按需调整下面的配置。

---

四、配置项

所有配置都在「设置 → 思考压缩」里。下面按面板的分组说明。

总开关与后端

选项	含义
启用思考压缩（enabled）	总开关，默认关。没有选择后端时强制关闭并锁定。
助手消息改写后端（rewriteBackend）	单选，只列出已安装的后端；再次点击已选中的那一项可以取消选择。

规则（分为"默认规则"和"逐模型规则"）

逐模型规则是稀疏的：没写的字段继续跟随默认规则；没有单独列出的模型一律使用默认规则。

选项	含义
对主对话启用（enabled）	该模型在主对话里是否压缩。
对可续接子代理启用（continuableSubagents）	是否也压缩可续聊子代理（如队友）。默认开，因为它们会持续重发思考。
对一次性子代理启用（oneShotSubagents）	是否压缩跑完即结束的一次性委派。默认关，因为它的最终回答之后没有任何请求会重放这次压缩。
最大生效深度（continuableMaxDepth / oneShotMaxDepth）	两个子代理开关各自带一个深度上限：比该深度更深的子孙代理不再压缩，0 表示不限制。
触发阈值（thresholdTokens）	一步思考估算超过多少 token 才触发，默认 4000。
最低节省（minSavedTokens）	压缩结果至少要比原文省这么多 token 才采用，默认 600；未达到时原文保持不变，但这次蒸馏的开销照样计入。
附带工具调用结果（includeToolResults）	交给蒸馏模型的上下文里是否附上该步工具调用的结果；工具调用本身始终附带。
压缩最终回答轮（includeFinalTurns）	是否压缩没有工具调用的收尾步（最终回答）。
超时（timeoutMs）	蒸馏必须在这个时间内完成；到点就放弃这次压缩（原文不动、不记账），下一步只等这么久。0 = 不设限，一直等到出结果。
背景块长度上限（maxInputChars）	交给蒸馏模型的单个上下文块（例如一条工具结果）的字符上限，0 = 不限。
蒸馏结果长度上限（maxOutputChars）	实际采用并重放的压缩结果字符上限，0 = 不限。
蒸馏服务商 / 蒸馏模型 / 思考强度（distiller.provider / model / effort）	用哪个模型做压缩；思考强度选 off 表示不让蒸馏模型自己再思考。默认 deepseek-official/deepseek-flash + off。

三种会话都关掉时，该规则的其他项不会生效，面板会把它们锁住。

分支后端专用选项（只有选中 message-edit 时出现）

选项	含义
分支超时（branchTimeoutMs）	宿主等待分支型后端建好分支的时限；超时就当什么都没发生，继续在原会话里跑。0 = 永不超时。
建分支后自动归档原会话（archiveSuperseded）	分支继续的是同一件工作，所以新分支显示出来后，把被替换的原会话收进归档（仍可从归档找回）。默认开。

通用

选项	含义
有后台工作/子代理时不压缩（skipWhileBusy）	默认开：只要该会话还有运行中的后台任务或子代理，就当作没触发（不蒸馏、不建分支）。关掉则照常压缩，只是被替换的原会话要等那份工作结束才会归档。

蒸馏提示词

选项	含义
蒸馏提示词（prompt）	替换内置的压缩指令；留空 = 使用内置提示词（可点"预览内置提示词"查看）。

模型价格与峰谷时段

价格只影响报告里算出来的金额，不影响是否触发压缩。

选项	含义
模型价格（prices）	按模型配置，每项三列：命中（cache hit）、未命中（miss）、输出（out），单位是"元 / 百万 token"。只有打开"使用峰谷两栏计价"（peakPricing）时才使用第二栏谷时价。内置 DeepSeek 模型出厂就带两栏价；其他模型默认没有条目、按 0 计算（它们的节省会显示为 0），需要时手动添加。
时段规则来源（peakSource）	builtin：北京时间工作日 9–12、14–18 为峰时，夜间、周末与节假日全天谷价。whale：读取已安装的 dsh-whale-widget 的时段与节假日常量，读不到时自动回退到内置规则。
节假日（holidays）	YYYY-MM-DD 列表，这些日期全天按谷价。可一键恢复内置节假日表。

报告里的几个数字

• 当前单次请求减量：当前生效的改写让这一次请求少带的估算 token，是存量而不是累计；改写被整段压缩淘汰后相应减少，全部淘汰归零。
• 历史累计节省：永不重置。
• 净收益 = 历史累计节省 − 蒸馏开销 − 缓存断裂开销。
• 最近一步未触发的原因：面板会直接给出（总开关关、未选择后端、规则关、未到阈值、这一步没有思考、有多个思考块、有后台工作在跑等）。