【免费下载链接】peon-pingWarcraft III Peon voice notifications ( more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.项目地址https://gitcode.com/gh_mirrors/pe/peon-ping点击查看免费下载peon-ping 是一个面向 AI 编码 Agent 的语音与通知提示工具当 Claude Code、Codex、Grok Build、Cursor 等智能体完成任务、需要权限或发生错误时用《魔兽争霸 III》兽人苦工Peon等游戏角色语音加上醒目的桌面横幅提醒你回到终端。本篇文章以仓库根目录的 CHANGELOG.md 为主干梳理该项目从 v1.0.0 到 v2.37.0 的完整演进脉络并结合 peon.sh、config.json 与测试用例等源码讲清事件路由、CESP 标准、音色包管理、多 IDE 适配器与跨平台音频这些核心机制的实现原理。读完本文你将理解一个给 Agent 配音的工程是如何一步步从单一 Claude Code 钩子长成覆盖 20 智能体的完整体系并掌握其中关键配置项的实战含义。一、版本纪元一个 AI Agent 提示系统的成长时间线CHANGELOG 记录了一个清晰的演进节奏项目诞生于 2026 年 2 月v1.0.0核心定位是Claude Code 钩子 Warcraft III 兽人苦工语音包 macOS 桌面通知 终端标签页标题。随后几乎以每 2~7 天一版的节奏迭代形成了三条主线引擎层事件路由、状态机、防抖/去重、静音窗口、多会话管理接入层从单一 Claude Code hook 扩展出 20 IDE/CLI 适配器体验层音色包注册中心registry、训练师Trainer、TTS、MCP 服务器、移动端推送。从版本号看v1.x 主要是安装器与播放链路打基础v2.x 是功能爆发期。v2.0.0 引入 Peon Trainerv2.5.0 加入cwd状态字段v2.12.0 补齐全部 IDE 的 Windows PowerShell 适配器v2.37.0 则完成了 Antigravity 与 Grok Build 的深度对接。这个节奏本身就是一个值得借鉴的工程样板每个版本都围绕真实用户的真实故障展开Fix 条目通常附带根因分析与 PR 编号Add 条目则明确标注了适配目标与配置文件路径。二、声音从哪来CESP 标准与七类事件分类理解 peon-ping 必须先理解它的声音分类学。项目实现了 Coding Event Sound Pack Specification (CESP) 这一开放标准将编程事件映射为七种音效类别定义在 peon.sh 的display_order中CESP 类别触发事件示例典型用途session.start会话开始打招呼Ready to work!task.acknowledge用户提交提示词应答声默认关闭task.complete任务结束Stop完工提示Work complete.task.error工具执行失败错误报警Bash 工具非零退出input.required权限请求、问题等待需要你回终端resource.limit上下文压缩资源上限预警user.spam短时间连续提问吐槽式烦人音效七类之外README 还提到 CESP 规范定义了session.end、task.progress等扩展类别音色包 manifest 可以声明但内置钩子事件暂不触发。这个类别 音色包的两层模型让同一个引擎可以驱动任意游戏/角色的语音音色包sound pack就是一个带 manifest 的声音集合仓库根目录的config.json中categories字段控制每类音效的开关categories: { session.start: true, task.acknowledge: false, task.complete: true, task.error: true, input.required: true, resource.limit: true, user.spam: true }从源码看peon.sh 的事件路由正是围绕这些类别实现的SessionStart直接落session.startUserPromptSubmit会先检查最近窗口内的提示词时间戳若在annoyed_window_seconds窗口内累计达到annoyed_threshold次则升级为user.spamStop落task.complete并受silent_window_seconds短任务静音约束。CHANGELOG v2.35.1 还记录了一个关键教训PEON_DIR目录不存在时所有配置写入会抛FileNotFoundError修复方式是在解析完PEON_DIR后立即确保数据目录存在——这类首装即崩溃的坑正是新用户最容易踩到的。三、安装体系与 CLI 的演进从一行脚本到子命令生态3.1 安装路径的多元化v1.6.0 确立了 Homebrew 安装为主要方式v1.8.0 引入原生 Windows PowerShell 安装器install.ps1v2.15.0 时代又出现--local、--global、--init-local-config三种模式的分化。到 v2.26.0安装器已支持install.sh --kimi这类无 Claude 依赖的独立根安装把文件放到~/.kimi/hooks/peon-ping/并自动启动 Kimi 监听守护进程当检测到已有 Claude 安装时还会把packs/目录软链过去共享语音包避免重复下载。3.2 CLI 从 flag 到子命令v1.6.0 是一次 breaking change所有--flag形式改为子命令peon --pause→peon pause。此后 CLI 家族持续扩张从 CHANGELOG 可以梳理出完整的子命令矩阵音色包peon packs list / use / install / remove / next / bind / unbind / bindingsv2.1.0 起含--registry、--all、--lang训练师peon trainer on/off/status/log/goal/helpv2.0.0 起v2.21.0 增加按星期排程调试peon debug on/off、peon logsv2.17.0 引入结构化日志9 阶段决策追踪通知peon notifications ...overlay/standard 样式与位置移动推送peon mobile ntfy/pushover/telegramSSH 音频peon ssh-audio [relay|auto|local]、peon relay --daemon/--stop/--status音量/轮换peon volume [0.0-1.0]、peon rotation [random|round-robin|agentskill]新建音色包peon create、peon eval name-or-pathv2.36.0 的草案 人耳验收门禁。值得注意的是 v2.36.0 引入的音色包验收门禁新包必须先成为~/.peon-ping/drafts/下的 draftmanifest 带x_openpeon_draft: true戳只有经过本地127.0.0.1网页逐个试听并显式 Approve 后才会移入~/.peon-ping/packs/成为正式包peon packs use拒绝激活 draft。整个流程由claude -p调用peon-ping-remixskill 按一条自然语言改稿意见重写生成提示词并重新渲染同时把 caption 与新旧 prompt 记入eval-log.json——这等于给音色包的诞生过程也建立了审计记录。四、多 IDE 适配器四种接入范式CHANGELOG 中最大的一块内容就是适配器。从 adapters/ 目录可以看到 20 个.sh/.ps1对它们按接入方式可分为四种范式理解这四种范式也就理解了整个适配层4.1 stdin JSON 钩子Claude Code 范式Claude Code、Qwen Code、iFlow CLI、Grok Build 等走标准输入 JSON 事件名模式。核心引擎 peon.sh 在启动时执行event_data json.load(sys.stdin)解析钩子事件并带一个防御性的 camelCase 归一化表hookName→hook_event_name、sessionId→session_id、toolName→tool_name等这正是 v2.29.0 为应对 GitHub Copilot CLI 1.0.48-1 泄露 camelCase 载荷而加入的。4.2 argv 参数钩子Rovo Dev / Kiro IDE 范式Rovo Dev CLI 的事件通过 shell 命令参数传递而非 stdinKiro IDE 的.kiro/hooks/*.kiro.hookAgent Hooks 也是把事件名放在 argv 上。对应适配器adapters/rovodev.sh就按参数位解析事件名再映射到 CESP。4.3 文件系统监听Amp / Antigravity / Kimi / Trae 范式对没有同步钩子 API 的 IDE采用后台守护进程轮询/监听会话文件。v2.28.0 的 Antigravity Python watcheradapters/antigravity-watcher.py用watchdog监听~/.gemini/antigravity/conversations/下的.pb/.db与brain/*/.system_generated/logs/transcript.jsonl以 25 秒空闲阈值判定回合结束并把事件以 CESP JSON 输出到 stdout 再管道给peon.sh。v2.37.0 是一次重大升级不再靠 mtime 猜回合边界而是解析transcript.jsonl以 Antigravity 自己的记录USER_INPUTsource: USER_EXPLICIT视为提问、带tool_calls的PLANNER_RESPONSE视为工作中、带散文且无工具调用的视为最终答复来确定回合实测重放 33 份 transcript 时 124 条用户提示恰好触发 124 次应答。4.4 TypeScript 插件OpenCode / Kilo / omp 范式OpenCode、Kilo CLI、oh-my-pi 使用插件系统。CHANGELOG v2.27.0 记录了一个典型 bugOpenCode 插件在 Bun 二进制下运行但插件代码跑在 Node 沙箱里Bun.spawn全局不可用导致每次触发都静默抛错被catch {}吞掉——修复是改用node:child_process的spawn。这个例子说明了宿主环境与插件沙箱的全局差异这类隐蔽陷阱。无论哪种范式事件最终都汇入peon.sh的会话识别层。peon.sh 的detect_session_ide()展示了识别优先级先看事件载荷里的source字段通过IDE_ALIASES归一化再看workspace_rootsCursor 特征最后按 session id 前缀codex-、omp-、kiro-ide-等 21 个前缀推断 IDE兜底才是claude。这正是 v2.30.0 所述kiro-ide- 排在 kiro- 前面让更长前缀优先命中的实现细节。五、核心引擎的纵深原理状态、路由与防抖5.1 状态文件与每会话钉住音色包引擎把会话状态持久化在.state.json关键状态包括session_packs会话→音色包映射、prompt_timestamps用于 spam 检测、last_active上次活跃会话的 session_id/pack/cwd/tty/时间戳、subagent_sessions、tty_names终端标签页命名等。v2.4.1 修复过session_packs字典格式不被in pack_rotation识别导致每回合换角色的 bug——这解释了音色包必须按会话钉住的设计初衷一个会话从头到尾只用同一个角色语音。5.2 六层音色包选择层级v2.22.0 把音色包选择固化成了六层优先级源码见 peon.shsession_override/peon-ping-use 技能钉住的会话包 path_rules按工作目录 glob 匹配 ide_rules按 IDE/source 匹配 pack_rotationrandom / round-robin / shuffle 轮换 default_pack静态兜底 硬编码 peon每层都有先验证包目录真实存在否则向下穿透的容错。此外exclude_dirs是独立短路层一旦 cwd 匹配排除目录整个调用直接suppressedTrue reasonexcluded_dir静默退出不播放任何声音也不发通知v2.25.0 修正了此前exclude 只跳过 path_rules 层的语义漏洞。路径匹配用fnmatch.fnmatch支持 glob同时对无通配符的路径做相等或前缀匹配peon.sh。5.3 防抖、去重与静音窗口CHANGELOG 反复出现防抖主题它们是同一类问题的不同解法Stop 防抖v1.4.0 引入后台任务快速连续完成时防止刷屏5 秒窗口内合并idle_prompt 去重v2.25.0Claude Code 在终端失焦时约每 60 秒重发idle_prompt通知若不做去重就会反复播放同一个完成音。suppress_idle_prompt_repeats默认trueidle_prompt_suppress_window_seconds默认3600在.state.json记录last_task_complete[session_id]窗口内同会话的后续 idle_prompt 直接静音silent_window_secondsv1.5.14 引入短于 N 秒的任务不发声session_start_cooldown_seconds默认 30会话开始音效的冷却。5.4 子代理subagent语义v2.13.0 起通过agent_id字段直接识别子代理事件Claude Code 只在 Task 工具派生的子代理载荷里带该字段suppress_subagent_complete开启时子代理的完成音被抑制但SubagentStart/Stop除外以保证音色包继承v2.30.0 又补充了subagent_input_required开关让子代理的权限请求仍能提醒用户。六、配置体系一份 config.json 看懂全部行为开关仓库根目录的 config.json 是引擎的默认配置模板也是 CHANGELOG 各版本新增配置项的汇总答案配置键默认值版本来源与含义volume0.5全局音量0.0–1.0default_packpeon默认音色包v2.7.0 由active_pack更名保留向后兼容pack_rotation_moderandomrandom / round-robin / shuffle / session_overridepath_rules/exclude_dirs/ide_rules[]路径匹配、目录排除、IDE 绑定v2.22.0annoyed_threshold/annoyed_window_seconds3/10user.spam 触发条件silent_window_seconds0短任务静音suppress_idle_prompt_repeats/idle_prompt_suppress_window_secondstrue/3600idle 提示去重v2.25.0suppress_subagent_complete/subagent_input_requiredfalse子代理控制v2.6.0 / v2.30.0terminal_tab_titletrue是否覆盖终端标签页标题v2.25.0tmux_passthroughfalsetmux 下是否透传 OSC 标题/颜色转义v2.32.0focus_detect/focus_detect_modefalse/allmacOS 专注模式感知all/sound/notificationsv2.30.0meeting_detectfalse会议检测需 Swift 助手meeting-detectnotification_title_idefalse标题显示项目 - IDEv2.25.0notification_title_marker●标题前缀符号可置空v2.19.0notification_title_script动态计算项目名的 shell 命令v2.13.0接收PEON_SESSION_ID/PEON_CWD/PEON_HOOK_EVENT/PEON_IDE环境变量project_name_map{}glob → 项目名映射mobile_notify.priority无ntfy/Pushover 显式优先级v2.31.0disabled_sounds无单声音禁用v2.26.0配peon sounds list/disable/enabletrainer见模板训练师开关、每日目标、提醒间隔、按星期排程v2.21.0tts见模板TTS 后端/音色/语速/音量/模式v2.24.0 真正可用debug/debug_retention_daysfalse/7结构化调试日志v2.17.0项目名的解析同样是一条明确的优先级链源码见 peon.sh状态内/peon-ping-rename会话名 tty::cwd复合键兜底名 CLAUDE_SESSION_NAME环境变量 项目根.peon-label文件 notification_title_script动态脚本 project_name_mapnotification_title_override git 仓库名 目录名。这条链在 v2.13.0 定稿v2.15.0 又修过/peon-ping-rename用tty::cwd导致同一项目不同标签页互相串名的 bug改为ppid::cwd键。此外v2.4.0 支持项目级覆盖在任意项目放.claude/hooks/peon-ping/config.json即可局部覆盖全局配置。七、通知系统的三次进化7.1 从标准横幅到 overlayv2.1.1 引入 macOS JXA Cocoa overlay 通知overlay/standard两档样式 peon notificationsCLI。v2.19.0 让同一会话的通知堆叠成单个 overlay 并显示计数徽章(3) project — needs approval用户恢复交互UserPromptSubmit/Stop/PreToolUse 等时自动消失notification_stacking默认true同版还为 glass/sakura/jarvis 三套主题加了可见的×关闭按钮notification_close_button。v2.15.1 引入NOTIFY_TYPE语义变量complete/permission/limit/idle/question顺着peon.sh → notify.sh → overlay的 argv 传递修正了此前只看颜色推断状态标签导致的错标。7.2 点击即聚焦click-to-focus从 v2.7.0 起通知点击后要**精确拉起发出声音的那个终端窗口**而不是最近聚焦的窗口。演进路径很有代表性macOS 下先从TERM_PROGRAM映射 bundle id再对 IDE 内嵌终端Cursor/Windsurf/Zed/VS Code用lsappinfo反查进程 PIDv2.8.0v2.17.2 补上 WezTerm bundle idv2.35.0 让标准通知模式也支持按 tty 精确选中 iTerm2 标签页、用open -b拉起对应 VS Code 系窗口Warp 则走WARP_FOCUS_URL深链跨 Spaces 切换v2.35.0。tmux 场景下v2.35.0还要在点击时现场询问tmux switch-client/select-window/select-pane定位到 Agent 自己的 pane而宿主终端的识别由scripts/local-focus.sh在点击时刻沿客户端进程祖先链反查v2.37.0 修复 tmux 冻结环境导致永远识别为首次附着终端的问题。7.3 跨机器relay 与移动推送v1.7.0 引入 SSH/远程音频本地起 relay 守护进程peon relay --daemon/--stop/--status远端 hook 通过 HTTP 把播放请求转发回本机devcontainer/Codespaces 则自动路由到host.docker.internal。v2.37.0 让被转发的远程 SSH 通知也支持点击聚焦peon.sh在POST /notify里嵌入白名单校验过的focus对象relay.sh校验失败即整体丢弃该对象scripts/ssh-focus.sh负责拉起宿主终端标签页并切换远端 tmux 到 Agent pane。移动端v1.7.0 起支持 ntfy.sh / Pushover / Telegram 三种通道v2.31.0 增加了mobile_notify.priority显式优先级解决 iOS 低优先级静默问题。八、跨平台音频的踩坑史CHANGELOG 里的音频修复是最能体现工程深度的部分因为无声往往比报错更难排查macOS 首声削波v2.33.0engine.start()在输出设备真正开始流 PCM 之前就返回空闲设备尤其蓝牙 A2DP休眠后需 100–300ms 唤醒上第一段样本落在未激活的 sink 上导致Happy to播成appy to。peon-play现在先调度一段静音缓冲默认 300ms-p ms可调WSL2 在 Windows 11 24H2 上静默v2.27.0 / v2.35.124H2 移除旧版 Windows Media PlayerWPF MediaPlayer 抛MILAVERR_INVALIDWMPVERSION。修复为按 Windows 构建号探测一次缓存于$PEON_DIR/.wsl-mediaplayer-probe-buildMediaPlayer 打不开时回退System.Media.SoundPlayer仅 WAVMP3 需 ffmpeg 逐事件转码到 Windows 临时目录并暴露PEON_WSL_AUDIO_BACKENDauto|mediaplayer|soundplayer环境变量覆盖探测v2.35.1 又修了 24H2 build 26200 上NaturalDuration在Open()后解析不出导致播放器毫秒级关闭的问题Windows git-bash argv 超限v2.25.0内嵌 Python 块膨胀到约 47 KB 后超出CreateProcess约 32 KB 的 argv 上限python3 -c直接E2BIG且静默退出。修复是写入临时文件再python3 path执行ntfy 认证头带空格被拆词v2.37.0-H Authorization: Bearer $TOKEN未加引号展开导致 shell 词切分改为 bash 数组pw-play媒体角色v2.26.0Linux 播放统一走 PipeWire 的 Notification 媒体角色--media-roleNotification避免压低 Spotify 音量或路由错端点。另外 v2.12.0 为全部 IDE 补齐了原生 PowerShell 适配器.ps1198 个 Pester 测试Windows 音频后端在 WPFMediaPlayer尊重音量、支持 MP3/WMA见 scripts/win-play.ps1与SoundPlayer纯 WAV之间两级回退。九、工程保障安全、测试与发布纪律CHANGELOG 的 Security 与 Internal 段落值得单独总结它们展示了一个开源项目的健康度安全加固v2.36.0 的 eval server 令牌门禁per-session token Host/Origin/Content-Type校验 声音文件只在 draft 目录内按解析后的真实路径防符号链接与路径穿越v2.36.0 校验 manifest 中的包名../victim/pwned这类路径注入会被模式检查与落盘目录一致性校验拦下v2.35.0 起UserPromptSubmit日志不再记录提示词正文防粘贴凭据泄露日志文件0600权限v2.20.0 把python3 -c块内的 shell 变量插值全部迁移为os.environ.get()模式防引号注入测试体系BATSshell与 PesterWindows PowerShell双轨并行共享夹具强制跨平台格式一致v2.17.0 的tests/fixtures/hook-logging/。v2.37.0 暴露过测试存在但从未在 CI 执行opencode 适配器 58 个 vitest 测试形同虚设与eval-server.bats 因socket.getfqdn()反向 DNS 阻塞而在 macOS CI 全挂两起隐性故障——后者直到 v2.36.0 才定位说明测试覆盖率与 CI 实际执行缺一不可发布纪律CHANGELOG 条目遵循 Fixed/Added/Changed/Security/Internal/Docs/Tests 分类每条注明 PR 号与致谢部分关键修复如 v2.29.0 的 Copilot 适配器重写、v2.35.1 的首装崩溃还带回归测试。README 的 README_zh.md、README_ja.md、README_ko.md 三语文档与 docs/public/llms.txt 的同步更新也作为独立条目被记录保证文档与代码同节奏。十、给读者的实战建议回看整个 CHANGELOG可以提炼出几条可复用的工程经验静默失败是最贵的 bug多起故障OpenCode 的Bun is not defined、git-bash 的E2BIG、TTS 后端脚本从未落盘都是无声音、无报错、无日志三无状态最终靠结构化日志peon debug onpeon logs9 阶段 JSONL 追踪定位。排查任何该响不响的问题第一件事就是peon debug on并查看事件路由阶段的suppressed与reason字段事件语义要从宿主自己记录的事实推导Antigravity 回合边界从transcript.jsonl的USER_INPUT/PLANNER_RESPONSE结构判断而不是靠文件 mtime 猜——猜时间总是会错读权威记录才是正解默认值即产品决策task.acknowledge默认关、suppress_idle_prompt_repeats默认开、tmux_passthrough默认关这些默认值都是为了少打扰新增功能先默认保守再给高级用户开关跨平台不能只信 CIargv 长度、反向 DNS、终端角色、24H2 行为差异这些环境细节只有真实设备才会暴露测试要同时覆盖故意握住文件不让事件完成这类时序边界。从 v1.0.0 的一个 Claude Code 钩子 两个音色包到 v2.37.0 的20 适配器、草案验收门禁、移动推送、TTS、MCP 服务器、Nix 模块——这份 CHANGELOG 不仅是一部功能清单更是一份完整的AI Agent 提示系统工程方法论档案。无论你是 peon-ping 的使用者、适配器贡献者还是想为自己的 Agent 工具建立类似事件→反馈管线的开发者都能从中找到可直接照搬的设计与教训。赞分享【免费下载链接】peon-pingWarcraft III Peon voice notifications ( more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.项目地址https://gitcode.com/gh_mirrors/pe/peon-ping点击查看免费下载相关推荐MemOS OpenClaw 云插件版本演进全解析从记忆挂钩到多 Agent 安全协作MemOS OpenClaw 云插件版本演进全解析从记忆挂钩到多 Agent 安全协作 本篇技术指南以 docs/cn/openclaw/changes.md人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin终极MinHook API钩子库版本演进史从v1.0到v1.3.4的15年技术革新之路终极MinHook API钩子库版本演进史从v1.0到v1.3.4的15年技术革新之路 MinHook是一款轻量级的x86/x64 API钩子库专为Wind逆向工程系统底层AutoGen.Net 0.0.x 版本演进解析从消息体系重构到多提供商 Agent 生态AutoGen.Net 0.0.x 版本演进解析从消息体系重构到多提供商 Agent 生态 本篇基于仓库中的更新日志 update.md https://li人工智能AI AgentAgent 框架多智能体大模型工具调用上一篇免费Windows加速神器OpenSpeedy终极完整使用指南下一篇ERNIE 4.5异构MoE架构重构多模态智能30亿参数激活开启企业AI普惠时代创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考