dsh-whale-bongo

QQ 弹弹的类 bongo 手手挂件

v0.3.5 · 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% 迟滞判断；桌面模式只在窗口吸附时按被吸附窗口 45%/55% 翻转，自由放置保持当前朝向；另有自定义分割线、始终不翻转、始终翻转；带弹性过渡。
菜单安全区	菜单不会进入 DSH 标题栏，关闭按钮始终可点。
自定义音效	支持上传本地音频替换默认敲击音，可恢复默认；音效保存在浏览器本地。
面板同步吸附	提问、授权、计划确认面板出现时，按输入框的吸附方式贴到当前面板上；面板关闭后回到输入框。
目标栏优先吸附	当前目标状态栏出现时，按任务栏 > 目标栏 > 排队框的顺序优先吸附。
排队框优先吸附	对话排队消息框出现时，优先吸附排队框；任务栏的优先级高于排队框。
任务栏优先吸附	输入框上方出现「任务 N 已完成」任务条时，优先吸附任务条，而不是隔着它吸输入框。
出现动效	首次挂载时从底部中心轻微上浮、放大并回弹到正常尺寸。
布局平滑过渡	任务栏展开/收起、提问/授权面板出现/消失时，挂件以底部中心为锚点，通过克制的弹簧位移和明显的身体拉伸/落地挤压平滑移动，幅度随「Q 弹程度」变化。
热启用 / 热关闭	在插件列表启用或关闭时即时挂载/移除，不需要重启 DSH。
无构建依赖	纯 DSH bundle，不需要 `npm install`，不需要前端 build。

安装

从 GitHub Release 安装

打开 GitHub Releases；
下载最新 Release 中的 dsh-whale-bongo-0.3.5-package.zip 或 dsh-whale-bongo-0.3.5.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）。

实时律动监视器（额外工具，不打包）

用于观察桌面挂件真实的 BPM 网格、候选 BPM、拍点、能量和计算耗时；工具本身不采集音频，也不修改插件设置。

node tools/beat-live-server.mjs

打开 http://127.0.0.1:8898/，先在桌面模式开启音乐律动。工具会自动发现 helper 的 loopback 端口，读取插件实际的数据流；也可以开始录制并导出完整 JSON，用于复现 BPM 和拍点问题。更多说明见 tools/README.md。

npm

dsh-whale-bongo

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

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

设置

分组	内容
主体图片	更换图片、恢复默认、图片大小、水平位置、垂直位置
手部	内部色、轮廓色、轮廓粗细、宽度、高宽比、间距、对称轴、垂直位置
音效	按键音量（0 显示「关」）、更换自定义音效、恢复默认音效
MOD	桌面系统音频、随背景音乐律动开关（仅桌面模式）；开启后显示下一项
律动模式	额外提前量
行为与动效	Q 弹程度；鼠标按压行为；水平翻转；过滤快捷键与修饰键；打字角度
大小	挂件尺寸

默认值：

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

音乐律动模式

桌面模式可以让挂件跟随系统里正在播放的音乐摆动。它只读取系统音频的实时节拍信息，不录音、不保存，也不会上传任何音频。

开启方式

进入桌面模式；
打开挂件菜单，展开 MOD；
确认 随背景音乐律动 已开启（默认开启）；
在下方新增的 律动模式 小节里调整提前量。

开启后需要播放一段有声音的音乐。开头约 3 秒只用于判断是否有真实声音，不会立即开始摆动；之后检测到稳定节拍才会触发动作。

会有什么效果

每个被接受的拍点都会让挂件复用一次「鼠标点按挂件」的按压回弹，而不是单独叠加一层点头动画。双手的具体行为跟随「鼠标按压时」设置：

跟随下压：手部向下压再回弹；
变扁不下压：手部原地压扁再回弹；
不跟随：只有身体按压。

按压幅度跟随「Q 弹程度」滑块，幅度越大，回弹越明显。

提前量

额外提前量 滑块用于校准「视觉最低点」和「听到的拍点」之间的偏差：

0：使用内置 55ms 按压动画补偿，通常就是对齐状态；
正值：更早按下，适合觉得动作总是慢半拍；
负值：更晚按下，适合觉得动作抢拍。

滑块范围 -100~150ms，步进 5ms。不同显示器刷新率、蓝牙耳机延迟和音乐本身的前奏都可能需要微调。

节拍判断

通过 Electron 的系统音频回环采集，再用内置的 MIT @audio/beat 检测节拍网格和 BPM；
开头静音或声音太小不会产生 BPM；
首次异常高 BPM 需要连续 3 次确认；半拍/倍拍关系需要 6 次确认；
112↔113 这类小变化只微调周期，不重排已经排好的拍点；
候选 BPM 确认期间继续沿用当前节奏；确认换速后留一个空拍再切换，避免突然停摆；
音乐停止约 450ms 后停止摆动；挂件自身按动音效会短暂屏蔽检测，避免自己触发自己；
打字不会暂停监听或冻结 BPM；检测到音乐时打字音效会降低，鼠标点按音效仍会短暂屏蔽检测。

权限与限制

仅桌面模式生效，客户端页面不采集系统音频；
Windows 使用系统回环，通常不需要额外授权；
macOS 需要系统音频采集权限；没有权限或设备不支持时，菜单会显示原因并自动停用；
只读取实时音频，不录音、不保存、不上传；
想观察实际 BPM、拍点、候选 BPM 和计算耗时，可使用上面的「实时律动监视器」工具。

桌面模式

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 弹程度」滑块；
桌面模式设置里有独立的「MOD」小节；完整的律动开关、提前量和节拍判断说明见上面的音乐律动模式。
桌面模式不显示吸附点。
想回到客户端模式，在桌面挂件菜单里把「显示位置」改回「客户端」。

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

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 的作者，注入方式、交互思路、图片与音效素材
DenseFLoe：macOS 兼容性测试、问题复现与修复建议
Kenney：CC0 音效原始素材
DSH：桌面端与 Web bundle 能力

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

dsh-whale-bongo

QQ 弹弹的类 bongo 手手挂件

v0.3.5 · 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% 迟滞判断；桌面模式只在窗口吸附时按被吸附窗口 45%/55% 翻转，自由放置保持当前朝向；另有自定义分割线、始终不翻转、始终翻转；带弹性过渡。
菜单安全区	菜单不会进入 DSH 标题栏，关闭按钮始终可点。
自定义音效	支持上传本地音频替换默认敲击音，可恢复默认；音效保存在浏览器本地。
面板同步吸附	提问、授权、计划确认面板出现时，按输入框的吸附方式贴到当前面板上；面板关闭后回到输入框。
目标栏优先吸附	当前目标状态栏出现时，按任务栏 > 目标栏 > 排队框的顺序优先吸附。
排队框优先吸附	对话排队消息框出现时，优先吸附排队框；任务栏的优先级高于排队框。
任务栏优先吸附	输入框上方出现「任务 N 已完成」任务条时，优先吸附任务条，而不是隔着它吸输入框。
出现动效	首次挂载时从底部中心轻微上浮、放大并回弹到正常尺寸。
布局平滑过渡	任务栏展开/收起、提问/授权面板出现/消失时，挂件以底部中心为锚点，通过克制的弹簧位移和明显的身体拉伸/落地挤压平滑移动，幅度随「Q 弹程度」变化。
热启用 / 热关闭	在插件列表启用或关闭时即时挂载/移除，不需要重启 DSH。
无构建依赖	纯 DSH bundle，不需要 `npm install`，不需要前端 build。

安装

从 GitHub Release 安装

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

本地开发安装

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

实时律动监视器（额外工具，不打包）

用于观察桌面挂件真实的 BPM 网格、候选 BPM、拍点、能量和计算耗时；工具本身不采集音频，也不修改插件设置。

node tools/beat-live-server.mjs

npm

dsh-whale-bongo

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

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

设置

分组	内容
主体图片	更换图片、恢复默认、图片大小、水平位置、垂直位置
手部	内部色、轮廓色、轮廓粗细、宽度、高宽比、间距、对称轴、垂直位置
音效	按键音量（0 显示「关」）、更换自定义音效、恢复默认音效
MOD	桌面系统音频、随背景音乐律动开关（仅桌面模式）；开启后显示下一项
律动模式	额外提前量
行为与动效	Q 弹程度；鼠标按压行为；水平翻转；过滤快捷键与修饰键；打字角度
大小	挂件尺寸

默认值：

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

音乐律动模式

桌面模式可以让挂件跟随系统里正在播放的音乐摆动。它只读取系统音频的实时节拍信息，不录音、不保存，也不会上传任何音频。

开启方式

进入桌面模式；
打开挂件菜单，展开 MOD；
确认 随背景音乐律动 已开启（默认开启）；
在下方新增的 律动模式 小节里调整提前量。

开启后需要播放一段有声音的音乐。开头约 3 秒只用于判断是否有真实声音，不会立即开始摆动；之后检测到稳定节拍才会触发动作。

会有什么效果

每个被接受的拍点都会让挂件复用一次「鼠标点按挂件」的按压回弹，而不是单独叠加一层点头动画。双手的具体行为跟随「鼠标按压时」设置：

跟随下压：手部向下压再回弹；
变扁不下压：手部原地压扁再回弹；
不跟随：只有身体按压。

按压幅度跟随「Q 弹程度」滑块，幅度越大，回弹越明显。

提前量

额外提前量 滑块用于校准「视觉最低点」和「听到的拍点」之间的偏差：

0：使用内置 55ms 按压动画补偿，通常就是对齐状态；
正值：更早按下，适合觉得动作总是慢半拍；
负值：更晚按下，适合觉得动作抢拍。

滑块范围 -100~150ms，步进 5ms。不同显示器刷新率、蓝牙耳机延迟和音乐本身的前奏都可能需要微调。

节拍判断

通过 Electron 的系统音频回环采集，再用内置的 MIT @audio/beat 检测节拍网格和 BPM；
开头静音或声音太小不会产生 BPM；
首次异常高 BPM 需要连续 3 次确认；半拍/倍拍关系需要 6 次确认；
112↔113 这类小变化只微调周期，不重排已经排好的拍点；
候选 BPM 确认期间继续沿用当前节奏；确认换速后留一个空拍再切换，避免突然停摆；
音乐停止约 450ms 后停止摆动；挂件自身按动音效会短暂屏蔽检测，避免自己触发自己；
打字不会暂停监听或冻结 BPM；检测到音乐时打字音效会降低，鼠标点按音效仍会短暂屏蔽检测。

权限与限制

仅桌面模式生效，客户端页面不采集系统音频；
Windows 使用系统回环，通常不需要额外授权；
macOS 需要系统音频采集权限；没有权限或设备不支持时，菜单会显示原因并自动停用；
只读取实时音频，不录音、不保存、不上传；
想观察实际 BPM、拍点、候选 BPM 和计算耗时，可使用上面的「实时律动监视器」工具。

桌面模式

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 弹程度」滑块；
桌面模式设置里有独立的「MOD」小节；完整的律动开关、提前量和节拍判断说明见上面的音乐律动模式。
桌面模式不显示吸附点。
想回到客户端模式，在桌面挂件菜单里把「显示位置」改回「客户端」。

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

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 的作者，注入方式、交互思路、图片与音效素材
DenseFLoe：macOS 兼容性测试、问题复现与修复建议
Kenney：CC0 音效原始素材
DSH：桌面端与 Web bundle 能力

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

MeteorNOX/dsh-whale-bongo

dsh-whale-bongo

目录

版本选择

这是什么

亮点

安装

从 GitHub Release 安装

本地开发安装

实时律动监视器（额外工具，不打包）

npm

设置

音乐律动模式

开启方式

会有什么效果

提前量

节拍判断

权限与限制

桌面模式

与 dsh-bongo-fish 共存

卸载与数据清理

常见问题

项目结构

来源与版权

素材与许可

致谢

Community comments

MeteorNOX/dsh-whale-bongo

dsh-whale-bongo

目录

版本选择

这是什么

亮点

安装

从 GitHub Release 安装

本地开发安装

实时律动监视器（额外工具，不打包）

npm

设置

音乐律动模式

开启方式

会有什么效果

提前量

节拍判断

权限与限制

桌面模式

与 dsh-bongo-fish 共存

卸载与数据清理

常见问题

项目结构

来源与版权

素材与许可

致谢

Community comments