YuChuanhui3/dsh-plugin-attention-chime

dsh-plugin-attention-chime

当 Agent 需要你时，让 macOS 发出声音。

当 DeepSeek Harness（dsh）里的 agent 等待你回复 / 向你提问 / 请求审批时，播放系统提示音并弹出 macOS 系统通知；安装 terminal-notifier 后，点击通知直接跳转到该会话的浏览器标签页。

license
platform
topic
Listed on dsh-plugin.org

为什么需要它

Agent 需要人的时刻有三种：回合结束等你回复、ask_user_question 提问、危险操作等审批。你一旦切去干别的事，就会让它白等几分钟甚至几小时。这个插件把「它需要你」变成听得见、看得见、点得到的信号。

功能

- 三类提醒，各自独立开关 / 提示音 / 音量：
- reply — 根 agent 回合结束转为 idle（默认 Glass）
- question — ask_user_question / exit_plan_mode 提问工具触发（默认 Funk）
- approval — 审批请求弹出（默认 Sosumi）
- 系统通知而非弹窗：横幅不打断当前工作；装有 terminal-notifier 时通知可点击，自动激活浏览器并切换到标题匹配该会话的标签页
- 后台任务守卫：agent 还有后台 job 或运行中的子代理时，不误报「等待回复」
- 升级提醒：长时间无人理会时按间隔重复提醒，音量逐次 +0.5（封顶 3），可指定专用升级提示音，最多 3 次
- 设置页卡片：设置 → 插件 → 可配置 → 「注意力提醒」，默认收起、点击展开，所有选项即改即生效，持久化到 ~/.dsh/settings.yaml
- 可选前置：提醒时把浏览器应用切到前台（默认关闭）

效果演示（真实输出）

系统通知横幅——agent 回合结束等待你回复时：

┌────────────────────────────────────────────┐
│ DeepSeek Harness                       现在 │
│ 等待你的回复 · 修复登录页面的样式问题          │
└────────────────────────────────────────────┘

点击横幅（需已安装 terminal-notifier）即激活浏览器，并切换到标题为「修复登录页面的样式问题 — DeepSeek Harness」的标签页。

升级提醒——5 分钟后仍无人理会，第 2 次提醒（音量自动 +0.5）：

等待你的回复（第2次提醒） · 修复登录页面的样式问题

服务器日志——插件挂载时：

[attention-chime] active v0.2.3 (enabled=true, reply=Glass, question=Funk, approval=Sosumi, escalate=3x every 300000ms +0.5/repeat, guard=on, jump=Google Chrome, foreground=off)
[attention-chime] terminal-notifier found: /opt/homebrew/bin/terminal-notifier

点击跳转日志——/tmp/dsh-attention-chime-jump.log：

2026-09-08 15:32:10 clicked

先试听提示音（无需安装插件）：

afplay /System/Library/Sounds/Glass.aiff    # reply（回复等待）
afplay /System/Library/Sounds/Funk.aiff     # question（提问等待）
afplay /System/Library/Sounds/Sosumi.aiff   # approval（审批等待）

环境要求

- macOS（依赖 afplay、osascript 与 /System/Library/Sounds 系统声音）
- DeepSeek Harness web profile（设置卡片需要；宿主提醒部分在含 dsh-base 的任意 profile 均可工作）
- 可选：terminal-notifier（启用「点击通知跳转」）：

brew install terminal-notifier

安装后首次使用：在 系统设置 → 通知 中允许 terminal-notifier 发通知；首次点击通知跳转时，macOS 会询问「terminal-notifier 想要控制 Google Chrome」，选择允许（一次性授权）。未安装 terminal-notifier 时自动回退为普通系统横幅（不可点击），其余功能不受影响。

安装

dsh plugin --profile web add github:YuChuanhui3/dsh-plugin-attention-chime

或从 git 地址安装：

dsh plugin --profile web add git+https://github.com/YuChuanhui3/dsh-plugin-attention-chime.git

然后重启 dsh web（新增 bundle 层需要重启；之后的配置改动都无需重启）。

卸载：

markdown
dsh plugin --profile web remove dsh-plugin-attention-chime

配置

安装即带默认值（见 cordis.patch.yml）。覆盖方式二选一：

1. 设置页卡片（推荐）：设置 → 插件 → 可配置 → 「注意力提醒」。即改即生效，写入 ~/.dsh/settings.yaml，重启保留。
2. profile 补丁：在 profile 的 cordis.patch.yml 里按 id 寻址（注意：补丁会整行替换 config，不做合并）：
yaml
- id: attention-chime
config:
alerts:
reply: { enabled: true, sound: 'Hero', volume: 1.5 }
question: { enabled: true, sound: 'Funk', volume: 1 }
approval: { enabled: true, sound: 'Sosumi', volume: 1 }
...其余字段需完整给出，见下表

配置项一览

| 字段 | 默认 | 说明 |
|---|---|---|
| enabled | true | 总开关 |
| idleGraceMs | 1200 | 回合结束后等待这么久仍 idle 才提醒（过滤连续回合） |
| minGapMs | 1500 | 两次提醒的最小间隔（防连环轰炸） |
| notificationTitle | DeepSeek Harness | 系统通知标题 |
| backgroundGuard | true | 有后台 job / 运行中子代理时不发「等待回复」提醒 |
| jump.enabled | true | 点击通知跳转会话标签页（需 terminal-notifier） |
| jump.browser | Google Chrome | 浏览器应用名（Safari / Microsoft Edge / Arc / Brave Browser…） |
| escalate.enabled | true | 升级提醒开关 |
| escalate.intervalMs | 300000 | 重复提醒间隔（5 分钟） |
| escalate.max | 3 | 最多重复次数 |
| escalate.volumeStep | 0.5 | 每次重复的音量增量 |
| escalate.maxVolume | 3 | 音量上限 |
| escalate.sound | '' | 升级专用提示音（空 = 沿用原提示音） |
| foreground.enabled | false | 提醒时把应用切到前台 |
| foreground.app | Google Chrome | 要前置的应用 |
| alerts.reply/question/approval | 见上 | 每类 {enabled, sound, volume} |

提示音为 /System/Library/Sounds/ 下的系统声音：Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink。音量为 afplay -v 值（1 = 正常，0.5 = 一半，0 = 静音）。

权限、风险与兼容性

全本地运行，零外部服务：插件不发起任何网络请求、无遥测、不收集数据。只调用本机系统命令：afplay（提示音）、osascript（通知与跳转）、terminal-notifier（可点击通知，可选）、command -v（探测）。

使用的 macOS 权限（均为系统标准授权流程）：

| 权限 | 用途 | 何时询问 |
|---|---|---|
| 通知 | 展示系统通知横幅 | 首次发送通知后，在系统设置 → 通知中允许 terminal-notifier |
| 自动化 | 点击通知时控制浏览器激活并切换标签页 | 首次点击通知时 macOS 弹窗「terminal-notifier 想要控制 Google Chrome」，允许一次即可 |

写入的文件（全部在 /tmp，重启系统即清空；不含会话内容，仅会话标题用于标签页匹配）：

- /tmp/dsh-attention-chime-jump.scpt 与 /tmp/dsh-attention-chime-jump.sh — 跳转脚本与点击包装器
- /tmp/dsh-attention-chime-jump.log — 点击日志
- /tmp/attention-chime-mounted.json — 挂载诊断标记

兼容性（dshTarget）：面向 dsh 0.1.2-rc 系列（在 0.1.2-rc.1 上开发验证；依赖 settings.installSection API，不兼容更早的 0.1.0 / 0.1.1 系列）。声明官方 dsh.bundle manifest（Distribution: Bundle）。仅支持 macOS。

已知限制：标签页匹配采用「标题包含会话名」策略，多个会话标题高度相似时可能聚焦到错误标签页；非 macOS 系统上提示音与跳转不可用。

工作原理

- 监听 Cordis 事件：agent/status（idle + 宽限期后提醒）、agent/disposed、tools/pre-execute（提问工具，waterfall 透传）、tools/result（提问结束清除状态）、approval/request（审批 waterfall，settle 后清除）
- 跳转实现：提醒时生成 AppleScript（按「标签页标题包含会话标题」匹配，GUI 标签标题为 会话名 — DeepSeek Harness），terminal-notifier 以 -execute 挂一个单词包装脚本触发它——对参数拆分/引号问题免疫
- 后台守卫：jobs.list(agent) 中存在 running/stopping，或 agents 中存在归属于该 agent 的 running 子代理，即视为忙碌
- 模块导出：默认导出 Cordis Service 类（loader 行标准形态），同时导出规范要求的 apply(ctx) 函数形式
- 宿主服务 attentionChime：status() 返回运行快照，test(kind) 立即试听某类提醒

本地开发

git clone git@github.com:YuChuanhui3/dsh-plugin-attention-chime.git
dsh plugin --profile web add ./dsh-plugin-attention-chime   # 在 clone 的父目录执行
重启 dsh web；之后改 client.js 只需刷新浏览器，改 index.js 需重启

注意：开发安装（link 方式）要求插件目录位于 profile 的 node_modules 解析树内（dsh plugin add 的路径安装会正确处理）。

License

MIT © 2026 YCH