dsh-web-notify

 

[English version](#dsh-web-notify-english) · 默认中文

> 本插件由 DeepSeek Harness（官方 cordis / @deepseek-ai/dsh-* 插件栈）驱动，结合 DeepSeek-V4-Flash-0731 模型参数的官方事件帧构建。 > > 当前 DeepSeek Harness 处于开发预览快速迭代期，推荐以开发调试模式（link: 本地仓库）挂载本插件：改代码后 npm run build 即时生效，配合 window.__NOTIFICATIONS__ diagnostics 排查问题最顺手；当然也提供了 npm 一键挂载的备选方式。

DSH Web GUI 的审批注意力插件：当任意会话出现待处理的审批 / 计划审批 / 提问时，浏览器不再静默——提示音、标签页标题与 Favicon 徽标、OS 通知、右下角通知中心同步呈现；会话完成、任务失败、连接掉线、模型/工具异常（429 配额等）也有提醒。检测管道覆盖全部会话行（含子代理）；受运行时委派策略约束，被委派的子代理实际上不会产生待审批/提问，其完成 / 失败 / 异常提醒照常生效（详见下文「子代理通知可达性」）。

纯插件形态：host 半（lib/index.js）+ client 半（lib/client.js，loader 格式），通过 profile patch 挂载。

快速上手（推荐路径）

① 克隆仓库 → 安装依赖 → 构建产物
        ↓
② link:仓库目录 挂入 web profile
        ↓
③ 放行设置命名空间（patch 脚本）
        ↓
④ 重启 dsh web → 设置页找到「通知」卡片 → 按自己需求开关通道/音量/免打扰
        ↓
⑤ DevTools 控制台观察 window.__NOTIFICATIONS__ ：
     applied / cardRegistered / monitors / lastHeartbeatAt
     hostStatuses / hostStatusCounts  ← 宿主投递的 job 状态词汇
     feedCounters                     ← 每类事件计数
     jobSamples / seenStatuses        ← 浏览器侧采样环
     demo() / demoSound()             ← 一键 UI / 音频 demo

场景应用

1. 待处理审批 / 计划审批 / 提问到达

任意会话（包括未打开过的子代理）出现 pendingInteraction 即触发；同一 (会话, kind) 在冷却期（默认 5s）内不重复报警。

当前会话降级：页面可见且新审批属于当前打开的会话时，提示音与 OS 通知静默（用户眼睛就在这），仅保留视觉通道；切走或最小化后恢复全通道。

子代理通知可达性：会话列表是客户端 lineage 展开后的同一张表（子代理行 origin: 'subagent' 按 parentSessionId 嵌套），因此检测管道天然覆盖子代理行——一旦某个子代理行挂上 pendingInteraction，提示音 / 徽标 / OS 通知 / Dock 全通道照常触发。但按当前 DSH 委派语义，被委派的子代理实际上不会产生这三种待处理状态：

• 审批：dsh-subagent 在委派边界把子代理的审批策略固定为 'never'（无论父级策略如何），任何需审批操作（如 sandbox 升权）被确定性拒绝，不产生 approval/requested 帧，也就没有 pendingInteraction；
• 提问 / 计划审批：dsh-user-questions 对受父级持有的调用方抛 DELEGATED_CALLER，子代理只能把未决问题写进最终结果，由父级代为询问；计划审批只是 intent.kind === 'plan-review' 的提问分类，同样不会产生；
• 因此通知中心里只可能出现父会话的审批条目，子代理行永远不会亮起待处理点。

与之相对，子代理的完成、任务失败、模型/工具异常走 session/event 流与 jobs 归集，覆盖所有会话，提醒照常生效。

2. 会话 / 子代理完成

任意会话 turn/end 完成 → 完成 toast 卡片（右上角，done 变体）+ 完成单音 + 可选 OS 通知。

• 页面可见 + 当前会话完成：toast / OS 静默，仅兜底播一声软完成音（用户可能滚走）
• 页面隐藏：无 toast（看不到），改用 tab 标题脉冲 + PWA 角标 + 提示音 + OS 通知

3. 任务失败

jobsBySession 中 job 状态为 failed / killed、或 completed 但 detail 非空且非 exit code: 0（DSH 真机异常终态映射）→ error 变体 toast + 提示音 + 可选 OS 通知。按 job 注册号只报一次。

4. 模型 / 工具运行异常（429 配额等）

宿主订阅官方 session/event 流，捕获 llm/retry（429 配额 / 限流）、turn/end 的 error / max-tokens / interrupted、tool/result 的 error / isError → error 变体 toast（错误原文进 body，截 240 字符）+ 提示音 + 可选 OS 通知。同会话同 kind 在冷却期内不重复。

5. 掉线 / 重连

共享 connection 服务断线持续超过 connectionAlertAfterMs（默认 10s）→ warning toast + 提示音；恢复时轻 toast + 完成单音。快速闪断（未跨阈值）不报。启动期从未连上过不报。

配置参数

设置卡片注册进 DSH Web 设置页的「插件配置」→「通知」（官方 settings.plugin.item 槽位），改完即生效（120 ms debounce 热重配，无需重启）。

几个常用调法示例：

• 只要审批不要失败/断线：completion=false、connection=false、jobFailure=false、agentError=false
• 只想听响，不喜欢卡片弹：toast=false、notify=false，保留 sound + badge + dock
• 夜间开发免打扰：quiet.enabled=true、quiet.start=22:00、quiet.end=09:00，提示音全关、视觉照常
• 只接 PWA / 任务栏，系统通知弹了嫌吵：notify=false、badge=true、dock=true

安装

DSH 插件通过 dsh plugin 命令安装进 profile（dsh web 对应 web profile）。考虑到 DeepSeek Harness 当前处于开发预览快速迭代期，推荐开发调试模式挂载，便于即时迭代与 diagnostics 排查；当然也提供了 npm 一键挂载的备选方式。

前提条件

• Node.js >= 22
• pnpm — dsh plugin 内部使用 pnpm 安装依赖：npm install -g pnpm
• dsh CLI — 若未全局安装，所有 dsh 命令前缀 npx @deepseek-ai/dsh，如 npx @deepseek-ai/dsh plugin --profile web add dsh-web-notify

方式一：开发调试模式挂载（当前推荐）

# 1. 克隆仓库
git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify

# 2. 安装依赖并构建（需要 Node.js >= 22）
npm install
npm run build

# 3. 把仓库挂进 web profile（link: 指向仓库根目录）
dsh plugin --profile web add link:$(pwd)
# Windows PowerShell: dsh plugin --profile web add link:$PWD.Path

# 4. 重启 dsh web，设置页「插件配置」下即出现「通知」卡片
dsh web

方式二：npm 一键挂载

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

AI 编码工具 / 沙箱环境注意事项

在 TRAE、Cursor 等 AI 编码工具中安装本插件时，需注意：

1. 沙箱写限制：AI 工具的沙箱通常阻止写入 ~/.dsh/ 目录，而 dsh plugin 和 dsh web 都需要写 profile 文件。必须在 AI 工具外部的普通终端中执行这些命令。 2. 切勿手动 npm install：手动把包塞进 ~/.dsh/profiles/web/node_modules/ 会绕过 dsh plugin 的依赖链接逻辑，导致插件的 @deepseek-ai/* peer 依赖与 DSH host 的模块树脱节，settings 服务不可达，命名空间注册静默失败（卡片永远只读）。 3. 始终用 dsh plugin --profile web add：这是唯一正确的安装方式，它会通过 pnpm 正确链接依赖、更新 package.json 和 cordis.patch.yml。

安装后校验

安装完成并重启 dsh web 后，检查以下文件和指标：

放行设置命名空间（可选，但推荐）

DSH 官方 apiproxy 的 WEB_SETTINGS_NAMESPACES 是硬编码白名单，第三方命名空间默认只读。运行一次本仓库的 patch 脚本把 notifications 注入白名单：

node scripts/patch-apiproxy.mjs

之后设置卡片可读可写；不放行则卡片只读，DEFAULTS 生效。dsh 升级后需重跑此脚本（脚本幂等，重跑安全）。

为什么必须 patch（官方暂无优雅注入方式）

DSH 官方把 settings 白名单（WEB_SETTINGS_NAMESPACES）与 host 事件转发白名单（API_REMOTE_FORWARDED_EVENTS）硬编码在包里，暂不开放插件注入（官方注释标记为 deferred work，见 deepseek-ai/deepseek-harness），所以只能 patch bundle。脚本在运行时用 os.homedir() 定位 npx 缓存并自动发现 _npx/<hash> 目录，换机器无需改路径。

Diagnostics 观察调试

插件加载后，在 DSH Web 页面打开 DevTools Console：

// 插件是否完整挂载
> __NOTIFICATIONS__.applied, __NOTIFICATIONS__.cardRegistered
  true, true

// 绑定到了哪个 settings provider，sessions / connection 服务是否可用
> __NOTIFICATIONS__.binder, __NOTIFICATIONS__.sessions, __NOTIFICATIONS__.connAvailable
  "settingsScope", true, true

// 宿主事件通道健康度（~30s 一次心跳；lastHeartbeatAt 不变表示 host feed 断了）
> __NOTIFICATIONS__.feedCounters, __NOTIFICATIONS__.lastHeartbeatAt
  { heartbeat: 4, "agent-error": 1, … }, 1756789012345

// 宿主投递的 job 状态全量词汇（可对照 sentinel / lifecycle 对哪些终态做判断）
> __NOTIFICATIONS__.hostStatuses, __NOTIFICATIONS__.hostStatusCounts
  ["failed","killed","completed","running",…], { completed: 8, failed: 2, … }

// 浏览器侧采样（diagnostics=true 时开启，最近 60 帧）
> __NOTIFICATIONS__.jobSamples[0]
  { ts, sessionId, sessionTitle, jobs: [{ jobId, status }], alerts: [] }

// 一键 demo 卡片 / demo 提示音（排查 UI 与音频是否能响）
> __NOTIFICATIONS__.demo("error")     // 弹 error 变体卡片
> __NOTIFICATIONS__.demoSound(0.3)    // 以指定音量播放完成单音

生效

插件集合变更必须重启 dsh web——仅刷新页面不会注册新包（官方 client-modules 文档明确：包元数据按名缓存且永不过期）。白名单 patch 之后也要重启。

验证

1. 设置页「插件配置」下出现独立的「通知」卡片，字段可编辑 2. 触发一个待审批：标签页标题出现 ⚠ 1 待审批 —，Favicon 显示红底数字 1，右下角 Dock 出现 FAB 与列表，播放三连音，OS 通知弹出（首次需授权） 3. 点击 OS 通知或 Dock 行的「去处理」→ 窗口聚焦并打开对应会话 4. 完成一个会话：右上角弹完成 toast + 完成单音 5. DevTools 控制台可见 [notifications] 前缀的日志；window.__NOTIFICATIONS__ 暴露 apply 分步记录与 jobSamples 采样环

卸载

dsh plugin --profile web remove dsh-web-notify

或删除本地 profile 的 cordis.patch.yml 插入行与 node_modules junction。

限制

• 提醒粒度是会话级（列表行只有 kind 状态）；任务失败能到 job 级（含命令 label 与 exit detail），模型 / 工具异常走事件流原文（截 240 字符）
• 子代理可达性：子代理行位于检测管道内（与会话同一张 lineage 表），但被委派子代理的审批策略固定为 'never'、提问被拒，实际不会产生待审批/计划审批/提问条目——只可能出现父会话的审批；完成 / 失败 / 异常提醒照常覆盖子代理（见上文「子代理通知可达性」）
• 提示音需要页面有过用户手势（浏览器音频策略）；无手势时静默降级为视觉通道
• OS 通知权限在首次提醒后的下一次点击时请求；若 Windows 不弹，检查浏览器站点设置（127.0.0.1 通知权限）与 Windows「专注助手」
• 设置卡片走 settings scope；若宿主 apiproxy 未放行第三方命名空间，卡片只读，DEFAULTS 生效

项目结构

dsh-web-notify/
├── package.json          # dsh.client.platform=web + inject + dsh.bundle.patch
├── cordis.patch.yml      # 插件行 insert
├── src/
│   ├── index.ts          # host 半：settings 命名空间 + systemPrompt 通告 + 事件流转发
│   └── client/           # 浏览器半（零 @deepseek-ai 运行时依赖）
│       ├── index.ts      #   入口：apply/inject/mount + settings scope 热重配 + 卡片注册
│       ├── types.ts      #   本地结构类型 + DEFAULTS
│       ├── locales.ts    #   zh/en 词典 + t()
│       ├── channels.ts   #   WebAudio 提示音 / 免打扰 / OS 通知 / jumpToSession
│       ├── badge.ts      #   标题徽标 + Favicon 徽章（canvas）+ PWA 徽标
│       ├── stores.ts     #   toast / dock 两个 uSES store
│       ├── toast-ui.tsx  #   toast 卡片 + 堆栈
│       ├── toast-mount.tsx
│       ├── sentinel.ts   #   待处理边沿哨兵（Dock 承担视觉，仅打脉冲）
│       ├── lifecycle.ts  #   ① 完成 + ③ 任务失败 + ② 连接监视
│       ├── dock.ts       #   Dock FAB + 面板 + mount + startDock
│       └── settings-card.tsx # 设置卡片
└── scripts/
    ├── build.mjs         # esbuild 构建 → lib/{index.js,client.js}（loader 包装）
    ├── smoke.mjs         # 运行时冒烟（9 场景，对生成产物跑）
    ├── patch-apiproxy.mjs # 把 notifications 注入 apiproxy 白名单
    └── release.mjs       # 发布流水线：build → smoke → pack → publish

License

MIT

---

dsh-web-notify (English)

[中文版](#dsh-web-notify) · Chinese by default

> Built on the DeepSeek Harness (official cordis / @deepseek-ai/dsh-* plugin stack) against event frames produced by the DeepSeek-V4-Flash-0731 model parameters. > > DeepSeek Harness is currently in a fast-iterating dev-preview phase. Mounting this plugin via the dev / debug mode (link: local repo) is recommended: after npm run build changes land immediately, and window.__NOTIFICATIONS__ diagnostics makes troubleshooting smoothest. An npm one-shot install is also provided as an alternative.

Approval-attention plugin for the DSH Web GUI: whenever any session has a pending approval / plan-review / question, the browser rings back — chime, tab-title + favicon badge, OS notification, and a corner dock all surface the event at once. The detection pipe covers every session row including subagents; delegated subagents cannot actually raise approval/question waits under the current runtime delegation policy (see "Subagent notification reachability" below) while their completion / failure / runtime-error alerts work normally. Completions, job failures, disconnects, and model/tool runtime errors (429 quota, etc.) also alert.

Pure plugin form: a host half (lib/index.js) plus a browser half (lib/client.js, loader format), mounted via a profile patch.

Quick start (recommended path)

(1) Clone → install deps → build artefacts
        ↓
(2) Link repo root into the web profile
        ↓
(3) Whitelist the settings namespace (patch script)
        ↓
(4) Restart `dsh web` → find the "Notifications" card in Settings →
    turn channels / volume / quiet-hours on and off as you like
        ↓
(5) In DevTools console, inspect `window.__NOTIFICATIONS__`:
       applied / cardRegistered / monitors / lastHeartbeatAt
       hostStatuses / hostStatusCounts ← job status vocab the host emits
       feedCounters                    ← per-event counters
       jobSamples / seenStatuses       ← browser-side sample ring
       demo() / demoSound()            ← one-shot UI / audio demos

Use cases

1. Pending approval / plan-review / question arrives

Fires on a pendingInteraction edge for any session (including never-opened subagents). The same (session, kind) is not re-alerted during the cooldown window (default 5 s).

Current-session degrade: while the page is visible and the new pending item belongs to the currently open session, chime + OS notify are silenced (you're looking right at it), only the visual surfaces stay active. Switching tabs or minimising restores the full surface.

Subagent notification reachability: the session list is one flattened lineage table (subagent rows with origin: 'subagent' nest under their parentSessionId), so the detection pipe covers subagent rows by construction — any pendingInteraction on a subagent row would fire every channel (chime / badge / OS notify / dock). Under the current DSH delegation semantics, however, a delegated subagent can never actually produce one of the three pending states:

• Approval: dsh-subagent pins the child's approval policy to 'never' at the delegation boundary (regardless of the parent's policy), so any approval-requiring operation (e.g. a sandbox escalation) is deterministically rejected — no approval/requested frame is ever emitted, hence no pendingInteraction;
• Question / plan-review: dsh-user-questions throws DELEGATED_CALLER for callers owned by another live agent, so a subagent can only fold the unresolved question into its final result for the parent to ask; plan-review is merely the intent.kind === 'plan-review' classification of a question frame and cannot occur either;
• As a result only parent-session approval entries can ever show up in the notification dock — a subagent row never lights up a pending marker.

By contrast, subagent completions, job failures and model/tool runtime errors ride the session/event stream and the jobs grouping, which cover every session, and alert normally.

2. Session / subagent completes

A session finishes on turn/end → completion toast card (top-right, "done" variant) + a single completion chime + optional OS notify.

• Visible + current session completion: toast + OS notify are silenced, a soft completion chime plays as a safety net (you might have scrolled away)
• Hidden page: no toast (nobody sees it) — tab-title pulse + PWA badge + chime + OS notify instead

3. Job failure

Any job in jobsBySession whose status is failed / killed, or completed with a non-empty, non-exit code: 0 detail (the DSH real-machine abnormal-terminal mapping) → error-variant toast + chime + optional OS notify. Reported once per registered job id.

4. Model / tool runtime errors (429 quota, etc.)

The host subscribes to the official session/event stream and catches: llm/retry (429 / rate-limit), turn/end flavours error / max-tokens / interrupted, and tool/result with error or isError content → error-variant toast carrying the raw provider message (capped at 240 chars) + chime + optional OS notify. Deduplicated per (session, kind) during the cooldown.

5. Disconnect / reconnect

The shared connection service stays down for longer than connectionAlertAfterMs (default 10 s) → warning toast + chime. On reconnect, a light toast + completion chime. Quick blips that never cross the threshold stay silent. Boot phases where it was never connected never alert.

Configuration

The settings card registers under Plugin settings → Notifications in the DSH Web Settings page (official settings.plugin.item slot). Changes take effect hot (120 ms debounce, no restart).

A few common recipes:

• Approvals only, no failures / disconnects: completion=false, connection=false, jobFailure=false, agentError=false
• Just the chime, hate popping cards: toast=false, notify=false, keep sound + badge + dock
• Late-night silence: quiet.enabled=true, quiet.start=22:00, quiet.end=09:00 — chimes fully off, visuals remain
• Only PWA / taskbar, OS notify is too loud: notify=false, badge=true, dock=true

Install

DSH plugins are installed into a profile via the dsh plugin command (dsh web uses the web profile). Given the DeepSeek Harness is currently in a fast-iterating dev-preview phase, the dev / debug mode mount is recommended for immediate iteration and diagnostics troubleshooting. An npm one-shot install is also provided as an alternative.

Method 1: dev / debug mode mount (recommended right now)

# 1. clone the repo
git clone https://github.com/renpengfei1027/dsh-web-notify.git
cd dsh-web-notify

# 2. install dependencies and build (Node.js >= 22 requ

…