dsh-agent-context-pruner

上下文剪枝插件（爱丽丝判断为核心）——开发会话中大部分上下文是一次性消费的残留，剪掉它们省 token 且保护注意力。

安装

cd <你的 self-plugins 目录>
git clone https://github.com/jonah791/dsh-agent-context-pruner.git
cd dsh-agent-context-pruner
pnpm install
pnpm build

设计定调（2026-08-16 主人）

• 「是否无用由爱丽丝自己判断」：插件只提供 候选检测（含缓存代价）+ 执行原语 + 统计；剪不剪、剪哪些、何时剪——决策归爱丽丝（自主性铁律：机制给原语不给剧本）
• 「不能破坏缓存命中」：候选按位置标注剪后缓存代价（其后内容重新 prefill 的一次性成本）。tail（最后 3 节点内）= 零缓存破坏；near-tail 小代价；middle 大代价——middle 仅在「节省 × 剩余轮数 > 缓存代价」时剪
• replay-safe：头+标记+尾替换（官方 dsh-compaction-tool-result-pruner 同款 surfaceOp replace），仅追加事件日志保留完整原始事件（可回放恢复）；替换前写 compaction/prune 定价事件（tokenMeter 定价）
• 白名单：只剪 tool/result 节点；系统注入/主人消息/当前任务轮永不入候选
• 注意力保护（爱丽丝侧判断纪律）：结论已落盘 + 可低成本重取 + 不在当前任务链，三条全满足才剪；剪前自问「主人下一句就问这个，我能答上来吗？」

工具

工具	说明
prune_candidates	候选检测（只读）：扫描当前会话表层 tool/result，列出 seq/轮次/大小/估算 token/超预算/剪后缓存代价/位置提示（tail/near-tail/middle）
prune_apply	执行剪枝（可写）：按 seq 剪指定节点（头+标记+尾），幂等（已剪/预算内自动跳过），返回替换明细与累计统计
prune_stats	统计（只读）：本会话累计剪枝次数/节省字符/节省 token/最近剪枝时间（进程内累计，重启清零）

配置

配置键	缺省	含义
thresholdChars	8192	合并文本超过此码点数才算超预算（缺省阈值）
headChars	4096	保留开头码点数
tailChars	1024	保留末尾码点数

用法

1. 上下文压力高时（或主动巡检）：prune_candidates 查看候选
2. 按判断纪律挑选：tail 放心剪；middle 权衡缓存代价
3. prune_apply({ seqs: [...] }) 执行
4. prune_stats 查看节省

每轮缓存命中率（v0.1.2+）

prune_stats 输出每轮每次模型请求的 provider 实测命中率（usage 透传）： hitRate = cacheRead / (input + cacheRead + cacheWrite)（DeepSeek adapter 从 prompt_tokens 中减出缓存计数）。

实证（2026-08-16 turn 102，剪 middle 节点 730739 前后）：

• 剪前 step 1-4：命中率 99.27% / 99.96% / 99.88% / 99.91%（cacheRead ~18.9 万）
• 剪后 step 5（第一个请求）：20.89%——input 从 ~200 暴涨到 149,826（剪枝点后全部重新 prefill，一次性代价）
• step 6-7：99.65% / 99.96% 完全恢复（新前缀被缓存）

结论：middle 剪枝 = 一次性重新 prefill 代价（实测 ~15 万 token）+ 长期每轮省下被剪内容；恢复后命中率回满。tail 剪枝零破坏（剪后序列是原前缀）。数据与候选标注的 cacheCostTokens 模型吻合。

入口守卫（v0.2.0+，核心：主人北极星「不破坏缓存命中 + 上下文内容有效」）

大工具结果在产生时（append 后 setImmediate）立即折叠为「头 1024 + 尾 512 + 标记」——模型首次看到的就是折叠版，原文从未进过上下文（无「先 prefill 再剪」的浪费）；确定性折叠 → 缓存前缀稳定 → 命中率不破坏。事件日志原文保留（replay-safe）。

• expand(callId)：按 callId 恢复全量（surfaceOp replace 回原文；豁免集防再折叠）
• prune_guard：查看/切换守卫（mode=on/off；阈值配置 guardThresholdChars 4096 / head 1024 / tail 512）

验证（2026-08-16 18:47）：返回 9k/12k 字符大结果 → 模型看到头+尾+标记（含 expand callId）→ foldedCount+1 → expand 恢复全量（替换节点落地）→ 命中率保持 99.5%+。

注意：run_code 嵌套工具（read 等）的结果不产生会话 tool/result（worker 内执行）；只有 run_code 自身返回进上下文——守卫对会话级工具结果生效。

验证记录（2026-08-16）

• 候选扫描：真实会话 66 个 tool/result，超预算 3 个（最大 49k 字符/12k token），位置/缓存代价标注正确
• 执行剪枝：seq 745172（9637→5159 字符，省 2422 token），替换节点落地（surfaceOp replace），compaction/prune 定价事件写入
• 幂等：已剪节点不再出现在候选
• 修复记录：session.append 解绑导致 reading 'log' 崩溃 → .bind(session) 保持 this

相关

• 我的数字生命爱丽丝 — 插件生态中心（架构总览）

License

MIT