任务通知推送 1215chen/dsh-plugin-task-notify

DSH 任务通知

把 DSH 的任务完成、失败和授权请求推送到安卓手机

AI 生成声明：本项目的大部分代码、文档和测试由 AI 编程助手生成，维护者已进行审查、运行和修正。

DSH 任务通知是一个自托管的手机通知方案：DSH 每轮任务结束、执行失败，或弹出工具授权请求时，把结果推送到安卓手机。

它支持两条通道：

- 局域网直连：同一 Wi-Fi 下 UDP 自动发现 + HTTP，无需公网。
- 云端中继：通过你自己的 HTTPS 服务器转发，手机和电脑不在同一网络也能收到。

不依赖 FCM、ntfy、账号体系或第三方推送服务。

flowchart LR
D["DSH Desktopdsh-plugin-task-notify"] -->|"LAN: HTTP 8765"| P["Android App"]
D -->|"Cloud: HTTPS POST"| R["Self-hosted relay"]
R -->|"SSE stream"| P
P --> N["Notification + local history"]

功能

| 功能 | 说明 |
| 任务通知 | 完成、失败、取消、中断、输出上限等回合结束状态 |
| 授权通知 | 监听 approval/asked，标题「需要授权」，正文包含工具名和原因 |
| 双通道 | 局域网直连和云端中继可同时开启 |
| 去重 | 同一 payload.id 在 10 分钟窗口内只保留一条通知和一条历史 |
| 本地历史 | 最近 50 条，点按查看详情，点通知自动定位 |
| 自托管云端 | 无第三方推送；SSE 断线重连、离线队列、Last-Event-ID 补发 |
| 安全 | 云端 HTTPS + Bearer Token；App 只信任内置 CA，插件固定同一 CA |

安装

环境要求

| 项目 | 要求 |
| 电脑 | Windows，已安装 DSH |
| 手机 | Android 8.0+（minSdk 26） |
| 局域网 | 手机和电脑在同一 Wi-Fi / 网段 |
| 云端（可选） | Ubuntu 等 Linux 服务器、可访问的 TCP 端口、HTTPS 证书 |

1. 下载

从 Releases 下载：

- DSH-Task-Notify-1.2.1.apk：安卓 App
- dsh-plugin-task-notify-0.2.0.tgz：DSH 插件
- SHA256SUMS.txt：校验值

2. 安装手机 App

1. 把 APK 传到手机并安装。系统提示「未知来源」时，允许当前文件管理器安装。
2. 打开 App，允许通知权限。
3. 接收服务默认启动，首页会显示手机在局域网中的地址，例如 192.168.1.23:8765。
4. 点「发送测试通知」，确认通知栏、声音和锁屏显示正常。
5. 建议把 App 加入电池白名单；vivo / iQOO 还必须允许「后台高耗电」，否则锁屏后服务会被系统冻结。

使用 ADB 安装：

adb install -r release\DSH-Task-Notify-1.2.1.apk

3. 安装电脑端插件

dsh plugin --profile desktop add "$env:USERPROFILE\Downloads\dsh-plugin-task-notify-0.2.0.tgz"

也可以在 DSH 的插件页面选择本地的 dsh-plugin-task-notify-0.2.0.tgz。

安装后确认 profile 的 package.json 包含：

"dependencies": {
"dsh-plugin-task-notify": "file:vendor/dsh-plugin-task-notify-0.2.0.tgz"
}

并且 dsh.profile.bundles 包含 dsh-plugin-task-notify。

4. 选择连接方式

局域网（推荐先跑通）

1. 手机和电脑连接同一个 Wi-Fi。
2. 手机 App 保持「接收服务」开启。
3. 插件默认通过 UDP 8766 自动发现手机，无需填写 IP。

如果自动发现失败（路由器隔离广播、防火墙拦截或访客网络），在 profile 的 cordis.patch.yml 写死手机地址：

- id: task-notify
config:
discover: false
devices:
- host: 192.168.1.23
port: 8765
name: 我的手机

云端（跨网络）

先按 完整配置过程 部署中继，然后在 App 和插件里填写同一个设备 ID 和令牌。

App：设置 → 云端中继，填写服务器地址、设备 ID、令牌，保存。

插件 cordis.patch.yml：

- id: task-notify
config:
cloud:
url: https://<RELAY_HOST>:<RELAY_PORT>
token: <TOKEN>
device: my-phone
caFile: C:/path/to/cloud-ca.pem

caFile 指向部署时生成的 CA 公钥。不要把 token、私钥或 keystore 提交到仓库。

5. 重启 DSH 并验证

插件只在 DSH 启动时加载。安装或修改配置后重启 DSH。

验证方式：

- 在对话里说：「用 phone_notify 测试一下手机通知」
- 或直接完成一轮任务，检查手机通知和 App「最近通知」
- 触发一次工具授权，确认收到「需要授权」通知

云端中继

云端完全可选。手机和电脑不在同一网络时，可以部署一个单用户中继：

- Node.js + systemd，不依赖 Docker
- HTTPS + 自签名 CA（不需要域名，也不需要 80/443）
- 每台设备最近 200 条离线队列
- 手机 App 内置 CA 校验，插件用 caFile 固定校验
- 同时支持局域网 + 云端，手机端自动去重

部署、证书、令牌轮换和新增手机见：

- 完整配置过程
- 云端中继说明

界面

- 手机端 APP 设计依照谷歌 Material Design 3 界面设计语言。
- 通知页只保留运行状态、接收地址、云端状态和最近通知，没有操作按钮。
- 设置页集中所有操作：接收服务、发送测试、电池优化、后台运行、云端中继、端口/设备名/令牌、清空记录和关于。
- 固定深色界面，底部导航切换「通知 / 设置」。
- 应用图标使用 DSH 桌面端的鲸鱼图标；通知栏小图标为白色鲸鱼剪影。

项目结构

.
├─ plugin/ DSH 插件源码与配置参考 ├─ apk/ Android 源码、资源、JVM 测试 ├─ cloud/ 云端中继、CA、systemd/Docker 文件 ├─ docs/ │ ├─ setup.md 从服务器到手机的完整配置过程 │ ├─ protocol.md LAN HTTP、云端 SSE、通知 JSON │ └─ device-test-report.md ├─ release/ 已签名 APK、插件包、校验值 ├─ build-apk.cmd 一键打包 APK └─ 使用说明.md 中文使用与排错手册

从源码构建 APK

需要：

- JDK 17+
- Android build-tools 34
- Android platform 34
- Node.js 22+

仓库不包含 _sdk/、签名密钥或构建产物。准备 SDK 后：

$env:DSH_KEYSTORE_PASSWORD = "your-keystore-password"
.\build-apk.cmd

首次构建会在 apk\keystore\ 生成本地签名密钥；该目录已被 .gitignore 排除。
APK 输出到 release\DSH-Task-Notify-1.2.1.apk。

更详细的构建、测试和签名说明见 apk/README.md。

兼容性与限制

- 已在 vivo V2154A / Android 14 上实测；其他 Android 版本和厂商 ROM 未逐一验证。
- vivo / iQOO 必须允许「后台高耗电」；否则锁屏后进程可能被冻结。
- 局域网模式要求手机和电脑在同一网段；云端模式需要手机能访问中继的 TCP 端口。
- 云端中继使用 SSE 长连接，不是 FCM：如果系统杀掉 App，通知会在下次连接时补发。
- 中继是单用户自托管服务，没有多租户、审计或限流，不要公开给不可信用户。
- 详细排错见 使用说明 和 设备测试报告。

安全

- 局域网默认不校验令牌；在不完全可信的 Wi-Fi 中，请在 App 和插件设置相同的 token。
- 云端使用 HTTPS + Bearer Token；App 只信任内置 CA，插件通过 caFile 固定校验。
- 令牌泄露后，修改服务器 /etc/dsh-notify.env 的 TOKEN，重启中继，再更新 App 和插件。
- 通知正文可能包含工作内容；可在插件配置中设置 includePreview: false。

文档

- 使用说明 — 安装、配置、故障排查、卸载、测试
- 完整配置过程 — Ubuntu、Node、CA、systemd、NAT、插件、App
- 云端中继 — 运维、证书、队列、令牌
- 插件配置参考 — 全部字段、通知规则、安全
- 通信协议 — LAN HTTP、云端 SSE、通知 JSON
- 真机测试报告 — vivo V2154A / Android 14
- 安卓工程 — 源码结构、构建、测试、签名

参与贡献

欢迎提交 Issue 和 Pull Request：

- Bug 请附上系统版本、App 版本、复现步骤和相关日志。
- 不要提交 token、CA 私钥、签名 keystore、服务器 IP 或本机用户路径。
- 修改插件或 App 后，请至少跑一遍相关测试：

插件集成测试
node apk/test/plugin-integration.mjs

云端中继协议测试（需要本地 relay）

node cloud/test-relay.mjs

AI 生成声明

本项目的大部分代码、文档、测试和发布说明由 AI 编程助手生成，维护者负责需求、审查、真机测试和修正。

AI 输出可能包含错误、过时信息或不适合生产环境的默认值。使用前请自行审查，尤其是：

- 云端部署、证书和令牌配置
- Android 签名密钥与发布流程
- 局域网/云端的安全边界

如果你发现 AI 生成内容中的问题，欢迎提交 Issue 或 Pull Request。

许可

插件与 App 源码采用 MIT License。Android SDK 工具仅用于本地构建，不随交付物分发。

AI-generated disclosure: Most of the code, documentation and tests in this
project were generated by AI coding assistants, then reviewed, run and corrected by the
maintainer.

把 DSH 任务完成、失败和审批请求推送到 Android 手机。项目自托管，不依赖 FCM、ntfy、账号系统或第三方推送服务商。

- 局域网：同一 Wi-Fi 下走 UDP 发现 + HTTP。
- 云端中继：通过你自己的服务器做 HTTPS 转发，支持 SSE 和离线队列。
mermaid
flowchart LR
D["DSH Desktopplugin"] -->|"LAN HTTP 8765"| P["Android App"]
D -->|"HTTPS POST"| R["Self-hosted relay"]
R -->|"SSE"| P
P --> N["Notification + history"]

功能

| 功能 | 说明 |
| 任务事件 | 完成、失败、取消、中断、token 上限 |
| 审批 | approval/asked → 「需要审批」，附带工具名和原因 |
| 双通道 | 局域网和云端可同时开启 |
| 去重 | 同一个 payload.id 在 10 分钟窗口内只投递一次 |
| 历史 | 最近 50 条通知，点开看详情 |
| 自托管云端 | SSE 重连、离线队列和 Last-Event-ID 重放 |
| 安全 | HTTPS + Bearer token；App 信任内置 CA，插件固定同一个 CA |

安装

1. 从 Releases 下载最新 APK 和插件。
2. 安装 APK，授予通知权限，允许后台活动。
vivo/iQOO 还需允许高后台耗电。
3. 安装桌面插件：

powershell
dsh plugin --profile desktop add "$env:USERPROFILE\Downloads\dsh-plugin-task-notify-0.2.0.tgz"

4. 局域网模式下，手机和桌面保持在同一 Wi-Fi。如果 UDP 发现被拦截，在 cordis.patch.yml 里固定手机地址：

yaml
- id: task-notify
config:
discover: false
devices:
- host: 192.168.1.23
port: 8765

5. 云端模式需要两端都配置。App：Settings → Cloud relay。插件：

yaml
- id: task-notify
config:
cloud:
url: https://<RELAY_HOST>:<RELAY_PORT>
token: <TOKEN>
device: my-phone
caFile: C:/path/to/cloud-ca.pem

6. 重启 DSH。用 phone_notify 工具或完成一个任务来验证。

服务器/CA/token 的详细配置见 docs/setup.md。中继运维见 cloud/README.md。

构建

要求：JDK 17+、Android build-tools 34、platform android-34 和 Node.js 22+。
powershell
$env:DSH_KEYSTORE_PASSWORD = "your-keystore-password"
.\build-apk.cmd
APK 会写入 release\DSH-Task-Notify-1.2.1.apk。签名密钥和 _sdk/ 已加入 git 忽略列表。

兼容性与安全

- 已在 vivo V2154A / Android 14 上测试；其他 ROM 未验证。
- 云端中继是单用户服务，没有多租户隔离、审计和限流。不要把它暴露给不受信任的用户。
- 局域网使用可选的共享 token。云端使用 HTTPS + Bearer token 和 CA 固定。
- 通知正文可能包含工作内容；如有需要，设置 includePreview: false。
- SSE 不是 FCM：如果系统杀掉应用，消息会在下次连接时重放。

文档

- 中文使用指南
- 完整安装指南
- 云端中继
- 插件参考
- 协议
- 设备测试报告

AI 生成内容声明

大部分代码、文档、测试和发布说明由 AI 编程助手生成。维护者负责需求、评审、真机测试和修复。

AI 输出可能包含错误、过时信息或不安全的默认值。投入生产前请先审查，尤其是云端部署、证书、token、Android 签名，以及局域网与云端之间的安全边界。

欢迎提交 issue 和 pull request 来纠正 AI 生成的内容。

许可证

MIT。Android SDK 工具仅用于本地构建，不随项目分发。