dsh-plugin-desktop-notify 0.5.6 → 0.6.0

package/README.en.md

@@ -1,214 +1,119 @@
 # dsh-plugin-desktop-notify
 
-Codex-style **macOS notifications and a Dock unread badge** for the
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) desktop app.
-
-- A native banner, attributed to **DeepSeek Harness itself**, when a turn finishes
-  **even while the window is in the background**, when a tool approval / question /
-  plan review is waiting, or when a turn fails.
-- **Click the banner to jump back to that session** and raise the window.
-- The Dock icon keeps a number for every session that needs you until you actually
-  look at it.
-
-[中文](README.md) · MIT
+Desktop notifications and an app-icon badge for DSH: a finished turn, a pending approval or question, and a failure, with click-through back to that session.
 
 ## What it does
 
-| Event | Banner | Dock badge |
-|---|---|---|
-| A turn finishes while you are not watching it | “Task completed” + “「name」Completed in 3m 12s” | +1 |
-| A tool approval / question / plan review is waiting | “Approval needed” / “Your reply is needed” / “Plan review needed” | +1 |
-| A turn fails | “Task failed” + the error summary | +1 |
-| You open (and look at) that session | — | cleared |
-
-Rules:
-
-- **A notification always implies a badge**: both read the same attention facts.
-- **“Watching” means** the session is in the main view **and** the window is focused
-  **and** visible. The harness’s own `completionUnread` only covers the first case;
-  a backgrounded window is invisible to the host, so the plugin adds the
-  focus/visibility half itself with `document.hasFocus()` / `visibilityState`.
-- **The badge is sticky** until you actually look at the session; the harness
-  clearing `completionUnread` does not silently drop it.
-- A failed turn posts the error banner only, never an extra “completed” one.
-- Sessions of subagents / Agent Teams members are ignored.
-
-## Requirements
-
-- Tested on **DSH Desktop 0.2.1-rc.3** (Electron **44.7.0**) on **macOS**.
-- The desktop shell must register `dsh-app://` as a secure context (current builds do),
-  otherwise `navigator.setAppBadge` and `Notification` are unavailable
-  (`capabilities()` in DevTools reports `badge: false`).
-- System Settings → Notifications → **DeepSeek Harness** must be allowed, otherwise
-  you get the badge without banners.
-- **Windows / Linux: untested, but expected to work.** Both surfaces are plain web
-  APIs: Electron has supported the Badging API on Windows since v29 (taskbar overlay,
-  see [the v29.1.5 Windows badge fix](https://releases.electronjs.org/release/v29.1.5)),
-  and `Notification` maps to Windows toasts. The real caveat is that Windows toasts
-  need an AppUserModelID plus a Start Menu shortcut, and the DSH main process never
-  calls `app.setAppUserModelId`, so whether banners appear depends on the shortcut
-  the installer writes.
-- The only genuinely macOS-only code is the **optional host fallback**
-  (`osascript` / `afplay` / `lsappinfo`), disabled by default.
-- To check a platform: run `capabilities()` (it reports `platform`) and then
-  `simulateComplete()`, and open an issue with the result.
-
-### Banner click does nothing?
-
-Read `__DSH_DESKTOP_NOTIFY__.state().lastClick`:
-
-- `null` → the click never reached the renderer. Rare on macOS, **common on Windows**:
-  WinRT toast activation needs a registered COM activator
-  ([electron/electron#24524](https://github.com/electron/electron/issues/24524)), and without
-  one the click may simply dismiss the toast. A plugin cannot fix that layer.
-- `opened.ok: false` → the click arrived but the session switch failed; `opened.attempts`
-  says why (`uiWorkspace` unreachable, `retain` failed, …). Since v0.5.2 the plugin declares
-  `uiWorkspace` as a dependency (the same way the official `ui-chat` plugin does), which is
-  what made the macOS click fail to switch sessions before.
-- `opened.ok: true` but the view did not change → the window was hidden; the click only
-  activates the app, so bring it forward from the Dock/taskbar.
-
-The click path can be exercised directly with `__DSH_DESKTOP_NOTIFY__.openSession("<session id>")`.
-
-### Windows: the click switches the session, but the window may stay behind
-
-Not something a plugin can fix. The click reaches the renderer (since v0.5.2
-`lastClick.opened.ok === true` and the session really switches), but raising the main
-window needs the main process (`BrowserWindow.show()` / `focus()`) or a registered
-AppUserModelID. The renderer only has `webContents.focus()`, and Windows' foreground
-lock ignores requests from non-foreground processes.
-
-Two upstream fixes, either works:
-
-1. Call `app.setAppUserModelId("com.deepseek.dsh")` in the desktop main process and ship a
-   Start Menu shortcut with the same AUMID — Windows then activates the app on toast
-   clicks, so the window comes forward.
-2. Expose a "focus window" IPC channel the renderer can call.
-
-Until then: if the window does not surface, click the taskbar/tray icon — **the session
-is already selected**.
-
-### Windows: badge appears, no banner
-
-**Fixed in v0.4.4**: older builds passed a long `tag`
-(`dsh-plugin-desktop-notify:complete:<sessionId>`), and Windows 11 silently drops web
-notifications whose tag is longer than ~34 characters
-([electron/electron#40433](https://github.com/electron/electron/issues/40433)). The
-plugin no longer sets `tag` / `silent`; dedupe relies on status edges, which is why a
-bare `new Notification("t",{body:"b"})` showed up while the plugin's banner did not.
-
-If it still fails after upgrading, use the checks below:
-
-
-The badge is a taskbar overlay and needs no AppUserModelID. **Windows toasts do need an
-AppUserModelID plus a Start Menu shortcut**, and the DSH main process never calls
-`app.setAppUserModelId` (checked `lib/main.js`), so Windows can drop the toast silently —
-it is not the plugin's logic. Confirm with:
-
-```js
-new Notification("test", { body: "windows toast check" })  // nothing here means app-level
-__DSH_DESKTOP_NOTIFY__.state().lastNotify                   // the last delivery attempt
-```
+- **Turn finished** — including while the window is backgrounded or another app is in front
+- **You are needed** — a tool approval, a question, or a plan waiting for confirmation
+- **Turn failed** — the error is summarised in the body
+- **Badge** — the app icon carries the number of sessions that need you, cleared once you have looked
+- **Click a notification** — it switches to that session instead of only raising the app
 
-Two ways out: DSH sets `app.setAppUserModelId` upstream (then the current code shows toasts
-with click-through), or the host half falls back to a PowerShell toast (visible, but
-attributed to Windows PowerShell and without click-through).
+Subagent sessions are skipped by default.
 
 ## Install
 
-Inside the DSH desktop app: **Plugins → Install**, then paste the package name:
+DSH desktop → **Plugins** → Install, then paste the package name:
 
 ```
 dsh-plugin-desktop-notify
 ```
 
-Press **⌘R** afterwards so the renderer reloads the bundle (restart the app if it
-says `restart-required`). To update, uninstall and install it again.
+Press **⌘R** afterwards. The GitHub address
+(`https://github.com/chendaleiQ/dsh-plugin-desktop-notify`) and an absolute local
+directory work the same way.
+
+## Preferences
 
-Without access to npmjs.com (or offline), the repository address
-(`https://github.com/chendaleiQ/dsh-plugin-desktop-notify`) and a local checkout
-directory both work the same way.
-For development, symlink it into the profile:
+Stored in localStorage under `dsh-plugin-desktop-notify.preferences`:
 
-```bash
-git clone https://github.com/chendaleiQ/dsh-plugin-desktop-notify.git
-cd dsh-plugin-desktop-notify
-ln -s "$PWD" ~/.dsh/profiles/desktop/node_modules/dsh-plugin-desktop-notify
-# then add "dsh-plugin-desktop-notify" to dsh.profile.bundles in
-# ~/.dsh/profiles/desktop/package.json
-```
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `notifications` | `true` | Master switch |
+| `notifyComplete` | `true` | Notify when a turn finishes |
+| `notifyPending` | `true` | Notify for an approval / question / plan |
+| `notifyError` | `true` | Notify when a turn fails |
+| `notifyViewed` | `false` | Also notify for the session you are looking at |
+| `badge` | `true` | Show the badge |
+| `excludeSubagents` | `true` | Ignore subagent sessions |
+| `titleComplete` / `titlePending` / `titleError` | empty | Custom titles; empty keeps the built-in copy |
+| `maxBodyChars` | `140` | Body length limit |
+
+## Language
+
+The copy follows DSH's language setting (Settings → General → Language): Chinese
+by default, English once the app is switched.
 
 ## Self-check
 
-Open DevTools (`⌘⌥I`) in the app window:
+From the renderer console:
 
 ```js
-__DSH_DESKTOP_NOTIFY__.capabilities()       // {notification:"granted", badge:true, ...}
-__DSH_DESKTOP_NOTIFY__.state()              // live attention + badge number
-__DSH_DESKTOP_NOTIFY__.simulateComplete()   // fire a banner and set the badge to 1
-__DSH_DESKTOP_NOTIFY__.reset()              // undo the simulation
-__DSH_DESKTOP_NOTIFY__.state().lastClick    // what the last banner click did
-__DSH_DESKTOP_NOTIFY__.openSession("<session id>")  // run the click path manually
+__DSH_DESKTOP_NOTIFY__.capabilities()
+__DSH_DESKTOP_NOTIFY__.state()
+__DSH_DESKTOP_NOTIFY__.report()
 ```
 
-## Preferences
 
-No settings UI; preferences live in the renderer’s `localStorage`
-(desktop and web profiles are independent), applied after ⌘R:
+## Notification interface for other tools
 
-```js
-localStorage.setItem("dsh-plugin-desktop-notify:preferences", JSON.stringify({
-  notifications: true,    // banners master switch
-  notifyComplete: true,
-  notifyPending: true,    // approvals / questions / plan reviews
-  notifyError: true,
-  notifyViewed: false,    // true = also banner the session you are watching
-  badge: true,            // Dock badge master switch
-  excludeSubagents: true,
-  // empty = built-in copy, following the UI language (zh/en)
-  titleComplete: "",
-  titlePending: "",
-  titleError: "",
-  maxBodyChars: 140
-}))
+The Host half exposes two loopback routes for scripts, browser agents and cron
+jobs:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/desktop-notify/request` | Post one notification: `{"title": "...", "body": "...", "sessionId": "optional"}` |
+| `GET` | `/desktop-notify/pending` | The renderer drains what is waiting (scripts do not call it) |
+
+The address is written to `~/.dsh/desktop-notify.endpoint`, so callers never guess
+the port:
+
+```bash
+curl -s "$(cat ~/.dsh/desktop-notify.endpoint)" \
+  -H 'content-type: application/json' \
+  -d '{"title":"BrowserOS needs you","body":"A takeover request is waiting"}'
 ```
 
-## How it works
+Python:
 
-Both surfaces only exist in the desktop **renderer**, not in the Host process:
+```python
+import json, pathlib, urllib.request
 
-| Capability | API | Lands at |
-|---|---|---|
-| Native banner + click callback | `new Notification(...)` / `onclick` | Electron → macOS Notification Center, attributed to DeepSeek Harness |
-| Dock badge | `navigator.setAppBadge(n)` / `clearAppBadge()` | Chromium → Electron `BadgeManager` → `NSDockTile.badgeLabel` |
+url = pathlib.Path.home().joinpath(".dsh/desktop-notify.endpoint").read_text().strip()
+request = urllib.request.Request(
+    url,
+    data=json.dumps({"title": "BrowserOS needs you", "body": "A takeover request is waiting"}).encode(),
+    headers={"content-type": "application/json"},
+)
+urllib.request.urlopen(request, timeout=3).read()
+```
 
-Facts come from the harness’s own `uiSession.sessionStatus`
-(`completionUnread`, `pendingInteraction`, the same data the sidebar dots read) plus
-`api-session/error` for failures, so “read” means exactly what the official UI means.
+Notes:
 
-The Host half (`index.js`) is an **osascript fallback, disabled by default**: flip
-`enabled` in `cordis.patch.yml` if a renderer has no `Notification` (enabling both
-double-notifies).
+- The banner is posted by **DSH itself** (attributed to DeepSeek Harness), not by
+  a script host
+- Clicking it raises the window; with `sessionId` it also switches to that session
+- The interface binds loopback only and needs no login; `enabled: false` switches
+  off the osascript fallback, not the interface
 
-## Development
+## Known limits
+
+- **Windows**: clicking a notification switches the session, but the window does
+  not always come to the front — the AppUserModelID and a main-process focus
+  channel are the desktop app's to provide
+- **Attribution**: the notification centre shows DeepSeek Harness, because the
+  banner is a renderer-side native notification
+- **Host half** (`index.js`, an osascript fallback) is off by default; switch it on
+  only when a renderer cannot post notifications
 
-Zero dependencies, hand-written ES modules, no build step.
+## Development
 
 ```bash
-node test/client.test.mjs                     # renderer half: node:vm + stubbed globals
-node test/host.test.mjs /tmp/host-test.log    # host fallback
-npm test
+node test/client.test.mjs
+node test/host.test.mjs
 ```
 
-## Limitations
-
-- macOS is verified; Windows / Linux are untested (see Requirements).
-- “Stuck” covers waiting-for-approval / question / plan review / failure; a
-  “still running but silent for N minutes” watchdog would need a host timer.
-- Badge facts live in host memory and reset when the app restarts (harness semantics).
-- Conflicts with `@caohaoyangcn/dsh-dock-badge` (badge-only, with a settings page):
-  install only one, they fight over the same Dock badge.
-
 ## License
 
-MIT — use it however you like.
+MIT · https://github.com/chendaleiQ/dsh-plugin-desktop-notify

package/README.md

@@ -1,238 +1,109 @@
 # dsh-plugin-desktop-notify
 
-给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 桌面版补上 **Codex 风格的系统通知 + 程序坞小红点**：
+给 DSH 加**桌面通知 + 应用图标小红点**：任务完成、等待你操作、任务失败时提醒你，点通知直接回到那个会话。
 
-- 任务跑完（**包括窗口在后台/最小化时**）弹一条 **DeepSeek Harness 自己发的** macOS 横幅；
-- 有工具等你审批、有提问等你回答、有计划等你确认时弹「需要你确认」；
-- 任务出错时弹「任务出错」，正文带错误摘要；
-- **点横幅直接回到那个会话**并抬起窗口；
-- 需要你处理的会话在 Dock 图标上留一个数字，直到你真的看过它才清零。
+## 它做什么
 
-[English](README.en.md) · MIT
+- **任务完成**——包括窗口切到后台、你在别的应用里的时候
+- **等待你操作**——工具审批、提问、执行计划确认
+- **任务失败**——这一轮出错时提示
+- **小红点**——应用图标上显示「需要你的会话数」，你看过之后才清零
+- **点击通知**——切到对应会话，而不是只把应用叫到前面
 
-## 和 Codex 桌面版对齐
-
-| Codex 桌面版 | 这里 |
-|---|---|
-| Settings → Notifications → **Task completion** | 标题「任务已完成」，正文「对话名」已完成，用时 3 分 12 秒 |
-| Settings → Notifications → **Approval required** | 标题「等待你的批准」，正文「对话名」请求使用 Bash，等待你的批准 |
-| 等你回复（提问 / 计划确认） | 标题「等待你的回答」/「等待你的确认」，正文带会话名 |
-| 任务失败 | 标题「任务执行失败」，正文带会话名与错误摘要 |
-| Dock 徽标 | 数字 = **当前需要你的会话数**；打开该会话即清 |
-
-规则：
-
-- **有通知就有红点**：两者读同一份 attention 事实，弹了横幅就一定进徽标。
-- **「在看」才算看过**：`主视图是它` **且** `窗口有焦点` **且** `窗口可见`，三者同时成立才不打扰。
-  宿主的 `completionUnread` 只覆盖第一种（切到别的会话）；窗口被切到后台时它看不见，
-  这部分由插件用 `document.hasFocus()` / `visibilityState` 自己补——否则最常见的那种
-  「切到别的 App 等它跑完」永远不会提醒。
-- **红点粘住**：弹过横幅的会话，红点保留到你真的切回来并看着它；宿主把 `completionUnread`
-  清掉并不会让红点消失。
-- **失败不重复播**：一轮以错误结束时只发「任务出错」，不再补一条「任务完成」。
-- 子会话（subagent / Agent Teams 成员）不弹不计；同一会话同类横幅用 `tag` 覆盖，不堆一屏。
-
-## 兼容性
-
-- **已在 macOS 实测**：DSH Desktop 0.2.1-rc.3（Electron 44.7.0）。
-- 需要桌面端把 `dsh-app://` 注册为 secure context（现版本就是这么做的），否则渲染层拿不到
-  `navigator.setAppBadge` 与 `Notification`；`capabilities()` 自检里会显示 `badge: false`。
-- 系统设置 → 通知 → **DeepSeek Harness** 必须是允许状态，否则只有红点没有横幅。
-- **Windows / Linux：未实测，但理论上可用**。渲染层用的是标准 Web API：
-  Electron 从 29 起支持 Windows 上的 Badging API（任务栏 overlay，修过 [Windows 下徽标文字不显示](https://releases.electronjs.org/release/v29.1.5)），
-  `Notification` 走 Windows toast。真正的风险在 Windows 的 toast 需要 AppUserModelID +
-  开始菜单快捷方式，而 DSH 主进程没有显式 `setAppUserModelId`（我查过 `lib/main.js`），
-  所以能不能出横幅取决于安装包写的快捷方式。
-- **唯一确定只在 macOS 的是宿主兜底那半边**（`osascript` / `afplay` / `lsappinfo`），
-  它默认关闭，只在你没有 `Notification` 时才需要。
-- 想验证 Windows：跑一次 `capabilities()`（会带上 `platform`），再 `simulateComplete()`，
-  看 toast 与任务栏数字是否出现，把结果开个 issue 就行。
-
-### 点击通知没反应？
-
-先看 `__DSH_DESKTOP_NOTIFY__.state().lastClick`：
-
-- `null` → 点击事件根本没送到渲染层。macOS 上基本不会；**Windows 上很常见**：Electron 的 WinRT toast 点击激活需要 COM activator 注册（[electron/electron#24524](https://github.com/electron/electron/issues/24524)），没注册时点横幅可能只是把系统通知收起。这一层插件修不了。
-- `opened.ok: false` → 点击到了，但切会话失败，`opened.attempts` 里写着原因（`uiWorkspace` 服务不可达 / `retain` 失败等）。
-  v0.5.2 起插件把 `uiWorkspace` 声明成了依赖（和官方 `ui-chat` 插件一致），此前它在这个插件里是取不到的——这就是 macOS 上「点击只激活应用、不切会话」的原因。
-- `opened.ok: true` 但界面没变 → 窗口被藏起来了（点横幅只激活应用，不一定会显示窗口），手动点 Dock/任务栏图标把窗口调出来即可。
-
-也可以直接验证切会话这条链路：`__DSH_DESKTOP_NOTIFY__.openSession("<会话 id>")`。
-
-### Windows：点通知切会话成功，但窗口不一定到最前
-
-这不是插件能修的：点击事件已经送到渲染层（v0.5.2 起 `lastClick.opened.ok === true`，会话也确实切了），
-但把**主窗口提到前台**需要主进程的 `BrowserWindow.show()` / `focus()`，或者系统层面的
-AppUserModelID 注册；渲染层只有 `webContents.focus()`，而 Windows 的前台锁定会忽略来自
-非前台进程的请求。
-
-两种上游修法（任一即可）：
-
-1. 桌面端主进程调用 `app.setAppUserModelId("com.deepseek.dsh")`，并让安装包写出带同一 AUMID
-   的开始菜单快捷方式——Windows 就会在点击 toast 时激活应用，窗口自然到前台。
-2. 主进程暴露一个「focus window」的 IPC 通道，让插件请求抬窗。
-
-在此之前：点通知后若窗口没上来，点任务栏/托盘图标即可，**会话已经切好了**。
-
-### Windows 上「有红点、没横幅」
-
-**v0.4.4 已修**：旧版本给每条通知带了一个很长的 `tag`（`dsh-plugin-desktop-notify:complete:<sessionId>`），
-而 Windows 11 会**静默丢弃 tag 长度超过约 34 字符的 Web Notification**（[electron/electron#40433](https://github.com/electron/electron/issues/40433)）。
-现在不再设置 `tag` / `silent`，去重改由状态边沿判断完成——所以裸 `new Notification("t",{body:"b"})` 能弹、
-插件的不弹，正是这个原因。
-
-如果升级后仍不弹，再按下面排查：
-
-
-红点走的是任务栏 overlay，不需要 AppUserModelID；**Windows toast 需要 AppUserModelID +
-开始菜单快捷方式**才会显示。DSH 主进程没有调用 `app.setAppUserModelId`（`lib/main.js` 里没有
-这行），所以 toast 很可能被 Windows 静默丢弃——这不是插件逻辑问题。先确认：
-
-```js
-new Notification("test", { body: "windows toast check" })  // 连这条都不弹 = 应用层问题
-__DSH_DESKTOP_NOTIFY__.state().lastNotify                   // 插件最后一次投递的结果
-```
-
-两条路：等 DSH 主进程补上 `app.setAppUserModelId`（那时现有代码就能正常出 toast 并支持点击）；
-或改用宿主侧 PowerShell toast 兜底（能提示，但归属会显示成 Windows PowerShell，点击无法跳回会话）。
+子智能体的会话默认不提醒（可在偏好里打开）。
 
 ## 安装
 
-### 方式一：npm（推荐）
-
-DSH 桌面版左侧栏 **插件** → **安装**，填包名：
+DSH 桌面版 → 左侧栏「插件」→ 安装，填包名：
 
 ```
 dsh-plugin-desktop-notify
 ```
 
-装完按 **⌘R** 刷新窗口（渲染层要重新加载）。提示 `restart-required` 就重启一次应用。
-更新：插件页里卸载再装一次即为最新版。
+装完按 **⌘R** 刷新窗口。也可以填 GitHub 地址
+（`https://github.com/chendaleiQ/dsh-plugin-desktop-notify`）或本地目录的绝对路径。
 
-> 国内网络可以给 npm 配镜像（`npm config set registry https://registry.npmmirror.com`），
-> 或者直接用下面的 GitHub / 本地方式。
+## 偏好
 
-### 方式二：从 GitHub 安装
+存在浏览器 localStorage 的 `dsh-plugin-desktop-notify.preferences`：
 
-插件页 → 安装 → 填仓库地址：
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `notifications` | `true` | 总开关 |
+| `notifyComplete` | `true` | 任务完成时通知 |
+| `notifyPending` | `true` | 等待审批 / 回答 / 计划确认时通知 |
+| `notifyError` | `true` | 任务失败时通知 |
+| `notifyViewed` | `false` | 正在看的会话也通知（默认跳过） |
+| `badge` | `true` | 显示小红点 |
+| `excludeSubagents` | `true` | 忽略子智能体会话 |
+| `titleComplete` / `titlePending` / `titleError` | 空 | 自定义标题，空 = 用内置文案 |
+| `maxBodyChars` | `140` | 正文长度上限 |
 
-```
-https://github.com/chendaleiQ/dsh-plugin-desktop-notify
-```
+## 语言
 
-### 方式三：本地目录
+跟随 DSH 的语言设置（设置 → 通用 → 语言）：默认中文，切成英文后通知文案同步变成英文。
 
-```bash
-git clone https://github.com/chendaleiQ/dsh-plugin-desktop-notify.git
-```
+## 自检
 
-插件页 → 安装 → 填这个目录的**绝对路径**（目录，不是文件）：
+渲染层控制台：
 
-```
-/path/to/dsh-plugin-desktop-notify
+```js
+__DSH_DESKTOP_NOTIFY__.capabilities()   // 平台、通知权限、小红点、服务可达性
+__DSH_DESKTOP_NOTIFY__.state()          // 小红点、待处理会话、最近一次通知/点击
+__DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于排查
 ```
 
-### 方式四：开发调试（直接 link 进 profile）
 
-```bash
-git clone https://github.com/chendaleiQ/dsh-plugin-desktop-notify.git
-cd dsh-plugin-desktop-notify
-ln -s "$PWD" ~/.dsh/profiles/desktop/node_modules/dsh-plugin-desktop-notify
-# 再把 dsh-plugin-desktop-notify 加进 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles
-```
+## 给其它工具用的通知接口
 
-改完代码按 ⌘R 重载渲染层即可（Host 那半边改动需要重启应用）。
+宿主半边在**回环地址**上开了两个路由，供脚本、浏览器代理、定时任务调用：
 
-## 自检
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| `POST` | `/desktop-notify/request` | 发一条通知，body：`{"title": "...", "body": "...", "sessionId": "可选"}` |
+| `GET` | `/desktop-notify/pending` | 渲染层取走待显示的通知（脚本不用调） |
 
-窗口里按 `⌘⌥I` 打开 DevTools，Console：
+地址写在 `~/.dsh/desktop-notify.endpoint`，所以调用方不用猜端口：
 
-```js
-__DSH_DESKTOP_NOTIFY__.capabilities()       // {notification:"granted", badge:true, ...}
-__DSH_DESKTOP_NOTIFY__.state()              // 当前 attention 与徽标数字
-__DSH_DESKTOP_NOTIFY__.simulateComplete()   // 立刻弹一条横幅并把 Dock 置 1
-__DSH_DESKTOP_NOTIFY__.reset()              // 清掉自检状态
-__DSH_DESKTOP_NOTIFY__.state().lastClick    // 上一次点横幅发生了什么
-__DSH_DESKTOP_NOTIFY__.openSession("<会话 id>")  // 直接按点击逻辑切会话，验证服务可达
+```bash
+curl -s "$(cat ~/.dsh/desktop-notify.endpoint)" \
+  -H 'content-type: application/json' \
+  -d '{"title":"BrowserOS 需要你","body":"有一个接管请求"}'
 ```
 
-手工验收：让一个会话跑十几秒，**切到别的 App**（失焦即可，不必切会话），跑完应看到横幅 + Dock `1`；
-点横幅回来，数字清零。
-
-## 偏好
+Python（比如监听 neo 的守护脚本）：
 
-没有设置界面，偏好放在渲染进程本地（desktop / web profile 各自独立），控制台执行后 ⌘R：
+```python
+import json, pathlib, urllib.request
 
-```js
-localStorage.setItem("dsh-plugin-desktop-notify:preferences", JSON.stringify({
-  notifications: true,    // 总开关：横幅
-  notifyComplete: true,   // 任务完成
-  notifyPending: true,    // 等审批 / 提问 / 计划确认
-  notifyError: true,      // 任务失败
-  notifyViewed: false,    // true = 盯着看它也弹（但不进红点）
-  badge: true,            // 总开关：Dock 红点
-  excludeSubagents: true, // 子会话不弹不计（建议保持）
-  // 留空 = 用内置文案（跟随界面语言 zh/en）
-  titleComplete: "",
-  titlePending: "",
-  titleError: "",
-  maxBodyChars: 140
-}))
-// 恢复默认
-localStorage.removeItem("dsh-plugin-desktop-notify:preferences")
+url = pathlib.Path.home().joinpath(".dsh/desktop-notify.endpoint").read_text().strip()
+request = urllib.request.Request(
+    url,
+    data=json.dumps({"title": "BrowserOS 需要你", "body": "有一个接管请求"}).encode(),
+    headers={"content-type": "application/json"},
+)
+urllib.request.urlopen(request, timeout=3).read()
 ```
 
-## 为什么是渲染层插件
-
-这两件事只能在桌面**渲染进程**做，Host 子进程碰不到：
-
-| 能力 | 接口 | 去处 |
-|---|---|---|
-| 原生横幅 + 点击回调 | `new Notification(...)` / `onclick` | Electron → macOS 通知中心，**归属 DeepSeek Harness** |
-| Dock 小红点 | `navigator.setAppBadge(n)` / `clearAppBadge()` | Chromium → Electron `BadgeManager` → `NSDockTile.badgeLabel` |
+要点：
 
-宿主半边（`index.js`）保留成**默认关闭的 osascript 兜底**：万一某个渲染环境没有 `Notification`，
-把 `cordis.patch.yml` 里的 `enabled` 改成 `true` 再重启——两者同时开会重复提醒。
+- 通知由 **DSH 自己弹出**（归属 DeepSeek Harness），不是 Script Editor
+- 点通知会把窗口叫到前面；带 `sessionId` 时会切到那个会话
+- 接口只监听回环地址，不需要登录；`enabled: false` 只关 osascript 兜底，不影响接口
 
-数据源用的是 Harness 自己的 `uiSession.sessionStatus`（`completionUnread` / `pendingInteraction`，
-和侧边栏状态点同源）+ `api-session/error`（失败），插件不自己记账，所以「读过」的语义和官方 UI 一致。
-
-## 目录
-
-```
-dsh-plugin-desktop-notify/
-├── package.json          # dsh.bundle.patch + dsh.client（渲染层入口与 inject 顺序）
-├── cordis.patch.yml      # desktop-notify 一行（宿主兜底默认 enabled: false）
-├── lib/client.js         # 渲染层：横幅 + 点击跳转 + Dock 徽标
-├── index.js              # Host 半边：osascript 兜底，默认关闭
-├── test/client.test.mjs  # 渲染层测试（node:vm + 假浏览器全局）
-├── test/host.test.mjs    # 宿主兜底测试
-├── icon.svg / locale/{en,zh}.json / README(.en).md / LICENSE
-```
+## 已知限制
 
-## 开发与测试
+- **Windows**：点通知会切到对应会话，但窗口不一定到前台——`AppUserModelID` 和主进程 focus 通道属于桌面端，渲染层插件做不到
+- **通知归属**：系统通知中心里显示为 DeepSeek Harness（用的是渲染层原生通知）
+- **宿主半边**（`index.js`，osascript 兜底）默认关闭；只有渲染层拿不到 `Notification` 时才需要打开
 
-零依赖，手写 ES 模块，无构建步骤。
+## 开发
 
 ```bash
-node test/client.test.mjs                     # 渲染层：node:vm + 假 window/navigator/Notification
-node test/host.test.mjs /tmp/host-test.log    # 宿主兜底：假 ctx + 合成 session/event
-npm test                                      # 两个都跑
+node test/client.test.mjs      # 渲染层：文案、小红点、点击链路
+node test/host.test.mjs        # 宿主兜底：dryRun 下的事件处理
 ```
 
-渲染层测试覆盖 40+ 项断言：边沿只弹一次、后台窗口算「没在看」、红点粘住到真看过、
-完成/审批/失败各自增减、失败不重复播、子会话排除、各偏好开关。
-
-## 已知限制
-
-- macOS 已实测；Windows / Linux 未实测（见上面「兼容性」）。
-- 「卡住」目前覆盖**等待审批 / 提问 / 计划确认 / 失败**；没有做「还在 running 但长时间无输出」
-  的超时判定（需要宿主侧定时器）。
-- `completionUnread` 与失败事实在宿主内存里，重启应用从零开始（官方语义）。
-- 点击横幅若对应会话已归档，只会抬窗。
-- 与 [`@caohaoyangcn/dsh-dock-badge`](https://www.npmjs.com/package/@caohaoyangcn/dsh-dock-badge)
-  功能重叠（那个只做徽标、带设置页），**两个都装会抢写同一个 Dock 徽标，只留一个**。
-
-## License
+## 协议
 
-MIT，随便用、随便改、随便发。
+MIT · 仓库 https://github.com/chendaleiQ/dsh-plugin-desktop-notify

package/index.js

@@ -15,9 +15,9 @@
  */
 
 import { execFile, spawn } from "node:child_process"
-import { appendFile, mkdir } from "node:fs/promises"
+import { appendFile, mkdir, rm, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
-import { basename, dirname } from "node:path"
+import { basename, dirname, join } from "node:path"
 
 /** Read the notification in argv order, so no AppleScript string escaping is needed. */
 const APPLESCRIPT = [
@@ -42,6 +42,14 @@ const DEFAULTS = {
   maxTrackedSessions: 64,
   /** Log the decision without spawning osascript/afplay; the tests use it. */
   dryRun: false,
+  /** Local interface other tools post notifications to (see README). */
+  api: true,
+  /** Where the endpoint URL is written for those tools. */
+  endpointPath: "~/.dsh/desktop-notify.endpoint",
+  /** Longest accepted request body. */
+  apiBodyLimit: 8192,
+  /** How many unread requests the interface keeps. */
+  apiQueueLimit: 50,
 }
 
 /** Turn-end bodies for the kinds that carry no model text. */
@@ -52,6 +60,172 @@ const TURN_END_BODIES = {
   "max-tokens": () => "输出达到上限，本轮结束",
 }
 
+/** The URL path tools post to, and the path the renderer drains. */
+const API_REQUEST_PATH = "/desktop-notify/request"
+const API_PENDING_PATH = "/desktop-notify/pending"
+
+/** Read one JSON request body, bounded by `limit` bytes. */
+function readBody(request, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    request.on("data", (chunk) => {
+      size += chunk.length
+      if (size > limit) {
+        reject(new Error("body too large"))
+        request.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    request.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")))
+      } catch (error) {
+        reject(error)
+      }
+    })
+    request.on("error", reject)
+  })
+}
+
+/** Write one JSON answer with the headers a local tool needs. */
+function answer(response, status, payload) {
+  const body = JSON.stringify(payload)
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    "cache-control": "no-store",
+    "access-control-allow-origin": "*",
+    "access-control-allow-headers": "content-type",
+  })
+  response.end(body)
+}
+
+/**
+ * Mount the local notification interface other tools (a watch script, a
+ * browser agent, a cron job) post to.
+ *
+ * The interface is two loopback HTTP routes on the Host's own web server: POST
+ * a request, and the renderer drains the queue over the app protocol. The
+ * renderer shows the banner, so it is attributed to DeepSeek Harness rather
+ * than to a script host. Nothing here needs authentication: the server binds
+ * loopback, and the endpoint URL is written to a file the caller can read.
+ */
+function mountInterface(ctx, config) {
+  if (!config.api) return
+  const server = (() => {
+    try {
+      return ctx.get?.("webServer")
+    } catch {
+      return undefined
+    }
+  })()
+  if (server === undefined || typeof server.register !== "function") return
+
+  const queue = []
+  const disposers = []
+
+  const post = async (request, response) => {
+    if (request.method === "OPTIONS") {
+      answer(response, 204, {})
+      return
+    }
+    if (request.method !== "POST") {
+      answer(response, 405, { ok: false, error: "use POST" })
+      return
+    }
+    let payload
+    try {
+      payload = await readBody(request, Math.max(1024, config.apiBodyLimit))
+    } catch (error) {
+      answer(response, 400, { ok: false, error: String(error?.message ?? error) })
+      return
+    }
+    const title = typeof payload?.title === "string" ? payload.title.trim() : ""
+    const body = typeof payload?.body === "string" ? payload.body.trim() : ""
+    if (title === "" && body === "") {
+      answer(response, 400, { ok: false, error: "title or body is required" })
+      return
+    }
+    queue.push({
+      at: new Date().toISOString(),
+      title: title === "" ? "DeepSeek Harness" : title,
+      body: body.slice(0, 400),
+      ...typeof payload?.sessionId === "string" && payload.sessionId !== "" ? { sessionId: payload.sessionId } : {},
+    })
+    while (queue.length > Math.max(1, config.apiQueueLimit)) queue.shift()
+    answer(response, 202, { ok: true, queued: queue.length })
+  }
+
+  const pending = (request, response) => {
+    if (request.method === "OPTIONS") {
+      answer(response, 204, {})
+      return
+    }
+    if (request.method !== "GET") {
+      answer(response, 405, { ok: false, error: "use GET" })
+      return
+    }
+    const items = queue.splice(0, queue.length)
+    answer(response, 200, items)
+  }
+
+  try {
+    disposers.push(server.register({ kind: "exact", path: API_REQUEST_PATH, handler: (request, response) => {
+      void post(request, response).catch(() => answer(response, 500, { ok: false }))
+    } }))
+    disposers.push(server.register({ kind: "exact", path: API_PENDING_PATH, handler: (request, response) => {
+      try {
+        pending(request, response)
+      } catch {
+        answer(response, 500, [])
+      }
+    } }))
+  } catch (error) {
+    void Promise.resolve(config.logPath).then((path) => noteToLog(path, `interface: ${String(error)}`))
+    return
+  }
+
+  // Hand the caller an address to post to; the port is whatever the Host took.
+  const endpointPath = expandHome(config.endpointPath)
+  const origin = (() => {
+    try {
+      return typeof server.getOrigin === "function" ? server.getOrigin() : undefined
+    } catch {
+      return undefined
+    }
+  })() ?? (typeof server.port === "number" ? `http://127.0.0.1:${server.port}` : undefined)
+  if (endpointPath !== "" && origin !== undefined) {
+    void mkdir(dirname(endpointPath), { recursive: true })
+      .then(() => writeFile(endpointPath, `${origin}${API_REQUEST_PATH}\n`, "utf8"))
+      .catch(() => {})
+  }
+
+  ctx.effect(() => () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        /* the route table is being torn down anyway */
+      }
+    }
+    if (endpointPath !== "") void rm(endpointPath, { force: true }).catch(() => {})
+  }, "desktop-notify: local interface")
+}
+
+/** Append one best-effort line to the log from outside the session machinery. */
+async function noteToLog(logPathConfig, line) {
+  try {
+    const path = expandHome(logPathConfig)
+    if (path === "") return
+    await mkdir(dirname(path), { recursive: true })
+    await appendFile(path, `${new Date().toISOString()} ${line}\n`, "utf8")
+  } catch {
+    /* logging is best effort */
+  }
+}
+
 /** Merge the row's config over the defaults, keeping field types honest. */
 function resolveConfig(raw) {
   const config = { ...DEFAULTS }
@@ -142,6 +316,7 @@ function runDetached(command, args) {
  */
 export function apply(ctx, rawConfig) {
   const config = resolveConfig(rawConfig)
+  mountInterface(ctx, config)
   if (!config.enabled) return
 
   const logPath = expandHome(config.logPath)

package/lib/client.js

@@ -30,7 +30,7 @@ window.__ModuleLoader__.load({
   factory: (require) => {
     const NS = "dsh-plugin-desktop-notify"
     /** Reported by capabilities(); keep in step with package.json (cross-machine support). */
-    const VERSION = "0.5.6"
+    const VERSION = "0.6.0"
     const PREFERENCES_KEY = `${NS}:preferences`
 
     /** Defaults; override per field with the localStorage JSON described in README. */
@@ -91,7 +91,7 @@ window.__ModuleLoader__.load({
       return name === "" ? text : `「${name}」${text}`
     }
 
-    /** The UI language drives the copy; the app always sets `<html lang>`. */
+    /** The UI language before the app's locale service answers: `<html lang>`, then the browser. */
     function activeLanguage() {
       try {
         const html = typeof document === "undefined" ? "" : document.documentElement?.lang ?? ""
@@ -104,14 +104,14 @@ window.__ModuleLoader__.load({
       return "zh"
     }
 
-    /** The copy table for the current UI language. */
-    function copy() {
-      return COPY[activeLanguage()] ?? COPY.zh
+    /** The copy table for one UI language. */
+    function copy(language) {
+      return COPY[language] ?? COPY.zh
     }
 
     /** Compact elapsed time: "42 秒" / "3 分 12 秒" / "1 小时 5 分". */
-    function durationText(milliseconds) {
-      const table = copy()
+    function durationText(milliseconds, language) {
+      const table = copy(language)
       const total = Math.max(1, Math.round(milliseconds / 1000))
       if (total < 60) return table.seconds(total)
       const minutes = Math.floor(total / 60)
@@ -243,12 +243,28 @@ window.__ModuleLoader__.load({
       }
     }
 
-    const inject = ["sessions", "uiSession", "uiWorkspace"]
+    const inject = ["sessions", "uiSession", "uiWorkspace", "locale"]
 
     /**
      * @param ctx - Client root context.
      */
     function apply(ctx) {
+      /**
+       * The app's own language, in the order DSH resolves it: the locale service
+       * (Settings → General), then `<html lang>`, then the browser. Chinese is
+       * the default; English is the only other language this plugin ships.
+       */
+      const languageOf = () => {
+        try {
+          const active = String(ctx.locale?.getSnapshot?.().active ?? "").toLowerCase()
+          if (active.startsWith("zh")) return "zh"
+          if (active.startsWith("en")) return "en"
+        } catch {
+          /* an older host without the locale service falls back below */
+        }
+        return activeLanguage()
+      }
+
       const preferences = readPreferences()
       askPermission()
 
@@ -328,6 +344,74 @@ window.__ModuleLoader__.load({
         return { ok: false, attempts }
       }
 
+      /**
+       * Banners requested by other tools: the Host half accepts POSTs on a
+       * loopback route and this half drains them over the app protocol, so the
+       * banner is a real DeepSeek Harness notification rather than a script
+       * host's.
+       */
+      const EXTERNAL_PENDING_PATH = "/desktop-notify/pending"
+      let externalTimer
+      let externalStopped = false
+      const showExternal = (item) => {
+        const title = typeof item?.title === "string" && item.title !== "" ? item.title : "DeepSeek Harness"
+        const body = typeof item?.body === "string" ? item.body.slice(0, 200) : ""
+        if (!preferences.notifications) {
+          recordNotify({ kind: "external", title, body, result: "skipped: preferences.notifications=false" })
+          return
+        }
+        if (!canNotify()) {
+          recordNotify({ kind: "external", title, body, result: "skipped: Notification unavailable" })
+          return
+        }
+        let notification
+        try {
+          notification = new Notification(title, { body })
+        } catch (error) {
+          recordNotify({ kind: "external", title, body, result: `threw: ${String(error)}` })
+          return
+        }
+        recordNotify({ kind: "external", title, body, result: "posted" })
+        notification.onclick = () => {
+          let focused = false
+          try {
+            window.focus()
+            focused = true
+          } catch {
+            /* focus is best effort */
+          }
+          const sessionId = typeof item?.sessionId === "string" && item.sessionId !== "" ? item.sessionId : null
+          const opened = sessionId === null ? undefined : openSessionTarget(sessionId)
+          lastClick = {
+            at: new Date().toISOString(),
+            kind: "external",
+            sessionId,
+            ...opened === undefined ? {} : { opened },
+            focused,
+          }
+        }
+      }
+      const pollExternal = async () => {
+        if (externalStopped || typeof fetch !== "function") return
+        try {
+          const response = await fetch(EXTERNAL_PENDING_PATH, {
+            headers: { accept: "application/json" },
+            cache: "no-store",
+          })
+          if (!response.ok) return
+          const items = await response.json()
+          for (const item of Array.isArray(items) ? items : []) showExternal(item)
+        } catch {
+          /* no Host half, or this build does not proxy the path */
+        }
+      }
+      if (preferences.notifications) {
+        externalTimer = setInterval(() => { void pollExternal() }, 2500)
+        // Node-style timers can hold a process open; the renderer's cannot.
+        externalTimer?.unref?.()
+        void pollExternal()
+      }
+
       /** Post one banner; clicking it opens the session and raises the window. */
       function notify(kind, sessionId, title, body) {
         if (!preferences.notifications) {
@@ -439,13 +523,13 @@ window.__ModuleLoader__.load({
             if (!turnStartedAt.has(sessionId)) turnStartedAt.set(sessionId, Date.now())
           }
 
-          const table = copy()
+          const table = copy(languageOf())
           const name = sessionName(summary, preferences.maxBodyChars)
 
           if (completionEdge) {
             const started = turnStartedAt.get(sessionId)
             turnStartedAt.delete(sessionId)
-            const duration = started === undefined ? "" : durationText(Date.now() - started)
+            const duration = started === undefined ? "" : durationText(Date.now() - started, languageOf())
             const title = preferences.titleComplete || table.completeTitle
             const body = bodyText(table.complete(name, duration), preferences.maxBodyChars)
             if (looking) {
@@ -498,7 +582,7 @@ window.__ModuleLoader__.load({
         const summary = summaries[sessionId]
         if (preferences.excludeSubagents && isSubagent(summary)) return
         if (isLooking(summary)) return
-        const table = copy()
+        const table = copy(languageOf())
         const raw = typeof message === "string" ? message.trim() : ""
         const text = bodyText(raw, preferences.maxBodyChars)
         const before = attention.get(sessionId) ?? {}
@@ -566,6 +650,11 @@ window.__ModuleLoader__.load({
         }
       }, "dsh-plugin-desktop-notify: failure watch")
 
+      ctx.effect(() => () => {
+        externalStopped = true
+        clearInterval(externalTimer)
+      }, "dsh-plugin-desktop-notify: external interface release")
+
       ctx.effect(() => () => {
         try {
           if (canBadge()) void navigator.clearAppBadge()
@@ -622,9 +711,9 @@ window.__ModuleLoader__.load({
           }
         },
         simulateComplete(sessionId = "desktop-notify-simulation") {
-          const table = copy()
+          const table = copy(languageOf())
           setAttention(sessionId, { completed: true })
-          notify("complete", sessionId, preferences.titleComplete || table.completeTitle, table.complete("", durationText(12000)))
+          notify("complete", sessionId, preferences.titleComplete || table.completeTitle, table.complete("", durationText(12000, languageOf())))
           applyBadge()
           return this.state()
         },

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Desktop Notifications & Dock Badge",
-    "description": "Codex-style alerts: a macOS banner for a finished turn, a pending approval or question, and a failure, plus a Dock badge counting the sessions that need you. Click the banner to open that session."
+    "title": "Desktop Notifications & Badge",
+    "description": "A system notification when a turn finishes, an approval or question is waiting, or a task fails, plus a badge on the app icon counting the sessions that need you. Click the notification to open that session."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "桌面通知与小红点",
-    "description": "对齐 Codex：任务完成、等待审批/回答、任务失败时弹 macOS 横幅，程序坞图标显示待处理会话数，点横幅回到该会话。"
+    "description": "任务完成、等待审批或回答、任务失败时弹系统通知，应用图标显示待处理数量；点通知直接回到那个会话。"
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-plugin-desktop-notify",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Codex-style macOS notifications and Dock badge for DeepSeek Harness: completion (including backgrounded windows), pending approval/question/plan, and failures, with click-through back to the session",
+  "description": "Desktop notifications and a Dock/taskbar badge for DeepSeek Harness: a finished turn, a pending approval or question, and a failure, with click-through back to the session",
   "license": "MIT",
   "main": "index.js",
   "exports": {