63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 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` 消费
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
cd FloatingMonitor
|
||
swift run
|
||
```
|
||
|
||
点击菜单栏仪表盘图标呼出悬浮窗，左键切换显隐，右键展开菜单。
|