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