🔔 dsh-notify-windows
DeepSeek Harness（DSH）插件：当 Agent 需要你关注时，向 Windows 发送系统桌面通知
任务完成 ✅ ｜ 等待审批 🔐 ｜ 等待回答 ❓ —— 离开屏幕也不错过任何需要你处理的事。
✨ 功能特性 / Features
- 任务完成提醒：监听会话
turn/end 事件，任务完成 / 出错 / 输出超限时立即弹窗，标题自动使用会话标题，正文显示原因与轮次；
- 权限审批提醒：监听
approval/asked 事件，有操作等待你的审批时立即提醒；会话审批策略为 never 时自动跳过（此时没有东西在等你）；
- 提问确认提醒：Agent 调用
ask_user_question 向你提问时提醒；本部署下所有工具都经 run_code 调用，插件会扫描 run_code 程序源码中的 tools.ask_user_question( 调用并提取问题文本；
- 防打扰：默认忽略子代理（subagent）会话，只提醒主会话；
- 零依赖：通知通过 Windows PowerShell 5.1 的 WinRT Toast API 发送，自动注册 HKCU 的 AppUserModelId（无需管理员权限）；
- 可诊断：可选日志（
%TEMP%\dsh-notify\notify.log）与 debug 事件日志。
📦 安装 / Install
项目通过 dsh.bundle 机制安装：npm 包自带的 cordis.patch.yml 会在
dsh plugin add 后自动挂载 dsh-notify 入口，不需要再手动 - insert:。
dsh plugin --profile web add dsh-notify-windows
重启 DSH 并刷新浏览器后生效：
dsh --profile web
注意：不要再用 - insert: 手动添加 dsh-notify，否则启动会报
duplicate loader entry id: dsh-notify。想调整配置，在 profile 的
cordis.patch.yml 里按 id 覆盖即可（见下节）。
更新 / 卸载
dsh plugin --profile web update dsh-notify-windows
dsh plugin --profile web remove dsh-notify-windows
更新后需重启 DSH 宿主（新增 bundle 层需要重新启动）。
⚙️ 配置 / Configuration
插件行 config 全字段可选，未填按默认值。需要调整时，在
$DSH_HOME/profiles/web/cordis.patch.yml 里按 id 覆盖主条目即可
（该文件被运行中的 DSH 热监视，改动立即生效，无需重启）：
- id: dsh-notify
name: dsh-notify-windows
config:
enabled: true
reasons: [completed, error, max-tokens]
notifyOnStart: true
notifyOnApproval: true
log: true
| 配置 | 默认值 | 说明 |
|---|
enabled | true | 总开关 |
reasons | [completed, error, max-tokens] | 需要提醒的回合结束原因（可选 aborted / interrupted / blocked） |
locale | zh | toast 文案的内置语言包：zh / en / ru |
messages | {} | 按 key 覆盖文案，优先级高于 locale（见「多语言」） |
includeSubagents | false | 是否也提醒子代理会话 |
notifyOnStart | false | 插件加载时发一条「已激活」通知 |
notifyOnApproval | true | 审批请求提醒（策略 never 时自动跳过） |
notifyOnAskUser | true | Agent 提问等待回答时提醒 |
notifyOnGoalRounds | false | /goal 自动推进回合不提醒（目标完成/阻塞的最终回合除外） |
excerpt | true | 通知正文附带 Agent 最后回复的摘要 |
excerptMaxChars | 80 | 摘要最大字符数 |
appName | DeepSeek Harness | 通知来源显示名与兜底标题 |
aumid | DeepSeekHarness.Notify | 通知 AppUserModelId |
log | true | 写日志到 %TEMP%\dsh-notify\notify.log |
debug | false | 把所有会话事件写入日志（排查用，量大） |
openOnClick | true | 任务完成 / 审批 / 提问 toast 是否可点击（false 回退为旧的无点击 toast） |
preferExisting | true | true 走 launcher 优先聚焦已开 DSH 窗口；false 直接用默认浏览器打开 URL |
webUrl | |
🌐 多语言 / Localization
toast 文案取自内置语言包，由 locale 选择。默认 zh，因此已有安装升级后文案完全不变；
en 与 ru 为完整语言包。任何一条文案都可以用 messages 按 key 覆盖，覆盖优先于语言包：
- id: dsh-notify
name: dsh-notify-windows
config:
locale: ru
messages:
approvalTitle: ' · Требуется одобрение'
turnSuffix: ' — попытка {turn}'
| key | 用途 |
|---|
completed / error / max-tokens / aborted / interrupted / blocked | 回合结束原因行（按 reason.kind 查表） |
turnEnded | 原因在语言包中没有对应条目时的兜底文案 |
turnSuffix | 追加在原因行后的轮次后缀 —— {turn} |
approvalTitle | 审批通知的标题后缀 |
approvalToolWithReason / approvalTool / approvalGeneric | 审批正文 —— {tool} / {reason} |
askTitle | 提问通知的标题后缀 |
askFallback | 提取不到问题文本时的提问正文 |
activated | notifyOnStart 的「已激活」通知 —— {version} |
warnSpawnFailed / warnToastFailed / warnExitCode / warnChannelUnavailable | DSH 日志文案 —— {code}；dsh-notify: 前缀不翻译，保证跨语言可 grep |
说明：{占位符} 由事件数据代入；未知占位符原样保留（不会被清空），非字符串的覆盖值会被忽略，
因此写错不会产生空正文或 [object Object]；未知 locale 回退默认语言包。
审批 / 提问路径的日志行新增 title 与 body 字段（与 notify 行一致），
%TEMP%\dsh-notify\notify.log 因此能直接看到实际发出的文案。
🔔 触发场景 / Triggers
| 场景 | 会话事件 | 通知示例 |
|---|
| 任务完成 | turn/end | 「任务已完成（第 N 轮）」 |
| 任务出错 / 超限 | turn/end | 「任务出错」/「输出达到 token 上限」 |
| 等待审批 | approval/asked | 「DeepSeek Harness · 需要审批 / 工具 pwsh：…」 |
| 等待回答 | tool/call（含 run_code 检测） | 「DeepSeek Harness · 需要回答 / 是否继续？」 |
🔗 点击通知跳转 / Click to Open
任务完成 / 等待审批 / 等待回答的 toast 可点击 → 打开 DSH Web GUI。优先聚焦已打开的
DSH 浏览器标签或 Chrome Application 窗口；没有已开窗口时在默认浏览器新开标签并打开 GUI。
目标 URL 带 ?session=<id> 参数（rc.8 前端暂不消费，为未来深链预留）。
配置：
openOnClick（默认 true，false 则关闭可点击，回退为旧的无点击 toast）；preferExisting（默认 true，true 走 launcher 优先复用已开窗口；false 直接用默认浏览器打开 URL）；webUrl（可选，覆盖自动发现的基地址，如 http://192.168.1.5:4000，留空自动发现 / 默认 http://127.0.0.1:3080）。
注意事项： 首次点击会自动注册 dshnotify:// 协议处理器（HKCU，无需管理员）；故障会静默降级为「默认浏览器打开」。
说明：DSH 0.1.0-rc.8 前端暂不支持按 URL 直达单个会话；点击后打开的是 DSH 界面（首页/会话列表）并聚焦已有窗口，目标会话需在列表中选择。未来 DSH 前端支持深链后 ?session=<id> 将直接定位。
🧩 兼容性 / Compatibility
DSH 0.2.1 起兼容门禁优先读取 engines.dsh。本插件声明 engines.dsh: ">=0.1.5-rc.1"（无上限；旧版 DSH 在未声明该字段时沿用 peer 规则），并已核对：
| DSH 版本 | 状态 |
|---|
| 0.1.5-rc.1 | ✅ 实测通过 |
| 0.1.5-rc.2 | ✅ 实测通过 |
| 0.1.6-alpha.2 | ✅ 实测通过 |
| 0.1.7-rc.1 | ✅ 实测通过 |
| 0.1.7-rc.2 | ✅ 实测通过 |
| 0.2.0-rc.1 | ✅ 实测通过 |
| 0.2.1-rc.1 | ✅ 兼容门禁 + 单测通过 |
| 0.2.1-rc.2 | ✅ 兼容门禁通过 |
只列出实际跑过的版本；未实测的不列。
v0.8.1 支持 DSH 0.1.2-alpha.4+，已在 0.1.5-rc.1 / 0.1.5-rc.2 / 0.1.6-alpha.2 / 0.1.7-rc.1 / 0.1.7-rc.2 / 0.2.0-rc.1 上核对 snapshotEvents() 契约；在 0.2.1-rc.1 上通过兼容门禁与 20 项单测，0.2.1-rc.2 门禁通过。历史读取同时兼容旧版 session.events（DSH ≤ 0.1.2-alpha.3）与新版 snapshotEvents()（DSH 0.1.2-alpha.4 起该属性已不存在），升级到 0.7.5 后摘要 / /goal 轮次 / 审批策略恢复正常。收到过「重启后所有通知静默」问题的请升级到 0.7.3+（见 FAQ）。
0.1.7-rc.1 说明：该版本起 snapshotEvents() 被标记为 @deprecated（"新调用被禁止，现有未迁移逻辑可暂时保留"）。本插件的历史读取属既有逻辑，按官方 Agent Note 的延期口径暂不迁移——DSH 仍在内存保留完整事件序列，通知摘要与 /goal 轮次检查照常工作；待 DSH 提供异步分页读取替代后再迁移。
🛠️ 开发 / Develop
node scripts\smoke-test.mjs
独立进程内用 cordis Context 模拟会话事件：应弹出任务完成 / 审批 / 提问三条测试通知，并断言日志记录与过滤行为（子代理、never 策略、无关调用均被过滤）。
❓ FAQ
- 收不到通知？ 检查 Windows「通知与操作」设置是否允许该应用显示通知，以及「专注助手」是否开启；首次发送会自动注册 AUMID。插件启动时会自检通知通道（
powershell.exe 与 notify.ps1 是否可达），通道不可用会在 DSH 日志中立即告警；每次发送失败也会记录详细原因到 %TEMP%\dsh-notify\notify.log。
- WSL 下收不到通知？ 插件会自动用
wslpath -w 把脚本路径转成 \\wsl.localhost\... UNC 路径，并优先通过 /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe 调用 PowerShell（不依赖 PATH，systemd / cron 等最小环境也能工作）。若仍失败，查看 %TEMP%\dsh-notify\notify.log 中的 error 条目。
- /goal 模式会提醒吗？ 默认不会：自动推进的中间回合保持静默，只有目标完成（或阻塞）的最终回合才提醒；如需每个回合都提醒，把
notifyOnGoalRounds 设为 true。
- 为什么审批提醒有时不弹？ 会话审批策略为
never 时审批会被自动拒绝、不会等待，插件会跳过提醒；策略为 ask 时才提醒。
- 重启 DSH 后所有通知都没了？ 这是 0.7.2 及更早的已知缺陷：子代理判定当时写作
delegationDepth !== undefined，会把每次 dsh web 重启后带 delegationDepth: 0 的主会话误判为子代理并静默过滤。该缺陷已在 0.7.3 修复（判定改为 (delegationDepth ?? 0) > 0）：请把插件升级到 0.7.3 及以上（推荐 0.7.5），执行 dsh plugin --profile web update dsh-notify-windows 后重启 DSH 宿主。
- 通知摘要变空、
/goal 中间回合开始提醒、never 策略仍提醒？ 插件读取的 session.events 属性自 DSH 0.1.2-alpha.4 起就不存在（历史读取改为 snapshotEvents()；0.1.2-alpha.3 及更早才有该属性），0.7.4 及更早读取该属性会拿到 undefined 后静默降级，出现上述三种症状。请升级到 0.7.5 及以上（历史读取已同时兼容两种 API；若升级后 %TEMP%\dsh-notify\notify.log 仍出现 history-unavailable 条目，请附日志反馈）。
- 更新插件代码后如何生效？ 执行
dsh plugin --profile web update dsh-notify-windows 后重启 DSH 宿主。
📄 许可证 / License
MIT © 2026 SeverusZh
