ds-turn-notify

Readme

# ds-turn-notify（含 Windows 版与 macOS 版）

DSH（DeepSeek Harness）Web 会话的背景提醒插件，两个独立插件共存于本仓库：

| 插件 | 目录 | 平台 | 视觉提醒 | 提示音 |
| --- | --- | --- | --- | --- |
| **ds-turn-notify**（Windows 版） | 仓库根目录 | Windows | `powershell.exe` → BurntToast / NotifyIcon 气泡 | `notify.ps1` → SoundPlayer / Beep |
| **ds-turn-notify-mac**（macOS 版） | [`mac/`](mac/) | macOS | `/usr/bin/osascript` → 通知中心 | `/usr/bin/afplay` |

两个插件功能一一对应，仅通知通道不同，各自独立安装、独立配置：

1. **回合完成**（主会话 `turn/end`）——提醒一次；
2. **索要权限**（`approval/asked`）——立即提醒（文案含工具名）。

默认只提醒主会话；子会话（subagent / fork / workflow，`header.origin === 'subagent'`）不提醒。

## 功能

- 零第三方依赖：只用 Node 内置模块 + 系统自带命令；`child_process.spawn` fire-and-forget（`stdio: 'ignore'`、`unref()`），不阻塞 agent turn。
- **仅页面在后台时提醒**（`notifyOnlyWhenHidden`）：浏览器 client 半检测页面可见性（`document.hidden` / 失焦）并经同源路由上报 host，所有 DSH 页面都不可见时才提醒；盯着页面时安静。
- **提醒文案携带当前会话标题**（`showTitle`）：`「标题」第 N 回合完成` / `「标题」会话请求权限：工具名`；无标题自动回退。
- 防抖：同一会话同一类事件在 `debounceMs` 内合并为一次；`approval/asked` 与 `turn/end` 分开计时。
- 任何提醒失败均不影响会话本身（仅 `logger.warn`）。

## 配置项（各插件 `cordis.patch.yml` → `config`）

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `enabled` | bool | `true` | 插件总开关 |
| `sound` | bool | `true` | 是否播放提示音 |
| `soundPath` | string | `''` | 自定义音频路径（Win: wav；Mac: afplay 支持 aiff/m4a/mp3 等） |
| `toast` | bool | `true` | 是否发送视觉提醒 |
| `onlyMainSession` | bool | `true` | 只提醒主会话 |
| `debounceMs` | number | `800` | 同类事件防抖间隔（毫秒） |
| `turnDone` | bool | `true` | 是否在回合完成时提醒 |
| `approval` | bool | `true` | 是否在请求权限时提醒 |
| `notifyOnlyWhenHidden` | bool | `true` | 仅所有 DSH 页面都不可见时提醒 |
| `showTitle` | bool | `true` | 提醒文案是否携带会话标题前缀 |
| `title` | string | `DSH 提醒` | 提醒标题 |

## 安装

Windows 版（仓库根目录）：

```bash
git clone https://github.com/237229953-create/ds-turn-notify.git
cd ds-turn-notify
dsh plugin --profile web add .
```

macOS 版（`mac/` 子目录）：

```bash
git clone https://github.com/237229953-create/ds-turn-notify.git
cd ds-turn-notify/mac
dsh plugin --profile web add .
```

安装后重启 dsh（`dsh web`）生效。

### macOS 通知权限

首次触发提醒时，macOS 可能弹出「终端/iTerm 想发送通知」的授权提示——请允许，否则 `osascript display notification` 不会显示。

## 目录结构

```
ds-turn-notify/
├── package.json        # Windows 版 bundle 元数据
├── cordis.patch.yml    # Windows 版挂载层
├── lib/                # Windows 版主体(index.js / notify.ps1 / client.js)
├── test/               # Windows 版逻辑测试
└── mac/                # macOS 版(独立插件,原 ds-turn-notify-mac 仓库)
    ├── package.json
    ├── cordis.patch.yml
    ├── lib/            # index.js / client.js
    └── test/
```

## 测试

```bash
node test/harness.mjs       # Windows 版
node mac/test/harness.mjs   # macOS 版
```

## 版本

- Windows 版：0.1.0
- macOS 版：0.1.0