dsh-niao/dsh-niao-message

---

Posts native macOS Notification Center banners at the moments that genuinely need the human: abnormal termination, action needed (questions / approvals) and task complete. Click a banner to open your app; notifications auto-dismiss when you return to the DSH page — never nagging.

✨ Features

Platform: macOS only — notification posting, click behavior and app scanning rely on macOS-specific mechanisms (terminal-notifier, the open command, /Applications).

🗂️ The three groups

💡 A single tool-call failure is not notified — it is an in-process failure and the agent usually retries or continues within the same turn, so it does not mean the task abnormally terminated; only a turn ending abnormally is alerted.

Default templates (all customizable):

Template variables: {reason} (specific reason — Abnormal termination), {tool} (tool awaiting approval — Action needed).

⚙️ Settings panel

After install, open the DSH settings dialog (⚙️ at the sidebar foot); the left nav gains a 「通知管理」 page:

• 是否启用 (Enable): master switch; when off, every group is silent.
• 通知行为 (Behavior): repeat-notification toggle and the app to open on click (auto-scans DeepSeek Harness desktop apps and browsers).
• 通知分组 (Groups): each of the three groups with a toggle, a sound picker and title/message template editors (with variable hints).
• Top-right 保存 (Save) (takes effect immediately, persisted to ~/.dsh/dsh-niao-message.config.json) and 测试通知 (Test) (posts a test banner immediately).

📦 Install

Install the package in a DSH profile (e.g. web):

# Option 1 (official CLI — maintains the bundles list automatically)
dsh plugin --profile web add dsh-niao-message

# Option 2 (manual pnpm)
cd ~/.dsh/profiles/web
pnpm add dsh-niao-message

For the manual way, add the package to the profile's dsh.profile.bundles and restart dsh web:

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

The package declares dsh.bundle (a bundle package), so dsh plugin add appends the bundles entry automatically; dependencies (@deepseek-ai/schemastery, node-notifier) are resolved at install time.

🛠️ Configuration

Priority: Config schema defaults (validated and filled by Cordis) < profile patch cordis.patch.yml config < settings-panel file ~/.dsh/dsh-niao-message.config.json (highest).

Patch-layer override example (config hot-reloads):

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

✅ Verification

• Settings panel: open Settings → 「通知管理」 → 测试通知 → a test banner appears.
• End-to-end: run a task → 「DSH · 任务完成」 appears; when the agent asks → 「DSH · 需要你操作」.
• Click: clicking the banner activates the configured app and deletes the marker file.
• Auto-dismiss: post a notification, switch to another app/tab, then switch back to the DSH page → the plugin's notifications are removed automatically (works in browser tabs and standalone PWA windows).
• Dedupe: leave the first banner un-clicked, trigger another completion → new banner skipped (skipped (un-clicked notification pending) in logs).

🧑‍💻 Development

npm install          # install deps (@deepseek-ai/schemastery + node-notifier + esbuild)
npm run build        # build browser bundle (src/client.js → lib/client.js)
npm run check        # syntax-check host / client / build script / smoke
npm run smoke        # smoke test (fake ctx + fake webServer + capture script, 38 checks, no real banners)

📦 Dependencies

Zero manual install. Everything is shipped with the plugin:

• macOS notification binary: lib/vendor/terminal-notifier.app (arm64, bundled — Apple Silicon works out of the box).
• npm dependency node-notifier (installed automatically): bundles an x86_64 terminal-notifier for Intel Macs.
• macOS built-in open command: click-to-open.
• To use a system-installed terminal-notifier (e.g. Homebrew), set tool in the config.

📄 License

MIT (bundled component licenses in THIRD_PARTY_NOTICES.md)