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 许可不覆盖图片和音效素材。二次使用或商用素材前，请联系原作者确认。
致谢
两款挂件，各有侧重；按需选择，也可同时安装。
