peon-ping-config

peon-ping-config

更新 peon-ping 配置设置。

配置文件位置

配置文件位于 ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/peon-ping/config.json。

可用设置

• volume（数字，0.0–1.0）：音量
• default_pack（字符串）：当前音效包名称（例如 "peon"、"sc_kerrigan"、"glados"）。旧键 active_pack 也可作为回退选项。
• enabled（布尔值）：总开关
• pack_rotation（字符串数组）：每个会话轮换使用的音效包列表。空数组 [] 表示仅使用 default_pack。
• pack_rotation_mode（字符串）："random"（默认值）表示每个会话随机选择一个音效包。"round-robin" 表示按顺序轮换。"session_override" 表示使用 /peon-ping-use 设置的显式会话分配；无效或缺失的音效包会回退到 default_pack，并移除过时的分配。旧值 "agentskill" 也可作为别名使用。
• categories（对象）：切换各个 CESP 音效类别：
  • session.start、task.acknowledge、task.complete、task.error、input.required、resource.limit、user.spam——每项都是布尔值
• disabled_sounds（对象）：禁用音效包中的特定音效文件，按音效包名称 → 类别 → 文件名（不含路径）的数组进行索引。示例：

  "disabled_sounds": {
    "peon": { "session.start": ["Hello1.wav"] }
  }
  

  如果某个类别中的所有音效都已列出，该类别将保持静音。建议使用 CLI：

  peon sounds list [pack]
  peon sounds disable <category> <file> [--pack=<name>]
  peon sounds enable  <category> <file> [--pack=<name>]
  

• annoyed_threshold（数字）：触发 user.spam 音效所需的短时间内提示词数量
• annoyed_window_seconds（数字）：烦躁阈值的时间窗口
• silent_window_seconds（数字）：抑制耗时短于此秒数的任务的 task.complete 音效
• session_ttl_days（数字，默认值：7）：过期超过 N 天的陈旧会话音效包分配（使用 session_override 模式时）
• desktop_notifications（布尔值）：独立于音效切换通知弹窗（默认值：true）
• use_sound_effects_device（布尔值）：通过 macOS Sound Effects 设备（true）或使用 afplay 通过默认输出设备（false）播放音频。仅影响 macOS。默认值：true

如何更新

1. 使用 Read 工具读取配置文件
2. 使用 Edit 工具编辑相关字段
3. 向用户确认更改

常见配置示例

禁用桌面通知弹窗，但保留音效

用户请求：“禁用桌面通知”

操作： 在配置中设置 desktop_notifications: false

结果：

• ✅ 音效继续播放（语音提醒）
• ❌ 桌面通知弹窗已抑制
• ✅ 移动通知不受影响（由单独的开关控制）

替代 CLI 命令：

peon notifications off
# or
peon popups off

调整音量

用户请求：“将音量设为 30%”

操作： 在配置中设置 volume: 0.3

启用轮流音效包轮换

用户请求：“启用 peon 和 glados 的轮流音效包轮换”

操作： 设置：

{
  "pack_rotation": ["peon", "glados"],
  "pack_rotation_mode": "round-robin"
}

目录音效包绑定

将音效包永久关联到工作目录，使该目录中的每个会话都自动使用合适的音效包。使用 path_rules 配置键（由 { "pattern": "<glob>", "pack": "<name>" } 对象组成的数组）。

CLI 命令

# Bind a pack to the current directory
peon packs bind <pack>
# e.g. peon packs bind glados
# → bound glados to /Users/dan/Frontend

# Bind with a custom glob pattern (matches any dir with that name)
peon packs bind <pack> --pattern "*/Frontend/*"

# Auto-download a missing pack and bind it
peon packs bind <pack> --install

# Remove binding for the current directory
peon packs unbind

# Remove a specific pattern binding
peon packs unbind --pattern "*/Frontend/*"

# List all bindings (* marks rules matching current directory)
peon packs bindings

手动配置

也可以直接编辑 config.json 中的 path_rules 数组：

{
  "path_rules": [
    { "pattern": "/Users/dan/Frontend/*", "pack": "glados" },
    { "pattern": "*/backend/*", "pack": "sc_kerrigan" }
  ]
}

匹配模式使用 Python fnmatch glob 语法。以第一个匹配的规则为准。路径规则优先于 default_pack 和 pack_rotation，但优先级低于 session_override 分配。

列出可用音效包

若要查看可用音效包，请运行：

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh packs list