dsh-win-toast：DeepSeek Harness 的 Windows 原生通知插件

前言¶

DeepSeek Harness（DSH）在需要确认或提问时，采用“浏览器端应答、宿主端永久等待”的模型。如果标签页不在前台，你很容易错过这些待办。dsh-win-toast 是一个宿主侧插件，在 DSH 进程中监听事件、调用 Windows Toast API，直接弹出系统通知，不依赖浏览器通知权限，也不要求标签页在前台。

是什么¶

名称：dsh-win-toast
维护者：LucienLL
类型：DeepSeek Harness 客户端插件（host-side）
仓库与文档：https://github.com/LucienLL/dsh-win-toast

它解决的是“标签页被切走、最小化或冻结时，仍能被及时提醒”的问题。

核心功能¶

插件在 DSH 宿主进程中监听四种事件，并在满足条件时弹出系统通知：

事件	默认开关	通知标题
`approval/request`（工具执行需要确认）	开	`DSH · 等待你确认`
`user-questions/request`（`ask_user_question`、计划确认）	开	`DSH · 需要你回答`
`turn/end` 且 `reason.kind === 'completed'`	开	`DSH · 回复完成`
`turn/end` 且为 `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`	开	`DSH · 回合中断`

不提醒的情况包括：

子智能体会话（header.origin === 'subagent' 或 delegationDepth > 0）——没有人类应答者，提醒为噪声。
turn/end 的 forked 原因——fork 种子的记账事件，不是你看到的回合结束。
同类通知小于 minIntervalMs（默认 1500ms）的重复——防止刷屏。

通知正文仅包含工具名、理由、会话标题，不含工具参数，避免敏感内容出现在锁屏界面。

安装与启用¶

从 npm 安装（推荐）：

dsh plugin --profile web add dsh-win-toast

或从本地目录安装：

dsh plugin --profile web add <本目录路径>

安装后重启 DSH web（插件是宿主侧插件，需要重新组合）。安装前建议只保留一个同功能插件（如 dsh-desktop-toast、dsh-desktop-notify、dsh-notify-me），避免同一次确认收到多条通知。

发送方身份（可选）¶

Windows 通知的发送方名称与图标由“与 AUMID 同名的开始菜单快捷方式”决定。没有快捷方式的 AUMID 会被 API 接受，但随后被系统静默丢弃。

不注册：默认使用 {1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe（系统自带），通知显示为“Windows PowerShell”。
注册（推荐外观）：在开始菜单创建带 AppID 的快捷方式，通知显示为“DeepSeek Harness”+ DSH 图标。

注册示例：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/register-aumid.ps1 `
  -Aumid 'DeepSeek.Harness.Notify' `
  -TargetPath 'E:\Program Files\DeepSeek Harness\DeepSeek Harness.exe' `
  -IconPath 'E:\Program Files\DeepSeek Harness\DeepSeek Harness.ico'

# 撤销
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/register-aumid.ps1 `
  -Aumid 'DeepSeek.Harness.Notify' -Unregister

注册后，在配置中将 appId 设为同一 AUMID；未注册时保持默认 PowerShell AUMID。

配置项¶

进入 DSH 的 Settings → Plugins，可配置以下字段：

键	默认	说明
`enabled`	true	总开关
`notifyApproval`	true	工具确认提醒
`notifyQuestion`	true	提问 / 计划确认提醒
`notifyTurnComplete`	true	回合完成提醒
`notifyTurnError`	true	回合异常提醒
`includeReason`	true	确认通知中是否附带工具给出的理由
`sound`	true	是否播放系统提示音
`minIntervalMs`	1500	同类通知最小间隔
`language`	zh	语言：`zh` / `en`
`appId`	PowerShell AUMID	通知发送方身份

实现要点¶

在 approval/request 与 user-questions/request 时以 { prepend: true } 注册回调，通知完成后原样 next() 交还给真正的应答者，不改变审批结果。所有回调包在 try/catch 中，通知失败不影响审批链路。
每次通知通过短命进程 powershell.exe -File lib/toast.ps1 发起（约 0.3–0.6s）。必须使用 Windows PowerShell 5.1（PowerShell 7 已移除 WinRT 投影，Windows.UI.Notifications 不可用）。
同一时刻只运行一个通知进程，后来的请求覆盖尚未启动的旧通知。
lib/toast.ps1 为纯 ASCII；Windows PowerShell 5.1 会按当前 ANSI 代码页解析无 BOM 的 UTF-8 脚本，源码中的中文会损坏。所有中文正文通过命令行参数（UTF-16）传入。

已知边界¶

Windows 专注助手 / 勿扰模式以及每个 AUMID 的通知开关拥有最终否决权，插件无法绕过。
DSH 标签页完全关闭时，审批本身仍会 fail-closed 拒绝，通知仅起提醒作用。
若不希望会话标题出现在通知中，可关闭对应开关。

验证方式¶

运行以下命令进行验证：

node --check lib/index.js
node test/notify.test.mjs        # 纯逻辑单测（10 项）
node scripts/smoke-wiring.mjs    # 假 ctx 跑通三条监听 + 瀑布委托，并实测发通知

smoke-wiring.mjs 结束后，可用 PowerShell 查询 Toast 历史，确认通知真正送达：

[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime]
([Windows.UI.Notifications.ToastNotificationManager]::History.GetHistory('DeepSeek.Harness.Notify')).Count

适用场景与注意¶

适合需要在后台被及时提醒的场景，如长时间运行的智能体、需要人工确认的工具调用链。
插件以当前 DSH 进程权限运行，安装前建议查看源码与许可证（MIT）。
Windows 专注助手 / 勿扰模式、各 AUMID 的通知开关为最终否决权，插件无法绕过。

总结¶

dsh-win-toast 在 DSH 宿主进程中直接调用 Windows Toast API，在需要确认、提问或回合结束时提供系统级通知，不依赖浏览器通知权限和前台标签页。它通过事件监听、AUMID 注册、配置开关和实现细节，将“错过待办”的风险降到最低。

插件目录页：https://www.skillhub.cn/plugins/LucienLL/dsh-win-toast
GitHub 仓库：https://github.com/LucienLL/dsh-win-toast