终端流式输出时偶尔自动滚动到顶部（pi-tui fullRender 触发清屏）

[li-xiu-qi]

What version of Kimi Code is running?

kimi, version 0.16.0

Which open platform/subscription were you using?

Kimi Code

Which model were you using?

K2.7 Code

What platform is your computer?

Windows 11, Git Bash (MINGW64)

What issue are you seeing?

流式输出过程中，终端偶尔会自动跳到最顶部，导致无法看到正在输出的内容，需要手动滚回底部。

What steps can reproduce the bug?

1. 启动 kimi-code，进行一个会产生较长输出的对话（超过终端视口高度）
2. 当模型先 thinking 再输出 assistant 文本时，thinking 阶段结束切换渲染模式时，终端会跳到顶部
3. 或者在长对话中，任何发生在视口上方的组件渲染变化都可能触发

What is the expected behavior?

流式输出时终端应保持在底部，跟随最新输出内容，不跳回顶部。

Additional information

根因分析

问题出在底层 TUI 渲染库 @earendil-works/pi-tui 的 doRender() 方法中。当前版本（0.16.0）依赖的 pi-tui 版本为 ^0.74.0，经确认最新发布的 0.18.0、0.19.0 也使用相同的 pi-tui 版本，因此该问题在最新版本中同样存在。

在 tui.js 第 909 行：

if (firstChanged < prevViewportTop) {
    fullRender(true);  // 发出清屏序列
    return;
}

当第一条变更行在视口上方时，diff 渲染器认为无法通过增量更新到达，触发全屏重绘。fullRender(true) 会发出清屏序列，导致终端从顶部开始重新渲染。

典型触发场景：thinking 阶段结束时，ThinkingComponent 从 live 模式（带动画 spinner）切换到 finalized 模式（静态文本），渲染输出发生变化。此时 transcript 已超过终端高度，视口在底部（prevViewportTop > 0），而 thinking 组件位于 transcript 靠前位置，firstChanged < prevViewportTop 条件成立。

上游修复情况

pi-tui 最新版本是 0.79.10（当前使用 0.74.0），相关修复：

• 0.51.1：修复了 prevViewportTop 计算使用 stale maxLinesRendered 导致不必要的 full redraw
• 0.63.0：修复了内容收缩后 viewport 跟踪错误

建议

1. 短期：升级 @earendil-works/pi-tui 到 >= 0.79.10，利用已有的 viewport 跟踪修复减少误触发
2. 根本修复：在 pi-tui 上游修复 firstChanged < prevViewportTop 分支的降级策略

[li-xiu-qi]

根因确认

Issue 的分析完全准确。经过对 @earendil-works/pi-tui 源码的交叉验证：

1. 0.74.0 第 909 行确实存在 firstChanged < prevViewportTop -> fullRender(true)

2. 0.74.0 已包含 0.51.1 和 0.63.0 的修复
prevViewportTop 计算已使用 this.previousViewportTop 而非 stale maxLinesRendered。

3. 升级到 0.79.10 不会修复此问题
0.79.10 在 doRender 核心逻辑上与 0.74.0 完全一致，firstChanged < prevViewportTop 分支一字未改。

4. ThinkingComponent finalize 触发链确认
streaming-ui.ts 的 onThinkingEnd() -> finalize() -> requestRender() -> doRender() -> firstChanged < prevViewportTop -> fullRender(true)。

---

上游参考

pi-tui 已有专门的 Issue 讨论此问题，并给出了修复方案：

• earendil-works/pi#4506 — 修复方案：当 firstChanged < prevViewportTop（变更在视口上方）时，不要触发 fullRender(true)，只更新内部状态并跳过重绘。

---

修复方向

短期：在 kimi-code 中用 pnpm patch 对 pi-tui 打补丁。

根本：推动 pi-tui 上游合入 #4506 的修复方案，然后 kimi-code 升级 pi-tui 依赖。

[li-xiu-qi]

补充：pi-tui #4506 的状态

pi-tui 的 Issue #4506 已在 2026-05-14 被 github-actions bot 自动关闭，原因是项目当时正在进行大规模重构，期间所有 issue 自动关闭。关闭评论原文：

This issue was auto-closed. All issues will be closed until 2026-05-17 while the project refactor is being completed.

现在重构期已过（已 6 月），但该 issue 未被重新打开，修复方案尚未合入。0.79.10 仍存在此 bug。

因此 kimi-code 短期修复仍然需要自行 patch pi-tui。

[li-xiu-qi]

补充：pi-tui 上游相关 Issue 汇总

在 pi-tui 仓库中搜索到多个描述同一问题的 issue：

Issue	状态	标题
#4506	closed (重构期 bot)	Screen jumping in Termux via SSH + tmux — 根因分析最完整，给出了修复方案
#5576	closed (bot)	Chat view jumps to the top during streaming output — mitsuhiko 参与讨论但无法复现，用户确认 --no-extensions 仍存在
#5839	closed (bot+mitsuhiko)	Sometimes when outputting long content, it suddenly scrolls back to the top — 0.79.6
#5825	open	Streaming markdown forces scroll to bottom — clearOnShrink 相关，但非 kimi-code 直接原因
#5786	closed	PageUp/scroll-up jumps to beginning
#3083	closed	spinner row leaks into scrollback — 也提到 firstChanged < prevViewportTop

关键发现：

• pi-tui 维护者 mitsuhiko 在 #5576 中表示无法复现，但多个用户在不同平台（Windows Terminal、Termux）都确认存在
• #4506 给出了完整的修复方案（firstChanged < prevViewportTop 时只更新状态，不触发 fullRender），但被重构期 bot 关闭后未重开
• 没有任何修复 PR 被合入 pi-tui，0.79.10 仍存在此 bug

[li-xiu-qi]

综合调查结论

1. 根因确认

Issue 分析完全准确。经过对 @earendil-works/pi-tui 源码的交叉验证：

• 0.74.0 第 909 行 确实存在 firstChanged < prevViewportTop → fullRender(true) 导致清屏跳顶
• 0.74.0 已包含 0.51.1 和 0.63.0 的修复（prevViewportTop 计算已使用 this.previousViewportTop 而非 stale maxLinesRendered）
• 升级到 0.79.10 不会修复：0.79.10 在 doRender 核心逻辑上与 0.74.0 完全一致，firstChanged < prevViewportTop 分支一字未改
• 触发链确认：onThinkingEnd() → finalize() → requestRender() → doRender() → firstChanged < prevViewportTop → fullRender(true)

2. pi-tui 上游 Issue 汇总

在 pi-tui 仓库中发现多个描述同一问题的 issue，均未修复：

Issue	状态
#4506	重构期自动关闭 — 根因分析最完整，给出了修复方案
#5576	自动关闭 — 维护者 mitsuhiko 参与讨论但无法复现
#5839	mitsuhiko 手动关闭 — 0.79.6 同样问题
#5825	仍 open — clearOnShrink 相关问题
#3083	已关闭 — 也提到 firstChanged < prevViewportTop

关键事实：维护者 mitsuhiko 在 #5576 中表示无法复现，但多个用户在不同平台（Windows Terminal、Termux）确认存在。没有任何修复 PR 合入 pi-tui。

3. 修复方向

短期：在 kimi-code 中用 pnpm patch 对 pi-tui 打补丁，将 firstChanged < prevViewportTop 分支的 fullRender(true) 替换为只更新内部状态（previousLines、prevViewportTop 等）并跳过重绘。变更在视口上方用户看不到，更新内存即可。

根本：推动 pi-tui 上游合入 #4506 的修复方案，然后 kimi-code 升级 pi-tui 依赖。

[ieasir]

Still reproducing this on kimi-code 0.23.1 under Windows PowerShell.

Symptom: while a turn is running and producing output, the terminal view suddenly jumps back to the very top of the conversation. I have to manually scroll back down to see the latest output. This happens repeatedly during a session, not just once.

Environment:

• Kimi Code: 0.23.1
• OS: Windows 11
• Terminal: Windows PowerShell (not Windows Terminal, plain PowerShell console)
• Install source: native Windows binary via install.ps1

It seems the same fullRender(true) / viewport-tracking issue described above also affects PowerShell, not only Git Bash. Happy to provide screenshots or a screen recording if that helps.

[skywalker-35]

+1, same issue here.\n\nEnvironment:\n- OS: Windows 11 25H2\n- Terminal: PowerShell 7\n- Kimi Code: 0.29.0\n\nSymptoms:\nWhen the model finishes the thinking phase and switches to rendering the assistant text, the terminal suddenly jumps back to the very top of the entire session. I have to manually scroll back to the bottom to see the latest output. This happens frequently, especially in long conversations.\n\nConsistent with the analysis in #981, it seems that the firstChanged < prevViewportTop -> fullRender(true) branch in pi-tui 0.74.0 is being incorrectly triggered when the ThinkingComponent switches state, causing a clear-screen sequence and a re-render from the top.\n\nNote: After upgrading to 0.29.1, I haven't reproduced this yet. Not sure if it was fixed or if the trigger conditions changed, just sharing for reference.

[zbl1998-sdjn]

I ran into the "TUI jumps to the top" problem and tried to narrow down which path actually causes it on my machine. Two observations that might be useful.

1. Which path reaches fullRender(true)

I ran a normal session with PI_DEBUG_REDRAW=1. Over ~9 minutes I got 7 destructive full redraws, and none of them were firstChanged < viewportTop:

first render (prev=0, new=1, height=30)
terminal width changed (-1 -> 120) (prev=0, new=32, height=30)
terminal width changed (-1 -> 120) (prev=0, new=110, height=30)
terminal width changed (-1 -> 120) (prev=0, new=110, height=30)
terminal width changed (-1 -> 120) (prev=0, new=178, height=30)
terminal width changed (-1 -> 120) (prev=0, new=233, height=30)
terminal width changed (-1 -> 120) (prev=0, new=233, height=30)

I never resized the window. The -1 is the sentinel from requestRender(force) in packages/pi-tui/src/tui.ts (the comment there says -1 triggers widthChanged, forcing a full clear, so that part is working as designed). kimi-code calls requestRender(true) in a number of ordinary places: closing the autocomplete menu, opening/closing the approval preview, Ctrl+O, panel open/close, theme switch. #2296 looks like the same path.

So at least on my machine, the analysis in this issue and the open PRs around the firstChanged < prevViewportTop branch may be looking at a different path from the one that actually fires. The log line also reads "terminal width changed" for these, which is easy to misread as a real resize.

2. Which part of the redraw causes the jump

I replayed the exact byte sequence fullRender(true) emits (ESC[?2026h + ESC[2J ESC[H ESC[3J + rewrite of the whole buffer + ESC[?2026l) from a small node script, scrolled up a few screens before it fired, and compared variants:

• ESC[3J alone, no rewrite afterwards: view jumps to the bottom — harmless
• the full sequence with ESC[3J: view jumps to the top — reproduces the bug
• the same sequence without ESC[3J: view stays put — but the old content remains in scrollback, so each redraw appends a duplicate copy of the buffer

So on this terminal it's specifically the combination "erase scrollback + rewrite the whole buffer" that yanks the view, and dropping ESC[3J just trades the jump for duplicated scrollback. I understand that's the trade-off space #1367 already dealt with, so I'm not suggesting a direction — just reporting what each variant does.

Environment: kimi-code 0.29.1, Windows 10, Windows Terminal 1.24.11911.0. This is one machine, so I'd be curious whether others see the same split in their PI_DEBUG_REDRAW logs (~/.pi/agent/pi-debug.log).