dsh-approval-alert · DSH 审批提醒
DSH 需要你审批/回答时,如果你的人不在这个窗口前,它会一直干等。
这个插件把"它在等你"变成听得见、看得见的提醒:
| 什么时候 | 会发生什么 |
|---|
| 审批 / 提问出现(窗口在前台) | 提示音 + 应用内右下角浮层(带「去处理」);任务栏图标带数字角标。 |
| 审批 / 提问出现(窗口在后台) | 再加一条 Windows 系统通知(点它直接切到对应会话)。 |
| 同一请求一直没人处理 | 按设定的次数与间隔重复提醒。 |
DSH 自身没有审批类的系统通知:窗口在后台时,提醒靠的就是插件补的这条 toast。
浮层里的「去处理」和系统通知的点击都会直接切到发起审批 / 提问的那个会话,不只是把窗口提到前台。
不想要系统通知可以在设置里关掉,声音与浮层不受影响。
声音可以按事件分别选择(8 种内置音效 + 自己导入的音频)、调音量、设定重复提醒的次数与间隔;
审批、提问/计划评审、任务完成三类事件各有开关。
安装
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
安装脚本会做三件事(幂等,可重复运行):
- 在
%USERPROFILE%\.dsh\profiles\desktop\package.json 的 dependencies 里加
"dsh-approval-alert": "link:<本目录>";
- 把
dsh-approval-alert 追加进同文件的 dsh.profile.bundles;
- 在 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)。
