[TUI] IDE 集成终端兼容矩阵：稳定输入光标与布局

[v833]

标签建议：area/tui, area/dx, priority/P1, type/feature

背景

当前能力：

• [TUI] 修复 VSCode 终端输入光标错位和左右键闪烁 #43 已先落地一版自动 cursor mode。
• VSCode、Cursor、Windsurf、Trae、JetBrains/IntelliJ IDEA 等 IDE 集成终端默认使用 inline 输入光标，避免 ANSI 光标同步在 Windows / ConPTY / IDE terminal 下出现错位、闪烁和抖动。
• Q_CODE_TUI_CURSOR=auto|ansi|inline|off 已作为排障开关存在。

痛点：

• 当前修复主要围绕已发现的 VSCode/IDE 集成终端问题，还缺一套持续维护的终端兼容矩阵。
• Windows ConPTY、VSCode xterm.js、JetBrains JediTerm、Cursor/Windsurf/Trae terminal 的软换行、CJK/emoji 宽度、真实光标和 ANSI cursor show/hide 行为都可能不同。
• 如果只靠产品名判断，很容易新增 IDE 或终端后再次出现光标错位、左右键闪烁、换行抖动或中文/emoji 宽度漂移。

需要补齐：

• 面向主流 IDE 和普通终端的 TUI 输入兼容矩阵。
• 稳定的 feature detection / 环境检测策略，而不是零散产品名特判。
• 输入渲染、光标模式和布局算法的回归测试与手工 dogfood 清单。

目标

完善 IDE 集成终端 TUI 光标与布局兼容矩阵：让主流 IDE 集成终端默认使用稳定输入体验，普通终端保留现有能力，并通过 Q_CODE_TUI_CURSOR=auto|ansi|inline|off 提供可解释、可测试、可排障的光标模式策略。

用户故事

• 作为 Windows + VSCode/Cursor/Windsurf/Trae 用户，我希望默认启动 q-code 后输入长 prompt 不出现光标错位、闪烁或抖动，以便不用了解 TUI 内部实现也能稳定使用。
• 作为 JetBrains / IntelliJ IDEA / Gateway 用户，我希望 IDE terminal 中中文、emoji、多行输入和左右键移动稳定，以便不必切到外部终端。
• 作为普通 Windows Terminal / macOS Terminal / iTerm2 用户，我希望非 IDE 终端不因为 IDE 兼容策略而退化，以便继续使用已有 ANSI 光标体验。
• 作为维护者，我希望每次改 TUI 输入布局时有兼容矩阵和回归测试，以便避免修一个终端坏另一个终端。
• 作为排障用户，我希望能通过 Q_CODE_TUI_CURSOR 强制切换模式，以便快速确认问题来自 ANSI 光标同步还是输入布局本身。

详细需求

1. 终端环境检测矩阵

• 建立并文档化主流终端环境识别字段：TERM_PROGRAM、TERM_PROGRAM_VERSION、VSCODE_INJECTION、WT_SESSION、ConEmuANSI、JetBrains 相关环境变量、CI/非 TTY 等。
• 覆盖以下环境：
  • VSCode integrated terminal。
  • Cursor integrated terminal。
  • Windsurf integrated terminal。
  • Trae integrated terminal。
  • JetBrains / IntelliJ IDEA / Gateway terminal。
  • Windows Terminal + PowerShell 7 / PowerShell 5.1。
  • Git Bash、WSL、macOS Terminal、iTerm2。
• 检测策略优先判断终端能力和已知风险组合，避免仅依赖单个产品名。

2. Cursor mode 策略

• 保留 Q_CODE_TUI_CURSOR=auto|ansi|inline|off。
• auto 下：已知 IDE 集成终端默认 inline，普通兼容终端可继续 ansi。
• ansi 强制使用真实 ANSI 光标同步，用于回归和对比。
• inline 强制使用文本渲染光标，减少真实光标移动依赖。
• off 隐藏输入光标，用于极端终端兼容兜底。
• 启动或 debug 输出中应能解释当前选择的 cursor mode 和原因。

3. 输入布局稳定性

• 覆盖输入文本、真实光标、软换行和 Unicode width 的一致性。
• 重点场景：中文、emoji、组合字素、长路径、@file mention、显式换行、多行输入、终端窄宽度。
• 左右键、Home/End、历史搜索、Esc 清空/恢复等操作不应造成明显闪烁或布局跳动。
• IDE 集成终端默认路径应尽量减少 save/restore cursor、show/hide cursor 和 setTimeout(..., 0/40) 追帧补偿。

4. 测试覆盖

• 抽出可测试的终端检测和 cursor mode 选择纯函数。
• 为不同环境变量组合建立 fixture，验证 auto 策略输出。
• 为输入布局和 cursor position 增加纯函数测试：ASCII wrap、CJK 宽字符、emoji / grapheme、显式换行、窄终端。
• 对 inline / ansi / off 模式至少覆盖渲染摘要或状态选择测试。

5. Dogfood / 手工验收清单

• 形成可重复手工验收 checklist，至少覆盖：
  • Windows + VSCode integrated terminal。
  • Windows + Cursor terminal。
  • Windows + Windsurf terminal。
  • Windows + Trae terminal。
  • Windows + IntelliJ IDEA terminal。
  • 普通 Windows Terminal + PowerShell 7。
  • 普通 Windows Terminal + Windows PowerShell 5.1。
• 每个环境记录：默认 cursor mode、输入稳定性、中文/emoji、多行、左右键、resize、Q_CODE_TUI_CURSOR 强制模式表现。

6. 文档与排障

• README 增加 TUI cursor mode 的 auto 策略和排障开关说明。
• 若新增环境变量或协作约定，同步 AGENTS。
• 文档明确：IDE terminal 默认 inline 是稳定性优先；用户仍可通过 ansi 强制旧模式对比。

输出样例

Debug 或诊断输出示例：

TUI cursor mode: inline
reason: detected VSCode-compatible integrated terminal on Windows/ConPTY
override: set Q_CODE_TUI_CURSOR=ansi|inline|off

兼容矩阵示例：

Environment                         auto mode   status
Windows + VSCode integrated          inline      pass
Windows + Cursor integrated          inline      pass
Windows Terminal + PowerShell 7      ansi        pass
JetBrains Gateway terminal           inline      needs dogfood

验收标准

• Q_CODE_TUI_CURSOR=auto|ansi|inline|off 四种模式行为清晰且可测试。
• auto 下 VSCode、Cursor、Windsurf、Trae、JetBrains/IntelliJ IDEA/Gateway 等 IDE 集成终端默认选择 inline。
• 普通 Windows Terminal、Git Bash、WSL、macOS Terminal、iTerm2 不因 IDE 策略默认退化到 inline，除非检测到已知风险组合。
• 默认配置下，主流 IDE 集成终端输入时无明显光标错位、闪烁、抖动或换行跳动。
• 中文、emoji、组合字素、长行 wrap、多行输入、@file mention、左右键、Home/End、历史搜索、Esc 清空/恢复均稳定。
• 终端 resize 后输入布局和 cursor mode 不出现明显漂移。
• Q_CODE_TUI_CURSOR=ansi 可强制回旧 ANSI 光标同步；inline 可强制文本渲染光标；off 可隐藏光标。
• README 说明 auto 策略、环境检测、排障开关和手工 dogfood 清单。
• 单元测试覆盖终端检测矩阵、cursor mode 选择和输入布局关键边界。

测试方案

• tests/unit/terminal.test.ts：补充 cursor mode 选择、输入布局、soft wrap、Unicode width 和 resize 相关测试。
• 新增或扩展终端环境检测测试：用环境变量 fixture 覆盖 VSCode、Cursor、Windsurf、Trae、JetBrains、Windows Terminal、WSL、macOS Terminal、iTerm2。
• 如拆出 terminal/cursor-mode.ts 或相邻纯函数，新增对应单测覆盖 auto|ansi|inline|off。
• 手工验证：按 dogfood checklist 在至少 Windows + VSCode integrated terminal 和普通 Windows Terminal + PowerShell 7 中验证；其余 IDE terminal 可作为后续矩阵逐步补齐。
• 提交前至少运行：
  • pnpm typecheck
  • pnpm test:unit
  • 如修改 TUI 输入组件，重点跑 vitest run tests/unit/terminal.test.ts

不在本期范围

• 立即迁移到 OpenTUI、ratatui 或其他完整 TUI 框架。
• 新增完整 IME 编辑器能力。
• 重做 @file mention、历史搜索或多行输入交互设计。
• 为所有小众终端提供一等支持；本期先覆盖主流 IDE 集成终端和普通终端路径。
• Web Dashboard 或 GUI 终端设置页。

依赖 / 风险

• 依赖 [TUI] 修复 VSCode 终端输入光标错位和左右键闪烁 #43 已落地的 cursor mode 基础能力和输入光标修复。
• IDE terminal 行为会随产品版本变化，环境检测矩阵需要持续维护。
• 仅靠环境变量识别可能误判；策略应允许用户通过 Q_CODE_TUI_CURSOR 覆盖。
• Unicode width、emoji、CJK、组合字素和终端实际渲染宽度可能存在差异，需要保守测试和手工验证。
• 过度减少 ANSI 光标同步可能影响真实终端的 native cursor 体验，必须保证普通终端不回归。
• Windows ConPTY 与 IDE terminal 的 resize/软换行行为存在细微差异，可能需要多轮 dogfood。

工作量评估

• 终端检测矩阵与 cursor mode 策略整理：1 人日
• 输入布局 / cursor mode 纯函数测试：1.5 人日
• TUI 渲染路径收敛与回归修复：1.5 人日
• README / AGENTS 文档与 dogfood checklist：0.5 人日
• 多终端手工验证：1 人日
• 合计：~5.5 人日

关联

• 依赖/延续：[TUI] 修复 VSCode 终端输入光标错位和左右键闪烁 #43
• Issue 标准：[流程] 功能 Issue 标准：统一背景、需求、验收与测试格式 #34