DeepSeek Harness 压缩进度可见性:基于 `compaction/start–end` 标记对的 TUI 实时独立压缩状态显示
DeepSeek Harness 压缩进度可见性:基于 compaction/start–end 标记对的 TUI 实时独立压缩状态显示
独立手动压缩(compaction)在 agent 空闲的轮次间隙运行,这一阶段既没有轮次阶段字形、也没有落地检查点,长时间摘要操作期间用户几乎无法感知系统正在工作。本篇技术指南以 DeepSeek Harness 存档的架构决策笔记 .agents/notes/archived/feature/2026-07-30-compaction-progress-visibility.zh.md 为核心,讲解项目如何用持久日志中的 compaction/start { turn: null } 与 compaction/end 标记对作为"正在压缩"状态的唯一真源(source of truth),在 TUI 提示词上方渲染带已用时间的固定行、以 ⊙ 呼吸动画复用现有运行状态指示器,并保证崩溃恢复后绝不会回放出虚假的进行中状态。读完本文,你将掌握这套实时状态与持久历史解耦的设计方法,以及它如何与排队式手动压缩、transcript 投影决策协同工作。
背景:为什么独立压缩需要专属的进度显示
压缩是 DeepSeek Harness 的一项可选能力(capability seam),分为自动压缩(压力策略触发)与手动压缩(/compact 命令、轮次间隙执行)两条路径,事件协议与事务顺序由 packages/compaction/compaction-basic 实现。独立手动压缩(standalone manual compaction)与带编号的自动压缩有本质区别:
- 没有轮次:它运行在轮次之间,agent 保持空闲,因此 TUI 的轮次阶段指示器始终显示普通的
>光标,无法表达"正在工作"。 - 没有中间产物:摘要过程缓慢时,由于替换检查点尚未落地,不会产生新的 transcript(文本记录)行,用户看到的会话如同停滞。
- 恢复存在陷阱:进程终止后,持久日志中可能保留未匹配的
compaction/start。这个未匹配标记是有用的恢复证据(说明上一次尝试没有完成),但无法证明当前进程中有工作正在运行——如果把它回放成进度,恢复后的会话会永久显示一条虚假的进度指示。
因此该决策要解决的是三个叠加的问题:空闲期的工作可见性、失败时的用户反馈、以及恢复时对陈旧日志的正确解读。
核心决策:标记对是进行中状态的唯一真源
TUI 将实时独立的 compaction/start { turn: null } 与匹配的 compaction/end 组成的标记对,作为显示进行中压缩状态的唯一真源。只有两个条件同时满足才开启进度显示:
- 有未匹配的独立开始标记(
turn: null标识独立手动尝试); - 该标记是由已挂载的 TUI 通过实时
session/event通知观察到的。
这一选择与压缩子系统的事件协议一致。在 docs/subsystems/compaction.md 中,压缩通过声明合并扩展了 SessionEventMap,三个事件全部是 log-only(仅记录、不进入模型 surface):
| 事件 | 负载要点 | 作用 |
|---|---|---|
compaction/start |
{ turn } |
获取日志记录的锁;数字标识打开的自动轮次,null 标识独立手动尝试 |
compaction/summary |
{ summary, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, ... } |
安全的摘要投影、遮蔽范围与 token 估算、模型调用信封 |
compaction/end |
{ turn, error? } |
用相同数字或 null 归属值释放锁;error 记录失败尝试 |
锁包围整个操作:compaction/start 最先追加,随后是摘要、compaction/summary 记录与 user/message 替换,最后才是 compaction/end。把锁释放放在最后,使得中途崩溃变成可检测的孤儿锁(有 start 无 end),而不是一个虚假声称压缩完成的 compaction/end。事务的实现位于 packages/compaction/compaction-basic/src/region.ts,其中 session.append('compaction/start', lifecycle)(region.ts#L191)是同步追加的,先记录标记、后调用摘要器,保证缓慢或崩溃的尝试都可观察,这也是对"先摘要再记录"调研方案的主动偏离。
配套的排队式手动压缩决策(.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.zh.md)进一步确认:compaction/start 是唯一的压缩锁,不存在 WeakSet、包装层 mutex 或事务外部的重复活动状态检查。
渲染机制:固定状态行加呼吸动画指示器
当上述真源条件满足时,TUI 启用模块局部的 compacting 状态,它记录渲染时钟的起始时间,并独占一个动画定时器。界面呈现两部分:
- 提示词上方的固定行:根据该时钟渲染
Context being compacted <elapsed>(已用时间持续刷新)。该行位于 transcript 之外,不带 spinner,也不另设定时器;内容为空时整行折叠。 - 运行状态指示器:现有的单格状态指示器通过与轮次阶段字形相同的明暗渐变和呼吸律动路径渲染
⊙。终端进度标志位(progress flag)会保持活跃,直至标记对闭合。
单格指示器的字形选择由 runningPhaseGlyph 负责,它在轮次阶段字形、⊙ 和空闲光标之间作出选择。优先级规则是轮次阶段字形更高:因为带编号的压缩标记对处于运行中的轮次内,该轮次的阶段已经激活了指示器,此时轮次信息优先,避免两处状态同时争抢用户注意力。
设计还刻意保持了界面其余部分的不变:压缩状态不会改变空闲编辑器边框、提示(prompt)或 steering(中途引导)徽标。这样做的结果是,在独立压缩预留轮次准入期间,界面仍然明确显示提示词已获接纳——用户能同时看到"提示词已接收"和"正在压缩",而不是被某个被改写的边框误导。
需要说明的是,Web 轨迹视图(trajectory)对压缩进行中状态有同源但独立的呈现:在 packages/client/ui-trajectory/src/client/layout.ts 中,运行中的压缩请求被渲染为 layout.compacting 文案,对应 locales.ts 中的 正在压缩上下文… / Compacting context…。TUI 与轨迹视图各自持有独立的 event-to-view 投影(trajectory-event-projection.ts),互不依赖。
恢复与实时性边界:历史绝不回放成进度
这条边界是该决策最严格的部分,包含三条规则:
- 只反映实时事件。挂载和 transcript 回放绝不会扫描历史来查找未匹配的
compaction/start。只有已挂载的 TUI 通过session/event通知观察到新的开始事件,才能开启进度显示。持久历史只提供成功标记与计时事实,"运行中"这一状态只有当前进程的观察才能提供。 - 轮次状态转换保留该状态,而终端清理(teardown)会清除其定时器和进度标志位——无论标记对是否闭合,TUI 销毁时实时状态都必须随之消失。
- 陈旧标记由 end-seed 边界区分。日志尾部扫描会分别识别最新未匹配的
compaction/start与最新session/end-seed:位于较新 end-seed 之后的未匹配 start 是当前生命周期的活动锁,会阻塞所有压缩入口点;位于其之前的未匹配 start 属于更早的会话生命周期,属于预期的陈旧持久历史,被忽略。这一逻辑在后端实现中同样存在,见 region.ts 中的assertCompactionInactive与尾部状态扫描inspectCompactionEntryState,并由测试固定:ignores an unmatched bracket inherited before a later end-seed marker验证了陈旧孤儿标记不会卡住恢复或 fork 后的会话,而reports a live unmatched bracket as busy without summarizing验证了活动未匹配标记会直接返回busy(见 packages/compaction/compaction-basic/tests/manual-compaction.spec.ts)。
结束与失败语义:先清状态,再结算 transcript
收到 compaction/end 时,TUI 的执行顺序是先清除 compacting 状态,再启动普通字形的淡出——淡出过程独占一个会自行终止的定时器,与实时压缩的开启/闭合生命周期严格分离,二者不共享定时器。
失败与成功的呈现方式刻意不同:
- 失败:携带
error的结束事件会以警告形式添加Compaction failed: <error>文本。这呼应了后端"失败尝试也会闭合并持久化记录"的事务语义——changed或summary失败会保持会话表层不变,但日志中会留下compaction/start与compaction/end { error }的完整闭合对。 - 成功:成功完成不再添加已结算的行,而是由已落地替换项的 transcript 标记(checkpoint)呈现。匹配且已持久记录的
start/end时间戳足以推导出持续时间,供未来需要新增 transcript 行的展示方式使用。
与其他决策的关系
该决策仅部分取代两份 transcript 决策中与进度相关的延期条款:
- .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md(终端 transcript 决策)
- .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md(浏览器 transcript 决策)
进度显示不要求标记携带规模信息,也不要求重构替换项渲染;两份记录保持活动状态,继续负责基于追加来源的 transcript 投影和已落地检查点标记。而 排队式手动压缩决策 继续负责标记对顺序、锁定机制和陈旧未匹配标记的分类——进度可见性只管"显示",不管"谁先谁后"。
曾考虑的替代方案
决策记录明确评估并拒绝了以下方案,每一条都值得了解其取舍:
| 候选方案 | 不予采用的理由 |
|---|---|
为 CommandDefinition 添加 progressLabel 和第二个 TUI 状态控制器(PR #669 探索过) |
命令元数据并非压缩生命周期的权威依据;自动压缩并非由人工命令发起;两个状态控制器可能对同一个指示器给出不一致状态 |
将 compacting 加入 TurnPhase |
独立压缩按设计没有轮次;带编号的压缩已有可见的运行轮次阶段 |
添加第五个 TimingBucket |
计时分桶用于划分开放模型步骤内的时间并为 transcript 页脚供数;独立压缩没有步骤转换,新分桶只会增加无意义的压缩列 |
| 让运行、淡出、压缩状态共享一个定时器 | 淡出独占自行终止的定时器,实时压缩有独立开启/闭合生命周期;共享会重构已评审的动画状态机却无法消除真实存在的并发定时器 |
扫描日志查找未匹配的 compact/start |
先前进程生命周期的陈旧未匹配标记是预期的持久历史,只有实时通知才能证明当前进程正在工作 |
| 使用通用命令运行指示器 | 压缩标记对是更精确的真源,且覆盖非命令路径;未来通用指示器应归属 command/run / command/done 生命周期 |
| 在 transcript 中添加动画压缩行 | 会为同一生命周期设置第二处状态动画;现有单格指示器负责运行状态,落地标记与失败警告负责已结算呈现 |
| 打印包含持续时间的成功通知 | 已落地替换项已提供完成标记;时间戳保留了持续时间,未来有合理展示需求时再使用 |
后果与验证
该决策落地后,用户可见的行为是:
- 手动压缩在 agent 空闲时,提示词上方显示带名称的已用时间(
Context being compacted <elapsed>),而非静止的>光标; - 失败直接产生警告(
Compaction failed: <error>),不再需要猜测摘要是否卡住; - 恢复会话时,陈旧的未匹配标记绝不会显示为活动状态;
- 提示符指示器始终保持一个终端字符单元宽,状态行与指示器复用现有状态动画、语义调色板和终端进度生命周期,不新增第二套视觉语言。
从状态生命周期看,实时状态及其定时器是额外的进程局部状态,在两种情况下都会被清除:标记对闭合、或 TUI 清理。按设计,这种显示状态不可重建——持久历史提供"成功标记 + 计时事实",只有当前进程的观察才能提供"运行中状态"。这保证了显示层的临时性不会污染持久日志的权威性。
验证层面,包级 TUI 测试固定了以下行为:独立开始事件、已用时间刷新、单指示器呈现、排除带编号的开始事件、淡出、失败警告、保留空闲状态、运行轮次优先级、存在未匹配标记时的恢复、定时器释放。后端侧,manual-compaction.spec.ts 固定了 turn: null 标记对的精确负载(#L414-L417)、活动未匹配标记的 busy 拒绝与陈旧标记的忽略逻辑;决策记录还提到,产品 TUI 场景曾观察到真实摘要边界保持开放期间的 Context being compacted 1.0s 与 dsh ⊙,该组装流程已移交给未来的终端部署。
小结
DeepSeek Harness 对压缩进度的处理可以概括为一句话:用持久标记对证明"曾发生",用实时通知证明"正在发生",两者绝不混用。compaction/start { turn: null } 与 compaction/end 既充当压缩锁的时间点证据,又是 TUI 进度显示的真源;session/end-seed 边界负责把陈旧历史与当前活动区分开;runningPhaseGlyph 用单格指示器在轮次阶段与压缩动画之间做单一职责的字形选择。这种"持久日志管事实、进程局部状态管动画、恢复时零回放"的三层设计,值得在需要为后台任务增加进度可见性的同类系统(TUI、Web 或任何事件驱动客户端)中借鉴。