KennethCheng
c2f44767a6
17 个源文件 + .gitignore + 默认 config.json 模板,严格按方案文档第 6 节实现。
用户核心场景:
- Windows 接收 Gotify 通知(WS /stream → AppNotificationBuilder)
- 应用内查看历史消息(打开 MainWindow 触发 GetRecentMessagesAsync,实时通过 MessageReceived 事件追加)
- 列表条目双击打开 extras.client::notification.click.url
关键变更点:
- GotifyMessage.Extras 类型由 Dictionary<string,object> 改为 Dictionary<string,JsonElement>,避免 System.Text.Json 反序列化时丢失嵌套结构
- 新增 HistoryConfig.ViewerLimit(默认 50,UI 硬上限 200)
- GotifyApiService.GetRecentMessagesAsync:since=0 拉最近 N 条,OrderByDescending(Id) 保证顺序
- GotifyWebSocketService 新增 MessageReceived 事件,MainWindow 用 Dispatcher.Invoke 切回 UI 线程追加
- NotificationService.AddArgument('url=...') 透传 click URL 给 OnNotificationInvoked
- MainWindow.xaml 增加 ListView + 刷新按钮,使用 ObservableCollection<GotifyMessage>
- 默认 config.json 用 https://gotify.example.com 占位 URL,ClientToken 留空,首启动自动写入 %LOCALAPPDATA%
依赖:Microsoft.WindowsAppSDK 2.4.0(方案文档固定版本)。
构建:本机 .NET 8 SDK 未安装,build 待用户在装好 SDK 后执行: dotnet restore && dotnet build -c Release
91 lines
5.9 KiB
Markdown
91 lines
5.9 KiB
Markdown
# AGENTS.md
|
|
|
|
Windows Gotify Agent —— 在 Windows 10/11 上以托盘程序方式运行，通过 WebSocket 连接 Gotify Server，把新消息以 Windows 原生通知呈现。
|
|
|
|
## 用户场景
|
|
|
|
V1 核心场景(用户明确要求):
|
|
|
|
- Windows 接收 Gotify 通知(WebSocket → Windows 原生通知)
|
|
- 应用内查看历史消息(打开 MainWindow → 历史列表,自动拉最近 N 条 + 实时追加新消息)
|
|
- 列表条目支持双击跳转:消息 `extras` 里有 `client::notification.click.url` 时,默认浏览器打开
|
|
|
|
V1 暂不做(避免范围蔓延):多 Gotify Server、消息过滤、GUI 完整配置编辑、MSI/MSIX 安装器、Linux/macOS 端。
|
|
|
|
## Setup commands
|
|
|
|
- 环境:Windows 10 19041+ / Windows 11、Visual Studio 2022、.NET 8 SDK、Desktop development with .NET 工作负载
|
|
- 还原依赖: `dotnet restore`
|
|
- 编译: `dotnet build -c Release`
|
|
- 本地运行: `dotnet run -c Release`
|
|
- 自包含发布(推荐): `dotnet publish -c Release -r win-x64 --self-contained true`
|
|
- 发布产物: `bin\Release\net8.0-windows\win-x64\publish\`(整个目录一起发布,不要只复制 EXE)
|
|
|
|
## Project layout
|
|
|
|
- `WindowsGotify.csproj` — SDK 风格项目文件,net8.0-windows / x64,UseWPF + UseWindowsForms,WindowsPackageType=None(unpackaged)
|
|
- `app.manifest` — asInvoker 兼容性清单(Win10/11 supportedOS)
|
|
- `App.xaml` + `App.xaml.cs` — 应用入口、Mutex 单实例锁、AppNotificationManager 注册/注销、生命周期编排
|
|
- `MainWindow.xaml` + `MainWindow.xaml.cs` — 设置窗(Gotify URL、Client Token、保存并重连、测试通知);关闭按钮只 Hide 不退出
|
|
- `Models/` — `AppConfig`(嵌套 Gotify/Notification/Reconnect/History/Startup 五个子配置) + `GotifyMessage`(+ `GotifyMessagePage`、`PagingInfo`)
|
|
- `Services/ConfigService.cs` — `config.json` 读写,路径 `%LOCALAPPDATA%\WindowsGotify\config.json`
|
|
- `Services/Logger.cs` — 文本日志写入 `app.log`,线程安全
|
|
- `Services/StateService.cs` — `state.json` 持久化 `LastMessageId`,断线重连/历史同步的去重锚点
|
|
- `Services/GotifyApiService.cs` — `GET /message?limit=&since=` 拉历史补偿;`GetRecentMessagesAsync` 拉最近 N 条(供 UI 历史查看)
|
|
- `Services/GotifyWebSocketService.cs` — `/stream?token=...` WebSocket 循环、自动重连(指数退避 2→5→10→20→30→60)、History 补偿;新增 `MessageReceived` 事件供 UI 实时追加
|
|
- `Services/NotificationService.cs` — 通过 `AppNotificationBuilder` 弹 Windows 原生通知,Priority ≥ 8 走 Alarm 音;若消息 `extras` 含 `client::notification.click.url`,通过 `AddArgument("url=...")` 透传给 `OnNotificationInvoked`
|
|
- `Services/NotificationService.cs` — 通过 `AppNotificationBuilder` 弹 Windows 原生通知,Priority ≥ 8 走 Alarm 音
|
|
- `Utils/StartupManager.cs` — 写入 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` 实现当前用户开机启动
|
|
- `Tray/TrayIconService.cs` — WinForms `NotifyIcon` 托盘(打开设置/测试通知/重新连接/退出)
|
|
|
|
## Code style
|
|
|
|
- C# 12 / .NET 8,`<Nullable>enable</Nullable>` + `<ImplicitUsings>enable</ImplicitUsings>`
|
|
- 顶层 `sealed class`,文件作用域命名空间,主命名空间 `WindowsGotify.*`
|
|
- 异步 API:WebSocket、API、状态保存一律 `async/await`,UI 事件用 `async void` + try/catch
|
|
- `using System.*;` 优先,然后第三方(`Microsoft.Windows.AppNotifications.*` / `Microsoft.Win32`),最后 `WindowsGotify.*`
|
|
- WPF XAML 资源引用走 `x:Name`,代码隐藏用 `_camelCase` 私有字段
|
|
- WebSocket 资源用 `using` 或 `try/finally` 保证释放,`ClientWebSocket.Abort()` 用于强制重连
|
|
- 不要把 `Application Token` 写进此项目(只允许 `Client Token`)
|
|
|
|
## Runtime data
|
|
|
|
- 配置文件: `%LOCALAPPDATA%\WindowsGotify\config.json`
|
|
- 状态文件: `%LOCALAPPDATA%\WindowsGotify\state.json`
|
|
- 运行日志: `%LOCALAPPDATA%\WindowsGotify\logs\app.log`
|
|
|
|
## Testing instructions
|
|
|
|
- V1 不带自动化测试,依赖手动 + Gotify 端到端验证
|
|
- 单元自测: 托盘菜单 → 「测试通知」,应弹出标题为「Gotify 测试」的 Windows 通知
|
|
- 端到端发消息(PowerShell):
|
|
```powershell
|
|
$headers = @{ "X-Gotify-Key" = "<Application Token>" }
|
|
$body = @{ title = "Hadoop"; message = "NameNode 启动完成"; priority = 3 } | ConvertTo-Json
|
|
Invoke-RestMethod -Uri "https://<gotify-host>/message" -Method Post -Headers $headers -ContentType "application/json" -Body $body
|
|
```
|
|
- 反向代理(Nginx / NPM)必须透传 WebSocket Upgrade 头,详见方案文档第 14 节
|
|
- 任意代码改动后必须执行: `dotnet restore && dotnet build -c Release`,并在目标 Windows 10/11 上跑一次端到端
|
|
|
|
## Gotify protocol 约束
|
|
|
|
- `/stream` 是 WebSocket 端点,`/message?limit=&since=` 是历史补偿端点,二者都只接受 `Client Token`
|
|
- 消息去重锚点 = `state.LastMessageId`,只处理 `Id > LastMessageId` 的消息,启动时用 `since=LastMessageId` 拉增量
|
|
- HTTP `ClientToken` 走 `Authorization: Bearer <token>`;WebSocket 走 query `?token=<token>`(日志中要打码为 `token=***`)
|
|
- 声音策略: `priority >= 8` → `AppNotificationSoundEvent.Alarm`,否则 `Default`
|
|
|
|
## PR & commit conventions
|
|
|
|
- 分支策略: 默认分支 `main`,所有改动走 feature 分支 + PR
|
|
- 提交信息: 简体中文 conventional commits,前缀使用 `feat:` / `fix:` / `docs:` / `refactor:` / `chore:` / `build:`
|
|
- 改动 `.csproj` / `Microsoft.WindowsAppSDK` 版本号必须在 PR 描述中单独说明,不允许顺手升级
|
|
- 涉及 `Client Token` / 真实 Gotify URL 的示例值用占位符 `<token>` / `<gotify-host>`,禁止提交真实凭据
|
|
|
|
## Security
|
|
|
|
- `Client Token` 只能进入 `config.json`,日志中只允许 `token=***` 打码输出
|
|
- 公网部署必须使用 HTTPS + wss;ws:// / http:// 仅允许内网
|
|
- 通知点击仅允许打开经 Gotify `extras` 传入的 URL,不要任意打开消息文本里出现的链接
|
|
- 启动项走 `HKCU\...\Run`(当前用户)而非 `HKLM`,避免提权与全员副作用
|
|
- 发布前在干净 Windows 10/11 上验证通知注册、通知中心授权、WebSocket 反代、自包含目录依赖完整
|