前言¶
在 DSH 里跑长任务时，浏览器窗口往往不在前台：智能体跑完、报错、或弹出多选确认、工具权限审批时，如果没有任何提醒，你只能隔一段时间回来点一下界面才知道状态。系统邮件、第三方 IM 可以补一层，但需要额外集成，也不一定能对齐 DSH 会话里的具体事件。
下面介绍社区插件 dsh-helper（npm 包名 dsh-helper）。它在 Windows 上通过原生 Toast 在会话结束、出错、即将提问或需要权限审批时弹出通知，并可选用完成提示音；配置写在 DSH Settings 里，改完会写回 profile 的 cordis.patch.yml，由 DSH 的 patch 监听热更新，无需重启。插件要求 DSH 0.1.2-rc.1+，且 web profile 已初始化；通知能力面向 Windows（macOS / Linux 下仍会加载，但 Toast 与声音为无操作）。
维护与源码见 GitHub 仓库 sunligh91/dsh-helper（MIT）。社区目录页：SkillHub — FlyGame91/dsh-helper。目录站为社区收录，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-helper 是 DSH 的 Cordis 插件：监听智能体与会话相关事件，在主机侧调用 PowerShell WinRT Toast 发通知，可选播放完成铃音；客户端通过 dsh-client-ui-settings 注入 Task Notifications (dsh-helper) 设置区。它不拦截或重试任务；若需要失败自动重试，README 建议搭配例如 npm 包 dsh-task-reliability 等重试类插件。
当前资料中的版本为 0.5.0；发布物为预构建的 lib/，npm 安装路径下无 install scripts，pnpm 不会因此要求授权构建。
核心功能¶
任务通知¶
在以下场景弹出 Windows Toast（均可单独开关）：
| 场景 | 默认 | 说明 |
|---|---|---|
| 会话结束 | 开启 | agent/status 为 idle 时；同一 session 60 秒内去重一次 |
| 出错 | 开启 | agent/request-error，仅透传，不阻塞、不重试 |
| 多选确认 | 开启 | tools/pre-execute 且为 ask_user_question |
| 权限审批 | 开启 | session/event → approval/asked（审计事件，避免被更早的 approval/request 瀑布链抢先返回而收不到通知） |
设置页提供三个测试按钮，可分别预览完成、多选确认、权限审批三类真实通知样式。
完成提示音¶
会话完成且开启 soundOnComplete 时，在完成 Toast 之后播放声音。内置合成双音铃；音量 0–100（默认 70）。soundFile 可指向本地 wav / mp3 / wma；为空用内置铃音；自定义文件缺失时回退内置，再回退 Windows 系统通知音。播放经 PowerShell WPF MediaPlayer；不可用时回退 System.Media.SoundPlayer（仅 wav，且忽略音量设置）。
设置与热更新¶
在 DSH 中打开 Settings → Task Notifications (dsh-helper)。默认值来自包内 cordis.patch.yml；你的覆盖写入 ~/.dsh/profiles/web/cordis.patch.yml。设置相关的 HTTP 路由为 /_dsh/dsh-helper/settings，仅绑定 localhost（非 127.0.0.1 / ::1 返回 403）。
Windows 投递身份（0.5.0）¶
Windows 要求桌面应用在「开始」菜单快捷方式上携带 System.AppUserModel.ID，否则 Toast 可能被间歇性静默丢弃（常见现象是只有窗口在前台时才收到）。插件在启动时幂等地创建 %APPDATA%\Microsoft\Windows\Start Menu\Programs\dsh-helper.lnk；无需管理员、无 install scripts。若清理工具删了快捷方式，下次启动 DSH 会再建。
安装与启用¶
前提：已至少执行过一次 dsh web 以初始化 web profile；Node.js ≥ 20；pnpm ≥ 10。
推荐从 npm 安装预构建包：
dsh plugin --profile web add dsh-helper@latest
若从 Git 源安装（会拉源码并在 prepare 阶段构建），pnpm ≥ 10 需显式允许构建。安装命令以 README 为准：
dsh plugin --profile web add github:sunligh91/dsh-helper
按 pnpm 提示在对应 profile 的 pnpm-workspace.yaml 中加入例如：
allowBuilds:
dsh-helper: true
仅希望使用预构建产物时，应优先使用上面的 npm 方式。
安装后可在设置页调整通知与声音；若从本地 file: 等方式链入插件，还需把 dsh-helper 加入 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 并对浏览器硬刷新（Ctrl/Cmd + Shift + R）。具体见仓库 README。
典型用法¶
1、按上一节完成安装，确认 DSH 版本满足 0.1.2-rc.1+。
2、打开 Settings → Task Notifications (dsh-helper)，按需开关四类通知与完成音；可用测试按钮确认 Toast 是否正常（注意 Windows 专注助手 / 勿扰可能压制通知）。
3、发起一段会进入 idle、或会触发确认/审批的智能体任务，切到其他窗口等待；对应事件应收到 Toast，完成时可选听到铃音。
配置项与默认值（摘自 README）：
| Key | 默认 | 说明 |
|---|---|---|
notifyOnComplete |
true |
会话结束通知 |
notifyOnError |
true |
错误通知 |
notifyOnConfirm |
true |
多选提问前通知 |
notifyOnPermission |
true |
工具权限审批通知 |
soundOnComplete |
true |
完成后播放铃音 |
soundVolume |
70 |
铃音音量 0–100 |
soundFile |
"" |
自定义音频路径，空为内置铃音 |
适用场景与注意¶
适合：主要在 Windows 上使用 DSH web profile、长时间后台跑智能体、需要在「跑完 / 出错 / 要你点选 / 要审批」时立刻被叫回桌面的开发者。
局限（见 README Known limitations）：
- 通知与铃音依赖 Windows；其他平台无实际 Toast/声音。
- 勿扰模式下 Toast 可能被系统抑制。
- 本插件只做通知，不做自动重试；重试需另装插件。
安全与信任：插件以当前 DSH 进程权限运行，会通过 PowerShell 发 Toast、播声音，并监听会话与工具事件。安装前请阅读 sunligh91/dsh-helper 源码与 MIT 许可证，确认符合你的环境策略；从 Git 安装并允许 allowBuilds 意味着允许该包在安装时在本机执行构建脚本。
结尾¶
dsh-helper 把 DSH 里几类「需要你回来」的时刻对齐到 Windows 原生通知与可选完成音，配置集中在 Settings，改完即热加载。若你已在用 DSH 跑长任务，可以把它当作 web profile 上的轻量提醒层；需要失败重试时再单独选配合的重试插件。
