Monitor/AGENTS.md

AGENTS.md

项目概述

FloatingMonitor 是 macOS 原生系统监控悬浮窗应用，纯 Swift + SwiftUI + AppKit 构建，实时展示 CPU/GPU/内存/Swap 占用率及 Top 进程。

技术栈

• 语言: Swift 6.2
• UI: SwiftUI + AppKit 混编
• 构建: Swift Package Manager (swift build / swift run)
• 最低系统: macOS 14 (Sonoma)
• 架构: 纯 AppKit 窗口 + SwiftUI 视图通过 NSHostingView 嵌入

项目结构

Sources/FloatingMonitor/
├── main.swift                          # 入口（5行）
├── App/
│   ├── AppDelegate.swift               # NSApplicationDelegate + NSStatusItem + NSMenu
│   ├── FloatingWindow.swift            # 悬浮窗 NSWindow 子类
│   ├── FloatingWindowController.swift  # 毛玻璃 + 视图嵌入 + 显隐逻辑
│   └── SettingsWindowController.swift  # 独立设置窗口
├── SystemMonitor.swift                 # 数据采集（host_statistics / IOKit / sysctl / ps）
├── Configuration.swift                 # UserDefaults 持久化配置（单例）
├── ContentView.swift                   # 主界面 + 布局引擎
└── Views/
    ├── GaugeView.swift                 # 5 种计量器样式（bar/ring/text/pie/compact）
    ├── SettingsView.swift              # 设置面板（显示/样式/行号/列位/宽高）
    └── ProcessListView.swift           # Top 进程列表

关键约定

窗口管理

• FloatingWindow：borderless + .floating level + isMovableByWindowBackground
• 毛玻璃通过 NSVisualEffectView（.hudWindow + .behindWindow）实现
• 所有子视图使用 Auto Layout 约束（translatesAutoresizingMaskIntoConstraints = false），禁止 frame 直接赋值

数据流

• SystemMonitor 是 @MainActor ObservableObject，通过 Timer 驱动刷新
• Configuration 是单例 @ObservedObject，所有持久化走 UserDefaults
• 跨组件通信（设置→主窗口）用 NotificationCenter（resizeMonitorWindow、refreshIntervalChanged）

布局系统

• 每个模块（CPU/GPU/内存/Swap/进程）独立配置 layoutRow（1-10）+ ModulePosition（left/right/full）
• moduleRows 计算属性按 row 排序，同行 left+right 配对用 HStack 并排，full 独占一行

修改原则

• 优先用 edit_file 精准修改，不要整文件重写
• 每个 Swift 文件不超过 200 行
• 新功能先在 Configuration 加属性，再在 SettingsView 加 UI，最后在 ContentView 消费

运行

cd FloatingMonitor
swift run

点击菜单栏仪表盘图标呼出悬浮窗，左键切换显隐，右键展开菜单。