Beep - Xiao Laba

Other

Provides mandatory, real-time voice announcements for all agent interactions, using concise, natural phrases under 20 characters to report received commands,...

Audits

Pending

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install audio-announcement-skills

beep-skills Skill 🔔

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

版本: 2.2.0 | 状态: ✅ 生产就绪

⚠️ 强制播报规则（重要！）

每次交互都必须语音播报！ 这是 OpenClaw Agent 的核心行为准则，必须严格遵守。

播报类型与正确示例

时机	类型	正确示例（≤20字）	错误示例
收到消息	`receive`	"收到发布指令"	"我收到了你的上传请求" ❌
开始工作	`task`	"准备上传到GitHub"	"我开始准备发布" ❌
执行中	`task`	"正在生成文档"	"我正在验证环境" ❌
任务完成	`complete`	"上传完成"	"我完成了版本升级" ❌
发送回复	`complete`	"已发送项目地址"	"我给你发了地址" ❌
发生错误	`error`	"网络连接失败"	"我遇到网络问题" ❌

内容原则（4条铁律）

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

自检清单

每次调用播报前，问自己：

是否 ≤20 字？
是否像朋友说话一样自然？
是否不含"我"、"你"、"用户"等名称？
是否包含足够信息（动作/目标/结果）？
是否使用正确的类型（receive/task/complete/error）？

📁 文件集成规则（必须遵守）

安装 beep-skills 后，需要在以下 OpenClaw 工作区文件中加入播报规则。每个文件的职责不同，缺一不可。

需要修改的文件清单

文件	职责	需要加入的内容
`AGENTS.md`	智能体行为准则	播报时机表、内容原则、强制播报场景、播报脚本路径、示例
`MEMORY.md`	记忆文档	强制播报规则表（receive/task/complete/error）
`IDENTITY.md`	身份标识	强制播报声明、启动播报自检
`TOOLS.md`	工具文档	语音播报系统说明、安装指南、配置
`USER.md`	用户偏好	播报偏好设置

1. AGENTS.md — 智能体行为准则

文件路径: workspace/AGENTS.md

需要加入的内容:

## 🦊 语音播报（强制执行）

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

### 播报时机与内容
| 时机 | 类型 | 内容要求 | 示例 |
|------|------|----------|------|
| 收到消息 | `receive` | 收到的指令信息 | "收到上传指令" |
| 开始工作 | `task` | 工作规划 | "准备上传到GitHub" |
| 执行中 | `task` | 下一步要处理的内容 | "正在生成文档" |
| 任务完成 | `complete` | 工作总结 | "上传完成" |
| **发送回复** | `complete` | 回复内容的简短总结 | "已发送项目地址" |

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

### 强制播报场景
- 每次收到用户消息 → 先播报指令内容
- 开始执行任务 → 播报工作规划
- 执行过程中 → 播报下一步要做什么
- 任务完成/失败 → 播报工作总结
- **发送文字回复前 → 播报回复内容的简短总结（1句话）**
- **API/网络异常时 → 播报告警信息**
  - Token 用完 → "额度不足"
  - 网络超时 → "连接超时"
  - 接口异常 → "服务异常"
  - 模型不可用 → "模型繁忙"

### 播报脚本
```bash
~/.openclaw-autoclaw/workspace/skills/beep-skills/scripts/announce.py <type> "<message>" [lang]

示例

# 收到消息 - 说出指令
python3 ~/.openclaw/workspace/skills/beep-skills/scripts/announce.py receive "收到上传指令"

# 开始工作 - 说出规划
python3 ~/.openclaw/workspace/skills/beep-skills/scripts/announce.py task "准备上传文件"

# 执行中 - 说出进度
python3 ~/.openclaw/workspace/skills/beep-skills/scripts/announce.py task "正在生成文档"

# 任务完成 - 说出总结
python3 ~/.openclaw/workspace/skills/beep-skills/scripts/announce.py complete "上传完成"

# 发送回复前 - 播报回复总结
python3 ~/.openclaw/workspace/skills/beep-skills/scripts/announce.py complete "已发送项目地址"

注意事项

路径使用正斜杠 / 而非反斜杠 \
播报内容不超过 20 个字
播报内容不带引号 ""
播报内容口语化

配置

主脚本: workspace/scripts/announce.py 技能
备用脚本: skills/beep-skills/audio_announcement/scripts/announce_pygame.py
配置文件: ~/.config/audio-announcement/config.json (音量=0.1, 异步默认=true)
配置说明: 音量、语言、异步设置
参考文档: AGENTS.md 和 IDENTITY.md


---

### 2. MEMORY.md — 记忆文档

**文件路径**: `workspace/MEMORY.md`

**需要加入的内容**（在"行为准则"部分）:

```markdown
### 强制播报规则
| 时机 | 类型 | 内容 |
|------|------|------|
| 收到指令 | receive | "收到" |
| 开始执行 | task | "开始执行" |
| 任务完成 | complete | "完成" |
| 任务出错 | error | "错误" |

- 播报内容需简洁，不超过 20 字
- 默认使用中文（zh）播报
- 若音频模块不可用，降级为控制台输出 [音频] 标签

3. IDENTITY.md — 身份标识

文件路径: workspace/IDENTITY.md

需要加入的内容:

### 强制播报
- ✅ 每次交互都必须语音播报（强制执行）
- ✅ 有温暖、机敏、可靠的声音
- ✅ 透明化操作，让用户知道我在做什么
- ✅ 遵守 AGENTS.md 中的播报规则

## 启动播报自检

### 配置文件路径
- **Windows:** `C:\Users\<用户名>\.openclaw-autoclaw\workspace\skills\beep-skills\config.json`
- **Linux/macOS:** `~/.openclaw-autoclaw/workspace/skills/beep-skills/config.json`

### 测试播报
```bash
python3 ~/.openclaw-autoclaw/workspace/skills/beep-skills/scripts/announce.py complete "测试播报"


---

### 4. TOOLS.md — 工具文档

**文件路径**: `workspace/TOOLS.md`

**需要加入的内容**:

```markdown
## 语音播报 (Audio Announcement)

### 安装
```bash
pip install beep-announcement pygame

配置

{
  "volume": 0.1,
  "async_default": true,
  "default_lang": "zh"
}

测试

audio-announce test ""

Python API

from audio_announcement import receive, task, complete, error


---

### 5. USER.md — 用户偏好

**文件路径**: `workspace/USER.md`

**需要加入的内容**（在"偏好与习惯"部分）:

```markdown
- **播报偏好:** 只在本地后台播放，不发送语音文件到聊天

🛠️ 快速集成

Python Agent（推荐）

# 方式1: 使用 beep 包（新名称）
from beep import receive, task, complete, error

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

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

命令行工具

# 新命令（推荐）
beep test                    # 测试所有类型播报
beep config                  # 查看/设置配置
beep verify-integration      # 一键验证集成
beep stats                   # 查看统计信息

# 旧命令（兼容）
audio-announce test         # 仍可用（向后兼容）
audio-announce config

配置管理

# 查看当前配置
beep config

# 设置配置
beep config async_default=true volume=0.8

# 测试所有类型
beep test

# 一键验证集成（推荐！）
beep verify-integration

# 查看统计
beep stats

# 启用/禁用
beep enable
beep disable

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

⚙️ 配置选项

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

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

运行时修改：

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

🔧 平台支持

平台	主方案	备选方案	安装命令
Windows	pygame	无	`pip install beep-announcement pygame`
macOS	pygame	afplay	`brew install edge-tts && pip install pygame beep-announcement`
Linux	pygame	mpg123	`apt install edge-tts mpg123 && pip install pygame beep-announcement`

自动选择逻辑：

如果 pygame 可用 → 所有平台统一使用 pygame 方案
如果 pygame 不可用 → macOS/Linux 使用系统播放器
Windows 无 pygame 会报错（必须安装 pygame）

📦 安装

# PyPI（推荐）
pip install beep-announcement pygame

# ClawHub
clawhub install beep

# GitHub 源码
git clone https://github.com/wililam/beep-announcement.git
cd beep-announcement
pip install -e .

🧪 验证集成

# 一键验证（推荐！）
beep verify-integration

# 基础测试
beep test

听到测试语音 + 看到 "🎉 所有检查通过！" 表示集成成功。

📁 文件结构

beep-skills/
├── SKILL.md                    # 本文件（技能说明 + 集成规则）
├── _meta.json                  # 技能元数据
├── pyproject.toml              # 安装配置
├── requirements.txt            # 依赖说明
├── scripts/
│   ├── announce.py             # 统一播报入口脚本
│   └── startup_check_announcement.py  # 启动自检
└── audio_announcement/
    ├── __init__.py             # 包入口
    ├── announce_helper.py      # 核心库
    ├── cli.py                  # CLI 工具
    └── scripts/
        └── announce_pygame.py  # pygame 播放脚本
│       └── announce.ps1        # PowerShell 脚本
└── tests/                      # 测试用例

🛡️ 防遗忘机制（6层防线）

为确保 Agent 在任何情况下都不会忘记播报，系统设计了 6 层防线：

层级	机制	文件	触发时机	强制力
1	Session Hook	`openclaw.json`	每次会话启动	🔴 程序化强制
2	启动自检脚本	`scripts/startup_check_announcement.py`	/new 或 /reset	🔴 程序化强制
3	BOOTSTRAP.md	`workspace/BOOTSTRAP.md`	新会话自动加载	🟡 规则提醒
4	AGENTS.md	`workspace/AGENTS.md`	Agent 读取行为准则	🟡 规则提醒
5	MEMORY.md	`workspace/MEMORY.md`	Agent 读取记忆	🟡 规则提醒
6	IDENTITY.md	`workspace/IDENTITY.md`	Agent 读取身份	🟡 规则提醒

防遗忘流程

新会话启动
    ↓
[层1] openclaw.json hooks → 自动运行 startup_check_announcement.py
    ↓
[层2] startup_check_announcement.py → 检查播报模块状态
    ↓
[层3] BOOTSTRAP.md → 加载播报规则到上下文
    ↓
[层4] AGENTS.md → 完整播报规则（时机、原则、示例）
    ↓
[层5] MEMORY.md → 播报规则表（快速参考）
    ↓
[层6] IDENTITY.md → 身份声明（强制播报）
    ↓
Agent 开始工作，每次交互都播报

关键配置

openclaw.json hooks（程序化强制）：

{
  "hooks": {
    "on_session_start": [
      {
        "run": "python scripts/startup_check_announcement.py",
        "description": "启动时自动检查播报模块状态"
      }
    ],
    "on_new_session": [
      {
        "run": "python scripts/startup_check_announcement.py",
        "description": "新建会话时自动检查播报模块状态"
      }
    ]
  }
}

BOOTSTRAP.md（规则提醒）：

每次新会话自动加载
包含播报规则速查表
包含启动自检清单

📚 相关文档

文档	说明
`BOOTSTRAP.md`	会话启动规则
`AGENTS.md`	智能体行为准则
`MEMORY.md`	记忆文档