stultuss/dsh-clear-tool-results

Listed on dsh-plugin.org

dsh-clear-tool-results

维护状态：【弃用/归档】

0.7.0 为最后一版，不再做功能维护。 原因与适用边界见下节：在 DeepSeek-V4.1-Flash 的真实峰价下，本插件的成本收益不成立；

DSH 宿主插件：把工具结果按轮归档并从对话上下文中清除以减少 Token 消耗；模型可用 read_tool_result_log 按轮次或时间自主取回原文。

维护状态与适用边界

已归档，0.7.0 为最后一版。归档原因：成本口径下不成立。

DeepSeek-V4.1-Flash 官方峰价（官方价目）：输入命中 $0.006/M、输入未命中 $0.30/M、输出 $1.20/M——命中价只有未命中的 1/50（c = 0.02）。在这个价目结构下，按 10 轮 × 10 步、每步 1 Think + 1 个 1K 工具结果（T = 1000/步、占位符 p = 35 token）推算：

| 单步 Think | 省（占基线 input 成本） |
| --- | --- |
| 0（无思维链） | 47.2% |
| 300 | 28.0% |
| 1000 | 5.6%（$0.0066；占含输出的总账单 2.8%） |
| ≥ 1,312 | 0（盈亏平衡点） |
| 2000 | −8.3% |

两个让 5.6% 在真实使用中进一步归零的结构性原因：

- 「不清除」的基线本身命中率已达 98%（9,702,000 / 9,900,000）：前缀天然稳定，「保住缓存」没有可保的空间，清除只可能引入重算。每轮边界都要把上一轮尾部（9T + 10p）按全价重算一次，9 次边界即 66,150 token；而重算代价随 T 线性增长——带 tools 的请求必须回传历史 reasoning_content 并拼进上下文（官方 thinking_mode 文档），所以每步 Think 都真占 prompt。
- 一次取回就能吃掉大半收益：取回一条 5K 结果 ≈ 5K 走全价 + 一个额外助手回合的 Think 输出 ≈ $0.0027，相当于 10 轮省额的 41%。

它仍然成立的地方：

- 上下文头寸，与价格无关：同一算例的上下文峰值 198,000 → 111,150（−44%）。会话本来会撞上下文上限时，它买的是「跑得完」，不是「省钱」。
- 短思维链 / 无思维链：T = 0 省 47.2%、T = 300 省 28.0% 的 input。
- 命中价占比更高的模型：c = 0.25 时省基线 input 的 39.5%，回到与 token 省额同阶的量级；c 越小越不划算，DeepSeek 的 1:50 是最极端的一档。

下文「缓存命中与成本分析」里的 4.3%~20.3% 是按 c = 0.25 假设算的，不是 DeepSeek 真实峰价；按 c = 0.02 重算会显著下调、部分情形转负。该节保留为测量记录——断点位置（上一轮第一个工具结果）、保留率 33%~47%、占位符需字节级固定等约束都是实测结论，仍然有效；原始 token 净省额 4,342,500 与 Think 长度无关，也仍然成立。但它不再作为价值主张。

代码仍可安装使用；归档只是不再把它当省钱工具宣传，也不再跟进 DSH 核心变化。

兼容性

同一份代码支持三代核心，无需改配置或按环境区分：

| 核心代数 | 差异 | 插件行为 |
| --- | --- | --- |
| 老核心 | 事件数组为 session.events | eventsOf() 回退读 session.events |
| ≥ 0.1.2-rc.1 | 事件数组改为 session.log | eventsOf() 优先读 session.log |
| ≥ 0.1.5-rc.1 | surface replace 键名改为 startSeq/endSeq | 按会话头版本选键名，被拒时换另一代重试一次 |

安装

dsh plugin --profile web add dsh-clear-tool-results

在 ~/.dsh/profiles/web/cordis.patch.yml 注册：

- insert:
- id: clear-tool-results-host
name: 'dsh-clear-tool-results'

使用

| 命令 | 效果 |
| --- | --- |
| /clear-tool-results on | 启用：工具结果按轮归档，并在下一轮开始前从对话清除 |
| /clear-tool-results off | 停用：保留工具结果、不再归档 |
| /clear-tool-results status | 显示启用状态与插件版本 |

状态存于 $DSH_HOME/clear-tool-results.json（DSH_HOME 未设置时回退 ~/.dsh）：{ "enabled": true }；旧的 { enabled, mode } 仍可读，mode 被忽略。

功能

0.7.0 保留的能力就是下面这几条：每轮归档 → 按轮清除（留占位符）→ 模型按需用 read_tool_result_log 取回。

- 归档：每轮结束时，从追加式会话日志（而非改写后的 surface）取出该轮原始 tool/result，保留轮次/步骤号、工具名与匹配的 tool/call，写入 round-NNNN.json 并登记 index.json；以 index 为准、幂等，可补归档中途启用或重启前的轮次。
- 清除：turn/end 把该轮 surface 节点替换为占位符，例如 [第 3 轮工具结果已清除归档：bash → git status（1.2k），可用 read_tool_result_log(turn: 3) 读取]。
- 归档上限 49000 字节（UTF-8）：超限结果不归档——harness 的 spill 策略在 50000 字节处把结果换成「首尾预览 + 通知」并从中间掐掉，存了也取不回完整原文。占位符写成「已清除（该结果 49.5k 字节，超过 49000 字节上限，未归档）…。未保存原文，如需请重新执行原工具获取」，不给取回坐标；同轮若还有可归档结果则保留坐标并追加「本轮另有 N 条超 49000 字节的结果未归档，需要时请重新执行原工具」。规则同时写进工具描述，随工具注入 Agent。
- 占位符索引：占位符带紧凑索引——工具名 → 关键参数（命令/路径/模式）+ 规模 + 是否失败，整行压到 60 字以内；同一步的多条合并成一行（最多列 2 条，其余归入「等 N 条」）；PTC（run_code）下优先显示里面的子调用（bash → git status），而不是 run_code 的代码前缀。让模型先知道「里面有什么」，再决定要不要取回。
- 取回：read_tool_result_log 注册为模型工具，按 turn 或 time 读取。返回紧凑纯文本（非 JSON）：每条以 --- turn N step S · 工具名 · 参数摘要 · 第 A-B 行 / 共 T 行 · N 字符 / M 字节 --- 开头（参数摘要为空时省略；offset 越过末尾时行窗口显示为「第 T 行之后无内容（共 T 行）」），后接原文。
- 输出预算 48000 字节：按整份载荷计（含表头与末尾通知 ⇒ 整份 ≤ 48400 字节，永不触发 harness 截断）；正文 ≤47.7k 字节可一次取回；更大的结果需带 offset/limit 分段，被截断的条目会附「续取：offset=…」坐标；若单条超出预算且未分段，则跳过该条并提示改用 offset/limit。
- 依赖：仅 Node 内置模块；适用于所有会话与 agent preset；与 DSH 内置 compaction 兼容。

0.7.0 的功能面 = 每轮归档 + 按轮清除（占位符索引）+ read_tool_result_log 取回，外加 49000 字节归档上限与分页。overclock 模式、配套核心补丁、归因埋点与逐轮追踪日志均已移除。每步清除解决不了「模型把自己的输出当缓存」：实测 ≤49000 字节的已清除结果里，事后只有 5.5% 走取回、52.6% 靠记忆代偿（41.2% 抄进推理、11.3% 抄进可见正文），而推理会被适配器以 reasoning_content 回灌上下文。

缓存命中与成本分析

本插件对工具结果的处理是每轮结束后原地替换为固定占位符，而非直接删除。但省 Token 的主力是「清除」这件事本身：历史不再携带全部工具结果。占位符的作用是保住 tool_call/result 配对，并给模型留下取回索引。

前缀缓存：断点落在上一轮第一个工具结果处

DeepSeek 的上下文缓存是块对齐的前缀缓存（实测会话里 cacheReadTokens 全部是 64 的整数倍）：从第 1 个 token 开始连续完全一致的部分才能复用 KV，一旦某个位置不匹配，从该位置往后全部未命中。

清除发生在 turn/end：上一轮的工具结果被替换成占位符，而占位符与真实结果字节不同——所以下一轮首个请求必然在「上一轮第一个工具结果」处断开，与直接删除断在同一个 token 位置。

Agent 多步调用中，工具结果天然穿插在助手消息之间：

S  U1  A1  T1  A2  T2  A3  T3

S：系统提示 + 工具定义
U1：用户消息
A1 A2 A3：助手思考/调用
T1 T2 T3：工具结果

下一轮首个请求里，上一轮的 T 已经变成占位符 P：前缀比对到 A1 结束时撞上 P1 ≠ T1，于是 A2 P2 A3 P3 U2 … 全部按全价重算。

实测（~/.dsh/sessions 中清除真正生效的会话；命中 = cacheReadTokens，保留率 = 命中 / 上一轮末 prompt）：

| 会话 | 上一轮步数 | 上一轮末 prompt | 下轮首请求 prompt | 命中 | 保留率 |
|---|---|---|---|---|---|
| session-2b193d28 | 10 步 | 38437 | 28081 | 12672 | 33.0% |
| session-ce28482c | 13 步 | 34399 | 27539 | 11392 | 33.1% |
| session-3e1783ea | 2 步 | 32345 | 17849 | 15232 | 47.1% |
| session-d19ab3bd | 15 步 | 36768 | 28696 | 14464 | 39.3% |

判定式：命中 ≈ 上一轮首请求 prompt + 上一轮首条助手消息（9 个边界误差  执行 python3 -c "import secrets; print('DSH-DEMO-' + secrets.token_hex(8))"。
只回复「完成」，不要复述命令输出，也不要在思考或正文里出现任何 token。

工具结果先显示完整值，随后被替换为占位符：

[第 1 轮工具结果已清除归档：bash → python3 -c "..."（26），可用 read_tool_result_log(turn: 1) 读取]

✅ 检查点 1：第 1 轮回复里不得出现 DSH-DEMO-。一旦出现，说明 token 已写进对话，之后可能靠记忆而非取回答对。

第 2 轮：显式跨轮取回

发送：

调用 read_tool_result_log({ turn: 1 }) 取回第 1 轮那条命令的原始输出，把完整 token 原样发我；不要用 bash/read 翻文件。

预期发起的工具调用与返回（工具名/行数/字节数随调用方式与输出浮动；直接调用 bash 时表头显示 bash，PTC/run_code 下显示 run_code）：

查询：第 1 轮

--- turn 1 step 1 · bash · {"command":"python3 -c \"...\""} · 第 1-N 行 / 共 N 行 · … 字符 / … 字节 ---
DSH-DEMO-xxxxxxxxxxxxxxxx

取回提示：归档在每轮结束时写入，之后随时可读；如需引用多轮原文，可在总结前逐轮取回。

通过标准

1. 第 2 轮确实调用 read_tool_result_log({ turn: 1 })，而不是用 bash/read 绕过。
2. 返回体以 查询：第 1 轮 开头，--- turn 1 step 1 · … --- 表头之后是原文。
3. 模型回答的 token 与第 1 轮归档里的 token 逐字相同——随机值意味着不可能是背出来的。

可选扩展

- 空参数 read_tool_result_log({}) → 已归档轮次：turn 1（…步，…条），确认归档已登记。
- 中间多聊几轮后再问同一问题 → 仍取回同一 token，证明取回与轮次间隔无关。
- 用 time 参数（取 index.json 中该轮的 timeFrom 毫秒值）→ 命中同一轮。

一键核对

grep -o 'DSH-DEMO-[0-9a-f]' ~/.dsh/sessions///tool-result-logs/round-0001.json

输出应与第 2 轮回答中的 token 一致。

验证

跨轮取回：见上一节 Demo（随机 token + 通过标准）。

超限回归：跑一条 >49000 字节的输出（如 python3 -c "print('中'16600)"）→ 占位符应写明「该结果 49.8k 字节，超过 49000 字节上限，未归档」，且 tool-result-logs/ 下不得出现该条目的归档记录。

文件检查：

ls ~/.dsh/sessions///tool-result-logs/
cat ~/.dsh/sessions///tool-result-logs/round-0001.json

卸载

1. 删除 cordis.patch.yml 中的注册行；
2. dsh plugin --profile web remove dsh-clear-tool-results；
3. 可选：删除 $DSH_HOME/clear-tool-results.json、$DSH_HOME/clear-tool-results.log 与各 tool-result-logs/ 目录。

链接

- GitHub:
- npm:

License

MIT