diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index c22205a..02239cc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,41 +1,49 @@ -name: Bug report -description: 报告可复现的问题（请勿上传 token 或会话正文） +name: Bug report / 错误报告 +description: Report a reproducible problem. Never upload tokens or conversation text. / 报告可复现问题，请勿上传 token 或会话正文 title: "[Bug] " -labels: ["bug"] +labels: ["bug", "needs triage"] body: - type: markdown attributes: - value: "感谢反馈。提交前请移除用户名、项目路径、token 和会话内容。" + value: "Thanks for helping improve MacPulse. Remove usernames, project paths, tokens, credentials, and conversation content before submitting. / 感谢反馈，提交前请移除用户名、项目路径、token、凭证与会话内容。" - type: input id: version attributes: - label: MacPulse 版本与构建号 + label: MacPulse version and build / 版本与构建号 placeholder: "0.9.0 (2)" validations: required: true - type: input id: environment attributes: - label: Mac 与 macOS + label: Mac and macOS / 设备与系统 placeholder: "MacBook Pro M3 Pro / macOS 15.5" validations: required: true - type: textarea id: steps attributes: - label: 复现步骤 + label: Steps to reproduce / 复现步骤 + description: Include the smallest reliable sequence. / 请提供最短且可靠的复现步骤。 validations: required: true - type: textarea id: expected attributes: - label: 预期与实际结果 + label: Expected and actual result / 预期与实际结果 validations: required: true - type: checkboxes id: privacy attributes: - label: 隐私确认 + label: Privacy confirmation / 隐私确认 options: - - label: 我已移除 token、会话正文与真实项目路径 + - label: I removed tokens, credentials, conversation text, usernames, and real project paths. / 我已移除 token、凭证、会话正文、用户名和真实项目路径。 + required: true + - type: checkboxes + id: release + attributes: + label: Release confirmation / 版本确认 + options: + - label: I checked whether this also happens in the latest public release. / 我已确认该问题是否也出现在最新公开版本中。 required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..654f83a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability / 安全漏洞 + url: https://github.com/hepinga/MacPulse/security/advisories/new + about: Report vulnerabilities privately. Never post credentials in a public issue. / 请私密报告漏洞，不要在公开 Issue 中粘贴凭证。 + - name: Download the latest release / 下载最新版本 + url: https://github.com/hepinga/MacPulse/releases/latest + about: Check the latest signed public release before reporting an installation issue. / 报告安装问题前，请先核对最新签名公开版本。 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 41a5a29..2de2edc 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,24 +1,40 @@ -name: Feature request -description: 提出功能或体验建议 +name: Feature request / 功能建议 +description: Propose a user problem and a focused improvement. / 提出用户问题与聚焦的改进方案 title: "[Feature] " -labels: ["enhancement"] +labels: ["enhancement", "needs triage"] body: + - type: markdown + attributes: + value: "Please describe the problem before the solution, and do not include private session content. / 请先描述问题，再描述方案；不要附上私人会话内容。" - type: textarea id: problem attributes: - label: 想解决的问题 + label: Problem to solve / 想解决的问题 validations: required: true - type: textarea id: proposal attributes: - label: 建议方案 + label: Proposed outcome / 建议结果 validations: required: true - type: dropdown id: area attributes: - label: 功能区域 - options: [系统监控, AI 用量, 额度提醒, 清理, Skills, 自动更新, 其他] + label: Product area / 功能区域 + options: + - System monitoring / 系统监控 + - AI usage / AI 用量 + - Quotas and notifications / 额度与提醒 + - Cleanup and memory / 清理与内存 + - Skills + - UI and themes / 界面与主题 + - Website / 官网 + - Other / 其他 validations: required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered / 考虑过的替代方案 + description: Optional, but useful for understanding the trade-off. / 可选，用于理解取舍。 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..bd63cc0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,33 @@ +## What changed / 变更内容 + + + +## Area / 涉及区域 + +- [ ] System monitoring / 系统监控 +- [ ] AI usage or quota / AI 用量或额度 +- [ ] Cleanup or memory tools / 清理或内存工具 +- [ ] Skills +- [ ] UI or website / 界面或官网 +- [ ] Documentation or community / 文档或社区 + +## Verification / 验证 + + + +- [ ] `./scripts/test.sh` +- [ ] `./scripts/build.sh` +- [ ] Relevant manual checks completed / 已完成相关人工验证 + +## Privacy and safety / 隐私与安全 + +- [ ] Screenshots and logs contain no tokens, credentials, usernames, private paths, or conversation text. +- [ ] 截图与日志不包含 token、凭证、用户名、私人路径或会话正文。 +- [ ] Cleanup/path changes preserve the documented safety invariants, or this PR does not touch them. +- [ ] 清理/路径改动保持既有安全不变量，或本 PR 未涉及这些逻辑。 + +## Release impact / 发布影响 + +- [ ] No release impact / 不影响发布 +- [ ] Requires changelog entry / 需要更新变更记录 +- [ ] Requires signing, notarization, appcast, or website coordination / 需要签名、公证、appcast 或官网协同 diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..b77de9c --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,46 @@ +# Reviewable source of truth for repository labels. Sync these values in GitHub Settings. +- name: bug + color: D73A4A + description: Something is not working / 可复现的问题 +- name: enhancement + color: A2EEEF + description: New feature or improvement / 新功能或改进 +- name: documentation + color: 0075CA + description: Documentation changes / 文档改进 +- name: privacy + color: 6F42C1 + description: Privacy boundary or local-data handling / 隐私边界或本地数据处理 +- name: security + color: B60205 + description: Security-sensitive work; disclose vulnerabilities privately / 安全相关；漏洞请私密披露 +- name: "area: system" + color: C5DEF5 + description: System metrics, sampling, temperature, fans, or processes +- name: "area: ai-usage" + color: C5DEF5 + description: Claude Code or Codex usage, tokens, and cost estimates +- name: "area: quota" + color: C5DEF5 + description: Quota windows, countdowns, and notifications +- name: "area: cleanup" + color: C5DEF5 + description: Cache cleanup, path safety, and memory release +- name: "area: skills" + color: C5DEF5 + description: Local Skills discovery and lifecycle +- name: "area: ui" + color: C5DEF5 + description: Menu bar, popover, dashboard, themes, or notch UI +- name: "area: website" + color: C5DEF5 + description: Public website or optional community service +- name: needs triage + color: EDEDED + description: Awaiting maintainer review / 等待维护者分流 +- name: good first issue + color: 7057FF + description: Approachable for a first contribution / 适合首次贡献 +- name: help wanted + color: 008672 + description: Maintainers welcome community help / 欢迎社区协助 diff --git a/README.md b/README.md index cb1f4d3..b103613 100644 --- a/README.md +++ b/README.md @@ -1,193 +1,156 @@ -# Mac监控器(MacPulse) - -一款面向 Apple Silicon 与 macOS 14+的菜单栏工具:系统监控 + AI 编程助手的用量/费用/额度监控, -灵感来自 SystemPal,架构参考开源项目 [exelban/stats](https://github.com/exelban/stats) 与 [ccusage](https://github.com/ryoppippi/ccusage)。 - -> 当前为免费公开 Beta 0.10.0，中文优先，MIT 开源。官网: -> [macpulse-monitor.peaceaii.chatgpt.site](https://macpulse-monitor.peaceaii.chatgpt.site)。 -> 使用前请阅读 [隐私说明](PRIVACY.md)；暂不支持 Intel Mac 和 Mac App Store。 - -## 功能总览 - -**菜单栏常驻**:`C12 M85 ¥52` —— CPU 使用率 / 内存使用率 / 今日 AI API 等价预估,2 秒刷新; -可选追加最紧张的额度(`◔78%` 已用 + 重置倒计时)。 - -**弹窗两种模式**(右上角一键切换) -- **简单模式**(默认):不出现 token/burn rate 等术语,用大白话回答三个问题—— - 额度还能用多久 / 今天会不会超支 / 电脑扛得住吗。 -- **专业模式**:系统 / AI 用量 / Skills 三个页签,细节全量展开。 - -**三套 UI 主题**(设置菜单切换,覆盖弹窗、监控台、灵动岛全部界面) -- **经典**:系统原生风,控件一律走系统原生。 -- **HUD**(默认):俄式影视包装 / FUI 风——深空底 + 示波青 + 中英双层代号 + 切角面板 + 四角取景框。 -- **LED**:复古健身器材仪表风——近黑底 + LED 点阵 + 七段数码管大读数(Canvas 真绘制,含残影)+ - 圆点灯珠电平条;单色琥珀亮度阶梯,多系列靠亮度区分。 -- 微交互全套:开机充能、扫描线、页签滑动、按钮 hover 辉光、鼠标跟随扫光(`SweepEffects`), - 全部尊重 `accessibilityReduceMotion`。 - -**系统页签** -- CPU:总使用率 + 系统/用户拆分 + 60 点实时折线图 + CPU 温度 -- 内存:已用/总量、联动/已压缩、压力配色进度条 -- 网络/磁盘:实时收发与读写速率 -- 传感器:CPU/GPU 温度(SMC Tp*/Tg* 键)、双风扇转速(F0Ac/F1Ac) -- 电池健康:健康度/循环次数/温度/充电状态(IOKit AppleSmartBattery) -- 进程 Top 6 按 CPU 排序;含清理与内存回收(见下) - -**清理与内存回收**(删文件,安全第一) -- 磁盘空间进度条 + 一键回收内存:免 root 的有界方案(mmap 申请并释放促使系统回收非活跃内存), - 上限 = min(3GB, 空闲一半),诚实显示回收量;真想腾内存优先结束应用(内存 Top 进程一键 SIGTERM,先弹确认) -- 垃圾清理:安全白名单只清可再生缓存——废纸篓 / 应用缓存(~/Library/Caches)/ 系统日志 / - 开发者缓存(npm _cacache、Xcode 派生数据),扫描后按类目勾选 -- **绝不触碰**:文档/桌面/下载、偏好设置、Application Support、pnpm store、SSH/iCloud 等—— - 三重路径守卫(在 home 下 + 归属白名单根 + 不命中保护目录),经 23 条生产守卫用例 + 符号链接/假 Home 端到端测试验证 -- 本机实测可清理约 13GB,并行扫描 ~1.3 秒 - -**AI 用量页签**(双数据源,逻辑对齐 ccusage v18) -- 数据源:Claude Code(`~/.claude/projects` 会话 JSONL)+ Codex CLI(`~/.codex/sessions` rollout JSONL, - 按 `last_token_usage` 增量计数,经本机 190M token 实测校准) -- 今日 API 等价预估(非订阅实际扣款)+ token 构成 + 调用次数;近 1 小时燃烧率 / 本月已用 / 整月外推预估 -- 近 7 天费用柱状图 + 本月按模型明细 -- 去重:跨文件 `messageId:requestId` 全局去重,文件按最早时间戳排序; - 流式多行快照取组内最大 output(比 ccusage v18 的 keep-first 更准,实测它少算 ~30% output) -- 计价:内置 2026-07-06 双源验证价格表(LiteLLM + Anthropic 官方页),区分 5m/1h 缓存写入、 - 读取 0.1x、200K 分层价、fast 模式倍率;JSONL 自带 costUSD 时优先采用 - -**额度中心**(菜单栏/简单模式/灵动岛共用) -- Claude:OAuth 端点,权威、实时(5 分钟一刷防 429) -- Codex:rollout 文件解析,截至上次会话(90 秒一刷) -- 额度重置自动探测 → 刘海提醒「满血复活」;快用完也会提醒(每周期一次防重复) - -**Skills 管理页签** -- 列出本机各 AI 工具已装的 skills,支持安装 / 卸载 / 跨工具复制 -- 安装对齐开源生态(skills.sh):支持 `owner/repo`、子路径、完整 GitHub URL, - 单仓多 skill 自动发现并弹窗挑选 -- 卸载比生态更安全:移入废纸篓(可恢复),不做 rm - -**Token 监控台**(独立大窗口,760×560 起) -- 信息模式与视觉主题解耦:**一眼看懂**只保留决策信息;**分析模式**展开 Token 构成、模型和项目明细 -- 顶部筛选时间/工具/项目/模型/Token 构成;项目与模型排行可点击下钻,选中态、占比和重置入口一致 -- 首屏四项:筛选范围内的 API 等价预估(明确环比基准和绝对差额)、最紧张额度、固定近 1 小时速度、缓存复用率 -- 自动洞察主要模型/项目/峰值时段;本月外推明确使用固定月度窗口,不会随顶部时间范围跳变 -- 分析模式把“新增处理量 = 输入 + 输出 + 缓存写”与“缓存复用”分列,避免总 Token 与明细口径误解 -- 数据状态显示刷新时间、Claude/Codex 来源覆盖、未知模型告警;隐私模式用稳定别名隐藏真实项目名 -- 可选等价成本提醒(默认关闭),每小时/每日阈值可配置且按周期去重 -- 跟随三主题,深色皮肤用自绘发光滚动条 -- LED Canvas 数码读数提供完整辅助功能语义,VoiceOver 可读金额、额度、速度和缓存率 - -**社区排行**(完全可选) -- 游客无需登录即可浏览 Token 与 API 等价费用本周榜单，本地监控功能不受影响 -- 使用 Google 登录后自动加入两个榜，默认昵称打码为 `＊＊＊平` 形式 -- 只同步上海时区每日总量、价格表版本与 App 版本，不上传会话正文、项目或模型明细 -- 登录用户可查看个人名次、自愿公开完整昵称，或退出并删除榜单汇总 - -**灵动岛(刘海)** -- 平时完全隐藏,鼠标移到刘海 → 无缝长出黑色下拉面板(高度随内容自适应),移开自动收起 -- 刘海强提醒 + Vibe 时刻:开工大吉(每天首次 AI 活动)/ 满血复活(额度重置)/ - 喝口水(久坐关怀)/ 电脑体温(过热提醒),各自有防打扰节流,受总开关约束 - -**显示设置** -- Token 单位:中文单位(万/亿)或 K/M/B;货币:¥(可设汇率)/ $ -- 主题切换、隐私模式、额度重置提醒、等价成本提醒阈值、菜单栏额度开关等 - -## 构建与运行 +
+ MacPulse app icon +

MacPulse

+

Monitor your Mac. Understand your AI.

+

A native menu bar monitor for Apple Silicon: system health, Claude Code and Codex usage, cost estimates, quotas, and local-first tools.

-```bash -./scripts/build.sh 0.10.0 3 # 编译 + 打包 dist/MacPulse.app + ad-hoc 签名 -./scripts/test.sh # 生产代码回归测试(含清理安全守卫) -open dist/MacPulse.app # 启动 -``` +

English · 简体中文

-真实 Claude/Codex 会话回归(只读本机 JSONL,显式开启): +

+ Latest release + CI status + MIT license + Public beta +

+

+ macOS 14 or later + Apple Silicon arm64 + SwiftUI and Swift 5 + Local-first privacy +

-```bash -MACPULSE_LIVE_TEST=1 swift test --filter CoreRegressionTests/testLiveAggregationInvariantsWhenRequested -``` +

+ Download latest signed DMG + · Website + · Gallery + · Privacy +

+
-**双版本约定**:日常从 `/Applications` 启动;每次 `build.sh` 之后要把 `dist/MacPulse.app` -拷贝覆盖 `/Applications`,否则桌面启动的仍是旧版(两版可同时运行,容易误判"改动没生效")。 +![MacPulse product overview](docs/assets/github/hero.webp) -本机 2026-07 起已装 Xcode 26.6(xcode-select 指向 Xcode,SDK MacOSX26)。 +> [!IMPORTANT] +> The latest public release and signed Sparkle feed are currently **v0.9.0**. The `main` branch contains unreleased v0.10 preview work, including the optional community ranking. The app interface is Chinese-first; the language switch above changes project documentation, not the app UI. -### 本机 CLT 残留说明(历史问题) +## Why MacPulse -这台机器的 CLT 有两个旧版本残留文件,曾导致任何 `swift build` 失败。 -`build.sh` 已内置无 sudo 的绕过方案(`.clt-fix/`,自动生成);残留文件存在时 workaround -仍会激活但无害。永久修复(二选一): +| | What it gives you | +| --- | --- | +| **System pulse** | CPU, memory, network, disk, battery, temperature, fans, and top processes in a menu bar app. | +| **AI usage** | Local aggregation of Claude Code and Codex JSONL sessions, with token composition, trends, and API-equivalent cost estimates. | +| **Quota awareness** | Claude and Codex quota windows, reset countdowns, optional notifications, and a compact notch experience. | +| **Local-first tools** | Privacy mode, safe cache cleanup, bounded memory release, process termination, and recoverable Skills management. | -```bash -# 方案 A:精准删除两个残留文件 -sudo rm /Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI/PackageDescription.swiftmodule/*.private.swiftinterface -sudo rm /Library/Developer/CommandLineTools/usr/include/swift/module.modulemap +MacPulse is designed for people who use AI coding tools heavily but still want a clear view of the Mac underneath them. The default simple mode answers three practical questions: how long the quota may last, whether today's pace is expensive, and whether the computer is under pressure. Analysis mode keeps the detailed token and model breakdown available when needed. -# 方案 B:重装 CLT -sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install -``` +## Gallery -## 发布(GitHub Releases + 官网，不上 MAS) +### Three visual systems -```bash -./scripts/preflight-release.sh # 当前源码 + 全部 Git 历史的发布闸门 -./scripts/release.sh 0.10.0 3 # 版本号 + 单调递增构建号 -SKIP_NOTARIZE=1 ./scripts/release.sh 0.10.0 3 # 本地干跑，绝不能公开分发 -``` +| HUD | LED | Classic | +| --- | --- | --- | +| ![HUD dashboard](docs/assets/github/dashboard-hud.png) | ![LED dashboard](docs/assets/github/dashboard-led.png) | ![Classic dashboard](docs/assets/github/dashboard-classic.png) | + +### Analysis mode + +![Token analysis mode with privacy aliases](docs/assets/github/analysis-mode.png) + +### Public website + +![MacPulse public website](docs/assets/github/website-home.png) + +All app screenshots above were captured from the built macOS app with privacy mode enabled. Project names are replaced with stable aliases. Screens showing unavailable services, credentials, admin tools, or private paths are intentionally excluded. + +## Features + +
+System monitoring + +- Menu bar label for CPU, memory, and today's AI API-equivalent estimate; optional tightest-quota indicator. +- CPU total/user/system load, real-time chart, and AppleSMC temperature sampling. +- Memory pressure, compression, disk and network throughput, battery health, and fan speed. +- Top processes by CPU or memory, with confirmation before sending `SIGTERM`. +- Safe cache cleanup guarded by lexical path validation, protected paths, and sandbox-style regression tests. -正式脚本会从内到外签名 Sparkle helper/framework 与主应用，开启 Hardened Runtime， -公证 App 与 DMG，然后产出 DMG、SHA-256、签名 appcast、发布说明和私下保留的 dSYM。 -一次性前置(Developer ID、`macpulse-notary`、Sparkle 密钥备份)及完整上线顺序见 -[`docs/发布指南.md`](docs/发布指南.md)。 -不上 App Store 的原因:沙盒禁 SMC(温度/风扇)、清理功能需授权目录改造。 +
-## 应用图标 +
+AI usage and quotas -唯一设计源是根目录 `logo icon.svg`(满 1024 出血、透明底、不画圆角); -`scripts/make-icon.swift` 用 WKWebView 渲染 SVG 再套 Apple 规范 squircle -(1024 画布 / 824 主体 / 半径 185.4 / continuous 连续曲率)生成 `Resources/AppIcon.icns`。 -`build.sh` 检测到 svg 比 icns 新会自动重新生成——换图标只改 svg 即可。 +- Reads local Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) JSONL files. +- Daily and monthly API-equivalent estimates, recent burn rate, seven-day trends, model/project drill-down, and cache reuse. +- Global `messageId:requestId` de-duplication aligned with ccusage semantics when both identifiers exist. +- Claude OAuth quota access is optional and disabled by default; Codex quota is derived from local rollout events. +- Cost figures are estimates for comparison and planning, not subscription invoices or actual charges. -## 登录自启(可选) +
+ +
+Experience and optional tools + +- Simple and professional information modes. +- Classic, HUD, and LED themes across the popover, dashboard, and notch surfaces. +- Local Skills discovery, installation, copying, and recoverable uninstall-to-Trash behavior. +- Optional quota-reset and wellbeing moments, each rate-limited and controlled by a master switch. +- Optional community ranking on `main` as an unreleased v0.10 preview; local monitoring works without signing in. + +
+ +## Download and requirements + +| Requirement | Support | +| --- | --- | +| Hardware | Apple Silicon (`arm64`) | +| macOS | 14 or later | +| Distribution | GitHub Releases, Developer ID signed and Apple notarized | +| App Store | Not available; sandboxing would block SMC and local session access | + +1. Download the latest `.dmg` from [GitHub Releases](https://github.com/hepinga/MacPulse/releases/latest). +2. Drag `MacPulse.app` to `/Applications`. +3. Open the app and review the first-run privacy explanation before enabling optional features. + +> [!NOTE] +> There is another macOS product using the `macpulse` Homebrew cask name. MacPulse does not currently publish a Homebrew install command, so use this repository's signed GitHub Release. + +## Privacy model + +MacPulse is local-first. It does not upload conversation text, prompts, responses, private project paths, or AI credentials. Product analytics, advertising telemetry, and automatic crash reporting are not enabled. + +Network access only occurs for user-visible features such as update checks, optional Claude quota access, installing a Skill from a user-selected GitHub repository, and the optional community ranking. See the full [Privacy Notice](PRIVACY.md) and [Security Policy](SECURITY.md). + +## Build from source + +Use the project scripts rather than a bare `swift build` when you need a runnable app bundle: ```bash -cat > ~/Library/LaunchAgents/com.liangheping.macpulse.plist <<'EOF' - - - - - Labelcom.liangheping.macpulse - ProgramArguments - /Applications/MacPulse.app/Contents/MacOS/MacPulse - RunAtLoad - ProcessTypeInteractive - - -EOF -launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.liangheping.macpulse.plist +./scripts/test.sh +./scripts/build.sh 0.10.0 3 +open dist/MacPulse.app ``` -停用:`launchctl bootout gui/$(id -u)/com.liangheping.macpulse` +The package uses Swift 5 language mode, targets macOS 14+, and is built with Swift Package Manager. The build script compiles, assembles `dist/MacPulse.app`, generates the icon when needed, and applies an ad-hoc signature for local testing. + +For release signing, notarization, Sparkle appcast generation, and Gatekeeper checks, follow [`docs/发布指南.md`](docs/发布指南.md). Do not distribute artifacts produced with `SKIP_NOTARIZE=1`. + +## Architecture highlights + +- SwiftUI `MenuBarExtra(.window)` and Swift Charts; no Xcode project is required. +- Mach APIs for CPU and memory, `getifaddrs` for network, IOKit for disk/battery, and AppleSMC for temperature/fans. +- Serial sampling queues behind `@MainActor` observable stores. +- Sparkle 2 for signed application updates. +- A separate website and lightweight worker for the optional public ranking preview. -## 实测指标(M5 Pro,1.6GB 会话数据,2026-07-17) +## Contributing and support -- 最新回归:40,058 条事件冷扫描 + 聚合检查约 18.6 秒;热扫描(文件 size/mtime 缓存命中)约 0.21 秒 -- 内存:安装版冷扫描完成物理占用 60.4MB,实测峰值 70.9MB(`vmmap -summary`) -- 实现:会话文件只读映射,避免把 1.6GB JSONL 反复拷进 malloc 脏页 -- 今日费用与独立脚本重算误差 < 时间窗口内的自然增量 +- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. +- Use the structured [bug report](https://github.com/hepinga/MacPulse/issues/new?template=bug_report.yml) and remove tokens, session text, usernames, and real project paths. +- Use GitHub's private vulnerability reporting flow for security issues; do not post credentials in a public Issue. +- Release history is maintained in [CHANGELOG.md](CHANGELOG.md). -## 技术要点 +## Acknowledgements -- 纯 SwiftUI `MenuBarExtra`(.window 样式)+ Swift Charts,SPM 构建,无 Xcode 工程 -- CPU/内存:`host_processor_info` / `host_statistics64`(Mach API) -- 网络:`getifaddrs` 增量;磁盘:IOKit `IOBlockStorageDriver` Statistics 增量 -- 温度/风扇:AppleSMC IOKit 用户客户端(M5 上 `flt ` 小端 float32, - 温度键 Tp*/Te*/Tf*/Tg* 前缀筛选 + 合理区间过滤;无需 sudo、无需 entitlement) -- 主题系统:弹窗三套独立视图树(`UI/Classic` / `HUD*` / `UI/LED`),监控台与灵动岛在组件内按主题分支, - 共享逻辑只有一份;系统原生控件(分段/按钮)在深色主题下由 `ThemedControls` 自绘替代 -- 刘海面板:NSPanel + 全局鼠标监听驱动(非激活浮层上 SwiftUI hover 不可靠), - 高度由内容测量上报(`NotchContentHeight` preference) -- 非沙盒(SMC 与 `~/.claude` 读取都不允许沙盒)；本地构建使用 ad-hoc，公开包使用 Developer ID + Apple 公证 +MacPulse was inspired by SystemPal and references ideas from [exelban/stats](https://github.com/exelban/stats) and [ccusage](https://github.com/ryoppippi/ccusage). Third-party license notices are listed in [THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt). -## 文档索引 +## License -- `AGENTS.md` / `CLAUDE.md` —— 构建约定、架构红线与安全测试要求 -- `docs/PRD.md`、`docs/追加需求.md` —— 产品需求 -- `docs/发布指南.md` —— 发布一次性前置配置 -- `PRIVACY.md`、`SECURITY.md`、`CONTRIBUTING.md` —— 公开隐私、安全与贡献政策 +[MIT](LICENSE) © 2026 Liang Heping diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..986e40d --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,156 @@ +
+ MacPulse 应用图标 +

MacPulse

+

看懂你的 Mac，也看懂 AI 用量。

+

面向 Apple Silicon 的原生菜单栏监控器：系统健康、Claude Code 与 Codex 用量、成本预估、额度和本地优先工具。

+ +

English · 简体中文

+ +

+ 最新版本 + CI 状态 + MIT 许可证 + 公开测试版 +

+

+ macOS 14 或更高版本 + Apple Silicon arm64 + SwiftUI 与 Swift 5 + 本地优先隐私 +

+ +

+ 下载最新签名 DMG + · 官网 + · 产品图集 + · 隐私说明 +

+
+ +![MacPulse 产品总览](docs/assets/github/hero.webp) + +> [!IMPORTANT] +> 当前正式公开版本与已签名 Sparkle 更新源仍是 **v0.9.0**。`main` 分支包含尚未发布的 v0.10 预览功能，包括可选社区排行。上方语言切换只切换项目文档；应用界面目前仍以中文为主。 + +## 为什么是 MacPulse + +| | 你能得到什么 | +| --- | --- | +| **系统脉搏** | 在菜单栏查看 CPU、内存、网络、磁盘、电池、温度、风扇和高占用进程。 | +| **AI 用量** | 本地汇总 Claude Code 与 Codex JSONL，会话 Token 构成、趋势和 API 等价成本一目了然。 | +| **额度感知** | Claude/Codex 额度窗口、重置倒计时、可选通知与刘海体验。 | +| **本地优先工具** | 隐私模式、安全缓存清理、有界内存回收、进程结束和可恢复的 Skills 管理。 | + +MacPulse 面向高频使用 AI 编程工具、同时又希望看清电脑状态的人。默认“一眼看懂”模式先回答三个实际问题：额度还能撑多久、今天的速度会不会太贵、电脑现在是否吃力；需要时再切换分析模式查看 Token、模型和项目明细。 + +## 产品图集 + +### 三套视觉系统 + +| HUD | LED | 经典 | +| --- | --- | --- | +| ![HUD 监控台](docs/assets/github/dashboard-hud.png) | ![LED 监控台](docs/assets/github/dashboard-led.png) | ![经典监控台](docs/assets/github/dashboard-classic.png) | + +### 分析模式 + +![开启隐私别名的 Token 分析模式](docs/assets/github/analysis-mode.png) + +### 公开官网 + +![MacPulse 公开官网](docs/assets/github/website-home.png) + +以上 App 截图均来自实际构建的 macOS 应用，并已开启隐私模式：真实项目名被替换成稳定别名。服务不可用、凭证、管理后台和私人路径等画面不会用于公开展示。 + +## 功能 + +
+系统监控 + +- 菜单栏常驻 CPU、内存和今日 AI API 等价预估；可选显示最紧张额度。 +- CPU 总量/用户/系统占比、实时曲线和 AppleSMC 温度采样。 +- 内存压力与压缩、磁盘和网络吞吐、电池健康与风扇转速。 +- CPU/内存高占用进程排行；发送 `SIGTERM` 前必须确认。 +- 缓存清理使用纯词法路径校验、保护目录和沙盒式回归测试守住删除边界。 + +
+ +
+AI 用量与额度 + +- 读取本机 Claude Code（`~/.claude/projects`）与 Codex（`~/.codex/sessions`）JSONL。 +- 今日与本月 API 等价预估、近一小时速度、七日趋势、模型/项目下钻和缓存复用率。 +- 两个标识都存在时按 `messageId:requestId` 全局去重，与 ccusage 语义保持一致。 +- Claude OAuth 额度默认关闭且完全可选；Codex 额度从本地 rollout 事件推导。 +- 所有金额都用于比较与规划，不代表订阅账单或真实扣款。 + +
+ +
+体验与可选工具 + +- 一眼看懂与分析模式两套信息密度。 +- 经典、HUD、LED 三套主题，覆盖弹窗、监控台和刘海界面。 +- 本机 Skills 发现、安装、复制，以及移动到废纸篓的可恢复卸载。 +- 可选额度重置和久坐关怀提醒；均有节流并受总开关控制。 +- `main` 上含尚未发布的 v0.10 社区排行预览；不登录不影响本地监控。 + +
+ +## 下载与要求 + +| 要求 | 支持情况 | +| --- | --- | +| 硬件 | Apple Silicon（`arm64`） | +| macOS | 14 或更高版本 | +| 分发 | GitHub Releases、Developer ID 签名与 Apple 公证 | +| App Store | 不提供；沙盒会阻止 SMC 和本机会话读取 | + +1. 从 [GitHub Releases](https://github.com/hepinga/MacPulse/releases/latest) 下载最新 `.dmg`。 +2. 将 `MacPulse.app` 拖入 `/Applications`。 +3. 打开应用，先阅读首次启动隐私说明，再决定是否开启可选功能。 + +> [!NOTE] +> Homebrew 已有另一个 macOS 产品使用 `macpulse` cask 名称。本项目目前不提供 Homebrew 安装命令，请使用本仓库的已签名 GitHub Release。 + +## 隐私模型 + +MacPulse 以本地处理为默认，不上传会话正文、提示词、回复、真实项目路径或 AI 凭证，也不启用产品分析、广告遥测或自动崩溃上报。 + +只有用户可感知功能会联网，例如检查更新、可选 Claude 额度、从用户指定 GitHub 仓库安装 Skill，以及可选社区排行。详细边界见 [隐私说明](PRIVACY.md) 与 [安全策略](SECURITY.md)。 + +## 从源码构建 + +需要得到可运行 App 包时请使用项目脚本，不要把裸 `swift build` 当成分发结果： + +```bash +./scripts/test.sh +./scripts/build.sh 0.10.0 3 +open dist/MacPulse.app +``` + +项目采用 Swift 5 语言模式、目标 macOS 14+，使用 Swift Package Manager。构建脚本会编译、组装 `dist/MacPulse.app`、按需生成图标，并为本地测试执行 ad-hoc 签名。 + +正式发布签名、公证、Sparkle appcast 和 Gatekeeper 检查见 [`docs/发布指南.md`](docs/发布指南.md)。`SKIP_NOTARIZE=1` 生成的产物不得公开分发。 + +## 架构要点 + +- SwiftUI `MenuBarExtra(.window)` 与 Swift Charts；不依赖 Xcode 工程文件。 +- CPU/内存使用 Mach API，网络使用 `getifaddrs`，磁盘/电池使用 IOKit，温度/风扇使用 AppleSMC。 +- `@MainActor` 可观察状态背后使用各自串行采样队列。 +- Sparkle 2 提供签名应用更新。 +- 独立官网与轻量 worker 承载可选社区排行预览。 + +## 贡献与反馈 + +- 提交 Pull Request 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 +- 使用结构化[错误报告](https://github.com/hepinga/MacPulse/issues/new?template=bug_report.yml)，并移除 token、会话正文、用户名和真实项目路径。 +- 安全问题请使用 GitHub 私密漏洞报告，不要在公开 Issue 中粘贴凭证。 +- 版本历史见 [CHANGELOG.md](CHANGELOG.md)。 + +## 致谢 + +MacPulse 的灵感来自 SystemPal，并参考了 [exelban/stats](https://github.com/exelban/stats) 与 [ccusage](https://github.com/ryoppippi/ccusage)。第三方许可见 [THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt)。 + +## 许可证 + +[MIT](LICENSE) © 2026 Liang Heping diff --git "a/docs/GitHub\350\243\205\344\277\256\350\260\203\347\240\224\344\270\216\346\226\271\346\241\210.md" "b/docs/GitHub\350\243\205\344\277\256\350\260\203\347\240\224\344\270\216\346\226\271\346\241\210.md" new file mode 100644 index 0000000..8d48413 --- /dev/null +++ "b/docs/GitHub\350\243\205\344\277\256\350\260\203\347\240\224\344\270\216\346\226\271\346\241\210.md" @@ -0,0 +1,182 @@ +# MacPulse GitHub 装修调研与方案 + +> 调研日期：2026-07-18 +> 目标：让第一次进入仓库的人在 30 秒内看懂“它是什么、为什么值得下载、是否可信、如何参与”，同时保持版本、隐私和分发信息真实。 + +## 一、结论先行 + +优秀项目的共同点不是“徽章越多越好”，而是把仓库首页当作产品落地页：首屏讲清定位与下一步，真实图片证明产品存在，结构化信息降低理解成本，社区文件让反馈可执行。MacPulse 应采用以下组合： + +1. 英文 `README.md` 作为默认首页，`README.zh-CN.md` 提供完整中文镜像，首屏双向切换。 +2. 只保留能回答事实问题的徽章：Release、CI、许可证、系统要求、芯片架构、技术栈、Beta 状态、本地优先。 +3. 用真实构建截图组成 Hero 与图集；截图默认开启隐私模式，不展示凭证、路径、后台或失败状态。 +4. 把下载、官网、隐私说明放在首屏，把维护细节折叠或链接到开发文档。 +5. 用 Issue 表单、PR 模板、Topics 与标签建立可搜索、可分流的社区入口。 +6. 明确区分 **v0.9.0 正式 Release** 与 `main` 上的 **v0.10 未发布预览**，不制造已经发布的错觉。 + +## 二、优秀案例与可复用模式 + +| 项目 | 首页做法 | 可复用模式 | MacPulse 的取舍 | +| --- | --- | --- | --- | +| [LocalSend](https://github.com/localsend/localsend) | 多语言入口、少量事实徽章、下载入口、跨平台截图 | 语言切换出现在首屏；“立即获取”比安装细节更靠前；截图承担产品解释 | 学习双语入口和下载层级，不照搬跨平台叙事 | +| [Ice](https://github.com/jordanbaird/Ice) | 图标、品牌横幅、系统要求与版本徽章、截图画廊 | 原生 macOS 项目适合以图标和宽屏视觉建立第一印象 | 学习原生感和画廊；MacPulse 不增加无事实依据的平台徽章 | +| [MonitorControl](https://github.com/MonitorControl/MonitorControl) | 清晰下载 CTA、状态徽章、主截图、多图网格 | 先证明“可以下载并运行”，再解释功能；多图覆盖关键任务 | 学习 CTA 与多图布局；不复制与显示器控制相关的技术信息 | +| [Stats](https://github.com/exelban/stats) | 大图优先、直接 Release 入口、语言列表 | 菜单栏工具需要尽快展示信息密度和原生界面 | 学习图片优先和直接下载；MacPulse 只维护两份高质量语言文档 | + +这些案例的共同结构可以归纳为： + +```text +品牌与一句话定位 + ├─ 语言 / 版本 / 平台事实 + ├─ 下载 / 官网 / 隐私主入口 + ├─ 一张宽屏产品证据图 + ├─ 核心价值与关键功能 + ├─ 多图画廊 + └─ 要求 / 隐私 / 开发 / 贡献 +``` + +## 三、GitHub 官方规范 + +### README 与相对链接 + +GitHub 会自动呈现仓库根目录等位置的 README，并建议 README 说明项目用途、入门方式、帮助入口和维护者信息。文档内图片、文件与目录宜使用相对路径，保证分支和克隆环境中的链接仍然成立。 + +- [About READMEs — GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) +- [Basic writing and formatting syntax / Relative links — GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/basic-writing-and-formatting-syntax#relative-links) + +### Topics + +Topics 用于发现和分类仓库。名称只能包含小写字母、数字和连字符；每个仓库最多 20 个。应优先覆盖平台、技术栈、产品形态、核心能力与集成对象，不把营销口号拆成 Topics。 + +- [Classifying your repository with topics — GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) + +### Social Preview + +GitHub 建议自定义社交预览图采用 2:1 画幅，推荐至少 1280×640，文件小于 1 MB。预览图在分享链接时承担“品牌识别 + 一句话解释”，不应塞入小字号功能清单。 + +- [Customizing your repository's social media preview — GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview) + +### 社区健康文件与安全 + +Issue 表单通过结构化字段提高复现质量；PR 模板用于统一验证、隐私与变更说明。公开安全问题不应要求用户粘贴凭证，仓库应引导使用私密漏洞报告或安全策略中的私密渠道。 + +- [Configuring issue templates for your repository — GitHub Docs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) +- [Creating a pull request template for your repository — GitHub Docs](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) +- [Adding a security policy to your repository — GitHub Docs](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) + +## 四、MacPulse 当前问题 + +装修前的首页信息丰富，但存在以下阻力： + +- 首屏缺少强定位、语言切换、下载与隐私入口，读者要滚动后才知道下一步。 +- 文字很长，产品价值、用户功能、实现细节和本机维护历史混在同一层级。 +- 缺少一组经过隐私处理的真实产品图，外部读者无法快速判断完成度与界面形态。 +- Release 事实与开发分支状态容易混淆：正式 Sparkle feed 仍是 v0.9.0，而 `main` 已包含 v0.10 预览内容。 +- Issue 分类较少，缺 PR 模板、Issue 配置与统一标签色板。 +- 仓库 About、Topics 与 Social Preview 尚未形成完整的发现入口。 + +## 五、推荐信息架构 + +### 首屏 + +1. 图标、项目名和一句话定位。 +2. `English · 简体中文` 双向切换。 +3. 两行事实徽章。 +4. 下载、官网、图集与隐私四个入口。 +5. 一张 16:9 宽屏 Hero。 +6. 紧随其后的版本事实提示：v0.9.0 已发布、v0.10 为未发布预览、App UI 仍以中文为主。 + +### 正文 + +- **核心价值**：系统脉搏、AI 用量、额度感知、本地优先工具。 +- **图集**：主题差异、分析模式、公开官网；后续有稳定自动化后再补刘海与 Skills 独立截图。 +- **功能矩阵**：系统、AI 用量、额度、体验与可选工具。 +- **下载要求**：Apple Silicon、macOS 14+、签名与公证。 +- **隐私边界**：本地数据、允许联网的可见功能、不采集的内容。 +- **开发与贡献**：构建脚本、发布文档、Issue/PR 入口。 + +维护者专属内容（例如特定机器上的 CLT 历史残留、签名凭证配置、公证排障）不应占据用户首页主叙事，应放在开发或发布文档中。 + +## 六、徽章准则 + +### 保留 + +| 徽章 | 回答的问题 | +| --- | --- | +| Latest Release | 当前可下载版本是什么 | +| CI | 主线是否通过自动检查 | +| MIT | 使用与分发的许可是什么 | +| macOS 14+ | 最低系统要求是什么 | +| Apple Silicon | 支持什么硬件架构 | +| Swift / SwiftUI | 主要技术栈是什么 | +| Public Beta | 产品成熟度是什么 | +| Local-first | 隐私和数据处理的核心承诺是什么 | + +### 不使用 + +- 访问量、Star 数、Fork 数等会制造热度但不提高理解的徽章。 +- 没有自动验证来源的“100% privacy”“production ready”等宣称。 +- Homebrew 徽章或 `brew install macpulse`：当前同名 cask 指向另一个产品，容易误装。 +- 把 `main` 中的版本号做成已发布版本徽章；Release 徽章必须动态读取 GitHub Releases。 + +## 七、图片准则与本次资产 + +### 准则 + +- 产品截图必须来自真实构建，优先成功状态；不得用设计稿伪装成运行结果。 +- 开启隐私模式，隐藏真实项目名、用户名、路径、Token、凭证和管理后台。 +- 排除“服务不可用”、登录错误、空白骨架等不适合作为产品证据的画面。 +- README 图采用仓库相对路径并提供有意义的 `alt` 文本。 +- 三列图在窄屏会缩小，单图分析界面保留独立宽屏展示。 +- Social Preview 固定为 1280×640、纯色背景、小于 1 MB；Hero 保留 1600×900 宽屏版本。 + +### 本次资产清单 + +| 文件 | 用途 | 尺寸 | +| --- | --- | --- | +| `docs/assets/github/hero.webp` | README 首屏 Hero | 1600×900 | +| `docs/assets/github/dashboard-hud.png` | HUD 主题 | 923×768 | +| `docs/assets/github/dashboard-led.png` | LED 主题 | 923×768 | +| `docs/assets/github/dashboard-classic.png` | 经典主题 | 923×768 | +| `docs/assets/github/analysis-mode.png` | AI Token 分析模式 | 923×768 | +| `docs/assets/github/website-home.png` | 公开官网 | 1265×712 | +| `docs/assets/github/social-preview.jpg` | GitHub Social Preview | 1280×640 | + +本轮没有为了凑数量伪造刘海或 Skills 独立截图：macOS 辅助功能未稳定暴露这些瞬时界面，且全屏捕获可能带入工作区隐私。后续应在干净桌面与演示数据环境中补拍，再替换图集，而不是拼接虚假状态。 + +## 八、Topics、标签与社区分类 + +### Topics + +建议 15 个（低于 GitHub 的 20 个上限）： + +`macos`、`swift`、`swiftui`、`menu-bar`、`menubar-app`、`macos-app`、`system-monitor`、`apple-silicon`、`cpu-monitor`、`memory-monitor`、`smc`、`ai-usage`、`token-usage`、`claude-code`、`codex-cli` + +### 标签 + +| 类别 | 标签 | 色彩策略 | +| --- | --- | --- | +| 类型 | `bug`、`enhancement`、`documentation` | 红、青、蓝 | +| 风险 | `privacy`、`security` | 紫、深红 | +| 区域 | `area: system`、`area: ai-usage`、`area: quota`、`area: cleanup`、`area: skills`、`area: ui`、`area: website` | 统一浅蓝 | +| 社区状态 | `needs triage`、`good first issue`、`help wanted` | 灰、紫、绿 | + +原计划写“六个 `area:*`”但同时列出了七个真实产品区域。本方案按产品结构保留七个，避免把官网或 UI 问题塞进不相关分类。仓库中的 `.github/labels.yml` 作为名称、说明与颜色的可审查来源；线上标签需通过 GitHub 设置同步。 + +## 九、上线检查 + +- [ ] `README.md` 与 `README.zh-CN.md` 首屏互链，主张一致。 +- [ ] Release 徽章动态读取，正文明确 v0.9.0 / v0.10 边界。 +- [ ] 所有相对链接和图片路径在分支上存在。 +- [ ] Social Preview 为 1280×640 且小于 1 MB。 +- [ ] README 在 GitHub PR 页面上检查桌面和窄屏布局。 +- [ ] CI 通过，且本任务没有修改 Swift 产品逻辑或发布新版本。 +- [ ] 仓库 About 使用准确简介与官网链接。 +- [ ] Topics、标签和 Social Preview 已在线同步；无法登录时明确标记为阻塞项。 +- [ ] PR 保持未合并，由维护者最后确认。 + +## 十、仓库元数据建议值 + +- **Description**：`Native macOS menu bar monitor for system health, Claude Code & Codex usage, cost estimates, quotas, and local-first tools.` +- **Website**：`https://macpulse-monitor.peaceaii.chatgpt.site` +- **Social Preview**：`docs/assets/github/social-preview.jpg` diff --git a/docs/assets/github/analysis-mode.png b/docs/assets/github/analysis-mode.png new file mode 100644 index 0000000..334f35b Binary files /dev/null and b/docs/assets/github/analysis-mode.png differ diff --git a/docs/assets/github/dashboard-classic.png b/docs/assets/github/dashboard-classic.png new file mode 100644 index 0000000..316a7b2 Binary files /dev/null and b/docs/assets/github/dashboard-classic.png differ diff --git a/docs/assets/github/dashboard-hud.png b/docs/assets/github/dashboard-hud.png new file mode 100644 index 0000000..ca1a3f9 Binary files /dev/null and b/docs/assets/github/dashboard-hud.png differ diff --git a/docs/assets/github/dashboard-led.png b/docs/assets/github/dashboard-led.png new file mode 100644 index 0000000..e5138b6 Binary files /dev/null and b/docs/assets/github/dashboard-led.png differ diff --git a/docs/assets/github/hero.webp b/docs/assets/github/hero.webp new file mode 100644 index 0000000..b66cdfe Binary files /dev/null and b/docs/assets/github/hero.webp differ diff --git a/docs/assets/github/social-preview.jpg b/docs/assets/github/social-preview.jpg new file mode 100644 index 0000000..a66434f Binary files /dev/null and b/docs/assets/github/social-preview.jpg differ diff --git a/docs/assets/github/website-home.png b/docs/assets/github/website-home.png new file mode 100644 index 0000000..36d0563 Binary files /dev/null and b/docs/assets/github/website-home.png differ