Skip to content

perf(tui): repaint the streaming message without re-arranging the transcript - #871

Closed
leonsong09 wants to merge 1 commit into
lsdefine:mainfrom
leonsong09:pr/tui-stream-layout
Closed

leonsong09 wants to merge 1 commit into
lsdefine:mainfrom
leonsong09:pr/tui-stream-layout

Conversation

@leonsong09

@leonsong09 leonsong09 commented Nov 12, 2026 •

Copy link
Copy Markdown

问题

TUI 在长会话里发卡、🤔 思考中 期间字成段地蹦出来。

线上进程用 py-spy record 12s 采到的事实:主线程忙 3.46s / 12s(29%),其中 **2.41s(70%)**全在

_on_timer_update -> _refresh_layout -> reflow -> _arrange_root -> compositor.add_widget...

即「重排版」,不是渲染内容本身。触发频率约 11.6 次/秒,偶发 400ms+ 的整屏重排。

根因

Static.update() 默认 layout=True(textual 8.2.5 源码),而流式渲染每 50ms 调一次:

last_widget.update(Text.from_ansi(display, style=C_FG))     # layout=True
self.query_one("#messages", VerticalScroll).refresh()       # 又标脏一次

于是每来一小段 token,整棵消息区就被标成 layout-dirty,下一帧全量 arrange —— 开销随已挂载消息数线性增长,所以对话越长越卡。

改动

  1. 新增 _rendered_height() / _update_text():先算新内容在该宽度下占几行,只有高度变化才请求 layout。同一段里追加字(流式最常见情况)变成重绘,换行/新段仍会撑高控件,不会裁行。
  2. spinner 与 turn 结束注释走同一 helper(固定单行,永不 layout)。
  3. 去掉多余的 #messages.refresh()(控件 update 已标脏)。
  4. 合流窗口 50ms → 常量 STREAM_PAINT_INTERVAL(默认 100ms,GA_TUI_PAINT_MS 可覆盖)。

实测

headless、真实 TUI 组件、30 轮对话、20Hz 流式 2 秒:

重排次数 主线程耗时
改前 37 466 ms
改后 3 18 ms

spinner 单测:20 次 → 3 次;update(layout=False) 全局对照:26 次 → 0 次。

回归

新增 frontends/tests/test_tuiapp_v2_stream_layout.py,钉两头:

  • 同一行内增长不得请求 layout;
  • 内容长出新行时控件高度必须跟着长(height == 9,最后一行 line 08 可见)——防裁行。

frontends/tests 全量:273 passed,3 个既有失败(test_data_backup symlink、test_release_qualification 缺文件)与本次无关,stash 后同样失败。

…nscript

`Static.update()` defaults to `layout=True`, so every 50ms streaming paint
marked the whole screen layout-dirty and made Textual re-arrange every mounted
message on the next frame.  On a long session that is 5-15ms per token chunk
(and ~400ms spikes), which shows up as an unresponsive composer and text that
only appears in bursts.

Paint only what changed:

* `_rendered_height()` / `_update_text()` compare the height the new content
  would occupy and request a layout pass only when it differs.  Same-line
  growth (the common case while tokens stream) becomes a repaint, not a reflow.
  New lines (.e.g a new paragraph) still grow the widget, so nothing is clipped.
* the spinner and the post-turn annotation go through the same helper - they are
  single-line and never need a layout.
* drop the redundant `#messages.refresh()`; the widget update already marks the
  changed region dirty.
* the streaming paint coalescing window becomes `STREAM_PAINT_INTERVAL`
  (default 100ms, `GA_TUI_PAINT_MS` to override) instead of a hard-coded 50ms.

Measured on a 30-turn transcript (headless, real widgets): 37 -> 3 layout
passes per 2s of 20Hz streaming, 466ms -> 18ms of main-thread time.  Live
profile before the change: 29% of the main thread inside
`_refresh_layout -> reflow` ("py-spy record" on a running TUI).

Co-Authored-By: GenericAgent <bot@gaagent.ai>
@leonsong09

Copy link
Copy Markdown
Author

superseded by #881 — see #880 / #881.

Folded into #881, unchanged, as the first commit (+222/-12).

Closing to keep one open diff per change.

@leonsong09 leonsong09 closed this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant