前言¶

DSH 插件在運行中會持續產生會話完成、agent 提問、進程異常、報錯和版本更新等事件。如果每個插件各自處理橫幅、系統通知和日誌，配置會分散，派生插件也難以複用同一套通知能力。

dsh-notifacation-frame 是 gameswu 維護的 DSH 通知框架：統一管理通知事件，允許派生插件註冊自己的通知項，並在設置頁爲每個通知項提供配置卡片。

這是什麼¶

這是一個 DSH 通知框架插件，用於把“某個事件發生時提醒用戶”抽象爲可註冊、可配置、可投遞的通知項。

它適合需要在 DSH web profile 中統一處理會話狀態、工具結果、進程異常和更新事件的智能體或派生插件。

許可證爲：

MIT © 2026 gameswu

核心功能¶

統一通知事件管理¶

內置通知項與派生插件註冊的通知項走同一註冊表、同一配置模型、同一投遞管線。

設置頁配置卡片¶

Settings → 通知 頁會爲每個通知項提供卡片，包含：

• 啓用開關
• 通道選擇
• 音效選擇
• 派生插件配置項
• 測試按鈕
• 最近通知歷史

自定義音效¶

每個通知項可選擇內置合成音效或自定義音頻 URL。卡片上可試聽，通知橫幅出現時播放。

派生插件支持¶

派生插件接入通知框架的關鍵接口是：

inject: ['notificationFrame']

以及：

ctx.notificationFrame.register(definition)

definition.fields 聲明的配置項由框架解析、校驗、補默認後經 env.config 傳入。配置修改時框架自動重激活。

頁內 toast、系統通知和日誌¶

支持：

• 瀏覽器 DSH Toast 橫幅
• 系統通知（盡力而爲）
• 可選通知日誌

系統通知在 Windows / Linux / macOS 上爲盡力而爲，並帶冷卻防刷屏。

內置通知項¶

內置通知項包括：

• session-complete
• ask-user-question
• process-crash
• agent-error
• agent-loop-config-start-failed
• tool-error
• dsh-update

其中 tool-error 默認關閉，因爲工具失敗通常由模型自愈，可按需開啓。agent/request-error 因過於嘈雜不接入。

安裝與啓用¶

下面以 web profile 爲例。

1、構建插件模塊：

cd dsh-notifacation-frame
pnpm install
pnpm run build

構建產出插件入口 lib/index.js 和瀏覽器 bundle lib/client.js。

2、安裝到 web profile：

dsh plugin --profile web add "file:$(pwd)"

3、重啓 DSH 使插件生效。

安裝後如需覆蓋框架級配置，可在 profile 的 cordis.patch.yml 中按 id 重述該行。cordis.patch.yml 是覆蓋層，不是掛載行；僅覆蓋框架級配置（如 logFile）時才重述該行。例如只覆蓋 logFile：

- id: notifacation-frame
  config:
    logFile: /path/to/notifications.log

卸載 web profile 中的插件：

dsh plugin --profile web remove dsh-notifacation-frame

典型用法¶

派生插件接入通知框架的最小路徑是三步：

1、聲明注入 notificationFrame；
2、定義通知項 definition，並用 fields 聲明配置項；
3、在 setup(env) 中訂閱事件，並調用 env.notify({ title, body }) 發送通知。

示例骨架：

export const inject = ['notificationFrame']

const myItem = {
  id: 'my-event',
  title: 'My event',
  description: 'Notify when a specific event happens.',
  severity: 'info',
  channels: ['web'],
  defaultChannels: ['web'],
  fields: [
    { key: 'minValue', label: 'Minimum value', type: 'number', default: 10 }
  ],
  setup(env) {
    // env.config 已包含解析、校驗和補默認後的字段值。
    return env.ctx.on('some/event', (payload) => {
      env.notify({
        title: 'Something happened',
        body: `value=${payload.v}`
      })
    })
  }
}

export function apply(ctx) {
  ctx.effect(() => ctx.notificationFrame.register(myItem))
}

用戶修改卡片中的 fields 配置後，框架會用新配置重跑 setup，實現熱生效。

適用場景與注意¶

適合：

• 在 DSH web profile 中統一處理會話完成、agent 提問、進程崩潰、agent 報錯、agent 循環配置啓動失敗、工具報錯和 dsh-update 等通知。
• 派生插件需要註冊自己的通知項，並複用設置頁卡片、通道選擇和音效能力。
• 需要瀏覽器橫幅、系統通知（盡力而爲）和可選日誌的輕量通知能力。

注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
• 系統通知在 Windows / Linux / macOS 上爲盡力而爲，並帶冷卻防刷屏。
• 自動播放策略下 AudioContext 可能被瀏覽器掛起，首次手勢後自動恢復；播放失敗靜默，不影響通知。
• 安裝或覆蓋配置後，需重啓 DSH 生效。

結尾¶

dsh-notifacation-frame 的價值在於把分散的通知處理收斂到一套註冊、配置和投遞機制：內置事件開箱即用，派生插件可以低成本擴展，設置頁可以統一調整開關、通道、音效和字段。

GitHub 鏈接：

https://github.com/gameswu/dsh-notifacation-frame

社區目錄爲獨立站點，可按插件名 dsh-notifacation-frame 檢索。