# Windows Gotify Agent

> Gotify → Windows 原生通知 · 应用内按应用分类查看历史 · 系统托盘常驻

![icon](Assets/gotify-mascot.png)

一个轻量级 Windows 桌面端,把 [Gotify](https://gotify.net/) 推送的消息以 **Windows 原生通知** 呈现,并在应用内按 **应用名** 分类查看历史。

---

## ✨ 功能

| 模块 | 说明 |
|---|---|
| 🔔 实时通知 | WebSocket 长连接(`/stream?token=`),Gotify 一推消息就弹 Windows 原生 toast,优先级 ≥ 8 走告警音 |
| 📜 历史查看 | 主窗左栏 ListView 显示最近 50 条,TextWrapping 不被截断;实时新消息插到最前 |
| 🏷️ 按应用分类 | 启动时拉 `GET /application` 缓存到 `ApplicationCache`,历史每行显示应用名(自动按名字 hash 出固定颜色);不是"App 12345"那种无意义编号 |
| 🌗 浅色 / 深色主题 | 主窗右上角 `☼ 浅色 / ☾ 深色` 按钮一键切换,所有颜色走 `DynamicResource` 实时刷新,选择自动存 `config.json` |
| 📋 复制 | 详情面板"消息正文"右侧 `[复制]` 按钮,一键把 `[应用名] 标题 / 时间 / 优先级 / 正文 / URL` 整段写进剪贴板 |
| 🛡️ 复制兜底 | 剪贴板被 UU远程 / RDP / 杀软长期占着时,自动弹一个预填 + 全选的小窗口,让你直接 Ctrl+C(绕开 OLE 锁) |
| 🖱️ 详情可选中 | 详情面板的标题 / 正文 / URL 全部用 `TextBox IsReadOnly`,鼠标拉黑、Ctrl+A、Ctrl+C 都能用 |
| 🧲 托盘常驻 | 关闭主窗只 Hide,进程留托盘;右键菜单:打开设置 / 测试通知 / 重新连接 / 退出 |
| 🚀 开机自启动 | 设置区 CheckBox 勾选后写 `HKCU\...\Run`(只当前用户,不需管理员);取消勾选会立刻从注册表删 |
| 🔗 通知跳链接 | 消息 `extras.client::notification.click.url` 透传到通知,点 toast 直接用默认浏览器打开 |

---

## 📸 截图

| 主窗(深色模式) | 主窗(浅色模式) |
|---|---|
| 托盘 + 应用内历史 + 详情面板 | 同上但浅色配色 |
| 优先级徽章彩色,应用名按名字分色 | 通知 hover 显示 |

> 截图占位 —— 跑起来后自行截图替换。

---

## 🛠️ 环境要求

- **OS**: Windows 10 (19041+) / Windows 11
- **运行时**: .NET 8 Desktop Runtime(开发用 SDK,运行用 Runtime)
- **依赖**: Windows App Runtime(`Microsoft.WindowsAppSDK 2.4.0` 同版本,本仓库 `dotnet publish --self-contained` 已自带)
- **Gotify**: 任意 v2.x server,需要创建一个 **Client**(不是 Application,本程序只消费消息不发送)

---

## 🚀 快速开始

### 方式 1:下载 Release(推荐普通用户)

1. 去 [Releases 页面](https://gitea.kennethcheng.cc/KennethCheng/Windows-Gotify-Client/releases) 下载最新 zip
2. 解压到任意目录(比如 `C:\Program Files\WindowsGotify\`)
3. 双击 `WindowsGotify.exe` 启动 → 托盘出现鸟图标
4. 右键托盘 → **打开设置 / 查看历史**
5. 填 `Gotify URL` + `Client Token` → **保存并重连**
6. 默认勾选 **开机自动启动**,登录 Windows 自动起

> ⚠️ 整个目录拷走,别只拷 EXE(WindowsAppSDK unpackaged 需要同一目录的 native DLLs)。

### 方式 2:源码编译(开发者)

```powershell
git clone https://gitea.kennethcheng.cc/KennethCheng/Windows-Gotify-Client.git
cd Windows-Gotify-Client

# 编译 + 跑 dev 版
dotnet restore
dotnet build -c Release
dotnet run -c Release

# 自包含发布(拷整个 bin\Release\net8.0-windows10.0.19041.0\win-x64\publish\ 目录)
dotnet publish -c Release -r win-x64 --self-contained true
```

---

## ⚙️ 配置

配置文件:`%LOCALAPPDATA%\WindowsGotify\config.json`

首次启动自动用默认值生成,主窗 GUI 编辑后实时落盘。

| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `Gotify.Url` | string | `http://127.0.0.1:8080` | Gotify server URL,**不要带尾部斜杠** |
| `Gotify.ClientToken` | string | (空) | Gotify 后台 **Clients** 标签里那个 `Cxxxx...` token(不是 Application Token) |
| `Notification.Enabled` | bool | `true` | 总开关,关掉就不弹 toast |
| `Notification.Sound` | bool | `true` | 是否带声音(优先级 ≥ 8 强制告警音) |
| `Notification.MaxMessageLength` | int | `2000` | 通知正文最大字符数,超出截断 |
| `Reconnect.InitialDelaySeconds` | int | `2` | WebSocket 断开首次重连延迟(秒) |
| `Reconnect.MaxDelaySeconds` | int | `60` | 指数退避上限(2 → 4 → 8 → ... → 60) |
| `History.Enabled` | bool | `true` | 启动时拉 `since=lastMessageId` 补齐离线期间消息 |
| `History.StartupSyncCount` | int | `20` | 启动时一次拉多少条增量 |
| `History.ViewerLimit` | int | `50` | 主窗历史列表最多显示多少条(UI 硬上限 200) |
| `Startup.Enabled` | bool | `true` | 开机自启动(写 `HKCU\...\Run`) |
| `Ui.Theme` | string | `System` | `Light` / `Dark` / `System`(System 等同 Light) |

---

## 🏗️ 架构

```
┌─ App.xaml.cs ──────────┐
│  单实例 Mutex          │
│  AppNotificationManager │ ← Windows App SDK
│  主题加载              │
└────────────┬─────────┘
             │
   ┌─────────┴──────────┐
   │                    │
┌──▼─────────┐    ┌─────▼──────────┐
│ TrayIcon   │    │ MainWindow     │
│ (WinForms) │    │ (WPF)          │
└────────────┘    └─┬─────────┬────┘
                    │         │
        ┌───────────┘         └────────────┐
        │                                  │
┌───────▼─────────┐               ┌─────────▼────────┐
│ GotifyWebSocket │               │ GotifyApi        │
│ Service         │               │ Service          │
│ - 自动重连      │               │ - GetMessages    │
│ - 去重(lastId)  │               │ - GetRecentMsg   │
│ - History 补偿  │               │ - GetApplications│
└─────────────────┘               └──────────────────┘
        │                                  │
        │              ┌───────────────────┘
        │              │
        │       ┌──────▼──────┐    ┌──────────────┐
        │       │ Application │    │ StateService │
        └──────►│ Cache       │    │ - lastId     │
                └─────────────┘    └──────────────┘

            ┌──────────────┐    ┌──────────────────┐
            │ Notification │    │ ConfigService    │
            │ Service      │    │ (config.json)    │
            └──────────────┘    └──────────────────┘
```

模块清单(参见 `AGENTS.md` 完整说明):

- `Models/` — `AppConfig` / `GotifyMessage` / `GotifyApplication`
- `Services/` — `ConfigService` / `Logger` / `StateService` / `GotifyApiService` / `GotifyWebSocketService` / `NotificationService` / `ApplicationCache` / `ThemeService`
- `Utils/StartupManager.cs` — 注册表 Run 项
- `Tray/TrayIconService.cs` — WinForms `NotifyIcon`
- `Themes/Light.xaml` / `Dark.xaml` — 主题资源
- `Converters/ValueConverters.cs` — 优先级色 / 应用名 hash 出色

---

## 🐛 已知问题

- **WindowsAppSDK 2.4.0 self-contained 打包漏 `Microsoft.WindowsAppRuntime.Insights.Resource.dll`** —— `dotnet build/publish` 输出目录里少了这个 DLL,首次启动 `AppNotificationManager.Register()` 会抛 `0x8007007E`。**修法**:
  - **dev**:从已装 WindowsAppSDK 的程序(本机如 `C:\Program Files\WSL\wslsettings\`)拷贝 5 个 DLL 到 build 目录:
    - `Microsoft.WindowsAppRuntime.Bootstrap.dll`、`Bootstrap.Net.dll`、`Microsoft.WindowsAppRuntime.dll`、`Insights.Resource.dll`、`Microsoft.WindowsAppRuntime.pri`
  - **prod**:`winget install Microsoft.WindowsAppRuntime.2`(或目标机器装 system-wide WindowsAppRuntime)
  - 详细见 `AGENTS.md`

---

## 🛣️ 路线图 (V2)

- 多 Gotify Server(同时连 NAS / 云的多个 instance)
- 按应用 / 优先级过滤历史(下拉框)
- 通知分类(Do Not Disturb 时段、白名单)
- 自定义通知图标(每个 app 一个图标)
- MSI / MSIX 安装器
- Gitea Actions CI:`push` tag 时自动 build + publish release
- 通知消息聚合(同一应用 1 分钟内多条合并为"X 条新消息")

---

## 📜 协议

- **Gotify 消息流**:通过 `/stream?token=<Client Token>` WebSocket 订阅
- **HTTP API**:`/application`(应用列表)、`/message?limit=&since=`(历史)
- **点击链接**:Gotify 消息 `extras.client::notification.click.url`,被透传到 toast 的 `AddArgument("url", ...)`,点击时用默认浏览器打开
- **本地状态**:`%LOCALAPPDATA%\WindowsGotify\state.json` 记录 `LastMessageId` 防止重启后重复通知

---

## 🔒 安全

- **只读 Client Token**:本程序只向 Gotify 订阅消息,不需要 Application Token;请勿在配置或日志里泄露任何 Application Token
- **当前用户 Run 项**:开机启动走 `HKCU`,不写 `HKLM`,不需要管理员权限,不影响其他用户
- **Token 日志脱敏**:WebSocket 连接日志把 `?token=***` 段打码,不输出完整 token
- **HTTPS / wss**:公网部署请用 HTTPS + wss;ws / http 仅适合内网
- **通知链接白名单**:通知点击只能打开 Gotify `extras` 显式声明的 URL,不会自动从消息文本里抓链接

---

## 📄 License

TBD

---

## 🙏 致谢

- [Gotify](https://gotify.net/) — 简单好用的自托管消息推送 server
- [Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/) — 现代 Windows 原生通知 API
- Ducker(Gotify 吉祥物)—— 萌