任务提示音通知ZincGluxx/dsh-task-toast

dsh-task-toast

成功/失败提示音 + 桌面通知插件 for DeepSeek Harness (DSH) · 当 DSH 任务成功或失败时，播放长而醒目的系统提示音和桌面通知 — Windows / Linux / macOS。

一个 DSH 事件插件：监听 agent 回合（turn/end）和（可选）工具调用结果（tools/result），在成功和失败时用不同的、更长更醒目的系统提示音 + 可选的桌面通知 + 可选语音播报告知当前状态，让你不盯屏幕也知道结果。

一个 DSH 事件插件：监听 agent 回合（turn/end）和（可选）工具调用结果（tools/result），在成功与失败时播放不同的、更长的系统提示音，外加可选的桌面通知和可选的语音播报 — 无需盯着屏幕即可知道结果。

零运行时 npm 依赖，只使用宿主传入的 ctx 与 Node 内建 node:child_process。所有 @deepseek-ai/ 均为 import type，编译期擦除。

零运行时 npm 依赖：只使用宿主提供的 ctx 和 Node 内建模块 node:child_process。所有 @deepseek-ai/ 导入均为 import type — 在编译期被擦除。

功能 / Features

| 场景 / Scenario | 默认提示音 / Default sound | 桌面通知 |
| --- | --- | --- |
| 回合成功 turn/end reason=completed | chimes（更长钟声） | ✅「任务成功」 |
| 回合失败 turn/end reason=error | hand（错误/关键停止音） | ✅「任务失败」 |
| 回合被打断/阻塞/超长 aborted blocked max-tokens interrupted | 静音（可配置 otherSound） | — |
| 工具调用成功/失败（mode: 'tool' \| 'both' 时） | 同上 success/failure 音（不弹通知，避免刷屏） | — |

更醒目可选三件套 / Three levers to make it more noticeable:

1. 换更长的音 — chimes / tada / ringout / notify，或任意音频文件路径
2. 重复播放 — repeat: 2 | 3，每次间隔 ~300ms，更长更刺耳
3. 通知 + 语音 — toast: true（默认）弹桌面通知；speak: true 用 TTS 播报结果

跨平台支持 / Platform support

三个平台使用同一套配置与声音名，各自映射到系统资源：

| 能力 | Windows | Linux | macOS |
| --- | --- | --- | --- |
| 声音来源 | AppEvents 注册表方案 + C:\Windows\Media\.wav | freedesktop 主题 /usr/share/sounds/freedesktop/stereo/.oga | /System/Library/Sounds/*.aiff |
| 播放器 | powershell.exe + Media.SoundPlayer | paplay → aplay → mpv → ffplay（自动探测） | afplay |
| 桌面通知 | Windows Toast（PowerShell WinRT） | notify-send | osascript display notification |
| TTS 语音 | SAPI（SAPI.SpVoice） | spd-say → espeak-ng → espeak（探测） | say |
| repeat 循环 | PowerShell 1..N \| ForEach-Object | POSIX while + sleep | POSIX while + sleep |

声音名跨平台一致（chimes/hand/tada/notify/ringout/asterisk/beep/exclamation/question/default），配置可移植。找不到对应系统资源时静默跳过，绝不干扰宿主进程。

安装教程 / Installation

前置要求 / Prerequisites

- DSH 运行时：dsh CLI（npm i -g @deepseek-ai/dsh）或 Oh-DSH Desktop
- Node.js：^22.19.0 || >=24.0.0（仅从源码构建时需要）
- 平台依赖（全部可选，缺失时对应功能静默跳过，不影响 DSH）：

| 平台 | 声音 | 通知 | 语音 |
| --- | --- | --- | --- |
| Windows | 无需（用系统声音方案） | 无需（系统通知） | 需已装 SAPI 语音包（中文语音包可选） |
| Linux | 任一播放器：paplay（PulseAudio）/aplay/mpv/ffplay | notify-send（libnotify） | spd-say / espeak-ng / espeak |
| macOS | 无需（系统自带 afplay） | 无需（osascript） | 无需（自带 say，含中文语音） |

方式 A：直接从 Git 仓库安装（推荐）
dsh plugin add 支持 git 仓库、本地目录、tarball、npm 包等来源，会安装为 profile 的 bundle 并自动接线。在任意目录执行（放在插件目录内也可，来源用 URL 不依赖相对路径）：

从 GitHub 仓库直接安装到 profile
dsh plugin --profile my-profile add https://github.com/ZincGluxx/dsh-task-toast.git
或使用简化 git 语法
dsh plugin --profile my-profile add github:ZincGluxx/dsh-task-toast

启动并使用
dsh --profile my-profile

方式 B：本地 / 开发目录安装

1. 获取源码
git clone https://github.com/ZincGluxx/dsh-task-toast.git
2. 从父目录安装（相对路径锚定调用目录）
cd dsh-task-toast/..

或直接对本地仓库目录执行（从父目录）
dsh plugin --profile my-profile add dsh-task-toast

方式 C：Oh-DSH Desktop 桌面端

桌面端与 CLI 使用同一套 profile 机制，直接对 desktop profile 执行同一个命令即可：

dsh plugin --profile desktop add https://github.com/ZincGluxx/dsh-task-toast.git
然后重启 Oh-DSH Desktop

插件市场（marketplace）收录后，也可以在桌面端插件商店搜索 dsh-task-toast 一键安装；当前版本暂未进市场目录，先用上面的 dsh plugin add 方式。

方式 D：从源码构建（维护者）

pnpm install
pnpm run build          # tsc -> dist/index.js (pure ESM)
npm test                # 三平台命令断言

验证安装 / Verify

该 profile 已安装的插件列表（应包含 dsh-task-toast）
dsh plugin --profile my-profile list

装配树应包含插件（且只出现一次）
dsh --profile my-profile --dump-config | grep -A2 dsh-task-toast

启动后日志出现插件激活行
dsh --profile my-profile
[dsh-task-toast] active platform=win32 mode=turn success="chimes" failure="hand" ...

弹一次「成功」+ 一次「失败」通知（注意：会真的播放声音和弹通知）
node scripts/toast-demo.mjs

只试听声音
node scripts/play-sounds.mjs

卸载 / Uninstall

dsh plugin --profile my-profile remove dsh-task-toast

桌面端同样用 dsh plugin --profile desktop remove dsh-task-toast 后重启即可。

配置 / Configuration

默认配置即可用；通过 patch 层覆盖（后层按 id 整行替换）：

Defaults work out of the box; override through patch layers (whole-row replace by id):

profile 的 cordis.patch.yml (or a later bundle layer)
- insert:
- id: dsh-task-toast
name: dsh-task-toast
config:
enabled: true          # 总开关 (master switch)
mode: turn             # turn | tool | both
successSound: chimes   # 更长的成功音；或任意音频文件路径
failureSound: hand
otherSound: ''         # 静音；可设成 exclamation/question 等
repeat: 2              # 连播次数（间隔 300ms），想更醒目就调大
toast: true            # 桌面通知（成功/失败）
speak: false           # TTS 播报（需已装对应语言语音包）
minIntervalMs: 1200    # 两次动作（声音/通知/语音）最小间隔
ignoreTools: []        # tool/both 模式下忽略的工具名

声音名映射（三个平台通用，候选依次回退到第一个存在的文件）：

| 名字 / Name | Windows | Linux (freedesktop) | macOS |
| --- | --- | --- | --- |
| chimes ⭐ | chimes.wav → tada.wav → Windows Ding.wav | complete.oga → bell.oga → message.oga | Glass.aiff → Hero.aiff → Funk.aiff |
| tada ⭐ | tada.wav → chimes.wav → notify.wav | complete.oga → bell.oga → message.oga | Funk.aiff → Hero.aiff → Glass.aiff |
| notify ⭐ | Windows Notify System Generic.wav → notify.wav → Windows Ding.wav | message.oga → bell.oga → dialog-information.oga | Ping.aiff → Pop.aiff → Tink.aiff |
| ringout ⭐ | Windows Ringout.wav → Ring01.wav → notify.wav | phone.oga → bell.oga → message.oga | Funk.aiff → Ping.aiff → Pop.aiff |
| hand | Windows Foreground.wav → Windows Error.wav → Windows Critical Stop.wav | dialog-error.oga → dialog-warning.oga → bell.oga | Sosumi.aiff → Basso.aiff → Frog.aiff |
| asterisk | SystemAsterisk 方案 | dialog-information.oga → bell.oga → message.oga | Glass.aiff → Ping.aiff → Pop.aiff |
| exclamation | SystemExclamation 方案 | dialog-warning.oga → dialog-information.oga | Basso.aiff → Blow.aiff |
| question | SystemQuestion 方案 | dialog-question.oga → bell.oga | Purr.aiff → Tink.aiff |
| beep / default | SystemDefault 方案 | bell.oga → dialog-information.oga | Pop.aiff → Tink.aiff |
| 任意音频文件路径 | 直接播放 | 直接播放 | 直接播放 |

⭐ = 更长 / 更醒目选项（推荐成功音用 chimes 或 tada）

常见问题 / FAQ

听不到声音？
- 检查系统音量 / Windows 声音方案（Win+R → mmsys.cpl → 声音 > 声音方案，确认「默认提示音」未设为「无声」）
- Linux 需安装任一播放器：sudo apt install pulseaudio-utils（paplay）或 alsa-utils（aplay）
- 试试 node scripts/play-sounds.mjs 独立排查

桌面通知不弹？
- Windows：设置 > 系统 > 通知，允许来自 PowerShell 的通知
- Linux：需要 libnotify-bin（notify-send）
- macOS：需要在登录的 GUI 会话中运行（SSH 会话无法弹通知）

语音播报不响？
- Linux 装 speech-dispatcher（spd-say）或 espeak-ng
- Windows 需安装中文语音包（设置 > 时间和语言 > 语音）
- macOS 自带 say，中文语音默认可用

每次回合都响太吵？
- 把 minIntervalMs 调大（如 5000），或 mode 保持 turn（只在回合结束响一次）

开发 / Development

npm run build                    # tsc -> dist/index.js
npm test                         # 单元测试（三平台命令断言）
node test/integration.mjs        # 真实 Cordis Context 装载 + 事件触发（会真实播放/弹通知）
node scripts/play-sounds.mjs     # 试听默认成功/失败/自定义声音
node scripts/toast-demo.mjs      # 弹一次成功 + 一次失败 Toast

生成的 POSIX 命令已用 sh -n 语法校验；Windows 命令面向 PowerShell 5.1，Linux/macOS 面向 POSIX sh。

License

MIT