交互提醒 waterc07/dsh-interaction-notify

dsh-interaction-notify

DeepSeek Harness 交互提醒：智能体停下来等你时，弹 Windows 系统通知、响一声提示音，点通知回到 DeepSeek Harness 窗口。

后台跑长任务时不必一直盯着窗口：要你回答、要你授权工具、要你批准计划的时候，会有一条系统通知 + 提示音把你叫回来。这是 host-only 的 DSH 插件：没有浏览器半，也不注入任何页面脚本，系统通知与窗口激活都由宿主进程完成。

功能特性

一次触发最多产生三个可感知的信号：

| 信号 | 说明 |
| 系统通知（Toast） | 出现在 Windows 通知中心，应用身份为「DeepSeek Harness 提示」（由开始菜单快捷方式注册）；标题/正文就是当前要你处理的内容 |
| 提示音 | 默认播放内置的 assets/notify.wav（C5→E5 双击音，默认音量 55）；可切换为 Windows 系统音或静音 |
| 任务栏闪烁 | 让 DSH 主窗口在任务栏闪 5 次，作为不打断当前操作的第三重提示 |

其它行为：

- 同一交互只提醒一次：按审批 id 或工具 callId 去重（内存中保留最近 200 个 id）。
- 防刷屏：非审批类通知受 minIntervalMs（默认 1200ms）最小间隔限制，间隔内的新提醒直接丢弃、不排队；审批请求永不节流（安全相关，只去重）。
- 不打扰正在看的你：默认 quietWhenFocused: true，DSH 已经在前台时整条提醒（含声音）都会跳过，日志记为 skipped: focused。
- 内容克制：通知只包含一句标题 + 一句话摘要（问题/工具名/reason），不包含完整会话内容，也不上传任何数据。
- 配置可热更新：通过本机 HTTP 路由修改后立即生效，无需重启。
- 无第三方依赖：插件只用 Node.js 内置模块 + Windows PowerShell 5.1。

三种触发场景

| 场景 | 宿主事件 | 通知标题 | 通知正文 |
| 提问 | tool/call，工具名为 ask_user_question | 需要你的回答 | 第一个问题（去除换行、截断 140 字）；多个问题时追加 （共 N 个问题）；没有问题时为 请打开对话回答问题 |
| 授权审批 | approval/asked | 需要你的批准 | 工具「<toolName>」需要你授权；有 reason 时追加 ：<reason>（截断 120 字） |
| 计划批准 | tool/call，工具名为 exit_plan_mode | 计划已就绪，等待你的批准 | 点击查看计划并批准，或给出修改意见 |

三类可分别用配置里的 events.question / events.approval / events.plan 单独关闭。

前置条件

- Windows 10 / 11（依赖 Toast 通知、开始菜单 AppUserModelID、user32 窗口 API）。
- DeepSeek Harness 桌面端（由宿主进程加载 Cordis 插件）。本插件没有浏览器半，package.json 里也没有 dsh.client。
- Windows PowerShell 5.1（%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe）。notify.ps1 使用 WinRT 的 Windows.UI.Notifications 类型，PowerShell 7（pwsh）无法加载，因此固定调用 5.1。
- 通知权限：Windows 设置 → 系统 → 通知，确认总开关打开，并允许「DeepSeek Harness 提示」（回退到 PowerShell 身份时还需允许 Windows PowerShell）。无需修改全局 PowerShell 执行策略——插件调用脚本时自带 -ExecutionPolicy Bypass。
- Node.js（仅构建/测试与安装脚本使用；运行时由 DSH 自带的 Node 执行插件）。本项目在 Node.js v25.9.0 上验证，建议使用较新的 LTS 版本（22+）。

安装

插件需要 lib/ 加载产物、profile 依赖声明、node_modules 软链接，以及注册通知身份的开始菜单快捷方式。推荐用仓库自带的 scripts/install.mjs 一次完成。

方式一：使用安装脚本（推荐）

先在 PowerShell 里确定 DSH 家目录（未设置 $env:DSH_HOME 时默认为 $env:USERPROFILE\.dsh）：

$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE '.dsh' }
$pluginDir = Join-Path $dshHome 'plugins\dsh-interaction-notify'
New-Item -ItemType Directory -Force -Path (Join-Path $dshHome 'plugins') | Out-Null

从 GitHub 克隆（也可下载 zip 解压到该目录）
git clone https://github.com/waterc07/dsh-interaction-notify.git $pluginDir
Set-Location $pluginDir

1) 先预览会改什么：不写任何文件
node scripts\install.mjs --profile desktop --dry-run

2) 正式安装（幂等，重复运行只补缺失项）
node scripts\install.mjs --profile desktop

install.mjs 会做四件事：

1. 在目标 profile 的 package.json 里写入依赖 "dsh-interaction-notify": "link:../../plugins/dsh-interaction-notify"；
2. 把 dsh-interaction-notify 追加到 dsh.profile.bundles（最高优先级层）；
3. 建立 node_modules\dsh-interaction-notify junction，让 profile 不执行 pnpm install 也能解析到插件；
4. 调用 scripts/setup-shortcut.ps1 创建带 AppUserModelID 的开始菜单快捷方式（点击通知回到窗口依赖它）。

要点：

- 写 profile 清单前会先生成一份带时间戳的备份（package.json.bak-dsh-interaction-notify-<时间戳>）。
- 脚本不会写入 DSH 安装目录：exe 解析顺序为 --exe > $env:DSH_EXE / 常见安装位置 > 正在运行的 DeepSeek Harness 进程 > 开始菜单快捷方式。找不到时用 --exe 指定：

node scripts\install.mjs --profile desktop --exe "<DSH 安装目录>\DeepSeek Harness.exe"

- 快捷方式步骤是「尽力而为」：setup-shortcut.ps1 缺失或失败只打印警告、不中断安装；但点击回窗口会失效，补跑即可。
- 其它参数：--profile <名称>（默认 desktop）、--dry-run、--uninstall、--help。
- profile 必须已经存在（先启动过一次 DSH 桌面端）；否则脚本会提示先启动一次。

方式二：手动注册（不使用安装脚本）

1. 把仓库克隆/解压到 $dshHome\plugins\dsh-interaction-notify。
2. 编辑 profile 清单 $dshHome\profiles\<profile>\package.json：

{
"dependencies": {
"dsh-interaction-notify": "link:../../plugins/dsh-interaction-notify"
},
"dsh": {
"profile": {
"bundles": ["dsh-interaction-notify"]
}
}
}

已有 dependencies / bundles 时按同样格式追加，不要覆盖原有条目。
3. 建立 junction（profile 的 node_modules 不存在时先创建）：

$profileDir = Join-Path $dshHome 'profiles\desktop'
New-Item -ItemType Directory -Force -Path (Join-Path $profileDir 'node_modules') | Out-Null
cmd /c mklink /J "$profileDir\node_modules\dsh-interaction-notify" $pluginDir

4. 创建开始菜单快捷方式（注册通知身份 + 点击回调）：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\setup-shortcut.ps1
-Action install -ExePath "<DSH 安装目录>\DeepSeek Harness.exe" -PluginRoot "$pluginDir"

5. 完全退出并重新打开 DSH（见下节）。

安装/升级后必须重启

profile 与 bundle 列表只在 DSH 启动时读取，因此安装、升级、卸载后都要完全退出并重新打开 DeepSeek Harness；刷新页面不算。

重启后自检：调用一次测试通知（见下一节）能弹通知 + 响铃，说明宿主半已加载。

使用与配置

触发是自动的：智能体调起提问 / 授权 / 计划批准时就会提醒。若想验证安装，可主动发一条测试通知。

配置文件与默认值

设置持久化在 $DSH_HOME\dsh-interaction-notify\state.json（默认 $DSH_HOME 为 $env:USERPROFILE\.dsh），原子写入、权限 0600；文件缺失或损坏时自动回退默认值。

| 字段 | 取值 | 默认 | 说明 |
| enabled | true / false | true | 总开关；false 时任何事件都不投递 |
| events.question | true / false | true | 是否在 ask_user_question 时提醒 |
| events.approval | true / false | true | 是否在审批请求时提醒（只去重，不受最小间隔限制） |
| events.plan | true / false | true | 是否在 exit_plan_mode 计划批准时提醒 |
| sound | "chime" / "system" / "silent" | "chime" | 内置音效 / Windows 提示音 / 静音（静音仍会弹通知） |
| volume | 0–100 的整数 | 55 | 内置音效的播放音量 |
| quietWhenFocused | true / false | true | DSH 已在前台时不打扰（整条提醒跳过，日志记 skipped: focused）；POST /test 不受此限 |
| clickToReturn | true / false | true | 是否在通知上显示「回到 DeepSeek Harness」按钮；关闭后不显示该按钮，通知与声音不受影响 |
| minIntervalMs | 毫秒数，≥ 0 | 1200 | 非审批类通知的最小间隔；间隔内的新通知直接丢弃、不排队。审批类永不节流 |

POST /set 只改请求里出现的字段（深合并），未提及的字段保持原值；非法值回退默认。用 POST /set 修改立即生效；如果直接用编辑器改 state.json，需要重启 DSH 才生效（运行中的实例只在启动时读取一次，之后用 /set 写回时也会以内存中的值为准）。

环境变量

| 变量 | 用途 |
| DSH_HOME | DSH 家目录；决定插件数据目录、profile 位置，未设置时为 $env:USERPROFILE\.dsh |
| DSH_EXE | scripts/install.mjs 自动解析用的桌面端 exe 路径（可用 --exe 覆盖） |
| DSH_INSTALL_ROOT | scripts/install.mjs 的只读保护目录（默认由解析到的 exe 所在目录推导），防止脚本写入 DSH 安装目录 |

如何关闭提醒

- 临时全部关闭：POST /set 传 { "enabled": false }（立即生效，无需重启）。
- 只关某一类：{ "events": { "plan": false } }。
- 只要声音关掉、通知保留：{ "sound": "silent" }。
- 完全移除插件：用 install.mjs --uninstall（见下文）。

HTTP 接口（改配置 / 测试 / 看日志）

宿主注册了以下路由，全部只接受本机 loopback + 同源请求（否则 403），无需鉴权头，PowerShell 直接调用即可。请求体上限 256 KiB。

| 路由 | 方法 | 说明 |
| /api/dsh-interaction-notify/state | GET | { config, platform, rev, stats } |
| /api/dsh-interaction-notify/set | POST | 部分配置 → { config, rev } |
| /api/dsh-interaction-notify/test | POST | 立即投递测试通知 { title?, body?, kind?, sound?, volume? } → { ok, code?, error?, stats }（绕过静默/去重/节流，仍尊重 sound） |
| /api/dsh-interaction-notify/log | GET | { lines: [...] } 最近 200 行通知尝试日志 |
| /api/dsh-interaction-notify/diag | POST | { name, payload } → 落盘 diag\<name>.json，返回 { ok, path }（文件名会被清洗） |

桌面端的 Web 服务使用随机端口且只监听 127.0.0.1，不要写死端口。最方便的办法是在 DSH 窗口内打开开发者工具执行 location.origin，得到形如 http://127.0.0.1:<port> 的值；用 dsh web 命令启动时 stdout 也会打印服务地址。

$base = 'http://127.0.0.1:<port>' # 换成上一步得到的 origin

当前配置、平台、统计 Invoke-RestMethod "$base/api/dsh-interaction-notify/state" | ConvertTo-Json -Depth 6

改配置（只传要改的字段） Invoke-RestMethod "$base/api/dsh-interaction-notify/set" -Method Post -ContentType 'application/json'
-Body (@{ sound = 'system'; volume = 70; quietWhenFocused = $false } | ConvertTo-Json)

只关掉「计划批准」这一类提醒 Invoke-RestMethod "$base/api/dsh-interaction-notify/set" -Method Post -ContentType 'application/json'
-Body (@{ events = @{ plan = $false } } | ConvertTo-Json)

立即弹一条测试通知（会真的响） Invoke-RestMethod "$base/api/dsh-interaction-notify/test" -Method Post -ContentType 'application/json'
-Body (@{ title = '测试'; body = '来自 dsh-interaction-notify'; kind = 'test' } | ConvertTo-Json)

看最近的通知尝试日志 (Invoke-RestMethod "$base/api/dsh-interaction-notify/log").lines

卸载

在插件目录下执行：

node scripts\install.mjs --profile desktop --uninstall

卸载会移除：依赖声明、dsh.profile.bundles 条目、node_modules junction、开始菜单快捷方式（%APPDATA%\Microsoft\Windows\Start Menu\Programs\DeepSeek Harness 提示.lnk）。state.json、日志与插件目录默认保留；需要彻底清理时手动删除 $DSH_HOME\dsh-interaction-notify\ 和插件目录。

工作原理

宿主监听

插件是标准的 Cordis 宿主插件：export const inject = ['webServer']，在 apply(ctx) 里用 ctx.effect(...) 一次性注册 HTTP 路由，并订阅根上下文的 session/event：

ctx.on('session/event', (session, event) => notifier.handleEvent(session, event))

session/event 在根上下文注册可收到全部会话的已提交事件。检测层（src/detection.js）是纯函数，只认三种事件：

- approval/asked → approval；
- tool/call 且 data.name === 'ask_user_question' → question；
- tool/call 且 data.name === 'exit_plan_mode' → plan。

其它事件、缺字段或脏数据一律返回 null，绝不抛错。

通知投递

src/notifier.js 负责去重、节流、按 events. 过滤、统计与写尝试日志，然后调用 src/deliver.js。deliver 运行在 DeepSeek Harness.exe 的 Node 环境里，没有 Electron 通知 API，因此：

1. 把标题/正文/声音/音量等写成一个临时 JSON payload（放在 $DSH_HOME\dsh-interaction-notify\tmp\，用完即删）；
2. 启动 %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File assets\notify.ps1 -PayloadFile <payload>；
3. 单次投递硬超时 25 秒，失败只记日志与统计，绝不影响产生事件的会话；非 Windows 平台直接返回 { ok: false, skipped: 'unsupported-platform' }。

assets/notify.ps1 负责整个可见侧：

- Toast：通过 WinRT ToastNotificationManager 弹出，通知音被显式静音（），避免和自定义声音重复；有「回到 DeepSeek Harness」按钮（clickToReturn 时）。
- 声音：chime 用 WPF MediaPlayer 播放 assets/notify.wav，volume 映射为播放器音量（不可用时回退 SoundPlayer）；system 播放 SystemSounds.Asterisk；silent 不发声。
- 任务栏闪烁：找到进程名为 DeepSeek Harness 的主窗口，调用 FlashWindowEx 闪 5 次。

点击通知回到窗口

Windows 只把前台权限交给「被点击的那个进程」，所以点击路径是：

点击通知 / 通知按钮 → 与 AppUserModelID（com.deepseek.harness.notify）关联的开始菜单快捷方式 → wscript.exe 隐藏启动 assets/activate.vbs → assets/activate.ps1：找到已存在的 DSH 主窗口
· 已在前台且未最小化 → 什么都不做
· 最小化 / 被隐藏 → ShowWindow 恢复 + SetForegroundWindow 置前（前台锁拒绝时用 AttachThreadInput + 合成 Alt 键兜底）
· 应用已完全退出 → 用快捷方式里记录的 exe 路径重新启动

这也是为什么不能靠「重新拉起一个 exe 进程再 window.focus()」：第二个进程拿到前台权限后立刻退出，原进程的聚焦会被 Windows 前台锁拦掉。快捷方式由 scripts/setup-shortcut.ps1 创建，install.mjs 会调用它。

如果开始菜单快捷方式缺失，notify.ps1 会回退到 Windows PowerShell 自己的身份：通知可能仍然弹出，但点击不会回到 DSH；如果快捷方式存在但 AppUserModelID 写入失败，通知可能完全不显示。这两种情况都可以重跑安装脚本或 setup-shortcut.ps1 修复。

设置、统计与日志

- 设置：$DSH_HOME\dsh-interaction-notify\state.json（原子写，0600）。
- 统计：内存中的 attempted / delivered / skipped / failed / lastAt / lastError，可通过 GET /state 读取。
- 尝试日志：$DSH_HOME\dsh-interaction-notify\notifications.log，每次尝试一行 JSON（{t, kind, id, ok, code?, skipped?, error?}）；超过 400 行时压缩为最近 200 行；GET /log 返回最近的 200 行。
- 诊断转储：POST /diag 写到 $DSH_HOME\dsh-interaction-notify\diag\<name>.json。

目录结构

dsh-interaction-notify/
├─ package.json 插件清单（宿主半；无 dsh.client） ├─ cordis.patch.yml 插入 profile 的 bundle 补丁 ├─ CONTRACT.md 模块接口与行为契约（设计文档） ├─ README.md 本文件 ├─ LICENSE MIT ├─ .gitignore ├─ src/ 源码 │ ├─ index.js Cordis 入口：事件监听 + HTTP 路由 │ ├─ detection.js 纯函数：会话事件 → 交互描述 │ ├─ notifier.js 去重/节流/统计/日志 → 调用 deliver │ ├─ deliver.js Windows 投递：payload + 调用 notify.ps1 │ └─ config.js 设置默认值/校验/深合并/原子写 ├─ lib/ src/ 的构建产物（scripts/build.mjs 直拷，随仓库提交） ├─ assets/ │ ├─ notify.ps1 弹 Toast + 播放声音 + 任务栏闪烁 │ ├─ activate.ps1 点击后聚焦/唤醒 DSH 窗口 │ ├─ activate.vbs wscript 隐藏启动 activate.ps1 的入口 │ └─ notify.wav 内置提示音 ├─ scripts/ │ ├─ build.mjs src → lib 复制 │ ├─ install.mjs 安装/卸载到 profile（幂等 + 备份） │ ├─ setup-shortcut.ps1 创建/删除带 AUMID 的开始菜单快捷方式 │ └─ make-chime.mjs 重新生成 assets/notify.wav └─ test/ ├─ detection.test.mjs ├─ config.test.mjs ├─ notifier.test.mjs ├─ routes.test.mjs ├─ e2e.test.mjs ├─ REPORT-final.md 测试证据 └─ lib/harness.mjs 测试桩（假宿主/假投递/临时 DSH_HOME）

开发与构建

以下命令都在插件目录下执行（克隆位置，如 $env:USERPROFILE\.dsh\plugins\dsh-interaction-notify）：

改过 src/ 后必须重建：宿主加载的是 lib/
node scripts\build.mjs

跑全部测试（node:test，无第三方依赖）
node --test "test/.test.mjs"

只跑单个文件
node --test "test/detection.test.mjs"

重新生成内置提示音（确定性，重复生成字节一致）
node scripts\make-chime.mjs

- lib/ 是构建产物，必须与 src/ 保持一致；只改 src/ 不重建，重启后跑的仍是旧代码。
- 构建就是直拷（ESM，无打包器、无网络），node scripts\build.mjs 输出 5 个文件。
- 调试时建议用独立配置档，避免影响正在使用的桌面端：
dsh --profile notifydev web --port 5599

（dsh 命令可来自 DSH 安装目录的 resources\runtime\cli\bin\dsh.cmd。）
- 测试的 createPlugin({ deliver }) 支持注入假投递；真实 deliver 使用 Windows PowerShell，测试永远不会弹通知或响铃。

测试

测试使用 Node 内置的 node:test，覆盖：

| 文件 | 覆盖内容 | 用例数 |
| test/detection.test.mjs | 三种事件 → 通知描述的纯函数契约、脏数据不抛错 | 13 |
| test/config.test.mjs | 默认值、normalize/mergeConfig、原子写、损坏文件回退 | 16 |
| test/notifier.test.mjs | 去重、节流（审批不节流）、开关、统计、日志裁剪、deliverNow | 26 |
| test/routes.test.mjs | 路由鉴权（loopback + 同源）、405/400、body 上限、/set、/test、/log、/diag | 20 |
| test/e2e.test.mjs | 真实 session/event → 假投递的端到端链路、dispose | 15 |

共 90 个用例。测试全部注入假 deliver，并把 $DSH_HOME 指向系统临时目录，因此不会产生真实通知、不会写真实状态；详细证据见 test/REPORT-final.md。

ℹ tests 90
ℹ pass 90
ℹ fail 0

已知限制

- 只有宿主半：没有图形化设置界面，改配置用 HTTP 接口或直接编辑 state.json。
- 点击只回到 DSH 窗口本身，不定位到具体会话或消息（通知是应用级的）。
- 依赖 Windows 10/11 的 Toast 与开始菜单 AppUserModelID 机制；macOS/Linux 上宿主半安全降级（不投递、不报错）。
- 通知投递是「尽力而为」：单次 25 秒超时、失败只记日志，绝不影响会话；通知能否显示还受 Windows 通知权限与「专注助手 / 请勿打扰」控制。
- quietWhenFocused 通过前台进程名判断；DSH 窗口在前台但被其它置顶窗口遮住等边缘情况可能误判。
- 若开始菜单快捷方式被删除或被安全软件改写，点击回窗口会失效（通知可能仍正常弹出），重跑安装脚本可修复。
- 插件依赖 DSH 的 session/event 事件与内建工具名（ask_user_question / exit_plan_mode）；若 DSH 后续调整这些协议，需要同步更新 src/detection.js。

故障排查

完全收不到通知

1. GET /state 看 enabled、events.* 是否被关掉，stats.skipped/stats.failed 是否在增长。
2. quietWhenFocused 默认为 true：你是不是正看着 DSH？用 POST /test 验证（它绕过该规则），或把配置改为 false。
3. Windows 设置 → 系统 → 通知：总开关、专注助手/请勿打扰，以及「DeepSeek Harness 提示」的允许开关。
4. 检查快捷方式是否存在：Test-Path "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\DeepSeek Harness 提示.lnk"。不存在就重跑 install.mjs 或 setup-shortcut.ps1。
5. GET /state 的 platform 必须是 win32；非 Windows 返回 skipped: unsupported-platform。

有通知但没声音

1. sound 不是 "silent"，volume 不是 0。
2. Windows 音量合成器里检查 Windows PowerShell 的音量（notify.ps1 在它下面播放）以及系统总音量/静音键。
3. chime 使用 assets/notify.wav；文件丢失时会退化为系统提示音。可用 node scripts\make-chime.mjs 重新生成。
4. 系统声音方案被禁用时 sound = "system" 也可能没声，换回 chime 验证。

点击通知回不到窗口

1. 检查开始菜单快捷方式是否存在（同上）；缺失时 notify.ps1 会回退到 PowerShell 身份，点击不会回到 DSH。
2. 快捷方式目标应为 wscript.exe "...\assets\activate.vbs" "<DSH exe>"，工作目录为插件根。
3. 手动双击该快捷方式，观察 DSH 窗口是否置前，以区分是快捷方式问题还是窗口状态问题。
4. 记住限制：只回到 DSH 窗口，不跳到具体会话；应用被完全退出时会重新启动。

日志与诊断

| 内容 | 位置 |
| 通知尝试日志 | $DSH_HOME\dsh-interaction-notify\notifications.log |
| 最近 200 行日志 | GET /api/dsh-interaction-notify/log |
| 诊断转储 | POST /api/dsh-interaction-notify/diag → $DSH_HOME\dsh-interaction-notify\diag\<name>.json |
| 设置 | $DSH_HOME\dsh-interaction-notify\state.json |
| 单次通知的临时 payload（正常会被删除） | $DSH_HOME\dsh-interaction-notify\tmp\ |

日志里 skipped 的常见值：focused（DSH 在前台，按 quietWhenFocused 静默）、unsupported-platform（非 Windows）。error / code 非空说明 PowerShell 投递失败，通常会带出具体原因。

安全说明

- 插件不联网、不上报、无第三方依赖；通知内容只来自本地会话事件。
- HTTP 路由只接受 loopback + 同源请求（含 DNS rebinding 防护），请求体限制 256 KiB。
- 设置、日志、payload 文件权限 0600，payload 用完即删。
- 开始菜单快捷方式只指向仓库内的 assets/activate.vbs 和用户指定的 DSH exe，不包含任何凭据。

许可

MIT © 2026 waterc

接口与内部行为约定见 CONTRACT.md。