# @goodandready/dsh-plugin-notify 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-plugin-notify/

版本：0\.4\.9
npm 元数据更新时间：2026-11-14T12:29:17.362Z
中文译文更新时间：2026-11-16T19:12:32.057Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-plugin-notify
原文对照：https://npmcn.com/package/%40goodandready/dsh-plugin-notify/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-plugin-notify#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-plugin-notify

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：173 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-session ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.0-rc\.2，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-credentials ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.0-rc\.2
- 首次发布：2026-09-18T19:59:59.208Z
- 最新版本发布：2026-11-14T12:29:17.202Z
- 近 30 天下载量：5385（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

DSH插件:音频密钥,跨会场土司,桌面推取,IM网络呼取,和网络推取(PWA)来进行转会完成,出错和批准.

## 安装

```sh
npm install @goodandready/dsh-plugin-notify
```

也可以使用：`pnpm add @goodandready/dsh-plugin-notify`、`yarn add @goodandready/dsh-plugin-notify`、`bun add @goodandready/dsh-plugin-notify`

## README

# 📦 @goodandready/dsh-plugin-notify

### 网页推送、IM Webhook、提示音、横幅与桌面通知：回合完成、出错、等待审批全场景覆盖

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-plugin-notify.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-plugin-notify) [![license](https://img.shields.io/badge/license-MIT-10b981.svg?style=for-the-badge&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-plugin-notify/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![GoodAndReady Showcase](https://img.shields.io/badge/%F0%9F%8C%90_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-plugin-notify/README.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-plugin-notify/README.zh.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-plugin-notify/README.ru.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

### 概述 / 问题

DeepSeek Harness 已经知道回合何时完成、失败或等待审批。没有本插件时，这些事件只留在会话里。如果你同时打开多个并行会话或切换到了其他应用，不得不频繁切回窗口手动查看状态。

本插件通过五个层级全面覆盖通知场景：

1.  **音频提示音 (Web Audio)**：使用浏览器内置 Web Audio API 合成双音五声音阶提示音，在任务完成、出错或等待审批时轻柔提示，无需外部音频文件。
2.  **跨会话屏幕横幅 (In-App Toasts)**：在界面上方显示浮动通知卡片，带有交互式\*\*“跳转至会话”\*\*按钮，可一键切换到触发事件的目标会话。
3.  **桌面 / 系统级通知 (OS Push)**：通过 HTML5 `Notification API` 触发 Windows、macOS、Linux 及 DSH 桌面端系统原生通知，点击自动聚焦窗口并跳转会话。
4.  **远程 IM Webhook**：向飞书、企业微信、钉钉、Slack、Discord 或自定义 HTTP 接口投递 JSON 负载。Webhook URL 作为机密安全保存在 DSH 凭据中。
5.  **网页推送 (Web Push / PWA)**：基于 W3C Push API 与 Service Worker 的真后台推送——**即使所有 dsh 标签页都已关闭**，手机或桌面仍能收到通知（其余浏览器通道需要标签页保持打开）。点击通知直接跳转到触发事件的会话。需要 HTTPS（或 localhost）；iOS 需先添加到主屏幕（iOS 16.4+）。

## 架构

```mermaid
graph TD
  A[DSH session/event] --> B[plugin-notify host]
  B -->|credential name| C[Credentials service]
  C -->|webhook URL| B
  B -->|POST JSON| D[Feishu / WeCom / DingTalk / Slack / Discord / custom]
  B -.->|macOS only| E[osascript notification]
  B -->|SSE stream: /dsh-plugin-notify/events| F[Client Listener lib/client.js]
  F -->|Web Audio API| G[音频提示音]
  F -->|DOM overlay| H[跨会话屏幕横幅]
  F -->|Notification API| I[系统桌面通知]
  B -->|web-push + VAPID| K[推送服务]
  K -->|后台推送| L[Service Worker /dsh-plugin-notify/sw.js]
  L -->|点击跳转会话| F
  J[设置卡片] -->|参数配置| B
```

## 功能说明

### 宿主（`lib/index.js`）

-   订阅 `session/event`。
-   `turn/end` 且 `reason.kind === 'completed'` → `task_done`。
-   其他 `turn/end` 原因 → `error`。
-   `approval/asked` → `approval_requested`。
-   `user-questions/request` → `question_requested`（用户提问与计划审阅）。
-   通过 Cordis `webServer` 服务向已连接的前端客户端提供实时 SSE 事件流（`GET /dsh-plugin-notify/events`）。
-   解析 `webhooks.*`：遗留 `http(s)://` URL（弃用警告）→ Credentials `resolve` → `process.env[name]`。
-   使用 `AbortSignal.timeout(timeoutMs)`（默认 5000 ms）。POST 失败只记录，不重试，不阻塞 agent 循环。
-   可选免打扰窗口（`HH:MM`，支持跨夜）。事件仍会观察；Webhook、提示音和本机弹窗会跳过。
-   `excludeSessionPrefixes` 会跳过 id 匹配前缀的会话。
-   **网页推送宿主**：`webPush.enabled` 开启 Push API 通道。默认 `webPush.onlyWhenAway`（仅在无浏览器连接时推送），正在观看时不会被打扰。
    -   路由：`GET /dsh-plugin-notify/push/key`（VAPID 公钥）、`POST /dsh-plugin-notify/push/subscribe`、`POST /dsh-plugin-notify/push/unsubscribe`、`POST /dsh-plugin-notify/push/test`、`GET /dsh-plugin-notify/sw.js`（Service Worker，响应头 `Service-Worker-Allowed: /`）。四个推送路由与 SSE 流使用同一信任围栏。
    -   VAPID 密钥首次使用时自动生成并持久化；可通过 `DSH_NOTIFY_VAPID_PUBLIC_KEY` + `DSH_NOTIFY_VAPID_PRIVATE_KEY` 自行管理。订阅保存在同一状态文件（默认 `$DSH_HOME/plugin-notify-state.json`，可用 `webPush.stateFile` 覆盖）。
    -   失效订阅（推送服务返回 404/410）自动清理。推送服务缓慢或故障绝不阻塞 agent 循环。

### 客户端（`lib/client.js`）

-   原生设置卡片：`settings.plugin.item`。
-   Web Audio API 双音提示音合成器，支持 `task_done`、`error` 与 `approval_requested`，附带“测试声音”按钮。
-   跨会话浮动 Toast 管理器，支持跳转会话及“测试通知”按钮。
-   HTML5 原生桌面通知集成与权限申请。
-   实时 SSE 订阅器，支持指数退避自动重连及可选的 `notifyBackgroundOnly` 过滤。
-   快照状态 `loading` / `unavailable` / `ready`。
-   保存会写入全部字段并列出失败项。
-   语言包只有 `en` 和 `zh`。俄语界面由 `dsh-russian-lang` 在运行时提供。
-   样式标签带 `data-dsh-plugin="dsh-plugin-notify"`。

## 安装

本包为私有包（GitHub Packages）。在具备仓库访问权限后：

```sh
dsh plugin --profile web add @goodandready/dsh-plugin-notify
```

重启 web 配置以便加载客户端。然后打开 **设置 → 插件 → Notify**。

## 配置

把每个 Webhook URL 放到 **设置 → 凭据**。在插件卡片里只填写凭据名称。

```yaml
- id: plugin-notify
  name: '@goodandready/dsh-plugin-notify'
  config:
    enableSound: false
    enableToasts: false
    enableDesktopNotifications: false
    notifyBackgroundOnly: false
    notifySubagents: false
    webhooks:
      feishu: NOTIFY_FEISHU_WEBHOOK
      wecom: NOTIFY_WECOM_WEBHOOK
      dingtalk: NOTIFY_DINGTALK_WEBHOOK
      slack: NOTIFY_SLACK_WEBHOOK
      discord: NOTIFY_DISCORD_WEBHOOK
      custom: NOTIFY_CUSTOM_WEBHOOK
    events: [task_done, error, approval_requested, question_requested]
    local: true
    timeoutMs: 5000
    dnd:
      start: ''
      end: ''
    includeSession: true
    includeDuration: true
    excludeSessionPrefixes: []
    webPush:
      enabled: false
      onlyWhenAway: true
      subject: 'mailto:notify@localhost'
      stateFile: ''
```

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enableSound` | boolean | `false` | 回合完成、出错或等待审批时播放 Web Audio 合成提示音（默认关闭，需显式开启）。 |
| `enableToasts` | boolean | `false` | 跨会话弹出屏幕横幅通知，附带一键跳转按钮（默认关闭，需显式开启）。 |
| `enableDesktopNotifications` | boolean | `false` | 系统原生桌面推送（Windows、macOS、Linux、DSH 桌面版，需显式开启并授权）。 |
| `notifyBackgroundOnly` | boolean | `false` | 仅当事件发生在非活跃/后台会话时才触发通知。 |
| `notifySubagents` | boolean | `false` | 是否发送委托子代理（subagent）回合通知（默认为 false 以抑制子代理噪音）。 |
| `webhooks.*` | string | 空 | 值为 Webhook URL 的凭据**名称**。空则关闭该通道。 |
| `events` | string\[\] | `task_done`, `error`, `approval_requested`, `question_requested` | 事件白名单。空则恢复默认项。 |
| `local` | boolean | `true` | macOS `osascript` 弹窗；其他平台忽略。 |
| `timeoutMs` | number | `5000` | 单次请求中止超时。 |
| `dnd.start` / `dnd.end` | string | 空 | `HH:MM` 窗口。相等或非法则关闭免打扰。 |
| `includeSession` | boolean | `true` | 在正文追加 `Session: …`。 |
| `includeDuration` | boolean | `true` | 在已知回合开始时间时追加 `Duration: …`。 |
| `excludeSessionPrefixes` | string\[\] | `[]` | 当 `session.id` 以任一前缀开头时跳过通知。 |
| `webPush.enabled` | boolean | `false` | 网页推送 (PWA) 通道：所有 dsh 标签页关闭时也能送达的后台推送（需手动开启）。 |
| `webPush.onlyWhenAway` | boolean | `true` | 有浏览器客户端连接时跳过网页推送。 |
| `webPush.subject` | string | `mailto:notify@localhost` | 向推送服务公示的 VAPID 联系方式（mailto:/https:）。 |
| `webPush.stateFile` | string | 空 | VAPID 密钥与订阅的状态文件（默认 `$DSH_HOME/plugin-notify-state.json`）。 |
| `webPush.allowedHosts` | string\[\] | `[]` | 额外允许的推送端点域名或通配符列表（默认严格仅允许 Google FCM、Mozilla、Apple、Microsoft）。 |

`webhooks.*` 中残留的原始 `http(s)://` 仍会发送，但会给出弃用警告。请迁移到凭据。

## 消息格式

| 通道 | JSON 正文 |
| --- | --- |
| 飞书 | `{ msg_type: 'text', content: { text } }` |
| 企业微信 | `{ msgtype: 'text', text: { content: text } }` |
| 钉钉 | `{ msgtype: 'text', text: { content: text } }` |
| Slack | `{ text }` |
| Discord | `{ content: text }` |
| custom | `{ text, kind, title, sessionId, durationMs, time }` |

## 测试

```sh
npm install --no-audit --no-fund --no-package-lock
npm test
```

`pretest` 会对 `lib/index.js` 和 `lib/client.js` 执行 `node --check`。随后 `node --test test/*.test.mjs`。

套件使用 stub `fetch` 或本地 HTTP 监听器，不会调用真实 IM 服务。真实投递需要你自己的 Webhook。

预期输出：

```text
✔ public package identity matches host, client and patch sites
✔ client locale registration coexists with Russian language pack
✔ client apply does not register ru and can reload after effect dispose
✔ legacy raw webhook URL still posts (compat)
✔ credential ref resolves webhook URL via credentials service
✔ resolveWebhookValue prefers credentials then env
✔ missing credential name does not post
✔ each IM channel posts the expected body shape
✔ recipient HTTP failure does not throw out of the session loop
✔ AbortSignal.timeout is attached to webhook POST
✔ excluded session prefixes suppress notifications
✔ Config schema validates sound, toast, and desktop notification fields with opt-in defaults
✔ SSE route delegates authentication to DSH connection service with loopback fallback (issue #21 fix)
✔ SSE route falls back to loopback-only check when connection service is absent (issue #21 fix)
✔ client does not register settings.section slot (issue #16 fix)
✔ deliveries and warnings are routed through ctx.logger without console calls (issue #22 fix)
✔ cleanupTurnStarts purges stale turnStarts entries older than TTL (issue #32 fix)
✔ sendSseHeartbeat writes ping comment to active clients and purges failed clients (issue #33 fix)
✔ summarizeTurn safely reverse iterates events and handles missing session.events (issue #34 fix)
✔ textOf handles plain strings, arrays of blocks, and strings in arrays (issue #35 fix)
✔ lifecycle: apply -> dispose closes SSE clients, resets turnStarts, and isolates re-apply (issue #40 fix)
✔ web push delivers approval requests to stored subscriptions
✔ turn completion produces a task_done push honoring text options
✔ onlyWhenAway skips push while a browser client is connected
✔ onlyWhenAway=false pushes even with clients connected
✔ disabled web push never sends
✔ DND window suppresses push like every other channel
✔ event filter and session-prefix exclusions apply to push
✔ dead subscriptions (404/410) are pruned, live failures are not
✔ no subscriptions means no sends and no errors
✔ sw.js is served unauthenticated with scope and cache headers
✔ sw.js rejects non-GET with 405
✔ push routes refuse non-loopback peers when no connection service exists
✔ push routes honor connection.requestRejection like the SSE stream
✔ push/key: 404 while disabled, key material while enabled
✔ push/subscribe: persists valid subscriptions, rejects invalid bodies
✔ push/unsubscribe: removes by endpoint
✔ push/test: sends to stored subscriptions via the injected library
✔ push routes answer 405 on wrong methods
✔ generateVapidKeys returns base64url P-256 keys
✔ resolveStatePath: explicit stateFile wins, then DSH_HOME, then ~/.dsh
✔ loadState tolerates missing and corrupted files
✔ saveState round-trips and leaves no temp files behind
✔ getVapidKeys generates once, persists, then reuses
✔ getVapidKeys env override wins over the state file
✔ addSubscription validates and dedupes by endpoint
✔ removeSubscription removes and reports
✔ concurrent saveState calls serialize into a valid file
ℹ tests 48
ℹ pass 48
ℹ fail 0
```

## 许可证

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 变更历史

完整更新日志详见 [CHANGELOG.md](https://npmcn.com/package/%40goodandready/dsh-plugin-notify/CHANGELOG.md)。

## 常见问题

### @goodandready/dsh-plugin-notify 是什么？

DSH插件:音频密钥,跨会场土司,桌面推取,IM网络呼取,和网络推取\(PWA\)来进行转会完成,出错和批准\.

### 如何安装 @goodandready/dsh-plugin-notify？

在项目目录运行 npm install @goodandready/dsh-plugin-notify，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-session（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.0-rc\.2）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-credentials（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.0-rc\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-plugin-notify 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-plugin-notify 是否存在。

### @goodandready/dsh-plugin-notify 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-plugin-notify 可以商用吗？

@goodandready/dsh-plugin-notify 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-plugin-notify 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-plugin-notify 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,385 次，日均约 180 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-plugin-notify 还在维护吗？

最新版本 0\.4\.9 发布于 2026/11/14（2 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/09/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

