# Agent Note：TUI 消息头部计时

Status: implemented

[English](2026-07-24-tui-message-header-timing.md) | 中文

## 问题

编辑器旁的轮次计时会在用户滚动时从 transcript（文本记录）中消失，且要等到编辑器状态渲染后才能出现。整轮聚合值还会掩盖工具调用之后各后续模型请求的延迟。

## 决策

每个模型步骤都在 `step/start` 时（即第一个流式分片到达之前）创建一个 assistant 头部。头部立即显示 `Model wait` 并以 100 ms 分辨率刷新；随着会话事件使该步骤在不同阶段之间切换，头部再加入互斥的 `Thinking`、`Response` 和 `Tools` 时间桶。

`step/end` 冻结头部并附上本地完成时间戳。transcript 回放从持久事件时间戳派生出相同的计时。空步骤和纯工具步骤同样保留头部；当重试处理重建活跃会话表层时，失败的实时输出与其头部一并撤除。

提示区上下文（prompt context）只保留排队中的 steering（中途引导）状态。计时归属于产生它的模型步骤，而不是编辑器或整个轮次。

## 考虑过的替代方案

把计时留在编辑器旁能保持布局稳定，但在 scrollback 和会话恢复中看不到各步骤的延迟。增加第二条状态行会让同一指标出现在两处。把第一个时间桶标为 `TTFT` 更紧凑，但依赖协议术语；`Model wait` 直接陈述用户可见的含义，而不宣称第一个分片总是文本。

## 后果

用户在模型输出之前就能得到可见反馈，并能比较工具或重试之后的每次请求。以 100 ms 分辨率刷新会在模型步骤活跃期间带来更多终端渲染。内部计时状态沿用既有的 `ttft` 名称，因为它精确标识所计量的时间桶；只有渲染文本使用 `Model wait`。
