dsh-fullscreen-shortcut
> 给 DeepSeek Harness (dsh) 桌面端补上 macOS 的窗口全屏快捷键 —— ⌃⌘F（Control + Command + F）。
目录
- 背景
- 功能
- 环境要求
- 安装
- 使用
- 工作原理
- 文件结构
- 卸载
- 从旧包名迁移
- 常见问题
- 开发
- License
背景
DSH 桌面端使用自定义的 Electron 外壳，并替换掉了 Electron 默认的应用菜单。macOS 原生的「进入全屏幕 / Enter Full Screen」菜单项因此不存在，挂在它上面的系统快捷键 ⌃⌘F 也随之失效；而外壳自带的快捷键目录里并没有「窗口全屏」这条命令。
结果就是：在 DSH 桌面窗口里，你没法像其他 macOS 应用那样按 ⌃⌘F 全屏，只能点系统窗口左上角的绿色按钮。
本插件只做一件事：把这个缺失的物理按键补回来，在 DSH 桌面窗口内切换页面全屏。
功能
⌃⌘F一键切换全屏：按一次进入全屏，再按一次退出。- 按物理键位判断：以
KeyboardEvent.code === "KeyF"匹配，不受键盘布局（QWERTY / Dvorak / 中文输入法等）影响。 - 不打扰其他输入：跳过长按重复（
event.repeat）和已被页面其他控件处理（event.defaultPrevented）的按键。 - 同步外壳状态：维护 `` 属性，让标题栏留白、红绿灯占位等布局样式与真实全屏状态保持一致。
- 轻量、无副作用：纯客户端插件，无网络请求、无持久化、不访问凭据。
环境要求
| 项 | 要求 |
|---|---|
| 平台 | macOS |
| 宿主 | DSH 桌面端（Electron 外壳） |
| 插件 API | dsh 0.2.x（dsh.client 客户端插件 + bundle patch） |
| 浏览器 Web 版 | 不需要本插件 —— 浏览器自带全屏，按键由浏览器自身处理 |
安装
> dsh plugin add 会修改 ~/.dsh/profiles/desktop 的依赖与 dsh.profile.bundles，安装后需要重启 DSH 桌面端才能激活客户端插件。
方式一：从 GitHub 直接安装（推荐）
dsh plugin --profile desktop add github:kimufly/dsh-fullscreen-shortcut
方式二：克隆后本地安装
git clone https://github.com/kimufly/dsh-fullscreen-shortcut.git
cd dsh-fullscreen-shortcut
dsh plugin --profile desktop add .
dsh plugin add 会把包写入 profile 的 dependencies，并把 dsh-fullscreen-shortcut 追加到 dsh.profile.bundles；重启桌面端后生效。
确认安装
dsh plugin --profile desktop why dsh-fullscreen-shortcut
安装成功后，DSH 桌面端「插件」列表里会出现 窗口全屏快捷键 / Window Fullscreen Shortcut。
使用
在 DSH 桌面窗口内：
| 操作 | 效果 |
|---|---|
⌃⌘F |
进入全屏 / 退出全屏 |
Esc |
退出全屏（Fullscreen API 的默认行为） |
> 提示：本插件走的是页面级 Fullscreen API（document.fullscreenElement），不是 macOS 的「原生全屏空间」。窗口会占满当前屏幕，但不会创建新的桌面 Space，也不会切换系统菜单里的「退出全屏幕」状态。
工作原理
- 注册客户端模块：
package.json的dsh.client声明platform: "web"、immediately: true，并注入@deepseek-ai/dsh-client-modules；cordis.patch.yml通过 bundle patch 把插件作为 loader 行插入。 - 自行绑定按键：桌面外壳只拦截已注册快捷键对应的按键（
before-input-event仅对已匹配的组合preventDefault），DOM 的keydown路径仍然畅通。插件在window的捕获阶段监听keydown，匹配code === "KeyF"且metaKey && ctrlKey（同时要求没有 Alt / Shift）。 - 调用 Fullscreen API：命中后调用
document.documentElement.requestFullscreen()/document.exitFullscreen()。真实键盘事件自带瞬时用户激活（transient user activation），这是requestFullscreen()的硬性要求；通过 IPC 派发的模拟按键没有该激活，会被浏览器拒绝。 - 同步外壳状态：桌面 preload 只在窗口收到原生
enter-full-screen事件时设置`；由页面主动发起的全屏不会触发该原生事件，布局便会继续为红绿灯预留标题栏高度。插件监听fullscreenchange`，自行维护该属性。
文件结构
| 文件 | 作用 |
|---|---|
client.js |
客户端插件本体：按键绑定、全屏切换、data-fullscreen 同步 |
index.js |
宿主侧空实现（行为全部在客户端） |
cordis.patch.yml |
bundle patch，把插件作为 loader 行插入 |
package.json |
包清单，声明 dsh.bundle.patch 与 dsh.client |
locale/zh.json、locale/en.json |
插件标题与描述文案 |
icon.svg |
插件图标 |
卸载
dsh plugin --profile desktop remove dsh-fullscreen-shortcut
重启 DSH 桌面端后生效。
从旧包名迁移
本插件原名 @local/window-fullscreen-shortcut（仅以本地链接方式安装）。如果你装过旧版，请先移除再安装新包：
dsh plugin --profile desktop remove @local/window-fullscreen-shortcut
dsh plugin --profile desktop add github:kimufly/dsh-fullscreen-shortcut
然后重启桌面端。
常见问题
按 ⌃⌘F 没反应？
- 确认装在了
desktopprofile：dsh plugin --profile desktop why dsh-fullscreen-shortcut。 - 确认已经重启过 DSH 桌面端，且焦点在 DSH 窗口内。
- 插件会跳过已被其他控件处理的按键；检查是否有其他插件或输入法占用了同一组合。
- 查看 DSH 日志里是否有
dsh-fullscreen-shortcut:前缀的告警（例如 Fullscreen API 被拒绝）。
全屏后标题栏还留着一条空白？
这是 ` 未同步的典型症状。本插件已通过fullscreenchange` 监听处理；若仍出现，欢迎带 DSH 版本与 macOS 版本提 issue。
和 macOS 绿色按钮的原生全屏是一回事吗？
不是。本插件走 HTML Fullscreen API，原生全屏属于系统窗口管理；两者互不替代，也不会互相「接管」。
Windows / Linux 能用吗？
当前只面向 macOS 的 ⌃⌘F 习惯，未做 Windows / Linux 适配，也未在对应平台测试。
开发
- 纯 JavaScript（ESM），无构建步骤。
client.js通过window.__ModuleLoader__.load(...)注册客户端模块；逻辑包在ctx.effect()中，返回的清理函数会在插件卸载/重载时移除监听。- 本地调试：克隆后执行
dsh plugin --profile desktop add .，修改client.js后重启桌面端（已安装的客户端模块不走热更新）。
License
MIT © 2026 kimufly
