前言¶
在 DeepSeek Harness（DSH）里跑 agent，常见情况是窗口不在前台：一轮对话跑完、审批卡片在等、或会话列表里还有没点开的消息。系统通知往往要读标题、点一下；弹窗和横幅也容易打断当前工作。若你更希望「余光里能察觉、不必立刻切回」，就需要一种不抢焦点、不代答审批的提醒方式。
下面介绍社区插件 dsh-desktop-alerts（维护者 onezeroyl，分类「趣味换装」）：在 DSH Web 界面内用全屏烟花、贴边呼吸色带和会话行高亮做纯视觉提醒；在 Windows 上还可通过透明点击穿透覆盖层，在页面被遮挡或窗口最小化时继续在整块屏幕上呈现同类效果。
这是什么¶
dsh-desktop-alerts 是面向 DSH 的桌面氛围提醒插件：会话 turn 完成时全屏烟花；需要你审批或回答提问时，屏幕四边深绿呼吸；计划待确认时用琥珀色边闪；出错时一次性红闪；回答完尚未查看的会话在左侧列表整行深绿高亮。没有弹窗、卡片、通知横幅和声音（配置里 sound 默认关闭）。
插件以 MIT 许可证发布，当前 package 版本为 0.3.7，要求 Node >=20。DSH 生态主张「一切皆插件」；插件目录页在 SkillHub，源码在 GitHub。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
页面内特效（全平台）¶
- 任务完成：全屏烟花，约 3 次爆发、约 600 颗粒子，带拖尾与辉光；深色主题偏霓虹，浅色主题更饱和。
- 审批 /
ask_user_question：四边 #15803D 深绿呼吸，贴边约 58px，不遮挡中间内容。 - 计划待确认：同样形式的边闪，琥珀色。
- 出错：一次性红闪后自行停止。
- 未读会话：跟随 DSH 未读点，列表中对应会话整行深绿；点开并消未读后高亮消失。免打扰时段（
quietHours）只挡烟花与边闪，不挡未读高亮。
Windows 原生覆盖层（可选兜底）¶
DSH 页面在前台时，由页面侧 lib/client.js 注册 shell.overlay，用 canvas / CSS 绘制（GPU 合成）。页面不在前台、被遮挡或整个 DSH 窗口最小化时，宿主通过 loopback HTTP 与单文件 C# WPF 程序 DshDesktopAlertsFx.exe 在多显示器上绘制透明、置顶、点击穿透的覆盖层，不抢焦点、不进任务栏与 Alt-Tab。
多显示器时：每块屏都会收到提醒；前台页只画所在屏，其余屏由覆盖层补位。
需要 Windows 10/11 且系统带有 .NET Framework 4.x 及 csc.exe（首次运行宿主用其编译覆盖层 exe）。macOS / Linux 可正常安装，页面内特效与未读高亮可用，跨窗口覆盖层自动降级。
架构要点¶
| 部分 | 位置 | 作用 |
|---|---|---|
| Host | lib/index.js |
拦截审批、计划确认、agent 状态与错误；维护队列；loopback 路由；编译并拉起覆盖层 |
| 页面层 | lib/client.js |
上报可见性与窗口矩形；前台时本地绘制 |
| 原生层 | widget/DshDesktopAlertsFx.cs |
约 1.5s 轮询 /state，补齐未覆盖屏幕 |
| 契约 | CONTRACT.md |
端点、StateSnapshot、渲染归属 |
安全边界：插件不代答审批，无 /answer；HTTP 仅 loopback 且带启动时随机 token；任一步失败则静默降级，不影响官方审批链路。
安装与启用¶
在 DSH 插件市场（Discover → 索引源 https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json）搜索 dsh-desktop-alerts 安装，或执行：
dsh plugin --profile web add dsh-desktop-alerts
本地已有插件目录时，可在 DSH 会话中让 agent 执行：
plugin_manager action: install_bundle
target: <本目录绝对路径>
安装后重启 DSH（或等待 profile 热加载）。可用 cordis_inspect_query 确认 dsh-desktop-alerts 状态为 schema。
卸载：
plugin_manager action: remove_bundle target: dsh-desktop-alerts
卸载后重启 DSH；%LOCALAPPDATA%\dsh-desktop-alerts 可手动删除。
配置¶
在 profile 的 cordis.patch.yml 中写入（字段以仓库 README 为准）：
- id: dsh-desktop-alerts
name: dsh-desktop-alerts
config:
enabled: true
debug: true # 排查时写 host.log
triggers: { approval: true, planReview: true, done: true, error: true }
celebrate: { enabled: true, cooldownMs: 800 }
effects: { fireworks: true, edgeFlash: true }
unreadHighlight: { enabled: true }
overlay: { autoStart: true }
quietHours: { enabled: false, start: "23:00", end: "08:00" }
sound: { enabled: false }
pendingTtlMs: 300000
想清静时可关闭 effects.fireworks / edgeFlash；Windows 上若不需要后台覆盖层，可调整 overlay.autoStart。
典型用法与验收¶
日常无需额外命令：开启插件后，完成 turn、触发审批或未读会话时会按配置自动呈现效果。
Windows 上可在不依赖真实任务的情况下预览覆盖层（README 示例）：
& "$env:LOCALAPPDATA\dsh-desktop-alerts\DshDesktopAlertsFx.exe" -ConfigPath "$env:LOCALAPPDATA\dsh-desktop-alerts\widget.json" -Preview 4
& "$env:LOCALAPPDATA\dsh-desktop-alerts\DshDesktopAlertsFx.exe" -ConfigPath "$env:LOCALAPPDATA\dsh-desktop-alerts\widget.json" -EdgePreview
排查时可查看 %LOCALAPPDATA%\dsh-desktop-alerts\host.log（需 debug: true）与 overlay.log。
适用场景与注意¶
适合长时间让 agent 在后台跑、又希望用余光感知「完成 / 待你点审批 / 有未读会话」的 DSH 用户。不适合依赖独占全屏（全屏游戏、部分 DRM 视频）的场景——覆盖层会被系统层级挡住。
安装前建议自行查看 GitHub 源码 与 MIT 许可证。插件以当前 DSH 进程权限运行；覆盖层不读屏、不抓键鼠，仅在本机 loopback 上同步状态，无遥测与远程请求。
已知限制：无 csc.exe 的精简 Windows 仅保留页面内特效；覆盖层不跟随系统「减少动效」；DSH 退出时覆盖层子进程一并退出。
结尾¶
dsh-desktop-alerts 把「完成庆祝、待办边闪、未读书签」做成无弹窗的桌面氛围层，并在 Windows 上补全页面不在前台时的多屏提醒。需要一键安装入口可看 SkillHub 目录页，细节与契约见 GitHub 仓库 README。
