dsh-plugin-approval-alert

DeepSeek Harness 审批提醒插件 · Approval Alert for DeepSeek Harness

当 Harness 需要你审批某个操作时，在桌面右下角（浏览器外部）弹出系统级通知，显示所属工作区名称，点击即可跳转到对应工作区；同时播放提示音，提醒不遗漏。

When DeepSeek Harness needs your approval, this plugin pops a native OS notification in the bottom-right corner of your desktop (outside the browser), shows which workspace needs attention, and jumps to that workspace when you click it — with a chime so you never miss a request.

---

功能特性 / Features

• 🔔 系统级通知（Native notifications）：显示在屏幕右下角、浏览器窗口之外；即使你切到其他窗口也能看到。
  OS-level toast on the desktop, visible even when you are in another window.
• ✅ 审批 + 选择方案全覆盖（Approval & decision prompts）：需要审批（approval）或需要你选择方案/回答问题（ask_user_question、方案审阅）时都会弹出通知。
  Notifies on both approval requests and question/plan-choice prompts (ask_user_question, plan review).
• 🏷️ 内容简洁、显示工作区（Concise & workspace-aware）：直接写明哪个工作区需要审批或选择方案（如 工作区「E:\sign」需要审批），不做冗余说明。
  The notification simply names the workspace that needs approval or your input.
• 🌐 多语言通知（Bilingual by system language）：跟随系统语言自动切换——简体中文 / 繁体中文 / 英文（其他语言一律英文）。
  Notification language follows the system: Simplified Chinese / Traditional Chinese / English (anything else falls back to English).
• 🖱️ 点击跳转（Click-to-jump）：点击通知拉回浏览器并跳转到对应工作区/会话；若点击导致浏览器新开窗口/标签页，新页面加载后也会自动打开目标会话。
  Clicking the notification focuses the browser and navigates to the right workspace/session — even when the click opens a brand-new browser window, the fresh page auto-navigates.
• ⏱️ 默认停留时长（OS default duration）：通知按操作系统的默认停留时间显示并自动收起，因此会播放系统自带的通知动画（Win10/Win11/macOS/Linux 各不相同）。
  Notifications linger for the OS's default duration and auto-dismiss, so the system's own notification animation plays (varies by OS).
• 🔊 提示音（Chime）：提醒到达瞬间播放双音上行提示音；首次交互自动解锁音频，规避浏览器自动播放策略，尽可能保证第一声就能听到。
  A two-tone chime plays on arrival; audio is unlocked on the first user gesture so the very first alert is audible.
• 📦 多会话提醒（Multi-session aware）：其他会话（如子代理）需要审批/选择方案时同样会弹通知，点击即可跳转。
  Prompts in other sessions (e.g. subagents) also raise notifications; click to jump.
• 🌐 跨平台（Cross-platform）：基于 Web Notifications API 与 Web Audio API，兼容 Win10 / Win11 / Linux / macOS（通知外观与动画由操作系统决定）。
  Built on the standard Web Notifications & Web Audio APIs; compatible with Win10 / Win11 / Linux / macOS (toast appearance & animation are OS-controlled).

---

工作原理 / How it works

纯浏览器端（Client-only）插件，不触碰审批流水线，对 Harness 零侵入：

• Harness 发起审批时，Web 客户端运行时会把该会话标记为 pendingInteraction: "approval"（响应式）。
• 插件在 shell.overlay（全屏浮层插槽，加法式、不影响任何现有 UI）注册一个"隐形"观察组件，通过标准的 useSessions / useWorkspaces 快照监听审批状态。
• 审批到达 → 通过 sessionIds 反查所属工作区 → 弹出系统通知 + 播放提示音。
• 点击通知 → 原页面存活时直接 sessions.open(目标会话)；否则把目标会话 id 暂存到 localStorage，新开的窗口/标签页加载后会等会话列表就绪再自动打开并清除标记。

A pure browser-client plugin with zero interference:

• When Harness raises an approval, the web client runtime marks that session as pendingInteraction: "approval" (reactively).
• The plugin registers an invisible watcher in the additive shell.overlay slot and observes the standard useSessions / useWorkspaces snapshots.
• On arrival it resolves the owning workspace via sessionIds, shows the OS notification and plays the chime.
• Clicking jumps directly via sessions.open(sessionId); if the click opens a brand-new window, the target session id is staged in localStorage and the fresh page auto-navigates once the session list is ready.

---

使用说明 / Usage

1. 安装本插件（见下方"安装 / Install"）。
2. 首次使用请点击页面任意位置一次：插件会在这次交互中自动请求浏览器"通知"权限并解锁音频。
3. 之后每次需要审批/选择方案：桌面右下角弹出通知（显示工作区名，按系统默认时长自动消失，播放系统通知动画）+ 提示音；点击通知即跳转到对应工作区。
4. 真正的"允许一次 / 拒绝"决策仍在浏览器内的审批卡片上完成。

Notes:

1. Install the plugin (see below).
2. Click anywhere in the page once on first use — the plugin asks for notification permission and unlocks audio on that gesture.
3. Every approval request then raises an OS toast (workspace name, OS default duration) plus a chime; click the toast to jump to the workspace.
4. The actual Allow-once / Reject decision stays on the in-browser approval card.

提示：若系统未弹出通知，请检查浏览器站点权限中的"通知"是否已允许。
If no toast appears, check the site's notification permission in the browser.

---

安装 / Install

方式一：动态插件（当前会话，快速体验）

在 Harness 会话中通过 cordis_define / cordis_run 加载客户端插件（源码见 src/client/index.js），注册到 shell.overlay 插槽即可。

方式二：npm 安装（推荐，可持久化）

插件已发布到 npm（包名 dsh-plugin-approval-alert），一条命令装进你的 profile：

dsh plugin --profile web add dsh-plugin-approval-alert

命令会在 profile 目录执行 pnpm 安装，并自动把声明了 dsh.bundle 的插件加入 profile 的 bundles 层。国内网络建议为 npm 配置 npmmirror 镜像（npm config set registry https://registry.npmmirror.com），无需 VPN 即可安装；直接 npm install dsh-plugin-approval-alert 也可以。

具体接入方式请以官方文档为准：

• deepseek-ai/deepseek-harness — docs/user/develop/basic/publish.md
• docs/user/develop/basic/index.zh.md

---

兼容性 / Compatibility

平台	系统通知	提示音	备注
Windows 10	✅	✅	toast 外观/退出动画由系统决定
Windows 11	✅	✅	圆角通知由系统提供
Linux	✅	✅	取决于桌面环境的通知服务
macOS	✅	✅	系统通知中心呈现

浏览器：Chrome / Edge / Firefox / Safari（需支持 Web Notifications 与 Web Audio API）。

---

许可 / License

MIT