名称： webchat-audio-notifications
描述： 为 Moltbot/Clawdbot 网页聊天添加浏览器音频通知，提供 5 种强度级别——从轻声细语到不容错过（仅在标签页处于后台时播放）。
版本： 1.1.0
作者： brokemac79
仓库： https://github.com/brokemac79/webchat-audio-notifications
主页： https://github.com/brokemac79/webchat-audio-notifications
标签：
- webchat
- notifications
- audio
- ux
- browser
- howler
元数据：
clawdbot:
emoji: 🔔
compatibility:
minVersion: "2026.1.0"
browsers:
- Chrome 92+
- Firefox 90+
- Safari 15+
- Edge 92+
dependencies:
- howler.js (已包含)
files:
- client/howler.min.js
- client/notification.js
- client/sounds/notification.mp3
- client/sounds/alert.mp3
install:
- kind: manual
label: 安装网页聊天音频通知
instructions: |
1. 将文件复制到您的网页聊天目录：
- client/howler.min.js → /webchat/js/
- client/notification.js → /webchat/js/
- client/sounds/ → /webchat/sounds/
2. 在网页聊天 HTML 的 `</body>` 标签前添加：
```html
<script src="/js/howler.min.js"></script>
<script src="/js/notification.js"></script>
<script>
const notifier = new WebchatNotifications({
soundPath: '/sounds/notification'
});
notifier.init();
</script>
```
3. 在消息事件中调用通知：
```javascript
socket.on('message', () => {
if (notifier) notifier.notify();
});
```
4. 通过切换标签页并触发消息进行测试
完整指南请参阅 `docs/integration.md`。
为 Moltbot/Clawdbot 网页聊天提供浏览器音频通知。当新消息到达时播放通知音效——但仅在标签页处于后台时触发。
cd examples
python3 -m http.server 8080
# 打开 http://localhost:8080/test.html
测试步骤：
1. 切换到另一个标签页
2. 点击“触发通知”
3. 听到声音！ 🔊
// 初始化
const notifier = new WebchatNotifications({
soundPath: './sounds',
soundName: 'level3', // 中等强度（默认）
defaultVolume: 0.7
});
await notifier.init();
// 在新消息时触发
socket.on('message', () => notifier.notify());
// 为不同事件使用不同级别
socket.on('mention', () => {
notifier.setSound('level5'); // 提及消息使用最响亮的音效
notifier.notify();
});
new WebchatNotifications({
soundPath: './sounds', // 音效目录路径
soundName: 'level3', // level1 (轻声) 到 level5 (非常响亮)
defaultVolume: 0.7, // 0.0 到 1.0
cooldownMs: 3000, // 警报之间的最短时间
enableButton: true, // 显示启用提示
debug: false // 控制台日志记录
});
强度级别说明：
- level1 - 轻声 (9.5KB) - 最轻微
- level2 - 柔和 (12KB) - 温和
- level3 - 中等 (13KB) - 默认
- level4 - 响亮 (43KB) - 引人注意
- level5 - 非常响亮 (63KB) - 不容错过
init() - 初始化（在 Howler 加载后调用）notify(eventType?) - 触发通知（仅在标签页隐藏时）test() - 立即播放音效（忽略标签页状态）setEnabled(bool) - 启用/禁用通知setVolume(0-1) - 设置音量setSound(level) - 更改强度（'level1' 到 'level5'）getSettings() - 获取当前设置| 浏览器 | 版本 | 支持情况 |
|---|---|---|
| Chrome | 92+ | ✅ 完全支持 |
| Firefox | 90+ | ✅ 完全支持 |
| Safari | 15+ | ✅ 完全支持 |
| 移动端 | 最新版 | ⚠️ 有限支持 |
总体情况： 92% 的用户（支持 Web Audio API）
webchat-audio-notifications/
├── client/
│ ├── notification.js # 主类 (10KB)
│ ├── howler.min.js # 音频库 (36KB)
│ └── sounds/
│ ├── level1.mp3 # 轻声 (9.5KB)
│ ├── level2.mp3 # 柔和 (12KB)
│ ├── level3.mp3 # 中等 (13KB, 默认)
│ ├── level4.mp3 # 响亮 (43KB)
│ └── level5.mp3 # 非常响亮 (63KB)
├── examples/
│ └── test.html # 包含所有级别的独立测试页面
├── docs/
│ └── integration.md # 集成指南
└── README.md # 完整文档
完整指南请参阅 docs/integration.md，内容包括：
- 分步设置说明
- Moltbot 特定钩子
- React/Vue 示例
- 常见模式（@提及、请勿打扰、徽章）
- 测试清单
const notifier = new WebchatNotifications();
await notifier.init();
notifier.notify();
const notifier = new WebchatNotifications({
soundPath: '/assets/sounds',
soundName: 'level2', // 从柔和音效开始
defaultVolume: 0.8,
cooldownMs: 5000,
debug: true
});
await notifier.init();
// 普通消息 = 柔和
socket.on('message', () => {
notifier.setSound('level2');
notifier.notify();
});
// 提及消息 = 非常响亮
socket.on('mention', () => {
notifier.setSound('level5');
notifier.notify();
});
// 私信 = 响亮
socket.on('dm', () => {
notifier.setSound('level4');
notifier.notify();
});
<input type="range" min="0" max="100"
onchange="notifier.setVolume(this.value / 100)">
<button onclick="notifier.test()">测试 🔊</button>
没有声音？
- 先点击页面（自动播放限制）
- 检查标签页是否确实隐藏
- 确认音量 > 0
- 检查控制台是否有错误
标签页激活时也播放声音？
- 启用调试模式
- 检查是否有“标签页可见，跳过”消息
- 如果缺失，请报告为 bug
移动端不工作？
- iOS 要求每次播放都需要用户手势
- 考虑视觉回退方案（闪烁网站图标）
MIT 许可证
examples/test.html 进行测试状态： ✅ v1.1.0 完成 - 5 种强度级别
测试环境： Chrome, Firefox, Safari
适用于： 生产环境 & ClawdHub 发布