{"_id":"@ag-dsh/dsh-web-notify","name":"@ag-dsh/dsh-web-notify","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ag-dsh/dsh-web-notify","description":"DSH web 通知提醒插件：对话完成/需要回答/需要授权/出错时通过浏览器系统通知提醒（Chrome/Edge/Firefox/Safari）","version":"0.2.0","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/AlphaGodzilla/ag-dsh-coding-plugins.git","directory":"packages/web-notify"},"type":"module","main":"lib/index.js","types":"lib/index.d.ts","exports":{".":{"types":"./lib/index.d.ts","default":"./lib/index.js"},"./client":"./lib/client.js","./cordis.patch.yml":"./cordis.patch.yml","./package.json":"./package.json"},"dsh":{"bundle":{"patch":"./cordis.patch.yml"},"client":{"platform":"web"}},"license":"MIT","engines":{"node":">=22"},"peerDependencies":{"@deepseek-ai/cordis":"^4.0.1","react":"^18.3.1"},"devDependencies":{"@deepseek-ai/cordis":"^4.0.1","@types/react":"^18.3.12","esbuild":"^0.28.2","react":"^18.3.1","typescript":"^5.9.0","vitest":"^4.1.0"},"scripts":{"build":"tsc -b && node build-client.mjs"},"_id":"@ag-dsh/dsh-web-notify@0.2.0","bugs":{"url":"https://github.com/AlphaGodzilla/ag-dsh-coding-plugins/issues"},"homepage":"https://github.com/AlphaGodzilla/ag-dsh-coding-plugins#readme","_integrity":"sha512-rymacEVvRAje+Kws/JYkidkeErEUQo5F6h8ZJyKo8WdCOOsS+iA71mv//EQHasl6mcU1v8uJJEKfSTNiJFFGWg==","_resolved":"/tmp/13293f5ec3c969ef0d3d733c92a79957/ag-dsh-dsh-web-notify-0.2.0.tgz","_from":"file:ag-dsh-dsh-web-notify-0.2.0.tgz","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-rymacEVvRAje+Kws/JYkidkeErEUQo5F6h8ZJyKo8WdCOOsS+iA71mv//EQHasl6mcU1v8uJJEKfSTNiJFFGWg==","shasum":"5deaf735b73958d1c4b9977326a01425b3d7429f","tarball":"https://registry.npmjs.org/@ag-dsh/dsh-web-notify/-/dsh-web-notify-0.2.0.tgz","fileCount":17,"unpackedSize":70029,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDgothLMrn1DUPBeNFIZ1ZGw/hnPAAgN7XXawCdEDrkmQIhAPkng1x0EAGVBc4eWIHFX89O+A5O47Y9/0ZmVrlIm3yW"}]},"_npmUser":{"name":"alphagodzilla","email":"AlphaGodzilla@protonmail.com"},"directories":{},"maintainers":[{"name":"alphagodzilla","email":"AlphaGodzilla@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-web-notify_0.2.0_1786789067630_0.40925657770072266"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-15T10:17:47.448Z","0.2.0":"2026-08-15T10:17:47.767Z","modified":"2026-08-15T10:17:48.046Z"},"maintainers":[{"name":"alphagodzilla","email":"AlphaGodzilla@protonmail.com"}],"description":"DSH web 通知提醒插件：对话完成/需要回答/需要授权/出错时通过浏览器系统通知提醒（Chrome/Edge/Firefox/Safari）","homepage":"https://github.com/AlphaGodzilla/ag-dsh-coding-plugins#readme","repository":{"type":"git","url":"git+https://github.com/AlphaGodzilla/ag-dsh-coding-plugins.git","directory":"packages/web-notify"},"bugs":{"url":"https://github.com/AlphaGodzilla/ag-dsh-coding-plugins/issues"},"license":"MIT","readme":"[中文](README.md) | [English](README.en.md)\n\n# @ag-dsh/dsh-web-notify\n\nDSH Web 通知提醒插件：对话完成、需要用户回答、需要授权、对话出错时，通过**浏览器原生系统通知**（Web Notifications API）提醒你——即使标签页在后台、窗口最小化或失焦，通知仍会出现在系统通知中心（macOS 通知中心 / Windows 操作中心）。支持 Chrome / Edge / Firefox / Safari。\n\n## Installation\n\n以最常用的 web profile 为例：\n\n```sh\n# 安装\ndsh plugin --profile web add @ag-dsh/dsh-web-notify\n\n# ⚠️ 安装后必须重启 dsh 才会加载：先退出当前 dsh 进程，再重新启动\ndsh --profile web\n```\n\n> `dsh plugin add` 只负责安装并登记进 `dsh.profile.bundles`（profile 的\n> `package.json`）；运行中的进程在启动时才组合配置树，热更新不监视 bundles\n> 列表，因此需要重启才生效。\n\n也可以不经过 bundle 机制，直接把插件行写入 profile 的 `cordis.yml` / `cordis.patch.yml`\n（HMR 热应用，无需重启）：\n\n```yaml\n- id: web-notify\n  name: '@ag-dsh/dsh-web-notify'\n```\n\n插件行（host 半区）只是**客户端 bundle 的载体**：dsh-client-modules 扫描已加载且声明\n`dsh.client` 的包，把其 `./client` 导出（`lib/client.js`）作为浏览器 bundle 提供给 Web 端。\n功能全部在浏览器侧运行，host 半区无业务逻辑。\n\n### 依赖的宿主服务\n\n| 服务 | 依赖方式 | 说明 |\n|---|---|---|\n| `slots`（客户端） | `ctx.get` 可选 | 注册 `shell.overlay` 后台会话引擎、`settings.plugin.item` 配置卡片与 `conversation.session.header.utilities` 观察引擎 |\n| `sessions`（客户端） | `ctx.get` 可选 | 点击通知时跳转到对应会话 |\n| `timer`（客户端） | `inject` 硬依赖 | 通知 12 秒后自动关闭 |\n\n## Usage\n\n1. **安装并重启后**，打开 **设置 → 插件 → 插件配置**，找到 **Web 通知** 卡片（`settings.plugin.item`），默认模式为**始终**（前台/后台都通知）、提示音默认**开启**。\n2. 在配置页点击**「开启通知」**并允许浏览器权限请求（Firefox / Safari 必须从该按钮发起，这是浏览器的用户手势要求）。\n3. 以下时刻会弹出系统通知（「始终」模式下前台也通知，可切回「仅后台」减少打扰）：\n   - **对话完成**：任一会话的 turn 结束；\n   - **需要你的回答**：助手调用 `ask_user_question` 提问（含 plan-review 计划确认）；\n   - **需要授权**：出现待决授权请求；\n   - **对话出错**：当前会话出现错误。\n4. **点击通知**可聚焦窗口并跳转到对应会话。\n5. 配置页控件：\n   - **通知模式**：三选一（**仅后台**=窗口失焦时通知；**始终**=前台也通知，默认；**关闭**=不通知）；\n   - **提示音**：开启/关闭开关（默认开启；不同事件音调不同：完成 1 声、提问/授权 2 声、出错 3 声），附「🎵 试听」按钮可依次播放三种提示音；\n   - **通知权限**：显示当前状态（已允许 / 未开启 / 被拒绝），「被拒绝」时需在浏览器站点设置中手动允许 `127.0.0.1`（或部署域名）。\n\n## Config\n\n无。\n\n## 模型可见文本\n\n以下为**稳定契约**：通知标题与正文由 `src/core.ts` 的 `notificationSpec` 生成，\n改动需同步本表与测试（`tests/index.spec.ts`）。\n\n| 事件 | 标题 | 正文（按优先级） |\n|---|---|---|\n| 对话完成 | 对话完成 | 「[会话标题] 最后回复摘要」（截断 220 字）→ 会话标题 → 「助手已回复，点击查看」 |\n| 需要回答 | 需要你的回答（多个问题时标注「（N 个问题）」） | 问题原文（截断 220 字）→ 会话标题 → 「请回答助手的问题」 |\n| 需要授权 | 需要授权（子代理会话标注「（子代理）」） | 「[会话标题] 工具名：原因」→ 会话标题 → 「需要你的授权」 |\n| 对话出错 | 对话出错 | 错误信息（截断 160 字）→ 「对话运行出错」 |\n\n通知正文在截断前会先压缩连续空白（含换行），保证单行可读；授权通知含发起会话标题与工具/原因，提问通知含问题数量与第一问原文，便于在系统通知中心直接判断是否需要处理。\n\n设置页文案（`src/core.ts` 的 `NOTIFY_MODE_LABELS`）：`仅后台` / `始终` / `关闭`；\n按钮文案：`开启通知` / `通知被拒` / `通知不可用`。\n\n## Behavior\n\n- **信号来源**：直接订阅 DSH Web 端已有的会话状态快照（`useSessions` / `useSession`，\n  由 websocket 推送驱动，**非轮询**），无 Host RPC、无额外网络请求。\n- **覆盖范围**：`shell.overlay` 引擎（不可见）观察**所有会话**（含后台会话/子代理）的\n  `running` 与 `pendingInteraction` 边沿；`conversation.session.header.utilities`\n  引擎提供**当前会话**的富文本通知（问题原文、授权工具名与原因、错误信息），\n  该槽位位于 composer 接管区域之外，提问/授权卡片弹出时观察不会中断。\n- **防误报**：每个观察点首次观察只记录基线（页面加载、切换会话、会话加入列表\n  均不误报）；通知 `tag = dsh-notify:<kind>:<sessionId>`，同会话同类通知在\n  系统通知中心互替，不堆积。\n- **浏览器兼容**：`Notification` API 为 Chrome / Edge / Firefox / Safari 原生支持；\n  `127.0.0.1` / `localhost` 属安全上下文，可正常申请权限。\n- **可逆副作用**：所有 Slot 注册（观察引擎与设置页）随插件 fiber 清理，定时器经\n  `ctx.timeout`（`timer` 服务），HMR/热更新安全。\n\n## Known Limitations and Deferred Work\n\n- **浏览器完全退出或标签页关闭时无法通知**：本插件为页面内原生通知，不依赖服务端\n  推送；需要「浏览器关闭也能收到」需接入 Web Push（Chrome 需 FCM、Safari 需 APNs），\n  本地 127.0.0.1 服务无法接入，不在本包范围。\n- **模式与提示音为进程内内存态**：页面刷新后重置为「始终 / 开启」；浏览器级\n  通知权限本身由浏览器持久化，不受影响。\n- **出错通知仅覆盖当前打开会话**：后台会话出错时，其 turn 结束会以「对话完成」\n  通知提示（`running` 回落是两者共用的信号）。\n- **多标签页**各自触发通知，靠 `tag` 互替避免同屏堆积。\n- **会话列表加载中的瞬时快照**：列表首次构建前 `items` 可能短暂为空，已做防御\n  （空数组处理），不会崩溃或误报。\n- **提示音受浏览器自动播放策略约束**：需先在设置页点击过一次任意按钮（如「🎵 试听」）后才可能\n  出声；不满足时静默降级。\n","readmeFilename":"README.md","_rev":"1-a46c4a6a18c90e9086375225d6105699"}