终端设置

Pi 使用 Kitty keyboard protocol 来可靠识别修饰键。大多数现代终端都支持这个协议，但有些需要额外配置。

能力覆盖

Pi 会自动检测 OSC 8 超链接、内联图片协议和真彩色。如果终端代理或多路复用器导致检测失败，可以使用以下高级覆盖设置：

设置的优先级高于环境变量；未设置或使用 auto 时保留自动检测。只有在完整终端链路支持某项能力时才应强制启用，否则不支持的转义序列可能破坏渲染。

Kitty

开箱即用。

iTerm2

普通 TUI 模式

开箱即用。

全屏 TUI 模式

Pi 会接管视口，因此 iTerm2 会发送鼠标滚轮报告，而不是滚动其原生滚动历史。在 iTerm2 默认的快速触控板行为下，这些报告可能丢失大部分加速滚轮增量，使全屏滚动明显慢于普通滚动。

如果快速鼠标滚轮手势在全屏模式下每次只移动大约一行：

1. 打开 iTerm2 → Settings → Advanced。
2. 搜索 Trackpad scrolls fast?，并设置为 No。

这是适用于整个 iTerm2 的变通方案，也可能改变原生触控板滚动。相关底层行为记录在 iTerm2 issue 9619。

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

那个映射会发送原始的 linefeed byte。在 Pi 内部，它和 Ctrl+J 没有区别，所以 tmux 和 Pi 都不再能看到真正的 shift+enter 按键事件。

如果你添加这个映射只是因为 Claude Code 2.x 或更新版本，你可以删掉它；不过如果你还想在 tmux 里使用 Claude Code，就先保留，因为在那里它仍然需要这个 Ghostty 映射。

Pi 默认将 Ctrl+J 绑定为换行别名，因此通过该重映射在 tmux 中使用 Shift+Enter 时，无需额外配置 Pi。

全屏 TUI 模式

在全屏模式下，链接仍然可以点击，但由于 Pi 会捕获鼠标输入，Ghostty 不会显示悬停下划线或左下角 URL 预览。在 macOS 上按住 Shift+Command，在 Linux 上按住 Shift+Ctrl，即可使用 Ghostty 的原生链接处理。

WezTerm

WezTerm 通常会通过 xterm modifyOtherKeys 让 Shift+Enter 开箱即用。若要显式使用 Kitty keyboard protocol，请创建 ~/.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 keyboard protocol，所以 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

Pi 在原生 Windows 或 WSL 中运行时使用 Windows 风格的按键绑定：

• Alt+V 粘贴图片或剪贴板文本。
• Ctrl+F 在全屏模式下搜索转录，Ctrl+Up/Ctrl+Down 在标记消息之间跳转。
• Alt+P 切换到上一个模型。
• 原生 Windows 使用 Ctrl+Z 撤销编辑；WSL 使用 Alt+Z，这样 Ctrl+Z 可以挂起 Pi。
• Ctrl+Q 将后续消息加入队列，Alt+Q 恢复排队消息。

将以下内容添加到 settings.json（Ctrl+Shift+, 或 Settings → Open JSON file），以转发用于插入换行的 Shift+Enter：

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    }
  ]
}

Windows Terminal 默认将 Alt+Enter 绑定为全屏。若要用它替代 Pi 默认的 Ctrl+Q 来排队后续消息，请配置 Windows Terminal 发送该按键，并在 Pi 中将 app.message.followUp 绑定到 alt+enter。

如果已经有 actions 数组，就把这个对象加进去。修改设置后，彻底关闭并重新打开 Windows Terminal。

xfce4-terminal、terminator

这些终端对转义序列的支持有限。像 Ctrl+Enter 和 Shift+Enter 这样的带修饰键 Enter，无法与普通 Enter 区分，因此 submit: ["ctrl+enter"] 这类自定义按键绑定无法工作。

为了获得最佳体验，请使用支持 Kitty keyboard protocol 的终端：

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

IntelliJ IDEA（集成终端）

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

如果你希望显示硬件光标，请在运行 Pi 前设置 PI_HARDWARE_CURSOR=1（默认关闭，以保证兼容性）。

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