企业官网建设流程全解析

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 Trainer，v2.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中：

七类之外，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.start；UserPromptSubmit会先检查"最近窗口内的提示词时间戳"，若在annoyed_window_seconds窗口内累计达到annoyed_threshold次则升级为user.spam；Stop落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.ps1），v2.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 / bindings（v2.1.0 起，含--registry、--all、--lang）；
• 训练师：peon trainer on/off/status/log/goal/help（v2.0.0 起，v2.21.0 增加按星期排程）；
• 调试：peon debug on/off、peon logs（v2.17.0 引入结构化日志，9 阶段决策追踪）；
• 通知：peon notifications ...（overlay/standard 样式与位置）；
• 移动推送：peon mobile ntfy/pushover/telegram；
• SSH 音频：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-path>（v2.36.0 的草案 + 人耳验收门禁）。

值得注意的是 v2.36.0 引入的音色包验收门禁：新包必须先成为~/.peon-ping/drafts/下的 draft（manifest 带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 命令参数传递而非 stdin；Kiro IDE 的.kiro/hooks/*.kiro.hookAgent Hooks 也是把事件名放在 argv 上。对应适配器（adapters/rovodev.sh）就按参数位解析事件名再映射到 CESP。

4.3 文件系统监听（Amp / Antigravity / Kimi / Trae 范式）

对没有同步钩子 API 的 IDE，采用后台守护进程轮询/监听会话文件。v2.28.0 的 Antigravity Python watcher（adapters/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_INPUT+source: 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 记录了一个典型 bug：OpenCode 插件在 Bun 二进制下运行，但插件代码跑在 Node 沙箱里，Bun.spawn全局不可用导致每次触发都静默抛错被catch {}吞掉——修复是改用node:child_process的spawn。这个例子说明了"宿主环境与插件沙箱的全局差异"这类隐蔽陷阱。

无论哪种范式，事件最终都汇入peon.sh的会话识别层。peon.sh 的detect_session_ide()展示了识别优先级：先看事件载荷里的source字段（通过IDE_ALIASES归一化），再看workspace_roots（Cursor 特征），最后按 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.sh）：

session_override（/peon-ping-use 技能钉住的会话包） > path_rules（按工作目录 glob 匹配） > ide_rules（按 IDE/source 匹配） > pack_rotation（random / round-robin / shuffle 轮换） > default_pack（静态兜底） > 硬编码 "peon"

每层都有"先验证包目录真实存在，否则向下穿透"的容错。此外exclude_dirs是独立短路层：一旦 cwd 匹配排除目录，整个调用直接suppressed=True reason=excluded_dir静默退出，不播放任何声音也不发通知（v2.25.0 修正了此前"exclude 只跳过 path_rules 层"的语义漏洞）。路径匹配用fnmatch.fnmatch支持 glob，同时对无通配符的路径做"相等或前缀"匹配（peon.sh）。

5.3 防抖、去重与静音窗口

CHANGELOG 反复出现"防抖"主题，它们是同一类问题的不同解法：

• Stop 防抖（v1.4.0 引入）：后台任务快速连续完成时防止刷屏，5 秒窗口内合并；
• idle_prompt 去重（v2.25.0）：Claude Code 在终端失焦时约每 60 秒重发idle_prompt通知，若不做去重就会反复播放同一个完成音。suppress_idle_prompt_repeats（默认true）+idle_prompt_suppress_window_seconds（默认3600）在.state.json记录last_task_complete[session_id]，窗口内同会话的后续 idle_prompt 直接静音；
• silent_window_seconds（v1.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 各版本新增配置项的"汇总答案"：

项目名的解析同样是一条明确的优先级链（源码见 peon.sh）：状态内/peon-ping-rename会话名 >tty::cwd复合键兜底名 >CLAUDE_SESSION_NAME环境变量 > 项目根.peon-label文件 >notification_title_script动态脚本 >project_name_map>notification_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 从标准横幅到 overlay

v2.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反查进程 PID（v2.8.0）；v2.17.2 补上 WezTerm bundle id；v2.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.0）：engine.start()在输出设备真正开始流 PCM 之前就返回，空闲设备（尤其蓝牙 A2DP，休眠后需 100–300ms 唤醒）上第一段样本落在未激活的 sink 上，导致"Happy to"播成"appy to"。peon-play现在先调度一段静音缓冲（默认 300ms，-p <ms>可调）；
• WSL2 在 Windows 11 24H2 上静默（v2.27.0 / v2.35.1）：24H2 移除旧版 Windows Media Player，WPF MediaPlayer 抛MILAVERR_INVALIDWMPVERSION。修复为按 Windows 构建号探测一次（缓存于$PEON_DIR/.wsl-mediaplayer-probe-<build>），MediaPlayer 打不开时回退System.Media.SoundPlayer（仅 WAV，MP3 需 ffmpeg 逐事件转码到 Windows 临时目录），并暴露PEON_WSL_AUDIO_BACKEND=auto|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.0）：Linux 播放统一走 PipeWire 的 Notification 媒体角色（--media-role=Notification），避免压低 Spotify 音量或路由错端点。

另外 v2.12.0 为全部 IDE 补齐了原生 PowerShell 适配器（.ps1，198 个 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()模式防引号注入；
• 测试体系：BATS（shell）与 Pester（Windows 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，可以提炼出几条可复用的工程经验：

1. "静默失败"是最贵的 bug：多起故障（OpenCode 的Bun is not defined、git-bash 的E2BIG、TTS 后端脚本从未落盘）都是"无声音、无报错、无日志"三无状态，最终靠结构化日志（peon debug on+peon logs，9 阶段 JSONL 追踪）定位。排查任何"该响不响"的问题，第一件事就是peon debug on并查看事件路由阶段的suppressed与reason字段；
2. 事件语义要从"宿主自己记录的事实"推导：Antigravity 回合边界从transcript.jsonl的USER_INPUT/PLANNER_RESPONSE结构判断，而不是靠文件 mtime 猜——猜时间总是会错，读权威记录才是正解；
3. 默认值即产品决策：task.acknowledge默认关、suppress_idle_prompt_repeats默认开、tmux_passthrough默认关，这些默认值都是为了"少打扰"，新增功能先默认保守，再给高级用户开关；
4. 跨平台不能只信 CI：argv 长度、反向 DNS、终端角色、24H2 行为差异这些环境细节只有真实设备才会暴露，测试要同时覆盖"故意握住文件不让事件完成"这类时序边界。

从 v1.0.0 的"一个 Claude Code 钩子 + 两个音色包"，到 v2.37.0 的"20+ 适配器、草案验收门禁、移动推送、TTS、MCP 服务器、Nix 模块"——这份 CHANGELOG 不仅是一部功能清单，更是一份完整的"AI Agent 提示系统"工程方法论档案。无论你是 peon-ping 的使用者、适配器贡献者，还是想为自己的 Agent 工具建立类似事件→反馈管线的开发者，都能从中找到可直接照搬的设计与教训。