diff --git a/README.md b/README.md index 7bca00b..2dd5d1c 100644 --- a/README.md +++ b/README.md @@ -26,21 +26,13 @@ Windows / macOS / Linux 三个平台走的是同一条通知通道（渲染进 **插件 → 会话通知**（插件自己的介绍页里）： -- 显示系统通知权限状态； -- 未授权时点「允许通知」请求权限（浏览器要求必须由你手动点击才能弹权限框），授权后自动发一条测试通知； -- 已授权时点「测试通知」随时验证； -- 权限被系统层关闭时，按平台给出开启路径（Windows / macOS 的通知设置、Linux 桌面环境的通知设置）； - 三个开关分别控制**完成 / 授权 / 提问**三类提醒（默认全开），状态存在浏览器本地，重装插件不丢； -- 最后一段显示观察器自身的健康状态（收不到会话状态时直接标红）。 +- 系统通知权限状态；未授权时点「允许通知」请求权限（浏览器要求必须由你手动点击才能弹权限框），授权后自动发一条测试通知；权限被系统层关闭时按平台给出开启路径； +- 「测试系统通知」直接走系统通知通道（窗口在前台也照发），专门用来验证系统通知本身是否可用； +- 「运行状态」一段显示：窗口现在是前台还是后台（决定会走哪条通道）、观察器是否真的收到了会话状态、以及**最近一次投递走的通道与时间**。 设置放在插件自己的页面里，而不是「设置 → 通用」：它是这个插件的配置，不是 DSH 的通用偏好。页面顶部是 DSH 自己渲染的插件标题与描述，所以这块配置不再重复标题，直接用一句「提醒是怎么送出去的」开头。 -### 关于「包含的组件」 - -插件页下方那一段（`组件` / `包含的组件`）是 **DSH 插件页固定渲染**的：`ui-plugin-manager` 的 `RowsSection` 无条件列出这个 bundle 在 `cordis.patch.yml` 里声明的**每一行**（行 id、运行状态、单独开关），没有"跳过"的口子。因为任何 bundle 都至少要声明一行才能挂上宿主半，所以这一节必然出现——本插件就是这一行。 - -它也不是纯冗余：它标出运行状态、允许单独关掉这个组件，并且当 bundle 与组件的关系变得复杂时是唯一的入口。如果你觉得一个组件时看着奇怪，那是 DSH 的呈现方式，插件侧没法隐藏。 - ## 安装 ### 1. 从 Git 仓库安装（推荐） @@ -72,8 +64,9 @@ D:\DeepSeek Harness Plugins\dsh-session-notify ## 平台说明与验证范围 - **通道是跨平台统一的**：插件的提醒都通过页面（Electron 渲染进程）的 `Notification` 构造器发出，Windows 通知中心 / macOS 通知中心 / Linux 通知守护（libnotify、GNOME、KDE）都由系统把它转成原生通知；应用内轻弹窗是纯 DOM，与平台无关。 +- **前台/后台的判定不依赖单一信号**：每次都现读页面的可见性与文档焦点（任一为"不可见"就算后台），不靠"记住上次的 blur 事件"——桌面外壳里漏掉一次 blur 曾让插件误判为前台而吃掉提醒（v1.0.5 修）。 - **宿主半拿不到系统通知**：DSH Desktop 的宿主进程是纯 Node 进程（不是 Electron 主进程），没有 Electron 的 `Notification` 可用，所以插件的所有提醒都在浏览器半产生——这也正是"三个平台一套代码"的原因。 -- **已验证**：Windows 上的安装、三个 slot 条目注册、以及 52 项离线断言（接线 / 国际化 / 轻弹窗结构 / 开关持久化 / 全部投递规则）。 +- **已验证**：Windows 上的安装、三个 slot 条目注册、以及 28 项离线断言（接线 / 国际化 / 两种后台信号 / 系统通道被拒时的降级 / 配置页诊断 / 全部投递规则）。 - **未验证**：macOS 与 Linux 上的实际弹窗效果本机无法测试。结构上它们与 Windows 共用同一条通道、同一份代码，只有"权限被系统关闭时显示的开启路径"是分平台的。 - 提醒只在 DSH 进程运行、页面打开时产生：**DSH 完全退出期间结束的会话不会再补发通知**。 @@ -97,6 +90,7 @@ D:\DeepSeek Harness Plugins\dsh-session-notify - **配置放在插件页**：`plugins.bundle.config` 的 key 取包名（`@dsh-plugin/session-notify`），插件页就会渲染这块配置；官方 `dsh-experimental-voice-input-bundle` 用的就是这个口子。行级口子是 `plugins.row.config`，key 形如 `<包名>#<行 id>`，会在该行上多出一个「配置」入口； - **不要**把"无渲染"条目放进 `sidebar.panellist`：该 slot 的宿主会把**每个条目的 id 当成一个左侧面板按钮**（`entriesOfSlot('sidebar.panellist')` → 面板列表，按钮文字取 `options.label ?? options.id`，条目本身作为图标内联渲染），放进去会在左侧多出一行空面板并挤坏侧边栏。本插件第一版踩过这个坑，现已改挂到通用浮层； - **文案必须注册字典**：`ctx.locale.register('session-notify', { zh, en })`，否则 `locale.bind(ns)` 在查不到该命名空间时会把 key 原样返回——界面上就会显示成 `settings.title` 这样的原始键（本插件第二版踩过这个坑）。注册会在 locale 修订号上打点，已经渲染出来的部件会自动换上文案，不需要刷新； +- **前台/后台要现读、不能只靠事件**：桌面外壳里 `blur` 可能不到，只记事件会让插件一直以为在前台而吃掉系统通知（本插件第三版踩过这个坑）。现在每次投递都读 `document.visibilityState` 与 `document.hasFocus()`； - 另外自带一份本地字典兜底：即使拿不到框架的 `t`、或 locale 服务没有保存注册，也会渲染中文/英文文案而不是原始键； - 样式只用主题 token，不 import 任何 `@deepseek-ai/dsh-client-*` 包（规范要求，也是渲染不被上游改动打断的前提）； - 宿主半不声明 `inject`、不注册服务、不注册路由；三个开关存浏览器本地，不改 DSH 的配置文件。 @@ -107,14 +101,14 @@ D:\DeepSeek Harness Plugins\dsh-session-notify `client.js` 是纯 JavaScript、浏览器端运行，可以在 Node 里用桩模块加载器评估并驱动： -- 模块接线：插件返回值、`inject` 声明、注册集合（含"配置挂在插件页""观察器绝不在 `sidebar.*` 里"这两条）； -- 国际化：字典已注册且中英键集合一致、插件页与弹窗渲染出的每个字符串都不是原始键、拿不到框架 `t` 时本地字典兜底、locale 服务不保存注册时仍然有文案； -- 轻弹窗结构：标题是触发类型、描述含会话名与细节； -- 开关：切换即写入浏览器本地，重开页面能读回； -- 渲染健壮性：各组件在空状态 / 权限被拒 / 无 Notification API 下渲染都不报错； -- 投递规则：完成提醒一次、当前会话不打扰、后台走系统通知、授权/提问各提醒一次、运行中延后、子会话跳过、空白会话跳过、历史不补发、开关生效、弹窗自动消失等。 +- 模块接线：插件返回值、注册集合（含"配置挂在插件页""观察器绝不在 `sidebar.*` 里"这两条）； +- 国际化：字典中英键集合一致且没有死键、插件页与弹窗渲染出的每个字符串都不是原始键、拿不到框架 `t` 时本地字典兜底； +- 前台/后台判定：**只给"页面不可见"信号**、或**只给"文档失焦"信号**（都不发 blur 事件）时，都必须走系统通知； +- 系统通道被拒时降级：构造器抛错时改用轻弹窗，并在配置页写明被拒； +- 配置页诊断：窗口状态、观察器健康、最近一次投递的通道与时间都能渲染； +- 投递规则：完成提醒一次、当前会话不打扰、授权/提问各提醒一次、运行中延后、子会话跳过、空白会话跳过、历史不补发等。 -合计 52 项断言。 +合计 28 项断言。 ## License diff --git a/client.js b/client.js index fe27877..d9e6c5a 100644 --- a/client.js +++ b/client.js @@ -73,7 +73,8 @@ window.__ModuleLoader__.load({ 'settings.permission.hint.mac': '系统设置 → 通知 → DeepSeek Harness', 'settings.permission.hint.linux': '在桌面环境的通知设置（GNOME / KDE）中允许 DeepSeek Harness', 'settings.action.allow': '允许通知', - 'settings.action.test': '测试通知', + 'settings.action.testSystem': '测试系统通知', + 'settings.action.testAny': '测试提醒', 'settings.action.unsupported': '不可用', 'settings.permission.promptFailed': '无法请求通知权限：{message}', 'settings.health.watching': '正在监听会话状态', @@ -89,6 +90,17 @@ window.__ModuleLoader__.load({ 'config.section.status': '运行状态', 'config.intro': '提醒都从当前页面发出：窗口不在前台时是系统通知，窗口在前台时是这里的轻弹窗。', 'config.saveNote': '开关保存在浏览器本地，重装插件不会丢失。', + 'config.testHint': '这里的按钮直接走系统通知通道，用来验证系统通知本身是否可用（窗口在前台也照发）。', + 'config.testAny': '测试提醒', + 'config.testSystem': '测试系统通知', + 'config.diag.window': '窗口状态', + 'config.diag.inFront': '在前台（会走轻弹窗）', + 'config.diag.away': '不在前台（会走系统通知）', + 'config.diag.last': '最近一次投递', + 'config.diag.none': '还没有投递过', + 'config.diag.system': '系统通知', + 'config.diag.popup': '应用内轻弹窗', + 'config.diag.refused': '系统通知被拒绝，改用了轻弹窗', } const en = { 'notification.completion': 'Conversation finished', @@ -113,7 +125,8 @@ window.__ModuleLoader__.load({ 'settings.permission.hint.mac': 'System Settings → Notifications → DeepSeek Harness', 'settings.permission.hint.linux': 'Allow DeepSeek Harness in your desktop notification settings (GNOME / KDE)', 'settings.action.allow': 'Allow notifications', - 'settings.action.test': 'Test notification', + 'settings.action.testSystem': 'Test system notification', + 'settings.action.testAny': 'Test alert', 'settings.action.unsupported': 'Unavailable', 'settings.permission.promptFailed': 'Could not request notification permission: {message}', 'settings.health.watching': 'Watching session status', @@ -129,6 +142,17 @@ window.__ModuleLoader__.load({ 'config.section.status': 'Status', 'config.intro': 'Every alert comes from this page: a system notification while the window is in the background, the light popup here while it is in the foreground.', 'config.saveNote': 'The switches are stored in this browser and survive reinstalling the plugin.', + 'config.testHint': 'The buttons here go straight to the system channel, so you can verify it on its own (they fire even while the window is in front).', + 'config.testAny': 'Test alert', + 'config.testSystem': 'Test system notification', + 'config.diag.window': 'Window', + 'config.diag.inFront': 'in front (popup is used)', + 'config.diag.away': 'not in front (system notification is used)', + 'config.diag.last': 'Last delivery', + 'config.diag.none': 'nothing delivered yet', + 'config.diag.system': 'system notification', + 'config.diag.popup': 'in-app popup', + 'config.diag.refused': 'system channel refused, popup was used instead', } /** @@ -309,13 +333,33 @@ window.__ModuleLoader__.load({ return 'default' } + /** + * Whether the Harness window is somewhere the user cannot see the app. + * + * Two independent browser facts are consulted, and ANY of them counts as "not + * in the foreground": the page's visibility and the document's focus. They are + * read at delivery time rather than remembered from an event, because a missed + * blur in the desktop shell made this plugin believe the window was in front + * and swallow the alert. + * @returns whether the alert must go to the system notification channel. + */ + function windowIsAway() { + try { + if (document.visibilityState === 'hidden') return true + } catch { + /* an unreadable visibility state leaves the focus fact */ + } + try { + if (typeof document.hasFocus === 'function') return !document.hasFocus() + } catch { + /* an unreadable focus state leaves the default below */ + } + return false + } + /** Read the window's live focus state rather than a cached value. */ function currentFocus() { - try { - return typeof document.hasFocus === 'function' ? document.hasFocus() : true - } catch { - return true - } + return !windowIsAway() } /** Focus the window without letting a refusal stop the navigation. */ @@ -504,9 +548,10 @@ window.__ModuleLoader__.load({ toasts: [], promptError: '', health: { state: 'starting', message: '' }, + lastDelivery: null, }) const notify = (message) => { - report(`session-notify: ${message}`) + report(message) } /** Every component translates through this: the slot's own seat when the owner supplies one, else the locale service. */ const seatFor = (props) => (typeof props.t === 'function' ? props.t : t) @@ -521,7 +566,6 @@ window.__ModuleLoader__.load({ live: { list: undefined, status: undefined, - focus: true, }, } const timers = new Map() @@ -632,12 +676,15 @@ window.__ModuleLoader__.load({ } } - /** Raise one system notification, tolerating every refusal a browser may give. */ + /** + * Raise one system notification, tolerating every refusal a browser may give. + * @returns the outcome the config page reports, so a refusal is never silent. + */ const systemNotify = (candidate, force) => { const Ctor = globalThis.Notification const permission = notificationPermission() - if (permission === 'unsupported') return false - if (!force && permission !== 'granted') return false + if (permission === 'unsupported') return 'unsupported' + if (!force && permission !== 'granted') return 'permission' try { const notice = copyFor(candidate) const options = { @@ -656,10 +703,10 @@ window.__ModuleLoader__.load({ /* close is best effort on every platform */ } } - return true + return 'raised' } catch (error) { notify(`system notification failed: ${text(error)}`) - return false + return 'threw' } } @@ -675,6 +722,25 @@ window.__ModuleLoader__.load({ return false } + /** + * Record what actually happened to the newest alert. + * + * Everything on the delivery path used to fail invisibly: the alert simply + * never appeared, with no way to tell a wrong channel decision from a + * refused constructor. The config page shows this record, so the next + * question ("did it even try?") has an answer. + */ + const recordDelivery = (outcome, candidate) => { + store.set({ + ...store.getSnapshot(), + lastDelivery: { + outcome, + at: new Date().toISOString().slice(11, 19), + title: copyFor(candidate).title, + }, + }) + } + /** * Whether a queued candidate is still worth delivering. Read from the LIVE * snapshot rather than the one captured when the transition was seen: a @@ -694,9 +760,12 @@ window.__ModuleLoader__.load({ /** * Deliver one candidate through exactly one channel: the system - * notification while the window is in the background, the light popup while - * it is in the foreground, and nothing at all for the conversation on - * screen. + * notification while the window is away, the light popup while it is in + * front, and nothing at all for the conversation on screen. + * + * The channel decision reads the window state right here, at delivery time, + * instead of trusting the state the observer last remembered — that is what + * an unreported blur used to defeat. */ const deliver = (candidate, ignoreThrottle) => { if (ignoreThrottle !== true) { @@ -704,12 +773,21 @@ window.__ModuleLoader__.load({ if (now - state.lastDelivery < THROTTLE_MS) return state.lastDelivery = now } - if (state.live.focus) { - if (!isOnScreen(candidate.sessionId, state.live.list)) showToast(candidate) + if (!windowIsAway()) { + if (isOnScreen(candidate.sessionId, state.live.list)) return + showToast(candidate) + recordDelivery('popup', candidate) return } - if (systemNotify(candidate, candidate.test === true)) return - if (candidate.test === true) showToast(candidate) + const outcome = systemNotify(candidate, candidate.test === true) + if (outcome === 'raised') { + recordDelivery('system', candidate) + return + } + // A test alert still has to reach the user, and so does a real one when + // the system channel refuses: the popup is the channel that remains. + showToast(candidate) + recordDelivery(`system-refused-${outcome}`, candidate) } /** @@ -736,11 +814,13 @@ window.__ModuleLoader__.load({ * One derivation pass over the client's own session state: remember the * freshest snapshot for the settle tick, compare it against what this page * already observed, emit at most one candidate per transition, and let the - * settle tick decide delivery. + * settle tick decide delivery. The window state is deliberately NOT captured + * here — the delivery reads it fresh, because it can change inside the + * settle window. */ - const observe = (focus, list, status) => { + const observe = (list, status) => { if (list === undefined || status === undefined) return - state.live = { list, status, focus } + state.live = { list, status } const kinds = store.getSnapshot().kinds for (const sessionId of Object.keys(list.byId ?? {})) { const summary = list.byId[sessionId] @@ -800,18 +880,36 @@ window.__ModuleLoader__.load({ // --------------------------------------------------------------- actions - /** Raise one test notification through the channel the current state selects. */ + /** Build one test alert that skips the throttle and the "on screen" rule. */ + const testCandidate = (title) => ({ + kind: 'completion', + sessionId: 'test', + title, + detail: '', + pendingKind: '', + test: true, + }) + + /** + * Raise one test alert through whichever channel the window state selects. + * Verified from the config page, where the user is looking at the app, so it + * normally lands in the popup — the way to prove the system channel is to + * press the button in a channel-specific test instead. + */ const sendTest = () => { - const candidate = { - kind: 'completion', - sessionId: 'test', - title: t('settings.title'), - detail: '', - pendingKind: '', - test: true, + deliver(testCandidate(t('config.testAny')), true) + } + + /** Raise the test alert on the system channel specifically, whatever the focus is. */ + const sendTestSystem = () => { + const candidate = testCandidate(t('config.testSystem')) + const outcome = systemNotify(candidate, true) + if (outcome === 'raised') { + recordDelivery('system', candidate) + return } - if (!currentFocus() && notificationPermission() === 'granted' && systemNotify(candidate, true)) return showToast(candidate) + recordDelivery(`system-refused-${outcome}`, candidate) } /** Request notification permission inside a user gesture, then report the outcome. */ @@ -854,21 +952,27 @@ window.__ModuleLoader__.load({ return React.useSyncExternalStore(source.subscribe, source.getSnapshot, source.getSnapshot) } - /** The window's focus state as a React value, kept current by the DOM's own events. */ - function useFocus() { + /** + * Subscribe to every browser signal that says whether the app is visible: + * the window's focus events and the document's visibility change. The value + * itself is a boolean, so the observer re-renders once per transition. + */ + function useWindowState() { const subscribe = React.useCallback((listener) => { try { window.addEventListener('focus', listener) window.addEventListener('blur', listener) + document.addEventListener('visibilitychange', listener) } catch { return () => {} } return () => { window.removeEventListener('focus', listener) window.removeEventListener('blur', listener) + document.removeEventListener('visibilitychange', listener) } }, []) - return React.useSyncExternalStore(subscribe, currentFocus, () => true) + return React.useSyncExternalStore(subscribe, () => !windowIsAway(), () => true) } /** @@ -876,9 +980,13 @@ window.__ModuleLoader__.load({ * how a plugin reaches the session hooks without occupying visible UI. It * renders `null`, and any failure in its own derivation is contained here so * a slot entry can never crash. + * + * It subscribes to the window state only so a foreground/background change + * re-derives promptly; the delivery itself re-reads that state, so a missed + * event can no longer pick the wrong channel. */ function NotifyObserver(props) { - const focus = useFocus() + useWindowState() const useSessions = props.useSessions const useSessionStatus = props.useSessionStatus const select = React.useCallback((snapshot) => snapshot, []) @@ -894,7 +1002,7 @@ window.__ModuleLoader__.load({ applyHealth(store, { state: 'starting', message: '' }) return } - observe(focus, list, status) + observe(list, status) applyHealth(store, { state: 'watching', message: '' }) } catch (error) { applyHealth(store, { state: 'error', message: text(error) }) @@ -1037,18 +1145,38 @@ window.__ModuleLoader__.load({ type: 'button', className: 'dsn-button', disabled: !supported, - onClick: permission === 'granted' ? props.test : props.ask, + onClick: permission === 'granted' ? props.testSystem : props.ask, }, tr(!supported ? 'settings.action.unsupported' - : permission === 'granted' ? 'settings.action.test' : 'settings.action.allow')))), + : permission === 'granted' ? 'settings.action.testSystem' : 'settings.action.allow'))), + h('p', { className: 'dsn-section-desc' }, tr('config.testHint'))), h('section', { className: 'dsn-section' }, h('h3', { className: 'dsn-section-title' }, tr('config.section.status')), h('div', { className: 'dsn-row' }, h('div', { className: 'dsn-row-text' }, + h('p', { className: 'dsn-status' }, `${tr('config.diag.window')}: ${tr(windowIsAway() ? 'config.diag.away' : 'config.diag.inFront')}`), h('p', { className: `dsn-status${healthFailed ? ' dsn-status-error' : ''}`, role: healthFailed ? 'alert' : 'status', - }, healthText)))))) + }, healthText), + h('p', { className: 'dsn-status' }, deliveryText(tr))), + h('button', { + type: 'button', + className: 'dsn-button', + onClick: props.testAny, + }, tr('settings.action.testAny')))))) + } + + /** Describe the newest alert's fate in one line. */ + function deliveryText(tr) { + const last = store.getSnapshot().lastDelivery + if (last === null || last === undefined) return tr('config.diag.none') + const outcome = last.outcome.startsWith('system-refused') + ? tr('config.diag.refused') + : last.outcome === 'system' + ? tr('config.diag.system') + : tr('config.diag.popup') + return `${tr('config.diag.last')}: ${last.at} · ${outcome} · ${last.title}` } // ---------------------------------------------------------- registration @@ -1116,7 +1244,8 @@ window.__ModuleLoader__.load({ store, platform: platformKey(), ask: requestPermission, - test: sendTest, + testAny: sendTest, + testSystem: sendTestSystem, setKind: setKindEnabled, }), }, ConfigSection)) diff --git a/package.json b/package.json index 3555b4f..a8e8ca6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@dsh-plugin/session-notify", - "version": "1.0.4", + "version": "1.0.5", "private": true, "type": "module", "description": "会话完成、需要授权、需要回答时提醒你：窗口不在前台用系统通知，窗口在前台用应用内轻弹窗。",