ds-notify-plugin

Readme

# 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（右下角通知横幅）提醒你。

[![npm version](https://img.shields.io/npm/v/ds-notify-plugin)](https://www.npmjs.com/package/ds-notify-plugin)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 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](https://www.deepseek.com) (`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 安装（推荐）

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

### From GitHub · 从 GitHub 安装

```powershell
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:

   ```powershell
   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 · 卸载

```powershell
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.
4. 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](docs/DEVELOPMENT.md) for architecture rationale,
pitfalls, and the testing history.