AtomCode TUI 架构决策解析:让视图模块的行进入流的滚动尾部(ADR 0020 深度解读)
AtomCode TUI 架构决策解析:让视图模块的行进入流的滚动尾部(ADR 0020 深度解读)
本技术指南围绕 AtomCode(Rust 构建的 Claude Code 开源替代方案)TUI 的架构决策记录 ADR 0020 展开,它回答了 ADR 0004 遗留的第三个问题——视图模块的行能否成为不可逆流的一部分跟着滚动。读完本文,你将理解
El::Stream { tail }的滚动几何、Host::pinned的钉住补偿机制、尾部高度封顶与让位仲裁的完整设计,以及这些决策在atomcode-tui源码中的落地方式,可直接用于理解或复刻同类终端 UI 的滚动架构。
一、背景:ADR 0004 留下的第三个问题
ADR 0004 为 TUI 定下了「屏幕内容是块序列」的基调:每块单向走完 Live ──settle──> Settled,没有返回边;不可逆性由借用检查器执行——Stream 刻意不提供任何能拿到 &mut settled[i] 的东西,生产者只拿到暴露 open / amend / settle 的 StreamWriter。
由此强制分出两类模块:
- 流生产者:追加不可逆块,有历史;
- 视图模块:每帧全量重画,无历史。
「块属于流,不属于模块」这条规定划清了不可逆性归谁,却没有回答第三件事:
一个视图模块的行,能不能成为流的一部分,跟着流一起滚?
现状是不能,而这带来两个具体后果:
todo(任务清单)与live(这一轮在做什么)的矩形由布局树定死(host::composer),moment.scroll对它们毫无影响——读者往回滚看历史时,面板钉在底部挡着历史。live为此开了一条特例:showing()(modules/live.rs)读moment.scroll.is_at_bottom()决定自己存不存在。一个视图模块为了决定自己画不画,去读宿主的滚动位置——职责错位,而且todo没有这条,两个同类模块行为不一致。
composer() 的文档记下了当时为什么没做:LayoutOp::Show 只有「对话之上」和「状态栏之下」两个方向,都在输入框的错误一侧,所以面板只能把自己的位置写进树里——而写进树就固定了矩形,也就与滚动无关。提交 3050cb06 的说明把这条约束写得更直白:「这一行的矩形是 composer 的,一行把自己画进 stream 的滚动里就是画在自己矩形之外——流的行数归宿主对着 offset 算」。
本条 ADR 就是拆掉这道几何约束。
二、核心决策:El::Stream 携带 tail 声明
决策本身很简洁:El::Stream 带一个 tail 声明,列出哪些模块的行构成流的尾部。
El::Stream { tail: Vec<String> }
tail 里的模块不再有自己的布局矩形。它们的行是流内容的一部分:参与滚动偏移,也参与滚动上界。tail 之外的一切照旧——El::place_into 仍把 Stream 当一个叶子、交给它一个矩形;El::wanted 仍让它报 1 行、靠 grow 吃满剩余。
这一设计在 el.rs 中有完整的落地与注释印证:
El::Stream仍是叶子:El::place_into交给它一个矩形就停;tail是 id 列表而非子节点——子节点会从上层 flex 拿到自己的矩形,意味着「全部永远可见」,而尾部要做的事恰恰是部分滚出视野;- 引擎保持对滚动无知:因为滚动位置
moment.scroll归宿主所有,由宿主负责拆分 pane。
构建方式是 El::stream()(空尾部)配合 with_tail()(el.rs):
pub fn stream() -> El {
El::Stream { tail: Vec::new() }
}
pub fn with_tail(self, tail: impl IntoIterator<Item = impl Into<String>>) -> El {
match self {
El::Stream { tail: existing } => El::Stream {
tail: existing.into_iter().chain(tail.into_iter().map(Into::into)).collect(),
},
other => other,
}
}
注意 with_tail 的语义:tail 内部顺序自顶向下,最后一个 id 贴着 pane 底边——因为「最新的东西属于底边」。
同一棵树里,tail 的 id 不能再作为 El::Module 叶子出现,否则模块会被画两次:named_twice()(el.rs)拒绝这种树,El::prune() 会过滤未挂载的 id(el.rs)。
三、滚动几何:visible_tail 与 block_scroll 的拆分
设 pane 拿到 H 行,内容 = 块(B 行)+ 尾部(T 行),滚动几何是三条公式:
visible_tail = (T - scroll).clamp(0, H)
block_scroll = (scroll - T).max(0)
scroll_limit = (B + T) - H
scroll 在 [0, T] 区间里 block_scroll 恒为 0——尾部先被吃掉,块的偏移不变。但这不等于「块在屏幕上一动不动」:block_rect.h 每格长一行而内容底对齐,所以块每格下移一行,顶上同时多露出一行更旧的。
写判据时别把这两件事说成一件:要断言的是「同几行字仍在视野里」,不是「块的行位置不变」。
尾部内部按「距底部的偏移」排,自底向上分配矩形。
这一几何在 host.rs 的 pane_geometry_capped 中原样落地:
let top = scroll.saturating_add(pane.h as usize);
let tail_full: usize = heights.iter().map(|(_, h)| *h as usize).sum();
let visible_tail = tail_full.saturating_sub(scroll).min(pane.h as usize) as u16;
// Walking bottom-up: the ids arrive top-to-bottom, so the last one is
// the lowest on screen — the newest thing where the eye already is.
for (id, h) in heights.iter().rev() { ... }
每个模块保留自己可见的部分作为矩形(vis_hi - vis_lo),完全滚出视野的模块不参与放置——这正是「模块被问的是它可见的高度」这一契约的几何来源。
四、尾部高度封顶:H−1 与自顶向下让行
尾部总高要封顶,而且从最上面开始让。 交给模块的是它可见的高度,于是高于 pane 的模块会在若干个不同 offset 上都被问「你有 pane 这么高」,每次都排出一模一样的画面——读者滚 T − H 格,屏幕不动,只有「还有 N 行」在涨。所以总高封在 H − 1(至少给对话留一行)。
让行的顺序是自顶向下:tail 里第一个先让完,才轮到下一个。理由是:贴着底边那个是最新的、也是回答「是不是卡住了」的那一个;而它上方的东西多半有兜底(任务清单有 window 和 +N 更多),它没有。
ADR 特意记录了一个真实教训:这一条曾经写反过——注释说底边保留、循环却从底边扣起,于是一份长计划在短终端里第一件事就是把 live 行清空。而 live 行恰恰是最不该先丢的:任务清单行不够时有 window 兜底,live 行没有任何兜底。
源码 host.rs 的 cap_tail 印证了这一实现与教训:
/// This was written backwards once: the comment said the bottom kept its
/// rows and the loop took them from the bottom first. On a long plan in a
/// short terminal that meant the live line was the first thing to go, which
/// is the worst of the two to lose — the task list has a `window` for
/// running out of room, and the live line has nothing to fall back on.
fn cap_tail(mut heights: Vec<(String, u16)>, pane_h: u16) -> Vec<(String, u16)> {
// One row for the conversation, at least. ...
let budget = pane_h.saturating_sub(1);
let mut total: u16 = heights.iter().map(|(_, h)| *h).sum();
// Forward, not reversed: `heights` is in layout order, top to bottom.
for (_, h) in heights.iter_mut() {
if total <= budget { break; }
let take = total.saturating_sub(budget).min(*h);
*h -= take;
total -= take;
}
...
}
五、同一把尺子:stream_room、stream_height 与 scroll_limit
几何与 stream_height 必须用同一个封顶,也必须用同一个「pane 有多大」。 两者都从 Host::stream_room(size, moment) -> Rect 出发:宽度是块被量的宽度(不是屏幕宽度——wide 下对话区只占 65%),高度是尾部要分享的高度。这两个数各自都有过一次"第二个答案",两次都表现为滚动的上界和画面对不上。
源码 host.rs 对 stream_room 的注释把这个陷阱讲得很透:
The only place a stream's size is worked out, and it is a
Rectrather than a pair of numbers because both dimensions matter and they are used for different things: the width is what every block is measured at, and the height is what the tail has to share with it.Taking the width from the screen instead is the mistake this exists to stop. Under
widethe conversation is 65% of the screen, so a block measured at the full width wraps into fewer rows than the frame draws — and a reader scrolled back drifts by the difference, one chunk at a time.
scroll_limit 与 stream_height 的契约也值得注意(host.rs):
pub fn scroll_limit(&self, size: (u16, u16), moment: &Moment) -> usize {
self.stream_height(size, moment).saturating_sub(self.stream_rows(size, moment) as usize)
}
stream_height 收 moment 的引用,不收字段。 尾部高度依赖 Moment(live 的高度由 activity 决定),而 scroll_limit 的契约是「调用方可能正持 moment 写锁」(plugin.rs 的两处确实如此),所以不能内部读锁——与 stream_rows 的签名对齐。
此外,每帧组成时 tail_heights_of(host.rs)从 layout.tree().tail() 取 id 列表,逐个问模块的 height(moment, width)(Fixed/Hug 取其行数,Fill 报 1),未挂载的 id 直接跳过——保证「几何与高度求和」永远用同一份来源。
六、钉住阅读:Host::pinned 的符号对称与唯一实现
尾部进入滚动总量之后,能改「有多少行可读」的路变多了,而且不再只增不减(activity 翻转、计划变短都会让尾部缩)。ADR 提出了一组相互咬合的原则:
6.1 「量 → 改 → 重新读 → 量」
补偿必须量得到改动之后的世界,所以第二次测量的 moment 要重新读,不能复用第一次的快照。这不只是整洁问题:折叠状态存在 Presentation 里而不是 Moment 里,用同一份快照回量两次会得到同一个数,grew 恒为 0——点击展开一个块就什么都不会补偿。这是真实发生过的一次。
6.2 四条路径,一个实现,一把锁
能改「有多少行可读」的有:折进一条事实(absorb)、事件循环写 activity、两处取消、以及点击折叠一个块。它们在两个线程上跑(事实在发射器线程、activity 在事件循环线程),所以除了共用一个方法,还要共用一个 gate:回合结束时事实和 activity 几乎同时到,各自量到同一个变化、各补一次,屏幕就跳两倍。
6.3 符号对称
absorb 原来只在内容变高时补偿滚动位置(if grew > 0),因为块只增不减。尾部进了滚动总量之后会缩(activity 翻转、计划变短),缩的那一半不补偿会让读者正看的行往下跳。
更要紧的是有几条路能改总量,而它们不是一条路:尾部高度有一半来自 Moment::activity,那是由事件循环写的,从不经过 absorb;state.turn 那一半才走事实。先后顺序没有保证,所以只挂在 absorb 上的补偿会「有的回合钉得住、有的钉不住」——比完全不钉更糟,因为它看起来是好的。
因此补偿是一个方法:Host::pinned(only_when_held, change)——「量、改、重新读、再量、写」,外面套一把 gate。哪条路自己抄一份算术,就会在那里分叉;哪条路忘了,就只有它不钉。
源码 host.rs 完整实现了这个契约:
fn pinned(&self, only_when_held: bool, change: impl FnOnce()) -> i64 {
let _gate = self.pin_gate.lock().expect("pin gate poisoned");
let room = *self.last_room.lock().expect("room poisoned");
...
let before = self.moment.read().expect("moment poisoned").clone();
let held = !only_when_held || before.scroll.0 > 0;
let before_h = if held { self.stream_height_in(room, &before).0 } else { 0 };
change();
if !held { return 0; }
// Measured again *after* the change, and against the moment as it is
// now — a fresh read, not the snapshot. ...
let after = self.moment.read().expect("moment poisoned").clone();
let after_h = self.stream_height_in(room, &after).0;
let grew = after_h as i64 - before_h as i64;
...
m.scroll = crate::moment::ScrollPos((m.scroll.0 as i64 + grew).clamp(0, max) as usize);
grew
}
调用点分散在五处:absorb_logged 折一条事实(self.pinned(true, || { self.fold(logged) }),host.rs)、Host::set_activity、两处取消、以及点击折叠一个块(走 held_while,host.rs)。
6.4 only_when_held 的真实差别
折一条事实时「在底部」的意思是跟随输出,不用钉;而点击是一个人指着某一行,那一行必须留在原处——展开一个块是向上长的,最常见的发生地点恰好就是底部。所以点击路径用 held_while(only_when_held = true 的反面语义),把「指着的那一行」钉在原位。
七、模块职责的收束:live 不再读 scroll,徽标锚在对话区
7.1 showing() 收回到只回答 doing()
live 的 showing() 不再读 scroll。 滚动位置归宿主,模块只回答「有没有话要说」(doing())。这同时是上面 stream_height 契约的前提:否则 stream_height 依赖 scroll、scroll_limit 又依赖 stream_height,成环。
源码 live.rs 的注释完整记录了这次职责收束,并直接引用本条 ADR:
One question, and it is not about the screen. This used to ask a second one — whether the reader was at the bottom — and hand the row back while they were not. That was a module deciding where it goes, which is the host's business, and it is why the live line had a rule the task list beside it did not. The row rides the stream's tail now: scrolling takes it away because it is content, and content moves, rather than because the line looked at
moment.scrolland withdrew. Seedocs/adr/0020.
showing 的实现因此退化为一句话:
fn showing(state: &State, moment: &Moment) -> Option<String> {
doing(state, moment)
}
7.2 「回到底部」徽标锚在对话区上,不是整个 pane
理由是它不该盖住尾部:锚到 pane 会让它在 0 < scroll ≤ T 时压住尾部最后一行的右半截——而尾部正是往回滚的读者没有在看的东西,而滚轮一格一行,读者会经常停在这段区间。
(徽标的数字仍是 moment.scroll,含尾部那些行。在这个区间里对话其实没有行在视野下方,所以数字说的不是「对话还有多少行」,而是「往上还有多少行内容」——措辞按后者读。)
八、准入判据与 ask 的让位口子
8.1 谁能进 tail
进 tail 的是「关于这一轮正在做什么、值得被滚回去看的」内容(todo、live);应用框架不进(status、input、tip)——尤其 tip,它的不变量是「行常在、永不动输入框」(modules/tip.rs)。
tail 是声明在树上的,所以 /hide、<a href="https://link.gitcode.com/i/9b067c8ade8319e8381ce7d748921a5d" target="_blank">[remove]]、prune(El::prune)对它照常生效——这是 ADR 0010「一行一个面板」的延续。生产布局中,[host.rs 的 TAIL 常量定义了默认尾部成员(todo、live 及各手工作面板),并通过 Region::stream().with_tail(TAIL.iter().copied()) 装配(host.rs)。
8.2 ask 让位:一条很窄的口子
一个 tail 成员可以让应用框架让位——但只能由一个明确的判据驱动,且只在让它让位的那一行自己身上。问题是按需出现的面板(modules::ask,见 ADR 0010),出现时它要占的正是输入框那一块:没有消息可打,要打的只有这一个答案。所以它出现时 tip 与 input 报 0 行,输入框的整块高度回到对话。这条口子的形状很窄,ADR 写清了它窄在哪:
-
判据是一个字段,不是一段逻辑。
Moment::asking有值时才是「问题占着屏幕」,而它只在面板行已挂载时才被置上(Host::sync_asking)——摘掉tui-panel-ask行后,问题退回流尾的纯文本兜底,输入框原地不动。所以「谁画问题」和「谁让位」永远是同一个答案,不会出现「为不存在的面板让了位」。源码 host.rs 印证了这一点:sync_asking是唯一写asking的地方,且以ask_panel_mounted()为门。 -
让位发生在仲裁处,不在模块里。
asked_height(host.rs)是唯一决定每个模块拿多少行的地方;tip/input的height仍只回答「我自己需要几行」,与屏上有没有别的东西无关。反过来做(模块自己读asking后返回 0)会让一个模块的尺寸取决于兄弟模块,而Hug契约的全部意义就是避免这件事。唯一在height里读asking的是live——因为它整个可见性本来就在height(由showing决定),再加一条「问题在场时让位」是同一个问题的第二个答案,不是跨模块耦合。 -
输入框不能为了「常在那」而不让位。
tip的不变量是「行常在、永不动输入框」,而问题在时并没有手正伸向输入框——这条让位不违背它的不变量,只是把它暂停在一个更弱的保证上。若日后有人给某个框架模块加「永不消失」的性质,这条要先被重新讨论。
ask 模块本身在 ask.rs 的文档注释中也确认了新归宿:「it is now a module riding the stream's tail (crate::modules::ask), because a question is the newest thing in the conversation and that is where the newest thing goes」。
九、不是「把 todo 塞进流」:与 tui-composability.md 的边界
docs/tui-composability.md §一「Todo:同一批事实,两个模块」明确反对把 todo 清单塞进流:清单做成块,每勾掉一项就追加一份,流被刷屏。那条结论不变,本条也不与它冲突——两件事的区别是:
| 做成块(被否) | 排在滚动尾部(本条) | |
|---|---|---|
| 模块类型 | 流生产者 | 仍是视图模块 |
| 每次变更 | 追加一个不可逆块 | 每帧重画,不追加任何东西 |
| 有历史 | 有(流被刷屏) | 无(与今天一致) |
| 变了什么 | 流的内容 | 只是行画在哪——从固定矩形改为滚动序列的尾部 |
换句话说:本条只挪动「面板的行在哪」,不改变「面板是不是每帧重画、有没有历史」。content_hash、Live → Settled、不可逆性一律不受影响,docs/tui-composability.md 中「滚动位置在 Moment 里,且不影响任何块的 content_hash」的条款继续成立。
十、实施路线与权衡:分两步走,放弃了什么
10.1 实施分两步:todo 先,live 后
两者的收益不对称——todo 可能有 5–10 行,能被部分滚出视野;live 只有 2 行,往回滚 2 行就出视野,与现状的「让位」观感几乎相同。先做 todo 可以在较小的影响面上验证最危险的部分(stream_height 的签名、pin 的符号性、尾部几何),而 live 那条 showing 判据此时还能当对照组。
10.2 放弃的四个方案
-
让位(现状):读者一往回滚,面板整体消失。 零成本,
live已经在这么做,todo加三行即可。放弃有两个理由:一是它是二值跳变——一个 10 行的todo面板只滚 1 行就整块消失,而「滚上去扫一眼再回来」是常见动作;二是它要求模块读宿主的滚动位置,与 0004 划的职责不符。代价:改动跨布局引擎与滚动算术。 -
刚性平移:按全高渲染,再切掉滚出去的几行。 更接近「整块移动」的字面语义,而且完全可见时输出与自适应方案逐行相同。放弃是因为切的顺序与两个模块的排版策略相反:
live的行序是<a href="https://link.gitcode.com/i/f5eb5dcf153702693d78284e50b19974" target="_blank">空白, 文字](margin 在上),底部先滚掉的是文字,会留一行空白;todo::window的策略是「默认取尾部、按 frontier 往前拉」,从底部切**正好切掉它刚优先保留的 frontier」。源码 [todo.rs 印证了window的兜底策略:「prefers the tail (where the recent work is) and pulls back only as far as the frontier needs: the in-progress item, else the first pending one. Items dropped below the window get a+Nrow」,即let start = (items.len() - body).min(frontier);。 -
并入流的单一缓冲区(帧里只有
part("stream"))。 一套裁剪逻辑,帧里更干净。放弃是因为它会丢掉每个模块的帧内身份:containment 检查(Frame::containment_violations,frame.rs)、part("live")式的测试定位、以及将来某一行要被单独寻址(点击、高亮)都会变难。代价是每个 tail 模块各算一次可见区间。为此每个 tail 模块保留自己的 part,owner 就是模块 id,不加前缀——因为一帧里 id 已经唯一:named_twice拒绝一棵同时把某个模块声明为 tail id 和独立叶子的树;加前缀的收益只是「帧里能看出层级」,代价是part("live")/part("todo")十几处调用点和 e2e 里按 rect 定位的用例全要改名——而本条要的恰恰是「测试继续能按模块名定位」。 -
给 tail 模块各自一个固定矩形,由宿主平移。 保住模块身份,改动更小。放弃是因为「部分滚出」要么回到刚性切行(行为错,同上),要么给每个模块引入裁剪概念——后者等于把滚动语义复制进每个模块。
十一、失效条件与演进边界
- 若出现在尾部需要交互的模块(点击折叠、按行选中),「它是一串行」的模型不够,要回到「每个模块自己的矩形 + 裁剪」。
- 若尾部高度变化的频率高到 pin 的补偿在观感上仍然抖,「尾部属于滚动内容」需要重新权衡(一条出路是给尾部一个固定预留高度)。
- 若出现第三类需要「有历史、又要每帧重画、又要可滚」的模块,0004 的两类划分与本条要一起重新论证。
结语与相关文档
ADR 0020 是 AtomCode TUI 在「时间可组合性」(ADR 0004 的不可逆流)与「空间可组合性」(面板布局)之间打通的关键一环:它把「视图模块的行属于宿主矩形」这条几何约束拆掉,让面板以仍是视图模块、仍无历史的身份进入滚动内容,同时用 pinned 的单点补偿与 stream_room 的统一量尺守住滚动体验的确定性。想继续深入可阅读:
- ADR 0004:TUI 的流是不可逆块序列——本条补的是它没有回答的第三件事
- ADR 0007:布局树与 op 词汇表
- ADR 0010:每个面板是一行——
tail仍是「一行一个面板」:位置声明在树上,prune照常剔除 - TUI 的时间与空间可组合性——流模型与「todo 不能塞进流」的原始论证
- 核心实现:el.rs、host.rs、live.rs、todo.rs