在 DeepSeek Harness (DSH) 的开发与使用中，智能体常在后台运行任务、等待人工审批或执行长时间流程。当浏览器标签页隐藏或关闭时，仅依赖浏览器 Notification API 的通知往往无法送达，导致重要任务被遗漏。 -> In the development and use of DeepSeek Harness (DSH), agents often run tasks in the background, wait for human approval, or execute long-running workflows. When the browser tab is hidden or closed, notifications relying solely on the browser Notification API often fail to be delivered, causing important tasks to be missed.

dsh-herald 通过让 DSH 宿主进程直接向操作系统发送通知，解决了这一断连问题。无论浏览器处于打开、隐藏还是关闭状态，系统通知中心都能收到推送。 -> dsh-herald resolves this disconnection issue by letting the DSH host process send notifications directly to the operating system. Whether the browser is open, hidden, or closed, the system notification center can receive push messages.

插件定位 -> ## Plugin Positioning

dsh-herald 是一个联网工具类插件，原名 dsh-task-notify 的深度定制版。由 bululuburuarua666 维护，采用 MIT 许可证。它为 DSH 提供了三路投递机制，将任务状态推送到前端浮层、浏览器横幅以及宿主系统通知中。 -> dsh-herald is an online utility plugin and a heavily customized version of the original dsh-task-notify. It is maintained by bululuburuarua666 and licensed under the MIT License. It provides DSH with a three-channel delivery mechanism, pushing task status to a front-end floating overlay, browser banners, and host system notifications.

核心功能 -> ## Core Features

三通道投递 -> ### Three-Channel Delivery

插件支持三种独立的通知渠道： -> The plugin supports three independent notification channels:

  1. 通道 A（页内浮层）：在 DSH 工作区页面内渲染的顶部浮层通知，带有提示音，支持悬停暂停。 -> Channel A (In-Page Overlay): A top overlay notification rendered inside the DSH workspace page, with a notification sound and hover-to-pause support.
  2. 通道 B（浏览器 OS 横幅）：通过浏览器 Notification API 发出的系统级横幅，需用户授权。 -> Channel B (Browser OS Banner): A system-level banner issued through the browser Notification API, requiring user authorization.
  3. 通道 C（宿主直发系统通知）：由 DSH 宿主进程直接调用的系统通知（Windows 使用 PowerShell WinRT，macOS 使用 osascript，Linux 使用 notify-send）。这是该插件的核心能力，浏览器关闭时仍可送达。 -> Channel C (Host Direct System Notification): A system notification invoked directly by the DSH host process (Windows uses PowerShell WinRT, macOS uses osascript, and Linux uses notify-send). This is the core capability of the plugin, and it can still be delivered when the browser is closed.

防轰炸机制 -> ### Anti-Spam Mechanism

为了防止通知频繁触发导致系统卡顿，插件内置了限流逻辑： -> To prevent system lag caused by frequent notification triggers, the plugin includes built-in rate-limiting logic:

  • 最小发送间隔：1.2 秒 -> Minimum sending interval: 1.2 seconds
  • 超时机制：5 秒内未发送则丢弃 -> Timeout mechanism: messages not sent within 5 seconds are discarded
  • 重试策略：仅重试一次 -> Retry strategy: retries only once

安全与配置 -> ### Security and Configuration

  • 注入安全：文本内容使用 base64(UTF-16LE) 编码传输，标签经过过滤，进程不使用 Shell 启动。 -> Injection Safety: Text content is transmitted using base64(UTF-16LE) encoding, tags are filtered, and processes are not launched via a Shell.
  • 高级面板：提供卡片式的通道设置界面，支持中英文双语切换，包含状态指示灯。 -> Advanced Panel: Provides a card-based channel settings interface, supports switching between Chinese and English, and includes status indicator lights.
  • 持久历史：本地记录 300 条通知历史，数据存储在 <profile>/data/task-notify/ 目录下，配置与历史记录可跨版本保留。 -> Persistent History: Stores 300 local notification history entries, with data saved under the <profile>/data/task-notify/ directory; configuration and history can be preserved across versions.

安装与启用 -> ## Installation and Activation

环境要求 -> ### Requirements

安装前需确保系统已安装 Node.js 和 pnpm。 -> Before installation, ensure that Node.js and pnpm are installed on the system.

安装步骤 -> ### Installation Steps

  1. 在终端执行以下命令安装插件： -> Run the following command in the terminal to install the plugin:
    dsh plugin --profile web add dsh-herald
  1. 安装完成后，必须重启 dsh web 进程。 -> After installation, the dsh web process must be restarted.
  2. 在浏览器中硬刷新页面（Ctrl+F5）以加载新插件。 -> Hard refresh the page in the browser (Ctrl+F5) to load the new plugin.

使用方法 -> ## Usage

安装并刷新页面后，点击页面右上角的 🔔 铃铛 图标展开抽屉。在抽屉中可以控制三个通道的开关并测试通知。 -> After installing and refreshing the page, click the 🔔 Bell icon in the top-right corner to expand the drawer. In the drawer, you can toggle the three channels and test notifications.

  • 宿主直发通知（通道 C）：无需额外权限，安装后默认可用。 -> Host Direct Notification (Channel C): No additional permissions are required, and it is available by default after installation.
  • 浏览器横幅（通道 B）：需要点击对应的“测试”按钮，由浏览器弹窗请求授权。 -> Browser Banner (Channel B): You must click the corresponding “Test” button, and the browser will display a popup to request authorization.
  • 通道联动：当通道 C 开启时，通道 B 会进入待机状态（Standby），避免重复通知。 -> Channel Linkage: When Channel C is enabled, Channel B enters standby mode (Standby) to avoid duplicate notifications.

配置与注意事项 -> ## Configuration and Notes

环境变量锁定 -> ### Environment Variable Lock

在宿主环境变量中设置 DSH_TASK_NOTIFY_OS=0 或 1，可以锁定通道 C 的行为。设置后，宿主侧的更改将覆盖客户端的设置。 -> Set DSH_TASK_NOTIFY_OS=0 or 1 in the host environment variables to lock the behavior of Channel C. After setting, host-side changes override client-side settings.

生效时机 -> ### When Changes Take Effect

  • 客户端更改：在浏览器中调整开关或设置，需刷新页面才能生效。 -> Client-side Changes: Adjusting switches or settings in the browser requires a page refresh to take effect.
  • 宿主更改：修改环境变量或配置文件，需重启 DSH 宿主进程才能生效。 -> Host-side Changes: Modifying environment variables or configuration files requires restarting the DSH host process to take effect.

总结 -> ## Summary

dsh-herald 通过引入宿主进程直接通知能力，解决了 DSH 后台任务与用户交互的信息断层问题。它提供了零运行时依赖的轻量级解决方案，适合需要在长时间运行任务中保持消息触达的开发者。 -> dsh-herald introduces direct notification capability from the host process, resolving the information gap between DSH background tasks and user interaction. It provides a lightweight solution with zero runtime dependencies, suitable for developers who need reliable message delivery during long-running tasks.