agent-doorbell

Agent Doorbell

使用此技能管理运行时钩子：当主 Agent 停止或需要输入时，提醒用户注意。子 Agent、队友和中间任务活动都保持静默。提醒由运行时钩子负责。

核心规则

此技能是钩子管理器。当用户最近一次请求明确调用 agent-doorbell 时，安装或更新默认运行时钩子，除非请求要求卸载、移除或禁用它。不要仅仅因为 Agent 即将发送最终回复就使用此技能。

安装钩子后，运行时会调用 OS 原生运行器并快速返回。对于同一个停止事件，不要再手动运行门铃助手。

操作路由

用户意图	操作
agent-doorbell、安装、设置、启用、更新、使提醒自动化	安装或更新钩子
卸载、移除、禁用、关闭门铃钩子	卸载钩子
测试、试运行、预览	使用 --dry-run 运行安装程序
普通最终回复、暂停进度或内部检查清单步骤	不触发此技能

如果用户禁止在本轮使用工具、Shell 命令、通知或更改设置，则不要写入钩子设置。简要说明跳过设置的原因。

运行时默认值

运行时	默认事件	设置目标	备注
Claude Code	Elicitation、PermissionRequest、Stop、StopFailure、经过筛选的 Notification	~/.claude/settings.json	使用可执行文件形式的命令钩子，包含 command、args、async: true、timeout 和 statusMessage。
Gemini CLI	AfterAgent	~/.gemini/settings.json	使用命令字符串、毫秒级超时和中性 JSON 输出。
Codex	Stop	~/.codex/hooks.json	使用命令字符串和以秒为单位的超时。在 /hooks 中审核新的定义。
Copilot CLI	agentStop	<COPILOT_HOME or ~/.copilot>/hooks/agent-doorbell.json	使用版本 1 的扁平钩子，包含直接的 exec、args 和 timeoutSec；项目级作用域为 .github/hooks/agent-doorbell.json。
Cursor	stop	~/.cursor/hooks.json	使用版本 1 的扁平钩子。必须显式指定 --runner node 才能读取完成状态；错误会触发 failed 提醒，中止的运行则保持静默。
其他 Agent 运行时	运行时专属的停止、完成或输入事件	运行时专属的本地设置	仅在运行时提供有文档说明的生命周期钩子时进行配置。有关仅限插件的集成限制，请参阅运行时适配器。

操作系统	默认钩子运行器	备注
Windows	powershell.exe + scripts/hook-runner.ps1	使用 ring.ps1 播放捆绑的 WAV 音频并发送托盘或桌面通知。
macOS	/bin/sh + scripts/hook-runner.sh	使用 afplay 播放捆绑的 WAV 音频，并使用 osascript 发送通知；系统提示音为备用方案。
Linux	/bin/sh + scripts/hook-runner.sh	使用 paplay 或 aplay 播放捆绑的 WAV 音频，在可用时使用 notify-send；有控制终端时则使用终端响铃作为备用方案。

共享的 Claude 注意力事件必须是有效的 JSON 对象，且不得包含子级 agent_id。POSIX 运行器使用 jq 进行此项检查；没有 jq 时，共享事件将保持静默，但完成提醒仍可用。

事件提示音

内置的 5 个 44.1 kHz 单声道 PCM WAV 文件使用 doorbell 插件原有的柔和提示音配方，每个文件时长都不到 0.6 秒。原生运行器会直接播放这些文件，因此在钩子触发时无需合成运行时或插件服务。

事件或原因	提示音
主 Stop、AfterAgent、Copilot agentStop、Cursor completed	done
子级、队友和中间任务事件	静音
Elicitation、筛选后的注意提示	needs-input
权限请求	approval
Claude StopFailure、Cursor error	failed
Cursor aborted	静音
明确的 blocked 原因	blocked
明确的 cancelled 原因	静音

钩子事件决定播放的声音；运行器不会根据响应文本推断目标是否受阻。只注册主 Agent 事件，并按照运行时适配器中的说明，根据 Agent 身份筛选共享的输入或权限负载。即使旧版钩子仍会调用运行器，子级、队友和任务生命周期事件也保持静音。注意事项匹配器会排除后台 Agent 和常规通知。Elicitation 涵盖外部输入请求，不包括助手响应中的所有问题。

Claude 异步钩子无法做出权限批准决定，不受钩子超时限制的约束，并且可能在非交互式 CLI 关闭期间被终止。quiet 和 normal 会以系统音量播放一次；loud 会播放两次。如果 WAV 播放失败，则使用系统声音作为备用方案。插件专属的会话去重、跨客户端路由和预热播放器进程需要插件宿主，不属于此钩子管理器的范围。

默认优先使用用户本地设置，因为钩子命令包含机器本地的可执行文件和技能路径。只有用户要求按项目设置行为时，才使用项目本地设置。

不要试图支持所有 Agent 运行时。仅支持具有文档化生命周期钩子的运行时。如果没有文档化钩子，请说明此技能目前无法提供可靠的自动停止提醒。

安装工作流

1. 确定包含此 SKILL.md 的技能目录。
2. 选择运行时。
   • 如果请求提及 Claude Code，或当前界面是 Claude Code，请使用 claude。
   • 如果请求提及 Gemini CLI，请使用 gemini。
   • 如果请求提及 Codex，或当前界面是 Codex，请使用 codex。
   • 对于 Copilot CLI，请使用 copilot；此适配器不会配置云端 Agent。
   • 只有在用户明确选择 Node 运行器时才使用 cursor；其状态负载需要解析。
   • 如果运行时不明确，请提出一个简短问题，而不是写入错误的设置文件。
3. 选择操作。
   • 用户明确调用 agent-doorbell 时，默认操作为安装/更新。
   • 用户说 uninstall、remove、disable 或表达类似意思时，使用卸载操作。
4. 如果有捆绑的安装程序，请运行它；否则，使用下方的钩子结构直接编辑目标设置 JSON。

Claude Code 安装：

.\scripts\install-hooks.ps1 -Runtime claude -Scope user

Claude Code 卸载：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime claude -Scope user

Gemini CLI 安装：

.\scripts\install-hooks.ps1 -Runtime gemini -Scope user

Gemini CLI 卸载：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime gemini -Scope user

Codex 安装/更新：

.\scripts\install-hooks.ps1 -Runtime codex -Scope user

Codex 卸载：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime codex -Scope user

Node 便捷安装程序示例，适用于有 Node 的 macOS/Linux：

node scripts/install-hooks.js --runtime claude --scope user
node scripts/install-hooks.js uninstall --runtime claude --scope user
node scripts/install-hooks.js --runtime gemini --scope user
node scripts/install-hooks.js --runtime codex --scope user
node scripts/install-hooks.js --runtime copilot --scope user
node scripts/install-hooks.js --runtime cursor --scope user --runner node

项目本地示例：

node scripts/install-hooks.js --runtime claude --scope project-local --project-root .
node scripts/install-hooks.js --runtime gemini --scope project --project-root .
node scripts/install-hooks.js --runtime codex --scope project --project-root .

使用 --dry-run 可预览更改，而不写入设置：

.\scripts\install-hooks.ps1 -Runtime claude -Scope user -DryRun

安装程序是用于写入 JSON 的便捷工具。Claude、Gemini、Codex 和 Copilot 钩子默认使用操作系统原生运行器，在停止时不需要 Node 或 Python。Cursor 需要明确选择 Node 运行器；PowerShell 安装程序支持其他四种适配器。Copilot 的 exec 形式仅适用于 CLI；不要将该项目文件用于其云端 Agent。安装程序是幂等的：写入替换项前会移除之前的 Agent Doorbell 钩子条目。它只会移除由 statusMessage/name 标识为 Agent Doorbell 的钩子，或命令指向 hook-runner.ps1、hook-runner.sh 或 hook-runner.js 的钩子；它也能识别旧版 hook-runner.py 条目，以便干净地替换较早的 Python 钩子。

只有在用户明确需要基于 Node 的钩子时，才使用 --runner node：

node scripts/install-hooks.js --runtime claude --scope user --runner node

钩子结构

Windows 上的 Claude Code 会写入与以下结构等效的条目：

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "powershell.exe", "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "<skill-path>/scripts/hook-runner.ps1", "-Event", "Stop", "-Reason", "done", "-Mode", "both", "-Intensity", "normal", "-Output", "none"], "async": true, "timeout": 10, "statusMessage": "Agent Doorbell"}]}]
  }
}

macOS/Linux 上的 Claude Code 使用 /bin/sh 和 scripts/hook-runner.sh，并传入相同的事件/原因参数。

macOS/Linux 上的 Gemini CLI 会写入与以下结构等效的条目，其中命令字符串使用 shell 引号：

{
  "hooks": {
    "AfterAgent": [{"hooks": [{"name": "Agent Doorbell", "type": "command", "command": "/bin/sh <skill-path>/scripts/hook-runner.sh --event AfterAgent --reason done --mode both --intensity normal --output gemini", "timeout": 10000, "description": "Ring a non-blocking Agent Doorbell cue when the agent stops or needs attention."}]}]
  }
}

Windows 上的 Gemini CLI 则使用 powershell.exe ... hook-runner.ps1 ... -Output gemini 命令字符串。

限制

• 不要仅仅因为 Agent 即将停止就安装钩子。
• 不要在普通的最终回复中手动鸣铃作为后备方案。
• 除非用户明确选择项目范围，否则不要写入包含本机路径的可共享项目设置。
• 不要在钩子摘要中包含机密、私人标识符、原始日志或大量输出。
• 不要打开窗口、抢占焦点或循环播放声音。
• 如实说明不受支持的运行时：如果没有文档说明的生命周期钩子，请说明此技能目前无法提供可靠的自动停止提醒。
• 对于不需要解析负载的适配器，请使用操作系统原生运行器。只有在用户选择其 Node 运行器后，才配置 Cursor；不要悄悄添加运行时依赖。

验证

测试命令和预期行为请参阅验证。选择或更改适配器时，请阅读运行时适配器，了解事件覆盖范围、版本限制及其他运行时限制。