# Omni-Notify 用户文档

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

它适合这些场景：

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

## 安装要求

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

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

## 下载与运行

下载发布包：

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

解压后运行：

```text
OmniNotify.exe
```

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

## 快速发送一条通知

默认接收地址：

```text
http://127.0.0.1:19845/notify
```

PowerShell 示例：

```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 的官方发布方式不使用混淆、壳、自解压或单文件打包。

## 数据位置

配置和历史记录保存在：

```text
%LOCALAPPDATA%\OmniNotify\state.json
```

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

## 面向开发者

如果你需要构建、修改或发布项目，请阅读 [开发者文档](docs/development.md)。