joejojoking-cloud/dsh-approval-popup-bridge

dsh-approval-popup-bridge

DSH（DeepSeek Harness）全局提醒 —— 当任何 agent 发起审批请求、输出完一轮结果、或向你提问时，弹出提醒。支持居中毛玻璃卡片和 Windows 系统 Toast 通知双通道，配守卫脚本自动拉起 + 计划任务系统级自愈，登录自启。

功能

- 🔔 实时感知所有会话/agent 的审批请求（approval/asked 事件），最快 ~300ms 内弹窗
- ✅ 结果完成提醒：agent 输出完一轮结果（turn/end 的 completed / max-tokens）时弹窗，显示会话标题 + 最后回复摘要（前 120 字），同会话 60 秒冷却防轰炸
- 💬 提问提醒：agent 调用 ask_user_question 向你提问时弹窗提示（隐私设计：不显示问题文本，只提示去 DSH 页面查看）
- 🪟 双通道提醒（popup-config.json 的 mode 控制，30 秒热重读）：
- both（默认）：居中毛玻璃 + Windows 系统 Toast 同时提示
- glass：只显示居中毛玻璃
- toast：只显示系统 Toast（Win10 右下角 / Win11 左下角），点击可在浏览器打开 DSH 页面（URL 带 session= 会话参数）
- 📋 三种提醒内容：审批（工具名/原因/会话）、完成（会话名/摘要）、提问（会话名）
- 🔁 已读提醒 id 持久化（seen.json），应用重启不重放
- 🌍 桥接插件挂在宿主组合（host composition），对所有会话生效

架构

agent 发起审批请求 / 输出完一轮结果 / 向你提问
│  approval/asked · turn/end(completed|max-tokens)
│  · tool/call(ask_user_question) 追加到会话日志
▼
宿主组合插件 dsh-approval-popup-bridge（index.cjs）
│  双通道：session/event 实时监听（含子代理会话，最快 ~0ms 感知）
│  + 250ms 扫描兜底（历史 seed + 事件 seq 水位线去重）
│  通过 webServer 暴露 GET /api/approval-popup/pending
▼
Windows 弹窗应用（ApprovalPopup.ps1，常驻进程）
│  300ms 轮询本地路由；asks 条目按 kind 区分
│  ask（审批请求）/ done（结果完成）/ question（有提问）
▼
主屏幕居中置顶：靛蓝毛玻璃弹窗
▲
守卫 ApprovalPopupGuard.ps1（一次性"确保在跑"脚本，写 guard.log）
▲  计划任务 DSHApprovalPopupGuard 每分钟执行 —— 系统级自愈（进程死了下一分钟自动重跑）
▲  HKCU Run 键登录时立即执行一次（弹窗秒起）

安装

一套文件可以放在任何目录（无需固定路径）：弹窗脚本/守护/配置自动跟随自身所在目录生成日志与已读记录。唯一要改的是 DSH 的 host 端口（默认 3080）——若你的 dsh web 不是 3080，见下文「端口」。

1. 桥接插件（宿主组合）

把 index.cjs 复制到 DSH 宿主组合目录（${DSH_HOME}/profiles/web/）并命名为 dsh-approval-popup-bridge-v7.cjs（当前部署版本，见下方版本命名说明）：

${DSH_HOME} 默认为 ~/.dsh
Copy-Item index.cjs "$env:USERPROFILE\.dsh\profiles\web\dsh-approval-popup-bridge-v7.cjs"

然后把 cordis.patch.yml 的内容追加到同目录的 cordis.patch.yml（${DSH_HOME}/profiles/web/cordis.patch.yml）。该文件是部署的补丁层，编辑后配置热更新自动生效，无需重启 DSH。

版本命名说明：插件是 CommonJS，Node 的 CJS 模块缓存按解析路径缓存，URL 查询串（?v=N）不会击穿缓存。要热更新代码而不重启进程，必须换文件名（递增 v 号）并同步改补丁里的 name；仅冷启动（重启 DSH）时文件名不变也没关系。

2. 弹窗应用（Windows）

把 ApprovalPopup.ps1、ApprovalPopupGuard.ps1、popup-config.json 放到同一个目录（如 D:\tools\dsh-popup\），用 Windows PowerShell 5.1 启动（脚本含中文，必须保留 UTF-8 BOM）：

powershell.exe -NoProfile -STA -WindowStyle Hidden -ExecutionPolicy Bypass -File ApprovalPopup.ps1

- 单实例互斥，重复启动自动退出
- 运行日志 popup.log、已读记录 seen.json、配置 popup-config.json 自动生成在脚本同目录
- 显示模式：popup-config.json 的 mode 字段（both/glass/toast），30 秒内自动生效；安装了 GUI 配置卡片（见 4）则在 DSH 设置页切换，~300ms 实时生效
- 提示音：toastSound 可选 default（系统默认轻声）/ reminder（推荐）/ sms / mail / im / alarm（长闹铃）/ off（静音），改完即生效；音量由系统控制（设置 → 系统 → 声音 → 更多声音设置，可单独调大每个声音事件）
- 端口：若 dsh web 不在 3080，用 -PollUrl 启动参数覆盖（守护自启场景还需同步改 popup-config.json 的 openBase）
- 系统 Toast 需要系统通知横幅开启（设置 → 系统 → 通知 → 对应应用 → 显示通知横幅）；Win11 下横幅在左下角
- 弹窗进程不随 DSH 生命周期绑定：DSH 重启、机器重启或意外退出后需要重新启动
3. 保活机制（一键安装：自动拉起 + 系统级自愈 + 登录自启）

ApprovalPopupGuard.ps1 是一个一次性、幂等的“确保在跑”脚本：检查弹窗进程（默认与守卫同目录的 ApprovalPopup.ps1）是否存在，缺失则自动重新启动（弹窗自身是单实例互斥的，竞态启动无害），然后退出。它由两个系统机制驱动，任一层都保证弹窗不会“死着没人管”：

1. 计划任务 DSHApprovalPopupGuard（每分钟）——Task Scheduler 是系统服务：就算守卫脚本某次被杀/崩溃，下一分钟任务自动重跑。这是“守卫的守卫”。旧版常驻 while($true) 进程一旦崩溃/被杀就要等下次登录才复活，本版已根除。任务通过 wscript.exe + run-hidden.vbs（无控制台宿主）启动守卫，不会闪 PowerShell 窗口。
2. HKCU Run 键 DSHApprovalPopupGuard（登录时）——登录后立即执行一次，弹窗秒起（分钟任务作兜底）。

一键安装/修复/移除（免管理员；-PopupDir 缺省为脚本所在目录，会把弹窗脚本部署过去并保留已有 popup-config.json 与日志）：

powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1                          # 安装
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -PopupDir "D:\tools\dsh-popup"  # 指定部署目录
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -Remove                  # 移除保活

也可手动跑一次守卫（隐藏窗口）：powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ApprovalPopupGuard.ps1

守卫每次真正拉起弹窗或出错都会写 guard.log（与脚本同目录）。

4. （可选）GUI 配置卡片

在 DSH 设置页「插件配置」里用三选一卡片切换提醒方式（同时 / 只毛玻璃 / 只 Toast，~300ms 实时生效），需要额外的 bundle 插件：dsh-popup-config。不装也能用（改 popup-config.json 的 mode 即可，30 秒生效）。

验证

桥接插件挂载后，路由应返回 JSON：

Invoke-RestMethod http://127.0.0.1:3080/api/approval-popup/pending
{ ok: true, seq: ..., pollCount: ..., asks: [{ id, kind: 'ask'|'done'|'question', session, ... }] }

pollCount 持续增长说明扫描在跑；seq 每次新提醒 +1。asks 条目三种：

| kind | 含义 | 关键字段 |
|---|---|---|
| ask | 审批请求 | toolName、reason、session |
| done | agent 输出完一轮结果 | session、preview（最后回复摘要） |
| question | agent 向你提问 | session（无问题文本，隐私设计） |

文件说明

| 文件 | 说明 |
|---|---|
| index.cjs | 宿主组合桥接插件（部署时复制为 dsh-approval-popup-bridge-v7.cjs） |
| ApprovalPopup.ps1 | Windows 提醒应用（WPF 毛玻璃 + 系统 Toast，UTF-8 BOM；日志/配置跟随脚本目录） |
| popup-config.json | 提醒配置：mode（both/glass/toast）、openBase（点击跳转地址）、toastSound（提示音，改完即生效） |
| ApprovalPopupGuard.ps1 | 守卫脚本（一次性幂等）：检测弹窗进程缺失并自动拉起，写 guard.log |
| install.ps1 | 一键安装/修复/移除保活：每分钟计划任务（系统级自愈）+ HKCU Run 登录自启 + 部署弹窗脚本 |
| run-hidden.vbs | 无控制台启动包装器：计划任务经 wscript.exe 调用守卫，不闪 PowerShell 窗口 |
| cordis.patch.yml | 挂载补丁模板（追加到部署的 cordis.patch.yml） |
| package.json | 项目元数据 |

注意事项

- 弹窗应用为常驻进程，DSH 重启不影响它；桥接插件随 DSH 一起启动
- 更新弹窗脚本后，结束弹窗进程即可——计划任务会在 ≤1 分钟内自动拉起新脚本（或手动跑一次守卫立即拉起）
- ⚠️ Windows 可能抑制系统 Toast 横幅（消息中心有通知、屏幕上不弹，常见于专注助手/勿扰/通知设置）：toast 模式在这种环境下等于“看不见弹窗”。建议使用 both 或 glass 模式——毛玻璃是自绘置顶窗口，不受系统通知设置约束
- 弹窗应用仅适用于 Windows 10/11（毛玻璃依赖 DWM 分层窗口渲染）
- 插件只读会话事件、注册一个本地 HTTP 路由，不修改任何业务数据

License

MIT