---

借鉴 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 插入行