session-notify/README.md

会话通知

DeepSeek Harness（DSH）插件：会话需要你注意时提醒你——窗口不在前台用系统通知，窗口在前台用应用内轻弹窗。

提醒什么

什么时候提醒	通知标题	内容里带什么
会话从「运行中」变为「空闲」（一轮回答结束）	会话已完成	会话题目
出现等待你处理的工具授权请求	需要授权	等待授权的工具名
出现等待你回答的提问，或等待你确认的计划	需要回答	提问提醒带问题原文，计划确认带会话题目

三类提醒可以分别开关。

每条只提醒一次：同一会话的同一轮只报一次完成，同一个待处理请求只报一次；请求消失之后再次出现，会重新提醒。

提醒送到哪里

按 DSH 窗口当时的状态选通道，你不需要预先设置：

窗口状态	怎么提醒
窗口不在前台	系统通知（Windows 通知中心 / macOS 通知中心 / Linux 通知守护）。点一下通知：窗口回到前台，并跳到那个会话
窗口在前台，但不是你正在看的那个会话	应用内轻弹窗：右上角浮出一张卡片，标题是提醒类型，下面一行是会话题目与细节
窗口在前台，且正是你在看的那个会话	不打扰（你就在看着，不需要弹）

系统通知的气泡只存在几秒，人不在电脑前时它等于没送到，所以：

• 凡是在窗口不在前台时投递的提醒，窗口回到前台的那一刻会再用轻弹窗补发一次（同一会话同一类只留最新一条，超过 30 分钟不再补发）；
• 唯一的例外：系统确认气泡已经弹出来、而且你 20 秒内就回到窗口——那条气泡还在屏幕上，就不再重复；
• 补发不受「正在看的会话不打扰」限制——这条提醒发生的时候你并不在看；
• 点掉系统通知本身就会取消对应的补发；
• 插件页「最近一次投递」会写清系统到底有没有确认显示（系统已确认弹出 / 系统没有回报 / 没弹出来）。

轻弹窗的用法：

• 点「查看」跳到该会话；
• 默认 6 秒后自动消失（可在插件页改成 3 / 10 / 30 秒，或设成永不关闭）；鼠标停在上面期间都不消失，移开后重新计时；
• 按 Esc 关掉最新的一条，或点 ✕ 关掉这一条；
• 同屏最多叠 3 条，更早的会被挤掉（即使设成永不关闭也一样，不会越堆越多）；
• 轻弹窗是 DSH 的浮层卡片样式（和菜单、弹窗同一层底色与阴影），跟随 DSH 的深色 / 浅色模式。

设置

插件 → 会话通知：

分组	内容
提醒内容	完成 / 授权 / 提问 三个开关，分别控制三类提醒，默认全开；开关保存在浏览器本地，重开页面、重装插件都保留
轻弹窗	自动关闭时间：3 / 6 / 10 / 30 秒，或永不（永不时要自己点 ✕ 或按 Esc）；鼠标停在卡片上时都不会消失
系统通知权限	一行状态（前面的小圆点表示健康程度）+ 一个按钮；尚未授权时按钮是「允许通知」（浏览器要求必须由你手动点击），授权成功后自动发一条测试提醒，按钮随之变成「测试系统通知」；权限被系统层关闭或当前环境不支持时，状态下面按当前平台告诉你去哪里打开
运行状态	四项读数：窗口状态（前台还是后台，即会走哪条通道）、会话监听（插件是否真的在读会话状态）、最近一次投递（时间、走的通道、系统是否确认弹出，下一行是提醒类型）、待补发提醒（还有几条在等你回到窗口）；下面「测试提醒」按钮发一条测试提醒

• 已经授权时，权限行的按钮变成「测试系统通知」：它直接走系统通知通道（窗口在前台也照发），专门用来验证系统通知本身是否可用。
• 开关只影响提醒，不改 DSH 本身的任何设置。

安装

从 Git 仓库安装（推荐）

在 DSH 的 插件 → 添加插件 的上方输入框里填：

https://gitea.iwake.top/dsh-plugin/session-notify.git#v1.0.10

# 后面跟标签或提交，用来锁定版本；不写则取默认分支。跟随 1.x 最新版可以写 #semver:^1.0.10。仓库是公开的，不需要凭据，也不用改「安装源」。

本地路径安装

把仓库克隆或下载到本机，在同一个输入框里填包目录的绝对路径，例如：

D:\DeepSeek Harness Plugins\dsh-session-notify

安装之后

• 装好刷新页面即生效；仓库里已经带好构建产物，所以既不需要 pnpm 下载，也不需要构建，本插件运行时没有第三方依赖。
• 卸载：在插件页里移除 @dsh-plugin/session-notify。
• 上面这两条说的都是使用者。要改插件本身，只需要一个 pnpm install（唯一依赖是打包用的 esbuild），见下面的仓库结构。

提醒规则

• 只在「运行中 → 空闲」的转变上提醒：打开应用时已经在跑的会话只建立基线，不补发；历史里早已结束的会话不会被翻出来提醒。
• 正在看的那个会话完成后不打扰。
• 子智能体的会话不单独提醒，等它归属的主会话结束时才提醒。
• 空白会话完成不提醒。
• 授权 / 提问会立刻提醒，不押后：待处理请求只有你能清掉，而会话「正在等它」本来就是会话的状态（running 是宿主自己的另一条事实，和有没有待处理请求无关），所以不会因为「会话还在跑」而压后提醒；请求在 400ms 确认窗口内被你自己答掉，就不再提醒。
• 节流：1.5 秒内只投递一条，多个会话同时完成不会刷屏。
• 完成提醒有 400ms 的确认窗口：如果那一轮马上又跑起来，就不报了。
• 同一会话的完成提醒会覆盖上一条（通知带 tag），不叠加堆积。
• 窗口不在前台时投递过的提醒，回到前台会补发一次轻弹窗（30 分钟内有效）。
• 提醒只在 DSH 运行、页面打开时产生：DSH 完全退出期间结束的会话不会再补发通知。

平台

• Windows / macOS / Linux 都支持，三个平台走同一条通知通道，行为一致；应用内轻弹窗与平台无关。
• 当前环境不支持系统通知时（权限一行会显示「不可用」），提醒仍然以应用内轻弹窗的形式送达。
• 系统通知被拒绝或发送失败时，插件会改用轻弹窗，并把原因写在插件页的权限 / 状态那一段，不会静默失败。

兼容性

需要 DeepSeek Harness 0.2.0-rc.2 或更高。

仓库结构

给要改这个插件本身的人；只是使用它的话，这一节不需要看。

路径	是什么
src/client/	浏览器半的全部源码：core/（观察、投递、系统通知通道、补发、弹窗栈、开关与动作）、ui/（弹窗、开关行、插件页、观察器、图标、样式、hooks）、i18n/（中英文字典与翻译器）、platform.js（窗口可见性、通知权限、图标、平台提示）、plugin.js（组合根：建 store、装配模块、注册 slot）
client.js	构建产物：src/client/** 打包成一个自包含单文件，由 DSH 的客户端模块系统加载。它提交进仓库——这正是安装免构建的原因
index.js / main.js	宿主半（目前是空壳），以及给按 main 解析的加载器用的同义入口
cordis.patch.yml、icon.svg、locale/	组合包 patch、图标、插件展示用的标题与简介
scripts/build-client.mjs	构建脚本：打包，并校验产物仍然满足注册契约
tests/	node --test：纯函数单测、组件渲染测试（含轻弹窗与插件页）、产物冒烟、以及产物与源码是否一致

为什么必须是单个文件：DSH 的客户端模块系统只把一个自包含 bundle 交给插件（window.__ModuleLoader__.load({ id, factory })），factory 里的 require 只能解析 react 这类平台模块，不能 require 同一个包里的相对文件。所以源码拆成模块之后，必须再打包回单文件——官方客户端插件（例如 dsh-experimental-client-ui-voice-input）也是这个形态：src/** 源码 + 构建出的客户端 bundle。

维护者命令：

pnpm install     # 只装 esbuild 一个 devDependency
pnpm run build   # 从 src/client 重新生成 client.js —— 改完源码必须跑
pnpm test        # node --test

• 不要直接改 client.js：它每次构建都会被覆盖；改完 src/ 忘记重新构建，tests/bundle.test.js 会直接报「产物已过期」。
• 改完产物后，正在运行的 DSH 里要在插件页把这一行停用再启用（或重启 DSH）：宿主对客户端 bundle 有缓存，只刷新页面不一定重新读取它。

License

MIT