oh-my-pi 键位绑定完全指南用/hotkeys与keybindings.yml定制 Coding Agent 的每一个快捷键【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇指南围绕 oh-my-piompCoding Agent 的键盘快捷键体系展开如何在会话内用/hotkeys查看当前构建实际生效的键位组合如何通过用户级~/.omp/agent/keybindings.yml逐项重映射动作以及剪贴板粘贴、语音输入、命名 Profile 继承等平台相关细节与底层实现原理。读完本文你将能独立完成从查看当前快捷键到编写自己的键位配置文件再到理解旧版键位名迁移与冲突处理的完整闭环。一、开场/hotkeys查看当前生效的键位oh-my-pi 的 TUI 界面将每一个可操作动作如切换模型、打开计划模式、搜索历史抽象为带命名空间的Action ID再通过一个全局键位注册表把 Action ID 映射到具体的按键组合chord。要查看你的构建实际加载了哪些键位只需在omp会话中输入/hotkeys该命令会以 Markdown 面板的形式弹出一份Keyboard Shortcuts清单内容由 packages/coding-agent/src/modes/utils/hotkeys-markdown.ts 中的buildHotkeysMarkdown()动态生成——它通过KeybindingsManager.getDisplayString(action)读取合并了用户重映射后的最终键位并格式化输出因此你看到的不是静态文档而是默认值 磁盘重映射 扩展新增绑定三者叠加后的真实结果。命令本身注册于 packages/coding-agent/src/slash-commands/builtin-session.ts#L387-L395描述为 Show all keyboard shortcuts图标为keyboard。在协同会话collab中/hotkeys也被列入客户端本地白名单见 docs/collab.md属于无需宿主授权即可运行的只读命令。值得注意的一点是该面板中的按键标签是平台感知的——在 macOS 上修饰键alt/super会被渲染为Option/Cmd对应源码中modifierLabel()的实现见 packages/coding-agent/src/config/keybindings.ts#L695-L706保证提示与你手头的实体键盘一致。二、自定义键位keybindings.yml2.1 文件位置与格式约定用户级重映射存放在~/.omp/agent/keybindings.yml。需要特别注意以下几点约定否则配置不会生效文件是一个YAML 映射键是键位动作的 Action ID值是一个按键串或按键串数组它不会从~/.omp/agent/config.yml中读取也没有嵌套的keybindings对象——不要把键位配置写进通用配置文件按键串大小写不敏感使用与 UI 中相同的记法例如CtrlP、AltShiftP、ShiftEnter、CtrlBackspace。最小可用的自定义示例含义见下文常见 Action ID 表app.model.cycleForward: CtrlP app.model.selectTemporary: AltP app.plan.toggle: AltShiftP2.2 禁用某个动作将某个动作设为空数组即可完全禁用该键位app.history.search: []从源码看KeybindingsManager在解析用户配置时会把空数组规约为空键列表normalizeKeys对空数组返回[]动作仍然存在、只是不再匹配任何按键/hotkeys面板中则会显示为 Disabled见 packages/coding-agent/src/modes/utils/hotkeys-markdown.ts#L7-L9。2.3 加载与校验的底层实现配置文件的实际加载发生在 packages/coding-agent/src/config/keybindings.tsresolveKeybindingsConfigPaths()按优先级查找keybindings.yml→keybindings.yaml→ 旧版keybindings.jsonL434-L451解析使用 Bun 内建的YAML.parse旧版 JSON 则用JSONC.parse兼容注释与尾逗号loadRawConfigL404-L421配置值既支持单个字符串也支持字符串数组toKeybindingsConfigL321-L337KeybindingsManager.create()是标准的入口读取合并后的配置构造管理器并通过setKeybindings()注册为全局实例L587-L593。在 TUI 底层packages/tui/src/keybindings.ts 的KeybindingsManager负责三件事把每个 Action ID 解析为一组规范化的键 IDcanonicalKeyId会统一大小写、把esc归一为escape、return归一为enter并自动为裸大写字母补shift修饰见 L190-L220为每个键生成匹配集合含符号键的shift别名见addKeyAliases以及冲突检测——如果用户把同一个键分配给了两个动作getConflicts()会将其记录为KeybindingConflictL247-L338。2.4 命名 Profile 下的继承规则当使用命名 Profile 时omp --profile name键位是唯一一个做合并而非完全隔离的配置项docs/config-usage.md 中有明确说明先加载默认 Profile agent 目录~/.omp/agent/keybindings.yml中的绑定再用活动 Profile 自己的~/.omp/profiles/name/agent/keybindings.yml逐 Action 覆盖合并逻辑见mergeKeybindingsConfigL453-L458。背后的设计理由是键盘绑定描述的是用户面前的终端/键盘它不会随活动 Profile 改变因此用户级重映射在每一个 Profile 中都持续生效除非该 Profile 显式覆盖。另一个重要约束是继承来的默认 Profile 键位文件在命名 Profile 进程中是只读的——旧格式的迁移写回只会发生在默认 Profile 自身启动时命名 Profile 进程绝不允许把迁移结果写回默认 Profile 的目录相关注释见 L483-L487。三、常见 Action ID 速查表下表为本文档整理的常用动作 ID 及其默认键位完整覆盖了文档给出的全部条目。注意 macOS 上Alt对应键盘的OptionCmd源码中的super同样可用。Action ID默认键位含义app.model.cycleForwardCtrlP向前循环角色模型app.model.cycleBackwardShiftCtrlP向后循环角色模型app.model.selectTemporaryAltP为当前会话临时挑选一个模型app.model.selectAltM打开模型选择器并设置角色app.plan.toggleAltShiftP切换计划模式app.history.searchCtrlR搜索提示词历史app.tools.expandCtrlO切换工具输出展开app.tools.toggleVisibilityCtrlShiftO显示或隐藏工具活动app.thinking.toggleCtrlT切换思考块可见性app.thinking.cycleShiftTab循环思考级别app.editor.externalCtrlG在$VISUAL/$EDITOR中编辑草稿app.message.followUpCtrlQ、CtrlEnter排队一条后续消息app.message.dequeueAltUp、ShiftUp把排队的消息取回编辑器app.retryAltR重试最后失败的助手回合app.display.resetAltL重置终端显示app.clipboard.copyLineAltShiftL复制当前行app.clipboard.copyPromptAltShiftC复制整个提示词app.clipboard.pasteTextRawCtrlShiftV、AltShiftV不折叠地粘贴剪贴板文本app.clipboard.pasteImageLinuxCtrlVmacOSCtrlV、CmdVWindowsCtrlV、AltV从剪贴板粘贴优先图片文本兜底app.stt.toggle未绑定按住Space切换语音转文字。默认没有按键组合——按住空格录音push-to-talk、松开转写在此处绑定一个组合键可改为按一下切换app.live.toggleCtrlL启动或停止实时语音模式等同/liveapp.agents.hubAltA打开 Agent Hub见 docs/agent-hub.md表格中默认键位定义可以在 packages/coding-agent/src/config/keybindings.ts#L79-L241 的KEYBINDINGS常量中逐一核对。两个细节值得注意app.retry的默认键实际是F5与AltR双绑定——源码注释说明F5会被每个终端原样传递而Ctrl/Alt/CmdEnter这类带修饰符的 Enter 组合常被各种终端吞掉或折叠为普通 EnterL144-L150app.message.dequeue同时绑定AltUp与ShiftUp因为 macOS Terminal.app 会占用 Option 做字符组合使AltUp不可达L151-L156。四、平台特例与剪贴板粘贴细节4.1 Windows Terminal 的两个吞键问题Windows Terminal 会在omp之前拦截部分按键需要依赖兜底键位CtrlV可能被终端粘贴命令先行处理。当剪贴板图片粘贴看起来无效时使用AltV兜底。CtrlEnter同样被 Windows Terminal 吞掉因此app.message.followUp同时绑定了CtrlQ——这也是 GitHub Copilot CLI 使用的同一组合键同一组合键还会提交 agent 仪表盘的新 Agent 描述与 hook 编辑器提示。冲突优先级如果你现有的keybindings.yml已把CtrlQ分配给其他动作那么用户重映射优先此时 follow-up 保留CtrlEnter除非你显式把app.message.followUp绑定到其他键。源码中的getFallbackKey()与userBindingClaimsKey()正是为此设计的默认情况下若用户占用了兜底键则从默认键列表中去掉该键避免冲突packages/coding-agent/src/config/keybindings.ts#L528-L625。4.2 剪贴板粘贴的文本兜底与图片加载当剪贴板中没有图片时app.clipboard.pasteImage会改为粘贴剪贴板文本。因此只发送单一组合键的宿主环境配置为转发CtrlV的 VS Code 集成终端、Windows 剪贴板历史的WinV等可以同时覆盖图片与文本两种负载。平台默认键位由getDefaultPasteImageKeys()按平台返回WindowsCtrlV/AltVmacOSCtrlV/CmdV其余CtrlV见 packages/coding-agent/src/config/keybindings.ts#L70-L74。4.3 OSC 5522 增强粘贴协议实现了OSC 5522 enhanced paste的终端可以直接把剪贴板 MIME 数据发送给omp图片粘贴会被附加为[Image #N]text/plain粘贴事件保持普通粘贴行为。当 OSC 5522 不可用时bracketed paste括号粘贴仍然负责文本此时如果粘贴的是一个单图片文件路径且该文件在omp宿主机上可读该路径会被加载为图片。五、旧版键位名迁移与文件格式演进键位体系经历过一轮命名空间化重构因此文档和配置都有一套明确的兼容策略旧的无限定动作名在加载keybindings.yml时会被自动迁移。迁移映射表KEYBINDING_NAME_MIGRATIONS覆盖了几乎所有历史名称例如cycleModelForward→app.model.cycleForward、togglePlanMode→app.plan.toggle、toggleSTT→app.stt.toggle、followUp→app.message.followUp以及整套 TUI 编辑器的旧名cursorUp→tui.editor.cursorUp、yank→tui.editor.yank等packages/coding-agent/src/config/keybindings.ts#L246-L312新文档与新配置应一律使用命名空间 Action ID上表形式不再使用旧名旧版keybindings.json文件仍然被接受读取后迁移并写回为keybindings.ymlkeybindings.yaml扩展名同样被接受。写回前配置会按KEYBINDINGS的键顺序重排orderKeybindingsConfig保证文件整洁且可预测L368-L383。迁移的两种路径默认 Profile 启动时旧 JSON 被读取 → 名称迁移 → 按顺序写出到keybindings.yml原 JSON 保留。命名 Profile 启动时从默认 Profile 继承的文件只读名称迁移仅在内存中执行磁盘迁移要等默认 Profile 自身下次启动才发生——这是为了防止命名 Profile 进程意外修改用户级共享配置。六、结语从查到配到懂至此你已经掌握了 oh-my-pi 键位体系的完整脉络查会话内执行/hotkeys看到的是默认值叠加用户重映射与扩展绑定后的真实结果且标签随平台自适应macOS 显示 Option/Cmd配编辑~/.omp/agent/keybindings.yml用 YAML 映射逐 Action 覆盖或禁用键位命名 Profile 下默认 Profile 的绑定先加载、活动 Profile 按动作覆盖继承文件只读懂底层KeybindingsManagerpackages/tui/src/keybindings.ts负责键位规范化、别名匹配与冲突检测应用层扩展了平台默认键、兜底键冲突仲裁与旧名迁移packages/coding-agent/src/config/keybindings.ts。配置好符合自己肌肉记忆的键位后模型切换、计划模式、历史搜索乃至语音输入都将尽在指尖。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考