atomcode TUI 架构决策解析:动画与时间由宿主注入,`render` 永不读系统时钟(ADR 0008)
atomcode TUI 架构决策解析:动画与时间由宿主注入,render 永不读系统时钟(ADR 0008)
本篇技术指南围绕 atomcode 仓库中的架构决策记录 ADR 0008(动画与时间由宿主注入,render 永不读系统时钟) 展开,深入讲解 atomcode TUI 如何在「动画、倒计时等随时间变化的呈现需求」与「可回放、可测试的确定性渲染闭环」之间做出取舍:时间被设计为 Moment 的注入字段,render 始终是 (state, tick, now, rect) 的纯函数。读完本文,你将掌握这套时间注入模型的设计动机、tick 与 now 的分工、模块如何声明重画周期、宿主如何驱动帧推进,以及为保住确定性闭环而放弃的四条备选方案。
一、背景:TUI 自动化闭环的确定性根基
atomcode TUI 的整套自动化与测试体系建立在一个强前提上:同一份输入必须产生同一份输出。这一前提由多项机制共同支撑:
- 回放 provider:测试可以通过回放既定的模型响应序列来驱动 TUI,无需真实网络;
- 无头终端:在没有真实终端的环境下渲染并断言画面;
start_paused时间:Tokio 测试运行时以start_paused = true冻结虚拟时钟,让超时、轮询类逻辑可被精确推进(见 scrollbar.rs 中tokio::time::sleep配合暂停时钟的测试写法);- 静默判据:判定会话进入静默(quiescence)的等待逻辑依赖可控制的时间流逝。
在这一闭环里,只要有一处 render 路径读了墙钟(Instant::now / SystemTime::now),闭环就废了——而且是静默地废:测试仍然全绿,只是同一份输入不再给出同一份输出。更隐蔽的是,人有先验知识能过滤偶发的红(测试偶尔失败),而 Agent 没有——它会把这根抽风当真信号,去修一个不存在的 bug,或者干脆把那条测试删掉。这正是 ADR 0008 想从结构上杜绝的失效模式。
需要随时间变化、却不等事实到达的模块在 TUI 里真实存在:
- 动画吉祥物(欢迎屏的吉祥物动画);
- 「思考中」的转轮(spinner,按帧切换字符);
- 「距离限流重置还有 30 秒」式的倒计时。
这些需求看似琐碎,但如果不加约束地实现,就会把墙钟悄悄引进渲染路径。
二、核心决策:时间是 Moment 的字段,由宿主注入
ADR 0008 的决策一句话即可概括:
时间是
Moment的字段,由宿主注入;render永不读系统时钟。
Moment 在 atomcode TUI 中的定位是「不可推导的环境」(the non-derivable half of what a module renders from),参见 moment.rs:终端尺寸、agent 状态、半截输入、焦点、滚动位置——这些既不是会话日志里的事实,又恰恰是渲染所必需的。时间正是这一类,所以本决策不是加了一个新概念,而是把一个本来就空着的槽填上了。
ADR 中给出的 Moment 形态如下:
pub struct Moment {
pub status: AgentStatus,
pub input: String,
pub focus: Option<ModuleId>,
pub scroll: ScrollPos,
pub tick: u64, // 逻辑帧计数:动画相位
pub now: Timestamp, // 注入的时刻:倒计时等需要真实间隔的场景
}
在真实源码中,这一设计被完整实现,并且两个时间字段带着非常明确的注释契约:
tick: u64——"Logical frame counter. Animation phase comes from here, never from a clock read insiderender— that would make the whole test loop non-deterministic while leaving it green."(moment.rs)now: Timestamp——"Injected wall time, for anything that needs a real interval (a countdown). Still injected: tests set it,rendernever reads a clock."(moment.rs)
Timestamp 是一个极简的封装类型,内部就是 u64 毫秒数,注释写明 "Injected time. Never Instant::now() inside a render — see docs/adr/0008."(moment.rs),提供 Timestamp::millis 构造与 as_millis 取值,语义为「会话开始以来的毫秒数,由宿主计数」。
Moment 的模块文档还点出了这个设计的纪律性价值(moment.rs):
The log is the source of truth for what happened; this is the short list of things that are true now and are not facts — terminal size, who has focus, the half-typed line, the scroll position, the time. Enumerating them is what stops non-derivable state from growing quietly: adding a field here is a visible act, and every one of them has to be settable by a test.
「每一个字段都必须能被测试设置」——这就是注入模型能支撑确定性测试的根本原因。
三、模块如何声明「我要按时间重画」:tick() 契约与最小周期驱动
只有时间字段还不够,宿主还需要知道何时推进帧。ADR 给出了模块侧的契约:
fn tick(&self) -> Option<Duration> { Some(Duration::from_millis(120)) }
// None(默认)= 只在事实到达时重画
源码中该契约位于 View trait 与 ViewObject trait 上(module.rs):
/// Ask to be redrawn on a timer even when no fact arrives. `None` (the
/// default) means this module only changes when the conversation does —
/// which is what stops an idle screen from burning bandwidth.
fn tick() -> Option<Duration> {
None
}
这个默认值 None 是性能纪律的一半:没有任何模块在动画时,宿主只在事实到达与按键输入时重画,空闲屏幕不烧带宽。对应的测试直接断言了这一点——nothing_animating_means_no_timer_at_all:挂载一个不声明 tick 的视图后,Modules::tick() 必须返回 None,"an idle screen must not burn bandwidth"(module.rs)。
宿主侧取所有已挂载视图的最小周期作为全局节拍,实现见 Modules::tick(module.rs):
/// The shortest interval any mounted module asked for. `None` when nothing
/// animates, and then the host redraws only on facts and input.
pub fn tick(&self) -> Option<Duration> {
self.views
.read()
.expect("modules poisoned")
.iter()
.filter_map(|v| v.tick())
.min()
}
事件循环拿到这个节拍后,通过 tokio::time::timeout(every, wake.recv()) 等待:超时即产生 Wake::Tick(plugin.rs)。Wake::Tick 的处理逻辑非常简洁——递增逻辑帧计数并标记重画(plugin.rs):
Wake::Tick => {
let mut m = self.host.moment.write().expect("moment poisoned");
if m.scrollbar_until
.is_some_and(|t| t <= tokio::time::Instant::now())
{
m.scrollbar_until = None;
}
m.tick = m.tick.wrapping_add(1);
stale = true;
}
注意这里的两个细节:
m.tick = m.tick.wrapping_add(1)用逻辑帧计数而非真实时间表达动画相位,避免溢出问题,也让「相位」与「真实时刻」彻底解耦;- 滚动条提示的过期判断也发生在这里(宿主层),而不是让模块在渲染时读时钟。
四、情绪来自事实,相位来自 tick:render 仍是纯函数
ADR 的核心洞察是把动画模块的状态切成两半:
- 情绪(emotion)来自事实:模块通过
absorb折叠会话事件,得到「agent 正在思考」「正在运行工具」「被限流」这类语义状态; - 相位(phase)来自
tick:spinner 转到了第几帧、倒计时还剩几秒,这些是 render 的输入,而非 render 内部读取时钟得出的结论。
由此 render 保持纯函数性质——同样的 (state, tick, now, rect) 永远给出同样的输出。
源码中的两个典型证据:
状态行(status)spinner。状态行的 tick() 声明 110ms 周期(status.rs),渲染时从帧表取帧:
let f = frames[(vp.moment.tick as usize) % frames.len()];
(status.rs)。帧表的选择也遵循同样的「注入」哲学:Caps::spinner(tick) 根据终端能力在 Unicode 帧集与 ASCII 帧集(<a href="https://link.gitcode.com/i/bb6d65f48f825e64628985b85f2b01d8" target="_blank">"-", "\\", "|", "/"])之间切换,模块绝不自己直接索引帧表([caps.rs)。
live 行(当前活动行)。它同样声明 110ms 节拍,注释解释了为什么动画帧不能只靠事实驱动:"The spinner needs frames, and so does the clock: a timer that only moves when a fact arrives freezes in exactly the case this line exists for — a model that has gone quiet."(live.rs)——模型静默恰恰是没有事实到达的场景,此时只有 tick 能让屏幕继续「活着」。
五、now 的用途:需要真实间隔的场景
tick 只提供相位,无法回答「已经过了多久」。倒计时、静默时长、重试等待这类需求必须使用注入的 now。ADR 中 Moment 只展示了 tick 与 now 两个字段,实际实现里 Moment 还承载了一族「在注入时钟上的读数」:
turn_started: Option<Timestamp>——当前回合的开始时刻;quiet_since: Option<Timestamp>——当前回合最后一次有动静的时刻;provider_retry_started: Option<Timestamp>——最近一次 provider 重试被宣布的时刻。
这些字段的注释反复强调同一条规则:屏幕上的时长是两个注入读数的差,日志不记录时钟,而 Host::absorb 是唯一同时看到事实与读数的位置(moment.rs)。对应的实现见 Host::absorb_logged:TurnStart 到达时写入 turn_started 与 quiet_since,TurnEnd 时清空,ProviderRetry Notice 时记录重试起点;任何其他事实到达都刷新 quiet_since("a chunk, a call, a result … is a sign of life")(host.rs)。
消费侧的例子在 live 行:quiet_for 用 moment.now.as_millis().saturating_sub(since.as_millis()) 计算静默秒数,超过阈值就显示「正在等待模型 · N 秒」(live.rs);provider 重试等待则用 provider_retry_started 与 now 的差计算「还有 N 秒发起第 M 次重试」(live.rs)。而测试直接手工设置 moment.now = Timestamp::millis(...) 来验证这些分支(live.rs)——这正是「每个字段都必须能被测试设置」的兑现。
六、执行者:三重结构防线
ADR 指出,光有约定不够,还要有结构性的执行者:
- 类型签名:
render的签名是fn render(&State, &Viewport<'_>) -> Vec<Line>,没有Context、不是 async、拿不到任何 IO——这已经堵死大半读取墙钟的路径。该签名见 module.rs,与 tui-composability.md §四 义务 2 相互印证; - lint 禁止:在
tuicrate 内禁用Instant::now/SystemTime::now(义务 11 原文:"render永不读系统时钟。(tuicrate 内禁Instant::now/SystemTime::now的 lint;时间从Moment.tick/Moment.now注入)一次墙钟读取就静默毁掉整个闭环——测试还绿,只是同一份输入不再给同一份输出。",见 tui-composability.md); - 宿主唯一读取点:整个 crate 对真实时钟的读取被收敛到事件循环里的
Clock结构——"The session's clock, and the only place this crate reads one",reading()以「循环启动以来的毫秒数」产出Timestamp(plugin.rs)。宿主在每次醒来(事实、按键、tick)时更新Moment.now,其余所有层只见注入值。
从源码结构看,宿主层(plugin.rs 的 Clock、事件循环)是唯一与墙钟接触的地方,而模块层(modules/ 下各视图)一律只读 vp.moment——三层防线把「时间注入」从纪律变成了难以绕开的结构事实。
七、放弃了什么:四条被否决的备选方案
ADR 的价值一半在决策本身,另一半在明确记录被否决的方案。这四条的取舍逻辑层层递进:
-
在
render里直接读墙钟——最省事,不需要把时间一路穿过Moment。放弃因为它静默地毁掉整个闭环:测试仍然绿,只是同一份输入不再给同一份输出。代价是Moment多两个字段,每个动画模块都要从参数取时间。ADR 特别告诫:"这个「啰嗦」正是下一个人会想简化掉的东西——这份记录就是拦他用的。" -
把动画帧做成日志事实(
SessionEvent::Tick)——这样 render 依然是折叠状态的纯函数,接口一个字段都不用加。放弃因为会话日志是 durable 的,被持久化、模型投影、恢复共用——往里面灌每秒约 8 帧的动画心跳,是拿一个共享的、要长期保存的东西去解一个纯呈现问题。代价是失去「所有 render 输入都来自日志」这个更整齐的说法。这与 ADR 0004 的流模型直接相关:流块属于「不可逆、有历史」的流生产者,动画属于「每帧全量重画、无历史」的视图模块,二者必须分开。 -
模块内部可变状态自增(interior mutability 自己动)——不改任何接口。放弃因为它直接破坏纯度:同一个状态连画两次给出不同结果,一致性套件里的「确定性」那一条当场失效,而那条是其余判据的地基。
-
宿主持有每个模块的动画状态机——把动画收归宿主管。放弃因为宿主要因此知道各模块的动画语义,而「宿主不认识任何模块」是空间可组合性的前提(同见 tui-composability.md 关于布局引擎不触碰模块状态的第 3 条义务)。
四条备选方案的失败模式各有不同:墙钟方案死于静默失效,日志事实方案死于污染持久化共享资源,interior mutability 死于破坏确定性判据,宿主托管死于破坏组合性——恰好从「正确性、资源边界、纯度、架构解耦」四个维度包围了主方案的合理性。
八、失效条件与演进空间
ADR 还诚实地列出了主方案自身可能失效的条件,这些边界同样值得读者注意:
- 过度重画:若模块数量增长到「取所有周期的最小值」造成过度重画,需要 per-module 的 tick 调度,而不是全局节拍。目前实现正是全局最小节拍(module.rs),多个 110ms 模块并存时整体按 110ms 驱动;
- 亚帧精度 / 真实墙钟同步:若出现需要与外部录制严格对齐等场景,注入的
now可能不够,需要重新评估——但 ADR 划定了底线:任何替代方案都必须保住「测试里时间可注入」这一条,否则闭环不成立; - 动画价值存疑:若动画被证明在真实使用中只是干扰(用户普遍关掉),
tick机制的存在价值需要重估——注意这并不影响「时间注入」本身,而只是让「按时间重画」这个机制失去存在理由。
九、相关文档与延伸阅读
本文主题在仓库中有完整的决策链条与实现支撑,可按需深入:
- ADR 0008:动画与时间由宿主注入,render 永不读系统时钟(本文主体);
- ADR 0004:TUI 的流是不可逆块序列——解释为什么动画只能存在于视图模块、不能进入流块(流的块 settle 后冻结、有历史,视图每帧重画、无历史);
- docs/tui-composability.md §四 义务 11 与 §八/§十四——把「render 永不读系统时钟」列为 TUI 可组合性的十一条义务之一,并给出 lint 执行方式与一致性套件判据;
- 核心实现:moment.rs(
Moment/Timestamp定义与注释契约)、module.rs(tick()契约与最小周期聚合)、plugin.rs(Clock唯一时钟读取点与Wake::Tick帧推进)、host.rs(absorb_logged在事实落地处打时间戳); - 消费示例:status.rs(spinner 帧)、live.rs(静默时长与重试倒计时)、caps.rs(按终端能力选择帧表)。
小结
ADR 0008 解决的并不是「如何做动画」这种表层问题,而是「如何在引入动画的同时,不破坏 TUI 赖以自证正确的确定性闭环」。它的答案是把时间降格为 Moment 的两个注入字段:tick 提供逻辑相位、now 提供真实间隔,宿主统一驱动,render 保持纯函数,再以类型签名、lint 与宿主唯一时钟读取点三道结构防线保证纪律不被打破。对任何构建「可回放、可自动化验证」的终端 UI 或类似交互系统的开发者而言,这套「时间作为输入而非全局可读资源」的思路都值得直接借鉴。