# 键绑定系统完全解析

本章解析 Claude Code 的快捷键管理系统——如何在 18 个不同 UI 上下文中实现上下文感知的键绑定分发、和弦组合键、平台适配与用户自定义热重载。

> ⚠️ **功能门控提醒**：键绑定自定义功能当前仅对 Anthropic 内部员工开放（通过 GrowthBook feature gate 控制）。外部用户始终使用默认绑定，无法自定义。本章对用户自定义、热重载、解绑等机制的分析，描述的是系统的完整设计，但请注意这些能力对绝大多数用户尚不可用。

## 概述

Claude Code 实现了一套完整的键绑定系统，支持上下文感知、和弦绑定（chord bindings）、平台适配、用户自定义和热重载。这套系统管理着从 `ctrl+c` 到 `ctrl+k ctrl+s` 等各种快捷键，在 18 个不同的 UI 上下文中精准路由用户输入。

**技术比喻（OS 视角）**：键绑定系统就像操作系统的**快捷键管理器**——Windows 的热键注册表或 macOS 的 Keyboard Shortcuts 设置面板。不同应用窗口（上下文）可以注册同一个快捷键的不同行为，系统负责根据当前焦点窗口分发键事件，并处理注册冲突。

> 💡 **通俗理解**：键绑定像餐厅的点菜快捷方式——常客说"老样子"（快捷键）直接上菜，新客翻菜单（命令面板）。而且不同座位区（上下文）有不同的快捷方式：吧台区说"来一杯"默认是啤酒（Chat 上下文的 Enter = 提交），包间里说"来一杯"默认是茶（Confirmation 上下文的 Enter = 确认）。

### 🌍 行业背景

键绑定系统是所有交互式开发工具的基础设施。各工具的实现策略差异很大：

- **VS Code**：拥有业界最成熟的键绑定架构——支持 `when` 条件表达式（如 `editorTextFocus && !editorReadonly`）、多层覆盖（默认/扩展/用户/工作区）、和弦绑定、以及完整的 GUI 键绑定编辑器。这是 Claude Code 明确参考但未完全追赶的目标。
- **Cursor / Windsurf**：作为 VS Code 的 fork，直接继承了 VS Code 的整套键绑定框架，包括 `keybindings.json` 格式和 `when` 条件系统。它们在此基础上添加 AI 专属快捷键（如 Cursor 的 `Cmd+K` 内联编辑）。
- **GitHub Copilot**：作为 VS Code 扩展运行，通过 `contributes.keybindings` 注册快捷键，受宿主编辑器的键绑定框架约束。
- **Aider**：纯终端工具，键绑定非常简单——依赖 readline 的默认绑定，不支持用户自定义或和弦组合键。
- **Codex（OpenAI）**：底层已用 Rust 重写（具体比例以官方为准），键绑定为硬编码的固定集合，无自定义能力。**OpenCode** 作为 Go+Zig 实现的 TUI 工具，通过 Tab 键切换 Build/Plan 模式，交互设计更接近传统终端应用。

Claude Code 的键绑定系统处于 Aider（极简）和 VS Code（全功能）之间的独特位置：它在终端环境中实现了和弦绑定、上下文分发、热重载等通常只有 GUI 编辑器才有的特性，同时受限于终端的修饰键识别能力。

---

## 1. 配置格式与 Schema

### 1.1 JSON Schema 定义

键绑定配置文件（`~/.claude/keybindings.json`）使用 Zod 定义严格的 schema：

```typescript
// 源码: src/keybindings/schema.ts (第177-229行)
export const KeybindingsSchema = lazySchema(() =>
  z.object({
    $schema: z.string().optional(),
    $docs: z.string().optional(),
    bindings: z.array(KeybindingBlockSchema()).describe('Array of keybinding blocks by context'),
  })
)
```

配置文件的顶层结构是一个对象，包含 `bindings` 数组。每个 block 指定一个上下文和该上下文下的绑定映射：

```json
{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": "chat:stash",
        "ctrl+k ctrl+e": "chat:externalEditor"
      }
    }
  ]
}
```

### 1.2 18 个上下文

系统定义了 18 个 UI 上下文，每个上下文代表一个可以接收键输入的界面状态：

```typescript
// 源码: src/keybindings/schema.ts (第12-32行)
export const KEYBINDING_CONTEXTS = [
  'Global',          // 全局——无论焦点在哪里都生效
  'Chat',            // 聊天输入框获焦
  'Autocomplete',    // 自动补全菜单可见
  'Confirmation',    // 确认/权限对话框
  'Help',            // 帮助覆盖层
  'Transcript',      // 查看对话记录
  'HistorySearch',   // 历史搜索 (ctrl+r)
  'Task',            // 后台任务运行中
  'ThemePicker',     // 主题选择器
  'Settings',        // 设置菜单
  'Tabs',            // Tab 导航
  'Attachments',     // 图像附件导航
  'Footer',          // 底栏指示器
  'MessageSelector', // 消息选择器（回溯）
  'DiffDialog',      // Diff 对话框
  'ModelPicker',     // 模型选择器
  'Select',          // 通用选择列表
  'Plugin',          // 插件对话框
] as const
```

### 1.3 动作枚举

系统预定义了 70+ 个合法动作标识符：

```typescript
// 源码: src/keybindings/schema.ts (第64-172行)
export const KEYBINDING_ACTIONS = [
  // App 级别
  'app:interrupt', 'app:exit', 'app:toggleTodos', 'app:toggleTranscript',
  // Chat 级别
  'chat:cancel', 'chat:submit', 'chat:newline', 'chat:undo',
  // 确认对话框
  'confirm:yes', 'confirm:no', 'confirm:toggle',
  // 更多...
  'voice:pushToTalk',
] as const
```

此外支持 `command:xxx` 格式的命令绑定，可以直接触发斜杠命令（如 `command:help`），但必须在 Chat 上下文中使用。

---

## 2. 解析器（Parser）

### 2.1 按键字符串解析

解析器将人类可读的按键字符串（如 `ctrl+shift+k`）转换为结构化的 `ParsedKeystroke` 对象：

```typescript
// 源码: src/keybindings/parser.ts (第13-75行)
export function parseKeystroke(input: string): ParsedKeystroke {
  const parts = input.split('+')
  const keystroke: ParsedKeystroke = {
    key: '', ctrl: false, alt: false, shift: false, meta: false, super: false,
  }
  for (const part of parts) {
    const lower = part.toLowerCase()
    switch (lower) {
      case 'ctrl': case 'control': keystroke.ctrl = true; break
      case 'alt': case 'opt': case 'option': keystroke.alt = true; break
      case 'shift': keystroke.shift = true; break
      case 'meta': keystroke.meta = true; break
      case 'cmd': case 'command': case 'super': case 'win': keystroke.super = true; break
      case 'esc': keystroke.key = 'escape'; break
      case 'return': keystroke.key = 'enter'; break
      case 'space': keystroke.key = ' '; break
      default: keystroke.key = lower; break
    }
  }
  return keystroke
}
```

支持丰富的修饰键别名：`ctrl`/`control`、`alt`/`opt`/`option`（`alt` 别名组）、`meta`（独立解析，不在 alt 别名组里）、`cmd`/`command`/`super`/`win`。注意：在 **parser 阶段** `alt` 和 `meta` 是两个独立的布尔位（见上面 case 分支），直到 **match 阶段** 才因终端限制合并（见 §3.2）。这确保了跨平台和不同用户习惯的兼容性。

### 2.2 和弦解析

和弦绑定（chord bindings）是由空格分隔的多个按键序列：

```typescript
// 源码: src/keybindings/parser.ts (第80-84行)
export function parseChord(input: string): Chord {
  if (input === ' ') return [parseKeystroke('space')]  // 特殊处理：空格键本身
  return input.trim().split(/\s+/).map(parseKeystroke)
}
```

`ctrl+k ctrl+s` 被解析为两个 `ParsedKeystroke` 的数组。特别注意：单独的空格字符 `' '` 被识别为空格键绑定而非分隔符——这是一个容易出错的边界情况。

### 2.3 平台感知的显示

显示时根据平台选择不同的修饰键名称：

```typescript
// 源码: src/keybindings/parser.ts (第157-176行)
export function keystrokeToDisplayString(ks, platform = 'linux'): string {
  const parts: string[] = []
  if (ks.ctrl) parts.push('ctrl')
  if (ks.alt || ks.meta) {
    parts.push(platform === 'macos' ? 'opt' : 'alt')  // macOS 用 opt
  }
  if (ks.shift) parts.push('shift')
  if (ks.super) {
    parts.push(platform === 'macos' ? 'cmd' : 'super')  // macOS 用 cmd
  }
  parts.push(displayKey)
  return parts.join('+')
}
```

alt 和 meta 在显示层面被合并：macOS 显示为 `opt`，其他平台显示为 `alt`。这反映了终端限制——大多数终端无法区分 Alt 和 Meta。

---

## 3. 匹配引擎（Match）

### 3.1 按键名提取

从 Ink 框架的原始 Key 对象中提取规范化的键名：

```typescript
// 源码: src/keybindings/match.ts (第29-47行)
export function getKeyName(input: string, key: Key): string | null {
  if (key.escape) return 'escape'
  if (key.return) return 'enter'
  if (key.tab) return 'tab'
  if (key.backspace) return 'backspace'
  if (key.upArrow) return 'up'
  if (key.downArrow) return 'down'
  if (key.wheelUp) return 'wheelup'     // 鼠标滚轮支持
  if (key.wheelDown) return 'wheeldown'
  if (input.length === 1) return input.toLowerCase()
  return null
}
```

注意包含了 `wheelup`/`wheeldown`——Claude Code 在支持鼠标协议的终端中可以响应滚轮事件。

### 3.2 修饰键匹配

修饰键匹配中有一个重要的 quirk 处理：

```typescript
// 源码: src/keybindings/match.ts (第60-79行)
function modifiersMatch(inkMods: InkModifiers, target: ParsedKeystroke): boolean {
  if (inkMods.ctrl !== target.ctrl) return false
  if (inkMods.shift !== target.shift) return false
  // Alt 和 meta 在终端中不可区分，合并为一个逻辑修饰键
  const targetNeedsMeta = target.alt || target.meta
  if (inkMods.meta !== targetNeedsMeta) return false
  // Super (cmd/win) 是独立的——只有 kitty 键盘协议才支持
  if (inkMods.super !== target.super) return false
  return true
}
```

三个关键设计决策：
- **alt/meta 合并**：终端限制使两者不可区分，绑定中的 `alt` 和 `meta` 效果相同
- **super 独立**：cmd/win 键只在支持 kitty 键盘协议的终端中可用（kitty、WezTerm、ghostty、iTerm2）
- **Escape quirk**：Ink 在按 Escape 时设置 `key.meta=true`（终端遗留行为），匹配 Escape 键时需要忽略 meta 标志

```typescript
// 源码: src/keybindings/match.ts (第96-105行)
if (key.escape) {
  return modifiersMatch({ ...inkMods, meta: false }, target)  // Escape 忽略 meta
}
```

---

## 4. 和弦解析器（Chord Resolver）

### 4.1 和弦状态机

和弦绑定（如 `ctrl+k ctrl+s`）需要跨按键的状态追踪。`resolveKeyWithChordState` 实现了一个五步决策流程（与下面代码注释 1–5 一一对应，可粗略归并为"取消 / 进行中 / 匹配"三阶段）：

```typescript
// 源码: src/keybindings/resolver.ts (第166-244行)
export function resolveKeyWithChordState(
  input, key, activeContexts, bindings, pending
): ChordResolveResult {
  // 1. Escape 取消当前和弦
  if (key.escape && pending !== null) {
    return { type: 'chord_cancelled' }
  }

  // 2. 构建当前按键序列（已有 pending + 新按键）
  const testChord = pending ? [...pending, currentKeystroke] : [currentKeystroke]

  // 3. 检查是否可能是更长和弦的前缀
  // 如果是，进入 chord_started 状态等待后续按键
  if (hasLongerChords) {
    return { type: 'chord_started', pending: testChord }
  }

  // 4. 检查精确匹配
  if (exactMatch) {
    return { type: 'match', action: exactMatch.action }
  }

  // 5. 无匹配且不是任何和弦的前缀
  if (pending !== null) {
    return { type: 'chord_cancelled' }
  }
  return { type: 'none' }
}
```

### 4.2 和弦优先级

当一个按键既是单键绑定又是和弦前缀时，和弦优先：

```
ctrl+k → 可能是 "ctrl+k ctrl+s" 的前缀
ctrl+k → 也可能是单独绑定

→ 优先进入 chord_started，等待后续输入
```

但有一个值得注意的例外——null 覆盖（unbind）的处理：

```typescript
// 源码: src/keybindings/resolver.ts (第199-215行)
const chordWinners = new Map<string, string | null>()
for (const binding of contextBindings) {
  if (binding.chord.length > testChord.length && chordPrefixMatches(testChord, binding)) {
    chordWinners.set(chordToString(binding.chord), binding.action)
  }
}
let hasLongerChords = false
for (const action of chordWinners.values()) {
  if (action !== null) {
    hasLongerChords = true  // 只有非 null 的绑定才算"更长和弦"
    break
  }
}
```

如果用户通过设置 `null` 解绑了 `ctrl+x ctrl+k`，那么 `ctrl+x` 不再进入和弦等待——`ctrl+x` 上的单键绑定可以正常触发。

> 📚 **课程关联**：和弦解析器的状态转换（idle → chord_started → match）看起来像《编译原理》中的确定性有限自动机（DFA），但严格来说不是——DFA 的转移函数是 `δ(state, input) → next_state`，而 `resolveKeyWithChordState` 的转移还取决于 `activeContexts` 参数（当前活跃的上下文列表），即 `δ(state, input, context) → next_state`。这更接近于一个**带守卫条件的参数化状态机**：同一个按键在不同的上下文集合下可能产生不同的转移路径。和弦绑定的"前缀匹配 vs 精确匹配"决策，等价于词法分析中**最长匹配（maximal munch）**规则的变体——系统优先尝试匹配更长的和弦序列。

### 4.3 按键比较

和弦匹配中的按键比较同样合并 alt/meta：

```typescript
// 源码: src/keybindings/resolver.ts (第107-118行)
export function keystrokesEqual(a: ParsedKeystroke, b: ParsedKeystroke): boolean {
  return (
    a.key === b.key &&
    a.ctrl === b.ctrl &&
    a.shift === b.shift &&
    (a.alt || a.meta) === (b.alt || b.meta) &&  // alt+k 和 meta+k 视为相同
    a.super === b.super
  )
}
```

---

## 5. 默认绑定

### 5.1 平台适配

默认绑定根据平台动态调整：

```typescript
// 源码: src/keybindings/defaultBindings.ts (第15-31行)
// 图像粘贴快捷键
const IMAGE_PASTE_KEY = getPlatform() === 'windows' ? 'alt+v' : 'ctrl+v'

// VT 模式检测
const SUPPORTS_TERMINAL_VT_MODE =
  getPlatform() !== 'windows' ||
  (isRunningWithBun()
    ? satisfies(process.versions.bun, '>=1.2.23')
    : satisfies(process.versions.node, '>=22.17.0 <23.0.0 || >=24.2.0'))

// 模式切换键
const MODE_CYCLE_KEY = SUPPORTS_TERMINAL_VT_MODE ? 'shift+tab' : 'meta+m'
```

Windows 上 `ctrl+v` 是系统粘贴，所以图像粘贴改用 `alt+v`。`shift+tab` 在没有 VT 模式支持的 Windows Terminal 上不可靠，回退为 `meta+m`。VT 模式的支持版本号精确到 Bun 1.2.23 和 Node 22.17.0——这种精度来自对上游 PR 的追踪。

### 5.2 Global 上下文

全局绑定是任何时候都生效的：

```typescript
// 源码: src/keybindings/defaultBindings.ts (第33-62行)
{
  context: 'Global',
  bindings: {
    'ctrl+c': 'app:interrupt',    // 不可重绑定
    'ctrl+d': 'app:exit',         // 不可重绑定
    'ctrl+l': 'app:redraw',
    'ctrl+t': 'app:toggleTodos',
    'ctrl+o': 'app:toggleTranscript',
    'ctrl+r': 'history:search',
  },
},
```

源码注释明确指出 `ctrl+c` 和 `ctrl+d` 虽然在这里定义，但**不能被用户重绑定**——reservedShortcuts.ts 中的验证会阻止。

### 5.3 Chat 上下文

聊天输入的绑定最为丰富：

```typescript
// 源码: src/keybindings/defaultBindings.ts (第64-98行)
{
  context: 'Chat',
  bindings: {
    escape: 'chat:cancel',
    'ctrl+x ctrl+k': 'chat:killAgents',  // 和弦绑定——避免占用 readline 编辑键
    [MODE_CYCLE_KEY]: 'chat:cycleMode',
    enter: 'chat:submit',
    'ctrl+_': 'chat:undo',              // 旧终端
    'ctrl+shift+-': 'chat:undo',        // kitty 协议终端
    'ctrl+x ctrl+e': 'chat:externalEditor',  // readline 原生编辑绑定
    'ctrl+g': 'chat:externalEditor',
    'ctrl+s': 'chat:stash',
  },
},
```

注意 `chat:undo` 有两个绑定：`ctrl+_` 用于传统终端（发送 `\x1f` 控制字符），`ctrl+shift+-` 用于 kitty 键盘协议终端（发送带修饰键的物理按键）。两个绑定针对同一动作，确保跨终端兼容。

`ctrl+x ctrl+k` 选择和弦而非单键是因为——`ctrl+a`、`ctrl+b`、`ctrl+e`、`ctrl+f` 等是 readline 编辑键（行首、前一字符、行尾、后一字符），不能被占用。使用 `ctrl+x` 作为和弦前缀避免了与 readline 的冲突。

### 5.4 功能门控

部分绑定受 feature flag 控制：

```typescript
// 源码: src/keybindings/defaultBindings.ts (第45-59行)
...(feature('KAIROS') || feature('KAIROS_BRIEF')
  ? { 'ctrl+shift+b': 'app:toggleBrief' as const }
  : {}),
...(feature('VOICE_MODE') ? { space: 'voice:pushToTalk' } : {}),
...(feature('TERMINAL_PANEL') ? { 'meta+j': 'app:toggleTerminal' } : {}),
```

使用 spread + 条件对象模式实现运行时的条件绑定注入——`feature('KAIROS')` 等调用在运行时查询 GrowthBook feature gate，而非编译期常量。绑定集合在每次调用 `getDefaultParsedBindings()` 时根据当前 feature flag 状态动态构建。

---

## 6. 用户自定义与加载

### 6.1 加载流程

用户绑定追加在默认绑定之后，"后来者优先"（last wins）：

```typescript
// 源码: src/keybindings/loadUserBindings.ts (第133-216行)
export async function loadKeybindings(): Promise<KeybindingsLoadResult> {
  const defaultBindings = getDefaultParsedBindings()

  // 非 Anthropic 员工跳过用户配置
  if (!isKeybindingCustomizationEnabled()) {
    return { bindings: defaultBindings, warnings: [] }
  }

  const content = await readFile(userPath, 'utf-8')
  const parsed = jsonParse(content)

  // 从 { "bindings": [...] } 格式提取
  let userBlocks = (parsed as { bindings: unknown }).bindings

  const userParsed = parseBindings(userBlocks)
  // 用户绑定在后面，覆盖默认绑定
  const mergedBindings = [...defaultBindings, ...userParsed]

  // 验证 + 重复键检测
  const duplicateKeyWarnings = checkDuplicateKeysInJson(content)
  const warnings = [...duplicateKeyWarnings, ...validateBindings(userBlocks, mergedBindings)]

  return { bindings: mergedBindings, warnings }
}
```

"后来者优先"的实现方式非常简单——数组拼接，解析时取最后一个匹配。这比维护覆盖映射表简洁得多，与 CSS 层叠规则的"后声明优先"机制同源。

### 6.2 热重载

配置文件使用 chokidar 监听变化，支持无需重启的实时更新：

```typescript
// 源码: src/keybindings/loadUserBindings.ts (第353-404行)
export async function initializeKeybindingWatcher(): Promise<void> {
  watcher = chokidar.watch(userPath, {
    persistent: true,
    ignoreInitial: true,
    awaitWriteFinish: {
      stabilityThreshold: FILE_STABILITY_THRESHOLD_MS,  // 500ms
      pollInterval: FILE_STABILITY_POLL_INTERVAL_MS,     // 200ms
    },
    ignorePermissionErrors: true,
    usePolling: false,
    atomic: true,
  })

  watcher.on('add', handleChange)
  watcher.on('change', handleChange)
  watcher.on('unlink', handleDelete)  // 删除文件 → 重置为默认
}
```

`awaitWriteFinish` 配置确保文件写入完成后再触发重新加载——编辑器可能分多次 fsync 写入文件，500ms 的稳定阈值避免了读取到半写文件。

> 📚 **课程关联**：`awaitWriteFinish` 的稳定阈值机制是《操作系统》中**去抖动（debouncing）**的典型应用——与硬件中断处理中的按键去抖完全同构。编辑器保存文件时可能触发多次 `write` 系统调用（truncate → write → fsync），文件监听器需要等待写入序列稳定后再响应，否则会读到不完整的文件内容。这也涉及 OS 课程中文件系统的**原子性写入**问题——`rename` 是原子的，但 `write` 不是。

### 6.3 解绑机制

用户可以通过设置 `null` 解绑默认快捷键：

```typescript
// 在 schema 中的定义
z.union([
  z.enum(KEYBINDING_ACTIONS),
  z.string().regex(/^command:[a-zA-Z0-9:\-_]+$/),
  z.null().describe('Set to null to unbind a default shortcut'),
])
```

解析时 `null` action 的绑定也参与匹配——如果匹配到 `null`，返回 `{ type: 'unbound' }` 而非 `{ type: 'none' }`，让上层知道这个键被显式解绑了（而非没有绑定）。

---

## 7. 验证系统

### 7.1 保留快捷键

某些快捷键被标记为不可重绑定：

```typescript
// 源码: src/keybindings/reservedShortcuts.ts (第16-33行)
export const NON_REBINDABLE: ReservedShortcut[] = [
  { key: 'ctrl+c', reason: '用于中断/退出 (硬编码)', severity: 'error' },
  { key: 'ctrl+d', reason: '用于退出 (硬编码)', severity: 'error' },
  { key: 'ctrl+m', reason: '在终端中与 Enter 相同 (均发送 CR)', severity: 'error' },
]

export const TERMINAL_RESERVED: ReservedShortcut[] = [
  { key: 'ctrl+z', reason: 'Unix 进程挂起 (SIGTSTP)', severity: 'warning' },
  { key: 'ctrl+\\', reason: '终端退出信号 (SIGQUIT)', severity: 'error' },
]

export const MACOS_RESERVED: ReservedShortcut[] = [
  { key: 'cmd+c', reason: 'macOS 系统复制', severity: 'error' },
  { key: 'cmd+v', reason: 'macOS 系统粘贴', severity: 'error' },
  // ...
]
```

注意 `ctrl+m` 的保留原因：在终端中 `Ctrl+M` 和 `Enter` 都发送 CR（回车），它们在终端层面不可区分。

### 7.2 JSON 重复键检测

JSON 规范允许重复键（后者覆盖前者），但这通常是用户错误。验证器通过正则匹配原始 JSON 字符串检测：

```typescript
// 源码: src/keybindings/validate.ts (第258-307行)
export function checkDuplicateKeysInJson(jsonString: string): KeybindingWarning[] {
  const bindingsBlockPattern = /"bindings"\s*:\s*\{([^{}]*(?:\{[^{}]*\}[^{}]*)*)\}/g
  // ... 在每个 bindings 块内查找重复键
  const keyPattern = /"([^"]+)"\s*:/g
  const keysByName = new Map<string, number>()
  // ...
}
```

这种检测必须在 `JSON.parse` 之前进行，因为解析后重复键已经被静默丢弃了。

### 7.3 按键字符串规范化

比较按键绑定时需要规范化，避免 `ctrl+shift+k` 和 `shift+ctrl+k` 被视为不同：

```typescript
// 源码: src/keybindings/reservedShortcuts.ts (第91-127行)
export function normalizeKeyForComparison(key: string): string {
  return key.trim().split(/\s+/).map(normalizeStep).join(' ')
}

function normalizeStep(step: string): string {
  const parts = step.split('+')
  const modifiers: string[] = []
  let mainKey = ''
  for (const part of parts) {
    // 规范化修饰键名: control→ctrl, option/opt→alt, command/cmd→cmd
    // ...
  }
  modifiers.sort()  // 修饰键排序
  return [...modifiers, mainKey].join('+')
}
```

修饰键名称规范化 + 排序，确保 `ctrl+shift+k` 和 `shift+control+k` 被视为等价。

### 7.4 语音绑定警告

对 `voice:pushToTalk` 有特殊验证——裸字母键绑定会导致问题：

```typescript
// 源码: src/keybindings/validate.ts (第220-243行)
if (action === 'voice:pushToTalk') {
  const ks = parseChord(key)[0]
  if (ks && !ks.ctrl && !ks.alt && !ks.shift && !ks.meta && !ks.super
      && /^[a-z]$/.test(ks.key)) {
    warnings.push({
      severity: 'warning',
      message: `绑定 "${key}" 到 voice:pushToTalk 会在预热期间打印到输入框`,
      suggestion: '使用 space 或带修饰键的组合（如 meta+k）',
    })
  }
}
```

按住说话（push-to-talk）需要检测按键持续按住。如果绑定到裸字母键，按键重复会在激活前向输入框打印字符。

---

## 8. 遥测

用户自定义绑定加载时记录遥测事件，但限制为每天一次：

```typescript
// 源码: src/keybindings/loadUserBindings.ts (第83-90行)
function logCustomBindingsLoadedOncePerDay(userBindingCount: number): void {
  const today = new Date().toISOString().slice(0, 10)
  if (lastCustomBindingsLogDate === today) return
  lastCustomBindingsLogDate = today
  logEvent('tengu_custom_keybindings_loaded', {
    user_binding_count: userBindingCount,
  })
}
```

这让团队能估算自定义键绑定的用户比例，同时不会因为热重载频繁触发遥测。

---

## 9. 上下文解析流程总结

一个按键从按下到产生动作的完整路径：

```
用户按下 ctrl+x
     │
     ▼
Ink 框架产生 { input: 'x', key: { ctrl: true, ... } }
     │
     ▼
getKeyName(input, key) → 'x'    // 从 Ink 原始事件提取规范化键名
matchesKeystroke(input, key, ...) → 检查修饰键匹配
     │
     ▼
resolveKeyWithChordState(input, key, ['Chat', 'Global'], bindings, null)
     │
     ├─ 找到更长和弦前缀 (ctrl+x ctrl+k 存在)
     │  → return { type: 'chord_started', pending: [ctrl+x] }
     │
     ▼ (用户继续按 ctrl+k)
     │
resolveKeyWithChordState(input, key, ['Chat', 'Global'], bindings, [ctrl+x])
     │
     ├─ 精确匹配 ctrl+x ctrl+k → 'chat:killAgents'
     │  → return { type: 'match', action: 'chat:killAgents' }
     │
     ▼
UI 层执行 chat:killAgents 动作
```

---

## 批判性分析

### 局限性

1. **功能门控限制**：键绑定自定义当前仅对 Anthropic 内部员工开放（`isKeybindingCustomizationEnabled()` 检查 GrowthBook feature gate）。外部用户始终使用默认绑定，无法自定义。

2. **无条件绑定**：不支持 VS Code 风格的 `when` 条件表达式（如 `"when": "editorTextFocus && !editorReadonly"`）。上下文是预定义的固定集合，无法组合。

3. **和弦深度限制**：虽然理论上支持任意深度的和弦，但实际只使用了 2 层（如 `ctrl+x ctrl+k`）。更深的和弦在终端环境中用户体验不佳。

4. **终端能力限制**：`super`（cmd/win）键只在支持 kitty 键盘协议的终端中可用，大量终端无法使用 `cmd+` 绑定。alt 和 meta 在终端层面不可区分，限制了可用的修饰键组合数量。

### 设计权衡

1. **"后来者优先" vs. 显式覆盖**：数组拼接的优先级机制简单但隐式——用户必须理解其绑定追加在默认绑定之后才能覆盖。没有"显式声明覆盖"的机制，也没有"只在默认绑定不存在时生效"的 fallback 语义。

2. **Zod 验证 vs. 宽松解析**：schema 验证严格到拒绝未知字段。这在配置格式演进时可能导致向前兼容问题——新版本添加的字段在旧版本中会被拒绝。

3. **同步加载 + 异步热重载**：系统提供两条并行路径——`loadKeybindingsSyncWithWarnings()`（`readFileSync`，用于 React `useState` 初始化器的首次同步加载）与 `loadKeybindings()`（`await readFile`，用于后续热重载）。§6.1 展示的 async 版本用于运行时热重载；两条路径的代码几乎完全重复，维护成本高。

4. **Escape 的 meta quirk**：Ink 框架在 Escape 时设置 `meta=true` 是一个终端遗留问题，系统在匹配层（match.ts）和构建层（resolver.ts）都需要特殊处理。这是一个不得不应对的外部约束。

### 整体评价

键绑定系统展现了对终端环境复杂性的充分了解——从 Windows VT 模式的版本号追踪到 `ctrl+m`/Enter 的等价性警告，这些细节反映了扎实的终端兼容性工程经验（类似的处理在 tmux、neovim 等终端工具中也能找到）。和弦解析器的 null-unbind 优先级处理设计得当。系统的主要短板在于功能门控导致大部分用户无法使用自定义能力，以及同步/异步双路径代码的维护负担。