审批桌面通知 sakuraboy9128-cmd/dsh-approval-notify

dsh-approval-notify

一个 DeepSeek Harness 插件包（bundle）：当 DSH 正在等你本人批准某次工具调用时，弹出桌面通知；点击通知会把 DSH 窗口切到前台。

通知卡片

托底展示方式（win32 卡片）：toast 不可用时的实际截图。

它覆盖审批服务发出的所有 ask，包括 @deepseek-ai/dsh-experimental-auto-review 在 ask 审批策略下产生的 ask —— 这正是它被写出来的场景：Auto review 拒绝了某个调用，DSH 来问你，而你没在看窗口。

通知只是提醒，不是授权。通知本身不能批准任何东西，决定仍然在 DSH 界面里做，通知也不会改变审批结果。

它做什么

- 在 @deepseek-ai/dsh-user-approval 拥有的 approval/request waterfall 上挂一个监听器。
- 用请求自身的字段（toolName、displayReason、reason）生成本地化标题与正文。不做任何推测：没有工具名的请求会被明确标注为未知，而不是猜一个。
- 在可配置的时间窗内压掉完全重复的通知（同工具 + 同原因），所以同一次请求不会播报两遍，而不同的请求一定会播报。
- 在 Windows 上通过一个常驻的 PowerShell 助手进程展示：进程有包标识符时用 WinRT toast，否则在屏幕角落显示置顶通知卡片。
- 点击时恢复并聚焦 DSH 窗口；若 DSH 没在运行，则启动配置的可执行文件，由它的单实例锁还原已有窗口。
- 在审批 waterfall 里从不抛错、也从不等待自己的 I/O：通知出问题不会把审批变成 fail-closed 的 unavailable，也不会拖慢 responder。

macOS（osascript）与 Linux（notify-send）只发普通通知，不含点击聚焦动作。

环境要求

- DSH 已挂载 approval 服务（@deepseek-ai/dsh-user-approval）——官方 Desktop 与 Web profile 默认如此。
- Windows 10/11 才有 toast 与卡片两种展示；macOS/Linux 需要系统自带 osascript/notify-send。
- 无任何 npm 依赖，只 import Node 内置模块。

安装

dsh plugin --profile <profile> add /absolute/path/to/dsh-approval-notify

CLI 会安装该包并把本 bundle 声明的 patch 追加进 profile，于是 approval-notify 这一行成为 profile 的一部分。如果 loader 提示需要重启，重启 DSH 即可。<profile> 换成你想接收通知的 profile —— 内置 Auto review 的是 desktop。

依赖它之前，先把通知链路自检一遍：

node bin/cli.mjs test # 弹一条测试通知
node bin/cli.mjs doctor # 打印链路里解析出的每个输入
node bin/cli.mjs logs # 查看插件与助手日志

配置

插件行的 config 支持下列字段。括号内为默认值；不可用的取值会回退到默认值，并在插件日志里留下一条 warning。

| 字段 | 默认 | 含义 |
| enabled | true | 设为 false 时插件照常激活但完全不通知 |
| mode | auto | auto = 先 toast，再卡片；也可选 toast、popup、balloon、none |
| clickAction | focus-dsh | focus-dsh 聚焦或启动 DSH 窗口；none 不做任何事 |
| locale | auto | auto 跟随宿主语言；也可 zh、en |
| title | '' | 自定义标题；留空使用本地化默认标题 |
| includeReason | true | 是否把请求自带的原因放进正文 |
| maxBodyChars | 220 | 标题与正文超过此长度即截断 |
| dedupeWindowMs | 4000 | 该窗口内压掉「同工具 + 同原因」的重复；0 关闭 |
| appId | '' | WinRT toast 的 AppUserModelID；留空依次尝试 DSH 自己的 ID 与 Explorer |
| dshExePath | '' | 没有 DSH 窗口时启动的可执行文件；留空自动探测 |
| windowTitleSuffix | DeepSeek Harness | 用于识别要聚焦的 DSH 窗口的标题后缀 |
| registerProtocol | true | 注册 dsh-approval-notify:// 处理器，使 toast 点击能聚焦 DSH |
| popupTimeoutMs | 12000 | 卡片停留时长；鼠标悬停会暂停倒计时 |
| helperIdleMs | 900000 | 助手进程空闲多久后退出 |
| sound | true | 是否播放提示音 |
| dshExeCandidates | [] | 在内置路径之前优先尝试的额外可执行文件路径 |

patch 行示例：

- id: approval-notify
name: 'dsh-approval-notify'
config:
mode: popup
locale: zh
dedupeWindowMs: 10000

点击如何回到 DSH

registerProtocol 会在 HKCU\Software\Classes\dsh-approval-notify 下写三个值，让 Windows 把 dsh-approval-notify://focus 交给本包自带的助手脚本。想撤销只需一条命令：

node bin/cli.mjs unregister-protocol

卡片展示方式完全不需要协议处理器：点击事件直接落在助手进程自己身上，这也是卡片在「点击聚焦」上更可靠的原因。

Windows 只允许「刚刚收到过用户输入」的进程把窗口提到前台，所以聚焦只在点击路径上尝试，绝不在后台尝试。助手会把实际生效的策略（setForegroundWindow、isForeground 或 launched）写进 helper.log，也就是 dsh-approval-notify logs 打印的内容。

已验证行为

环境：Windows 11（build 26100）、DSH Desktop profile、Node 24。

| 行为 | 结果 |
| approval/request 监听器收到真实 ask 并发出通知 | 已验证 —— plugin.log 记录 notified: tool=pwsh reason=displayReason.zh |
| bundle 在运行中的 profile 里免重启激活 | 已验证 —— 热加载进 desktop profile，plugin.log 记录 activated: … presenter=windows |
| 由 DSH 宿主进程启动的助手发 WinRT toast | 已验证成功 —— toast sent with AppUserModelID "com.deepseek.dsh" |
| 由沙箱子进程发 WinRT toast | 失败：com.deepseek.dsh、ai.deepseek.dsh.desktop、Microsoft.Windows.Explorer、PowerShell AUMID 均返回 0x80073D54（进程无包标识符） |
| toast 被拒后回退卡片 | 已验证 —— 卡片确实出现在屏幕上且可点击（assets/screenshot-popup.png） |
| 点击聚焦 DSH 窗口 | 已验证 —— 日志记录 setForegroundWindow=True isForeground=True，来自真实点击 |
| 协议处理器注册 | 已验证 —— reg.exe 退出码 0, 0, 0 |
| 钩子接线：prepend 监听、next() 透传、notifier 抛错被兜住 | 由 test/plugin.test.mjs 验证 |
| 单元测试 | 40 个全部通过（node --test） |

toast 是首选路径，并且在宿主允许的环境里确实可用：「有无包标识符」由谁启动了助手进程决定，所以 auto 保持 toast 优先、卡片兜底，并把每条通知实际走的路径写进日志，而不是假设某一条必然可用。

上表中的真实 ask 来自一次沙箱提权审批。Auto review 的 ask 走同一个 seam —— 它的 tools/pre-execute 监听器返回 { kind: 'ask', reason, displayReason }，由工具管线交给 ctx.approval.request() —— 因此被同一个监听器覆盖；但本次没有单独端到端观察它。

未验证：macOS/Linux 展示方式（无对应宿主）、多显示器、以及 DSH 以管理员身份运行而助手不是的情况。

排查

| 现象 | 原因与处理 |
| 完全没有通知 | 会话审批策略是 never（服务会在任何 responder 之前直接拒绝，因此根本不会 ask）、插件行被禁用，或 mode: none。先看 dsh-approval-notify logs。 |
| 从不出现 toast，只有卡片 | 无包标识符宿主上的预期行为，helper.log 里会有 0x80073D54。可设 mode: popup 跳过这次尝试。 |
| 点击不聚焦 DSH | registerProtocol: false，或没有窗口标题以 windowTitleSuffix 结尾。把 windowTitleSuffix 改成你语言下 DSH 实际使用的后缀。 |
| 语言不对 | 显式设置 locale；auto 跟随宿主进程语言。 |
| 通知会重复 | 不同原因本来就是不同通知。调大 dedupeWindowMs 可以合并近似重复。 |
| 助手进程残留 | 宿主退出时它会自动退出，空闲超过 helperIdleMs 也会退出。必要时设 mode: none 并重启 DSH。 |

日志位于 %TEMP%\dsh-approval-notify\（plugin.log、helper.log）。若宿主给每个进程分配的临时目录都不同，可用环境变量 DSH_APPROVAL_NOTIFY_DIR 固定该目录。

开发

node --test # 40 个测试，无依赖
node bin/cli.mjs test --mode popup --wait 20000

结构：index.js（Cordis 插件）、lib/（配置、文案、去重、展示器、助手生命周期）、assets/notify-helper.ps1（toast、卡片、balloon 与协议处理器合在一个文件里）、bin/cli.mjs、test/。

许可

MIT，见 LICENSE。