快捷键速览 metaone01/dsh-easy-hotkey

DSH Easy Hotkey

长按一下，让快捷键浮现在眼前。

为 DeepSeek Harness Desktop 提供轻量、窗口内的快捷键速览。

Ctrl · 长按唤出 · 三种搜索 · 亮暗主题 · 中英双语

简体中文 · English

界面预览 · 快速上手 · 三种搜索 · 安装 · 开发与验证

借鉴 PowerToys 长按唤出快捷键指南的交互思路，DSH Easy Hotkey 把 DSH 当前窗口真实注册的快捷键 整理成随手可查的浮窗。无需离开正在进行的工作，也无需记住一整张按键表。

默认长按 Ctrl 650 ms 唤出。只在安装了本插件的应用窗口内生效，不注册系统全局快捷键。

界面预览

亮色暗色

以上为实际 DSH Desktop 截图，点击可查看原图。快捷键及数量来自截图时的宿主配置，不是一份固定清单；不同配置、插件和版本可能不同。

为什么使用它

- 看见真实的快捷键：直接读取宿主的可配置与固定快捷键目录，随目录、描述和语言变化更新，不再维护另一份按键表。
- 按需出现，随手退出：支持“切换”和“长按”；点击设置或搜索即可临时固定，不会刚松手就消失。
- 想做什么，或按了什么，都能找：按功能名称搜索、直接录制按键搜索，也能把两个条件组合起来。
- 清晰而不抢眼：半透明遮罩与背景模糊降低底层干扰，说明在左、键帽在右，搜索和设置独立悬浮。
- 细节不妨碍操作：打开自动聚焦列表，立即支持滚轮；右下角提示会避让鼠标，始终不拦截点击。

快速上手

1. 在 DSH 窗口中，按住 Ctrl。右下角键帽边框会逐渐蓄满。
2. 达到默认的 650 ms 后，浮窗展开。左右 Ctrl 都可以使用。
3. 在底部搜索功能，或点击左侧的设置按钮调整显示模式、时长、唤出按键和主题。
4. 点击浮窗的空白区域、说明文字，或按 Esc 关闭。

打开时聚焦的是 快捷键列表，不是输入框，因此不会自动进入搜索或触发临时固定。滚轮也可以在浮窗空白处滚动列表，按住 Ctrl 时不会误变成页面缩放。

两种显示模式

| 模式 | 松开唤出按键后 | 如何关闭 |
| 切换 | 保持展开 | 点击非交互区域、按 Esc，或再次完成一次长按 |
| 长按 | 立即关闭，临时固定时除外 | 松开唤出按键、点击非交互区域，或按 Esc |

输入框、按钮和选择框属于交互控件，点击它们不会被当作关闭操作。点击背景关闭时，也不会同时点到背景下方的应用控件。

临时固定

在长按模式中，点击设置展开或点击搜索区域，就立即临时固定，无需开始输入。设置区或搜索区内切换控件时保持固定；收起设置或焦点离开这些区域后，恢复长按行为。

- 唤出按键已经松开：恢复长按后关闭。
- 唤出按键仍按住：继续显示，直到松开。
- 窗口失焦或隐藏：长按浮窗仍会关闭；Esc 始终可以主动关闭。

右下角提示用键帽表达状态：

| 状态 | 键帽样式 | 说明文字 |
| 等待唤出 | 默认样式 | 查看快捷键 |
| 长按蓄力 | 边框逐渐填满 | 查看快捷键 |
| 普通长按展开 | 浅色高亮 | 快捷键已展开 |
| 切换模式展开 | 主色背景、白色文字 | 快捷键已展开 |
| 长按模式临时固定 | 主色背景、白色文字 | 临时固定 |

鼠标进入提示周围 48 px 的范围时，提示淡出，离开后恢复。窄窗口展开浮窗时，提示暂时隐藏，避免遮住底部控件。

三种搜索

默认选择 搜索功能。底部模式选择框可以随时切换，切换或收起设置不会清空已有搜索条件。

| 模式 | 输入方式 | 筛选方式 |
| 搜索功能 | 输入功能名称 | 仅匹配功能描述，不匹配键名 |
| 搜索按键 | 点击按键输入区，直接按下单键或组合键 | 显示录制键帽，匹配包含该按键组合的快捷键 |
| 功能＋按键 | 同时输入功能名称与录制按键 | 两个条件共同筛选；任一条件为空时，仅使用另一个 |

例如：

- 想新建会话：在功能模式中输入 新会话，无需知道按键。
- 想找 Enter 相关操作：在按键模式中直接按下 Enter，不用输入 Enter 这几个字母。
- 想进一步缩小范围：在组合模式中输入功能关键词，再按下 Ctrl 或更具体的组合键。

按键以 键帽 显示；新的一次按键输入会替换上一组，不把已经松开的按键不断拼接。使用按键旁的清除按钮，只清除录制按键，保留功能文字。水印和控件名称随搜索模式及宿主语言变化。

按键搜索录制期间，会抑制宿主的应用快捷键，避免搜索时意外执行命令。失焦、Tab 导航、关闭或卸载时释放录制；Esc 保留为关闭浮窗。

自定义设置

点击搜索栏左侧的 设置按钮，四个控件向右展开，同时隐藏搜索栏；再次点击恢复搜索。

| 设置 | 可选项与默认值 |
| 显示模式 | 切换 / 长按；默认 切换 |
| 长按时长 | 0–5000 ms；默认 650 ms，0 表示立即唤出 |
| 唤出按键 | 单键、修饰键组合，或修饰键加一个普通键；默认 Ctrl |
| 主题 | 亮色 / 暗色 / 跟随系统；默认 跟随系统 |

- 唤出按键采用按键录制，Esc 与 Tab 保留；拒绝宿主已注册的冲突组合和系统保留组合。
- 普通键触发器在输入框、可编辑区域及终端中不生效，避免输入文字时误唤出。
- 修改唤出按键或时长，会取消当前蓄力，下次按下生效；越界时长会截断到 0 或 5000。
- 中英文文案跟随宿主语言；主题实时响应系统亮暗变化。
- 设置保存在当前应用 origin 的 localStorage，刷新后保留；无法保存时会提示，当前设置仍生效。

安装

本仓库提供 源码构建与 Desktop profile 安装，不需要修改 DSH 主程序。安装前需有已初始化的 DSH Desktop profile，以及可运行本项目脚本的 Node.js 和 npm；当前开发验证环境为 Node.js 25.9.0。

在仓库根目录执行：

npm install
npm run check
npm run install:dsh

安装器使用 DSH_HOME 下的 profiles/desktop；未指定 DSH_HOME 时使用 ~/.dsh/profiles/desktop。也可以显式指定 profile：

node scripts/install-dsh.mjs "<DSH Desktop profile 路径>"

安装时会：

1. 备份原 cordis.patch.yml 和已有插件到 profile 的 .plugin-backups/。
2. 复制客户端与宿主构建文件到 node_modules/dsh-easy-hotkey/。
3. 仅追加本插件的 roster 行，保留其他配置；重复安装不会重复注册。
4. 校验安装文件与本次构建完全一致。

安装器不会自动重启 DSH。 在方便的时候完全退出并重新打开 Desktop，加载新安装或更新的插件；重启前请留意正在执行的任务。

停用插件与备份说明

在目标 profile 的 cordis.patch.yml 中移除本插件自己的插入行，然后重新打开 DSH。不要删除同一文件中的其他插件或设置：

- insert:
- id: easy-hotkey
name: dsh-easy-hotkey

历史备份位于 .plugin-backups/easy-hotkey-<时间戳>/，包含补丁、已有插件副本（如果此前安装过）与安装回执。恢复整个旧补丁可能同时回退其他设置，操作前应先比较差异。

开发与验证

| 命令 | 用途 |
| npm run typecheck | TypeScript 类型检查 |
| npm test | 状态机、搜索、交互、打包入口及安装回归 |
| npm run build | 生成 Desktop 插件及本地预览文件 |
| npm run check | 依次执行类型检查、测试和构建 |
| npm run demo | 启动本机预览，默认 http://127.0.0.1:8743 |
| node scripts/browser-smoke.mjs | 实际浏览器交互检查与截图 |

预览使用 演示目录，并不代表当前宿主的真实快捷键。浏览器检查默认调用已安装的 Edge，使用独立临时配置，只监听本机；也可用 DSH_HOTKEY_BROWSER 指定浏览器路径。截图及报告输出到 .artifacts/。

开发脚本优先使用本仓库依赖；本地缺失时，会只读复用相邻 dsh-floating-ball / dsh-better-float 的既有开发工具。独立使用本仓库时，应安装本项目声明的依赖。

2026-10-03 验证记录：类型检查与构建通过，98 项自动测试、61 项实际浏览器检查通过；用户已确认 DSH Desktop 手动验证通过。本记录是该版本的验收快照，不代表所有平台与后续版本均已验证。

能力边界

- 仅限应用窗口：不是系统全局指南，不会为其他应用拦截按键。
- 仅监听插件所在的顶层窗口：跨源 iframe、Electron webview 的原始长按与松键不透传；其他窗口需要单独挂载本插件。
- 正常快捷键不受干扰：例如 Ctrl+C 会取消尚未完成的 Ctrl 蓄力，直到完整松开后才允许再次蓄力；只有显式录制期间接管按键。
- 只展示宿主已注册内容：不会自动发现操作系统、未注册插件或第三方应用的快捷键。
- 验收范围诚实限定：目前有 Windows DSH Desktop 的用户手动验收，不将按键标签的平台适配视为 macOS / Linux 的实机验收。

宿主接入与项目结构

客户端通过 window.__ModuleLoader__.load 注册，以 shell.overlay 槽挂载。React 由宿主提供，服务依赖同时声明在 manifest 与客户端 inject 中。卸载时释放焦点监听、目录订阅、计时器及录制占用。

assets/ 中英文、亮暗主题的实际 Desktop 截图 src/guide.ts 浮窗、焦点、提示与录制交互 src/controller.ts 长按与临时固定状态机 src/search.ts 三种搜索模式的匹配逻辑 src/locales.ts 中英文文案 src/styles.css 主题、悬浮控件、键帽与滚动条 scripts/ 构建、安装、预览与浏览器验证 tests/ 自动回归检查 cordis.patch.yml DSH bundle roster 插入行