Kitty 终端兼容性问题：ESC、Ctrl+D、Shift+Tab 等按键无法正常工作 (v0.5.17)

[Samuelcdf]

相关链接

1. iFlow CLI Issue 在 Kitty 终端中快捷键失效（Ctrl+C、方向键输出 escape 序列） #231: 在 Kitty 终端中快捷键失效（Ctrl+C、方向键输出 escape 序列） #231

   • 另一个用户报告的类似问题（2025年11月）

2. Kitty Keyboard Protocol 官方文档: https://sw.kovidgoyal.net/kitty/keyboard-protocol/

3. Ink Kitty Protocol Support: Support kitty keyboard protocol to enable more complex keyboard interaction vadimdemedes/ink#824

4. Crossterm Kitty Protocol Issue: Incomplete kitty progressive enhancement support and missing "base-layout-key" support crossterm-rs/crossterm#968

   • Rust 社区对 kitty protocol 的实现参考

What happened?

在kiity中運行iflow, 很多按鍵無法正常使用

What did you expect to happen?

按鍵可以正常發揮原本的功能

Client information

Details

$ iflow /about
# paste output here# iFlow CLI Kitty 终端兼容性问题分析报告

## 问题描述

在 Kitty 终端中运行 iFlow CLI (v0.5.17) 时，多个快捷键无法正常工作：
- **ESC 键**：无法中断正在进行的操作
- **Ctrl+D Ctrl+D**：无法退出程序，连续按 Ctrl+D 会输出 `0;133u` 字符串
- **Shift+Tab**：无法正常切换

在其他终端（如 Alacritty、GNOME Terminal）中，iFlow CLI 工作正常。

## 复现步骤

1. 在 Kitty 终端中运行：`iflow`
2. 尝试按 ESC 键中断操作 → 无反应
3. 连续按 Ctrl+D 两次 → 输出 `0;133u` 字符串，未退出
4. 按 Shift+Tab → 无法正常切换

## 环境信息

- **操作系统**: Linux 6.18.6-100.fc42.x86_64
- **终端**: Kitty (TERM=xterm-kitty)
- **iFlow CLI 版本**: 0.5.17
- **Node.js**: 22+
- **键盘布局**: US (xkb layout)

## 技术栈分析

iFlow CLI 的技术栈：
- **UI 框架**: Ink (React for terminal)
- **语言**: TypeScript + Node.js
- **终端输入**: Node.js stdin → Ink useInput hook

## 根本原因分析

### 1. Kitty Keyboard Protocol

Kitty 终端使用扩展的 **Keyboard Protocol** (CSI-u 格式)，提供更丰富的按键信息：

ESC [ ; ; u

例如：
- `ESC [ 0 ; 133 u` → Ctrl+D (keycode: 133, modifiers: 0)
- `ESC [ 27 ; 0 u` → ESC (keycode: 27, modifiers: 0)

### 2. 问题链条

iFlow CLI
↓ (使用)
Ink (React for terminal)
↓ (useInput hook)
Node.js stdin
↓
Kitty Terminal (发送 CSI-u 格式序列)

### 3. 具体问题

**iFlow CLI (或 Ink) 的行为：**
1. 检测到 Kitty 终端后，发送启用序列：`ESC [ > 1 u`
2. Kitty 开始发送 CSI-u 格式的按键序列
3. iFlow CLI 无法正确解析这些序列，导致原始序列直接显示在屏幕上

**证据：**
- 连续按 Ctrl+D 输出 `0;133u`，这是 CSI-u 格式的原始序列
- `133` = D 键的 keycode
- `0` = 修饰符（表示 Ctrl 键被按下）

### 4. 为什么 v0.5.17 的修复无效

Changelog 声称：
> "Improved keyboard CSI sequence handling with Kitty CSI-u protocol support, preventing unrecognized sequences from leaking into input buffer"

但实际修复可能只是：
- 过滤了"泄漏"到输入缓冲区的未识别序列
- **没有实现 CSI-u 序列的正确解析和转换为内部按键事件**

### 5. 为什么 screen 能解决问题

screen 在启动时会：
1. 重置终端状态
2. 发送禁用序列：`ESC [ > 0 u`
3. 这就主动禁用了 kitty keyboard protocol
4. iFlow CLI 接收到的是传统的按键输入，所以工作正常

### 6. Ink 对 Kitty Keyboard Protocol 的支持

**Ink issue #824**: https://github.com/vadimdemedes/ink/issues/824

- 该 issue 还在讨论中，尚未完全实现 kitty protocol 支持
- Ink 目前的 useInput hook 无法正确处理 CSI-u 格式的按键
- 这是底层库的限制，不是 iFlow CLI 独有的问题

## 临时解决方案

### 方案 1：使用 screen 包装

创建 `~/bin/iflow-kitty`：

```bash
#!/bin/bash
# Start iflow in screen for better kitty compatibility
screen -S iflow -dm iflow "$@"
screen -r iflow

运行：iflow-kitty

方案 2：直接在 screen 中运行

screen
iflow

建议的修复方案

方案 1：禁用 Kitty Keyboard Protocol（短期）

在 iFlow CLI 启动时检测到 Kitty 终端后：

1. 不要发送 ESC [ > 1 u 启用序列
2. 或者发送 ESC [ > 0 u 显式禁用
3. 这样 Kitty 会使用传统的按键编码

方案 2：实现完整的 CSI-u 解析器（长期）

参考 crossterm 的实现（https://github.com/crossterm-rs/crossterm/issues/968）：

1. 解析 CSI-u 格式序列：ESC [ <unicode_key> ':' <shifted_key> ':' <base_layout_key> ';' <modifiers> ';' <text> u
2. 转换为内部按键事件格式
3. 处理所有字段：
   • unicode_key: Unicode 字符
   • shifted_key: Shift 按下时的字符
   • base_layout_key: 物理按键（与布局无关）
   • modifiers: 修饰键标志（Ctrl, Alt, Shift）
   • text: 完整文本（用于输入）

方案 3：等待 Ink 官方支持

关注并集成 Ink issue #824 的实现。

测试建议

修复后请测试以下场景：

1. ESC 键中断操作
2. Ctrl+D Ctrl+D 退出
3. Shift+Tab 切换
4. Ctrl+C 中断
5. 方向键导航
6. 修饰键组合（Ctrl+字母、Alt+字母等）
7. 不同键盘布局（如果支持）

总结

这是一个终端输入解析问题，具体表现为：

• iFlow CLI 启用了 Kitty Keyboard Protocol
• 但无法正确解析返回的 CSI-u 格式按键序列
• 导致原始序列泄漏到输出中

根本原因可能是：

• Ink 库对 kitty protocol 的支持不完整
• iFlow CLI 在 v0.5.17 中的修复只做了部分工作

建议优先级：

1. 短期：禁用 kitty protocol（方案 1）
2. 长期：实现完整解析器或等待 Ink 支持（方案 2 或 3）