🔔 dsh-niao-message

DeepSeek Harness 的 macOS 系统通知插件 — 在真正需要你的时候，弹一条通知。

English · 简体中文

· macOS · DeepSeek Harness

在对话的关键节点向 macOS 通知中心弹出横幅：任务异常终止、需要你操作（提问 / 授权）、正常完成。点击横幅直达指定应用；回到 DSH 页面时通知自动清空，绝不打扰。

✨ 特性

| | | |---|---| | 🗂️ 三大通知组 | 「异常终止 / 需要你操作 / 正常完成」三组独立配置：开关、提示音、标题/消息模板，简单直观 | | 🖱️ 点击直达 | 点击横幅执行 open -a '<应用名>'（或按 bundle id 激活 / 自定义 shell），自动扫描本机 DeepSeek Harness 桌面应用与浏览器 | | ✨ 回到页面即自动清空 | 切回 DSH 页面（浏览器页签或独立窗口 PWA）时，本插件弹出的全部通知自动消失——visibilitychange + focus 纯事件驱动，零轮询、零常驻开销 | | 🛡️ 防打扰三件套 | 同类通知 3 秒节流、未点击去重（标记文件 + 过期）、可配置重复通知策略 | | 🚀 零手动安装 | 自带 macOS 通知二进制（arm64 开箱即用；Intel 自动回退 node-notifier 自带 x86_64），无需安装任何系统工具 | | ⚙️ 可视化设置面板 | 设置弹窗 →「通知管理」：开关 / 提示音 / 模板即改即生效，一键「测试通知」 | | 🧩 宿主端事件驱动 | 监听宿主进程的 session/event 与 subagent/end，页签后台 / 最小化时通知照常弹出 |

平台：仅支持 macOS（通知发送、点击行为、应用扫描均依赖 macOS 专属机制，如 terminal-notifier、open 命令、/Applications 目录）。

🗂️ 三大通知组

| 组 | 默认 | 提示音 | 覆盖情况 | |---|---|---|---| | 异常终止 | ✅ 开 | Sosumi | 上下文超限、任务阻塞、任务被中止、任务被中断、回答出错 | | 需要你操作 | ✅ 开 | Ping | 等待用户确认（提问 / 是否继续）、等待用户批准（授权） | | 正常完成 | ✅ 开 | Glass | 回答完成、子代理结束 |

💡 单次工具调用失败不通知——它只是过程性失败，Agent 通常会在同一轮内重试或继续，不代表任务异常终止；只有整轮以异常结束才会提醒。

默认模板（均可自定义）：

| 组 | 标题 | 消息 | |---|---|---| | 异常终止 | DSH · 任务异常终止 | 任务未能正常完成：{reason} | | 需要你操作 | DSH · 需要你操作 | 对话已暂停，等待你的确认或授权 | | 正常完成 | DSH · 任务完成 | 任务已顺利完成 |

模板变量：{reason}（具体原因，异常终止组）、{tool}（等待批准的工具名，需要你操作组）。

⚙️ 设置面板

安装后打开 DSH 设置弹窗（左下角 ⚙️），左侧边出现 「通知管理」 页面：

• 是否启用：总开关，关闭后所有组静默。
• 通知行为：重复通知开关、点击横幅后打开的应用（自动扫描 DeepSeek Harness 桌面应用与浏览器）。
• 通知分组：三大组各一个开关 + 提示音 + 标题/消息模板编辑（含模板变量提示）。
• 右上角 保存（配置即时生效，持久化到 ~/.dsh/dsh-niao-message.config.json）与 测试通知（立即弹一条测试横幅）。

📦 安装

在 DSH profile（如 web）中安装：

# 方式一（官方 CLI，自动维护 bundles 列表）
dsh plugin --profile web add dsh-niao-message

# 方式二（pnpm 手动安装）
cd ~/.dsh/profiles/web
pnpm add dsh-niao-message

手动方式需要把包加入 profile 的 dsh.profile.bundles，然后重启 dsh web：

{
  "dependencies": { "dsh-niao-message": "^0.1.0" },
  "dsh": { "profile": { "bundles": [ "...", "dsh-niao-message" ] } }
}

包声明了 dsh.bundle（组合包），dsh plugin add 会自动追加 bundles 项；依赖（@deepseek-ai/schemastery、node-notifier）随安装自动解析。

🛠️ 配置

配置优先级：Config schema 默认值（插件内置，Cordis 校验并填充） < profile 补丁层 cordis.patch.yml 的 config < 设置面板保存的 ~/.dsh/dsh-niao-message.config.json（最高）。

补丁层覆盖示例（config 改动热加载生效）：

- insert:
    - id: dsh-niao-message
      name: 'dsh-niao-message'
      config:
        click:
          open: DeepSeek Harness
        groups:
          abnormal:
            enabled: true
            sound: Basso
            title: 'DSH · 工具出错'
            message: '任务异常：{reason}'

| 配置项 | 含义 | 默认 | |---|---|---| | enabled | 总开关 | true | | tool | terminal-notifier 可执行文件路径（留空自动探测：插件自带 → node-notifier 自带 → 系统路径） | 自动探测 | | click.open | 点击横幅时用 open -a 打开的应用名 | 空（仅消失） | | click.activate | 备选：按 bundle id 激活应用 | — | | click（字符串） | 备选：自定义点击 shell 命令 | — | | allowRepeat | 存在未点击通知时仍继续弹新通知 | false | | throttleMs | 同类通知节流窗口（毫秒） | 3000 | | approvalGraceMs | 批准宽限期（期内自动放行则静默，毫秒） | 1000 | | pendingFile | 去重标记文件路径 | ~/.dsh/dsh-niao-message-pending.json | | configFile | 设置面板持久化配置文件 | ~/.dsh/dsh-niao-message.config.json | | pendingMaxAgeMs | 标记过期时间（毫秒） | 300000 | | groups.<key>.enabled / sound / title / message | 三大组独立配置（key ∈ abnormal / waiting / success） | 见上表 |

✅ 验证

• 设置面板：打开设置弹窗 → 左侧「通知管理」→ 点「测试通知」→ 通知中心出现测试横幅。
• 功能生效：发起一次任务 → 完成后出现「DSH · 任务完成」；Agent 提问时出现「DSH · 需要你操作」。
• 点击行为：点击横幅 → 配置的应用被激活 + 标记文件被删除。
• 自动清空：发一条通知后切到其它应用/页签，再切回 DSH 页面 → 本插件弹出的通知自动消失（浏览器页签与独立窗口 PWA 均支持）。
• 去重行为：不点第一条通知，再触发一次完成 → 新通知被跳过（插件日志出现 skipped (un-clicked notification pending)）。

🧑‍💻 开发

npm install          # 安装依赖（@deepseek-ai/schemastery + node-notifier + esbuild）
npm run build        # 构建浏览器端 bundle（src/client.js → lib/client.js）
npm run check        # 语法检查宿主端 / 客户端 / 构建脚本 / smoke
npm run smoke        # 冒烟测试（fake ctx + 假 webServer + 录制脚本，不弹真实通知，38 项）

📦 依赖

零手动安装。插件自带了全部所需组件：

• macOS 通知二进制：lib/vendor/terminal-notifier.app（arm64，随插件分发，Apple Silicon 开箱即用）。
• npm 依赖 node-notifier（安装插件时自动安装）：自带 x86_64 版 terminal-notifier，覆盖 Intel Mac。
• macOS 系统自带的 open 命令：点击横幅打开软件。
• 如需使用系统自装的 terminal-notifier（如 Homebrew 版本），在配置里设 tool 即可覆盖。

📄 许可证

MIT（附带组件许可见 THIRD_PARTY_NOTICES.md）