English | 中文
缓存感知的 dsh（DeepSeek Harness）压缩引擎插件——压缩前判定前缀缓存冷热：热时维持原生前缀重放（命中缓存、几乎免费），冷时切换转录式压缩（避免重放大段前缀却全 miss 的白付）。
DeepSeek API 2026-08-17 起涨价并引入峰谷定价，缓存命中/未命中输入价差达 30 倍（hit 0.10 vs miss 3.00 元/百万 token，flash 高峰价）。dsh 原生压缩（dsh-compaction-basic）用「前缀重放」构造压缩调用——缓存热时几乎免费，缓存冷时整段重放按 miss 价付费。本插件在压缩触发时先判定冷热，冷时改用转录式压缩（专用摘要提示 + 扁平化转录），实测把压缩调用输入从重放的 U(1−R) 降到转录的 T ≈ 38% × U(1−R)，缓存真冷时省 62% 的压缩调用输入成本。
压缩触发（agent/pre-step 或 context-overflow）
└─ 判定：倒序扫描会话日志，取最近一次同 (provider, model) 调用的 usage
v0.2 盈亏平衡规则（替代 v0.1 的 cacheRead > 0 布尔判定）：
R = cacheRead / (cacheRead + uncached)
热 ⟺ R ≥ (1 − τ·(1+margin)) / (1 − ρ)，τ = T/U（压缩点精确估算）
cacheWrite > 0 → 热（首写必命中）；样本过期（cacheTtlSeconds）→ 冷
├─ 热 → 原生前缀重放（super.summarize，与 stock dsh 逐字节等价）
└─ 冷 → 转录式压缩（TRANSCRIPT_SYSTEM_PROMPT + 扁平化转录 + 8 段 checkpoint 指令）
└─ 回退保护：转录估算 ≥ 重放估算时自动退回重放路径
- 服务名保持
"compaction"→/compact手动命令、上下文溢出恢复、tool-result pruner 全部自动兼容 - 配置：
coldMode: transcribe | refuse（默认 transcribe）、cachePolicy: auto | hot | cold（hot/cold 为实验覆盖） - 冷热记忆按
(provider, model)隔离——模型切换后判定归零重算（已由 GUI 实测两次切换验证，见 M3 报告 §7.4） - 只覆盖基类两个钩子（
summarize/compactIfNeeded），范围选择、事务、落盘、稳定性校验全部复用基类
v0.1 用 cacheRead > 0 判热。M3 报告 §2 记录了它的盲区：opencode-go 中继对任何请求都报 cacheRead ≈ 8064（跨会话共享的 harness system prompt 前缀缓存）——在这种路由上 v0.1 恒判热，冷路径永远走不到。v0.2 改为比较两条路径的期望输入成本（以 miss 价为 1）：
重放成本 = U · (1 − R + R·ρ) # R 为命中率，ρ = hit价/miss价
转录成本 = T # 全按 miss 价
热划算 ⟺ R ≥ (1 − τ·(1+margin)) / (1 − ρ) τ = T/U
- τ 在压缩点精确估算（同一份 input 既算转录 token 也算重放 token），临界值不是拍脑袋的常数，而是随会话形态浮动的盈亏平衡点；
- refuse 预检发生在基类构建 input 之前，用
assumedSavingsRatio（M3 实测 T/U ≈ 0.38 → 临界 R ≈ 0.60）近似，summarize阶段再用精确值复判； cacheTtlSeconds（默认 3600，0 关闭）：带time的 usage 样本超过该时长按陈旧处理判冷——v0.1 已知缺陷「长空闲后被驱逐仍判热」的可配置缓解（dsh 事件携带 epoch 毫秒time，dsh-session/lib/index.js:1460）；- 平局判热：判错的代价只是多付重放价，不会偏离 stock 行为。
用 M3 中继数据代入：短会话（R = 8064/12064 = 0.67 ≥ 临界 0.60）判热正确；长会话（R = 8064/28064 = 0.29 < 临界）判冷——v0.1 在这里会白付 2 万 token 的全价 miss。
| 指标 | 数值 |
|---|---|
| 冷压转录输入 T vs 热压重放 U(1−R) | 4.6K vs 12.2K（38%） |
| 缓存真冷时压缩调用输入成本 | 省 62%（0.146 → 0.056 元/次，flash 高峰价） |
| 热路径与原生一致性 | 逐字节同构；实测命中画像一致（77% vs 66-96%） |
| 摘要质量 | 8 段 checkpoint 全部落盘；压缩前事实压缩后复述全对 |
| 单测 | 73/73 全绿（config 12 + decision 22 + transcript 18 + engine 21；v0.2 新增盈亏平衡/TTL 12 例） |
| 模型切换缓存隔离 | 跨 provider 与同 provider 仅切模型，切换后首请求 cacheRead 均归零（实证） |
完整数据与实验方法：docs/cache-aware-m3-report.md。
背景：v0.2 的 cacheTtlSeconds=3600（1h）是「provider 驱逐策略无文档」时的保守读取（M3 §6 长空闲失效模式）。
实测（command-code 中继，会话空闲 17h 后 resume）：
| 时刻 | cacheRead | 说明 |
|---|---|---|
| 空闲前最后一条 | 59,264 | 会话前缀缓存基线 |
| 空闲 17h 后第一条 | 59,648 | 无驱逐（还涨了 384） |
| 空闲 17h 后第二条 | 60,288 | 持续命中（确认非波动） |
结论：command-code 的缓存驱逐窗口实测 >17h——1h 的默认值在该环境偏保守（会把空闲 1h 后仍热的会话误判冷、走转录，多付压缩钱，但方向安全）。
默认值决策：保持 3600（保守），不做环境拟合。引擎是通用组件，command-code 的观测不代表 DeepSeek 官方 API 等其他 provider 的驱逐策略（官方 API 未实测）；3600 对驱逐窗口未知的环境是安全默认。若你的 provider 已知长保留缓存，可调大 cacheTtlSeconds（见配置说明）。
独立设计，原创性自证（英文版见 README_EN.md）。
- 动机：DeepSeek 2026-08-17 涨价并引入峰谷定价，缓存命中/未命中价差达 30 倍（hit 0.10 vs miss 3.00 元/百万 token，flash 高峰价）；压缩调用在冷缓存下重放整段前缀，全按 miss 价付费。
- 时间线：
- 08-13 — 逆向研究 Reasonix（esengine/DeepSeek-Reasonix），致谢其转录式压缩设计启发。
- 08-15 14:36Z — 独立设计，本仓库创建于 14:36Z。
- 08-15 18:09Z — Zhuchen00123/dsh-compaction-cacheaware 发布同思路项目（晚 3.5 小时创建，同为涨价驱动）——平行独立发明，无交集。
- 独立决策点：冷热判定（cacheRead/cacheWrite 归零检测）、转录式压缩（T ≈ 38% × U(1−R)）、回退保护（转录估算 ≥ 重放估算时自动退回重放路径）。
- 致谢：Reasonix（esengine/DeepSeek-Reasonix）设计启发。
前置：本机已安装 dsh（验证于 0.1.1-rc.2 版本线，见下方版本说明）。
# 1. 安装插件到 web profile（本地路径安装）
dsh plugin --profile web add file:/path/to/dsh-cache-aware-compaction/dsh-compaction-cache-aware
# 2. 创建/复制 agent preset（见 examples/agent.cordis.yml 思路）
# 把 compaction 组里的 compaction-basic 行替换为：
# - id: compaction-cache-aware
# name: '@septtpes/dsh-compaction-cache-aware'
# config: { coldMode: transcribe }
# 3. settings.yaml 选择该 preset
# agent-presets:
# default: <your-preset-id>headless 环境的挂载方式（cordis.patch.yml disabled + insert）与坑位见 docs/dsh_cache_aware_compaction_recon.md §1 及实验脚本 experiments/scripts/run-m3.sh。
coldMode: transcribe # 冷缓存时的行为：transcribe=转录式自动压缩；refuse=跳过压缩（仅 pressure；overflow 从不拒绝）
cachePolicy: auto # auto=按 usage 判定；hot/cold=强制路径（实验/对照用）
hitPriceRatio: 0.0333 # ρ=hit价/miss价（DeepSeek flash 高峰 0.10/3.00 → 1/30），盈亏平衡公式参数
savingsMargin: 0.1 # 转录须比重放便宜出该相对边际才判冷（平局偏热，防 CJK 低估 T）
assumedSavingsRatio: 0.38 # refuse 预检用的 T/U 近似（M3 实测 4647/12192）
cacheTtlSeconds: 3600 # usage 样本超过该秒数按陈旧判冷；0=关闭（长空闲驱逐的可配置缓解）。实测参考：command-code 中继驱逐窗口 >17h（2026-09-03 B8 取证），若 provider 已知长保留可调大；保守默认 1h 安全（误判冷只多付钱，不偏离 stock）
# 其余键与 dsh-compaction-basic 完全一致（thresholdRatio/retainRatio/summarizationProvider/
# summarizationModel/maxTokens/modelPolicies/...），透传基类注意：coldMode: refuse 在部分中继路由（如 opencode-go）上会导致任务被 max-tokens 截断——该路由的超窗请求不报 CONTEXT_WINDOW_EXCEEDED，overflow 兜底永不触发。中继路由建议保留默认 transcribe（详见 M3 报告 §7.3）。
dsh-cache-aware-compaction/
├── dsh-compaction-cache-aware/ # 插件包（lib/ + test/，61 单测）
├── docs/
│ ├── dsh_cache_aware_compaction_plan_input_2026-08-15.md # 任务输入（自包含）
│ ├── dsh_cache_aware_compaction_recon.md # 源码侦察笔记（行号证据）
│ ├── plan-cache-aware-compaction-v0.1.md # 决策完备实施计划
│ ├── cache-aware-m3-report.md # 四组对照实验报告
│ ├── model-compare-report.md # 多模型对照实验（flash/glm/mimo）
│ └── dsh-plugin-plan-build-workflow-template.md # plan/build 双会话工作流模板
├── experiments/ # 可复现实验（脚本已参数化路径；需 dsh + API key）
└── LICENSE # MIT
# 在装有 dsh 0.1.1-rc.2 版本线的机器上（依赖从 dsh 安装的 node_modules 解析）：
cd dsh-compaction-cache-aware && node --test版本说明：npm registry 上 @deepseek-ai/dsh-* 已发布 0.1.1-rc.2（2026-08 复核），本插件的 peerDependencies 对应 ^0.1.1-rc.2（支持范围：dsh 0.1.1-rc.x 版本线，引擎基类 API 与 0.1.0-rc.x 逐字节一致），CI 已启用 push/pull_request 自动触发。本包未发布 npm，安装走 dsh plugin --profile <name> add file:... 本地路径；若你要发布到 npm，以 @septtpes scope 直接发布即可。
MIT © 2026 SeptTpes