前言¶

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 检索。