ds-notify-plugin

ds-notify-plugin

Windows desktop toast notifications for DeepSeek Harness (dsh). Pops a native
Windows toast (bottom-right banner) whenever the main conversation finishes a
turn, so you can look away while a long reply is being generated.

DeepSeek Harness（dsh）主对话完成通知插件：主对话每轮完成后，用 Windows 系统
toast（右下角通知横幅）提醒你。

Features · 功能

• Windows only · 仅 Windows — on other platforms the plugin is a no-op.
  非 Windows 平台自动不生效。
• Main conversation only · 仅主对话 — toasts only when a root (main
  conversation) agent finishes a turn; subagents and workflow agents don't
  trigger it. 只有主对话完成时通知；子代理、工作流 agent 完成不打扰。
• Conversation title in the toast · 通知带对话标题 — the toast names the
  conversation that finished (its auto-generated or user-renamed title), so
  you know at a glance which one it is; a conversation without a title yet
  keeps the original fixed text. 通知会写明是哪个对话完成（自动生成或手动
  重命名的标题），一眼可知；尚无标题的对话保留原有固定文案。
• Debounced · 防抖合并 — completion signals within 1.5 s are merged into one
  toast. 1.5 秒内的连续完成信号合并为一条通知。
• Zero dependencies · 零依赖 — drives the built-in powershell.exe + WinRT
  ToastNotificationManager; nothing to install. 调用 Windows 自带的 PowerShell +
  WinRT，不装任何第三方模块。
• No dsh files modified · 不修改 dsh 安装文件 — upgrades of dsh won't
  overwrite or break it. 升级 dsh 不受影响。

Requirements · 前置条件

• Windows 10 / 11 (uses the built-in powershell.exe)
• DeepSeek Harness (dsh)
• pnpm on PATH (pnpm --version must work)
• GitHub route only · 仅 GitHub 安装方式: git on PATH (pnpm clones the repo
  automatically)

Install · 安装

This plugin ships as a bundle (dsh.bundle.patch pointing to an in-package
cordis.patch.yml). dsh plugin appends it to the profile's
dsh.profile.bundles automatically — no manual composition edits on the
receiving side, and nothing to download or copy by hand: one command fetches
and installs the package. 无需手动下载或复制文件，一条命令即可安装。

After installing, restart dsh. The plugin then loads automatically on every
start, with no approval required. 安装后重启 dsh，之后每次启动自动加载。

From npm · 从 npm 安装（推荐）

dsh plugin --profile web add ds-notify-plugin

From GitHub · 从 GitHub 安装

dsh plugin --profile web add github:JohnWes7/ds-notify-plugin

The plugin has zero dependencies and no build step, so nothing needs to be
allowed in the receiving side's pnpm-workspace.yaml. 插件零依赖、无构建
脚本，接收方无需放行任何构建。

Local directory · 本地目录（开发 / 离线）

1. Put this directory in a stable location.

2. From its parent directory, run:

   cd D:\dsh\plugin
   dsh plugin --profile web add link:./ds-notify-plugin
   

   • link: creates a symlink so code edits take effect immediately
     (recommended while developing);
   • file:./ds-notify-plugin copies the directory instead.

To install into another profile, replace web with that profile's name in
any of the commands above. 把上面命令里的 web 换成目标 profile 名即可装到
其他 profile。

Uninstall · 卸载

dsh plugin --profile web remove ds-notify-plugin

Restart dsh afterwards.

How it works · 工作原理

1. The plugin listens for the agent/status event (broadcast up to the root
   context).
2. On idle — a turn finished, covering normal completion, errors, and
   interruption — it checks agents.roots() and ignores subagents.
3. A 1.5 s debounce merges burst signals, then the conversation title is read
   from the session log via the sessionTitle service (latest session/title
   event; the toast falls back to fixed text when there is none yet).
4. It spawns powershell.exe (hidden window, stdio: 'ignore') to show a
   WinRT toast via ToastNotificationManager, with the title XML-escaped
   into the body line.
5. The toast uses the registered "Windows PowerShell" AUMID so a non-packaged
   process can display toasts reliably.

FAQ · 常见问题

• No toast after a turn completes · 对话完成后没弹通知
  1. Windows Focus Assist / Do Not Disturb silently drops toasts — turn it off.
     检查"专注助手 / 勿扰模式"，开着会吞掉 toast。
  2. Check whether notifications for the "Windows PowerShell" app are disabled
     in Windows notification settings. 检查 Windows 通知设置里 "Windows
     PowerShell" 应用的通知是否被禁用。
  3. Confirm the profile's dsh.profile.bundles contains ds-notify-plugin
     and dsh was restarted. 确认 profile 的 bundles 列表包含本插件且已重启 dsh。
• The toast source shows "Windows PowerShell" · 通知来源显示为 Windows
  PowerShell — intentional: the plugin borrows PowerShell's registered
  shortcut identity (AUMID) so toasts display reliably from a non-packaged
  process. 这是有意为之（借用 PowerShell 的快捷方式身份让非打包进程的 toast
  可靠显示），属正常现象。
• The toast has no conversation title · 通知里没有对话标题 — a brand-new
  conversation may not have a title committed yet when its first turn ends;
  the toast then keeps the original fixed text. If an older conversation's
  toast is still titleless, check %TEMP%\ds-notify-plugin.log: every toast
  decision is appended there as one JSON line (service/session presence and
  the resolved title; the file self-caps at 64 KiB, dropping the oldest half).
  全新对话在首轮结束时可能还没生成标题，此时保留原固定文案；若旧对话的通知
  仍无标题，查看 %TEMP%\ds-notify-plugin.log，每次通知决策都会追加一行 JSON
  （服务/会话是否存在、解析出的标题；文件上限 64 KiB，超出时自动丢弃最旧的一半）。

Development · 开发

See docs/DEVELOPMENT.md for architecture rationale,
pitfalls, and the testing history.