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
