DSH Easy Hotkey

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

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

界面预览

亮色

暗色

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

为什么使用它

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

快速上手

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

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

两种显示模式

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

临时固定

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

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

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

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

三种搜索

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

例如：

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

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

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

自定义设置

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

• 唤出按键采用按键录制，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，加载新安装或更新的插件；重启前请留意正在执行的任务。

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

开发与验证

预览使用 演示目录，并不代表当前宿主的真实快捷键。浏览器检查默认调用已安装的 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 的实机验收。

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