前言¶

在 DSH 的 web GUI 里，部分常用操作原本需要反复用鼠标点击：聚焦输入框、新建会话、切换侧栏、切换详情面板、滚动对话、切换主题等。@blue-a11y/dsh-client-shortcuts 把这些浏览器内的 UI 动作注册成全局键盘快捷键，并提供一个设置页用于查看、录制、重置和校验组合键。

下面介绍它的定位、核心功能、安装方式、典型用法、开发构建和注意事项。

这是什么¶

@blue-a11y/dsh-client-shortcuts 是 blue-a11y 维护的 DeepSeek Harness web GUI 插件，许可证为 MIT。它是一个浏览器端 UI 插件，node half 刻意为空，整个功能都运行在浏览器侧。

它提供 ShortcutRegistry 服务，也就是 ctx.shortcuts。这个服务会在 window 上挂一个捕获阶段的 keydown 监听，并分发已注册的组合键。

它同时提供设置页：

• 注册于 settings.section；
• 基于 @deepseek-ai/dsh-client-ui-primitives 构建；
• 列出全部可绑定动作；
• 支持录制组合键、重置改键、冲突检测和保留组合键拦截。

该包声明了 dsh.bundle，属于组合包。package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml，安装后会激活其配置层。

这个插件只把浏览器键盘手势转发为 UI 动作，不触及任何模型请求。

核心功能¶

全局快捷键注册¶

核心服务是 ShortcutRegistry，即 ctx.shortcuts。它负责：

• 在 window 上监听捕获阶段 keydown；
• 解析和匹配已注册组合键；
• 分发到对应 UI 动作；
• 提供绑定注销能力。

mod 在 macOS 上匹配 Cmd，在其他平台匹配 Ctrl。文档和 UI 以 cmd 友好形式书写组合键，例如 cmd 与 mod 在组合键表达中按约定对应处理。

文本输入框保护¶

默认情况下，焦点在文本输入框内时会放行键盘事件，避免影响正常输入。

如果某个绑定显式声明输入框内可用，它才会在输入框内响应。

可绑定动作¶

插件列出全部可绑定动作，包括：

• 聚焦输入框；
• 新建会话；
• 切换侧栏；
• 切换详情面板；
• 上一个会话；
• 下一个会话；
• 切换浅色/深色主题；
• 滚动到对话顶部；
• 滚动到对话底部；
• 分叉当前会话。

其中，没有安全默认值的动作默认不绑定。用户可以在设置页录制组合键启用，也可以重置回未绑定状态。

会话切换顺序¶

会话切换镜像侧栏的完整显示顺序，会跳过「新建任务」空白条目和归档会话，并在两端循环。也就是说，最后一个会话继续切换时会回到第一个可用会话，第一个会话反向切换时会回到最后一个可用会话。

改键与冲突检测¶

设置页支持：

• 录制新的组合键；
• 重置为未绑定；
• 校验与现有绑定是否冲突；
• 拒绝浏览器保留组合键；
• 拒绝 macOS 的 Option/Alt 改写组合。

浏览器保留组合键会在页面监听器执行 preventDefault 之前被浏览器消费，web 插件无法绑定。macOS 的 Option/Alt 改写组合可能导致 event.key 与注册键不再匹配，因此设置页会拒绝这类组合。

改键生命周期¶

改键仅在插件 fiber 生命周期内有效。刷新页面后会恢复默认状态，当前不会持久化保存用户改键结果。

安装与启用¶

前置条件¶

先安装 dsh CLI：

npm i -g @deepseek-ai/dsh

然后确保运行环境满足：

• Node 22.19 或更高版本；
• pnpm 可用。

从 npm 安装¶

推荐从 npm 安装：

dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts

该包是组合包，安装后会激活其配置层。

本地 checkout 安装¶

开发期可以安装本地目录：

dsh plugin --profile web add ./dsh-client-shortcuts

打包产物安装¶

如果有打包产物，也可以使用 tarball：

dsh plugin --profile web add ./dsh-client-shortcuts-0.1.0.tgz

重启与验证¶

新增插件行后，需要重启一次 dsh web，因为插件行发现在每次启动时缓存。

先查看配置：

dsh --profile web --dump-config

配置中应能看到 id: shortcuts 行。

然后启动 web GUI：

dsh web

浏览器打开后，进入「设置 → 快捷键」，应能看到快捷键设置页。

更新与卸载¶

更新时重新执行安装命令：

dsh plugin --profile web add @blue-a11y/dsh-client-shortcuts

如果需要锁定版本，需指定版本号。

卸载命令：

dsh plugin --profile web remove @blue-a11y/dsh-client-shortcuts

卸载会同时移除相关依赖与配置层。

pnpm 构建授权¶

如果使用 pnpm 10 或更高版本，可能需要在 pnpm-workspace.yaml 的 allowBuilds 中一次性授权 profile。

典型用法¶

打开设置页¶

启动 dsh web 后，在浏览器中进入：

设置 → 快捷键

设置页会列出全部可绑定动作，并展示当前组合键与触发计数。

录制组合键¶

对于默认未绑定的动作，可以在设置页使用录制控件按下想要绑定的组合键。

录制控件会暂停注册中心分发，按下的组合键会被捕获而不是直接触发。设置页会校验该组合键是否与现有绑定冲突，并拒绝非法或保留组合键。

重置组合键¶

如果某个动作不再需要自定义键位，可以重置，使其清回未绑定状态。

会话切换¶

绑定会话切换动作后，快捷键会按侧栏的完整显示顺序移动，跳过「新建任务」空白条目和归档会话，并在首尾之间循环。

不触及模型请求¶

这些快捷键只用于浏览器内的 UI 操作。插件不会发起模型请求，也不会改变模型调用路径。

开发与构建¶

克隆仓库¶

git clone https://github.com/blue-a11y/dsh-client-shortcuts.git
cd dsh-client-shortcuts
pnpm install

常用命令¶

pnpm install
pnpm run build
pnpm test

pnpm run build 会生成构建产物，pnpm test 会运行测试。

本地热更新¶

本地开发时，可以先安装本地目录：

dsh plugin --profile web add ./dsh-client-shortcuts

修改源码并重新构建后，client HMR 链路可以自动换新模块。只有新增或删除插件行时，才需要重启 dsh web。

依赖关系¶

该包的 peer dependencies 包含：

@deepseek-ai/cordis ^4.0.1
@deepseek-ai/dsh-invariants ^0.1.0-rc.6

适用场景与注意¶

适合谁使用¶

适合使用 dsh web 并希望减少鼠标操作的开发者，尤其是：

• 需要频繁聚焦输入框；
• 需要快速新建会话；
• 需要频繁切换侧栏或详情面板；
• 需要在多个会话之间快速移动；
• 需要快速滚动到对话顶部或底部；
• 需要对浏览器 UI 动作做轻量自定义。

它适合放在 DSH 的插件化工作流中，作为 web GUI 的键盘增强插件使用。这里介绍的插件来自独立社区目录，不是 DeepSeek 或幻方官方应用商店。

安全注意¶

该插件会加入当前 dsh 的 web profile 配置层，并随当前 dsh 进程加载运行。安装前应检查源码、许可证和依赖关系。

该插件许可证为 MIT。它只处理浏览器键盘事件和 UI 动作，不触及模型请求，但任何第三方插件都应在使用前确认其来源和构建产物。

行为边界¶

需要注意以下边界：

• 改键不会持久化，刷新页面后恢复默认；
• 焦点在输入框内时默认放行，除非绑定声明输入框内可用；
• 浏览器保留组合键无法被 web 插件绑定；
• macOS 的 Option/Alt 改写组合会被设置页拒绝；
• 聚焦输入框依赖 [data-phase] DOM 查询，因为当前没有 composer 暴露聚焦服务；
• 新增插件行后需要重启一次 dsh web。

结尾¶

@blue-a11y/dsh-client-shortcuts 的价值比较集中：它为 dsh web 提供一组可绑定的 UI 快捷键，并提供可录制、可重置、可校验的设置页。它不改变模型请求链路，只优化浏览器内的操作路径。

仓库地址：

https://github.com/blue-a11y/dsh-client-shortcuts