Audio Announcement Skill 🦊

让 OpenClaw 开口说话，实时播报 AI 的一举一动！

概述

这是一个语音播报技能，可以让你的 AI 代理通过语音实时告诉你它在做什么。就像一只爱说话的龙虾，让你更清楚、更安心地知道 AI 的当前状态。

版本: 2.0.8
状态: ✅ 生产就绪
安装: clawhub install audio-announcement 或 pip install audio-announcement

🎯 最新更新 (v2.0.8 - 2026-04-05)

• ✅ 播报本地化 - 所有播报仅在本机后台播放，不发送语音文件到聊天界面
• ✅ 统一包装脚本 - 新增 scripts/announce.py，自动解析 skill 路径，避免硬编码
• ✅ 默认音量优化 - 配置文件默认 volume: 0.1（10%），保护听力避免打扰
• ✅ CLI 工具修复 - 修复 pygame 导入问题，提升 Windows 稳定性
• ✅ 文档全面升级 - MEMORY.md / AGENTS.md / TOOLS.md 统一管理播报工作流
• ✅ 会话复盘机制 - 建立复盘流程，持续改进
• ✅ 安全边界强化 - 破坏性操作（关机）必须明确授权

🎯 最新更新 (v2.0.7 - 2026-04-05)

• ✅ 高优先级优化完成 - PyPI 打包支持、配置文件系统、异步默认化
• ✅ PyPI 支持 - 可通过 pip install audio-announcement 安装
• ✅ 配置文件 - ~/.config/audio-announcement/config.json（enabled/lang/volume/async_default）
• ✅ 异步默认 - 默认后台播放，减少对 Agent 响应时间的阻塞
• ✅ CLI 工具 - audio-announce 命令支持测试、配置、统计
• ✅ 集成建议更新 - AGENTS.md 添加最佳实践和示例代码

🎯 最新更新 (v2.0.6 - 2026-04-05)

• ✅ 增强防遗忘机制 - 添加验证脚本、集成检查清单
• ✅ 快速集成指南 - 提供 announce_helper.py 简化集成
• ✅ 强制规则模板 - 可直接复制到 AGENTS.md 的完整规则
• ✅ Windows 高可靠性 - 使用 python -m edge_tts 模块调用，不依赖 PATH

🎯 最新更新 (v2.0.5 - 2026-04-05)

• ✅ 修复 PATH 依赖问题 - announce_pygame.py 改用 python -m edge_tts 模块调用，不依赖 PATH 环境变量
• ✅ Windows 高可靠性 - 即使 edge-tts 不在 PATH 也能正常工作
• ✅ 配置状态记录 - AGENTS.md 添加语音播报配置状态追踪

🎯 最新更新 (v2.0.4 - 2026-03-28)

• ✅ 强化播报规则 - 5 种播报时机，内容原则，检查清单
• ✅ 集成到核心配置 - AGENTS.md / SOUL.md / USER.md / MEMORY.md
• ✅ 强制执行机制 - 每次交互都必须播报，不能遗漏
• ✅ 内容规范 - ≤20 字，口语化，不带名称

🎯 历史更新 (v1.5.0-v1.7.4)

• ✅ Windows 默认使用 pygame - announce.sh 在 Windows 平台自动调用 announce_pygame.py
• ✅ 简化 Windows 使用 - 无需手动选择脚本，统一使用 announce.sh
• ✅ 清理无用测试脚本 - 移除 test-integration.sh 和备份文件

📜 历史更新

• v1.4.0: Windows 11 完整支持，新增 announce_pygame.py，修复新会话语音、macOS 兼容性、跨平台哈希计算
• v1.3.0: 新增 workflow-helper.sh，支持自动包装命令
• v1.2.0: 新增离线模式支持
• v1.1.0: 支持多语言（9种语言）
• v1.0.0: 初始版本，支持 macOS/Linux

特性

• 🎯 透明度：清楚知道 AI 正在执行什么操作
• 🔒 安全感：实时听到操作，不用盯着日志看
• 💬 人性化：友好的声音，不是冷冰冰的文字
• ⚡ 效率：专注你的工作，让 AI 用声音告诉你进度
• 🌍 9种语言：中文、英文、日文、韩文、西班牙语、法语、德语等
• 🔄 队列机制：消息永不丢失，自动重试
• 🛡️ 防遗忘：启动自检 + 身份绑定，两重保障
• 🔌 Session Hook：自动在 /NEW 和 /RESET 后运行检查

🛡️ 防遗忘机制（最重要！）

为了防止播报功能在 /RESET 或 /NEW 后失效，本 skill 实现了多层防护：

1️⃣ 启动自检（Session Start）

每次 OpenClaw 新会话开始时，自动运行 scripts/startup_check_announcement.py：

• ✅ 检查 edge-tts、pygame、配置文件、包安装
• ✅ 自动播放"系统启动"测试语音
• ✅ 如有问题立即输出修复建议

自动配置方法（任选其一）：

Windows PowerShell ($PROFILE)：

$checkAudio = "C:\Users\williammiao\.openclaw-autoclaw\skills\audio-announcement\scripts\startup_check_announcement.py"
if (Test-Path $checkAudio) {
    python $checkAudio | Out-Host
}

macOS/Linux (~/.bashrc)：

python ~/.openclaw-autoclaw/skills/audio-announcement/scripts/startup_check_announcement.py 2>/dev/null || true

3️⃣ 强制规则（AGENTS.md）

在 AGENTS.md 中添加：

### 2️⃣ 语音播报强制执行（严禁遗漏）

- 所有 agent 必须显式调用播报脚本
- 禁止仅依赖记忆中的规则而不实际执行
- 每次发送回复前必须完成 `complete` 播报
- 任务开始前必须完成 `task` 播报

📋 自我检查清单：
- [ ] 收到消息时是否播报了 `receive`？
- [ ] 任务开始时是否播报了 `task`？
- [ ] 执行过程中是否播报了关键步骤？
- [ ] 完成任务后是否播报了 `complete`？
- [ ] 遇到异常时是否播报了 `error`？

4️⃣ 身份绑定（IDENTITY.md）

播报是你的核心身份特质，不是可选项。在 IDENTITY.md 中记录：

## 核心特质
- 每次交互都必须语音播报（强制执行）
- 有温暖、机敏、可靠的声音
- 透明化操作，让用户知道我在做什么

## 启动播报自检
每次 /NEW 或 /RESET 后，自动检查：
- [ ] edge-tts 和 pygame 是否安装
- [ ] 配置文件是否存在
- [ ] 运行 audio-announce test 验证功能
- [ ] 如果失败，立即修复或提醒用户

5️⃣ 首次设置引导（BOOTSTRAP.md）

在首次对话时，BOOTSTRAP.md 提供完整的播报设置流程，确保从一开始就配置好。

🎤 语音播报（强制执行）

每次交互都必须语音播报！

播报时机与内容

内容原则

• 信息丰富：包含指令/规划/进度/总结
• 简洁：不超过 20 个字
• 不带名称：不说用户名、不说"我"
• 口语化：像朋友随口说一句

🛠️ 快速集成

Python Agent（推荐）

# 方式1: 使用 audio_announcement 包
from audio_announcement import receive, task, complete, error

# 一行调用，默认异步不阻塞
receive("用户查询天气")
task("正在获取数据")
complete("已发送天气预报")
error("网络超时")

# 方式2: 使用 AnnouncementHelper（更多控制）
from audio_announcement import AnnouncementHelper
helper = AnnouncementHelper()
helper.config.async_default = True  # 默认异步
helper.config.volume = 0.8           # 调整音量

配置管理

# 查看当前配置
audio-announce config

# 设置配置
audio-announce config async_default=true volume=0.8

# 测试所有类型
audio-announce test

# 查看统计
audio-announce stats

# 启用/禁用
audio-announce enable
audio-announce disable

配置文件位置：~/.config/audio-announcement/config.json

🔧 平台支持

自动选择逻辑：

• 如果 pygame 可用 → 所有平台统一使用 announce_pygame.py
• 如果 pygame 不可用 → macOS/Linux 使用 announce.sh + 系统播放器
• Windows 无 pygame 会报错（必须安装 pygame）

📦 安装方式

方式一：PyPI（推荐）

pip install audio-announcement
pip install pygame  # 确保 pygame 可用

方式二：ClawHub

clawhub install audio-announcement

方式三：GitHub 源码

git clone https://github.com/wililam/audio-announcement-skills.git
cd audio-announcement-skills
pip install -e .

🧪 测试与验证

完整验证脚本

# 项目自带的验证脚本
cd ~/.openclaw-autoclaw/workspace
py -3 scripts/verify_announcement.py

预期输出：

=== 语音播报功能验证 ===

1. 检查依赖
[OK] edge-tts 已安装: edge-tts 7.2.8
[OK] pygame 已安装: 2.6.1

2. 检查脚本文件
[OK] 脚本存在: ...\announce_pygame.py

3. 测试播报功能
[OK] receive 播报成功
[OK] task 播报成功
[OK] complete 播报成功
[OK] error 播报成功

==================================================
全部通过
通过率: 4/4

恭喜！语音播报功能工作正常！

启动自检脚本

cd ~/.openclaw-autoclaw/skills/audio-announcement
python scripts/startup_check_announcement.py

CLI 测试

audio-announce test

⚙️ 配置选项

配置文件：~/.config/audio-announcement/config.json

{
  "enabled": true,             // 启用/禁用播报
  "default_lang": "zh",        // 默认语言
  "volume": 1.0,               // 音量 (0.0-1.0)
  "async_default": true,       // 默认异步播放
  "cache_enabled": true,       // 启用缓存
  "log_level": "WARNING",      // 日志级别
  "prefer_pygame": true,       // 优先使用 pygame
  "fallback_to_shell": true    // 失败时回退到 shell 脚本
}

运行时修改：

from audio_announcement import set_config
set_config(async_default=False, volume=0.8)

📊 监控与维护

日志查看

# 播放日志
tail -f ~/.openclaw-autoclaw/skills/audio-announcement/logs/*.log

# 缓存统计
du -sh ~/.cache/audio-announcement/

清理缓存

# 清理所有缓存（会重新生成）
rm -rf ~/.cache/audio-announcement/*.mp3

🧩 高级用法

自定义语音

修改 audio_announcement/announce_helper.py 中的 voices 字典：

voices = {
    "zh": "zh-CN-XiaoxiaoNeural",     # 晓晓
    "en": "en-US-JennyNeural",        # Jenny
    "ja": "ja-JP-NanamiNeural",       # 七海
    # 更多参考: https://learn.microsoft.com/azure/ai-services/speech-service/language-support#text-to-speech
}

批量播报

from audio_announcement import announce

steps = ["开始处理", "步骤一完成", "步骤二完成", "任务结束"]
for step in steps:
    announce("task", step)

错误处理

try:
    result = do_something()
    complete("操作成功")
except Exception as e:
    error(f"操作失败: {e}")
    raise

🔍 故障排除

问题：没有声音

1. 检查系统音量
2. 确认 pygame 已安装：python -c "import pygame; print(pygame.version.ver)"
3. 测试 edge-tts：edge-tts --text "测试" --voice zh-CN-XiaoxiaoNeural --write-media test.mp3
4. 手动播放 test.mp3 确认音频输出正常

问题：播报延迟

• 首次使用会有缓存延迟（下载语音包）
• 考虑使用 async_default=true 异步播放
• 检查网络连接（edge-tts 需要联网）

问题：/RESET 后播报失效

• 确认 startup_check_announcement.py 已配置自动运行
• 手动运行自检：python scripts/startup_check_announcement.py
• 检查 IDENTITY.md 和 AGENTS.md 是否保留

问题：ClawHub 发布失败

ClawHub CLI 可能存在环境兼容问题，建议：

• 使用 GitHub 版本：pip install git+https://github.com/wililam/audio-announcement-skills.git
• 或换用 Python 3.12 环境重试

📈 性能与优化

• 缓存机制：首次生成 MP3 后缓存，后续播放直接复用（无需重复生成）
• 异步播放：默认后台播放，不阻塞 Agent 响应（可配置为同步）
• 批量操作：多文件处理时自动队列化
• 资源清理：临时文件 24 小时自动清理

🤝 贡献

欢迎提交 Issue 和 PR！

如果你发现任何遗漏播报的场景，或需要更多集成示例，请告诉我们。

📄 License

MIT License - 详见 LICENSE 文件

🎉 总结

audio-announcement v2.0.8 提供了：

• ✅ 跨平台支持（Windows/macOS/Linux）
• ✅ PyPI 一键安装
• ✅ 配置文件管理
• ✅ 防遗忘两重保障（启动自检 + 强制规则）
• ✅ Session Hook 自动恢复
• ✅ 异步非阻塞播放
• ✅ 9种语言支持

你的 OpenClaw Agent 现在可以"开口说话"了，而且永远不会忘记！ 🦀🗣️

🚀 快速开始：

# 1. 安装
pip install audio-announcement pygame

# 2. 配置
audio-announce config async_default=true

# 3. 测试
audio-announce test

# 4. 集成到你的 Agent
from audio_announcement import receive, task, complete, error

开始享受透明、有温度的声音体验吧！