按键绑定

所有键盘快捷键都可以通过 ~/.pi/agent/keybindings.json 自定义。每个操作都可以绑定一个或多个按键。

配置文件使用的，是 Pi 内部同样一套带命名空间的 keybinding id。扩展作者在 keyHint() 和注入的 keybindings 管理器中，也使用这一套。

使用旧版未带命名空间 id（例如 cursorUp 或 expandTools）的旧配置，会在启动时自动迁移为带命名空间的 id。

编辑完 keybindings.json 后，在 Pi 里运行 /reload，即可应用更改，无需重启会话。

按键格式

modifier+key，其中修饰键是 ctrl、shift、alt（可组合），按键包括：

• 字母： a-z
• 数字： 0-9
• 特殊按键： escape、esc、enter、return、tab、space、backspace、delete、insert、clear、home、end、pageUp、pageDown、up、down、left、right
• 功能键： f1-f12
• 符号： `、-、=、[、]、\、;、'、,、.、/、!、@、#、$、%、^、&、*、(、)、_、+、|、~、{、}、:、<、>、?

修饰键组合：ctrl+shift+x、alt+ctrl+x、ctrl+shift+alt+x、ctrl+1 等。

全部操作

TUI 编辑器光标移动

TUI 编辑器删除

TUI 输入

TUI 剪切环

TUI 剪贴板与选择

TUI 全屏视口

这些操作在交互模式使用 --tui-mode fullscreen 时生效，作用于主要的转录滚动区域。双指触控板和鼠标滚轮会滚动指针所在区域；如果指针位于固定的编辑器/状态/底部栏上，则回退为滚动转录区域。点击 OSC 8 超链接会使用默认处理程序打开。按住鼠标左键拖动可以选择文本并复制到剪贴板；停留在转录区域顶部或底部边缘时会自动滚动到屏幕外内容。终端专属的鼠标和触控板行为见终端设置。

全屏转录绑定优先于编辑器绑定。因此，在全屏模式下，默认的未修饰导航键控制转录，而对应的 ctrl 变体继续控制编辑器；在全屏之外，两种变体都控制编辑器。

该路由仍可通过普通操作绑定配置。例如，"tui.altScreen.pageUp": "ctrl+pageUp" 会让全屏模式下的 pageUp 控制编辑器、ctrl+pageUp 控制转录。可以绑定 tui.altScreen.halfPageUp 和 tui.altScreen.halfPageDown 实现半页移动，或绑定 tui.altScreen.lineUp 和 tui.altScreen.lineDown 实现单行移动。将 "tui.altScreen.pageUp": [] 设为空数组，可以完全禁用该转录快捷键。用户绑定会替换该操作的默认值。

应用

会话

模型与思考

显示与消息队列

树导航

---

作用域模型选择器

在作用域模型选择器中使用（通过 /scoped-models 打开）。

自定义配置

创建 ~/.pi/agent/keybindings.json：

{
  "tui.editor.historyPrevious": "ctrl+p",
  "tui.editor.historyNext": "ctrl+n",
  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}

每个动作都可以配置单个按键或按键数组。用户配置会覆盖默认值。

在原生 Windows 上，app.suspend 默认没有绑定，因为 Windows 终端不支持 Unix 的作业控制。如果你手动绑定它，Pi 会显示状态消息，而不是挂起。在 WSL 中，Linux 下正常的 ctrl+z/fg 行为仍然适用。

Emacs 示例

{
  "tui.editor.historyPrevious": "ctrl+p",
  "tui.editor.historyNext": "ctrl+n",
  "tui.editor.cursorLeft": ["left", "ctrl+b"],
  "tui.editor.cursorRight": ["right", "ctrl+f"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
  "tui.input.newLine": ["shift+enter", "ctrl+j"]
}

Vim 示例

{
  "tui.editor.cursorUp": ["up", "alt+k"],
  "tui.editor.cursorDown": ["down", "alt+j"],
  "tui.editor.cursorLeft": ["left", "alt+h"],
  "tui.editor.cursorRight": ["right", "alt+l"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
}