dsh-ntfy-notifier 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 liangfu
+
+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

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# dsh-ntfy-notifier-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 ntfy 消息转换为 Windows 本机通知的 DeepSeek Harness（DSH）插件。
+
+插件直接在 Host 进程中用 Node 内置 `http`/`https` 订阅 ntfy 的 JSON 流，不依赖 `ntfy.exe`。支持配置多个 ntfy 服务器，每个服务器可配置多个频道，每个「服务器 + 频道」组合独立连接、独立重连。
+
+插件包名是 `dsh-ntfy-notifier`；安装后由 DSH 插件管理器按本地目录或 npm 包加载。
+
+> **AI 开发说明**：本插件由 AI 开发，代码和文档由 AI 生成并整理。使用前请自行审查代码、配置和运行行为。
+
+## 功能
+
+- 多个 ntfy 服务器，每个服务器多个频道
+- 每个服务器地址、每个频道各用一个输入框；点 `+` 添加新服务器或新频道
+- 订阅 ntfy 的 JSON 流，断线后指数退避重连
+- 使用最后一条消息 ID 续订，并按消息 ID 去重
+- 支持 `title`、`message`、`priority`
+- 优先级 4/5 可选用系统闹钟铃声，其他优先级使用普通提示音
+- 消息通过 base64 JSON 传给 PowerShell，避免命令行和 XML 注入
+- 支持全局 Bearer Token，也支持每个服务器节点单独配置并覆盖全局 Token
+- 配置页按频道显示运行状态：等待、订阅完成、心跳正常、连接失败
+- 插件停用或 DSH 退出时关闭连接和通知进程
+
+## 环境要求
+
+- Windows 10/11
+- DeepSeek Harness（支持 `dsh.client` 与 `plugins.row.config` 的版本）
+- Windows PowerShell 5.1（系统自带）
+- Node.js 24 或 DSH 自带的运行时
+- pnpm（安装 `@deepseek-ai/schemastery` 依赖时需要）
+
+## 安装
+
+1. 将插件目录放到本地任意位置，并在该目录中安装依赖：
+
+   ```powershell
+   cd <插件目录>
+   pnpm install --ignore-scripts
+   ```
+
+2. 在 DSH 的 **插件** 页面选择 **添加插件 → 安装第三方插件**，填入本目录的绝对路径。
+3. 安装完成后打开 `ntfy 系统通知` 的详情，在插件行 `ntfy-notifier` 点 **配置**。
+4. 填入自己的 ntfy 服务器地址和频道，保存。
+
+> 如果配置页没有出现，先刷新一次 Web GUI。首次安装时如果客户端模块已被缓存为“无界面”，DSH 可能需要重启后才能重新扫描客户端模块。
+
+## 配置
+
+### 通过界面配置
+
+入口：**左侧栏「插件」→ `ntfy 系统通知` → 插件行 `ntfy-notifier` → 「配置」**。
+
+配置页按服务器分组：
+
+```text
+服务器 1
+  服务器地址: [http://127.0.0.1:2586]
+  访问令牌: [留空则使用全局令牌]
+  频道: [message] [alerts]  [+ 添加频道]
+
+服务器 2
+  服务器地址: [https://ntfy.example.com]
+  访问令牌: [可填写该服务器自己的令牌]
+  频道: [system]  [+ 添加频道]
+
+[+ 添加服务器]  [保存]
+```
+
+- 每个服务器地址是一个输入框
+- 每个服务器可以单独填写访问令牌；留空时使用全局 `accessToken`
+- 每个频道也是一个独立输入框
+- 点 **+ 添加频道** 给当前服务器增加频道输入框
+- 点 **+ 添加服务器** 增加一组服务器和频道输入框
+- 可移除服务器或单个频道
+- 保存后 Host 会更新配置并重新建立订阅
+
+### 通过 YAML 配置
+
+在 `cordis.patch.yml` 中覆盖插件条目的 `config`：
+
+```yaml
+- id: ntfy-notifier
+  name: 'dsh-ntfy-notifier'
+  config:
+    servers:
+      - url: 'http://127.0.0.1:2586'
+        topics:
+          - message
+          - alerts
+        accessToken: ''
+      - url: 'https://ntfy.example.com'
+        topics:
+          - system
+        accessToken: 'server-token'
+    accessToken: 'global-token'
+    appId: 'ntfy'
+    sound: true
+    highPriorityAlarm: true
+    reconnectDelaySeconds: 5
+    maxReconnectDelaySeconds: 60
+```
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `servers` | 一个本地服务器和一个 `message` 频道 | 服务器列表，每项包含 `url`、该服务器的 `topics` 和可选的 `accessToken` |
+| `servers[].accessToken` | 空 | 可选，该服务器自己的 Bearer Token；非空时覆盖全局 `accessToken` |
+| `accessToken` | 空 | 可选，全局 Bearer Token；服务器节点没有填写 `accessToken` 时使用 |
+| `appId` | `ntfy` | Windows Toast 的 AUMID；未注册时自动回退到 `Microsoft.Windows.PowerShell` |
+| `sound` | `true` | 是否播放通知声音 |
+| `highPriorityAlarm` | `true` | 优先级 4/5 是否使用系统闹钟铃声 |
+| `reconnectDelaySeconds` | `5` | 首次重连等待秒数 |
+| `maxReconnectDelaySeconds` | `60` | 指数退避上限 |
+
+频道名不要包含空格或斜杠。如果使用反向代理子路径，`url` 填到子路径为止，例如 `https://ntfy.example.com/ntfy`，插件会请求 `https://ntfy.example.com/ntfy/<channel>/json`。
+
+### 运行状态
+
+配置页的每个频道旁会显示当前运行状态：
+
+| 状态 | 颜色 | 含义 |
+|---|---|---|
+| 等待 | 黄色 | 正在连接，或等待重连 |
+| 订阅完成 | 绿色 | 已收到 ntfy 的 `open` 事件 |
+| 心跳正常 | 绿色 | 已收到 keepalive 或消息 |
+| 连接失败 | 红色 | 连续 3 次心跳检查没有收到任何数据 |
+
+心跳检查每 45 秒执行一次；连续 3 次没有活动（约 135 秒）会标记为连接失败并触发重连。任何 keepalive 或消息都会重置心跳计数。
+
+状态由 Host 提供给配置页，不包含 Token、Authorization 头或完整服务器地址。
+
+## 工作原理
+
+1. 对每个「服务器 + 频道」组合请求 `<server>/<channel>/json`，读取换行分隔的 JSON 事件。
+2. 只处理 `event: "message"`，忽略 `open`、`keepalive` 等控制事件。
+3. 通过 `notify.ps1` 调用 Windows WinRT `ToastNotificationManager` 弹出通知。
+4. 消息标题和正文先做控制字符清理、长度截断，再以 base64 UTF-8 JSON 传给 PowerShell；PowerShell 使用 `SecurityElement.Escape` 转义 XML。
+5. 连接断开、超时或出错后按指数退避重连；续订参数使用最后一条消息的 `id`。
+
+## 安全说明
+
+- 不使用外部 `ntfy.exe`，减少一个可执行文件依赖。
+- 消息内容不拼接进 PowerShell 命令行，也不直接拼进 XML，避免命令和 XML 注入。
+- `accessToken` 和 `servers[].accessToken` 会以明文保存在 DSH 的 profile 配置中；请确保本机账号和 profile 文件权限可信。
+- 未配置服务器级 `accessToken` 的服务器会使用全局 `accessToken`；如果某台服务器不受信，建议不要设置全局令牌，或为每个服务器配置独立令牌。
+- 局域网 HTTP 不加密。跨网络部署建议使用 HTTPS，并配置访问令牌。
+- 插件只读取 ntfy 消息并将其显示为本机通知，不执行消息内容。
+
+## 开发与验证
+
+```powershell
+# 安装运行时依赖
+pnpm install --ignore-scripts
+
+# 语法检查
+node --check index.js
+node --check client.js
+
+# PowerShell 助手语法检查
+$tokens = $null
+$errors = $null
+[System.Management.Automation.Language.Parser]::ParseFile(
+  (Resolve-Path '.\notify.ps1'),
+  [ref]$tokens,
+  [ref]$errors
+) | Out-Null
+if ($errors.Count) { $errors | ForEach-Object Message; exit 1 }
+```
+
+本地测试 Windows 通知助手（会实际弹出一条通知）：
+
+```powershell
+$json = '{"title":"ntfy test","message":"notify.ps1 works","priority":3,"appId":"ntfy","sound":true,"alarm":true}'
+$b64 = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\notify.ps1 -PayloadBase64 $b64
+```
+
+## 故障排查
+
+- **配置页看不到**：刷新 Web GUI；确认插件行是 `ntfy-notifier` 且处于启用状态；确认配置页的客户端模块已经加载。
+- **没有通知**：检查 Windows 通知权限、专注助手/勿扰模式，以及 `appId` 是否被系统接受；可先用上面的助手命令测试。
+- **连接失败**：确认服务器地址、频道名、反向代理路径，以及该服务器的 `servers[].accessToken` 或全局 `accessToken`；查看 DSH Host 日志中的 `ntfy:` 前缀。
+- **频道重复**：同一个 URL 只会建立一条连接，重复频道会被去重。
+
+## 限制
+
+- 插件仅在 DSH 运行期间监听，不是常驻 Windows 服务。
+- 当前只实现 Windows Toast；其他平台会记录警告但不会弹窗。
+- 首次连接只接收新消息，不补发历史消息。
+- 服务器节点没有填写 `accessToken` 时，会回退到全局 `accessToken`。
+- 配置页依赖 DSH 的 `plugins.row.config` 和 `settings` 服务；也可以通过 YAML 配置。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。