dsh-tool-notify：DeepSeek Harness 通知工具

前言¶

DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”，开发者可以通过扩展组件增强 Agent 的能力。在构建长期运行的 Agent 任务时，一个常见需求是：当任务完成或需要人工介入时，能够及时通知到外部渠道。dsh-tool-notify 插件正是为此设计的。它为模型提供了一个原生的 notify 工具，支持通过 ntfy 或 Webhook 两种方式发送通知，解决了 Agent 与外部系统交互的集成痛点。

功能概览¶

该插件主要提供以下能力：
* 模型原生工具：模型在运行中可以直接调用 notify 工具。
* 双通道支持：
* ntfy（默认）：发布到 ntfy 服务器（如 https://ntfy.sh 或自建服务）。
* webhook：向任意通用的 Webhook 端点发送 JSON 载荷。
* 触发时机：通常在 Agent 任务完成或需要关注时调用。

安装与启用¶

环境要求¶

在安装前，请确保环境满足以下条件：
* Node.js 版本：>=22.19 或 >=24。
* 包管理器：通过 Corepack 启用 pnpm，版本需为 pnpm@11.7.0。
* 运行中的 DSH Profile：通过 dsh --profile <name> 启动的环境。

安装命令¶

使用 npm 预构建包安装（推荐，无需构建权限）：

dsh plugin --profile demo add dsh-tool-notify

从 GitHub 源码安装¶

如果从 GitHub 源码安装，构建脚本会在安装时运行。注意：如果使用的 pnpm 版本大于 10，需要先配置允许构建：

在你的 profile 配置目录下找到 pnpm-workspace.yaml，添加以下配置：

allowBuilds:
  dsh-tool-notify: true

重新运行安装命令，并指定具体的 commit SHA：

dsh plugin --profile demo add github:rizkirmdhn/dsh-tool-notify#<commit-sha>

配置¶

插件安装后，需要通过 cordis.patch.yml 覆盖默认配置。该文件位于 profile 配置目录中，后续层级的配置会覆盖先前的配置。

- patch:
    - id: notify
      config:
        endpoint: https://ntfy.sh
        defaultTopic: dsh-alerts
        timeoutMs: 10000
        channel: ntfy
        # tokenRef: NTFY_TOKEN

配置项说明¶

字段	类型	默认值	说明
`endpoint`	string	`https://ntfy.sh`	ntfy 服务的基础 URL 或完整的 Webhook URL
`defaultTopic`	string	`dsh-alerts`	模型未提供 topic 时的默认值（仅 ntfy）
`timeoutMs`	number	`10000`	HTTP 请求超时时间（毫秒）
`channel`	string	`ntfy`	通知渠道类型，可选 `ntfy` 或 `webhook`
`tokenRef`	string	—	凭证引用名（环境变量风格），用于 Bearer Token

认证方式¶

严禁在配置文件中直接写入密钥。请设置 tokenRef 为凭证名称（例如 NTFY_TOKEN），然后通过 DSH 的凭证提供者（环境变量、.env 文件或 UI）配置该凭证。插件会在每次调用时通过 ctx.credentials 解析该凭证，支持动态刷新。

典型用法¶

模型调用 notify 工具时，会传递以下参数：

{
  "message": "string (required)",
  "title": "string (optional)",
  "priority": "'min' | 'low' | 'default' | 'high' | 'max' (optional, ntfy)",
  "topic": "string (optional, ntfy override)"
}

ntfy 模式¶

当 channel 设为 ntfy 时，插件会向 {endpoint}/{topic} 发送 POST 请求，Body 包含：

{
  "topic": "...",
  "message": "...",
  "title": "...",
  "priority": "..."
}

webhook 模式¶

当 channel 设为 webhook 时，插件直接向 {endpoint} 发送 POST 请求，Body 仅包含基础信息：

{
  "message": "...",
  "title": "..."
}

返回值¶

无论成功与否，工具都会返回状态对象，而非抛出异常：
* 成功：{ ok: true, status, channel }
* 失败（非 2xx 响应）：{ ok: false, status, channel }
* 网络/超时错误：作为工具错误处理。

适用场景与注意¶

适用场景：适合需要在 Agent 执行长任务后、或发现异常情况时，通过手机 App（配合 ntfy.sh）或自定义 Webhook 系统接收即时通知的开发者。
注意事项：
- 开发者预览：目前处于开发者预览阶段，预计会有破坏性变更，生产环境使用需谨慎。
- 权限与安全：从 GitHub 源码安装时，allowBuilds 配置意味着插件代码将在你的机器上构建运行，请仅信任你添加的源码。
- 版本锁定：建议在安装时锁定 commit SHA，以避免因快速迭代导致的兼容性问题。

总结¶

dsh-tool-notify 为 DeepSeek Harness 提供了一个标准化的通知出口。通过简单的配置和模型原生的工具调用，Agent 可以轻松具备发送通知的能力，从而实现更完善的任务闭环。

插件目录：https://www.skillhub.cn/plugins/rizkirmdhnnn/dsh-tool-notify
GitHub 仓库：https://github.com/rizkirmdhnnn/dsh-tool-notify