1实现原理 · 为什么它能做到
本体不是提示词而是真程序：peon.sh 被安装器注册为宿主的多类生命周期 hook（README 列出 SessionStart / SessionEnd / SubagentStart / Stop / Notification / PermissionRequest / PostToolUseFailure / PreCompact），事件到来时执行播放与通知逻辑（SKILL.md 只是外壳）。
README.md
`peon.sh` is a Claude Code hook registered for `SessionStart`, `SessionEnd`, `SubagentStart`, `Stop`, `Notification`, `PermissionRequest`, `PostToolUseFailure`, and `PreCompact` events. On each event:
这条把『纯 prompt vs 壳 + 真 CLI』定性钉死：事件源是宿主 IDE 的 hook 系统，peon.sh 是 267.7KB / 7071 行的 Bash 主程序。
安装器把同一命令写进用户级 ~/.claude/settings.json 的 hooks 段（--local 则写项目 ./.claude/settings.json），且只清理自己装的 peon.sh / notify.sh 条目。
install.sh
echo "Updating Claude Code hooks in settings.json..."
落盘在同文件稍后的 `with open(settings_path, 'w') as f:`；注释说明只剥离 peon 自己的 hook，兄弟工具注册的 notify.sh 会保留。
多数 skill 是薄提示词：/peon-ping-toggle 让模型去 shell 调安装目录下的 peon.sh toggle，真正逻辑仍在程序里。
skills/peon-ping-toggle/SKILL.md
bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh toggle
同一模式见 peon-ping-config/SKILL.md（packs list）、peon-ping-log/SKILL.md（trainer log），以及 toggle 的 Windows 分支 peon.ps1。
/peon-ping-use 走 hook 拦截路径而非模型路径：UserPromptSubmit hook 读到 prompt 就自己处理并阻断 LLM，零 token 完成配置改写。
skills/peon-ping-use/SKILL.md
The hook scripts (`scripts/hook-handle-use.sh` and `scripts/hook-handle-use.ps1`) do all the work - this SKILL.md file exists solely for discoverability in the `/` command autocomplete menu.
hook 同时被写进 Cursor 的 hooks.json；hook-handle-use.sh 用 grep 正则判定『这条 prompt 是不是我的命令』。
会话级语音包分配＝hook 直接改写配置与状态文件：把 pack_rotation_mode 设为 session_override，并在 .state.json 的 session_packs 写 session→pack 映射。
scripts/hook-handle-use.sh
config['pack_rotation_mode'] = 'session_override'
随后 json.dump 落盘 config.json，并写 state['session_packs'][session_id]；rename hook 同构。
语音包不在仓库里：安装期先读自建 registry 清单，再从 raw.githubusercontent.com 逐文件拉进 <peon_dir>/packs/<pack>/，并记录 sha256 校验和。
scripts/pack-download.sh
PACK_BASE="https://raw.githubusercontent.com/$SOURCE_REPO/$SOURCE_REF/$SOURCE_PATH"
下载前用 is_safe_pack_name / is_safe_source_repo / is_safe_source_ref / is_safe_source_path 做白名单；下载后 store_checksum 写 .checksums。仓库内只有 trainer/sounds 与演示 wav，没有 packs/。
播放走各平台原生程序：macOS 首选 afplay（若装了 peon-play 二进制则改用它以支持 Sound Effects 设备），Linux 依次探测多种播放器。
peon.sh
local player="afplay"
Linux 侧按 pw-play → paplay → ffplay → mpv → play → aplay 探测；全都没有时打印 WARNING 提示安装其中之一，不静默失败。
桌面通知分平台实现：Linux 用 notify-send，macOS 用 terminal-notifier（缺则回退 osascript），Windows/WSL 用 PowerShell toast。
scripts/notify.sh
nohup notify-send --urgency="$urgency" $expire_time_flag $icon_flag "$title" "$msg" >/dev/null 2>&1 &
macOS 分支会先探测 terminal-notifier，再回退 osascript display notification；Windows toast 侧另有专门的注入缓解（把消息写临时文件而不是插值进 PowerShell）。
同一仓库还提供 MCP server：不依赖 hook，直接 spawn 系统播放器播放指定 pack/sound。
mcp/peon-mcp.js
const child = spawn(cmd[0], cmd[1], { stdio: "ignore" });
播放命令按平台解析（mac 优先安装目录里的 peon-play，否则 afplay）；对外注册的工具名为 play_sound。
SSH / devcontainer / Codespaces 场景不本地出声，而是把音频与通知请求发给本机 19998 端口的 relay 服务。
peon.sh
"http://${relay_host}:${relay_port}/notify" >/dev/null 2>&1 &
音频路径为 `curl -sf -H "X-Volume: $vol" "http://${relay_host}:${relay_port}/play?file=…"`；relay.sh 是配套的服务端，含 /health 探活。
2核心能力
01按角色语音包在会话事件时发声（默认包 peon）
02跨平台桌面弹窗通知（notify-send / terminal-notifier / osascript / PowerShell toast）
03给当前会话指定专属语音包（session_override 轮换模式）
04细粒度配置（音量 / 轮换 / 分类 / 单条音效）
05训练打卡与久坐提醒嵌入会话流
06把完成 / 需人工介入推送到手机（ntfy / Pushover / Telegram）
07以 MCP 工具形式给任意 agent 放音
08用大模型 + 云 TTS 从零生成新语音包（ElevenLabs 渲染）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| network | GitHub raw（核心文件与语音包下载，main 分支未 pin） |
| network | 语音包文件下载基址（按 registry 的 source_repo/ref/path 拼接） |
| network | 自建语音包 registry 清单 |
| network | GitHub 仓库 tarball（部分适配器安装包） |
| api | ElevenLabs 声音生成 / TTS（xi-api-key 头鉴权） |
| api | MiniMax 语音合成（T2A v2，两个地区端点） |
| api | ntfy 手机推送（服务器可在配置中覆盖） |
| api | Pushover 推送 |
| api | Telegram Bot 推送 |
| network | 本机音频 / 通知 relay |
| cli | 系统通知 / 播放 / 编译依赖 |
| package | MCP SDK（Node，供 mcp/peon-mcp.js 使用） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: 安装即把 peon.sh 注册成 Claude Code 的事件 command hook（README 列出的 8 类：SessionStart /
- 网络端点: 声明外部网络访问: 安装/更新取核心代码：REPO_BASE 指向 raw.githubusercontent.com 的 **main 分支**，安装器用 curl -
- 本地工作目录: 文件读写与工件输出: 写用户级 Claude 设置并注册 hooks：install.sh 以 `with open(settings_path, 'w') as f:`
审计说明： 🟠 橙色：评估后使用。本 skill 命中两条橙色特征且都有源码证据：①凭据与环境变量读取——ELEVENLABS_API_KEY / MINIMAX_API_KEY(+GROUP_ID) / DEEPGRAM_API_KEY（文档示例）/ PEON_ENV_NTFY_TOKEN，以及从 config.json 读出的手机推送 token，另会回退读取 ~/.config/peon-ping/credentials；②依赖第三方远程包与未固定版本的安装链——安装与自更新都从 raw.githubusercontent.com 的 **main 分支**取脚本并 `curl | bash` 执行，语音包从自建 registry + GitHub raw 下载，适配器还会拉 GitHub tarball；安装期写 ~/.claude/settings.json、shell rc、~/.local/bin，并可为部分适配器注册 macOS LaunchAgent（开机自启）。之所以不判红：没有反爬/反检测绕过、没有关闭 TLS 校验、无 sudo（权限动作只有 chmod +x 与 ln -sf），且对用户输入做了字符集白名单、对包清单做了路径校验、Windows 侧还专门为消息内容做了 PowerShell 注入缓解。需要额外知晓的一点是配置驱动的执行面：peon.sh 会把 config 的 notification_title_script 以 `shell=True` 运行（默认空串，即默认关闭）。
5第二遍独立确认
- [ok] skill.path 的选取（skills/peon-ping-use） — 重读仓库根目录（无 SKILL.md、无 plugin.json/marketplace.json）、glob **/SKILL.md（恰 7 个，全在 skills/peon-ping-*/）、glob **/plugin.json 与 **/marketplace.json（零命中）、以及 docs/public/llms.txt 与 README 对技能的分组排序。结论：展示名是产品级/仓库级，没有单一插件入口声明，必须主观择一；选 peon-ping-use（frontmatter 带 license: MIT 与 metadata.author: PeonPing，且是会话级语音包切换的主实现）。七个技能的 name/description 原文均已取证，可零成本改选。
- [discrepancy] 仓库 7 个 SKILL.md 与安装器 6 个的矛盾 — 重读 install.sh 的 install_skill 调用段（仅 6 个：toggle/config/use/log/remix/create-pack）与 install.ps1 的技能数组（同样 6 个，无 rename）。结论：peon-ping-rename 的 SKILL.md 不会被装到用户目录，只有它的 hook 脚本被单独下载——宣称 7 个、落地 6 个。
- [ok] external_deps：raw.githubusercontent.com 系列调用点 — 分别重读 install.sh 的 REPO_BASE 定义与下载段、pack-download.sh 的 PACK_BASE 拼接、peon.sh 的自更新与 VERSION 探测、adapters/omp.sh 与 adapters/kilo.sh。全部为明文 HTTPS 拉取，**无 pin、无签名校验**（语音包的 sha256 基线也来自同一来源，故不能防上游作恶）。
- [ok] external_deps：自建 registry 与 peon.sh 内的 urllib 拉取 — 重读 install.sh 的 REGISTRY_URL 常量，并在 peon.sh 检索 urllib.request.urlopen 命中两处同一 URL；另 pack-download.sh 亦有同域请求。属自建静态清单，与包文件所在 GitHub raw 分离。
- [ok] security：hooks 写进了哪里、注册了哪些事件 — 重读 install.sh 的 hook 安装段：HOOK_CMD 指向 $GLOBAL_BASE/hooks/peon-ping/peon.sh，settings.json 两次被以 'w' 模式改写；另确认 UserPromptSubmit 的两个 hook 分别指向 hook-handle-use.sh 与 hook-handle-rename.sh。README 侧 11 类事件清单与之吻合。
- [ok] security：是否提权 / 是否碰系统目录 — 对 install.sh、peon.sh、relay.sh、scripts/、adapters/ 检索 sudo：零命中；重读 install.sh 的 chmod 与软链段确认权限动作只有 chmod +x，写入目标全部在 $HOME 之下（~/.claude、~/.local/bin、~/.zshrc、~/.bashrc、~/.config/fish、~/Library/LaunchAgents）。
- [ok] security：凭据读取清单 — 重读 pack-render.py（env + 两处文件回退 + xi-api-key 头）、tts-minimax.sh/.ps1（MINIMAX_API_KEY / GROUP_ID）、peon.sh 的手机推送凭据读段。结论：本地配置/环境变量 → 明文 HTTPS 出站到用户自选的第三方服务，无第三方中转、不上传至作者域名。
- [ok] security：配置驱动的 shell 执行 — 在 peon.sh 检索 notification_title_script 命中取值与执行两处，重读该段确认 `_sp.run(_script, shell=True, capture_output=True, text=True, timeout=2, env=_env)`；又重读 config.json 确认默认值为空串。结论：默认关闭但机制真实存在。
6结论
适合： 适合希望在 Claude Code / Codex 等编码 agent 里获得即时听觉与桌面反馈的开发者：事件驱动发声、跨平台通知、SSH/devcontainer 通过 relay 也能听到声音，且支持按会话切换角色语音包、打卡提醒与手机推送。也适合研究『多 IDE 事件归一化（CESP）+ hook 优先于模型』这套工程做法的作者参考其适配器与 hook 设计。
不适合： 不适合对宿主环境整洁度敏感或需要可审计变更流的用户：它会在安装时改写 settings.json、shell rc 与 PATH，并可为部分适配器注册开机自启。不适合要求供应链可验证（固定版本 + 签名）的环境：安装与自更新都是 main 分支的 curl | bash。不适合禁止配置文件触发命令执行的环境（notification_title_script）。也不适合完全离线的机器——语音包、更新与可选 TTS 都需要出网。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload peon-ping.tar.gz
sha256:
Option B · Copy Guide for Agent6daa61016ffad439…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 8ef376602f.