• src/index.ts(node 半边)——注册 ui-shortcuts 设置命名空间。
• src/client/(浏览器半边,/plugins/ui-shortcuts/client.js)——按键接线与 设置 → 插件 里的快捷键卡片。

行 id ui-shortcuts 与官方 @deepseek-ai/dsh-client-ui-shortcuts bundle 同名——一个 profile 里最多组合其一(重复 loader id 会在启动时 fail loud);官方默认镜像不挂载任何一方,上文的一条命令安装即常规路径。

动作全部走公开服务,从不触及 ui-conversation 内部:

重绑:点击键位录制下一个组合键(Esc 取消,Delete/Backspace 解绑,Ctrl/Cmd 在所有平台都计为一个 primary 修饰键),或恢复默认。偏好持久化在 $DSH_HOME/settings.yaml 的 ui-shortcuts 小节。

Escape 分层:Escape 暂停是全局的,但让位于先消费该键的一方:已被消费的 keydown(defaultPrevented——composer 的斜杠菜单、popupSelect)、打开的弹层(模态框、菜单、设置面板)、以及 composer 之外的可编辑目标(行内重命名、搜索框)。其余任何位置——composer 文本框、侧边栏、会话列表——Escape 都会暂停运行中的回合。IME 组合输入与按住重复的按键不会触发任一动作。

给插件作者——通过 ctx.shortcuts 注册表贡献动作:

ctx.effect(() => ctx.shortcuts.registerAction({
  id: 'my-plugin.myAction',          // 唯一 id,惯例 <插件>.<动作>
  label: { ns: 'my-plugin', key: 'action.myAction' },
  description: { ns: 'my-plugin', key: 'action.myAction.desc' },
  defaultBinding: { kind: 'key', modifiers: ['primary', 'shift'], key: 'o' },
  layering: 'global',                // 'global':capture 阶段,抑制浏览器默认
                                     // 'yield':bubble 阶段,让位于已消费按键/打开的弹层/可编辑目标
  available: () => true,             // 可选的分发时门禁
  run: () => { /* ... */ },
}), 'my-plugin: shortcut')

贡献项的文案留在贡献方自己的 locale 命名空间。id 重复会 loud 报错;多个动作共享同一组合键时先注册者生效。用户可在 设置 → 插件 → 快捷键 重绑或解绑任何动作。无模型请求、无 KV cache 影响——这些动作调用的正是 composer 自身控件使用的公开动词。