DeepSeek Harness 上下文压缩机制：13 帧图文拆解
跟着源码级拆解视频逐帧看懂 dsh 压缩：什么时候触发、裁什么、摘什么，日志又怎么在替换后重建整个会话。
最近更新: 2026-09-23
这页图文基于一支源码级拆解视频，逐帧讲清 DeepSeek Harness 的上下文压缩机制。先说清画面属性：原片是旁白讲解的机制示意动画——作者用幻灯片把压缩流水线一步一步画出来，不是产品界面实录。也正因为是示意，每个机制都被干净地隔离在一页里，适合当架构课本来读。
文中关键数值——80% 默认触发阈值、8192 码点裁剪（保留开头 4096 + 结尾 1024）、16% 近期原文保留——已对照 deepseek-harness 官方仓库文档核验一致（thresholdRatio 0.8、thresholdChars 8192、retainRatio 0.16，2026-09-23 查证）。官方文档没有展开的细节（如检查点的八类信息划分）来自作者小木头对源码的解读，文中已标注。
一分钟版本
- ▸压缩在 dsh 里是插件能力而非内置逻辑：ctx.compaction 是能力接口，compaction-basic 是默认实现；上下文占用接近窗口 80%、服务端报超窗、或你手动输入 /compact，都会触发整理。
- ▸摘要之前先裁剪：超过 8192 码点的工具结果只保留开头 4096 和结尾 1024；裁完若压力达标，连摘要这步模型调用都省了。
- ▸被压缩的历史变成结构化检查点，最近约 16% 窗口原文保留；持久日志完整记录每个事件，模型视图随时可以靠重放重建。
压缩流水线，12 步走完
压缩在架构里的位置
- 1
先看位置：DeepSeek 的请求链里多了压缩一段
视频开场对比请求结构：Codex 式请求是输入 + 上下文 + 模型请求，DeepSeek Harness 在上下文和模型调用之间插入了一个专门的压缩阶段。这页就是整支视频的地图——压缩是请求流水线里的正式一环，不是事后补救。
请求流水线在上下文和模型调用之间多出压缩一段。去视频 0:32 处看 - 2
认角色：一项能力，多个插件协作
压缩被拆成一条能力缝：/compact 命令是人工入口，ctx.compaction 是能力接口，compaction-basic 是接口背后的默认实现；旁边还有两个可选搭档——负责计量压力的 token meter 和负责裁剪工具结果的 tool result pruner。把 compaction-basic 换掉，其余照常工作。
$ctx.compaction$dsh-compaction$compaction-basic$command-compact
一条能力缝、五个角色：命令、接口、默认实现加两个可选搭档。去视频 2:18 处看 - 3
记住三个触发入口
压缩从三个地方启动。每次请求前的 pre-step 检查会把估算压力和默认 80% 阈值（可按模型配置）比较；服务端已经报超窗时，恢复流程跳过常规阈值、先修复现场；你在 agent 空闲时输入 /compact，则不等 80% 直接按需整理。
$agent/pre-step$context-overflow$/compact · agent idle
三条启动路径，只有第一条真的等 80%。去视频 3:50 处看 - 4
看懂计量表：提供商读数 + 变化估算
token meter 对自己的定位很诚实：它以最近一次成功调用的提供商用量为锚点，再估算这之后模型可见内容的变化——新增消息往上加，替换可能往下减。片中的进度条是定性示意，不代表实测比例。
计量表是估算：上次官方读数，加上之后的漂移。去视频 4:20 处看
裁剪、选区与摘要
- 5
先裁日志，再谈测量
第一个杠杆不是摘要，是删除。一条超长工具结果就能占满大半个上下文，把它的中段裁掉，压力可能直接回落到阈值以下。后面几章的机制，都默认这道最便宜的工序已经跑过。
先裁再说——一条巨大的工具结果可能就是全部问题。去视频 1:15 处看 - 6
拆裁剪器：8192 码点，保留 4096 + 1024
工具结果文本超过 8192 个 Unicode 码点（三个 Web 预设当前的配置）就会被重写：保留开头 4096 码点、一条裁剪标记、结尾 1024 码点。计量单位是码点不是 token，而且这一步完全不调用模型。这两个数值与官方 compaction-tool-result-pruner 默认值（thresholdChars 8192、headChars 4096、tailChars 1024）一致。
$threshold: 8192 code points$keep head 4096 + tail 1024
8192 码点是门槛；开头 4096、标记、结尾 1024。去视频 5:40 处看 - 7
选区：近期 16% 原文保留，切线避开配对
裁完压力还超，compaction-basic 就开始选区：从最新消息向前累计，原文保留到大约 16% 窗口预算为止（即官方 retainRatio 默认值），并且切线永远落在工具调用和它的结果之外——配对不拆散。按完整消息节点累计，实际保留量可能略超 16%；此时只是选定区间，还没有生成任何摘要。
从最新往前走，切线永不落在调用与结果之间。去视频 6:00 处看 - 8
生成检查点：compaction/start 与八类信息
摘要以追加指令的方式运行：请求保留原 system、原 tools 和选定的旧消息，末尾追加一条 user 消息，要求把对话整理成结构化检查点。视频把它画成八类信息——用户目标与意图、关键技术概念、文件与代码、错误与修复、待完成工作、当前工作、下一步行动、关键背景与约束。官方文档确认存在检查点前言，八类的具体划分是作者的示意解读。
$compaction/start
摘要指令要求产出结构化检查点——八类是作者的示意画法。去视频 7:05 处看 - 9
摘要合格，才准替换
摘要要过三道关才能顶替历史：模型完整结束并给出非空文本（报错、中断、达到输出上限截断都算失败）；只保留 text 内容——reasoning 和 tool calls 不写入检查点，图片输出直接拒绝；含包装的摘要估值必须小于被替换旧区间的估值。
任何一关不过，摘要都到不了模型面前。去视频 7:56 处看
替换、重放与边界
- 10
日志只追加，模型视图被替换
成功之后，持久日志追加 start、summary、checkpoint、end 一串事件，而模型可见历史通过一次表层替换换新——画面里写作 surfaceOp: undefined：检查点在前，保留下来的近期原文在后。上游什么都没删，日志仍是完整记录。
$surfaceOp: { op: 'replace' }$compaction/start · summary · end
日志只增不减，被换掉的只是模型视图。去视频 8:48 处看 - 11
恢复靠重放日志
因为日志只追加且完整，恢复从不需要原始上下文：按事件顺序读回，逐条应用 surfaceOp 的 append 或 replace，模型视图就重建出来了——旧内容、检查点、近期原文各归其位。被压缩过的会话能挺过重启，靠的就是这个。
$surfaceOp: append / replace
恢复就是对只追加日志的确定性重放。去视频 9:05 处看 - 12
收束：接口稳定，实现可换
结尾页把整条流水线收成四个动作——测量压力、裁剪工具结果、按需摘要、替换模型视图——并划清分工：ctx.compaction 保持稳定，compaction-basic 是当前默认实现，agent loop、token meter 和 /compact 入口环绕在外。每一块都能独立演化而不牵连其他。
四个动作、一个稳定接口、一个可替换实现。去视频 10:00 处看
对应官方 0.1.7 的部分
这页拆的是插件流水线，而官方 0.1.7 版本线正从产品侧打磨同一处接缝——alpha 更新说明写明为主动压缩预留输出容量与上下文余量，长命令超时后可转入后台继续跑。想算清这些长任务的真实开销， 看这份 token 用量与成本追踪指南.
常见问题
触发、丢失与上限——画面本身说不清的部分。
压缩是怎么触发的？会不会打断我正在跑的任务？
三个入口：请求前预检（默认 80% 阈值）、服务端超窗恢复、以及空闲时手动 /compact。触发点都在请求之间，不会拦腰打断正在生成的回合；/compact 在 agent 忙碌时会提示暂不可用，你排队发出的消息等它跑完再继续。
压缩之后上下文会不会丢？
旧回合的原文会离开模型视野，但不是凭空消失：它们被整理成覆盖目标、文件、错误、待办的结构化检查点；最近约 16% 窗口原文保留；持久日志里每个原始事件都还在。丢的是模型对旧原文的直接引用，不是记录本身。
8192 码点裁剪，会不会把重要的工具输出砍断？
有可能，这是设计取舍：裁剪器只认位置不认语义，保留开头和结尾，中段一律替换成标记。好处是确定性——绝不把 emoji 之类的代理对切坏；代价是语义上重要的中段内容，要靠你自己在必要时重跑命令取回。
这些数字是写死的吗？
不是。80% 是 thresholdRatio 默认值，16% 是 retainRatio 默认值，都能按提供商和模型分别配置；裁剪器的 8192/4096/1024 码点预算同样可配。本文数值以 2026-09-23 官方仓库文档为准——把它们当当前默认值，不是常量。
长任务还是被截断了，压缩救不了怎么办？
压缩救的是会话太长，救不了单件超大产物：系统提示、工具定义、会话前缀压不动，一条巨大的工具调用也不会被拆开。这种情况把任务拆小，或转给子代理、后台任务去跑，让主会话只收结论。
相关攻略
DSH 学习路线里的相邻课题。
DeepSeek Harness Token 用量与成本追踪
压缩省了多少，量出来才算数：会话内、日志里、提供商账单页三处对账。
阅读指南DeepSeek Harness 四种模式对比
standard、code（PTC）、cordis 三个 Web 预设共用同一套压缩组合，其余差异看这篇。
阅读指南DeepSeek Harness 故障排查手册
超窗报错、压缩重试这些长会话高发故障，一次给到位的修法。
阅读指南DeepSeek Harness 子代理实战指南
一个上下文不够用时：把长任务拆给子代理和后台任务，别硬撑单线程。
阅读指南dsh TUI 终端上手
ask_user_question 与后台任务同屏的终端，长任务挂后台的理想搭档
阅读指南来源与署名
全部 13 帧画面截自同一支视频——旁白讲解的机制示意动画，非官方产品界面、非实机录屏；每张图都可深链回原片对应秒数。同一支拆解在 YouTube 由 01Coder、在 Bilibili 由 五里墩茶社 发布（同一作者：小木头）。