dsh-plugin-attention-chime

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

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

为什么需要它

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 层需要重启；之后的配置改动都无需重启）。

卸载：

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

配置

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

1. 设置页卡片（推荐）：设置 → 插件 → 可配置 → 「注意力提醒」。即改即生效，写入 ~/.dsh/settings.yaml，重启保留。
2. profile 补丁：在 profile 的 cordis.patch.yml 里按 id 寻址（注意：补丁会整行替换 config，不做合并）：

- 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