终端设置

Pi 使用 Kitty keyboard protocol 进行可靠的修饰键检测。大多数现代终端都支持此协议，但有些需要配置。

开箱即用。

Pi 在可用时启用增强的关键报告。如果 Terminal.app 仍然发送 Shift+Enter 的普通 Return，则 pi 使用本地 macOS 修饰符后备将该 Return 视为 Shift+Enter。

仅当 pi 与 Terminal.app 在同一台 Mac 上运行时，此后备才有效。它无法通过远程SSH检测到本地键盘。

添加到您的 Ghostty 配置（macOS 上为 ~/Library/Application Support/com.mitchellh.ghostty/config，Linux 上为 ~/.config/ghostty/config）：

keybind = alt+backspace=text:\x1b\x7f

较旧的克劳德代码版本可能添加了此 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 通常通过 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 通常开箱即用，适用于 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 1.109.5 及更高版本默认在集成终端中启用 Kitty 键盘协议，因此 Shift+Enter 应该可以开箱即用。

早于 1.109.5 的 VS Code 版本需要 Shift+Enter 的显式终端键绑定。

keybindings.json地点：

• 苹果系统：~/Library/Application Support/Code/User/keybindings.json
• Linux：~/.config/Code/User/keybindings.json
• 窗户：%APPDATA%\\Code\\User\\keybindings.json

添加到keybindings.json：

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b[13;2u" },
  "when": "terminalFocus"
}

添加到settings.json（Ctrl+Shift+，或设置→打开JSON文件）以转发修改后的Enter键pi使用：

{
  "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 终端。

这些终端的转义序列支持有限。修改后的 Enter 键（如 Ctrl+Enter 和 Shift+Enter）无法与普通的 Enter 区分开来，从而阻止自定义键绑定（如 submit: ["ctrl+enter"]）工作。

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

• Kitty
• Ghostty
• WezTerm
• iTerm2
• Alacritty（需要带有Kitty协议支持的编译）

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

如果您希望硬件光标可见，请在运行 pi 之前设置 PI_HARDWARE_CURSOR=1 （默认情况下禁用兼容性）。

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