melt502/dsh-hotkey

dsh-hotkey

DSH Desktop
License: MIT

为 DSH Desktop Web GUI 提供可配置的 VS Code 风格键盘快捷键，并带有设置页按键绑定编辑器、冲突检测以及 JSON 导入/导出功能。

为 DSH Desktop Web GUI 提供可配置、VS Code / Codex 风格的键盘快捷键，并在设置页内直接改键。

English · 中文

English

dsh-hotkey 为常见的工作台操作添加快捷键入口，并在 设置 → 键盘快捷键 下提供一个可视化的按键绑定编辑器。每个操作都优先通过服务 API 解析，失败时回退到 DOM 交互，因为 DSH 客户端插件是异步注册其服务的，当快捷键插件激活时，某个服务可能尚不存在。

前置条件： Ctrl+Alt+V（切换 Vision 模式）需要 dsh-vision-router 插件，右侧边栏快捷键（ Ctrl+ 、Ctrl+J、Ctrl+Alt+B、Ctrl+Shift+E、Ctrl+Shift+G、Alt+E）需要 dsh-better-sidebar 插件。请先安装它们，否则这些绑定在设置页中会显示为不可用。参见前置插件表。

前置插件

部分快捷键所驱动的功能由其他 DSH 插件提供。请先安装对应的插件；否则受影响的绑定在设置页中将保持不可用。

| 插件 | 提供 | 解锁的快捷键 |
| --- | --- | --- |
| dsh-vision-router | 输入框中的 Vision 模式切换按钮 | Ctrl+Alt+V — 切换 Vision 模式 |
| dsh-better-sidebar | 承载终端、文件、Git、Side Chat 以及底部面板的右侧边栏 |  Ctrl+  Ctrl+J Ctrl+Alt+B Ctrl+Shift+E Ctrl+Shift+G Alt+E |

这两个插件都是可选的——其他所有快捷键在没有它们的情况下均可正常工作。

功能特性

- 20 个操作，默认绑定 16 个
- 在 设置 → 键盘快捷键 下可重新绑定、禁用、重置单个或全部重置
- 冲突检测；发生冲突时，表格中靠前的操作优先
- 整个键位映射的 JSON 导入/导出
- 持久化到 DSH 设置作用域（命名空间 hotkey）
- 跟随 DSH 界面语言（中文 / 英文）
- 右侧边栏键盘导航：↑ / ↓ 在可见按钮之间移动，Enter 点击
- 两阶段 Side Chat：Alt+E 先展开右侧边栏，然后打开或创建聊天
- Vision 模式切换：Ctrl+Alt+V 点击 dsh-vision-router 输入框按钮，以打开或关闭 Vision 模式
- 服务优先并带 DOM 回退，因此延迟注册的服务不会导致快捷键失效

默认按键绑定

| 按键 | 操作 | 备注 |
| --- | --- | --- |
| Ctrl+B | 切换左侧边栏 | 会话 / 工作区列 |
| Ctrl+  | 打开 / 聚焦终端 | 右侧终端标签页 |
| Ctrl+J | 切换底部面板 | 底部终端 / 面板 |
| Ctrl+Alt+B | 切换右侧边栏 | 承载文件、Git、侧边聊天的侧边卡片 |
| Ctrl+Shift+E | 文件 / 编辑器 | 打开文件标签页 |
| Ctrl+Shift+G | Git 面板 | 打开源代码管理标签页 |
| Alt+E | 侧边聊天 | 展开右侧边栏，然后打开聊天 |
| Ctrl+Alt+V | 切换 Vision 模式 | 点击 dsh-vision-router 按钮（需要 dsh-vision-router） |
| Ctrl+F | 打开新工作区 | 打开“添加工作区”选择器 |
| Ctrl+N | 新建会话 | 在当前工作区中新建会话 |
| Enter | 批准 | 仅在批准卡片可见时 |
| Esc | 拒绝 | 仅在批准卡片可见时 |
| Ctrl+[ | 上一个会话 | 会话列表导航 |
| Ctrl+] | 下一个会话 | 会话列表导航 |
| Ctrl+I | 聚焦输入框 | 光标移至末尾 |
| Ctrl+, | 打开设置 | DSH 设置入口 |

还有四个操作默认未绑定快捷键：右侧详情列、子代理面板、系统终端窗口、命令菜单。

Enter / Esc 仅在批准卡片可见时被拦截；否则 DSH 保持其原生行为。

安装

从本地检出目录：

dsh plugin --profile web add "link:"

添加该 bundle 后重启 DSH Desktop。在开发过程中，对 lib/client.js 的修改会在刷新后生效于正在运行的 GUI；若要在不刷新的情况下进行热替换，还需要来自同一 DSH 检出目录的 pnpm run dev:web 监听器。

如果该 profile 的 pnpm 解析被最低发布年龄策略阻止，请手动将 node_modules/dsh-hotkey 链接到此仓库，并将 dsh-hotkey 添加到 web profile 的 package.json 中的 dependencies 和 dsh.profile.bundles 两处。

配置

打开 设置 → 键盘快捷键：

- 按下 更改，然后输入新的组合键
- Esc 取消录制
- Delete / Backspace 禁用该操作
- 重置单个绑定或全部绑定
- 将当前键位映射导出为 JSON，编辑后再导入回来

运行时诊断

在 DSH web 的 DevTools 控制台中：

window.__DSH_HOTKEY__.effective()    // active keymap
window.__DSH_HOTKEY__.availability() // per-action availability shown in settings
window.__DSH_HOTKEY__.probe()        // services, DOM, tabs, sessions, panels
window.__DSH_HOTKEY__.readiness()    // handler readiness
window.__DSH_HOTKEY__.debug(true)    // per-key debug logging

测试

无开发依赖；测试套件仅使用 Node.js 内置模块。

npm test

或单独运行：

node test\bindings.test.mjs   # pure core logic + core/client drift guard
node test\harness.cjs         # ModuleLoader factory and apply() activation
node test\verify-bundle.cjs   # package / patch / bundle structure checks
node test\dom.test.mjs        # fake-DOM integration and action checks

请直接运行这些文件，而不是 node --test test/，后者在受限的 Windows 沙箱中可能会失败。

兼容性

- 目标：DSH Desktop web profile
- DOM 兜底依赖当前的 DSH / better-sidebar DOM 契约；在 DSH UI 升级后，需重新运行测试套件并在实时页面中验证
- 避免绑定浏览器或 Electron 保留的组合键（Ctrl+W、Ctrl+R、F11）

中文

dsh-hotkey 为常用工作台操作增加键盘入口，并在 系统设置 → 快捷键 中提供可视化改键、禁用、冲突检测及 JSON 导入/导出。由于 DSH 客户端插件的服务是异步注册的，插件激活时服务可能尚不存在，因此每个动作都采用「服务 API 优先、DOM 兜底」的策略。

前置条件： Ctrl+Alt+V（切换识图模式）需要安装 dsh-vision-router 插件；右侧边栏相关快捷键（ Ctrl+ 、Ctrl+J、Ctrl+Alt+B、Ctrl+Shift+E、Ctrl+Shift+G、Alt+E）需要安装 dsh-better-sidebar 插件。未安装时这些绑定会在设置页显示为「不可用」。详见下方前提插件表。

前提插件

部分快捷键作用于其他 DSH 插件提供的功能。使用前必须先安装对应插件，否则该绑定会在设置页显示为「不可用」。

| 前提插件 | 提供的功能 | 解锁的快捷键 |
| --- | --- | --- |
| dsh-vision-router | 输入框右下角的识图模式开关按钮 | Ctrl+Alt+V — 切换识图模式 |
| dsh-better-sidebar | 承载终端、文件、Git、侧边对话与底部面板的右侧边栏 |  Ctrl+  Ctrl+J Ctrl+Alt+B Ctrl+Shift+E Ctrl+Shift+G Alt+E |

两个插件都是可选的——其余快捷键无需它们也能正常使用。

功能

- 20 个动作，16 个默认键位
- 在 系统设置 → 快捷键 中改键、禁用、单条恢复默认、全部恢复默认
- 组合键冲突检测；冲突时按动作表顺序确定优先级
- JSON 导入 / 导出完整键位表
- 持久化到 DSH settings scope（命名空间 hotkey）
- 跟随 DSH 界面语言（中文 / 英文）
- 右侧边栏键盘导航：↑ / ↓ 在可见按钮间移动，Enter 模拟点击
- Side Chat 两阶段打开：Alt+E 先展开右侧边栏，再打开或新建对话
- 服务与 DOM 双路径，避免服务延迟注册导致快捷键完全失效

默认快捷键

| 快捷键 | 动作 | 说明 |
| --- | --- | --- |
| Ctrl+B | 切换左侧边栏 | 会话 / 工作区栏 |
| Ctrl+  | 打开 / 聚焦终端 | 右侧终端标签 |
| Ctrl+J | 切换底部面板 | 底部终端 / 面板 |
| Ctrl+Alt+B | 切换右侧边栏 | 承载文件、Git、侧边对话的侧边卡片 |
| Ctrl+Shift+E | 文件树 / 编辑器 | 打开文件标签 |
| Ctrl+Shift+G | Git 面板 | 打开源代码管理标签 |
| Alt+E | 侧边对话 | 先展开右侧边栏，再打开对话 |
| Ctrl+Alt+V | 切换识图模式 | 点击 dsh-vision-router 右下角识图按钮（需先安装该插件） |
| Ctrl+F | 打开新的工作区 | 打开「添加工作区」选择器 |
| Ctrl+N | 新建会话 | 在当前工作区新建会话 |
| Enter | 同意审批 | 仅审批卡片可见时接管 |
| Esc | 拒绝审批 | 仅审批卡片可见时接管 |
| Ctrl+[ | 上一个会话 | 会话列表导航 |
| Ctrl+] | 下一个会话 | 会话列表导航 |
| Ctrl+I | 聚焦输入框 | 光标移至末尾 |
| Ctrl+, | 打开系统设置 | DSH 设置入口 |

另有 4 个动作默认不分配键位：右侧详情列、子代理面板、系统终端窗口、命令菜单。

Enter / Esc 只在审批卡片可见时拦截，其他情况保持 DSH 原生行为。

安装

从本地目录安装：

dsh plugin --profile web add "link:"

新增 bundle 后需重启 DSH Desktop。开发期间修改 lib/client.js 刷新页面即生效；若要免刷新热替换，还需同一 DSH checkout 下运行 pnpm run dev:web watcher。

若 profile 的 pnpm 解析被最小发布时间策略阻止，可手动把 node_modules/dsh-hotkey 链接到本仓库，并把 dsh-hotkey 同时加入 web profile package.json 的 dependencies 与 dsh.profile.bundles。

配置

进入 系统设置 → 快捷键：

- 点击「修改」后直接按下新组合键
- Esc 取消录制
- Delete / Backspace 禁用该动作
- 单条恢复默认或全部恢复默认
- 导出当前 JSON 配置，编辑后重新导入

运行时诊断

在 DSH Web DevTools Console 中：

window.__DSH_HOTKEY__.effective()    // 当前生效键位表
window.__DSH_HOTKEY__.availability() // 设置页可用性判定
window.__DSH_HOTKEY__.probe()        // 服务、DOM、标签、会话、面板诊断
window.__DSH_HOTKEY__.readiness()    // handler 就绪信息
window.__DSH_HOTKEY__.debug(true)    // 逐键调试日志

测试

无需开发依赖，测试仅使用 Node.js 内置模块。

npm test

或单独运行：

node test\bindings.test.mjs   # 纯核心逻辑 + core/client 漂移检查
node test\harness.cjs         # ModuleLoader 工厂与 apply() 激活
node test\verify-bundle.cjs   # package / patch / bundle 结构检查
node test\dom.test.mjs        # 模拟 DOM 集成与动作检查

请直接运行测试文件，不要用 node --test test/：在受限的 Windows 沙箱下可能因子进程限制失败。

兼容性与限制

- 目标平台：DSH Desktop web profile
- DOM 兜底依赖当前 DSH / better-sidebar 的 DOM 契约；DSH UI 升级后应重新跑测试并在真实页面验证
- 不建议绑定浏览器或 Electron 已保留的组合键（Ctrl+W、Ctrl+R、F11）

项目结构 / Structure

dsh-hotkey/
├── cordis.patch.yml       # DSH bundle loader patch
├── package.json           # bundle / client contract
├── lib/
│   ├── index.js           # node half (bundle entry)
│   ├── core.mjs           # combo parsing, matching, conflicts
│   └── client.js          # browser bundle: actions, settings page, keydown
├── test/
│   ├── bindings.test.mjs
│   ├── harness.cjs
│   ├── verify-bundle.cjs
│   └── dom.test.mjs
└── tools/                 # DOM contract inspection scripts

License

MIT