终端设置

Pi 使用 Kitty 键盘协议 可靠地检测修饰键。大多数现代终端都支持该协议，但部分终端需要额外配置。

Kitty、iTerm2

开箱即用，无需配置。

Apple Terminal

Pi 会在可用时启用增强按键上报。如果 Terminal.app 对 Shift+Enter 仍发送普通的 Return，pi 会使用 macOS 本地修饰键回退，将该 Return 视为 Shift+Enter。

该回退只在 pi 与 Terminal.app 运行在同一台 Mac 上时生效。通过远程 SSH 连接时无法检测本地键盘。

Ghostty

在 Ghostty 配置中添加（macOS 为 ~/Library/Application Support/com.mitchellh.ghostty/config，Linux 为 ~/.config/ghostty/config）：

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。

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 候选窗口。如果中日韩 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 Terminal

在 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 Terminal 默认将 Alt+Enter 绑定为全屏。这会使 pi 无法收到用于追问排队的 Alt+Enter。
• 将 Alt+Enter 重映射为 sendInput 后，真实的按键组合会转发给 pi。

如果你已经有 actions 数组，把这些对象加进去即可。如果旧的全屏行为仍然存在，请完全关闭并重新打开 Windows Terminal。

xfce4-terminal、terminator

这些终端对转义序列的支持有限。Ctrl+Enter、Shift+Enter 等带修饰键的 Enter 无法与普通 Enter 区分，导致 submit: ["ctrl+enter"] 之类的自定义快捷键绑定无法工作。

为了获得最佳体验，请使用支持 Kitty 键盘协议的终端：

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty（需要编译时启用 Kitty 协议支持）

IntelliJ IDEA（集成终端）

内置终端对转义序列的支持有限。在 IntelliJ 的终端中，Shift+Enter 无法与 Enter 区分。

如果希望硬件光标可见，请在运行 pi 前设置 PI_HARDWARE_CURSOR=1（出于兼容性默认关闭）。

考虑使用独立的终端模拟器以获得最佳体验。