dsh-localnotify：DSH 本地通知欄插件

前言¶

在 DSH（DeepSeek Harness）的開發或使用場景中，Agent 完成任務後需要一種即時反饋機制，同時也需要一種方式讓腳本或定時任務在後臺運行時能夠通知用戶。現有的 Web UI 缺乏這種輕量級的消息通知能力。

dsh-localnotify 是一個 DSH 客戶端插件，旨在側邊欄新增【通知】入口，並打開全屏通知中心，解決上述問題。

安裝與啓用¶

安裝過程非常簡單，使用官方提供的安裝命令即可。

dsh plugin --profile web add github:yakoylp/dsh-localnotify

安裝完成後，需要重啓 dsh web 服務以加載客戶端 bundle。重啓後，側邊欄底部 Settings 旁會出現一個鈴鐺圖標 🔔【通知】，未讀數量會顯示在圖標角標上。

核心功能¶

側邊欄入口與通知中心¶

側邊欄【通知】入口位於左側欄底部 Settings 旁，帶有未讀數量徽標。
點擊入口會打開一個全屏浮層（shell.overlay），卡片列表展示標題與正文單行預覽。

通知中心支持以下操作與篩選：
* 級別視覺分級：根據 info（品牌色）、success（綠）、warn（黃）、error（紅）進行顏色區分。
* 篩選與搜索：支持按時間（全部/今天/近7天/近30天）、來源（agent/cron/cli等）、排序（最新/最舊/未讀優先）進行篩選，以及標題和內容的實時搜索。
* 詳情與複製：點擊卡片彈出詳情頁（包含完整時間、級別、來源、全文），並支持一鍵複製標題、正文或全部內容。詳情頁打開時自動標記已讀。
* 管理操作：支持標記全部已讀、刪除（帶二次確認）、查看當前頁數（每頁 10/20/50/100）。

實時性與多語言¶

• 實時刷新：頁面打開時每 3 秒輪詢一次；關閉後每 30 秒保持徽標同步。
• 多語言：界面文案自動跟隨 DSH Web 語言切換（zh / en）。

數據持久化與自動清理¶

• 存儲位置：默認保存在 ~/.dsh/notify/notifications.json（優先使用 DSH_HOME 環境變量）。
• 寫入機制：支持 Agent 工具、CLI 命令行以及直接修改 JSON 文件三種方式。寫入操作爲原子替換（臨時文件 + rename），不會出現文件半截損壞的情況。
• 自動清理：支持配置保留天數（retainDays），超期通知在寫入時自動刪除；默認關閉，但始終有 500 條上限兜底。

使用方式¶

CLI 寫入¶

插件提供了 dsh-localnotify CLI 工具，適合腳本或定時任務調用。

# 新增通知（默認 info 級別）
dsh-localnotify add "任務完成" -b "轉換結果已生成"

# 指定來源與級別
dsh-localnotify add "提醒" --source cron --level warn

# 列出通知（* 爲未讀，[E]/[W]/[OK] 爲級別標記）
dsh-localnotify list --unread

# 查看或設置自動清理保留天數（0=永久）
dsh-localnotify config --retain-days 7

# 立即執行一次清理
dsh-localnotify prune

Agent 工具¶

在 DSH Agent 對話中，插件註冊了 notify_add 工具。Agent 可以在任務完成時調用該工具寫入通知。

notify_add(title: "文檔轉換完成", body: "23 頁掃描件已轉爲 Markdown...", level: "success")

JSON 文件格式¶

通知數據以 JSON 格式存儲，結構如下：

{
  "version": 2,
  "notifications": [
    {
      "id": "n_mtisij3d_q32zcn",
      "title": "任務完成",
      "body": "轉換結果已生成，共 23 頁。",
      "createdAt": 1788274582825,
      "read": false,
      "source": "agent",
      "level": "success"
    }
  ],
  "settings": { "retainDays": 0 }
}

架構與限制¶

• 架構：插件分爲 Node 半區（Host 端 API 註冊與存儲邏輯）和瀏覽器半區（Client 端 UI 渲染與輪詢）。
• 實時性：目前採用輪詢機制（同源小請求），未實現 Host → Client 的實時推送。
• 併發安全：多進程同時寫入依賴原子 rename 操作，極端併發下後寫者勝出。單進程內寫操作已串行化。
• 文件透明：文件可被外部工具修改，讀取時以當前內容爲準。

總結¶

dsh-localnotify 爲 DSH 提供了一個本地化、無依賴的通知解決方案，既支持 Agent 在對話中主動推送，也支持腳本被動寫入，配合全屏通知中心與級別分級，能有效提升工作流的反饋效率。

• GitHub 倉庫
• 技能目錄頁