拓冰网站定制 
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 是一款面向编码工作流与长时间自治任务的 RLMRuntime Language ModelAgent其交互式 TUI 依赖终端对修饰键Modifier Key可靠检测来区分Enter、ShiftEnter、AltEnter等按键语义。本文以 terminal-setup.md 为主线系统梳理 Ghostty、WezTerm、VS Code 集成终端、Windows Terminal、xfce4-terminal、IntelliJ IDEA 等环境的配置方法并结合 packages/tui/src/keys.ts 的源码解析ShiftEnter换行、AltEnter排队追问、CtrlEnter提交等核心按键在底层是如何被识别的。读完本文你将掌握不同终端下让 Prime Agent 完整识别修饰键的具体配置、tmux 中恢复按键语义的最佳实践以及~/.prime/agent/keybindings.json的自定义方法。背景Prime Agent 为什么依赖 Kitty 键盘协议Prime Agent 使用Kitty 键盘协议Kitty keyboard protocol实现可靠的修饰键检测。该协议通过 CSI-uCSIu序列把「按键 修饰键 基础布局键」编码成无歧义的转义序列例如ShiftEnter编码为\x1b[13;2u、CtrlEnter编码为\x1b[13;5u、AltEnter编码为\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 与 iTerm2Kitty与iTerm2直接支持 Kitty 键盘协议无需任何额外配置即可让 Prime Agent 完整识别ShiftEnter、CtrlEnter、AltEnter等修饰键组合。Ghostty两处配置与一个易踩的坑Ghostty 需要在配置文件中增加一个键位映射才能在 macOS 与 Linux 下正常工作macOS 配置文件路径~/Library/Application Support/com.mitchellh.ghostty/configLinux 配置文件路径~/.config/ghostty/config向该文件追加以下内容keybind altbackspacetext:\x1b\x7f这条映射把AltBackspace显式发送为\x1b\x7fESC DEL对应 Prime Agent 中「删除上一个单词」的操作。在 packages/tui/src/keybindings.ts 第 112 行tui.editor.deleteWordBackward的默认键正是[ctrlw, altbackspace]而 packages/tui/src/keys.ts 第 914-922 行在处理altbackspace时也明确接受\x1b\x7f与\x1b\b两种传统序列。需要移除的旧版 Ghostty 映射早期 Claude Code 版本曾建议在 Ghostty 中增加如下映射keybind shiftentertext:\n这条映射会把ShiftEnter直接发送成原始的换行字节\n。在 Prime Agent 内部\n与CtrlJ的字节流完全一致见 packages/tui/src/keys.ts 第 873-876 行Kitty 协议激活时\n会被当作 Ghostty 的shiftenter映射处理因此 tmux 和 Prime Agent 都无法再收到真实的ShiftEnter键事件。如果你添加这条映射的唯一原因是 Claude Code那么可以放心删除它——除非你打算在 tmux 里使用 Claude Code那种场景下它仍然需要这条 Ghostty 映射。如果你希望在 tmux 中通过这条重映射继续使用ShiftEnter可以在 Prime Agent 的~/.prime/agent/keybindings.json中为newLine动作追加ctrlj作为备用键{ newLine: [shiftenter, ctrlj] }这样当 Ghostty 把ShiftEnter转成\n即等效于CtrlJ时Prime Agent 仍能触发换行。该配置使用的newLine即tui.input.newLine动作其默认绑定就是shiftenter见 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 集成终端让 ShiftEnter 支持多行输入VS Code 内置终端默认不把ShiftEnter转发给应用程序。需要在用户级keybindings.json中增加一条sendSequence绑定手动发送 CSI-u 序列\x1b[13;2u即ShiftEntermacOS~/Library/Application Support/Code/User/keybindings.jsonLinux~/.config/Code/User/keybindings.jsonWindows%APPDATA%\Code\User\keybindings.json{ key: shiftenter, command: workbench.action.terminal.sendSequence, args: { text: \u001b[13;2u }, when: terminalFocus }关键点when: terminalFocus保证该映射只在终端获得焦点时生效不会影响编辑器内的ShiftEnter行为\u001b[13;2u正是 packages/tui/src/keys.ts 中matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift)期望收到的 CSI-u 序列。配置完成后ShiftEnter在 Prime Agent 输入框中即可插入换行tui.input.newLine。Windows TerminalShiftEnter 与 AltEnter 的完整转发Windows Terminal 需要在settings.jsonCtrlShift,或 Settings → Open JSON file中把 Prime Agent 使用的修饰键 Enter 转发出去。在actions数组中追加两个sendInput动作{ actions: [ { command: { action: sendInput, input: \u001b[13;2u }, keys: shiftenter }, { command: { action: sendInput, input: \u001b[13;3u }, keys: altenter } ] }配置效果说明ShiftEnter插入新行发送\x1b[13;2u对应tui.input.newLine默认shiftenter。AltEnter排队追问Windows Terminal 默认把AltEnter绑定为全屏切换这会拦截 Prime Agent 接收AltEnter。将其重映射为sendInput发送\x1b[13;3u后真实的按键组合才会被转发给 Prime Agent用于app.message.followUp默认altenter见 keybindings.md 第 135 行。如果settings.json中已经存在actions数组直接把上述对象合并进去即可。若旧的全屏行为仍然生效请完全关闭并重新打开 Windows Terminal。受限终端xfce4-terminal 与 terminatorxfce4-terminal与terminator对转义序列的支持有限CtrlEnter、ShiftEnter等修饰键 Enter无法与普通Enter区分因此诸如submit: [ctrlenter]的自定义键绑定无法生效。对于这类终端最稳妥的方案是改用完整支持 Kitty 键盘协议的终端。仓库文档明确推荐以下选择KittyGhosttyWezTermiTerm2Alacritty需要编译时启用 Kitty 协议支持IntelliJ IDEA 集成终端建议改用独立终端模拟器IntelliJ IDEA 内置终端的转义序列支持同样有限无法区分ShiftEnter与Enter因此 Prime Agent 的换行/提交键语义会受影响。如果你仍希望在该终端中获得更好的光标体验可以在启动prime-agent前设置环境变量PI_HARDWARE_CURSOR1来显示硬件光标PI_HARDWARE_CURSOR1 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 的 ControlOptionArrow 快捷键冲突待发送消息pending message的排序默认使用ControlOptionUp上移与ControlOptionDown下移。Prime Agent 同时接受两类输入现代修饰键箭头序列Kitty CSI-u传统「Option 作为 Meta」包裹的ControlArrow序列。macOS 的VoiceOver使用ControlOption作为其修饰键系统或终端快捷键也可能在这些按键组合到达 Prime Agent 之前将其拦截。如果发生冲突可以在~/.prime/agent/keybindings.json中重映射app.message.moveEarlier与app.message.moveLater对应keybindings.md中默认的ctrlaltup与ctrlaltdown。配套方案tmux 中的修饰键恢复若在 tmux 中运行 Prime Agenttmux 默认会剥掉部分按键的修饰信息导致ShiftEnter与CtrlEnter退化为普通Enter。推荐在~/.tmux.conf中启用 CSI-u 格式的扩展键set -g extended-keys on set -g extended-keys-format csi-u然后完全重启 tmuxtmux kill-server tmux原理说明详见 tmux.md仅启用extended-keys on时tmux 默认使用 xtermmodifyOtherKeys格式例如CtrlC→\x1b[27;5;99~、CtrlEnter→\x1b[27;5;13~指定extended-keys-format csi-u后同样按键以 CSI-u 格式转发CtrlC→\x1b[99;5u、CtrlEnter→\x1b[13;5u这是最可靠的配置。对比无扩展键时的退化行为按键无扩展键启用csi-uEnter\r\rShiftEnter\r\x1b[13;2uCtrlEnter\r\x1b[13;5uAlt/OptionEnter\x1b\r\x1b[13;3u注意ShiftEnter与CtrlEnter在无扩展键时全部坍缩为\r这正是自定义修改 Enter 键绑定失效的根因。启用条件为tmux 3.2 及以上用tmux -V检查且终端模拟器支持扩展键Ghostty、Kitty、iTerm2、WezTerm、Windows Terminal 均可。键位自定义keybindings.json 速查Prime Agent 的所有键盘快捷键都可以通过~/.prime/agent/keybindings.json自定义每个动作可绑定一个或多个按键详见 keybindings.md。键格式为modifierkey修饰键支持ctrl、shift、alt自由组合如ctrlshiftaltx、ctrl1。与终端配置直接相关的核心动作默认值如下键绑定 ID默认键说明tui.input.submitenter提交输入tui.input.newLineshiftenter插入新行tui.editor.deleteWordBackwardctrlw,altbackspace删除上一个单词app.message.followUpaltenter排队追问消息app.message.moveEarlierctrlaltup上移待发送消息app.message.moveLaterctrlaltdown下移待发送消息修改keybindings.json后在 Prime Agent 内执行/reload即可热生效无需重启会话。老版本中未加命名空间的旧键 ID如cursorUp会在启动时自动迁移到新的命名空间格式。小结按终端速查表终端所需配置备注Kitty / iTerm2无开箱即用Ghosttyaltbackspacetext:\x1b\x7f删除旧的shiftentertext:\n映射WezTermconfig.enable_kitty_keyboard true写入~/.wezterm.luaVS Code 终端sendSequence发送\x1b[13;2u需terminalFocus限定Windows TerminalsendInput转发\x1b[13;2u与\x1b[13;3u需释放AltEnter全屏绑定xfce4-terminal / terminator不支持建议换 Kitty 协议终端IntelliJ 终端有限支持可用PI_HARDWARE_CURSOR1建议用独立终端tmuxextended-keys onextended-keys-format csi-u需 tmux 3.2配置完成后ShiftEnter换行、AltEnter追问排队、CtrlEnter提交等核心交互即可在 Prime Agent 中稳定工作。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 是一款面向编码工作流与长时间自治任务的 RLMRuntime Language ModelAgent其交互式 TUI 依赖终端对修饰键Modifier Key可靠检测来区分Enter、ShiftEnter、AltEnter等按键语义。本文以 terminal-setup.md 为主线系统梳理 Ghostty、WezTerm、VS Code 集成终端、Windows Terminal、xfce4-terminal、IntelliJ IDEA 等环境的配置方法并结合 packages/tui/src/keys.ts 的源码解析ShiftEnter换行、AltEnter排队追问、CtrlEnter提交等核心按键在底层是如何被识别的。读完本文你将掌握不同终端下让 Prime Agent 完整识别修饰键的具体配置、tmux 中恢复按键语义的最佳实践以及~/.prime/agent/keybindings.json的自定义方法。背景Prime Agent 为什么依赖 Kitty 键盘协议Prime Agent 使用Kitty 键盘协议Kitty keyboard protocol实现可靠的修饰键检测。该协议通过 CSI-uCSIu序列把「按键 修饰键 基础布局键」编码成无歧义的转义序列例如ShiftEnter编码为\x1b[13;2u、CtrlEnter编码为\x1b[13;5u、AltEnter编码为\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 与 iTerm2Kitty与iTerm2直接支持 Kitty 键盘协议无需任何额外配置即可让 Prime Agent 完整识别ShiftEnter、CtrlEnter、AltEnter等修饰键组合。Ghostty两处配置与一个易踩的坑Ghostty 需要在配置文件中增加一个键位映射才能在 macOS 与 Linux 下正常工作macOS 配置文件路径~/Library/Application Support/com.mitchellh.ghostty/configLinux 配置文件路径~/.config/ghostty/config向该文件追加以下内容keybind altbackspacetext:\x1b\x7f这条映射把AltBackspace显式发送为\x1b\x7fESC DEL对应 Prime Agent 中「删除上一个单词」的操作。在 packages/tui/src/keybindings.ts 第 112 行tui.editor.deleteWordBackward的默认键正是[ctrlw, altbackspace]而 packages/tui/src/keys.ts 第 914-922 行在处理altbackspace时也明确接受\x1b\x7f与\x1b\b两种传统序列。需要移除的旧版 Ghostty 映射早期 Claude Code 版本曾建议在 Ghostty 中增加如下映射keybind shiftentertext:\n这条映射会把ShiftEnter直接发送成原始的换行字节\n。在 Prime Agent 内部\n与CtrlJ的字节流完全一致见 packages/tui/src/keys.ts 第 873-876 行Kitty 协议激活时\n会被当作 Ghostty 的shiftenter映射处理因此 tmux 和 Prime Agent 都无法再收到真实的ShiftEnter键事件。如果你添加这条映射的唯一原因是 Claude Code那么可以放心删除它——除非你打算在 tmux 里使用 Claude Code那种场景下它仍然需要这条 Ghostty 映射。如果你希望在 tmux 中通过这条重映射继续使用ShiftEnter可以在 Prime Agent 的~/.prime/agent/keybindings.json中为newLine动作追加ctrlj作为备用键{ newLine: [shiftenter, ctrlj] }这样当 Ghostty 把ShiftEnter转成\n即等效于CtrlJ时Prime Agent 仍能触发换行。该配置使用的newLine即tui.input.newLine动作其默认绑定就是shiftenter见 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 集成终端让 ShiftEnter 支持多行输入VS Code 内置终端默认不把ShiftEnter转发给应用程序。需要在用户级keybindings.json中增加一条sendSequence绑定手动发送 CSI-u 序列\x1b[13;2u即ShiftEntermacOS~/Library/Application Support/Code/User/keybindings.jsonLinux~/.config/Code/User/keybindings.jsonWindows%APPDATA%\Code\User\keybindings.json{ key: shiftenter, command: workbench.action.terminal.sendSequence, args: { text: \u001b[13;2u }, when: terminalFocus }关键点when: terminalFocus保证该映射只在终端获得焦点时生效不会影响编辑器内的ShiftEnter行为\u001b[13;2u正是 packages/tui/src/keys.ts 中matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift)期望收到的 CSI-u 序列。配置完成后ShiftEnter在 Prime Agent 输入框中即可插入换行tui.input.newLine。Windows TerminalShiftEnter 与 AltEnter 的完整转发Windows Terminal 需要在settings.jsonCtrlShift,或 Settings → Open JSON file中把 Prime Agent 使用的修饰键 Enter 转发出去。在actions数组中追加两个sendInput动作{ actions: [ { command: { action: sendInput, input: \u001b[13;2u }, keys: shiftenter }, { command: { action: sendInput, input: \u001b[13;3u }, keys: altenter } ] }配置效果说明ShiftEnter插入新行发送\x1b[13;2u对应tui.input.newLine默认shiftenter。AltEnter排队追问Windows Terminal 默认把AltEnter绑定为全屏切换这会拦截 Prime Agent 接收AltEnter。将其重映射为sendInput发送\x1b[13;3u后真实的按键组合才会被转发给 Prime Agent用于app.message.followUp默认altenter见 keybindings.md 第 135 行。如果settings.json中已经存在actions数组直接把上述对象合并进去即可。若旧的全屏行为仍然生效请完全关闭并重新打开 Windows Terminal。受限终端xfce4-terminal 与 terminatorxfce4-terminal与terminator对转义序列的支持有限CtrlEnter、ShiftEnter等修饰键 Enter无法与普通Enter区分因此诸如submit: [ctrlenter]的自定义键绑定无法生效。对于这类终端最稳妥的方案是改用完整支持 Kitty 键盘协议的终端。仓库文档明确推荐以下选择KittyGhosttyWezTermiTerm2Alacritty需要编译时启用 Kitty 协议支持IntelliJ IDEA 集成终端建议改用独立终端模拟器IntelliJ IDEA 内置终端的转义序列支持同样有限无法区分ShiftEnter与Enter因此 Prime Agent 的换行/提交键语义会受影响。如果你仍希望在该终端中获得更好的光标体验可以在启动prime-agent前设置环境变量PI_HARDWARE_CURSOR1来显示硬件光标PI_HARDWARE_CURSOR1 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 的 ControlOptionArrow 快捷键冲突待发送消息pending message的排序默认使用ControlOptionUp上移与ControlOptionDown下移。Prime Agent 同时接受两类输入现代修饰键箭头序列Kitty CSI-u传统「Option 作为 Meta」包裹的ControlArrow序列。macOS 的VoiceOver使用ControlOption作为其修饰键系统或终端快捷键也可能在这些按键组合到达 Prime Agent 之前将其拦截。如果发生冲突可以在~/.prime/agent/keybindings.json中重映射app.message.moveEarlier与app.message.moveLater对应keybindings.md中默认的ctrlaltup与ctrlaltdown。配套方案tmux 中的修饰键恢复若在 tmux 中运行 Prime Agenttmux 默认会剥掉部分按键的修饰信息导致ShiftEnter与CtrlEnter退化为普通Enter。推荐在~/.tmux.conf中启用 CSI-u 格式的扩展键set -g extended-keys on set -g extended-keys-format csi-u然后完全重启 tmuxtmux kill-server tmux原理说明详见 tmux.md仅启用extended-keys on时tmux 默认使用 xtermmodifyOtherKeys格式例如CtrlC→\x1b[27;5;99~、CtrlEnter→\x1b[27;5;13~指定extended-keys-format csi-u后同样按键以 CSI-u 格式转发CtrlC→\x1b[99;5u、CtrlEnter→\x1b[13;5u这是最可靠的配置。对比无扩展键时的退化行为按键无扩展键启用csi-uEnter\r\rShiftEnter\r\x1b[13;2uCtrlEnter\r\x1b[13;5uAlt/OptionEnter\x1b\r\x1b[13;3u注意ShiftEnter与CtrlEnter在无扩展键时全部坍缩为\r这正是自定义修改 Enter 键绑定失效的根因。启用条件为tmux 3.2 及以上用tmux -V检查且终端模拟器支持扩展键Ghostty、Kitty、iTerm2、WezTerm、Windows Terminal 均可。键位自定义keybindings.json 速查Prime Agent 的所有键盘快捷键都可以通过~/.prime/agent/keybindings.json自定义每个动作可绑定一个或多个按键详见 keybindings.md。键格式为modifierkey修饰键支持ctrl、shift、alt自由组合如ctrlshiftaltx、ctrl1。与终端配置直接相关的核心动作默认值如下键绑定 ID默认键说明tui.input.submitenter提交输入tui.input.newLineshiftenter插入新行tui.editor.deleteWordBackwardctrlw,altbackspace删除上一个单词app.message.followUpaltenter排队追问消息app.message.moveEarlierctrlaltup上移待发送消息app.message.moveLaterctrlaltdown下移待发送消息修改keybindings.json后在 Prime Agent 内执行/reload即可热生效无需重启会话。老版本中未加命名空间的旧键 ID如cursorUp会在启动时自动迁移到新的命名空间格式。小结按终端速查表终端所需配置备注Kitty / iTerm2无开箱即用Ghosttyaltbackspacetext:\x1b\x7f删除旧的shiftentertext:\n映射WezTermconfig.enable_kitty_keyboard true写入~/.wezterm.luaVS Code 终端sendSequence发送\x1b[13;2u需terminalFocus限定Windows TerminalsendInput转发\x1b[13;2u与\x1b[13;3u需释放AltEnter全屏绑定xfce4-terminal / terminator不支持建议换 Kitty 协议终端IntelliJ 终端有限支持可用PI_HARDWARE_CURSOR1建议用独立终端tmuxextended-keys onextended-keys-format csi-u需 tmux 3.2配置完成后ShiftEnter换行、AltEnter追问排队、CtrlEnter提交等核心交互即可在 Prime Agent 中稳定工作。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考