推送通知 xuan25/dsh-ntfy

dsh-ntfy

dsh-ntfy 给 DSH 智能体提供一条推送通知通道：调用一次工具，就能把消息发布到 ntfy 主题，任务结果、告警和报告随即送达用户设备——或者任何订阅了该主题的应用和 feed。

- 兼容 ntfy.sh 或任何自建 ntfy 服务器
- 支持多个主题频道；一次发送只投递到一个频道
- 零状态、零文件、零运行时依赖

安装

dsh-ntfy 是 dsh 配置档的树外插件。用 dsh 插件命令安装：

dsh plugin --profile <name> add dsh-ntfy

配置分层叠加：内置默认值、NTFY_* 环境变量块，以及 cordis 配置层（见下文）；插件不创建任何文件。

配置

环境变量块在进程启动时固定；改动环境变量后需重启宿主才生效。一个变量声明一个频道，其余变量可选：

| 变量 | 是否必填 | 含义 |
| NTFY_<NAME>_TOPIC | 是 | 声明频道 <name>，即 <NAME> 的小写形式（例如 NTFY_DASH_TOPIC 声明频道 dash）；主题就是寻址凭据，字符集为 [-_A-Za-z0-9]{1,64} |
| NTFY_<NAME>_SERVER | 否 | 服务器基础 URL（默认 https://ntfy.sh；任何自建 ntfy 都可用） |
| NTFY_<NAME>_USER + NTFY_<NAME>_PASS | 否（成对出现） | Basic 认证 |
| NTFY_<NAME>_TOKEN | 否 | Bearer token（不可与 USER/PASS 同时使用） |
| NTFY_DEFAULT_CHANNEL | 否 | 发送时未指定频道则使用该频道名（匹配不区分大小写） |

示例：

NTFY_DEFAULT_CHANNEL=dash
NTFY_DASH_TOPIC=dsh-alerts-Kx7pQm

变量名中的 <NAME> 段只允许大写字母和数字，频道名是它的小写形式；频道名必须匹配 ^[a-z][a-z0-9-]{0,31}$（与主题字符集不同，不允许下划线，也不允许以数字开头）。因此 NTFY_A_B_TOPIC 或 NTFY_1TOPIC 不会声明任何频道，而 NTFY_dash_TOPIC 这类小写段则完全匹配不上。无效频道会被丢弃并给出警告（不影响启动）。

配置层（cordis 补丁）

环境变量块之上还可以叠加一层可选配置：一条补丁条目，目标插件 id 为 dsh-ntfy（可写在配置档的 cordis.patch.yml、用户全局的 ~/.dsh/cordis.patch.yml，或 --patch 覆盖层中），携带 config 对象，其键是环境变量字段的 camelCase 镜像——defaultChannel 和 channels（频道名到 topic、server、user、pass、token 的映射）。每个键都可选。

- id: dsh-ntfy
config:
defaultChannel: dash
channels:
dash:
server: https://ntfy.example.com

- 只有一条优先级链：配置层给出的值 > 环境变量值 > 内置默认值；配置层省略的键按环境变量块解析，因此 config: {}（或没有条目）就是纯环境变量的行为。
- 补丁按 id 定位一行，替换整份配置，不做深度合并。所以某一层只覆盖一个字段时，要把它保留的字段一并重写（层顺序：插件自带的默认条目、配置档补丁、用户全局补丁、任何 --patch 覆盖层）。
- 插件启动前先校验层：未知键或字符集之外的 topic 会让插件条目在加载时失败；解析器丢弃的 channel（Basic auth 只给了一半、token 与 Basic auth 同时出现、topic 非法）只告警，和 env 块一样；层里声明的 channel 在两层里都没有 topic，会告警说它不是 channel。
- 开启实时补丁重载后，改补丁文件会重新运行插件，不用重启；否则改动在下次重启时生效。

用法

插件新增 ntfy 工具（动词 send / channels）和 dsh-ntfy 技能，技能里写明了完整参数集、限制和故障排查。典型调用：

ntfy { verb: "send", body: "deploy finished", title: "CI", priority: "high" }
ntfy { verb: "send", body: "nightly backup done", channel: "backups" }
ntfy { verb: "channels" }

一次 send 只发往一个 channel。正文超过 4096 UTF-8 字节会拆成顺序分块；某块失败就中止其余分块，结果里报告已送达多少块，剩下的需要你显式重发。

限制

- ntfy.sh 每个访客每天允许 250 条消息；自建服务器自己设限。插件不做客户端限流。
- ntfy 消息限制：正文 4096 字节（即分块大小），标题 1 KB，tags 512 字节。
- 消息发出后无法撤回（没有 update/clear/delete 接口）。