把系统总音量搬上灵动岛：收起态一个小音量段，展开是滑块与音量合成器，光标悬在岛上还能直接滚轮调节。
| 项 | 值 |
|---|---|
| 插件标识 | com.nps.volumecontrol |
| 交付形态 | 单个 dll（无需额外文件） |
| 宿主要求 | NotchPeninsula 1.9.3 及以上（目标框架 net10.0-windows10.0.19041.0） |
一、安装
- 把
NpsVolumeControl.dll放进宿主plugins\目录（与宿主 exe 同级的文件夹）。 - 启动宿主，进入插件中心，启用「音量控制」。
- 若之前装过旧版「任务栏状态」（
com.nps.taskbarisland），请先删除旧 dll —— 新插件是独立标识，两者会同时显示。
二、岛上使用
收起态：平时只显示一个喇叭图标；鼠标悬停时才在右侧显示「百分比」或「已静音」， 不悬停就不占文字宽度。
| 动作 | 效果 |
|---|---|
| 滚轮（光标悬在音量组件上） | 直接调总音量，每格 2%；滚到顶 / 底会有轻微提示动画 |
| 左键单击 | 切换静音 / 取消静音 |
| 右键单击 | 展开详情页（音量合成器就在里面） |
滚轮是怎么实现的
宿主的插件契约不向插件转发滚轮消息，插件在自己进程内装了一个低层鼠标钩子。
接管条件是三重判定，缺一不可：
- 光标落在本插件自己的屏幕矩形内（由组件在绘制时逐帧上报，超时自动失效）；
- 详情页活跃时，改按详情页的矩形判定；
- 再用
WindowFromPoint复核，确认命中的确实是岛体窗口（该 API 精确尊重分层窗口的 alpha， 透明像素不算命中）。
因此不会误吞任务栏或岛上其它组件（时钟、媒体控制等）的滚轮。实际调音量派发到独立线程执行， 钩子回调本身只做判断，不拖慢系统输入。
遇到「右键却静音」？
宿主的右键链路不经过静音。若日志里出现「左键 → 快速静音」而你按的确实是右键， 说明鼠标驱动把右键发成了左键（部分触摸板两指点按 / 按键映射软件如此）。 可在记事本等程序里右键验证一下。
三、详情页：音量合成器
右键组件展开详情页 —— 音量合成器直接内置在详情页里：
- 顶部主音量卡：大图标 + 百分比 + 静音按钮 + 可拖动滑块；
- 应用音量列表：视口一次显示 3 行，右侧有滚动条（可拖动 / 点槽翻页）， 每行是图标 + 名称 + 进度条 + 百分比，点行首即可单独静音该应用；
- 「系统声音」一行管的是系统提示音（UAC 弹窗、通知等）；
- 底部两个按钮：
立即刷新与收起。
3.1 详情页里的滚轮分工
| 悬浮位置 | 滚轮效果 |
|---|---|
| 某个应用的进度条 | 调那个应用的音量（每格 2%） |
| 主音量滑块 | 调总音量 |
| 详情页其它区域 | 滚动应用列表 |
| 详情页之外 | 完全不接管，还给系统 |
写入是即时生效的 —— 与 Windows 自带的「音量合成器」等价。
面板不会太快消失
详情页里有需要拖动的滑块，所以自动收起延迟设为 4 秒（鼠标移开后计时）。
四、设置项
插件只做音量一件事，因此设置很少：
| 设置键 | 默认值 | 说明 |
|---|---|---|
refreshMs | 1000 | 后台刷新间隔（毫秒），范围 300 ～ 10000。音量与音频会话列表都靠它刷新 |
notify | 0（关） | 状态变化时是否在岛上弹提醒。默认关闭（静默常驻）；滚轮调音量不会触发它 |
这两项通过宿主的设置接口持久化，落在注册表：
HKCU\SOFTWARE\NotchPeninsula\Plugin.com.nps.volumecontrol.refreshMs
HKCU\SOFTWARE\NotchPeninsula\Plugin.com.nps.volumecontrol.notify关于配置界面
当前版本不提供插件自建的配置窗口 —— 这两项在默认值下已经适用绝大多数场景， 需要调整时直接改上面的注册表键即可，改完重载插件生效。
五、常见问题
Q：音量显示「—」？ 没有默认输出设备（未装声卡驱动 / 音频服务未启动）时会这样。插入耳机或切一次默认设备即可恢复； 若仍不行，看日志里 音量不可用：<原因> 那一行。
Q：滚轮没反应？ 按顺序检查：
- 光标必须悬在音量组件可见区域上（宿主窗口是全屏宽画布，岛体只是中间一小段， 悬在两侧空白处、或悬在别的组件上都不触发）；
- 部分全屏游戏（独占模式）会屏蔽低层钩子，属系统行为；
- 极少数安全软件会限制低层鼠标钩子的安装，日志里会写明原因。
Q：合成器里某个应用不见了？ 该应用当前没有创建音频会话（也就是没在出声）。播放一段声音后点「立即刷新」。 另外宿主自身与 Rainmeter 的会话会被插件主动忽略 —— 它们与岛上的频谱采样互相干扰。
Q：为什么岛上的时钟 / 媒体组件上滚轮不能调音量了？ 这是 1.1.1 的修复结果。早期版本按「岛体可见区域」判定，会把其它组件上的滚动一起吃掉； 现在改为只在音量组件自己的矩形内接管。
Q：改了注册表设置，岛上没变化？ 到插件中心点一次「热重载」。
六、日志
日志随插件写入宿主日志目录：
logs\plugins\com.nps.volumecontrol\反馈问题时请附带最近几行。日志里会记录音量不可用的原因、滚轮钩子的安装结果， 以及左右键的原始事件 —— 排查「右键却静音」这类问题时很有用。