pi-mono是一个功能强大的 AI 编程智能体（coding agent），它运行在终端里，靠一套精心设计的快捷键和出色的终端兼容性来提升日常开发效率。本文带你快速掌握 pi-mono 的键盘操作、Kitty 键盘协议原理，以及 Mac 键盘、Ghostty 等终端的正确配置方法，让每一次输入都丝滑顺畅。🚀

为什么 pi-mono 依赖 Kitty 键盘协议？

传统终端只能靠 ANSI 转义序列识别按键，但一旦出现Ctrl、Shift、Alt等修饰键组合，信息就会丢失或冲突。pi-mono 因此采用了 Kitty keyboard protocol：

• 终端向 pi-mono 发送带精确修饰键信息的CSI-u序列（如\x1b[13;2u表示Shift+Enter）；
• pi-mono 源码packages/tui/src/keys.ts中实现了协议解析与modifyOtherKeys回退机制（当终端不支持协议时自动降级）；
• 好处：Shift+Enter换行、Alt+方向键按单词移动、符号键（@、?）等都能被准确识别，不会误触其他功能。

💡 简言之：协议负责"准确"，终端配置负责"打通"。下面分终端给出配置技巧。

pi-mono 核心快捷键速查表

以下是最常用的操作，覆盖导航、编辑与会话控制三大类：

导航类

编辑类

会话控制类

Mac 键盘适配技巧 🍎

Mac 用户最常遇到的问题是Option 键行为不一致：pi-mono 的源码讨论中专门提到，macOS 上 Option 组合键有时会被终端解释为ESC前缀，导致Alt+Left这类单词级移动失效。

推荐做法：

1. 把 Option 当作真正的 Alt 键：在终端设置的 Profile 中找到 "Left Option key" 选项，选择Esc+（或 "Alt"），这样Alt+Left/Right才能正确发出修饰键序列；
2. 行首行尾移动：macOS 上没有Home/End，直接用Cmd+Left/Cmd+Right，pi-mono 原生支持这两个绑定；
3. Shift+Enter换行：若你的终端吞掉了该组合，可先用Ctrl+J作为默认回退（newLine动作默认绑定为shift+enter和ctrl+j）。

Ghostty 配置技巧 ⚡

Ghostty 性能极佳，但默认键位会拦截Alt+Backspace和Shift+Enter。只需在~/.config/ghostty/config中加入两行：

keybind = alt+backspace=text:\x1b\x7f keybind = shift+enter=text:\n

这样 pi-mono 的按单词删除和多行输入就都能正常工作了。Ghostty 同时支持 Kitty 图形协议，工具输出中的图片还能内联渲染——不支持的终端则显示文本占位符。

其他主流终端一步到位配置

• Kitty、iTerm2：开箱即用，无需任何配置；
• VS Code 集成终端：在keybindings.json中把Shift+Enter映射为workbench.action.terminal.sendSequence，参数text设为\u001b[13;2u；
• Windows Terminal：在settings.json的actions中给shift+enter发送\u001b[13;2u；
• WezTerm：~/.wezterm.lua中设置config.enable_kitty_keyboard = true；
• IntelliJ 内置终端：转义序列支持有限，建议改用独立终端获得最佳体验。

自定义快捷键：一个 JSON 文件搞定

所有快捷键都可以通过~/.pi/agent/keybindings.json重新绑定，每个动作支持多个按键：

{ "cursorLeft": ["left", "alt+h"], "cursorRight": ["right", "alt+l"], "cursorWordLeft": ["alt+left", "alt+b"], "deleteWordBackward": ["ctrl+w", "alt+backspace"] }

按键格式为modifier+key，修饰键支持ctrl、shift、alt，键位除字母数字外还支持escape、tab、enter以及@、?等符号键。喜欢 Vim 风格？把上下左右改成j/k/h/l即可，官方文档还给出了现成的 Vim 风格示例。

参考资料 📚

• 项目说明：README.md
• 快捷键文档：packages/coding-agent/docs/keybindings.md（含完整动作清单与自定义示例）
• 按键解析实现：packages/tui/src/keys.ts、packages/tui/src/keybindings.ts
• Ghostty / Kitty 协议配置细节可在本仓库的会话记录中查阅，如 2026-01-25T02-28-18-217Z_974e9afe-4026-463a-9878-455ba28b746e.jsonl
• Mac 键盘 Option 键讨论：2026-03-07T22-25-48-100Z_61747bb0-9a5e-4a44-bdf3-ad8d5da99b42.jsonl

掌握这套快捷键与终端配置后，pi-mono 的手感会立刻脱胎换骨——快打开你的终端试试吧！🎯