dsh-agent-notify

维护中的 fork（@kkabuka/dsh-agent-notify，v1.0.1）：源自 chidaic/dsh-agent-notify（MIT；上游 npm 停在 1.0.0 / 2026-08-22，已停更）。本 fork 面向 dsh 0.2.x 持续修复，许可与署名仍归上游（见文末）。

相对上游 1.0.0 的四处适配（差异全文 = CHANGELOG）：① 点击跳转改接 ctx.uiWorkspace.openSession ② 需输入信号改接 ctx.uiSession.sessionStatus（两者保留旧内核回退）③ 卡片三枚失效 CSS 令牌改回内核实有令牌 ④ 通知正文摘要改接 ctx.uiConversation（替换已删的 SessionSnapshot.nodes）。

安装（npm）

dsh plugin --profile web add @kkabuka/[email protected]

旧名 dsh-agent-notify 是上游包（未适配 0.2.x：会话导航与通知正文会静默失效）——不要装。源码安装 = npm pack → dsh plugin --profile web add file:<tgz>。

DSH Web GUI 的「任务完成通知」插件：当 agent 执行完任务 / 回复完对话、或需要你做出选择（提问 / 批准 / 审阅计划）时，弹出 Windows 系统级通知（通知中心气泡，声音为 Windows 系统通知音）——无论你在哪个窗口都能看到。纯系统提示：无网页内弹窗、无合成音、无额外 UI 按钮。

纯浏览器端插件（host half 为空），无需构建工具，手写 bundle 直接加载。

功能

• 任务完成通知：会话从 running 变为停止时，发送「任务完成」系统通知。
• 需要输入通知：agent 提问（question）时发送「需要你的回答」。
• 批准 / 计划审阅通知：approval / plan-review 时发送「需要你的批准 / 请审阅计划」。
• 系统级通知（浏览器 Notification API，类 Codex CLI 体验）：Windows 通知中心弹出气泡，声音为 Windows 系统通知音（由 Windows 设置控制）；点击气泡会聚焦页面并打开对应会话。三种模式可选：不发送 / 后台时发送 / 始终发送（默认）。
• 自动授权：首次点击页面时自动请求通知权限（浏览器会询问，选「允许」即可）；也可在设置页手动授权。
• 通知内容：会话标题（+ 该会话最后一条 assistant 回复的前 90 字摘要）。摘要取自 ctx.uiConversation 的 Chat 视图：优先 navigation.items()[].response（内核自带的有界回复预览），回退 legacy.nodes 逐节点取文本。⚠ 前提 = 该会话仍被 retain（窗口开着）——uiConversation.binding() 对未 retain 的会话会抛错，故窗口已关闭的会话只显示标题（与 rc.1 时代同一约束）。每条通知都是全新气泡（不带 tag——Windows 上 Chrome 对同 tag 通知只静默更新不弹新气泡，这是本插件历史上「通知消失」的根因，已移除）。
• 设置入口 = DSH 官方设置界面的一级页面：设置 → 任务提示（注册进官方 settings.section slot，与「设置 → 宠物」同级）：启用通知、是否包含子代理通知、系统通知模式、权限状态与授权、发送测试通知（一键诊断，显示具体结果）。设置保存在 localStorage（dsh.agentNotify.settings.v3）。页面顶部显示插件版本与当前生效配置，便于排查旧缓存。
• 诊断：设置页的「发送测试通知」无视发送模式直接弹一条系统通知，并显示结果——「已发送 ✓」却没弹，说明问题在浏览器/Windows 通知设置（地址栏站点权限、Windows 设置 → 系统 → 通知 → 浏览器通知开关与通知声音、专注助手），与插件逻辑无关。
• 防误报：
  • 页面加载 / 重连后，第一个列表快照只作为基线，不重放历史完成事件；
  • 重连期间发生的完成不会在恢复连接后误报；
  • 同一 pending 状态不重复通知；
  • 子代理会话默认不通知（可在设置中开启）。

安装

从 npm（推荐，安装走 tarball 秒级完成）：

dsh plugin --profile web add dsh-agent-notify

从 GitHub：

dsh plugin --profile web add github:chidaic/dsh-agent-notify

或在 DSH 设置 → 插件市场（dshmarket）中搜索 dsh-agent-notify 一键安装。

浏览器端 bundle 变更后刷新页面即可（/plugins/dsh-agent-notify/client.js 每次读取最新文件；若遇到旧缓存，用 Ctrl+Shift+R 硬刷新）。

配置

无 host 配置。浏览器端设置位于官方设置界面 →「任务提示」页面，持久化于 localStorage。

目录结构

dsh-agent-notify/
├── package.json          # dsh.client 声明（platform: web；inject 已于 rc.1 fork 删除，见 CHANGELOG）
├── cordis.patch.yml      # 插件行（bundle patch）
├── LICENSE               # MIT
├── CHANGELOG.md
├── scripts/
│   └── verify-notify.mjs # 真页面验收探针（只读；6 判据；共用外壳 = dsh-clips/scripts/probe-harness.mjs）
├── test/                 # 单测（node:test · 零依赖，`npm test`；夹具 = test/_harness.cjs）
│   ├── client.test.cjs   # 决策契约：何时发/不发、降级留痕、基线不重放、诊断面
│   └── card.test.cjs     # 设置卡片：注册面、死令牌回归锁、落盘、失败路径
└── lib/
    ├── index.js          # host half（空 apply）
    └── client.js         # 浏览器 bundle（手写，无构建步骤）

测试面分工（2026-10-12 补单测）：① 单测（npm test = node --test "test/*.test.cjs"，21 例，零依赖免安装）= 决策与契约面（何时发/何时不发、降级留痕、基线不重放、注册面与卡片内容契约）；② 无头真页面探针（node dsh/plugins/dsh-agent-notify/scripts/verify-notify.mjs --allow-main，6 判据；口径与证据 = docs/plugin-matrix.md 本包行 + 无头验收报告）= 真 DOM / 真 React / 真弹窗面。⚠ 两册互补、不可互替：单测跑在 node:vm 沙箱（stub React/Notification），证明不了"浏览器里真的弹出来了"。

沿革：2026-09-27 曾按"不假装成功"撤除指向不存在 test/ 的声明（test 脚本 / CI 徽章 / npm test 说明三处）；本次是先有测试再挂声明，故声明重新成立。devDependencies（jsdom / react / react-dom）为真页面链所备，单测不依赖它们。

开发

• 修改 lib/client.js 后运行 node --check lib/client.js 验证语法。
• 单测：npm test（= node --test "test/*.test.cjs"；21 例，零依赖免安装）。改 lib/client.js 的决策面 / 卡片文案 / 令牌名后必跑；新增测试文件按 test/<名>.test.cjs 命名即被 glob 收进（无需改脚本）。
• 行为改动必须跑真页面探针（本包的三个历史缺陷全是「静默失效」型：不报错、不崩、控制台无线索，只有真页面能判）：

  node dsh/plugins/dsh-agent-notify/scripts/verify-notify.mjs --allow-main            # 在役/隔离实例 3080
  node ... --port 3081 --log <该实例启动日志> --allow-main                            # 隔离实例
  

  ⛔ 探针只读（读 computed 样式 + 调插件诊断钩子；会话导航只发生在本探针浏览器内）；token 由共用外壳从启动日志在进程内取用，不打印、不落报告。
• 每次行为变更请递增 BUNDLE_VERSION（设置页会显示，用于诊断浏览器缓存旧 bundle）。
• 页内诊断钩子：__agentNotify.version / sources()（信号源是否解析到）/ preview([sessionId])（通知正文会写什么，省略 id 即当前主视图会话）/ events()（最近 20 条通知尝试）。

许可

MIT © chidaic