dsh-windows-notify：Windows 级系统提醒插件

前言¶

DeepSeek Harness（DSH）的 Agent 运行是异步的。在长时间任务或后台运行时，单纯依赖控制台日志容易错过关键状态变更。dsh-windows-notify 插件为 DSH 提供了 Windows 原生的系统级提醒能力，通过 Toast 弹窗、自定义提示音和任务栏气泡角标，将 Agent 的运行状态、待决策提示直接同步到桌面环境。

该插件作为原生 DSH 配置文件插件（Profile Bundle）开发，不修改任何内置包文件，安装升级后重启即可生效。

核心功能¶

Agent 回合状态通知
监听 Agent 状态从 running 到 idle 的变化。当 Agent 完成当前回合或任务结束时，触发系统 Toast 弹窗。支持「仅角标」模式与 5 秒窗口内的合并摘要显示。
决策提醒与角标联动
当 Agent 调用 ask_user_question 需要输入时，弹出「DSH 需要你的决定 ❓」提示框，列出问题与选项。用户回答或取消后，任务栏托盘图标右上角的红色气泡角标自动减 1。
任务栏气泡角标
托盘图标右上角的红色气泡同时显示「待回复决策」与「已完成但未查看」的数量。单击托盘图标可打开 DSH GUI 并清零已完成项。DSH 退出后，托盘进程会通过端口看门狗自动关闭。
提示音与免打扰
内置四套合成提示音（soft/brisk/calm/crisp），无版权风险，可在设置页试听。支持免打扰时段（支持跨午夜设置），期间仅累计角标，不弹窗不发声。同时支持跟随 Windows 专注助手或系统勿扰模式静音。

安装与启用¶

安装命令如下，将插件添加到指定 DSH Profile 中：

dsh plugin --profile web add dsh-windows-notify

安装或升级后，必须重启 DSH 才能加载新的插件配置和补丁。

配置与用法¶

设置页配置¶

插件在 DSH 设置页增加了一个「通知」区段，命名空间为 dsh-notify。修改配置后保存即生效。

配置项	默认值	说明
`sound`	`soft`	提示音风格：soft / brisk / calm / crisp
`soundEnabled`	`true`	提示音总开关
`quietHours.enabled` / `start` / `end`	`false` / `22:00` / `08:00`	免打扰时段（支持跨午夜）
`respectSystemDnd`	`true`	跟随 Windows 专注助手/勿扰
`completeMode`	`toast`	完成通知模式：toast 弹窗 / badge-only 仅角标
`completeMerge`	`true`	5 秒窗口内合并完成摘要

环境变量控制¶

通过环境变量可全局控制插件行为：

DSH_NOTIFY=0：禁用所有通知。
DSH_NOTIFY_SOUND=<wav路径>：覆盖默认提示音路径。
DSH_NOTIFY_MIN_INTERVAL_MS：设置通知节流间隔（防止高频弹窗）。

技术架构与限制¶

插件机制¶

插件采用原生 DSH 插件机制实现：
* Profile Bundle：通过 cordis.patch.yml 补丁层向 Profile 组合注入依赖。
* Settings 命名空间：使用 ctx.settings.register 注册 dsh-notify 配置，持久化到 $DSH_HOME/settings.yaml。
* WebServer 路由：提供 /api/dsh-notify/config（读写配置）与 /api/dsh-notify/preview（试听）接口。

技术实现¶

宿主端：监听 agent/status 事件，处理决策提醒逻辑。
浏览器端：通过 __ModuleLoader__ 工厂零构建加载，通过自有路由读写配置（避开 DSH 的白名单限制）。
通知内核：通过 PowerShell 脚本调用 Windows WinRT Toast API 和 ITaskbarList3 接口实现原生 UI。脚本以 UTF-8 BOM 编码保存以支持中文。

已知限制¶

仅提醒：当前版本仅提供通知展示，不支持 Toast 内置按钮交互（受限于 Windows 对未打包应用的限制）。
热加载限制：Bundle 补丁不支持热加载，安装或升级插件后必须重启 DSH。
平台限制：仅支持 Windows 10/11。非 win32 平台（如 Linux、macOS）所有提醒逻辑会自动跳过。
数据隐私：配置与日志仅存储于本地 $DSH_HOME 目录，不联网、无遥测、不读取凭据。

结语¶

dsh-windows-notify 是一个专注于提升 DSH Windows 用户体验的插件，它通过原生的系统通知机制，解决了长时间运行任务时信息获取滞后的问题。如果你在 Windows 平台使用 DSH，这是一个值得安装的辅助工具。

项目地址：https://github.com/Sutera-Diffusus/dsh-windows-notify
插件目录：https://www.skillhub.cn/plugins/Sutera-Diffusus/dsh-windows-notify