omni-notify/docs/development.md

Omni-Notify 开发者文档

本文档面向需要构建、修改、审查或发布 Omni-Notify 的开发者。最终用户安装和使用说明请见 README.md。

技术栈

• .NET 8
• WPF
• Windows Forms NotifyIcon
• Built-in HttpListener
• JSON 本地持久化

项目不依赖第三方 NuGet 包。

项目结构

文件	责任
App.xaml.cs	应用生命周期、单实例互斥、托盘入口、本地 HTTP 服务启动
MainWindow.xaml	主控制面板 UI
MainWindow.xaml.cs	频道管理、历史筛选、全局设置保存
Models.cs	应用状态、频道、弹窗样式、历史记录、输入消息模型
Services.cs	状态持久化、消息路由、限流熔断、本地 HTTP 接收服务
PopupCoordinator.cs	弹窗队列、堆叠、替换和位置计算
PopupWindow.xaml	单个弹窗窗口 UI
PopupWindow.xaml.cs	弹窗动画、生命周期和正文溢出处理
app.manifest	Windows 应用清单，声明普通用户权限运行
scripts/package-release.ps1	标准发布脚本

本地构建

dotnet build .\OmniNotify.csproj -c Release

目标框架：

net8.0-windows

应用类型为 WPF 桌面应用，输出为 WinExe。

本地运行

dotnet run --project .\OmniNotify.csproj

默认监听：

http://127.0.0.1:19845/

通知接口：

POST http://127.0.0.1:19845/notify

请求体：

{
  "channel": "default",
  "title": "Build finished",
  "body": "The nightly job completed successfully."
}

状态持久化

状态文件路径：

%LOCALAPPDATA%\OmniNotify\state.json

保存内容包括：

• 全局设置
• 频道列表和频道样式
• 历史记录

AppStore.Save 会在写入前清理超出保留天数和数量限制的历史记录。

消息处理流程

1. LocalHttpServer 接收本地 HTTP 请求。
2. 请求体反序列化为 IncomingMessage。
3. NotificationRouter.Receive 进入 UI Dispatcher。
4. 检查熔断状态和每秒消息上限。
5. 按 channel 严格匹配频道。
6. 根据免打扰状态决定是否弹窗。
7. 写入历史记录。
8. PopupCoordinator 按频道样式显示弹窗。

未知频道不会弹窗，会记录为 IllegalChannel。

发布包

生成 v0.2.0 Windows x64 发布包：

.\scripts\package-release.ps1 -Version 0.2.0

默认产物：

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

脚本参数：

参数	默认值	说明
Configuration	Release	构建配置
Version	0.2.0	应用版本和产物版本
RuntimeIdentifier	win-x64	目标运行时标识

发布策略

当前发布策略刻意保持透明、标准和低风险：

• SelfContained=false
• PublishSingleFile=false
• PublishTrimmed=false
• PublishReadyToRun=false
• --self-contained false
• 不使用混淆器
• 不使用 UPX
• 不使用自解压启动器
• 不请求管理员权限

发布脚本会检查产物目录中是否出现以下 .NET 运行时文件：

• coreclr.dll
• clrjit.dll
• hostfxr.dll
• hostpolicy.dll

如果出现这些文件，脚本会失败，避免误发布自包含运行时包。

安全敏感行为约束

v0.2.0 已删除开机自启功能。代码中不应重新引入以下行为，除非经过明确产品决策：

• 写入 HKCU\Software\Microsoft\Windows\CurrentVersion\Run
• 创建计划任务实现自启动
• 后台下载或执行外部程序
• 全局键盘/鼠标钩子
• 注入、提权、隐藏进程或绕过安全产品

应用保留的本地监听服务仅绑定 127.0.0.1，不应改为 0.0.0.0 或局域网地址，除非同时补充认证和明确的安全设计。

版本与 Git

发布新版本时：

1. 更新 OmniNotify.csproj 中的 Version、FileVersion、AssemblyVersion。
2. 更新 app.manifest 中的 assemblyIdentity version。
3. 更新文档中的示例版本号。
4. 运行发布脚本生成 zip。
5. 验证发布目录不包含 .NET 运行时文件。
6. 提交代码。
7. 创建 tag，例如 v0.2.0。
8. 推送分支和 tag。

建议 tag 命名：

vMAJOR.MINOR.PATCH

建议发布资产命名：

omni-notify-vMAJOR.MINOR.PATCH-win-x64.zip

v0.2.0 发布摘要

• 删除开机自启功能及相关注册表写入逻辑。
• 新增标准应用清单，声明普通用户权限运行。
• 新增 framework-dependent 发布脚本。
• 发布包改为 omni-notify-v0.2.0-win-x64.zip。
• README 改为用户文档，开发信息迁入本文档。