Prime Agent 终端环境配置指南：从 Kitty 键盘协议到各终端按键映射完整方案

Prime Agent 终端环境配置指南：从 Kitty 键盘协议到各终端按键映射完整方案

【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent

导读

Prime Agent 是一款面向编码工作流与长时间自治任务的 RLM（Runtime Language Model）Agent，其交互式 TUI 依赖终端对修饰键（Modifier Key）可靠检测来区分Enter、Shift+Enter、Alt+Enter等按键语义。本文以 terminal-setup.md 为主线，系统梳理 Ghostty、WezTerm、VS Code 集成终端、Windows Terminal、xfce4-terminal、IntelliJ IDEA 等环境的配置方法，并结合 packages/tui/src/keys.ts 的源码解析Shift+Enter换行、Alt+Enter排队追问、Ctrl+Enter提交等核心按键在底层是如何被识别的。读完本文，你将掌握：不同终端下让 Prime Agent 完整识别修饰键的具体配置、tmux 中恢复按键语义的最佳实践，以及~/.prime/agent/keybindings.json的自定义方法。

背景：Prime Agent 为什么依赖 Kitty 键盘协议

Prime Agent 使用Kitty 键盘协议（Kitty keyboard protocol）实现可靠的修饰键检测。该协议通过 CSI-u（CSIu）序列把「按键 + 修饰键 + 基础布局键」编码成无歧义的转义序列，例如Shift+Enter编码为\x1b[13;2u、Ctrl+Enter编码为\x1b[13;5u、Alt+Enter编码为\x1b[13;3u。

在 TUI 源码中，这一协议的处理集中在 packages/tui/src/keys.ts：

• 第 5-10 行注释明确引用了 Kitty 键盘协议文档，并针对legacy-ctrl-mapping-of-ascii-keys做了兼容处理；
• parseKittySequence与parseModifyOtherKeysSequence（第 669-675 行）分别解析 CSI-u 与 xtermmodifyOtherKeys两种格式；
• 对于Enter键（第 858-912 行），匹配逻辑依次尝试：CSI-u 标准序列 → xtermmodifyOtherKeys回退格式 → 各终端的自定义映射（如 Ghostty 的\n与 Kitty 的\x1b\r）。

大多数现代终端原生支持该协议，但部分终端需要额外配置，少数终端（如 xfce4-terminal、IntelliJ 内置终端）则完全不支持，导致修饰键无法区分。下文按终端逐一说明。

开箱即用的终端：Kitty 与 iTerm2

Kitty与iTerm2直接支持 Kitty 键盘协议，无需任何额外配置即可让 Prime Agent 完整识别Shift+Enter、Ctrl+Enter、Alt+Enter等修饰键组合。

Ghostty：两处配置与一个易踩的坑

Ghostty 需要在配置文件中增加一个键位映射，才能在 macOS 与 Linux 下正常工作：

• macOS 配置文件路径：~/Library/Application Support/com.mitchellh.ghostty/config
• Linux 配置文件路径：~/.config/ghostty/config

向该文件追加以下内容：

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

这条映射把Alt+Backspace显式发送为\x1b\x7f（ESC + DEL），对应 Prime Agent 中「删除上一个单词」的操作。在 packages/tui/src/keybindings.ts 第 112 行，tui.editor.deleteWordBackward的默认键正是["ctrl+w", "alt+backspace"]；而 packages/tui/src/keys.ts 第 914-922 行在处理alt+backspace时，也明确接受\x1b\x7f与\x1b\b两种传统序列。

需要移除的旧版 Ghostty 映射

早期 Claude Code 版本曾建议在 Ghostty 中增加如下映射：

keybind = shift+enter=text:\n

这条映射会把Shift+Enter直接发送成原始的换行字节（\n）。在 Prime Agent 内部，\n与Ctrl+J的字节流完全一致（见 packages/tui/src/keys.ts 第 873-876 行：Kitty 协议激活时\n会被当作 Ghostty 的shift+enter映射处理），因此 tmux 和 Prime Agent 都无法再收到真实的Shift+Enter键事件。

如果你添加这条映射的唯一原因是 Claude Code，那么可以放心删除它——除非你打算在 tmux 里使用 Claude Code，那种场景下它仍然需要这条 Ghostty 映射。

如果你希望在 tmux 中通过这条重映射继续使用Shift+Enter，可以在 Prime Agent 的~/.prime/agent/keybindings.json中为newLine动作追加ctrl+j作为备用键：

{ "newLine": ["shift+enter", "ctrl+j"] }

这样，当 Ghostty 把Shift+Enter转成\n（即等效于Ctrl+J）时，Prime Agent 仍能触发换行。该配置使用的newLine即tui.input.newLine动作，其默认绑定就是shift+enter（见 packages/tui/src/keybindings.ts 第 134-138 行）。

WezTerm：两行 Lua 配置启用 Kitty 协议

WezTerm 默认未开启 Kitty 键盘协议，需要在~/.wezterm.lua中显式启用：

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

创建该文件后重启 WezTerm 即可生效。

VS Code 集成终端：让 Shift+Enter 支持多行输入

VS Code 内置终端默认不把Shift+Enter转发给应用程序。需要在用户级keybindings.json中增加一条sendSequence绑定，手动发送 CSI-u 序列\x1b[13;2u（即Shift+Enter）：

• macOS：~/Library/Application Support/Code/User/keybindings.json
• Linux：~/.config/Code/User/keybindings.json
• Windows：%APPDATA%\Code\User\keybindings.json

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

关键点："when": "terminalFocus"保证该映射只在终端获得焦点时生效，不会影响编辑器内的Shift+Enter行为；\u001b[13;2u正是 packages/tui/src/keys.ts 中matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift)期望收到的 CSI-u 序列。配置完成后，Shift+Enter在 Prime Agent 输入框中即可插入换行（tui.input.newLine）。

Windows Terminal：Shift+Enter 与 Alt+Enter 的完整转发

Windows Terminal 需要在settings.json（Ctrl+Shift+,或 Settings → Open JSON file）中把 Prime Agent 使用的修饰键 Enter 转发出去。在actions数组中追加两个sendInput动作：

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

配置效果说明：

• Shift+Enter插入新行：发送\x1b[13;2u，对应tui.input.newLine（默认shift+enter）。
• Alt+Enter排队追问：Windows Terminal 默认把Alt+Enter绑定为全屏切换，这会拦截 Prime Agent 接收Alt+Enter。将其重映射为sendInput（发送\x1b[13;3u）后，真实的按键组合才会被转发给 Prime Agent，用于app.message.followUp（默认alt+enter，见 keybindings.md 第 135 行）。

如果settings.json中已经存在actions数组，直接把上述对象合并进去即可。若旧的全屏行为仍然生效，请完全关闭并重新打开 Windows Terminal。

受限终端：xfce4-terminal 与 terminator

xfce4-terminal与terminator对转义序列的支持有限，Ctrl+Enter、Shift+Enter等修饰键 Enter无法与普通Enter区分，因此诸如submit: ["ctrl+enter"]的自定义键绑定无法生效。

对于这类终端，最稳妥的方案是改用完整支持 Kitty 键盘协议的终端。仓库文档明确推荐以下选择：

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

IntelliJ IDEA 集成终端：建议改用独立终端模拟器

IntelliJ IDEA 内置终端的转义序列支持同样有限，无法区分Shift+Enter与Enter，因此 Prime Agent 的换行/提交键语义会受影响。

如果你仍希望在该终端中获得更好的光标体验，可以在启动prime-agent前设置环境变量PI_HARDWARE_CURSOR=1来显示硬件光标：

PI_HARDWARE_CURSOR=1 prime-agent

该变量默认关闭（为兼容性考虑），其读取逻辑位于 packages/coding-agent/src/core/settings-manager.ts 第 1274 行：this.settings.showHardwareCursor ?? process.env.PI_HARDWARE_CURSOR === "1"，即显式设置为"1"时启用硬件光标，否则由全局设置项showHardwareCursor决定。

从整体体验出发，IntelliJ 内置终端下仍建议优先使用专用终端模拟器运行 Prime Agent。

macOS 的 Control+Option+Arrow 快捷键冲突

待发送消息（pending message）的排序默认使用Control+Option+Up（上移）与Control+Option+Down（下移）。Prime Agent 同时接受两类输入：

• 现代修饰键箭头序列（Kitty CSI-u）；
• 传统「Option 作为 Meta」包裹的Control+Arrow序列。

macOS 的VoiceOver使用Control+Option作为其修饰键，系统或终端快捷键也可能在这些按键组合到达 Prime Agent 之前将其拦截。如果发生冲突，可以在~/.prime/agent/keybindings.json中重映射app.message.moveEarlier与app.message.moveLater（对应keybindings.md中默认的ctrl+alt+up与ctrl+alt+down）。

配套方案：tmux 中的修饰键恢复

若在 tmux 中运行 Prime Agent，tmux 默认会剥掉部分按键的修饰信息，导致Shift+Enter与Ctrl+Enter退化为普通Enter。推荐在~/.tmux.conf中启用 CSI-u 格式的扩展键：

set -g extended-keys on set -g extended-keys-format csi-u

然后完全重启 tmux：

tmux kill-server tmux

原理说明（详见 tmux.md）：

• 仅启用extended-keys on时，tmux 默认使用 xtermmodifyOtherKeys格式，例如Ctrl+C→\x1b[27;5;99~、Ctrl+Enter→\x1b[27;5;13~；
• 指定extended-keys-format csi-u后，同样按键以 CSI-u 格式转发：Ctrl+C→\x1b[99;5u、Ctrl+Enter→\x1b[13;5u，这是最可靠的配置。

对比无扩展键时的退化行为：

按键	无扩展键	启用csi-u
Enter	\r	\r
Shift+Enter	\r	\x1b[13;2u
Ctrl+Enter	\r	\x1b[13;5u
Alt/Option+Enter	\x1b\r	\x1b[13;3u

注意：Shift+Enter与Ctrl+Enter在无扩展键时全部坍缩为\r，这正是自定义修改 Enter 键绑定失效的根因。启用条件为tmux 3.2 及以上（用tmux -V检查）且终端模拟器支持扩展键（Ghostty、Kitty、iTerm2、WezTerm、Windows Terminal 均可）。

键位自定义：keybindings.json 速查

Prime Agent 的所有键盘快捷键都可以通过~/.prime/agent/keybindings.json自定义，每个动作可绑定一个或多个按键（详见 keybindings.md）。键格式为modifier+key，修饰键支持ctrl、shift、alt自由组合（如ctrl+shift+alt+x、ctrl+1）。

与终端配置直接相关的核心动作默认值如下：

键绑定 ID	默认键	说明
tui.input.submit	enter	提交输入
tui.input.newLine	shift+enter	插入新行
tui.editor.deleteWordBackward	ctrl+w,alt+backspace	删除上一个单词
app.message.followUp	alt+enter	排队追问消息
app.message.moveEarlier	ctrl+alt+up	上移待发送消息
app.message.moveLater	ctrl+alt+down	下移待发送消息

修改keybindings.json后，在 Prime Agent 内执行/reload即可热生效，无需重启会话。老版本中未加命名空间的旧键 ID（如cursorUp）会在启动时自动迁移到新的命名空间格式。

小结：按终端速查表

终端	所需配置	备注
Kitty / iTerm2	无	开箱即用
Ghostty	alt+backspace=text:\x1b\x7f	删除旧的shift+enter=text:\n映射
WezTerm	config.enable_kitty_keyboard = true	写入~/.wezterm.lua
VS Code 终端	sendSequence发送\x1b[13;2u	需terminalFocus限定
Windows Terminal	sendInput转发\x1b[13;2u与\x1b[13;3u	需释放Alt+Enter全屏绑定
xfce4-terminal / terminator	不支持	建议换 Kitty 协议终端
IntelliJ 终端	有限支持	可用PI_HARDWARE_CURSOR=1；建议用独立终端
tmux	extended-keys on+extended-keys-format csi-u	需 tmux 3.2+

配置完成后，Shift+Enter换行、Alt+Enter追问排队、Ctrl+Enter提交等核心交互即可在 Prime Agent 中稳定工作。

【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent