DesktopPulse（原生 macOS WidgetKit 小组件）

一个真正的 macOS WidgetKit 小组件，可在系统“编辑小组件”面板中添加到桌面。项目由两个部分组成：

• DesktopPulse.app：菜单栏后台数据桥接，读取本机状态和脱敏 AI 配额。
• DesktopPulseWidgetExtension.appex：由 macOS WidgetKit 托管的小号/中号/大号系统小组件。

小组件展示：

• 上海实时天气（可改城市与经纬度）
• CPU、GPU、内存、SSD、温度、风扇与实时上下行网速
• Codex、Cursor、Claude Code、Grok 的已消耗、剩余、使用进度与今日 Token（数据来自本机 Kaboo / 日志 / Hook，不读认证密钥）

要求 macOS 14+、Xcode 15+、XcodeGen。

./scripts/package_app.sh
open dist/DesktopPulse.app

也可以直接打开生成的 DesktopPulseWidget.xcodeproj。工程包含 App 与 Widget Extension 两个 Target。

1. 把 DesktopPulse.app 放入 /Applications 或 ~/Applications 并启动。
2. 在桌面空白处右键，选择“编辑小组件”。
3. 搜索 DesktopPulse，选择小号、中号或大号并拖到桌面。
4. 保持菜单栏里的 DesktopPulse 数据桥接运行；可在菜单中启用“登录时启动”。
5. 菜单「小组件皮肤」可在 液态玻璃 与 赛博朋克 两套外观间切换（快捷键 ⌘1 / ⌘2）。

macOS 不允许应用代替用户自动固定小组件，因此第 2～3 步必须由用户完成一次。

• 天气来自 Open-Meteo Forecast API，无需 API Key。
• 系统状态通过 macOS 原生框架本机读取。
• Codex 只读 Kaboo 的脱敏配额快照及本地扫描缓存，按 source=codex 汇总当天 token；界面不显示 Kaboo 品牌，也不读取 Codex 令牌、浏览器 Cookie 或钥匙串。
• Grok 通过本地 CLI Hook 从统一日志提取 creditUsagePercent、套餐名，并按当天模型调用的 prompt + completion 汇总 token；组件不读取 Grok 认证文件。
• 后台 App 只在 127.0.0.1:41789 监听，把脱敏 JSON 快照提供给沙箱内的 Widget Extension；不监听局域网地址，也不上传数据。
• 宿主每约 3 秒采样 CPU / 内存 / 网速 / 温度 / 风扇，并约每 12 秒请求刷新小组件时间线；小组件侧请求约 1 分钟再拉一次。WidgetKit 由系统调度，无法保证秒级刷新，能耗策略下可能被拉长。

安装一次全局 Hook：

./scripts/install_grok_usage_hook.sh

Hook 配置保存到 ~/.grok/hooks/desktoppulse-usage.json，提取器与快照保存在 ~/.local/share/desktoppulse/。安装脚本会立即生成第一份快照，此后每次 Grok 会话开始或结束都会更新。

Resources/DesktopPulse-logo.png 是高分辨率 Logo 源文件。打包脚本会自动生成带透明圆角的完整 macOS .icns 图标集；天气、系统健康和 AI 用量三块组件由同一条 Pulse 线连接，呼应 DesktopPulse 的产品含义。