dsh-turn-done-notify

A third-party DeepSeek Harness host-side plugin that pops a Windows notification (+ sound) when a conversation turn finishes.

English · 中文 · 中文说明文档 (README.zh.md)

---

English

What it does

DeepSeek Harness runs in the browser, but there is no built-in "turn done" alert — the only brand-new-completion signal (the sidebar green dot) fires for other sessions, not the one you are watching. This plugin listens to the host-side session/event firehose and, when a top-level conversation turn/end event arrives with reason completed, shows a native Windows tray-balloon notification and plays a system sound. It fires from the host, so it works even when the browser tab is backgrounded, minimised, or closed.

Install

Prerequisite: DeepSeek Harness installed (dsh on PATH) and a web profile already initialized (run dsh web once).

powershell -ExecutionPolicy Bypass -File .\dsh-turn-done-notify\install.ps1

The installer is idempotent (safe to re-run) and:

1. copies the plugin into $DSH_HOME/profiles/node_modules/dsh-turn-done-notify/
2. registers it in $DSH_HOME/profiles/web/cordis.patch.yml

You must fully restart dsh web for the new plugin to load (hot-reload does not import a brand-new plugin):

1. Stop the running dsh web (Ctrl+C in its console, or kill it).
2. Start it again: dsh web
3. Refresh http://127.0.0.1:3080 in the browser.

Configuration

Edit the turn-done-notify block in $DSH_HOME/profiles/web/cordis.patch.yml:

config:
  notifyOn: ['completed']   # turn/end reasons that trigger; add 'error' / 'blocked' / 'max-tokens'
  sound: true               # play the system sound
  onlyTopLevel: true        # only notify top-level sessions (skip subagents)

The balloon title/body default to DeepSeek Harness / 任务已完成; change them in lib/index.js (DEFAULTS). Enable debug: true to write a per-event log to ~/.dsh/turn-done-notify.log.

If you put non-ASCII text in the YAML config, save the file as UTF-8 or you may get mojibake (a GBK-locale gotcha). The safest place for localized text is lib/index.js DEFAULTS (unicode escapes recommended) — which is why the default there uses \u4EFB\u52A1\u5DF2\u5B8C\u6210 for 任务已完成.

Repository layout

dsh-turn-done-notify/
├── package.json      # plugin metadata (type=module)
├── install.ps1       # one-click installer
├── LICENSE           # MIT
└── lib/
    ├── index.js      # plugin body: subscribes to session/event, fires on turn/end
    └── notify.ps1    # PowerShell: tray-balloon + system sound

How it works / gotchas

• session/event is the host-side authoritative "turn finished" signal; turn/end carries a reason.kind.
• The notification shells out with powershell.exe -File notify.ps1 (NOT -Command), using { stdio: 'ignore', windowsHide: true } and never detached: true — detached makes the child "exit successfully" without actually running on some Windows systems (the trickiest bug this plugin hit).
• Reason kinds: completed / aborted / blocked / error / max-tokens / interrupted.

---

中文

功能

DeepSeek Harness 在浏览器里运行，但没有内置的「任务完成」提醒（唯一的完成提示——侧边栏绿点——是针对其他会话的，不是当前正看的这个）。本插件监听宿主侧 session/event 事件流，当顶层会话的 turn/end 事件以 completed 结束时，弹出 Windows 右下角托盘气泡通知并播放系统提示音。通知在宿主机触发，因此即使浏览器标签页在后台、最小化或已关闭，也能收到提醒。

安装

前提：已安装 DeepSeek Harness（dsh 在 PATH）且运行过一次 dsh web（已初始化 web profile）。

powershell -ExecutionPolicy Bypass -File .\dsh-turn-done-notify\install.ps1

安装脚本幂等（可重复运行），会：

1. 把插件复制到 $DSH_HOME/profiles/node_modules/dsh-turn-done-notify/
2. 向 $DSH_HOME/profiles/web/cordis.patch.yml 登记插件

安装后必须完全重启 dsh web（热加载不会导入全新插件）：

1. 停掉正在运行的 dsh web
2. 重新运行 dsh web
3. 浏览器刷新 http://127.0.0.1:3080

配置

编辑 $DSH_HOME/profiles/web/cordis.patch.yml 里的 turn-done-notify 段：

config:
  notifyOn: ['completed']   # 触发的 turn/end 原因；可加 'error' / 'blocked' / 'max-tokens'
  sound: true               # 是否播放提示音
  onlyTopLevel: true        # 只提醒顶层会话（跳过子代理）

气泡标题/正文默认 DeepSeek Harness / 任务已完成，改 lib/index.js 里的 DEFAULTS。设 debug: true 可把逐事件日志写到 ~/.dsh/turn-done-notify.log。

YAML 里写中文需以 UTF-8 保存，否则可能乱码；最稳妥是改 lib/index.js 的 DEFAULTS（推荐 unicode 转义——默认就用 \u4EFB\u52A1\u5DF2\u5B8C\u6210 表示「任务已完成」）。

目录结构

dsh-turn-done-notify/
├── package.json      # 插件元信息
├── install.ps1       # 一键安装脚本
├── LICENSE           # MIT
└── lib/
    ├── index.js      # 插件主体：监听 session/event，turn/end 时触发
    └── notify.ps1    # PowerShell：托盘气泡 + 系统提示音

原理 / 踩坑记录

• session/event 是宿主侧权威的「回合结束」信号；turn/end 带 reason.kind。
• 通知用 powershell.exe -File notify.ps1（不要用 -Command），spawn 选项用 { stdio: 'ignore', windowsHide: true }，绝不加 detached: true（detached 会让子进程「假退出却不执行」，是本插件踩过最隐蔽的坑）。
• 结束原因：completed / aborted / blocked / error / max-tokens / interrupted。

---

License

MIT — see LICENSE.