omni-notify/README.md

Omni-Notify 用户文档

Omni-Notify 是一款 Windows 本地通知弹窗工具。它接收来自本机脚本、自动化任务或其他程序的结构化消息，并以可配置的频道样式显示轻量弹窗。

它适合这些场景：

• 构建、部署、备份等脚本完成后弹出提示。
• 本地监控任务发现异常时发出视觉提醒。
• 工作流工具向桌面发送不抢焦点的状态通知。
• 不想使用系统通知中心，希望弹窗样式、位置和历史记录可控。

安装要求

• Windows 10 或更高版本
• .NET 8 Desktop Runtime

Omni-Notify 的发布包不内置 .NET 运行时，因此体积较小。首次运行前，请确认电脑已安装 .NET 8 Desktop Runtime。

下载与运行

下载发布包：

omni-notify-v0.2.0-win-x64.zip

解压后运行：

OmniNotify.exe

应用启动后会出现在系统托盘。左键点击托盘图标可显示或隐藏主控制面板，右键点击可打开菜单。

快速发送一条通知

默认接收地址：

http://127.0.0.1:19845/notify

PowerShell 示例：

Invoke-RestMethod `
  -Uri "http://127.0.0.1:19845/notify" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body '{"channel":"default","title":"Build finished","body":"The nightly job completed successfully."}'

JSON 字段说明：

字段	必填	说明
channel	是	频道名称，必须已在主面板中创建
title	否	弹窗标题
body	否	弹窗正文

如果发送到不存在的频道，消息不会弹窗，但会在历史记录中标记为无效频道。

频道

频道用于区分不同来源或不同用途的通知。每个频道都可以独立配置弹窗样式。

常见用法：

• default：普通通知。
• build：构建或 CI 任务。
• monitor：监控告警。
• backup：备份任务。

在主控制面板的“频道”页中可以新建、删除、重命名频道，并配置该频道的显示效果。

弹窗样式

每个频道支持配置：

• 显示器序号和屏幕位置。
• 边距、宽度、最大高度和内边距。
• 字体、标题字号、正文字号。
• 文本颜色、背景颜色、边框颜色和透明度。
• 存在时间、进入动画和退出动画。
• 多条消息的堆叠方式。
• 正文过长时的截断、滚动或拆分显示方式。

建议先配置频道，再点击“发送测试”观察实际效果。

历史记录

历史记录页会记录接收过的消息，包括：

• 接收时间
• 频道
• 状态
• 标题
• 正文

你可以搜索、筛选、清空历史记录，也可以右键复制消息内容或重新显示某条历史消息。

全局设置

全局设置包括：

• 免打扰模式：继续接收消息并记录历史，但不弹窗。
• 每秒最多处理消息数：超过阈值后触发熔断保护。
• 历史保留天数。
• 历史最多保留条数。
• 本地监听端口。

Omni-Notify v0.2.0 已移除开机自启功能。应用不会写入 Windows 启动项注册表。

熔断保护

如果短时间内收到大量消息，Omni-Notify 会自动进入熔断状态，防止弹窗刷屏或持续写入大量历史记录。

触发熔断后，你可以在托盘菜单或全局设置页中手动解除。

常见问题

发送请求后没有弹窗

先确认频道名称是否存在，再确认是否开启了免打扰模式。也可以查看历史记录中的状态。

提示无法连接本地地址

确认 Omni-Notify 正在运行，并检查全局设置中的本地监听端口。如果修改了端口，请使用新的端口发送请求。

为什么发布包这么小

发布包采用 framework-dependent 模式，不内置 .NET 运行时。这样体积更小，文件结构也更透明。

是否会开机自动启动

不会。v0.2.0 已删除开机自启功能，也不会写入 HKCU\Software\Microsoft\Windows\CurrentVersion\Run。

杀毒软件仍然提示风险怎么办

建议使用正式签名的发布版本，并避免从不可信来源下载。Omni-Notify 的官方发布方式不使用混淆、壳、自解压或单文件打包。

数据位置

配置和历史记录保存在：

%LOCALAPPDATA%\OmniNotify\state.json

需要重置配置时，可以在退出应用后删除该文件。

面向开发者

如果你需要构建、修改或发布项目，请阅读 开发者文档。