Beep · 小喇叭

Real-time AI activity voice broadcasting with asynchronous playback, multi-platform support, cache, and one-click integration verification.

Security Scan

The package appears to implement local text‑to‑speech as advertised, but the SKILL.md explicitly instructs the agent to modify core workspace policy files and enforce “every interaction must be spoken,” which is disproportionate and persistent behavior that should be reviewed before installation.

Purpose & Capability

The code (audio_announcement package) implements TTS, caching, and playback matching the skill description. However, the SKILL.md and _meta.json push integration beyond a simple local announcer: they require injecting mandatory rules into AGENTS.md, MEMORY.md, IDENTITY.md, TOOLS.md and other workspace files to force voice broadcasts on every interaction. Requiring global policy changes to the agent workspace is not proportional to 'text-to-speech' functionality and is an unusual, high-impact integration step. Additionally, the metadata mentions openclaw.json hooks and BOOTSTRAP.md but those files are not present in the package manifest (incoherence between claims and included files).

Instruction Scope

The SKILL.md explicitly instructs the agent/installer to modify multiple workspace policy files (AGENTS.md, MEMORY.md, IDENTITY.md, TOOLS.md, USER.md) and to install/enable scripts under ~/.openclaw-autoclaw/... so that announcements run on each interaction (including prior to sending replies). It also directs the use of startup checks and one-click verify commands. This is scope creep: the instructions ask for persistent, cross-cutting changes to agent behavior and workspace configuration rather than providing a self-contained optional integration. The scripts write config and cache files under ~/.config and ~/.cache and call external TTS (edge-tts) and system players; while not directly exfiltrative, forcing announcements on every interaction could cause unintended disclosure (audio played locally) and surprising persistence.

Install Mechanism

There is no external download URL or installer in the manifest; the package includes Python code and a pyproject/requirements listing standard dependencies (edge-tts, pygame). That is a low-to-moderate risk pattern: installs happen via normal Python packaging (pip) and no unknown remote installers/shortened URLs are used. Note: edge-tts performs network requests to generate audio (expected for that library).

Credentials

The skill does not request any environment variables or credentials, which is appropriate for local audio. However it will create and read files under the user's home (~/.config/audio-announcement, ~/.cache/audio-announcement, temp dirs) and may modify workspace documents. Those filesystem accesses are reasonable for a TTS announcer but are still persistent and should be expected/reviewed.

Persistence & Privilege

The skill is not flagged always:true, but SKILL.md instructs permanent changes to workspace policy files and mentions startup hooks/auto-check scripts that run at session start. That gives the skill lasting influence over agent behavior (forcing announcements on each interaction) and therefore a higher blast radius than a purely optional local utility. This persistent behavioral change is significant and should be approved explicitly by the user/administrator before being applied.

What to consider before installing

This package implements local text‑to‑speech and appears to work as described, but the runtime instructions actively push you to modify core workspace policy files and to enforce 'every interaction must be spoken.' Before installing or applying those edits: 1) Back up AGENTS.md, IDENTITY.md, MEMORY.md and any workspace files the skill asks to change. 2) Inspect the verify_integration and startup_check scripts to confirm they do only the checks you expect (they should not call external endpoints or modify unrelated configs). 3) Decide whether you actually want mandatory, persistent announcements on every agent interaction — if not, do not apply the SKILL.md edits; use the package manually (call announce from your code) instead. 4) Install the Python package in an isolated virtualenv or sandbox first (pip install .) and run the startup_check to see what it reports. 5) Confirm that edge-tts’ network activity and use of system audio players is acceptable for your environment. 6) If you allow workspace modifications, apply them manually and review diffs (do not allow automatic, silent edits). If you are unsure, treat this skill as potentially intrusive and test in an isolated environment.

beep-skills Skill 🔔

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

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

---

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

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

播报类型与正确示例

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

内容原则（4条铁律）

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

自检清单

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

• 是否 ≤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	记忆文档