dsh-helper

dsh-helper

🌏 English · 中文

一个 DSH 插件：当 agent 会话完成、异常或需要你确认时弹出 Windows 原生通知，完成时还可附带提示音——长任务可以放手不管，出事的瞬间你会知道。

✨ 功能一览

• 🔔 任务通知 — agent 进入空闲（任务完成）、出错、或即将向你提问时，弹出 Windows 原生 Toast。
• 🔊 完成音效 — 会话完成时播放提示音。随包内置一段合成的双音提示音；音量可调（0–100），也可指定任意本地音频文件（wav / mp3 / wma）。
• ⚙️ 设置面板 — DSH 设置页新增「任务通知 (dsh-helper)」分区：三个通知开关 + 音效控制。
• 🧪 测试按钮 — 一键发送测试通知并按当前设置试听音效，验证本机链路是否正常。
• 🪶 零原生依赖 — 通知走 PowerShell WinRT Toast，无需编译任何二进制。
• 🔁 热重载 — 配置写回 profile 的 cordis.patch.yml，由 DSH 的 patch watcher 自动生效，无需重启。

🚀 安装

前置条件：DSH 0.1.2-rc.1+，且 web profile 已初始化（至少跑过一次 dsh web），Node.js ≥ 20、pnpm ≥ 10。

方式一 — npm registry（推荐）

dsh plugin --profile web add dsh-helper@latest

包内是预构建产物（lib/ 已随包发布），不含任何安装脚本，因此 pnpm 不会要求你授权构建，装完即用。

方式二 — 从 git 仓库安装

dsh plugin --profile web add github:sunligh91/dsh-helper

git 源安装会拉源码并由 pnpm 运行 prepare；pnpm ≥10 在得到显式允许前会拒绝执行，需要把 pnpm 打印的包键写进该 profile 的 pnpm-workspace.yaml：

allowBuilds:
  dsh-helper: true

该授权等于「允许此包的代码在安装时于本机执行」。若只想装预构建代码，请用方式一。

方式三 — 从源码安装

git clone https://github.com/sunligh91/dsh-helper.git
cd dsh-helper

# 链接到你的 web profile
cd ~/.dsh/profiles/web
pnpm add file:/绝对路径/dsh-helper

然后把 "dsh-helper" 加进 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 数组，并硬刷新浏览器（Ctrl/Cmd + Shift + R）。

⚙️ 配置

进入 设置 → 任务通知 (dsh-helper)。

默认值随包附在 cordis.patch.yml；你的改动会写入 ~/.dsh/profiles/web/cordis.patch.yml。

🔌 工作原理

审批通知监听的是会话审计事件 approval/asked，而不是瀑布事件 approval/request。原因是 cordis 的 waterfall 语义为「不调用 next() 即否决整条链」，任何排在前面并直接返回结果的监听器（例如自动审批门控）都会让后面的监听器永远收不到事件。approval/asked 是决策前写入日志的纯审计事件，不受此影响。

设置路由（/_dsh/dsh-helper/settings）仅监听本机，非 127.0.0.1 / ::1 的请求一律返回 403。

🔄 还需要自动重试？ 本插件只做通知，这是有意为之。可搭配专门的重试插件，例如 dsh-task-reliability（它在同一事件上返回 { kind: 'retry' } 触发 DSH 原生重试）。

🛠️ 开发与构建

git clone https://github.com/sunligh91/dsh-helper.git
cd dsh-helper

两侧都是原生 ES module / UMD，没有打包器，改完刷新即可。

⚠️ 已知限制

• 通知面向 Windows（PowerShell WinRT Toast）。在 macOS/Linux 上插件仍会加载，但通知和音效都是静默空操作。
• 音效走 PowerShell + WPF MediaPlayer；不可用时退回 System.Media.SoundPlayer（仅支持 wav，且音量设置不生效）。
• 若 Windows「专注助手 / 勿扰」开启，通知可能被拦截。
• 投递身份（0.5.0 起自动处理）：Windows 要求桌面程序在开始菜单有一条携带 System.AppUserModel.ID 的快捷方式，否则 toast 会被间歇性静默丢弃（尤其当有前台窗口时），表现为「焦点不在本应用就收不到通知」。插件启动时会自动幂等补齐这条快捷方式（%APPDATA%\Microsoft\Windows\Start Menu\Programs\dsh-helper.lnk），无需手动操作、也无需管理员权限。
• 快捷方式若被清理软件删除，下次启动 DSH 会自动重建。

📄 许可证

MIT © sunligh91

📝 更新日志

• 0.5.0 — 修复「焦点不在 DSH 就收不到通知」：Windows 要求桌面程序的开始菜单快捷方式携带 System.AppUserModel.ID，否则 toast 会被间歇性静默丢弃。插件启动时自动幂等补齐该快捷方式（运行时自建，包内不含任何安装脚本，npm 安装无需授权）。另：审批通知改挂 session/event → approval/asked，不再被自动审批门控的瀑布抢答吞掉。
• 0.4.4 — 移除 0.4.3 引入的全局节流（会吞掉并发主会话的完成通知），只保留子 agent 不通知这一条过滤规则。
• 0.4.3 — 修复通知轰炸：任务完成通知不再对子 agent 触发（dsh 并行跑多个子 agent，每个收尾都发一条，通知中心被刷爆——主会话 id 带 session- 前缀，子 agent 是裸 UUID，据此过滤）；另加全局节流，60 秒内最多一条完成通知。
• 0.4.2 — 通知顶部改用自有应用标识：AUMID 从借用的 File Explorer GUID 换成 dsh-helper，并在每次发送前幂等写入 HKCU\Software\Classes\AppUserModelId\dsh-helper 的 DisplayName，通知顶部由一串十六进制 GUID 变为 dsh-helper。
• 0.4.1 — 修复通知回退成弹窗的根因：GetTemplateContent 被误调在 ToastNotifier 实例上（该方法属于 ToastNotificationManager 静态类），WinRT toast 从未真正成功过，一直走 WScript 弹窗兜底。现改回正确调用并实测弹出真通知。
• 0.4.0 — 新增「需要授权」通知（钩 approval/request 事件，工具权限审批时提醒）；设置面板拆分为三个测试按钮：完成 / 多选一确认 / 权限审批。
• 0.3.2 — 修复确认通知不显示：Windows 会静默丢弃未注册自定义应用 id 的 Toast，现改用文件资源管理器的注册 AUMID 发送；新增 WScript.Shell 弹窗兜底。
• 0.3.1 — 加入临时诊断日志（确认问题解决后移除）。
• 0.3.0 — 新增完成音效（内置合成双音、音量可调、可指定本地文件）。
• 0.2.0 — 移除自动重试，专注通知。
• 0.1.0 — 首个版本：完成 / 异常 / 确认通知。