phase-10-keybinding-system

[pionxe]

Phase 10: 全新快捷键系统

• Phase: 10
• 优先级: P1
• 依赖: Phase 9（Command Prompt 可用）

---

What — 要做什么

实现 TUI v2 的三层键位系统：Input Mode、Normal Mode、Leader Key。完全独立于 TUI v1 的键位系统。

三层模式

                    ┌──────────────┐
       默认进入      │  Input Mode   │
  ┌───────────────▶│  (打字/发送)   │
  │                └──────┬───────┘
  │                       │ Esc
  │                       ▼
  │                ┌──────────────┐
  │      i / Enter  │ Normal Mode  │
  │  ◀────────────│  (导航/命令)  │
  │                └──┬───────┬───┘
  │                   │       │ Space
  │                   │       ▼
  │                   │  ┌──────────────┐
  │                   │  │ Leader Mode   │
  │                   │  │ (Space + key) │
  │                   │  └──────────────┘
  │                   │       │
  │                   │   key pressed
  │                   │  (自动回到 Normal)
  │                   │       │
  └───────────────────┴───────┘

Input Mode 键位

按键	行为
可打印字符	输入文本
Enter	发送消息 / 确认
Shift+Enter	换行
Backspace	删除前一个字符
Ctrl+C	取消当前运行（首次），再次退出（双退）
Ctrl+D	退出（EOF）
Esc	进入 Normal Mode
Ctrl+A / Ctrl+E	行首 / 行尾
Ctrl+K	删除到行尾
Ctrl+W	删除前一个词

按下 Leader key 后的按键后自动回到 Normal Mode（除非打开的面板保持打开）。

模式切换信号

模式切换通过自定义 tea.Msg 传递：

type ModeChangedMsg struct {
    Mode state.InputMode
}

App.Update() 收到 ModeChangedMsg 后更新 ViewState.Mode，底部状态行自动反映当前模式。

模式指示器

底部状态行左侧：

• [input] — Input Mode（FG 色）
• [normal] — Normal Mode（Subtle 色）
• [leader] — Leader Mode（Accent 色，闪烁或加粗）

---

Why — 为什么全新键位系统

1. v1 键位不可兼容：v1 的 Esc=聚焦输入、Ctrl+J=换行、Ctrl+W=取消运行，与 v2 的 Esc=Normal Mode、Shift+Enter=换行、Ctrl+C=取消 冲突 —— 无法在同一套 keyMap 共存
2. Vim 用户直觉：三层模式是 Vim/Neovim 用户熟悉的操作模型，降低学习成本
3. 输入与导航分离：打字时不会被 j/k 滚动干扰，导航时不会误输入字符

---

How — 怎么做

1. 创建 internal/tuiv2/keymap/keymap.go，定义三种模式的按键映射
2. 使用 Bubble Tea 的 key.Binding 类型定义每个按键绑定
3. 在 App.Update() 中根据 ViewState.Mode 路由按键到不同 handler
4. 实现 handleInputModeKey(), handleNormalModeKey(), handleLeaderModeKey()
5. Leader Mode 实现为有限状态机：Space → 等待下一个按键 → 执行动作 → 回到 Normal
6. :q 退出使用 mini-command-line（底部单行输入），:debug 同样
7. 不复用 v1 的 keyMap，不 import internal/tui/

---

验收标准

• Esc 从 Input Mode 切换到 Normal Mode
• Normal Mode 下 i / Enter 回到 Input Mode
• Normal Mode 下 j/k 滚动 Agent Stream
• Space 进入 Leader Mode，按下 key 后执行动作并回到 Normal
• Ctrl+C 双退逻辑：首次取消运行，再次退出程序
• :q 退出程序
• 底部状态行模式指示正确切换
• go test ./internal/tuiv2/keymap/... 覆盖各模式转换