dsh-blocker-notify

English | 简体中文

DeepSeek Harness（DSH）阻塞提醒插件：当 Agent 在工作中被卡住、需要用户介入时，在网页端实时提醒，让你不用一直盯着屏幕等待操作。

触发提醒的三类"阻塞"信号：

信号	说明
提权 / 审批（approval/request）	Agent 请求提升沙箱权限、或需要审批时（如 read-only 下 write 提权）→ 提醒
沙箱拒绝（FS_SANDBOX_DENIED）	write/edit 在 read-only / workspace-write 模式下被拒 → 仅 Host 记录（诊断用），不打扰用户
等待用户交互（question / plan-review）	Agent 在等你回答提问、审阅计划 → 提醒

只提醒需要你操作的事件（审批 / 提问 / 计划审阅）。沙箱拒绝是已完结事件、无可操作项，保持静默（即使审批策略是 never 也不会弹出打扰）。

四种提醒方式

方式	效果
全局消息（横幅）	右上角琥珀色横幅，列出所有被阻塞的会话；每行只显示会话标题 + 状态（不写工具名/原因）；点击条目 = 跳转会话 + 该条立即移除（不依赖审批结果）；✕ 关闭整个横幅；新阻塞到达时重新出现
工作区条目标黄并闪烁	左侧工作区会话条目上的黄色状态点 1.1s 闪烁——黄色标记是 DSH 自带的（"等待用户"状态），本插件加上闪烁动画；阻塞解决后自动停止
提示音（声响）	新增阻塞出现时，页面播放两声短提示音（Web Audio 合成，无需音频文件）；只在阻塞集合变化（有新阻塞）时响，页面加载时已有的阻塞不响；浏览器未解锁自动播放或环境不支持时静默降级
操作系统级通知	新增阻塞出现时，浏览器通过 Notification API 弹出系统通知（Windows 操作中心 / macOS 通知中心）；点击通知可聚焦 DSH 页面（单个阻塞时直接打开对应会话）；单个阻塞显示「会话标题 — 类别（工具名 — 原因）」，多个阻塞合并为一条；权限已开启时横幅标题栏显示小 🔔 图标（点击弹测试通知），未开启/被拒绝时横幅显示操作行（一键开启 / 去浏览器设置修复）

怎么用

方式一：动态插件（快速启用，5 分钟，推荐先试）

不需要安装任何东西，不需要重启 DSH。缺点：进程内存态，DSH 重启后需重新启用。

1. 获取本仓库源码：git clone https://github.com/Frost-Reed/blocker-notify（或直接在 GitHub 页面下载）。

2. 打开任意会话（建议 cordis / 创造模式），把下面这段指令发给 Agent（把 <仓库路径> 换成你本地克隆的路径）：

   请把 dsh-blocker-notify 启用为动态插件：
   1. 用 read 工具读取 <仓库路径>/dynamic/host.js 和 <仓库路径>/dynamic/client.js（分别是 code.host 与 code.client 的函数体，直接使用文件内容）。
   2. 调用 cordis_define：plugin: { kind: "new", idPrefix: "ntfy" }；name: "blocker-notify"；purpose 一句话；code.host = host.js 内容；code.client = client.js 内容。
   3. 用 cordis_define 返回的 pluginId/packageId 调用 cordis_run（mode: "run"）。
   4. 运行请求可能需要用户在网页端批准 Client 半；等待批准结果，不要重复请求。
   5. 完成后用 cordis_inspect_self(pluginId, packageId) 确认 host/client 均为 running。
   

3. 在网页端批准 Client 半的运行请求（一次即可）。

4. 立即验证（见下文"验证"）。

方式二：正式 bundle 安装（持久生效，v0.2.0）

按 DSH 的正式插件规范打包（dsh.bundle + dsh.client），安装后跨重启生效。

若 dsh 不在 PATH（例如从源码仓构建运行、或未全局安装），把下面命令里的 dsh 换成 pnpm dsh（在源码仓根目录）或 npx @deepseek-ai/dsh。

从 GitHub 安装（已发布，推荐）：

dsh plugin --profile web add github:Frost-Reed/blocker-notify

从本地源码安装（开发调试）：

dsh plugin --profile web add file:<本地克隆路径>

安装后：

# 确认进入层栈
Get-Content $env:USERPROFILE\.dsh\profiles\web\package.json   # 应看到 dsh-blocker-notify 出现在 dsh.profile.bundles
# 确认配置树里有行
dsh --dump-config --profile web | Select-String "dsh-blocker-notify"
# 新增依赖/层需要重启进程
dsh web

lib/ 是已提交的构建产物（由 src/ 经 tsdown 生成）。git 安装会运行 prepare 构建脚本，pnpm 需在 allowBuilds 授权一次；也可用 npm 包 / pnpm pack tarball 安装（预构建产物，无需授权）。

验证（两种方式通用）

场景	操作	预期
提问自测	让 Agent 调用一次 ask_user_question	提问弹窗出现时：横幅「等待回答」+ 提示音 + 系统通知；点击横幅行跳转并移除该条
提权审批	设置里把审批策略设为 ask、沙箱设为 read-only，让 Agent 尝试带 sandbox_permissions 的写入	审批卡片出现时：横幅「等待授权」+ 提示音 + 系统通知（含工具名与原因）；点击横幅行跳转并移除（批准与否都移除）
沙箱拒绝	让 Agent 不带提权参数写入被拒文件	静默（无横幅、无提示音、无系统通知；仅 Host 日志记录供诊断）

工作原理

Host 半（进程内，未打 scope 标签 → 观察所有 agent 的审批/工具结果）
  ├─ ctx.on('approval/request', (req, next) => …)   // waterfall，仅观察，必须 return next()
  └─ ctx.on('tools/result', …)                       // 检测 FS_SANDBOX_DENIED
        │  写入进程内告警日志（按 key 去重、10 分钟 TTL、上限 60 条）
        ▼
  详情通道：正式版 = webServer 路由 GET /api/dsh-blocker-notify/alerts
             动态版 = harness.handle('blocker-notify/alerts') RPC
        ▼
Client 半（浏览器页面，根作用域）
  ├─ useSessions（shell.overlay 标准 prop）→ 实时发现 pendingInteraction（approval / plan-review / question）
  ├─ 轮询详情（fetch / host.call）→ 合并审批详情（工具名 / 原因）
  ├─ CSS 注入 → 让 [data-state="warning"] 黄点闪烁
  ├─ Web Audio → 新增可操作阻塞出现时播放提示音（首次交互预热 AudioContext）
  └─ Notification API → 新增可操作阻塞出现时弹系统通知（横幅内一键开启/测试，点击通知跳回页面）

• Host 半：捕获阻塞信号、维护进程内告警日志（纯 JS，无 UI）；沙箱拒绝只记录、不参与提醒。
• Client 半：只展示挂起中的可操作阻塞（审批/提问/审阅，解决或点击即消失）；沙箱拒绝静默。数据来自 shell.overlay 的标准 prop useSessions（快照 { ids, byId, … }，byId 条目带 id / title / pendingInteraction）+ Host 详情轮询。
• 正式版与动态版共用同一套逻辑；仅"详情通道"不同（webServer 路由 vs. 动态 RPC），见 docs/ROUTE-B.md。

常见问题

现象	处理
什么提示都没有	确认确实存在可操作阻塞（提问/审批/审阅；沙箱拒绝已静默）；动态版确认 cordis_inspect_self 里 host/client 均 running；刷新页面重试
只有闪烁、没有横幅	横幅数据来自 useSessions 的 { ids, byId } 结构，确认用的是 pkg-4 / v0.2.0 及以后的版本
只有横幅、没有闪烁	闪烁是 CSS 动画（span[data-state=warning]），确认用的是 pkg-3 / v0.2.0 及以后的版本
动态版重启后失效	正常——动态插件是进程内存态；改走方式二（正式安装）
正式安装后 GUI 看不到	新增依赖/层需重启 dsh web；插件列表在设置页，重新打开刷新
dsh plugin add github:... 第一次失败	包有 prepare 构建脚本（tsdown），pnpm 需要授权：把报错给出的包键加进 $DSH_HOME/profiles/web/pnpm-workspace.yaml 的 allowBuilds 后重跑；lib/ 已提交，也可用 npm 包或 pnpm pack tarball 安装（预构建，无需授权）

开发与构建

• src/ 是 TypeScript 源码（按源码仓官方方法编写）；lib/ 是 tsdown 构建产物（已提交）——pnpm build（tsdown，复刻官方 clientBundle 约定）从 src/ 生成 lib/index.js（ESM 命名导出插件）与 lib/client.js（官方 window.__ModuleLoader__.load({ id, factory }) 格式 web bundle）。
• 提交 lib/ 使 git 安装无需构建授权；prepare 脚本（= tsdown）会在 git 安装时重建产物。
• 离线冒烟测试：node scripts/smoke.mjs（校验两半导出、inject、事件监听、路由 JSON、CSS 注入、槽位注册、渲染、中文文案）。
• dynamic/ 是动态插件函数体（方式一使用），与 lib/ 逻辑一致、通道不同。
• 转正路线 B 的完整调研与实施记录：docs/ROUTE-B.md；新部署启用指南：docs/ENABLE.md。

源码结构

dsh-blocker-notify/
├── LICENSE               # MIT
├── package.json          # bundle（dsh.bundle）+ client（dsh.client）双 manifest
├── README.en.md          # English readme
├── cordis.patch.yml      # bundle patch：插入 Host 行
├── src/                  # TypeScript 源码（源码仓官方方法）
│   ├── index.ts          # Host 半（ESM name/inject/apply + webServer 路由）
│   └── client/index.ts   # Client 半（构建为 ModuleLoader web bundle）
├── tsdown.config.ts      # 构建配置（复刻官方 clientBundle 约定）
├── tsconfig.json
├── lib/                  # tsdown 构建产物（已提交）
│   ├── index.js          # Host 半
│   └── client.js         # Client 半（ModuleLoader 格式）
├── scripts/
│   └── smoke.mjs         # 离线冒烟测试
├── dynamic/              # 动态插件函数体（方式一）
│   ├── host.js
│   └── client.js
└── docs/
    ├── ENABLE.md         # 全新部署启用指南
    └── ROUTE-B.md        # 转正路线 B 实施记录

License

MIT