commit 4b7f3a383c22df98150b1dec29a8e7e90c53b281
Author: kennethcheng <a1478925630@163.com>
Date:   Sun Sep 6 18:16:12 2026 +0800

    docs: 初始化 AGENTS.md,定义项目 agent 协作规范

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8abff17
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,79 @@
+# AGENTS.md
+
+Windows Gotify Agent —— 在 Windows 10/11 上以托盘程序方式运行，通过 WebSocket 连接 Gotify Server，把新消息以 Windows 原生通知呈现。
+
+## 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=` 拉历史消息
+- `Services/GotifyWebSocketService.cs` — `/stream?token=...` WebSocket 循环、自动重连(指数退避 2→5→10→20→30→60)、History 补偿
+- `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 反代、自包含目录依赖完整