AtomCode TUI 滚动尾部机制解析:视图模块的行如何成为流内容并随对话一起滚动
AtomCode TUI 滚动尾部机制解析:视图模块的行如何成为流内容并随对话一起滚动
AtomCode 的 TUI 前端将屏幕内容划分为「不可逆块序列(Stream)」与「每帧重画的视图模块」两大类。本篇文章围绕 docs/plans/2026-09-15-stream-tail-view-module-scroll.md 这份实施计划及其决策依据 ADR 0020,完整讲解「滚动尾部(scroll tail)」机制:todo(任务清单)与 live(这一轮在做什么)等视图模块的行如何从「钉死在屏幕底部的独立面板」变成「流内容的一部分」,读者回滚时随对话一起上移。读完你既能掌握尾部几何模型、接缝划分与落地步骤,也能从当前源码中定位 Stream { tail }、cap_tail、pinned 等关键实现的真实位置。
背景:ADR 0004 留下的第三个问题
ADR 0004 把屏幕分成两类实体:
- 流生产者:追加不可逆块(对话内容);
- 视图模块:每帧全量重画、无历史(面板)。
它划清了「块的不可逆性归谁」,但没有回答第三件事:一个视图模块的行,能不能成为流的一部分,跟着流一起滚?
现状是不能,并带来两个后果(见 ADR 0020 背景):
todo与live的矩形由布局树定死(host::composer),moment.scroll对它们毫无影响——读者往回滚看历史时,面板钉在底部挡着历史。live为此开了一条特例:showing()(modules/live.rs)读moment.scroll.is_at_bottom()决定自己存不存在。一个视图模块为了决定自己画不画,去读宿主的滚动位置——职责错位,而且todo没有这条,两个同类模块行为不一致。
composer() 的文档曾记下当时为什么没做:LayoutOp::Show 只有「对话之上」和「状态栏之下」两个方向,都在输入框的错误一侧;面板只能把自己的位置写进树里,而写进树就固定了矩形,也就与滚动无关。本条 ADR 就是拆掉这道几何约束。
核心决策:El::Stream 携带 tail 声明
决策一句话:El::Stream 带一个 tail 声明——哪些模块的行构成流的尾部(ADR 0020 决策)。
El::Stream { tail: Vec<String> }
tail 里的模块不再有自己的布局矩形。它们的行是流内容的一部分:参与滚动偏移,也参与滚动上界。tail 之外的一切照旧——El::place_into 仍把 Stream 当一个叶子、交给它一个矩形;El::wanted 仍让它报 1 行、靠 grow 吃满剩余。
在今天的源码里,这一决策已完整落地为 el.rs 的 El::Stream { tail: Vec<String> }(el.rs#L141),配套两个构造器:
El::stream()(el.rs#L215):不带 tail 的普通流,测试与无尾布局的常见形态;El::with_tail(...)(el.rs#L225):追加 tail id,顺序即尾部内部自上而下的布局顺序,最后一个 id 贴着 pane 底边——最新的东西在眼睛所在处;对非 Stream 节点调用是 no-op,布局是用户可写的数据,包错节点不能让屏幕崩掉。
为什么 tail 必须是 id 列表,而不是子节点
这是接缝 S1,动手前就已定死:
El::Stream仍是叶子:place_into照旧交出整个矩形就停;- 切 pane 的是 host:compose 的循环绑定
region本身(host.rs 的Region::Stream分支),所以它可以从同一个值里读到tail,自己算出block_rect+ N 个尾部矩形; - 不能把尾部做成
Stream的子节点。那样布局引擎会按 flex 给每个子节点一个矩形——永远全部 N 个可见,而我们要的恰恰是「能被部分滚出视野」。滚动概念一旦进引擎,就得在引擎里重做一遍偏移算术。
一句话:引擎对滚动一无所知,tail 只是一个 id 列表。 这一点在 el.rs#L126-L141 的文档注释里写得很清楚。
第三条路:tail 声明放在 default_layout()
面板定位自己的位置今天有两种做法:
| 面板 | 怎么定位 | inject() |
|---|---|---|
MascotPanel |
用 LayoutOp::Show{side: Top} 自己占位 |
["tui-modules","tui-layout"] |
TodoPanel |
什么都不做,只 add_view |
["tui-modules"] |
TodoPanel 的注释正是 ADR 0020 的出发点:「Mount only. Where it goes is the composer's to write——LayoutOp::Show has no side that means "above the field".」所以 composer() 是「宿主替这类面板写位置」的唯一地方。tail 声明放在同一层(default_layout() 里构造 Stream{tail}),不是新机制,而是那条既有约束的延伸。ADR 把它描述成第三条路:不是「用 op 自己占位」,也不是「宿主写死一个 rect」,而是「宿主写死它属于可滚动尾部」。
当前源码中,宿主层的唯一构造入口是 scroll_region():
pub fn scroll_region() -> Region {
Region::stream().with_tail(TAIL.iter().copied())
}
而 TAIL 是一份单点定义的常量列表(host.rs#L7435):
pub const TAIL: &[&str] = &[
crate::modules::todo::ID, // "todo"
crate::modules::live::ID, // "live"
crate::modules::settings::ID,
crate::modules::providers::ID,
crate::modules::plugins::ID,
crate::modules::tools::ID,
crate::modules::mcp::ID,
crate::modules::rewind::ID,
crate::modules::resume::ID,
crate::modules::sheet::ID,
crate::modules::flow::ID,
crate::modules::bg::ID,
crate::modules::ask::ID,
crate::modules::steering::ID,
];
这份列表的注释交代了每个成员的排位理由:ask 坐在 live 与 steering 条之间(模型在等待什么);settings/providers 同族同行、直接坐在 live 下;steering 最后——尾部自底向上排,最后意味着最靠近读者刚打完字的输入框。「一条路径补偿、另一条不补」是计划里点名的风险,而「一个列表、放在一处」正是对应的兜底:named_twice 只防「画两遍」,不防「一遍都没画」,所以列表只能加一次或根本不加。
与 TAIL 配套的是 HELD(host.rs#L7456):正在被手使用的面板不随滚动离开——设置、供应商、插件、工具、MCP、rewind、resume、sheet、flow、bg、ask 都属于这一类,它们钉住 pane 底部,只有 todo、live、steering 这些「只读」成员真正参与滚动(详见下文 pane_geometry)。
几何模型:一个 pane 怎么被切成块区与尾部
设 pane 拿到 H 行,内容 = 块(B 行)+ 尾部(T 行),计划与 ADR 0020 给出的核心公式:
visible_tail = (T - scroll).clamp(0, H)
block_scroll = (scroll - T).max(0)
block_rect.h = H - visible_tail
scroll_limit = (B + T) - H
几个必须理解到位的行为:
- scroll 在
[0, T]区间里block_scroll恒为 0——尾部先被吃掉,块的偏移不变; - 但这不是「块在屏幕上一动不动」:
block_rect.h每格长一行而内容底对齐,所以块每格下移一行,顶上同时多露出一行更旧的。ADR 里「块纹丝不动」说的是偏移,不是屏幕坐标。判据要断言的是「同几行字仍在视野里」,不是「块的行位置不变」; - 尾部内部按「距底部的偏移」自底向上分配;某模块
visible == 0时不 place(即part(...).is_none()); - 尾部交付的是可见高度,模块自己排版(不刚性切行)——
todo::window会保住 frontier 并标+N 更多,live::render会在放不下 margin 时丢 margin 保文字。
这套几何在源码中的真实实现是 Host::pane_geometry(host.rs#L5749)与 Host::pane_geometry_capped(host.rs#L5775)。后者从 scroll 起按「距底部的距离」倒走循环:d = 0 是最后一行内容,窗口覆盖 [scroll, scroll + h);模块完全在上方折线之上就不 place,被拦腰截断的模块保留可见行、rect 相应变短——这正是「问模块要它自己的高度、而不是给它一整条带」的原因。HELD 成员在 pane_geometry 里被单独切出钉在 pane 底部,其余部分照常滚动,且滚动上界不变((B + T_rest) - (H - T_held) 与 (B + T) - H 相等),只是面板高于 HOLD_LEAVES(5 行)时会放弃钉住、随尾部滚走。
尾部总高必须封顶:cap_tail
尾部总高要封顶,而且从最上面开始让(ADR 0020 决策)。原因:交给模块的是它可见的高度,高于 pane 的模块会在若干个不同 offset 上都被问「你有 pane 这么高」,每次都排出一模一样的画面——读者滚 T − H 格,屏幕不动,只有「还有 N 行」在涨。所以总高封在 H − 1(至少给对话留一行)。
让行的顺序自顶向下:tail 里第一个先让完,才轮到下一个。贴着底边那个是最新的、也是回答「是不是卡住了」的那一个;它上方的东西多半有兜底(任务清单有 window 和 +N 更多),它没有。这条曾经写反过——注释说底边保留、循环却从底边扣起,于是一份长计划在短终端里第一件事就是把 live 行清空。
源码实现 cap_tail:
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;
}
heights
}
封顶必须与 stream_height 共用同一个值、同一个 pane 高度——几何和量高两处各算一次封顶、各有一种答案,就是滚动上界与画面对不上的根因(详见下文「宽度不一致」一节)。
尾部自适应排版:todo::window 与 live 的 margin
尾部不给模块刚性高度,而是把可见高度交给模块自己排版。两个模块都早已会处理「行不够」:
- modules/todo.rs 的
window(todo.rs#L426):默认取尾部、按 frontier 往前拉。frontier是InProgress项、否则第一个Pending项,窗口从(items.len() - body).min(frontier)起——正在做的那条优先保住,被藏掉的下方条目用+N 更多说明;被藏掉的上方条目不需要标记,因为带编号、#6开头已经读作「上面还有五条」。 - modules/live.rs 的渲染在放不下 margin 时丢 margin 保文字。
刚性平移先切掉的正是这两样,所以被否决(ADR 0020 放弃了什么)。
接缝:只有两个函数要真正理解 tail
计划里逐一核定了 El::Stream 变结构体后各函数的命运(接缝 S2):
| 函数 | 改法 |
|---|---|
modules()(el.rs) |
要改——收集 tail 里的 id。否则 /hide todo 报 NotOnScreen(Layout::apply 查的就是 tree().modules()) |
prune()(el.rs) |
要改——过滤 tail 列表(未挂载的剔除) |
place_into(el.rs) |
不动——仍交出一个 rect |
wanted(el.rs) |
不动——仍报 1,靠 grow 吃满 |
当前源码印证:modules()(el.rs#L344)在遍历时对 El::Stream { tail } 执行 out.extend(tail.iter().cloned());El::tail()(el.rs#L394)穿透 Flex/Stack 找到流的 tail;named_twice()(el.rs#L372)拒绝一棵「同一模块既是 tail id 又是独立叶子」的树。
这是 Step 2/3 必须守住的不变量:同一模块不得同时出现在 tail 和树中——否则被渲染两次。Layout::apply(layout.rs#L113)在安装新树前统一检查 named_twice() 并返回 LayoutError::NamedTwice;Hide/Show 的 on_screen.contains(module) 检查也因此对 tail 成员正确生效(tail 在屏上时 Hide 可接受、Show 拒绝并返回 AlreadyOnScreen)。
/hide /show /swap 的行为核对
逐条核过 Layout::apply(layout.rs#L113-L156):
| op | 行为 | 结论 |
|---|---|---|
Hide{todo} |
先查 on_screen.contains(module) |
tail id 必须进 modules()——即 S2 ✅ |
Show{todo} |
已在屏上时返回 AlreadyOnScreen |
todo 在 tail 里时被正确拒绝 ✅ |
Swap{Target::Stream} |
matches() 只认叶子模式 |
⚠️ 原来按 Target 重建节点,tail 会丢;已修成找到原节点整体克隆,并拒绝以 tail id 为目标 |
既存别扭(不是本次引入): /hide todo 之后 /show todo,它会作为浮动兄弟节点插回来(Region::split,size 默认 1 行),不会回到 tail。今天也一样,不是回归,可靠的回退路径一直是 Undo。
落地过程:Step 1–5
计划记录了五步的完整落地链(每步对应一个 commit):
Step 1——el.rs:Stream 带 tail(行为不变),commit 25a09e40
// 改前
Stream,
// 改为
Stream { tail: Vec<String> },
El 已 derive Clone, Debug, PartialEq,加字段无需额外 derive。新逻辑只落在 modules() 与 prune() 两个函数上;place_into 与 wanted 不动。完成判据:cargo nextest run -p atomcode-tui 全绿——tail 处处为空,行为不变。
Step 2——host.rs:几何与签名(行为不变),commit 9b47cb0b
新增纯函数(便于单测、不碰锁):
struct Pane {
block_rect: Rect,
block_scroll: usize,
tail: Vec<(String, Rect)>, // (id, 可见矩形);visible == 0 的不在此列
}
fn tail_geometry(pane: Rect, scroll: usize, heights: &[(String, u16)]) -> Pane
stream_lines 收 offset(内部从 moment.read() 取 scroll 改为参数);compose 里 Region::Stream 分支接线;stream_height 收 &Moment——因为尾部高度依赖 Moment(live 由 activity 决定),而调用方可能正持写锁(plugin.rs 的 click 路径确实如此),所以不能内部读锁。计划如实记下「行为不变」与 2e 符号化的张力:if grew > 0 改成 if grew != 0 只有在「块高在一次 absorb 里不会减少」时才等价,而这一点当时没有证明、也没有判据;真正修掉这条的是 b7fb3829。
Step 3——先接 todo,commit c94a301a
三个构造点,一个入口。 尾部要在三处出现:host::default_layout()、layout.rs 的 focus 与 wide 两个 preset。漏掉一个,那个 preset 里 todo 就悄悄消失,而 named_twice 照样绿——它只防「画两遍」,不防「一遍都没画」。所以抽唯一入口:
pub fn scroll_region() -> Region { Region::stream().with_tail(TAIL) }
判据改成**「每棵出厂的树里 todo 和 live 恰好出现一次」**,而不是「没有出现两次」——后者对「一次都没有」是绿的,前者两边都拦。
其余要点:拆 host::composer(),滚动部分(todo)与框架部分(tip + input)分开;移走树里的 El::Module("todo") 与声明 tail 必须同时发生,否则 todo 被渲染两次;新增判据 pin 符号对称——用 activity 翻转触发(set_activity),不用「todo 变短」——后者走 absorb 路径,而 absorb 那条路在 b7fb3829 之前就已经有判据了,盖不住 activity 那条。
wide 下 tail 会跟着 stream 缩进左边 65% 那一列,今天是整宽。这是行为变化,不是回归,写在这里免得被当成 bug。
Step 4——接 live,删让位,commit 2b9580b2
tail: vec!["todo".into(), "live".into()];- modules/live.rs 的
showing():删除if !moment.scroll.is_at_bottom() { return None }; - 删掉测试
the_line_gets_out_of_the_way_while_the_reader_is_scrolled_up; a_scrolled_up_reader_is_not_shown_the_live_line改写:滚上去后 live 仍在滚动内容里,再滚一行才出视野(替代原来的「整体消失」断言);- 原断言「live 令 stream 高 -2」不再成立(现在 live 在 pane 内),按新几何改。
这一步完成后:视图模块不再读 scroll(全仓仅 live 曾有此特权)。今天的 showing() 只剩 doing(state, moment)——滚动位置归宿主,模块只回答「有没有话要说」。
Step 5——补齐无兜底的风险,commit 4247ed59
夹具先要真的挂上尾部:host() 只挂了 transcript/status/input,没挂 todo/live,也不声明 tail——用它写尾部判据会恒真(tail_heights 返回空,几何退化成恒等,断言什么都过)。Step 2 已为此建了 host_with_peek_tail()(带一个高度只跟 activity 走的 Peek 仪器模块);Step 3/4 需要挂真 todo/live 的版本(即 Step 3 之后的 default_layout() 本身),判据从这里出发。五条判据:
- pin 符号对称——用 activity 翻转触发(
set_activity),而不是「todo 变短」; - 框架模块不受 scroll 影响:
status/input/tip的 rect 在任何scroll下不变——守住「输入框永不移动」(modules/tip.rs); stream_height与实画一致:块区行数 + 各 tail 模块实际 place 的行数 == 该高度(都用封顶后的值);- 同一模块不得同时出现在
tail和树中:构造一棵故意同时含tail: ["todo"]与El::Module("todo")的树,断言它被判红(El::named_twice+Layout::apply拒绝 +the_layout_this_build_ships_names_no_module_twice); - pin 符号对称的补充判据:已随
b7fb3829落地。
已修的地基缺陷(外部评审,2026-09-15)
两条会在 Step 3/4 落地后发作为真 bug 的问题,在 Step 2 之后、Step 3 之前修掉(b7fb3829 / b453eb4e),判据成为地基的一部分:
① 补偿只挂在 absorb 上,而 tail 高度有一半不经过 absorb。 state.turn 走事实(absorb),Moment::activity 由事件循环写(从不经过 absorb)。先后无保证,所以读者回滚时每轮开始/结束屏幕会跳 tail 那两行。修法:补偿收成 Host::pinned 一个方法,五条路径共走(absorb / Host::set_activity / Cancel ×2 / 点击折叠)。判据用 set_activity 触发——这正是 bug 的要害所在。
② swap 按 Target 重建节点,于是 tail 静默消失,swap todo stream 还会把对话整个删掉并返回 Ok("换位");resize 命中不到时返回原树 + Ok。修法:swap 改为找到并整体克隆命中的原节点;tail 里的 id 作目标直接拒绝;resize 返回 (tree, found),未命中报 NotOnScreen。
③ 徽标锚点:stream_rect 锚 pane.block_rect,不是整个 pane——否则 0 < scroll ≤ T 时它盖住尾部的最后一行右半截。ADR 的解释:回到底部徽标应该锚在对话区上,因为它不该盖住尾部——尾部正是往回滚的读者没有在看的东西,而滚轮一格一行,读者会经常停在这段区间。它显示的数字仍是 moment.scroll(含尾部那些行),所以数字说的是「往上还有多少行内容」,不是「对话还有多少行」。
④ tail 总高封顶:Host::cap_tail 把总高封在 pane_h - 1,自底向上分配。几何和 stream_height 必须用同一个封顶,因此 stream_height 的签名是 size: (u16, u16)。不封顶时 tail 高于 pane 会让屏幕在 [0, T−H] 冻住(实测 T=20/H=19 时 scroll 0 与 1 的 rect 完全相同)。
宽度不一致(评审第 7 条,67c7afde 修)
原来 scroll_limit(size, …) 按 size.0(整屏宽)量块高,而画的时候用 stream 自己的 rect.w;wide 下是 65% 对 100%,滚动上界因此可能少算。这条与 absorb 的回归(评审第 2 条)是同一个问题:「stream 有多大」有两个答案。现在只有一个——Host::stream_room:
fn stream_room(&self, size: (u16, u16), moment: &Moment) -> Rect
宽度给块量行数,高度给尾部算封顶。 stream_height 收 room: Rect(源码里是 stream_height_in,返回 (total, tail) 二元组,因为总量与尾部分额必须来自同一次遍历,两次走会互相打架),scroll_limit 与 pin 都从这里出发,几何和画用同一个数。计划还记下了判断是怎么变的:上一轮归成「既有缺陷、与本次改动无关」是对的——但下一轮同一个东西以「吸收路径按错宽度」的形式回来了。同一个根因的两种表现,分两次到达,第二次才被认出来是同一件事。
pinned 的实现形态
Host::pinned 是「量 → 改 → 重新读 → 量」的完整实现,外面套一把 pin_gate 锁:回合结束时事实和 activity 几乎同时到,各自量到同一个变化、各补一次,屏幕就跳两倍,gate 让五条路径加起来只补偿一次。两次测量用不同的 moment 快照:折叠状态存在 Presentation 里而不是 Moment 里,用同一份快照回量两次会得到同一个数,grew 恒为 0——点击展开一个块就什么都不会补偿,这是真实发生过的一次。
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");
if room.is_empty() { change(); return 0; }
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; }
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;
if grew == 0 { return 0; }
let mut m = self.moment.write().expect("moment poisoned");
let max = self.scroll_limit((room.w, room.h), &after) as i64;
m.scroll = crate::moment::ScrollPos((m.scroll.0 as i64 + grew).clamp(0, max) as usize);
grew
}
only_when_held 是那个真实的差别:折一条事实时「在底部」意味着跟随输出,不用钉;而点击是一个人指着某一行,那一行必须留在原处——展开一个块是向上长的,最常见的发生地点恰好就是底部(此时 scroll.0 == 0,held 为真)。
compose 接线:一帧里尾部模块如何被画出来
源码 host.rs#L6242-L6392 展示了 Region::Stream 分支的完整接线:
- 取
content_rect(去掉滚动条列)作为 pane; tail_heights_of(&tail, rect.w, &moment)向每个 tail 模块问高度(tail_heights_of:Height::Fixed(n) | Height::Hug(n) => n,Height::Fill => 1;未挂载的直接跳过——prune会把它从树上摘掉,未挂载的 tail id 不是任何行);pane_geometry(rect, moment.scroll.0, &heights)切出 block_rect 与各尾部矩形;stream_lines(pane.block_rect, pane.block_scroll, ...)画块区,Hits只索引块区——尾部的 y 落在block_rect之外 →block_at返回None→ 点尾部什么都不发生(与今天一致),RowOwner不需要新变体;- 每个 tail 模块按
frame.place(id.clone(), *tail_rect, lines)放在自己的 id 下、不加路径前缀:named_twice已保证一帧内 id 唯一,part("live")/part("todo")等十几处调用点和 e2e 按 rect 定位的用例都不用改名(ADR 评审第 8 条); - 交互面板(ask/settings/providers/plugins/tools/mcp/rewind/resume/sheet/bg)的 rect 被记进
hits——指针必须由屏幕上那帧回答,而不是由一个需要复现尾部切分的公式回答。
stream_height_in 的量高与实画严格同源:块区总量来自 row_index 单次求和,尾部用同一个 cap_tail、同一个 room.h 计算,未挂载 ask 面板时问题行的兜底文本也计入——一行「帧画了而量高没算」的行就会在滚动底部够不着,这正是 row_index 存在要防的失败。
验证方式与判据棘轮
计划给出的验证命令(每步之后):
# 每步之后
cargo nextest run -p atomcode-tui
cargo test --doc -p atomcode-tui # nextest 不跑 doctest(本 crate 可跑 0,确认没丢)
# 每步收尾
bash gates/tui-test-count.sh # 判据数只能升(当前 486)
bash gates/tui.sh
bash gates/tui-layers.sh
bash gates/tui-string-slice.sh
bash gates/tui-negative.sh
# 交付前(唯一阻塞门)
cargo fmt --all && cargo fmt --all -- --check
注意不要 --workspace(AGENTS.md:9 个 consumer 各开不同 feature,全量会编 19 次);本次无跨 crate 依赖变化,-p atomcode-tui 足够。判据基线记录在 gates/tui-test-count.baseline(开工时 468,交付时 495),棘轮只能升——新增判据必须用新测试钉住,不允许删测试换绿灯。
退化风险与兜底
| 风险 | 兜底 |
|---|---|
尾部绕过 window_into → 整块物化 |
✅ host.rs COPIED_ROWS == drawn(不并入缓冲区时天然成立) |
| 滚回时渲染量随会话增长 | ✅ host.rs 的滚回路径按窗口裁剪 |
height 与实画行数失衡 |
✅ stream_height_in + Step 5.3 判据 |
| pin 单边补偿 → 抖动 | ✅ b7fb3829 的 activity 翻转判据已覆盖 |
stream_height 内部读锁 → 死锁 |
⚠️ 会挂而非静默;stream_height 收 &Moment,调用方传守卫 |
| 同一模块同时在 tail 与树中 → 画两遍 | ✅ named_twice + Layout::apply 拒绝 + the_layout_this_build_ships_names_no_module_twice |
| 一条路径补偿、另一条不补 | ✅ pinned 收成一个方法、五条路径共走;opening_a_call_leaves_the_row_that_was_clicked_where_it_was 钉住点击那条(底部也钉) |
| 封顶时先扣掉 live | ✅ cap_tail 自顶向下让 + a_capped_tail_keeps_the_live_line_and_cuts_the_plan |
| 尾部每帧小量渲染 | 可忽略(scroll == 0 时与现状相同;滚过之后反而被算术跳过,不再渲染) |
已知未验证与边界
计划末尾诚实列出了已知未验证的部分:
- 没有实测帧耗时。 本仓无 bench(
crates/atomcode-tui/benches不存在),gates/的性能判据都是计数类(COPIED_ROWS、asked),且只数块、不数模块渲染。「尾部增量成本可忽略」是从代码结构推的,不是量出来的; absorb的last_size是新字段,需确认Host的其它构造/测试路径(直接调scroll_limit/stream_rows的位置)不受影响。
此外还有两件本次未动的既有行为写进了注释:wide 的侧栏 findings 从不挂载、team 没有成员时不占位;以及一处与本主题无关的既有 flaky(harness/tests/harness.rs 的日志落盘顺序用例在完整套件里约 4 次红 1 次)。
ADR 0020 失效条件还给出了三条未来触发重新权衡的信号:出现需要在尾部交互(点击折叠、按行选中)的模块;尾部高度变化频率高到 pin 补偿在观感上仍然抖;出现第三类「有历史、又要每帧重画、又要可滚」的模块。
这不是「把 todo 塞进流」
tui-composability.md §一明确反对把 todo 清单做成流块:清单做成块,每勾掉一项就追加一份,流被刷屏。滚动尾部与「做成块」的区别是(ADR 0020):
| 做成块(被否) | 排在滚动尾部(本条) | |
|---|---|---|
| 模块类型 | 流生产者 | 仍是视图模块 |
| 每次变更 | 追加一个不可逆块 | 每帧重画,不追加任何东西 |
| 有历史 | 有(流被刷屏) | 无(与今天一致) |
| 变了什么 | 流的内容 | 只是行画在哪——从固定矩形改为滚动序列的尾部 |
换句话说:本机制只挪动「面板的行在哪」,不改变「面板是不是每帧重画、有没有历史」。content_hash、Live → Settled、不可逆性一律不受影响,ADR 0004 的「滚动位置在 Moment 里,且不影响任何块的 content_hash」继续成立。
经验沉淀
这份计划文档在开头特意说明「这是一份记录,不是说明书」:文中 file:line 全是写下那一刻的行号,此后代码改动过多次,大多已不对了(抽查 6 处只有 1 处还凑巧落在原处)。要读实现请看文件与函数名——Host::pane_geometry、Host::cap_tail、Host::pinned、Host::stream_room——而不是行号。留着这份文档是因为为什么这么做比当时改哪一行活得久。这也正是「滚动尾部」这条机制给后续开发者的最大价值:它不是一套要照抄的补丁,而是一组关于「哪些职责归引擎、哪些归宿主、哪些判据必须存在」的边界结论,值得在 ADR 0020 与 gates/ 里长期留档。