dsh-macos-notify 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrombastiC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# dsh-macos-notify
+
+Native macOS notifications for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with event-specific sounds, notification filtering, multi-task coalescing, and a settings card in the DSH Web UI.
+
+## Features
+
+- Notification Center alerts when a turn completes, fails, is blocked, or waits for approval.
+- Separate sounds for completed, error, aborted, and approval events; any event can be muted.
+- System sound picker plus managed custom sound import and deletion from the Web settings card.
+- Custom imports are converted to AIFF, limited to 5 MB and 10 seconds, capped at 20 managed files / 50 MB total, and stored in `~/Library/Sounds`.
+- A 1.5-second coalescing window and optional digest mode prevent parallel tasks from flooding Notification Center.
+- Recent notification diagnostics explain whether an event was sent, queued, suppressed, or failed.
+- A six-event test matrix validates completed, error, approval, aborted, coalesced, and digest notifications.
+- Daily quiet hours and temporary 30-minute, 1-hour, or 24-hour pauses.
+- Duplicate error suppression with a configurable cooldown window.
+- Project path rules for muting, error-only alerts, or important-project bypasses.
+- Minimum turn-duration filtering avoids notifications for near-instant replies.
+- Optional Web-tab focus suppression and macOS HID idle-time gating.
+- Dedicated wording for API rate limits, including provider retry timing when available.
+- OSC 9 notifications for supported terminals, including tmux DCS passthrough.
+- Live settings updates without restarting DSH.
+
+## Requirements
+
+- macOS
+- Node.js 22 or newer
+- DeepSeek Harness with the `web` profile
+
+## Install
+
+Install the published npm package:
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add dsh-macos-notify
+npx -y @deepseek-ai/dsh web
+```
+
+Alternatively, install the latest source directly from GitHub:
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add github:CrombastiC/dsh-macos-notify
+```
+
+Then open **Settings → Plugins → Plugin configuration → macOS notifications**.
+
+To remove the plugin:
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web remove dsh-macos-notify
+```
+
+### Local development install
+
+From this repository checkout:
+
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add .
+npx -y @deepseek-ai/dsh web
+```
+
+`dsh plugin` anchors relative paths to the invoking directory and forwards the install to pnpm in the selected profile. Avoid absolute-path bundle overlays in `cordis.dev.yml`; install the local package through `plugin add` instead.
+
+## Configuration
+
+The settings namespace is `macos-notify`. Values changed from the Web card apply live.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `onCompleted` | `true` | Notify when a turn completes normally. |
+| `onError` | `true` | Notify for errors and blocked turns. These alerts bypass completion gates and digesting. |
+| `onAborted` | `false` | Notify when a user aborts a turn. |
+| `onApproval` | `true` | Notify immediately when a tool waits for approval. |
+| `minDurationSec` | `30` | Suppress completed-turn notifications shorter than this many seconds; `0` disables the threshold. |
+| `onlyWhenIdleSec` | `0` | Require this many seconds of keyboard/mouse idle time for completed notifications; `0` disables idle gating. |
+| `onlyWhenUnfocused` | `true` | Suppress completed notifications while any DSH Web tab is focused. |
+| `digestMinutes` | `0` | Collect completed notifications into a periodic digest; `0` sends them immediately. |
+| `includeSubagents` | `false` | Include subagent sessions instead of notifying only for top-level sessions. |
+| `channel` | `auto` | `auto`, `osascript`, or `osc9`. |
+| `sounds.completed` | `Glass` | Sound for completed turns. |
+| `sounds.error` | `Basso` | Sound for errors, blocked turns, and rate limits. |
+| `sounds.aborted` | empty | Sound for aborted turns; empty means silent. |
+| `sounds.approval` | `Ping` | Sound for approval requests. |
+| `coalesceMs` | `1500` | Window for merging simultaneous turn results; `0` disables merging. |
+| `quietHoursEnabled` | `false` | Enable the daily local-time quiet period. |
+| `quietStart` | `23:00` | Quiet-period start in local `HH:mm` time. |
+| `quietEnd` | `08:00` | Quiet-period end in local `HH:mm` time. Overnight ranges are supported. |
+| `quietAllowCritical` | `true` | Continue sending error, blocked, and approval alerts during quiet hours. |
+| `pauseUntil` | `0` | Temporary pause deadline as Unix milliseconds; managed by quick actions in the Web card. |
+| `duplicateWindowSec` | `300` | Suppress identical errors from the same session within this window; `0` disables it. |
+| `projectRulesJson` | `[]` | Project rules managed by the Web card. More-specific descendant paths win. |
+| `notifyOnLoad` | `true` | Send a test notification when the plugin loads. |
+
+### Project rule modes
+
+- `mute` — suppress every notification under the configured project path.
+- `errors` — allow only errors, blocked events, and approval requests.
+- `important` — bypass minimum-duration, focus, idle, quiet-hour, and temporary-pause filters.
+
+The settings card keeps the last 50 decisions in process memory. Each row records whether an event was sent, queued, suppressed, or failed and includes the reason. This history resets when DSH restarts and does not contain message content.
+
+## Notification channels
+
+`auto` uses OSC 9 when the terminal is recognized as supporting it, and falls back to `osascript` otherwise.
+
+Recognized OSC 9 terminals include iTerm2, WezTerm, Kitty, Ghostty, and Warp. tmux sessions are wrapped in DCS passthrough automatically.
+
+Sound selection applies to the `osascript` channel. With OSC 9, the terminal controls whether and how a notification sound is played.
+
+## Custom sounds
+
+In the settings card, select **Edit → Import sound**. Supported inputs include AAC, AIFF, CAF, FLAC, M4A, MP3, OGG, Opus, and WAV.
+
+The host validates the extension, decoded size, converted duration, managed-file count, and total managed size before writing anything to the user sound directory. Imports are converted to 44.1 kHz mono AIFF using macOS `afconvert`, with `ffmpeg` as a fallback for formats that `afconvert` cannot decode. Existing files are never overwritten; a numeric suffix is added instead.
+
+New imports are recorded in `~/Library/Application Support/dsh-macos-notify/sounds.json` and can be deleted from the settings card. If a sound is currently selected, deletion asks for confirmation and changes affected events to silent. Files remain in `~/Library/Sounds` if the plugin is removed without deleting them first.
+
+## Known limitations
+
+- The plugin is macOS-only. Native notifications use `osascript`, and custom import uses macOS audio tooling.
+- OSC 9 sound behavior belongs to the terminal and ignores the per-event sound selection.
+- The Web settings card uses the trusted `/macos-notify` RPC channel because the current DSH Web settings proxy has a namespace allowlist for built-in settings.
+- Only sounds imported by v0.2.0 or later are tracked as managed sounds. Earlier manually copied/imported files can still be selected, but must be removed from `~/Library/Sounds` manually.
+
+## Development
+
+The package is intentionally build-free:
+
+- `index.js` — host plugin, event handling, notification delivery, settings RPC, and sound import.
+- `client.js` — hand-written DSH client module for focus reporting and the Web settings card.
+- `cordis.patch.yml` — profile bundle patch.
+
+Run the release checks:
+
+```bash
+node --check index.js
+node --check client.js
+npm test
+npm pack --dry-run
+```
+
+## 中文说明
+
+这是一个仅支持 macOS 的 DeepSeek Harness 通知插件。它可以在任务完成、出错、等待审批时发送系统通知，并支持通知诊断、测试矩阵、每日勿扰、临时暂停、自定义声音管理、重复错误抑制、项目规则、焦点抑制、合并通知和定时汇总。推荐从 npm 安装，也可以直接从 GitHub 安装最新版源码。
+
+## License
+
+[MIT](LICENSE) © 2026 CrombastiC

package/client.js

@@ -0,0 +1,204 @@
+// dsh-macos-notify Web UI: focus reporting, settings, sound management and diagnostics.
+window.__ModuleLoader__.load({
+  id: 'dsh-macos-notify',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    var React = require('react')
+    var h = React.createElement
+
+    var SOUND_ROWS = [
+      ['completed', '任务完成'], ['error', '出错 / 被阻止'],
+      ['aborted', '任务中断'], ['approval', '等待审批'],
+    ]
+    var FALLBACK_SOUNDS = ['Basso', 'Blow', 'Bottle', 'Frog', 'Funk', 'Glass', 'Hero', 'Morse', 'Ping', 'Pop', 'Purr', 'Sosumi', 'Submarine', 'Tink']
+    var RULE_LABELS = { mute: '全部静音', errors: '仅错误与审批', important: '重要项目（忽略过滤）' }
+    var KIND_LABELS = { completed: '完成', error: '错误', aborted: '中断', approval: '审批' }
+    var inputStyle = { width: '150px', padding: '5px 8px', fontSize: '12px', boxSizing: 'border-box', border: '1px solid var(--dsw-alias-border-l2,#444)', borderRadius: '6px', background: 'transparent', color: 'inherit' }
+    var buttonStyle = { padding: '5px 10px', minHeight: '29px', fontSize: '12px', cursor: 'pointer', border: '1px solid var(--dsw-alias-border-l2,#444)', borderRadius: '6px', background: 'transparent', color: 'inherit' }
+    var sectionStyle = { borderTop: '1px solid var(--dsw-alias-border-l2,#444)', paddingTop: '12px', display: 'flex', flexDirection: 'column', gap: '8px' }
+    var rowStyle = { display: 'flex', alignItems: 'center', gap: '9px', minHeight: '30px' }
+    var css = [
+      '@keyframes dshSaved{0%{box-shadow:0 0 0 0 rgba(46,157,98,.3);border-color:rgba(46,157,98,.7)}100%{box-shadow:0 0 0 5px rgba(46,157,98,0)}}',
+      '@keyframes dshShake{0%,100%{transform:translateX(0)}30%{transform:translateX(-3px)}70%{transform:translateX(3px)}}',
+      '.dsh-notify-saved{animation:dshSaved 650ms ease-out both}.dsh-notify-error{animation:dshShake 240ms ease-out both}',
+      '@media(prefers-reduced-motion:reduce){.dsh-notify-saved,.dsh-notify-error{animation:none!important}}',
+    ].join('\n')
+
+    function parseRules(raw) {
+      try {
+        var value = JSON.parse(raw || '[]')
+        return Array.isArray(value) ? value.map(function (rule) { return { path: String(rule.path || ''), mode: String(rule.mode || 'mute') } }) : []
+      } catch { return [] }
+    }
+    function toDraft(settings) {
+      return Object.assign({}, settings, { sounds: Object.assign({}, settings.sounds || {}), projectRules: parseRules(settings.projectRulesJson) })
+    }
+    function toPatch(draft) {
+      return {
+        onCompleted: !!draft.onCompleted, onError: !!draft.onError, onAborted: !!draft.onAborted, onApproval: !!draft.onApproval,
+        minDurationSec: Math.max(0, Number(draft.minDurationSec) || 0), onlyWhenIdleSec: Math.max(0, Number(draft.onlyWhenIdleSec) || 0),
+        onlyWhenUnfocused: !!draft.onlyWhenUnfocused, digestMinutes: Math.max(0, Number(draft.digestMinutes) || 0),
+        includeSubagents: !!draft.includeSubagents, channel: draft.channel || 'auto', sounds: Object.assign({}, draft.sounds),
+        coalesceMs: Math.max(0, Number(draft.coalesceMs) || 0), quietHoursEnabled: !!draft.quietHoursEnabled,
+        quietStart: draft.quietStart || '23:00', quietEnd: draft.quietEnd || '08:00', quietAllowCritical: !!draft.quietAllowCritical,
+        pauseUntil: Number(draft.pauseUntil) || 0, duplicateWindowSec: Math.max(0, Number(draft.duplicateWindowSec) || 0),
+        projectRulesJson: JSON.stringify((draft.projectRules || []).filter(function (rule) { return rule.path.trim() }).map(function (rule) { return { path: rule.path.trim(), mode: rule.mode } })),
+      }
+    }
+    function SectionTitle(props) {
+      return h('div', { style: { display: 'flex', justifyContent: 'space-between', gap: '8px' } },
+        h('strong', null, props.title), props.note ? h('span', { style: { opacity: .55, fontSize: '11px', textAlign: 'right' } }, props.note) : null)
+    }
+    function Toggle(props) {
+      return h('label', { style: rowStyle }, h('input', { type: 'checkbox', checked: !!props.value, disabled: props.disabled, onChange: function (e) { props.onChange(e.target.checked) } }), h('span', { style: { flex: 1 } }, props.label))
+    }
+    function SettingRow(props) {
+      return h('label', { style: rowStyle }, h('span', { style: { flex: 1 } }, props.label, props.note ? h('small', { style: { display: 'block', opacity: .5 } }, props.note) : null), props.children)
+    }
+
+    function Card(props) {
+      var settingsState = React.useState(null), settings = settingsState[0], setSettings = settingsState[1]
+      var draftState = React.useState(null), draft = draftState[0], setDraft = draftState[1]
+      var catalogState = React.useState({ names: [], managed: [], limits: {} }), catalog = catalogState[0], setCatalog = catalogState[1]
+      var diagState = React.useState({ entries: [], status: {} }), diagnostics = diagState[0], setDiagnostics = diagState[1]
+      var editingState = React.useState(false), editing = editingState[0], setEditing = editingState[1]
+      var savingState = React.useState(false), saving = savingState[0], setSaving = savingState[1]
+      var savedState = React.useState(false), saved = savedState[0], setSaved = savedState[1]
+      var importingState = React.useState(false), importing = importingState[0], setImporting = importingState[1]
+      var testingState = React.useState(''), testing = testingState[0], setTesting = testingState[1]
+      var errorState = React.useState(''), error = errorState[0], setError = errorState[1]
+      var fileInput = React.useRef(null), savedTimer = React.useRef(null), testTimer = React.useRef(null)
+
+      var loadSettings = function () { return props.call('settings', { op: 'get' }).then(function (value) { setSettings(value); setDraft(toDraft(value)); return value }) }
+      var loadCatalog = function () { return props.call('sounds', {}).then(function (value) { if (value && Array.isArray(value.names)) setCatalog(value); return value }) }
+      var loadDiagnostics = function () { return props.call('diagnostics', { op: 'get' }).then(setDiagnostics).catch(function () {}) }
+      React.useEffect(function () {
+        Promise.all([loadSettings(), loadCatalog(), loadDiagnostics()]).catch(function (err) { setError(String(err && err.message || '设置读取失败')) })
+        var timer = setInterval(loadDiagnostics, 5000)
+        return function () { clearInterval(timer); if (savedTimer.current) clearTimeout(savedTimer.current); if (testTimer.current) clearTimeout(testTimer.current) }
+      }, [])
+      if (!settings || !draft) return h('div', { style: { padding: '12px', opacity: .6 } }, '加载中…')
+
+      var patch = toPatch(draft), dirty = JSON.stringify(patch) !== JSON.stringify(toPatch(toDraft(settings)))
+      var status = diagnostics.status || {}, pauseActive = Number(status.pauseUntil) > Date.now()
+      var availableSounds = catalog.names.length ? catalog.names : FALLBACK_SOUNDS
+      var change = function (field, value) { setDraft(Object.assign({}, draft, { [field]: value })) }
+      var changeSound = function (kind, value) { setDraft(Object.assign({}, draft, { sounds: Object.assign({}, draft.sounds, { [kind]: value }) })) }
+      var beginEdit = function () { setDraft(toDraft(settings)); setEditing(true); setSaved(false); setError('') }
+      var cancel = function () { setDraft(toDraft(settings)); setEditing(false); setError('') }
+      var save = function () {
+        if (!dirty || saving) return
+        setSaving(true); setError('')
+        props.call('settings', { op: 'patch', value: patch }).then(function (value) {
+          setSettings(value); setDraft(toDraft(value)); setEditing(false); setSaved(true); loadDiagnostics()
+          if (savedTimer.current) clearTimeout(savedTimer.current)
+          savedTimer.current = setTimeout(function () { setSaved(false) }, 1800)
+        }).catch(function (err) { setError(String(err && err.message || '保存失败')) }).finally(function () { setSaving(false) })
+      }
+      var test = function (kind, sound) {
+        setTesting(kind); setError('')
+        props.call('test', { kind: kind, sound: sound }).then(loadDiagnostics).catch(function (err) { setError(String(err && err.message || '测试失败')) })
+        if (testTimer.current) clearTimeout(testTimer.current)
+        testTimer.current = setTimeout(function () { setTesting('') }, 1200)
+      }
+      var pause = function (duration) {
+        var until = duration ? Date.now() + duration : 0
+        props.call('settings', { op: 'set', field: 'pauseUntil', value: until }).then(function () {
+          setSettings(Object.assign({}, settings, { pauseUntil: until }))
+          setDraft(Object.assign({}, draft, { pauseUntil: until }))
+          return loadDiagnostics()
+        }).catch(function (err) { setError(String(err && err.message || '暂停设置失败')) })
+      }
+      var importFile = function (event) {
+        var file = event.target.files && event.target.files[0]; event.target.value = ''
+        if (!file) return
+        if (file.size > 5 * 1024 * 1024) { setError('声音文件不能超过 5MB'); return }
+        setImporting(true); setError('')
+        var reader = new FileReader()
+        reader.onload = function () {
+          props.call('sound/import', { filename: file.name, data: String(reader.result || '').split(',')[1] || '' }).then(function (result) {
+            if (!result || !result.name) throw new Error('导入结果无效')
+            changeSound('completed', result.name); return loadCatalog()
+          }).catch(function (err) { setError(String(err && err.message || '导入失败')) }).finally(function () { setImporting(false) })
+        }
+        reader.onerror = function () { setImporting(false); setError('声音文件读取失败') }
+        reader.readAsDataURL(file)
+      }
+      var deleteSound = function (name, force) {
+        props.call('sound/delete', { name: name, force: !!force }).then(function (result) {
+          if (result && result.requiresConfirmation) {
+            var used = result.inUse.map(function (kind) { return KIND_LABELS[kind] || kind }).join('、')
+            if (window.confirm('“' + name + '”正在用于' + used + '通知。删除后会改为静音，继续吗？')) return deleteSound(name, true)
+            return
+          }
+          var nextSavedSounds = Object.assign({}, settings.sounds)
+          var nextDraftSounds = Object.assign({}, draft.sounds)
+          Object.keys(nextSavedSounds).forEach(function (kind) { if (nextSavedSounds[kind] === name) nextSavedSounds[kind] = '' })
+          Object.keys(nextDraftSounds).forEach(function (kind) { if (nextDraftSounds[kind] === name) nextDraftSounds[kind] = '' })
+          setSettings(Object.assign({}, settings, { sounds: nextSavedSounds }))
+          setDraft(Object.assign({}, draft, { sounds: nextDraftSounds }))
+          return loadCatalog()
+        }).catch(function (err) { setError(String(err && err.message || '删除失败')) })
+      }
+      var updateRule = function (index, field, value) { var rules = draft.projectRules.slice(); rules[index] = Object.assign({}, rules[index], { [field]: value }); change('projectRules', rules) }
+      var removeRule = function (index) { change('projectRules', draft.projectRules.filter(function (_, candidate) { return candidate !== index })) }
+      var addRule = function () { change('projectRules', draft.projectRules.concat({ path: props.getCurrentCwd() || '', mode: 'mute' })) }
+
+      return h('div', { className: saved ? 'dsh-notify-saved' : '', style: { border: '1px solid var(--dsw-alias-border-l2,#444)', borderRadius: '10px', padding: '14px 16px', fontSize: '13px', display: 'flex', flexDirection: 'column', gap: '12px' } },
+        h('style', null, css),
+        h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '10px' } },
+          h('div', null, h('strong', null, 'macOS 通知'), h('div', { style: { opacity: .55, fontSize: '11px', marginTop: '2px' } }, '通道：' + (status.channel || settings.channel) + ' · 诊断记录 ' + diagnostics.entries.length + ' 条')),
+          editing ? h('span', { style: { padding: '3px 7px', borderRadius: '99px', fontSize: '11px', background: 'rgba(47,111,237,.1)' } }, '整体编辑中') : h('button', { style: buttonStyle, disabled: saved, onClick: beginEdit }, saved ? '已保存 ✓' : '编辑全部')),
+        error ? h('div', { className: 'dsh-notify-error', role: 'alert', style: { padding: '7px 9px', borderRadius: '6px', color: '#d94b43', background: 'rgba(217,75,67,.1)' } }, error) : null,
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '运行状态与测试', note: status.quietActive ? '当前处于勿扰时段' : pauseActive ? '通知已暂停' : '运行正常' }),
+          h('div', { style: { display: 'flex', gap: '6px', flexWrap: 'wrap' } }, ['completed', 'error', 'approval', 'aborted', 'coalesced', 'digest'].map(function (kind) {
+            var names = { completed: '完成', error: '错误', approval: '审批', aborted: '中断', coalesced: '合并', digest: '摘要' }
+            return h('button', { key: kind, style: buttonStyle, onClick: function () { test(kind, draft.sounds[kind]) } }, testing === kind ? '发送中…' : '测试' + names[kind])
+          })),
+          h('div', { style: { display: 'flex', gap: '6px', flexWrap: 'wrap', alignItems: 'center' } }, h('small', { style: { opacity: .55 } }, pauseActive ? '暂停至 ' + new Date(status.pauseUntil).toLocaleTimeString() : '临时暂停：'),
+            h('button', { style: buttonStyle, onClick: function () { pause(30 * 60 * 1000) } }, '30 分钟'), h('button', { style: buttonStyle, onClick: function () { pause(60 * 60 * 1000) } }, '1 小时'), h('button', { style: buttonStyle, onClick: function () { pause(24 * 60 * 60 * 1000) } }, '24 小时'), pauseActive ? h('button', { style: buttonStyle, onClick: function () { pause(0) } }, '立即恢复') : null)),
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '通知事件与过滤' }),
+          [['onCompleted', '任务完成'], ['onError', '错误与阻止'], ['onApproval', '等待审批'], ['onAborted', '用户中断']].map(function (row) { return h(Toggle, { key: row[0], disabled: !editing, value: draft[row[0]], label: row[1], onChange: function (value) { change(row[0], value) } }) }),
+          h(Toggle, { disabled: !editing, value: draft.onlyWhenUnfocused, label: '仅在 DSH 页面未聚焦时发送完成通知', onChange: function (value) { change('onlyWhenUnfocused', value) } }),
+          h(Toggle, { disabled: !editing, value: draft.includeSubagents, label: '包含子 Agent 会话', onChange: function (value) { change('includeSubagents', value) } }),
+          [['minDurationSec', '完成通知最短耗时（秒）'], ['onlyWhenIdleSec', '键鼠空闲门槛（秒）'], ['digestMinutes', '摘要间隔（分钟）'], ['coalesceMs', '合并窗口（毫秒）'], ['duplicateWindowSec', '重复错误抑制（秒）']].map(function (row) { return h(SettingRow, { key: row[0], label: row[1] }, h('input', { style: inputStyle, type: 'number', min: 0, disabled: !editing, value: draft[row[0]], onChange: function (e) { change(row[0], e.target.value) } })) }),
+          h(SettingRow, { label: '通知通道' }, h('select', { style: inputStyle, disabled: !editing, value: draft.channel, onChange: function (e) { change('channel', e.target.value) } }, h('option', { value: 'auto' }, '自动'), h('option', { value: 'osascript' }, 'osascript'), h('option', { value: 'osc9' }, 'OSC 9')))),
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '每日勿扰', note: '使用本机时间' }),
+          h(Toggle, { disabled: !editing, value: draft.quietHoursEnabled, label: '启用每日勿扰时段', onChange: function (value) { change('quietHoursEnabled', value) } }),
+          h(SettingRow, { label: '时段' }, h('span', { style: { display: 'flex', alignItems: 'center', gap: '6px' } }, h('input', { 'aria-label': '勿扰开始时间', style: Object.assign({}, inputStyle, { width: '104px' }), type: 'time', disabled: !editing, value: draft.quietStart, onChange: function (e) { change('quietStart', e.target.value) } }), h('span', null, '至'), h('input', { 'aria-label': '勿扰结束时间', style: Object.assign({}, inputStyle, { width: '104px' }), type: 'time', disabled: !editing, value: draft.quietEnd, onChange: function (e) { change('quietEnd', e.target.value) } }))),
+          h(Toggle, { disabled: !editing, value: draft.quietAllowCritical, label: '勿扰时仍允许错误、阻止和审批', onChange: function (value) { change('quietAllowCritical', value) } })),
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '提示音', note: '单个≤5MB/10秒；最多20个/50MB' }),
+          editing ? h('div', { style: rowStyle }, h('input', { ref: fileInput, type: 'file', accept: '.aac,.aif,.aiff,.caf,.flac,.m4a,.mp3,.oga,.ogg,.opus,.wav,audio/*', style: { display: 'none' }, onChange: importFile }), h('button', { style: buttonStyle, disabled: importing, onClick: function () { if (fileInput.current) fileInput.current.click() } }, importing ? '导入中…' : '导入声音'), h('small', { style: { opacity: .55 } }, '已管理 ' + catalog.managed.length + ' 个')) : null,
+          SOUND_ROWS.map(function (row) { var kind = row[0], value = draft.sounds[kind] || '', choices = availableSounds.includes(value) || !value ? availableSounds : [value].concat(availableSounds); return h('div', { key: kind, style: rowStyle }, h('span', { style: { width: '110px' } }, row[1]), h('select', { style: Object.assign({}, inputStyle, { flex: 1, width: 'auto' }), disabled: !editing, value: value, onChange: function (e) { changeSound(kind, e.target.value) } }, h('option', { value: '' }, '静音'), choices.map(function (name) { return h('option', { key: name, value: name }, name) })), h('button', { style: buttonStyle, onClick: function () { test(kind, value) } }, testing === kind ? '播放中…' : '试听')) }),
+          catalog.managed.length ? h('div', { style: { padding: '8px', borderRadius: '7px', background: 'rgba(127,127,127,.06)' } }, catalog.managed.map(function (item) { return h('div', { key: item.name, style: rowStyle }, h('span', { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' } }, item.name), h('small', { style: { opacity: .5 } }, (item.bytes / 1024).toFixed(0) + 'KB'), editing ? h('button', { style: Object.assign({}, buttonStyle, { color: '#d94b43' }), onClick: function () { deleteSound(item.name, false) } }, '删除') : null) })) : null),
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '项目规则', note: '更具体的路径优先' }),
+          draft.projectRules.length ? draft.projectRules.map(function (rule, index) { return h('div', { key: index, style: { display: 'grid', gridTemplateColumns: 'minmax(0,1fr) 150px auto', gap: '6px' } }, h('input', { style: Object.assign({}, inputStyle, { width: '100%' }), disabled: !editing, value: rule.path, placeholder: '/Users/name/project', onChange: function (e) { updateRule(index, 'path', e.target.value) } }), h('select', { style: Object.assign({}, inputStyle, { width: '100%' }), disabled: !editing, value: rule.mode, onChange: function (e) { updateRule(index, 'mode', e.target.value) } }, Object.keys(RULE_LABELS).map(function (mode) { return h('option', { key: mode, value: mode }, RULE_LABELS[mode]) })), editing ? h('button', { style: Object.assign({}, buttonStyle, { color: '#d94b43' }), onClick: function () { removeRule(index) } }, '移除') : h('span')) }) : h('small', { style: { opacity: .55 } }, '尚未配置项目规则'),
+          editing ? h('button', { style: Object.assign({}, buttonStyle, { alignSelf: 'flex-start' }), onClick: addRule }, props.getCurrentCwd() ? '添加当前项目' : '添加规则') : null),
+
+        h('div', { style: sectionStyle }, h(SectionTitle, { title: '最近通知诊断', note: '当前进程最近50条' }),
+          diagnostics.entries.length ? diagnostics.entries.slice(0, 12).map(function (entry) { var colors = { sent: '#238452', suppressed: '#b36b00', queued: '#3867c8', error: '#d94b43' }, labels = { sent: '已发送', suppressed: '已抑制', queued: '排队中', error: '失败' }; return h('div', { key: entry.id, style: { display: 'grid', gridTemplateColumns: '58px minmax(0,1fr) auto', gap: '7px', padding: '6px 0', borderBottom: '1px solid rgba(127,127,127,.12)' } }, h('span', { style: { color: colors[entry.status], fontSize: '11px', fontWeight: 600 } }, labels[entry.status] || entry.status), h('span', null, h('b', null, entry.label || entry.title || entry.kind), h('small', { style: { display: 'block', opacity: .55 } }, entry.detail)), h('small', { style: { opacity: .45, whiteSpace: 'nowrap' } }, new Date(entry.time).toLocaleTimeString())) }) : h('small', { style: { opacity: .55 } }, '暂无记录，可以点击上方测试按钮。'),
+          diagnostics.entries.length ? h('button', { style: Object.assign({}, buttonStyle, { alignSelf: 'flex-start' }), onClick: function () { props.call('diagnostics', { op: 'clear' }).then(setDiagnostics) } }, '清空记录') : null),
+
+        editing ? h('div', { style: { position: 'sticky', bottom: '8px', display: 'flex', gap: '8px', padding: '9px', borderRadius: '8px', background: 'var(--dsw-alias-bg-primary,#1d1d1d)', border: '1px solid var(--dsw-alias-border-l2,#444)', boxShadow: '0 5px 18px rgba(0,0,0,.18)' } }, h('button', { style: Object.assign({}, buttonStyle, { fontWeight: 650 }), disabled: !dirty || saving || importing, onClick: save }, saving ? '保存中…' : dirty ? '保存全部' : '没有改动'), h('button', { style: buttonStyle, disabled: saving || importing, onClick: cancel }, '取消')) : null)
+    }
+
+    exports.inject = ['connection', 'slots', 'sessions']
+    exports.apply = function apply(ctx) {
+      var clientId = crypto.randomUUID()
+      var report = function () { ctx.connection.rpc.call('/macos-notify', 'visibility', { id: clientId, focused: document.visibilityState === 'visible' && document.hasFocus() }).catch(function () {}) }
+      report(); document.addEventListener('visibilitychange', report); window.addEventListener('focus', report); window.addEventListener('blur', report)
+      var timer = setInterval(report, 30000)
+      var call = function (endpoint, payload) { return ctx.connection.rpc.call('/macos-notify', endpoint, payload).then(function (result) { if (!result || result.ok !== true) throw new Error(result && result.error && result.error.message || 'RPC 调用失败'); return result.value }) }
+      var getCurrentCwd = function () { try { var state = ctx.sessions.list.getSnapshot(); return state.current && state.byId[state.current] && state.byId[state.current].cwd || '' } catch { return '' } }
+      ctx.slots.inject('settings.plugin.item', function* () { yield ctx.slots.register({ name: 'settings.plugin.item', id: 'macos-notify', order: 100, inject: function () { return { call: call, getCurrentCwd: getCurrentCwd } } }, Card) })
+      ctx.effect(function () { return function () { clearInterval(timer); document.removeEventListener('visibilitychange', report); window.removeEventListener('focus', report); window.removeEventListener('blur', report) } })
+    }
+    return module.exports
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: macos-notify
+      name: dsh-macos-notify

package/index.js

@@ -0,0 +1,858 @@
+import { execFile } from 'node:child_process'
+import { constants as fsConstants } from 'node:fs'
+import { chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { basename, extname, join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-macos-notify'
+export const inject = ['sessions', 'settings']
+
+export const Config = Schema.object({
+  /** 轮次正常完成时通知 */
+  onCompleted: Schema.boolean().default(true),
+  /** 轮次出错或被阻止时通知（不受 minDurationSec / onlyWhenIdleSec / onlyWhenUnfocused / digestMinutes 限制） */
+  onError: Schema.boolean().default(true),
+  /** 用户取消（中断）时通知 */
+  onAborted: Schema.boolean().default(false),
+  /** 工具等待审批时通知（立即发送，不参与合并） */
+  onApproval: Schema.boolean().default(true),
+  /** 「完成」通知的最短轮次时长（秒）：短于此值的轮次不弹完成通知，0 表示都弹 */
+  minDurationSec: Schema.number().default(30),
+  /** 「完成」类通知仅在键鼠空闲超过此值（秒）时发送，0 关闭。注意：测的是输入空闲，切走应用但还在打字就不算空闲 */
+  onlyWhenIdleSec: Schema.number().default(0),
+  /** 「完成」类通知仅在没有任何浏览器 tab 聚焦 dsh 时发送（切走 tab 或切走应用都会弹）。无客户端上报时（如 headless）视为未聚焦，照弹 */
+  onlyWhenUnfocused: Schema.boolean().default(true),
+  /** 「完成」类通知的汇总间隔（分钟）：攒一批定时合并发送，0 表示实时。审批和出错不受影响 */
+  digestMinutes: Schema.number().default(0),
+  /** 子 agent 会话也通知（默认只通知顶层会话，避免刷屏） */
+  includeSubagents: Schema.boolean().default(false),
+  /** 通知通道：auto = 支持的终端走 OSC 9，否则 osascript；osc9/osascript 强制指定 */
+  channel: Schema.union(['auto', 'osascript', 'osc9']).default('auto'),
+  /** 各事件类型的通知声音（macOS 声音名，空串为静音；OSC 9 通道下声音由终端决定，此配置无效） */
+  sounds: Schema.object({
+    completed: Schema.string().default('Glass'),
+    error: Schema.string().default('Basso'),
+    aborted: Schema.string().default(''),
+    approval: Schema.string().default('Ping'),
+  }).default({ completed: 'Glass', error: 'Basso', aborted: '', approval: 'Ping' }),
+  /** 轮次结束通知的合并窗口（毫秒）：窗口内多个会话的结束合并成一条，0 关闭合并 */
+  coalesceMs: Schema.number().default(1500),
+  /** 是否启用每日勿扰时段 */
+  quietHoursEnabled: Schema.boolean().default(false),
+  /** 每日勿扰开始时间（本机时间，HH:mm） */
+  quietStart: Schema.string().default('23:00'),
+  /** 每日勿扰结束时间（本机时间，HH:mm） */
+  quietEnd: Schema.string().default('08:00'),
+  /** 勿扰时段仍允许错误、阻止和审批通知 */
+  quietAllowCritical: Schema.boolean().default(true),
+  /** 临时暂停截止时间（Unix 毫秒）；0 表示未暂停 */
+  pauseUntil: Schema.number().default(0),
+  /** 相同会话相同错误的重复抑制窗口（秒）；0 表示关闭 */
+  duplicateWindowSec: Schema.number().default(300),
+  /** 项目规则 JSON：[{ path, mode }]，mode 为 mute / errors / important */
+  projectRulesJson: Schema.string().default('[]'),
+  /** 插件加载时发一条测试通知 */
+  notifyOnLoad: Schema.boolean().default(true),
+})
+
+/** 设置页可编辑的提示音字段 */
+const SOUND_KINDS = ['completed', 'error', 'aborted', 'approval']
+const SOUND_EXTENSIONS = new Set(['.aif', '.aiff', '.caf', '.m4a', '.wav'])
+const IMPORT_EXTENSIONS = new Set([
+  '.aac', '.aif', '.aiff', '.caf', '.flac', '.m4a', '.mp3', '.oga', '.ogg', '.opus', '.wav',
+])
+const MAX_SOUND_BYTES = 5 * 1024 * 1024
+const MAX_SOUND_DURATION_SEC = 10
+const MAX_MANAGED_SOUND_COUNT = 20
+const MAX_MANAGED_SOUND_BYTES = 50 * 1024 * 1024
+const MAX_DIAGNOSTICS = 50
+const execFileAsync = promisify(execFile)
+
+function userSoundsDir() {
+  return join(homedir(), 'Library/Sounds')
+}
+
+function soundRegistryPath() {
+  return join(homedir(), 'Library/Application Support/dsh-macos-notify/sounds.json')
+}
+
+async function readSoundRegistry() {
+  try {
+    const parsed = JSON.parse(await readFile(soundRegistryPath(), 'utf8'))
+    return Array.isArray(parsed) ? parsed.filter((item) =>
+      item && typeof item.name === 'string' && typeof item.filename === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+async function writeSoundRegistry(entries) {
+  const path = soundRegistryPath()
+  await mkdir(resolve(path, '..'), { recursive: true })
+  await writeFile(path, `${JSON.stringify(entries, null, 2)}\n`, { mode: 0o600 })
+}
+
+async function managedSoundCatalog() {
+  const dir = userSoundsDir()
+  const registry = await readSoundRegistry()
+  const catalog = []
+  const kept = []
+  for (const item of registry) {
+    const path = join(dir, item.filename)
+    try {
+      const info = await stat(path)
+      if (!info.isFile()) continue
+      kept.push(item)
+      catalog.push({
+        name: item.name,
+        filename: item.filename,
+        bytes: info.size,
+        importedAt: Number(item.importedAt) || info.birthtimeMs || info.mtimeMs,
+      })
+    } catch {
+      // 用户在 Finder 中删除了文件；下次写回时清理失效注册项。
+    }
+  }
+  if (kept.length !== registry.length) await writeSoundRegistry(kept)
+  return catalog.sort((a, b) => b.importedAt - a.importedAt)
+}
+
+function safeSoundName(filename) {
+  const extension = extname(filename).toLowerCase()
+  if (!IMPORT_EXTENSIONS.has(extension)) {
+    throw new Error('不支持该音频格式')
+  }
+  const name = basename(filename, extension)
+    .normalize('NFKC')
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/^\.+|\.+$/g, '')
+    .trim()
+    .slice(0, 80)
+  if (!name) throw new Error('声音文件名无效')
+  return { extension, name }
+}
+
+async function availableSoundPath(name) {
+  const dir = userSoundsDir()
+  await mkdir(dir, { recursive: true })
+  const existing = new Set((await readdir(dir)).map((item) => item.toLowerCase()))
+  for (let suffix = 0; suffix < 1000; suffix += 1) {
+    const candidateName = suffix === 0 ? name : `${name} (${suffix + 1})`
+    const filename = `${candidateName}.aiff`
+    if (!existing.has(filename.toLowerCase())) {
+      return { candidateName, path: join(dir, filename) }
+    }
+  }
+  throw new Error('同名声音文件过多')
+}
+
+async function convertToAiff(input, output) {
+  try {
+    await execFileAsync('/usr/bin/afconvert', ['-f', 'AIFF', '-d', 'BEI16@44100', input, output])
+  } catch (afconvertError) {
+    try {
+      await execFileAsync('ffmpeg', [
+        '-y', '-loglevel', 'error', '-i', input,
+        '-ar', '44100', '-ac', '1', '-c:a', 'pcm_s16be', output,
+      ])
+    } catch {
+      throw new Error(`音频转换失败：${afconvertError?.message ?? '格式无法识别'}`)
+    }
+  }
+}
+
+async function validateSoundDuration(path) {
+  const { stdout } = await execFileAsync('/usr/bin/afinfo', ['-r', path])
+  const match = stdout.match(/estimated duration:\s*([\d.]+)\s*sec/i)
+  const duration = match ? Number(match[1]) : NaN
+  if (!Number.isFinite(duration)) throw new Error('无法读取音频时长')
+  if (duration > MAX_SOUND_DURATION_SEC) {
+    throw new Error(`提示音时长不能超过 ${MAX_SOUND_DURATION_SEC} 秒`)
+  }
+}
+
+async function importSound(payload) {
+  if (typeof payload?.filename !== 'string' || typeof payload?.data !== 'string') {
+    throw new Error('缺少声音文件')
+  }
+  if (payload.data.length > Math.ceil(MAX_SOUND_BYTES * 4 / 3) + 8) {
+    throw new Error('声音文件不能超过 5MB')
+  }
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(payload.data)) {
+    throw new Error('声音文件内容无效')
+  }
+  const bytes = Buffer.from(payload.data, 'base64')
+  if (bytes.length === 0 || bytes.length > MAX_SOUND_BYTES) {
+    throw new Error('声音文件不能超过 5MB')
+  }
+
+  const { extension, name } = safeSoundName(payload.filename)
+  const tempDir = await mkdtemp(join(tmpdir(), 'dsh-macos-notify-'))
+  try {
+    const input = join(tempDir, `input${extension}`)
+    const output = join(tempDir, 'output.aiff')
+    await writeFile(input, bytes)
+    await convertToAiff(input, output)
+    await validateSoundDuration(output)
+    const existing = await managedSoundCatalog()
+    const outputInfo = await stat(output)
+    const usedBytes = existing.reduce((total, item) => total + item.bytes, 0)
+    if (existing.length >= MAX_MANAGED_SOUND_COUNT) {
+      throw new Error(`最多管理 ${MAX_MANAGED_SOUND_COUNT} 个自定义提示音，请先删除不用的声音`)
+    }
+    if (usedBytes + outputInfo.size > MAX_MANAGED_SOUND_BYTES) {
+      throw new Error('自定义提示音总容量不能超过 50MB，请先删除不用的声音')
+    }
+    const destination = await availableSoundPath(name)
+    await copyFile(output, destination.path, fsConstants.COPYFILE_EXCL)
+    await chmod(destination.path, 0o644)
+    try {
+      const registry = await readSoundRegistry()
+      registry.push({
+        name: destination.candidateName,
+        filename: basename(destination.path),
+        importedAt: Date.now(),
+      })
+      await writeSoundRegistry(registry)
+    } catch (err) {
+      await rm(destination.path, { force: true })
+      throw err
+    }
+    return destination.candidateName
+  } finally {
+    await rm(tempDir, { recursive: true, force: true })
+  }
+}
+
+async function deleteManagedSound(name) {
+  const registry = await readSoundRegistry()
+  const index = registry.findIndex((item) => item.name === name)
+  if (index < 0) throw new Error('只能删除由本插件导入并管理的声音')
+  const [entry] = registry.splice(index, 1)
+  const target = resolve(userSoundsDir(), entry.filename)
+  const root = `${resolve(userSoundsDir())}/`
+  if (!target.startsWith(root) || basename(target) !== entry.filename) {
+    throw new Error('声音文件路径无效')
+  }
+  try {
+    await unlink(target)
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+  }
+  await writeSoundRegistry(registry)
+}
+
+/** macOS 系统与用户声音目录；读取失败的目录直接忽略 */
+async function systemSoundNames() {
+  const dirs = [
+    '/System/Library/Sounds',
+    '/Library/Sounds',
+    userSoundsDir(),
+  ]
+  const names = new Set()
+  await Promise.all(dirs.map(async (dir) => {
+    try {
+      const entries = await readdir(dir, { withFileTypes: true })
+      for (const entry of entries) {
+        if (!entry.isFile()) continue
+        const extension = extname(entry.name).toLowerCase()
+        if (SOUND_EXTENSIONS.has(extension)) names.add(basename(entry.name, extension))
+      }
+    } catch {
+      // 目录可能不存在或无读取权限；其余目录仍可用
+    }
+  }))
+  return [...names].sort((a, b) => a.localeCompare(b, 'en'))
+}
+
+async function soundCatalog() {
+  const [names, managed] = await Promise.all([systemSoundNames(), managedSoundCatalog()])
+  return {
+    names,
+    managed,
+    limits: { count: MAX_MANAGED_SOUND_COUNT, bytes: MAX_MANAGED_SOUND_BYTES },
+  }
+}
+
+function esc(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+function notify(title, body, sound, channel, onResult = () => {}) {
+  if (channel === 'osc9') {
+    emitOsc9(title, body)
+    onResult(null)
+    return
+  }
+  const soundPart = sound ? ` sound name "${esc(sound)}"` : ''
+  const script = `display notification "${esc(body)}" with title "${esc(title)}"${soundPart}`
+  execFile('osascript', ['-e', script], (err) => {
+    if (err) console.warn('[dsh-macos-notify] osascript failed:', err.message)
+    onResult(err ?? null)
+  })
+}
+
+// —— OSC 9 通道（思路参考 kimi-code 的 terminal-notification.ts）——
+
+/** 认识 OSC 9 桌面通知的终端白名单；不认识 OSC 9 的终端收到转义序列会打印乱码，所以必须保守 */
+function supportsOsc9(env = process.env) {
+  const termProgram = env.TERM_PROGRAM ?? ''
+  if (['iTerm.app', 'WezTerm', 'ghostty', 'WarpTerminal'].includes(termProgram)) return true
+  const term = env.TERM ?? ''
+  return term === 'xterm-kitty' || term === 'xterm-ghostty'
+}
+
+/** 剥掉控制字符，避免污染终端 */
+function sanitizeOsc9(s) {
+  return String(s).replace(/[\x00-\x1f\x7f]/g, ' ').trim()
+}
+
+function emitOsc9(title, body) {
+  const message = [title, body].map(sanitizeOsc9).filter(Boolean).join(': ').slice(0, 256)
+  if (!message) return
+  let seq = `\x1b]9;${message}\x07`
+  // tmux 会吞掉 OSC，需要 DCS passthrough 包裹并把载荷里的 ESC 双写
+  if (process.env.TMUX) {
+    seq = `\x1bPtmux;${seq.replaceAll('\x1b', '\x1b\x1b')}\x1b\\`
+  }
+  process.stdout.write(seq)
+}
+
+/** macOS 键鼠空闲秒数；读不到时返回 0（视为"人在电脑前"，即不抑制通知） */
+function idleSeconds() {
+  return new Promise((resolve) => {
+    execFile('ioreg', ['-c', 'IOHIDSystem', '-d', '1'], (err, stdout) => {
+      const m = stdout?.match(/"HIDIdleTime" = (\d+)/)
+      resolve(m ? Number(m[1]) / 1e9 : 0)
+    })
+  })
+}
+
+function minuteOfDay(value) {
+  const match = /^(\d{2}):(\d{2})$/.exec(String(value))
+  if (!match) return null
+  const hour = Number(match[1])
+  const minute = Number(match[2])
+  if (hour > 23 || minute > 59) return null
+  return hour * 60 + minute
+}
+
+function quietHoursActive(config, now = new Date()) {
+  if (!config.quietHoursEnabled) return false
+  const start = minuteOfDay(config.quietStart)
+  const end = minuteOfDay(config.quietEnd)
+  if (start === null || end === null || start === end) return false
+  const currentMinute = now.getHours() * 60 + now.getMinutes()
+  return start < end
+    ? currentMinute >= start && currentMinute < end
+    : currentMinute >= start || currentMinute < end
+}
+
+function parseProjectRules(raw) {
+  try {
+    const value = JSON.parse(raw)
+    if (!Array.isArray(value)) return []
+    return value.slice(0, 50).flatMap((item) => {
+      const path = typeof item?.path === 'string' ? item.path.trim() : ''
+      const mode = item?.mode
+      if (!path || !['mute', 'errors', 'important'].includes(mode)) return []
+      return [{ path: resolve(path), mode }]
+    })
+  } catch {
+    return []
+  }
+}
+
+function matchingProjectRule(rules, cwd) {
+  if (!cwd) return null
+  const target = resolve(cwd)
+  return rules
+    .filter((rule) => target === rule.path || target.startsWith(`${rule.path}/`))
+    .sort((a, b) => b.path.length - a.path.length)[0] ?? null
+}
+
+function isCriticalKind(kind) {
+  return kind === '出错' || kind === '被阻止' || kind === '审批'
+}
+
+export function apply(ctx, config) {
+  // 配置三层叠加：schema 默认值 < cordis 组合层（base = 插件 config）< 用户层（设置页）。
+  // 设置页写入后经 watch 实时生效，不需要重启。
+  const scope = ctx.settings.register('macos-notify', Config, { base: config, applies: 'live' })
+  let current = scope.get()
+
+  // sessionId -> 最新标题（session/title 事件是 latest-wins 快照）
+  const titles = new Map()
+  // sessionId -> 本轮 turn/start 的时间戳，用于算轮次时长
+  const turnStartedAt = new Map()
+  // 有未关闭轮次的顶层会话，用于「还有 N 个任务进行中」
+  const running = new Set()
+  // 合并窗口内待发的轮次结束通知（实时通道）
+  let pending = []
+  let flushTimer = null
+  // digest 通道：只攒「完成」
+  let digestPending = []
+  let digestTimer = null
+  // 最近的通知决策，仅保存在当前进程内；设置页用于解释“为什么没弹”。
+  let diagnostics = []
+  let diagnosticSeq = 0
+  // 重复错误键 -> 首次发送时间、被抑制次数
+  const duplicates = new Map()
+  let projectRules = parseProjectRules(current.projectRulesJson)
+
+  const record = (status, item, detail, extra = {}) => {
+    diagnostics.unshift({
+      id: ++diagnosticSeq,
+      time: Date.now(),
+      status,
+      kind: item?.kind ?? '系统',
+      title: item?.title ?? '',
+      label: item?.label ?? '',
+      sessionId: item?.sessionId ?? null,
+      cwd: item?.cwd ?? null,
+      detail,
+      channel: resolvedChannel,
+      ...extra,
+    })
+    if (diagnostics.length > MAX_DIAGNOSTICS) diagnostics.length = MAX_DIAGNOSTICS
+  }
+
+  // 通知通道：auto 在支持的终端里走 OSC 9（终端自己转系统通知），否则 osascript
+  let resolvedChannel = resolveChannel()
+  function resolveChannel() {
+    return current.channel === 'auto' ? (supportsOsc9() ? 'osc9' : 'osascript') : current.channel
+  }
+  const send = (title, body, sound, items = [], options = {}) => {
+    const representative = items[0] ?? { kind: options.kind ?? '系统', title, label: body }
+    notify(title, body, sound, resolvedChannel, (err) => {
+      if (err) {
+        for (const item of items.length ? items : [representative]) {
+          record('error', item, `发送失败：${err.message}`)
+        }
+        return
+      }
+      for (const item of items.length ? items : [representative]) {
+        record('sent', item, options.detail ?? `已通过 ${resolvedChannel} 发送`)
+      }
+    })
+  }
+
+  // 上报「正在看 dsh tab」的浏览器客户端：id -> 最近一次聚焦上报的时间戳
+  const focusedClients = new Map()
+
+  /** 是否有客户端正聚焦在 dsh tab 上（90 秒未上报视为已关闭） */
+  const anyFocused = () => {
+    const cutoff = Date.now() - 90_000
+    for (const [id, at] of focusedClients) {
+      if (at < cutoff) focusedClients.delete(id)
+    }
+    return focusedClients.size > 0
+  }
+
+  // 接收浏览器半的焦点上报、试听与设置读写。connection 服务只在 web profile 存在，
+  // 用 ctx.inject() 延迟挂载：headless 下回调永不触发（视为无人盯着，通知照发）
+  //
+  // 注意一：设置读写走自有 RPC 而不是 settings.describe/mutate 线面——
+  // dsh-host-apiproxy 对暴露给 Web 的设置命名空间有硬编码白名单
+  // （WEB_SETTINGS_NAMESPACES），第三方命名空间目前上不了那条线。
+  // 注意二：共享的 /api 通道只允许一个拦截器（已被 api-gateway 占用），
+  // 所以用 rpc.handle 注册独立通道 /macos-notify。
+  ctx.inject(['connection'], (connCtx) => {
+    try {
+      connCtx.connection.rpc.handle(
+      '/macos-notify',
+      async (endpoint, payload) => {
+        if (endpoint === 'visibility') {
+          const { id, focused } = payload ?? {}
+          if (typeof id === 'string') {
+            if (focused) focusedClients.set(id, Date.now())
+            else focusedClients.delete(id)
+          }
+          return { ok: true, value: null }
+        }
+        if (endpoint === 'test') {
+          // 测试矩阵绕过勿扰和过滤规则，确保能直接验证系统投递通道。
+          const kind = payload?.kind
+          if (SOUND_KINDS.includes(kind)) {
+            const sound = typeof payload?.sound === 'string' ? payload.sound : current.sounds[kind]
+            const labels = {
+              completed: ['完成测试', '模拟任务已完成'],
+              error: ['错误测试', '模拟任务发生错误'],
+              aborted: ['中断测试', '模拟任务已中断'],
+              approval: ['审批测试', '模拟工具正在等待审批'],
+            }
+            const item = { kind: kind === 'approval' ? '审批' : `测试/${kind}`, title: labels[kind][0], label: labels[kind][1] }
+            send(labels[kind][0], labels[kind][1], sound, [item], { detail: '设置页测试通知' })
+          } else if (kind === 'coalesced') {
+            const items = [
+              { kind: '完成', title: '合并测试', label: '示例任务 A' },
+              { kind: '完成', title: '合并测试', label: '示例任务 B' },
+            ]
+            send('2 个任务有结果', '2 个完成：示例任务 A、示例任务 B', current.sounds.completed, items, { detail: '设置页合并通知测试' })
+          } else if (kind === 'digest') {
+            const item = { kind: '完成', title: '摘要测试', label: '3 个示例任务' }
+            send('3 个任务完成', '示例任务 A、示例任务 B、示例任务 C', current.sounds.completed, [item], { detail: '设置页摘要通知测试' })
+          }
+          return { ok: true, value: null }
+        }
+        if (endpoint === 'sounds') {
+          return { ok: true, value: await soundCatalog() }
+        }
+        if (endpoint === 'sound/import') {
+          try {
+            const imported = await importSound(payload)
+            return { ok: true, value: { name: imported } }
+          } catch (err) {
+            console.warn('[dsh-macos-notify] sound import failed:', err?.message ?? err)
+            return {
+              ok: false,
+              error: { code: 'internal', message: String(err?.message ?? err), details: {} },
+            }
+          }
+        }
+        if (endpoint === 'sound/delete') {
+          try {
+            const soundName = typeof payload?.name === 'string' ? payload.name : ''
+            const inUse = SOUND_KINDS.filter((kind) => current.sounds[kind] === soundName)
+            if (inUse.length && payload?.force !== true) {
+              return { ok: true, value: { requiresConfirmation: true, inUse } }
+            }
+            await deleteManagedSound(soundName)
+            if (inUse.length) {
+              const sounds = { ...current.sounds }
+              for (const kind of inUse) sounds[kind] = ''
+              await scope.update({ sounds })
+            }
+            return { ok: true, value: { deleted: true, catalog: await soundCatalog() } }
+          } catch (err) {
+            return { ok: false, error: { code: 'internal', message: String(err?.message ?? err), details: {} } }
+          }
+        }
+        if (endpoint === 'diagnostics') {
+          const op = payload?.op ?? 'get'
+          if (op === 'clear') diagnostics = []
+          anyFocused()
+          return {
+            ok: true,
+            value: {
+              entries: diagnostics,
+              status: {
+                channel: resolvedChannel,
+                configuredChannel: current.channel,
+                focusedTabs: focusedClients.size,
+                quietActive: quietHoursActive(current),
+                pauseUntil: current.pauseUntil,
+                pending: pending.length,
+                digestPending: digestPending.length,
+              },
+            },
+          }
+        }
+        if (endpoint === 'settings') {
+          // 设置卡片读写用户层：get 返回解析后的生效值，set 写入一个字段
+          const op = payload?.op
+          if (op === 'get') return { ok: true, value: scope.get() }
+          if (op === 'set' && typeof payload.field === 'string') {
+            try {
+              await scope.update({ [payload.field]: payload.value })
+              return { ok: true, value: null }
+            } catch (err) {
+              return { ok: false, error: { code: 'internal', message: String(err?.message ?? err), details: {} } }
+            }
+          }
+          if (op === 'patch' && payload.value && typeof payload.value === 'object' && !Array.isArray(payload.value)) {
+            try {
+              const editable = new Set([
+                'onCompleted', 'onError', 'onAborted', 'onApproval', 'minDurationSec',
+                'onlyWhenIdleSec', 'onlyWhenUnfocused', 'digestMinutes', 'includeSubagents',
+                'channel', 'sounds', 'coalesceMs', 'quietHoursEnabled', 'quietStart', 'quietEnd',
+                'quietAllowCritical', 'pauseUntil', 'duplicateWindowSec', 'projectRulesJson',
+              ])
+              if (Object.keys(payload.value).some((key) => !editable.has(key))) throw new Error('包含不可编辑的设置字段')
+              for (const field of ['quietStart', 'quietEnd']) {
+                if (field in payload.value && minuteOfDay(payload.value[field]) === null) throw new Error('勿扰时间格式无效')
+              }
+              if (typeof payload.value.projectRulesJson === 'string') {
+                const parsed = JSON.parse(payload.value.projectRulesJson)
+                if (!Array.isArray(parsed) || parsed.length > 50) throw new Error('项目规则格式无效')
+                if (parsed.some((rule) => typeof rule?.path !== 'string' || !['mute', 'errors', 'important'].includes(rule?.mode))) {
+                  throw new Error('项目规则格式无效')
+                }
+              }
+              await scope.update(payload.value)
+              return { ok: true, value: scope.get() }
+            } catch (err) {
+              return { ok: false, error: { code: 'internal', message: String(err?.message ?? err), details: {} } }
+            }
+          }
+          return { ok: false, error: { code: 'internal', message: 'unknown settings op', details: {} } }
+        }
+        return { ok: false, error: { code: 'internal', message: 'unknown endpoint', details: {} } }
+      },
+      { authority: 'trusted-host' },
+    )
+      console.log('[dsh-macos-notify] RPC intercept mounted')
+    } catch (err) {
+      console.error('[dsh-macos-notify] RPC intercept failed:', err)
+    }
+  })
+
+  const label = (session) =>
+    titles.get(session.id) ??
+    (session.header?.cwd ? basename(session.header.cwd) : String(session.id).slice(0, 8))
+
+  const runningSuffix = () => {
+    const n = running.size
+    return n > 0 ? `（还有 ${n} 个任务进行中）` : ''
+  }
+
+  const makeItem = (kind, title, body, sound, session) => ({
+    kind,
+    title,
+    body,
+    sound,
+    label: label(session),
+    sessionId: session?.id ?? null,
+    cwd: session?.header?.cwd ?? null,
+    important: false,
+  })
+
+  const applyProjectRule = (item) => {
+    const rule = matchingProjectRule(projectRules, item.cwd)
+    if (!rule) return true
+    if (rule.mode === 'mute') {
+      record('suppressed', item, `项目规则已静音：${rule.path}`)
+      return false
+    }
+    if (rule.mode === 'errors' && !isCriticalKind(item.kind)) {
+      record('suppressed', item, `项目规则仅允许错误和审批：${rule.path}`)
+      return false
+    }
+    if (rule.mode === 'important') item.important = true
+    return true
+  }
+
+  const applyTimePolicy = (item) => {
+    if (item.important) return true
+    if (current.pauseUntil > Date.now()) {
+      record('suppressed', item, `通知已暂停至 ${new Date(current.pauseUntil).toLocaleString()}`)
+      return false
+    }
+    if (quietHoursActive(current) && !(current.quietAllowCritical && isCriticalKind(item.kind))) {
+      record('suppressed', item, `当前处于勿扰时段 ${current.quietStart}–${current.quietEnd}`)
+      return false
+    }
+    return true
+  }
+
+  const applyDuplicatePolicy = (item) => {
+    if (!['出错', '被阻止'].includes(item.kind) || current.duplicateWindowSec <= 0) return true
+    const now = Date.now()
+    const key = `${item.sessionId ?? ''}\u0000${item.kind}\u0000${item.body}`
+    const previous = duplicates.get(key)
+    const windowMs = current.duplicateWindowSec * 1000
+    if (previous && now - previous.at < windowMs) {
+      previous.count += 1
+      record('suppressed', item, `重复通知已合并（本窗口第 ${previous.count} 次）`)
+      return false
+    }
+    if (previous?.count) item.body += `（此前重复 ${previous.count} 次）`
+    duplicates.set(key, { at: now, count: 0 })
+    for (const [candidate, value] of duplicates) {
+      if (now - value.at > Math.max(windowMs * 2, 60_000)) duplicates.delete(candidate)
+    }
+    return true
+  }
+
+  // 发送前再检查实时策略；摘要可能在进入队列后才跨入勿扰时段。
+  const gateAndNotify = async (items, sendBatch) => {
+    let allowed = items.filter(applyTimePolicy)
+    if (allowed.length === 0) return
+    if (current.onlyWhenUnfocused && anyFocused()) {
+      allowed = allowed.filter((item) => {
+        if (item.kind !== '完成' || item.important) return true
+        record('suppressed', item, 'DSH Web 页面当前处于聚焦状态')
+        return false
+      })
+    }
+    const idleCandidates = allowed.filter((item) => item.kind === '完成' && !item.important)
+    if (current.onlyWhenIdleSec > 0 && idleCandidates.length) {
+      const idle = await idleSeconds()
+      if (idle < current.onlyWhenIdleSec) {
+        allowed = allowed.filter((item) => {
+          if (item.kind !== '完成' || item.important) return true
+          record('suppressed', item, `键鼠仅空闲 ${Math.floor(idle)} 秒，要求 ${current.onlyWhenIdleSec} 秒`)
+          return false
+        })
+      }
+    }
+    if (allowed.length) sendBatch(allowed)
+  }
+
+  const render = (items) => {
+    if (items.length === 1) {
+      return { title: items[0].title, body: items[0].body, sound: items[0].sound }
+    }
+    // 同类合并：N 个完成 / N 个出错；列表取前 3 个标签
+    const byKind = Map.groupBy(items, (i) => i.kind)
+    const parts = []
+    let sound = ''
+    for (const [kind, group] of byKind) {
+      const names = group.slice(0, 3).map((g) => g.label).join('、')
+      const more = group.length > 3 ? ` 等 ${group.length} 个` : ''
+      parts.push(`${group.length} 个${kind}：${names}${more}`)
+      // 合并通知的声音：有出错优先用出错声，否则用第一条的
+      if (!sound || kind === '出错' || kind === '被阻止') sound = group[0].sound
+    }
+    return { title: `${items.length} 个任务有结果`, body: parts.join('；'), sound }
+  }
+
+  const flush = () => {
+    flushTimer = null
+    const items = pending
+    pending = []
+    if (items.length === 0) return
+    void gateAndNotify(items, (allowed) => {
+      const { title, body, sound } = render(allowed)
+      send(title, body + runningSuffix(), sound, allowed)
+    })
+  }
+
+  const flushDigest = () => {
+    const items = digestPending
+    digestPending = []
+    if (items.length === 0) return
+    void gateAndNotify(items, (allowed) => {
+      const names = allowed.slice(0, 5).map((i) => i.label).join('、')
+      const more = allowed.length > 5 ? ` 等 ${allowed.length} 个` : ''
+      send(
+        `${allowed.length} 个任务完成`,
+        `${names}${more}${runningSuffix()}`,
+        current.sounds.completed,
+        allowed,
+      )
+    })
+  }
+
+  const setupDigest = () => {
+    if (digestTimer) {
+      clearInterval(digestTimer)
+      digestTimer = null
+    }
+    if (current.digestMinutes > 0) {
+      digestTimer = setInterval(flushDigest, current.digestMinutes * 60_000)
+    }
+  }
+  setupDigest()
+
+  // 设置页写入实时生效：换配置快照、重算通道、按新间隔重建 digest 定时器
+  scope.watch((next) => {
+    current = next
+    resolvedChannel = resolveChannel()
+    projectRules = parseProjectRules(current.projectRulesJson)
+    setupDigest()
+  })
+
+  const enqueue = (kind, title, body, sound, session, options = {}) => {
+    const item = makeItem(kind, title, body, sound, session)
+    if (!applyProjectRule(item)) return
+    if (kind === '完成' && options.durationSec < current.minDurationSec && !item.important) {
+      record('suppressed', item, `任务耗时 ${options.durationSec.toFixed(1)} 秒，短于 ${current.minDurationSec} 秒`)
+      return
+    }
+    if (!applyDuplicatePolicy(item)) return
+    if (kind === '完成' && current.digestMinutes > 0) {
+      digestPending.push(item)
+      record('queued', item, `已进入 ${current.digestMinutes} 分钟摘要队列`)
+      return
+    }
+    if (current.coalesceMs <= 0) {
+      void gateAndNotify([item], (allowed) => {
+        send(title, body + runningSuffix(), sound, allowed)
+      })
+      return
+    }
+    pending.push(item)
+    record('queued', item, `等待 ${current.coalesceMs} 毫秒合并窗口`)
+    if (!flushTimer) flushTimer = setTimeout(flush, current.coalesceMs)
+  }
+
+  if (current.notifyOnLoad) {
+    send('DSH', 'macOS 通知插件已加载', current.sounds.completed, [], { detail: '插件加载测试通知' })
+  }
+
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'session/title') {
+      titles.set(session.id, event.data.title)
+      return
+    }
+
+    if (!current.includeSubagents && session.header?.origin === 'subagent') {
+      if (event.type === 'turn/end' || event.type === 'approval/asked') {
+        record('suppressed', makeItem('子 Agent', '通知已过滤', label(session), '', session), '配置已排除子 Agent 会话')
+      }
+      return
+    }
+
+    if (event.type === 'turn/start') {
+      running.add(session.id)
+      turnStartedAt.set(session.id, event.time)
+      return
+    }
+
+    if (event.type === 'turn/end') {
+      running.delete(session.id)
+      const startedAt = turnStartedAt.get(session.id)
+      turnStartedAt.delete(session.id)
+      const durationSec = startedAt ? (event.time - startedAt) / 1000 : Infinity
+
+      const kind = event.data.reason?.kind
+      const name = label(session)
+      if (kind === 'completed') {
+        if (current.onCompleted) enqueue('完成', '任务完成', name, current.sounds.completed, session, { durationSec })
+        else record('suppressed', makeItem('完成', '任务完成', name, current.sounds.completed, session), '完成通知已关闭')
+      } else if (kind === 'aborted') {
+        if (current.onAborted) enqueue('中断', '任务已中断', name, current.sounds.aborted, session)
+        else record('suppressed', makeItem('中断', '任务已中断', name, current.sounds.aborted, session), '中断通知已关闭')
+      } else if (kind === 'blocked') {
+        if (current.onError) enqueue('被阻止', '任务被阻止', name, current.sounds.error, session)
+        else record('suppressed', makeItem('被阻止', '任务被阻止', name, current.sounds.error, session), '错误通知已关闭')
+      } else if (kind === 'error' && current.onError) {
+        const err = event.data.reason?.error
+        if (err?.code === 'RATE_LIMIT' || err?.status === 429) {
+          const retry = err.providerRetryAfterMs
+            ? `，服务商建议 ${Math.ceil(err.providerRetryAfterMs / 1000)} 秒后重试`
+            : ''
+          enqueue('出错', 'API 限流', `${name}: 请求被限流（429）${retry}`, current.sounds.error, session)
+        } else {
+          const msg = err?.message ?? '未知错误'
+          enqueue('出错', '任务出错', `${name}: ${msg}`, current.sounds.error, session)
+        }
+      } else if (kind === 'error') {
+        record('suppressed', makeItem('出错', '任务出错', name, current.sounds.error, session), '错误通知已关闭')
+      }
+      return
+    }
+
+    if (event.type === 'approval/asked' && current.onApproval) {
+      // 审批需要人处理，立即发，不合并
+      const reason = event.data.reason ? ` — ${event.data.reason}` : ''
+      const body = `${label(session)}: ${event.data.toolName}${reason}`
+      const item = makeItem('审批', '等待审批', body, current.sounds.approval, session)
+      if (applyProjectRule(item)) {
+        void gateAndNotify([item], (allowed) => send('等待审批', body, current.sounds.approval, allowed))
+      }
+    } else if (event.type === 'approval/asked') {
+      record('suppressed', makeItem('审批', '等待审批', label(session), current.sounds.approval, session), '审批通知已关闭')
+    }
+  })
+
+  // 卸载时清掉未发出的通知，避免插件已卸载还弹通知
+  ctx.effect(() => () => {
+    if (flushTimer) clearTimeout(flushTimer)
+    if (digestTimer) clearInterval(digestTimer)
+  })
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dsh-macos-notify",
+  "version": "0.2.1",
+  "description": "Native macOS notifications and configurable sounds for DeepSeek Harness",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "client.js", "cordis.patch.yml"],
+  "keywords": ["dsh-plugin", "deepseek-harness", "macos", "notifications"],
+  "author": "CrombastiC",
+  "license": "MIT",
+  "homepage": "https://github.com/CrombastiC/dsh-macos-notify#readme",
+  "bugs": {
+    "url": "https://github.com/CrombastiC/dsh-macos-notify/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CrombastiC/dsh-macos-notify.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "os": ["darwin"],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}