dsh-whale-bongo

Whale Bongo

QQ 弹弹的类 bongo 手手挂件

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:MeteorNOX/dsh-whale-bongo#4a283cd7ba781fda3b189b8d3758b2fdc28c2baf

兼容性与来源证明

Whale Bongo 以 dsh-whale-bongo 发布，当前版本为 0.3.3。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/11/2

版本

0.3.3stable

2026/11/2

0.3.2stable

2026/11/2

0.3.1stable

2026/11/2

查看其余 5 个版本收起版本

0.3.0stable

2026/11/1

0.2.3stable

2026/11/1

0.2.2stable

2026/10/31

0.2.0stable

2026/10/31

0.1.0stable

2026/10/30

README

dsh-whale-bongo 图标

dsh-whale-bongo

QQ 弹弹的类 bongo 手手挂件

v0.3.3 · dsh-bongo-fish 的独立重置版本

DSH Web Bundle No Build MIT Code

是 dsh-bongo-fish 的独立重置版本；参考其注入方式与交互思路。
不是官方分支，也不代表原作者发布。

版本选择

两款挂件面向不同的使用偏好，可以按自己的习惯选择：

	原版 `dsh-bongo-fish`	本版 `dsh-whale-bongo`
适合的需求	正常手/萌圆手两套配置、图片和音效上传、提醒拍手	双手按键反馈、图片 Q 弹、打字角度、手部几何/颜色/轮廓
安装	前往原版仓库	安装本版
同时安装	可以；两个挂件并存，拖开即可

主要区别：

手部：原版有正常手/萌圆手两套配置；本版为双手按键的手手，支持手部几何、颜色和轮廓粗细调节。
按压手感：原版正常手瞬切下沉、萌圆手下压回弹；本版手手按压后回弹，并提供鼠标按压行为选项。
原版敲击抖动：原版敲击键盘时插件有抖动反馈。

这是什么

dsh-whale-bongo 是一个 QQ 弹弹的类 bongo 手手挂件，是 dsh-bongo-fish 的重置版本。

原版 dsh-bongo-fish 是一个 bongo cat 风格的 DSH 打字挂件，强调跟随敲击节奏互动的原味手感。本版参考它的注入方式与交互思路，重新实现了双手动作、图片回弹和设置系统，采用偏 Q 弹、手部按压表现明显的方向。

它浮在 DSH 输入框旁：

默认磁吸在输入框右上方；
每敲一下键盘，手手随之按下；
支持自定义图片、手手颜色、音效、挂件大小；
支持水平自动翻转；
透明区域点击/拖动直接穿透到 DSH。

本仓库不是原项目的官方分支，也不代表原作者发布。

一句话：原版偏原味节奏，本版偏 Q 弹、手部表现和可调角度；按习惯选择，也可以两个都装。

亮点


双手按键反馈	两只手随敲键按下。
鼠标点击按压	点击角色图片区域，双手按下、图片压扁；按住保持，松开回弹。
同键同手	同一按键保持同一只手，不同按键交替左右手。
图片 Q 弹	以图片底边为锚点压扁回弹，强度 0–10；回弹时不裁左右，投影完整。
打字角度	随机角度和真实键位两套方向系统，真实键位支持左右手分管；默认真实键位（左右分管）。
透明穿透	按图片 alpha 生成 SVG `clip-path`，只有角色本体接收鼠标，透明区域直接穿透。
自由磁吸	吸附输入框上/下边线段、上沿中心点，或页面视口边线；中心点会记忆并在布局变化时跟随，拖动时显示吸附圆点。
水平翻转	自动按输入框 45%/55% 迟滞判断、自定义分割线、始终不翻转、始终翻转；带弹性过渡。
菜单安全区	菜单不会进入 DSH 标题栏，关闭按钮始终可点。
自定义音效	支持上传本地音频替换默认敲击音，可恢复默认；音效保存在浏览器本地。
面板同步吸附	提问、授权、计划确认面板出现时，按输入框的吸附方式贴到当前面板上；面板关闭后回到输入框。
目标栏优先吸附	当前目标状态栏出现时，按任务栏 > 目标栏 > 排队框的顺序优先吸附。
排队框优先吸附	对话排队消息框出现时，优先吸附排队框；任务栏的优先级高于排队框。
任务栏优先吸附	输入框上方出现「任务 N 已完成」任务条时，优先吸附任务条，而不是隔着它吸输入框。
出现动效	首次挂载时从底部中心轻微上浮、放大并回弹到正常尺寸。
布局平滑过渡	任务栏展开/收起、提问/授权面板出现/消失时，挂件以底部中心为锚点，通过克制的弹簧位移和明显的身体拉伸/落地挤压平滑移动，幅度随「Q 弹程度」变化。
热启用 / 热关闭	在插件列表启用或关闭时即时挂载/移除，不需要重启 DSH。
无构建依赖	纯 DSH bundle，不需要 `npm install`，不需要前端 build。

安装

从 GitHub Release 安装

打开 GitHub Releases；
下载最新 Release 中的 dsh-whale-bongo-0.3.3-package.zip 或 dsh-whale-bongo-0.3.3.tgz；
在 DSH「插件 → 添加插件 → 安装本地 bundle」中选择解压后的目录，或选择 .tgz；
在插件列表启用；正常情况下挂件会即时出现。若 Host 路由尚未加载，刷新一次页面即可。

本地开发安装

打开 DSH → 设置 / 插件；
选择 添加插件 / 安装本地 bundle；
指向本仓库目录，或输入：
```
link:<本仓库绝对路径>
```
在插件列表启用，挂件会即时挂载；如果 Host 路由尚未加载，刷新一次页面；
之后在插件列表启用/关闭会即时显示或移除挂件，无需重启 DSH。

原生 sidecar 源码在 runtime/electron-helper/native/WhaleNativeHelper.cs，发布包内已附带编译好的 whale-native-helper.exe。修改后可在 Windows 上运行 npm run build:native 重新编译（使用 .NET Framework 自带的 csc.exe）。

npm

dsh-whale-bongo

dsh plugin --profile web add dsh-whale-bongo@0.3.3

[!TIP] 给其他 AI / 其他 DSH 的安装教程见 INSTALL-FOR-AI.md，包含 plugin_manager、命令行兜底和 health 验证。

设置

分组	内容
主体图片	更换图片、恢复默认、图片大小、水平位置、垂直位置
手部	内部色、轮廓色、轮廓粗细、宽度、高宽比、间距、对称轴、垂直位置
音效	按键音量（0 显示「关」）、更换自定义音效、恢复默认音效
行为与动效	Q 弹程度；鼠标按压行为；水平翻转；过滤快捷键与修饰键；打字角度
大小	挂件尺寸

默认值：

图片          本体.png
图片缩放      100%
图片位置      0, 0
轮廓粗细      100%
手部宽度      14
高宽比        81
手部间距      35
对称轴        41
垂直位置      77.5
图片 Q 弹     5
鼠标按压      手部变扁，不下压
翻转          自动
分割线        50%
过滤快捷键    关闭
打字角度      真实键位(左右分管)
角度偏移      30°
音量          15
音效          默认音效
挂件大小      140

桌面模式

v0.3.0 新增：挂件可以从 DSH 页面里“跳出来”，作为一个透明、无边框、置顶的桌面窗口显示。

开启方式：

右键挂件或点左上角 ☰；
打开「行为与动效」；
把「显示位置」改为「桌面」。

开启后：

客户端挂件隐藏，桌面窗口默认出现在主显示器工作区，之后可拖到其他显示器；
桌面窗口默认点击穿透，鼠标移到角色或菜单上才可交互；
拖动角色可在整个桌面范围内移动挂件本体；
桌面菜单和客户端菜单使用同一套设置；
设置、图片、音效和当前打字节奏会同步；
桌面模式使用全局键盘监听，在 DSH 或其他应用里打字都会触发动作（Windows；macOS 桌面模式使用 DSH 页面按键）；
桌面 helper 的窗口枚举和鼠标跟随由原生进程 whale-native-helper.exe 负责（Windows）；全局键盘暂时继续使用已验证的 PowerShell global-keys.ps1，因为 Raw Input 在该桌面会话中收不到物理按键；macOS 使用 Quartz 原生采样器；
DSH 客户端内也通过 Host 全局键盘流补发按键，搜狗输入法等拦截页面 keydown 时仍能驱动挂件；Host 侧继续保持原有 PowerShell 监控；
macOS 桌面模式需要安装 Xcode Command Line Tools（xcrun clang）；首次启用会在私有临时目录编译采样器，不申请屏幕录制或辅助功能权限；
桌面/客户端切换手势：客户端拖到窗口右下角保持 0.5 秒进入桌面；桌面拖到输入框中心吸附点保持 0.5 秒回到客户端；
桌面窗口边缘吸附：拖动挂件靠近所有可见顶层窗口的上/下边缘时会吸附；
横向采用和输入框一致的中段比例、左右按距离策略；
吸附后窗口移动/缩放时，挂件直接跟随边缘：窗口移动时约 6ms 热采样（helper 启用 1ms 系统计时器），静止时约 33ms；采样按渲染帧合并，落位使用合成层 translate 偏移；
支持 Windows 125% / 150% / 200% 等缩放和混合 DPI 多屏：窗口矩形会先转换为覆盖层内的 DIP 坐标，再用于吸附和翻面；
支持把挂件拖到其他显示器：拖到当前覆盖层边缘时，helper 会为相邻显示器创建一个独立透明覆盖层，切换后挂件和鼠标抓取点保持相对位置；
使用 Shift+Win+方向键 把桌面窗口移到其他显示器后，helper 会自动切到目标显示器的覆盖层，不会再把挂件留在屏幕外；
已经吸附在某个窗口上的挂件也会跟着该窗口换屏：helper 追踪吸附窗口的句柄，窗口换屏时先准备目标显示器的覆盖层，再继续按窗口边缘吸附；
每个覆盖层固定铺满所在显示器的工作区，跨屏只切换窗口、不改变同一个渲染进程的坐标系，因此不会再出现旧坐标插值造成的瞬移；切换时挂件从目标显示器相对来向的一侧横向 Q 弹入场，不使用渐隐缩放；
点击系统托盘图标，或右键选择「召回挂件到当前屏幕」，可把挂件召回到鼠标所在显示器；
右键托盘菜单选择「回到客户端内部」，可退出桌面模式，并把挂件放回 DSH 输入框上方；过渡与手动拖到输入框磁吸点一致，会先淡出桌面挂件再在客户端入场；
跟随窗口位置时直接按采样结果落位，不再为每个采样叠加 CSS 过渡；吸附窗口横向移动时，挂件底部保持原位，上半身像有惯性一样向运动反方向摆动后回弹；纵向也加入约一半强度的拉伸/压缩惯性，同样以底部为锚点，不会上下平移或过冲；强度跟随「Q 弹程度」滑块；
桌面模式不显示吸附点。
想回到客户端模式，在桌面挂件菜单里把「显示位置」改回「客户端」。

性能排查（可选环境变量）：

DSH_WHALE_SOFTWARE_RENDER=1   关闭 GPU 加速，改用软件合成
DSH_WHALE_FRAME_RATE=30       覆盖层目标帧率，范围 30–120，默认 60

默认保持 GPU 加速和 60 帧；软件合成能降低一些内存，但会牺牲透明窗口的合成流畅度，不建议日常开启。

桌面模式需要 Electron。第一次切换到「桌面」时，如果本机还没有运行时，页面下方会出现准备卡片：

点「准备桌面运行时（约 138 MB）」即可自动下载，不需要打开终端；
下载过程中显示进度、来源和已下载大小，可以随时取消；
下载完成后自动校验 SHA-256、解压并原子安装，然后自动进入桌面模式；
失败或取消时会保持客户端模式，并显示原因和重试按钮，不会留下半成品。

如果已有可用运行时，会直接复用；否则自动扫描：

~/.dsh/electron-whale/<任意已安装版本>/electron.exe
~/.dsh/electron-whale/current/electron.exe
~/.dsh/electron/electron.exe

默认准备经验证的 Electron 43.3.0，先走 npmmirror，失败再回退 GitHub；可用 DSH_WHALE_ELECTRON_VERSION=latest 改为最新版，或用 DSH_WHALE_ELECTRON_DIR 指定安装目录。如果系统设置了 HTTPS_PROXY / https_proxy（HTTP CONNECT 代理），下载会自动走代理，NO_PROXY 可绕过；暂不支持 SOCKS 代理。也可以手动运行零依赖脚本：

node scripts/ensure-electron.mjs

说明：

Electron 缺失或桌面进程启动失败时，会保持客户端模式，并在页面下方显示失败原因和准备入口。
桌面模式不参与 DSH 输入框、任务栏、排队框等页面吸附；这些吸附只在客户端模式生效。
桌面模式使用覆盖当前显示器工作区的透明、点击穿透窗口；只有挂件和菜单区域可交互。
菜单可以在整个工作区拖动，不会因为窗口尺寸变化而瞬移。
桌面进程会跟随 DSH 宿主退出，不会留下独立僵尸进程。

与 dsh-bongo-fish 共存

可以同时安装：

包名不同：dsh-bongo-fish / dsh-whale-bongo
Host 路由独立：本插件使用 /dsh-whale-bongo
DOM id 不同
localStorage 键不同
菜单、图片、手部参数各自独立

同时安装后：

两个挂件会同时出现，可能重叠；拖动其中一个错开即可；
两边按键音效会同时响，可以调低其中一个的音量，或只保留一个；
卸载其中一个不会影响另一个。

卸载与数据清理

优先在 DSH 插件管理器中移除 dsh-whale-bongo。
Web / CLI 环境在 npm 发布后可执行：

dsh plugin --profile web remove dsh-whale-bongo

卸载后挂件会停止加载。设置与自定义图片保存在当前浏览器 localStorage 中；如需彻底清理，可在浏览器站点数据中删除本插件的存储。

常见问题

安装后看不到挂件

确认插件列表里 dsh-whale-bongo 已启用；
Ctrl + F5 硬刷新；
确认当前在对话页，不是设置页或插件页；
如果 Host 路由 404，再重启一次 DSH 加载新的 Host 半；
检查 Host 路由：
```
/dsh-whale-bongo/health
```

真实键位模式没有角度

检查 /dsh-whale-bongo/key-angles.json 是否返回 200；
如果 404，说明 Host 还是旧版本，需要完全重启 DSH；
浏览器里只刷新页面不会加载新的 Host 路由。

菜单关闭按钮点不到 / 菜单进入标题栏

当前版本已给菜单增加 56px 顶部安全区，并把最大高度限制在安全区下方。
如果 DSH 标题栏比 56px 更高，需要按实际高度调整安全区。

菜单按钮不见了

菜单按钮默认隐藏，只在鼠标悬浮到图片或按钮本身时显示；离开后延迟约 420ms 隐藏。

没有声音

检查菜单「音效 → 音量」是否大于 0；系统音量/浏览器自动播放策略也可能影响首次播放。

npm 安装失败

当前 npm 包尚未发布。请使用 GitHub Release 的 zip/tgz，或本地目录安装。

项目结构

展开查看项目结构

dsh-whale-bongo/
  package.json          # bundle 元数据、DSH client 配置
  cordis.patch.yml      # Host 注入行
  index.js              # Host 半：路由、静态资源、注入
  client.js             # 客户端模块入口
  assets/widget.js      # 浏览器半
  assets/key-angles.json # 真实键位模式的键位横向坐标表
  assets/dsh-whale-bongo-icon.png  # 图片素材（版权归原作者）
  assets/portrait.png   # 图片素材（版权归原作者）
  assets/sounds/        # 音效素材（版权归原作者）+ CC0 许可
  runtime/electron-helper/ # Electron 透明覆盖层与原生 sidecar
  scripts/ensure-electron.mjs     # 零依赖下载 Electron
  scripts/build-native-helper.mjs # 编译 whale-native-helper.exe
  icon.png              # 插件列表图标（版权归原作者）
  locale/               # 中英文标题
  LICENSE
  CHANGELOG.md
  CONTRIBUTORS.md
  .gitignore
  README.md
  INSTALL-FOR-AI.md     # 给其他 AI 的安装教程

菜单里的下拉使用可复用的 .dsnw-select 组件：触发器、浮层选项、选中态、键盘操作和点击外部关闭都在同一套样式/逻辑中，后续新增下拉设置时可以直接复用。

来源与版权

[!IMPORTANT] 图片素材与音效素材版权归原作者所有，不跟随本仓库代码的 MIT 许可。

原版 dsh-bongo-fish（作者 YUsaltyfish）是一个 bongo cat 风格的 DSH 打字挂件；原项目名称、原始代码、原始素材和原有品牌归原作者所有。
本仓库是 dsh-bongo-fish 的重置版本，参考其注入方式和交互思路，独立重写；两个仓库分开维护。
经双方友好协商，双方互为对方仓库的协作者。
本仓库的代码与重写逻辑版权归本仓库作者，按 MIT 许可。
当前所有图片与音效素材（assets/portrait.png、assets/dsh-whale-bongo-icon.png、icon.png、assets/sounds/hit.wav）版权归 YUsaltyfish；本仓库按双方约定使用，不随代码 MIT 许可重新授权。
音效的原始素材来源为 Kenney CC0；具体许可见 assets/sounds/LICENSE-kenney-CC0.txt。
如需二次使用或商用图片/音效，请联系原作者确认；不要仅依据代码的 MIT 许可使用素材。
本仓库不是 dsh-bongo-fish 的官方分支，也不会把原项目说成自己的原创项目。

简单说：代码归代码，素材归原作者；仓库分开，互相署名，两个都能装。

素材与许可

内容	版权 / 许可
本仓库代码与重写逻辑	MIT
`assets/portrait.png`	版权归 YUsaltyfish；按双方约定使用
`assets/dsh-whale-bongo-icon.png`	版权归 YUsaltyfish；按双方约定使用
`icon.png`	版权归 YUsaltyfish；按双方约定使用
`assets/sounds/hit.wav`	版权归 YUsaltyfish；原始素材为 Kenney CC0
`dsh-bongo-fish` 原项目	版权归原作者，遵循原项目许可

代码的 MIT 许可不覆盖图片和音效素材。二次使用或商用素材前，请联系原作者确认。

致谢

YUsaltyfish：原版 dsh-bongo-fish 的作者，注入方式、交互思路、图片与音效素材
Kenney：CC0 音效原始素材
DSH：桌面端与 Web bundle 能力

_{两款挂件，各有侧重；按需选择，也可同时安装。}

README

dsh-whale-bongo 图标

dsh-whale-bongo

QQ 弹弹的类 bongo 手手挂件

v0.3.3 · dsh-bongo-fish 的独立重置版本

DSH Web Bundle No Build MIT Code

是 dsh-bongo-fish 的独立重置版本；参考其注入方式与交互思路。
不是官方分支，也不代表原作者发布。

版本选择

两款挂件面向不同的使用偏好，可以按自己的习惯选择：

	原版 `dsh-bongo-fish`	本版 `dsh-whale-bongo`
适合的需求	正常手/萌圆手两套配置、图片和音效上传、提醒拍手	双手按键反馈、图片 Q 弹、打字角度、手部几何/颜色/轮廓
安装	前往原版仓库	安装本版
同时安装	可以；两个挂件并存，拖开即可

主要区别：

手部：原版有正常手/萌圆手两套配置；本版为双手按键的手手，支持手部几何、颜色和轮廓粗细调节。
按压手感：原版正常手瞬切下沉、萌圆手下压回弹；本版手手按压后回弹，并提供鼠标按压行为选项。
原版敲击抖动：原版敲击键盘时插件有抖动反馈。

这是什么

dsh-whale-bongo 是一个 QQ 弹弹的类 bongo 手手挂件，是 dsh-bongo-fish 的重置版本。

它浮在 DSH 输入框旁：

默认磁吸在输入框右上方；
每敲一下键盘，手手随之按下；
支持自定义图片、手手颜色、音效、挂件大小；
支持水平自动翻转；
透明区域点击/拖动直接穿透到 DSH。

本仓库不是原项目的官方分支，也不代表原作者发布。

一句话：原版偏原味节奏，本版偏 Q 弹、手部表现和可调角度；按习惯选择，也可以两个都装。

亮点


双手按键反馈	两只手随敲键按下。
鼠标点击按压	点击角色图片区域，双手按下、图片压扁；按住保持，松开回弹。
同键同手	同一按键保持同一只手，不同按键交替左右手。
图片 Q 弹	以图片底边为锚点压扁回弹，强度 0–10；回弹时不裁左右，投影完整。
打字角度	随机角度和真实键位两套方向系统，真实键位支持左右手分管；默认真实键位（左右分管）。
透明穿透	按图片 alpha 生成 SVG `clip-path`，只有角色本体接收鼠标，透明区域直接穿透。
自由磁吸	吸附输入框上/下边线段、上沿中心点，或页面视口边线；中心点会记忆并在布局变化时跟随，拖动时显示吸附圆点。
水平翻转	自动按输入框 45%/55% 迟滞判断、自定义分割线、始终不翻转、始终翻转；带弹性过渡。
菜单安全区	菜单不会进入 DSH 标题栏，关闭按钮始终可点。
自定义音效	支持上传本地音频替换默认敲击音，可恢复默认；音效保存在浏览器本地。
面板同步吸附	提问、授权、计划确认面板出现时，按输入框的吸附方式贴到当前面板上；面板关闭后回到输入框。
目标栏优先吸附	当前目标状态栏出现时，按任务栏 > 目标栏 > 排队框的顺序优先吸附。
排队框优先吸附	对话排队消息框出现时，优先吸附排队框；任务栏的优先级高于排队框。
任务栏优先吸附	输入框上方出现「任务 N 已完成」任务条时，优先吸附任务条，而不是隔着它吸输入框。
出现动效	首次挂载时从底部中心轻微上浮、放大并回弹到正常尺寸。
布局平滑过渡	任务栏展开/收起、提问/授权面板出现/消失时，挂件以底部中心为锚点，通过克制的弹簧位移和明显的身体拉伸/落地挤压平滑移动，幅度随「Q 弹程度」变化。
热启用 / 热关闭	在插件列表启用或关闭时即时挂载/移除，不需要重启 DSH。
无构建依赖	纯 DSH bundle，不需要 `npm install`，不需要前端 build。

安装

从 GitHub Release 安装

打开 GitHub Releases；
下载最新 Release 中的 dsh-whale-bongo-0.3.3-package.zip 或 dsh-whale-bongo-0.3.3.tgz；
在 DSH「插件 → 添加插件 → 安装本地 bundle」中选择解压后的目录，或选择 .tgz；
在插件列表启用；正常情况下挂件会即时出现。若 Host 路由尚未加载，刷新一次页面即可。

本地开发安装

打开 DSH → 设置 / 插件；
选择 添加插件 / 安装本地 bundle；
指向本仓库目录，或输入：
```
link:<本仓库绝对路径>
```
在插件列表启用，挂件会即时挂载；如果 Host 路由尚未加载，刷新一次页面；
之后在插件列表启用/关闭会即时显示或移除挂件，无需重启 DSH。

npm

dsh-whale-bongo

dsh plugin --profile web add dsh-whale-bongo@0.3.3

[!TIP] 给其他 AI / 其他 DSH 的安装教程见 INSTALL-FOR-AI.md，包含 plugin_manager、命令行兜底和 health 验证。

设置

分组	内容
主体图片	更换图片、恢复默认、图片大小、水平位置、垂直位置
手部	内部色、轮廓色、轮廓粗细、宽度、高宽比、间距、对称轴、垂直位置
音效	按键音量（0 显示「关」）、更换自定义音效、恢复默认音效
行为与动效	Q 弹程度；鼠标按压行为；水平翻转；过滤快捷键与修饰键；打字角度
大小	挂件尺寸

默认值：

图片          本体.png
图片缩放      100%
图片位置      0, 0
轮廓粗细      100%
手部宽度      14
高宽比        81
手部间距      35
对称轴        41
垂直位置      77.5
图片 Q 弹     5
鼠标按压      手部变扁，不下压
翻转          自动
分割线        50%
过滤快捷键    关闭
打字角度      真实键位(左右分管)
角度偏移      30°
音量          15
音效          默认音效
挂件大小      140

桌面模式

v0.3.0 新增：挂件可以从 DSH 页面里“跳出来”，作为一个透明、无边框、置顶的桌面窗口显示。

开启方式：

右键挂件或点左上角 ☰；
打开「行为与动效」；
把「显示位置」改为「桌面」。

开启后：

客户端挂件隐藏，桌面窗口默认出现在主显示器工作区，之后可拖到其他显示器；
桌面窗口默认点击穿透，鼠标移到角色或菜单上才可交互；
拖动角色可在整个桌面范围内移动挂件本体；
桌面菜单和客户端菜单使用同一套设置；
设置、图片、音效和当前打字节奏会同步；
桌面模式使用全局键盘监听，在 DSH 或其他应用里打字都会触发动作（Windows；macOS 桌面模式使用 DSH 页面按键）；
桌面 helper 的窗口枚举和鼠标跟随由原生进程 whale-native-helper.exe 负责（Windows）；全局键盘暂时继续使用已验证的 PowerShell global-keys.ps1，因为 Raw Input 在该桌面会话中收不到物理按键；macOS 使用 Quartz 原生采样器；
DSH 客户端内也通过 Host 全局键盘流补发按键，搜狗输入法等拦截页面 keydown 时仍能驱动挂件；Host 侧继续保持原有 PowerShell 监控；
macOS 桌面模式需要安装 Xcode Command Line Tools（xcrun clang）；首次启用会在私有临时目录编译采样器，不申请屏幕录制或辅助功能权限；
桌面/客户端切换手势：客户端拖到窗口右下角保持 0.5 秒进入桌面；桌面拖到输入框中心吸附点保持 0.5 秒回到客户端；
桌面窗口边缘吸附：拖动挂件靠近所有可见顶层窗口的上/下边缘时会吸附；
横向采用和输入框一致的中段比例、左右按距离策略；
吸附后窗口移动/缩放时，挂件直接跟随边缘：窗口移动时约 6ms 热采样（helper 启用 1ms 系统计时器），静止时约 33ms；采样按渲染帧合并，落位使用合成层 translate 偏移；
支持 Windows 125% / 150% / 200% 等缩放和混合 DPI 多屏：窗口矩形会先转换为覆盖层内的 DIP 坐标，再用于吸附和翻面；
支持把挂件拖到其他显示器：拖到当前覆盖层边缘时，helper 会为相邻显示器创建一个独立透明覆盖层，切换后挂件和鼠标抓取点保持相对位置；
使用 Shift+Win+方向键 把桌面窗口移到其他显示器后，helper 会自动切到目标显示器的覆盖层，不会再把挂件留在屏幕外；
已经吸附在某个窗口上的挂件也会跟着该窗口换屏：helper 追踪吸附窗口的句柄，窗口换屏时先准备目标显示器的覆盖层，再继续按窗口边缘吸附；
每个覆盖层固定铺满所在显示器的工作区，跨屏只切换窗口、不改变同一个渲染进程的坐标系，因此不会再出现旧坐标插值造成的瞬移；切换时挂件从目标显示器相对来向的一侧横向 Q 弹入场，不使用渐隐缩放；
点击系统托盘图标，或右键选择「召回挂件到当前屏幕」，可把挂件召回到鼠标所在显示器；
右键托盘菜单选择「回到客户端内部」，可退出桌面模式，并把挂件放回 DSH 输入框上方；过渡与手动拖到输入框磁吸点一致，会先淡出桌面挂件再在客户端入场；
跟随窗口位置时直接按采样结果落位，不再为每个采样叠加 CSS 过渡；吸附窗口横向移动时，挂件底部保持原位，上半身像有惯性一样向运动反方向摆动后回弹；纵向也加入约一半强度的拉伸/压缩惯性，同样以底部为锚点，不会上下平移或过冲；强度跟随「Q 弹程度」滑块；
桌面模式不显示吸附点。
想回到客户端模式，在桌面挂件菜单里把「显示位置」改回「客户端」。

性能排查（可选环境变量）：

DSH_WHALE_SOFTWARE_RENDER=1   关闭 GPU 加速，改用软件合成
DSH_WHALE_FRAME_RATE=30       覆盖层目标帧率，范围 30–120，默认 60

默认保持 GPU 加速和 60 帧；软件合成能降低一些内存，但会牺牲透明窗口的合成流畅度，不建议日常开启。

桌面模式需要 Electron。第一次切换到「桌面」时，如果本机还没有运行时，页面下方会出现准备卡片：

点「准备桌面运行时（约 138 MB）」即可自动下载，不需要打开终端；
下载过程中显示进度、来源和已下载大小，可以随时取消；
下载完成后自动校验 SHA-256、解压并原子安装，然后自动进入桌面模式；
失败或取消时会保持客户端模式，并显示原因和重试按钮，不会留下半成品。

如果已有可用运行时，会直接复用；否则自动扫描：

~/.dsh/electron-whale/<任意已安装版本>/electron.exe
~/.dsh/electron-whale/current/electron.exe
~/.dsh/electron/electron.exe

node scripts/ensure-electron.mjs

说明：

Electron 缺失或桌面进程启动失败时，会保持客户端模式，并在页面下方显示失败原因和准备入口。
桌面模式不参与 DSH 输入框、任务栏、排队框等页面吸附；这些吸附只在客户端模式生效。
桌面模式使用覆盖当前显示器工作区的透明、点击穿透窗口；只有挂件和菜单区域可交互。
菜单可以在整个工作区拖动，不会因为窗口尺寸变化而瞬移。
桌面进程会跟随 DSH 宿主退出，不会留下独立僵尸进程。

与 dsh-bongo-fish 共存

可以同时安装：

包名不同：dsh-bongo-fish / dsh-whale-bongo
Host 路由独立：本插件使用 /dsh-whale-bongo
DOM id 不同
localStorage 键不同
菜单、图片、手部参数各自独立

同时安装后：

两个挂件会同时出现，可能重叠；拖动其中一个错开即可；
两边按键音效会同时响，可以调低其中一个的音量，或只保留一个；
卸载其中一个不会影响另一个。

卸载与数据清理

优先在 DSH 插件管理器中移除 dsh-whale-bongo。
Web / CLI 环境在 npm 发布后可执行：

dsh plugin --profile web remove dsh-whale-bongo

卸载后挂件会停止加载。设置与自定义图片保存在当前浏览器 localStorage 中；如需彻底清理，可在浏览器站点数据中删除本插件的存储。

常见问题

安装后看不到挂件

确认插件列表里 dsh-whale-bongo 已启用；
Ctrl + F5 硬刷新；
确认当前在对话页，不是设置页或插件页；
如果 Host 路由 404，再重启一次 DSH 加载新的 Host 半；
检查 Host 路由：
```
/dsh-whale-bongo/health
```

真实键位模式没有角度

检查 /dsh-whale-bongo/key-angles.json 是否返回 200；
如果 404，说明 Host 还是旧版本，需要完全重启 DSH；
浏览器里只刷新页面不会加载新的 Host 路由。

菜单关闭按钮点不到 / 菜单进入标题栏

当前版本已给菜单增加 56px 顶部安全区，并把最大高度限制在安全区下方。
如果 DSH 标题栏比 56px 更高，需要按实际高度调整安全区。

菜单按钮不见了

菜单按钮默认隐藏，只在鼠标悬浮到图片或按钮本身时显示；离开后延迟约 420ms 隐藏。

没有声音

检查菜单「音效 → 音量」是否大于 0；系统音量/浏览器自动播放策略也可能影响首次播放。

npm 安装失败

当前 npm 包尚未发布。请使用 GitHub Release 的 zip/tgz，或本地目录安装。

项目结构

展开查看项目结构

dsh-whale-bongo/
  package.json          # bundle 元数据、DSH client 配置
  cordis.patch.yml      # Host 注入行
  index.js              # Host 半：路由、静态资源、注入
  client.js             # 客户端模块入口
  assets/widget.js      # 浏览器半
  assets/key-angles.json # 真实键位模式的键位横向坐标表
  assets/dsh-whale-bongo-icon.png  # 图片素材（版权归原作者）
  assets/portrait.png   # 图片素材（版权归原作者）
  assets/sounds/        # 音效素材（版权归原作者）+ CC0 许可
  runtime/electron-helper/ # Electron 透明覆盖层与原生 sidecar
  scripts/ensure-electron.mjs     # 零依赖下载 Electron
  scripts/build-native-helper.mjs # 编译 whale-native-helper.exe
  icon.png              # 插件列表图标（版权归原作者）
  locale/               # 中英文标题
  LICENSE
  CHANGELOG.md
  CONTRIBUTORS.md
  .gitignore
  README.md
  INSTALL-FOR-AI.md     # 给其他 AI 的安装教程

来源与版权

[!IMPORTANT] 图片素材与音效素材版权归原作者所有，不跟随本仓库代码的 MIT 许可。

原版 dsh-bongo-fish（作者 YUsaltyfish）是一个 bongo cat 风格的 DSH 打字挂件；原项目名称、原始代码、原始素材和原有品牌归原作者所有。
本仓库是 dsh-bongo-fish 的重置版本，参考其注入方式和交互思路，独立重写；两个仓库分开维护。
经双方友好协商，双方互为对方仓库的协作者。
本仓库的代码与重写逻辑版权归本仓库作者，按 MIT 许可。
当前所有图片与音效素材（assets/portrait.png、assets/dsh-whale-bongo-icon.png、icon.png、assets/sounds/hit.wav）版权归 YUsaltyfish；本仓库按双方约定使用，不随代码 MIT 许可重新授权。
音效的原始素材来源为 Kenney CC0；具体许可见 assets/sounds/LICENSE-kenney-CC0.txt。
如需二次使用或商用图片/音效，请联系原作者确认；不要仅依据代码的 MIT 许可使用素材。
本仓库不是 dsh-bongo-fish 的官方分支，也不会把原项目说成自己的原创项目。

简单说：代码归代码，素材归原作者；仓库分开，互相署名，两个都能装。

素材与许可

内容	版权 / 许可
本仓库代码与重写逻辑	MIT
`assets/portrait.png`	版权归 YUsaltyfish；按双方约定使用
`assets/dsh-whale-bongo-icon.png`	版权归 YUsaltyfish；按双方约定使用
`icon.png`	版权归 YUsaltyfish；按双方约定使用
`assets/sounds/hit.wav`	版权归 YUsaltyfish；原始素材为 Kenney CC0
`dsh-bongo-fish` 原项目	版权归原作者，遵循原项目许可

代码的 MIT 许可不覆盖图片和音效素材。二次使用或商用素材前，请联系原作者确认。

致谢

YUsaltyfish：原版 dsh-bongo-fish 的作者，注入方式、交互思路、图片与音效素材
Kenney：CC0 音效原始素材
DSH：桌面端与 Web bundle 能力

_{两款挂件，各有侧重；按需选择，也可同时安装。}

Whale Bongo

兼容性与来源证明

版本

相关插件

Whale Bongo

README

dsh-whale-bongo

目录

版本选择

这是什么

亮点

安装

从 GitHub Release 安装

本地开发安装

npm

设置

桌面模式

与 dsh-bongo-fish 共存

卸载与数据清理

常见问题

项目结构

来源与版权

素材与许可

致谢

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

dsh-whale-bongo

目录

版本选择

这是什么

亮点

安装

从 GitHub Release 安装

本地开发安装

npm

设置

桌面模式

与 dsh-bongo-fish 共存

卸载与数据清理

常见问题

项目结构

来源与版权

素材与许可

致谢