📝 添加 AGENTS.md 和 README.md

2026-05-05 21:30:01 +08:00 · 2026-05-05 21:30:01 +08:00 · c5a2cbef12
commit c5a2cbef12
parent 4ab9a7b28c
2 changed files with 134 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,62 @@
+# 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
+```
+
+点击菜单栏仪表盘图标呼出悬浮窗，左键切换显隐，右键展开菜单。
--- a/README.md
+++ b/README.md
@ -0,0 +1,72 @@
+# Monitor
+
+> macOS 原生系统监控悬浮窗 —— 实时 CPU/GPU/内存/Swap + Top进程，半透明可拖动，一切可定制。
+
+## 截图
+
+点击菜单栏 <img src="https://img.shields.io/badge/⏲-Monitor-blue" height="18"> 图标呼出悬浮窗：
+
+```
+┌──────────────────────┐
+│ ⏲ Monitor   21:30:00 ✕│
+│──────────────────────│
+│  CPU   ████████░░ 42% │
+│  10 核心 · Apple M2 Pro│
+│                       │
+│  内存  ███░░░░░░░ 35% │
+│  5.6 / 16 GB          │
+│                       │
+│  CPU 消耗 Top          │
+│  WindowServer  12.3%  │
+│  Code          8.1%   │
+└──────────────────────┘
+```
+
+## 功能
+
+- **CPU / GPU / 内存 / Swap** 实时占用率
+- **Top 进程** 按 CPU 和内存消耗排列
+- **5 种计量器样式**：圆环、条状、纯文本、扇形、紧凑横条
+- **灵活布局**：每个模块独立指定行号 + 左/右/全宽列位
+- **半透明悬浮窗**：毛玻璃 HUD 风格，任意拖动
+- **菜单栏图标**：左键切换显隐，右键菜单（设置、退出）
+- **独立设置窗口**：显示内容、样式、行号列位、宽高、字体、透明度、刷新率全部可调
+
+## 安装
+
+### 方式一：DMG
+下载 `Monitor.dmg`，将 `FloatingMonitor` 拖入 Applications。
+
+### 方式二：源码运行
+```bash
+git clone git@git.cyjai.com:JOJO/Monitor.git
+cd Monitor
+swift run
+```
+
+## 要求
+
+- macOS 14 (Sonoma) 或更高
+- Xcode 16+ 或 Swift 6.2 工具链
+
+## 使用
+
+1. 启动后菜单栏出现仪表盘图标
+2. **左键点击**图标 → 切换悬浮窗显隐
+3. **右键点击**图标 → 展开菜单（显示设置 / 退出）
+4. 悬浮窗可**任意拖动**，设置中可调宽高
+
+## 技术
+
+| 层面 | 实现 |
+|------|------|
+| CPU 采样 | `host_statistics` 双采样差值 |
+| GPU 占用 | IOKit `IOAccelerator` → `PerformanceStatistics` |
+| 内存/Swap | `vm_statistics64` / `sysctl vm.swapusage` |
+| 进程列表 | `ps -eo pid,%cpu,rss,comm` |
+| UI | SwiftUI + AppKit `NSHostingView` |
+| 毛玻璃 | `NSVisualEffectView` `.hudWindow` + `.behindWindow` |
+
+## 许可
+
+MIT