Terminal Compatibility 专题¶

重要性：⭐⭐（终端兼容——iTerm2 / Terminal.app / Windows Terminal / tmux / etc.） 真实位置：src/ink/ + src/keybindings/ + src/utils/platform.ts + src/utils/parse-keypress.ts 角色：在多种终端中工作正常关联：topics/i18n-strategy.md、topics/abi-compatibility.md

1. Terminal 兼容性¶

Claude Code 是 CLI —— 必须在多种终端中工作： - macOS: Terminal.app / iTerm2 / Alacritty / WezTerm - Linux: gnome-terminal / konsole / xterm / alacritty - Windows: Windows Terminal / cmd / PowerShell - 远程: ssh + tmux / screen

挑战：每个终端行为略不同。

2. 5 大兼容维度¶

┌────────────────────────────────────┐
│  1. ANSI 转义序列（颜色 / 光标）  │
│  2. 鼠标 / 键盘事件                │
│  3. AlternateScreen               │
│  4. Unicode / CJK 字符宽度        │
│  5. Resize / SIGWINCH            │
└────────────────────────────────────┘

5 维。

3. ANSI 转义序列¶

3.1 chalk 处理¶

import chalk from 'chalk'
chalk.yellow('text')  // \x1b[33m...\x1b[39m

chalk 库 —— 跨终端兼容。

3.2 ANSI 检测¶

// chalk 自动检测颜色支持
chalk.level  // 0-3

3 级颜色： - 0: 无色 - 1: 16 色 - 2: 256 色 - 3: 16M 色

3.3 NO_COLOR 支持¶

NO_COLOR=1 claude

禁用颜色 —— 可访问性。

4. 鼠标 / 键盘事件¶

4.1 parse-keypress¶

// utils/parse-keypress.ts
function parseKeypress(buffer: Buffer): Keypress | null

按键解析 —— stdin raw mode。

4.2 鼠标支持¶

// ink/ink.tsx
<AlternateScreen mouseTracking={isMouseTrackingEnabled()}>

鼠标事件 —— 实验性。

4.3 键盘 modifier¶

Ctrl
Alt / Meta
Shift
Super (Cmd / Win)

4 modifier。

4.4 特殊键¶

Arrow keys (←→↑↓)
Home / End / PageUp / PageDown
Insert / Delete
F1-F12
Esc / Enter / Tab / Backspace

20+ 特殊键。

5. AlternateScreen¶

5.1 是什么¶

AlternateScreen = 终端的"备用屏幕 buffer" - 切换时不留痕迹 - 类似 vim / less 的全屏体验

5.2 实现¶

<AlternateScreen mouseTracking={isMouseTrackingEnabled()}>
  {mainReturn}
</AlternateScreen>

Ink 组件 —— 自动管理。

5.3 终端要求¶

支持 xterm 控制序列
现代终端基本都支持
推测兼容性测试：iTerm2 ✅ / Terminal.app ✅ / Windows Terminal ✅

6. 字符宽度¶

6.1 CJK¶

// CJK 字符 = 2 终端宽度

CJK 2 倍。

6.2 emoji¶

// emoji 1-2 宽度

emoji 兼容。

6.3 组合字符¶

// combining chars 0 宽度（位于前字符）

combining。

6.4 ANSI escape¶

// \x1b[... 不占宽度

ANSI 透明。

6.5 计算¶

function measureText(text: string): number {
  // 字符宽度计算
}

统一 measure。

7. Resize / SIGWINCH¶

7.1 监听 resize¶

process.on('SIGWINCH', () => {
  // terminal resized
})

SIGWINCH —— 终端尺寸变化。

7.2 useTerminalSize¶

// hooks/useTerminalSize.ts
const { columns, rows } = useTerminalSize()

响应式。

7.3 重新布局¶

// resize 后重新计算 Yoga layout

重新布局。

8. tmux / screen 兼容¶

8.1 tmux 检测¶

// 推测
if (process.env.TMUX) {
  // 在 tmux 中
}

TMUX env 检测。

8.2 颜色降级¶

// tmux 可能 256 色
chalk.level = 2

降级。

8.3 Alt screen 嵌套¶

// tmux 已经有 alt screen
// Claude Code 进 alt screen 会嵌套

注意。

9. 终端类型¶

9.1 推测支持¶

终端	支持	备注
iTerm2 (mac)	✅	主要测试
Terminal.app (mac)	✅	内置
Alacritty	✅	GPU 加速
WezTerm	✅	Rust
Windows Terminal	✅	现代
gnome-terminal	✅	Linux
konsole	✅	KDE
xterm	✅	经典
tmux	✅	嵌套
screen	✅	旧

9+ 终端。

9.2 推测部分支持¶

cmd.exe（Windows 旧）—— 可能有限
PowerShell ISE —— 不支持（推测）
mintty (Cygwin) —— 推测部分

10. Ink 抽象层¶

10.1 Ink 处理差异¶

// ink/ink.tsx
// 自动处理大多数兼容

Ink 抽象 —— 终端差异隐藏。

10.2 探测¶

// chalk / supports-color 检测能力

能力探测。

10.3 降级¶

// 不支持的功能降级

优雅降级。

11. 字符编码¶

11.1 UTF-8 默认¶

$ echo $LANG
en_US.UTF-8

UTF-8 默认。

11.2 旧编码兼容¶

# 推测：项目不支持非 UTF-8
# LANG=en_US.ISO-8859-1

推测不支持。

12. 终端大小¶

12.1 process.stdout.columns¶

process.stdout.columns  // 列数
process.stdout.rows     // 行数

Node API。

12.2 TTY 检测¶

process.stdout.isTTY  // 是否 TTY

isTTY —— 非 TTY 时降级。

12.3 最小尺寸¶

if (columns < 80) {
  // 警告
}

最小尺寸 检测。

13. 5 类 Terminal 行为差异¶

维度	差异
颜色	8/16/256/16M 色
鼠标	支持 / 不支持
Alt screen	支持 / 不支持
字符宽度	½ 宽度
Resize	SIGWINCH / Win API

5 维差异。

14. 关键设计模式¶

14.1 Ink 抽象¶

屏蔽差异。

14.2 chalk 颜色检测¶

自动降级。

14.3 NO_COLOR 支持¶

可访问性。

14.4 SIGWINCH 监听¶

响应 resize。

14.5 AlternateScreen¶

干净切换。

14.6 isTTY 检查¶

非 TTY 降级。

14.7 字符宽度计算¶

CJK 2 倍。

15. 关键洞察¶

15.1 9+ 终端支持¶

跨平台。

15.2 Ink 抽象¶

屏蔽差异。

15.3 chalk 颜色检测¶

自动降级。

15.4 NO_COLOR 支持¶

可访问性。

15.5 SIGWINCH 监听¶

响应 resize。

15.6 AlternateScreen¶

干净切换。

15.7 CJK 2 倍宽度¶

字符计算。

15.8 isTTY 降级¶

非 TTY 处理。

15.9 5 维差异¶

颜色 / 鼠标 / Alt screen / 字符宽度 / Resize。

15.10 tmux 兼容¶

嵌套 alt screen 注意。

16. 改进方向¶

16.1 终端能力测试¶

// 启动时测试终端能力

能力测试。

16.2 配置化¶

// settings.json 设 terminal 类型

用户配置。

16.3 警告 / 降级¶

// 老终端警告

警告。

16.4 远程 / SSH 优化¶

// 远程延迟补偿

远程优化。

17. 阅读建议¶

看 ink/ink.tsx —— 入口
看 utils/parse-keypress.ts —— 按键解析
看 hooks/useTerminalSize.ts —— 尺寸
看 utils/platform.ts —— 平台检测

18. 与其他专题的关系¶

文件	关系
`i18n-strategy.md`	locale
`abi-compatibility.md`	跨平台
`ink-react-reconciler.md`	Ink 渲染