Peon Ping——AI 代理语音通知
为 Claude Code、Codex、Cursor 等 AI 编程代理添加魔兽争霸风格的语音和桌面通知，不再反复盯着终端。
证据显示：安装脚本会修改用户配置（如~/.claude/settings.json）并下载声音包，但未明确说明权限范围或提供最小权限原则。用户确认方面，安装过程有交互式向导，但未明确要求用户确认所有修改。数据流透明度：文档描述了事件和通知，但未详细说明数据如何流动或是否上传。敏感数据处理：未提及处理敏感数据，但可能读取会话信息。依赖安全：未提供依赖清单或安全审计。外部影响：会修改系统设置和播放声音，但未说明影响范围。回滚：提供卸载脚本，但未说明回滚机制。来源归属：未明确说明声音包来源和验证。
证据显示：README和测试文件在功能描述上基本一致，但部分功能（如Windows支持）在文档中标注为部分支持，存在不一致。依赖可用性：依赖外部服务（如Homebrew、GitHub）和系统组件，但未提供依赖可用性保证。失败消息：文档中提供了一些调试命令，但未详细说明错误处理。
证据显示：明确列出了多种IDE和平台支持，场景覆盖广泛。能力边界：文档说明了支持的事件和功能，但未明确限制。触发精度：提供了详细的配置选项和事件分类，但未说明触发条件的具体实现。环境适配：提供了多种安装方式和配置选项，但未说明所有环境的具体适配。
证据显示：README结构清晰，包含安装、配置、使用等章节。安装说明详细，提供了多种安装方式。命名稳定性：命令和配置项命名一致。示例和FAQ：提供了示例和部分FAQ，但未覆盖所有问题。已知限制：文档中提到了Windows部分功能不支持，但未全面列出。许可证：MIT许可证明确。版本和变更日志：未提供明确的版本号和变更日志。维护责任：未明确说明维护者或贡献指南。
证据显示：输出（声音和通知）设计直观，易于理解。边际价值：提供了独特的功能（游戏声音通知），但可能对部分用户价值有限。成本效益：安装和使用成本低，但需要下载声音包和配置。
证据显示：README中的声明部分有测试支持（如OpenCode适配器测试），但未提供所有声明的验证。跨来源验证：未提供多个来源的验证。事实与推断分离：文档中未明确区分事实和推断。
- 安装脚本会修改用户配置和下载外部内容，建议审查后再执行。
- 声音包来源未明确验证，可能存在安全风险。
- 部分功能（如Windows高级命令）未完全实现，文档可能夸大。
这个 Agent 能做什么，适合哪些场景？
peon-ping 是一款为 AI 编程代理提供游戏角色语音提示与醒目横幅通知的开源工具。当代理完成、等待输入、出错或触发速率限制时，它通过事件钩子播放魔兽争霸、星际争霸、传送门、塞尔达等游戏中的语音片段，并在所有屏幕上显示覆盖式横幅（macOS/WSL/MSYS2），同时更新终端标签标题。该工具实现了编码事件声音包规范（CESP），支持通过适配器接入 Claude Code、Amp、GitHub Copilot、Codex、Cursor、OpenCode、Kilo CLI、Kiro、Kimi Code、Windsurf、Google Antigravity、Rovo Dev CLI、DeepAgents、Qwen Code、iFlow CLI、Trae、Kiro IDE、ECA 等；内置 MCP 服务器，允许任何 MCP 兼容代理直接调用 play_sound 工具播放指定声音。配置丰富，可调整音量、分类开关、通知样式、主题、包轮换、路径和 IDE 规则，支持专注模式、会议检测、手机推送（通过 ntfy）等，并附带基于 CLI 的健身教练功能。
peon-ping 安装钩子或适配器，将 IDE 事件（如 session.start、task.complete、input.required、task.error、resource.limit、user.spam）映射为声音和通知。其核心是 peon.sh/peon.ps1 脚本，负责解析事件负载、读取 ~/.claude/hooks/peon-ping/config.json 配置、选择声音包（通过六层优先级：session_override > path_rules > ide_rules > pack_rotation > default_pack > 内置 'peon'），并使用 afplay（macOS）、pw-play/paplay/ffplay（Linux）或 Windows 上的 MediaPlayer/SoundPlayer 播放音频。桌面通知通过 macOS JXA Cocoa 覆盖层或 Windows Forms 弹出窗口显示，可点击且能聚焦终端；也可切换为系统标准通知。它还提供 CLI 命令（peon）用于管理包、音量、通知、轮换、路径绑定、排除目录等。MCP 服务器（mcp/peon-mcp.js）暴露 play_sound 工具和目录资源。
- 使用 Claude Code 的开发者，希望在代理完成长任务时听到“Work complete”语音，不必一直盯着终端。
- 在 IDE 中运行 Codex 的开发者，希望代理需要权限时获得醒目提示，避免错过输入请求。
- 多项目工作者，希望根据项目目录（path_rules）或 IDE（ide_rules）自动切换不同声音包。
- 使用 SSH 或 devcontainer 的远程开发者，通过 peon relay 在本地播放音频。
- 想要手机推送的开发者，通过 peon mobile ntfy 设置 ntfy 主题，在离开电脑时接收通知。
- 希望在编码时被提醒锻炼的开发者，使用 peon trainer 功能进行每日健身提醒。
这个 Agent 有哪些优点和局限？
- 支持广泛的 IDE 和 CLI 集成，包括 Claude Code、Codex、Cursor、Copilot 等，通过适配器覆盖主流工具。
- 丰富的配置选项，包轮换、路径/IDE 绑定、专注检测、会议检测、通知样式和主题，高度可定制。
- 内置 MCP 服务器，允许 AI 代理自主选择播放声音，提供更灵活的交互。
- 遵循开放的 CESP 规范，声音包可从注册中心获取，可移植。
- 主要针对终端工作流优化，对 GUI IDE 的支持需要额外适配器配置，可能不够无缝。
- Windows 支持部分功能不完整，如 setup、rotation、preview 等命令尚未实现。
- 依赖外部工具如 ffmpeg（WSL2 上播放 MP3）和 terminal-notifier（macOS 标准通知），增加了安装复杂度。
- 音频输出在部分环境（如 WSL2 旧版本）可能需要手动调整，存在兼容性问题。
如何安装或部署这个 Agent？
推荐使用 Homebrew 安装：brew install PeonPing/tap/peon-ping，然后运行 peon-ping-setup 注册钩子并下载声音包。或者使用安装脚本：curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash。Windows 用户可运行 PowerShell 安装脚本：Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1"; powershell -ExecutionPolicy Bypass -File .\install.ps1。也可通过 Nix 直接运行：nix run github:PeonPing/peon-ping -- status。
如何使用这个 Agent？
安装后，运行 peon setup 启动交互式向导配置音量、分类、通知主题和位置。常用命令：peon status 检查状态，peon toggle 切换静音，peon packs list 查看已安装声音包，peon packs use glados 切换包，peon notifications on/off 控制桌面通知，peon volume 0.7 调整音量。在 Claude Code 中可使用斜杠命令 /peon-ping-toggle 和 /peon-ping-config。MCP 客户端可添加 MCP 服务器配置以使用 play_sound 工具。