审批提醒 yl216/dsh-approval-alert

dsh-approval-alert · DSH 审批提醒

DSH 需要你审批或回答时，如果你人不在这个窗口前，它会一直干等。
这个插件把「它在等你」变成听得见、看得见的提醒：

| 什么时候 | 会发生什么 |
| 审批 / 提问出现（窗口在前台） | 提示音 + 应用内右下角浮层（带「去处理」）；任务栏图标带数字角标。 |
| 审批 / 提问出现（窗口在后台） | 再加一条 Windows 系统通知（点它直接切到对应会话）。 |
| 同一请求一直没人处理 | 按设定的次数与间隔重复提醒。 |

DSH 自身没有审批类的系统通知：窗口在后台时，提醒靠的就是插件补的这条 toast。
浮层里的「去处理」和系统通知的点击都会直接切到发起审批 / 提问的那个会话，不只是把窗口提到前台。
不想要系统通知可以在设置里关掉，声音与浮层不受影响。

声音可以按事件分别选择（8 种内置音效 + 自己导入的音频）、调音量、设定重复提醒的次数与间隔；审批、提问 / 计划评审、任务完成三类事件各有开关。

安装

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

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

1. 在 %USERPROFILE%\.dsh\profiles\desktop\package.json 的 dependencies 里加 "dsh-approval-alert": "link:<本目录>"；
2. 把 dsh-approval-alert 追加进同文件的 dsh.profile.bundles；
3. 在 profile 的 node_modules 下建一个指向本目录的目录联接。

然后 完全退出并重新启动 DeepSeek Harness（只刷新网页不够：插件的浏览器 bundle 在启动时进入加载图）。

想装进 web profile 用 -Profile web；想走官方 pnpm 流程（顺便维护 pnpm-lock.yaml）在 DSH 完全退出后加 -UsePnpm。

卸载：

powershell -ExecutionPolicy Bypass -File scripts\uninstall.ps1

用起来

启动后：

- 右下角浮层 —— 有审批时贴在窗口最右下角出现：点「去处理」跳到该会话，点「设置」打开本插件设置，点「关闭」收起本次浮层。
- 系统通知 —— 窗口在后台时才弹，点一下等于「去处理」（切到该会话并把窗口提到前台）。
- 设置 → 插件 → dsh-approval-alert —— 同样的完整设置页。

界面上没有常驻的悬浮按钮：提醒只在真正需要你的时候出现，配色沿用页面的淡蓝色主题色。

设置项一览：

- 总开关
- 审批提醒 / 提问 / 计划评审提醒：开关、提示音、音量、重复次数（1–5）、重复间隔（3–120 秒）
- 任务完成提醒（默认关闭）：本轮结束时给一次性提示
- 提醒方式：
- 右下角浮层（默认开）
- 窗口在后台时弹系统通知（默认开；关掉就只剩声音）
- 自定义音效：导入 wav / mp3 / ogg（≤1.5MB），保存在本机浏览器存储里，可试听、删除，并选给任意事件

自检 / 排查

- 设置页里的 「立即测试」 立刻演示一次审批提醒（声音 + 浮层），不用真的触发审批。
- 开发者工具控制台里也可以：

__dshApprovalAlert.testAlert() // 演示审批提醒
__dshApprovalAlert.testAlert('question')
__dshApprovalAlert.describe() // 焦点 / 通知权限 / 音频解锁 / 挂起的提醒 / 等待中的会话
__dshApprovalAlert.getSnapshot() // 完整状态

- 听不到声音：浏览器要求先有用户手势才允许出声。在 DSH 里随便点一下 / 敲一下键就会解锁（设置页的「运行状态」会显示音频是否已就绪）。
- 看不到系统通知：先在设置页「运行状态」看「系统通知权限」。Windows 侧还要允许 DeepSeek Harness 发通知（设置 → 系统 → 通知）；被拒绝时插件安静降级为「提示音 + 应用内浮层 + 任务栏角标」。
另外系统通知只在窗口不在前台时发，前台时只有声音与浮层。
- 「去处理」没跳过去：确认宿主版本提供 uiWorkspace.openSession()（新版还会兜底 sessions.open()）；两者都没有时，按钮退化为只把窗口提到前台。
- 完全没反应：确认重启过 DSH，并确认 profile 里确实接好了线：

$env:ELECTRON_RUN_AS_NODE='1'
& 'D:\Software\dsh\DeepSeek Harness.exe' test\verify-host.mjs
Remove-Item Env:\ELECTRON_RUN_AS_NODE

它会打印 profile 的 bundle 层、合成后的配置条目，以及客户端 bundle 的形态。

工作原理（给维护者）

- Host 侧（lib/index.js）是一个空插件。它存在的唯一理由是：只有 Loader 挂载的插件才会被 dsh.client 扫描，从而让浏览器 bundle 进入加载图。
- 浏览器侧（lib/client.js）订阅 uiSession.sessionStatus
（Map<sessionId, { running, pendingInteraction, completionUnread }>）。
审批卡片出现的前提就是某个会话的 pendingInteraction.kind === 'approval'，所以订阅它 = 「审批出现的瞬间」，并且 完全不参与 approval/request 责任链 ——提醒插件再怎么写坏，也不会让审批无法被回答。
- 声音：内置音效全部用 Web Audio 现场合成（不随包带音频文件）；自定义音效以 data URL 存在 localStorage。
- 跳会话：提醒里记着 sessionId；点「去处理」时依次尝试 uiWorkspace.openSession(id)、
sessions.open(id)（只探测、不硬依赖），把 DSH 主视图切到那个会话。
- 系统通知：窗口不在前台（document.hasFocus() 为假或页面不可见）时，new Notification(...) 补一条 Windows toast：tag 固定为 dsh-approval-alert，silent: true（声音由插件自己放，避免双响）；点通知等于「去处理」。前台时不弹，避免和审批卡片重复。权限在首次手势里申请。
- 持久化：设置存在 localStorage['dsh-approval-alert:settings:v1']，按 schema 归一化（越界值、失效的音效引用都会被修正，旧版的 notify.whenUnfocused 等字段会被丢弃），读失败/写失败都不会让插件中断。
- 依赖极小：inject = ['slots', 'uiSession']，只从平台模块表取 react，其余是原生 DOM / Web Audio。

卸载与回滚

scripts/uninstall.ps1 会把三条接线全部撤回（并把原 package.json 的备份留在 package.json.bak）。插件自己不写任何 Host 侧状态，删掉即干净。

已知边界

- 需要重启 DSH 才能生效（新 bundle 进入加载图发生在启动时）。
- 审批弹窗不是本插件画的：带「允许一次 / 拒绝」的那张卡由 DSH 自带的 @deepseek-ai/dsh-client-ui-approval 渲染（出现在审批所属会话的输入框区域，Enter = 允许一次，
Esc = 拒绝）。本插件只负责提示音、系统通知、右下角浮层、任务栏角标与「去处理」跳转。
- 系统通知只在窗口不在前台时发：审批在你看着屏幕时出现、你随后才切走，并且重复次数设为 1 时，不会再补发通知。把重复次数调到 2 以上，下一跳会在后台补发。
- 「去处理」依赖宿主提供 uiWorkspace.openSession()（新版还会兜底 sessions.open()）；两者都没有时，按钮退化为只把窗口提到前台。
- 任务完成提醒默认关闭：子智能体的一轮结束也会让"正在运行"翻转，默认开着会很吵（代码里已尽量过滤子会话）。
- 手工接线不会更新 pnpm-lock.yaml；若之后在插件管理器里增删插件导致 pnpm 重装 profile，重跑一次 scripts/install.ps1 即可（或用 -UsePnpm）。