终端设置

Pi 使用 Kitty 键盘协议以可靠地检测修饰键。大多数现代终端都支持此协议，但某些需要配置。

Kitty、iTerm2

开箱即用。

Apple Terminal

当可用时，Pi 启用增强的键报告。如果 Terminal.app 仍然为 Shift+Enter 发送普通 Return，Pi 使用本地 macOS 修饰键回退将其视为 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：

lua

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config

在 macOS 上，WezTerm 默认将 Option+Enter 绑定为全屏。若要使用 Option+Enter 进行 Pi 后续队列，添加此键覆盖：

lua

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 中添加：

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 中添加：

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 键：

json

{
  "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（默认禁用以确保兼容性）。

为获得最佳体验，建议使用专用终端模拟器。

终端设置 ​

Kitty、iTerm2 ​

Apple Terminal ​

Ghostty ​

WezTerm ​

Alacritty ​

VS Code（集成终端） ​

Windows Terminal ​

xfce4-terminal、terminator ​

IntelliJ IDEA（集成终端） ​