dsh-mobile-push-notify

Readme

# dsh-mobile-push-notify

DeepSeek Harness (dsh) 任务完成通知插件：**一个包、零账号、零手写配置**。

- 电脑端：macOS / Windows / Linux 原生系统通知 + 提示音 + 任务摘要与用时
- 手机端：扫码配对后，iPhone / Android 以 PWA 形式打开同一个 dsh Web 界面，任务完成时收到 **Web Push 锁屏通知**，点击直接回到 dsh 查看结果
- 公网：一键启动 Cloudflare 快速隧道（自动下载 cloudflared，无需账号/域名），人在外面也能收通知和远程查看

## 与现有方案的关系

目前 dsh 生态里最主流的手机远程监控是“远程同屏 Web 壳 + QR 配对 + 隧道 + PWA/Web Push”（代表：`dsh-pocket`、`@linxin666/dsh-remote-web-ui`、`dsh-zen-remote`）。本插件复用同一套成熟模式，但只聚焦一件事：**任务完成时让你第一时间知道**，远程界面复用官方 dsh Web，不做第二套 UI。

## 工作原理（Plugin 层）

一个 npm 包，`cordis.patch.yml` 自动挂三行宿主插件：

| Row | 模块 | 职责 |
|---|---|---|
| `task-notify` | `dsh-mobile-push-notify` | 监听 `session/event` 的 `turn/end` / `goal/change`，发桌面系统通知 |
| `task-notify-gateway` | `dsh-mobile-push-notify/gateway` | spawn 独立网关：扫码配对、反向代理 dsh Web、PWA/Web Push、cloudflared 隧道 |
| `task-notify-push` | `dsh-mobile-push-notify/push` | 同一套会话事件决策，把完成通知 POST 给网关，网关用 VAPID + aes128gcm 推送到手机 |

事件语义（与桌面通知完全一致）：

- 普通轮次 `turn/end` + `reason.kind === 'completed'` → 通知
- `error` / `aborted` → 通知；`max-tokens` / `blocked` 可选
- 目标模式：`goal/change` 的 `phase === 'complete'` 才通知一次，中间轮次不打扰
- 子代理会话（`session.header.parentSession` / `delegationDepth`）默认跳过
- 手机推送对成功类通知做 3s 去抖；错误/取消不去抖

## 安装

```sh
dsh plugin --profile web add dsh-mobile-push-notify
```

然后重启：

```sh
dsh web
```

无需任何配置，桌面通知立即生效；网关管理页会打印在启动日志里：

```text
[dsh-mobile-push-notify-gateway] 已启动 · 管理页 http://127.0.0.1:3188/admin · 反代目标 http://127.0.0.1:3080
```

> 从 git 仓库安装（开发）：`dsh plugin --profile web add link:/path/to/dsh-mobile-push-notify`

## 使用

### 1. 电脑端通知（零配置）

什么都不用做。任务完成时：

- **macOS**：通知中心横幅 + `Glass` 提示音（`osascript`）
- **Windows**：系统 Toast（PowerShell WinRT）
- **Linux**：`notify-send`
- 系统通知失败时自动响终端铃兜底

### 2. 手机配对（一次扫码）

1. 电脑浏览器打开 `http://127.0.0.1:3188/admin`
2. **局域网**：手机和电脑同一 WiFi，扫「局域网配对」二维码即可
3. **公网**：点「开启公网隧道」，首次会自动下载 cloudflared，稍等出现公网二维码后扫码
4. 手机自动进入同一个官方 dsh Web 界面，实时同步

### 3. 开启手机推送（iOS / Android）

1. 配对进入 dsh 后，页面右下角有「🔔 开启任务通知」按钮，点一下并允许通知
2. **iOS**：用 Safari 打开 → 分享 → 添加到主屏幕 → 从主屏幕图标打开 PWA，再点「开启任务通知」（iOS 16.4+；Web Push 必须 HTTPS，请走公网隧道）
3. Android Chrome/Edge：可直接安装 PWA 或允许通知

之后任务完成，手机锁屏会收到：

> **✅ dsh 任务完成**
> 修复 CI 构建失败
> 用时 3min 12s

点击通知会打开 dsh 界面查看结果。

## 配置

三行插件的默认值已经够用。需要调整时，在 `~/.dsh/profiles/web/cordis.patch.yml` 给对应 id 加 `config`（见仓库根目录 `cordis.patch.yml` 的注释），或用环境变量。

### 常用环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `DSH_TASK_NOTIFY_ENABLED` | `1` | 总开关 |
| `DSH_TASK_NOTIFY_EVENTS` | `completed,error,aborted,goal-completed` | 通知事件 |
| `DSH_TASK_NOTIFY_SOUND` | `Glass` | macOS 提示音名；`none` 静音 |
| `DSH_TASK_NOTIFY_BELL` | `0` | 通知失败/无系统通知时响铃 |
| `DSH_TASK_NOTIFY_GATEWAY_PORT` | `3188` | 网关端口 |
| `DSH_TASK_NOTIFY_TARGET_PORT` | 自动读 `dsh web --port` | dsh web 端口 |
| `DSH_TASK_NOTIFY_VAPID_SUBJECT` | `mailto:dsh-mobile-push-notify@users.noreply.github.com` | iOS 严格校验 VAPID subject |
| `DSH_TASK_NOTIFY_PUBLIC_BASE_URL` | 空 | 固定公网地址（如自己的域名反代） |
| `DSH_TASK_NOTIFY_PAIR_PIN` | 空 | 设置后配对需额外输入 PIN |
| `CLOUDFLARED_BIN` | 自动下载 | cloudflared 可执行文件路径 |

### 可选高级推送

桌面通知行仍保留可选 Bark / 通用 webhook（非零配置，按需开启）：

```jsonc
// ~/.dsh/task-notify.json
{
  "barkKey": "你的 Bark key",
  "webhookUrl": "https://example.com/hook/{{title}}"
}
```

或对应环境变量 `DSH_TASK_NOTIFY_BARK_KEY`、`DSH_TASK_NOTIFY_WEBHOOK_URL`。

## 安全模型

- 网关反代到 `127.0.0.1` 的 dsh Web，**不需要把 dsh web 绑定到 0.0.0.0**
- 非回环请求必须携带有效设备 cookie；公网隧道请求按 `cf-connecting-ip` / `x-forwarded-for` 判为远程，不会绕过门禁
- 配对 token 一次性时效 10 分钟，可刷新；设备可逐台撤销，「停止全部配对」同时清空设备与推送订阅
- 管理页 `/admin*` 与推送发送端点只接受回环；配对设备是完整控制凭据，只配对自己控制的设备
- Web Push payload 由 `web-push` 标准 aes128gcm 加密，推送服务只能看到密文
- 公网隧道会把“能执行代码的 dsh”暴露到互联网，请用完即关；需要固定地址可配 `DSH_TASK_NOTIFY_PUBLIC_BASE_URL` + 自己的反代/Cloudflare 命名隧道

## 开发

```sh
npm install
npm test        # 16 个测试:桌面通知决策、网关配对/代理/推送、push row
node lib/gateway-server.js   # 独立跑网关(可用 DSH_TASK_NOTIFY_GATEWAY_CONFIG 传 JSON 配置)
```

发布：

```sh
npm publish     # dshhub / awesome-dsh-plugin 会按 package.json 的 dsh.dshhub 元数据收录
```

## License

MIT