终端设置
Pi 使用 Kitty 键盘协议 以实现可靠的修饰键检测。大多数现代终端都支持此协议，但有些需要配置。
Kitty
开箱即用。
iTerm2
常规 TUI 模式
开箱即用。
全屏 TUI 模式
Pi 拥有视口，因此 iTerm2 发送鼠标滚轮报告而不是滚动其原生的回滚缓冲区。在 iTerm2 默认的快速触控板行为下，这些报告可能会丢失大部分加速滚轮增量，使得全屏滚动比常规滚动慢得多。
如果在全屏模式下快速鼠标滚轮手势每次只移动大约一行：
- 打开 iTerm2 → 设置 → 高级.
- 搜索 触控板快速滚动？ 并将其设置为 否.
这是一个 iTerm2 全局的变通方法，也可能会改变原生的触控板滚动。底层行为在 iTerm2 问题 9619.
Apple 终端
Pi 在可用时启用增强的按键报告。如果 Terminal.app 仍然为 Shift+Enter发送普通的 Return，pi 使用本地的 macOS 修饰键回退将该 Return 视为 Shift+Enter.
此回退仅在 pi 与 Terminal.app 在同一台 Mac 上运行时有效。它无法通过远程 SSH 检测本地键盘。
幽灵终端
添加到你的 Ghostty 配置（~/Library/Application Support/com.mitchellh.ghostty/config 在 macOS 上， ~/.config/ghostty/config 在 Linux 上）：
keybind = alt+backspace=text:\x1b\x7f
较旧的 Claude Code 版本可能添加了此 Ghostty 映射：
keybind = shift+enter=text:\n
该映射发送一个原始的换行字节。在 pi 内部，这与 Ctrl+J无法区分，因此 tmux 和 pi 不再看到真正的 shift+enter 按键事件。
如果 Claude Code 2.x 或更新版本是你添加该映射的唯一原因，你可以将其移除，除非你想在 tmux 中使用 Claude Code，在那里它仍然需要该 Ghostty 映射。
Pi 将 Ctrl+J 绑定为默认的换行别名，因此 Shift+Enter 通过该重新映射在 tmux 中继续工作，无需额外的 pi 配置。
全屏 TUI 模式
在全屏模式下，链接仍然可点击，但当 pi 捕获鼠标输入时，Ghostty 不会显示其悬停下划线或左下角的 URL 预览。按住 Shift+Command 在 macOS 上或 Shift+Ctrl 在 Linux 上以使用 Ghostty 的原生链接处理。
WezTerm
WezTerm 通常通过 xterm modifyOtherKeys 对 Shift+Enter 开箱即用。要显式使用 Kitty 键盘协议，请创建 ~/.wezterm.lua:
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config在 macOS 上，WezTerm 默认将 Option+Enter 绑定到全屏。要将 Option+Enter 用于 pi 的后续排队，请添加此按键覆盖：
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.keys = {
{
key = 'Enter',
mods = 'ALT',
action = wezterm.action.SendString('\x1b[13;3u'),
},
}
return config如果你已经有一个 config.keys 表，请将条目添加到其中。
在 WSL 上，WezTerm 可能需要一个可见的硬件光标来进行 IME 候选窗口定位。如果 CJK IME 候选不跟随文本光标，请在运行 pi 之前设置 PI_HARDWARE_CURSOR=1 或在设置中将 showHardwareCursor 设置为 true 在设置中。
Alacritty
Alacritty 通常开箱即用，适用于 Shift+Enter。在 macOS 上， Option+Enter 可能以纯文本形式出现 Enter。要使用 Option+Enter 进行 pi 的后续排队，请添加到 ~/.config/alacritty/alacritty.toml:
[[keyboard.bindings]]
key = "Enter"
mods = "Alt"
chars = "\u001b[13;3u"更改配置后重启 Alacritty。
VS Code（集成终端）
VS Code 1.109.5 及更高版本默认在集成终端中启用 Kitty 键盘协议，因此 Shift+Enter 应该开箱即用。
低于 1.109.5 的 VS Code 版本需要为 Shift+Enter.
keybindings.json 位置显式设置终端键绑定：
- macOS：
~/Library/Application Support/Code/User/keybindings.json - Linux：
~/.config/Code/User/keybindings.json - Windows：
%APPDATA%\\Code\\User\\keybindings.json
添加到 keybindings.json:
{
"key": "shift+enter",
"command": "workbench.action.terminal.sendSequence",
"args": { "text": "\u001b[13;2u" },
"when": "terminalFocus"
}Windows 终端
添加到 settings.json （Ctrl+Shift+, 或设置 → 打开 JSON 文件）以转发 pi 使用的修改后的 Enter 键：
{
"actions": [
{
"command": { "action": "sendInput", "input": "\u001b[13;2u" },
"keys": "shift+enter"
},
{
"command": { "action": "sendInput", "input": "\u001b[13;3u" },
"keys": "alt+enter"
}
]
}Shift+Enter插入新行。- Windows 终端默认将
Alt+Enter绑定到全屏。这会阻止 pi 接收Alt+Enter以进行后续排队。 - 将
Alt+Enter重新映射到sendInput会将真实的组合键转发给 pi。
如果你已经有一个 actions 数组，请将对象添加到其中。如果旧的全屏行为仍然存在，请完全关闭并重新打开 Windows 终端。
xfce4终端、终结者
这些终端的转义序列支持有限。修改后的 Enter 键，如 Ctrl+Enter 和 Shift+Enter 无法与普通的 Enter区分开来，从而阻止自定义键绑定（如 submit: ["ctrl+enter"] ）正常工作。
为了获得最佳体验，请使用支持 Kitty 键盘协议的终端：
IntelliJ IDEA（集成终端）
内置终端的转义序列支持有限。在 IntelliJ 的终端中，Shift+Enter 无法与 Enter 区分开来。
如果你希望硬件光标可见，请在运行 pi 之前设置 PI_HARDWARE_CURSOR=1 （默认情况下为兼容性而禁用）。
为了获得最佳体验，请考虑使用专用的终端模拟器。