AtomCode TUI 滚动尾部机制解析:视图模块的行如何成为流内容并随对话一起滚动

原创2026-10-14 10:00:121,907 阅读
文章标签:代码智能体AI Agent人工智能大模型CLIMCP Clients工具调用开发工具Agent 工作流

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 背景):

  1. todo 与 live 的矩形由布局树定死(host::composer),moment.scroll 对它们毫无影响——读者往回滚看历史时,面板钉在底部挡着历史。
  2. 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() 本身),判据从这里出发。五条判据:

  1. pin 符号对称——用 activity 翻转触发(set_activity),而不是「todo 变短」;
  2. 框架模块不受 scroll 影响:status / input / tip 的 rect 在任何 scroll 下不变——守住「输入框永不移动」(modules/tip.rs);
  3. stream_height 与实画一致:块区行数 + 各 tail 模块实际 place 的行数 == 该高度(都用封顶后的值);
  4. 同一模块不得同时出现在 tail 和树中:构造一棵故意同时含 tail: ["todo"] 与 El::Module("todo") 的树,断言它被判红(El::named_twice + Layout::apply 拒绝 + the_layout_this_build_ships_names_no_module_twice);
  5. 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 分支的完整接线:

  1. 取 content_rect(去掉滚动条列)作为 pane;
  2. tail_heights_of(&tail, rect.w, &moment) 向每个 tail 模块问高度(tail_heights_of:Height::Fixed(n) | Height::Hug(n) => n,Height::Fill => 1;未挂载的直接跳过——prune 会把它从树上摘掉,未挂载的 tail id 不是任何行);
  3. pane_geometry(rect, moment.scroll.0, &heights) 切出 block_rect 与各尾部矩形;
  4. stream_lines(pane.block_rect, pane.block_scroll, ...) 画块区,Hits 只索引块区——尾部的 y 落在 block_rect 之外 → block_at 返回 None → 点尾部什么都不发生(与今天一致),RowOwner 不需要新变体;
  5. 每个 tail 模块按 frame.place(id.clone(), *tail_rect, lines) 放在自己的 id 下、不加路径前缀:named_twice 已保证一帧内 id 唯一,part("live")/part("todo") 等十几处调用点和 e2e 按 rect 定位的用例都不用改名(ADR 评审第 8 条);
  6. 交互面板(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/ 里长期留档。

登录后查看全文
atomcode