yakoylp/dsh-localnotify

🌐 English: README.en.md · 🤖 AI Agent 使用手册: README.agent.md

DSH（DeepSeek Harness）本地通知栏插件：在 Web UI 侧边栏新增【通知】入口，点击打开全屏通知中心。通知以卡片形式展示（标题 + 正文单行预览），支持级别视觉分级、时间/来源筛选、标题/内容搜索、排序、未读/已读标记、删除；点击卡片弹出完整信息详情页并可一键复制标题/正文。通知由 agent 工具（notify_add）或 CLI（dsh-localnotify）写入本地 JSON 文件，页面实时刷新，全程本地、无外部服务。

典型场景：任务完成后由 agent 写一条通知提醒你，你在通知栏随时回看；脚本/定时任务也可通过 CLI 直接投递。

功能特性

• 侧边栏【通知】入口：铃铛图标 + 未读数量徽标（折叠态红点角标），位于左侧栏底部 Settings 旁，不遮挡现有 UI
• 全屏通知中心（shell.overlay，独立于任何会话）：
  • 卡片列表：标题 + 正文单行预览（超长省略号），未读卡片带级别色左边框与圆点，高度紧凑
  • 级别视觉分级：info(品牌色) / success(绿) / warn(黄) / error(红)，卡片与详情页显示级别标签，未读扫一眼即知轻重缓急
  • 分页浏览：底部工具条「每页 10/20/50/100」（默认 20）+ 上一页/下一页翻页（显示 共 N 条 · 第 x/y 页），只渲染当前页卡片
  • 时间筛选：全部 / 今天 / 近7天 / 近30天
  • 来源筛选：按通知来源（agent / cron / cli 等，自动汇总）过滤
  • 排序切换：最新优先 / 最旧优先 / 未读优先
  • 标题 + 内容搜索：实时过滤（不区分大小写）
  • 详情弹层：点击卡片弹出完整信息（完整时间 / 级别 / 来源 / 已读状态 + 全文），右下角一键复制标题、正文或全部（点击后按钮显示「已复制 ✓」），打开详情时自动标记已读
  • 顶部「全部已读」；卡片「删除」带两步确认（防误删）
  • 点关闭按钮或遮罩空白处退出
• 实时刷新：页面打开时每 3 秒轮询，关闭时每 30 秒保持徽标同步（agent/CLI 写入后几秒内可见）
• 主题适配：全部使用 DSH 官方主题 token（--dsw-alias-*），明暗主题自动跟随
• 多语言：界面文案跟随 dsh web 语言自动切换（zh / en，切换实时生效）
• 自动清理：可选设置保留天数，超期通知随每次写入自动删除（默认关闭，500 条上限始终兜底）
• 写入方式（无页面新增入口，保持界面纯净）：
  • agent 工具：对话中由 agent 调用 notify_add 写通知（支持 level 分级）
  • CLI：dsh-localnotify add "标题" -b "正文" [--level success]，适合脚本/定时任务

数据存储

通知保存在 ~/.dsh/notify/notifications.json（DSH_HOME 环境变量优先），结构：

{
  "version": 2,
  "notifications": [
    {
      "id": "n_mtisij3d_q32zcn",
      "title": "任务完成",
      "body": "转换结果已生成，共 23 页。",
      "createdAt": 1788274582825,
      "read": false,
      "source": "agent",
      "level": "success"
    }
  ],
  "settings": { "retainDays": 0 }
}

• level: info | success | warn | error（旧数据无此字段按 info 显示）

• settings.retainDays: 自动清理保留天数；0=永久保留（默认）；>0 时每次写入自动删除超过该天数的通知（可经 CLI config --retain-days 设置，版本 1 旧文件读入后自动升级到 version 2）

• 写入为原子替换（临时文件 + rename），不会出现半截文件

• 文件缺失或损坏时按空库处理，绝不覆盖原文件

• 单进程内写操作串行化；最多保留 500 条，超出自动裁剪

• 文件透明可读，可手动编辑、备份、随 ~/.dsh 整体迁移

安装

方式一：GitHub 仓库（推荐）

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

方式二：本地目录开发安装

先把仓库克隆（或解压源码包）到任意目录，再用该目录安装：

git clone https://github.com/yakoylp/dsh-localnotify.git
dsh plugin --profile web add ./dsh-localnotify               # macOS / Linux
dsh plugin --profile web add "C:\path\to\dsh-localnotify"    # Windows（换成实际路径）

安装后重启 dsh web（客户端 bundle 由 web 服务在启动时加载）。重启后侧边栏底部出现 🔔【通知】入口即为成功；可用 dsh-localnotify add "测试" 投递一条验证。

CLI 用法

dsh-localnotify add "任务完成" -b "转换结果已生成"                     # 新增通知
dsh-localnotify add "提醒" --source cron --level warn                   # 指定来源与级别
dsh-localnotify add "部署成功" --level success                          # 级别: info/success/warn/error
dsh-localnotify list                                                    # 列出（* 为未读; [E]/[W]/[OK] 为级别标记）
dsh-localnotify list --unread                                           # 仅未读
dsh-localnotify list --level error                                      # 仅错误级
dsh-localnotify list --json                                             # JSON 输出（脚本友好）
dsh-localnotify read n_xxxx                                             # 标记单条已读
dsh-localnotify read --all                                              # 全部已读
dsh-localnotify delete n_xxxx                                           # 删除
dsh-localnotify config [--retain-days 7]                                # 查看/设置自动清理保留天数(0=永久)
dsh-localnotify prune                                                   # 按 retain-days 立即清理一次
dsh-localnotify --help                                                  # 帮助
dsh-localnotify --file /path/to/notifications.json add ...              # 覆盖存储路径

CLI 直接读写同一个 JSON 文件，不依赖 cordis 运行，可在任何终端/脚本/cron 中使用。

Agent 工具

插件注册 notify_add 工具，agent 在对话中调用即可写入通知（自动校验：标题必填 ≤200 字、正文 ≤5000 字）。例如任务完成时，agent 会调用：

notify_add(title: "文档转换完成", body: "23 页扫描件已转为 Markdown，输出于 ...", level: "success")

level 为可选枚举 info | success | warn | error，用于视觉分级：任务成功用 success、失败/出错用 error、需要用户注意用 warn、一般消息省略（默认 info）。

通知提交路径（agent / 脚本如何投递）

方式	使用者	前提
notify_add 工具	DSH agent（同一 profile）	插件已安装即自动注册；agent 在工具列表中看到该工具并按其描述在任务完成等场景调用，无需额外配置
dsh-localnotify CLI	脚本 / cron / 终端	插件已安装（bin 链接到 profile 的 node_modules/.bin）；或直接 node <插件路径>/lib/cli.js
直接写 JSON 文件	任意程序	按上文文件格式写入 ~/.dsh/notify/notifications.json，页面 3s 内可见

说明：notify_add 工具对**安装了插件的同一 DSH 环境（profile）**内的 agent 可见；其他环境/agent 需各自安装插件才能用工具投递，但 CLI 与文件写入不受环境限制。

HTTP API

Host 半区注册同源路由 POST /dsh-localnotify/api/<method>（仅 DSH 自带 web 服务可达），请求/响应均为 JSON，响应包裹 { ok, value } 或 { ok: false, error: { code, message } }：

方法	参数	说明
list	{}	返回 { notifications, storagePath }
markRead	{ id }	标记单条已读
markAllRead	{}	全部已读
delete	{ id }	删除单条

架构

• Node 半区（cordis.patch.yml 挂载，lib/index.js）：注册 notify_add 工具（ctx.tools.register）与 /dsh-localnotify/api/* 路由（ctx.webServer.register，prefix 匹配）；存储逻辑在 lib/store.js（Host 与 CLI 共用）
• 浏览器半区（dsh.client + exports["./client"] → lib/client.js）：手工编写的 ModuleLoader bundle（window.__ModuleLoader__.load({ id, factory })，与官方 tsdown 产物同格式，仅依赖基线外部模块 react）；通过 ctx.slots.inject/register 注册 sidebar.footer.action（入口）与 shell.overlay（通知中心），数据走同源 fetch 调 Host API
• 主题：颜色全部引用 DSH 主题 token（--dsw-alias-bg-* / --dsw-alias-label-* / --dsw-alias-border-* / --dsw-alias-brand-primary 等）

开发

node --test                    # 运行全部测试（store 存储层 + API handler + CLI 端到端）
node lib/cli.js --file ./tmp-notify.json add "测试" -b "正文" --level success
node lib/cli.js --file ./tmp-notify.json list
node lib/cli.js --file ./tmp-notify.json config --retain-days 7

常见问题（排障）

• 侧边栏入口可见，但通知中心列表为空：先直测 Host 路由是否注册——curl -X POST http://127.0.0.1:<port>/dsh-localnotify/api/list -H "Content-Type: application/json" -d "{}"。若返回 405（空 body），说明 Host 路由未注册，请升级到 ≥1.1.0（1.0.0 存在 inject 缺 webServer 导致路由静默失效的问题）；若返回 { ok:true, value: { notifications, ... } } 则路由正常，检查存储文件是否有数据
• 多条通知被压成细条、无滚动条：1.0.0 的 flex 布局缺陷，升级到 ≥1.1.0（卡片已禁止 flex 压缩，列表容器可正常滚动）

已知限制与后续

• 通知中心为全屏浮层（非独立路由页面），关闭后回到原会话 —— 设计取舍：保持轻量，不占导航
• 实时性依赖轮询（打开 3s / 关闭 30s），未做 Host→Client 推送。轮询成本极低（同源小请求），且不依赖额外事件通道；如未来 DSH 提供推送通道再评估升级
• 多进程同时写（如 CLI 与 Host 并发）依赖原子 rename，极端并发下后写者胜出。通知场景写入频率低，该语义足够安全（单进程内写已串行化）；若未来出现高频并发写入需求再引入文件锁
• 文件被外部工具修改时，以读取时内容为准（页面 3s 内可见）

测试与 CI

• 测试覆盖三层：存储层（新增/校验/级别/自动清理/旧文件兼容/损坏兜底/500 上限）、HTTP API（方法分发/错误包裹/读写联动）、CLI（spawn 端到端：add/list/read/delete/config/prune/错误路径）
• GitHub Actions 在 Node 18 / 20 / 22 上自动运行全部测试（.github/workflows/test.yml）

License

MIT