dsh-turn-notify

DSH 通知插件：在 Agent 需要你介入的任何时刻发送 Windows 系统通知。

在 Agent 运行过程中，开发者往往需要离开屏幕处理其他事务，此时很难第一时间感知到 Agent 何时完成了任务、遇到了阻塞或等待人工批准。dsh-turn-notify 通过 Windows Toast 通知和系统提示音，在 Agent 需要人工操作时通知开发者。

功能特性¶

触发时机
插件覆盖 Agent 运行中的关键状态，包括：
* 轮次完成
* 目标阻塞 / 暂停
* 对话中断 / 中止
* 轮次出错
* 达到输出上限
* 会话中断（崩溃恢复）
* 等待批准
* 等待回答（Agent 主动提问）
* 计划待审阅
* 运行出错（步骤级错误）

通知样式与行为
* 通知类型：支持 Windows Toast 长横幅与特定模板。
* 内容预览：显示会话编号、问答内容预览（默认截断 15 字）。
* 提示音：默认播放 Windows Background.wav，与弹窗同步。
* 子代理静默：仅通知根会话，子代理产生的通知会被过滤。
* 防风暴机制：同会话内同类关键事件在 1.5 秒内合并为一条通知，避免重复弹窗。
* 多会话隔离：按 session.id 区分，互不干扰。
* 双语支持：支持中文与英文。

降级方案
* 优先使用 C# 编译的 dsh-notify.exe。
* 缺失时自动回退 notify.ps1 脚本。
* 通知失败时降级为日志记录。

安装与启用¶

使用官方命令安装插件。安装后需要在配置文件中启用相应事件的通知。

1. 安装插件

dsh plugin --profile web add github:Ruiming-cn/dsh-turn-notify

2. 配置补丁
在 ~/.dsh/profiles/web/cordis.patch.yml 中为 turn-notify 条目添加 config 配置。以下配置项均为可选，插件代码内部已有默认值：

    - id: turn-notify
      config:
        language: zh            # zh | en
        sound: true
        notify:
          completed: true
          blocked: true
          aborted: true
          error: true
          maxTokens: true
          interrupted: true
          goals: true
          approvals: true
          questions: true
          planReview: true
          agentError: true
        cooldownMs: 10000
        mergeWindowMs: 1500
        previewChars: 15
        titlePrefix: DSH
        showSessionTag: true
        timeoutMs: 10000
        dryRun: false
        rootSessionsOnly: true

3. 重启 DSH
修改插件代码后，必须重启 DSH GUI 才能生效。

构建原生通知器¶

插件仓库中不包含 dsh-notify.exe 二进制文件，需要自行编译。

1. 准备环境
确保系统安装了 .NET Framework 4.8 的 csc.exe（通常位于 C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe）以及 Windows SDK 的 Windows.winmd。

2. 编译
在 plugin/ 目录下执行以下命令编译 C# 源码：

$winmd = "C:\Program Files (x86)\Windows Kits\10\UnionMetadata\10.0.26100.0\Windows.winmd"
$sysruntime = "C:\Windows\Microsoft.NET\assembly\GAC_MSIL\System.Runtime\v4.0_4.0.0.0__b03f5f7f11d50a3a\System.Runtime.dll"
& "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe" /nologo /nostdlib /target:exe /out:"dsh-notify.exe" /r:mscorlib.dll /r:System.dll /r:System.Core.dll /r:"$sysruntime" /r:System.Windows.Forms.dll /r:System.Drawing.dll /r:System.Runtime.WindowsRuntime.dll /r:"$winmd" "dsh-notify.cs"

编译完成后，将 plugin/ 目录整体拷贝到全局 DSH 目录，重启 GUI 即可使用原生通知器。

注意事项¶

• 系统要求：仅支持 Windows 10/11。
• 重启生效：修改插件代码（JS 或 C#）后，必须重启 DSH GUI 才能加载新代码。
• 安全软件：PowerShell 回退脚本可能被安全软件拦截，建议自行构建 dsh-notify.exe。
• 通知特性：通知是系统级 UI，与 DSH 窗口焦点无关；如果开启了系统的“专注助手”，可能会阻止通知弹出。