会话完成通知 LeeeWM/dsh-session-toast

dsh-session-toast

DSH 宿主侧插件：每当一轮会话回复结束，在 Windows 11 右下角弹出系统通知，作用类似 Claude Code / Codex 的完成提示。默认只有 DSH 不在前台时才提示，避免盯着屏幕时被打扰。

为什么需要它

长任务跑起来以后，人通常会切到别的应用；DSH 这一轮结束、等你下一步输入时，没有任何提示。这个插件把 DSH 的 turn/end 事件变成一条 Windows 原生通知，带上会话标题、用时和轮次。

- 零运行时依赖：没有 npm 依赖、不需要 BurntToast、不写注册表。
- 不打扰：DSH 在前台时自动跳过。
- 不刷屏：1.2 秒去抖，下一轮 turn/start 会取消上一条待发通知。
- 不炸子代理：默认忽略 subagent 会话。
- 生命周期干净：定时器/子进程都由 ctx.effect 清理。

特性

| 能力 | 行为 |
| 完成通知 | 监听 session/event → turn/end；默认 completed 与 error |
| 标题 | 取 session/title；没有标题时退回工作目录名 |
| 正文 | 会话标题 · 用时 · 第 N 轮；出错时显示错误摘要 |
| 前台策略 | 前台窗口属于 DeepSeek Harness 时不弹 |
| 去抖 | 1.2 秒；期间收到 turn/start 则取消 |
| 子代理 | 默认不通知；notifySubagents: true 打开 |
| 原生 Toast | WinRT ToastNotificationManager；不可用时降级 NotifyIcon 气泡 |
| 中文安全 | payload 用 base64(UTF-8 JSON)；中文/emoji 不经过代码页 |
| 配置 | 15 个可选键，见配置 |

兼容性

| 项 | 值 |
| DSH | 0.2.1-rc.3（实测；dsh.compatibility 已声明） |
| 系统 | Windows 11；依赖自带的 Windows PowerShell 5.1 |
| Node | 20+（DSH 自带运行时） |
| 其他平台 | 插件自动不激活 |

安装

⚠️ 请只按 dsh-session-toast 这个名字安装。npm 上的 dsh-session-notifier 属于另一位作者，与本项目无关。

从 GitHub 安装（非桌面 profile，推荐）

dsh plugin --profile <profile> add github:LeeeWM/dsh-session-toast
dsh --profile <profile> --dump-config | Select-String "dsh-session-toast"

适用于 web / headless / tui 等非 desktop profile。

桌面端

Desktop profile 由 Electron 独占管理，CLI 会拒绝安装。请走 UI：

1. git clone https://github.com/LeeeWM/dsh-session-toast.git
2. Plugins → Add plugin → Install a third-party plugin；
3. 填克隆目录的绝对路径 → Install → Enable now。

如果你的 Plugins UI 支持直接填 GitHub 包名，也可以尝试 github:LeeeWM/dsh-session-toast；本仓库文档以“目录安装”为准。

本地开发

桌面端：Plugins → Add plugin → 第三方插件 → 填插件目录绝对路径非桌面 profile：
dsh plugin --profile <profile> add "C:\path\to\dsh-session-toast"

本地目录是 link: 安装：改完 index.js / notify.ps1 后，需要禁用再启用插件（或重启 DSH）才加载新模块。

名字变更（v0.2.0）：0.1.x 叫 dsh-session-notifier，但 npm 上这个名字已被另一位作者的包占用（那是一个 Web 客户端 + WSL 通知插件，与本项目无关），按名安装会装错。从 v0.2.0 起，包名、插件行 id、GitHub 仓库统一为 dsh-session-toast。升级步骤：

1. 在 Plugins 里 Remove 旧的 dsh-session-notifier（包括按名字误装的 npm 1.x）；
2. 按上面的方式重新安装 dsh-session-toast；
3. 点 Install → Enable now，并用 --dump-config 确认输出里有 # == dsh-session-toast。

配置

config 全部可选；省略即使用默认值。整行替换：覆盖时把需要的键写全。

| 键 | 默认 | 说明 |
| enabled | true | 总开关；false 时插件不注册任何监听 |
| notifyOn | 'completed-and-error' | 'completed' / 'completed-and-error' / 'all'（含 aborted、blocked、max-tokens） |
| onlyWhenUnfocused | true | DSH 在前台时不弹 |
| sound | true | 播放系统通知音（Toast 的 ；balloon 用 SystemSounds） |
| language | 'zh' | 内置文案语言：'zh' / 'en' |
| debounceMs | 1200 | 去抖窗口；期间收到 turn/start 则取消 |
| minTurnDurationMs | 0 | 短于该时长的轮次不通知 |
| notifySubagents | false | 是否也通知子代理会话 |
| dshProcessNames | ['DeepSeek Harness'] | 判定「DSH 在前台」的进程名（不区分大小写，可写多个） |
| mode | 'auto' | 'auto' / 'toast' / 'balloon' |
| aumid | '' | 已注册的 AppUserModelID；默认借用 Windows PowerShell 的 AUMID |
| logFile | '' | notify.ps1 的诊断日志路径（UTF-8）；排查「没弹」时打开 |
| timeoutMs | 20000 | 通知进程超时被杀 |
| dryRun | false | 只把 payload 打到控制台，不弹通知（测试用） |
| appName | 'DeepSeek Harness' | 通知里的归属名称 |

自定义配置

插件行的默认配置由 bundle 层提供。要改配置，在 机器级用户层 $DSH_HOME/cordis.patch.yml（本机 C:\Users\Lenovo\.dsh\cordis.patch.yml）追加一行整行覆盖，例如：

- id: dsh-session-toast
name: dsh-session-toast
config:
enabled: true
notifyOn: completed-and-error
onlyWhenUnfocused: false
sound: true
language: zh
debounceMs: 800
notifySubagents: false
mode: auto
logFile: 'C:\Users\Lenovo\.dsh\logs\dsh-session-toast.log'

不要在 ~/.dsh/profiles/desktop/ 里手改 package.json / cordis.patch.yml（桌面 profile 由 Electron 独占管理）。临时调试可用 dsh --profile <test> --patch <overlay.yml>。

工作原理

DSH session ──turn/start──▶ 记录开始时间，取消待发通知 ──session/title▶ 缓存会话标题 ──turn/end────▶ 过滤（子代理 / reason / 最短时长） └─ 1.2s 去抖 └─ spawn powershell.exe notify.ps1 ├─ 前台是 DSH？→ 跳过 └─ WinRT Toast → 失败则 balloon

- 事件 API：ctx.on('session/event', (session, event) => …)（与官方 dsh-session-persistence-jsonl 相同的监听方式）。
- 通知投递：notify.ps1 由 Windows PowerShell 5.1 执行；payload 用 base64(UTF-8 JSON) 通过 argv 传入，中文/emoji 不经过代码页。
- 本插件不 import 任何 @deepseek-ai/* 包，只用 Node 内置模块，因此本地 link: 安装不依赖 DSH 安装目录的模块解析。

文件

| 文件 | 作用 |
| index.js | 宿主插件入口：配置、事件监听、去抖、调用通知脚本 |
| notify.ps1 | Windows 通知投递：前台检测、WinRT Toast、balloon 兜底、退出码 |
| cordis.patch.yml | 插入插件行（id: dsh-session-toast，name 与包名一致） |
| package.json | dsh.bundle.patch、dsh.compatibility、files 白名单、脚本 |
| locale/{zh,en}.json | Plugins 页标题/描述 |
| icon.svg / assets/icon-180.png | 插件图标（SVG 源文件；180px 位图用于市场卡片） |
| test/mock-apply.mjs | 离线 mock 宿主测试（不弹通知） |
| test/live-smoke.mjs | 真实弹一条通知的联调脚本 |
| README.md / README.en.md | 中文 / English 文档 |
| CHANGELOG.md / SECURITY.md / LICENSE | 变更记录 / 安全策略 / MIT 许可 |

开发与验证

npm run check # node --check index.js
npm test # 10 个离线 mock 宿主检查
npm run test:live # 真实弹一条通知

静态检查：
node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log('json ok')"

PowerShell 语法（Windows PowerShell 5.1） $t=$null;$e=$null
[void][System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path 'notify.ps1').Path,[ref]$t,[ref]$e)
"ps errors: $($e.Count)"

mock 覆盖：监听注册、禁用、标题/时长/轮次、去抖取消、子代理过滤、notifyOn、重复 turn/end、目录名回退、异步标题刷新、卸载清理。

用一次性配置档做真实加载验证

dsh --profile notifier-test --from-default-profile headless --dump-config
dsh plugin --profile notifier-test add "C:\path\to\dsh-session-toast"
dsh --profile notifier-test --dump-config # 出现 "# == dsh-session-toast"
dsh plugin --profile notifier-test remove dsh-session-toast

排查

| 现象 | 处理 |
| 装好了但完全没通知（先查这条） | 确认插件真的启用了：dsh --profile <profile> --dump-config 的输出里应有 # == dsh-session-toast 这一层；桌面端 Plugins 页应显示 Enabled。只在 package.json 依赖里、dsh.profile.bundles 里没有这一行时，插件不会被加载，也不会产生任何通知 |
| 完全没通知 | 看 Windows 设置 → 系统 → 通知 是否关闭 / 勿扰；先设 onlyWhenUnfocused: false；再设 logFile 看 notify.ps1 日志 |
| DSH 在前台时不弹 | 这是默认行为；要始终提示就设 onlyWhenUnfocused: false |
| 来源标签显示 “Windows PowerShell” | Toast 借用的是系统已注册的 PowerShell AUMID；如需自定义，注册 AppUserModelID 后填 aumid（非微软文档保证行为） |
| 子代理任务不弹 | 默认 notifySubagents: false；需要时打开（可能一次任务弹多条） |
| 通知太多 | 调大 minTurnDurationMs / debounceMs，或 notifyOn: 'completed' |
| 想看插件是否加载 | 启动日志出现 [dsh-session-toast] loaded (…) |

调试时设置环境变量 DSH_SESSION_TOAST_DEBUG=1（0.1.x 的 DSH_SESSION_NOTIFIER_DEBUG=1 仍兼容）：DSH 控制台会打印每条 turn/end 的去向（入队，或被哪条规则跳过）、实际 payload、PowerShell PID，并把 notify.ps1 的 DELIVERED / SKIPPED reason=… 透传出来 —— 这是判断“到底是没加载、被过滤、还是被前台策略跳过”的最快方式。

已知限制

- 仅 Windows（process.platform === 'win32'），其他平台插件自动不激活。
- 通知依赖 Windows PowerShell 5.1（Win11 自带）；无 pwsh、无 BurntToast 也能用。
- 勿扰 / 通知总开关关闭时，Toast 可能被系统静默丢弃，脚本无法检测；可用 mode: 'balloon' 换通道。
- Toast 约 5 秒后自动消失；不实现点击跳转/聚焦 DSH。
- 通知正文包含会话标题（本地显示，不联网）。
- 子代理默认不通知；多会话并行时按会话分别通知。
- 使用 session/title 作为标题；若会话从未生成标题，则退回目录名。
- goal / 自动续跑：去抖只覆盖 1.2 秒内立刻开始的下一轮；goal 续跑如果先 await session/flush 或等待子代理超过该窗口，会先提示“完成”再继续跑。DSH 目前没有公开的 “session idle” 事件（最接近的是 agent/status === 'idle'），本插件未用 agent/status 做门控；如需更严格可调大 debounceMs 或暂时关闭 goal。

安全

- 插件只读取 session/title、session/header.cwd、turn/end、session/disposed 事件。
- 只启动本地 powershell.exe（-NoProfile -NonInteractive -WindowStyle Hidden），不联网、不读取凭据、不做 shell 字符串拼接（参数走数组传递）。
- 运行时不需要 GitHub token 或任何账号数据；可选的 logFile 只包含通知文案。
- 漏洞报告见 SECURITY.md。

卸载

桌面端：Plugins → dsh-session-toast → Remove。

非桌面配置档：

dsh plugin --profile <profile> remove dsh-session-toast
dsh --profile <profile> --dump-config | Select-String "dsh-session-toast"

License

MIT © 2026 LeeeWM