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 仓库
• 技能目录页