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，独立于任何会话）：
  • 卡片列表：标题 + 正文单行预览（超长省略号），未读卡片带品牌色左边框与圆点，高度紧凑
  • 分页浏览：底部工具条「每页 10/20/50/100」（默认 20）+ 上一页/下一页翻页（显示 共 N 条 · 第 x/y 页），只渲染当前页卡片
  • 时间筛选：全部 / 今天 / 近7天 / 近30天
  • 标题 + 内容搜索：实时过滤（不区分大小写）
  • 详情弹层：点击卡片弹出完整信息（完整时间 YYYY-MM-DD HH:mm:ss / 来源 / 已读状态 + 全文），右下角一键复制标题、正文或全部（点击后按钮显示「已复制 ✓」），打开详情时自动标记已读
  • 顶部「全部已读」；卡片「删除」带两步确认（防误删）
  • 点关闭按钮或遮罩空白处退出
• 实时刷新：页面打开时每 3 秒轮询，关闭时每 30 秒保持徽标同步（agent/CLI 写入后几秒内可见）
• 主题适配：全部使用 DSH 官方主题 token（--dsw-alias-*），明暗主题自动跟随
• 多语言：界面文案跟随 dsh web 语言自动切换（zh / en，切换实时生效）
• 写入方式（无页面新增入口，保持界面纯净）：
  • agent 工具：对话中由 agent 调用 notify_add 写通知
  • CLI：dsh-localnotify add "标题" -b "正文"，适合脚本/定时任务

数据存储

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

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

• 写入为原子替换（临时文件 + rename），不会出现半截文件
• 文件缺失或损坏时按空库处理，绝不覆盖原文件
• 单进程内写操作串行化；最多保留 500 条，超出自动裁剪
• 文件透明可读，可手动编辑、备份、随 ~/.dsh 整体迁移

安装

方式一：GitHub 仓库（推荐）

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

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

dsh plugin --profile web add "E:\deepseekharness\deepseekharness plugin\dsh-localnotify"

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

CLI 用法

dsh-localnotify add "任务完成" -b "转换结果已生成"      # 新增通知
dsh-localnotify add "提醒" --source cron               # 指定来源标记
dsh-localnotify list                                  # 列出（* 为未读）
dsh-localnotify list --unread                         # 仅未读
dsh-localnotify list --json                           # JSON 输出（脚本友好）
dsh-localnotify read n_xxxx                          # 标记单条已读
dsh-localnotify read --all                            # 全部已读
dsh-localnotify delete n_xxxx                        # 删除
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，输出于 ...")

通知提交路径（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                       # 存储层单元测试（7 项）
node lib/cli.js --file "$TEMP/test.json" add "测试" -b "正文"
node lib/cli.js --file "$TEMP/test.json" list

常见问题（排障）

• 侧边栏入口可见，但通知中心列表为空：先直测 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 推送；后续可在 Host 侧增加事件通道
• 文件被外部工具修改时，以读取时内容为准（页面 3s 内可见）
• 多进程同时写（如 CLI 与 Host 并发）依赖原子 rename，极端并发下后写者胜出

License

MIT