DeepSeek Harness 终端实时压缩进度展示:基于 `compact/start` / `compact/end` 事件括号的 TUI 活性指示设计
DeepSeek Harness 终端实时压缩进度展示:基于 compact/start / compact/end 事件括号的 TUI 活性指示设计
导读
本文深入解析 DeepSeek Harness 中"独立手动压缩(standalone manual compaction)"在 TUI(终端用户界面)中的实时进度可见性设计。当 Agent 在两轮对话之间的空闲期执行一次耗时的上下文压缩时,TUI 如何在不引入第二个动画状态位的前提下,通过复用既有状态指示器,向用户呈现"正在压缩"的活性反馈、已用时长与失败警告?读完本文,你将掌握这套基于 compact/start { turn: null } 与 compact/end 事件括号的展示状态机设计——包括模块级 compacting 单元格、单一动画定时器、runningPhaseGlyph 字形仲裁规则,以及"孤儿事件不复活"的进程内活性判定原则。
背景:压缩生命周期与事件的"括号"语义
压缩能力缝与 compaction/* 会话事件
在 DeepSeek Harness 中,压缩(compaction)是一个可选能力(capability),并非 Agent 主循环的脊柱组件。它的词汇定义在 docs/subsystems/compaction.md 中,服务定义位于 packages/compaction/compaction,参考后端实现为 packages/compaction/compaction-basic。
压缩通过声明合并为 SessionEventMap 扩展了三个 仅记录(log-only) 会话事件,其类型定义可追溯到 packages/compaction/compaction/src/types.ts:
| 事件 | Payload 要点 | 职责 |
|---|---|---|
compaction/start |
{ compactionId, sourceCommandId?, turn: number | null } |
获取日志记录的锁;数字编号标识自动压缩所处的回合,null 标识回合间独立的手动尝试 |
compaction/summary |
{ summary, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage?, rawOutput?, llmStreamCall? } |
记录安全摘要投影、被遮蔽范围与序数、预估 token 数与模型调用信封 |
compaction/end |
{ compactionId, sourceCommandId?, turn: number | null, error? } |
以与 start 相同的数字或 null 归属者释放锁;error 记录失败尝试 |
这三个事件都不会进入模型面(surface),SurfaceEventType 被刻意地不扩展;真正的摘要替换由紧随其后的、携带 surfaceOp: { op: 'replace', start, end } 的 user/message 事件完成。
关键约束:锁必须括住整个操作——先追加 compaction/start,再做摘要、追加 compaction/summary 与替换 user/message,最后才追加 compaction/end。将锁释放放在最后,使进程崩溃留下的是一个"可检测的孤儿锁"(有 start 无 end),而不是一个虚假宣称压缩完成的 end。这正是本文进度可见性设计的底层事实来源。
turn: null:独立手动压缩的身份
.agents/notes/implemented/feature/2026-07-30-queued-manual-compaction.md 定义了手动压缩事务:/compact 命令调用 CompactionEngine 的第三个抽象操作 compactNow(agent, signal),其括号使用 turn: null,只要求所选区间(selected span)的稳定性,并在 finally 中释放入场许可前冲刷每个成功关闭的尝试。
由此产生了本文展示逻辑的关键输入:一个 turn: null 的 compaction/start 到匹配 compaction/end 的括号,是"当前进程中正在进行的独立压缩"的权威信号。而数字编号的 compaction/start(自动压缩)被一个正在运行的回合(turn)所包裹,该回合的相位(phase)本就已经点亮了指示器,因此不需要额外的进度展示。
要解决的问题:为何需要独立的压缩活性展示
在设计这个功能之前,TUI 面临两个具体的体验缺陷(详见关联 Agent Note 的 Problem 部分):
- 状态指示器无感知:独立手动压缩在回合之间运行,Agent 处于空闲态。TUI 的回合相位指示器在整个慢速摘要操作期间一直保持普通的
>光标符,用户无法得知系统正在工作。 - 失败无痕迹:一次失败的压缩尝试由于没有落地替换检查点(replacement checkpoint),不会产生任何 transcript 行,失败对用户完全不可见。
同时存在一个必须避免的陷阱:进程死亡后,持久化日志中会保留一个无匹配的 compact/start 孤儿。它是宝贵的恢复证据,但不是当前进程正在工作的证明——若把重放日志中的孤儿当作进度来展示,恢复后的会话会留下一个永不消失的"幽灵指示器"。
核心决策:单个模块级单元格 + 单一动画定时器 + 固定状态行
关联文档的 Decision 部分给出了完整的展示架构:
- TUI 把实时的独立
compact/start { turn: null }到匹配compact/end的括号,作为进行中压缩展示的来源; - 一个模块级(module-local)
compacting单元格记录渲染时钟(render-clock)的起始时刻,并独占一个动画定时器; - 提示符(prompt)上方的一个固定行渲染
Context being compacted <elapsed>(基于该时钟的已用时长); - 既有的单单元格运行状态指示器通过与回合相位字形相同的淡入/脉动(fade and throb)路径渲染
⊙; - 终端进度位(terminal progress bit)在括号关闭前保持激活。
runningPhaseGlyph 的字形仲裁规则
字形选择由 runningPhaseGlyph 统一负责,候选包括:回合相位字形、⊙、空闲光标符 >。仲裁优先级为:
- 回合相位字形优先:因为带编号的压缩括号被一个正在运行的回合所包裹,该回合的相位已经点亮了指示器;
- 只有无回合包裹的独立压缩才渲染
⊙; - 空闲时保持普通
>光标。
这一设计保证了"提示符指示器始终保持一个终端单元格宽度"这一不变式——不引入第二个动画状态位,也就从根上杜绝了两个状态控制器对同一指示器意见不一致的可能。
固定行的定位与折叠
Context being compacted <elapsed> 这一行位于 transcript 之外、提示符之上,自身不持有 spinner 也不持有第二个定时器——动画由 compacting 单元格独占的定时器驱动。该行在为空(无进行中压缩)时自动折叠(collapse),不占用界面空间。
对提示符接受性的刻意保留
压缩单元格不会改变空闲编辑器的边框、提示(hint)或 steering badge。也就是说,即使独立压缩正在保留回合入场权(reserves turn admission),提示符依然让用户感到"输入被接受"。输入会被排队,待压缩结束后再进入既有的驱动路径。
活性与持久性的边界:live-only 单元格
这是本设计中最关键、也最容易被误解的原则——compacting 单元格是"仅实时(live-only)"的:
- 挂载(mount)与 transcript 重放绝不扫描历史去查找一个未匹配的 start;
- 只有挂载中的 TUI 观察到的
session/event通知才能打开(open)该单元格; - 回合状态迁移会保留(preserve)该单元格,不会因回合指示器变化而清除;
- 终端销毁(teardown)会清除其定时器与进度位。
对应地,孤儿事件的语义如下:日志中一个无匹配的 compact/start 属于更早进程生命周期的正常持久历史(stale evidence),重放它只会让恢复后的会话出现一个永久性的幽灵指示器。因此,只有实时通知才能证明当前工作正在进行。这一判定与 queued-manual-compaction 中"end-seed 区分存活与陈旧孤儿"的边界一致:无匹配的 start 若出现在较新的 session/end-seed 之后则为存活并阻塞所有压缩入口;若在其之前则属于更早的生命周期,不应卡死恢复或分叉的会话。
压缩结束的呈现:清除、警告与成功标记
compact/end 到达时的处理顺序:
- 先清除
compacting单元格,再开始普通的字形淡出(glyph fade-out); - 若 end 携带
error,则追加一行Compaction failed: <error>作为警告(warning)——注意这是 TUI 层为失败提供的直接可见呈现; - 成功完成不额外打印成功通知:落地的替换检查点在 transcript 中已经作为完成标记存在(对应 packages/client/ui-chat/src/client/conversation-nodes/compaction.ts 中按
compactionId匹配compaction/summary与 checkpoint 并构建 marker 的逻辑); - 压缩时长不做单独的已定稿(settled)行:匹配的持久化 start 与 end 时间戳已足够推导时长,留待未来某个"值得新增 transcript 行"的呈现再做。
失败尝试的语义区分
需要强调的是,失败的 changed 或 summary 尝试不会改变会话面,但日志并非无痕——它包含 compaction/start 和携带 error 的 compaction/end。ManualCompactionErrorCode 枚举(见 docs/subsystems/compaction.md 的 Service 一节)覆盖了 busy | cancelled | changed | summary | commit | persistence 六类预期失败;TUI 的 Compaction failed: <error> 警告行正是对这些失败类的直接用户可见映射。若端关闭本身失败,未匹配的 start 会刻意保持可见并阻塞,且不尝试冲刷(flush)。
被否决的备选方案及其理由
关联文档的 Alternatives considered 部分记录了 PR #669 探索中的全部备选方案与否决理由,这些决策记录对后续维护者极具参考价值:
| 备选方案 | 否决理由 |
|---|---|
向 CommandDefinition 添加 progressLabel 并新增第二个 TUI 状态控制器 |
命令元数据不是压缩生命周期的权威来源;自动压缩并不源自人类命令;两个状态控制器可能对同一指示器意见不一致 |
把 compacting 加入 TurnPhase |
独立压缩刻意没有回合;而带编号的压缩已经有可见的运行中回合相位 |
新增第五个 TimingBucket |
timing buckets 划分的是打开的模型步骤并喂给其 transcript footer;独立压缩没有步骤迁移,新 bucket 只会在每个步骤总览中添一列无意义的压缩列 |
| 在 running、fading、compaction 之间共享一个定时器 | 淡出拥有自终止定时器,而实时压缩有独立的开/关生命周期;共享会重构已评审的动画状态机却并未消除真正并发的定时器 |
扫描日志查找未匹配的 compact/start |
更早进程生命周期留下的陈旧孤儿是预期的持久历史;只有实时通知能证明当前工作 |
| 使用通用的命令运行指示器 | 压缩括号是更精确的来源且覆盖非命令路径;未来的通用命令指示器应归属 command/run / command/done 生命周期 |
| 在 transcript 中新增动画压缩行 | 会为同一生命周期创造第二个状态动画点;单单元格指示器拥有活性,落地 marker 与失败警告拥有已定稿呈现 |
| 打印带时长的成功通知 | 落地替换已提供完成标记;括号时间戳保留时长,留待未来需要额外 transcript 行的呈现 |
实现边界与测试锚点
进程内状态的生命周期
compacting 单元格与定时器是额外的进程本地状态,在括号关闭与 TUI 销毁两个时点都会被清除。文档明确指出这是刻意不可重建(not reconstructible)的呈现状态:持久历史提供成功的标记与计时事实,而仅当前进程的观察提供活性(liveness)。
包级 TUI 测试钉住的契约
关联文档的 Consequences 部分列出了包级 TUI 测试覆盖的行为面,它们共同构成该功能的回归防线:
- 独立
compact/start的呈现; - 已用时间的刷新(elapsed-time refresh);
- 单指示器呈现(不出现第二动画点);
- 带编号 start 的排除(自动压缩不渲染
⊙); - 淡出(fade-out);
- 失败警告;
- 空闲状态指示器保留(提示符仍显示为可接受输入);
- 运行中回合优先(回合相位字形压过
⊙); - 孤儿恢复(恢复的会话不会出现幽灵指示器);
- 定时器销毁(teardown 清理)。
此外,被移除的产品级 TUI 场景曾经跨真实摘要边界断言 Context being compacted 1.0s 与 dsh ⊙ 的呈现;文档注明"未来的终端部署"将拥有这条端到端的组装旅程——即当前的包级测试以单元级契约承担了该职责。
关联决策的所有权边界
为避免读者误解,关联文档明确划定了本决策与相邻决策的关系:
- 本决策仅部分取代 terminal transcript 决策 与 browser transcript 决策 中与进度相关的 deferred 条款:进度展示不需要 marker 缩放,也不需要替换渲染重构;两份笔记依然有效,继续各自拥有 append-origin transcript 投影与落地检查点 marker;
- queued manual compaction 决策 继续拥有括号排序、锁与陈旧孤儿分类的所有权——本展示层只是其事件语义的消费方之一。
总结
DeepSeek Harness 的实时压缩进度展示是一次典型的"克制型" UI 设计:它不为一个新生命周期引入第二套状态机制,而是通过复用既有状态指示器的字形路径、以单个模块级单元格 + 单个定时器承载活性,用括号事件作为唯一权威来源,并用 live-only 语义把"进程内正在工作"与"日志中的历史孤儿"严格区分开。最终的效果是:手动压缩有可读的已用时长展示、失败有直接的警告、恢复后的会话永远不会把陈旧日志误认为正在运行的进度,而提示符指示器始终只有一个终端单元格宽。