docs(troubleshooting): add workaround for TUI flicker in web-based terminals

[LelandJin]

What this PR does

Adds a troubleshooting entry for TUI flickering/tearing in web-based terminals (for example Alibaba Cloud Workbench), documenting the confirmed cause and the verified workaround (ui.useTerminalBuffer: false, optionally ui.mouseTracking: false). Docs only — no code changes.

Why it's needed

Issue #8659 reports continuous flicker/tearing when Qwen Code runs in browser-based terminals. @doudouOUC confirmed the cause in the thread: shouldUseVirtualViewport() cannot distinguish web terminals (TERM=xterm on a TTY, no COLORTERM, no TERM_PROGRAM), so Virtualized History activates by default and its full-screen ANSI repaints overwhelm high-latency web terminals. The fix direction agreed in the thread is "docs + startup hint first, auto-detection later". This PR delivers the docs half so affected users can find the workaround today; the startup hint and auto-detection need a detection-heuristic design discussion (missing COLORTERM + TERM_PROGRAM alone false-positives on ordinary SSH xterm sessions) and are proposed as a follow-up.

Reviewer Test Plan

How to verify

Docs-only change. Confirm the new entry renders correctly in docs/users/support/troubleshooting.md (placed next to the other terminal-behavior entries: tmux trackpad, right-click/mouse tracking). The workaround itself was verified by the reporter in #8659: setting ui.useTerminalBuffer: false switches rendering to the append-only Static path and resolves the flicker in Alibaba Cloud Workbench.

Evidence (Before & After)

N/A — docs change.

Tested on

OS	Status
🍏 macOS	N/A
🪟 Windows	N/A
🐧 Linux	✅

Environment (optional)

Alibaba Cloud Workbench (browser-based terminal), TERM=xterm, no COLORTERM/TERM_PROGRAM — the environment from the original report.

Risk & Scope

• Main risk or tradeoff: none identified; documentation only, workaround wording follows the maintainer's confirmed analysis in TUI flickering / screen tearing in web-based terminals (Alibaba Cloud Workbench, xterm TERM, no COLORTERM) #8659.
• Not validated / out of scope: the startup hint and web-terminal auto-detection/fallback (needs design discussion on reliable detection signals; offered as follow-up).
• Breaking changes / migration notes: none.

Linked Issues

Part of #8659

中文说明

本 PR 的内容

为「基于 Web 的终端（如阿里云 Workbench）中 TUI 闪烁/撕裂」问题新增一条 troubleshooting 文档，记录已确认的原因和已验证的解决方案（ui.useTerminalBuffer: false，可选 ui.mouseTracking: false）。纯文档改动，无代码变更。

为什么需要

Issue #8659 报告在浏览器终端中运行时 Qwen Code 持续闪屏/撕裂。@doudouOUC 在讨论中确认了原因：shouldUseVirtualViewport() 无法识别 web 终端（TTY 上 TERM=xterm、无 COLORTERM、无 TERM_PROGRAM），导致 Virtualized History 默认启用，其全屏 ANSI 重绘超出高延迟 web 终端的处理能力。讨论中商定的修复方向是「先文档 + 启动提示，自动检测后续再做」。本 PR 先交付文档部分，让受影响用户今天就能找到解决方案；启动提示与自动检测需要先讨论检测启发式（仅凭缺少 COLORTERM + TERM_PROGRAM 会在普通 SSH xterm 会话上误报），建议作为后续 PR。

审阅者测试计划

验证方式：纯文档改动。确认 docs/users/support/troubleshooting.md 中新条目渲染正常（与 tmux 滚轮、右键/鼠标追踪等其他终端行为条目放在一起）。解决方案本身已由 #8659 报告者验证：设置 ui.useTerminalBuffer: false 后渲染切换到 append-only Static 路径，阿里云 Workbench 中闪烁消失。

前后对比：N/A — 文档改动。

测试系统：Linux ✅（macOS/Windows N/A）。

环境：阿里云 Workbench（浏览器终端），TERM=xterm，无 COLORTERM/TERM_PROGRAM —— 与原始报告一致。

风险与范围

• 主要风险/权衡：未发现；纯文档，措辞遵循 maintainer 在 TUI flickering / screen tearing in web-based terminals (Alibaba Cloud Workbench, xterm TERM, no COLORTERM) #8659 中确认的分析。
• 未验证/超出范围：启动提示与 web 终端自动检测回退（需先讨论可靠的检测信号，愿作为后续 PR 跟进）。
• 破坏性变更/迁移说明：无。

关联 Issue

Part of #8659（不自动关闭，自动检测部分待后续）

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: observed, not theoretical — linked issue #8659 reports continuous flicker/tearing in Alibaba Cloud Workbench with full environment details (TERM=xterm, no COLORTERM/TERM_PROGRAM, v0.21.7), and @doudouOUC confirmed the cause in that thread: shouldUseVirtualViewport() has no web-terminal detection, so Virtualized History activates by default. I verified this against the code too (packages/cli/src/ui/utils/terminal-buffer.ts — the gate only checks TTY + non-CI + TERM != dumb + screen reader).

Direction: aligned — the maintainer's comment in #8659 explicitly sets the fix direction as "docs + startup hint first, auto-detection later", and this PR ships exactly the docs half. Deferring auto-detection to a follow-up is the right call: missing COLORTERM/TERM_PROGRAM alone would false-positive on ordinary SSH xterm sessions.

Size: not applicable — docs-only, 1 file, +15/−0, no core paths.

Approach: the scope is exactly right. One troubleshooting entry placed next to the existing terminal-behavior entries (tmux trackpad, right-click/mouse tracking), no unrelated changes. The entry matches the maintainer's confirmed analysis: ui.useTerminalBuffer: false is the load-bearing setting, ui.mouseTracking: false is correctly marked optional, and the note that ui.renderMode is unrelated to flicker matches the thread. I also confirmed the settings schema defaults ui.useTerminalBuffer to true, so the "on by default" claim in the entry holds.

Risk: no elevated risk signals (docs path only, no high-risk files touched).

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已观测到的真实问题，非理论推测——关联 issue #8659 报告了阿里云 Workbench 中的持续闪烁/撕裂，附完整环境信息（TERM=xterm、无 COLORTERM/TERM_PROGRAM、v0.21.7）；@doudouOUC 已在该帖中确认原因。我也对照代码核实：packages/cli/src/ui/utils/terminal-buffer.ts 中的 shouldUseVirtualViewport() 只检查 TTY + 非 CI + TERM != dumb + 读屏器，确实没有 web 终端检测。

方向：对齐——maintainer 在 #8659 中明确给出的修复方向是「先文档 + 启动提示，自动检测后续再做」，本 PR 交付的正是文档部分。自动检测推迟到后续 PR 是合理的：仅凭缺少 COLORTERM/TERM_PROGRAM 会在普通 SSH xterm 会话上误报。

规模：不适用——纯文档，1 个文件，+15/−0，未触及核心路径。

方案：范围恰当。新增一条 troubleshooting 条目，紧邻现有终端行为条目（tmux 滚轮、右键/鼠标追踪），无无关改动。内容与 maintainer 确认的分析一致：ui.useTerminalBuffer: false 是关键设置，ui.mouseTracking: false 正确标注为可选，且正确注明 ui.renderMode 与闪烁无关。另已核实 settings schema 中 ui.useTerminalBuffer 默认为 true，条目中「默认启用」的说法成立。

风险：无升级风险信号（仅文档路径，未触及高风险文件）。

进入代码审查 🔍

— Qwen Code · qwen3.8-max

_{Reviewed at 8514ec670c5b72c16cf2e1d4b1dfa19dd27fb27c · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

Docs-only change, reviewed statically against current main.

Independent proposal first: for "document the confirmed web-terminal flicker workaround", I'd add one entry under "Common error messages and solutions" in docs/users/support/troubleshooting.md, next to the existing terminal-behavior entries, in the same Issue/Cause/Solution shape, naming exactly two settings — ui.useTerminalBuffer: false (load-bearing) and ui.mouseTracking: false (optional).

That is exactly what this PR does. What I verified:

• Placement & format — inserted after the right-click/mouse-tracking entry, before the IDE Companion section; bold-heading + Issue/Cause/Solution bullets match the neighboring entries.
• Technical claims — cross-checked against code: shouldUseVirtualViewport() (packages/cli/src/ui/utils/terminal-buffer.ts) only checks TTY + non-CI + TERM != dumb + screen reader, so "cannot distinguish them from ordinary terminals automatically yet" is accurate; the settings schema defaults ui.useTerminalBuffer to true, so "on by default" holds; the non-VP path is the append-only <Static> render, so "switches rendering back to append-only output" holds.
• Config example — correctly drops ui.renderMode from the reporter's original workaround config (the maintainer noted in TUI flickering / screen tearing in web-based terminals (Alibaba Cloud Workbench, xterm TERM, no COLORTERM) #8659 that it's unrelated to flicker) and carries that caveat in the Note line. The scroll-key caveat is consistent with the neighboring mouseTracking entry.
• Scope — +15/−0 in one file, zero unrelated edits.

No blockers, no convention violations. No diagram or files table — one file doesn't earn them.

Test evidence

This is an unattended CI run — triage never builds or executes PR code; the signal below is the PR's own CI read via the API.

Check	Conclusion
Qwen Code CI (pull_request suite)	⏸️ action_required — waiting on maintainer approval (first-time-contributor fork)
precheck-pr / precheck	✅ success
PR self-report label	✅ success
label	✅ success

The full Qwen Code CI suite has not executed on this commit yet: fork PRs from first-time contributors are gated behind maintainer approval, and that run is sitting at action_required. The precheck gates passed. The table above is updated in place once the suite runs.

The PR's substantive claim — that ui.useTerminalBuffer: false resolves the flicker in Alibaba Cloud Workbench — is the reporter's own verified workaround from #8659, confirmed by @doudouOUC in-thread; this PR documents it without changing any behavior, so there is no behavioral claim a sandboxed lane would settle. Not verified here: the rendered docs page (no docs-build CI signal yet) — the markdown follows the file's existing structure, so risk is negligible.

中文说明

代码审查

纯文档改动，基于当前 main 做静态审查。

先给独立方案：要「记录已确认的 web 终端闪烁解决方案」，我会在 docs/users/support/troubleshooting.md 的「Common error messages and solutions」一节、紧挨现有终端行为条目处加一条，采用相同的 Issue/Cause/Solution 结构，只写两个设置项——ui.useTerminalBuffer: false（关键项）和 ui.mouseTracking: false（可选）。

PR 的实际做法与此完全一致。核实内容：

• 位置与格式——插在右键/鼠标追踪条目之后、IDE Companion 小节之前；加粗标题 + Issue/Cause/Solution 列表与相邻条目一致。
• 技术表述——对照代码核实：shouldUseVirtualViewport()（packages/cli/src/ui/utils/terminal-buffer.ts）只检查 TTY + 非 CI + TERM != dumb + 读屏器，因此「目前无法自动区分」的表述准确；settings schema 中 ui.useTerminalBuffer 默认为 true，「默认启用」成立；非 VP 路径即 append-only 的 <Static> 渲染，「切回追加式输出」成立。
• 配置示例——正确地去掉了报告者原始配置里的 ui.renderMode（maintainer 在 TUI flickering / screen tearing in web-based terminals (Alibaba Cloud Workbench, xterm TERM, no COLORTERM) #8659 中指出它与闪烁无关），并在 Note 中说明。滚动按键的提示与相邻 mouseTracking 条目一致。
• 范围——单文件 +15/−0，无任何无关改动。

无阻塞项，无规范违规。只有一个文件，不附时序图或文件清单。

测试证据

本次为无人值守 CI 运行——triage 从不构建或执行 PR 代码；以下是通过 API 读取的 PR 自身 CI 信号。

完整的 Qwen Code CI 套件尚未在此 commit 上执行：首次贡献者的 fork PR 需要 maintainer 批准才能运行，当前状态为 action_required。precheck 各项已通过。套件运行后上表会就地更新。

PR 的实质主张——ui.useTerminalBuffer: false 能解决阿里云 Workbench 中的闪烁——来自报告者本人在 #8659 中已验证的方案，并经 @doudouOUC 在帖中确认；本 PR 只是将其写入文档，不改变任何行为，因此没有需要沙箱验证通道来证实的行为主张。此处未验证：文档页面渲染（尚无 docs 构建 CI 信号）——markdown 遵循该文件现有结构，风险可忽略。

— Qwen Code · qwen3.8-max

_{Reviewed at 8514ec670c5b72c16cf2e1d4b1dfa19dd27fb27c · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — clean docs-only change that delivers exactly what the maintainer prescribed in #8659; every technical claim in the entry checks out against the code.

Stepping back: this PR exists because a maintainer said "docs first", and it does exactly that — one accurate, correctly-placed entry, nothing more. My independent proposal and the diff converge on the same change, and I found no simpler version of it. The author also resisted the temptation to bundle the startup hint or auto-detection code; that's the right scope call, and the PR names the follow-up explicitly. The entry even improves on the original issue report by dropping the irrelevant renderMode key and noting why. In six months this will either save a Workbench user a support thread or sit harmlessly — that's what a troubleshooting doc is for.

Verdict: approve. One procedural caveat: the full CI suite has not executed on this commit yet — fork PRs from first-time contributors wait on maintainer approval, and the run is at action_required. Approval is therefore deferred until CI lands green on 8514ec670c5b72c16cf2e1d4b1dfa19dd27fb27c; no approval is posted in this run.

中文说明

置信度：5/5 —— 干净的纯文档改动，恰好交付 maintainer 在 #8659 中指定的内容；条目中的每项技术表述都已对照代码核实。

退一步看：这个 PR 源于 maintainer 的一句「先做文档」，而它做的也仅此而已——一条准确、位置恰当的条目。我的独立方案与 diff 殊途同归，也没有更简的做法。作者也没有顺手夹带启动提示或自动检测代码，范围取舍正确，且 PR 中明确指出了后续工作。条目甚至比原始 issue 报告更严谨：去掉了无关的 renderMode 键并说明了原因。半年后，它要么帮一位 Workbench 用户省下一个求助帖，要么安静地躺在那里——这正是 troubleshooting 文档的价值。

结论：批准。一个程序性说明：完整 CI 套件尚未在此 commit 上执行——首次贡献者的 fork PR 需 maintainer 批准运行，当前状态为 action_required。因此批准推迟到 CI 在 8514ec670c5b72c16cf2e1d4b1dfa19dd27fb27c 上变绿之后；本次运行不提交批准。

— Qwen Code · qwen3.8-max

_{Reviewed at 8514ec670c5b72c16cf2e1d4b1dfa19dd27fb27c · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

📄 Docs-only change — the automatic review ran at --effort medium (verified findings, no reverse audit; medium posts no inline comments). Outcome:

Review complete: pr-8867 — Comment, not posted (0 Critical, 1 Suggestion)

Reviewed head: 95d43cac4c9f54e1bf545080cfd20e0573b11af4. Full report in the workflow run. For a full high-effort review with inline comments, comment @qwen-code /review.

中文说明

📄 纯文档变更 —— 自动评审以 --effort medium 运行（发现已验证、无反向审计；medium 不发布行内评论），结果见上方引用行。评审的 head：95d43cac4c9f54e1bf545080cfd20e0573b11af4。完整报告见 workflow 运行；如需带行内评论的完整高强度（high-effort）评审，请评论 @qwen-code /review。

[doudouOUC]

Reviewed — no blockers. Suggestions are inline. 2 Suggestion-level finding(s) could not be anchored to a changed line and were dropped; nothing further to act on here.

中文说明

已审查——无阻断问题。 建议见行内评论。 2 条建议级发现无法锚定到改动行，已丢弃；此处无需进一步处理。

— deepseek-v4-flash via Qwen Code /review (v0.21.8)