10 键盘快捷键

10.1 概述

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

配置文件使用与 Pi 内部相同的命名空间化快捷键 ID。旧版配置中使用非命名空间 ID（如 cursorUp 或 expandTools）的条目会在启动时自动迁移到命名空间版本。

Tip

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

10.2 按键格式

快捷键使用 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 等。

10.3 所有操作

10.3.1 编辑器光标移动

ID	默认按键	描述
`tui.editor.cursorUp`	`up`	光标上移
`tui.editor.cursorDown`	`down`	光标下移
`tui.editor.cursorLeft`	`left`、`ctrl+b`	光标左移
`tui.editor.cursorRight`	`right`、`ctrl+f`	光标右移
`tui.editor.cursorWordLeft`	`alt+left`、`ctrl+left`、`alt+b`	光标左移一个单词
`tui.editor.cursorWordRight`	`alt+right`、`ctrl+right`、`alt+f`	光标右移一个单词
`tui.editor.cursorLineStart`	`home`、`ctrl+a`	移动到行首
`tui.editor.cursorLineEnd`	`end`、`ctrl+e`	移动到行尾
`tui.editor.jumpForward`	`ctrl+]`	向前跳转到字符
`tui.editor.jumpBackward`	`ctrl+alt+]`	向后跳转到字符
`tui.editor.pageUp`	`pageUp`	上翻一页
`tui.editor.pageDown`	`pageDown`	下翻一页

10.3.2 编辑器删除

ID	默认按键	描述
`tui.editor.deleteCharBackward`	`backspace`	向后删除字符
`tui.editor.deleteCharForward`	`delete`、`ctrl+d`	向前删除字符
`tui.editor.deleteWordBackward`	`ctrl+w`、`alt+backspace`	向后删除单词
`tui.editor.deleteWordForward`	`alt+d`、`alt+delete`	向前删除单词
`tui.editor.deleteToLineStart`	`ctrl+u`	删除到行首
`tui.editor.deleteToLineEnd`	`ctrl+k`	删除到行尾

10.3.3 编辑器输入

ID	默认按键	描述
`tui.input.newLine`	`shift+enter`、`ctrl+j`	插入新行
`tui.input.submit`	`enter`	提交输入
`tui.input.tab`	`tab`	Tab / 自动补全

Note

在 Windows Terminal 上，多行输入使用 Ctrl+Enter，因为 Shift+Enter 可能被终端拦截。

10.3.4 Kill Ring

ID	默认按键	描述
`tui.editor.yank`	`ctrl+y`	粘贴最近删除的文本
`tui.editor.yankPop`	`alt+y`	在删除文本历史中循环
`tui.editor.undo`	`ctrl+-`	撤销上次编辑

Tip

Kill Ring 机制源自 Emacs。当你用 ctrl+w 或 ctrl+k 删除文本后，可以用 ctrl+y 粘贴回来，然后用 alt+y 在多个删除条目间循环切换。

10.3.5 剪贴板与选择

ID	默认按键	描述
`tui.input.copy`	`ctrl+c`	复制选中文本
`tui.select.up`	`up`	选择上移
`tui.select.down`	`down`	选择下移
`tui.select.pageUp`	`pageUp`	列表上翻
`tui.select.pageDown`	`pageDown`	列表下翻
`tui.select.confirm`	`enter`	确认选择
`tui.select.cancel`	`escape`、`ctrl+c`	取消选择

10.3.6 备用屏幕视口

以下操作在使用 --alt 启动交互模式时生效，针对主对话记录滚动区域。

ID	默认按键	描述
`tui.altScreen.pageUp`	`shift+pageUp`	向上滚动一页
`tui.altScreen.pageDown`	`shift+pageDown`	向下滚动一页
`tui.altScreen.top`	`ctrl+home`	滚动到对话记录开头
`tui.altScreen.bottom`	`ctrl+end`	滚动到末尾并跟随新输出

Note

使用 --alt 时，对话记录在终端视口内滚动，而排队的消息、工作状态、扩展小部件、编辑器和页脚保持固定在底部。鼠标/触控板输入滚动指针下方的区域。

10.3.7 应用级操作

ID	默认按键	描述
`app.interrupt`	`escape`	取消/中止
`app.clear`	`ctrl+c`	清空编辑器
`app.exit`	`ctrl+d`	退出（编辑器为空时）
`app.suspend`	`ctrl+z`（Windows 无）	挂起到后台
`app.editor.external`	`ctrl+g`	打开外部编辑器
`app.clipboard.pasteImage`	`ctrl+v`（Windows 为 `alt+v`）	粘贴剪贴板图片

10.3.8 会话操作

ID	默认按键	描述
`app.session.new`	(无)	开始新会话（`/new`）
`app.session.tree`	(无)	打开会话树导航（`/tree`）
`app.session.fork`	(无)	分叉当前会话（`/fork`）
`app.session.resume`	(无)	打开会话恢复选择器（`/resume`）
`app.session.togglePath`	`ctrl+p`	切换路径显示
`app.session.toggleSort`	`ctrl+s`	切换排序模式
`app.session.toggleNamedFilter`	`ctrl+n`	切换命名会话过滤器
`app.session.rename`	`ctrl+r`	重命名会话
`app.session.delete`	`ctrl+d`	删除会话
`app.session.deleteNoninvasive`	`ctrl+backspace`	查询为空时删除会话

10.3.9 模型与思考

ID	默认按键	描述
`app.model.select`	`ctrl+l`	打开模型选择器
`app.model.cycleForward`	`ctrl+p`	循环到下一个模型
`app.model.cycleBackward`	`shift+ctrl+p`	循环到上一个模型
`app.thinking.cycle`	`shift+tab`	切换思考级别
`app.thinking.toggle`	`ctrl+t`	折叠/展开思考块

10.3.10 显示与消息队列

ID	默认按键	描述
`app.tools.expand`	`ctrl+o`	折叠/展开工具输出
`app.message.copy`	`ctrl+x`	复制最后的助手消息，或在 `/tree` 中复制选中消息
`app.message.followUp`	`alt+enter`	排队后续消息
`app.message.dequeue`	`alt+up`	将排队消息恢复到编辑器

10.3.11 树导航

ID	默认按键	描述
`app.tree.foldOrUp`	`ctrl+left`、`alt+left`	折叠当前分支段，或跳到上一段开始
`app.tree.unfoldOrDown`	`ctrl+right`、`alt+right`	展开当前分支段，或跳到下一段开始或分支结束
`app.tree.editLabel`	`shift+l`	编辑选中节点的标签
`app.tree.toggleLabelTimestamp`	`shift+t`	切换标签时间戳
`app.tree.filter.default`	`ctrl+d`	设置过滤器为默认视图
`app.tree.filter.noTools`	`ctrl+t`	切换隐藏工具结果的过滤器
`app.tree.filter.userOnly`	`ctrl+u`	切换仅显示用户消息的过滤器
`app.tree.filter.labeledOnly`	`ctrl+l`	切换仅显示标记条目的过滤器
`app.tree.filter.all`	`ctrl+a`	切换显示所有条目的过滤器
`app.tree.filter.cycleForward`	`ctrl+o`	向前循环过滤器
`app.tree.filter.cycleBackward`	`shift+ctrl+o`	向后循环过滤器

10.3.12 作用域模型选择器

在通过 /scoped-models 打开的作用域模型选择器中使用：

ID	默认按键	描述
`app.models.save`	`ctrl+s`	保存当前模型选择到设置
`app.models.enableAll`	`ctrl+a`	启用所有模型（或匹配当前搜索的所有模型）
`app.models.clearAll`	`ctrl+x`	清除所有模型（或匹配当前搜索的所有模型）
`app.models.toggleProvider`	`ctrl+p`	切换当前提供商的所有模型
`app.models.reorderUp`	`alt+up`	上移选中的模型（循环顺序中）
`app.models.reorderDown`	`alt+down`	下移选中的模型（循环顺序中）

10.4 自定义配置

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

{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "ctrl+n"],
  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}

每个操作可以绑定单个按键或按键数组。用户配置覆盖默认值。

Note

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

10.4.1 Emacs 风格配置示例

{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "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"]
}

10.4.2 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"]
}

Tip

使用 /hotkeys 命令可以在 Pi 中随时查看当前所有快捷键绑定，包括你的自定义配置。