前言¶
在使用 DeepSeek Harness（DSH）时，Agent 运行、需要授权或等待选择时，往往需要在控制台窗口来回切换。如果能直接在系统通知中心看到这些状态，就能减少手动刷新的负担。
dsh-agent-notify 就是为此设计的 DSH 客户端插件。它监听 Agent 的运行状态和会话事件，在需要你介入的三个时刻弹出 WinRT Toast 通知，并显示在 “DeepSeek Harness” 的通知条目下，点击可回到桌面应用。
插件定位¶
- 名称：dsh-agent-notify（仓库：ssupervipuser/dsh-agent-notify）
- 维护者：Ssupervipuser
- 分类：客户端
- 作用：当 DSH Agent 完成任务、需要授权或等待用户选择时，在 Windows 通知中心显示真实系统通知（WinRT Toast）
核心能力¶
插件通过监听以下事件触发通知：
-
任务完成：
agent/status从running变为idle，且期间有turn/end事件。通知标题根据结束原因显示（如“任务完成”“任务出错”等）。 -
需要授权：会话事件
approval/asked触发。通知标题为“需要你的授权”，用于工具调用被权限确认卡住时提醒。 -
需要你选择：会话事件
tool/call且工具为ask_user_question时触发。通知标题为“需要你的选择”。
上述触发条件只对主 Agent 会话生效，子会话（subagent）全部跳过，避免代理团队刷屏。同一会话同类等待通知默认 20 秒冷却，防止重试时连续推送。
安装与启用¶
环境要求¶
- Windows 10/11
- PowerShell 5.1（
WindowsPowerShell\v1.0\powershell.exe，WinRT 投影仅在该版本可用） - DeepSeek Harness 桌面版（通知以该应用的 AppUserModelID 发送）
- Node.js ≥ 20
安装步骤¶
从市场或 GitHub 安装（任意非 desktop profile）：
dsh plugin add --profile web github:Ssupervipuser/dsh-agent-notify
如果使用桌面版 profile（由 Electron 应用管理），请用仓库自带的安装脚本：
git clone https://github.com/Ssupervipuser/dsh-agent-notify.git
node dsh-agent-notify/test/install.mjs
安装脚本会：备份 profile 清单 → 发布 lib/releases/impl-<build>.js → 写入稳定入口 shim → 更新 package.json 依赖与 dsh.profile.bundles。
验证安装：
node test/installed-smoke.mjs
配置¶
在 profile 的 cordis.patch.yml 中找到 agent-notify 这一行，覆盖其 config 字段（整段替换，保留需要的键）。默认配置如下：
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
总开关 |
minDurationSec |
0 |
只通知耗时超过 N 秒的“任务完成”（0 = 总是通知） |
duration |
long |
Toast 停留时长：long（≈25 秒）/ short（≈5 秒） |
silent |
false |
静音（silent="true"） |
appId |
'' |
指定 AppUserModelID；空 = 使用桌面应用自己的 AUMID |
fallbackCard |
true |
Toast 不可用时是否画兜底卡片 |
cardSeconds |
8 |
兜底卡片停留秒数 |
skipWhenForeground |
false |
当前窗口标题已包含该会话时跳过通知 |
title |
'' |
覆盖“任务完成”标题行；空 = 按结束原因自动取 |
notifyApprovals |
true |
权限请求时通知 |
notifyQuestions |
true |
需要用户选择/回答时通知 |
alertCooldownSec |
20 |
同一会话同类等待通知的最小间隔（秒） |
例如，只保留“任务结束”通知、静音、且只在任务超过 30 秒时提醒：
- id: agent-notify
config:
enabled: true
minDurationSec: 30
duration: long
silent: true
appId: ''
fallbackCard: true
cardSeconds: 8
skipWhenForeground: false
title: ''
notifyApprovals: false
notifyQuestions: false
alertCooldownSec: 20
通知通道与兜底¶
-
主通道：
lib/notify.ps1调用 WinRTToastNotificationManager，使用 DSH 桌面应用的 AppUserModelID（com.deepseek.dsh）发送，因此系统显示为 “DeepSeek Harness” 的通知，可点击返回应用。 -
兜底：系统没有 Toast API 或 AUMID 被拒时，调用
lib/card.ps1画一张原生置顶卡片（不是网页弹窗）。 -
中文不乱码：文案通过 UTF-8 JSON 任务单文件传给 PowerShell，不走命令行码页。
更新与热更新¶
DSH 宿主按 URL 缓存 ESM 模块，直接改入口文件不会生效。安装副本里的 lib/index.js 是一个永不变化的 shim，每次激活时读取 lib/current-build.txt 并动态加载对应的 lib/releases/impl-*.js。重新发布后，只需触发配置重载（保存 profile 的 package.json 或切换行开关），新代码就会生效，无需重启应用。
若修改 lib/index.js 后未自动生效，可在 cordis.patch.yml 中切换该行开关（disabled: true 再改回 false）或重启应用。
安全与注意事项¶
插件会在本地执行 PowerShell：每次通知会启动一个短命子进程 powershell.exe -File lib/notify.ps1，将文案通过 UTF-8 JSON 任务单文件传给脚本。它不发起网络请求、不读取凭据，也不在插件目录以外写入文件（仅 %TEMP% 下的日志与任务单）。通知文本来自会话标题和工具参数，写入 JSON 前不经过 shell，因此不会被拼进命令行。
适用场景：需要将 DSH Agent 的运行状态与操作权限同步到桌面环境，减少在终端与桌面间切换的开发者。使用前请确保插件源码与许可证与预期一致。
短结尾¶
dsh-agent-notify 通过 WinRT Toast 在 Windows 通知中心呈现 DSH Agent 的运行状态与等待事件，配合本地 PowerShell 通道与兜底机制，在桌面与终端之间提供直观的状态同步。如需查看目录页或源码仓库，可访问：https://www.skillhub.cn/plugins/Ssupervipuser/dsh-agent-notify 与 https://github.com/Ssupervipuser/dsh-agent-notify。
