dsh-plugin-attention-chime

Readme

# dsh-plugin-attention-chime

> Agent 需要你时，让 macOS 发出声音。
>
> 当 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）里的 agent **等待你回复 / 向你提问 / 请求审批**时，播放系统提示音并弹出 macOS 系统通知；安装 terminal-notifier 后，**点击通知直接跳转到该会话的浏览器标签页**。

[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![platform](https://img.shields.io/badge/platform-macOS-blue)](#环境要求)
[![topic](https://img.shields.io/badge/topic-dsh--plugin-orange)](https://github.com/topics/dsh-plugin)
[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/YuChuanhui3/dsh-plugin-attention-chime)

## 为什么需要它

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

## 功能

- **三类提醒**，各自独立开关 / 提示音 / 音量：
  - `reply` — 根 agent 回合结束转为 idle（默认 Glass）
  - `question` — `ask_user_question` / `exit_plan_mode` 提问工具触发（默认 Funk）
  - `approval` — 审批请求弹出（默认 Sosumi）
- **系统通知而非弹窗**：横幅不打断当前工作；装有 [terminal-notifier](https://github.com/julienxx/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
```

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

```sh
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`（启用「点击通知跳转」）：

```sh
brew install terminal-notifier
```

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

## 安装

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

或从 git 地址安装：

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

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

卸载：

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

## 配置

安装即带默认值（见 [cordis.patch.yml](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)` 立即试听某类提醒

## 本地开发

```sh
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](LICENSE) © 2026 YCH