前言¶

在 DeepSeek Harness (DSH) 的開發中，爲不同的任務流添加通知機制通常意味着要編寫針對特定傳輸層（如 Telegram Bot API）的集成代碼。dsh-maestro-notifier 插件旨在通過抽象一個可插拔的通知服務層，解決這一問題。

插件定位¶

這是一個由 ddtcorex 維護的插件，隸屬於 Maestro Harness 套件（dsh-maestro-*）。它提供了一個基於內存的提供者註冊表，默認集成了 Telegram 傳輸，並預留了擴展其他傳輸層的能力。

核心功能¶

該插件主要提供以下能力：

1. maestroNotifier 服務：服務對象包含 register、ids 和 send 方法，用於管理通知提供者並分發消息。
2. Telegram 傳輸：作爲默認的傳輸層，提供單向機器人消息發送。配置包括消息內容保護（protect_content）、禁用鏈接預覽，以及 10 秒超時設置。插件設計上不會記錄憑據。
3. 默認目標解析：當調用 send 方法未顯式指定目標時，會嘗試從共享設置存儲中讀取 notify.telegram 配置作爲默認目標。
4. Never-Throw 交付：這是一個設計原則。無論是未知的提供商還是目標解析失敗，都不會拋出異常，而是返回一個包含狀態和原因的對象 { sent: false, reason }。

安裝與啓用¶

使用官方提供的命令進行安裝。該插件需要與 DeepSeek Harness 的 Cordis 核心兼容。

dsh plugin --profile web add @ddtcorex/dsh-maestro-notifier

安裝完成後，該服務會在 Cordis 上下文中註冊，可通過 ctx.get('maestroNotifier') 獲取。

典型用法¶

在代碼中獲取 maestroNotifier 實例並調用 send 方法。下面的示例展示瞭如何發送一條消息，其中目標通過默認解析邏輯獲取。

const notifier = ctx.get('maestroNotifier')

// target 參數省略時，會嘗試從共享設置讀取 notify.telegram
await notifier.send('telegram', undefined, { text: 'review finished' })

依賴與環境¶

在使用此插件前，請確認運行環境滿足以下依賴要求：

• Node.js 版本：要求 ^22.19.0 或 >=24.0.0。
• Cordis 版本：依賴 @deepseek-ai/cordis，版本要求 ~4.0.4。
• 配置庫：依賴 @ddtcorex/dsh-maestro-config-lib（workspace:^0.3.0）。

注意事項¶

1. 僅傳輸層：這是一個純傳輸層的插件。消息的文本內容（領域文本）屬於消費插件，此包從不生成領域文本。
2. 顯式目標優先：如果調用方顯式提供了目標參數，將優先使用該參數；任何解析器故障最終都會降級爲 { sent: false, reason: 'not-configured' }。
3. 生態歸屬：它是 Maestro Harness 套件的一部分，短別名爲 maestro-notifier。

總結¶

dsh-maestro-notifier 爲 DeepSeek Harness 提供了一個簡單、無侵入式的通知抽象。通過 Never-Throw 的設計和默認的目標解析機制，它降低了通知功能的接入成本。開發者可以直接通過代碼調用服務，而無需處理底層的傳輸細節或錯誤拋出。

• 插件目錄：ddtcorex/dsh-maestro-notifier
• 源碼倉庫：GitHub